From 5a1d05561cf9e8b123546a0e92953be6fcd2f0f7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:14 +0200 Subject: [PATCH 001/698] New translations built-with-sanic.md (Japanese) --- guide/content/ja/built-with-sanic.md | 67 ++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 guide/content/ja/built-with-sanic.md diff --git a/guide/content/ja/built-with-sanic.md b/guide/content/ja/built-with-sanic.md new file mode 100644 index 0000000000..fa5d78e1cf --- /dev/null +++ b/guide/content/ja/built-with-sanic.md @@ -0,0 +1,67 @@ +--- +title: Full Speed Ahead - How We Built This Site with Sanic +layout: main +--- + +.. attrs:: +:class: title + +``` +Full Speed Ahead: +``` + +.. attrs:: +:class: subtitle + +``` +How We Built This Site with Sanic +``` + +Welcome to our little corner of the Internet where we proudly say, "Yes, we built this with Sanic!" This isn't just a website; it's our playground, our test lab, our battlefield, and, well, our home. + +![](/assets/images/built-with-sanic.png) + +### The Story: "We Drink Our Own Champagne" + +We believe in Sanic so much that we decided to put it to the ultimate test—running our own website. It's like a chef eating at their own restaurant, only with less risk of food poisoning. + +Why? Because building a website or web application is hard. There are countless moving parts, a plethora of challenges, and the ever-present need for speed and reliability. We want to show you just one of the many ways you _could_ do it. + +In this high-stakes digital kitchen, Sanic is our secret ingredient. By deploying our own website on Sanic, we're not just showcasing its capabilities; we're stress-testing them in the real world. This is our chance to walk the walk, proving that Sanic isn't just good on paper—it's a robust, high-performance framework that can handle everything from the smallest blog to the busiest e-commerce site. + +So, here we are, sipping our own champagne, confident in the knowledge that if Sanic can run our site, it can power yours too. Cheers to coding at the speed of thought! 🥂 + +### The Setup: Digital Ocean, Ahoy! + +We launched our site on Digital Ocean's App Platform because we love high-performance cloud sailing. Think of it as having a Ferrari in the cloud—fast, sleek, but way easier to handle. + +Why go for simplicity? With a lean team and no DevOps gurus, we needed a no-fuss, straightforward solution. Digital Ocean gives us that smooth sailing platform-as-a-service (PaaS) experience. It’s perfect for our needs: easy setup, automatic deployments, and the kind of reliability that lets you sleep soundly. + +Our choice reflects our ethos: focus on your strengths and let the platform do the heavy lifting. For us, it means creating amazing web experiences with Sanic, supported by a deployment solution that's simple yet powerful. ⛵ + +### The Code: GitHub's Where It's At + +All our code is out in the open, basking in the glory of public scrutiny on GitHub. Why hide the magic? It's right there, in full view, at [our GitHub repository](https://github.com/sanic-org/sanic/tree/main/guide). Go ahead, take a peek, fork it, play with it, break it (and then kindly fix it). + +Open-source isn't just a buzzword for us; it's our ethos. It's about building something bigger than ourselves, together. Our code is a testament to collaborative innovation, a playground for development, and a real-life example of Sanic in action. + +Every line of code, every commit, reflects our journey with Sanic, showcasing how we leverage its speed and scalability. Your contributions, whether fixing a bug, suggesting a feature, or enhancing documentation, are what propel this project forward. + +So, dive in, contribute your genius, and let's keep shaping the future of web development with Sanic. Together, we're not just coding – we're creating a community-driven powerhouse. 🚀 + +### The Invitation: Write, Code, Break, Fix! + +- **Documentarians**: Love making complex stuff sound easy? Our docs are your canvas. Paint away in words! 🎨 + +- **Code Ninjas**: Find bugs? Squash 'em. Got ideas? Code 'em. Make pull requests rain! 🥷 + +- **Bug Hunters**: If you find bugs, don't just stare. Let us know. We love a good bug hunt. 🐛 + +### The Bottom Line + +We built this site with Sanic to show off what it can do. It's fast, it's fun, and it's what we use. So, if things load swiftly, pat us on the back. If they don't, well, uh... we blame cosmic rays? + +Join us in making Sanic not just good, but "I-can't-believe-it's-not-butter" good! + +Cheers, +The Sanic Team (who occasionally wear capes) From 9ce108bd2b31ef7cd9112ab48699fcd0d469d61d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:15 +0200 Subject: [PATCH 002/698] New translations built-with-sanic.md (Korean) --- guide/content/ko/built-with-sanic.md | 67 ++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 guide/content/ko/built-with-sanic.md diff --git a/guide/content/ko/built-with-sanic.md b/guide/content/ko/built-with-sanic.md new file mode 100644 index 0000000000..fa5d78e1cf --- /dev/null +++ b/guide/content/ko/built-with-sanic.md @@ -0,0 +1,67 @@ +--- +title: Full Speed Ahead - How We Built This Site with Sanic +layout: main +--- + +.. attrs:: +:class: title + +``` +Full Speed Ahead: +``` + +.. attrs:: +:class: subtitle + +``` +How We Built This Site with Sanic +``` + +Welcome to our little corner of the Internet where we proudly say, "Yes, we built this with Sanic!" This isn't just a website; it's our playground, our test lab, our battlefield, and, well, our home. + +![](/assets/images/built-with-sanic.png) + +### The Story: "We Drink Our Own Champagne" + +We believe in Sanic so much that we decided to put it to the ultimate test—running our own website. It's like a chef eating at their own restaurant, only with less risk of food poisoning. + +Why? Because building a website or web application is hard. There are countless moving parts, a plethora of challenges, and the ever-present need for speed and reliability. We want to show you just one of the many ways you _could_ do it. + +In this high-stakes digital kitchen, Sanic is our secret ingredient. By deploying our own website on Sanic, we're not just showcasing its capabilities; we're stress-testing them in the real world. This is our chance to walk the walk, proving that Sanic isn't just good on paper—it's a robust, high-performance framework that can handle everything from the smallest blog to the busiest e-commerce site. + +So, here we are, sipping our own champagne, confident in the knowledge that if Sanic can run our site, it can power yours too. Cheers to coding at the speed of thought! 🥂 + +### The Setup: Digital Ocean, Ahoy! + +We launched our site on Digital Ocean's App Platform because we love high-performance cloud sailing. Think of it as having a Ferrari in the cloud—fast, sleek, but way easier to handle. + +Why go for simplicity? With a lean team and no DevOps gurus, we needed a no-fuss, straightforward solution. Digital Ocean gives us that smooth sailing platform-as-a-service (PaaS) experience. It’s perfect for our needs: easy setup, automatic deployments, and the kind of reliability that lets you sleep soundly. + +Our choice reflects our ethos: focus on your strengths and let the platform do the heavy lifting. For us, it means creating amazing web experiences with Sanic, supported by a deployment solution that's simple yet powerful. ⛵ + +### The Code: GitHub's Where It's At + +All our code is out in the open, basking in the glory of public scrutiny on GitHub. Why hide the magic? It's right there, in full view, at [our GitHub repository](https://github.com/sanic-org/sanic/tree/main/guide). Go ahead, take a peek, fork it, play with it, break it (and then kindly fix it). + +Open-source isn't just a buzzword for us; it's our ethos. It's about building something bigger than ourselves, together. Our code is a testament to collaborative innovation, a playground for development, and a real-life example of Sanic in action. + +Every line of code, every commit, reflects our journey with Sanic, showcasing how we leverage its speed and scalability. Your contributions, whether fixing a bug, suggesting a feature, or enhancing documentation, are what propel this project forward. + +So, dive in, contribute your genius, and let's keep shaping the future of web development with Sanic. Together, we're not just coding – we're creating a community-driven powerhouse. 🚀 + +### The Invitation: Write, Code, Break, Fix! + +- **Documentarians**: Love making complex stuff sound easy? Our docs are your canvas. Paint away in words! 🎨 + +- **Code Ninjas**: Find bugs? Squash 'em. Got ideas? Code 'em. Make pull requests rain! 🥷 + +- **Bug Hunters**: If you find bugs, don't just stare. Let us know. We love a good bug hunt. 🐛 + +### The Bottom Line + +We built this site with Sanic to show off what it can do. It's fast, it's fun, and it's what we use. So, if things load swiftly, pat us on the back. If they don't, well, uh... we blame cosmic rays? + +Join us in making Sanic not just good, but "I-can't-believe-it's-not-butter" good! + +Cheers, +The Sanic Team (who occasionally wear capes) From aa532989a7999a88811d0b5e378537a91fd98881 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:16 +0200 Subject: [PATCH 003/698] New translations built-with-sanic.md (Chinese Simplified) --- guide/content/zh/built-with-sanic.md | 67 ++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 guide/content/zh/built-with-sanic.md diff --git a/guide/content/zh/built-with-sanic.md b/guide/content/zh/built-with-sanic.md new file mode 100644 index 0000000000..fa5d78e1cf --- /dev/null +++ b/guide/content/zh/built-with-sanic.md @@ -0,0 +1,67 @@ +--- +title: Full Speed Ahead - How We Built This Site with Sanic +layout: main +--- + +.. attrs:: +:class: title + +``` +Full Speed Ahead: +``` + +.. attrs:: +:class: subtitle + +``` +How We Built This Site with Sanic +``` + +Welcome to our little corner of the Internet where we proudly say, "Yes, we built this with Sanic!" This isn't just a website; it's our playground, our test lab, our battlefield, and, well, our home. + +![](/assets/images/built-with-sanic.png) + +### The Story: "We Drink Our Own Champagne" + +We believe in Sanic so much that we decided to put it to the ultimate test—running our own website. It's like a chef eating at their own restaurant, only with less risk of food poisoning. + +Why? Because building a website or web application is hard. There are countless moving parts, a plethora of challenges, and the ever-present need for speed and reliability. We want to show you just one of the many ways you _could_ do it. + +In this high-stakes digital kitchen, Sanic is our secret ingredient. By deploying our own website on Sanic, we're not just showcasing its capabilities; we're stress-testing them in the real world. This is our chance to walk the walk, proving that Sanic isn't just good on paper—it's a robust, high-performance framework that can handle everything from the smallest blog to the busiest e-commerce site. + +So, here we are, sipping our own champagne, confident in the knowledge that if Sanic can run our site, it can power yours too. Cheers to coding at the speed of thought! 🥂 + +### The Setup: Digital Ocean, Ahoy! + +We launched our site on Digital Ocean's App Platform because we love high-performance cloud sailing. Think of it as having a Ferrari in the cloud—fast, sleek, but way easier to handle. + +Why go for simplicity? With a lean team and no DevOps gurus, we needed a no-fuss, straightforward solution. Digital Ocean gives us that smooth sailing platform-as-a-service (PaaS) experience. It’s perfect for our needs: easy setup, automatic deployments, and the kind of reliability that lets you sleep soundly. + +Our choice reflects our ethos: focus on your strengths and let the platform do the heavy lifting. For us, it means creating amazing web experiences with Sanic, supported by a deployment solution that's simple yet powerful. ⛵ + +### The Code: GitHub's Where It's At + +All our code is out in the open, basking in the glory of public scrutiny on GitHub. Why hide the magic? It's right there, in full view, at [our GitHub repository](https://github.com/sanic-org/sanic/tree/main/guide). Go ahead, take a peek, fork it, play with it, break it (and then kindly fix it). + +Open-source isn't just a buzzword for us; it's our ethos. It's about building something bigger than ourselves, together. Our code is a testament to collaborative innovation, a playground for development, and a real-life example of Sanic in action. + +Every line of code, every commit, reflects our journey with Sanic, showcasing how we leverage its speed and scalability. Your contributions, whether fixing a bug, suggesting a feature, or enhancing documentation, are what propel this project forward. + +So, dive in, contribute your genius, and let's keep shaping the future of web development with Sanic. Together, we're not just coding – we're creating a community-driven powerhouse. 🚀 + +### The Invitation: Write, Code, Break, Fix! + +- **Documentarians**: Love making complex stuff sound easy? Our docs are your canvas. Paint away in words! 🎨 + +- **Code Ninjas**: Find bugs? Squash 'em. Got ideas? Code 'em. Make pull requests rain! 🥷 + +- **Bug Hunters**: If you find bugs, don't just stare. Let us know. We love a good bug hunt. 🐛 + +### The Bottom Line + +We built this site with Sanic to show off what it can do. It's fast, it's fun, and it's what we use. So, if things load swiftly, pat us on the back. If they don't, well, uh... we blame cosmic rays? + +Join us in making Sanic not just good, but "I-can't-believe-it's-not-butter" good! + +Cheers, +The Sanic Team (who occasionally wear capes) From ce8766fb386582cdb10d58e6bd56a552650c195f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:17 +0200 Subject: [PATCH 004/698] New translations class-based-views.md (Japanese) --- .../ja/guide/advanced/class-based-views.md | 227 ++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 guide/content/ja/guide/advanced/class-based-views.md diff --git a/guide/content/ja/guide/advanced/class-based-views.md b/guide/content/ja/guide/advanced/class-based-views.md new file mode 100644 index 0000000000..901e0848bf --- /dev/null +++ b/guide/content/ja/guide/advanced/class-based-views.md @@ -0,0 +1,227 @@ +# Class Based Views + +## Why use them? + +.. column:: + +``` +### The problem + +A common pattern when designing an API is to have multiple functionality on the same endpoint that depends upon the HTTP method. + +While both of these options work, they are not good design practices and may be hard to maintain over time as your project grows. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def foo_get(request): + ... + +@app.post("/foo") +async def foo_post(request): + ... + +@app.put("/foo") +async def foo_put(request): + ... + +@app.route("/bar", methods=["GET", "POST", "PATCH"]) +async def bar(request): + if request.method == "GET": + ... + + elif request.method == "POST": + ... + + elif request.method == "PATCH": + ... +``` +```` + +.. column:: + +``` +### The solution + +Class-based views are simply classes that implement response behavior to requests. They provide a way to compartmentalize handling of different HTTP request types at the same endpoint. +``` + +.. column:: + +```` +```python +from sanic.views import HTTPMethodView + +class FooBar(HTTPMethodView): + async def get(self, request): + ... + + async def post(self, request): + ... + + async def put(self, request): + ... + +app.add_route(FooBar.as_view(), "/foobar") +``` +```` + +## Defining a view + +A class-based view should subclass :class:`sanic.views.HTTPMethodView`. You can then implement class methods with the name of the corresponding HTTP method. If a request is received that has no defined method, a `405: Method not allowed` response will be generated. + +.. column:: + +``` +To register a class-based view on an endpoint, the `app.add_route` method is used. The first argument should be the defined class with the method `as_view` invoked, and the second should be the URL endpoint. + +The available methods are: + +- get +- post +- put +- patch +- delete +- head +- options +``` + +.. column:: + +```` +```python +from sanic.views import HTTPMethodView +from sanic.response import text + +class SimpleView(HTTPMethodView): + + def get(self, request): + return text("I am get method") + + # You can also use async syntax + async def post(self, request): + return text("I am post method") + + def put(self, request): + return text("I am put method") + + def patch(self, request): + return text("I am patch method") + + def delete(self, request): + return text("I am delete method") + +app.add_route(SimpleView.as_view(), "/") +``` +```` + +## Path parameters + +.. column:: + +``` +You can use path parameters exactly as discussed in [the routing section](/guide/basics/routing.md). +``` + +.. column:: + +```` +```python +class NameView(HTTPMethodView): + + def get(self, request, name): + return text("Hello {}".format(name)) + +app.add_route(NameView.as_view(), "/") +``` +```` + +## Decorators + +As discussed in [the decorators section](/guide/best-practices/decorators.md), often you will need to add functionality to endpoints with the use of decorators. You have two options with CBV: + +1. Apply to _all_ HTTP methods in the view +2. Apply individually to HTTP methods in the view + +Let's see what the options look like: + +.. column:: + +``` +### Apply to all methods + +If you want to add any decorators to the class, you can set the `decorators` class variable. These will be applied to the class when `as_view` is called. +``` + +.. column:: + +```` +```python +class ViewWithDecorator(HTTPMethodView): + decorators = [some_decorator_here] + + def get(self, request, name): + return text("Hello I have a decorator") + + def post(self, request, name): + return text("Hello I also have a decorator") + +app.add_route(ViewWithDecorator.as_view(), "/url") +``` +```` + +.. column:: + +``` +### Apply to individual methods + +But if you just want to decorate some methods and not all methods, you can as shown here. +``` + +.. column:: + +```` +```python +class ViewWithSomeDecorator(HTTPMethodView): + + @staticmethod + @some_decorator_here + def get(request, name): + return text("Hello I have a decorator") + + def post(self, request, name): + return text("Hello I do not have any decorators") + + @some_decorator_here + def patch(self, request, name): + return text("Hello I have a decorator") +``` +```` + +## Generating a URL + +.. column:: + +``` +This works just like [generating any other URL](/guide/basics/routing.md#generating-a-url), except that the class name is a part of the endpoint. +``` + +.. column:: + +```` +```python +@app.route("/") +def index(request): + url = app.url_for("SpecialClassView") + return redirect(url) + +class SpecialClassView(HTTPMethodView): + def get(self, request): + return text("Hello from the Special Class View!") + +app.add_route(SpecialClassView.as_view(), "/special_class_view") +``` +```` From e0e1815982ddd0ab637daf3fbaac19556d470a65 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:18 +0200 Subject: [PATCH 005/698] New translations class-based-views.md (Korean) --- .../ko/guide/advanced/class-based-views.md | 227 ++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 guide/content/ko/guide/advanced/class-based-views.md diff --git a/guide/content/ko/guide/advanced/class-based-views.md b/guide/content/ko/guide/advanced/class-based-views.md new file mode 100644 index 0000000000..901e0848bf --- /dev/null +++ b/guide/content/ko/guide/advanced/class-based-views.md @@ -0,0 +1,227 @@ +# Class Based Views + +## Why use them? + +.. column:: + +``` +### The problem + +A common pattern when designing an API is to have multiple functionality on the same endpoint that depends upon the HTTP method. + +While both of these options work, they are not good design practices and may be hard to maintain over time as your project grows. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def foo_get(request): + ... + +@app.post("/foo") +async def foo_post(request): + ... + +@app.put("/foo") +async def foo_put(request): + ... + +@app.route("/bar", methods=["GET", "POST", "PATCH"]) +async def bar(request): + if request.method == "GET": + ... + + elif request.method == "POST": + ... + + elif request.method == "PATCH": + ... +``` +```` + +.. column:: + +``` +### The solution + +Class-based views are simply classes that implement response behavior to requests. They provide a way to compartmentalize handling of different HTTP request types at the same endpoint. +``` + +.. column:: + +```` +```python +from sanic.views import HTTPMethodView + +class FooBar(HTTPMethodView): + async def get(self, request): + ... + + async def post(self, request): + ... + + async def put(self, request): + ... + +app.add_route(FooBar.as_view(), "/foobar") +``` +```` + +## Defining a view + +A class-based view should subclass :class:`sanic.views.HTTPMethodView`. You can then implement class methods with the name of the corresponding HTTP method. If a request is received that has no defined method, a `405: Method not allowed` response will be generated. + +.. column:: + +``` +To register a class-based view on an endpoint, the `app.add_route` method is used. The first argument should be the defined class with the method `as_view` invoked, and the second should be the URL endpoint. + +The available methods are: + +- get +- post +- put +- patch +- delete +- head +- options +``` + +.. column:: + +```` +```python +from sanic.views import HTTPMethodView +from sanic.response import text + +class SimpleView(HTTPMethodView): + + def get(self, request): + return text("I am get method") + + # You can also use async syntax + async def post(self, request): + return text("I am post method") + + def put(self, request): + return text("I am put method") + + def patch(self, request): + return text("I am patch method") + + def delete(self, request): + return text("I am delete method") + +app.add_route(SimpleView.as_view(), "/") +``` +```` + +## Path parameters + +.. column:: + +``` +You can use path parameters exactly as discussed in [the routing section](/guide/basics/routing.md). +``` + +.. column:: + +```` +```python +class NameView(HTTPMethodView): + + def get(self, request, name): + return text("Hello {}".format(name)) + +app.add_route(NameView.as_view(), "/") +``` +```` + +## Decorators + +As discussed in [the decorators section](/guide/best-practices/decorators.md), often you will need to add functionality to endpoints with the use of decorators. You have two options with CBV: + +1. Apply to _all_ HTTP methods in the view +2. Apply individually to HTTP methods in the view + +Let's see what the options look like: + +.. column:: + +``` +### Apply to all methods + +If you want to add any decorators to the class, you can set the `decorators` class variable. These will be applied to the class when `as_view` is called. +``` + +.. column:: + +```` +```python +class ViewWithDecorator(HTTPMethodView): + decorators = [some_decorator_here] + + def get(self, request, name): + return text("Hello I have a decorator") + + def post(self, request, name): + return text("Hello I also have a decorator") + +app.add_route(ViewWithDecorator.as_view(), "/url") +``` +```` + +.. column:: + +``` +### Apply to individual methods + +But if you just want to decorate some methods and not all methods, you can as shown here. +``` + +.. column:: + +```` +```python +class ViewWithSomeDecorator(HTTPMethodView): + + @staticmethod + @some_decorator_here + def get(request, name): + return text("Hello I have a decorator") + + def post(self, request, name): + return text("Hello I do not have any decorators") + + @some_decorator_here + def patch(self, request, name): + return text("Hello I have a decorator") +``` +```` + +## Generating a URL + +.. column:: + +``` +This works just like [generating any other URL](/guide/basics/routing.md#generating-a-url), except that the class name is a part of the endpoint. +``` + +.. column:: + +```` +```python +@app.route("/") +def index(request): + url = app.url_for("SpecialClassView") + return redirect(url) + +class SpecialClassView(HTTPMethodView): + def get(self, request): + return text("Hello from the Special Class View!") + +app.add_route(SpecialClassView.as_view(), "/special_class_view") +``` +```` From 2c5646eabbc7a1737903e83926cd58fd7240791a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:19 +0200 Subject: [PATCH 006/698] New translations class-based-views.md (Chinese Simplified) --- .../zh/guide/advanced/class-based-views.md | 227 ++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 guide/content/zh/guide/advanced/class-based-views.md diff --git a/guide/content/zh/guide/advanced/class-based-views.md b/guide/content/zh/guide/advanced/class-based-views.md new file mode 100644 index 0000000000..901e0848bf --- /dev/null +++ b/guide/content/zh/guide/advanced/class-based-views.md @@ -0,0 +1,227 @@ +# Class Based Views + +## Why use them? + +.. column:: + +``` +### The problem + +A common pattern when designing an API is to have multiple functionality on the same endpoint that depends upon the HTTP method. + +While both of these options work, they are not good design practices and may be hard to maintain over time as your project grows. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def foo_get(request): + ... + +@app.post("/foo") +async def foo_post(request): + ... + +@app.put("/foo") +async def foo_put(request): + ... + +@app.route("/bar", methods=["GET", "POST", "PATCH"]) +async def bar(request): + if request.method == "GET": + ... + + elif request.method == "POST": + ... + + elif request.method == "PATCH": + ... +``` +```` + +.. column:: + +``` +### The solution + +Class-based views are simply classes that implement response behavior to requests. They provide a way to compartmentalize handling of different HTTP request types at the same endpoint. +``` + +.. column:: + +```` +```python +from sanic.views import HTTPMethodView + +class FooBar(HTTPMethodView): + async def get(self, request): + ... + + async def post(self, request): + ... + + async def put(self, request): + ... + +app.add_route(FooBar.as_view(), "/foobar") +``` +```` + +## Defining a view + +A class-based view should subclass :class:`sanic.views.HTTPMethodView`. You can then implement class methods with the name of the corresponding HTTP method. If a request is received that has no defined method, a `405: Method not allowed` response will be generated. + +.. column:: + +``` +To register a class-based view on an endpoint, the `app.add_route` method is used. The first argument should be the defined class with the method `as_view` invoked, and the second should be the URL endpoint. + +The available methods are: + +- get +- post +- put +- patch +- delete +- head +- options +``` + +.. column:: + +```` +```python +from sanic.views import HTTPMethodView +from sanic.response import text + +class SimpleView(HTTPMethodView): + + def get(self, request): + return text("I am get method") + + # You can also use async syntax + async def post(self, request): + return text("I am post method") + + def put(self, request): + return text("I am put method") + + def patch(self, request): + return text("I am patch method") + + def delete(self, request): + return text("I am delete method") + +app.add_route(SimpleView.as_view(), "/") +``` +```` + +## Path parameters + +.. column:: + +``` +You can use path parameters exactly as discussed in [the routing section](/guide/basics/routing.md). +``` + +.. column:: + +```` +```python +class NameView(HTTPMethodView): + + def get(self, request, name): + return text("Hello {}".format(name)) + +app.add_route(NameView.as_view(), "/") +``` +```` + +## Decorators + +As discussed in [the decorators section](/guide/best-practices/decorators.md), often you will need to add functionality to endpoints with the use of decorators. You have two options with CBV: + +1. Apply to _all_ HTTP methods in the view +2. Apply individually to HTTP methods in the view + +Let's see what the options look like: + +.. column:: + +``` +### Apply to all methods + +If you want to add any decorators to the class, you can set the `decorators` class variable. These will be applied to the class when `as_view` is called. +``` + +.. column:: + +```` +```python +class ViewWithDecorator(HTTPMethodView): + decorators = [some_decorator_here] + + def get(self, request, name): + return text("Hello I have a decorator") + + def post(self, request, name): + return text("Hello I also have a decorator") + +app.add_route(ViewWithDecorator.as_view(), "/url") +``` +```` + +.. column:: + +``` +### Apply to individual methods + +But if you just want to decorate some methods and not all methods, you can as shown here. +``` + +.. column:: + +```` +```python +class ViewWithSomeDecorator(HTTPMethodView): + + @staticmethod + @some_decorator_here + def get(request, name): + return text("Hello I have a decorator") + + def post(self, request, name): + return text("Hello I do not have any decorators") + + @some_decorator_here + def patch(self, request, name): + return text("Hello I have a decorator") +``` +```` + +## Generating a URL + +.. column:: + +``` +This works just like [generating any other URL](/guide/basics/routing.md#generating-a-url), except that the class name is a part of the endpoint. +``` + +.. column:: + +```` +```python +@app.route("/") +def index(request): + url = app.url_for("SpecialClassView") + return redirect(url) + +class SpecialClassView(HTTPMethodView): + def get(self, request): + return text("Hello from the Special Class View!") + +app.add_route(SpecialClassView.as_view(), "/special_class_view") +``` +```` From 3aba6f0e2eaa4651a6e9da63095c19ea93892fa1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:20 +0200 Subject: [PATCH 007/698] New translations proxy-headers.md (Japanese) --- .../ja/guide/advanced/proxy-headers.md | 576 ++++++++++++++++++ 1 file changed, 576 insertions(+) create mode 100644 guide/content/ja/guide/advanced/proxy-headers.md diff --git a/guide/content/ja/guide/advanced/proxy-headers.md b/guide/content/ja/guide/advanced/proxy-headers.md new file mode 100644 index 0000000000..ff151b592b --- /dev/null +++ b/guide/content/ja/guide/advanced/proxy-headers.md @@ -0,0 +1,576 @@ +# Proxy configuration + +When you use a reverse proxy server (e.g. nginx), the value of `request.ip` will contain the IP of a proxy, typically `127.0.0.1`. Almost always, this is **not** what you will want. + +Sanic may be configured to use proxy headers for determining the true client IP, available as `request.remote_addr`. The full external URL is also constructed from header fields _if available_. + +.. tip:: Heads up + +``` +Without proper precautions, a malicious client may use proxy headers to spoof its own IP. To avoid such issues, Sanic does not use any proxy headers unless explicitly enabled. +``` + +.. column:: + +``` +Services behind reverse proxies must configure one or more of the following [configuration values](/guide/deployment/configuration.md): + +- `FORWARDED_SECRET` +- `REAL_IP_HEADER` +- `PROXIES_COUNT` +``` + +.. column:: + +```` +```python +app.config.FORWARDED_SECRET = "super-duper-secret" +app.config.REAL_IP_HEADER = "CF-Connecting-IP" +app.config.PROXIES_COUNT = 2 +``` +```` + +## Forwarded header + +In order to use the `Forwarded` header, you should set `app.config.FORWARDED_SECRET` to a value known to the trusted proxy server. The secret is used to securely identify a specific proxy server. + +Sanic ignores any elements without the secret key, and will not even parse the header if no secret is set. + +All other proxy headers are ignored once a trusted forwarded element is found, as it already carries complete information about the client. + +To learn more about the `Forwarded` header, read the related [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) and [Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) articles. + +## Traditional proxy headers + +### IP Headers + +When your proxy forwards you the IP address in a known header, you can tell Sanic what that is with the `REAL_IP_HEADER` config value. + +### X-Forwarded-For + +This header typically contains a chain of IP addresses through each layer of a proxy. Setting `PROXIES_COUNT` tells Sanic how deep to look to get an actual IP address for the client. This value should equal the _expected_ number of IP addresses in the chain. + +### Other X-headers + +If a client IP is found by one of these methods, Sanic uses the following headers for URL parts: + +- x-forwarded-proto +- x-forwarded-host +- x-forwarded-port +- x-forwarded-path +- x-scheme + +## Examples + +In the following examples, all requests will assume that the endpoint looks like this: + +```python +@app.route("/fwd") +async def forwarded(request): + return json( + { + "remote_addr": request.remote_addr, + "scheme": request.scheme, + "server_name": request.server_name, + "server_port": request.server_port, + "forwarded": request.forwarded, + } + ) +``` + +*** + +##### Example 1 + +Without configured FORWARDED_SECRET, x-headers should be respected + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "ws", + "server_name": "local.site", + "server_port": 80, + "forwarded": { + "for": "127.0.0.2", + "proto": "ws" + } +} +``` +```` + +*** + +##### Example 2 + +FORWARDED_SECRET now configured + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "[::2]", + "scheme": "https", + "server_name": "me.tld", + "server_port": 443, + "forwarded": { + "for": "[::2]", + "proto": "https", + "host": "me.tld", + "path": "/app/", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 3 + +Empty Forwarded header -> use X-headers + +```sh +curl localhost:8000/fwd \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "ws", + "server_name": "local.site", + "server_port": 80, + "forwarded": { + "for": "127.0.0.2", + "proto": "ws" + } +} +``` +```` + +*** + +##### Example 4 + +Header present but not matching anything + +```sh +curl localhost:8000/fwd \ + -H "Forwarded: nomatch" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": {} +} + +``` +```` + +*** + +##### Example 5 + +Forwarded header present but no matching secret -> use X-headers + +```sh +curl localhost:8000/fwd \ + -H "Forwarded: for=1.1.1.1;secret=x, for=127.0.0.1" \ + -H "X-Real-IP: 127.0.0.2" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "127.0.0.2" + } +} +``` +```` + +*** + +##### Example 6 + +Different formatting and hitting both ends of the header + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: Secret="mySecret";For=127.0.0.4;Port=1234' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.4", + "scheme": "http", + "server_name": "localhost", + "server_port": 1234, + "forwarded": { + "secret": "mySecret", + "for": "127.0.0.4", + "port": 1234 + } +} +``` +```` + +*** + +##### Example 7 + +Test escapes (modify this if you see anyone implementing quoted-pairs) + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;quoted="\,x=x;y=\";secret=mySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "test", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "test", + "quoted": "\\,x=x;y=\\", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 8 + +Secret insulated by malformed field #1 + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;secret=mySecret;b0rked;proto=wss;' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "test", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "test", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 9 + +Secret insulated by malformed field #2 + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;b0rked;secret=mySecret;proto=wss' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "secret": "mySecret", + "proto": "wss" + } +} +``` +```` + +*** + +##### Example 10 + +Unexpected termination should not lose existing acceptable values + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: b0rked;secret=mySecret;proto=wss' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "secret": "mySecret", + "proto": "wss" + } +} +``` +```` + +*** + +##### Example 11 + +Field normalization + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: PROTO=WSS;BY="CAFE::8000";FOR=unknown;PORT=X;HOST="A:2";PATH="/With%20Spaces%22Quoted%22/sanicApp?key=val";SECRET=mySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "a", + "server_port": 2, + "forwarded": { + "proto": "wss", + "by": "[cafe::8000]", + "host": "a:2", + "path": "/With Spaces\"Quoted\"/sanicApp?key=val", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 12 + +Using "by" field as secret + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.2.3.4; by=_proxySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "_proxySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "1.2.3.4", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "1.2.3.4", + "by": "_proxySecret" + } +} + +``` +```` From f5e11b51dbedfbf840781db1a601d29fb620ce0f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:21 +0200 Subject: [PATCH 008/698] New translations proxy-headers.md (Korean) --- .../ko/guide/advanced/proxy-headers.md | 576 ++++++++++++++++++ 1 file changed, 576 insertions(+) create mode 100644 guide/content/ko/guide/advanced/proxy-headers.md diff --git a/guide/content/ko/guide/advanced/proxy-headers.md b/guide/content/ko/guide/advanced/proxy-headers.md new file mode 100644 index 0000000000..ff151b592b --- /dev/null +++ b/guide/content/ko/guide/advanced/proxy-headers.md @@ -0,0 +1,576 @@ +# Proxy configuration + +When you use a reverse proxy server (e.g. nginx), the value of `request.ip` will contain the IP of a proxy, typically `127.0.0.1`. Almost always, this is **not** what you will want. + +Sanic may be configured to use proxy headers for determining the true client IP, available as `request.remote_addr`. The full external URL is also constructed from header fields _if available_. + +.. tip:: Heads up + +``` +Without proper precautions, a malicious client may use proxy headers to spoof its own IP. To avoid such issues, Sanic does not use any proxy headers unless explicitly enabled. +``` + +.. column:: + +``` +Services behind reverse proxies must configure one or more of the following [configuration values](/guide/deployment/configuration.md): + +- `FORWARDED_SECRET` +- `REAL_IP_HEADER` +- `PROXIES_COUNT` +``` + +.. column:: + +```` +```python +app.config.FORWARDED_SECRET = "super-duper-secret" +app.config.REAL_IP_HEADER = "CF-Connecting-IP" +app.config.PROXIES_COUNT = 2 +``` +```` + +## Forwarded header + +In order to use the `Forwarded` header, you should set `app.config.FORWARDED_SECRET` to a value known to the trusted proxy server. The secret is used to securely identify a specific proxy server. + +Sanic ignores any elements without the secret key, and will not even parse the header if no secret is set. + +All other proxy headers are ignored once a trusted forwarded element is found, as it already carries complete information about the client. + +To learn more about the `Forwarded` header, read the related [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) and [Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) articles. + +## Traditional proxy headers + +### IP Headers + +When your proxy forwards you the IP address in a known header, you can tell Sanic what that is with the `REAL_IP_HEADER` config value. + +### X-Forwarded-For + +This header typically contains a chain of IP addresses through each layer of a proxy. Setting `PROXIES_COUNT` tells Sanic how deep to look to get an actual IP address for the client. This value should equal the _expected_ number of IP addresses in the chain. + +### Other X-headers + +If a client IP is found by one of these methods, Sanic uses the following headers for URL parts: + +- x-forwarded-proto +- x-forwarded-host +- x-forwarded-port +- x-forwarded-path +- x-scheme + +## Examples + +In the following examples, all requests will assume that the endpoint looks like this: + +```python +@app.route("/fwd") +async def forwarded(request): + return json( + { + "remote_addr": request.remote_addr, + "scheme": request.scheme, + "server_name": request.server_name, + "server_port": request.server_port, + "forwarded": request.forwarded, + } + ) +``` + +*** + +##### Example 1 + +Without configured FORWARDED_SECRET, x-headers should be respected + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "ws", + "server_name": "local.site", + "server_port": 80, + "forwarded": { + "for": "127.0.0.2", + "proto": "ws" + } +} +``` +```` + +*** + +##### Example 2 + +FORWARDED_SECRET now configured + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "[::2]", + "scheme": "https", + "server_name": "me.tld", + "server_port": 443, + "forwarded": { + "for": "[::2]", + "proto": "https", + "host": "me.tld", + "path": "/app/", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 3 + +Empty Forwarded header -> use X-headers + +```sh +curl localhost:8000/fwd \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "ws", + "server_name": "local.site", + "server_port": 80, + "forwarded": { + "for": "127.0.0.2", + "proto": "ws" + } +} +``` +```` + +*** + +##### Example 4 + +Header present but not matching anything + +```sh +curl localhost:8000/fwd \ + -H "Forwarded: nomatch" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": {} +} + +``` +```` + +*** + +##### Example 5 + +Forwarded header present but no matching secret -> use X-headers + +```sh +curl localhost:8000/fwd \ + -H "Forwarded: for=1.1.1.1;secret=x, for=127.0.0.1" \ + -H "X-Real-IP: 127.0.0.2" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "127.0.0.2" + } +} +``` +```` + +*** + +##### Example 6 + +Different formatting and hitting both ends of the header + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: Secret="mySecret";For=127.0.0.4;Port=1234' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.4", + "scheme": "http", + "server_name": "localhost", + "server_port": 1234, + "forwarded": { + "secret": "mySecret", + "for": "127.0.0.4", + "port": 1234 + } +} +``` +```` + +*** + +##### Example 7 + +Test escapes (modify this if you see anyone implementing quoted-pairs) + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;quoted="\,x=x;y=\";secret=mySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "test", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "test", + "quoted": "\\,x=x;y=\\", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 8 + +Secret insulated by malformed field #1 + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;secret=mySecret;b0rked;proto=wss;' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "test", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "test", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 9 + +Secret insulated by malformed field #2 + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;b0rked;secret=mySecret;proto=wss' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "secret": "mySecret", + "proto": "wss" + } +} +``` +```` + +*** + +##### Example 10 + +Unexpected termination should not lose existing acceptable values + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: b0rked;secret=mySecret;proto=wss' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "secret": "mySecret", + "proto": "wss" + } +} +``` +```` + +*** + +##### Example 11 + +Field normalization + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: PROTO=WSS;BY="CAFE::8000";FOR=unknown;PORT=X;HOST="A:2";PATH="/With%20Spaces%22Quoted%22/sanicApp?key=val";SECRET=mySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "a", + "server_port": 2, + "forwarded": { + "proto": "wss", + "by": "[cafe::8000]", + "host": "a:2", + "path": "/With Spaces\"Quoted\"/sanicApp?key=val", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 12 + +Using "by" field as secret + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.2.3.4; by=_proxySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "_proxySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "1.2.3.4", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "1.2.3.4", + "by": "_proxySecret" + } +} + +``` +```` From 1560639d62e3bf3924399f6073af5548fec56857 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:22 +0200 Subject: [PATCH 009/698] New translations proxy-headers.md (Chinese Simplified) --- .../zh/guide/advanced/proxy-headers.md | 576 ++++++++++++++++++ 1 file changed, 576 insertions(+) create mode 100644 guide/content/zh/guide/advanced/proxy-headers.md diff --git a/guide/content/zh/guide/advanced/proxy-headers.md b/guide/content/zh/guide/advanced/proxy-headers.md new file mode 100644 index 0000000000..ff151b592b --- /dev/null +++ b/guide/content/zh/guide/advanced/proxy-headers.md @@ -0,0 +1,576 @@ +# Proxy configuration + +When you use a reverse proxy server (e.g. nginx), the value of `request.ip` will contain the IP of a proxy, typically `127.0.0.1`. Almost always, this is **not** what you will want. + +Sanic may be configured to use proxy headers for determining the true client IP, available as `request.remote_addr`. The full external URL is also constructed from header fields _if available_. + +.. tip:: Heads up + +``` +Without proper precautions, a malicious client may use proxy headers to spoof its own IP. To avoid such issues, Sanic does not use any proxy headers unless explicitly enabled. +``` + +.. column:: + +``` +Services behind reverse proxies must configure one or more of the following [configuration values](/guide/deployment/configuration.md): + +- `FORWARDED_SECRET` +- `REAL_IP_HEADER` +- `PROXIES_COUNT` +``` + +.. column:: + +```` +```python +app.config.FORWARDED_SECRET = "super-duper-secret" +app.config.REAL_IP_HEADER = "CF-Connecting-IP" +app.config.PROXIES_COUNT = 2 +``` +```` + +## Forwarded header + +In order to use the `Forwarded` header, you should set `app.config.FORWARDED_SECRET` to a value known to the trusted proxy server. The secret is used to securely identify a specific proxy server. + +Sanic ignores any elements without the secret key, and will not even parse the header if no secret is set. + +All other proxy headers are ignored once a trusted forwarded element is found, as it already carries complete information about the client. + +To learn more about the `Forwarded` header, read the related [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) and [Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) articles. + +## Traditional proxy headers + +### IP Headers + +When your proxy forwards you the IP address in a known header, you can tell Sanic what that is with the `REAL_IP_HEADER` config value. + +### X-Forwarded-For + +This header typically contains a chain of IP addresses through each layer of a proxy. Setting `PROXIES_COUNT` tells Sanic how deep to look to get an actual IP address for the client. This value should equal the _expected_ number of IP addresses in the chain. + +### Other X-headers + +If a client IP is found by one of these methods, Sanic uses the following headers for URL parts: + +- x-forwarded-proto +- x-forwarded-host +- x-forwarded-port +- x-forwarded-path +- x-scheme + +## Examples + +In the following examples, all requests will assume that the endpoint looks like this: + +```python +@app.route("/fwd") +async def forwarded(request): + return json( + { + "remote_addr": request.remote_addr, + "scheme": request.scheme, + "server_name": request.server_name, + "server_port": request.server_port, + "forwarded": request.forwarded, + } + ) +``` + +*** + +##### Example 1 + +Without configured FORWARDED_SECRET, x-headers should be respected + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "ws", + "server_name": "local.site", + "server_port": 80, + "forwarded": { + "for": "127.0.0.2", + "proto": "ws" + } +} +``` +```` + +*** + +##### Example 2 + +FORWARDED_SECRET now configured + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "[::2]", + "scheme": "https", + "server_name": "me.tld", + "server_port": 443, + "forwarded": { + "for": "[::2]", + "proto": "https", + "host": "me.tld", + "path": "/app/", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 3 + +Empty Forwarded header -> use X-headers + +```sh +curl localhost:8000/fwd \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "ws", + "server_name": "local.site", + "server_port": 80, + "forwarded": { + "for": "127.0.0.2", + "proto": "ws" + } +} +``` +```` + +*** + +##### Example 4 + +Header present but not matching anything + +```sh +curl localhost:8000/fwd \ + -H "Forwarded: nomatch" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": {} +} + +``` +```` + +*** + +##### Example 5 + +Forwarded header present but no matching secret -> use X-headers + +```sh +curl localhost:8000/fwd \ + -H "Forwarded: for=1.1.1.1;secret=x, for=127.0.0.1" \ + -H "X-Real-IP: 127.0.0.2" | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.2", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "127.0.0.2" + } +} +``` +```` + +*** + +##### Example 6 + +Different formatting and hitting both ends of the header + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: Secret="mySecret";For=127.0.0.4;Port=1234' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "127.0.0.4", + "scheme": "http", + "server_name": "localhost", + "server_port": 1234, + "forwarded": { + "secret": "mySecret", + "for": "127.0.0.4", + "port": 1234 + } +} +``` +```` + +*** + +##### Example 7 + +Test escapes (modify this if you see anyone implementing quoted-pairs) + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;quoted="\,x=x;y=\";secret=mySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "test", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "test", + "quoted": "\\,x=x;y=\\", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 8 + +Secret insulated by malformed field #1 + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;secret=mySecret;b0rked;proto=wss;' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "test", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "test", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 9 + +Secret insulated by malformed field #2 + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=test;b0rked;secret=mySecret;proto=wss' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "secret": "mySecret", + "proto": "wss" + } +} +``` +```` + +*** + +##### Example 10 + +Unexpected termination should not lose existing acceptable values + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: b0rked;secret=mySecret;proto=wss' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "secret": "mySecret", + "proto": "wss" + } +} +``` +```` + +*** + +##### Example 11 + +Field normalization + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: PROTO=WSS;BY="CAFE::8000";FOR=unknown;PORT=X;HOST="A:2";PATH="/With%20Spaces%22Quoted%22/sanicApp?key=val";SECRET=mySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "mySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "", + "scheme": "wss", + "server_name": "a", + "server_port": 2, + "forwarded": { + "proto": "wss", + "by": "[cafe::8000]", + "host": "a:2", + "path": "/With Spaces\"Quoted\"/sanicApp?key=val", + "secret": "mySecret" + } +} +``` +```` + +*** + +##### Example 12 + +Using "by" field as secret + +```sh +curl localhost:8000/fwd \ + -H 'Forwarded: for=1.2.3.4; by=_proxySecret' | jq +``` + +.. column:: + +```` +```python +# Sanic application config +app.config.PROXIES_COUNT = 1 +app.config.REAL_IP_HEADER = "x-real-ip" +app.config.FORWARDED_SECRET = "_proxySecret" +``` +```` + +.. column:: + +```` +```bash +# curl response +{ + "remote_addr": "1.2.3.4", + "scheme": "http", + "server_name": "localhost", + "server_port": 8000, + "forwarded": { + "for": "1.2.3.4", + "by": "_proxySecret" + } +} + +``` +```` From 9665373d6a2717bc75c190befc94d2f7dd318309 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:23 +0200 Subject: [PATCH 010/698] New translations signals.md (Japanese) --- guide/content/ja/guide/advanced/signals.md | 400 +++++++++++++++++++++ 1 file changed, 400 insertions(+) create mode 100644 guide/content/ja/guide/advanced/signals.md diff --git a/guide/content/ja/guide/advanced/signals.md b/guide/content/ja/guide/advanced/signals.md new file mode 100644 index 0000000000..971582bb1e --- /dev/null +++ b/guide/content/ja/guide/advanced/signals.md @@ -0,0 +1,400 @@ +# Signals + +Signals provide a way for one part of your application to tell another part that something happened. + +```python +@app.signal("user.registration.created") +async def send_registration_email(**context): + await send_email(context["email"], template="registration") + +@app.post("/register") +async def handle_registration(request): + await do_registration(request) + await request.app.dispatch( + "user.registration.created", + context={"email": request.json.email} + }) +``` + +## Adding a signal + +.. column:: + +``` +The API for adding a signal is very similar to adding a route. +``` + +.. column:: + +```` +```python +async def my_signal_handler(): + print("something happened") + +app.add_signal(my_signal_handler, "something.happened.ohmy") +``` +```` + +.. column:: + +``` +But, perhaps a slightly more convenient method is to use the built-in decorators. +``` + +.. column:: + +```` +```python +@app.signal("something.happened.ohmy") +async def my_signal_handler(): + print("something happened") +``` +```` + +.. column:: + +``` +If the signal requires conditions, make sure to add them while adding the handler. +``` + +.. column:: + +```` +```python +async def my_signal_handler1(): + print("something happened") + +app.add_signal( + my_signal_handler, + "something.happened.ohmy1", + conditions={"some_condition": "value"} +) + +@app.signal("something.happened.ohmy2", conditions={"some_condition": "value"}) +async def my_signal_handler2(): + print("something happened") +``` +```` + +.. column:: + +``` +Signals can also be declared on blueprints +``` + +.. column:: + +```` +```python +bp = Blueprint("foo") + +@bp.signal("something.happened.ohmy") +async def my_signal_handler(): + print("something happened") +``` +```` + +## Built-in signals + +In addition to creating a new signal, there are a number of built-in signals that are dispatched from Sanic itself. These signals exist to provide developers with more opportunities to add functionality into the request and server lifecycles. + +_Added in v21.9_ + +.. column:: + +``` +You can attach them just like any other signal to an application or blueprint instance. +``` + +.. column:: + +```` +```python +@app.signal("http.lifecycle.complete") +async def my_signal_handler(conn_info): + print("Connection has been closed") +``` +```` + +These signals are the signals that are available, along with the arguments that the handlers take, and the conditions that attach (if any). + +| Event name | Arguments | Conditions | +| -------------------------- | ------------------------------- | --------------------------------------------------------- | +| `http.routing.before` | request | | +| `http.routing.after` | request, route, kwargs, handler | | +| `http.handler.before` | request | | +| `http.handler.after` | request | | +| `http.lifecycle.begin` | conn_info | | +| `http.lifecycle.read_head` | head | | +| `http.lifecycle.request` | request | | +| `http.lifecycle.handle` | request | | +| `http.lifecycle.read_body` | body | | +| `http.lifecycle.exception` | request, exception | | +| `http.lifecycle.response` | request, response | | +| `http.lifecycle.send` | data | | +| `http.lifecycle.complete` | conn_info | | +| `http.middleware.before` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `http.middleware.after` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `server.exception.report` | app, exception | | +| `server.init.before` | app, loop | | +| `server.init.after` | app, loop | | +| `server.shutdown.before` | app, loop | | +| `server.shutdown.after` | app, loop | | + +Version 22.9 added `http.handler.before` and `http.handler.after`. + +Version 23.6 added `server.exception.report`. + +.. column:: + +``` +To make using the built-in signals easier, there is an `Enum` object that contains all of the allowed built-ins. With a modern IDE this will help so that you do not need to remember the full list of event names as strings. + +*Added in v21.12* +``` + +.. column:: + +```` +```python +from sanic.signals import Event + +@app.signal(Event.HTTP_LIFECYCLE_COMPLETE) +async def my_signal_handler(conn_info): + print("Connection has been closed") +``` +```` + +## Events + +.. column:: + +``` +Signals are based off of an _event_. An event, is simply a string in the following pattern: +``` + +.. column:: + +```` +``` +namespace.reference.action +``` +```` + +.. tip:: Events must have three parts. If you do not know what to use, try these patterns: + +``` +- `my_app.something.happened` +- `sanic.notice.hello` +``` + +### Event parameters + +.. column:: + +``` +An event can be "dynamic" and declared using the same syntax as [path parameters](../basics/routing.md#path-parameters). This allows matching based upon arbitrary values. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") +async def signal_handler(thing): + print(f"[signal_handler] {thing=}") + +@app.get("/") +async def trigger(request): + await app.dispatch("foo.bar.baz") + return response.text("Done.") +``` +```` + +Checkout [path parameters](../basics/routing.md#path-parameters) for more information on allowed type definitions. + +.. info:: Only the third part of an event (the action) may be dynamic: + +``` +- `foo.bar.` 🆗 +- `foo..baz` ❌ +``` + +### Waiting + +.. column:: + +``` +In addition to executing a signal handler, your application can wait for an event to be triggered. +``` + +.. column:: + +```` +```python +await app.event("foo.bar.baz") +``` +```` + +.. column:: + +``` +**IMPORTANT**: waiting is a blocking function. Therefore, you likely will want this to run in a [background task](../basics/tasks.md). +``` + +.. column:: + +```` +```python +async def wait_for_event(app): + while True: + print("> waiting") + await app.event("foo.bar.baz") + print("> event found\n") + +@app.after_server_start +async def after_server_start(app, loop): + app.add_task(wait_for_event(app)) +``` +```` + +.. column:: + +``` +If your event was defined with a dynamic path, you can use `*` to catch any action. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") + +... + +await app.event("foo.bar.*") +``` +```` + +## Dispatching + +_In the future, Sanic will dispatch some events automatically to assist developers to hook into life cycle events._ + +.. column:: + +``` +Dispatching an event will do two things: + +1. execute any signal handlers defined on the event, and +2. resolve anything that is "waiting" for the event to complete. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") +async def foo_bar(thing): + print(f"{thing=}") + +await app.dispatch("foo.bar.baz") +``` +``` +thing=baz +``` +```` + +### Context + +.. column:: + +``` +Sometimes you may find the need to pass extra information into the signal handler. In our first example above, we wanted our email registration process to have the email address for the user. +``` + +.. column:: + +```` +```python +@app.signal("user.registration.created") +async def send_registration_email(**context): + print(context) + +await app.dispatch( + "user.registration.created", + context={"hello": "world"} +) +``` +``` +{'hello': 'world'} +``` +```` + +.. tip:: FYI + +``` +Signals are dispatched in a background task. +``` + +### Blueprints + +Dispatching blueprint signals works similar in concept to [middleware](../basics/middleware.md). Anything that is done from the app level, will trickle down to the blueprints. However, dispatching on a blueprint, will only execute the signals that are defined on that blueprint. + +.. column:: + +``` +Perhaps an example is easier to explain: +``` + +.. column:: + +```` +```python +bp = Blueprint("bp") + +app_counter = 0 +bp_counter = 0 + +@app.signal("foo.bar.baz") +def app_signal(): + nonlocal app_counter + app_counter += 1 + +@bp.signal("foo.bar.baz") +def bp_signal(): + nonlocal bp_counter + bp_counter += 1 +``` +```` + +.. column:: + +``` +Running `app.dispatch("foo.bar.baz")` will execute both signals. +``` + +.. column:: + +```` +```python +await app.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 1 +``` +```` + +.. column:: + +``` +Running `bp.dispatch("foo.bar.baz")` will execute only the blueprint signal. +``` + +.. column:: + +```` +```python +await bp.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 2 +``` +```` From 9f62b13b45fb4896e3eb08e5445930ac0383c31b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:25 +0200 Subject: [PATCH 011/698] New translations signals.md (Korean) --- guide/content/ko/guide/advanced/signals.md | 400 +++++++++++++++++++++ 1 file changed, 400 insertions(+) create mode 100644 guide/content/ko/guide/advanced/signals.md diff --git a/guide/content/ko/guide/advanced/signals.md b/guide/content/ko/guide/advanced/signals.md new file mode 100644 index 0000000000..971582bb1e --- /dev/null +++ b/guide/content/ko/guide/advanced/signals.md @@ -0,0 +1,400 @@ +# Signals + +Signals provide a way for one part of your application to tell another part that something happened. + +```python +@app.signal("user.registration.created") +async def send_registration_email(**context): + await send_email(context["email"], template="registration") + +@app.post("/register") +async def handle_registration(request): + await do_registration(request) + await request.app.dispatch( + "user.registration.created", + context={"email": request.json.email} + }) +``` + +## Adding a signal + +.. column:: + +``` +The API for adding a signal is very similar to adding a route. +``` + +.. column:: + +```` +```python +async def my_signal_handler(): + print("something happened") + +app.add_signal(my_signal_handler, "something.happened.ohmy") +``` +```` + +.. column:: + +``` +But, perhaps a slightly more convenient method is to use the built-in decorators. +``` + +.. column:: + +```` +```python +@app.signal("something.happened.ohmy") +async def my_signal_handler(): + print("something happened") +``` +```` + +.. column:: + +``` +If the signal requires conditions, make sure to add them while adding the handler. +``` + +.. column:: + +```` +```python +async def my_signal_handler1(): + print("something happened") + +app.add_signal( + my_signal_handler, + "something.happened.ohmy1", + conditions={"some_condition": "value"} +) + +@app.signal("something.happened.ohmy2", conditions={"some_condition": "value"}) +async def my_signal_handler2(): + print("something happened") +``` +```` + +.. column:: + +``` +Signals can also be declared on blueprints +``` + +.. column:: + +```` +```python +bp = Blueprint("foo") + +@bp.signal("something.happened.ohmy") +async def my_signal_handler(): + print("something happened") +``` +```` + +## Built-in signals + +In addition to creating a new signal, there are a number of built-in signals that are dispatched from Sanic itself. These signals exist to provide developers with more opportunities to add functionality into the request and server lifecycles. + +_Added in v21.9_ + +.. column:: + +``` +You can attach them just like any other signal to an application or blueprint instance. +``` + +.. column:: + +```` +```python +@app.signal("http.lifecycle.complete") +async def my_signal_handler(conn_info): + print("Connection has been closed") +``` +```` + +These signals are the signals that are available, along with the arguments that the handlers take, and the conditions that attach (if any). + +| Event name | Arguments | Conditions | +| -------------------------- | ------------------------------- | --------------------------------------------------------- | +| `http.routing.before` | request | | +| `http.routing.after` | request, route, kwargs, handler | | +| `http.handler.before` | request | | +| `http.handler.after` | request | | +| `http.lifecycle.begin` | conn_info | | +| `http.lifecycle.read_head` | head | | +| `http.lifecycle.request` | request | | +| `http.lifecycle.handle` | request | | +| `http.lifecycle.read_body` | body | | +| `http.lifecycle.exception` | request, exception | | +| `http.lifecycle.response` | request, response | | +| `http.lifecycle.send` | data | | +| `http.lifecycle.complete` | conn_info | | +| `http.middleware.before` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `http.middleware.after` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `server.exception.report` | app, exception | | +| `server.init.before` | app, loop | | +| `server.init.after` | app, loop | | +| `server.shutdown.before` | app, loop | | +| `server.shutdown.after` | app, loop | | + +Version 22.9 added `http.handler.before` and `http.handler.after`. + +Version 23.6 added `server.exception.report`. + +.. column:: + +``` +To make using the built-in signals easier, there is an `Enum` object that contains all of the allowed built-ins. With a modern IDE this will help so that you do not need to remember the full list of event names as strings. + +*Added in v21.12* +``` + +.. column:: + +```` +```python +from sanic.signals import Event + +@app.signal(Event.HTTP_LIFECYCLE_COMPLETE) +async def my_signal_handler(conn_info): + print("Connection has been closed") +``` +```` + +## Events + +.. column:: + +``` +Signals are based off of an _event_. An event, is simply a string in the following pattern: +``` + +.. column:: + +```` +``` +namespace.reference.action +``` +```` + +.. tip:: Events must have three parts. If you do not know what to use, try these patterns: + +``` +- `my_app.something.happened` +- `sanic.notice.hello` +``` + +### Event parameters + +.. column:: + +``` +An event can be "dynamic" and declared using the same syntax as [path parameters](../basics/routing.md#path-parameters). This allows matching based upon arbitrary values. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") +async def signal_handler(thing): + print(f"[signal_handler] {thing=}") + +@app.get("/") +async def trigger(request): + await app.dispatch("foo.bar.baz") + return response.text("Done.") +``` +```` + +Checkout [path parameters](../basics/routing.md#path-parameters) for more information on allowed type definitions. + +.. info:: Only the third part of an event (the action) may be dynamic: + +``` +- `foo.bar.` 🆗 +- `foo..baz` ❌ +``` + +### Waiting + +.. column:: + +``` +In addition to executing a signal handler, your application can wait for an event to be triggered. +``` + +.. column:: + +```` +```python +await app.event("foo.bar.baz") +``` +```` + +.. column:: + +``` +**IMPORTANT**: waiting is a blocking function. Therefore, you likely will want this to run in a [background task](../basics/tasks.md). +``` + +.. column:: + +```` +```python +async def wait_for_event(app): + while True: + print("> waiting") + await app.event("foo.bar.baz") + print("> event found\n") + +@app.after_server_start +async def after_server_start(app, loop): + app.add_task(wait_for_event(app)) +``` +```` + +.. column:: + +``` +If your event was defined with a dynamic path, you can use `*` to catch any action. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") + +... + +await app.event("foo.bar.*") +``` +```` + +## Dispatching + +_In the future, Sanic will dispatch some events automatically to assist developers to hook into life cycle events._ + +.. column:: + +``` +Dispatching an event will do two things: + +1. execute any signal handlers defined on the event, and +2. resolve anything that is "waiting" for the event to complete. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") +async def foo_bar(thing): + print(f"{thing=}") + +await app.dispatch("foo.bar.baz") +``` +``` +thing=baz +``` +```` + +### Context + +.. column:: + +``` +Sometimes you may find the need to pass extra information into the signal handler. In our first example above, we wanted our email registration process to have the email address for the user. +``` + +.. column:: + +```` +```python +@app.signal("user.registration.created") +async def send_registration_email(**context): + print(context) + +await app.dispatch( + "user.registration.created", + context={"hello": "world"} +) +``` +``` +{'hello': 'world'} +``` +```` + +.. tip:: FYI + +``` +Signals are dispatched in a background task. +``` + +### Blueprints + +Dispatching blueprint signals works similar in concept to [middleware](../basics/middleware.md). Anything that is done from the app level, will trickle down to the blueprints. However, dispatching on a blueprint, will only execute the signals that are defined on that blueprint. + +.. column:: + +``` +Perhaps an example is easier to explain: +``` + +.. column:: + +```` +```python +bp = Blueprint("bp") + +app_counter = 0 +bp_counter = 0 + +@app.signal("foo.bar.baz") +def app_signal(): + nonlocal app_counter + app_counter += 1 + +@bp.signal("foo.bar.baz") +def bp_signal(): + nonlocal bp_counter + bp_counter += 1 +``` +```` + +.. column:: + +``` +Running `app.dispatch("foo.bar.baz")` will execute both signals. +``` + +.. column:: + +```` +```python +await app.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 1 +``` +```` + +.. column:: + +``` +Running `bp.dispatch("foo.bar.baz")` will execute only the blueprint signal. +``` + +.. column:: + +```` +```python +await bp.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 2 +``` +```` From bb0bbb6a6cf2d2c00ae1c3aeec2a363cfb90484e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:26 +0200 Subject: [PATCH 012/698] New translations signals.md (Chinese Simplified) --- guide/content/zh/guide/advanced/signals.md | 400 +++++++++++++++++++++ 1 file changed, 400 insertions(+) create mode 100644 guide/content/zh/guide/advanced/signals.md diff --git a/guide/content/zh/guide/advanced/signals.md b/guide/content/zh/guide/advanced/signals.md new file mode 100644 index 0000000000..971582bb1e --- /dev/null +++ b/guide/content/zh/guide/advanced/signals.md @@ -0,0 +1,400 @@ +# Signals + +Signals provide a way for one part of your application to tell another part that something happened. + +```python +@app.signal("user.registration.created") +async def send_registration_email(**context): + await send_email(context["email"], template="registration") + +@app.post("/register") +async def handle_registration(request): + await do_registration(request) + await request.app.dispatch( + "user.registration.created", + context={"email": request.json.email} + }) +``` + +## Adding a signal + +.. column:: + +``` +The API for adding a signal is very similar to adding a route. +``` + +.. column:: + +```` +```python +async def my_signal_handler(): + print("something happened") + +app.add_signal(my_signal_handler, "something.happened.ohmy") +``` +```` + +.. column:: + +``` +But, perhaps a slightly more convenient method is to use the built-in decorators. +``` + +.. column:: + +```` +```python +@app.signal("something.happened.ohmy") +async def my_signal_handler(): + print("something happened") +``` +```` + +.. column:: + +``` +If the signal requires conditions, make sure to add them while adding the handler. +``` + +.. column:: + +```` +```python +async def my_signal_handler1(): + print("something happened") + +app.add_signal( + my_signal_handler, + "something.happened.ohmy1", + conditions={"some_condition": "value"} +) + +@app.signal("something.happened.ohmy2", conditions={"some_condition": "value"}) +async def my_signal_handler2(): + print("something happened") +``` +```` + +.. column:: + +``` +Signals can also be declared on blueprints +``` + +.. column:: + +```` +```python +bp = Blueprint("foo") + +@bp.signal("something.happened.ohmy") +async def my_signal_handler(): + print("something happened") +``` +```` + +## Built-in signals + +In addition to creating a new signal, there are a number of built-in signals that are dispatched from Sanic itself. These signals exist to provide developers with more opportunities to add functionality into the request and server lifecycles. + +_Added in v21.9_ + +.. column:: + +``` +You can attach them just like any other signal to an application or blueprint instance. +``` + +.. column:: + +```` +```python +@app.signal("http.lifecycle.complete") +async def my_signal_handler(conn_info): + print("Connection has been closed") +``` +```` + +These signals are the signals that are available, along with the arguments that the handlers take, and the conditions that attach (if any). + +| Event name | Arguments | Conditions | +| -------------------------- | ------------------------------- | --------------------------------------------------------- | +| `http.routing.before` | request | | +| `http.routing.after` | request, route, kwargs, handler | | +| `http.handler.before` | request | | +| `http.handler.after` | request | | +| `http.lifecycle.begin` | conn_info | | +| `http.lifecycle.read_head` | head | | +| `http.lifecycle.request` | request | | +| `http.lifecycle.handle` | request | | +| `http.lifecycle.read_body` | body | | +| `http.lifecycle.exception` | request, exception | | +| `http.lifecycle.response` | request, response | | +| `http.lifecycle.send` | data | | +| `http.lifecycle.complete` | conn_info | | +| `http.middleware.before` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `http.middleware.after` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `server.exception.report` | app, exception | | +| `server.init.before` | app, loop | | +| `server.init.after` | app, loop | | +| `server.shutdown.before` | app, loop | | +| `server.shutdown.after` | app, loop | | + +Version 22.9 added `http.handler.before` and `http.handler.after`. + +Version 23.6 added `server.exception.report`. + +.. column:: + +``` +To make using the built-in signals easier, there is an `Enum` object that contains all of the allowed built-ins. With a modern IDE this will help so that you do not need to remember the full list of event names as strings. + +*Added in v21.12* +``` + +.. column:: + +```` +```python +from sanic.signals import Event + +@app.signal(Event.HTTP_LIFECYCLE_COMPLETE) +async def my_signal_handler(conn_info): + print("Connection has been closed") +``` +```` + +## Events + +.. column:: + +``` +Signals are based off of an _event_. An event, is simply a string in the following pattern: +``` + +.. column:: + +```` +``` +namespace.reference.action +``` +```` + +.. tip:: Events must have three parts. If you do not know what to use, try these patterns: + +``` +- `my_app.something.happened` +- `sanic.notice.hello` +``` + +### Event parameters + +.. column:: + +``` +An event can be "dynamic" and declared using the same syntax as [path parameters](../basics/routing.md#path-parameters). This allows matching based upon arbitrary values. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") +async def signal_handler(thing): + print(f"[signal_handler] {thing=}") + +@app.get("/") +async def trigger(request): + await app.dispatch("foo.bar.baz") + return response.text("Done.") +``` +```` + +Checkout [path parameters](../basics/routing.md#path-parameters) for more information on allowed type definitions. + +.. info:: Only the third part of an event (the action) may be dynamic: + +``` +- `foo.bar.` 🆗 +- `foo..baz` ❌ +``` + +### Waiting + +.. column:: + +``` +In addition to executing a signal handler, your application can wait for an event to be triggered. +``` + +.. column:: + +```` +```python +await app.event("foo.bar.baz") +``` +```` + +.. column:: + +``` +**IMPORTANT**: waiting is a blocking function. Therefore, you likely will want this to run in a [background task](../basics/tasks.md). +``` + +.. column:: + +```` +```python +async def wait_for_event(app): + while True: + print("> waiting") + await app.event("foo.bar.baz") + print("> event found\n") + +@app.after_server_start +async def after_server_start(app, loop): + app.add_task(wait_for_event(app)) +``` +```` + +.. column:: + +``` +If your event was defined with a dynamic path, you can use `*` to catch any action. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") + +... + +await app.event("foo.bar.*") +``` +```` + +## Dispatching + +_In the future, Sanic will dispatch some events automatically to assist developers to hook into life cycle events._ + +.. column:: + +``` +Dispatching an event will do two things: + +1. execute any signal handlers defined on the event, and +2. resolve anything that is "waiting" for the event to complete. +``` + +.. column:: + +```` +```python +@app.signal("foo.bar.") +async def foo_bar(thing): + print(f"{thing=}") + +await app.dispatch("foo.bar.baz") +``` +``` +thing=baz +``` +```` + +### Context + +.. column:: + +``` +Sometimes you may find the need to pass extra information into the signal handler. In our first example above, we wanted our email registration process to have the email address for the user. +``` + +.. column:: + +```` +```python +@app.signal("user.registration.created") +async def send_registration_email(**context): + print(context) + +await app.dispatch( + "user.registration.created", + context={"hello": "world"} +) +``` +``` +{'hello': 'world'} +``` +```` + +.. tip:: FYI + +``` +Signals are dispatched in a background task. +``` + +### Blueprints + +Dispatching blueprint signals works similar in concept to [middleware](../basics/middleware.md). Anything that is done from the app level, will trickle down to the blueprints. However, dispatching on a blueprint, will only execute the signals that are defined on that blueprint. + +.. column:: + +``` +Perhaps an example is easier to explain: +``` + +.. column:: + +```` +```python +bp = Blueprint("bp") + +app_counter = 0 +bp_counter = 0 + +@app.signal("foo.bar.baz") +def app_signal(): + nonlocal app_counter + app_counter += 1 + +@bp.signal("foo.bar.baz") +def bp_signal(): + nonlocal bp_counter + bp_counter += 1 +``` +```` + +.. column:: + +``` +Running `app.dispatch("foo.bar.baz")` will execute both signals. +``` + +.. column:: + +```` +```python +await app.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 1 +``` +```` + +.. column:: + +``` +Running `bp.dispatch("foo.bar.baz")` will execute only the blueprint signal. +``` + +.. column:: + +```` +```python +await bp.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 2 +``` +```` From c4031dafcdbf550e3d618d413bc9b35a1223d286 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:27 +0200 Subject: [PATCH 013/698] New translations streaming.md (Japanese) --- guide/content/ja/guide/advanced/streaming.md | 169 +++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 guide/content/ja/guide/advanced/streaming.md diff --git a/guide/content/ja/guide/advanced/streaming.md b/guide/content/ja/guide/advanced/streaming.md new file mode 100644 index 0000000000..646e645137 --- /dev/null +++ b/guide/content/ja/guide/advanced/streaming.md @@ -0,0 +1,169 @@ +# Streaming + +## Request streaming + +Sanic allows you to stream data sent by the client to begin processing data as the bytes arrive. + +.. column:: + +``` +When enabled on an endpoint, you can stream the request body using `await request.stream.read()`. + +That method will return `None` when the body is completed. +``` + +.. column:: + +```` +```python +from sanic.views import stream + +class SimpleView(HTTPMethodView): + @stream + async def post(self, request): + result = "" + while True: + body = await request.stream.read() + if body is None: + break + result += body.decode("utf-8") + return text(result) +``` +```` + +.. column:: + +``` +It also can be enabled with a keyword argument in the decorator... +``` + +.. column:: + +```` +```python +@app.post("/stream", stream=True) +async def handler(request): + ... + body = await request.stream.read() + ... +``` +```` + +.. column:: + +``` +... or the `add_route()` method. +``` + +.. column:: + +```` +```python +bp.add_route( + bp_handler, + "/bp_stream", + methods=["POST"], + stream=True, +) +``` +```` + +.. tip:: FYI + +``` +Only post, put and patch decorators have stream argument. +``` + +## Response streaming + +.. column:: + +``` +Sanic allows you to stream content to the client. +``` + +.. column:: + +```` +```python +@app.route("/") +async def test(request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") + + # Optionally, you can explicitly end the stream by calling: + await response.eof() +``` +```` + +This is useful in situations where you want to stream content to the client that originates in an external service, like a database. For example, you can stream database records to the client with the asynchronous cursor that `asyncpg` provides. + +```python +@app.route("/") +async def index(request): + response = await request.respond() + conn = await asyncpg.connect(database='test') + async with conn.transaction(): + async for record in conn.cursor('SELECT generate_series(0, 10)'): + await response.send(record[0]) +``` + +You can explicitly end a stream by calling `await response.eof()`. It a convenience method to replace `await response.send("", True)`. It should be called **one time** _after_ your handler has determined that it has nothing left to send back to the client. While it is _optional_ to use with Sanic server, if you are running Sanic in ASGI mode, then you **must** explicitly terminate the stream. + +_Calling `eof` became optional in v21.6_ + +## File streaming + +.. column:: + +``` +Sanic provides `sanic.response.file_stream` function that is useful when you want to send a large file. It returns a `StreamingHTTPResponse` object and will use chunked transfer encoding by default; for this reason Sanic doesn’t add `Content-Length` HTTP header in the response. + +A typical use case might be streaming an video file. +``` + +.. column:: + +```` +```python +@app.route("/mp4") +async def handler_file_stream(request): + return await response.file_stream( + "/path/to/sample.mp4", + chunk_size=1024, + mime_type="application/metalink4+xml", + headers={ + "Content-Disposition": 'Attachment; filename="nicer_name.meta4"', + "Content-Type": "application/metalink4+xml", + }, + ) +``` +```` + +.. column:: + +``` +If you want to use the `Content-Length` header, you can disable chunked transfer encoding and add it manually simply by adding the `Content-Length` header. +``` + +.. column:: + +```` +```python +from aiofiles import os as async_os +from sanic.response import file_stream + +@app.route("/") +async def index(request): + file_path = "/srv/www/whatever.png" + + file_stat = await async_os.stat(file_path) + headers = {"Content-Length": str(file_stat.st_size)} + + return await file_stream( + file_path, + headers=headers, + ) +``` +```` From 1da5dd0ffc234008d3228f51808b2cd1470ead95 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:28 +0200 Subject: [PATCH 014/698] New translations streaming.md (Korean) --- guide/content/ko/guide/advanced/streaming.md | 169 +++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 guide/content/ko/guide/advanced/streaming.md diff --git a/guide/content/ko/guide/advanced/streaming.md b/guide/content/ko/guide/advanced/streaming.md new file mode 100644 index 0000000000..646e645137 --- /dev/null +++ b/guide/content/ko/guide/advanced/streaming.md @@ -0,0 +1,169 @@ +# Streaming + +## Request streaming + +Sanic allows you to stream data sent by the client to begin processing data as the bytes arrive. + +.. column:: + +``` +When enabled on an endpoint, you can stream the request body using `await request.stream.read()`. + +That method will return `None` when the body is completed. +``` + +.. column:: + +```` +```python +from sanic.views import stream + +class SimpleView(HTTPMethodView): + @stream + async def post(self, request): + result = "" + while True: + body = await request.stream.read() + if body is None: + break + result += body.decode("utf-8") + return text(result) +``` +```` + +.. column:: + +``` +It also can be enabled with a keyword argument in the decorator... +``` + +.. column:: + +```` +```python +@app.post("/stream", stream=True) +async def handler(request): + ... + body = await request.stream.read() + ... +``` +```` + +.. column:: + +``` +... or the `add_route()` method. +``` + +.. column:: + +```` +```python +bp.add_route( + bp_handler, + "/bp_stream", + methods=["POST"], + stream=True, +) +``` +```` + +.. tip:: FYI + +``` +Only post, put and patch decorators have stream argument. +``` + +## Response streaming + +.. column:: + +``` +Sanic allows you to stream content to the client. +``` + +.. column:: + +```` +```python +@app.route("/") +async def test(request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") + + # Optionally, you can explicitly end the stream by calling: + await response.eof() +``` +```` + +This is useful in situations where you want to stream content to the client that originates in an external service, like a database. For example, you can stream database records to the client with the asynchronous cursor that `asyncpg` provides. + +```python +@app.route("/") +async def index(request): + response = await request.respond() + conn = await asyncpg.connect(database='test') + async with conn.transaction(): + async for record in conn.cursor('SELECT generate_series(0, 10)'): + await response.send(record[0]) +``` + +You can explicitly end a stream by calling `await response.eof()`. It a convenience method to replace `await response.send("", True)`. It should be called **one time** _after_ your handler has determined that it has nothing left to send back to the client. While it is _optional_ to use with Sanic server, if you are running Sanic in ASGI mode, then you **must** explicitly terminate the stream. + +_Calling `eof` became optional in v21.6_ + +## File streaming + +.. column:: + +``` +Sanic provides `sanic.response.file_stream` function that is useful when you want to send a large file. It returns a `StreamingHTTPResponse` object and will use chunked transfer encoding by default; for this reason Sanic doesn’t add `Content-Length` HTTP header in the response. + +A typical use case might be streaming an video file. +``` + +.. column:: + +```` +```python +@app.route("/mp4") +async def handler_file_stream(request): + return await response.file_stream( + "/path/to/sample.mp4", + chunk_size=1024, + mime_type="application/metalink4+xml", + headers={ + "Content-Disposition": 'Attachment; filename="nicer_name.meta4"', + "Content-Type": "application/metalink4+xml", + }, + ) +``` +```` + +.. column:: + +``` +If you want to use the `Content-Length` header, you can disable chunked transfer encoding and add it manually simply by adding the `Content-Length` header. +``` + +.. column:: + +```` +```python +from aiofiles import os as async_os +from sanic.response import file_stream + +@app.route("/") +async def index(request): + file_path = "/srv/www/whatever.png" + + file_stat = await async_os.stat(file_path) + headers = {"Content-Length": str(file_stat.st_size)} + + return await file_stream( + file_path, + headers=headers, + ) +``` +```` From 61e8ab1df9a78d77ea7895ff7701e1c7834e6d81 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:29 +0200 Subject: [PATCH 015/698] New translations streaming.md (Chinese Simplified) --- guide/content/zh/guide/advanced/streaming.md | 169 +++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 guide/content/zh/guide/advanced/streaming.md diff --git a/guide/content/zh/guide/advanced/streaming.md b/guide/content/zh/guide/advanced/streaming.md new file mode 100644 index 0000000000..646e645137 --- /dev/null +++ b/guide/content/zh/guide/advanced/streaming.md @@ -0,0 +1,169 @@ +# Streaming + +## Request streaming + +Sanic allows you to stream data sent by the client to begin processing data as the bytes arrive. + +.. column:: + +``` +When enabled on an endpoint, you can stream the request body using `await request.stream.read()`. + +That method will return `None` when the body is completed. +``` + +.. column:: + +```` +```python +from sanic.views import stream + +class SimpleView(HTTPMethodView): + @stream + async def post(self, request): + result = "" + while True: + body = await request.stream.read() + if body is None: + break + result += body.decode("utf-8") + return text(result) +``` +```` + +.. column:: + +``` +It also can be enabled with a keyword argument in the decorator... +``` + +.. column:: + +```` +```python +@app.post("/stream", stream=True) +async def handler(request): + ... + body = await request.stream.read() + ... +``` +```` + +.. column:: + +``` +... or the `add_route()` method. +``` + +.. column:: + +```` +```python +bp.add_route( + bp_handler, + "/bp_stream", + methods=["POST"], + stream=True, +) +``` +```` + +.. tip:: FYI + +``` +Only post, put and patch decorators have stream argument. +``` + +## Response streaming + +.. column:: + +``` +Sanic allows you to stream content to the client. +``` + +.. column:: + +```` +```python +@app.route("/") +async def test(request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") + + # Optionally, you can explicitly end the stream by calling: + await response.eof() +``` +```` + +This is useful in situations where you want to stream content to the client that originates in an external service, like a database. For example, you can stream database records to the client with the asynchronous cursor that `asyncpg` provides. + +```python +@app.route("/") +async def index(request): + response = await request.respond() + conn = await asyncpg.connect(database='test') + async with conn.transaction(): + async for record in conn.cursor('SELECT generate_series(0, 10)'): + await response.send(record[0]) +``` + +You can explicitly end a stream by calling `await response.eof()`. It a convenience method to replace `await response.send("", True)`. It should be called **one time** _after_ your handler has determined that it has nothing left to send back to the client. While it is _optional_ to use with Sanic server, if you are running Sanic in ASGI mode, then you **must** explicitly terminate the stream. + +_Calling `eof` became optional in v21.6_ + +## File streaming + +.. column:: + +``` +Sanic provides `sanic.response.file_stream` function that is useful when you want to send a large file. It returns a `StreamingHTTPResponse` object and will use chunked transfer encoding by default; for this reason Sanic doesn’t add `Content-Length` HTTP header in the response. + +A typical use case might be streaming an video file. +``` + +.. column:: + +```` +```python +@app.route("/mp4") +async def handler_file_stream(request): + return await response.file_stream( + "/path/to/sample.mp4", + chunk_size=1024, + mime_type="application/metalink4+xml", + headers={ + "Content-Disposition": 'Attachment; filename="nicer_name.meta4"', + "Content-Type": "application/metalink4+xml", + }, + ) +``` +```` + +.. column:: + +``` +If you want to use the `Content-Length` header, you can disable chunked transfer encoding and add it manually simply by adding the `Content-Length` header. +``` + +.. column:: + +```` +```python +from aiofiles import os as async_os +from sanic.response import file_stream + +@app.route("/") +async def index(request): + file_path = "/srv/www/whatever.png" + + file_stat = await async_os.stat(file_path) + headers = {"Content-Length": str(file_stat.st_size)} + + return await file_stream( + file_path, + headers=headers, + ) +``` +```` From c707d9eed173700359464435790d01be7c30efe5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:29 +0200 Subject: [PATCH 016/698] New translations versioning.md (Japanese) --- guide/content/ja/guide/advanced/versioning.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 guide/content/ja/guide/advanced/versioning.md diff --git a/guide/content/ja/guide/advanced/versioning.md b/guide/content/ja/guide/advanced/versioning.md new file mode 100644 index 0000000000..9225c23622 --- /dev/null +++ b/guide/content/ja/guide/advanced/versioning.md @@ -0,0 +1,189 @@ +# Versioning + +It is standard practice in API building to add versions to your endpoints. This allows you to easily differentiate incompatible endpoints when you try and change your API down the road in a breaking manner. + +Adding a version will add a `/v{version}` url prefix to your endpoints. + +The version can be a `int`, `float`, or `str`. Acceptable values: + +- `1`, `2`, `3` +- `1.1`, `2.25`, `3.0` +- `"1"`, `"v1"`, `"v1.1"` + +## Per route + +.. column:: + +``` +You can pass a version number to the routes directly. +``` + +.. column:: + +```` +```python +# /v1/text +@app.route("/text", version=1) +def handle_request(request): + return response.text("Hello world! Version 1") + +# /v2/text +@app.route("/text", version=2) +def handle_request(request): + return response.text("Hello world! Version 2") +``` +```` + +## Per Blueprint + +.. column:: + +``` +You can also pass a version number to the blueprint, which will apply to all routes in that blueprint. +``` + +.. column:: + +```` +```python +bp = Blueprint("test", url_prefix="/foo", version=1) + +# /v1/foo/html +@bp.route("/html") +def handle_request(request): + return response.html("

Hello world!

") +``` +```` + +## Per Blueprint Group + +.. column:: + +``` +In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint +group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the +same information with a value specified while creating a blueprint instance. + +When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to +the routes being registered. + +1. Route Level configuration +2. Blueprint level configuration +3. Blueprint Group level configuration + +If we find a more pointed versioning specification, we will pick that over the more generic versioning specification +provided under the Blueprint or Blueprint Group +``` + +.. column:: + +```` +```python +from sanic.blueprints import Blueprint +from sanic.response import json + +bp1 = Blueprint( + name="blueprint-1", + url_prefix="/bp1", + version=1.25, +) +bp2 = Blueprint( + name="blueprint-2", + url_prefix="/bp2", +) + +group = Blueprint.group( + [bp1, bp2], + url_prefix="/bp-group", + version="v2", +) + +# GET /v1.25/bp-group/bp1/endpoint-1 +@bp1.get("/endpoint-1") +async def handle_endpoint_1_bp1(request): + return json({"Source": "blueprint-1/endpoint-1"}) + +# GET /v2/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-1") +async def handle_endpoint_1_bp2(request): + return json({"Source": "blueprint-2/endpoint-1"}) + +# GET /v1/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-2", version=1) +async def handle_endpoint_2_bp2(request): + return json({"Source": "blueprint-2/endpoint-2"}) +``` +```` + +## Version prefix + +As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. + +The `version_prefix` argument can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. + +The default value of `version_prefix` is `/v`. + +.. column:: + +``` +An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. +``` + +.. column:: + +```` +```python +# /v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` +```` + +.. column:: + +``` +Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. +``` + +.. column:: + +```` +```python +# /v1/my/path +app = Sanic(__name__) +v2ip = Blueprint("v2ip", url_prefix="/ip", version=2) +api = Blueprint.group(v2ip, version_prefix="/api/version") + +# /api/version2/ip +@v2ip.get("/") +async def handler(request): + return text(request.ip) + +app.blueprint(api) +``` +```` + +We can therefore learn that a route's URI is: + +``` +version_prefix + version + url_prefix + URI definition +``` + +.. tip:: + +```` +Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. + +```python +version_prefix="//v" +``` +```` + +_Added in v21.6_ From 2d61ebe433228b7b230344330b35478ea4141930 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:30 +0200 Subject: [PATCH 017/698] New translations versioning.md (Korean) --- guide/content/ko/guide/advanced/versioning.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 guide/content/ko/guide/advanced/versioning.md diff --git a/guide/content/ko/guide/advanced/versioning.md b/guide/content/ko/guide/advanced/versioning.md new file mode 100644 index 0000000000..9225c23622 --- /dev/null +++ b/guide/content/ko/guide/advanced/versioning.md @@ -0,0 +1,189 @@ +# Versioning + +It is standard practice in API building to add versions to your endpoints. This allows you to easily differentiate incompatible endpoints when you try and change your API down the road in a breaking manner. + +Adding a version will add a `/v{version}` url prefix to your endpoints. + +The version can be a `int`, `float`, or `str`. Acceptable values: + +- `1`, `2`, `3` +- `1.1`, `2.25`, `3.0` +- `"1"`, `"v1"`, `"v1.1"` + +## Per route + +.. column:: + +``` +You can pass a version number to the routes directly. +``` + +.. column:: + +```` +```python +# /v1/text +@app.route("/text", version=1) +def handle_request(request): + return response.text("Hello world! Version 1") + +# /v2/text +@app.route("/text", version=2) +def handle_request(request): + return response.text("Hello world! Version 2") +``` +```` + +## Per Blueprint + +.. column:: + +``` +You can also pass a version number to the blueprint, which will apply to all routes in that blueprint. +``` + +.. column:: + +```` +```python +bp = Blueprint("test", url_prefix="/foo", version=1) + +# /v1/foo/html +@bp.route("/html") +def handle_request(request): + return response.html("

Hello world!

") +``` +```` + +## Per Blueprint Group + +.. column:: + +``` +In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint +group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the +same information with a value specified while creating a blueprint instance. + +When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to +the routes being registered. + +1. Route Level configuration +2. Blueprint level configuration +3. Blueprint Group level configuration + +If we find a more pointed versioning specification, we will pick that over the more generic versioning specification +provided under the Blueprint or Blueprint Group +``` + +.. column:: + +```` +```python +from sanic.blueprints import Blueprint +from sanic.response import json + +bp1 = Blueprint( + name="blueprint-1", + url_prefix="/bp1", + version=1.25, +) +bp2 = Blueprint( + name="blueprint-2", + url_prefix="/bp2", +) + +group = Blueprint.group( + [bp1, bp2], + url_prefix="/bp-group", + version="v2", +) + +# GET /v1.25/bp-group/bp1/endpoint-1 +@bp1.get("/endpoint-1") +async def handle_endpoint_1_bp1(request): + return json({"Source": "blueprint-1/endpoint-1"}) + +# GET /v2/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-1") +async def handle_endpoint_1_bp2(request): + return json({"Source": "blueprint-2/endpoint-1"}) + +# GET /v1/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-2", version=1) +async def handle_endpoint_2_bp2(request): + return json({"Source": "blueprint-2/endpoint-2"}) +``` +```` + +## Version prefix + +As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. + +The `version_prefix` argument can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. + +The default value of `version_prefix` is `/v`. + +.. column:: + +``` +An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. +``` + +.. column:: + +```` +```python +# /v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` +```` + +.. column:: + +``` +Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. +``` + +.. column:: + +```` +```python +# /v1/my/path +app = Sanic(__name__) +v2ip = Blueprint("v2ip", url_prefix="/ip", version=2) +api = Blueprint.group(v2ip, version_prefix="/api/version") + +# /api/version2/ip +@v2ip.get("/") +async def handler(request): + return text(request.ip) + +app.blueprint(api) +``` +```` + +We can therefore learn that a route's URI is: + +``` +version_prefix + version + url_prefix + URI definition +``` + +.. tip:: + +```` +Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. + +```python +version_prefix="//v" +``` +```` + +_Added in v21.6_ From 792bdaf641e79023c59de532317ea4366d833ed9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:31 +0200 Subject: [PATCH 018/698] New translations versioning.md (Chinese Simplified) --- guide/content/zh/guide/advanced/versioning.md | 189 ++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 guide/content/zh/guide/advanced/versioning.md diff --git a/guide/content/zh/guide/advanced/versioning.md b/guide/content/zh/guide/advanced/versioning.md new file mode 100644 index 0000000000..9225c23622 --- /dev/null +++ b/guide/content/zh/guide/advanced/versioning.md @@ -0,0 +1,189 @@ +# Versioning + +It is standard practice in API building to add versions to your endpoints. This allows you to easily differentiate incompatible endpoints when you try and change your API down the road in a breaking manner. + +Adding a version will add a `/v{version}` url prefix to your endpoints. + +The version can be a `int`, `float`, or `str`. Acceptable values: + +- `1`, `2`, `3` +- `1.1`, `2.25`, `3.0` +- `"1"`, `"v1"`, `"v1.1"` + +## Per route + +.. column:: + +``` +You can pass a version number to the routes directly. +``` + +.. column:: + +```` +```python +# /v1/text +@app.route("/text", version=1) +def handle_request(request): + return response.text("Hello world! Version 1") + +# /v2/text +@app.route("/text", version=2) +def handle_request(request): + return response.text("Hello world! Version 2") +``` +```` + +## Per Blueprint + +.. column:: + +``` +You can also pass a version number to the blueprint, which will apply to all routes in that blueprint. +``` + +.. column:: + +```` +```python +bp = Blueprint("test", url_prefix="/foo", version=1) + +# /v1/foo/html +@bp.route("/html") +def handle_request(request): + return response.html("

Hello world!

") +``` +```` + +## Per Blueprint Group + +.. column:: + +``` +In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint +group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the +same information with a value specified while creating a blueprint instance. + +When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to +the routes being registered. + +1. Route Level configuration +2. Blueprint level configuration +3. Blueprint Group level configuration + +If we find a more pointed versioning specification, we will pick that over the more generic versioning specification +provided under the Blueprint or Blueprint Group +``` + +.. column:: + +```` +```python +from sanic.blueprints import Blueprint +from sanic.response import json + +bp1 = Blueprint( + name="blueprint-1", + url_prefix="/bp1", + version=1.25, +) +bp2 = Blueprint( + name="blueprint-2", + url_prefix="/bp2", +) + +group = Blueprint.group( + [bp1, bp2], + url_prefix="/bp-group", + version="v2", +) + +# GET /v1.25/bp-group/bp1/endpoint-1 +@bp1.get("/endpoint-1") +async def handle_endpoint_1_bp1(request): + return json({"Source": "blueprint-1/endpoint-1"}) + +# GET /v2/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-1") +async def handle_endpoint_1_bp2(request): + return json({"Source": "blueprint-2/endpoint-1"}) + +# GET /v1/bp-group/bp2/endpoint-2 +@bp2.get("/endpoint-2", version=1) +async def handle_endpoint_2_bp2(request): + return json({"Source": "blueprint-2/endpoint-2"}) +``` +```` + +## Version prefix + +As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. + +The `version_prefix` argument can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. + +The default value of `version_prefix` is `/v`. + +.. column:: + +``` +An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. +``` + +.. column:: + +```` +```python +# /v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` +```` + +.. column:: + +``` +Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. +``` + +.. column:: + +```` +```python +# /v1/my/path +app = Sanic(__name__) +v2ip = Blueprint("v2ip", url_prefix="/ip", version=2) +api = Blueprint.group(v2ip, version_prefix="/api/version") + +# /api/version2/ip +@v2ip.get("/") +async def handler(request): + return text(request.ip) + +app.blueprint(api) +``` +```` + +We can therefore learn that a route's URI is: + +``` +version_prefix + version + url_prefix + URI definition +``` + +.. tip:: + +```` +Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. + +```python +version_prefix="//v" +``` +```` + +_Added in v21.6_ From 3b5c04945816196c1732f8cd216bdd1879b0e201 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:33 +0200 Subject: [PATCH 019/698] New translations websockets.md (Japanese) --- guide/content/ja/guide/advanced/websockets.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 guide/content/ja/guide/advanced/websockets.md diff --git a/guide/content/ja/guide/advanced/websockets.md b/guide/content/ja/guide/advanced/websockets.md new file mode 100644 index 0000000000..71e5b1dbfa --- /dev/null +++ b/guide/content/ja/guide/advanced/websockets.md @@ -0,0 +1,91 @@ +# Websockets + +Sanic provides an easy to use abstraction on top of [websockets](https://websockets.readthedocs.io/en/stable/). + +## Routing + +.. column:: + +``` +Websocket handlers can be hooked up to the router similar to regular handlers. +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +async def feed(request: Request, ws: Websocket): + pass + +app.add_websocket_route(feed, "/feed") +``` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + pass +``` +```` + +## Handler + +.. column:: + +``` +Typically, a websocket handler will want to hold open a loop. + +It can then use the `send()` and `recv()` methods on the second object injected into the handler. + +This example is a simple endpoint that echos back to the client messages that it receives. +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + while True: + data = "hello!" + print("Sending: " + data) + await ws.send(data) + data = await ws.recv() + print("Received: " + data) +``` +```` + +.. column:: + +``` +You can simplify your loop by just iterating over the `Websocket` object in a for loop. + +*Added in v22.9* +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` +```` + +## Configuration + +See [configuration section](/guide/deployment/configuration.md) for more details, however the defaults are shown below. + +```python +app.config.WEBSOCKET_MAX_SIZE = 2 ** 20 +app.config.WEBSOCKET_PING_INTERVAL = 20 +app.config.WEBSOCKET_PING_TIMEOUT = 20 +``` From 6547756883999307521bb3c4dd9e9d8addabd975 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:33 +0200 Subject: [PATCH 020/698] New translations websockets.md (Korean) --- guide/content/ko/guide/advanced/websockets.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 guide/content/ko/guide/advanced/websockets.md diff --git a/guide/content/ko/guide/advanced/websockets.md b/guide/content/ko/guide/advanced/websockets.md new file mode 100644 index 0000000000..71e5b1dbfa --- /dev/null +++ b/guide/content/ko/guide/advanced/websockets.md @@ -0,0 +1,91 @@ +# Websockets + +Sanic provides an easy to use abstraction on top of [websockets](https://websockets.readthedocs.io/en/stable/). + +## Routing + +.. column:: + +``` +Websocket handlers can be hooked up to the router similar to regular handlers. +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +async def feed(request: Request, ws: Websocket): + pass + +app.add_websocket_route(feed, "/feed") +``` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + pass +``` +```` + +## Handler + +.. column:: + +``` +Typically, a websocket handler will want to hold open a loop. + +It can then use the `send()` and `recv()` methods on the second object injected into the handler. + +This example is a simple endpoint that echos back to the client messages that it receives. +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + while True: + data = "hello!" + print("Sending: " + data) + await ws.send(data) + data = await ws.recv() + print("Received: " + data) +``` +```` + +.. column:: + +``` +You can simplify your loop by just iterating over the `Websocket` object in a for loop. + +*Added in v22.9* +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` +```` + +## Configuration + +See [configuration section](/guide/deployment/configuration.md) for more details, however the defaults are shown below. + +```python +app.config.WEBSOCKET_MAX_SIZE = 2 ** 20 +app.config.WEBSOCKET_PING_INTERVAL = 20 +app.config.WEBSOCKET_PING_TIMEOUT = 20 +``` From 4d69f6a8d2d9fb806501dd57230caf72bd07f287 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:34 +0200 Subject: [PATCH 021/698] New translations websockets.md (Chinese Simplified) --- guide/content/zh/guide/advanced/websockets.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 guide/content/zh/guide/advanced/websockets.md diff --git a/guide/content/zh/guide/advanced/websockets.md b/guide/content/zh/guide/advanced/websockets.md new file mode 100644 index 0000000000..71e5b1dbfa --- /dev/null +++ b/guide/content/zh/guide/advanced/websockets.md @@ -0,0 +1,91 @@ +# Websockets + +Sanic provides an easy to use abstraction on top of [websockets](https://websockets.readthedocs.io/en/stable/). + +## Routing + +.. column:: + +``` +Websocket handlers can be hooked up to the router similar to regular handlers. +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +async def feed(request: Request, ws: Websocket): + pass + +app.add_websocket_route(feed, "/feed") +``` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + pass +``` +```` + +## Handler + +.. column:: + +``` +Typically, a websocket handler will want to hold open a loop. + +It can then use the `send()` and `recv()` methods on the second object injected into the handler. + +This example is a simple endpoint that echos back to the client messages that it receives. +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + while True: + data = "hello!" + print("Sending: " + data) + await ws.send(data) + data = await ws.recv() + print("Received: " + data) +``` +```` + +.. column:: + +``` +You can simplify your loop by just iterating over the `Websocket` object in a for loop. + +*Added in v22.9* +``` + +.. column:: + +```` +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` +```` + +## Configuration + +See [configuration section](/guide/deployment/configuration.md) for more details, however the defaults are shown below. + +```python +app.config.WEBSOCKET_MAX_SIZE = 2 ** 20 +app.config.WEBSOCKET_PING_INTERVAL = 20 +app.config.WEBSOCKET_PING_TIMEOUT = 20 +``` From 2fcc9d2046de078607460f743a09780534888118 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:35 +0200 Subject: [PATCH 022/698] New translations readme.md (Japanese) --- guide/content/ja/guide/basics/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/basics/README.md diff --git a/guide/content/ja/guide/basics/README.md b/guide/content/ja/guide/basics/README.md new file mode 100644 index 0000000000..25dcc52044 --- /dev/null +++ b/guide/content/ja/guide/basics/README.md @@ -0,0 +1 @@ +# Basics From 64aaf994ec370f57b0e15f5f8d6abfab99466c82 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:36 +0200 Subject: [PATCH 023/698] New translations readme.md (Korean) --- guide/content/ko/guide/basics/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/basics/README.md diff --git a/guide/content/ko/guide/basics/README.md b/guide/content/ko/guide/basics/README.md new file mode 100644 index 0000000000..25dcc52044 --- /dev/null +++ b/guide/content/ko/guide/basics/README.md @@ -0,0 +1 @@ +# Basics From d5ffae681ee8e43a91a6a7f58f4d50683282d34f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:37 +0200 Subject: [PATCH 024/698] New translations readme.md (Chinese Simplified) --- guide/content/zh/guide/basics/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/basics/README.md diff --git a/guide/content/zh/guide/basics/README.md b/guide/content/zh/guide/basics/README.md new file mode 100644 index 0000000000..25dcc52044 --- /dev/null +++ b/guide/content/zh/guide/basics/README.md @@ -0,0 +1 @@ +# Basics From 877d42514ba1488d73c54ce2044d99a913f6041f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:38 +0200 Subject: [PATCH 025/698] New translations app.md (Japanese) --- guide/content/ja/guide/basics/app.md | 634 +++++++++++++++++++++++++++ 1 file changed, 634 insertions(+) create mode 100644 guide/content/ja/guide/basics/app.md diff --git a/guide/content/ja/guide/basics/app.md b/guide/content/ja/guide/basics/app.md new file mode 100644 index 0000000000..4cded1f51a --- /dev/null +++ b/guide/content/ja/guide/basics/app.md @@ -0,0 +1,634 @@ +--- +title: Sanic Application +--- + +# Sanic Application + +See API docs: [sanic.app](/api/sanic.app) + +## Instance + +.. column:: + +``` +The most basic building block is the :class:`sanic.app.Sanic` instance. It is not required, but the custom is to instantiate this in a file called `server.py`. +``` + +.. column:: + +```` +```python +# /path/to/server.py + +from sanic import Sanic + +app = Sanic("MyHelloWorldApp") +``` +```` + +## Application context + +Most applications will have the need to share/reuse data or objects across different parts of the code base. Sanic helps be providing the `ctx` object on application instances. It is a free space for the developer to attach any objects or data that should existe throughout the lifetime of the application. + +.. column:: + +``` +The most common pattern is to attach a database instance to the application. +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.ctx.db = Database() +``` +```` + +.. column:: + +``` +While the previous example will work and is illustrative, it is typically considered best practice to attach objects in one of the two application startup [listeners](./listeners). +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") + +@app.before_server_start +async def attach_db(app, loop): + app.ctx.db = Database() +``` +```` + +## App Registry + +.. column:: + +``` +When you instantiate a Sanic instance, that can be retrieved at a later time from the Sanic app registry. This can be useful, for example, if you need to access your Sanic instance from a location where it is not otherwise accessible. +``` + +.. column:: + +```` +```python +# ./path/to/server.py +from sanic import Sanic + +app = Sanic("my_awesome_server") + +# ./path/to/somewhere_else.py +from sanic import Sanic + +app = Sanic.get_app("my_awesome_server") +``` +```` + +.. column:: + +``` +If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name. +``` + +.. column:: + +```` +```python +app = Sanic.get_app( + "non-existing", + force_create=True, +) +``` +```` + +.. column:: + +``` +If there is **only one** Sanic instance registered, then calling `Sanic.get_app()` with no arguments will return that instance +``` + +.. column:: + +```` +```python +Sanic("My only app") + +app = Sanic.get_app() +``` +```` + +## Configuration + +.. column:: + +``` +Sanic holds the configuration in the `config` attribute of the `Sanic` instance. Configuration can be modified **either** using dot-notation **OR** like a dictionary. +``` + +.. column:: + +```` +```python +app = Sanic('myapp') + +app.config.DB_NAME = 'appdb' +app.config['DB_USER'] = 'appuser' + +db_settings = { + 'DB_HOST': 'localhost', + 'DB_NAME': 'appdb', + 'DB_USER': 'appuser' +} +app.config.update(db_settings) +``` +```` + +.. note:: Heads up + +```` +Config keys _should_ be uppercase. But, this is mainly by convention, and lowercase will work most of the time. +```python +app.config.GOOD = "yay!" +app.config.bad = "boo" +``` +```` + +There is much [more detail about configuration](../running/configuration.md) later on. + +## Factory pattern + +Many of the examples in these docs will show the instantiation of the :class:`sanic.app.Sanic` instance in a file called `server.py` in the "global scope" (i.e. not inside a function). This is a common pattern for very simple "hello world" style applications, but it is often beneficial to use a factory pattern instead. + +A "factory" is just a function that returns an instance of the object you want to use. This allows you to abstract the instantiation of the object, but also may make it easier to isolate the application instance. + +.. column:: + +``` +A super simple factory pattern could look like this: +``` + +.. column:: + +```` +```python +# ./path/to/server.py +from sanic import Sanic +from .path.to.config import MyConfig +from .path.to.some.blueprint import bp + + +def create_app(config=MyConfig) -> Sanic: + app = Sanic("MyApp", config=config) + app.blueprint(bp) + return app +``` +```` + +.. column:: + +``` +When we get to running Sanic later, you will learn that the Sanic CLI can detect this pattern and use it to run your application. +``` + +.. column:: + +```` +```sh +sanic path.to.server:create_app +``` +```` + +## Customization + +The Sanic application instance can be customized for your application needs in a variety of ways at instantiation. + +For complete details, see the [API docs](/api/sanic.app). + +### Custom configuration + +.. column:: + +``` +This simplest form of custom configuration would be to pass your own object directly into that Sanic application instance + +If you create a custom configuration object, it is *highly* recommended that you subclass the :class:`sanic.config.Config` option to inherit its behavior. You could use this option for adding properties, or your own set of custom logic. + +*Added in v21.6* +``` + +.. column:: + +```` +```python +from sanic.config import Config + +class MyConfig(Config): + FOO = "bar" + +app = Sanic(..., config=MyConfig()) +``` +```` + +.. column:: + +``` +A useful example of this feature would be if you wanted to use a config file in a form that differs from what is [supported](../running/configuration.md#using-sanicupdateconfig). +``` + +.. column:: + +```` +```python +from sanic import Sanic, text +from sanic.config import Config + +class TomlConfig(Config): + def __init__(self, *args, path: str, **kwargs): + super().__init__(*args, **kwargs) + + with open(path, "r") as f: + self.apply(toml.load(f)) + + def apply(self, config): + self.update(self._to_uppercase(config)) + + def _to_uppercase(self, obj: Dict[str, Any]) -> Dict[str, Any]: + retval: Dict[str, Any] = {} + for key, value in obj.items(): + upper_key = key.upper() + if isinstance(value, list): + retval[upper_key] = [ + self._to_uppercase(item) for item in value + ] + elif isinstance(value, dict): + retval[upper_key] = self._to_uppercase(value) + else: + retval[upper_key] = value + return retval + +toml_config = TomlConfig(path="/path/to/config.toml") +app = Sanic(toml_config.APP_NAME, config=toml_config) +``` +```` + +### Custom context + +.. column:: + +``` +By default, the application context is a [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) that allows you to set any properties you want on it. However, you also have the option of passing any object whatsoever instead. + +*Added in v21.6* +``` + +.. column:: + +```` +```python +app = Sanic(..., ctx=1) +``` + +```python +app = Sanic(..., ctx={}) +``` + +```python +class MyContext: + ... + +app = Sanic(..., ctx=MyContext()) +``` +```` + +### Custom requests + +.. column:: + +``` +It is sometimes helpful to have your own `Request` class, and tell Sanic to use that instead of the default. One example is if you wanted to modify the default `request.id` generator. + + + +.. note:: Important + + It is important to remember that you are passing the *class* not an instance of the class. +``` + +.. column:: + +```` +```python +import time + +from sanic import Request, Sanic, text + +class NanoSecondRequest(Request): + @classmethod + def generate_id(*_): + return time.time_ns() + +app = Sanic(..., request_class=NanoSecondRequest) + +@app.get("/") +async def handler(request): + return text(str(request.id)) +``` +```` + +### Custom error handler + +.. column:: + +``` +See [exception handling](../best-practices/exceptions.md#custom-error-handling) for more +``` + +.. column:: + +```` +```python +from sanic.handlers import ErrorHandler + +class CustomErrorHandler(ErrorHandler): + def default(self, request, exception): + ''' handles errors that have no error handlers assigned ''' + # You custom error handling logic... + return super().default(request, exception) + +app = Sanic(..., error_handler=CustomErrorHandler()) +``` +```` + +### Custom dumps function + +.. column:: + +``` +It may sometimes be necessary or desirable to provide a custom function that serializes an object to JSON data. +``` + +.. column:: + +```` +```python +import ujson + +dumps = partial(ujson.dumps, escape_forward_slashes=False) +app = Sanic(__name__, dumps=dumps) +``` +```` + +.. column:: + +``` +Or, perhaps use another library or create your own. +``` + +.. column:: + +```` +```python +from orjson import dumps + +app = Sanic("MyApp", dumps=dumps) +``` +```` + +### Custom loads function + +.. column:: + +``` +Similar to `dumps`, you can also provide a custom function for deserializing data. + +*Added in v22.9* +``` + +.. column:: + +```` +```python +from orjson import loads + +app = Sanic("MyApp", loads=loads) +``` +```` + +### Custom typed application + +Beginning in v23.6, the correct type annotation of a default Sanic application instance is: + +```python +sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace] +``` + +It refers to two generic types: + +1. The first is the type of the configuration object. It defaults to :class:`sanic.config.Config`, but can be any subclass of that. +2. The second is the type of the application context. It defaults to [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace), but can be **any object** as show above. + +Let's look at some examples of how the type will change. + +.. column:: + +``` +Consider this example where we pass a custom subclass of :class:`sanic.config.Config` and a custom context object. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +app = Sanic("test", config=CustomConfig()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]" +``` +``` +sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace] +``` +```` + +.. column:: + +``` +Similarly, when passing a custom context object, the type will change to reflect that. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +class Foo: + pass + +app = Sanic("test", ctx=Foo()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, main.Foo]" +``` +``` +sanic.app.Sanic[sanic.config.Config, main.Foo] +``` +```` + +.. column:: + +``` +Of course, you can set both the config and context to custom types. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +app = Sanic("test", config=CustomConfig(), ctx=Foo()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, main.Foo]" +``` +``` +sanic.app.Sanic[main.CustomConfig, main.Foo] +``` +```` + +This pattern is particularly useful if you create a custom type alias for your application instance so that you can use it to annotate listeners and handlers. + +```python +# ./path/to/types.py +from sanic.app import Sanic +from sanic.config import Config +from myapp.context import MyContext +from typing import TypeAlias + +MyApp = TypeAlias("MyApp", Sanic[Config, MyContext]) +``` + +```python +# ./path/to/listeners.py +from myapp.types import MyApp + +def add_listeners(app: MyApp): + @app.before_server_start + async def before_server_start(app: MyApp): + # do something with your fully typed app instance + await app.ctx.db.connect() +``` + +```python +# ./path/to/server.py +from myapp.types import MyApp +from myapp.context import MyContext +from myapp.config import MyConfig +from myapp.listeners import add_listeners + +app = Sanic("myapp", config=MyConfig(), ctx=MyContext()) +add_listeners(app) +``` + +_Added in v23.6_ + +### Custom typed request + +Sanic also allows you to customize the type of the request object. This is useful if you want to add custom properties to the request object, or be able to access your custom properties of a typed application instance. + +The correct, default type of a Sanic request instance is: + +```python +sanic.request.Request[ + sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace], + types.SimpleNamespace +] +``` + +It refers to two generic types: + +1. The first is the type of the application instance. It defaults to `sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]`, but can be any subclass of that. +2. The second is the type of the request context. It defaults to `types.SimpleNamespace`, but can be **any object** as show above in [custom requests](#custom-requests). + +Let's look at some examples of how the type will change. + +.. column:: + +``` +Expanding upon the full example above where there is a type alias for a customized application instance, we can also create a custom request type so that we can access those same type annotations. + +Of course, you do not need type aliases for this to work. We are only showing them here to cut down on the amount of code shown. +``` + +.. column:: + +```` +```python +from sanic import Request +from myapp.types import MyApp +from types import SimpleNamespace + +def add_routes(app: MyApp): + @app.get("/") + async def handler(request: Request[MyApp, SimpleNamespace]): + # do something with your fully typed app instance + results = await request.app.ctx.db.query("SELECT * FROM foo") +``` +```` + +.. column:: + +``` +Perhaps you have a custom request object that generates a custom context object. You can type annotate it to properly access those properties with your IDE as shown here. +``` + +.. column:: + +```` +```python +from sanic import Request, Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +class RequestContext: + foo: Foo + +class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]): + @staticmethod + def make_context() -> RequestContext: + ctx = RequestContext() + ctx.foo = Foo() + return ctx + +app = Sanic( + "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest +) + +@app.get("/") +async def handler(request: CustomRequest): + # Full access to typed: + # - custom application configuration object + # - custom application context object + # - custom request context object + pass +``` +```` + +See more information in the [custom request context](./request#custom-request-context) section. + +_Added in v23.6_ From 06c89fc1affbf7a16966abbd6b5b7d0e2c7aa95b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:39 +0200 Subject: [PATCH 026/698] New translations app.md (Korean) --- guide/content/ko/guide/basics/app.md | 634 +++++++++++++++++++++++++++ 1 file changed, 634 insertions(+) create mode 100644 guide/content/ko/guide/basics/app.md diff --git a/guide/content/ko/guide/basics/app.md b/guide/content/ko/guide/basics/app.md new file mode 100644 index 0000000000..4cded1f51a --- /dev/null +++ b/guide/content/ko/guide/basics/app.md @@ -0,0 +1,634 @@ +--- +title: Sanic Application +--- + +# Sanic Application + +See API docs: [sanic.app](/api/sanic.app) + +## Instance + +.. column:: + +``` +The most basic building block is the :class:`sanic.app.Sanic` instance. It is not required, but the custom is to instantiate this in a file called `server.py`. +``` + +.. column:: + +```` +```python +# /path/to/server.py + +from sanic import Sanic + +app = Sanic("MyHelloWorldApp") +``` +```` + +## Application context + +Most applications will have the need to share/reuse data or objects across different parts of the code base. Sanic helps be providing the `ctx` object on application instances. It is a free space for the developer to attach any objects or data that should existe throughout the lifetime of the application. + +.. column:: + +``` +The most common pattern is to attach a database instance to the application. +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.ctx.db = Database() +``` +```` + +.. column:: + +``` +While the previous example will work and is illustrative, it is typically considered best practice to attach objects in one of the two application startup [listeners](./listeners). +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") + +@app.before_server_start +async def attach_db(app, loop): + app.ctx.db = Database() +``` +```` + +## App Registry + +.. column:: + +``` +When you instantiate a Sanic instance, that can be retrieved at a later time from the Sanic app registry. This can be useful, for example, if you need to access your Sanic instance from a location where it is not otherwise accessible. +``` + +.. column:: + +```` +```python +# ./path/to/server.py +from sanic import Sanic + +app = Sanic("my_awesome_server") + +# ./path/to/somewhere_else.py +from sanic import Sanic + +app = Sanic.get_app("my_awesome_server") +``` +```` + +.. column:: + +``` +If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name. +``` + +.. column:: + +```` +```python +app = Sanic.get_app( + "non-existing", + force_create=True, +) +``` +```` + +.. column:: + +``` +If there is **only one** Sanic instance registered, then calling `Sanic.get_app()` with no arguments will return that instance +``` + +.. column:: + +```` +```python +Sanic("My only app") + +app = Sanic.get_app() +``` +```` + +## Configuration + +.. column:: + +``` +Sanic holds the configuration in the `config` attribute of the `Sanic` instance. Configuration can be modified **either** using dot-notation **OR** like a dictionary. +``` + +.. column:: + +```` +```python +app = Sanic('myapp') + +app.config.DB_NAME = 'appdb' +app.config['DB_USER'] = 'appuser' + +db_settings = { + 'DB_HOST': 'localhost', + 'DB_NAME': 'appdb', + 'DB_USER': 'appuser' +} +app.config.update(db_settings) +``` +```` + +.. note:: Heads up + +```` +Config keys _should_ be uppercase. But, this is mainly by convention, and lowercase will work most of the time. +```python +app.config.GOOD = "yay!" +app.config.bad = "boo" +``` +```` + +There is much [more detail about configuration](../running/configuration.md) later on. + +## Factory pattern + +Many of the examples in these docs will show the instantiation of the :class:`sanic.app.Sanic` instance in a file called `server.py` in the "global scope" (i.e. not inside a function). This is a common pattern for very simple "hello world" style applications, but it is often beneficial to use a factory pattern instead. + +A "factory" is just a function that returns an instance of the object you want to use. This allows you to abstract the instantiation of the object, but also may make it easier to isolate the application instance. + +.. column:: + +``` +A super simple factory pattern could look like this: +``` + +.. column:: + +```` +```python +# ./path/to/server.py +from sanic import Sanic +from .path.to.config import MyConfig +from .path.to.some.blueprint import bp + + +def create_app(config=MyConfig) -> Sanic: + app = Sanic("MyApp", config=config) + app.blueprint(bp) + return app +``` +```` + +.. column:: + +``` +When we get to running Sanic later, you will learn that the Sanic CLI can detect this pattern and use it to run your application. +``` + +.. column:: + +```` +```sh +sanic path.to.server:create_app +``` +```` + +## Customization + +The Sanic application instance can be customized for your application needs in a variety of ways at instantiation. + +For complete details, see the [API docs](/api/sanic.app). + +### Custom configuration + +.. column:: + +``` +This simplest form of custom configuration would be to pass your own object directly into that Sanic application instance + +If you create a custom configuration object, it is *highly* recommended that you subclass the :class:`sanic.config.Config` option to inherit its behavior. You could use this option for adding properties, or your own set of custom logic. + +*Added in v21.6* +``` + +.. column:: + +```` +```python +from sanic.config import Config + +class MyConfig(Config): + FOO = "bar" + +app = Sanic(..., config=MyConfig()) +``` +```` + +.. column:: + +``` +A useful example of this feature would be if you wanted to use a config file in a form that differs from what is [supported](../running/configuration.md#using-sanicupdateconfig). +``` + +.. column:: + +```` +```python +from sanic import Sanic, text +from sanic.config import Config + +class TomlConfig(Config): + def __init__(self, *args, path: str, **kwargs): + super().__init__(*args, **kwargs) + + with open(path, "r") as f: + self.apply(toml.load(f)) + + def apply(self, config): + self.update(self._to_uppercase(config)) + + def _to_uppercase(self, obj: Dict[str, Any]) -> Dict[str, Any]: + retval: Dict[str, Any] = {} + for key, value in obj.items(): + upper_key = key.upper() + if isinstance(value, list): + retval[upper_key] = [ + self._to_uppercase(item) for item in value + ] + elif isinstance(value, dict): + retval[upper_key] = self._to_uppercase(value) + else: + retval[upper_key] = value + return retval + +toml_config = TomlConfig(path="/path/to/config.toml") +app = Sanic(toml_config.APP_NAME, config=toml_config) +``` +```` + +### Custom context + +.. column:: + +``` +By default, the application context is a [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) that allows you to set any properties you want on it. However, you also have the option of passing any object whatsoever instead. + +*Added in v21.6* +``` + +.. column:: + +```` +```python +app = Sanic(..., ctx=1) +``` + +```python +app = Sanic(..., ctx={}) +``` + +```python +class MyContext: + ... + +app = Sanic(..., ctx=MyContext()) +``` +```` + +### Custom requests + +.. column:: + +``` +It is sometimes helpful to have your own `Request` class, and tell Sanic to use that instead of the default. One example is if you wanted to modify the default `request.id` generator. + + + +.. note:: Important + + It is important to remember that you are passing the *class* not an instance of the class. +``` + +.. column:: + +```` +```python +import time + +from sanic import Request, Sanic, text + +class NanoSecondRequest(Request): + @classmethod + def generate_id(*_): + return time.time_ns() + +app = Sanic(..., request_class=NanoSecondRequest) + +@app.get("/") +async def handler(request): + return text(str(request.id)) +``` +```` + +### Custom error handler + +.. column:: + +``` +See [exception handling](../best-practices/exceptions.md#custom-error-handling) for more +``` + +.. column:: + +```` +```python +from sanic.handlers import ErrorHandler + +class CustomErrorHandler(ErrorHandler): + def default(self, request, exception): + ''' handles errors that have no error handlers assigned ''' + # You custom error handling logic... + return super().default(request, exception) + +app = Sanic(..., error_handler=CustomErrorHandler()) +``` +```` + +### Custom dumps function + +.. column:: + +``` +It may sometimes be necessary or desirable to provide a custom function that serializes an object to JSON data. +``` + +.. column:: + +```` +```python +import ujson + +dumps = partial(ujson.dumps, escape_forward_slashes=False) +app = Sanic(__name__, dumps=dumps) +``` +```` + +.. column:: + +``` +Or, perhaps use another library or create your own. +``` + +.. column:: + +```` +```python +from orjson import dumps + +app = Sanic("MyApp", dumps=dumps) +``` +```` + +### Custom loads function + +.. column:: + +``` +Similar to `dumps`, you can also provide a custom function for deserializing data. + +*Added in v22.9* +``` + +.. column:: + +```` +```python +from orjson import loads + +app = Sanic("MyApp", loads=loads) +``` +```` + +### Custom typed application + +Beginning in v23.6, the correct type annotation of a default Sanic application instance is: + +```python +sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace] +``` + +It refers to two generic types: + +1. The first is the type of the configuration object. It defaults to :class:`sanic.config.Config`, but can be any subclass of that. +2. The second is the type of the application context. It defaults to [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace), but can be **any object** as show above. + +Let's look at some examples of how the type will change. + +.. column:: + +``` +Consider this example where we pass a custom subclass of :class:`sanic.config.Config` and a custom context object. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +app = Sanic("test", config=CustomConfig()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]" +``` +``` +sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace] +``` +```` + +.. column:: + +``` +Similarly, when passing a custom context object, the type will change to reflect that. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +class Foo: + pass + +app = Sanic("test", ctx=Foo()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, main.Foo]" +``` +``` +sanic.app.Sanic[sanic.config.Config, main.Foo] +``` +```` + +.. column:: + +``` +Of course, you can set both the config and context to custom types. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +app = Sanic("test", config=CustomConfig(), ctx=Foo()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, main.Foo]" +``` +``` +sanic.app.Sanic[main.CustomConfig, main.Foo] +``` +```` + +This pattern is particularly useful if you create a custom type alias for your application instance so that you can use it to annotate listeners and handlers. + +```python +# ./path/to/types.py +from sanic.app import Sanic +from sanic.config import Config +from myapp.context import MyContext +from typing import TypeAlias + +MyApp = TypeAlias("MyApp", Sanic[Config, MyContext]) +``` + +```python +# ./path/to/listeners.py +from myapp.types import MyApp + +def add_listeners(app: MyApp): + @app.before_server_start + async def before_server_start(app: MyApp): + # do something with your fully typed app instance + await app.ctx.db.connect() +``` + +```python +# ./path/to/server.py +from myapp.types import MyApp +from myapp.context import MyContext +from myapp.config import MyConfig +from myapp.listeners import add_listeners + +app = Sanic("myapp", config=MyConfig(), ctx=MyContext()) +add_listeners(app) +``` + +_Added in v23.6_ + +### Custom typed request + +Sanic also allows you to customize the type of the request object. This is useful if you want to add custom properties to the request object, or be able to access your custom properties of a typed application instance. + +The correct, default type of a Sanic request instance is: + +```python +sanic.request.Request[ + sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace], + types.SimpleNamespace +] +``` + +It refers to two generic types: + +1. The first is the type of the application instance. It defaults to `sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]`, but can be any subclass of that. +2. The second is the type of the request context. It defaults to `types.SimpleNamespace`, but can be **any object** as show above in [custom requests](#custom-requests). + +Let's look at some examples of how the type will change. + +.. column:: + +``` +Expanding upon the full example above where there is a type alias for a customized application instance, we can also create a custom request type so that we can access those same type annotations. + +Of course, you do not need type aliases for this to work. We are only showing them here to cut down on the amount of code shown. +``` + +.. column:: + +```` +```python +from sanic import Request +from myapp.types import MyApp +from types import SimpleNamespace + +def add_routes(app: MyApp): + @app.get("/") + async def handler(request: Request[MyApp, SimpleNamespace]): + # do something with your fully typed app instance + results = await request.app.ctx.db.query("SELECT * FROM foo") +``` +```` + +.. column:: + +``` +Perhaps you have a custom request object that generates a custom context object. You can type annotate it to properly access those properties with your IDE as shown here. +``` + +.. column:: + +```` +```python +from sanic import Request, Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +class RequestContext: + foo: Foo + +class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]): + @staticmethod + def make_context() -> RequestContext: + ctx = RequestContext() + ctx.foo = Foo() + return ctx + +app = Sanic( + "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest +) + +@app.get("/") +async def handler(request: CustomRequest): + # Full access to typed: + # - custom application configuration object + # - custom application context object + # - custom request context object + pass +``` +```` + +See more information in the [custom request context](./request#custom-request-context) section. + +_Added in v23.6_ From d21c7b7ffdc93124745c7b0da29bcdc43f1350d9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:40 +0200 Subject: [PATCH 027/698] New translations app.md (Chinese Simplified) --- guide/content/zh/guide/basics/app.md | 634 +++++++++++++++++++++++++++ 1 file changed, 634 insertions(+) create mode 100644 guide/content/zh/guide/basics/app.md diff --git a/guide/content/zh/guide/basics/app.md b/guide/content/zh/guide/basics/app.md new file mode 100644 index 0000000000..4cded1f51a --- /dev/null +++ b/guide/content/zh/guide/basics/app.md @@ -0,0 +1,634 @@ +--- +title: Sanic Application +--- + +# Sanic Application + +See API docs: [sanic.app](/api/sanic.app) + +## Instance + +.. column:: + +``` +The most basic building block is the :class:`sanic.app.Sanic` instance. It is not required, but the custom is to instantiate this in a file called `server.py`. +``` + +.. column:: + +```` +```python +# /path/to/server.py + +from sanic import Sanic + +app = Sanic("MyHelloWorldApp") +``` +```` + +## Application context + +Most applications will have the need to share/reuse data or objects across different parts of the code base. Sanic helps be providing the `ctx` object on application instances. It is a free space for the developer to attach any objects or data that should existe throughout the lifetime of the application. + +.. column:: + +``` +The most common pattern is to attach a database instance to the application. +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.ctx.db = Database() +``` +```` + +.. column:: + +``` +While the previous example will work and is illustrative, it is typically considered best practice to attach objects in one of the two application startup [listeners](./listeners). +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") + +@app.before_server_start +async def attach_db(app, loop): + app.ctx.db = Database() +``` +```` + +## App Registry + +.. column:: + +``` +When you instantiate a Sanic instance, that can be retrieved at a later time from the Sanic app registry. This can be useful, for example, if you need to access your Sanic instance from a location where it is not otherwise accessible. +``` + +.. column:: + +```` +```python +# ./path/to/server.py +from sanic import Sanic + +app = Sanic("my_awesome_server") + +# ./path/to/somewhere_else.py +from sanic import Sanic + +app = Sanic.get_app("my_awesome_server") +``` +```` + +.. column:: + +``` +If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name. +``` + +.. column:: + +```` +```python +app = Sanic.get_app( + "non-existing", + force_create=True, +) +``` +```` + +.. column:: + +``` +If there is **only one** Sanic instance registered, then calling `Sanic.get_app()` with no arguments will return that instance +``` + +.. column:: + +```` +```python +Sanic("My only app") + +app = Sanic.get_app() +``` +```` + +## Configuration + +.. column:: + +``` +Sanic holds the configuration in the `config` attribute of the `Sanic` instance. Configuration can be modified **either** using dot-notation **OR** like a dictionary. +``` + +.. column:: + +```` +```python +app = Sanic('myapp') + +app.config.DB_NAME = 'appdb' +app.config['DB_USER'] = 'appuser' + +db_settings = { + 'DB_HOST': 'localhost', + 'DB_NAME': 'appdb', + 'DB_USER': 'appuser' +} +app.config.update(db_settings) +``` +```` + +.. note:: Heads up + +```` +Config keys _should_ be uppercase. But, this is mainly by convention, and lowercase will work most of the time. +```python +app.config.GOOD = "yay!" +app.config.bad = "boo" +``` +```` + +There is much [more detail about configuration](../running/configuration.md) later on. + +## Factory pattern + +Many of the examples in these docs will show the instantiation of the :class:`sanic.app.Sanic` instance in a file called `server.py` in the "global scope" (i.e. not inside a function). This is a common pattern for very simple "hello world" style applications, but it is often beneficial to use a factory pattern instead. + +A "factory" is just a function that returns an instance of the object you want to use. This allows you to abstract the instantiation of the object, but also may make it easier to isolate the application instance. + +.. column:: + +``` +A super simple factory pattern could look like this: +``` + +.. column:: + +```` +```python +# ./path/to/server.py +from sanic import Sanic +from .path.to.config import MyConfig +from .path.to.some.blueprint import bp + + +def create_app(config=MyConfig) -> Sanic: + app = Sanic("MyApp", config=config) + app.blueprint(bp) + return app +``` +```` + +.. column:: + +``` +When we get to running Sanic later, you will learn that the Sanic CLI can detect this pattern and use it to run your application. +``` + +.. column:: + +```` +```sh +sanic path.to.server:create_app +``` +```` + +## Customization + +The Sanic application instance can be customized for your application needs in a variety of ways at instantiation. + +For complete details, see the [API docs](/api/sanic.app). + +### Custom configuration + +.. column:: + +``` +This simplest form of custom configuration would be to pass your own object directly into that Sanic application instance + +If you create a custom configuration object, it is *highly* recommended that you subclass the :class:`sanic.config.Config` option to inherit its behavior. You could use this option for adding properties, or your own set of custom logic. + +*Added in v21.6* +``` + +.. column:: + +```` +```python +from sanic.config import Config + +class MyConfig(Config): + FOO = "bar" + +app = Sanic(..., config=MyConfig()) +``` +```` + +.. column:: + +``` +A useful example of this feature would be if you wanted to use a config file in a form that differs from what is [supported](../running/configuration.md#using-sanicupdateconfig). +``` + +.. column:: + +```` +```python +from sanic import Sanic, text +from sanic.config import Config + +class TomlConfig(Config): + def __init__(self, *args, path: str, **kwargs): + super().__init__(*args, **kwargs) + + with open(path, "r") as f: + self.apply(toml.load(f)) + + def apply(self, config): + self.update(self._to_uppercase(config)) + + def _to_uppercase(self, obj: Dict[str, Any]) -> Dict[str, Any]: + retval: Dict[str, Any] = {} + for key, value in obj.items(): + upper_key = key.upper() + if isinstance(value, list): + retval[upper_key] = [ + self._to_uppercase(item) for item in value + ] + elif isinstance(value, dict): + retval[upper_key] = self._to_uppercase(value) + else: + retval[upper_key] = value + return retval + +toml_config = TomlConfig(path="/path/to/config.toml") +app = Sanic(toml_config.APP_NAME, config=toml_config) +``` +```` + +### Custom context + +.. column:: + +``` +By default, the application context is a [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) that allows you to set any properties you want on it. However, you also have the option of passing any object whatsoever instead. + +*Added in v21.6* +``` + +.. column:: + +```` +```python +app = Sanic(..., ctx=1) +``` + +```python +app = Sanic(..., ctx={}) +``` + +```python +class MyContext: + ... + +app = Sanic(..., ctx=MyContext()) +``` +```` + +### Custom requests + +.. column:: + +``` +It is sometimes helpful to have your own `Request` class, and tell Sanic to use that instead of the default. One example is if you wanted to modify the default `request.id` generator. + + + +.. note:: Important + + It is important to remember that you are passing the *class* not an instance of the class. +``` + +.. column:: + +```` +```python +import time + +from sanic import Request, Sanic, text + +class NanoSecondRequest(Request): + @classmethod + def generate_id(*_): + return time.time_ns() + +app = Sanic(..., request_class=NanoSecondRequest) + +@app.get("/") +async def handler(request): + return text(str(request.id)) +``` +```` + +### Custom error handler + +.. column:: + +``` +See [exception handling](../best-practices/exceptions.md#custom-error-handling) for more +``` + +.. column:: + +```` +```python +from sanic.handlers import ErrorHandler + +class CustomErrorHandler(ErrorHandler): + def default(self, request, exception): + ''' handles errors that have no error handlers assigned ''' + # You custom error handling logic... + return super().default(request, exception) + +app = Sanic(..., error_handler=CustomErrorHandler()) +``` +```` + +### Custom dumps function + +.. column:: + +``` +It may sometimes be necessary or desirable to provide a custom function that serializes an object to JSON data. +``` + +.. column:: + +```` +```python +import ujson + +dumps = partial(ujson.dumps, escape_forward_slashes=False) +app = Sanic(__name__, dumps=dumps) +``` +```` + +.. column:: + +``` +Or, perhaps use another library or create your own. +``` + +.. column:: + +```` +```python +from orjson import dumps + +app = Sanic("MyApp", dumps=dumps) +``` +```` + +### Custom loads function + +.. column:: + +``` +Similar to `dumps`, you can also provide a custom function for deserializing data. + +*Added in v22.9* +``` + +.. column:: + +```` +```python +from orjson import loads + +app = Sanic("MyApp", loads=loads) +``` +```` + +### Custom typed application + +Beginning in v23.6, the correct type annotation of a default Sanic application instance is: + +```python +sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace] +``` + +It refers to two generic types: + +1. The first is the type of the configuration object. It defaults to :class:`sanic.config.Config`, but can be any subclass of that. +2. The second is the type of the application context. It defaults to [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace), but can be **any object** as show above. + +Let's look at some examples of how the type will change. + +.. column:: + +``` +Consider this example where we pass a custom subclass of :class:`sanic.config.Config` and a custom context object. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +app = Sanic("test", config=CustomConfig()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]" +``` +``` +sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace] +``` +```` + +.. column:: + +``` +Similarly, when passing a custom context object, the type will change to reflect that. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +class Foo: + pass + +app = Sanic("test", ctx=Foo()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, main.Foo]" +``` +``` +sanic.app.Sanic[sanic.config.Config, main.Foo] +``` +```` + +.. column:: + +``` +Of course, you can set both the config and context to custom types. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +app = Sanic("test", config=CustomConfig(), ctx=Foo()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, main.Foo]" +``` +``` +sanic.app.Sanic[main.CustomConfig, main.Foo] +``` +```` + +This pattern is particularly useful if you create a custom type alias for your application instance so that you can use it to annotate listeners and handlers. + +```python +# ./path/to/types.py +from sanic.app import Sanic +from sanic.config import Config +from myapp.context import MyContext +from typing import TypeAlias + +MyApp = TypeAlias("MyApp", Sanic[Config, MyContext]) +``` + +```python +# ./path/to/listeners.py +from myapp.types import MyApp + +def add_listeners(app: MyApp): + @app.before_server_start + async def before_server_start(app: MyApp): + # do something with your fully typed app instance + await app.ctx.db.connect() +``` + +```python +# ./path/to/server.py +from myapp.types import MyApp +from myapp.context import MyContext +from myapp.config import MyConfig +from myapp.listeners import add_listeners + +app = Sanic("myapp", config=MyConfig(), ctx=MyContext()) +add_listeners(app) +``` + +_Added in v23.6_ + +### Custom typed request + +Sanic also allows you to customize the type of the request object. This is useful if you want to add custom properties to the request object, or be able to access your custom properties of a typed application instance. + +The correct, default type of a Sanic request instance is: + +```python +sanic.request.Request[ + sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace], + types.SimpleNamespace +] +``` + +It refers to two generic types: + +1. The first is the type of the application instance. It defaults to `sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]`, but can be any subclass of that. +2. The second is the type of the request context. It defaults to `types.SimpleNamespace`, but can be **any object** as show above in [custom requests](#custom-requests). + +Let's look at some examples of how the type will change. + +.. column:: + +``` +Expanding upon the full example above where there is a type alias for a customized application instance, we can also create a custom request type so that we can access those same type annotations. + +Of course, you do not need type aliases for this to work. We are only showing them here to cut down on the amount of code shown. +``` + +.. column:: + +```` +```python +from sanic import Request +from myapp.types import MyApp +from types import SimpleNamespace + +def add_routes(app: MyApp): + @app.get("/") + async def handler(request: Request[MyApp, SimpleNamespace]): + # do something with your fully typed app instance + results = await request.app.ctx.db.query("SELECT * FROM foo") +``` +```` + +.. column:: + +``` +Perhaps you have a custom request object that generates a custom context object. You can type annotate it to properly access those properties with your IDE as shown here. +``` + +.. column:: + +```` +```python +from sanic import Request, Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +class RequestContext: + foo: Foo + +class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]): + @staticmethod + def make_context() -> RequestContext: + ctx = RequestContext() + ctx.foo = Foo() + return ctx + +app = Sanic( + "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest +) + +@app.get("/") +async def handler(request: CustomRequest): + # Full access to typed: + # - custom application configuration object + # - custom application context object + # - custom request context object + pass +``` +```` + +See more information in the [custom request context](./request#custom-request-context) section. + +_Added in v23.6_ From 1a2963e1e1213652b2639255fe0b74b4ef6ad9bf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:41 +0200 Subject: [PATCH 028/698] New translations cookies.md (Japanese) --- guide/content/ja/guide/basics/cookies.md | 122 +++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 guide/content/ja/guide/basics/cookies.md diff --git a/guide/content/ja/guide/basics/cookies.md b/guide/content/ja/guide/basics/cookies.md new file mode 100644 index 0000000000..a4d60b504c --- /dev/null +++ b/guide/content/ja/guide/basics/cookies.md @@ -0,0 +1,122 @@ +# Cookies + +## Reading + +.. column:: + +``` +Cookies can be accessed via the `Request` object’s `cookies` dictionary. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + test_cookie = request.cookies.get("test") + return text(f"Test cookie: {test_cookie}") +``` +```` + +.. tip:: FYI + +``` +💡 The `request.cookies` object is one of a few types that is a dictionary with each value being a `list`. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the `.get()` method to access the first element and not a `list`. If you do want a `list` of all items, you can use `.getlist()`. + +*Added in v23.3* +``` + +## Writing + +.. column:: + +``` +When returning a response, cookies can be set on the `Response` object: `response.cookies`. This object is an instance of `CookieJar` which is a special sort of dictionary that automatically will write the response headers for you. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + response = text("There's a cookie up in this response") + response.add_cookie( + "test", + "It worked!", + domain=".yummy-yummy-cookie.com", + httponly=True + ) + return response +``` +```` + +Response cookies can be set like dictionary values and have the following parameters available: + +- `path: str` - The subset of URLs to which this cookie applies. Defaults to `/`. +- `domain: str` - Specifies the domain for which the cookie is valid. An explicitly specified domain must always start with a dot. +- `max_age: int` - Number of seconds the cookie should live for. +- `expires: datetime` - The time for the cookie to expire on the client’s browser. Usually it is better to use max-age instead. +- `secure: bool` - Specifies whether the cookie will only be sent via HTTPS. Defaults to `True`. +- `httponly: bool` - Specifies whether the cookie cannot be read by JavaScript. +- `samesite: str` - Available values: Lax, Strict, and None. Defaults to `Lax`. +- `comment: str` - A comment (metadata). +- `host_prefix: bool` - Whether to add the `__Host-` prefix to the cookie. +- `secure_prefix: bool` - Whether to add the `__Secure-` prefix to the cookie. +- `partitioned: bool` - Whether to mark the cookie as partitioned. + +To better understand the implications and usage of these values, it might be helpful to read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) on [setting cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie). + +.. tip:: FYI + +``` +By default, Sanic will set the `secure` flag to `True` to ensure that cookies are only sent over HTTPS as a sensible default. This should not be impactful for local development since secure cookies over HTTP should still be sent to `localhost`. For more information, you should read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) on [secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure). +``` + +## Deleting + +.. column:: + +``` +Cookies can be removed semantically or explicitly. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + response = text("Time to eat some cookies muahaha") + + # This cookie will be set to expire in 0 seconds + response.delete_cookie("eat_me") + + # This cookie will self destruct in 5 seconds + response.add_cookie("fast_bake", "Be quick!", max_age=5) + + return response +``` + +*Don't forget to add `path` or `domain` if needed!* +```` + +## Eating + +.. column:: + +``` +Sanic likes cookies +``` + +.. column:: + +``` +.. attrs:: + :class: is-size-1 has-text-centered + + 🍪 +``` From 766706a64a20025ef1da0bdce20aaf067e56f1c3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:42 +0200 Subject: [PATCH 029/698] New translations cookies.md (Korean) --- guide/content/ko/guide/basics/cookies.md | 122 +++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 guide/content/ko/guide/basics/cookies.md diff --git a/guide/content/ko/guide/basics/cookies.md b/guide/content/ko/guide/basics/cookies.md new file mode 100644 index 0000000000..a4d60b504c --- /dev/null +++ b/guide/content/ko/guide/basics/cookies.md @@ -0,0 +1,122 @@ +# Cookies + +## Reading + +.. column:: + +``` +Cookies can be accessed via the `Request` object’s `cookies` dictionary. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + test_cookie = request.cookies.get("test") + return text(f"Test cookie: {test_cookie}") +``` +```` + +.. tip:: FYI + +``` +💡 The `request.cookies` object is one of a few types that is a dictionary with each value being a `list`. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the `.get()` method to access the first element and not a `list`. If you do want a `list` of all items, you can use `.getlist()`. + +*Added in v23.3* +``` + +## Writing + +.. column:: + +``` +When returning a response, cookies can be set on the `Response` object: `response.cookies`. This object is an instance of `CookieJar` which is a special sort of dictionary that automatically will write the response headers for you. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + response = text("There's a cookie up in this response") + response.add_cookie( + "test", + "It worked!", + domain=".yummy-yummy-cookie.com", + httponly=True + ) + return response +``` +```` + +Response cookies can be set like dictionary values and have the following parameters available: + +- `path: str` - The subset of URLs to which this cookie applies. Defaults to `/`. +- `domain: str` - Specifies the domain for which the cookie is valid. An explicitly specified domain must always start with a dot. +- `max_age: int` - Number of seconds the cookie should live for. +- `expires: datetime` - The time for the cookie to expire on the client’s browser. Usually it is better to use max-age instead. +- `secure: bool` - Specifies whether the cookie will only be sent via HTTPS. Defaults to `True`. +- `httponly: bool` - Specifies whether the cookie cannot be read by JavaScript. +- `samesite: str` - Available values: Lax, Strict, and None. Defaults to `Lax`. +- `comment: str` - A comment (metadata). +- `host_prefix: bool` - Whether to add the `__Host-` prefix to the cookie. +- `secure_prefix: bool` - Whether to add the `__Secure-` prefix to the cookie. +- `partitioned: bool` - Whether to mark the cookie as partitioned. + +To better understand the implications and usage of these values, it might be helpful to read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) on [setting cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie). + +.. tip:: FYI + +``` +By default, Sanic will set the `secure` flag to `True` to ensure that cookies are only sent over HTTPS as a sensible default. This should not be impactful for local development since secure cookies over HTTP should still be sent to `localhost`. For more information, you should read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) on [secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure). +``` + +## Deleting + +.. column:: + +``` +Cookies can be removed semantically or explicitly. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + response = text("Time to eat some cookies muahaha") + + # This cookie will be set to expire in 0 seconds + response.delete_cookie("eat_me") + + # This cookie will self destruct in 5 seconds + response.add_cookie("fast_bake", "Be quick!", max_age=5) + + return response +``` + +*Don't forget to add `path` or `domain` if needed!* +```` + +## Eating + +.. column:: + +``` +Sanic likes cookies +``` + +.. column:: + +``` +.. attrs:: + :class: is-size-1 has-text-centered + + 🍪 +``` From 1e6585afb49fd22b56e11aec77a7724a6960e17f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:43 +0200 Subject: [PATCH 030/698] New translations cookies.md (Chinese Simplified) --- guide/content/zh/guide/basics/cookies.md | 122 +++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 guide/content/zh/guide/basics/cookies.md diff --git a/guide/content/zh/guide/basics/cookies.md b/guide/content/zh/guide/basics/cookies.md new file mode 100644 index 0000000000..a4d60b504c --- /dev/null +++ b/guide/content/zh/guide/basics/cookies.md @@ -0,0 +1,122 @@ +# Cookies + +## Reading + +.. column:: + +``` +Cookies can be accessed via the `Request` object’s `cookies` dictionary. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + test_cookie = request.cookies.get("test") + return text(f"Test cookie: {test_cookie}") +``` +```` + +.. tip:: FYI + +``` +💡 The `request.cookies` object is one of a few types that is a dictionary with each value being a `list`. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the `.get()` method to access the first element and not a `list`. If you do want a `list` of all items, you can use `.getlist()`. + +*Added in v23.3* +``` + +## Writing + +.. column:: + +``` +When returning a response, cookies can be set on the `Response` object: `response.cookies`. This object is an instance of `CookieJar` which is a special sort of dictionary that automatically will write the response headers for you. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + response = text("There's a cookie up in this response") + response.add_cookie( + "test", + "It worked!", + domain=".yummy-yummy-cookie.com", + httponly=True + ) + return response +``` +```` + +Response cookies can be set like dictionary values and have the following parameters available: + +- `path: str` - The subset of URLs to which this cookie applies. Defaults to `/`. +- `domain: str` - Specifies the domain for which the cookie is valid. An explicitly specified domain must always start with a dot. +- `max_age: int` - Number of seconds the cookie should live for. +- `expires: datetime` - The time for the cookie to expire on the client’s browser. Usually it is better to use max-age instead. +- `secure: bool` - Specifies whether the cookie will only be sent via HTTPS. Defaults to `True`. +- `httponly: bool` - Specifies whether the cookie cannot be read by JavaScript. +- `samesite: str` - Available values: Lax, Strict, and None. Defaults to `Lax`. +- `comment: str` - A comment (metadata). +- `host_prefix: bool` - Whether to add the `__Host-` prefix to the cookie. +- `secure_prefix: bool` - Whether to add the `__Secure-` prefix to the cookie. +- `partitioned: bool` - Whether to mark the cookie as partitioned. + +To better understand the implications and usage of these values, it might be helpful to read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) on [setting cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie). + +.. tip:: FYI + +``` +By default, Sanic will set the `secure` flag to `True` to ensure that cookies are only sent over HTTPS as a sensible default. This should not be impactful for local development since secure cookies over HTTP should still be sent to `localhost`. For more information, you should read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) on [secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure). +``` + +## Deleting + +.. column:: + +``` +Cookies can be removed semantically or explicitly. +``` + +.. column:: + +```` +```python +@app.route("/cookie") +async def test(request): + response = text("Time to eat some cookies muahaha") + + # This cookie will be set to expire in 0 seconds + response.delete_cookie("eat_me") + + # This cookie will self destruct in 5 seconds + response.add_cookie("fast_bake", "Be quick!", max_age=5) + + return response +``` + +*Don't forget to add `path` or `domain` if needed!* +```` + +## Eating + +.. column:: + +``` +Sanic likes cookies +``` + +.. column:: + +``` +.. attrs:: + :class: is-size-1 has-text-centered + + 🍪 +``` From 5603556c64bc5342731db8a8473da544bc27e154 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:44 +0200 Subject: [PATCH 031/698] New translations handlers.md (Japanese) --- guide/content/ja/guide/basics/handlers.md | 217 ++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 guide/content/ja/guide/basics/handlers.md diff --git a/guide/content/ja/guide/basics/handlers.md b/guide/content/ja/guide/basics/handlers.md new file mode 100644 index 0000000000..dd9e98b21b --- /dev/null +++ b/guide/content/ja/guide/basics/handlers.md @@ -0,0 +1,217 @@ +# Handlers + +The next important building block are your _handlers_. These are also sometimes called "views". + +In Sanic, a handler is any callable that takes at least a :class:`sanic.request.Request` instance as an argument, and returns either an :class:`sanic.response.HTTPResponse` instance, or a coroutine that does the same. + +.. column:: + +``` +Huh? 😕 + +It is a **function**; either synchronous or asynchronous. + +The job of the handler is to respond to an endpoint and do something. This is where the majority of your business logic will go. +``` + +.. column:: + +```` +```python +def i_am_a_handler(request): + return HTTPResponse() + +async def i_am_ALSO_a_handler(request): + return HTTPResponse() +``` +```` + +Two more important items to note: + +1. You almost _never_ will want to use :class:`sanic.response.HTTPresponse` directly. It is much simpler to use one of the [convenience methods](./response#methods). + + - `from sanic import json` + - `from sanic import html` + - `from sanic import redirect` + - _etc_ +2. As we will see in [the streaming section](../advanced/streaming#response-streaming), you do not always need to return an object. If you use this lower-level API, you can control the flow of the response from within the handler, and a return object is not used. + +.. tip:: Heads up + +``` +If you want to learn more about encapsulating your logic, checkout [class based views](../advanced/class-based-views.md). For now, we will continue forward with just function-based views. +``` + +### A simple function-based handler + +The most common way to create a route handler is to decorate the function. It creates a visually simple identification of a route definition. We'll learn more about [routing soon](./routing.md). + +.. column:: + +``` +Let's look at a practical example. + +- We use a convenience decorator on our app instance: `@app.get()` +- And a handy convenience method for generating out response object: `text()` + +Mission accomplished 💪 +``` + +.. column:: + +```` +```python +from sanic import text + +@app.get("/foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +*** + +## A word about _async_... + +.. column:: + +``` +It is entirely possible to write handlers that are synchronous. + +In this example, we are using the _blocking_ `time.sleep()` to simulate 100ms of processing time. Perhaps this represents fetching data from a DB, or a 3rd-party website. + +Using four (4) worker processes and a common benchmarking tool: + +- **956** requests in 30.10s +- Or, about **31.76** requests/second +``` + +.. column:: + +```` +```python +@app.get("/sync") +def sync_handler(request): + time.sleep(0.1) + return text("Done.") +``` +```` + +.. column:: + +``` +Just by changing to the asynchronous alternative `asyncio.sleep()`, we see an incredible change in performance. 🚀 + +Using the same four (4) worker processes: + +- **115,590** requests in 30.08s +- Or, about **3,843.17** requests/second + +.. attrs:: + :class: is-size-2 + + 🤯 +``` + +.. column:: + +```` +```python +@app.get("/async") +async def async_handler(request): + await asyncio.sleep(0.1) + return text("Done.") +``` +```` + +Okay... this is a ridiculously overdramatic result. And any benchmark you see is inherently very biased. This example is meant to over-the-top show the benefit of `async/await` in the web world. Results will certainly vary. Tools like Sanic and other async Python libraries are not magic bullets that make things faster. They make them _more efficient_. + +In our example, the asynchronous version is so much better because while one request is sleeping, it is able to start another one, and another one, and another one, and another one... + +But, this is the point! Sanic is fast because it takes the available resources and squeezes performance out of them. It can handle many requests concurrently, which means more requests per second. + +.. tip:: A common mistake! + +``` +Don't do this! You need to ping a website. What do you use? `pip install your-fav-request-library` 🙈 + +Instead, try using a client that is `async/await` capable. Your server will thank you. Avoid using blocking tools, and favor those that play well in the asynchronous ecosystem. If you need recommendations, check out [Awesome Sanic](https://github.com/mekicha/awesome-sanic). + +Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package (sanic-testing) 😉. +``` + +*** + +## A fully annotated handler + +For those that are using type annotations... + +```python +from sanic.response import HTTPResponse, text +from sanic.request import Request + +@app.get("/typed") +async def typed_handler(request: Request) -> HTTPResponse: + return text("Done.") +``` + +## Naming your handlers + +All handlers are named automatically. This is useful for debugging, and for generating URLs in templates. When not specified, the name that will be used is the name of the function. + +.. column:: + +``` +For example, this handler will be named `foo_handler`. +``` + +.. column:: + +```` +```python +# Handler name will be "foo_handler" +@app.get("/foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +.. column:: + +``` +However, you can override this by passing the `name` argument to the decorator. +``` + +.. column:: + +```` +```python +# Handler name will be "foo" +@app.get("/foo", name="foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +.. column:: + +``` +In fact, as you will, there may be times when you **MUST** supply a name. For example, if you use two decorators on the same function, you will need to supply a name for at least one of them. + +If you do not, you will get an error and your app will not start. Names **must** be unique within your app. +``` + +.. column:: + +```` +```python +# Two handlers, same function, +# different names: +# - "foo_arg" +# - "foo" +@app.get("/foo/", name="foo_arg") +@app.get("/foo") +async def foo(request, arg=None): + return text("I said foo!") +``` +```` From d6b7be1216af0b85aa39e4874c416309bb6b652b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:45 +0200 Subject: [PATCH 032/698] New translations handlers.md (Korean) --- guide/content/ko/guide/basics/handlers.md | 217 ++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 guide/content/ko/guide/basics/handlers.md diff --git a/guide/content/ko/guide/basics/handlers.md b/guide/content/ko/guide/basics/handlers.md new file mode 100644 index 0000000000..dd9e98b21b --- /dev/null +++ b/guide/content/ko/guide/basics/handlers.md @@ -0,0 +1,217 @@ +# Handlers + +The next important building block are your _handlers_. These are also sometimes called "views". + +In Sanic, a handler is any callable that takes at least a :class:`sanic.request.Request` instance as an argument, and returns either an :class:`sanic.response.HTTPResponse` instance, or a coroutine that does the same. + +.. column:: + +``` +Huh? 😕 + +It is a **function**; either synchronous or asynchronous. + +The job of the handler is to respond to an endpoint and do something. This is where the majority of your business logic will go. +``` + +.. column:: + +```` +```python +def i_am_a_handler(request): + return HTTPResponse() + +async def i_am_ALSO_a_handler(request): + return HTTPResponse() +``` +```` + +Two more important items to note: + +1. You almost _never_ will want to use :class:`sanic.response.HTTPresponse` directly. It is much simpler to use one of the [convenience methods](./response#methods). + + - `from sanic import json` + - `from sanic import html` + - `from sanic import redirect` + - _etc_ +2. As we will see in [the streaming section](../advanced/streaming#response-streaming), you do not always need to return an object. If you use this lower-level API, you can control the flow of the response from within the handler, and a return object is not used. + +.. tip:: Heads up + +``` +If you want to learn more about encapsulating your logic, checkout [class based views](../advanced/class-based-views.md). For now, we will continue forward with just function-based views. +``` + +### A simple function-based handler + +The most common way to create a route handler is to decorate the function. It creates a visually simple identification of a route definition. We'll learn more about [routing soon](./routing.md). + +.. column:: + +``` +Let's look at a practical example. + +- We use a convenience decorator on our app instance: `@app.get()` +- And a handy convenience method for generating out response object: `text()` + +Mission accomplished 💪 +``` + +.. column:: + +```` +```python +from sanic import text + +@app.get("/foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +*** + +## A word about _async_... + +.. column:: + +``` +It is entirely possible to write handlers that are synchronous. + +In this example, we are using the _blocking_ `time.sleep()` to simulate 100ms of processing time. Perhaps this represents fetching data from a DB, or a 3rd-party website. + +Using four (4) worker processes and a common benchmarking tool: + +- **956** requests in 30.10s +- Or, about **31.76** requests/second +``` + +.. column:: + +```` +```python +@app.get("/sync") +def sync_handler(request): + time.sleep(0.1) + return text("Done.") +``` +```` + +.. column:: + +``` +Just by changing to the asynchronous alternative `asyncio.sleep()`, we see an incredible change in performance. 🚀 + +Using the same four (4) worker processes: + +- **115,590** requests in 30.08s +- Or, about **3,843.17** requests/second + +.. attrs:: + :class: is-size-2 + + 🤯 +``` + +.. column:: + +```` +```python +@app.get("/async") +async def async_handler(request): + await asyncio.sleep(0.1) + return text("Done.") +``` +```` + +Okay... this is a ridiculously overdramatic result. And any benchmark you see is inherently very biased. This example is meant to over-the-top show the benefit of `async/await` in the web world. Results will certainly vary. Tools like Sanic and other async Python libraries are not magic bullets that make things faster. They make them _more efficient_. + +In our example, the asynchronous version is so much better because while one request is sleeping, it is able to start another one, and another one, and another one, and another one... + +But, this is the point! Sanic is fast because it takes the available resources and squeezes performance out of them. It can handle many requests concurrently, which means more requests per second. + +.. tip:: A common mistake! + +``` +Don't do this! You need to ping a website. What do you use? `pip install your-fav-request-library` 🙈 + +Instead, try using a client that is `async/await` capable. Your server will thank you. Avoid using blocking tools, and favor those that play well in the asynchronous ecosystem. If you need recommendations, check out [Awesome Sanic](https://github.com/mekicha/awesome-sanic). + +Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package (sanic-testing) 😉. +``` + +*** + +## A fully annotated handler + +For those that are using type annotations... + +```python +from sanic.response import HTTPResponse, text +from sanic.request import Request + +@app.get("/typed") +async def typed_handler(request: Request) -> HTTPResponse: + return text("Done.") +``` + +## Naming your handlers + +All handlers are named automatically. This is useful for debugging, and for generating URLs in templates. When not specified, the name that will be used is the name of the function. + +.. column:: + +``` +For example, this handler will be named `foo_handler`. +``` + +.. column:: + +```` +```python +# Handler name will be "foo_handler" +@app.get("/foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +.. column:: + +``` +However, you can override this by passing the `name` argument to the decorator. +``` + +.. column:: + +```` +```python +# Handler name will be "foo" +@app.get("/foo", name="foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +.. column:: + +``` +In fact, as you will, there may be times when you **MUST** supply a name. For example, if you use two decorators on the same function, you will need to supply a name for at least one of them. + +If you do not, you will get an error and your app will not start. Names **must** be unique within your app. +``` + +.. column:: + +```` +```python +# Two handlers, same function, +# different names: +# - "foo_arg" +# - "foo" +@app.get("/foo/", name="foo_arg") +@app.get("/foo") +async def foo(request, arg=None): + return text("I said foo!") +``` +```` From 3e417f926cbdf1242e009706260bd1a5cfe3da92 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:46 +0200 Subject: [PATCH 033/698] New translations handlers.md (Chinese Simplified) --- guide/content/zh/guide/basics/handlers.md | 217 ++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 guide/content/zh/guide/basics/handlers.md diff --git a/guide/content/zh/guide/basics/handlers.md b/guide/content/zh/guide/basics/handlers.md new file mode 100644 index 0000000000..dd9e98b21b --- /dev/null +++ b/guide/content/zh/guide/basics/handlers.md @@ -0,0 +1,217 @@ +# Handlers + +The next important building block are your _handlers_. These are also sometimes called "views". + +In Sanic, a handler is any callable that takes at least a :class:`sanic.request.Request` instance as an argument, and returns either an :class:`sanic.response.HTTPResponse` instance, or a coroutine that does the same. + +.. column:: + +``` +Huh? 😕 + +It is a **function**; either synchronous or asynchronous. + +The job of the handler is to respond to an endpoint and do something. This is where the majority of your business logic will go. +``` + +.. column:: + +```` +```python +def i_am_a_handler(request): + return HTTPResponse() + +async def i_am_ALSO_a_handler(request): + return HTTPResponse() +``` +```` + +Two more important items to note: + +1. You almost _never_ will want to use :class:`sanic.response.HTTPresponse` directly. It is much simpler to use one of the [convenience methods](./response#methods). + + - `from sanic import json` + - `from sanic import html` + - `from sanic import redirect` + - _etc_ +2. As we will see in [the streaming section](../advanced/streaming#response-streaming), you do not always need to return an object. If you use this lower-level API, you can control the flow of the response from within the handler, and a return object is not used. + +.. tip:: Heads up + +``` +If you want to learn more about encapsulating your logic, checkout [class based views](../advanced/class-based-views.md). For now, we will continue forward with just function-based views. +``` + +### A simple function-based handler + +The most common way to create a route handler is to decorate the function. It creates a visually simple identification of a route definition. We'll learn more about [routing soon](./routing.md). + +.. column:: + +``` +Let's look at a practical example. + +- We use a convenience decorator on our app instance: `@app.get()` +- And a handy convenience method for generating out response object: `text()` + +Mission accomplished 💪 +``` + +.. column:: + +```` +```python +from sanic import text + +@app.get("/foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +*** + +## A word about _async_... + +.. column:: + +``` +It is entirely possible to write handlers that are synchronous. + +In this example, we are using the _blocking_ `time.sleep()` to simulate 100ms of processing time. Perhaps this represents fetching data from a DB, or a 3rd-party website. + +Using four (4) worker processes and a common benchmarking tool: + +- **956** requests in 30.10s +- Or, about **31.76** requests/second +``` + +.. column:: + +```` +```python +@app.get("/sync") +def sync_handler(request): + time.sleep(0.1) + return text("Done.") +``` +```` + +.. column:: + +``` +Just by changing to the asynchronous alternative `asyncio.sleep()`, we see an incredible change in performance. 🚀 + +Using the same four (4) worker processes: + +- **115,590** requests in 30.08s +- Or, about **3,843.17** requests/second + +.. attrs:: + :class: is-size-2 + + 🤯 +``` + +.. column:: + +```` +```python +@app.get("/async") +async def async_handler(request): + await asyncio.sleep(0.1) + return text("Done.") +``` +```` + +Okay... this is a ridiculously overdramatic result. And any benchmark you see is inherently very biased. This example is meant to over-the-top show the benefit of `async/await` in the web world. Results will certainly vary. Tools like Sanic and other async Python libraries are not magic bullets that make things faster. They make them _more efficient_. + +In our example, the asynchronous version is so much better because while one request is sleeping, it is able to start another one, and another one, and another one, and another one... + +But, this is the point! Sanic is fast because it takes the available resources and squeezes performance out of them. It can handle many requests concurrently, which means more requests per second. + +.. tip:: A common mistake! + +``` +Don't do this! You need to ping a website. What do you use? `pip install your-fav-request-library` 🙈 + +Instead, try using a client that is `async/await` capable. Your server will thank you. Avoid using blocking tools, and favor those that play well in the asynchronous ecosystem. If you need recommendations, check out [Awesome Sanic](https://github.com/mekicha/awesome-sanic). + +Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package (sanic-testing) 😉. +``` + +*** + +## A fully annotated handler + +For those that are using type annotations... + +```python +from sanic.response import HTTPResponse, text +from sanic.request import Request + +@app.get("/typed") +async def typed_handler(request: Request) -> HTTPResponse: + return text("Done.") +``` + +## Naming your handlers + +All handlers are named automatically. This is useful for debugging, and for generating URLs in templates. When not specified, the name that will be used is the name of the function. + +.. column:: + +``` +For example, this handler will be named `foo_handler`. +``` + +.. column:: + +```` +```python +# Handler name will be "foo_handler" +@app.get("/foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +.. column:: + +``` +However, you can override this by passing the `name` argument to the decorator. +``` + +.. column:: + +```` +```python +# Handler name will be "foo" +@app.get("/foo", name="foo") +async def foo_handler(request): + return text("I said foo!") +``` +```` + +.. column:: + +``` +In fact, as you will, there may be times when you **MUST** supply a name. For example, if you use two decorators on the same function, you will need to supply a name for at least one of them. + +If you do not, you will get an error and your app will not start. Names **must** be unique within your app. +``` + +.. column:: + +```` +```python +# Two handlers, same function, +# different names: +# - "foo_arg" +# - "foo" +@app.get("/foo/", name="foo_arg") +@app.get("/foo") +async def foo(request, arg=None): + return text("I said foo!") +``` +```` From da021e62ebb0f1c9ec7e1244ce8d10d2fc8c5235 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:47 +0200 Subject: [PATCH 034/698] New translations headers.md (Japanese) --- guide/content/ja/guide/basics/headers.md | 249 +++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 guide/content/ja/guide/basics/headers.md diff --git a/guide/content/ja/guide/basics/headers.md b/guide/content/ja/guide/basics/headers.md new file mode 100644 index 0000000000..1e85f926d2 --- /dev/null +++ b/guide/content/ja/guide/basics/headers.md @@ -0,0 +1,249 @@ +# Headers + +Request and response headers are available in the `Request` and `HTTPResponse` objects, respectively. They make use of the [`multidict` package](https://multidict.readthedocs.io/en/stable/multidict.html#cimultidict) that allows a single key to have multiple values. + +.. tip:: FYI + +``` +Header keys are converted to *lowercase* when parsed. Capitalization is not considered for headers. +``` + +## Request + +Sanic does attempt to do some normalization on request headers before presenting them to the developer, and also make some potentially meaningful extractions for common use cases. + +.. column:: + +``` +#### Tokens + +Authorization tokens in the form `Token ` or `Bearer ` are extracted to the request object: `request.token`. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(request.token) +``` + +```sh +curl localhost:8000 \ + -H "Authorization: Token ABCDEF12345679" +ABCDEF12345679 +``` + +```sh +curl localhost:8000 \ + -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" +eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` +```` + +### Proxy headers + +Sanic has special handling for proxy headers. See the [proxy headers](/guide/advanced/proxy-headers.md) section for more details. + +### Host header and dynamic URL construction + +.. column:: + +``` +The *effective host* is available via `request.host`. This is not necessarily the same as the host header, as it prefers proxy-forwarded host and can be forced by the server name setting. + +Webapps should generally use this accessor so that they can function the same no matter how they are deployed. The actual host header, if needed, can be found via `request.headers` + +The effective host is also used in dynamic URL construction via `request.url_for`, which uses the request to determine the external address of a handler. + +.. tip:: Be wary of malicious clients + + These URLs can be manipulated by sending misleading host headers. `app.url_for` should be used instead if this is a concern. +``` + +.. column:: + +```` +```python +app.config.SERVER_NAME = "https://example.com" + +@app.route("/hosts", name="foo") +async def handler(request): + return json( + { + "effective host": request.host, + "host header": request.headers.get("host"), + "forwarded host": request.forwarded.get("host"), + "you are here": request.url_for("foo"), + } + ) +``` + +```sh +curl localhost:8000/hosts +{ + "effective host": "example.com", + "host header": "localhost:8000", + "forwarded host": null, + "you are here": "https://example.com/hosts" +} +``` +```` + +### Other headers + +.. column:: + +``` +All request headers are available on `request.headers`, and can be accessed in dictionary form. Capitalization is not considered for headers, and can be accessed using either uppercase or lowercase keys. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return json( + { + "foo_weakref": request.headers["foo"], + "foo_get": request.headers.get("Foo"), + "foo_getone": request.headers.getone("FOO"), + "foo_getall": request.headers.getall("fOo"), + "all": list(request.headers.items()), + } + ) +``` + +```sh +curl localhost:9999/headers -H "Foo: one" -H "FOO: two"|jq +{ + "foo_weakref": "one", + "foo_get": "one", + "foo_getone": "one", + "foo_getall": [ + "one", + "two" + ], + "all": [ + [ + "host", + "localhost:9999" + ], + [ + "user-agent", + "curl/7.76.1" + ], + [ + "accept", + "*/*" + ], + [ + "foo", + "one" + ], + [ + "foo", + "two" + ] + ] +} +``` +```` + +.. tip:: FYI + +``` +💡 The request.headers object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the .get() or .getone() methods to access the first element and not a list. If you do want a list of all items, you can use .getall(). +``` + +### Request ID + +.. column:: + +``` +Often it is convenient or necessary to track a request by its `X-Request-ID` header. You can easily access that as: `request.id`. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(request.id) +``` + +```sh +curl localhost:8000 \ + -H "X-Request-ID: ABCDEF12345679" +ABCDEF12345679 +``` +```` + +## Response + +Sanic will automatically set the following response headers (when appropriate) for you: + +- `content-length` +- `content-type` +- `connection` +- `transfer-encoding` + +In most circumstances, you should never need to worry about setting these headers. + +.. column:: + +``` +Any other header that you would like to set can be done either in the route handler, or a response middleware. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text("Done.", headers={"content-language": "en-US"}) + +@app.middleware("response") +async def add_csp(request, response): + response.headers["content-security-policy"] = "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'" +``` +```` + +.. column:: + +``` +A common [middleware](middleware.md) you might want is to add a `X-Request-ID` header to every response. As stated above: `request.id` will provide the ID from the incoming request. But, even if no ID was supplied in the request headers, one will be automatically supplied for you. + +[See API docs for more details](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#sanic.request.Request.id) +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(str(request.id)) + +@app.on_response +async def add_request_id_header(request, response): + response.headers["X-Request-ID"] = request.id +``` + +```sh +curl localhost:8000 -i +HTTP/1.1 200 OK +X-Request-ID: 805a958e-9906-4e7a-8fe0-cbe83590431b +content-length: 36 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +805a958e-9906-4e7a-8fe0-cbe83590431b +``` +```` From 394e44fd28559b0a447e98cd95891773aee8298f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:48 +0200 Subject: [PATCH 035/698] New translations headers.md (Korean) --- guide/content/ko/guide/basics/headers.md | 249 +++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 guide/content/ko/guide/basics/headers.md diff --git a/guide/content/ko/guide/basics/headers.md b/guide/content/ko/guide/basics/headers.md new file mode 100644 index 0000000000..1e85f926d2 --- /dev/null +++ b/guide/content/ko/guide/basics/headers.md @@ -0,0 +1,249 @@ +# Headers + +Request and response headers are available in the `Request` and `HTTPResponse` objects, respectively. They make use of the [`multidict` package](https://multidict.readthedocs.io/en/stable/multidict.html#cimultidict) that allows a single key to have multiple values. + +.. tip:: FYI + +``` +Header keys are converted to *lowercase* when parsed. Capitalization is not considered for headers. +``` + +## Request + +Sanic does attempt to do some normalization on request headers before presenting them to the developer, and also make some potentially meaningful extractions for common use cases. + +.. column:: + +``` +#### Tokens + +Authorization tokens in the form `Token ` or `Bearer ` are extracted to the request object: `request.token`. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(request.token) +``` + +```sh +curl localhost:8000 \ + -H "Authorization: Token ABCDEF12345679" +ABCDEF12345679 +``` + +```sh +curl localhost:8000 \ + -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" +eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` +```` + +### Proxy headers + +Sanic has special handling for proxy headers. See the [proxy headers](/guide/advanced/proxy-headers.md) section for more details. + +### Host header and dynamic URL construction + +.. column:: + +``` +The *effective host* is available via `request.host`. This is not necessarily the same as the host header, as it prefers proxy-forwarded host and can be forced by the server name setting. + +Webapps should generally use this accessor so that they can function the same no matter how they are deployed. The actual host header, if needed, can be found via `request.headers` + +The effective host is also used in dynamic URL construction via `request.url_for`, which uses the request to determine the external address of a handler. + +.. tip:: Be wary of malicious clients + + These URLs can be manipulated by sending misleading host headers. `app.url_for` should be used instead if this is a concern. +``` + +.. column:: + +```` +```python +app.config.SERVER_NAME = "https://example.com" + +@app.route("/hosts", name="foo") +async def handler(request): + return json( + { + "effective host": request.host, + "host header": request.headers.get("host"), + "forwarded host": request.forwarded.get("host"), + "you are here": request.url_for("foo"), + } + ) +``` + +```sh +curl localhost:8000/hosts +{ + "effective host": "example.com", + "host header": "localhost:8000", + "forwarded host": null, + "you are here": "https://example.com/hosts" +} +``` +```` + +### Other headers + +.. column:: + +``` +All request headers are available on `request.headers`, and can be accessed in dictionary form. Capitalization is not considered for headers, and can be accessed using either uppercase or lowercase keys. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return json( + { + "foo_weakref": request.headers["foo"], + "foo_get": request.headers.get("Foo"), + "foo_getone": request.headers.getone("FOO"), + "foo_getall": request.headers.getall("fOo"), + "all": list(request.headers.items()), + } + ) +``` + +```sh +curl localhost:9999/headers -H "Foo: one" -H "FOO: two"|jq +{ + "foo_weakref": "one", + "foo_get": "one", + "foo_getone": "one", + "foo_getall": [ + "one", + "two" + ], + "all": [ + [ + "host", + "localhost:9999" + ], + [ + "user-agent", + "curl/7.76.1" + ], + [ + "accept", + "*/*" + ], + [ + "foo", + "one" + ], + [ + "foo", + "two" + ] + ] +} +``` +```` + +.. tip:: FYI + +``` +💡 The request.headers object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the .get() or .getone() methods to access the first element and not a list. If you do want a list of all items, you can use .getall(). +``` + +### Request ID + +.. column:: + +``` +Often it is convenient or necessary to track a request by its `X-Request-ID` header. You can easily access that as: `request.id`. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(request.id) +``` + +```sh +curl localhost:8000 \ + -H "X-Request-ID: ABCDEF12345679" +ABCDEF12345679 +``` +```` + +## Response + +Sanic will automatically set the following response headers (when appropriate) for you: + +- `content-length` +- `content-type` +- `connection` +- `transfer-encoding` + +In most circumstances, you should never need to worry about setting these headers. + +.. column:: + +``` +Any other header that you would like to set can be done either in the route handler, or a response middleware. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text("Done.", headers={"content-language": "en-US"}) + +@app.middleware("response") +async def add_csp(request, response): + response.headers["content-security-policy"] = "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'" +``` +```` + +.. column:: + +``` +A common [middleware](middleware.md) you might want is to add a `X-Request-ID` header to every response. As stated above: `request.id` will provide the ID from the incoming request. But, even if no ID was supplied in the request headers, one will be automatically supplied for you. + +[See API docs for more details](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#sanic.request.Request.id) +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(str(request.id)) + +@app.on_response +async def add_request_id_header(request, response): + response.headers["X-Request-ID"] = request.id +``` + +```sh +curl localhost:8000 -i +HTTP/1.1 200 OK +X-Request-ID: 805a958e-9906-4e7a-8fe0-cbe83590431b +content-length: 36 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +805a958e-9906-4e7a-8fe0-cbe83590431b +``` +```` From d8e530f8effa6d2ce62b778322321f108c8bf653 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:49 +0200 Subject: [PATCH 036/698] New translations headers.md (Chinese Simplified) --- guide/content/zh/guide/basics/headers.md | 249 +++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 guide/content/zh/guide/basics/headers.md diff --git a/guide/content/zh/guide/basics/headers.md b/guide/content/zh/guide/basics/headers.md new file mode 100644 index 0000000000..1e85f926d2 --- /dev/null +++ b/guide/content/zh/guide/basics/headers.md @@ -0,0 +1,249 @@ +# Headers + +Request and response headers are available in the `Request` and `HTTPResponse` objects, respectively. They make use of the [`multidict` package](https://multidict.readthedocs.io/en/stable/multidict.html#cimultidict) that allows a single key to have multiple values. + +.. tip:: FYI + +``` +Header keys are converted to *lowercase* when parsed. Capitalization is not considered for headers. +``` + +## Request + +Sanic does attempt to do some normalization on request headers before presenting them to the developer, and also make some potentially meaningful extractions for common use cases. + +.. column:: + +``` +#### Tokens + +Authorization tokens in the form `Token ` or `Bearer ` are extracted to the request object: `request.token`. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(request.token) +``` + +```sh +curl localhost:8000 \ + -H "Authorization: Token ABCDEF12345679" +ABCDEF12345679 +``` + +```sh +curl localhost:8000 \ + -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" +eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c +``` +```` + +### Proxy headers + +Sanic has special handling for proxy headers. See the [proxy headers](/guide/advanced/proxy-headers.md) section for more details. + +### Host header and dynamic URL construction + +.. column:: + +``` +The *effective host* is available via `request.host`. This is not necessarily the same as the host header, as it prefers proxy-forwarded host and can be forced by the server name setting. + +Webapps should generally use this accessor so that they can function the same no matter how they are deployed. The actual host header, if needed, can be found via `request.headers` + +The effective host is also used in dynamic URL construction via `request.url_for`, which uses the request to determine the external address of a handler. + +.. tip:: Be wary of malicious clients + + These URLs can be manipulated by sending misleading host headers. `app.url_for` should be used instead if this is a concern. +``` + +.. column:: + +```` +```python +app.config.SERVER_NAME = "https://example.com" + +@app.route("/hosts", name="foo") +async def handler(request): + return json( + { + "effective host": request.host, + "host header": request.headers.get("host"), + "forwarded host": request.forwarded.get("host"), + "you are here": request.url_for("foo"), + } + ) +``` + +```sh +curl localhost:8000/hosts +{ + "effective host": "example.com", + "host header": "localhost:8000", + "forwarded host": null, + "you are here": "https://example.com/hosts" +} +``` +```` + +### Other headers + +.. column:: + +``` +All request headers are available on `request.headers`, and can be accessed in dictionary form. Capitalization is not considered for headers, and can be accessed using either uppercase or lowercase keys. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return json( + { + "foo_weakref": request.headers["foo"], + "foo_get": request.headers.get("Foo"), + "foo_getone": request.headers.getone("FOO"), + "foo_getall": request.headers.getall("fOo"), + "all": list(request.headers.items()), + } + ) +``` + +```sh +curl localhost:9999/headers -H "Foo: one" -H "FOO: two"|jq +{ + "foo_weakref": "one", + "foo_get": "one", + "foo_getone": "one", + "foo_getall": [ + "one", + "two" + ], + "all": [ + [ + "host", + "localhost:9999" + ], + [ + "user-agent", + "curl/7.76.1" + ], + [ + "accept", + "*/*" + ], + [ + "foo", + "one" + ], + [ + "foo", + "two" + ] + ] +} +``` +```` + +.. tip:: FYI + +``` +💡 The request.headers object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the .get() or .getone() methods to access the first element and not a list. If you do want a list of all items, you can use .getall(). +``` + +### Request ID + +.. column:: + +``` +Often it is convenient or necessary to track a request by its `X-Request-ID` header. You can easily access that as: `request.id`. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(request.id) +``` + +```sh +curl localhost:8000 \ + -H "X-Request-ID: ABCDEF12345679" +ABCDEF12345679 +``` +```` + +## Response + +Sanic will automatically set the following response headers (when appropriate) for you: + +- `content-length` +- `content-type` +- `connection` +- `transfer-encoding` + +In most circumstances, you should never need to worry about setting these headers. + +.. column:: + +``` +Any other header that you would like to set can be done either in the route handler, or a response middleware. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text("Done.", headers={"content-language": "en-US"}) + +@app.middleware("response") +async def add_csp(request, response): + response.headers["content-security-policy"] = "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'" +``` +```` + +.. column:: + +``` +A common [middleware](middleware.md) you might want is to add a `X-Request-ID` header to every response. As stated above: `request.id` will provide the ID from the incoming request. But, even if no ID was supplied in the request headers, one will be automatically supplied for you. + +[See API docs for more details](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#sanic.request.Request.id) +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request): + return text(str(request.id)) + +@app.on_response +async def add_request_id_header(request, response): + response.headers["X-Request-ID"] = request.id +``` + +```sh +curl localhost:8000 -i +HTTP/1.1 200 OK +X-Request-ID: 805a958e-9906-4e7a-8fe0-cbe83590431b +content-length: 36 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +805a958e-9906-4e7a-8fe0-cbe83590431b +``` +```` From f3d162a588b8332fff3a47bbd98d04e914228655 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:50 +0200 Subject: [PATCH 037/698] New translations listeners.md (Japanese) --- guide/content/ja/guide/basics/listeners.md | 330 +++++++++++++++++++++ 1 file changed, 330 insertions(+) create mode 100644 guide/content/ja/guide/basics/listeners.md diff --git a/guide/content/ja/guide/basics/listeners.md b/guide/content/ja/guide/basics/listeners.md new file mode 100644 index 0000000000..33a20b379a --- /dev/null +++ b/guide/content/ja/guide/basics/listeners.md @@ -0,0 +1,330 @@ +# Listeners + +Sanic provides you with eight (8) opportunities to inject an operation into the life cycle of your application server. This does not include the [signals](../advanced/signals.md), which allow further injection customization. + +There are two (2) that run **only** on your main Sanic process (ie, once per call to `sanic server.app`.) + +- `main_process_start` +- `main_process_stop` + +There are also two (2) that run **only** in a reloader process if auto-reload has been turned on. + +- `reload_process_start` +- `reload_process_stop` + +_Added `reload_process_start` and `reload_process_stop` in v22.3_ + +There are four (4) that enable you to execute startup/teardown code as your server starts or closes. + +- `before_server_start` +- `after_server_start` +- `before_server_stop` +- `after_server_stop` + +The life cycle of a worker process looks like this: + +.. mermaid:: + +``` +sequenceDiagram +autonumber +participant Process +participant Worker +participant Listener +participant Handler +Note over Process: sanic server.app +loop + Process->>Listener: @app.main_process_start + Listener->>Handler: Invoke event handler +end +Process->>Worker: Run workers +loop Start each worker + loop + Worker->>Listener: @app.before_server_start + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: started + loop + Worker->>Listener: @app.after_server_start + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: ready +end +Process->>Worker: Graceful shutdown +loop Stop each worker + loop + Worker->>Listener: @app.before_server_stop + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: stopped + loop + Worker->>Listener: @app.after_server_stop + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: closed +end +loop + Process->>Listener: @app.main_process_stop + Listener->>Handler: Invoke event handler +end +Note over Process: exit +``` + +The reloader process live outside of this worker process inside of a process that is responsible for starting and stopping the Sanic processes. Consider the following example: + +```python +@app.reload_process_start +async def reload_start(*_): + print(">>>>>> reload_start <<<<<<") + +@app.main_process_start +async def main_start(*_): + print(">>>>>> main_start <<<<<<") + +@app.before_server_start +async def before_start(*_): + print(">>>>>> before_start <<<<<<") +``` + +If this application were run with auto-reload turned on, the `reload_start` function would be called once when the reloader process starts. The `main_start` function would also be called once when the main process starts. **HOWEVER**, the `before_start` function would be called once for each worker process that is started, and subsequently every time that a file is saved and the worker is restarted. + +## Attaching a listener + +.. column:: + +``` +The process to setup a function as a listener is similar to declaring a route. + +The currently running `Sanic()` instance is injected into the listener. +``` + +.. column:: + +```` +```python +async def setup_db(app): + app.ctx.db = await db_setup() + +app.register_listener(setup_db, "before_server_start") +``` +```` + +.. column:: + +``` +The `Sanic` app instance also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def setup_db(app): + app.ctx.db = await db_setup() +``` +```` + +.. column:: + +``` +Prior to v22.3, both the application instance and the current event loop were injected into the function. However, only the application instance is injected by default. If your function signature will accept both, then both the application and the loop will be injected as shown here. +``` + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def setup_db(app, loop): + app.ctx.db = await db_setup() +``` +```` + +.. column:: + +``` +You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. +``` + +.. column:: + +```` +```python +@app.before_server_start +async def setup_db(app): + app.ctx.db = await db_setup() +``` +```` + +## Order of execution + +Listeners are executed in the order they are declared during startup, and reverse order of declaration during teardown + +| | Phase | Order | +| --------------------- | --------------- | ------------- | +| `main_process_start` | main startup | regular 🙂 ⬇️ | +| `before_server_start` | worker startup | regular 🙂 ⬇️ | +| `after_server_start` | worker startup | regular 🙂 ⬇️ | +| `before_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `after_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `main_process_stop` | main shutdown | 🙃 ⬆️ reverse | + +Given the following setup, we should expect to see this in the console if we run two workers. + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def listener_1(app, loop): + print("listener_1") + +@app.before_server_start +async def listener_2(app, loop): + print("listener_2") + +@app.listener("after_server_start") +async def listener_3(app, loop): + print("listener_3") + +@app.after_server_start +async def listener_4(app, loop): + print("listener_4") + +@app.listener("before_server_stop") +async def listener_5(app, loop): + print("listener_5") + +@app.before_server_stop +async def listener_6(app, loop): + print("listener_6") + +@app.listener("after_server_stop") +async def listener_7(app, loop): + print("listener_7") + +@app.after_server_stop +async def listener_8(app, loop): + print("listener_8") +``` +```` + +.. column:: + +```` +```bash +[pid: 1000000] [INFO] Goin' Fast @ http://127.0.0.1:9999 +[pid: 1000000] [INFO] listener_0 +[pid: 1111111] [INFO] listener_1 +[pid: 1111111] [INFO] listener_2 +[pid: 1111111] [INFO] listener_3 +[pid: 1111111] [INFO] listener_4 +[pid: 1111111] [INFO] Starting worker [1111111] +[pid: 1222222] [INFO] listener_1 +[pid: 1222222] [INFO] listener_2 +[pid: 1222222] [INFO] listener_3 +[pid: 1222222] [INFO] listener_4 +[pid: 1222222] [INFO] Starting worker [1222222] +[pid: 1111111] [INFO] Stopping worker [1111111] +[pid: 1222222] [INFO] Stopping worker [1222222] +[pid: 1222222] [INFO] listener_6 +[pid: 1222222] [INFO] listener_5 +[pid: 1222222] [INFO] listener_8 +[pid: 1222222] [INFO] listener_7 +[pid: 1111111] [INFO] listener_6 +[pid: 1111111] [INFO] listener_5 +[pid: 1111111] [INFO] listener_8 +[pid: 1111111] [INFO] listener_7 +[pid: 1000000] [INFO] listener_9 +[pid: 1000000] [INFO] Server Stopped +``` +In the above example, notice how there are three processes running: + +- `pid: 1000000` - The *main* process +- `pid: 1111111` - Worker 1 +- `pid: 1222222` - Worker 2 + +*Just because our example groups all of one worker and then all of another, in reality since these are running on separate processes, the ordering between processes is not guaranteed. But, you can be sure that a single worker will **always** maintain its order.* +```` + +.. tip:: FYI + +``` +The practical result of this is that if the first listener in `before_server_start` handler setups a database connection, listeners that are registered after it can rely upon that connection being alive both when they are started and stopped. +``` + +### Priority + +.. new:: v23.12 + +``` +In v23.12, the `priority` keyword argument was added to listeners. This allows for fine-tuning the order of execution of listeners. The default priority is `0`. Listeners with a higher priority will be executed first. Listeners with the same priority will be executed in the order they were registered. Furthermore, listeners attached to the `app` instance will be executed before listeners attached to a `Blueprint` instance. +``` + +Overall the rules for deciding the order of execution are as follows: + +1. Priority in descending order +2. Application listeners before Blueprint listeners +3. Registration order + +.. column:: + +```` +As an example, consider the following, which will print: + +```bash +third +bp_third +second +bp_second +first +fourth +bp_first +``` +```` + +.. column:: + +```` +```python +@app.before_server_start +async def first(app): + print("first") + +@app.listener("before_server_start", priority=2) +async def second(app): + print("second") + +@app.before_server_start(priority=3) +async def third(app): + print("third") + +@bp.before_server_start +async def bp_first(app): + print("bp_first") + +@bp.listener("before_server_start", priority=2) +async def bp_second(app): + print("bp_second") + +@bp.before_server_start(priority=3) +async def bp_third(app): + print("bp_third") + +@app.before_server_start +async def fourth(app): + print("fourth") + +app.blueprint(bp) +``` +```` + +## ASGI Mode + +If you are running your application with an ASGI server, then make note of the following changes: + +- `reload_process_start` and `reload_process_stop` will be **ignored** +- `main_process_start` and `main_process_stop` will be **ignored** +- `before_server_start` will run as early as it can, and will be before `after_server_start`, but technically, the server is already running at that point +- `after_server_stop` will run as late as it can, and will be after `before_server_stop`, but technically, the server is still running at that point From b91e2803d6e5dd425e7cce347ecf90426c09d4a6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:51 +0200 Subject: [PATCH 038/698] New translations listeners.md (Korean) --- guide/content/ko/guide/basics/listeners.md | 330 +++++++++++++++++++++ 1 file changed, 330 insertions(+) create mode 100644 guide/content/ko/guide/basics/listeners.md diff --git a/guide/content/ko/guide/basics/listeners.md b/guide/content/ko/guide/basics/listeners.md new file mode 100644 index 0000000000..33a20b379a --- /dev/null +++ b/guide/content/ko/guide/basics/listeners.md @@ -0,0 +1,330 @@ +# Listeners + +Sanic provides you with eight (8) opportunities to inject an operation into the life cycle of your application server. This does not include the [signals](../advanced/signals.md), which allow further injection customization. + +There are two (2) that run **only** on your main Sanic process (ie, once per call to `sanic server.app`.) + +- `main_process_start` +- `main_process_stop` + +There are also two (2) that run **only** in a reloader process if auto-reload has been turned on. + +- `reload_process_start` +- `reload_process_stop` + +_Added `reload_process_start` and `reload_process_stop` in v22.3_ + +There are four (4) that enable you to execute startup/teardown code as your server starts or closes. + +- `before_server_start` +- `after_server_start` +- `before_server_stop` +- `after_server_stop` + +The life cycle of a worker process looks like this: + +.. mermaid:: + +``` +sequenceDiagram +autonumber +participant Process +participant Worker +participant Listener +participant Handler +Note over Process: sanic server.app +loop + Process->>Listener: @app.main_process_start + Listener->>Handler: Invoke event handler +end +Process->>Worker: Run workers +loop Start each worker + loop + Worker->>Listener: @app.before_server_start + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: started + loop + Worker->>Listener: @app.after_server_start + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: ready +end +Process->>Worker: Graceful shutdown +loop Stop each worker + loop + Worker->>Listener: @app.before_server_stop + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: stopped + loop + Worker->>Listener: @app.after_server_stop + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: closed +end +loop + Process->>Listener: @app.main_process_stop + Listener->>Handler: Invoke event handler +end +Note over Process: exit +``` + +The reloader process live outside of this worker process inside of a process that is responsible for starting and stopping the Sanic processes. Consider the following example: + +```python +@app.reload_process_start +async def reload_start(*_): + print(">>>>>> reload_start <<<<<<") + +@app.main_process_start +async def main_start(*_): + print(">>>>>> main_start <<<<<<") + +@app.before_server_start +async def before_start(*_): + print(">>>>>> before_start <<<<<<") +``` + +If this application were run with auto-reload turned on, the `reload_start` function would be called once when the reloader process starts. The `main_start` function would also be called once when the main process starts. **HOWEVER**, the `before_start` function would be called once for each worker process that is started, and subsequently every time that a file is saved and the worker is restarted. + +## Attaching a listener + +.. column:: + +``` +The process to setup a function as a listener is similar to declaring a route. + +The currently running `Sanic()` instance is injected into the listener. +``` + +.. column:: + +```` +```python +async def setup_db(app): + app.ctx.db = await db_setup() + +app.register_listener(setup_db, "before_server_start") +``` +```` + +.. column:: + +``` +The `Sanic` app instance also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def setup_db(app): + app.ctx.db = await db_setup() +``` +```` + +.. column:: + +``` +Prior to v22.3, both the application instance and the current event loop were injected into the function. However, only the application instance is injected by default. If your function signature will accept both, then both the application and the loop will be injected as shown here. +``` + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def setup_db(app, loop): + app.ctx.db = await db_setup() +``` +```` + +.. column:: + +``` +You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. +``` + +.. column:: + +```` +```python +@app.before_server_start +async def setup_db(app): + app.ctx.db = await db_setup() +``` +```` + +## Order of execution + +Listeners are executed in the order they are declared during startup, and reverse order of declaration during teardown + +| | Phase | Order | +| --------------------- | --------------- | ------------- | +| `main_process_start` | main startup | regular 🙂 ⬇️ | +| `before_server_start` | worker startup | regular 🙂 ⬇️ | +| `after_server_start` | worker startup | regular 🙂 ⬇️ | +| `before_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `after_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `main_process_stop` | main shutdown | 🙃 ⬆️ reverse | + +Given the following setup, we should expect to see this in the console if we run two workers. + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def listener_1(app, loop): + print("listener_1") + +@app.before_server_start +async def listener_2(app, loop): + print("listener_2") + +@app.listener("after_server_start") +async def listener_3(app, loop): + print("listener_3") + +@app.after_server_start +async def listener_4(app, loop): + print("listener_4") + +@app.listener("before_server_stop") +async def listener_5(app, loop): + print("listener_5") + +@app.before_server_stop +async def listener_6(app, loop): + print("listener_6") + +@app.listener("after_server_stop") +async def listener_7(app, loop): + print("listener_7") + +@app.after_server_stop +async def listener_8(app, loop): + print("listener_8") +``` +```` + +.. column:: + +```` +```bash +[pid: 1000000] [INFO] Goin' Fast @ http://127.0.0.1:9999 +[pid: 1000000] [INFO] listener_0 +[pid: 1111111] [INFO] listener_1 +[pid: 1111111] [INFO] listener_2 +[pid: 1111111] [INFO] listener_3 +[pid: 1111111] [INFO] listener_4 +[pid: 1111111] [INFO] Starting worker [1111111] +[pid: 1222222] [INFO] listener_1 +[pid: 1222222] [INFO] listener_2 +[pid: 1222222] [INFO] listener_3 +[pid: 1222222] [INFO] listener_4 +[pid: 1222222] [INFO] Starting worker [1222222] +[pid: 1111111] [INFO] Stopping worker [1111111] +[pid: 1222222] [INFO] Stopping worker [1222222] +[pid: 1222222] [INFO] listener_6 +[pid: 1222222] [INFO] listener_5 +[pid: 1222222] [INFO] listener_8 +[pid: 1222222] [INFO] listener_7 +[pid: 1111111] [INFO] listener_6 +[pid: 1111111] [INFO] listener_5 +[pid: 1111111] [INFO] listener_8 +[pid: 1111111] [INFO] listener_7 +[pid: 1000000] [INFO] listener_9 +[pid: 1000000] [INFO] Server Stopped +``` +In the above example, notice how there are three processes running: + +- `pid: 1000000` - The *main* process +- `pid: 1111111` - Worker 1 +- `pid: 1222222` - Worker 2 + +*Just because our example groups all of one worker and then all of another, in reality since these are running on separate processes, the ordering between processes is not guaranteed. But, you can be sure that a single worker will **always** maintain its order.* +```` + +.. tip:: FYI + +``` +The practical result of this is that if the first listener in `before_server_start` handler setups a database connection, listeners that are registered after it can rely upon that connection being alive both when they are started and stopped. +``` + +### Priority + +.. new:: v23.12 + +``` +In v23.12, the `priority` keyword argument was added to listeners. This allows for fine-tuning the order of execution of listeners. The default priority is `0`. Listeners with a higher priority will be executed first. Listeners with the same priority will be executed in the order they were registered. Furthermore, listeners attached to the `app` instance will be executed before listeners attached to a `Blueprint` instance. +``` + +Overall the rules for deciding the order of execution are as follows: + +1. Priority in descending order +2. Application listeners before Blueprint listeners +3. Registration order + +.. column:: + +```` +As an example, consider the following, which will print: + +```bash +third +bp_third +second +bp_second +first +fourth +bp_first +``` +```` + +.. column:: + +```` +```python +@app.before_server_start +async def first(app): + print("first") + +@app.listener("before_server_start", priority=2) +async def second(app): + print("second") + +@app.before_server_start(priority=3) +async def third(app): + print("third") + +@bp.before_server_start +async def bp_first(app): + print("bp_first") + +@bp.listener("before_server_start", priority=2) +async def bp_second(app): + print("bp_second") + +@bp.before_server_start(priority=3) +async def bp_third(app): + print("bp_third") + +@app.before_server_start +async def fourth(app): + print("fourth") + +app.blueprint(bp) +``` +```` + +## ASGI Mode + +If you are running your application with an ASGI server, then make note of the following changes: + +- `reload_process_start` and `reload_process_stop` will be **ignored** +- `main_process_start` and `main_process_stop` will be **ignored** +- `before_server_start` will run as early as it can, and will be before `after_server_start`, but technically, the server is already running at that point +- `after_server_stop` will run as late as it can, and will be after `before_server_stop`, but technically, the server is still running at that point From 7bbe89dde9ef80530244f50fa2a0e65862504348 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:52 +0200 Subject: [PATCH 039/698] New translations listeners.md (Chinese Simplified) --- guide/content/zh/guide/basics/listeners.md | 330 +++++++++++++++++++++ 1 file changed, 330 insertions(+) create mode 100644 guide/content/zh/guide/basics/listeners.md diff --git a/guide/content/zh/guide/basics/listeners.md b/guide/content/zh/guide/basics/listeners.md new file mode 100644 index 0000000000..33a20b379a --- /dev/null +++ b/guide/content/zh/guide/basics/listeners.md @@ -0,0 +1,330 @@ +# Listeners + +Sanic provides you with eight (8) opportunities to inject an operation into the life cycle of your application server. This does not include the [signals](../advanced/signals.md), which allow further injection customization. + +There are two (2) that run **only** on your main Sanic process (ie, once per call to `sanic server.app`.) + +- `main_process_start` +- `main_process_stop` + +There are also two (2) that run **only** in a reloader process if auto-reload has been turned on. + +- `reload_process_start` +- `reload_process_stop` + +_Added `reload_process_start` and `reload_process_stop` in v22.3_ + +There are four (4) that enable you to execute startup/teardown code as your server starts or closes. + +- `before_server_start` +- `after_server_start` +- `before_server_stop` +- `after_server_stop` + +The life cycle of a worker process looks like this: + +.. mermaid:: + +``` +sequenceDiagram +autonumber +participant Process +participant Worker +participant Listener +participant Handler +Note over Process: sanic server.app +loop + Process->>Listener: @app.main_process_start + Listener->>Handler: Invoke event handler +end +Process->>Worker: Run workers +loop Start each worker + loop + Worker->>Listener: @app.before_server_start + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: started + loop + Worker->>Listener: @app.after_server_start + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: ready +end +Process->>Worker: Graceful shutdown +loop Stop each worker + loop + Worker->>Listener: @app.before_server_stop + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: stopped + loop + Worker->>Listener: @app.after_server_stop + Listener->>Handler: Invoke event handler + end + Note over Worker: Server status: closed +end +loop + Process->>Listener: @app.main_process_stop + Listener->>Handler: Invoke event handler +end +Note over Process: exit +``` + +The reloader process live outside of this worker process inside of a process that is responsible for starting and stopping the Sanic processes. Consider the following example: + +```python +@app.reload_process_start +async def reload_start(*_): + print(">>>>>> reload_start <<<<<<") + +@app.main_process_start +async def main_start(*_): + print(">>>>>> main_start <<<<<<") + +@app.before_server_start +async def before_start(*_): + print(">>>>>> before_start <<<<<<") +``` + +If this application were run with auto-reload turned on, the `reload_start` function would be called once when the reloader process starts. The `main_start` function would also be called once when the main process starts. **HOWEVER**, the `before_start` function would be called once for each worker process that is started, and subsequently every time that a file is saved and the worker is restarted. + +## Attaching a listener + +.. column:: + +``` +The process to setup a function as a listener is similar to declaring a route. + +The currently running `Sanic()` instance is injected into the listener. +``` + +.. column:: + +```` +```python +async def setup_db(app): + app.ctx.db = await db_setup() + +app.register_listener(setup_db, "before_server_start") +``` +```` + +.. column:: + +``` +The `Sanic` app instance also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def setup_db(app): + app.ctx.db = await db_setup() +``` +```` + +.. column:: + +``` +Prior to v22.3, both the application instance and the current event loop were injected into the function. However, only the application instance is injected by default. If your function signature will accept both, then both the application and the loop will be injected as shown here. +``` + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def setup_db(app, loop): + app.ctx.db = await db_setup() +``` +```` + +.. column:: + +``` +You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. +``` + +.. column:: + +```` +```python +@app.before_server_start +async def setup_db(app): + app.ctx.db = await db_setup() +``` +```` + +## Order of execution + +Listeners are executed in the order they are declared during startup, and reverse order of declaration during teardown + +| | Phase | Order | +| --------------------- | --------------- | ------------- | +| `main_process_start` | main startup | regular 🙂 ⬇️ | +| `before_server_start` | worker startup | regular 🙂 ⬇️ | +| `after_server_start` | worker startup | regular 🙂 ⬇️ | +| `before_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `after_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `main_process_stop` | main shutdown | 🙃 ⬆️ reverse | + +Given the following setup, we should expect to see this in the console if we run two workers. + +.. column:: + +```` +```python +@app.listener("before_server_start") +async def listener_1(app, loop): + print("listener_1") + +@app.before_server_start +async def listener_2(app, loop): + print("listener_2") + +@app.listener("after_server_start") +async def listener_3(app, loop): + print("listener_3") + +@app.after_server_start +async def listener_4(app, loop): + print("listener_4") + +@app.listener("before_server_stop") +async def listener_5(app, loop): + print("listener_5") + +@app.before_server_stop +async def listener_6(app, loop): + print("listener_6") + +@app.listener("after_server_stop") +async def listener_7(app, loop): + print("listener_7") + +@app.after_server_stop +async def listener_8(app, loop): + print("listener_8") +``` +```` + +.. column:: + +```` +```bash +[pid: 1000000] [INFO] Goin' Fast @ http://127.0.0.1:9999 +[pid: 1000000] [INFO] listener_0 +[pid: 1111111] [INFO] listener_1 +[pid: 1111111] [INFO] listener_2 +[pid: 1111111] [INFO] listener_3 +[pid: 1111111] [INFO] listener_4 +[pid: 1111111] [INFO] Starting worker [1111111] +[pid: 1222222] [INFO] listener_1 +[pid: 1222222] [INFO] listener_2 +[pid: 1222222] [INFO] listener_3 +[pid: 1222222] [INFO] listener_4 +[pid: 1222222] [INFO] Starting worker [1222222] +[pid: 1111111] [INFO] Stopping worker [1111111] +[pid: 1222222] [INFO] Stopping worker [1222222] +[pid: 1222222] [INFO] listener_6 +[pid: 1222222] [INFO] listener_5 +[pid: 1222222] [INFO] listener_8 +[pid: 1222222] [INFO] listener_7 +[pid: 1111111] [INFO] listener_6 +[pid: 1111111] [INFO] listener_5 +[pid: 1111111] [INFO] listener_8 +[pid: 1111111] [INFO] listener_7 +[pid: 1000000] [INFO] listener_9 +[pid: 1000000] [INFO] Server Stopped +``` +In the above example, notice how there are three processes running: + +- `pid: 1000000` - The *main* process +- `pid: 1111111` - Worker 1 +- `pid: 1222222` - Worker 2 + +*Just because our example groups all of one worker and then all of another, in reality since these are running on separate processes, the ordering between processes is not guaranteed. But, you can be sure that a single worker will **always** maintain its order.* +```` + +.. tip:: FYI + +``` +The practical result of this is that if the first listener in `before_server_start` handler setups a database connection, listeners that are registered after it can rely upon that connection being alive both when they are started and stopped. +``` + +### Priority + +.. new:: v23.12 + +``` +In v23.12, the `priority` keyword argument was added to listeners. This allows for fine-tuning the order of execution of listeners. The default priority is `0`. Listeners with a higher priority will be executed first. Listeners with the same priority will be executed in the order they were registered. Furthermore, listeners attached to the `app` instance will be executed before listeners attached to a `Blueprint` instance. +``` + +Overall the rules for deciding the order of execution are as follows: + +1. Priority in descending order +2. Application listeners before Blueprint listeners +3. Registration order + +.. column:: + +```` +As an example, consider the following, which will print: + +```bash +third +bp_third +second +bp_second +first +fourth +bp_first +``` +```` + +.. column:: + +```` +```python +@app.before_server_start +async def first(app): + print("first") + +@app.listener("before_server_start", priority=2) +async def second(app): + print("second") + +@app.before_server_start(priority=3) +async def third(app): + print("third") + +@bp.before_server_start +async def bp_first(app): + print("bp_first") + +@bp.listener("before_server_start", priority=2) +async def bp_second(app): + print("bp_second") + +@bp.before_server_start(priority=3) +async def bp_third(app): + print("bp_third") + +@app.before_server_start +async def fourth(app): + print("fourth") + +app.blueprint(bp) +``` +```` + +## ASGI Mode + +If you are running your application with an ASGI server, then make note of the following changes: + +- `reload_process_start` and `reload_process_stop` will be **ignored** +- `main_process_start` and `main_process_stop` will be **ignored** +- `before_server_start` will run as early as it can, and will be before `after_server_start`, but technically, the server is already running at that point +- `after_server_stop` will run as late as it can, and will be after `before_server_stop`, but technically, the server is still running at that point From 9bc9ed23b3e6c8c52ac71a3458da054593a91abc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:53 +0200 Subject: [PATCH 040/698] New translations middleware.md (Japanese) --- guide/content/ja/guide/basics/middleware.md | 279 ++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 guide/content/ja/guide/basics/middleware.md diff --git a/guide/content/ja/guide/basics/middleware.md b/guide/content/ja/guide/basics/middleware.md new file mode 100644 index 0000000000..7352f175ca --- /dev/null +++ b/guide/content/ja/guide/basics/middleware.md @@ -0,0 +1,279 @@ +# Middleware + +Whereas listeners allow you to attach functionality to the lifecycle of a worker process, middleware allows you to attach functionality to the lifecycle of an HTTP stream. + +```python +@app.on_request +async def example(request): + print("I execute before the handler.") +``` + +You can execute middleware either _before_ the handler is executed, or _after_. + +```python +@app.on_response +async def example(request, response): + print("I execute after the handler.") +``` + +.. mermaid:: + +``` +sequenceDiagram +autonumber +participant Worker +participant Middleware +participant MiddlewareHandler +participant RouteHandler +Note over Worker: Incoming HTTP request +loop + Worker->>Middleware: @app.on_request + Middleware->>MiddlewareHandler: Invoke middleware handler + MiddlewareHandler-->>Worker: Return response (optional) +end +rect rgba(255, 13, 104, .1) +Worker->>RouteHandler: Invoke route handler +RouteHandler->>Worker: Return response +end +loop + Worker->>Middleware: @app.on_response + Middleware->>MiddlewareHandler: Invoke middleware handler + MiddlewareHandler-->>Worker: Return response (optional) +end +Note over Worker: Deliver response +``` + +## Attaching middleware + +.. column:: + +``` +This should probably look familiar by now. All you need to do is declare when you would like the middleware to execute: on the `request` or on the `response`. +``` + +.. column:: + +```` +```python +async def extract_user(request): + request.ctx.user = await extract_user_from_request(request) + +app.register_middleware(extract_user, "request") +``` +```` + +.. column:: + +``` +Again, the `Sanic` app instance also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.middleware("request") +async def extract_user(request): + request.ctx.user = await extract_user_from_request(request) +``` +```` + +.. column:: + +``` +Response middleware receives both the `request` and `response` arguments. +``` + +.. column:: + +```` +```python +@app.middleware('response') +async def prevent_xss(request, response): + response.headers["x-xss-protection"] = "1; mode=block" +``` +```` + +.. column:: + +``` +You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. + +This is the preferred usage, and is what we will use going forward. +``` + +.. column:: + +```` +```python +@app.on_request +async def extract_user(request): + ... + +@app.on_response +async def prevent_xss(request, response): + ... +``` +```` + +## Modification + +Middleware can modify the request or response parameter it is given, _as long as it does not return it_. + +.. column:: + +``` +#### Order of execution + +1. Request middleware: `add_key` +2. Route handler: `index` +3. Response middleware: `prevent_xss` +4. Response middleware: `custom_banner` +``` + +.. column:: + +```` +```python +@app.on_request +async def add_key(request): + # Arbitrary data may be stored in request context: + request.ctx.foo = "bar" + +@app.on_response +async def custom_banner(request, response): + response.headers["Server"] = "Fake-Server" + +@app.on_response +async def prevent_xss(request, response): + response.headers["x-xss-protection"] = "1; mode=block" + +@app.get("/") +async def index(request): + return text(request.ctx.foo) + +``` +```` + +.. column:: + +``` +You can modify the `request.match_info`. A useful feature that could be used, for example, in middleware to convert `a-slug` to `a_slug`. +``` + +.. column:: + +```` +```python +@app.on_request +def convert_slug_to_underscore(request: Request): + request.match_info["slug"] = request.match_info["slug"].replace("-", "_") + +@app.get("/") +async def handler(request, slug): + return text(slug) +``` +``` +$ curl localhost:9999/foo-bar-baz +foo_bar_baz +``` +```` + +## Responding early + +.. column:: + +``` +If middleware returns a `HTTPResponse` object, the request will stop processing and the response will be returned. If this occurs to a request before the route handler is reached, the handler will **not** be called. Returning a response will also prevent any further middleware from running. + +``` + +.. tip:: + +``` +You can return a `None` value to stop the execution of the middleware handler to allow the request to process as normal. This can be useful when using early return to avoid processing requests inside of that middleware handler. +``` + +.. column:: + +```` +```python +@app.on_request +async def halt_request(request): + return text("I halted the request") + +@app.on_response +async def halt_response(request, response): + return text("I halted the response") +``` +```` + +## Order of execution + +Request middleware is executed in the order declared. Response middleware is executed in **reverse order**. + +Given the following setup, we should expect to see this in the console. + +.. column:: + +```` +```python +@app.on_request +async def middleware_1(request): + print("middleware_1") + +@app.on_request +async def middleware_2(request): + print("middleware_2") + +@app.on_response +async def middleware_3(request, response): + print("middleware_3") + +@app.on_response +async def middleware_4(request, response): + print("middleware_4") + +@app.get("/handler") +async def handler(request): + print("~ handler ~") + return text("Done.") +``` +```` + +.. column:: + +```` +```bash +middleware_1 +middleware_2 +~ handler ~ +middleware_4 +middleware_3 +[INFO][127.0.0.1:44788]: GET http://localhost:8000/handler 200 5 +``` +```` + +### Middleware priority + +.. column:: + +``` +You can modify the order of execution of middleware by assigning it a higher priority. This happens inside of the middleware definition. The higher the value, the earlier it will execute relative to other middleware. The default priority for middleware is `0`. +``` + +.. column:: + +```` +```python +@app.on_request +async def low_priority(request): + ... + +@app.on_request(priority=99) +async def high_priority(request): + ... +``` +```` + +_Added in v22.9_ From c0ce36c81e1e3d9fbeb7c6ff2b9638794698a1ea Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:54 +0200 Subject: [PATCH 041/698] New translations middleware.md (Korean) --- guide/content/ko/guide/basics/middleware.md | 279 ++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 guide/content/ko/guide/basics/middleware.md diff --git a/guide/content/ko/guide/basics/middleware.md b/guide/content/ko/guide/basics/middleware.md new file mode 100644 index 0000000000..7352f175ca --- /dev/null +++ b/guide/content/ko/guide/basics/middleware.md @@ -0,0 +1,279 @@ +# Middleware + +Whereas listeners allow you to attach functionality to the lifecycle of a worker process, middleware allows you to attach functionality to the lifecycle of an HTTP stream. + +```python +@app.on_request +async def example(request): + print("I execute before the handler.") +``` + +You can execute middleware either _before_ the handler is executed, or _after_. + +```python +@app.on_response +async def example(request, response): + print("I execute after the handler.") +``` + +.. mermaid:: + +``` +sequenceDiagram +autonumber +participant Worker +participant Middleware +participant MiddlewareHandler +participant RouteHandler +Note over Worker: Incoming HTTP request +loop + Worker->>Middleware: @app.on_request + Middleware->>MiddlewareHandler: Invoke middleware handler + MiddlewareHandler-->>Worker: Return response (optional) +end +rect rgba(255, 13, 104, .1) +Worker->>RouteHandler: Invoke route handler +RouteHandler->>Worker: Return response +end +loop + Worker->>Middleware: @app.on_response + Middleware->>MiddlewareHandler: Invoke middleware handler + MiddlewareHandler-->>Worker: Return response (optional) +end +Note over Worker: Deliver response +``` + +## Attaching middleware + +.. column:: + +``` +This should probably look familiar by now. All you need to do is declare when you would like the middleware to execute: on the `request` or on the `response`. +``` + +.. column:: + +```` +```python +async def extract_user(request): + request.ctx.user = await extract_user_from_request(request) + +app.register_middleware(extract_user, "request") +``` +```` + +.. column:: + +``` +Again, the `Sanic` app instance also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.middleware("request") +async def extract_user(request): + request.ctx.user = await extract_user_from_request(request) +``` +```` + +.. column:: + +``` +Response middleware receives both the `request` and `response` arguments. +``` + +.. column:: + +```` +```python +@app.middleware('response') +async def prevent_xss(request, response): + response.headers["x-xss-protection"] = "1; mode=block" +``` +```` + +.. column:: + +``` +You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. + +This is the preferred usage, and is what we will use going forward. +``` + +.. column:: + +```` +```python +@app.on_request +async def extract_user(request): + ... + +@app.on_response +async def prevent_xss(request, response): + ... +``` +```` + +## Modification + +Middleware can modify the request or response parameter it is given, _as long as it does not return it_. + +.. column:: + +``` +#### Order of execution + +1. Request middleware: `add_key` +2. Route handler: `index` +3. Response middleware: `prevent_xss` +4. Response middleware: `custom_banner` +``` + +.. column:: + +```` +```python +@app.on_request +async def add_key(request): + # Arbitrary data may be stored in request context: + request.ctx.foo = "bar" + +@app.on_response +async def custom_banner(request, response): + response.headers["Server"] = "Fake-Server" + +@app.on_response +async def prevent_xss(request, response): + response.headers["x-xss-protection"] = "1; mode=block" + +@app.get("/") +async def index(request): + return text(request.ctx.foo) + +``` +```` + +.. column:: + +``` +You can modify the `request.match_info`. A useful feature that could be used, for example, in middleware to convert `a-slug` to `a_slug`. +``` + +.. column:: + +```` +```python +@app.on_request +def convert_slug_to_underscore(request: Request): + request.match_info["slug"] = request.match_info["slug"].replace("-", "_") + +@app.get("/") +async def handler(request, slug): + return text(slug) +``` +``` +$ curl localhost:9999/foo-bar-baz +foo_bar_baz +``` +```` + +## Responding early + +.. column:: + +``` +If middleware returns a `HTTPResponse` object, the request will stop processing and the response will be returned. If this occurs to a request before the route handler is reached, the handler will **not** be called. Returning a response will also prevent any further middleware from running. + +``` + +.. tip:: + +``` +You can return a `None` value to stop the execution of the middleware handler to allow the request to process as normal. This can be useful when using early return to avoid processing requests inside of that middleware handler. +``` + +.. column:: + +```` +```python +@app.on_request +async def halt_request(request): + return text("I halted the request") + +@app.on_response +async def halt_response(request, response): + return text("I halted the response") +``` +```` + +## Order of execution + +Request middleware is executed in the order declared. Response middleware is executed in **reverse order**. + +Given the following setup, we should expect to see this in the console. + +.. column:: + +```` +```python +@app.on_request +async def middleware_1(request): + print("middleware_1") + +@app.on_request +async def middleware_2(request): + print("middleware_2") + +@app.on_response +async def middleware_3(request, response): + print("middleware_3") + +@app.on_response +async def middleware_4(request, response): + print("middleware_4") + +@app.get("/handler") +async def handler(request): + print("~ handler ~") + return text("Done.") +``` +```` + +.. column:: + +```` +```bash +middleware_1 +middleware_2 +~ handler ~ +middleware_4 +middleware_3 +[INFO][127.0.0.1:44788]: GET http://localhost:8000/handler 200 5 +``` +```` + +### Middleware priority + +.. column:: + +``` +You can modify the order of execution of middleware by assigning it a higher priority. This happens inside of the middleware definition. The higher the value, the earlier it will execute relative to other middleware. The default priority for middleware is `0`. +``` + +.. column:: + +```` +```python +@app.on_request +async def low_priority(request): + ... + +@app.on_request(priority=99) +async def high_priority(request): + ... +``` +```` + +_Added in v22.9_ From dfa015bf5a02e739e2158e3e8c9ef48a32170009 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:55 +0200 Subject: [PATCH 042/698] New translations middleware.md (Chinese Simplified) --- guide/content/zh/guide/basics/middleware.md | 279 ++++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 guide/content/zh/guide/basics/middleware.md diff --git a/guide/content/zh/guide/basics/middleware.md b/guide/content/zh/guide/basics/middleware.md new file mode 100644 index 0000000000..7352f175ca --- /dev/null +++ b/guide/content/zh/guide/basics/middleware.md @@ -0,0 +1,279 @@ +# Middleware + +Whereas listeners allow you to attach functionality to the lifecycle of a worker process, middleware allows you to attach functionality to the lifecycle of an HTTP stream. + +```python +@app.on_request +async def example(request): + print("I execute before the handler.") +``` + +You can execute middleware either _before_ the handler is executed, or _after_. + +```python +@app.on_response +async def example(request, response): + print("I execute after the handler.") +``` + +.. mermaid:: + +``` +sequenceDiagram +autonumber +participant Worker +participant Middleware +participant MiddlewareHandler +participant RouteHandler +Note over Worker: Incoming HTTP request +loop + Worker->>Middleware: @app.on_request + Middleware->>MiddlewareHandler: Invoke middleware handler + MiddlewareHandler-->>Worker: Return response (optional) +end +rect rgba(255, 13, 104, .1) +Worker->>RouteHandler: Invoke route handler +RouteHandler->>Worker: Return response +end +loop + Worker->>Middleware: @app.on_response + Middleware->>MiddlewareHandler: Invoke middleware handler + MiddlewareHandler-->>Worker: Return response (optional) +end +Note over Worker: Deliver response +``` + +## Attaching middleware + +.. column:: + +``` +This should probably look familiar by now. All you need to do is declare when you would like the middleware to execute: on the `request` or on the `response`. +``` + +.. column:: + +```` +```python +async def extract_user(request): + request.ctx.user = await extract_user_from_request(request) + +app.register_middleware(extract_user, "request") +``` +```` + +.. column:: + +``` +Again, the `Sanic` app instance also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.middleware("request") +async def extract_user(request): + request.ctx.user = await extract_user_from_request(request) +``` +```` + +.. column:: + +``` +Response middleware receives both the `request` and `response` arguments. +``` + +.. column:: + +```` +```python +@app.middleware('response') +async def prevent_xss(request, response): + response.headers["x-xss-protection"] = "1; mode=block" +``` +```` + +.. column:: + +``` +You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. + +This is the preferred usage, and is what we will use going forward. +``` + +.. column:: + +```` +```python +@app.on_request +async def extract_user(request): + ... + +@app.on_response +async def prevent_xss(request, response): + ... +``` +```` + +## Modification + +Middleware can modify the request or response parameter it is given, _as long as it does not return it_. + +.. column:: + +``` +#### Order of execution + +1. Request middleware: `add_key` +2. Route handler: `index` +3. Response middleware: `prevent_xss` +4. Response middleware: `custom_banner` +``` + +.. column:: + +```` +```python +@app.on_request +async def add_key(request): + # Arbitrary data may be stored in request context: + request.ctx.foo = "bar" + +@app.on_response +async def custom_banner(request, response): + response.headers["Server"] = "Fake-Server" + +@app.on_response +async def prevent_xss(request, response): + response.headers["x-xss-protection"] = "1; mode=block" + +@app.get("/") +async def index(request): + return text(request.ctx.foo) + +``` +```` + +.. column:: + +``` +You can modify the `request.match_info`. A useful feature that could be used, for example, in middleware to convert `a-slug` to `a_slug`. +``` + +.. column:: + +```` +```python +@app.on_request +def convert_slug_to_underscore(request: Request): + request.match_info["slug"] = request.match_info["slug"].replace("-", "_") + +@app.get("/") +async def handler(request, slug): + return text(slug) +``` +``` +$ curl localhost:9999/foo-bar-baz +foo_bar_baz +``` +```` + +## Responding early + +.. column:: + +``` +If middleware returns a `HTTPResponse` object, the request will stop processing and the response will be returned. If this occurs to a request before the route handler is reached, the handler will **not** be called. Returning a response will also prevent any further middleware from running. + +``` + +.. tip:: + +``` +You can return a `None` value to stop the execution of the middleware handler to allow the request to process as normal. This can be useful when using early return to avoid processing requests inside of that middleware handler. +``` + +.. column:: + +```` +```python +@app.on_request +async def halt_request(request): + return text("I halted the request") + +@app.on_response +async def halt_response(request, response): + return text("I halted the response") +``` +```` + +## Order of execution + +Request middleware is executed in the order declared. Response middleware is executed in **reverse order**. + +Given the following setup, we should expect to see this in the console. + +.. column:: + +```` +```python +@app.on_request +async def middleware_1(request): + print("middleware_1") + +@app.on_request +async def middleware_2(request): + print("middleware_2") + +@app.on_response +async def middleware_3(request, response): + print("middleware_3") + +@app.on_response +async def middleware_4(request, response): + print("middleware_4") + +@app.get("/handler") +async def handler(request): + print("~ handler ~") + return text("Done.") +``` +```` + +.. column:: + +```` +```bash +middleware_1 +middleware_2 +~ handler ~ +middleware_4 +middleware_3 +[INFO][127.0.0.1:44788]: GET http://localhost:8000/handler 200 5 +``` +```` + +### Middleware priority + +.. column:: + +``` +You can modify the order of execution of middleware by assigning it a higher priority. This happens inside of the middleware definition. The higher the value, the earlier it will execute relative to other middleware. The default priority for middleware is `0`. +``` + +.. column:: + +```` +```python +@app.on_request +async def low_priority(request): + ... + +@app.on_request(priority=99) +async def high_priority(request): + ... +``` +```` + +_Added in v22.9_ From 110db81f0ee2676ccbcbe154364bfa97ffcd2abf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:56 +0200 Subject: [PATCH 043/698] New translations request.md (Japanese) --- guide/content/ja/guide/basics/request.md | 478 +++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 guide/content/ja/guide/basics/request.md diff --git a/guide/content/ja/guide/basics/request.md b/guide/content/ja/guide/basics/request.md new file mode 100644 index 0000000000..c3dd8d08d9 --- /dev/null +++ b/guide/content/ja/guide/basics/request.md @@ -0,0 +1,478 @@ +# Request + +See API docs: [sanic.request](/api/sanic.request) + +The :class:`sanic.request.Request` instance contains **a lot** of helpful information available on its parameters. Refer to the [API documentation](https://sanic.readthedocs.io/) for full details. + +As we saw in the section on [handlers](./handlers), the first argument in a route handler is usually the :class:`sanic.request.Request` object. Because Sanic is an async framework, the handler will run inside of a [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) and will be scheduled by the event loop. This means that the handler will be executed in an isolated context and the request object will be unique to that handler's task. + +.. column:: + +``` +By convention, the argument is named `request`, but you can name it whatever you want. The name of the argument is not important. Both of the following handlers are valid. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def typical_use_case(request): + return text("I said foo!") +``` + +```python +@app.get("/foo") +async def atypical_use_case(req): + return text("I said foo!") +``` +```` + +.. column:: + +``` +Annotating a request object is super simple. + +``` + +.. column:: + +```` +```python +from sanic.request import Request +from sanic.response import text + +@app.get("/typed") +async def typed_handler(request: Request): + return text("Done.") +``` +```` + +.. tip:: + +``` +For your convenience, assuming you are using a modern IDE, you should leverage type annotations to help with code completion and documentation. This is especially helpful when using the `request` object as it has **MANY** properties and methods. + +To see the full list of available properties and methods, refer to the [API documentation](/api/sanic.request). +``` + +## Body + +The `Request` object allows you to access the content of the request body in a few different ways. + +### JSON + +.. column:: + +``` +**Parameter**: `request.json` +**Description**: The parsed JSON object +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d '{"foo": "bar"}' +``` + +```python +>>> print(request.json) +{'foo': 'bar'} +``` +```` + +### Raw + +.. column:: + +``` +**Parameter**: `request.body` +**Description**: The raw bytes from the request body +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d '{"foo": "bar"}' +``` + +```python +>>> print(request.body) +b'{"foo": "bar"}' +``` +```` + +### Form + +.. column:: + +``` +**Parameter**: `request.form` +**Description**: The form data + +.. tip:: FYI + + The `request.form` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + + Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d 'foo=bar' +``` + +```python +>>> print(request.body) +b'foo=bar' + +>>> print(request.form) +{'foo': ['bar']} + +>>> print(request.form.get("foo")) +bar + +>>> print(request.form.getlist("foo")) +['bar'] +``` +```` + +### Uploaded + +.. column:: + +``` +**Parameter**: `request.files` +**Description**: The files uploaded to the server + +.. tip:: FYI + + The `request.files` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + + Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +.. column:: + +```` +```bash +$ curl -F 'my_file=@/path/to/TEST' http://localhost:8000 +``` + +```python +>>> print(request.body) +b'--------------------------cb566ad845ad02d3\r\nContent-Disposition: form-data; name="my_file"; filename="TEST"\r\nContent-Type: application/octet-stream\r\n\r\nhello\n\r\n--------------------------cb566ad845ad02d3--\r\n' + +>>> print(request.files) +{'my_file': [File(type='application/octet-stream', body=b'hello\n', name='TEST')]} + +>>> print(request.files.get("my_file")) +File(type='application/octet-stream', body=b'hello\n', name='TEST') + +>>> print(request.files.getlist("my_file")) +[File(type='application/octet-stream', body=b'hello\n', name='TEST')] +``` +```` + +## Context + +### Request context + +The `request.ctx` object is your playground to store whatever information you need to about the request. This lives only for the duration of the request and is unique to the request. + +This can be constrasted with the `app.ctx` object which is shared across all requests. Be careful not to confuse them! + +The `request.ctx` object by default is a `SimpleNamespace` object allowing you to set arbitrary attributes on it. Sanic will not use this object for anything, so you are free to use it however you want without worrying about name clashes. + +````python + +### Typical use case + +This is often used to store items like authenticated user details. We will get more into [middleware](./middleware.md) later, but here is a simple example. + +```python +@app.on_request +async def run_before_handler(request): + request.ctx.user = await fetch_user_by_token(request.token) + +@app.route('/hi') +async def hi_my_name_is(request): + if not request.ctx.user: + return text("Hmm... I don't know you) + return text(f"Hi, my name is {request.ctx.user.name}") +```` + +As you can see, the `request.ctx` object is a great place to store information that you need to access in multiple handlers making your code more DRY and easier to maintain. But, as we will learn in the [middleware section](./middleware.md), you can also use it to store information from one middleware that will be used in another. + +### Connection context + +.. column:: + +``` +Often times your API will need to serve multiple concurrent (or consecutive) requests to the same client. This happens, for example, very often with progressive web apps that need to query multiple endpoints to get data. + +The HTTP protocol calls for an easing of overhead time caused by the connection with the use of [keep alive headers](../deployment/configuration.md#keep-alive-timeout). + +When multiple requests share a single connection, Sanic provides a context object to allow those requests to share state. +``` + +.. column:: + +```` +```python +@app.on_request +async def increment_foo(request): + if not hasattr(request.conn_info.ctx, "foo"): + request.conn_info.ctx.foo = 0 + request.conn_info.ctx.foo += 1 + +@app.get("/") +async def count_foo(request): + return text(f"request.conn_info.ctx.foo={request.conn_info.ctx.foo}") +``` + +```bash +$ curl localhost:8000 localhost:8000 localhost:8000 +request.conn_info.ctx.foo=1 +request.conn_info.ctx.foo=2 +request.conn_info.ctx.foo=3 +``` +```` + +.. warning:: + +``` +While this looks like a convenient place to store information between requests by a single HTTP connection, do not assume that all requests on a single connection came from a single end user. This is because HTTP proxies and load balancers can multiplex multiple connections into a single connection to your server. + +**DO NOT** use this to store information about a single user. Use the `request.ctx` object for that. +``` + +### Custom Request Objects + +As dicussed in [application customization](./app.md#custom-requests), you can create a subclass of :class:`sanic.request.Request` to add additional functionality to the request object. This is useful for adding additional attributes or methods that are specific to your application. + +.. column:: + +``` +For example, imagine your application sends a custom header that contains a user ID. You can create a custom request object that will parse that header and store the user ID for you. +``` + +.. column:: + +```` +```python +from sanic import Sanic, Request + +class CustomRequest(Request): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.user_id = self.headers.get("X-User-ID") + +app = Sanic("Example", request_class=CustomRequest) +``` +```` + +.. column:: + +``` +Now, in your handlers, you can access the `user_id` attribute. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request: CustomRequest): + return text(f"User ID: {request.user_id}") +``` +```` + +### Custom Request Context + +By default, the request context (`request.ctx`) is a [`Simplenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) object allowing you to set arbitrary attributes on it. While this is super helpful to reuse logic across your application, it can be difficult in the development experience since the IDE will not know what attributes are available. + +To help with this, you can create a custom request context object that will be used instead of the default `SimpleNamespace`. This allows you to add type hints to the context object and have them be available in your IDE. + +.. column:: + +``` +Start by subclassing the :class:`sanic.request.Request` class to create a custom request type. Then, you will need to add a `make_context()` method that returns an instance of your custom context object. *NOTE: the `make_context` method should be a static method.* +``` + +.. column:: + +```` +```python +from sanic import Sanic, Request +from types import SimpleNamespace + +class CustomRequest(Request): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.ctx.user_id = self.headers.get("X-User-ID") + + @staticmethod + def make_context() -> CustomContext: + return CustomContext() + +@dataclass +class CustomContext: + user_id: str = None +``` +```` + +.. note:: + +``` +This is a Sanic poweruser feature that makes it super convenient in large codebases to have typed request context objects. It is of course not required, but can be very helpful. +``` + +_Added in v23.6_ + +## Parameters + +.. column:: + +``` +Values that are extracted from the path parameters are injected into the handler as argumets, or more specifically as keyword arguments. There is much more detail about this in the [Routing section](./routing.md). +``` + +.. column:: + +```` +```python +@app.route('/tag/') +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) + +# or, explicitly as keyword arguments +@app.route('/tag/') +async def tag_handler(request, *, tag): + return text("Tag - {}".format(tag)) +``` +```` + +## Arguments + +There are two attributes on the `request` instance to get query parameters: + +- `request.args` +- `request.query_args` + +These allow you to access the query parameters from the request path (the part after the `?` in the URL). + +### Typical use case + +In most use cases, you will want to use the `request.args` object to access the query parameters. This will be the parsed query string as a dictionary. + +This is by far the most common pattern. + +.. column:: + +``` +Consider the example where we have a `/search` endpoint with a `q` parameter that we want to use to search for something. +``` + +.. column:: + +```` +```python +@app.get("/search") +async def search(request): + query = request.args.get("q") + if not query: + return text("No query string provided") + return text(f"Searching for: {query}") +``` +```` + +### Parsing the query string + +Sometimes, however, you may want to access the query string as a raw string or as a list of tuples. For this, you can use the `request.query_string` and `request.query_args` attributes. + +It also should be noted that HTTP allows multiple values for a single key. Although `request.args` may seem like a regular dictionary, it is actually a special type that allows for multiple values for a single key. You can access this by using the `request.args.getlist()` method. + +- `request.query_string` - The raw query string +- `request.query_args` - The parsed query string as a list of tuples +- `request.args` - The parsed query string as a _special_ dictionary + - `request.args.get()` - Get the first value for a key (behaves like a regular dictionary) + - `request.args.getlist()` - Get all values for a key + +```sh +curl "http://localhost:8000?key1=val1&key2=val2&key1=val3" +``` + +```python +>>> print(request.args) +{'key1': ['val1', 'val3'], 'key2': ['val2']} + +>>> print(request.args.get("key1")) +val1 + +>>> print(request.args.getlist("key1")) +['val1', 'val3'] + +>>> print(request.query_args) +[('key1', 'val1'), ('key2', 'val2'), ('key1', 'val3')] + +>>> print(request.query_string) +key1=val1&key2=val2&key1=val3 + +``` + +.. tip:: FYI + +``` +The `request.args` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +## Current request getter + +Sometimes you may find that you need access to the current request in your application in a location where it is not accessible. A typical example might be in a `logging` format. You can use `Request.get_current()` to fetch the current request (if any). + +Remember, the request object is confined to the single [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) that is running the handler. If you are not in that task, there is no request object. + +```python +import logging + +from sanic import Request, Sanic, json +from sanic.exceptions import SanicException +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_FORMAT = ( + "%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: " + "%(request_id)s %(request)s %(message)s %(status)d %(byte)d" +) + +old_factory = logging.getLogRecordFactory() + +def record_factory(*args, **kwargs): + record = old_factory(*args, **kwargs) + record.request_id = "" + + try: + request = Request.get_current() + except SanicException: + ... + else: + record.request_id = str(request.id) + + return record + +logging.setLogRecordFactory(record_factory) + + +LOGGING_CONFIG_DEFAULTS["formatters"]["access"]["format"] = LOGGING_FORMAT +app = Sanic("Example", log_config=LOGGING_CONFIG_DEFAULTS) +``` + +In this example, we are adding the `request.id` to every access log message. + +_Added in v22.6_ From 57ef97ea836d69de67c0aac5ea467d88686a9269 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:57 +0200 Subject: [PATCH 044/698] New translations request.md (Korean) --- guide/content/ko/guide/basics/request.md | 478 +++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 guide/content/ko/guide/basics/request.md diff --git a/guide/content/ko/guide/basics/request.md b/guide/content/ko/guide/basics/request.md new file mode 100644 index 0000000000..c3dd8d08d9 --- /dev/null +++ b/guide/content/ko/guide/basics/request.md @@ -0,0 +1,478 @@ +# Request + +See API docs: [sanic.request](/api/sanic.request) + +The :class:`sanic.request.Request` instance contains **a lot** of helpful information available on its parameters. Refer to the [API documentation](https://sanic.readthedocs.io/) for full details. + +As we saw in the section on [handlers](./handlers), the first argument in a route handler is usually the :class:`sanic.request.Request` object. Because Sanic is an async framework, the handler will run inside of a [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) and will be scheduled by the event loop. This means that the handler will be executed in an isolated context and the request object will be unique to that handler's task. + +.. column:: + +``` +By convention, the argument is named `request`, but you can name it whatever you want. The name of the argument is not important. Both of the following handlers are valid. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def typical_use_case(request): + return text("I said foo!") +``` + +```python +@app.get("/foo") +async def atypical_use_case(req): + return text("I said foo!") +``` +```` + +.. column:: + +``` +Annotating a request object is super simple. + +``` + +.. column:: + +```` +```python +from sanic.request import Request +from sanic.response import text + +@app.get("/typed") +async def typed_handler(request: Request): + return text("Done.") +``` +```` + +.. tip:: + +``` +For your convenience, assuming you are using a modern IDE, you should leverage type annotations to help with code completion and documentation. This is especially helpful when using the `request` object as it has **MANY** properties and methods. + +To see the full list of available properties and methods, refer to the [API documentation](/api/sanic.request). +``` + +## Body + +The `Request` object allows you to access the content of the request body in a few different ways. + +### JSON + +.. column:: + +``` +**Parameter**: `request.json` +**Description**: The parsed JSON object +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d '{"foo": "bar"}' +``` + +```python +>>> print(request.json) +{'foo': 'bar'} +``` +```` + +### Raw + +.. column:: + +``` +**Parameter**: `request.body` +**Description**: The raw bytes from the request body +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d '{"foo": "bar"}' +``` + +```python +>>> print(request.body) +b'{"foo": "bar"}' +``` +```` + +### Form + +.. column:: + +``` +**Parameter**: `request.form` +**Description**: The form data + +.. tip:: FYI + + The `request.form` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + + Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d 'foo=bar' +``` + +```python +>>> print(request.body) +b'foo=bar' + +>>> print(request.form) +{'foo': ['bar']} + +>>> print(request.form.get("foo")) +bar + +>>> print(request.form.getlist("foo")) +['bar'] +``` +```` + +### Uploaded + +.. column:: + +``` +**Parameter**: `request.files` +**Description**: The files uploaded to the server + +.. tip:: FYI + + The `request.files` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + + Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +.. column:: + +```` +```bash +$ curl -F 'my_file=@/path/to/TEST' http://localhost:8000 +``` + +```python +>>> print(request.body) +b'--------------------------cb566ad845ad02d3\r\nContent-Disposition: form-data; name="my_file"; filename="TEST"\r\nContent-Type: application/octet-stream\r\n\r\nhello\n\r\n--------------------------cb566ad845ad02d3--\r\n' + +>>> print(request.files) +{'my_file': [File(type='application/octet-stream', body=b'hello\n', name='TEST')]} + +>>> print(request.files.get("my_file")) +File(type='application/octet-stream', body=b'hello\n', name='TEST') + +>>> print(request.files.getlist("my_file")) +[File(type='application/octet-stream', body=b'hello\n', name='TEST')] +``` +```` + +## Context + +### Request context + +The `request.ctx` object is your playground to store whatever information you need to about the request. This lives only for the duration of the request and is unique to the request. + +This can be constrasted with the `app.ctx` object which is shared across all requests. Be careful not to confuse them! + +The `request.ctx` object by default is a `SimpleNamespace` object allowing you to set arbitrary attributes on it. Sanic will not use this object for anything, so you are free to use it however you want without worrying about name clashes. + +````python + +### Typical use case + +This is often used to store items like authenticated user details. We will get more into [middleware](./middleware.md) later, but here is a simple example. + +```python +@app.on_request +async def run_before_handler(request): + request.ctx.user = await fetch_user_by_token(request.token) + +@app.route('/hi') +async def hi_my_name_is(request): + if not request.ctx.user: + return text("Hmm... I don't know you) + return text(f"Hi, my name is {request.ctx.user.name}") +```` + +As you can see, the `request.ctx` object is a great place to store information that you need to access in multiple handlers making your code more DRY and easier to maintain. But, as we will learn in the [middleware section](./middleware.md), you can also use it to store information from one middleware that will be used in another. + +### Connection context + +.. column:: + +``` +Often times your API will need to serve multiple concurrent (or consecutive) requests to the same client. This happens, for example, very often with progressive web apps that need to query multiple endpoints to get data. + +The HTTP protocol calls for an easing of overhead time caused by the connection with the use of [keep alive headers](../deployment/configuration.md#keep-alive-timeout). + +When multiple requests share a single connection, Sanic provides a context object to allow those requests to share state. +``` + +.. column:: + +```` +```python +@app.on_request +async def increment_foo(request): + if not hasattr(request.conn_info.ctx, "foo"): + request.conn_info.ctx.foo = 0 + request.conn_info.ctx.foo += 1 + +@app.get("/") +async def count_foo(request): + return text(f"request.conn_info.ctx.foo={request.conn_info.ctx.foo}") +``` + +```bash +$ curl localhost:8000 localhost:8000 localhost:8000 +request.conn_info.ctx.foo=1 +request.conn_info.ctx.foo=2 +request.conn_info.ctx.foo=3 +``` +```` + +.. warning:: + +``` +While this looks like a convenient place to store information between requests by a single HTTP connection, do not assume that all requests on a single connection came from a single end user. This is because HTTP proxies and load balancers can multiplex multiple connections into a single connection to your server. + +**DO NOT** use this to store information about a single user. Use the `request.ctx` object for that. +``` + +### Custom Request Objects + +As dicussed in [application customization](./app.md#custom-requests), you can create a subclass of :class:`sanic.request.Request` to add additional functionality to the request object. This is useful for adding additional attributes or methods that are specific to your application. + +.. column:: + +``` +For example, imagine your application sends a custom header that contains a user ID. You can create a custom request object that will parse that header and store the user ID for you. +``` + +.. column:: + +```` +```python +from sanic import Sanic, Request + +class CustomRequest(Request): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.user_id = self.headers.get("X-User-ID") + +app = Sanic("Example", request_class=CustomRequest) +``` +```` + +.. column:: + +``` +Now, in your handlers, you can access the `user_id` attribute. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request: CustomRequest): + return text(f"User ID: {request.user_id}") +``` +```` + +### Custom Request Context + +By default, the request context (`request.ctx`) is a [`Simplenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) object allowing you to set arbitrary attributes on it. While this is super helpful to reuse logic across your application, it can be difficult in the development experience since the IDE will not know what attributes are available. + +To help with this, you can create a custom request context object that will be used instead of the default `SimpleNamespace`. This allows you to add type hints to the context object and have them be available in your IDE. + +.. column:: + +``` +Start by subclassing the :class:`sanic.request.Request` class to create a custom request type. Then, you will need to add a `make_context()` method that returns an instance of your custom context object. *NOTE: the `make_context` method should be a static method.* +``` + +.. column:: + +```` +```python +from sanic import Sanic, Request +from types import SimpleNamespace + +class CustomRequest(Request): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.ctx.user_id = self.headers.get("X-User-ID") + + @staticmethod + def make_context() -> CustomContext: + return CustomContext() + +@dataclass +class CustomContext: + user_id: str = None +``` +```` + +.. note:: + +``` +This is a Sanic poweruser feature that makes it super convenient in large codebases to have typed request context objects. It is of course not required, but can be very helpful. +``` + +_Added in v23.6_ + +## Parameters + +.. column:: + +``` +Values that are extracted from the path parameters are injected into the handler as argumets, or more specifically as keyword arguments. There is much more detail about this in the [Routing section](./routing.md). +``` + +.. column:: + +```` +```python +@app.route('/tag/') +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) + +# or, explicitly as keyword arguments +@app.route('/tag/') +async def tag_handler(request, *, tag): + return text("Tag - {}".format(tag)) +``` +```` + +## Arguments + +There are two attributes on the `request` instance to get query parameters: + +- `request.args` +- `request.query_args` + +These allow you to access the query parameters from the request path (the part after the `?` in the URL). + +### Typical use case + +In most use cases, you will want to use the `request.args` object to access the query parameters. This will be the parsed query string as a dictionary. + +This is by far the most common pattern. + +.. column:: + +``` +Consider the example where we have a `/search` endpoint with a `q` parameter that we want to use to search for something. +``` + +.. column:: + +```` +```python +@app.get("/search") +async def search(request): + query = request.args.get("q") + if not query: + return text("No query string provided") + return text(f"Searching for: {query}") +``` +```` + +### Parsing the query string + +Sometimes, however, you may want to access the query string as a raw string or as a list of tuples. For this, you can use the `request.query_string` and `request.query_args` attributes. + +It also should be noted that HTTP allows multiple values for a single key. Although `request.args` may seem like a regular dictionary, it is actually a special type that allows for multiple values for a single key. You can access this by using the `request.args.getlist()` method. + +- `request.query_string` - The raw query string +- `request.query_args` - The parsed query string as a list of tuples +- `request.args` - The parsed query string as a _special_ dictionary + - `request.args.get()` - Get the first value for a key (behaves like a regular dictionary) + - `request.args.getlist()` - Get all values for a key + +```sh +curl "http://localhost:8000?key1=val1&key2=val2&key1=val3" +``` + +```python +>>> print(request.args) +{'key1': ['val1', 'val3'], 'key2': ['val2']} + +>>> print(request.args.get("key1")) +val1 + +>>> print(request.args.getlist("key1")) +['val1', 'val3'] + +>>> print(request.query_args) +[('key1', 'val1'), ('key2', 'val2'), ('key1', 'val3')] + +>>> print(request.query_string) +key1=val1&key2=val2&key1=val3 + +``` + +.. tip:: FYI + +``` +The `request.args` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +## Current request getter + +Sometimes you may find that you need access to the current request in your application in a location where it is not accessible. A typical example might be in a `logging` format. You can use `Request.get_current()` to fetch the current request (if any). + +Remember, the request object is confined to the single [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) that is running the handler. If you are not in that task, there is no request object. + +```python +import logging + +from sanic import Request, Sanic, json +from sanic.exceptions import SanicException +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_FORMAT = ( + "%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: " + "%(request_id)s %(request)s %(message)s %(status)d %(byte)d" +) + +old_factory = logging.getLogRecordFactory() + +def record_factory(*args, **kwargs): + record = old_factory(*args, **kwargs) + record.request_id = "" + + try: + request = Request.get_current() + except SanicException: + ... + else: + record.request_id = str(request.id) + + return record + +logging.setLogRecordFactory(record_factory) + + +LOGGING_CONFIG_DEFAULTS["formatters"]["access"]["format"] = LOGGING_FORMAT +app = Sanic("Example", log_config=LOGGING_CONFIG_DEFAULTS) +``` + +In this example, we are adding the `request.id` to every access log message. + +_Added in v22.6_ From 88c579e7eccc64c9bf635d1c727c35b8ac0f9395 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:59 +0200 Subject: [PATCH 045/698] New translations request.md (Chinese Simplified) --- guide/content/zh/guide/basics/request.md | 478 +++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 guide/content/zh/guide/basics/request.md diff --git a/guide/content/zh/guide/basics/request.md b/guide/content/zh/guide/basics/request.md new file mode 100644 index 0000000000..c3dd8d08d9 --- /dev/null +++ b/guide/content/zh/guide/basics/request.md @@ -0,0 +1,478 @@ +# Request + +See API docs: [sanic.request](/api/sanic.request) + +The :class:`sanic.request.Request` instance contains **a lot** of helpful information available on its parameters. Refer to the [API documentation](https://sanic.readthedocs.io/) for full details. + +As we saw in the section on [handlers](./handlers), the first argument in a route handler is usually the :class:`sanic.request.Request` object. Because Sanic is an async framework, the handler will run inside of a [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) and will be scheduled by the event loop. This means that the handler will be executed in an isolated context and the request object will be unique to that handler's task. + +.. column:: + +``` +By convention, the argument is named `request`, but you can name it whatever you want. The name of the argument is not important. Both of the following handlers are valid. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def typical_use_case(request): + return text("I said foo!") +``` + +```python +@app.get("/foo") +async def atypical_use_case(req): + return text("I said foo!") +``` +```` + +.. column:: + +``` +Annotating a request object is super simple. + +``` + +.. column:: + +```` +```python +from sanic.request import Request +from sanic.response import text + +@app.get("/typed") +async def typed_handler(request: Request): + return text("Done.") +``` +```` + +.. tip:: + +``` +For your convenience, assuming you are using a modern IDE, you should leverage type annotations to help with code completion and documentation. This is especially helpful when using the `request` object as it has **MANY** properties and methods. + +To see the full list of available properties and methods, refer to the [API documentation](/api/sanic.request). +``` + +## Body + +The `Request` object allows you to access the content of the request body in a few different ways. + +### JSON + +.. column:: + +``` +**Parameter**: `request.json` +**Description**: The parsed JSON object +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d '{"foo": "bar"}' +``` + +```python +>>> print(request.json) +{'foo': 'bar'} +``` +```` + +### Raw + +.. column:: + +``` +**Parameter**: `request.body` +**Description**: The raw bytes from the request body +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d '{"foo": "bar"}' +``` + +```python +>>> print(request.body) +b'{"foo": "bar"}' +``` +```` + +### Form + +.. column:: + +``` +**Parameter**: `request.form` +**Description**: The form data + +.. tip:: FYI + + The `request.form` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + + Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +.. column:: + +```` +```bash +$ curl localhost:8000 -d 'foo=bar' +``` + +```python +>>> print(request.body) +b'foo=bar' + +>>> print(request.form) +{'foo': ['bar']} + +>>> print(request.form.get("foo")) +bar + +>>> print(request.form.getlist("foo")) +['bar'] +``` +```` + +### Uploaded + +.. column:: + +``` +**Parameter**: `request.files` +**Description**: The files uploaded to the server + +.. tip:: FYI + + The `request.files` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + + Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +.. column:: + +```` +```bash +$ curl -F 'my_file=@/path/to/TEST' http://localhost:8000 +``` + +```python +>>> print(request.body) +b'--------------------------cb566ad845ad02d3\r\nContent-Disposition: form-data; name="my_file"; filename="TEST"\r\nContent-Type: application/octet-stream\r\n\r\nhello\n\r\n--------------------------cb566ad845ad02d3--\r\n' + +>>> print(request.files) +{'my_file': [File(type='application/octet-stream', body=b'hello\n', name='TEST')]} + +>>> print(request.files.get("my_file")) +File(type='application/octet-stream', body=b'hello\n', name='TEST') + +>>> print(request.files.getlist("my_file")) +[File(type='application/octet-stream', body=b'hello\n', name='TEST')] +``` +```` + +## Context + +### Request context + +The `request.ctx` object is your playground to store whatever information you need to about the request. This lives only for the duration of the request and is unique to the request. + +This can be constrasted with the `app.ctx` object which is shared across all requests. Be careful not to confuse them! + +The `request.ctx` object by default is a `SimpleNamespace` object allowing you to set arbitrary attributes on it. Sanic will not use this object for anything, so you are free to use it however you want without worrying about name clashes. + +````python + +### Typical use case + +This is often used to store items like authenticated user details. We will get more into [middleware](./middleware.md) later, but here is a simple example. + +```python +@app.on_request +async def run_before_handler(request): + request.ctx.user = await fetch_user_by_token(request.token) + +@app.route('/hi') +async def hi_my_name_is(request): + if not request.ctx.user: + return text("Hmm... I don't know you) + return text(f"Hi, my name is {request.ctx.user.name}") +```` + +As you can see, the `request.ctx` object is a great place to store information that you need to access in multiple handlers making your code more DRY and easier to maintain. But, as we will learn in the [middleware section](./middleware.md), you can also use it to store information from one middleware that will be used in another. + +### Connection context + +.. column:: + +``` +Often times your API will need to serve multiple concurrent (or consecutive) requests to the same client. This happens, for example, very often with progressive web apps that need to query multiple endpoints to get data. + +The HTTP protocol calls for an easing of overhead time caused by the connection with the use of [keep alive headers](../deployment/configuration.md#keep-alive-timeout). + +When multiple requests share a single connection, Sanic provides a context object to allow those requests to share state. +``` + +.. column:: + +```` +```python +@app.on_request +async def increment_foo(request): + if not hasattr(request.conn_info.ctx, "foo"): + request.conn_info.ctx.foo = 0 + request.conn_info.ctx.foo += 1 + +@app.get("/") +async def count_foo(request): + return text(f"request.conn_info.ctx.foo={request.conn_info.ctx.foo}") +``` + +```bash +$ curl localhost:8000 localhost:8000 localhost:8000 +request.conn_info.ctx.foo=1 +request.conn_info.ctx.foo=2 +request.conn_info.ctx.foo=3 +``` +```` + +.. warning:: + +``` +While this looks like a convenient place to store information between requests by a single HTTP connection, do not assume that all requests on a single connection came from a single end user. This is because HTTP proxies and load balancers can multiplex multiple connections into a single connection to your server. + +**DO NOT** use this to store information about a single user. Use the `request.ctx` object for that. +``` + +### Custom Request Objects + +As dicussed in [application customization](./app.md#custom-requests), you can create a subclass of :class:`sanic.request.Request` to add additional functionality to the request object. This is useful for adding additional attributes or methods that are specific to your application. + +.. column:: + +``` +For example, imagine your application sends a custom header that contains a user ID. You can create a custom request object that will parse that header and store the user ID for you. +``` + +.. column:: + +```` +```python +from sanic import Sanic, Request + +class CustomRequest(Request): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.user_id = self.headers.get("X-User-ID") + +app = Sanic("Example", request_class=CustomRequest) +``` +```` + +.. column:: + +``` +Now, in your handlers, you can access the `user_id` attribute. +``` + +.. column:: + +```` +```python +@app.route("/") +async def handler(request: CustomRequest): + return text(f"User ID: {request.user_id}") +``` +```` + +### Custom Request Context + +By default, the request context (`request.ctx`) is a [`Simplenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) object allowing you to set arbitrary attributes on it. While this is super helpful to reuse logic across your application, it can be difficult in the development experience since the IDE will not know what attributes are available. + +To help with this, you can create a custom request context object that will be used instead of the default `SimpleNamespace`. This allows you to add type hints to the context object and have them be available in your IDE. + +.. column:: + +``` +Start by subclassing the :class:`sanic.request.Request` class to create a custom request type. Then, you will need to add a `make_context()` method that returns an instance of your custom context object. *NOTE: the `make_context` method should be a static method.* +``` + +.. column:: + +```` +```python +from sanic import Sanic, Request +from types import SimpleNamespace + +class CustomRequest(Request): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.ctx.user_id = self.headers.get("X-User-ID") + + @staticmethod + def make_context() -> CustomContext: + return CustomContext() + +@dataclass +class CustomContext: + user_id: str = None +``` +```` + +.. note:: + +``` +This is a Sanic poweruser feature that makes it super convenient in large codebases to have typed request context objects. It is of course not required, but can be very helpful. +``` + +_Added in v23.6_ + +## Parameters + +.. column:: + +``` +Values that are extracted from the path parameters are injected into the handler as argumets, or more specifically as keyword arguments. There is much more detail about this in the [Routing section](./routing.md). +``` + +.. column:: + +```` +```python +@app.route('/tag/') +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) + +# or, explicitly as keyword arguments +@app.route('/tag/') +async def tag_handler(request, *, tag): + return text("Tag - {}".format(tag)) +``` +```` + +## Arguments + +There are two attributes on the `request` instance to get query parameters: + +- `request.args` +- `request.query_args` + +These allow you to access the query parameters from the request path (the part after the `?` in the URL). + +### Typical use case + +In most use cases, you will want to use the `request.args` object to access the query parameters. This will be the parsed query string as a dictionary. + +This is by far the most common pattern. + +.. column:: + +``` +Consider the example where we have a `/search` endpoint with a `q` parameter that we want to use to search for something. +``` + +.. column:: + +```` +```python +@app.get("/search") +async def search(request): + query = request.args.get("q") + if not query: + return text("No query string provided") + return text(f"Searching for: {query}") +``` +```` + +### Parsing the query string + +Sometimes, however, you may want to access the query string as a raw string or as a list of tuples. For this, you can use the `request.query_string` and `request.query_args` attributes. + +It also should be noted that HTTP allows multiple values for a single key. Although `request.args` may seem like a regular dictionary, it is actually a special type that allows for multiple values for a single key. You can access this by using the `request.args.getlist()` method. + +- `request.query_string` - The raw query string +- `request.query_args` - The parsed query string as a list of tuples +- `request.args` - The parsed query string as a _special_ dictionary + - `request.args.get()` - Get the first value for a key (behaves like a regular dictionary) + - `request.args.getlist()` - Get all values for a key + +```sh +curl "http://localhost:8000?key1=val1&key2=val2&key1=val3" +``` + +```python +>>> print(request.args) +{'key1': ['val1', 'val3'], 'key2': ['val2']} + +>>> print(request.args.get("key1")) +val1 + +>>> print(request.args.getlist("key1")) +['val1', 'val3'] + +>>> print(request.query_args) +[('key1', 'val1'), ('key2', 'val2'), ('key1', 'val3')] + +>>> print(request.query_string) +key1=val1&key2=val2&key1=val3 + +``` + +.. tip:: FYI + +``` +The `request.args` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. + +Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +``` + +## Current request getter + +Sometimes you may find that you need access to the current request in your application in a location where it is not accessible. A typical example might be in a `logging` format. You can use `Request.get_current()` to fetch the current request (if any). + +Remember, the request object is confined to the single [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) that is running the handler. If you are not in that task, there is no request object. + +```python +import logging + +from sanic import Request, Sanic, json +from sanic.exceptions import SanicException +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_FORMAT = ( + "%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: " + "%(request_id)s %(request)s %(message)s %(status)d %(byte)d" +) + +old_factory = logging.getLogRecordFactory() + +def record_factory(*args, **kwargs): + record = old_factory(*args, **kwargs) + record.request_id = "" + + try: + request = Request.get_current() + except SanicException: + ... + else: + record.request_id = str(request.id) + + return record + +logging.setLogRecordFactory(record_factory) + + +LOGGING_CONFIG_DEFAULTS["formatters"]["access"]["format"] = LOGGING_FORMAT +app = Sanic("Example", log_config=LOGGING_CONFIG_DEFAULTS) +``` + +In this example, we are adding the `request.id` to every access log message. + +_Added in v22.6_ From 639c902ec976bc913faec343a5a8310d32e4efb5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:19:59 +0200 Subject: [PATCH 046/698] New translations response.md (Japanese) --- guide/content/ja/guide/basics/response.md | 299 ++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 guide/content/ja/guide/basics/response.md diff --git a/guide/content/ja/guide/basics/response.md b/guide/content/ja/guide/basics/response.md new file mode 100644 index 0000000000..5efe8c3ad3 --- /dev/null +++ b/guide/content/ja/guide/basics/response.md @@ -0,0 +1,299 @@ +# Response + +All [handlers](./handlers.md) _usually_ return a response object, and [middleware](./middleware.md) may optionally return a response object. + +To clarify that statement: + +- unless the handler is a streaming endpoint handling its own pattern for sending bytes to the client, the return value must be an instance of :class:`sanic.response.HTTPResponse` (to learn more about this exception see [streaming responses](../advanced/streaming.md#response-streaming)). In **most** use cases, you will need to return a response. +- if a middleware does return a response object, that will be used instead of whatever the handler would do (see [middleware](./middleware.md) to learn more). + +A most basic handler would look like the following. The :class:`sanic.response.HTTPResponse` object will allow you to set the status, body, and headers to be returned to the client. + +```python +from sanic import HTTPResponse, Sanic + +app = Sanic("TestApp") + +@app.route("") +def handler(_): + return HTTPResponse() +``` + +However, usually it is easier to use one of the convenience methods discussed below. + +## Methods + +The easiest way to generate a response object is to use one of the convenience functions. + +### Text + +.. column:: + +``` +**Default Content-Type**: `text/plain; charset=utf-8` +**Description**: Returns plain text +``` + +.. column:: + +```` +```python +from sanic import text + +@app.route("/") +async def handler(request): + return text("Hi 😎") +``` +```` + +### HTML + +.. column:: + +``` +**Default Content-Type**: `text/html; charset=utf-8` +**Description**: Returns an HTML document +``` + +.. column:: + +```` +```python +from sanic import html + +@app.route("/") +async def handler(request): + return html('
Hi 😎
') +``` +```` + +### JSON + +.. column:: + +``` +**Default Content-Type**: `application/json` +**Description**: Returns a JSON document +``` + +.. column:: + +```` +```python +from sanic import json + +@app.route("/") +async def handler(request): + return json({"foo": "bar"}) +``` +```` + +By default, Sanic ships with [`ujson`](https://github.com/ultrajson/ultrajson) as its JSON encoder of choice. If `ujson` is not installed, it will fall back to the standard library `json` module. + +It is super simple to change this if you want. + +```python +from sanic import json +from orjson import dumps + +json({"foo": "bar"}, dumps=dumps) +``` + +You may additionally declare which implementation to use globally across your application at initialization: + +```python +from orjson import dumps + +app = Sanic(..., dumps=dumps) +``` + +### File + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: Returns a file +``` + +.. column:: + +```` +```python +from sanic import file + +@app.route("/") +async def handler(request): + return await file("/path/to/whatever.png") +``` +```` + +Sanic will examine the file, and try and guess its mime type and use an appropriate value for the content type. You could be explicit, if you would like: + +```python +file("/path/to/whatever.png", mime_type="image/png") +``` + +You can also choose to override the file name: + +```python +file("/path/to/whatever.png", filename="super-awesome-incredible.png") +``` + +### File Streaming + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: Streams a file to a client, useful when streaming large files, like a video +``` + +.. column:: + +```` +```python +from sanic.response import file_stream + +@app.route("/") +async def handler(request): + return await file_stream("/path/to/whatever.mp4") +``` +```` + +Like the `file()` method, `file_stream()` will attempt to determine the mime type of the file. + +### Raw + +.. column:: + +``` +**Default Content-Type**: `application/octet-stream` +**Description**: Send raw bytes without encoding the body +``` + +.. column:: + +```` +```python +from sanic import raw + +@app.route("/") +async def handler(request): + return raw(b"raw bytes") +``` +```` + +### Redirect + +.. column:: + +``` +**Default Content-Type**: `text/html; charset=utf-8` +**Description**: Send a `302` response to redirect the client to a different path +``` + +.. column:: + +```` +```python +from sanic import redirect + +@app.route("/") +async def handler(request): + return redirect("/login") +``` +```` + +### Empty + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: For responding with an empty message as defined by [RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) +``` + +.. column:: + +```` +```python +from sanic import empty + +@app.route("/") +async def handler(request): + return empty() +``` + +Defaults to a `204` status. +```` + +## Default status + +The default HTTP status code for the response is `200`. If you need to change it, it can be done by the response method. + +```python +@app.post("/") +async def create_new(request): + new_thing = await do_create(request) + return json({"created": True, "id": new_thing.thing_id}, status=201) +``` + +## Returning JSON data + +Starting in v22.12, When you use the `sanic.json` convenience method, it will return a subclass of `HTTPResponse` called :class:`sanic.response.types.JSONResponse`. This object will +have several convenient methods available to modify common JSON body. + +```python +from sanic import json + +resp = json(...) +``` + +- `resp.set_body()` - Set the body of the JSON object to the value passed +- `resp.append()` - Append a value to the body like `list.append` (only works if the root JSON is an array) +- `resp.extend()` - Extend a value to the body like `list.extend` (only works if the root JSON is an array) +- `resp.update()` - Update the body with a value like `dict.update` (only works if the root JSON is an object) +- `resp.pop()` - Pop a value like `list.pop` or `dict.pop` (only works if the root JSON is an array or an object) + +.. warning:: + +``` +The raw Python object is stored on the `JSONResponse` object as `raw_body`. While it is safe to overwrite this value with a new one, you should **not** attempt to mutate it. You should instead use the methods listed above. +``` + +```python +resp = json({"foo": "bar"}) + +# This is OKAY +resp.raw_body = {"foo": "bar", "something": "else"} + +# This is better +resp.set_body({"foo": "bar", "something": "else"}) + +# This is also works well +resp.update({"something": "else"}) + +# This is NOT OKAY +resp.raw_body.update({"something": "else"}) +``` + +```python +# Or, even treat it like a list +resp = json(["foo", "bar"]) + +# This is OKAY +resp.raw_body = ["foo", "bar", "something", "else"] + +# This is better +resp.extend(["something", "else"]) + +# This is also works well +resp.append("something") +resp.append("else") + +# This is NOT OKAY +resp.raw_body.append("something") +``` + +_Added in v22.9_ From f8d970d35e60d09d7f348cd024816d6be8ad9f2d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:00 +0200 Subject: [PATCH 047/698] New translations response.md (Korean) --- guide/content/ko/guide/basics/response.md | 299 ++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 guide/content/ko/guide/basics/response.md diff --git a/guide/content/ko/guide/basics/response.md b/guide/content/ko/guide/basics/response.md new file mode 100644 index 0000000000..5efe8c3ad3 --- /dev/null +++ b/guide/content/ko/guide/basics/response.md @@ -0,0 +1,299 @@ +# Response + +All [handlers](./handlers.md) _usually_ return a response object, and [middleware](./middleware.md) may optionally return a response object. + +To clarify that statement: + +- unless the handler is a streaming endpoint handling its own pattern for sending bytes to the client, the return value must be an instance of :class:`sanic.response.HTTPResponse` (to learn more about this exception see [streaming responses](../advanced/streaming.md#response-streaming)). In **most** use cases, you will need to return a response. +- if a middleware does return a response object, that will be used instead of whatever the handler would do (see [middleware](./middleware.md) to learn more). + +A most basic handler would look like the following. The :class:`sanic.response.HTTPResponse` object will allow you to set the status, body, and headers to be returned to the client. + +```python +from sanic import HTTPResponse, Sanic + +app = Sanic("TestApp") + +@app.route("") +def handler(_): + return HTTPResponse() +``` + +However, usually it is easier to use one of the convenience methods discussed below. + +## Methods + +The easiest way to generate a response object is to use one of the convenience functions. + +### Text + +.. column:: + +``` +**Default Content-Type**: `text/plain; charset=utf-8` +**Description**: Returns plain text +``` + +.. column:: + +```` +```python +from sanic import text + +@app.route("/") +async def handler(request): + return text("Hi 😎") +``` +```` + +### HTML + +.. column:: + +``` +**Default Content-Type**: `text/html; charset=utf-8` +**Description**: Returns an HTML document +``` + +.. column:: + +```` +```python +from sanic import html + +@app.route("/") +async def handler(request): + return html('
Hi 😎
') +``` +```` + +### JSON + +.. column:: + +``` +**Default Content-Type**: `application/json` +**Description**: Returns a JSON document +``` + +.. column:: + +```` +```python +from sanic import json + +@app.route("/") +async def handler(request): + return json({"foo": "bar"}) +``` +```` + +By default, Sanic ships with [`ujson`](https://github.com/ultrajson/ultrajson) as its JSON encoder of choice. If `ujson` is not installed, it will fall back to the standard library `json` module. + +It is super simple to change this if you want. + +```python +from sanic import json +from orjson import dumps + +json({"foo": "bar"}, dumps=dumps) +``` + +You may additionally declare which implementation to use globally across your application at initialization: + +```python +from orjson import dumps + +app = Sanic(..., dumps=dumps) +``` + +### File + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: Returns a file +``` + +.. column:: + +```` +```python +from sanic import file + +@app.route("/") +async def handler(request): + return await file("/path/to/whatever.png") +``` +```` + +Sanic will examine the file, and try and guess its mime type and use an appropriate value for the content type. You could be explicit, if you would like: + +```python +file("/path/to/whatever.png", mime_type="image/png") +``` + +You can also choose to override the file name: + +```python +file("/path/to/whatever.png", filename="super-awesome-incredible.png") +``` + +### File Streaming + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: Streams a file to a client, useful when streaming large files, like a video +``` + +.. column:: + +```` +```python +from sanic.response import file_stream + +@app.route("/") +async def handler(request): + return await file_stream("/path/to/whatever.mp4") +``` +```` + +Like the `file()` method, `file_stream()` will attempt to determine the mime type of the file. + +### Raw + +.. column:: + +``` +**Default Content-Type**: `application/octet-stream` +**Description**: Send raw bytes without encoding the body +``` + +.. column:: + +```` +```python +from sanic import raw + +@app.route("/") +async def handler(request): + return raw(b"raw bytes") +``` +```` + +### Redirect + +.. column:: + +``` +**Default Content-Type**: `text/html; charset=utf-8` +**Description**: Send a `302` response to redirect the client to a different path +``` + +.. column:: + +```` +```python +from sanic import redirect + +@app.route("/") +async def handler(request): + return redirect("/login") +``` +```` + +### Empty + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: For responding with an empty message as defined by [RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) +``` + +.. column:: + +```` +```python +from sanic import empty + +@app.route("/") +async def handler(request): + return empty() +``` + +Defaults to a `204` status. +```` + +## Default status + +The default HTTP status code for the response is `200`. If you need to change it, it can be done by the response method. + +```python +@app.post("/") +async def create_new(request): + new_thing = await do_create(request) + return json({"created": True, "id": new_thing.thing_id}, status=201) +``` + +## Returning JSON data + +Starting in v22.12, When you use the `sanic.json` convenience method, it will return a subclass of `HTTPResponse` called :class:`sanic.response.types.JSONResponse`. This object will +have several convenient methods available to modify common JSON body. + +```python +from sanic import json + +resp = json(...) +``` + +- `resp.set_body()` - Set the body of the JSON object to the value passed +- `resp.append()` - Append a value to the body like `list.append` (only works if the root JSON is an array) +- `resp.extend()` - Extend a value to the body like `list.extend` (only works if the root JSON is an array) +- `resp.update()` - Update the body with a value like `dict.update` (only works if the root JSON is an object) +- `resp.pop()` - Pop a value like `list.pop` or `dict.pop` (only works if the root JSON is an array or an object) + +.. warning:: + +``` +The raw Python object is stored on the `JSONResponse` object as `raw_body`. While it is safe to overwrite this value with a new one, you should **not** attempt to mutate it. You should instead use the methods listed above. +``` + +```python +resp = json({"foo": "bar"}) + +# This is OKAY +resp.raw_body = {"foo": "bar", "something": "else"} + +# This is better +resp.set_body({"foo": "bar", "something": "else"}) + +# This is also works well +resp.update({"something": "else"}) + +# This is NOT OKAY +resp.raw_body.update({"something": "else"}) +``` + +```python +# Or, even treat it like a list +resp = json(["foo", "bar"]) + +# This is OKAY +resp.raw_body = ["foo", "bar", "something", "else"] + +# This is better +resp.extend(["something", "else"]) + +# This is also works well +resp.append("something") +resp.append("else") + +# This is NOT OKAY +resp.raw_body.append("something") +``` + +_Added in v22.9_ From 0d46e29a2a3de89c34fb20ceee2e691500e36e96 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:02 +0200 Subject: [PATCH 048/698] New translations response.md (Chinese Simplified) --- guide/content/zh/guide/basics/response.md | 299 ++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 guide/content/zh/guide/basics/response.md diff --git a/guide/content/zh/guide/basics/response.md b/guide/content/zh/guide/basics/response.md new file mode 100644 index 0000000000..5efe8c3ad3 --- /dev/null +++ b/guide/content/zh/guide/basics/response.md @@ -0,0 +1,299 @@ +# Response + +All [handlers](./handlers.md) _usually_ return a response object, and [middleware](./middleware.md) may optionally return a response object. + +To clarify that statement: + +- unless the handler is a streaming endpoint handling its own pattern for sending bytes to the client, the return value must be an instance of :class:`sanic.response.HTTPResponse` (to learn more about this exception see [streaming responses](../advanced/streaming.md#response-streaming)). In **most** use cases, you will need to return a response. +- if a middleware does return a response object, that will be used instead of whatever the handler would do (see [middleware](./middleware.md) to learn more). + +A most basic handler would look like the following. The :class:`sanic.response.HTTPResponse` object will allow you to set the status, body, and headers to be returned to the client. + +```python +from sanic import HTTPResponse, Sanic + +app = Sanic("TestApp") + +@app.route("") +def handler(_): + return HTTPResponse() +``` + +However, usually it is easier to use one of the convenience methods discussed below. + +## Methods + +The easiest way to generate a response object is to use one of the convenience functions. + +### Text + +.. column:: + +``` +**Default Content-Type**: `text/plain; charset=utf-8` +**Description**: Returns plain text +``` + +.. column:: + +```` +```python +from sanic import text + +@app.route("/") +async def handler(request): + return text("Hi 😎") +``` +```` + +### HTML + +.. column:: + +``` +**Default Content-Type**: `text/html; charset=utf-8` +**Description**: Returns an HTML document +``` + +.. column:: + +```` +```python +from sanic import html + +@app.route("/") +async def handler(request): + return html('
Hi 😎
') +``` +```` + +### JSON + +.. column:: + +``` +**Default Content-Type**: `application/json` +**Description**: Returns a JSON document +``` + +.. column:: + +```` +```python +from sanic import json + +@app.route("/") +async def handler(request): + return json({"foo": "bar"}) +``` +```` + +By default, Sanic ships with [`ujson`](https://github.com/ultrajson/ultrajson) as its JSON encoder of choice. If `ujson` is not installed, it will fall back to the standard library `json` module. + +It is super simple to change this if you want. + +```python +from sanic import json +from orjson import dumps + +json({"foo": "bar"}, dumps=dumps) +``` + +You may additionally declare which implementation to use globally across your application at initialization: + +```python +from orjson import dumps + +app = Sanic(..., dumps=dumps) +``` + +### File + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: Returns a file +``` + +.. column:: + +```` +```python +from sanic import file + +@app.route("/") +async def handler(request): + return await file("/path/to/whatever.png") +``` +```` + +Sanic will examine the file, and try and guess its mime type and use an appropriate value for the content type. You could be explicit, if you would like: + +```python +file("/path/to/whatever.png", mime_type="image/png") +``` + +You can also choose to override the file name: + +```python +file("/path/to/whatever.png", filename="super-awesome-incredible.png") +``` + +### File Streaming + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: Streams a file to a client, useful when streaming large files, like a video +``` + +.. column:: + +```` +```python +from sanic.response import file_stream + +@app.route("/") +async def handler(request): + return await file_stream("/path/to/whatever.mp4") +``` +```` + +Like the `file()` method, `file_stream()` will attempt to determine the mime type of the file. + +### Raw + +.. column:: + +``` +**Default Content-Type**: `application/octet-stream` +**Description**: Send raw bytes without encoding the body +``` + +.. column:: + +```` +```python +from sanic import raw + +@app.route("/") +async def handler(request): + return raw(b"raw bytes") +``` +```` + +### Redirect + +.. column:: + +``` +**Default Content-Type**: `text/html; charset=utf-8` +**Description**: Send a `302` response to redirect the client to a different path +``` + +.. column:: + +```` +```python +from sanic import redirect + +@app.route("/") +async def handler(request): + return redirect("/login") +``` +```` + +### Empty + +.. column:: + +``` +**Default Content-Type**: N/A +**Description**: For responding with an empty message as defined by [RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) +``` + +.. column:: + +```` +```python +from sanic import empty + +@app.route("/") +async def handler(request): + return empty() +``` + +Defaults to a `204` status. +```` + +## Default status + +The default HTTP status code for the response is `200`. If you need to change it, it can be done by the response method. + +```python +@app.post("/") +async def create_new(request): + new_thing = await do_create(request) + return json({"created": True, "id": new_thing.thing_id}, status=201) +``` + +## Returning JSON data + +Starting in v22.12, When you use the `sanic.json` convenience method, it will return a subclass of `HTTPResponse` called :class:`sanic.response.types.JSONResponse`. This object will +have several convenient methods available to modify common JSON body. + +```python +from sanic import json + +resp = json(...) +``` + +- `resp.set_body()` - Set the body of the JSON object to the value passed +- `resp.append()` - Append a value to the body like `list.append` (only works if the root JSON is an array) +- `resp.extend()` - Extend a value to the body like `list.extend` (only works if the root JSON is an array) +- `resp.update()` - Update the body with a value like `dict.update` (only works if the root JSON is an object) +- `resp.pop()` - Pop a value like `list.pop` or `dict.pop` (only works if the root JSON is an array or an object) + +.. warning:: + +``` +The raw Python object is stored on the `JSONResponse` object as `raw_body`. While it is safe to overwrite this value with a new one, you should **not** attempt to mutate it. You should instead use the methods listed above. +``` + +```python +resp = json({"foo": "bar"}) + +# This is OKAY +resp.raw_body = {"foo": "bar", "something": "else"} + +# This is better +resp.set_body({"foo": "bar", "something": "else"}) + +# This is also works well +resp.update({"something": "else"}) + +# This is NOT OKAY +resp.raw_body.update({"something": "else"}) +``` + +```python +# Or, even treat it like a list +resp = json(["foo", "bar"]) + +# This is OKAY +resp.raw_body = ["foo", "bar", "something", "else"] + +# This is better +resp.extend(["something", "else"]) + +# This is also works well +resp.append("something") +resp.append("else") + +# This is NOT OKAY +resp.raw_body.append("something") +``` + +_Added in v22.9_ From 379622109de712fd498557330cae30421377a43a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:03 +0200 Subject: [PATCH 049/698] New translations routing.md (Japanese) --- guide/content/ja/guide/basics/routing.md | 927 +++++++++++++++++++++++ 1 file changed, 927 insertions(+) create mode 100644 guide/content/ja/guide/basics/routing.md diff --git a/guide/content/ja/guide/basics/routing.md b/guide/content/ja/guide/basics/routing.md new file mode 100644 index 0000000000..243b8a0e9a --- /dev/null +++ b/guide/content/ja/guide/basics/routing.md @@ -0,0 +1,927 @@ +# Routing + +.. column:: + +``` +So far we have seen a lot of this decorator in different forms. + +But what is it? And how do we use it? +``` + +.. column:: + +```` +```python +@app.route("/stairway") + ... + +@app.get("/to") + ... + +@app.post("/heaven") + ... +``` +```` + +## Adding a route + +.. column:: + +``` +The most basic way to wire up a handler to an endpoint is with `app.add_route()`. + +See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.Sanic.url_for) for more details. +``` + +.. column:: + +```` +```python +async def handler(request): + return text("OK") + +app.add_route(handler, "/test") +``` +```` + +.. column:: + +``` +By default, routes are available as an HTTP `GET` call. You can change a handler to respond to one or more HTTP methods. +``` + +.. column:: + +```` +```python +app.add_route( + handler, + '/test', + methods=["POST", "PUT"], +) +``` +```` + +.. column:: + +``` +Using the decorator syntax, the previous example is identical to this. +``` + +.. column:: + +```` +```python +@app.route('/test', methods=["POST", "PUT"]) +async def handler(request): + return text('OK') +``` +```` + +## HTTP methods + +Each of the standard HTTP methods has a convenience decorator. + +### GET + +```python +@app.get('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) + +### POST + +```python +@app.post('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) + +### PUT + +```python +@app.put('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) + +### PATCH + +```python +@app.patch('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) + +### DELETE + +```python +@app.delete('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) + +### HEAD + +```python +@app.head('/test') +async def handler(request): + return empty() +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) + +### OPTIONS + +```python +@app.options('/test') +async def handler(request): + return empty() +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) + +.. warning:: + +```` +By default, Sanic will **only** consume the incoming request body on non-safe HTTP methods: `POST`, `PUT`, `PATCH`, `DELETE`. If you want to receive data in the HTTP request on any other method, you will need to do one of the following two options: + +**Option #1 - Tell Sanic to consume the body using `ignore_body`** +```python +@app.request("/path", ignore_body=False) +async def handler(_): + ... +``` + +**Option #2 - Manually consume the body in the handler using `receive_body`** +```python +@app.get("/path") +async def handler(request: Request): + await request.receive_body() +``` +```` + +## Path parameters + +.. column:: + +``` +Sanic allows for pattern matching, and for extracting values from URL paths. These parameters are then injected as keyword arguments in the route handler. +``` + +.. column:: + +```` +```python +@app.get("/tag/") +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) +``` +```` + +.. column:: + +``` +You can declare a type for the parameter. This will be enforced when matching, and also will type cast the variable. +``` + +.. column:: + +```` +```python +@app.get("/foo/") +async def uuid_handler(request, foo_id: UUID): + return text("UUID - {}".format(foo_id)) +``` +```` + +.. column:: + +``` +For some standard types like `str`, `int`, and `UUID`, Sanic can infer the path parameter type from the function signature. This means that it may not always be necessary to include the type in the path parameter definition. +``` + +.. column:: + +```` +```python +@app.get("/foo/") # Notice there is no :uuid in the path parameter +async def uuid_handler(request, foo_id: UUID): + return text("UUID - {}".format(foo_id)) +``` +```` + +### Supported types + +### `str` + +.. column:: + +``` +**Regular expression applied**: `r"[^/]+"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python%203` + +Beginning in v22.3 `str` will *not* match on empty strings. See `strorempty` for this behavior. +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `strorempty` + +.. column:: + +``` +**Regular expression applied**: `r"[^/]*"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python%203` +- `/path/to/` + +Unlike the `str` path parameter type, `strorempty` can also match on an empty string path segment. + +*Added in v22.3* +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `int` + +.. column:: + +``` +**Regular expression applied**: `r"-?\d+"` +**Cast type**: `int` +**Example matches**: + +- `/path/to/10` +- `/path/to/-10` + +_Does not match float, hex, octal, etc_ +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: int): + ... +``` +```` + +### `float` + +.. column:: + +``` +**Regular expression applied**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)"` +**Cast type**: `float` +**Example matches**: + +- `/path/to/10` +- `/path/to/-10` +- `/path/to/1.5` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: float): + ... +``` +```` + +### `alpha` + +.. column:: + +``` +**Regular expression applied**: `r"[A-Za-z]+"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python` + +_Does not match a digit, or a space or other special character_ +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `slug` + +.. column:: + +``` +**Regular expression applied**: `r"[a-z0-9]+(?:-[a-z0-9]+)*"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/some-news-story` +- `/path/to/or-has-digits-123` + +*Added in v21.6* +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, article: str): + ... +``` +```` + +### `path` + +.. column:: + +``` +**Regular expression applied**: `r"[^/].*?"` +**Cast type**: `str` +**Example matches**: +- `/path/to/hello` +- `/path/to/hello.txt` +- `/path/to/hello/world.txt` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +.. warning:: + +``` +Because this will match on `/`, you should be careful and thoroughly test your patterns that use `path` so they do not capture traffic intended for another endpoint. Additionally, depending on how you use this type, you may be creating a path traversal vulnerability in your application. It is your job to protect your endpoint against this, but feel free to ask in our community channels for help if you need it :) +``` + +### `ymd` + +.. column:: + +``` +**Regular expression applied**: `r"^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))"` +**Cast type**: `datetime.date` +**Example matches**: + +- `/path/to/2021-03-28` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: datetime.date): + ... +``` +```` + +### `uuid` + +.. column:: + +``` +**Regular expression applied**: `r"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}"` +**Cast type**: `UUID` +**Example matches**: + +- `/path/to/123a123a-a12a-1a1a-a1a1-1a12a1a12345` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: UUID): + ... +``` +```` + +### ext + +.. column:: + +``` +**Regular expression applied**: n/a +**Cast type**: *varies* +**Example matches**: +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str, ext: str): + ... +``` +```` + +| definition | example | filename | extension | +| ---------------------------------- | ----------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | + +File extensions can be matched using the special `ext` parameter type. It uses a special format that allows you to specify other types of parameter types as the file name, and one or more specific extensions as shown in the example table above. + +It does _not_ support the `path` parameter type. + +_Added in v22.3_ + +### regex + +.. column:: + +``` +**Regular expression applied**: _whatever you insert_ +**Cast type**: `str` +**Example matches**: + +- `/path/to/2021-01-01` + +This gives you the freedom to define specific matching patterns for your use case. + +In the example shown, we are looking for a date that is in `YYYY-MM-DD` format. +``` + +.. column:: + +```` +```python +@app.route(r"/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### Regex Matching + +More often than not, compared with complex routing, the above example is too simple, and we use a completely different routing matching pattern, so here we will explain the advanced usage of regex matching in detail. + +Sometimes, you want to match a part of a route: + +```text +/image/123456789.jpg +``` + +If you wanted to match the file pattern, but only capture the numeric portion, you need to do some regex fun 😄: + +```python +app.route(r"/image/\d+)\.jpg>") +``` + +Further, these should all be acceptable: + +```python +@app.get(r"/") # matching on the full pattern +@app.get(r"/") # defining a single matching group +@app.get(r"/[a-z]{3}).txt>") # defining a single named matching group +@app.get(r"/[a-z]{3}).(?:txt)>") # defining a single named matching group, with one or more non-matching groups +``` + +Also, if using a named matching group, it must be the same as the segment label. + +```python +@app.get(r"/\d+).jpg>") # OK +@app.get(r"/\d+).jpg>") # NOT OK +``` + +For more regular usage methods, please refer to [Regular expression operations](https://docs.python.org/3/library/re.html) + +## Generating a URL + +.. column:: + +``` +Sanic provides a method to generate URLs based on the handler method name: `app.url_for()`. This is useful if you want to avoid hardcoding url paths into your app; instead, you can just reference the handler name. +``` + +.. column:: + +```` +```python +@app.route('/') +async def index(request): + # generate a URL for the endpoint `post_handler` + url = app.url_for('post_handler', post_id=5) + + # Redirect to `/posts/5` + return redirect(url) + +@app.route('/posts/') +async def post_handler(request, post_id): + ... +``` +```` + +.. column:: + +``` +You can pass any arbitrary number of keyword arguments. Anything that is _not_ a request parameter will be implemented as a part of the query string. +``` + +.. column:: + +```` +```python +assert app.url_for( + "post_handler", + post_id=5, + arg_one="one", + arg_two="two", +) == "/posts/5?arg_one=one&arg_two=two" +``` +```` + +.. column:: + +``` +Also supported is passing multiple values for a single query key. +``` + +.. column:: + +```` +```python +assert app.url_for( + "post_handler", + post_id=5, + arg_one=["one", "two"], +) == "/posts/5?arg_one=one&arg_one=two" +``` +```` + +### Special keyword arguments + +See API Docs for more details. + +```python +app.url_for("post_handler", post_id=5, arg_one="one", _anchor="anchor") +# '/posts/5?arg_one=one#anchor' + +# _external requires you to pass an argument _server or set SERVER_NAME in app.config if not url will be same as no _external +app.url_for("post_handler", post_id=5, arg_one="one", _external=True) +# '//server/posts/5?arg_one=one' + +# when specifying _scheme, _external must be True +app.url_for("post_handler", post_id=5, arg_one="one", _scheme="http", _external=True) +# 'http://server/posts/5?arg_one=one' + +# you can pass all special arguments at once +app.url_for("post_handler", post_id=5, arg_one=["one", "two"], arg_two=2, _anchor="anchor", _scheme="http", _external=True, _server="another_server:8888") +# 'http://another_server:8888/posts/5?arg_one=one&arg_one=two&arg_two=2#anchor' +``` + +### Customizing a route name + +.. column:: + +``` +A custom route name can be used by passing a `name` argument while registering the route. +``` + +.. column:: + +```` +```python +@app.get("/get", name="get_handler") +def handler(request): + return text("OK") +``` +```` + +.. column:: + +``` +Now, use this custom name to retrieve the URL +``` + +.. column:: + +```` +```python +assert app.url_for("get_handler", foo="bar") == "/get?foo=bar" +``` +```` + +## Websockets routes + +.. column:: + +``` +Websocket routing works similar to HTTP methods. +``` + +.. column:: + +```` +```python +async def handler(request, ws): + message = "Start" + while True: + await ws.send(message) + message = await ws.recv() + +app.add_websocket_route(handler, "/test") +``` +```` + +.. column:: + +``` +It also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.websocket("/test") +async def handler(request, ws): + message = "Start" + while True: + await ws.send(message) + message = await ws.recv() +``` +```` + +Read the [websockets section](/guide/advanced/websockets.md) to learn more about how they work. + +## Strict slashes + +.. column:: + +``` +Sanic routes can be configured to strictly match on whether or not there is a trailing slash: `/`. This can be configured at a few levels and follows this order of precedence: + +1. Route +2. Blueprint +3. BlueprintGroup +4. Application +``` + +.. column:: + +```` +```python +# provide default strict_slashes value for all routes +app = Sanic(__file__, strict_slashes=True) +``` + +```python +# overwrite strict_slashes value for specific route +@app.get("/get", strict_slashes=False) +def handler(request): + return text("OK") +``` + +```python +# it also works for blueprints +bp = Blueprint(__file__, strict_slashes=True) + +@bp.get("/bp/get", strict_slashes=False) +def handler(request): + return text("OK") +``` + +```python +bp1 = Blueprint(name="bp1", url_prefix="/bp1") +bp2 = Blueprint( + name="bp2", + url_prefix="/bp2", + strict_slashes=False, +) + +# This will enforce strict slashes check on the routes +# under bp1 but ignore bp2 as that has an explicitly +# set the strict slashes check to false +group = Blueprint.group([bp1, bp2], strict_slashes=True) +``` +```` + +## Static files + +.. column:: + +``` +In order to serve static files from Sanic, use `app.static()`. + +The order of arguments is important: + +1. Route the files will be served from +2. Path to the files on the server + +See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic.static) for more details. +``` + +.. column:: + +```` +```python +app.static("/static/", "/path/to/directory/") +``` +```` + +.. tip:: + +``` +It is generally best practice to end your directory paths with a trailing slash (`/this/is/a/directory/`). This removes ambiguity by being more explicit. +``` + +.. column:: + +``` +You can also serve individual files. +``` + +.. column:: + +```` +```python +app.static("/", "/path/to/index.html") +``` +```` + +.. column:: + +``` +It is also sometimes helpful to name your endpoint +``` + +.. column:: + +```` +```python +app.static( + "/user/uploads/", + "/path/to/uploads/", + name="uploads", +) +``` +```` + +.. column:: + +``` +Retrieving the URLs works similar to handlers. But, we can also add the `filename` argument when we need a specific file inside a directory. +``` + +.. column:: + +```` +```python +assert app.url_for( + "static", + name="static", + filename="file.txt", +) == "/static/file.txt" +``` +```python +assert app.url_for( + "static", + name="uploads", + filename="image.png", +) == "/user/uploads/image.png" + +``` +```` + +.. tip:: + +```` +If you are going to have multiple `static()` routes, then it is *highly* suggested that you manually name them. This will almost certainly alleviate potential hard to discover bugs. + +```python +app.static("/user/uploads/", "/path/to/uploads/", name="uploads") +app.static("/user/profile/", "/path/to/profile/", name="profile_pics") +``` +```` + +#### Auto index serving + +.. column:: + +``` +If you have a directory of static files that should be served by an index page, you can provide the filename of the index. Now, when reaching that directory URL, the index page will be served. +``` + +.. column:: + +```` +```python +app.static("/foo/", "/path/to/foo/", index="index.html") +``` +```` + +_Added in v23.3_ + +#### File browser + +.. column:: + +``` +When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. +``` + +.. column:: + +```` +```python +app.static("/uploads/", "/path/to/dir", directory_view=True) +``` +```` + +You now have a browsable directory in your web browser: + +![image](/assets/images/directory-view.png) + +_Added in v23.3_ + +## Route context + +.. column:: + +``` +When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. +``` + +.. column:: + +```` +```python +@app.get("/1", ctx_label="something") +async def handler1(request): + ... + +@app.get("/2", ctx_label="something") +async def handler2(request): + ... + +@app.get("/99") +async def handler99(request): + ... + +@app.on_request +async def do_something(request): + if request.route.ctx.label == "something": + ... +``` +```` + +_Added in v21.12_ From 6a54d3bb0dc06a1021eda04e1717d8214d64111b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:04 +0200 Subject: [PATCH 050/698] New translations routing.md (Korean) --- guide/content/ko/guide/basics/routing.md | 927 +++++++++++++++++++++++ 1 file changed, 927 insertions(+) create mode 100644 guide/content/ko/guide/basics/routing.md diff --git a/guide/content/ko/guide/basics/routing.md b/guide/content/ko/guide/basics/routing.md new file mode 100644 index 0000000000..243b8a0e9a --- /dev/null +++ b/guide/content/ko/guide/basics/routing.md @@ -0,0 +1,927 @@ +# Routing + +.. column:: + +``` +So far we have seen a lot of this decorator in different forms. + +But what is it? And how do we use it? +``` + +.. column:: + +```` +```python +@app.route("/stairway") + ... + +@app.get("/to") + ... + +@app.post("/heaven") + ... +``` +```` + +## Adding a route + +.. column:: + +``` +The most basic way to wire up a handler to an endpoint is with `app.add_route()`. + +See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.Sanic.url_for) for more details. +``` + +.. column:: + +```` +```python +async def handler(request): + return text("OK") + +app.add_route(handler, "/test") +``` +```` + +.. column:: + +``` +By default, routes are available as an HTTP `GET` call. You can change a handler to respond to one or more HTTP methods. +``` + +.. column:: + +```` +```python +app.add_route( + handler, + '/test', + methods=["POST", "PUT"], +) +``` +```` + +.. column:: + +``` +Using the decorator syntax, the previous example is identical to this. +``` + +.. column:: + +```` +```python +@app.route('/test', methods=["POST", "PUT"]) +async def handler(request): + return text('OK') +``` +```` + +## HTTP methods + +Each of the standard HTTP methods has a convenience decorator. + +### GET + +```python +@app.get('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) + +### POST + +```python +@app.post('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) + +### PUT + +```python +@app.put('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) + +### PATCH + +```python +@app.patch('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) + +### DELETE + +```python +@app.delete('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) + +### HEAD + +```python +@app.head('/test') +async def handler(request): + return empty() +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) + +### OPTIONS + +```python +@app.options('/test') +async def handler(request): + return empty() +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) + +.. warning:: + +```` +By default, Sanic will **only** consume the incoming request body on non-safe HTTP methods: `POST`, `PUT`, `PATCH`, `DELETE`. If you want to receive data in the HTTP request on any other method, you will need to do one of the following two options: + +**Option #1 - Tell Sanic to consume the body using `ignore_body`** +```python +@app.request("/path", ignore_body=False) +async def handler(_): + ... +``` + +**Option #2 - Manually consume the body in the handler using `receive_body`** +```python +@app.get("/path") +async def handler(request: Request): + await request.receive_body() +``` +```` + +## Path parameters + +.. column:: + +``` +Sanic allows for pattern matching, and for extracting values from URL paths. These parameters are then injected as keyword arguments in the route handler. +``` + +.. column:: + +```` +```python +@app.get("/tag/") +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) +``` +```` + +.. column:: + +``` +You can declare a type for the parameter. This will be enforced when matching, and also will type cast the variable. +``` + +.. column:: + +```` +```python +@app.get("/foo/") +async def uuid_handler(request, foo_id: UUID): + return text("UUID - {}".format(foo_id)) +``` +```` + +.. column:: + +``` +For some standard types like `str`, `int`, and `UUID`, Sanic can infer the path parameter type from the function signature. This means that it may not always be necessary to include the type in the path parameter definition. +``` + +.. column:: + +```` +```python +@app.get("/foo/") # Notice there is no :uuid in the path parameter +async def uuid_handler(request, foo_id: UUID): + return text("UUID - {}".format(foo_id)) +``` +```` + +### Supported types + +### `str` + +.. column:: + +``` +**Regular expression applied**: `r"[^/]+"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python%203` + +Beginning in v22.3 `str` will *not* match on empty strings. See `strorempty` for this behavior. +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `strorempty` + +.. column:: + +``` +**Regular expression applied**: `r"[^/]*"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python%203` +- `/path/to/` + +Unlike the `str` path parameter type, `strorempty` can also match on an empty string path segment. + +*Added in v22.3* +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `int` + +.. column:: + +``` +**Regular expression applied**: `r"-?\d+"` +**Cast type**: `int` +**Example matches**: + +- `/path/to/10` +- `/path/to/-10` + +_Does not match float, hex, octal, etc_ +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: int): + ... +``` +```` + +### `float` + +.. column:: + +``` +**Regular expression applied**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)"` +**Cast type**: `float` +**Example matches**: + +- `/path/to/10` +- `/path/to/-10` +- `/path/to/1.5` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: float): + ... +``` +```` + +### `alpha` + +.. column:: + +``` +**Regular expression applied**: `r"[A-Za-z]+"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python` + +_Does not match a digit, or a space or other special character_ +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `slug` + +.. column:: + +``` +**Regular expression applied**: `r"[a-z0-9]+(?:-[a-z0-9]+)*"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/some-news-story` +- `/path/to/or-has-digits-123` + +*Added in v21.6* +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, article: str): + ... +``` +```` + +### `path` + +.. column:: + +``` +**Regular expression applied**: `r"[^/].*?"` +**Cast type**: `str` +**Example matches**: +- `/path/to/hello` +- `/path/to/hello.txt` +- `/path/to/hello/world.txt` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +.. warning:: + +``` +Because this will match on `/`, you should be careful and thoroughly test your patterns that use `path` so they do not capture traffic intended for another endpoint. Additionally, depending on how you use this type, you may be creating a path traversal vulnerability in your application. It is your job to protect your endpoint against this, but feel free to ask in our community channels for help if you need it :) +``` + +### `ymd` + +.. column:: + +``` +**Regular expression applied**: `r"^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))"` +**Cast type**: `datetime.date` +**Example matches**: + +- `/path/to/2021-03-28` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: datetime.date): + ... +``` +```` + +### `uuid` + +.. column:: + +``` +**Regular expression applied**: `r"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}"` +**Cast type**: `UUID` +**Example matches**: + +- `/path/to/123a123a-a12a-1a1a-a1a1-1a12a1a12345` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: UUID): + ... +``` +```` + +### ext + +.. column:: + +``` +**Regular expression applied**: n/a +**Cast type**: *varies* +**Example matches**: +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str, ext: str): + ... +``` +```` + +| definition | example | filename | extension | +| ---------------------------------- | ----------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | + +File extensions can be matched using the special `ext` parameter type. It uses a special format that allows you to specify other types of parameter types as the file name, and one or more specific extensions as shown in the example table above. + +It does _not_ support the `path` parameter type. + +_Added in v22.3_ + +### regex + +.. column:: + +``` +**Regular expression applied**: _whatever you insert_ +**Cast type**: `str` +**Example matches**: + +- `/path/to/2021-01-01` + +This gives you the freedom to define specific matching patterns for your use case. + +In the example shown, we are looking for a date that is in `YYYY-MM-DD` format. +``` + +.. column:: + +```` +```python +@app.route(r"/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### Regex Matching + +More often than not, compared with complex routing, the above example is too simple, and we use a completely different routing matching pattern, so here we will explain the advanced usage of regex matching in detail. + +Sometimes, you want to match a part of a route: + +```text +/image/123456789.jpg +``` + +If you wanted to match the file pattern, but only capture the numeric portion, you need to do some regex fun 😄: + +```python +app.route(r"/image/\d+)\.jpg>") +``` + +Further, these should all be acceptable: + +```python +@app.get(r"/") # matching on the full pattern +@app.get(r"/") # defining a single matching group +@app.get(r"/[a-z]{3}).txt>") # defining a single named matching group +@app.get(r"/[a-z]{3}).(?:txt)>") # defining a single named matching group, with one or more non-matching groups +``` + +Also, if using a named matching group, it must be the same as the segment label. + +```python +@app.get(r"/\d+).jpg>") # OK +@app.get(r"/\d+).jpg>") # NOT OK +``` + +For more regular usage methods, please refer to [Regular expression operations](https://docs.python.org/3/library/re.html) + +## Generating a URL + +.. column:: + +``` +Sanic provides a method to generate URLs based on the handler method name: `app.url_for()`. This is useful if you want to avoid hardcoding url paths into your app; instead, you can just reference the handler name. +``` + +.. column:: + +```` +```python +@app.route('/') +async def index(request): + # generate a URL for the endpoint `post_handler` + url = app.url_for('post_handler', post_id=5) + + # Redirect to `/posts/5` + return redirect(url) + +@app.route('/posts/') +async def post_handler(request, post_id): + ... +``` +```` + +.. column:: + +``` +You can pass any arbitrary number of keyword arguments. Anything that is _not_ a request parameter will be implemented as a part of the query string. +``` + +.. column:: + +```` +```python +assert app.url_for( + "post_handler", + post_id=5, + arg_one="one", + arg_two="two", +) == "/posts/5?arg_one=one&arg_two=two" +``` +```` + +.. column:: + +``` +Also supported is passing multiple values for a single query key. +``` + +.. column:: + +```` +```python +assert app.url_for( + "post_handler", + post_id=5, + arg_one=["one", "two"], +) == "/posts/5?arg_one=one&arg_one=two" +``` +```` + +### Special keyword arguments + +See API Docs for more details. + +```python +app.url_for("post_handler", post_id=5, arg_one="one", _anchor="anchor") +# '/posts/5?arg_one=one#anchor' + +# _external requires you to pass an argument _server or set SERVER_NAME in app.config if not url will be same as no _external +app.url_for("post_handler", post_id=5, arg_one="one", _external=True) +# '//server/posts/5?arg_one=one' + +# when specifying _scheme, _external must be True +app.url_for("post_handler", post_id=5, arg_one="one", _scheme="http", _external=True) +# 'http://server/posts/5?arg_one=one' + +# you can pass all special arguments at once +app.url_for("post_handler", post_id=5, arg_one=["one", "two"], arg_two=2, _anchor="anchor", _scheme="http", _external=True, _server="another_server:8888") +# 'http://another_server:8888/posts/5?arg_one=one&arg_one=two&arg_two=2#anchor' +``` + +### Customizing a route name + +.. column:: + +``` +A custom route name can be used by passing a `name` argument while registering the route. +``` + +.. column:: + +```` +```python +@app.get("/get", name="get_handler") +def handler(request): + return text("OK") +``` +```` + +.. column:: + +``` +Now, use this custom name to retrieve the URL +``` + +.. column:: + +```` +```python +assert app.url_for("get_handler", foo="bar") == "/get?foo=bar" +``` +```` + +## Websockets routes + +.. column:: + +``` +Websocket routing works similar to HTTP methods. +``` + +.. column:: + +```` +```python +async def handler(request, ws): + message = "Start" + while True: + await ws.send(message) + message = await ws.recv() + +app.add_websocket_route(handler, "/test") +``` +```` + +.. column:: + +``` +It also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.websocket("/test") +async def handler(request, ws): + message = "Start" + while True: + await ws.send(message) + message = await ws.recv() +``` +```` + +Read the [websockets section](/guide/advanced/websockets.md) to learn more about how they work. + +## Strict slashes + +.. column:: + +``` +Sanic routes can be configured to strictly match on whether or not there is a trailing slash: `/`. This can be configured at a few levels and follows this order of precedence: + +1. Route +2. Blueprint +3. BlueprintGroup +4. Application +``` + +.. column:: + +```` +```python +# provide default strict_slashes value for all routes +app = Sanic(__file__, strict_slashes=True) +``` + +```python +# overwrite strict_slashes value for specific route +@app.get("/get", strict_slashes=False) +def handler(request): + return text("OK") +``` + +```python +# it also works for blueprints +bp = Blueprint(__file__, strict_slashes=True) + +@bp.get("/bp/get", strict_slashes=False) +def handler(request): + return text("OK") +``` + +```python +bp1 = Blueprint(name="bp1", url_prefix="/bp1") +bp2 = Blueprint( + name="bp2", + url_prefix="/bp2", + strict_slashes=False, +) + +# This will enforce strict slashes check on the routes +# under bp1 but ignore bp2 as that has an explicitly +# set the strict slashes check to false +group = Blueprint.group([bp1, bp2], strict_slashes=True) +``` +```` + +## Static files + +.. column:: + +``` +In order to serve static files from Sanic, use `app.static()`. + +The order of arguments is important: + +1. Route the files will be served from +2. Path to the files on the server + +See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic.static) for more details. +``` + +.. column:: + +```` +```python +app.static("/static/", "/path/to/directory/") +``` +```` + +.. tip:: + +``` +It is generally best practice to end your directory paths with a trailing slash (`/this/is/a/directory/`). This removes ambiguity by being more explicit. +``` + +.. column:: + +``` +You can also serve individual files. +``` + +.. column:: + +```` +```python +app.static("/", "/path/to/index.html") +``` +```` + +.. column:: + +``` +It is also sometimes helpful to name your endpoint +``` + +.. column:: + +```` +```python +app.static( + "/user/uploads/", + "/path/to/uploads/", + name="uploads", +) +``` +```` + +.. column:: + +``` +Retrieving the URLs works similar to handlers. But, we can also add the `filename` argument when we need a specific file inside a directory. +``` + +.. column:: + +```` +```python +assert app.url_for( + "static", + name="static", + filename="file.txt", +) == "/static/file.txt" +``` +```python +assert app.url_for( + "static", + name="uploads", + filename="image.png", +) == "/user/uploads/image.png" + +``` +```` + +.. tip:: + +```` +If you are going to have multiple `static()` routes, then it is *highly* suggested that you manually name them. This will almost certainly alleviate potential hard to discover bugs. + +```python +app.static("/user/uploads/", "/path/to/uploads/", name="uploads") +app.static("/user/profile/", "/path/to/profile/", name="profile_pics") +``` +```` + +#### Auto index serving + +.. column:: + +``` +If you have a directory of static files that should be served by an index page, you can provide the filename of the index. Now, when reaching that directory URL, the index page will be served. +``` + +.. column:: + +```` +```python +app.static("/foo/", "/path/to/foo/", index="index.html") +``` +```` + +_Added in v23.3_ + +#### File browser + +.. column:: + +``` +When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. +``` + +.. column:: + +```` +```python +app.static("/uploads/", "/path/to/dir", directory_view=True) +``` +```` + +You now have a browsable directory in your web browser: + +![image](/assets/images/directory-view.png) + +_Added in v23.3_ + +## Route context + +.. column:: + +``` +When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. +``` + +.. column:: + +```` +```python +@app.get("/1", ctx_label="something") +async def handler1(request): + ... + +@app.get("/2", ctx_label="something") +async def handler2(request): + ... + +@app.get("/99") +async def handler99(request): + ... + +@app.on_request +async def do_something(request): + if request.route.ctx.label == "something": + ... +``` +```` + +_Added in v21.12_ From d0e4063b346c69d159b79b7c3692b7b238be0339 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:06 +0200 Subject: [PATCH 051/698] New translations routing.md (Chinese Simplified) --- guide/content/zh/guide/basics/routing.md | 927 +++++++++++++++++++++++ 1 file changed, 927 insertions(+) create mode 100644 guide/content/zh/guide/basics/routing.md diff --git a/guide/content/zh/guide/basics/routing.md b/guide/content/zh/guide/basics/routing.md new file mode 100644 index 0000000000..243b8a0e9a --- /dev/null +++ b/guide/content/zh/guide/basics/routing.md @@ -0,0 +1,927 @@ +# Routing + +.. column:: + +``` +So far we have seen a lot of this decorator in different forms. + +But what is it? And how do we use it? +``` + +.. column:: + +```` +```python +@app.route("/stairway") + ... + +@app.get("/to") + ... + +@app.post("/heaven") + ... +``` +```` + +## Adding a route + +.. column:: + +``` +The most basic way to wire up a handler to an endpoint is with `app.add_route()`. + +See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.Sanic.url_for) for more details. +``` + +.. column:: + +```` +```python +async def handler(request): + return text("OK") + +app.add_route(handler, "/test") +``` +```` + +.. column:: + +``` +By default, routes are available as an HTTP `GET` call. You can change a handler to respond to one or more HTTP methods. +``` + +.. column:: + +```` +```python +app.add_route( + handler, + '/test', + methods=["POST", "PUT"], +) +``` +```` + +.. column:: + +``` +Using the decorator syntax, the previous example is identical to this. +``` + +.. column:: + +```` +```python +@app.route('/test', methods=["POST", "PUT"]) +async def handler(request): + return text('OK') +``` +```` + +## HTTP methods + +Each of the standard HTTP methods has a convenience decorator. + +### GET + +```python +@app.get('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) + +### POST + +```python +@app.post('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) + +### PUT + +```python +@app.put('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) + +### PATCH + +```python +@app.patch('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) + +### DELETE + +```python +@app.delete('/test') +async def handler(request): + return text('OK') +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) + +### HEAD + +```python +@app.head('/test') +async def handler(request): + return empty() +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) + +### OPTIONS + +```python +@app.options('/test') +async def handler(request): + return empty() +``` + +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) + +.. warning:: + +```` +By default, Sanic will **only** consume the incoming request body on non-safe HTTP methods: `POST`, `PUT`, `PATCH`, `DELETE`. If you want to receive data in the HTTP request on any other method, you will need to do one of the following two options: + +**Option #1 - Tell Sanic to consume the body using `ignore_body`** +```python +@app.request("/path", ignore_body=False) +async def handler(_): + ... +``` + +**Option #2 - Manually consume the body in the handler using `receive_body`** +```python +@app.get("/path") +async def handler(request: Request): + await request.receive_body() +``` +```` + +## Path parameters + +.. column:: + +``` +Sanic allows for pattern matching, and for extracting values from URL paths. These parameters are then injected as keyword arguments in the route handler. +``` + +.. column:: + +```` +```python +@app.get("/tag/") +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) +``` +```` + +.. column:: + +``` +You can declare a type for the parameter. This will be enforced when matching, and also will type cast the variable. +``` + +.. column:: + +```` +```python +@app.get("/foo/") +async def uuid_handler(request, foo_id: UUID): + return text("UUID - {}".format(foo_id)) +``` +```` + +.. column:: + +``` +For some standard types like `str`, `int`, and `UUID`, Sanic can infer the path parameter type from the function signature. This means that it may not always be necessary to include the type in the path parameter definition. +``` + +.. column:: + +```` +```python +@app.get("/foo/") # Notice there is no :uuid in the path parameter +async def uuid_handler(request, foo_id: UUID): + return text("UUID - {}".format(foo_id)) +``` +```` + +### Supported types + +### `str` + +.. column:: + +``` +**Regular expression applied**: `r"[^/]+"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python%203` + +Beginning in v22.3 `str` will *not* match on empty strings. See `strorempty` for this behavior. +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `strorempty` + +.. column:: + +``` +**Regular expression applied**: `r"[^/]*"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python%203` +- `/path/to/` + +Unlike the `str` path parameter type, `strorempty` can also match on an empty string path segment. + +*Added in v22.3* +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `int` + +.. column:: + +``` +**Regular expression applied**: `r"-?\d+"` +**Cast type**: `int` +**Example matches**: + +- `/path/to/10` +- `/path/to/-10` + +_Does not match float, hex, octal, etc_ +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: int): + ... +``` +```` + +### `float` + +.. column:: + +``` +**Regular expression applied**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)"` +**Cast type**: `float` +**Example matches**: + +- `/path/to/10` +- `/path/to/-10` +- `/path/to/1.5` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: float): + ... +``` +```` + +### `alpha` + +.. column:: + +``` +**Regular expression applied**: `r"[A-Za-z]+"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/Bob` +- `/path/to/Python` + +_Does not match a digit, or a space or other special character_ +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### `slug` + +.. column:: + +``` +**Regular expression applied**: `r"[a-z0-9]+(?:-[a-z0-9]+)*"` +**Cast type**: `str` +**Example matches**: + +- `/path/to/some-news-story` +- `/path/to/or-has-digits-123` + +*Added in v21.6* +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, article: str): + ... +``` +```` + +### `path` + +.. column:: + +``` +**Regular expression applied**: `r"[^/].*?"` +**Cast type**: `str` +**Example matches**: +- `/path/to/hello` +- `/path/to/hello.txt` +- `/path/to/hello/world.txt` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +.. warning:: + +``` +Because this will match on `/`, you should be careful and thoroughly test your patterns that use `path` so they do not capture traffic intended for another endpoint. Additionally, depending on how you use this type, you may be creating a path traversal vulnerability in your application. It is your job to protect your endpoint against this, but feel free to ask in our community channels for help if you need it :) +``` + +### `ymd` + +.. column:: + +``` +**Regular expression applied**: `r"^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))"` +**Cast type**: `datetime.date` +**Example matches**: + +- `/path/to/2021-03-28` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: datetime.date): + ... +``` +```` + +### `uuid` + +.. column:: + +``` +**Regular expression applied**: `r"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}"` +**Cast type**: `UUID` +**Example matches**: + +- `/path/to/123a123a-a12a-1a1a-a1a1-1a12a1a12345` +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: UUID): + ... +``` +```` + +### ext + +.. column:: + +``` +**Regular expression applied**: n/a +**Cast type**: *varies* +**Example matches**: +``` + +.. column:: + +```` +```python +@app.route("/path/to/") +async def handler(request, foo: str, ext: str): + ... +``` +```` + +| definition | example | filename | extension | +| ---------------------------------- | ----------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | + +File extensions can be matched using the special `ext` parameter type. It uses a special format that allows you to specify other types of parameter types as the file name, and one or more specific extensions as shown in the example table above. + +It does _not_ support the `path` parameter type. + +_Added in v22.3_ + +### regex + +.. column:: + +``` +**Regular expression applied**: _whatever you insert_ +**Cast type**: `str` +**Example matches**: + +- `/path/to/2021-01-01` + +This gives you the freedom to define specific matching patterns for your use case. + +In the example shown, we are looking for a date that is in `YYYY-MM-DD` format. +``` + +.. column:: + +```` +```python +@app.route(r"/path/to/") +async def handler(request, foo: str): + ... +``` +```` + +### Regex Matching + +More often than not, compared with complex routing, the above example is too simple, and we use a completely different routing matching pattern, so here we will explain the advanced usage of regex matching in detail. + +Sometimes, you want to match a part of a route: + +```text +/image/123456789.jpg +``` + +If you wanted to match the file pattern, but only capture the numeric portion, you need to do some regex fun 😄: + +```python +app.route(r"/image/\d+)\.jpg>") +``` + +Further, these should all be acceptable: + +```python +@app.get(r"/") # matching on the full pattern +@app.get(r"/") # defining a single matching group +@app.get(r"/[a-z]{3}).txt>") # defining a single named matching group +@app.get(r"/[a-z]{3}).(?:txt)>") # defining a single named matching group, with one or more non-matching groups +``` + +Also, if using a named matching group, it must be the same as the segment label. + +```python +@app.get(r"/\d+).jpg>") # OK +@app.get(r"/\d+).jpg>") # NOT OK +``` + +For more regular usage methods, please refer to [Regular expression operations](https://docs.python.org/3/library/re.html) + +## Generating a URL + +.. column:: + +``` +Sanic provides a method to generate URLs based on the handler method name: `app.url_for()`. This is useful if you want to avoid hardcoding url paths into your app; instead, you can just reference the handler name. +``` + +.. column:: + +```` +```python +@app.route('/') +async def index(request): + # generate a URL for the endpoint `post_handler` + url = app.url_for('post_handler', post_id=5) + + # Redirect to `/posts/5` + return redirect(url) + +@app.route('/posts/') +async def post_handler(request, post_id): + ... +``` +```` + +.. column:: + +``` +You can pass any arbitrary number of keyword arguments. Anything that is _not_ a request parameter will be implemented as a part of the query string. +``` + +.. column:: + +```` +```python +assert app.url_for( + "post_handler", + post_id=5, + arg_one="one", + arg_two="two", +) == "/posts/5?arg_one=one&arg_two=two" +``` +```` + +.. column:: + +``` +Also supported is passing multiple values for a single query key. +``` + +.. column:: + +```` +```python +assert app.url_for( + "post_handler", + post_id=5, + arg_one=["one", "two"], +) == "/posts/5?arg_one=one&arg_one=two" +``` +```` + +### Special keyword arguments + +See API Docs for more details. + +```python +app.url_for("post_handler", post_id=5, arg_one="one", _anchor="anchor") +# '/posts/5?arg_one=one#anchor' + +# _external requires you to pass an argument _server or set SERVER_NAME in app.config if not url will be same as no _external +app.url_for("post_handler", post_id=5, arg_one="one", _external=True) +# '//server/posts/5?arg_one=one' + +# when specifying _scheme, _external must be True +app.url_for("post_handler", post_id=5, arg_one="one", _scheme="http", _external=True) +# 'http://server/posts/5?arg_one=one' + +# you can pass all special arguments at once +app.url_for("post_handler", post_id=5, arg_one=["one", "two"], arg_two=2, _anchor="anchor", _scheme="http", _external=True, _server="another_server:8888") +# 'http://another_server:8888/posts/5?arg_one=one&arg_one=two&arg_two=2#anchor' +``` + +### Customizing a route name + +.. column:: + +``` +A custom route name can be used by passing a `name` argument while registering the route. +``` + +.. column:: + +```` +```python +@app.get("/get", name="get_handler") +def handler(request): + return text("OK") +``` +```` + +.. column:: + +``` +Now, use this custom name to retrieve the URL +``` + +.. column:: + +```` +```python +assert app.url_for("get_handler", foo="bar") == "/get?foo=bar" +``` +```` + +## Websockets routes + +.. column:: + +``` +Websocket routing works similar to HTTP methods. +``` + +.. column:: + +```` +```python +async def handler(request, ws): + message = "Start" + while True: + await ws.send(message) + message = await ws.recv() + +app.add_websocket_route(handler, "/test") +``` +```` + +.. column:: + +``` +It also has a convenience decorator. +``` + +.. column:: + +```` +```python +@app.websocket("/test") +async def handler(request, ws): + message = "Start" + while True: + await ws.send(message) + message = await ws.recv() +``` +```` + +Read the [websockets section](/guide/advanced/websockets.md) to learn more about how they work. + +## Strict slashes + +.. column:: + +``` +Sanic routes can be configured to strictly match on whether or not there is a trailing slash: `/`. This can be configured at a few levels and follows this order of precedence: + +1. Route +2. Blueprint +3. BlueprintGroup +4. Application +``` + +.. column:: + +```` +```python +# provide default strict_slashes value for all routes +app = Sanic(__file__, strict_slashes=True) +``` + +```python +# overwrite strict_slashes value for specific route +@app.get("/get", strict_slashes=False) +def handler(request): + return text("OK") +``` + +```python +# it also works for blueprints +bp = Blueprint(__file__, strict_slashes=True) + +@bp.get("/bp/get", strict_slashes=False) +def handler(request): + return text("OK") +``` + +```python +bp1 = Blueprint(name="bp1", url_prefix="/bp1") +bp2 = Blueprint( + name="bp2", + url_prefix="/bp2", + strict_slashes=False, +) + +# This will enforce strict slashes check on the routes +# under bp1 but ignore bp2 as that has an explicitly +# set the strict slashes check to false +group = Blueprint.group([bp1, bp2], strict_slashes=True) +``` +```` + +## Static files + +.. column:: + +``` +In order to serve static files from Sanic, use `app.static()`. + +The order of arguments is important: + +1. Route the files will be served from +2. Path to the files on the server + +See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic.static) for more details. +``` + +.. column:: + +```` +```python +app.static("/static/", "/path/to/directory/") +``` +```` + +.. tip:: + +``` +It is generally best practice to end your directory paths with a trailing slash (`/this/is/a/directory/`). This removes ambiguity by being more explicit. +``` + +.. column:: + +``` +You can also serve individual files. +``` + +.. column:: + +```` +```python +app.static("/", "/path/to/index.html") +``` +```` + +.. column:: + +``` +It is also sometimes helpful to name your endpoint +``` + +.. column:: + +```` +```python +app.static( + "/user/uploads/", + "/path/to/uploads/", + name="uploads", +) +``` +```` + +.. column:: + +``` +Retrieving the URLs works similar to handlers. But, we can also add the `filename` argument when we need a specific file inside a directory. +``` + +.. column:: + +```` +```python +assert app.url_for( + "static", + name="static", + filename="file.txt", +) == "/static/file.txt" +``` +```python +assert app.url_for( + "static", + name="uploads", + filename="image.png", +) == "/user/uploads/image.png" + +``` +```` + +.. tip:: + +```` +If you are going to have multiple `static()` routes, then it is *highly* suggested that you manually name them. This will almost certainly alleviate potential hard to discover bugs. + +```python +app.static("/user/uploads/", "/path/to/uploads/", name="uploads") +app.static("/user/profile/", "/path/to/profile/", name="profile_pics") +``` +```` + +#### Auto index serving + +.. column:: + +``` +If you have a directory of static files that should be served by an index page, you can provide the filename of the index. Now, when reaching that directory URL, the index page will be served. +``` + +.. column:: + +```` +```python +app.static("/foo/", "/path/to/foo/", index="index.html") +``` +```` + +_Added in v23.3_ + +#### File browser + +.. column:: + +``` +When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. +``` + +.. column:: + +```` +```python +app.static("/uploads/", "/path/to/dir", directory_view=True) +``` +```` + +You now have a browsable directory in your web browser: + +![image](/assets/images/directory-view.png) + +_Added in v23.3_ + +## Route context + +.. column:: + +``` +When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. +``` + +.. column:: + +```` +```python +@app.get("/1", ctx_label="something") +async def handler1(request): + ... + +@app.get("/2", ctx_label="something") +async def handler2(request): + ... + +@app.get("/99") +async def handler99(request): + ... + +@app.on_request +async def do_something(request): + if request.route.ctx.label == "something": + ... +``` +```` + +_Added in v21.12_ From 51b57b3cc298840c2135f315f45f2abceb3bf5bd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:07 +0200 Subject: [PATCH 052/698] New translations tasks.md (Japanese) --- guide/content/ja/guide/basics/tasks.md | 166 +++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 guide/content/ja/guide/basics/tasks.md diff --git a/guide/content/ja/guide/basics/tasks.md b/guide/content/ja/guide/basics/tasks.md new file mode 100644 index 0000000000..dd37abf98e --- /dev/null +++ b/guide/content/ja/guide/basics/tasks.md @@ -0,0 +1,166 @@ +--- +title: Background tasks +--- + +# Background tasks + +## Creating Tasks + +It is often desirable and very convenient to make usage of [tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) in async Python. Sanic provides a convenient method to add tasks to the currently **running** loop. It is somewhat similar to `asyncio.create_task`. For adding tasks before the 'App' loop is running, see next section. + +```python +async def notify_server_started_after_five_seconds(): + await asyncio.sleep(5) + print('Server successfully started!') + +app.add_task(notify_server_started_after_five_seconds()) +``` + +.. column:: + +``` +Sanic will attempt to automatically inject the app, passing it as an argument to the task. +``` + +.. column:: + +```` +```python +async def auto_inject(app): + await asyncio.sleep(5) + print(app.name) + +app.add_task(auto_inject) +``` +```` + +.. column:: + +``` +Or you can pass the `app` argument explicitly. +``` + +.. column:: + +```` +```python +async def explicit_inject(app): + await asyncio.sleep(5) + print(app.name) + +app.add_task(explicit_inject(app)) +``` +```` + +## Adding tasks before `app.run` + +It is possible to add background tasks before the App is run ie. before `app.run`. To add a task before the App is run, it is recommended to not pass the coroutine object (ie. one created by calling the `async` callable), but instead just pass the callable and Sanic will create the coroutine object on **each worker**. Note: the tasks that are added such are run as `before_server_start` jobs and thus run on every worker (and not in the main process). This has certain consequences, please read [this comment](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668) on [this issue](https://github.com/sanic-org/sanic/issues/2139) for further details. + +To add work on the main process, consider adding work to [`@app.main_process_start`](./listeners.md). Note: the workers won't start until this work is completed. + +.. column:: + +``` +Example to add a task before `app.run` +``` + +.. column:: + +```` +```python +async def slow_work(): + ... + +async def even_slower(num): + ... + +app = Sanic(...) +app.add_task(slow_work) # Note: we are passing the callable and not coroutine object ... +app.add_task(even_slower(10)) # ... or we can call the function and pass the coroutine. +app.run(...) +``` +```` + +## Named tasks + +.. column:: + +``` +When creating a task, you can ask Sanic to keep track of it for you by providing a `name`. +``` + +.. column:: + +```` +```python +app.add_task(slow_work, name="slow_task") +``` +```` + +.. column:: + +``` +You can now retrieve that task instance from anywhere in your application using `get_task`. +``` + +.. column:: + +```` +```python +task = app.get_task("slow_task") +``` +```` + +.. column:: + +``` +If that task needs to be cancelled, you can do that with `cancel_task`. Make sure that you `await` it. +``` + +.. column:: + +```` +```python +await app.cancel_task("slow_task") +``` +```` + +.. column:: + +``` +All registered tasks can be found in the `app.tasks` property. To prevent cancelled tasks from filling up, you may want to run `app.purge_tasks` that will clear out any completed or cancelled tasks. +``` + +.. column:: + +```` +```python +app.purge_tasks() +``` +```` + +This pattern can be particularly useful with `websockets`: + +```python +async def receiver(ws): + while True: + message = await ws.recv() + if not message: + break + print(f"Received: {message}") + +@app.websocket("/feed") +async def feed(request, ws): + task_name = f"receiver:{request.id}" + request.app.add_task(receiver(ws), name=task_name) + try: + while True: + await request.app.event("my.custom.event") + await ws.send("A message") + finally: + # When the websocket closes, let's cleanup the task + await request.app.cancel_task(task_name) + request.app.purge_tasks() +``` + +_Added in v21.12_ From fa44392f78990d242306b37d8325b147e2f02465 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:08 +0200 Subject: [PATCH 053/698] New translations tasks.md (Korean) --- guide/content/ko/guide/basics/tasks.md | 166 +++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 guide/content/ko/guide/basics/tasks.md diff --git a/guide/content/ko/guide/basics/tasks.md b/guide/content/ko/guide/basics/tasks.md new file mode 100644 index 0000000000..dd37abf98e --- /dev/null +++ b/guide/content/ko/guide/basics/tasks.md @@ -0,0 +1,166 @@ +--- +title: Background tasks +--- + +# Background tasks + +## Creating Tasks + +It is often desirable and very convenient to make usage of [tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) in async Python. Sanic provides a convenient method to add tasks to the currently **running** loop. It is somewhat similar to `asyncio.create_task`. For adding tasks before the 'App' loop is running, see next section. + +```python +async def notify_server_started_after_five_seconds(): + await asyncio.sleep(5) + print('Server successfully started!') + +app.add_task(notify_server_started_after_five_seconds()) +``` + +.. column:: + +``` +Sanic will attempt to automatically inject the app, passing it as an argument to the task. +``` + +.. column:: + +```` +```python +async def auto_inject(app): + await asyncio.sleep(5) + print(app.name) + +app.add_task(auto_inject) +``` +```` + +.. column:: + +``` +Or you can pass the `app` argument explicitly. +``` + +.. column:: + +```` +```python +async def explicit_inject(app): + await asyncio.sleep(5) + print(app.name) + +app.add_task(explicit_inject(app)) +``` +```` + +## Adding tasks before `app.run` + +It is possible to add background tasks before the App is run ie. before `app.run`. To add a task before the App is run, it is recommended to not pass the coroutine object (ie. one created by calling the `async` callable), but instead just pass the callable and Sanic will create the coroutine object on **each worker**. Note: the tasks that are added such are run as `before_server_start` jobs and thus run on every worker (and not in the main process). This has certain consequences, please read [this comment](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668) on [this issue](https://github.com/sanic-org/sanic/issues/2139) for further details. + +To add work on the main process, consider adding work to [`@app.main_process_start`](./listeners.md). Note: the workers won't start until this work is completed. + +.. column:: + +``` +Example to add a task before `app.run` +``` + +.. column:: + +```` +```python +async def slow_work(): + ... + +async def even_slower(num): + ... + +app = Sanic(...) +app.add_task(slow_work) # Note: we are passing the callable and not coroutine object ... +app.add_task(even_slower(10)) # ... or we can call the function and pass the coroutine. +app.run(...) +``` +```` + +## Named tasks + +.. column:: + +``` +When creating a task, you can ask Sanic to keep track of it for you by providing a `name`. +``` + +.. column:: + +```` +```python +app.add_task(slow_work, name="slow_task") +``` +```` + +.. column:: + +``` +You can now retrieve that task instance from anywhere in your application using `get_task`. +``` + +.. column:: + +```` +```python +task = app.get_task("slow_task") +``` +```` + +.. column:: + +``` +If that task needs to be cancelled, you can do that with `cancel_task`. Make sure that you `await` it. +``` + +.. column:: + +```` +```python +await app.cancel_task("slow_task") +``` +```` + +.. column:: + +``` +All registered tasks can be found in the `app.tasks` property. To prevent cancelled tasks from filling up, you may want to run `app.purge_tasks` that will clear out any completed or cancelled tasks. +``` + +.. column:: + +```` +```python +app.purge_tasks() +``` +```` + +This pattern can be particularly useful with `websockets`: + +```python +async def receiver(ws): + while True: + message = await ws.recv() + if not message: + break + print(f"Received: {message}") + +@app.websocket("/feed") +async def feed(request, ws): + task_name = f"receiver:{request.id}" + request.app.add_task(receiver(ws), name=task_name) + try: + while True: + await request.app.event("my.custom.event") + await ws.send("A message") + finally: + # When the websocket closes, let's cleanup the task + await request.app.cancel_task(task_name) + request.app.purge_tasks() +``` + +_Added in v21.12_ From f6e0a3c0cf919c67b45684045b18ca8667599e5b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:09 +0200 Subject: [PATCH 054/698] New translations tasks.md (Chinese Simplified) --- guide/content/zh/guide/basics/tasks.md | 166 +++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 guide/content/zh/guide/basics/tasks.md diff --git a/guide/content/zh/guide/basics/tasks.md b/guide/content/zh/guide/basics/tasks.md new file mode 100644 index 0000000000..dd37abf98e --- /dev/null +++ b/guide/content/zh/guide/basics/tasks.md @@ -0,0 +1,166 @@ +--- +title: Background tasks +--- + +# Background tasks + +## Creating Tasks + +It is often desirable and very convenient to make usage of [tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) in async Python. Sanic provides a convenient method to add tasks to the currently **running** loop. It is somewhat similar to `asyncio.create_task`. For adding tasks before the 'App' loop is running, see next section. + +```python +async def notify_server_started_after_five_seconds(): + await asyncio.sleep(5) + print('Server successfully started!') + +app.add_task(notify_server_started_after_five_seconds()) +``` + +.. column:: + +``` +Sanic will attempt to automatically inject the app, passing it as an argument to the task. +``` + +.. column:: + +```` +```python +async def auto_inject(app): + await asyncio.sleep(5) + print(app.name) + +app.add_task(auto_inject) +``` +```` + +.. column:: + +``` +Or you can pass the `app` argument explicitly. +``` + +.. column:: + +```` +```python +async def explicit_inject(app): + await asyncio.sleep(5) + print(app.name) + +app.add_task(explicit_inject(app)) +``` +```` + +## Adding tasks before `app.run` + +It is possible to add background tasks before the App is run ie. before `app.run`. To add a task before the App is run, it is recommended to not pass the coroutine object (ie. one created by calling the `async` callable), but instead just pass the callable and Sanic will create the coroutine object on **each worker**. Note: the tasks that are added such are run as `before_server_start` jobs and thus run on every worker (and not in the main process). This has certain consequences, please read [this comment](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668) on [this issue](https://github.com/sanic-org/sanic/issues/2139) for further details. + +To add work on the main process, consider adding work to [`@app.main_process_start`](./listeners.md). Note: the workers won't start until this work is completed. + +.. column:: + +``` +Example to add a task before `app.run` +``` + +.. column:: + +```` +```python +async def slow_work(): + ... + +async def even_slower(num): + ... + +app = Sanic(...) +app.add_task(slow_work) # Note: we are passing the callable and not coroutine object ... +app.add_task(even_slower(10)) # ... or we can call the function and pass the coroutine. +app.run(...) +``` +```` + +## Named tasks + +.. column:: + +``` +When creating a task, you can ask Sanic to keep track of it for you by providing a `name`. +``` + +.. column:: + +```` +```python +app.add_task(slow_work, name="slow_task") +``` +```` + +.. column:: + +``` +You can now retrieve that task instance from anywhere in your application using `get_task`. +``` + +.. column:: + +```` +```python +task = app.get_task("slow_task") +``` +```` + +.. column:: + +``` +If that task needs to be cancelled, you can do that with `cancel_task`. Make sure that you `await` it. +``` + +.. column:: + +```` +```python +await app.cancel_task("slow_task") +``` +```` + +.. column:: + +``` +All registered tasks can be found in the `app.tasks` property. To prevent cancelled tasks from filling up, you may want to run `app.purge_tasks` that will clear out any completed or cancelled tasks. +``` + +.. column:: + +```` +```python +app.purge_tasks() +``` +```` + +This pattern can be particularly useful with `websockets`: + +```python +async def receiver(ws): + while True: + message = await ws.recv() + if not message: + break + print(f"Received: {message}") + +@app.websocket("/feed") +async def feed(request, ws): + task_name = f"receiver:{request.id}" + request.app.add_task(receiver(ws), name=task_name) + try: + while True: + await request.app.event("my.custom.event") + await ws.send("A message") + finally: + # When the websocket closes, let's cleanup the task + await request.app.cancel_task(task_name) + request.app.purge_tasks() +``` + +_Added in v21.12_ From 77ce1707bb3de6c428e252f9fbdea530db88ed8e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:10 +0200 Subject: [PATCH 055/698] New translations blueprints.md (Japanese) --- .../ja/guide/best-practices/blueprints.md | 521 ++++++++++++++++++ 1 file changed, 521 insertions(+) create mode 100644 guide/content/ja/guide/best-practices/blueprints.md diff --git a/guide/content/ja/guide/best-practices/blueprints.md b/guide/content/ja/guide/best-practices/blueprints.md new file mode 100644 index 0000000000..7a3571058c --- /dev/null +++ b/guide/content/ja/guide/best-practices/blueprints.md @@ -0,0 +1,521 @@ +# Blueprints + +## Overview + +Blueprints are objects that can be used for sub-routing within an application. Instead of adding routes to the application instance, blueprints define similar methods for adding routes, which are then registered with the application in a flexible and pluggable manner. + +Blueprints are especially useful for larger applications, where your application logic can be broken down into several groups or areas of responsibility. + +## Creating and registering + +.. column:: + +``` +First, you must create a blueprint. It has a very similar API as the `Sanic()` app instance with many of the same decorators. +``` + +.. column:: + +```` +```python +# ./my_blueprint.py +from sanic.response import json +from sanic import Blueprint + +bp = Blueprint("my_blueprint") + +@bp.route("/") +async def bp_root(request): + return json({"my": "blueprint"}) +``` +```` + +.. column:: + +``` +Next, you register it with the app instance. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from my_blueprint import bp + +app = Sanic(__name__) +app.blueprint(bp) +``` +```` + +Blueprints also have the same `websocket()` decorator and `add_websocket_route` method for implementing websockets. + +.. column:: + +``` +Beginning in v21.12, a Blueprint may be registered before or after adding objects to it. Previously, only objects attached to the Blueprint at the time of registration would be loaded into application instance. +``` + +.. column:: + +```` +```python +app.blueprint(bp) + +@bp.route("/") +async def bp_root(request): + ... +``` +```` + +## Copying + +.. column:: + +``` +Blueprints along with everything that is attached to them can be copied to new instances using the `copy()` method. The only required argument is to pass it a new `name`. However, you could also use this to override any of the values from the old blueprint. +``` + +.. column:: + +```` +```python +v1 = Blueprint("Version1", version=1) + +@v1.route("/something") +def something(request): + pass + +v2 = v1.copy("Version2", version=2) + +app.blueprint(v1) +app.blueprint(v2) +``` + +``` +Available routes: +/v1/something +/v2/something + +``` +```` + +_Added in v21.9_ + +## Blueprint groups + +Blueprints may also be registered as part of a list or tuple, where the registrar will recursively cycle through any sub-sequences of blueprints and register them accordingly. The Blueprint.group method is provided to simplify this process, allowing a ‘mock’ backend directory structure mimicking what’s seen from the front end. Consider this (quite contrived) example: + +```text +api/ +├──content/ +│ ├──authors.py +│ ├──static.py +│ └──__init__.py +├──info.py +└──__init__.py +app.py +``` + +.. column:: + +``` +#### First blueprint +``` + +.. column:: + +```` +```python +# api/content/authors.py +from sanic import Blueprint + +authors = Blueprint("content_authors", url_prefix="/authors") +``` +```` + +.. column:: + +``` +#### Second blueprint +``` + +.. column:: + +```` +```python +# api/content/static.py +from sanic import Blueprint + +static = Blueprint("content_static", url_prefix="/static") +``` +```` + +.. column:: + +``` +#### Blueprint group +``` + +.. column:: + +```` +```python +# api/content/__init__.py +from sanic import Blueprint +from .static import static +from .authors import authors + +content = Blueprint.group(static, authors, url_prefix="/content") +``` +```` + +.. column:: + +``` +#### Third blueprint +``` + +.. column:: + +```` +```python +# api/info.py +from sanic import Blueprint + +info = Blueprint("info", url_prefix="/info") +``` +```` + +.. column:: + +``` +#### Another blueprint group +``` + +.. column:: + +```` +```python +# api/__init__.py +from sanic import Blueprint +from .content import content +from .info import info + +api = Blueprint.group(content, info, url_prefix="/api") +``` +```` + +.. column:: + +``` +#### Main server + +All blueprints are now registered +``` + +.. column:: + +```` +```python +# app.py +from sanic import Sanic +from .api import api + +app = Sanic(__name__) +app.blueprint(api) +``` +```` + +### Blueprint group prefixes and composability + +As shown in the code above, when you create a group of blueprints you can extend the URL prefix of all the blueprints in the group by passing the `url_prefix` argument to the `Blueprint.group` method. This is useful for creating a mock directory structure for your API. + +In addition, there is a `name_prefix` argument that can be used to make blueprints reusable and composable. The is specifically necessary when applying a single blueprint to multiple groups. By doing this, the blueprint will be registered with a unique name for each group, which allows the blueprint to be registered multiple times and have its routes each properly named with a unique identifier. + +.. column:: + +``` +Consider this example. The routes built will be named as follows: +- `TestApp.group-a_bp1.route1` +- `TestApp.group-a_bp2.route2` +- `TestApp.group-b_bp1.route1` +- `TestApp.group-b_bp2.route2` +``` + +.. column:: + +```` +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +bp1.add_route(lambda _: ..., "/", name="route1") +bp2.add_route(lambda _: ..., "/", name="route2") + +group_a = Blueprint.group( + bp1, bp2, url_prefix="/group-a", name_prefix="group-a" +) +group_b = Blueprint.group( + bp1, bp2, url_prefix="/group-b", name_prefix="group-b" +) + +app = Sanic("TestApp") +app.blueprint(group_a) +app.blueprint(group_b) +``` +```` + +_Name prefixing added in v23.6_ + +## Middleware + +.. column:: + +``` +Blueprints can also have middleware that is specifically registered for its endpoints only. +``` + +.. column:: + +```` +```python +@bp.middleware +async def print_on_request(request): + print("I am a spy") + +@bp.middleware("request") +async def halt_request(request): + return text("I halted the request") + +@bp.middleware("response") +async def halt_response(request, response): + return text("I halted the response") +``` +```` + +.. column:: + +``` +Similarly, using blueprint groups, it is possible to apply middleware to an entire group of nested blueprints. +``` + +.. column:: + +```` +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +@bp1.middleware("request") +async def bp1_only_middleware(request): + print("applied on Blueprint : bp1 Only") + +@bp1.route("/") +async def bp1_route(request): + return text("bp1") + +@bp2.route("/") +async def bp2_route(request, param): + return text(param) + +group = Blueprint.group(bp1, bp2) + +@group.middleware("request") +async def group_middleware(request): + print("common middleware applied for both bp1 and bp2") + +# Register Blueprint group under the app +app.blueprint(group) +``` +```` + +## Exceptions + +.. column:: + +``` +Just like other [exception handling](./exceptions.md), you can define blueprint specific handlers. +``` + +.. column:: + +```` +```python +@bp.exception(NotFound) +def ignore_404s(request, exception): + return text("Yep, I totally found the page: {}".format(request.url)) +``` +```` + +## Static files + +.. column:: + +``` +Blueprints can also have their own static handlers +``` + +.. column:: + +```` +```python +bp = Blueprint("bp", url_prefix="/bp") +bp.static("/web/path", "/folder/to/serve") +bp.static("/web/path", "/folder/to/server", name="uploads") +``` +```` + +.. column:: + +``` +Which can then be retrieved using `url_for()`. See [routing](/guide/basics/routing.md) for more information. +``` + +.. column:: + +```` +```python +>>> print(app.url_for("static", name="bp.uploads", filename="file.txt")) +'/bp/web/path/file.txt' +``` +```` + +## Listeners + +.. column:: + +``` +Blueprints can also implement [listeners](/guide/basics/listeners.md). +``` + +.. column:: + +```` +```python +@bp.listener("before_server_start") +async def before_server_start(app, loop): + ... + +@bp.listener("after_server_stop") +async def after_server_stop(app, loop): + ... +``` +```` + +## Versioning + +As discussed in the [versioning section](/guide/advanced/versioning.md), blueprints can be used to implement different versions of a web API. + +.. column:: + +``` +The `version` will be prepended to the routes as `/v1` or `/v2`, etc. +``` + +.. column:: + +```` +```python +auth1 = Blueprint("auth", url_prefix="/auth", version=1) +auth2 = Blueprint("auth", url_prefix="/auth", version=2) +``` +```` + +.. column:: + +``` +When we register our blueprints on the app, the routes `/v1/auth` and `/v2/auth` will now point to the individual blueprints, which allows the creation of sub-sites for each API version. +``` + +.. column:: + +```` +```python +from auth_blueprints import auth1, auth2 + +app = Sanic(__name__) +app.blueprint(auth1) +app.blueprint(auth2) +``` +```` + +.. column:: + +``` +It is also possible to group the blueprints under a `BlueprintGroup` entity and version multiple of them together at the +same time. +``` + +.. column:: + +```` +```python +auth = Blueprint("auth", url_prefix="/auth") +metrics = Blueprint("metrics", url_prefix="/metrics") + +group = Blueprint.group(auth, metrics, version="v1") + +# This will provide APIs prefixed with the following URL path +# /v1/auth/ and /v1/metrics +``` +```` + +## Composable + +A `Blueprint` may be registered to multiple groups, and each of `BlueprintGroup` itself could be registered and nested further. This creates a limitless possibility `Blueprint` composition. + +_Added in v21.6_ + +.. column:: + +``` +Take a look at this example and see how the two handlers are actually mounted as five (5) distinct routes. +``` + +.. column:: + +```` +```python +app = Sanic(__name__) +blueprint_1 = Blueprint("blueprint_1", url_prefix="/bp1") +blueprint_2 = Blueprint("blueprint_2", url_prefix="/bp2") +group = Blueprint.group( + blueprint_1, + blueprint_2, + version=1, + version_prefix="/api/v", + url_prefix="/grouped", + strict_slashes=True, +) +primary = Blueprint.group(group, url_prefix="/primary") + +@blueprint_1.route("/") +def blueprint_1_default_route(request): + return text("BP1_OK") + +@blueprint_2.route("/") +def blueprint_2_default_route(request): + return text("BP2_OK") + +app.blueprint(group) +app.blueprint(primary) +app.blueprint(blueprint_1) + +# The mounted paths: +# /api/v1/grouped/bp1/ +# /api/v1/grouped/bp2/ +# /api/v1/primary/grouped/bp1 +# /api/v1/primary/grouped/bp2 +# /bp1 + +``` +```` + +## Generating a URL + +When generating a url with `url_for()`, the endpoint name will be in the form: + +```text +{blueprint_name}.{handler_name} +``` From 19c6602a985510ae176850dc6cd441e09e8d01a0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:11 +0200 Subject: [PATCH 056/698] New translations blueprints.md (Korean) --- .../ko/guide/best-practices/blueprints.md | 521 ++++++++++++++++++ 1 file changed, 521 insertions(+) create mode 100644 guide/content/ko/guide/best-practices/blueprints.md diff --git a/guide/content/ko/guide/best-practices/blueprints.md b/guide/content/ko/guide/best-practices/blueprints.md new file mode 100644 index 0000000000..7a3571058c --- /dev/null +++ b/guide/content/ko/guide/best-practices/blueprints.md @@ -0,0 +1,521 @@ +# Blueprints + +## Overview + +Blueprints are objects that can be used for sub-routing within an application. Instead of adding routes to the application instance, blueprints define similar methods for adding routes, which are then registered with the application in a flexible and pluggable manner. + +Blueprints are especially useful for larger applications, where your application logic can be broken down into several groups or areas of responsibility. + +## Creating and registering + +.. column:: + +``` +First, you must create a blueprint. It has a very similar API as the `Sanic()` app instance with many of the same decorators. +``` + +.. column:: + +```` +```python +# ./my_blueprint.py +from sanic.response import json +from sanic import Blueprint + +bp = Blueprint("my_blueprint") + +@bp.route("/") +async def bp_root(request): + return json({"my": "blueprint"}) +``` +```` + +.. column:: + +``` +Next, you register it with the app instance. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from my_blueprint import bp + +app = Sanic(__name__) +app.blueprint(bp) +``` +```` + +Blueprints also have the same `websocket()` decorator and `add_websocket_route` method for implementing websockets. + +.. column:: + +``` +Beginning in v21.12, a Blueprint may be registered before or after adding objects to it. Previously, only objects attached to the Blueprint at the time of registration would be loaded into application instance. +``` + +.. column:: + +```` +```python +app.blueprint(bp) + +@bp.route("/") +async def bp_root(request): + ... +``` +```` + +## Copying + +.. column:: + +``` +Blueprints along with everything that is attached to them can be copied to new instances using the `copy()` method. The only required argument is to pass it a new `name`. However, you could also use this to override any of the values from the old blueprint. +``` + +.. column:: + +```` +```python +v1 = Blueprint("Version1", version=1) + +@v1.route("/something") +def something(request): + pass + +v2 = v1.copy("Version2", version=2) + +app.blueprint(v1) +app.blueprint(v2) +``` + +``` +Available routes: +/v1/something +/v2/something + +``` +```` + +_Added in v21.9_ + +## Blueprint groups + +Blueprints may also be registered as part of a list or tuple, where the registrar will recursively cycle through any sub-sequences of blueprints and register them accordingly. The Blueprint.group method is provided to simplify this process, allowing a ‘mock’ backend directory structure mimicking what’s seen from the front end. Consider this (quite contrived) example: + +```text +api/ +├──content/ +│ ├──authors.py +│ ├──static.py +│ └──__init__.py +├──info.py +└──__init__.py +app.py +``` + +.. column:: + +``` +#### First blueprint +``` + +.. column:: + +```` +```python +# api/content/authors.py +from sanic import Blueprint + +authors = Blueprint("content_authors", url_prefix="/authors") +``` +```` + +.. column:: + +``` +#### Second blueprint +``` + +.. column:: + +```` +```python +# api/content/static.py +from sanic import Blueprint + +static = Blueprint("content_static", url_prefix="/static") +``` +```` + +.. column:: + +``` +#### Blueprint group +``` + +.. column:: + +```` +```python +# api/content/__init__.py +from sanic import Blueprint +from .static import static +from .authors import authors + +content = Blueprint.group(static, authors, url_prefix="/content") +``` +```` + +.. column:: + +``` +#### Third blueprint +``` + +.. column:: + +```` +```python +# api/info.py +from sanic import Blueprint + +info = Blueprint("info", url_prefix="/info") +``` +```` + +.. column:: + +``` +#### Another blueprint group +``` + +.. column:: + +```` +```python +# api/__init__.py +from sanic import Blueprint +from .content import content +from .info import info + +api = Blueprint.group(content, info, url_prefix="/api") +``` +```` + +.. column:: + +``` +#### Main server + +All blueprints are now registered +``` + +.. column:: + +```` +```python +# app.py +from sanic import Sanic +from .api import api + +app = Sanic(__name__) +app.blueprint(api) +``` +```` + +### Blueprint group prefixes and composability + +As shown in the code above, when you create a group of blueprints you can extend the URL prefix of all the blueprints in the group by passing the `url_prefix` argument to the `Blueprint.group` method. This is useful for creating a mock directory structure for your API. + +In addition, there is a `name_prefix` argument that can be used to make blueprints reusable and composable. The is specifically necessary when applying a single blueprint to multiple groups. By doing this, the blueprint will be registered with a unique name for each group, which allows the blueprint to be registered multiple times and have its routes each properly named with a unique identifier. + +.. column:: + +``` +Consider this example. The routes built will be named as follows: +- `TestApp.group-a_bp1.route1` +- `TestApp.group-a_bp2.route2` +- `TestApp.group-b_bp1.route1` +- `TestApp.group-b_bp2.route2` +``` + +.. column:: + +```` +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +bp1.add_route(lambda _: ..., "/", name="route1") +bp2.add_route(lambda _: ..., "/", name="route2") + +group_a = Blueprint.group( + bp1, bp2, url_prefix="/group-a", name_prefix="group-a" +) +group_b = Blueprint.group( + bp1, bp2, url_prefix="/group-b", name_prefix="group-b" +) + +app = Sanic("TestApp") +app.blueprint(group_a) +app.blueprint(group_b) +``` +```` + +_Name prefixing added in v23.6_ + +## Middleware + +.. column:: + +``` +Blueprints can also have middleware that is specifically registered for its endpoints only. +``` + +.. column:: + +```` +```python +@bp.middleware +async def print_on_request(request): + print("I am a spy") + +@bp.middleware("request") +async def halt_request(request): + return text("I halted the request") + +@bp.middleware("response") +async def halt_response(request, response): + return text("I halted the response") +``` +```` + +.. column:: + +``` +Similarly, using blueprint groups, it is possible to apply middleware to an entire group of nested blueprints. +``` + +.. column:: + +```` +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +@bp1.middleware("request") +async def bp1_only_middleware(request): + print("applied on Blueprint : bp1 Only") + +@bp1.route("/") +async def bp1_route(request): + return text("bp1") + +@bp2.route("/") +async def bp2_route(request, param): + return text(param) + +group = Blueprint.group(bp1, bp2) + +@group.middleware("request") +async def group_middleware(request): + print("common middleware applied for both bp1 and bp2") + +# Register Blueprint group under the app +app.blueprint(group) +``` +```` + +## Exceptions + +.. column:: + +``` +Just like other [exception handling](./exceptions.md), you can define blueprint specific handlers. +``` + +.. column:: + +```` +```python +@bp.exception(NotFound) +def ignore_404s(request, exception): + return text("Yep, I totally found the page: {}".format(request.url)) +``` +```` + +## Static files + +.. column:: + +``` +Blueprints can also have their own static handlers +``` + +.. column:: + +```` +```python +bp = Blueprint("bp", url_prefix="/bp") +bp.static("/web/path", "/folder/to/serve") +bp.static("/web/path", "/folder/to/server", name="uploads") +``` +```` + +.. column:: + +``` +Which can then be retrieved using `url_for()`. See [routing](/guide/basics/routing.md) for more information. +``` + +.. column:: + +```` +```python +>>> print(app.url_for("static", name="bp.uploads", filename="file.txt")) +'/bp/web/path/file.txt' +``` +```` + +## Listeners + +.. column:: + +``` +Blueprints can also implement [listeners](/guide/basics/listeners.md). +``` + +.. column:: + +```` +```python +@bp.listener("before_server_start") +async def before_server_start(app, loop): + ... + +@bp.listener("after_server_stop") +async def after_server_stop(app, loop): + ... +``` +```` + +## Versioning + +As discussed in the [versioning section](/guide/advanced/versioning.md), blueprints can be used to implement different versions of a web API. + +.. column:: + +``` +The `version` will be prepended to the routes as `/v1` or `/v2`, etc. +``` + +.. column:: + +```` +```python +auth1 = Blueprint("auth", url_prefix="/auth", version=1) +auth2 = Blueprint("auth", url_prefix="/auth", version=2) +``` +```` + +.. column:: + +``` +When we register our blueprints on the app, the routes `/v1/auth` and `/v2/auth` will now point to the individual blueprints, which allows the creation of sub-sites for each API version. +``` + +.. column:: + +```` +```python +from auth_blueprints import auth1, auth2 + +app = Sanic(__name__) +app.blueprint(auth1) +app.blueprint(auth2) +``` +```` + +.. column:: + +``` +It is also possible to group the blueprints under a `BlueprintGroup` entity and version multiple of them together at the +same time. +``` + +.. column:: + +```` +```python +auth = Blueprint("auth", url_prefix="/auth") +metrics = Blueprint("metrics", url_prefix="/metrics") + +group = Blueprint.group(auth, metrics, version="v1") + +# This will provide APIs prefixed with the following URL path +# /v1/auth/ and /v1/metrics +``` +```` + +## Composable + +A `Blueprint` may be registered to multiple groups, and each of `BlueprintGroup` itself could be registered and nested further. This creates a limitless possibility `Blueprint` composition. + +_Added in v21.6_ + +.. column:: + +``` +Take a look at this example and see how the two handlers are actually mounted as five (5) distinct routes. +``` + +.. column:: + +```` +```python +app = Sanic(__name__) +blueprint_1 = Blueprint("blueprint_1", url_prefix="/bp1") +blueprint_2 = Blueprint("blueprint_2", url_prefix="/bp2") +group = Blueprint.group( + blueprint_1, + blueprint_2, + version=1, + version_prefix="/api/v", + url_prefix="/grouped", + strict_slashes=True, +) +primary = Blueprint.group(group, url_prefix="/primary") + +@blueprint_1.route("/") +def blueprint_1_default_route(request): + return text("BP1_OK") + +@blueprint_2.route("/") +def blueprint_2_default_route(request): + return text("BP2_OK") + +app.blueprint(group) +app.blueprint(primary) +app.blueprint(blueprint_1) + +# The mounted paths: +# /api/v1/grouped/bp1/ +# /api/v1/grouped/bp2/ +# /api/v1/primary/grouped/bp1 +# /api/v1/primary/grouped/bp2 +# /bp1 + +``` +```` + +## Generating a URL + +When generating a url with `url_for()`, the endpoint name will be in the form: + +```text +{blueprint_name}.{handler_name} +``` From 82b3fe1ca48bbc931c08756ebd4857f28d9b3bd1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:12 +0200 Subject: [PATCH 057/698] New translations blueprints.md (Chinese Simplified) --- .../zh/guide/best-practices/blueprints.md | 521 ++++++++++++++++++ 1 file changed, 521 insertions(+) create mode 100644 guide/content/zh/guide/best-practices/blueprints.md diff --git a/guide/content/zh/guide/best-practices/blueprints.md b/guide/content/zh/guide/best-practices/blueprints.md new file mode 100644 index 0000000000..7a3571058c --- /dev/null +++ b/guide/content/zh/guide/best-practices/blueprints.md @@ -0,0 +1,521 @@ +# Blueprints + +## Overview + +Blueprints are objects that can be used for sub-routing within an application. Instead of adding routes to the application instance, blueprints define similar methods for adding routes, which are then registered with the application in a flexible and pluggable manner. + +Blueprints are especially useful for larger applications, where your application logic can be broken down into several groups or areas of responsibility. + +## Creating and registering + +.. column:: + +``` +First, you must create a blueprint. It has a very similar API as the `Sanic()` app instance with many of the same decorators. +``` + +.. column:: + +```` +```python +# ./my_blueprint.py +from sanic.response import json +from sanic import Blueprint + +bp = Blueprint("my_blueprint") + +@bp.route("/") +async def bp_root(request): + return json({"my": "blueprint"}) +``` +```` + +.. column:: + +``` +Next, you register it with the app instance. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from my_blueprint import bp + +app = Sanic(__name__) +app.blueprint(bp) +``` +```` + +Blueprints also have the same `websocket()` decorator and `add_websocket_route` method for implementing websockets. + +.. column:: + +``` +Beginning in v21.12, a Blueprint may be registered before or after adding objects to it. Previously, only objects attached to the Blueprint at the time of registration would be loaded into application instance. +``` + +.. column:: + +```` +```python +app.blueprint(bp) + +@bp.route("/") +async def bp_root(request): + ... +``` +```` + +## Copying + +.. column:: + +``` +Blueprints along with everything that is attached to them can be copied to new instances using the `copy()` method. The only required argument is to pass it a new `name`. However, you could also use this to override any of the values from the old blueprint. +``` + +.. column:: + +```` +```python +v1 = Blueprint("Version1", version=1) + +@v1.route("/something") +def something(request): + pass + +v2 = v1.copy("Version2", version=2) + +app.blueprint(v1) +app.blueprint(v2) +``` + +``` +Available routes: +/v1/something +/v2/something + +``` +```` + +_Added in v21.9_ + +## Blueprint groups + +Blueprints may also be registered as part of a list or tuple, where the registrar will recursively cycle through any sub-sequences of blueprints and register them accordingly. The Blueprint.group method is provided to simplify this process, allowing a ‘mock’ backend directory structure mimicking what’s seen from the front end. Consider this (quite contrived) example: + +```text +api/ +├──content/ +│ ├──authors.py +│ ├──static.py +│ └──__init__.py +├──info.py +└──__init__.py +app.py +``` + +.. column:: + +``` +#### First blueprint +``` + +.. column:: + +```` +```python +# api/content/authors.py +from sanic import Blueprint + +authors = Blueprint("content_authors", url_prefix="/authors") +``` +```` + +.. column:: + +``` +#### Second blueprint +``` + +.. column:: + +```` +```python +# api/content/static.py +from sanic import Blueprint + +static = Blueprint("content_static", url_prefix="/static") +``` +```` + +.. column:: + +``` +#### Blueprint group +``` + +.. column:: + +```` +```python +# api/content/__init__.py +from sanic import Blueprint +from .static import static +from .authors import authors + +content = Blueprint.group(static, authors, url_prefix="/content") +``` +```` + +.. column:: + +``` +#### Third blueprint +``` + +.. column:: + +```` +```python +# api/info.py +from sanic import Blueprint + +info = Blueprint("info", url_prefix="/info") +``` +```` + +.. column:: + +``` +#### Another blueprint group +``` + +.. column:: + +```` +```python +# api/__init__.py +from sanic import Blueprint +from .content import content +from .info import info + +api = Blueprint.group(content, info, url_prefix="/api") +``` +```` + +.. column:: + +``` +#### Main server + +All blueprints are now registered +``` + +.. column:: + +```` +```python +# app.py +from sanic import Sanic +from .api import api + +app = Sanic(__name__) +app.blueprint(api) +``` +```` + +### Blueprint group prefixes and composability + +As shown in the code above, when you create a group of blueprints you can extend the URL prefix of all the blueprints in the group by passing the `url_prefix` argument to the `Blueprint.group` method. This is useful for creating a mock directory structure for your API. + +In addition, there is a `name_prefix` argument that can be used to make blueprints reusable and composable. The is specifically necessary when applying a single blueprint to multiple groups. By doing this, the blueprint will be registered with a unique name for each group, which allows the blueprint to be registered multiple times and have its routes each properly named with a unique identifier. + +.. column:: + +``` +Consider this example. The routes built will be named as follows: +- `TestApp.group-a_bp1.route1` +- `TestApp.group-a_bp2.route2` +- `TestApp.group-b_bp1.route1` +- `TestApp.group-b_bp2.route2` +``` + +.. column:: + +```` +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +bp1.add_route(lambda _: ..., "/", name="route1") +bp2.add_route(lambda _: ..., "/", name="route2") + +group_a = Blueprint.group( + bp1, bp2, url_prefix="/group-a", name_prefix="group-a" +) +group_b = Blueprint.group( + bp1, bp2, url_prefix="/group-b", name_prefix="group-b" +) + +app = Sanic("TestApp") +app.blueprint(group_a) +app.blueprint(group_b) +``` +```` + +_Name prefixing added in v23.6_ + +## Middleware + +.. column:: + +``` +Blueprints can also have middleware that is specifically registered for its endpoints only. +``` + +.. column:: + +```` +```python +@bp.middleware +async def print_on_request(request): + print("I am a spy") + +@bp.middleware("request") +async def halt_request(request): + return text("I halted the request") + +@bp.middleware("response") +async def halt_response(request, response): + return text("I halted the response") +``` +```` + +.. column:: + +``` +Similarly, using blueprint groups, it is possible to apply middleware to an entire group of nested blueprints. +``` + +.. column:: + +```` +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +@bp1.middleware("request") +async def bp1_only_middleware(request): + print("applied on Blueprint : bp1 Only") + +@bp1.route("/") +async def bp1_route(request): + return text("bp1") + +@bp2.route("/") +async def bp2_route(request, param): + return text(param) + +group = Blueprint.group(bp1, bp2) + +@group.middleware("request") +async def group_middleware(request): + print("common middleware applied for both bp1 and bp2") + +# Register Blueprint group under the app +app.blueprint(group) +``` +```` + +## Exceptions + +.. column:: + +``` +Just like other [exception handling](./exceptions.md), you can define blueprint specific handlers. +``` + +.. column:: + +```` +```python +@bp.exception(NotFound) +def ignore_404s(request, exception): + return text("Yep, I totally found the page: {}".format(request.url)) +``` +```` + +## Static files + +.. column:: + +``` +Blueprints can also have their own static handlers +``` + +.. column:: + +```` +```python +bp = Blueprint("bp", url_prefix="/bp") +bp.static("/web/path", "/folder/to/serve") +bp.static("/web/path", "/folder/to/server", name="uploads") +``` +```` + +.. column:: + +``` +Which can then be retrieved using `url_for()`. See [routing](/guide/basics/routing.md) for more information. +``` + +.. column:: + +```` +```python +>>> print(app.url_for("static", name="bp.uploads", filename="file.txt")) +'/bp/web/path/file.txt' +``` +```` + +## Listeners + +.. column:: + +``` +Blueprints can also implement [listeners](/guide/basics/listeners.md). +``` + +.. column:: + +```` +```python +@bp.listener("before_server_start") +async def before_server_start(app, loop): + ... + +@bp.listener("after_server_stop") +async def after_server_stop(app, loop): + ... +``` +```` + +## Versioning + +As discussed in the [versioning section](/guide/advanced/versioning.md), blueprints can be used to implement different versions of a web API. + +.. column:: + +``` +The `version` will be prepended to the routes as `/v1` or `/v2`, etc. +``` + +.. column:: + +```` +```python +auth1 = Blueprint("auth", url_prefix="/auth", version=1) +auth2 = Blueprint("auth", url_prefix="/auth", version=2) +``` +```` + +.. column:: + +``` +When we register our blueprints on the app, the routes `/v1/auth` and `/v2/auth` will now point to the individual blueprints, which allows the creation of sub-sites for each API version. +``` + +.. column:: + +```` +```python +from auth_blueprints import auth1, auth2 + +app = Sanic(__name__) +app.blueprint(auth1) +app.blueprint(auth2) +``` +```` + +.. column:: + +``` +It is also possible to group the blueprints under a `BlueprintGroup` entity and version multiple of them together at the +same time. +``` + +.. column:: + +```` +```python +auth = Blueprint("auth", url_prefix="/auth") +metrics = Blueprint("metrics", url_prefix="/metrics") + +group = Blueprint.group(auth, metrics, version="v1") + +# This will provide APIs prefixed with the following URL path +# /v1/auth/ and /v1/metrics +``` +```` + +## Composable + +A `Blueprint` may be registered to multiple groups, and each of `BlueprintGroup` itself could be registered and nested further. This creates a limitless possibility `Blueprint` composition. + +_Added in v21.6_ + +.. column:: + +``` +Take a look at this example and see how the two handlers are actually mounted as five (5) distinct routes. +``` + +.. column:: + +```` +```python +app = Sanic(__name__) +blueprint_1 = Blueprint("blueprint_1", url_prefix="/bp1") +blueprint_2 = Blueprint("blueprint_2", url_prefix="/bp2") +group = Blueprint.group( + blueprint_1, + blueprint_2, + version=1, + version_prefix="/api/v", + url_prefix="/grouped", + strict_slashes=True, +) +primary = Blueprint.group(group, url_prefix="/primary") + +@blueprint_1.route("/") +def blueprint_1_default_route(request): + return text("BP1_OK") + +@blueprint_2.route("/") +def blueprint_2_default_route(request): + return text("BP2_OK") + +app.blueprint(group) +app.blueprint(primary) +app.blueprint(blueprint_1) + +# The mounted paths: +# /api/v1/grouped/bp1/ +# /api/v1/grouped/bp2/ +# /api/v1/primary/grouped/bp1 +# /api/v1/primary/grouped/bp2 +# /bp1 + +``` +```` + +## Generating a URL + +When generating a url with `url_for()`, the endpoint name will be in the form: + +```text +{blueprint_name}.{handler_name} +``` From f0f7736149b459b9d78b101ab504b89cdf0e8567 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:13 +0200 Subject: [PATCH 058/698] New translations decorators.md (Japanese) --- .../ja/guide/best-practices/decorators.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 guide/content/ja/guide/best-practices/decorators.md diff --git a/guide/content/ja/guide/best-practices/decorators.md b/guide/content/ja/guide/best-practices/decorators.md new file mode 100644 index 0000000000..3f1bfdf6c0 --- /dev/null +++ b/guide/content/ja/guide/best-practices/decorators.md @@ -0,0 +1,195 @@ +# Decorators + +One of the best ways to create a consistent and DRY web API is to make use of decorators to remove functionality from the handlers, and make it repeatable across your views. + +.. column:: + +``` +Therefore, it is very common to see a Sanic view handler with several decorators on it. +``` + +.. column:: + +```` +```python +@app.get("/orders") +@authorized("view_order") +@validate_list_params() +@inject_user() +async def get_order_details(request, params, user): + ... +``` +```` + +## Example + +Here is a starter template to help you create decorators. + +In this example, let’s say you want to check that a user is authorized to access a particular endpoint. You can create a decorator that wraps a handler function, checks a request if the client is authorized to access a resource, and sends the appropriate response. + +```python +from functools import wraps +from sanic.response import json + +def authorized(): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + # run some method that checks the request + # for the client's authorization status + is_authorized = await check_request_for_authorization_status(request) + + if is_authorized: + # the user is authorized. + # run the handler method and return the response + response = await f(request, *args, **kwargs) + return response + else: + # the user is not authorized. + return json({"status": "not_authorized"}, 403) + return decorated_function + return decorator + +@app.route("/") +@authorized() +async def test(request): + return json({"status": "authorized"}) +``` + +## Templates + +Decorators are **fundamental** to building applications with Sanic. They increase the portability and maintainablity of your code. + +In paraphrasing the Zen of Python: "[decorators] are one honking great idea -- let's do more of those!" + +To make it easier to implement them, here are three examples of copy/pastable code to get you started. + +.. column:: + +``` +Don't forget to add these import statements. Although it is *not* necessary, using `@wraps` helps keep some of the metadata of your function intact. [See docs](https://docs.python.org/3/library/functools.html#functools.wraps). Also, we use the `isawaitable` pattern here to allow the route handlers to by regular or asynchronous functions. +``` + +.. column:: + +```` +```python +from inspect import isawaitable +from functools import wraps +``` +```` + +### With args + +.. column:: + +```` +Often, you will want a decorator that will *always* need arguments. Therefore, when it is implemented you will always be calling it. + +```python +@app.get("/") +@foobar(1, 2) +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(arg1, arg2): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator +``` +```` + +### Without args + +.. column:: + +```` +Sometimes you want a decorator that will not take arguments. When this is the case, it is a nice convenience not to have to call it + +```python +@app.get("/") +@foobar +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(func): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator(func) +``` +```` + +### With or Without args + +.. column:: + +```` +If you want a decorator with the ability to be called or not, you can follow this pattern. Using keyword only arguments is not necessary, but might make implementation simpler. + +```python +@app.get("/") +@foobar(arg1=1, arg2=2) +async def handler(request: Request): + return text("hi") +``` + +```python +@app.get("/") +@foobar +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(maybe_func=None, *, arg1=None, arg2=None): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator(maybe_func) if maybe_func else decorator +``` +```` From 7fe55e76b4b9f04b9e97db97dcd36885a77ea4f9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:14 +0200 Subject: [PATCH 059/698] New translations decorators.md (Korean) --- .../ko/guide/best-practices/decorators.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 guide/content/ko/guide/best-practices/decorators.md diff --git a/guide/content/ko/guide/best-practices/decorators.md b/guide/content/ko/guide/best-practices/decorators.md new file mode 100644 index 0000000000..3f1bfdf6c0 --- /dev/null +++ b/guide/content/ko/guide/best-practices/decorators.md @@ -0,0 +1,195 @@ +# Decorators + +One of the best ways to create a consistent and DRY web API is to make use of decorators to remove functionality from the handlers, and make it repeatable across your views. + +.. column:: + +``` +Therefore, it is very common to see a Sanic view handler with several decorators on it. +``` + +.. column:: + +```` +```python +@app.get("/orders") +@authorized("view_order") +@validate_list_params() +@inject_user() +async def get_order_details(request, params, user): + ... +``` +```` + +## Example + +Here is a starter template to help you create decorators. + +In this example, let’s say you want to check that a user is authorized to access a particular endpoint. You can create a decorator that wraps a handler function, checks a request if the client is authorized to access a resource, and sends the appropriate response. + +```python +from functools import wraps +from sanic.response import json + +def authorized(): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + # run some method that checks the request + # for the client's authorization status + is_authorized = await check_request_for_authorization_status(request) + + if is_authorized: + # the user is authorized. + # run the handler method and return the response + response = await f(request, *args, **kwargs) + return response + else: + # the user is not authorized. + return json({"status": "not_authorized"}, 403) + return decorated_function + return decorator + +@app.route("/") +@authorized() +async def test(request): + return json({"status": "authorized"}) +``` + +## Templates + +Decorators are **fundamental** to building applications with Sanic. They increase the portability and maintainablity of your code. + +In paraphrasing the Zen of Python: "[decorators] are one honking great idea -- let's do more of those!" + +To make it easier to implement them, here are three examples of copy/pastable code to get you started. + +.. column:: + +``` +Don't forget to add these import statements. Although it is *not* necessary, using `@wraps` helps keep some of the metadata of your function intact. [See docs](https://docs.python.org/3/library/functools.html#functools.wraps). Also, we use the `isawaitable` pattern here to allow the route handlers to by regular or asynchronous functions. +``` + +.. column:: + +```` +```python +from inspect import isawaitable +from functools import wraps +``` +```` + +### With args + +.. column:: + +```` +Often, you will want a decorator that will *always* need arguments. Therefore, when it is implemented you will always be calling it. + +```python +@app.get("/") +@foobar(1, 2) +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(arg1, arg2): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator +``` +```` + +### Without args + +.. column:: + +```` +Sometimes you want a decorator that will not take arguments. When this is the case, it is a nice convenience not to have to call it + +```python +@app.get("/") +@foobar +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(func): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator(func) +``` +```` + +### With or Without args + +.. column:: + +```` +If you want a decorator with the ability to be called or not, you can follow this pattern. Using keyword only arguments is not necessary, but might make implementation simpler. + +```python +@app.get("/") +@foobar(arg1=1, arg2=2) +async def handler(request: Request): + return text("hi") +``` + +```python +@app.get("/") +@foobar +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(maybe_func=None, *, arg1=None, arg2=None): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator(maybe_func) if maybe_func else decorator +``` +```` From 0d614675742245f8c413741ba0fe387e5287cc7d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:15 +0200 Subject: [PATCH 060/698] New translations decorators.md (Chinese Simplified) --- .../zh/guide/best-practices/decorators.md | 195 ++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 guide/content/zh/guide/best-practices/decorators.md diff --git a/guide/content/zh/guide/best-practices/decorators.md b/guide/content/zh/guide/best-practices/decorators.md new file mode 100644 index 0000000000..3f1bfdf6c0 --- /dev/null +++ b/guide/content/zh/guide/best-practices/decorators.md @@ -0,0 +1,195 @@ +# Decorators + +One of the best ways to create a consistent and DRY web API is to make use of decorators to remove functionality from the handlers, and make it repeatable across your views. + +.. column:: + +``` +Therefore, it is very common to see a Sanic view handler with several decorators on it. +``` + +.. column:: + +```` +```python +@app.get("/orders") +@authorized("view_order") +@validate_list_params() +@inject_user() +async def get_order_details(request, params, user): + ... +``` +```` + +## Example + +Here is a starter template to help you create decorators. + +In this example, let’s say you want to check that a user is authorized to access a particular endpoint. You can create a decorator that wraps a handler function, checks a request if the client is authorized to access a resource, and sends the appropriate response. + +```python +from functools import wraps +from sanic.response import json + +def authorized(): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + # run some method that checks the request + # for the client's authorization status + is_authorized = await check_request_for_authorization_status(request) + + if is_authorized: + # the user is authorized. + # run the handler method and return the response + response = await f(request, *args, **kwargs) + return response + else: + # the user is not authorized. + return json({"status": "not_authorized"}, 403) + return decorated_function + return decorator + +@app.route("/") +@authorized() +async def test(request): + return json({"status": "authorized"}) +``` + +## Templates + +Decorators are **fundamental** to building applications with Sanic. They increase the portability and maintainablity of your code. + +In paraphrasing the Zen of Python: "[decorators] are one honking great idea -- let's do more of those!" + +To make it easier to implement them, here are three examples of copy/pastable code to get you started. + +.. column:: + +``` +Don't forget to add these import statements. Although it is *not* necessary, using `@wraps` helps keep some of the metadata of your function intact. [See docs](https://docs.python.org/3/library/functools.html#functools.wraps). Also, we use the `isawaitable` pattern here to allow the route handlers to by regular or asynchronous functions. +``` + +.. column:: + +```` +```python +from inspect import isawaitable +from functools import wraps +``` +```` + +### With args + +.. column:: + +```` +Often, you will want a decorator that will *always* need arguments. Therefore, when it is implemented you will always be calling it. + +```python +@app.get("/") +@foobar(1, 2) +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(arg1, arg2): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator +``` +```` + +### Without args + +.. column:: + +```` +Sometimes you want a decorator that will not take arguments. When this is the case, it is a nice convenience not to have to call it + +```python +@app.get("/") +@foobar +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(func): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator(func) +``` +```` + +### With or Without args + +.. column:: + +```` +If you want a decorator with the ability to be called or not, you can follow this pattern. Using keyword only arguments is not necessary, but might make implementation simpler. + +```python +@app.get("/") +@foobar(arg1=1, arg2=2) +async def handler(request: Request): + return text("hi") +``` + +```python +@app.get("/") +@foobar +async def handler(request: Request): + return text("hi") +``` +```` + +.. column:: + +```` +```python +def foobar(maybe_func=None, *, arg1=None, arg2=None): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + + response = f(request, *args, **kwargs) + if isawaitable(response): + response = await response + + return response + + return decorated_function + + return decorator(maybe_func) if maybe_func else decorator +``` +```` From d82c17b42bfb508ef3c7f0959c55d305fc7917dc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:16 +0200 Subject: [PATCH 061/698] New translations exceptions.md (Japanese) --- .../ja/guide/best-practices/exceptions.md | 636 ++++++++++++++++++ 1 file changed, 636 insertions(+) create mode 100644 guide/content/ja/guide/best-practices/exceptions.md diff --git a/guide/content/ja/guide/best-practices/exceptions.md b/guide/content/ja/guide/best-practices/exceptions.md new file mode 100644 index 0000000000..9b46c551a1 --- /dev/null +++ b/guide/content/ja/guide/best-practices/exceptions.md @@ -0,0 +1,636 @@ +# Exceptions + +## Using Sanic exceptions + +Sometimes you just need to tell Sanic to halt execution of a handler and send back a status code response. You can raise a `SanicException` for this and Sanic will do the rest for you. + +You can pass an optional `status_code` argument. By default, a SanicException will return an internal server error 500 response. + +```python +from sanic.exceptions import SanicException + +@app.route("/youshallnotpass") +async def no_no(request): + raise SanicException("Something went wrong.", status_code=501) +``` + +Sanic provides a number of standard exceptions. They each automatically will raise the appropriate HTTP status code in your response. [Check the API reference](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) for more details. + +.. column:: + +``` +The more common exceptions you _should_ implement yourself include: + +- `BadRequest` (400) +- `Unauthorized` (401) +- `Forbidden` (403) +- `NotFound` (404) +- `ServerError` (500) +``` + +.. column:: + +```` +```python +from sanic import exceptions + +@app.route("/login") +async def login(request): + user = await some_login_func(request) + if not user: + raise exceptions.NotFound( + f"Could not find user with username={request.json.username}" + ) +``` +```` + +## Exception properties + +All exceptions in Sanic derive from `SanicException`. That class has a few properties on it that assist the developer in consistently reporting their exceptions across an application. + +- `message` +- `status_code` +- `quiet` +- `headers` +- `context` +- `extra` + +All of these properties can be passed to the exception when it is created, but the first three can also be used as class variables as we will see. + +.. column:: + +``` +### `message` + +The `message` property obviously controls the message that will be displayed as with any other exception in Python. What is particularly useful is that you can set the `message` property on the class definition allowing for easy standardization of language across an application +``` + +.. column:: + +```` +```python +class CustomError(SanicException): + message = "Something bad happened" + +raise CustomError +# or +raise CustomError("Override the default message with something else") +``` +```` + +.. column:: + +``` +### `status_code` + +This property is used to set the response code when the exception is raised. This can particularly be useful when creating custom 400 series exceptions that are usually in response to bad information coming from the client. +``` + +.. column:: + +```` +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +# or +raise TeapotError(status_code=400) +``` +```` + +.. column:: + +``` +### `quiet` + +By default, exceptions will be output by Sanic to the `error_logger`. Sometimes this may not be desirable, especially if you are using exceptions to trigger events in exception handlers (see [the following section](./exceptions.md#handling)). You can suppress the log output using `quiet=True`. +``` + +.. column:: + +```` +```python +class SilentError(SanicException): + message = "Something happened, but not shown in logs" + quiet = True + +raise SilentError +# or +raise InvalidUsage("blah blah", quiet=True) +``` +```` + +.. column:: + +``` +Sometimes while debugging you may want to globally ignore the `quiet=True` property. You can force Sanic to log out all exceptions regardless of this property using `NOISY_EXCEPTIONS` + +*Added in v21.12* +``` + +.. column:: + +```` +```python +app.config.NOISY_EXCEPTIONS = True +``` +```` + +.. column:: + +``` +### `headers` + +Using `SanicException` as a tool for creating responses is super powerful. This is in part because not only can you control the `status_code`, but you can also control reponse headers directly from the exception. +``` + +.. column:: + +```` +```python +class MyException(SanicException): + headers = { + "X-Foo": "bar" + } + +raise MyException +# or +raise InvalidUsage("blah blah", headers={ + "X-Foo": "bar" +}) +``` +```` + +.. column:: + +``` +### `extra` + +See [contextual exceptions](./exceptions.md#contextual-exceptions) + +*Added in v21.12* +``` + +.. column:: + +```` +```python +raise SanicException(..., extra={"name": "Adam"}) +``` +```` + +.. column:: + +``` +### `context` + +See [contextual exceptions](./exceptions.md#contextual-exceptions) + +*Added in v21.12* +``` + +.. column:: + +```` +```python +raise SanicException(..., context={"foo": "bar"}) +``` +```` + +## Handling + +Sanic handles exceptions automatically by rendering an error page, so in many cases you don't need to handle them yourself. However, if you would like more control on what to do when an exception is raised, you can implement a handler yourself. + +Sanic provides a decorator for this, which applies to not only the Sanic standard exceptions, but **any** exception that your application might throw. + +.. column:: + +``` +The easiest method to add a handler is to use `@app.exception()` and pass it one or more exceptions. +``` + +.. column:: + +```` +```python +from sanic.exceptions import NotFound + +@app.exception(NotFound, SomeCustomException) +async def ignore_404s(request, exception): + return text("Yep, I totally found the page: {}".format(request.url)) +``` +```` + +.. column:: + +``` +You can also create a catchall handler by catching `Exception`. +``` + +.. column:: + +```` +```python +@app.exception(Exception) +async def catch_anything(request, exception): + ... +``` +```` + +.. column:: + +``` +You can also use `app.error_handler.add()` to add error handlers. +``` + +.. column:: + +```` +```python +async def server_error_handler(request, exception): + return text("Oops, server error", status=500) + +app.error_handler.add(Exception, server_error_handler) +``` +```` + +## Built-in error handling + +Sanic ships with three formats for exceptions: HTML, JSON, and text. You can see examples of them below in the [Fallback handler](#fallback-handler) section. + +.. column:: + +``` +You can control _per route_ which format to use with the `error_format` keyword argument. + +*Added in v21.9* +``` + +.. column:: + +```` +```python +@app.request("/", error_format="text") +async def handler(request): + ... +``` +```` + +## Custom error handling + +In some cases, you might want to add some more error handling functionality to what is provided by default. In that case, you can subclass Sanic's default error handler as such: + +```python +from sanic.handlers import ErrorHandler + +class CustomErrorHandler(ErrorHandler): + def default(self, request: Request, exception: Exception) -> HTTPResponse: + ''' handles errors that have no error handlers assigned ''' + # You custom error handling logic... + status_code = getattr(exception, "status_code", 500) + return json({ + "error": str(exception), + "foo": "bar" + }, status=status_code) + +app.error_handler = CustomErrorHandler() +``` + +## Fallback handler + +Sanic comes with three fallback exception handlers: + +1. HTML +2. Text +3. JSON + +These handlers present differing levels of detail depending upon whether your application is in [debug mode](/guide/deployment/development.md) or not. + +By default, Sanic will be in "auto" mode, which means that it will using the incoming request and potential matching handler to choose the appropriate response format. For example, when in a browser it should always provide an HTML error page. When using curl, you might see JSON or plain text. + +### HTML + +```python +app.config.FALLBACK_ERROR_FORMAT = "html" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +![Error](/assets/images/error-display-html-debug.png) +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +![Error](/assets/images/error-display-html-prod.png) +```` + +### Text + +```python +app.config.FALLBACK_ERROR_FORMAT = "text" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 620 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +⚠️ 500 — Internal Server Error +============================== +That time when that thing broke that other thing? That happened. + +ServerError: That time when that thing broke that other thing? That happened. while handling path /exc +Traceback of TestApp (most recent call last): + + ServerError: That time when that thing broke that other thing? That happened. + File /path/to/sanic/app.py, line 979, in handle_request + response = await response + + File /path/to/server.py, line 16, in handler + do_something(cause_error=True) + + File /path/to/something.py, line 9, in do_something + raise ServerError( +``` +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 134 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +⚠️ 500 — Internal Server Error +============================== +That time when that thing broke that other thing? That happened. +``` +```` + +### JSON + +```python +app.config.FALLBACK_ERROR_FORMAT = "json" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 572 +connection: keep-alive +content-type: application/jso + +{ + "description": "Internal Server Error", + "status": 500, + "message": "That time when that thing broke that other thing? That happened.", + "path": "/exc", + "args": {}, + "exceptions": [ + { + "type": "ServerError", + "exception": "That time when that thing broke that other thing? That happened.", + "frames": [ + { + "file": "/path/to/sanic/app.py", + "line": 979, + "name": "handle_request", + "src": "response = await response" + }, + { + "file": "/path/to/server.py", + "line": 16, + "name": "handler", + "src": "do_something(cause_error=True)" + }, + { + "file": "/path/to/something.py", + "line": 9, + "name": "do_something", + "src": "raise ServerError(" + } + ] + } + ] +} +``` +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 129 +connection: keep-alive +content-type: application/json + +{ + "description": "Internal Server Error", + "status": 500, + "message": "That time when that thing broke that other thing? That happened." +} + +``` +```` + +### Auto + +Sanic also provides an option for guessing which fallback option to use. + +```python +app.config.FALLBACK_ERROR_FORMAT = "auto" +``` + +## Contextual Exceptions + +Default exception messages that simplify the ability to consistently raise exceptions throughout your application. + +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +But this lacks two things: + +1. A dynamic and predictable message format +2. The ability to add additional context to an error message (more on this in a moment) + +_Added in v21.12_ + +Using one of Sanic's exceptions, you have two options to provide additional details at runtime: + +```python +raise TeapotError(extra={"foo": "bar"}, context={"foo": "bar"}) +``` + +What's the difference and when should you decide to use each? + +- `extra` - The object itself will **never** be sent to a production client. It is meant for internal use only. What could it be used for? + - Generating (as we will see in a minute) a dynamic error message + - Providing runtime details to a logger + - Debug information (when in development mode, it is rendered) +- `context` - This object is **always** sent to production clients. It is generally meant to be used to send additional details about the context of what happened. What could it be used for? + - Providing alternative values on a `BadRequest` validation issue + - Responding with helpful details for your customers to open a support ticket + - Displaying state information like current logged in user info + +### Dynamic and predictable message using `extra` + +Sanic exceptions can be raised using `extra` keyword arguments to provide additional information to a raised exception instance. + +```python +class TeapotError(SanicException): + status_code = 418 + + @property + def message(self): + return f"Sorry {self.extra['name']}, I cannot make you coffee" + +raise TeapotError(extra={"name": "Adam"}) +``` + +The new feature allows the passing of `extra` meta to the exception instance, which can be particularly useful as in the above example to pass dynamic data into the message text. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. + +.. column:: + +``` +**DEVELOPMENT** + +![image](~@assets/images/error-extra-debug.png) +``` + +.. column:: + +``` +**PRODUCTION** + +![image](~@assets/images/error-extra-prod.png) +``` + +### Additional `context` to an error message + +Sanic exceptions can also be raised with a `context` argument to pass intended information along to the user about what happened. This is particularly useful when creating microservices or an API intended to pass error messages in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. + +```python +raise TeapotError(context={"foo": "bar"}) +``` + +This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: + +.. column:: + +```` +**PRODUCTION** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + } +} +``` +```` + +.. column:: + +```` +**DEVELOPMENT** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + }, + "path": "/", + "args": {}, + "exceptions": [ + { + "type": "TeapotError", + "exception": "Sorry Adam, I cannot make you coffee", + "frames": [ + { + "file": "handle_request", + "line": 83, + "name": "handle_request", + "src": "" + }, + { + "file": "/tmp/p.py", + "line": 17, + "name": "handler", + "src": "raise TeapotError(" + } + ] + } + ] +} +``` +```` + +## Error reporting + +Sanic has a [signal](../advanced/signals.md#built-in-signals) that allows you to hook into the exception reporting process. This is useful if you want to send exception information to a third party service like Sentry or Rollbar. This can be conveniently accomplished by attaching an error reporting handler as show below: + +```python +@app.report_exception +async def catch_any_exception(app: Sanic, exception: Exception): +print("Caught exception:", exception) +``` + +.. note:: + +``` +This handler will be dispatched into a background task and **IS NOT** intended for use to manipulate any response data. It is intended to be used for logging or reporting purposes only, and should not impact the ability of your application to return the error response to the client. +``` + +_Added in v23.6_ From b7d4a422d909f22d7130805075d74e4d443b45b1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:17 +0200 Subject: [PATCH 062/698] New translations exceptions.md (Korean) --- .../ko/guide/best-practices/exceptions.md | 636 ++++++++++++++++++ 1 file changed, 636 insertions(+) create mode 100644 guide/content/ko/guide/best-practices/exceptions.md diff --git a/guide/content/ko/guide/best-practices/exceptions.md b/guide/content/ko/guide/best-practices/exceptions.md new file mode 100644 index 0000000000..9b46c551a1 --- /dev/null +++ b/guide/content/ko/guide/best-practices/exceptions.md @@ -0,0 +1,636 @@ +# Exceptions + +## Using Sanic exceptions + +Sometimes you just need to tell Sanic to halt execution of a handler and send back a status code response. You can raise a `SanicException` for this and Sanic will do the rest for you. + +You can pass an optional `status_code` argument. By default, a SanicException will return an internal server error 500 response. + +```python +from sanic.exceptions import SanicException + +@app.route("/youshallnotpass") +async def no_no(request): + raise SanicException("Something went wrong.", status_code=501) +``` + +Sanic provides a number of standard exceptions. They each automatically will raise the appropriate HTTP status code in your response. [Check the API reference](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) for more details. + +.. column:: + +``` +The more common exceptions you _should_ implement yourself include: + +- `BadRequest` (400) +- `Unauthorized` (401) +- `Forbidden` (403) +- `NotFound` (404) +- `ServerError` (500) +``` + +.. column:: + +```` +```python +from sanic import exceptions + +@app.route("/login") +async def login(request): + user = await some_login_func(request) + if not user: + raise exceptions.NotFound( + f"Could not find user with username={request.json.username}" + ) +``` +```` + +## Exception properties + +All exceptions in Sanic derive from `SanicException`. That class has a few properties on it that assist the developer in consistently reporting their exceptions across an application. + +- `message` +- `status_code` +- `quiet` +- `headers` +- `context` +- `extra` + +All of these properties can be passed to the exception when it is created, but the first three can also be used as class variables as we will see. + +.. column:: + +``` +### `message` + +The `message` property obviously controls the message that will be displayed as with any other exception in Python. What is particularly useful is that you can set the `message` property on the class definition allowing for easy standardization of language across an application +``` + +.. column:: + +```` +```python +class CustomError(SanicException): + message = "Something bad happened" + +raise CustomError +# or +raise CustomError("Override the default message with something else") +``` +```` + +.. column:: + +``` +### `status_code` + +This property is used to set the response code when the exception is raised. This can particularly be useful when creating custom 400 series exceptions that are usually in response to bad information coming from the client. +``` + +.. column:: + +```` +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +# or +raise TeapotError(status_code=400) +``` +```` + +.. column:: + +``` +### `quiet` + +By default, exceptions will be output by Sanic to the `error_logger`. Sometimes this may not be desirable, especially if you are using exceptions to trigger events in exception handlers (see [the following section](./exceptions.md#handling)). You can suppress the log output using `quiet=True`. +``` + +.. column:: + +```` +```python +class SilentError(SanicException): + message = "Something happened, but not shown in logs" + quiet = True + +raise SilentError +# or +raise InvalidUsage("blah blah", quiet=True) +``` +```` + +.. column:: + +``` +Sometimes while debugging you may want to globally ignore the `quiet=True` property. You can force Sanic to log out all exceptions regardless of this property using `NOISY_EXCEPTIONS` + +*Added in v21.12* +``` + +.. column:: + +```` +```python +app.config.NOISY_EXCEPTIONS = True +``` +```` + +.. column:: + +``` +### `headers` + +Using `SanicException` as a tool for creating responses is super powerful. This is in part because not only can you control the `status_code`, but you can also control reponse headers directly from the exception. +``` + +.. column:: + +```` +```python +class MyException(SanicException): + headers = { + "X-Foo": "bar" + } + +raise MyException +# or +raise InvalidUsage("blah blah", headers={ + "X-Foo": "bar" +}) +``` +```` + +.. column:: + +``` +### `extra` + +See [contextual exceptions](./exceptions.md#contextual-exceptions) + +*Added in v21.12* +``` + +.. column:: + +```` +```python +raise SanicException(..., extra={"name": "Adam"}) +``` +```` + +.. column:: + +``` +### `context` + +See [contextual exceptions](./exceptions.md#contextual-exceptions) + +*Added in v21.12* +``` + +.. column:: + +```` +```python +raise SanicException(..., context={"foo": "bar"}) +``` +```` + +## Handling + +Sanic handles exceptions automatically by rendering an error page, so in many cases you don't need to handle them yourself. However, if you would like more control on what to do when an exception is raised, you can implement a handler yourself. + +Sanic provides a decorator for this, which applies to not only the Sanic standard exceptions, but **any** exception that your application might throw. + +.. column:: + +``` +The easiest method to add a handler is to use `@app.exception()` and pass it one or more exceptions. +``` + +.. column:: + +```` +```python +from sanic.exceptions import NotFound + +@app.exception(NotFound, SomeCustomException) +async def ignore_404s(request, exception): + return text("Yep, I totally found the page: {}".format(request.url)) +``` +```` + +.. column:: + +``` +You can also create a catchall handler by catching `Exception`. +``` + +.. column:: + +```` +```python +@app.exception(Exception) +async def catch_anything(request, exception): + ... +``` +```` + +.. column:: + +``` +You can also use `app.error_handler.add()` to add error handlers. +``` + +.. column:: + +```` +```python +async def server_error_handler(request, exception): + return text("Oops, server error", status=500) + +app.error_handler.add(Exception, server_error_handler) +``` +```` + +## Built-in error handling + +Sanic ships with three formats for exceptions: HTML, JSON, and text. You can see examples of them below in the [Fallback handler](#fallback-handler) section. + +.. column:: + +``` +You can control _per route_ which format to use with the `error_format` keyword argument. + +*Added in v21.9* +``` + +.. column:: + +```` +```python +@app.request("/", error_format="text") +async def handler(request): + ... +``` +```` + +## Custom error handling + +In some cases, you might want to add some more error handling functionality to what is provided by default. In that case, you can subclass Sanic's default error handler as such: + +```python +from sanic.handlers import ErrorHandler + +class CustomErrorHandler(ErrorHandler): + def default(self, request: Request, exception: Exception) -> HTTPResponse: + ''' handles errors that have no error handlers assigned ''' + # You custom error handling logic... + status_code = getattr(exception, "status_code", 500) + return json({ + "error": str(exception), + "foo": "bar" + }, status=status_code) + +app.error_handler = CustomErrorHandler() +``` + +## Fallback handler + +Sanic comes with three fallback exception handlers: + +1. HTML +2. Text +3. JSON + +These handlers present differing levels of detail depending upon whether your application is in [debug mode](/guide/deployment/development.md) or not. + +By default, Sanic will be in "auto" mode, which means that it will using the incoming request and potential matching handler to choose the appropriate response format. For example, when in a browser it should always provide an HTML error page. When using curl, you might see JSON or plain text. + +### HTML + +```python +app.config.FALLBACK_ERROR_FORMAT = "html" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +![Error](/assets/images/error-display-html-debug.png) +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +![Error](/assets/images/error-display-html-prod.png) +```` + +### Text + +```python +app.config.FALLBACK_ERROR_FORMAT = "text" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 620 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +⚠️ 500 — Internal Server Error +============================== +That time when that thing broke that other thing? That happened. + +ServerError: That time when that thing broke that other thing? That happened. while handling path /exc +Traceback of TestApp (most recent call last): + + ServerError: That time when that thing broke that other thing? That happened. + File /path/to/sanic/app.py, line 979, in handle_request + response = await response + + File /path/to/server.py, line 16, in handler + do_something(cause_error=True) + + File /path/to/something.py, line 9, in do_something + raise ServerError( +``` +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 134 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +⚠️ 500 — Internal Server Error +============================== +That time when that thing broke that other thing? That happened. +``` +```` + +### JSON + +```python +app.config.FALLBACK_ERROR_FORMAT = "json" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 572 +connection: keep-alive +content-type: application/jso + +{ + "description": "Internal Server Error", + "status": 500, + "message": "That time when that thing broke that other thing? That happened.", + "path": "/exc", + "args": {}, + "exceptions": [ + { + "type": "ServerError", + "exception": "That time when that thing broke that other thing? That happened.", + "frames": [ + { + "file": "/path/to/sanic/app.py", + "line": 979, + "name": "handle_request", + "src": "response = await response" + }, + { + "file": "/path/to/server.py", + "line": 16, + "name": "handler", + "src": "do_something(cause_error=True)" + }, + { + "file": "/path/to/something.py", + "line": 9, + "name": "do_something", + "src": "raise ServerError(" + } + ] + } + ] +} +``` +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 129 +connection: keep-alive +content-type: application/json + +{ + "description": "Internal Server Error", + "status": 500, + "message": "That time when that thing broke that other thing? That happened." +} + +``` +```` + +### Auto + +Sanic also provides an option for guessing which fallback option to use. + +```python +app.config.FALLBACK_ERROR_FORMAT = "auto" +``` + +## Contextual Exceptions + +Default exception messages that simplify the ability to consistently raise exceptions throughout your application. + +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +But this lacks two things: + +1. A dynamic and predictable message format +2. The ability to add additional context to an error message (more on this in a moment) + +_Added in v21.12_ + +Using one of Sanic's exceptions, you have two options to provide additional details at runtime: + +```python +raise TeapotError(extra={"foo": "bar"}, context={"foo": "bar"}) +``` + +What's the difference and when should you decide to use each? + +- `extra` - The object itself will **never** be sent to a production client. It is meant for internal use only. What could it be used for? + - Generating (as we will see in a minute) a dynamic error message + - Providing runtime details to a logger + - Debug information (when in development mode, it is rendered) +- `context` - This object is **always** sent to production clients. It is generally meant to be used to send additional details about the context of what happened. What could it be used for? + - Providing alternative values on a `BadRequest` validation issue + - Responding with helpful details for your customers to open a support ticket + - Displaying state information like current logged in user info + +### Dynamic and predictable message using `extra` + +Sanic exceptions can be raised using `extra` keyword arguments to provide additional information to a raised exception instance. + +```python +class TeapotError(SanicException): + status_code = 418 + + @property + def message(self): + return f"Sorry {self.extra['name']}, I cannot make you coffee" + +raise TeapotError(extra={"name": "Adam"}) +``` + +The new feature allows the passing of `extra` meta to the exception instance, which can be particularly useful as in the above example to pass dynamic data into the message text. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. + +.. column:: + +``` +**DEVELOPMENT** + +![image](~@assets/images/error-extra-debug.png) +``` + +.. column:: + +``` +**PRODUCTION** + +![image](~@assets/images/error-extra-prod.png) +``` + +### Additional `context` to an error message + +Sanic exceptions can also be raised with a `context` argument to pass intended information along to the user about what happened. This is particularly useful when creating microservices or an API intended to pass error messages in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. + +```python +raise TeapotError(context={"foo": "bar"}) +``` + +This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: + +.. column:: + +```` +**PRODUCTION** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + } +} +``` +```` + +.. column:: + +```` +**DEVELOPMENT** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + }, + "path": "/", + "args": {}, + "exceptions": [ + { + "type": "TeapotError", + "exception": "Sorry Adam, I cannot make you coffee", + "frames": [ + { + "file": "handle_request", + "line": 83, + "name": "handle_request", + "src": "" + }, + { + "file": "/tmp/p.py", + "line": 17, + "name": "handler", + "src": "raise TeapotError(" + } + ] + } + ] +} +``` +```` + +## Error reporting + +Sanic has a [signal](../advanced/signals.md#built-in-signals) that allows you to hook into the exception reporting process. This is useful if you want to send exception information to a third party service like Sentry or Rollbar. This can be conveniently accomplished by attaching an error reporting handler as show below: + +```python +@app.report_exception +async def catch_any_exception(app: Sanic, exception: Exception): +print("Caught exception:", exception) +``` + +.. note:: + +``` +This handler will be dispatched into a background task and **IS NOT** intended for use to manipulate any response data. It is intended to be used for logging or reporting purposes only, and should not impact the ability of your application to return the error response to the client. +``` + +_Added in v23.6_ From 327fefd5577c558fb5c8341bb537a327890a4030 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:18 +0200 Subject: [PATCH 063/698] New translations exceptions.md (Chinese Simplified) --- .../zh/guide/best-practices/exceptions.md | 636 ++++++++++++++++++ 1 file changed, 636 insertions(+) create mode 100644 guide/content/zh/guide/best-practices/exceptions.md diff --git a/guide/content/zh/guide/best-practices/exceptions.md b/guide/content/zh/guide/best-practices/exceptions.md new file mode 100644 index 0000000000..9b46c551a1 --- /dev/null +++ b/guide/content/zh/guide/best-practices/exceptions.md @@ -0,0 +1,636 @@ +# Exceptions + +## Using Sanic exceptions + +Sometimes you just need to tell Sanic to halt execution of a handler and send back a status code response. You can raise a `SanicException` for this and Sanic will do the rest for you. + +You can pass an optional `status_code` argument. By default, a SanicException will return an internal server error 500 response. + +```python +from sanic.exceptions import SanicException + +@app.route("/youshallnotpass") +async def no_no(request): + raise SanicException("Something went wrong.", status_code=501) +``` + +Sanic provides a number of standard exceptions. They each automatically will raise the appropriate HTTP status code in your response. [Check the API reference](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) for more details. + +.. column:: + +``` +The more common exceptions you _should_ implement yourself include: + +- `BadRequest` (400) +- `Unauthorized` (401) +- `Forbidden` (403) +- `NotFound` (404) +- `ServerError` (500) +``` + +.. column:: + +```` +```python +from sanic import exceptions + +@app.route("/login") +async def login(request): + user = await some_login_func(request) + if not user: + raise exceptions.NotFound( + f"Could not find user with username={request.json.username}" + ) +``` +```` + +## Exception properties + +All exceptions in Sanic derive from `SanicException`. That class has a few properties on it that assist the developer in consistently reporting their exceptions across an application. + +- `message` +- `status_code` +- `quiet` +- `headers` +- `context` +- `extra` + +All of these properties can be passed to the exception when it is created, but the first three can also be used as class variables as we will see. + +.. column:: + +``` +### `message` + +The `message` property obviously controls the message that will be displayed as with any other exception in Python. What is particularly useful is that you can set the `message` property on the class definition allowing for easy standardization of language across an application +``` + +.. column:: + +```` +```python +class CustomError(SanicException): + message = "Something bad happened" + +raise CustomError +# or +raise CustomError("Override the default message with something else") +``` +```` + +.. column:: + +``` +### `status_code` + +This property is used to set the response code when the exception is raised. This can particularly be useful when creating custom 400 series exceptions that are usually in response to bad information coming from the client. +``` + +.. column:: + +```` +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +# or +raise TeapotError(status_code=400) +``` +```` + +.. column:: + +``` +### `quiet` + +By default, exceptions will be output by Sanic to the `error_logger`. Sometimes this may not be desirable, especially if you are using exceptions to trigger events in exception handlers (see [the following section](./exceptions.md#handling)). You can suppress the log output using `quiet=True`. +``` + +.. column:: + +```` +```python +class SilentError(SanicException): + message = "Something happened, but not shown in logs" + quiet = True + +raise SilentError +# or +raise InvalidUsage("blah blah", quiet=True) +``` +```` + +.. column:: + +``` +Sometimes while debugging you may want to globally ignore the `quiet=True` property. You can force Sanic to log out all exceptions regardless of this property using `NOISY_EXCEPTIONS` + +*Added in v21.12* +``` + +.. column:: + +```` +```python +app.config.NOISY_EXCEPTIONS = True +``` +```` + +.. column:: + +``` +### `headers` + +Using `SanicException` as a tool for creating responses is super powerful. This is in part because not only can you control the `status_code`, but you can also control reponse headers directly from the exception. +``` + +.. column:: + +```` +```python +class MyException(SanicException): + headers = { + "X-Foo": "bar" + } + +raise MyException +# or +raise InvalidUsage("blah blah", headers={ + "X-Foo": "bar" +}) +``` +```` + +.. column:: + +``` +### `extra` + +See [contextual exceptions](./exceptions.md#contextual-exceptions) + +*Added in v21.12* +``` + +.. column:: + +```` +```python +raise SanicException(..., extra={"name": "Adam"}) +``` +```` + +.. column:: + +``` +### `context` + +See [contextual exceptions](./exceptions.md#contextual-exceptions) + +*Added in v21.12* +``` + +.. column:: + +```` +```python +raise SanicException(..., context={"foo": "bar"}) +``` +```` + +## Handling + +Sanic handles exceptions automatically by rendering an error page, so in many cases you don't need to handle them yourself. However, if you would like more control on what to do when an exception is raised, you can implement a handler yourself. + +Sanic provides a decorator for this, which applies to not only the Sanic standard exceptions, but **any** exception that your application might throw. + +.. column:: + +``` +The easiest method to add a handler is to use `@app.exception()` and pass it one or more exceptions. +``` + +.. column:: + +```` +```python +from sanic.exceptions import NotFound + +@app.exception(NotFound, SomeCustomException) +async def ignore_404s(request, exception): + return text("Yep, I totally found the page: {}".format(request.url)) +``` +```` + +.. column:: + +``` +You can also create a catchall handler by catching `Exception`. +``` + +.. column:: + +```` +```python +@app.exception(Exception) +async def catch_anything(request, exception): + ... +``` +```` + +.. column:: + +``` +You can also use `app.error_handler.add()` to add error handlers. +``` + +.. column:: + +```` +```python +async def server_error_handler(request, exception): + return text("Oops, server error", status=500) + +app.error_handler.add(Exception, server_error_handler) +``` +```` + +## Built-in error handling + +Sanic ships with three formats for exceptions: HTML, JSON, and text. You can see examples of them below in the [Fallback handler](#fallback-handler) section. + +.. column:: + +``` +You can control _per route_ which format to use with the `error_format` keyword argument. + +*Added in v21.9* +``` + +.. column:: + +```` +```python +@app.request("/", error_format="text") +async def handler(request): + ... +``` +```` + +## Custom error handling + +In some cases, you might want to add some more error handling functionality to what is provided by default. In that case, you can subclass Sanic's default error handler as such: + +```python +from sanic.handlers import ErrorHandler + +class CustomErrorHandler(ErrorHandler): + def default(self, request: Request, exception: Exception) -> HTTPResponse: + ''' handles errors that have no error handlers assigned ''' + # You custom error handling logic... + status_code = getattr(exception, "status_code", 500) + return json({ + "error": str(exception), + "foo": "bar" + }, status=status_code) + +app.error_handler = CustomErrorHandler() +``` + +## Fallback handler + +Sanic comes with three fallback exception handlers: + +1. HTML +2. Text +3. JSON + +These handlers present differing levels of detail depending upon whether your application is in [debug mode](/guide/deployment/development.md) or not. + +By default, Sanic will be in "auto" mode, which means that it will using the incoming request and potential matching handler to choose the appropriate response format. For example, when in a browser it should always provide an HTML error page. When using curl, you might see JSON or plain text. + +### HTML + +```python +app.config.FALLBACK_ERROR_FORMAT = "html" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +![Error](/assets/images/error-display-html-debug.png) +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +![Error](/assets/images/error-display-html-prod.png) +```` + +### Text + +```python +app.config.FALLBACK_ERROR_FORMAT = "text" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 620 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +⚠️ 500 — Internal Server Error +============================== +That time when that thing broke that other thing? That happened. + +ServerError: That time when that thing broke that other thing? That happened. while handling path /exc +Traceback of TestApp (most recent call last): + + ServerError: That time when that thing broke that other thing? That happened. + File /path/to/sanic/app.py, line 979, in handle_request + response = await response + + File /path/to/server.py, line 16, in handler + do_something(cause_error=True) + + File /path/to/something.py, line 9, in do_something + raise ServerError( +``` +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 134 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +⚠️ 500 — Internal Server Error +============================== +That time when that thing broke that other thing? That happened. +``` +```` + +### JSON + +```python +app.config.FALLBACK_ERROR_FORMAT = "json" +``` + +.. column:: + +```` +```python +app.config.DEBUG = True +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 572 +connection: keep-alive +content-type: application/jso + +{ + "description": "Internal Server Error", + "status": 500, + "message": "That time when that thing broke that other thing? That happened.", + "path": "/exc", + "args": {}, + "exceptions": [ + { + "type": "ServerError", + "exception": "That time when that thing broke that other thing? That happened.", + "frames": [ + { + "file": "/path/to/sanic/app.py", + "line": 979, + "name": "handle_request", + "src": "response = await response" + }, + { + "file": "/path/to/server.py", + "line": 16, + "name": "handler", + "src": "do_something(cause_error=True)" + }, + { + "file": "/path/to/something.py", + "line": 9, + "name": "do_something", + "src": "raise ServerError(" + } + ] + } + ] +} +``` +```` + +.. column:: + +```` +```python +app.config.DEBUG = False +``` + +```sh +curl localhost:8000/exc -i +HTTP/1.1 500 Internal Server Error +content-length: 129 +connection: keep-alive +content-type: application/json + +{ + "description": "Internal Server Error", + "status": 500, + "message": "That time when that thing broke that other thing? That happened." +} + +``` +```` + +### Auto + +Sanic also provides an option for guessing which fallback option to use. + +```python +app.config.FALLBACK_ERROR_FORMAT = "auto" +``` + +## Contextual Exceptions + +Default exception messages that simplify the ability to consistently raise exceptions throughout your application. + +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +But this lacks two things: + +1. A dynamic and predictable message format +2. The ability to add additional context to an error message (more on this in a moment) + +_Added in v21.12_ + +Using one of Sanic's exceptions, you have two options to provide additional details at runtime: + +```python +raise TeapotError(extra={"foo": "bar"}, context={"foo": "bar"}) +``` + +What's the difference and when should you decide to use each? + +- `extra` - The object itself will **never** be sent to a production client. It is meant for internal use only. What could it be used for? + - Generating (as we will see in a minute) a dynamic error message + - Providing runtime details to a logger + - Debug information (when in development mode, it is rendered) +- `context` - This object is **always** sent to production clients. It is generally meant to be used to send additional details about the context of what happened. What could it be used for? + - Providing alternative values on a `BadRequest` validation issue + - Responding with helpful details for your customers to open a support ticket + - Displaying state information like current logged in user info + +### Dynamic and predictable message using `extra` + +Sanic exceptions can be raised using `extra` keyword arguments to provide additional information to a raised exception instance. + +```python +class TeapotError(SanicException): + status_code = 418 + + @property + def message(self): + return f"Sorry {self.extra['name']}, I cannot make you coffee" + +raise TeapotError(extra={"name": "Adam"}) +``` + +The new feature allows the passing of `extra` meta to the exception instance, which can be particularly useful as in the above example to pass dynamic data into the message text. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. + +.. column:: + +``` +**DEVELOPMENT** + +![image](~@assets/images/error-extra-debug.png) +``` + +.. column:: + +``` +**PRODUCTION** + +![image](~@assets/images/error-extra-prod.png) +``` + +### Additional `context` to an error message + +Sanic exceptions can also be raised with a `context` argument to pass intended information along to the user about what happened. This is particularly useful when creating microservices or an API intended to pass error messages in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. + +```python +raise TeapotError(context={"foo": "bar"}) +``` + +This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: + +.. column:: + +```` +**PRODUCTION** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + } +} +``` +```` + +.. column:: + +```` +**DEVELOPMENT** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + }, + "path": "/", + "args": {}, + "exceptions": [ + { + "type": "TeapotError", + "exception": "Sorry Adam, I cannot make you coffee", + "frames": [ + { + "file": "handle_request", + "line": 83, + "name": "handle_request", + "src": "" + }, + { + "file": "/tmp/p.py", + "line": 17, + "name": "handler", + "src": "raise TeapotError(" + } + ] + } + ] +} +``` +```` + +## Error reporting + +Sanic has a [signal](../advanced/signals.md#built-in-signals) that allows you to hook into the exception reporting process. This is useful if you want to send exception information to a third party service like Sentry or Rollbar. This can be conveniently accomplished by attaching an error reporting handler as show below: + +```python +@app.report_exception +async def catch_any_exception(app: Sanic, exception: Exception): +print("Caught exception:", exception) +``` + +.. note:: + +``` +This handler will be dispatched into a background task and **IS NOT** intended for use to manipulate any response data. It is intended to be used for logging or reporting purposes only, and should not impact the ability of your application to return the error response to the client. +``` + +_Added in v23.6_ From 6913a141accded2898c38f86c051997955fbbd7a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:19 +0200 Subject: [PATCH 064/698] New translations logging.md (Japanese) --- .../ja/guide/best-practices/logging.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 guide/content/ja/guide/best-practices/logging.md diff --git a/guide/content/ja/guide/best-practices/logging.md b/guide/content/ja/guide/best-practices/logging.md new file mode 100644 index 0000000000..acc2791c88 --- /dev/null +++ b/guide/content/ja/guide/best-practices/logging.md @@ -0,0 +1,101 @@ +# Logging + +Sanic allows you to do different types of logging (access log, error log) on the requests based on the [Python logging API](https://docs.python.org/3/howto/logging.html). You should have some basic knowledge on Python logging if you want to create a new configuration. + +## Quick Start + +.. column:: + +``` +A simple example using default settings would be like this: +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.log import logger +from sanic.response import text + +app = Sanic('logging_example') + +@app.route('/') +async def test(request): + logger.info('Here is your log') + return text('Hello World!') + +if __name__ == "__main__": + app.run(debug=True, access_log=True) +``` +```` + +After the server is running, you should see logs like this. + +```text +[2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 +[2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] +``` + +You can send a request to server and it will print the log messages. + +```text +[2021-01-04 15:26:28 +0200] [1929659] [INFO] Here is your log +[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: GET http://localhost:8000/ 200 -1 +``` + +## Changing Sanic loggers + +To use your own logging config, simply use `logging.config.dictConfig`, or pass `log_config` when you initialize Sanic app. + +```python +app = Sanic('logging_example', log_config=LOGGING_CONFIG) + +if __name__ == "__main__": + app.run(access_log=False) +``` + +.. tip:: FYI + +``` +Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. + +This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. + +For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +``` + +## Configuration + +Sanic's default logging configuration is: `sanic.log.LOGGING_CONFIG_DEFAULTS`. + +.. column:: + +``` +There are three loggers used in sanic, and must be defined if you want to create your own logging configuration: + +| **Logger Name** | **Use Case** | +|-----------------|-------------------------------| +| `sanic.root` | Used to log internal messages. | +| `sanic.error` | Used to log error logs. | +| `sanic.access` | Used to log access logs. | +``` + +.. column:: + +### Log format + +In addition to default parameters provided by Python (`asctime`, `levelname`, `message`), Sanic provides additional parameters for access logger with. + +| Log Context Parameter | Parameter Value | Datatype | +| --------------------- | ------------------------------------ | -------- | +| `host` | `request.ip` | `str` | +| `request` | `request.method + " " + request.url` | `str` | +| `status` | `response` | `int` | +| `byte` | `len(response.body)` | `int` | + +The default access log format is: + +```text +%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d +``` From ab3edb6f44c10cf7399da5325ce898027f0d34b3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:20 +0200 Subject: [PATCH 065/698] New translations logging.md (Korean) --- .../ko/guide/best-practices/logging.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 guide/content/ko/guide/best-practices/logging.md diff --git a/guide/content/ko/guide/best-practices/logging.md b/guide/content/ko/guide/best-practices/logging.md new file mode 100644 index 0000000000..acc2791c88 --- /dev/null +++ b/guide/content/ko/guide/best-practices/logging.md @@ -0,0 +1,101 @@ +# Logging + +Sanic allows you to do different types of logging (access log, error log) on the requests based on the [Python logging API](https://docs.python.org/3/howto/logging.html). You should have some basic knowledge on Python logging if you want to create a new configuration. + +## Quick Start + +.. column:: + +``` +A simple example using default settings would be like this: +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.log import logger +from sanic.response import text + +app = Sanic('logging_example') + +@app.route('/') +async def test(request): + logger.info('Here is your log') + return text('Hello World!') + +if __name__ == "__main__": + app.run(debug=True, access_log=True) +``` +```` + +After the server is running, you should see logs like this. + +```text +[2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 +[2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] +``` + +You can send a request to server and it will print the log messages. + +```text +[2021-01-04 15:26:28 +0200] [1929659] [INFO] Here is your log +[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: GET http://localhost:8000/ 200 -1 +``` + +## Changing Sanic loggers + +To use your own logging config, simply use `logging.config.dictConfig`, or pass `log_config` when you initialize Sanic app. + +```python +app = Sanic('logging_example', log_config=LOGGING_CONFIG) + +if __name__ == "__main__": + app.run(access_log=False) +``` + +.. tip:: FYI + +``` +Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. + +This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. + +For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +``` + +## Configuration + +Sanic's default logging configuration is: `sanic.log.LOGGING_CONFIG_DEFAULTS`. + +.. column:: + +``` +There are three loggers used in sanic, and must be defined if you want to create your own logging configuration: + +| **Logger Name** | **Use Case** | +|-----------------|-------------------------------| +| `sanic.root` | Used to log internal messages. | +| `sanic.error` | Used to log error logs. | +| `sanic.access` | Used to log access logs. | +``` + +.. column:: + +### Log format + +In addition to default parameters provided by Python (`asctime`, `levelname`, `message`), Sanic provides additional parameters for access logger with. + +| Log Context Parameter | Parameter Value | Datatype | +| --------------------- | ------------------------------------ | -------- | +| `host` | `request.ip` | `str` | +| `request` | `request.method + " " + request.url` | `str` | +| `status` | `response` | `int` | +| `byte` | `len(response.body)` | `int` | + +The default access log format is: + +```text +%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d +``` From b866ce0490154a8f4c8e3c2acf890d091200e4e4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:21 +0200 Subject: [PATCH 066/698] New translations logging.md (Chinese Simplified) --- .../zh/guide/best-practices/logging.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 guide/content/zh/guide/best-practices/logging.md diff --git a/guide/content/zh/guide/best-practices/logging.md b/guide/content/zh/guide/best-practices/logging.md new file mode 100644 index 0000000000..acc2791c88 --- /dev/null +++ b/guide/content/zh/guide/best-practices/logging.md @@ -0,0 +1,101 @@ +# Logging + +Sanic allows you to do different types of logging (access log, error log) on the requests based on the [Python logging API](https://docs.python.org/3/howto/logging.html). You should have some basic knowledge on Python logging if you want to create a new configuration. + +## Quick Start + +.. column:: + +``` +A simple example using default settings would be like this: +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.log import logger +from sanic.response import text + +app = Sanic('logging_example') + +@app.route('/') +async def test(request): + logger.info('Here is your log') + return text('Hello World!') + +if __name__ == "__main__": + app.run(debug=True, access_log=True) +``` +```` + +After the server is running, you should see logs like this. + +```text +[2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 +[2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] +``` + +You can send a request to server and it will print the log messages. + +```text +[2021-01-04 15:26:28 +0200] [1929659] [INFO] Here is your log +[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: GET http://localhost:8000/ 200 -1 +``` + +## Changing Sanic loggers + +To use your own logging config, simply use `logging.config.dictConfig`, or pass `log_config` when you initialize Sanic app. + +```python +app = Sanic('logging_example', log_config=LOGGING_CONFIG) + +if __name__ == "__main__": + app.run(access_log=False) +``` + +.. tip:: FYI + +``` +Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. + +This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. + +For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +``` + +## Configuration + +Sanic's default logging configuration is: `sanic.log.LOGGING_CONFIG_DEFAULTS`. + +.. column:: + +``` +There are three loggers used in sanic, and must be defined if you want to create your own logging configuration: + +| **Logger Name** | **Use Case** | +|-----------------|-------------------------------| +| `sanic.root` | Used to log internal messages. | +| `sanic.error` | Used to log error logs. | +| `sanic.access` | Used to log access logs. | +``` + +.. column:: + +### Log format + +In addition to default parameters provided by Python (`asctime`, `levelname`, `message`), Sanic provides additional parameters for access logger with. + +| Log Context Parameter | Parameter Value | Datatype | +| --------------------- | ------------------------------------ | -------- | +| `host` | `request.ip` | `str` | +| `request` | `request.method + " " + request.url` | `str` | +| `status` | `response` | `int` | +| `byte` | `len(response.body)` | `int` | + +The default access log format is: + +```text +%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d +``` From d3da21d47445fc7cfb3d6614460953f12c7caeb7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:22 +0200 Subject: [PATCH 067/698] New translations testing.md (Japanese) --- guide/content/ja/guide/best-practices/testing.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 guide/content/ja/guide/best-practices/testing.md diff --git a/guide/content/ja/guide/best-practices/testing.md b/guide/content/ja/guide/best-practices/testing.md new file mode 100644 index 0000000000..a7ac6fdaf6 --- /dev/null +++ b/guide/content/ja/guide/best-practices/testing.md @@ -0,0 +1,3 @@ +# Testing + +See [sanic-testing](../../plugins/sanic-testing/getting-started.md) From 6ca15bbf310851b67f8b4ebc86bdaf4395c1eac2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:23 +0200 Subject: [PATCH 068/698] New translations testing.md (Korean) --- guide/content/ko/guide/best-practices/testing.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 guide/content/ko/guide/best-practices/testing.md diff --git a/guide/content/ko/guide/best-practices/testing.md b/guide/content/ko/guide/best-practices/testing.md new file mode 100644 index 0000000000..a7ac6fdaf6 --- /dev/null +++ b/guide/content/ko/guide/best-practices/testing.md @@ -0,0 +1,3 @@ +# Testing + +See [sanic-testing](../../plugins/sanic-testing/getting-started.md) From 04eebbc125860013468a62ca0b7f0d477a330696 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:24 +0200 Subject: [PATCH 069/698] New translations testing.md (Chinese Simplified) --- guide/content/zh/guide/best-practices/testing.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 guide/content/zh/guide/best-practices/testing.md diff --git a/guide/content/zh/guide/best-practices/testing.md b/guide/content/zh/guide/best-practices/testing.md new file mode 100644 index 0000000000..a7ac6fdaf6 --- /dev/null +++ b/guide/content/zh/guide/best-practices/testing.md @@ -0,0 +1,3 @@ +# Testing + +See [sanic-testing](../../plugins/sanic-testing/getting-started.md) From e18452ca9ef894f285effad6fcacf308a0d004e5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:24 +0200 Subject: [PATCH 070/698] New translations caddy.md (Japanese) --- guide/content/ja/guide/deployment/caddy.md | 74 ++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 guide/content/ja/guide/deployment/caddy.md diff --git a/guide/content/ja/guide/deployment/caddy.md b/guide/content/ja/guide/deployment/caddy.md new file mode 100644 index 0000000000..77d8eb39fc --- /dev/null +++ b/guide/content/ja/guide/deployment/caddy.md @@ -0,0 +1,74 @@ +# Caddy Deployment + +## Introduction + +Caddy is a state-of-the-art web server and proxy that supports up to HTTP/3. Its simplicity lies in its minimalistic configuration and the inbuilt ability to automatically procure TLS certificates for your domains from Let's Encrypt. In this setup, we will configure the Sanic application to serve locally at 127.0.0.1:8001, with Caddy playing the role of the public-facing server for the domain example.com. + +You may install Caddy from your favorite package menager on Windows, Linux and Mac. The package is named `caddy`. + +## Proxied Sanic app + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("proxied_example") + +@app.get("/") +def index(request): + # This should display external (public) addresses: + return text( + f"{request.remote_addr} connected to {request.url_for('index')}\n" + f"Forwarded: {request.forwarded}\n" + ) +``` + +To run this application, save as `proxied_example.py`, and use the sanic command-line interface as follows: + +```bash +SANIC_PROXIES_COUNT=1 sanic proxied_example --port 8001 +``` + +Setting the SANIC_PROXIES_COUNT environment variable instructs Sanic to trust the X-Forwarded-\* headers sent by Caddy, allowing it to correctly identify the client's IP address and other information. + +## Caddy is simple + +If you have no other web servers running, you can simply run Caddy CLI (needs `sudo` on Linux): + +```bash +caddy reverse-proxy --from example.com --to :8001 +``` + +This is a complete server that includes a certificate for your domain, http-to-https redirect, proxy headers, streaming and WebSockets. Your Sanic application should now be available on the domain you specified by HTTP versions 1, 2 and 3. Remember to open up UDP/443 on your firewall to enable H3 communications. + +All done? + +Soon enough you'll be needing more than one server, or more control over details, which is where the configuration files come in. The above command is equivalent to this `Caddyfile`, serving as a good starting point for your install: + +``` +example.com { + reverse_proxy localhost:8001 +} +``` + +Some Linux distributions install Caddy such that it reads configuration from `/etc/caddy/Caddyfile`, which `import /etc/caddy/conf.d/*` for each site you are running. If not, you'll need to manually run `caddy run` as a system service, pointing it at the proper config file. Alternatively, use Caddy API mode with `caddy run --resume` for persistent config changes. Note that any Caddyfile loading will replace all prior configuration and thus `caddy-api` is not configurable in this traditional manner. + +## Advanced configuration + +At times, you might need to mix static files and handlers at the site root for cleaner URLs. In Sanic, you'd use `app.static("/", "static", index="index.html")` to achieve this. However, for improved performance, you can offload serving static files to Caddy: + +``` +app.example.com { + # Look for static files first, proxy to Sanic if not found + route { + file_server { + root /srv/sanicexample/static + precompress br # brotli your large scripts and styles + pass_thru + } + reverse_proxy unix//tmp/sanic.socket # sanic --unix /tmp/sanic.socket + } +} +``` + +Please refer to [Caddy documentation](https://caddyserver.com/docs/) for more options. From 68475c2401fa93a62b085cb155079aef23b19e1f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:25 +0200 Subject: [PATCH 071/698] New translations caddy.md (Korean) --- guide/content/ko/guide/deployment/caddy.md | 74 ++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 guide/content/ko/guide/deployment/caddy.md diff --git a/guide/content/ko/guide/deployment/caddy.md b/guide/content/ko/guide/deployment/caddy.md new file mode 100644 index 0000000000..77d8eb39fc --- /dev/null +++ b/guide/content/ko/guide/deployment/caddy.md @@ -0,0 +1,74 @@ +# Caddy Deployment + +## Introduction + +Caddy is a state-of-the-art web server and proxy that supports up to HTTP/3. Its simplicity lies in its minimalistic configuration and the inbuilt ability to automatically procure TLS certificates for your domains from Let's Encrypt. In this setup, we will configure the Sanic application to serve locally at 127.0.0.1:8001, with Caddy playing the role of the public-facing server for the domain example.com. + +You may install Caddy from your favorite package menager on Windows, Linux and Mac. The package is named `caddy`. + +## Proxied Sanic app + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("proxied_example") + +@app.get("/") +def index(request): + # This should display external (public) addresses: + return text( + f"{request.remote_addr} connected to {request.url_for('index')}\n" + f"Forwarded: {request.forwarded}\n" + ) +``` + +To run this application, save as `proxied_example.py`, and use the sanic command-line interface as follows: + +```bash +SANIC_PROXIES_COUNT=1 sanic proxied_example --port 8001 +``` + +Setting the SANIC_PROXIES_COUNT environment variable instructs Sanic to trust the X-Forwarded-\* headers sent by Caddy, allowing it to correctly identify the client's IP address and other information. + +## Caddy is simple + +If you have no other web servers running, you can simply run Caddy CLI (needs `sudo` on Linux): + +```bash +caddy reverse-proxy --from example.com --to :8001 +``` + +This is a complete server that includes a certificate for your domain, http-to-https redirect, proxy headers, streaming and WebSockets. Your Sanic application should now be available on the domain you specified by HTTP versions 1, 2 and 3. Remember to open up UDP/443 on your firewall to enable H3 communications. + +All done? + +Soon enough you'll be needing more than one server, or more control over details, which is where the configuration files come in. The above command is equivalent to this `Caddyfile`, serving as a good starting point for your install: + +``` +example.com { + reverse_proxy localhost:8001 +} +``` + +Some Linux distributions install Caddy such that it reads configuration from `/etc/caddy/Caddyfile`, which `import /etc/caddy/conf.d/*` for each site you are running. If not, you'll need to manually run `caddy run` as a system service, pointing it at the proper config file. Alternatively, use Caddy API mode with `caddy run --resume` for persistent config changes. Note that any Caddyfile loading will replace all prior configuration and thus `caddy-api` is not configurable in this traditional manner. + +## Advanced configuration + +At times, you might need to mix static files and handlers at the site root for cleaner URLs. In Sanic, you'd use `app.static("/", "static", index="index.html")` to achieve this. However, for improved performance, you can offload serving static files to Caddy: + +``` +app.example.com { + # Look for static files first, proxy to Sanic if not found + route { + file_server { + root /srv/sanicexample/static + precompress br # brotli your large scripts and styles + pass_thru + } + reverse_proxy unix//tmp/sanic.socket # sanic --unix /tmp/sanic.socket + } +} +``` + +Please refer to [Caddy documentation](https://caddyserver.com/docs/) for more options. From 7296e95c13ef36744500fd8963b909d90913fbe8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:26 +0200 Subject: [PATCH 072/698] New translations caddy.md (Chinese Simplified) --- guide/content/zh/guide/deployment/caddy.md | 74 ++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 guide/content/zh/guide/deployment/caddy.md diff --git a/guide/content/zh/guide/deployment/caddy.md b/guide/content/zh/guide/deployment/caddy.md new file mode 100644 index 0000000000..77d8eb39fc --- /dev/null +++ b/guide/content/zh/guide/deployment/caddy.md @@ -0,0 +1,74 @@ +# Caddy Deployment + +## Introduction + +Caddy is a state-of-the-art web server and proxy that supports up to HTTP/3. Its simplicity lies in its minimalistic configuration and the inbuilt ability to automatically procure TLS certificates for your domains from Let's Encrypt. In this setup, we will configure the Sanic application to serve locally at 127.0.0.1:8001, with Caddy playing the role of the public-facing server for the domain example.com. + +You may install Caddy from your favorite package menager on Windows, Linux and Mac. The package is named `caddy`. + +## Proxied Sanic app + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("proxied_example") + +@app.get("/") +def index(request): + # This should display external (public) addresses: + return text( + f"{request.remote_addr} connected to {request.url_for('index')}\n" + f"Forwarded: {request.forwarded}\n" + ) +``` + +To run this application, save as `proxied_example.py`, and use the sanic command-line interface as follows: + +```bash +SANIC_PROXIES_COUNT=1 sanic proxied_example --port 8001 +``` + +Setting the SANIC_PROXIES_COUNT environment variable instructs Sanic to trust the X-Forwarded-\* headers sent by Caddy, allowing it to correctly identify the client's IP address and other information. + +## Caddy is simple + +If you have no other web servers running, you can simply run Caddy CLI (needs `sudo` on Linux): + +```bash +caddy reverse-proxy --from example.com --to :8001 +``` + +This is a complete server that includes a certificate for your domain, http-to-https redirect, proxy headers, streaming and WebSockets. Your Sanic application should now be available on the domain you specified by HTTP versions 1, 2 and 3. Remember to open up UDP/443 on your firewall to enable H3 communications. + +All done? + +Soon enough you'll be needing more than one server, or more control over details, which is where the configuration files come in. The above command is equivalent to this `Caddyfile`, serving as a good starting point for your install: + +``` +example.com { + reverse_proxy localhost:8001 +} +``` + +Some Linux distributions install Caddy such that it reads configuration from `/etc/caddy/Caddyfile`, which `import /etc/caddy/conf.d/*` for each site you are running. If not, you'll need to manually run `caddy run` as a system service, pointing it at the proper config file. Alternatively, use Caddy API mode with `caddy run --resume` for persistent config changes. Note that any Caddyfile loading will replace all prior configuration and thus `caddy-api` is not configurable in this traditional manner. + +## Advanced configuration + +At times, you might need to mix static files and handlers at the site root for cleaner URLs. In Sanic, you'd use `app.static("/", "static", index="index.html")` to achieve this. However, for improved performance, you can offload serving static files to Caddy: + +``` +app.example.com { + # Look for static files first, proxy to Sanic if not found + route { + file_server { + root /srv/sanicexample/static + precompress br # brotli your large scripts and styles + pass_thru + } + reverse_proxy unix//tmp/sanic.socket # sanic --unix /tmp/sanic.socket + } +} +``` + +Please refer to [Caddy documentation](https://caddyserver.com/docs/) for more options. From 8e6d13e2120e340b925d8296de25e5a60fa607da Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:27 +0200 Subject: [PATCH 073/698] New translations docker.md (Japanese) --- guide/content/ja/guide/deployment/docker.md | 199 ++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/ja/guide/deployment/docker.md diff --git a/guide/content/ja/guide/deployment/docker.md b/guide/content/ja/guide/deployment/docker.md new file mode 100644 index 0000000000..fe6f0dd05f --- /dev/null +++ b/guide/content/ja/guide/deployment/docker.md @@ -0,0 +1,199 @@ +# Docker Deployment + +## Introduction + +For a long time, the environment has always been a difficult problem for deployment. If there are conflicting configurations in your project, you have to spend a lot of time resolving them. Fortunately, virtualization provides us with a good solution. Docker is one of them. If you don't know Docker, you can visit [Docker official website](https://www.docker.com/) to learn more. + +## Build Image + +Let's start with a simple project. We will use a Sanic project as an example. Assume the project path is `/path/to/SanicDocker`. + +.. column:: + +``` +The directory structure looks like this: +``` + +.. column:: + +```` +```text +# /path/to/SanicDocker +SanicDocker +├── requirements.txt +├── dockerfile +└── server.py +``` +```` + +.. column:: + +``` +And the `server.py` code looks like this: +``` + +.. column:: + +```` +```python +app = Sanic("MySanicApp") + +@app.get('/') +async def hello(request): + return text("OK!") + +if __name__ == '__main__': + app.run(host='0.0.0.0', port=8000) +``` +```` + +.. note:: + +``` +Please note that the host cannot be 127.0.0.1 . In docker container, 127.0.0.1 is the default network interface of the container, only the container can communicate with other containers. more information please visit [Docker network](https://docs.docker.com/engine/reference/commandline/network/) +``` + +Code is ready, let's write the `Dockerfile`: + +```Dockerfile + +FROM sanicframework/sanic:3.8-latest + +WORKDIR /sanic + +COPY . . + +RUN pip install -r requirements.txt + +EXPOSE 8000 + +CMD ["python", "server.py"] +``` + +Run the following command to build the image: + +```shell +docker build -t my-sanic-image . +``` + +## Start Container + +.. column:: + +``` +After the image built, we can start the container use `my-sanic-image`: +``` + +.. column:: + +```` +```shell +docker run --name mysanic -p 8000:8000 -d my-sanic-image +``` +```` + +.. column:: + +``` +Now we can visit `http://localhost:8000` to see the result: +``` + +.. column:: + +```` +```text +OK! +``` +```` + +## Use docker-compose + +If your project consist of multiple services, you can use [docker-compose](https://docs.docker.com/compose/) to manage them. + +for example, we will deploy `my-sanic-image` and `nginx`, achieve through nginx access sanic server. + +.. column:: + +``` +First of all, we need prepare nginx configuration file. create a file named `mysanic.conf`: +``` + +.. column:: + +```` +```nginx +server { + listen 80; + listen [::]:80; + location / { + proxy_pass http://mysanic:8000/; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection upgrade; + proxy_set_header Accept-Encoding gzip; + } +} +``` +```` + +.. column:: + +``` +Then, we need to prepare `docker-compose.yml` file. The content follows: +``` + +.. column:: + +```` +```yaml +version: "3" + +services: + mysanic: + image: my-sanic-image + ports: + - "8000:8000" + restart: always + + mynginx: + image: nginx:1.13.6-alpine + ports: + - "80:80" + depends_on: + - mysanic + volumes: + - ./mysanic.conf:/etc/nginx/conf.d/mysanic.conf + restart: always + +networks: + default: + driver: bridge +``` +```` + +.. column:: + +``` +After that, we can start them: +``` + +.. column:: + +```` +```shell +docker-compose up -d +``` +```` + +.. column:: + +``` +Now, we can visit `http://localhost:80` to see the result: +``` + +.. column:: + +```` +```text +OK! +``` +```` From 630f29dd1b80bb4fc5ee11509ea09d4dc47d9dcf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:28 +0200 Subject: [PATCH 074/698] New translations docker.md (Korean) --- guide/content/ko/guide/deployment/docker.md | 199 ++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/ko/guide/deployment/docker.md diff --git a/guide/content/ko/guide/deployment/docker.md b/guide/content/ko/guide/deployment/docker.md new file mode 100644 index 0000000000..fe6f0dd05f --- /dev/null +++ b/guide/content/ko/guide/deployment/docker.md @@ -0,0 +1,199 @@ +# Docker Deployment + +## Introduction + +For a long time, the environment has always been a difficult problem for deployment. If there are conflicting configurations in your project, you have to spend a lot of time resolving them. Fortunately, virtualization provides us with a good solution. Docker is one of them. If you don't know Docker, you can visit [Docker official website](https://www.docker.com/) to learn more. + +## Build Image + +Let's start with a simple project. We will use a Sanic project as an example. Assume the project path is `/path/to/SanicDocker`. + +.. column:: + +``` +The directory structure looks like this: +``` + +.. column:: + +```` +```text +# /path/to/SanicDocker +SanicDocker +├── requirements.txt +├── dockerfile +└── server.py +``` +```` + +.. column:: + +``` +And the `server.py` code looks like this: +``` + +.. column:: + +```` +```python +app = Sanic("MySanicApp") + +@app.get('/') +async def hello(request): + return text("OK!") + +if __name__ == '__main__': + app.run(host='0.0.0.0', port=8000) +``` +```` + +.. note:: + +``` +Please note that the host cannot be 127.0.0.1 . In docker container, 127.0.0.1 is the default network interface of the container, only the container can communicate with other containers. more information please visit [Docker network](https://docs.docker.com/engine/reference/commandline/network/) +``` + +Code is ready, let's write the `Dockerfile`: + +```Dockerfile + +FROM sanicframework/sanic:3.8-latest + +WORKDIR /sanic + +COPY . . + +RUN pip install -r requirements.txt + +EXPOSE 8000 + +CMD ["python", "server.py"] +``` + +Run the following command to build the image: + +```shell +docker build -t my-sanic-image . +``` + +## Start Container + +.. column:: + +``` +After the image built, we can start the container use `my-sanic-image`: +``` + +.. column:: + +```` +```shell +docker run --name mysanic -p 8000:8000 -d my-sanic-image +``` +```` + +.. column:: + +``` +Now we can visit `http://localhost:8000` to see the result: +``` + +.. column:: + +```` +```text +OK! +``` +```` + +## Use docker-compose + +If your project consist of multiple services, you can use [docker-compose](https://docs.docker.com/compose/) to manage them. + +for example, we will deploy `my-sanic-image` and `nginx`, achieve through nginx access sanic server. + +.. column:: + +``` +First of all, we need prepare nginx configuration file. create a file named `mysanic.conf`: +``` + +.. column:: + +```` +```nginx +server { + listen 80; + listen [::]:80; + location / { + proxy_pass http://mysanic:8000/; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection upgrade; + proxy_set_header Accept-Encoding gzip; + } +} +``` +```` + +.. column:: + +``` +Then, we need to prepare `docker-compose.yml` file. The content follows: +``` + +.. column:: + +```` +```yaml +version: "3" + +services: + mysanic: + image: my-sanic-image + ports: + - "8000:8000" + restart: always + + mynginx: + image: nginx:1.13.6-alpine + ports: + - "80:80" + depends_on: + - mysanic + volumes: + - ./mysanic.conf:/etc/nginx/conf.d/mysanic.conf + restart: always + +networks: + default: + driver: bridge +``` +```` + +.. column:: + +``` +After that, we can start them: +``` + +.. column:: + +```` +```shell +docker-compose up -d +``` +```` + +.. column:: + +``` +Now, we can visit `http://localhost:80` to see the result: +``` + +.. column:: + +```` +```text +OK! +``` +```` From baea463e82f8da8fa1f6803a9b1424d725530b85 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:29 +0200 Subject: [PATCH 075/698] New translations docker.md (Chinese Simplified) --- guide/content/zh/guide/deployment/docker.md | 199 ++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/zh/guide/deployment/docker.md diff --git a/guide/content/zh/guide/deployment/docker.md b/guide/content/zh/guide/deployment/docker.md new file mode 100644 index 0000000000..fe6f0dd05f --- /dev/null +++ b/guide/content/zh/guide/deployment/docker.md @@ -0,0 +1,199 @@ +# Docker Deployment + +## Introduction + +For a long time, the environment has always been a difficult problem for deployment. If there are conflicting configurations in your project, you have to spend a lot of time resolving them. Fortunately, virtualization provides us with a good solution. Docker is one of them. If you don't know Docker, you can visit [Docker official website](https://www.docker.com/) to learn more. + +## Build Image + +Let's start with a simple project. We will use a Sanic project as an example. Assume the project path is `/path/to/SanicDocker`. + +.. column:: + +``` +The directory structure looks like this: +``` + +.. column:: + +```` +```text +# /path/to/SanicDocker +SanicDocker +├── requirements.txt +├── dockerfile +└── server.py +``` +```` + +.. column:: + +``` +And the `server.py` code looks like this: +``` + +.. column:: + +```` +```python +app = Sanic("MySanicApp") + +@app.get('/') +async def hello(request): + return text("OK!") + +if __name__ == '__main__': + app.run(host='0.0.0.0', port=8000) +``` +```` + +.. note:: + +``` +Please note that the host cannot be 127.0.0.1 . In docker container, 127.0.0.1 is the default network interface of the container, only the container can communicate with other containers. more information please visit [Docker network](https://docs.docker.com/engine/reference/commandline/network/) +``` + +Code is ready, let's write the `Dockerfile`: + +```Dockerfile + +FROM sanicframework/sanic:3.8-latest + +WORKDIR /sanic + +COPY . . + +RUN pip install -r requirements.txt + +EXPOSE 8000 + +CMD ["python", "server.py"] +``` + +Run the following command to build the image: + +```shell +docker build -t my-sanic-image . +``` + +## Start Container + +.. column:: + +``` +After the image built, we can start the container use `my-sanic-image`: +``` + +.. column:: + +```` +```shell +docker run --name mysanic -p 8000:8000 -d my-sanic-image +``` +```` + +.. column:: + +``` +Now we can visit `http://localhost:8000` to see the result: +``` + +.. column:: + +```` +```text +OK! +``` +```` + +## Use docker-compose + +If your project consist of multiple services, you can use [docker-compose](https://docs.docker.com/compose/) to manage them. + +for example, we will deploy `my-sanic-image` and `nginx`, achieve through nginx access sanic server. + +.. column:: + +``` +First of all, we need prepare nginx configuration file. create a file named `mysanic.conf`: +``` + +.. column:: + +```` +```nginx +server { + listen 80; + listen [::]:80; + location / { + proxy_pass http://mysanic:8000/; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection upgrade; + proxy_set_header Accept-Encoding gzip; + } +} +``` +```` + +.. column:: + +``` +Then, we need to prepare `docker-compose.yml` file. The content follows: +``` + +.. column:: + +```` +```yaml +version: "3" + +services: + mysanic: + image: my-sanic-image + ports: + - "8000:8000" + restart: always + + mynginx: + image: nginx:1.13.6-alpine + ports: + - "80:80" + depends_on: + - mysanic + volumes: + - ./mysanic.conf:/etc/nginx/conf.d/mysanic.conf + restart: always + +networks: + default: + driver: bridge +``` +```` + +.. column:: + +``` +After that, we can start them: +``` + +.. column:: + +```` +```shell +docker-compose up -d +``` +```` + +.. column:: + +``` +Now, we can visit `http://localhost:80` to see the result: +``` + +.. column:: + +```` +```text +OK! +``` +```` From efadc9592185cba3bc951e2117cf7b23c4874b5a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:30 +0200 Subject: [PATCH 076/698] New translations kubernetes.md (Japanese) --- guide/content/ja/guide/deployment/kubernetes.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/deployment/kubernetes.md diff --git a/guide/content/ja/guide/deployment/kubernetes.md b/guide/content/ja/guide/deployment/kubernetes.md new file mode 100644 index 0000000000..8d6340de1c --- /dev/null +++ b/guide/content/ja/guide/deployment/kubernetes.md @@ -0,0 +1 @@ +# Kubernetes From b298d023d5063be6711aa3b762e06bb693233380 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:31 +0200 Subject: [PATCH 077/698] New translations kubernetes.md (Korean) --- guide/content/ko/guide/deployment/kubernetes.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/deployment/kubernetes.md diff --git a/guide/content/ko/guide/deployment/kubernetes.md b/guide/content/ko/guide/deployment/kubernetes.md new file mode 100644 index 0000000000..8d6340de1c --- /dev/null +++ b/guide/content/ko/guide/deployment/kubernetes.md @@ -0,0 +1 @@ +# Kubernetes From 97d0f0e6cc2b036eb9285ce20474c7051db0d185 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:32 +0200 Subject: [PATCH 078/698] New translations kubernetes.md (Chinese Simplified) --- guide/content/zh/guide/deployment/kubernetes.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/deployment/kubernetes.md diff --git a/guide/content/zh/guide/deployment/kubernetes.md b/guide/content/zh/guide/deployment/kubernetes.md new file mode 100644 index 0000000000..8d6340de1c --- /dev/null +++ b/guide/content/zh/guide/deployment/kubernetes.md @@ -0,0 +1 @@ +# Kubernetes From 138ff08ce3e6f48174ab85c4b22550b6a1864924 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:33 +0200 Subject: [PATCH 079/698] New translations nginx.md (Japanese) --- guide/content/ja/guide/deployment/nginx.md | 172 +++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 guide/content/ja/guide/deployment/nginx.md diff --git a/guide/content/ja/guide/deployment/nginx.md b/guide/content/ja/guide/deployment/nginx.md new file mode 100644 index 0000000000..ee78d2967a --- /dev/null +++ b/guide/content/ja/guide/deployment/nginx.md @@ -0,0 +1,172 @@ +# Nginx Deployment + +## Introduction + +Although Sanic can be run directly on Internet, it may be useful to use a proxy +server such as Nginx in front of it. This is particularly useful for running +multiple virtual hosts on the same IP, serving NodeJS or other services beside +a single Sanic app, and it also allows for efficient serving of static files. +TLS and HTTP/2 are also easily implemented on such proxy. + +We are setting the Sanic app to serve only locally at 127.0.0.1:8001, while the +Nginx installation is responsible for providing the service to public Internet +on domain example.com. Static files will be served by Nginx for maximal +performance. + +## Proxied Sanic app + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("proxied_example") + +@app.get("/") +def index(request): + # This should display external (public) addresses: + return text( + f"{request.remote_addr} connected to {request.url_for('index')}\n" + f"Forwarded: {request.forwarded}\n" + ) +``` + +Since this is going to be a system service, save your code to +`/srv/sanicservice/proxied_example.py`. + +For testing, run your app in a terminal using the `sanic` CLI in the folder where you saved the file. + +```bash +SANIC_FORWARDED_SECRET=_hostname sanic proxied_example --port 8001 +``` + +We provide Sanic config `FORWARDED_SECRET` to identify which proxy it gets +the remote addresses from. Note the `_` in front of the local hostname. +This gives basic protection against users spoofing these headers and faking +their IP addresses and more. + +## SSL certificates + +Install Certbot and obtain a certicate for all your domains. This will spin up its own webserver on port 80 for a moment to verify you control the given domain names. + +```bash +certbot -d example.com -d www.example.com +``` + +## Nginx configuration + +Quite much configuration is required to allow fast transparent proxying, but +for the most part these don't need to be modified, so bear with me. + +.. tip:: Note + +``` +Separate upstream section, rather than simply adding the IP after `proxy_pass` +as in most tutorials, is needed for HTTP keep-alive. We also enable streaming, +WebSockets and Nginx serving static files. +``` + +The following config goes inside the `http` section of `nginx.conf` or if your +system uses multiple config files, `/etc/nginx/sites-available/default` or +your own files (be sure to symlink them to `sites-enabled`): + +```nginx +# Files managed by Certbot +ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; +ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; + +# Sanic service +upstream example.com { + keepalive 100; + server 127.0.0.1:8001; + #server unix:/tmp//sanic.sock; +} + +server { + server_name example.com; + listen 443 ssl http2 default_server; + listen [::]:443 ssl http2 default_server; + # Serve static files if found, otherwise proxy to Sanic + location / { + root /srv/sanicexample/static; + try_files $uri @sanic; + } + location @sanic { + proxy_pass http://$server_name; + # Allow fast streaming HTTP/1.1 pipes (keep-alive, unbuffered) + proxy_http_version 1.1; + proxy_request_buffering off; + proxy_buffering off; + proxy_set_header forwarded 'by=\"_$hostname\";$for_addr;proto=$scheme;host=\"$http_host\"'; + # Allow websockets and keep-alive (avoid connection: close) + proxy_set_header connection "upgrade"; + proxy_set_header upgrade $http_upgrade; + } +} + +# Redirect WWW to no-WWW +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name ~^www\.(.*)$; + return 308 $scheme://$1$request_uri; +} + +# Redirect all HTTP to HTTPS with no-WWW +server { + listen 80 default_server; + listen [::]:80 default_server; + server_name ~^(?:www\.)?(.*)$; + return 308 https://$1$request_uri; +} + +# Forwarded for= client IP address formatting +map $remote_addr $for_addr { + ~^[0-9.]+$ "for=$remote_addr"; # IPv4 client address + ~^[0-9A-Fa-f:.]+$ "for=\"[$remote_addr]\""; # IPv6 bracketed and quoted + default "for=unknown"; # Unix socket +} +``` + +Start or restart Nginx for changes to take effect. E.g. + +```bash +systemctl restart nginx +``` + +You should be able to connect your app on `https://example.com`. Any 404 +errors and such will be handled by Sanic's error pages, and whenever a static +file is present at a given path, it will be served by Nginx. + +## Running as a service + +This part is for Linux distributions based on `systemd`. Create a unit file +`/etc/systemd/system/sanicexample.service` + +``` +[Unit] +Description=Sanic Example + +[Service] +DynamicUser=Yes +WorkingDirectory=/srv/sanicservice +Environment=SANIC_PROXY_SECRET=_hostname +ExecStart=sanic proxied_example --port 8001 --fast +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Then reload service files, start your service and enable it on boot: + +```bash +systemctl daemon-reload +systemctl start sanicexample +systemctl enable sanicexample +``` + +.. tip:: Note + +``` +For brevity we skipped setting up a separate user account and a Python virtual environment or installing your app as a Python module. There are good tutorials on those topics elsewhere that easily apply to Sanic as well. The DynamicUser setting creates a strong sandbox which basically means your application cannot store its data in files, so you may consider setting `User=sanicexample` instead if you need that. +``` From 43ef5ce73882d6de0b1bb74683f2c17dd071c3cb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:34 +0200 Subject: [PATCH 080/698] New translations nginx.md (Korean) --- guide/content/ko/guide/deployment/nginx.md | 172 +++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 guide/content/ko/guide/deployment/nginx.md diff --git a/guide/content/ko/guide/deployment/nginx.md b/guide/content/ko/guide/deployment/nginx.md new file mode 100644 index 0000000000..ee78d2967a --- /dev/null +++ b/guide/content/ko/guide/deployment/nginx.md @@ -0,0 +1,172 @@ +# Nginx Deployment + +## Introduction + +Although Sanic can be run directly on Internet, it may be useful to use a proxy +server such as Nginx in front of it. This is particularly useful for running +multiple virtual hosts on the same IP, serving NodeJS or other services beside +a single Sanic app, and it also allows for efficient serving of static files. +TLS and HTTP/2 are also easily implemented on such proxy. + +We are setting the Sanic app to serve only locally at 127.0.0.1:8001, while the +Nginx installation is responsible for providing the service to public Internet +on domain example.com. Static files will be served by Nginx for maximal +performance. + +## Proxied Sanic app + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("proxied_example") + +@app.get("/") +def index(request): + # This should display external (public) addresses: + return text( + f"{request.remote_addr} connected to {request.url_for('index')}\n" + f"Forwarded: {request.forwarded}\n" + ) +``` + +Since this is going to be a system service, save your code to +`/srv/sanicservice/proxied_example.py`. + +For testing, run your app in a terminal using the `sanic` CLI in the folder where you saved the file. + +```bash +SANIC_FORWARDED_SECRET=_hostname sanic proxied_example --port 8001 +``` + +We provide Sanic config `FORWARDED_SECRET` to identify which proxy it gets +the remote addresses from. Note the `_` in front of the local hostname. +This gives basic protection against users spoofing these headers and faking +their IP addresses and more. + +## SSL certificates + +Install Certbot and obtain a certicate for all your domains. This will spin up its own webserver on port 80 for a moment to verify you control the given domain names. + +```bash +certbot -d example.com -d www.example.com +``` + +## Nginx configuration + +Quite much configuration is required to allow fast transparent proxying, but +for the most part these don't need to be modified, so bear with me. + +.. tip:: Note + +``` +Separate upstream section, rather than simply adding the IP after `proxy_pass` +as in most tutorials, is needed for HTTP keep-alive. We also enable streaming, +WebSockets and Nginx serving static files. +``` + +The following config goes inside the `http` section of `nginx.conf` or if your +system uses multiple config files, `/etc/nginx/sites-available/default` or +your own files (be sure to symlink them to `sites-enabled`): + +```nginx +# Files managed by Certbot +ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; +ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; + +# Sanic service +upstream example.com { + keepalive 100; + server 127.0.0.1:8001; + #server unix:/tmp//sanic.sock; +} + +server { + server_name example.com; + listen 443 ssl http2 default_server; + listen [::]:443 ssl http2 default_server; + # Serve static files if found, otherwise proxy to Sanic + location / { + root /srv/sanicexample/static; + try_files $uri @sanic; + } + location @sanic { + proxy_pass http://$server_name; + # Allow fast streaming HTTP/1.1 pipes (keep-alive, unbuffered) + proxy_http_version 1.1; + proxy_request_buffering off; + proxy_buffering off; + proxy_set_header forwarded 'by=\"_$hostname\";$for_addr;proto=$scheme;host=\"$http_host\"'; + # Allow websockets and keep-alive (avoid connection: close) + proxy_set_header connection "upgrade"; + proxy_set_header upgrade $http_upgrade; + } +} + +# Redirect WWW to no-WWW +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name ~^www\.(.*)$; + return 308 $scheme://$1$request_uri; +} + +# Redirect all HTTP to HTTPS with no-WWW +server { + listen 80 default_server; + listen [::]:80 default_server; + server_name ~^(?:www\.)?(.*)$; + return 308 https://$1$request_uri; +} + +# Forwarded for= client IP address formatting +map $remote_addr $for_addr { + ~^[0-9.]+$ "for=$remote_addr"; # IPv4 client address + ~^[0-9A-Fa-f:.]+$ "for=\"[$remote_addr]\""; # IPv6 bracketed and quoted + default "for=unknown"; # Unix socket +} +``` + +Start or restart Nginx for changes to take effect. E.g. + +```bash +systemctl restart nginx +``` + +You should be able to connect your app on `https://example.com`. Any 404 +errors and such will be handled by Sanic's error pages, and whenever a static +file is present at a given path, it will be served by Nginx. + +## Running as a service + +This part is for Linux distributions based on `systemd`. Create a unit file +`/etc/systemd/system/sanicexample.service` + +``` +[Unit] +Description=Sanic Example + +[Service] +DynamicUser=Yes +WorkingDirectory=/srv/sanicservice +Environment=SANIC_PROXY_SECRET=_hostname +ExecStart=sanic proxied_example --port 8001 --fast +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Then reload service files, start your service and enable it on boot: + +```bash +systemctl daemon-reload +systemctl start sanicexample +systemctl enable sanicexample +``` + +.. tip:: Note + +``` +For brevity we skipped setting up a separate user account and a Python virtual environment or installing your app as a Python module. There are good tutorials on those topics elsewhere that easily apply to Sanic as well. The DynamicUser setting creates a strong sandbox which basically means your application cannot store its data in files, so you may consider setting `User=sanicexample` instead if you need that. +``` From bbc3383fb20c7104509af367ee608c7a7e8c3195 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:34 +0200 Subject: [PATCH 081/698] New translations nginx.md (Chinese Simplified) --- guide/content/zh/guide/deployment/nginx.md | 172 +++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 guide/content/zh/guide/deployment/nginx.md diff --git a/guide/content/zh/guide/deployment/nginx.md b/guide/content/zh/guide/deployment/nginx.md new file mode 100644 index 0000000000..ee78d2967a --- /dev/null +++ b/guide/content/zh/guide/deployment/nginx.md @@ -0,0 +1,172 @@ +# Nginx Deployment + +## Introduction + +Although Sanic can be run directly on Internet, it may be useful to use a proxy +server such as Nginx in front of it. This is particularly useful for running +multiple virtual hosts on the same IP, serving NodeJS or other services beside +a single Sanic app, and it also allows for efficient serving of static files. +TLS and HTTP/2 are also easily implemented on such proxy. + +We are setting the Sanic app to serve only locally at 127.0.0.1:8001, while the +Nginx installation is responsible for providing the service to public Internet +on domain example.com. Static files will be served by Nginx for maximal +performance. + +## Proxied Sanic app + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("proxied_example") + +@app.get("/") +def index(request): + # This should display external (public) addresses: + return text( + f"{request.remote_addr} connected to {request.url_for('index')}\n" + f"Forwarded: {request.forwarded}\n" + ) +``` + +Since this is going to be a system service, save your code to +`/srv/sanicservice/proxied_example.py`. + +For testing, run your app in a terminal using the `sanic` CLI in the folder where you saved the file. + +```bash +SANIC_FORWARDED_SECRET=_hostname sanic proxied_example --port 8001 +``` + +We provide Sanic config `FORWARDED_SECRET` to identify which proxy it gets +the remote addresses from. Note the `_` in front of the local hostname. +This gives basic protection against users spoofing these headers and faking +their IP addresses and more. + +## SSL certificates + +Install Certbot and obtain a certicate for all your domains. This will spin up its own webserver on port 80 for a moment to verify you control the given domain names. + +```bash +certbot -d example.com -d www.example.com +``` + +## Nginx configuration + +Quite much configuration is required to allow fast transparent proxying, but +for the most part these don't need to be modified, so bear with me. + +.. tip:: Note + +``` +Separate upstream section, rather than simply adding the IP after `proxy_pass` +as in most tutorials, is needed for HTTP keep-alive. We also enable streaming, +WebSockets and Nginx serving static files. +``` + +The following config goes inside the `http` section of `nginx.conf` or if your +system uses multiple config files, `/etc/nginx/sites-available/default` or +your own files (be sure to symlink them to `sites-enabled`): + +```nginx +# Files managed by Certbot +ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; +ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; + +# Sanic service +upstream example.com { + keepalive 100; + server 127.0.0.1:8001; + #server unix:/tmp//sanic.sock; +} + +server { + server_name example.com; + listen 443 ssl http2 default_server; + listen [::]:443 ssl http2 default_server; + # Serve static files if found, otherwise proxy to Sanic + location / { + root /srv/sanicexample/static; + try_files $uri @sanic; + } + location @sanic { + proxy_pass http://$server_name; + # Allow fast streaming HTTP/1.1 pipes (keep-alive, unbuffered) + proxy_http_version 1.1; + proxy_request_buffering off; + proxy_buffering off; + proxy_set_header forwarded 'by=\"_$hostname\";$for_addr;proto=$scheme;host=\"$http_host\"'; + # Allow websockets and keep-alive (avoid connection: close) + proxy_set_header connection "upgrade"; + proxy_set_header upgrade $http_upgrade; + } +} + +# Redirect WWW to no-WWW +server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name ~^www\.(.*)$; + return 308 $scheme://$1$request_uri; +} + +# Redirect all HTTP to HTTPS with no-WWW +server { + listen 80 default_server; + listen [::]:80 default_server; + server_name ~^(?:www\.)?(.*)$; + return 308 https://$1$request_uri; +} + +# Forwarded for= client IP address formatting +map $remote_addr $for_addr { + ~^[0-9.]+$ "for=$remote_addr"; # IPv4 client address + ~^[0-9A-Fa-f:.]+$ "for=\"[$remote_addr]\""; # IPv6 bracketed and quoted + default "for=unknown"; # Unix socket +} +``` + +Start or restart Nginx for changes to take effect. E.g. + +```bash +systemctl restart nginx +``` + +You should be able to connect your app on `https://example.com`. Any 404 +errors and such will be handled by Sanic's error pages, and whenever a static +file is present at a given path, it will be served by Nginx. + +## Running as a service + +This part is for Linux distributions based on `systemd`. Create a unit file +`/etc/systemd/system/sanicexample.service` + +``` +[Unit] +Description=Sanic Example + +[Service] +DynamicUser=Yes +WorkingDirectory=/srv/sanicservice +Environment=SANIC_PROXY_SECRET=_hostname +ExecStart=sanic proxied_example --port 8001 --fast +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Then reload service files, start your service and enable it on boot: + +```bash +systemctl daemon-reload +systemctl start sanicexample +systemctl enable sanicexample +``` + +.. tip:: Note + +``` +For brevity we skipped setting up a separate user account and a Python virtual environment or installing your app as a Python module. There are good tutorials on those topics elsewhere that easily apply to Sanic as well. The DynamicUser setting creates a strong sandbox which basically means your application cannot store its data in files, so you may consider setting `User=sanicexample` instead if you need that. +``` From 9a97a8a0c9b11c952db8a510190514a7c7fddd4d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:35 +0200 Subject: [PATCH 082/698] New translations getting-started.md (Japanese) --- guide/content/ja/guide/getting-started.md | 106 ++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 guide/content/ja/guide/getting-started.md diff --git a/guide/content/ja/guide/getting-started.md b/guide/content/ja/guide/getting-started.md new file mode 100644 index 0000000000..67fc26f940 --- /dev/null +++ b/guide/content/ja/guide/getting-started.md @@ -0,0 +1,106 @@ +# Getting Started + +Before we begin, make sure you are running Python 3.8 or higher. Currently, Sanic is works with Python versions 3.8 – 3.11. + +## Install + +```sh +pip install sanic +``` + +## Hello, world application + +.. column:: + +``` +If you have ever used one of the many decorator based frameworks, this probably looks somewhat familiar to you. + + + +.. note:: + + If you are coming from Flask or another framework, there are a few important things to point out. Remember, Sanic aims for performance, flexibility, and ease of use. These guiding principles have tangible impact on the API and how it works. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +### Important to note + +- Every request handler can either be sync (`def hello_world`) or async (`async def hello_world`). Unless you have a clear reason for it, always go with `async`. +- The `request` object is always the first argument of your handler. Other frameworks pass this around in a context variable to be imported. In the `async` world, this would not work so well and it is far easier (not to mention cleaner and more performant) to be explicit about it. +- You **must** use a response type. MANY other frameworks allow you to have a return value like this: `return "Hello, world."` or this: `return {"foo": "bar"}`. But, in order to do this implicit calling, somewhere in the chain needs to spend valuable time trying to determine what you meant. So, at the expense of this ease, Sanic has decided to require an explicit call. + +### Running + +.. column:: + +``` +Let's save the above file as `server.py`. And launch it. +``` + +.. column:: + +```` +```sh +sanic server +``` +```` + +.. note:: + +``` +This **another** important distinction. Other frameworks come with a built in development server and explicitly say that it is _only_ intended for development use. The opposite is true with Sanic. + +**The packaged server is production ready.** +``` + +## Sanic Extensions + +Sanic intentionally aims for a clean and unopinionated feature list. The project does not want to require you to build your application in a certain way, and tries to avoid prescribing specific development patterns. There are a number of third-party plugins that are built and maintained by the community to add additional features that do not otherwise meet the requirements of the core repository. + +However, in order **to help API developers**, the Sanic organization maintains an official plugin called [Sanic Extensions](../plugins/sanic-ext/getting-started.md) to provide all sorts of goodies, including: + +- **OpenAPI** documentation with Redoc and/or Swagger +- **CORS** protection +- **Dependency injection** into route handlers +- Request query arguments and body input **validation** +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- Predefined, endpoint-specific response serializers + +The preferred method to set it up is to install it along with Sanic, but you can also install the packages on their own. + +.. column:: + +```` +```sh +pip install sanic[ext] +``` +```` + +.. column:: + +```` +```sh +pip install sanic sanic-ext +``` +```` + +Starting in v21.12, Sanic will automatically setup Sanic Extensions if it is in the same environment. You will also have access to two additional application properties: + +- `app.extend()` - used to configure Sanic Extensions +- `app.ext` - the `Extend` instance attached to the application + +See [the plugin documentation](../plugins/sanic-ext/getting-started.md) for more information about how to use and work with the plugin From 6dc5285c77f757b249ca632d4f69af54e646f2d2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:36 +0200 Subject: [PATCH 083/698] New translations getting-started.md (Korean) --- guide/content/ko/guide/getting-started.md | 106 ++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 guide/content/ko/guide/getting-started.md diff --git a/guide/content/ko/guide/getting-started.md b/guide/content/ko/guide/getting-started.md new file mode 100644 index 0000000000..67fc26f940 --- /dev/null +++ b/guide/content/ko/guide/getting-started.md @@ -0,0 +1,106 @@ +# Getting Started + +Before we begin, make sure you are running Python 3.8 or higher. Currently, Sanic is works with Python versions 3.8 – 3.11. + +## Install + +```sh +pip install sanic +``` + +## Hello, world application + +.. column:: + +``` +If you have ever used one of the many decorator based frameworks, this probably looks somewhat familiar to you. + + + +.. note:: + + If you are coming from Flask or another framework, there are a few important things to point out. Remember, Sanic aims for performance, flexibility, and ease of use. These guiding principles have tangible impact on the API and how it works. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +### Important to note + +- Every request handler can either be sync (`def hello_world`) or async (`async def hello_world`). Unless you have a clear reason for it, always go with `async`. +- The `request` object is always the first argument of your handler. Other frameworks pass this around in a context variable to be imported. In the `async` world, this would not work so well and it is far easier (not to mention cleaner and more performant) to be explicit about it. +- You **must** use a response type. MANY other frameworks allow you to have a return value like this: `return "Hello, world."` or this: `return {"foo": "bar"}`. But, in order to do this implicit calling, somewhere in the chain needs to spend valuable time trying to determine what you meant. So, at the expense of this ease, Sanic has decided to require an explicit call. + +### Running + +.. column:: + +``` +Let's save the above file as `server.py`. And launch it. +``` + +.. column:: + +```` +```sh +sanic server +``` +```` + +.. note:: + +``` +This **another** important distinction. Other frameworks come with a built in development server and explicitly say that it is _only_ intended for development use. The opposite is true with Sanic. + +**The packaged server is production ready.** +``` + +## Sanic Extensions + +Sanic intentionally aims for a clean and unopinionated feature list. The project does not want to require you to build your application in a certain way, and tries to avoid prescribing specific development patterns. There are a number of third-party plugins that are built and maintained by the community to add additional features that do not otherwise meet the requirements of the core repository. + +However, in order **to help API developers**, the Sanic organization maintains an official plugin called [Sanic Extensions](../plugins/sanic-ext/getting-started.md) to provide all sorts of goodies, including: + +- **OpenAPI** documentation with Redoc and/or Swagger +- **CORS** protection +- **Dependency injection** into route handlers +- Request query arguments and body input **validation** +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- Predefined, endpoint-specific response serializers + +The preferred method to set it up is to install it along with Sanic, but you can also install the packages on their own. + +.. column:: + +```` +```sh +pip install sanic[ext] +``` +```` + +.. column:: + +```` +```sh +pip install sanic sanic-ext +``` +```` + +Starting in v21.12, Sanic will automatically setup Sanic Extensions if it is in the same environment. You will also have access to two additional application properties: + +- `app.extend()` - used to configure Sanic Extensions +- `app.ext` - the `Extend` instance attached to the application + +See [the plugin documentation](../plugins/sanic-ext/getting-started.md) for more information about how to use and work with the plugin From 01dbcafc02fcb16affaabcfeb87040e125045915 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:37 +0200 Subject: [PATCH 084/698] New translations getting-started.md (Chinese Simplified) --- guide/content/zh/guide/getting-started.md | 106 ++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 guide/content/zh/guide/getting-started.md diff --git a/guide/content/zh/guide/getting-started.md b/guide/content/zh/guide/getting-started.md new file mode 100644 index 0000000000..67fc26f940 --- /dev/null +++ b/guide/content/zh/guide/getting-started.md @@ -0,0 +1,106 @@ +# Getting Started + +Before we begin, make sure you are running Python 3.8 or higher. Currently, Sanic is works with Python versions 3.8 – 3.11. + +## Install + +```sh +pip install sanic +``` + +## Hello, world application + +.. column:: + +``` +If you have ever used one of the many decorator based frameworks, this probably looks somewhat familiar to you. + + + +.. note:: + + If you are coming from Flask or another framework, there are a few important things to point out. Remember, Sanic aims for performance, flexibility, and ease of use. These guiding principles have tangible impact on the API and how it works. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +### Important to note + +- Every request handler can either be sync (`def hello_world`) or async (`async def hello_world`). Unless you have a clear reason for it, always go with `async`. +- The `request` object is always the first argument of your handler. Other frameworks pass this around in a context variable to be imported. In the `async` world, this would not work so well and it is far easier (not to mention cleaner and more performant) to be explicit about it. +- You **must** use a response type. MANY other frameworks allow you to have a return value like this: `return "Hello, world."` or this: `return {"foo": "bar"}`. But, in order to do this implicit calling, somewhere in the chain needs to spend valuable time trying to determine what you meant. So, at the expense of this ease, Sanic has decided to require an explicit call. + +### Running + +.. column:: + +``` +Let's save the above file as `server.py`. And launch it. +``` + +.. column:: + +```` +```sh +sanic server +``` +```` + +.. note:: + +``` +This **another** important distinction. Other frameworks come with a built in development server and explicitly say that it is _only_ intended for development use. The opposite is true with Sanic. + +**The packaged server is production ready.** +``` + +## Sanic Extensions + +Sanic intentionally aims for a clean and unopinionated feature list. The project does not want to require you to build your application in a certain way, and tries to avoid prescribing specific development patterns. There are a number of third-party plugins that are built and maintained by the community to add additional features that do not otherwise meet the requirements of the core repository. + +However, in order **to help API developers**, the Sanic organization maintains an official plugin called [Sanic Extensions](../plugins/sanic-ext/getting-started.md) to provide all sorts of goodies, including: + +- **OpenAPI** documentation with Redoc and/or Swagger +- **CORS** protection +- **Dependency injection** into route handlers +- Request query arguments and body input **validation** +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- Predefined, endpoint-specific response serializers + +The preferred method to set it up is to install it along with Sanic, but you can also install the packages on their own. + +.. column:: + +```` +```sh +pip install sanic[ext] +``` +```` + +.. column:: + +```` +```sh +pip install sanic sanic-ext +``` +```` + +Starting in v21.12, Sanic will automatically setup Sanic Extensions if it is in the same environment. You will also have access to two additional application properties: + +- `app.extend()` - used to configure Sanic Extensions +- `app.ext` - the `Extend` instance attached to the application + +See [the plugin documentation](../plugins/sanic-ext/getting-started.md) for more information about how to use and work with the plugin From 0bfc3219d5406c5fd5333e7696b89eda8016f871 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:38 +0200 Subject: [PATCH 085/698] New translations readme.md (Japanese) --- guide/content/ja/guide/how-to/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/README.md diff --git a/guide/content/ja/guide/how-to/README.md b/guide/content/ja/guide/how-to/README.md new file mode 100644 index 0000000000..8e66fc0483 --- /dev/null +++ b/guide/content/ja/guide/how-to/README.md @@ -0,0 +1 @@ +# How to ... From 8a4745083afd4d1ffbd2ae9f1610dbb1d457269b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:39 +0200 Subject: [PATCH 086/698] New translations readme.md (Korean) --- guide/content/ko/guide/how-to/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/README.md diff --git a/guide/content/ko/guide/how-to/README.md b/guide/content/ko/guide/how-to/README.md new file mode 100644 index 0000000000..8e66fc0483 --- /dev/null +++ b/guide/content/ko/guide/how-to/README.md @@ -0,0 +1 @@ +# How to ... From b834f8980da3cb6dad78d562d53af01ea40d017d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:40 +0200 Subject: [PATCH 087/698] New translations readme.md (Chinese Simplified) --- guide/content/zh/guide/how-to/README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/README.md diff --git a/guide/content/zh/guide/how-to/README.md b/guide/content/zh/guide/how-to/README.md new file mode 100644 index 0000000000..8e66fc0483 --- /dev/null +++ b/guide/content/zh/guide/how-to/README.md @@ -0,0 +1 @@ +# How to ... From 7a30527b7ab9c987790c396d6ea965141e78c0c0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:41 +0200 Subject: [PATCH 088/698] New translations authentication.md (Japanese) --- .../content/ja/guide/how-to/authentication.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 guide/content/ja/guide/how-to/authentication.md diff --git a/guide/content/ja/guide/how-to/authentication.md b/guide/content/ja/guide/how-to/authentication.md new file mode 100644 index 0000000000..28e1bc29ad --- /dev/null +++ b/guide/content/ja/guide/how-to/authentication.md @@ -0,0 +1,116 @@ +# Authentication + +> How do I control authentication and authorization? + +This is an _extremely_ complicated subject to cram into a few snippets. But, this should provide you with an idea on ways to tackle this problem. This example uses [JWTs](https://jwt.io/), but the concepts should be equally applicable to sessions or some other scheme. + +## `server.py` + +```python +from sanic import Sanic, text + +from auth import protected +from login import login + +app = Sanic("AuthApp") +app.config.SECRET = "KEEP_IT_SECRET_KEEP_IT_SAFE" +app.blueprint(login) + +@app.get("/secret") +@protected +async def secret(request): + return text("To go fast, you must be fast.") +``` + +## `login.py` + +```python +import jwt +from sanic import Blueprint, text + +login = Blueprint("login", url_prefix="/login") + +@login.post("/") +async def do_login(request): + token = jwt.encode({}, request.app.config.SECRET) + return text(token) +``` + +## `auth.py` + +```python +from functools import wraps + +import jwt +from sanic import text + +def check_token(request): + if not request.token: + return False + + try: + jwt.decode( + request.token, request.app.config.SECRET, algorithms=["HS256"] + ) + except jwt.exceptions.InvalidTokenError: + return False + else: + return True + +def protected(wrapped): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + is_authenticated = check_token(request) + + if is_authenticated: + response = await f(request, *args, **kwargs) + return response + else: + return text("You are unauthorized.", 401) + + return decorated_function + + return decorator(wrapped) +``` + +This decorator pattern is taken from the [decorators page](/en/guide/best-practices/decorators.md). + +*** + +```bash +$ curl localhost:9999/secret -i +HTTP/1.1 401 Unauthorized +content-length: 21 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +You are unauthorized. + + +$ curl localhost:9999/login -X POST +eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE + + +$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE" +HTTP/1.1 200 OK +content-length: 29 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +To go fast, you must be fast. + + +$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.BAD" +HTTP/1.1 401 Unauthorized +content-length: 21 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +You are unauthorized. +``` + +Also, checkout some resources from the community: + +- Awesome Sanic - [Authorization](https://github.com/mekicha/awesome-sanic/blob/master/README.md#authentication) & [Session](https://github.com/mekicha/awesome-sanic/blob/master/README.md#session) +- [EuroPython 2020 - Overcoming access control in web APIs](https://www.youtube.com/watch?v=Uqgoj43ky6A) From cfd7d3c608459a0e83bbfa3c10f9d6b14b86dbad Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:42 +0200 Subject: [PATCH 089/698] New translations authentication.md (Korean) --- .../content/ko/guide/how-to/authentication.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 guide/content/ko/guide/how-to/authentication.md diff --git a/guide/content/ko/guide/how-to/authentication.md b/guide/content/ko/guide/how-to/authentication.md new file mode 100644 index 0000000000..28e1bc29ad --- /dev/null +++ b/guide/content/ko/guide/how-to/authentication.md @@ -0,0 +1,116 @@ +# Authentication + +> How do I control authentication and authorization? + +This is an _extremely_ complicated subject to cram into a few snippets. But, this should provide you with an idea on ways to tackle this problem. This example uses [JWTs](https://jwt.io/), but the concepts should be equally applicable to sessions or some other scheme. + +## `server.py` + +```python +from sanic import Sanic, text + +from auth import protected +from login import login + +app = Sanic("AuthApp") +app.config.SECRET = "KEEP_IT_SECRET_KEEP_IT_SAFE" +app.blueprint(login) + +@app.get("/secret") +@protected +async def secret(request): + return text("To go fast, you must be fast.") +``` + +## `login.py` + +```python +import jwt +from sanic import Blueprint, text + +login = Blueprint("login", url_prefix="/login") + +@login.post("/") +async def do_login(request): + token = jwt.encode({}, request.app.config.SECRET) + return text(token) +``` + +## `auth.py` + +```python +from functools import wraps + +import jwt +from sanic import text + +def check_token(request): + if not request.token: + return False + + try: + jwt.decode( + request.token, request.app.config.SECRET, algorithms=["HS256"] + ) + except jwt.exceptions.InvalidTokenError: + return False + else: + return True + +def protected(wrapped): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + is_authenticated = check_token(request) + + if is_authenticated: + response = await f(request, *args, **kwargs) + return response + else: + return text("You are unauthorized.", 401) + + return decorated_function + + return decorator(wrapped) +``` + +This decorator pattern is taken from the [decorators page](/en/guide/best-practices/decorators.md). + +*** + +```bash +$ curl localhost:9999/secret -i +HTTP/1.1 401 Unauthorized +content-length: 21 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +You are unauthorized. + + +$ curl localhost:9999/login -X POST +eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE + + +$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE" +HTTP/1.1 200 OK +content-length: 29 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +To go fast, you must be fast. + + +$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.BAD" +HTTP/1.1 401 Unauthorized +content-length: 21 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +You are unauthorized. +``` + +Also, checkout some resources from the community: + +- Awesome Sanic - [Authorization](https://github.com/mekicha/awesome-sanic/blob/master/README.md#authentication) & [Session](https://github.com/mekicha/awesome-sanic/blob/master/README.md#session) +- [EuroPython 2020 - Overcoming access control in web APIs](https://www.youtube.com/watch?v=Uqgoj43ky6A) From e4a069161053251ad065785c97f1da6ed18b7bdd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:43 +0200 Subject: [PATCH 090/698] New translations authentication.md (Chinese Simplified) --- .../content/zh/guide/how-to/authentication.md | 116 ++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 guide/content/zh/guide/how-to/authentication.md diff --git a/guide/content/zh/guide/how-to/authentication.md b/guide/content/zh/guide/how-to/authentication.md new file mode 100644 index 0000000000..28e1bc29ad --- /dev/null +++ b/guide/content/zh/guide/how-to/authentication.md @@ -0,0 +1,116 @@ +# Authentication + +> How do I control authentication and authorization? + +This is an _extremely_ complicated subject to cram into a few snippets. But, this should provide you with an idea on ways to tackle this problem. This example uses [JWTs](https://jwt.io/), but the concepts should be equally applicable to sessions or some other scheme. + +## `server.py` + +```python +from sanic import Sanic, text + +from auth import protected +from login import login + +app = Sanic("AuthApp") +app.config.SECRET = "KEEP_IT_SECRET_KEEP_IT_SAFE" +app.blueprint(login) + +@app.get("/secret") +@protected +async def secret(request): + return text("To go fast, you must be fast.") +``` + +## `login.py` + +```python +import jwt +from sanic import Blueprint, text + +login = Blueprint("login", url_prefix="/login") + +@login.post("/") +async def do_login(request): + token = jwt.encode({}, request.app.config.SECRET) + return text(token) +``` + +## `auth.py` + +```python +from functools import wraps + +import jwt +from sanic import text + +def check_token(request): + if not request.token: + return False + + try: + jwt.decode( + request.token, request.app.config.SECRET, algorithms=["HS256"] + ) + except jwt.exceptions.InvalidTokenError: + return False + else: + return True + +def protected(wrapped): + def decorator(f): + @wraps(f) + async def decorated_function(request, *args, **kwargs): + is_authenticated = check_token(request) + + if is_authenticated: + response = await f(request, *args, **kwargs) + return response + else: + return text("You are unauthorized.", 401) + + return decorated_function + + return decorator(wrapped) +``` + +This decorator pattern is taken from the [decorators page](/en/guide/best-practices/decorators.md). + +*** + +```bash +$ curl localhost:9999/secret -i +HTTP/1.1 401 Unauthorized +content-length: 21 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +You are unauthorized. + + +$ curl localhost:9999/login -X POST +eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE + + +$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE" +HTTP/1.1 200 OK +content-length: 29 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +To go fast, you must be fast. + + +$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.BAD" +HTTP/1.1 401 Unauthorized +content-length: 21 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +You are unauthorized. +``` + +Also, checkout some resources from the community: + +- Awesome Sanic - [Authorization](https://github.com/mekicha/awesome-sanic/blob/master/README.md#authentication) & [Session](https://github.com/mekicha/awesome-sanic/blob/master/README.md#session) +- [EuroPython 2020 - Overcoming access control in web APIs](https://www.youtube.com/watch?v=Uqgoj43ky6A) From 95143dc2afbad01597a0d798239e555daaf13751 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:43 +0200 Subject: [PATCH 091/698] New translations autodiscovery.md (Japanese) --- .../content/ja/guide/how-to/autodiscovery.md | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 guide/content/ja/guide/how-to/autodiscovery.md diff --git a/guide/content/ja/guide/how-to/autodiscovery.md b/guide/content/ja/guide/how-to/autodiscovery.md new file mode 100644 index 0000000000..90cda60083 --- /dev/null +++ b/guide/content/ja/guide/how-to/autodiscovery.md @@ -0,0 +1,197 @@ +--- +title: Autodiscovery +--- + +# Autodiscovery of Blueprints, Middleware, and Listeners + +> How do I autodiscover the components I am using to build my application? + +One of the first problems someone faces when building an application, is _how_ to structure the project. Sanic makes heavy use of decorators to register route handlers, middleware, and listeners. And, after creating blueprints, they need to be mounted to the application. + +A possible solution is a single file in which **everything** is imported and applied to the Sanic instance. Another is passing around the Sanic instance as a global variable. Both of these solutions have their drawbacks. + +An alternative is autodiscovery. You point your application at modules (already imported, or strings), and let it wire everything up. + +## `server.py` + +```python +from sanic import Sanic +from sanic.response import empty + +import blueprints +from utility import autodiscover + +app = Sanic("auto", register=True) +autodiscover( + app, + blueprints, + "parent.child", + "listeners.something", + recursive=True, +) + +app.route("/")(lambda _: empty()) +``` + +```bash +[2021-03-02 21:37:02 +0200] [880451] [INFO] Goin' Fast @ http://127.0.0.1:9999 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ nested +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ level1 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ level3 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something inside __init__.py +[2021-03-02 21:37:02 +0200] [880451] [INFO] Starting worker [880451] +``` + +## `utility.py` + +```python + +from glob import glob +from importlib import import_module, util +from inspect import getmembers +from pathlib import Path +from types import ModuleType +from typing import Union + +from sanic.blueprints import Blueprint + +def autodiscover( + app, *module_names: Union[str, ModuleType], recursive: bool = False +): + mod = app.__module__ + blueprints = set() + _imported = set() + + def _find_bps(module): + nonlocal blueprints + + for _, member in getmembers(module): + if isinstance(member, Blueprint): + blueprints.add(member) + + for module in module_names: + if isinstance(module, str): + module = import_module(module, mod) + _imported.add(module.__file__) + _find_bps(module) + + if recursive: + base = Path(module.__file__).parent + for path in glob(f"{base}/**/*.py", recursive=True): + if path not in _imported: + name = "module" + if "__init__" in path: + *_, name, __ = path.split("/") + spec = util.spec_from_file_location(name, path) + specmod = util.module_from_spec(spec) + _imported.add(path) + spec.loader.exec_module(specmod) + _find_bps(specmod) + + for bp in blueprints: + app.blueprint(bp) +``` + +## `blueprints/level1.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +level1 = Blueprint("level1") + +@level1.after_server_start +def print_something(app, loop): + logger.debug("something @ level1") +``` + +## `blueprints/one/two/level3.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +level3 = Blueprint("level3") + +@level3.after_server_start +def print_something(app, loop): + logger.debug("something @ level3") +``` + +## `listeners/something.py` + +```python +from sanic import Sanic +from sanic.log import logger + +app = Sanic.get_app("auto") + +@app.after_server_start +def print_something(app, loop): + logger.debug("something") +``` + +## `parent/child/__init__.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +bp = Blueprint("__init__") + +@bp.after_server_start +def print_something(app, loop): + logger.debug("something inside __init__.py") +``` + +## `parent/child/nested.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +nested = Blueprint("nested") + +@nested.after_server_start +def print_something(app, loop): + logger.debug("something @ nested") +``` + +*** + +```text +here is the dir tree +generate with 'find . -type d -name "__pycache__" -exec rm -rf {} +; tree' + +. # run 'sanic sever -d' here +├── blueprints +│ ├── __init__.py # you need add this file, just empty +│ ├── level1.py +│ └── one +│ └── two +│ └── level3.py +├── listeners +│ └── something.py +├── parent +│ └── child +│ ├── __init__.py +│ └── nested.py +├── server.py +└── utility.py +``` + +```sh +source ./.venv/bin/activate # activate the python venv which sanic is installed in +sanic sever -d # run this in the directory containing server.py +``` + +```text +you will see "something ***" like this: + +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something inside __init__.py +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ level3 +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ level1 +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ nested +``` From be50fb84564108c5bec0cb526f381f52c1e596cb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:44 +0200 Subject: [PATCH 092/698] New translations autodiscovery.md (Korean) --- .../content/ko/guide/how-to/autodiscovery.md | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 guide/content/ko/guide/how-to/autodiscovery.md diff --git a/guide/content/ko/guide/how-to/autodiscovery.md b/guide/content/ko/guide/how-to/autodiscovery.md new file mode 100644 index 0000000000..90cda60083 --- /dev/null +++ b/guide/content/ko/guide/how-to/autodiscovery.md @@ -0,0 +1,197 @@ +--- +title: Autodiscovery +--- + +# Autodiscovery of Blueprints, Middleware, and Listeners + +> How do I autodiscover the components I am using to build my application? + +One of the first problems someone faces when building an application, is _how_ to structure the project. Sanic makes heavy use of decorators to register route handlers, middleware, and listeners. And, after creating blueprints, they need to be mounted to the application. + +A possible solution is a single file in which **everything** is imported and applied to the Sanic instance. Another is passing around the Sanic instance as a global variable. Both of these solutions have their drawbacks. + +An alternative is autodiscovery. You point your application at modules (already imported, or strings), and let it wire everything up. + +## `server.py` + +```python +from sanic import Sanic +from sanic.response import empty + +import blueprints +from utility import autodiscover + +app = Sanic("auto", register=True) +autodiscover( + app, + blueprints, + "parent.child", + "listeners.something", + recursive=True, +) + +app.route("/")(lambda _: empty()) +``` + +```bash +[2021-03-02 21:37:02 +0200] [880451] [INFO] Goin' Fast @ http://127.0.0.1:9999 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ nested +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ level1 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ level3 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something inside __init__.py +[2021-03-02 21:37:02 +0200] [880451] [INFO] Starting worker [880451] +``` + +## `utility.py` + +```python + +from glob import glob +from importlib import import_module, util +from inspect import getmembers +from pathlib import Path +from types import ModuleType +from typing import Union + +from sanic.blueprints import Blueprint + +def autodiscover( + app, *module_names: Union[str, ModuleType], recursive: bool = False +): + mod = app.__module__ + blueprints = set() + _imported = set() + + def _find_bps(module): + nonlocal blueprints + + for _, member in getmembers(module): + if isinstance(member, Blueprint): + blueprints.add(member) + + for module in module_names: + if isinstance(module, str): + module = import_module(module, mod) + _imported.add(module.__file__) + _find_bps(module) + + if recursive: + base = Path(module.__file__).parent + for path in glob(f"{base}/**/*.py", recursive=True): + if path not in _imported: + name = "module" + if "__init__" in path: + *_, name, __ = path.split("/") + spec = util.spec_from_file_location(name, path) + specmod = util.module_from_spec(spec) + _imported.add(path) + spec.loader.exec_module(specmod) + _find_bps(specmod) + + for bp in blueprints: + app.blueprint(bp) +``` + +## `blueprints/level1.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +level1 = Blueprint("level1") + +@level1.after_server_start +def print_something(app, loop): + logger.debug("something @ level1") +``` + +## `blueprints/one/two/level3.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +level3 = Blueprint("level3") + +@level3.after_server_start +def print_something(app, loop): + logger.debug("something @ level3") +``` + +## `listeners/something.py` + +```python +from sanic import Sanic +from sanic.log import logger + +app = Sanic.get_app("auto") + +@app.after_server_start +def print_something(app, loop): + logger.debug("something") +``` + +## `parent/child/__init__.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +bp = Blueprint("__init__") + +@bp.after_server_start +def print_something(app, loop): + logger.debug("something inside __init__.py") +``` + +## `parent/child/nested.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +nested = Blueprint("nested") + +@nested.after_server_start +def print_something(app, loop): + logger.debug("something @ nested") +``` + +*** + +```text +here is the dir tree +generate with 'find . -type d -name "__pycache__" -exec rm -rf {} +; tree' + +. # run 'sanic sever -d' here +├── blueprints +│ ├── __init__.py # you need add this file, just empty +│ ├── level1.py +│ └── one +│ └── two +│ └── level3.py +├── listeners +│ └── something.py +├── parent +│ └── child +│ ├── __init__.py +│ └── nested.py +├── server.py +└── utility.py +``` + +```sh +source ./.venv/bin/activate # activate the python venv which sanic is installed in +sanic sever -d # run this in the directory containing server.py +``` + +```text +you will see "something ***" like this: + +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something inside __init__.py +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ level3 +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ level1 +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ nested +``` From f6c258099a1b2259f8b2e74c4b85385b70bf946f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:45 +0200 Subject: [PATCH 093/698] New translations autodiscovery.md (Chinese Simplified) --- .../content/zh/guide/how-to/autodiscovery.md | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 guide/content/zh/guide/how-to/autodiscovery.md diff --git a/guide/content/zh/guide/how-to/autodiscovery.md b/guide/content/zh/guide/how-to/autodiscovery.md new file mode 100644 index 0000000000..90cda60083 --- /dev/null +++ b/guide/content/zh/guide/how-to/autodiscovery.md @@ -0,0 +1,197 @@ +--- +title: Autodiscovery +--- + +# Autodiscovery of Blueprints, Middleware, and Listeners + +> How do I autodiscover the components I am using to build my application? + +One of the first problems someone faces when building an application, is _how_ to structure the project. Sanic makes heavy use of decorators to register route handlers, middleware, and listeners. And, after creating blueprints, they need to be mounted to the application. + +A possible solution is a single file in which **everything** is imported and applied to the Sanic instance. Another is passing around the Sanic instance as a global variable. Both of these solutions have their drawbacks. + +An alternative is autodiscovery. You point your application at modules (already imported, or strings), and let it wire everything up. + +## `server.py` + +```python +from sanic import Sanic +from sanic.response import empty + +import blueprints +from utility import autodiscover + +app = Sanic("auto", register=True) +autodiscover( + app, + blueprints, + "parent.child", + "listeners.something", + recursive=True, +) + +app.route("/")(lambda _: empty()) +``` + +```bash +[2021-03-02 21:37:02 +0200] [880451] [INFO] Goin' Fast @ http://127.0.0.1:9999 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ nested +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ level1 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something @ level3 +[2021-03-02 21:37:02 +0200] [880451] [DEBUG] something inside __init__.py +[2021-03-02 21:37:02 +0200] [880451] [INFO] Starting worker [880451] +``` + +## `utility.py` + +```python + +from glob import glob +from importlib import import_module, util +from inspect import getmembers +from pathlib import Path +from types import ModuleType +from typing import Union + +from sanic.blueprints import Blueprint + +def autodiscover( + app, *module_names: Union[str, ModuleType], recursive: bool = False +): + mod = app.__module__ + blueprints = set() + _imported = set() + + def _find_bps(module): + nonlocal blueprints + + for _, member in getmembers(module): + if isinstance(member, Blueprint): + blueprints.add(member) + + for module in module_names: + if isinstance(module, str): + module = import_module(module, mod) + _imported.add(module.__file__) + _find_bps(module) + + if recursive: + base = Path(module.__file__).parent + for path in glob(f"{base}/**/*.py", recursive=True): + if path not in _imported: + name = "module" + if "__init__" in path: + *_, name, __ = path.split("/") + spec = util.spec_from_file_location(name, path) + specmod = util.module_from_spec(spec) + _imported.add(path) + spec.loader.exec_module(specmod) + _find_bps(specmod) + + for bp in blueprints: + app.blueprint(bp) +``` + +## `blueprints/level1.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +level1 = Blueprint("level1") + +@level1.after_server_start +def print_something(app, loop): + logger.debug("something @ level1") +``` + +## `blueprints/one/two/level3.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +level3 = Blueprint("level3") + +@level3.after_server_start +def print_something(app, loop): + logger.debug("something @ level3") +``` + +## `listeners/something.py` + +```python +from sanic import Sanic +from sanic.log import logger + +app = Sanic.get_app("auto") + +@app.after_server_start +def print_something(app, loop): + logger.debug("something") +``` + +## `parent/child/__init__.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +bp = Blueprint("__init__") + +@bp.after_server_start +def print_something(app, loop): + logger.debug("something inside __init__.py") +``` + +## `parent/child/nested.py` + +```python +from sanic import Blueprint +from sanic.log import logger + +nested = Blueprint("nested") + +@nested.after_server_start +def print_something(app, loop): + logger.debug("something @ nested") +``` + +*** + +```text +here is the dir tree +generate with 'find . -type d -name "__pycache__" -exec rm -rf {} +; tree' + +. # run 'sanic sever -d' here +├── blueprints +│ ├── __init__.py # you need add this file, just empty +│ ├── level1.py +│ └── one +│ └── two +│ └── level3.py +├── listeners +│ └── something.py +├── parent +│ └── child +│ ├── __init__.py +│ └── nested.py +├── server.py +└── utility.py +``` + +```sh +source ./.venv/bin/activate # activate the python venv which sanic is installed in +sanic sever -d # run this in the directory containing server.py +``` + +```text +you will see "something ***" like this: + +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something inside __init__.py +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ level3 +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ level1 +[2023-07-12 11:23:36 +0000] [113704] [DEBUG] something @ nested +``` From 6afe3d15d0451335ce08f3b2fec1b905c39c1eb3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:46 +0200 Subject: [PATCH 094/698] New translations cors.md (Japanese) --- guide/content/ja/guide/how-to/cors.md | 138 ++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 guide/content/ja/guide/how-to/cors.md diff --git a/guide/content/ja/guide/how-to/cors.md b/guide/content/ja/guide/how-to/cors.md new file mode 100644 index 0000000000..250b0aea74 --- /dev/null +++ b/guide/content/ja/guide/how-to/cors.md @@ -0,0 +1,138 @@ +--- +title: CORS +--- + +# Cross-origin resource sharing (CORS) + +> How do I configure my application for CORS? + +.. note:: + +``` +🏆 The best solution is to use [Sanic Extensions](../../plugins/sanic-ext/http/cors.md). + +However, if you would like to build your own version, you could use this limited example as a starting point. +``` + +### `server.py` + +```python +from sanic import Sanic, text + +from cors import add_cors_headers +from options import setup_options + +app = Sanic("app") + +@app.route("/", methods=["GET", "POST"]) +async def do_stuff(request): + return text("...") + +# Add OPTIONS handlers to any route that is missing it +app.register_listener(setup_options, "before_server_start") + +# Fill in CORS headers +app.register_middleware(add_cors_headers, "response") +``` + +## `cors.py` + +```python +from typing import Iterable + +def _add_cors_headers(response, methods: Iterable[str]) -> None: + allow_methods = list(set(methods)) + if "OPTIONS" not in allow_methods: + allow_methods.append("OPTIONS") + headers = { + "Access-Control-Allow-Methods": ",".join(allow_methods), + "Access-Control-Allow-Origin": "mydomain.com", + "Access-Control-Allow-Credentials": "true", + "Access-Control-Allow-Headers": ( + "origin, content-type, accept, " + "authorization, x-xsrf-token, x-request-id" + ), + } + response.headers.extend(headers) + +def add_cors_headers(request, response): + if request.method != "OPTIONS": + methods = [method for method in request.route.methods] + _add_cors_headers(response, methods) +``` + +## `options.py` + +```python +from collections import defaultdict +from typing import Dict, FrozenSet + +from sanic import Sanic, response +from sanic.router import Route + +from cors import _add_cors_headers + +def _compile_routes_needing_options( + routes: Dict[str, Route] +) -> Dict[str, FrozenSet]: + needs_options = defaultdict(list) + # This is 21.12 and later. You will need to change this for older versions. + for route in routes.values(): + if "OPTIONS" not in route.methods: + needs_options[route.uri].extend(route.methods) + + return { + uri: frozenset(methods) for uri, methods in dict(needs_options).items() + } + +def _options_wrapper(handler, methods): + def wrapped_handler(request, *args, **kwargs): + nonlocal methods + return handler(request, methods) + + return wrapped_handler + +async def options_handler(request, methods) -> response.HTTPResponse: + resp = response.empty() + _add_cors_headers(resp, methods) + return resp + +def setup_options(app: Sanic, _): + app.router.reset() + needs_options = _compile_routes_needing_options(app.router.routes_all) + for uri, methods in needs_options.items(): + app.add_route( + _options_wrapper(options_handler, methods), + uri, + methods=["OPTIONS"], + ) + app.router.finalize() +``` + +*** + +``` +$ curl localhost:9999/ -i +HTTP/1.1 200 OK +Access-Control-Allow-Methods: OPTIONS,POST,GET +Access-Control-Allow-Origin: mydomain.com +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsrf-token, x-request-id +content-length: 3 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +... + +$ curl localhost:9999/ -i -X OPTIONS +HTTP/1.1 204 No Content +Access-Control-Allow-Methods: GET,POST,OPTIONS +Access-Control-Allow-Origin: mydomain.com +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsrf-token, x-request-id +connection: keep-alive +``` + +Also, checkout some resources from the community: + +- [Awesome Sanic](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) From 8b87de55fcf58744d3abd61da19f595dd33b2abc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:47 +0200 Subject: [PATCH 095/698] New translations cors.md (Korean) --- guide/content/ko/guide/how-to/cors.md | 138 ++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 guide/content/ko/guide/how-to/cors.md diff --git a/guide/content/ko/guide/how-to/cors.md b/guide/content/ko/guide/how-to/cors.md new file mode 100644 index 0000000000..250b0aea74 --- /dev/null +++ b/guide/content/ko/guide/how-to/cors.md @@ -0,0 +1,138 @@ +--- +title: CORS +--- + +# Cross-origin resource sharing (CORS) + +> How do I configure my application for CORS? + +.. note:: + +``` +🏆 The best solution is to use [Sanic Extensions](../../plugins/sanic-ext/http/cors.md). + +However, if you would like to build your own version, you could use this limited example as a starting point. +``` + +### `server.py` + +```python +from sanic import Sanic, text + +from cors import add_cors_headers +from options import setup_options + +app = Sanic("app") + +@app.route("/", methods=["GET", "POST"]) +async def do_stuff(request): + return text("...") + +# Add OPTIONS handlers to any route that is missing it +app.register_listener(setup_options, "before_server_start") + +# Fill in CORS headers +app.register_middleware(add_cors_headers, "response") +``` + +## `cors.py` + +```python +from typing import Iterable + +def _add_cors_headers(response, methods: Iterable[str]) -> None: + allow_methods = list(set(methods)) + if "OPTIONS" not in allow_methods: + allow_methods.append("OPTIONS") + headers = { + "Access-Control-Allow-Methods": ",".join(allow_methods), + "Access-Control-Allow-Origin": "mydomain.com", + "Access-Control-Allow-Credentials": "true", + "Access-Control-Allow-Headers": ( + "origin, content-type, accept, " + "authorization, x-xsrf-token, x-request-id" + ), + } + response.headers.extend(headers) + +def add_cors_headers(request, response): + if request.method != "OPTIONS": + methods = [method for method in request.route.methods] + _add_cors_headers(response, methods) +``` + +## `options.py` + +```python +from collections import defaultdict +from typing import Dict, FrozenSet + +from sanic import Sanic, response +from sanic.router import Route + +from cors import _add_cors_headers + +def _compile_routes_needing_options( + routes: Dict[str, Route] +) -> Dict[str, FrozenSet]: + needs_options = defaultdict(list) + # This is 21.12 and later. You will need to change this for older versions. + for route in routes.values(): + if "OPTIONS" not in route.methods: + needs_options[route.uri].extend(route.methods) + + return { + uri: frozenset(methods) for uri, methods in dict(needs_options).items() + } + +def _options_wrapper(handler, methods): + def wrapped_handler(request, *args, **kwargs): + nonlocal methods + return handler(request, methods) + + return wrapped_handler + +async def options_handler(request, methods) -> response.HTTPResponse: + resp = response.empty() + _add_cors_headers(resp, methods) + return resp + +def setup_options(app: Sanic, _): + app.router.reset() + needs_options = _compile_routes_needing_options(app.router.routes_all) + for uri, methods in needs_options.items(): + app.add_route( + _options_wrapper(options_handler, methods), + uri, + methods=["OPTIONS"], + ) + app.router.finalize() +``` + +*** + +``` +$ curl localhost:9999/ -i +HTTP/1.1 200 OK +Access-Control-Allow-Methods: OPTIONS,POST,GET +Access-Control-Allow-Origin: mydomain.com +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsrf-token, x-request-id +content-length: 3 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +... + +$ curl localhost:9999/ -i -X OPTIONS +HTTP/1.1 204 No Content +Access-Control-Allow-Methods: GET,POST,OPTIONS +Access-Control-Allow-Origin: mydomain.com +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsrf-token, x-request-id +connection: keep-alive +``` + +Also, checkout some resources from the community: + +- [Awesome Sanic](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) From 42daa19f24f2b1913ec7cc8d5068f7abfe1e6950 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:48 +0200 Subject: [PATCH 096/698] New translations cors.md (Chinese Simplified) --- guide/content/zh/guide/how-to/cors.md | 138 ++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 guide/content/zh/guide/how-to/cors.md diff --git a/guide/content/zh/guide/how-to/cors.md b/guide/content/zh/guide/how-to/cors.md new file mode 100644 index 0000000000..250b0aea74 --- /dev/null +++ b/guide/content/zh/guide/how-to/cors.md @@ -0,0 +1,138 @@ +--- +title: CORS +--- + +# Cross-origin resource sharing (CORS) + +> How do I configure my application for CORS? + +.. note:: + +``` +🏆 The best solution is to use [Sanic Extensions](../../plugins/sanic-ext/http/cors.md). + +However, if you would like to build your own version, you could use this limited example as a starting point. +``` + +### `server.py` + +```python +from sanic import Sanic, text + +from cors import add_cors_headers +from options import setup_options + +app = Sanic("app") + +@app.route("/", methods=["GET", "POST"]) +async def do_stuff(request): + return text("...") + +# Add OPTIONS handlers to any route that is missing it +app.register_listener(setup_options, "before_server_start") + +# Fill in CORS headers +app.register_middleware(add_cors_headers, "response") +``` + +## `cors.py` + +```python +from typing import Iterable + +def _add_cors_headers(response, methods: Iterable[str]) -> None: + allow_methods = list(set(methods)) + if "OPTIONS" not in allow_methods: + allow_methods.append("OPTIONS") + headers = { + "Access-Control-Allow-Methods": ",".join(allow_methods), + "Access-Control-Allow-Origin": "mydomain.com", + "Access-Control-Allow-Credentials": "true", + "Access-Control-Allow-Headers": ( + "origin, content-type, accept, " + "authorization, x-xsrf-token, x-request-id" + ), + } + response.headers.extend(headers) + +def add_cors_headers(request, response): + if request.method != "OPTIONS": + methods = [method for method in request.route.methods] + _add_cors_headers(response, methods) +``` + +## `options.py` + +```python +from collections import defaultdict +from typing import Dict, FrozenSet + +from sanic import Sanic, response +from sanic.router import Route + +from cors import _add_cors_headers + +def _compile_routes_needing_options( + routes: Dict[str, Route] +) -> Dict[str, FrozenSet]: + needs_options = defaultdict(list) + # This is 21.12 and later. You will need to change this for older versions. + for route in routes.values(): + if "OPTIONS" not in route.methods: + needs_options[route.uri].extend(route.methods) + + return { + uri: frozenset(methods) for uri, methods in dict(needs_options).items() + } + +def _options_wrapper(handler, methods): + def wrapped_handler(request, *args, **kwargs): + nonlocal methods + return handler(request, methods) + + return wrapped_handler + +async def options_handler(request, methods) -> response.HTTPResponse: + resp = response.empty() + _add_cors_headers(resp, methods) + return resp + +def setup_options(app: Sanic, _): + app.router.reset() + needs_options = _compile_routes_needing_options(app.router.routes_all) + for uri, methods in needs_options.items(): + app.add_route( + _options_wrapper(options_handler, methods), + uri, + methods=["OPTIONS"], + ) + app.router.finalize() +``` + +*** + +``` +$ curl localhost:9999/ -i +HTTP/1.1 200 OK +Access-Control-Allow-Methods: OPTIONS,POST,GET +Access-Control-Allow-Origin: mydomain.com +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsrf-token, x-request-id +content-length: 3 +connection: keep-alive +content-type: text/plain; charset=utf-8 + +... + +$ curl localhost:9999/ -i -X OPTIONS +HTTP/1.1 204 No Content +Access-Control-Allow-Methods: GET,POST,OPTIONS +Access-Control-Allow-Origin: mydomain.com +Access-Control-Allow-Credentials: true +Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsrf-token, x-request-id +connection: keep-alive +``` + +Also, checkout some resources from the community: + +- [Awesome Sanic](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) From 6913d43ce725e1f429a88ff7982049df86a2f6a7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:49 +0200 Subject: [PATCH 097/698] New translations csrf.md (Japanese) --- guide/content/ja/guide/how-to/csrf.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/csrf.md diff --git a/guide/content/ja/guide/how-to/csrf.md b/guide/content/ja/guide/how-to/csrf.md new file mode 100644 index 0000000000..7f982ff12f --- /dev/null +++ b/guide/content/ja/guide/how-to/csrf.md @@ -0,0 +1 @@ +csrf From 08a0698826aff6e4f85778dc36b058f5f691cf0a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:50 +0200 Subject: [PATCH 098/698] New translations csrf.md (Korean) --- guide/content/ko/guide/how-to/csrf.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/csrf.md diff --git a/guide/content/ko/guide/how-to/csrf.md b/guide/content/ko/guide/how-to/csrf.md new file mode 100644 index 0000000000..7f982ff12f --- /dev/null +++ b/guide/content/ko/guide/how-to/csrf.md @@ -0,0 +1 @@ +csrf From c9ae8dcfc96f0a93ee47a06d3a29878fccdd533b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:50 +0200 Subject: [PATCH 099/698] New translations csrf.md (Chinese Simplified) --- guide/content/zh/guide/how-to/csrf.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/csrf.md diff --git a/guide/content/zh/guide/how-to/csrf.md b/guide/content/zh/guide/how-to/csrf.md new file mode 100644 index 0000000000..7f982ff12f --- /dev/null +++ b/guide/content/zh/guide/how-to/csrf.md @@ -0,0 +1 @@ +csrf From 2647259742a8a728420f11cd23a24f1cdb98164e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:51 +0200 Subject: [PATCH 100/698] New translations db.md (Japanese) --- guide/content/ja/guide/how-to/db.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/db.md diff --git a/guide/content/ja/guide/how-to/db.md b/guide/content/ja/guide/how-to/db.md new file mode 100644 index 0000000000..60ca822eac --- /dev/null +++ b/guide/content/ja/guide/how-to/db.md @@ -0,0 +1 @@ +connecting to data sources From a9510cb2063f3911ccc49a356f725418e25c8ee1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:52 +0200 Subject: [PATCH 101/698] New translations db.md (Korean) --- guide/content/ko/guide/how-to/db.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/db.md diff --git a/guide/content/ko/guide/how-to/db.md b/guide/content/ko/guide/how-to/db.md new file mode 100644 index 0000000000..60ca822eac --- /dev/null +++ b/guide/content/ko/guide/how-to/db.md @@ -0,0 +1 @@ +connecting to data sources From f4c97dbcd5fbed016b212d60b6fc25723b2b1cb8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:53 +0200 Subject: [PATCH 102/698] New translations db.md (Chinese Simplified) --- guide/content/zh/guide/how-to/db.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/db.md diff --git a/guide/content/zh/guide/how-to/db.md b/guide/content/zh/guide/how-to/db.md new file mode 100644 index 0000000000..60ca822eac --- /dev/null +++ b/guide/content/zh/guide/how-to/db.md @@ -0,0 +1 @@ +connecting to data sources From 0dd38f9a23116f9afb8ef19bd1eb94003169947e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:54 +0200 Subject: [PATCH 103/698] New translations decorators.md (Japanese) --- guide/content/ja/guide/how-to/decorators.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/decorators.md diff --git a/guide/content/ja/guide/how-to/decorators.md b/guide/content/ja/guide/how-to/decorators.md new file mode 100644 index 0000000000..9ef318134e --- /dev/null +++ b/guide/content/ja/guide/how-to/decorators.md @@ -0,0 +1 @@ +decorators From 73acb965b5a48532626d644fe58662e2496f0f77 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:55 +0200 Subject: [PATCH 104/698] New translations decorators.md (Korean) --- guide/content/ko/guide/how-to/decorators.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/decorators.md diff --git a/guide/content/ko/guide/how-to/decorators.md b/guide/content/ko/guide/how-to/decorators.md new file mode 100644 index 0000000000..9ef318134e --- /dev/null +++ b/guide/content/ko/guide/how-to/decorators.md @@ -0,0 +1 @@ +decorators From df214c32b268b77e4c6ccb7348db42bceff9e16d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:56 +0200 Subject: [PATCH 105/698] New translations decorators.md (Chinese Simplified) --- guide/content/zh/guide/how-to/decorators.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/decorators.md diff --git a/guide/content/zh/guide/how-to/decorators.md b/guide/content/zh/guide/how-to/decorators.md new file mode 100644 index 0000000000..9ef318134e --- /dev/null +++ b/guide/content/zh/guide/how-to/decorators.md @@ -0,0 +1 @@ +decorators From e38696998b2ca3caceb4955403004cfec17c8742 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:57 +0200 Subject: [PATCH 106/698] New translations mounting.md (Japanese) --- guide/content/ja/guide/how-to/mounting.md | 53 +++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 guide/content/ja/guide/how-to/mounting.md diff --git a/guide/content/ja/guide/how-to/mounting.md b/guide/content/ja/guide/how-to/mounting.md new file mode 100644 index 0000000000..47bf056fbb --- /dev/null +++ b/guide/content/ja/guide/how-to/mounting.md @@ -0,0 +1,53 @@ +# Application Mounting + +> How do I mount my application at some path above the root? + +```python +# server.py +from sanic import Sanic, text + +app = Sanic("app") +app.config.SERVER_NAME = "example.com/api" + +@app.route("/foo") +def handler(request): + url = app.url_for("handler", _external=True) + return text(f"URL: {url}") +``` + +```yaml +# docker-compose.yml +version: "3.7" +services: + app: + image: nginx:alpine + ports: + - 80:80 + volumes: + - type: bind + source: ./conf + target: /etc/nginx/conf.d/default.conf +``` + +```nginx +# conf +server { + listen 80; + + # Computed data service + location /api/ { + proxy_pass http://:9999/; + proxy_set_header Host example.com; + } +} +``` + +```bash +$ docker-compose up -d +$ sanic server.app --port=9999 --host=0.0.0.0 +``` + +```bash +$ curl localhost/api/foo +URL: http://example.com/api/foo +``` From c172e7395d8963bf521c38ba0d2d92798697328a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:57 +0200 Subject: [PATCH 107/698] New translations mounting.md (Korean) --- guide/content/ko/guide/how-to/mounting.md | 53 +++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 guide/content/ko/guide/how-to/mounting.md diff --git a/guide/content/ko/guide/how-to/mounting.md b/guide/content/ko/guide/how-to/mounting.md new file mode 100644 index 0000000000..47bf056fbb --- /dev/null +++ b/guide/content/ko/guide/how-to/mounting.md @@ -0,0 +1,53 @@ +# Application Mounting + +> How do I mount my application at some path above the root? + +```python +# server.py +from sanic import Sanic, text + +app = Sanic("app") +app.config.SERVER_NAME = "example.com/api" + +@app.route("/foo") +def handler(request): + url = app.url_for("handler", _external=True) + return text(f"URL: {url}") +``` + +```yaml +# docker-compose.yml +version: "3.7" +services: + app: + image: nginx:alpine + ports: + - 80:80 + volumes: + - type: bind + source: ./conf + target: /etc/nginx/conf.d/default.conf +``` + +```nginx +# conf +server { + listen 80; + + # Computed data service + location /api/ { + proxy_pass http://:9999/; + proxy_set_header Host example.com; + } +} +``` + +```bash +$ docker-compose up -d +$ sanic server.app --port=9999 --host=0.0.0.0 +``` + +```bash +$ curl localhost/api/foo +URL: http://example.com/api/foo +``` From 527d5d060872e23df835fba6c974253907b47ceb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:20:58 +0200 Subject: [PATCH 108/698] New translations mounting.md (Chinese Simplified) --- guide/content/zh/guide/how-to/mounting.md | 53 +++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 guide/content/zh/guide/how-to/mounting.md diff --git a/guide/content/zh/guide/how-to/mounting.md b/guide/content/zh/guide/how-to/mounting.md new file mode 100644 index 0000000000..47bf056fbb --- /dev/null +++ b/guide/content/zh/guide/how-to/mounting.md @@ -0,0 +1,53 @@ +# Application Mounting + +> How do I mount my application at some path above the root? + +```python +# server.py +from sanic import Sanic, text + +app = Sanic("app") +app.config.SERVER_NAME = "example.com/api" + +@app.route("/foo") +def handler(request): + url = app.url_for("handler", _external=True) + return text(f"URL: {url}") +``` + +```yaml +# docker-compose.yml +version: "3.7" +services: + app: + image: nginx:alpine + ports: + - 80:80 + volumes: + - type: bind + source: ./conf + target: /etc/nginx/conf.d/default.conf +``` + +```nginx +# conf +server { + listen 80; + + # Computed data service + location /api/ { + proxy_pass http://:9999/; + proxy_set_header Host example.com; + } +} +``` + +```bash +$ docker-compose up -d +$ sanic server.app --port=9999 --host=0.0.0.0 +``` + +```bash +$ curl localhost/api/foo +URL: http://example.com/api/foo +``` From a67af163620a0f834f1c21481df1dbb1c46e645d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:00 +0200 Subject: [PATCH 109/698] New translations orm.md (Japanese) --- guide/content/ja/guide/how-to/orm.md | 467 +++++++++++++++++++++++++++ 1 file changed, 467 insertions(+) create mode 100644 guide/content/ja/guide/how-to/orm.md diff --git a/guide/content/ja/guide/how-to/orm.md b/guide/content/ja/guide/how-to/orm.md new file mode 100644 index 0000000000..5f7f188d9a --- /dev/null +++ b/guide/content/ja/guide/how-to/orm.md @@ -0,0 +1,467 @@ +# ORM + +> How do I use SQLAlchemy with Sanic ? + +All ORM tools can work with Sanic, but non-async ORM tool have a impact on Sanic performance. +There are some orm packages who support + +At present, there are many ORMs that support Python's `async`/`await` keywords. Some possible choices include： + +- [Mayim](https://ahopkins.github.io/mayim/) +- [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) +- [tortoise-orm](https://github.com/tortoise/tortoise-orm) + +Integration in to your Sanic application is fairly simple: + +## Mayim + +Mayim ships with [an extension for Sanic Extensions](https://ahopkins.github.io/mayim/guide/extensions.html#sanic), which makes it super simple to get started with Sanic. It is certainly possible to run Mayim with Sanic without the extension, but it is recommended because it handles all of the [lifecycle events](https://sanic.dev/en/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html). + +.. column:: + +``` +### Dependencies + +First, we need to install the required dependencies. See [Mayim docs](https://ahopkins.github.io/mayim/guide/install.html#postgres) for the installation needed for your DB driver. +``` + +.. column:: + +```` +```shell +pip install sanic-ext +pip install mayim[postgres] +``` +```` + +.. column:: + +``` +### Define ORM Model + +Mayim allows you to use whatever you want for models. Whether it is [dataclasses](https://docs.python.org/3/library/dataclasses.html), [pydantic](https://pydantic-docs.helpmanual.io/), [attrs](https://www.attrs.org/en/stable/), or even just plain `dict` objects. Since it works very nicely [out of the box with Pydantic](https://ahopkins.github.io/mayim/guide/pydantic.html), that is what we will use here. +``` + +.. column:: + +```` +```python +# ./models.py +from pydantic import BaseModel + +class City(BaseModel): + id: int + name: str + district: str + population: int + +class Country(BaseModel): + code: str + name: str + continent: str + region: str + capital: City +``` +```` + +.. column:: + +``` +### Define SQL + +If you are unfamiliar, Mayim is different from other ORMs in that it is one-way, SQL-first. This means you define your own queries either inline, or in a separate `.sql` file, which is what we will do here. +``` + +.. column:: + +```` +```sql +-- ./queries/select_all_countries.sql +SELECT country.code, + country.name, + country.continent, + country.region, + ( + SELECT row_to_json(q) + FROM ( + SELECT city.id, + city.name, + city.district, + city.population + ) q + ) capital +FROM country + JOIN city ON country.capital = city.id +ORDER BY country.name ASC +LIMIT $limit OFFSET $offset; +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +We need to create the app instance and attach the `SanicMayimExtension` with any executors. +``` + +.. column:: + +```` +```python +# ./server.py +from sanic import Sanic, Request, json +from sanic_ext import Extend +from mayim.executor import PostgresExecutor +from mayim.extensions import SanicMayimExtension +from models import Country + +class CountryExecutor(PostgresExecutor): + async def select_all_countries( + self, limit: int = 4, offset: int = 0 + ) -> list[Country]: + ... + +app = Sanic("Test") +Extend.register( + SanicMayimExtension( + executors=[CountryExecutor], + dsn="postgres://...", + ) +) +``` +```` + +.. column:: + +``` +### Register Routes + +Because we are using Mayim's extension for Sanic, we have the automatic `CountryExecutor` injection into the route handler. It makes for an easy, type-annotated development experience. +``` + +.. column:: + +```` +```python +@app.get("/") +async def handler(request: Request, executor: CountryExecutor): + countries = await executor.select_all_countries() + return json({"countries": [country.dict() for country in co +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl 'http://127.0.0.1:8000' +{"countries":[{"code":"AFG","name":"Afghanistan","continent":"Asia","region":"Southern and Central Asia","capital":{"id":1,"name":"Kabul","district":"Kabol","population":1780000}},{"code":"ALB","name":"Albania","continent":"Europe","region":"Southern Europe","capital":{"id":34,"name":"Tirana","district":"Tirana","population":270000}},{"code":"DZA","name":"Algeria","continent":"Africa","region":"Northern Africa","capital":{"id":35,"name":"Alger","district":"Alger","population":2168000}},{"code":"ASM","name":"American Samoa","continent":"Oceania","region":"Polynesia","capital":{"id":54,"name":"Fagatogo","district":"Tutuila","population":2323}}]} +``` +```` + +## SQLAlchemy + +Because [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) has added native support for `asyncio`, Sanic can finally work well with SQLAlchemy. Be aware that this functionality is still considered _beta_ by the SQLAlchemy project. + +.. column:: + +``` +### Dependencies + +First, we need to install the required dependencies. In the past, the dependencies installed were `sqlalchemy` and `pymysql`, but now `sqlalchemy` and `aiomysql` are needed. +``` + +.. column:: + +```` +```shell +pip install -U sqlalchemy +pip install -U aiomysql +``` +```` + +.. column:: + +``` +### Define ORM Model + +ORM model creation remains the same. +``` + +.. column:: + +```` +```python +# ./models.py +from sqlalchemy import INTEGER, Column, ForeignKey, String +from sqlalchemy.orm import declarative_base, relationship + +Base = declarative_base() + +class BaseModel(Base): + __abstract__ = True + id = Column(INTEGER(), primary_key=True) + +class Person(BaseModel): + __tablename__ = "person" + name = Column(String()) + cars = relationship("Car") + + def to_dict(self): + return {"name": self.name, "cars": [{"brand": car.brand} for car in self.cars]} + +class Car(BaseModel): + __tablename__ = "car" + + brand = Column(String()) + user_id = Column(ForeignKey("person.id")) + user = relationship("Person", back_populates="cars") +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +Here we use mysql as the database, and you can also choose PostgreSQL/SQLite. Pay attention to changing the driver from `aiomysql` to `asyncpg`/`aiosqlite`. +``` + +.. column:: + +```` +```python +# ./server.py +from sanic import Sanic +from sqlalchemy.ext.asyncio import create_async_engine + +app = Sanic("my_app") + +bind = create_async_engine("mysql+aiomysql://root:root@localhost/test", echo=True) +``` +```` + +.. column:: + +``` +### Register Middlewares + +The request middleware creates an usable `AsyncSession` object and set it to `request.ctx` and `_base_model_session_ctx`. + +Thread-safe variable `_base_model_session_ctx` helps you to use the session object instead of fetching it from `request.ctx`. +``` + +.. column:: + +```` +```python +# ./server.py +from contextvars import ContextVar + +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy.orm import sessionmaker + +_sessionmaker = sessionmaker(bind, AsyncSession, expire_on_commit=False) + +_base_model_session_ctx = ContextVar("session") + +@app.middleware("request") +async def inject_session(request): + request.ctx.session = _sessionmaker() + request.ctx.session_ctx_token = _base_model_session_ctx.set(request.ctx.session) + +@app.middleware("response") +async def close_session(request, response): + if hasattr(request.ctx, "session_ctx_token"): + _base_model_session_ctx.reset(request.ctx.session_ctx_token) + await request.ctx.session.close() +``` +```` + +.. column:: + +``` +### Register Routes + +According to sqlalchemy official docs, `session.query` will be legacy in 2.0, and the 2.0 way to query an ORM object is using `select`. +``` + +.. column:: + +```` +```python +# ./server.py +from sqlalchemy import select +from sqlalchemy.orm import selectinload +from sanic.response import json + +from models import Car, Person + +@app.post("/user") +async def create_user(request): + session = request.ctx.session + async with session.begin(): + car = Car(brand="Tesla") + person = Person(name="foo", cars=[car]) + session.add_all([person]) + return json(person.to_dict()) + +@app.get("/user/") +async def get_user(request, pk): + session = request.ctx.session + async with session.begin(): + stmt = select(Person).where(Person.id == pk).options(selectinload(Person.cars)) + result = await session.execute(stmt) + person = result.scalar() + + if not person: + return json({}) + + return json(person.to_dict()) +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl --location --request POST 'http://127.0.0.1:8000/user' +{"name":"foo","cars":[{"brand":"Tesla"}]} +``` + +```sh +curl --location --request GET 'http://127.0.0.1:8000/user/1' +{"name":"foo","cars":[{"brand":"Tesla"}]} +``` +```` + +## Tortoise-ORM + +.. column:: + +``` +### Dependencies + +tortoise-orm's dependency is very simple, you just need install tortoise-orm. +``` + +.. column:: + +```` +```shell +pip install -U tortoise-orm +``` +```` + +.. column:: + +``` +### Define ORM Model + +If you are familiar with Django, you should find this part very familiar. +``` + +.. column:: + +```` +```python +# ./models.py +from tortoise import Model, fields + +class Users(Model): + id = fields.IntField(pk=True) + name = fields.CharField(50) + + def __str__(self): + return f"I am {self.name}" +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +Tortoise-orm provides a set of registration interface, which is convenient for users, and you can use it to create database connection easily. +``` + +.. column:: + +```` +```python +# ./main.py + +from models import Users +from tortoise.contrib.sanic import register_tortoise + +app = Sanic(__name__) + +register_tortoise( + app, db_url="mysql://root:root@localhost/test", modules={"models": ["models"]}, generate_schemas=True +) + +``` +```` + +.. column:: + +``` +### Register Routes +``` + +.. column:: + +```` +```python +# ./main.py + +from models import Users +from sanic import Sanic, response + +@app.route("/user") +async def list_all(request): + users = await Users.all() + return response.json({"users": [str(user) for user in users]}) + +@app.route("/user/") +async def get_user(request, pk): + user = await Users.query(pk=pk) + return response.json({"user": str(user)}) + +if __name__ == "__main__": + app.run(port=5000) +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl --location --request POST 'http://127.0.0.1:8000/user' +{"users":["I am foo", "I am bar"]} +``` + +```sh +curl --location --request GET 'http://127.0.0.1:8000/user/1' +{"user": "I am foo"} +``` +```` From ac587dadb59ced023ea3966ba3fd0b4e643d01fe Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:01 +0200 Subject: [PATCH 110/698] New translations orm.md (Korean) --- guide/content/ko/guide/how-to/orm.md | 467 +++++++++++++++++++++++++++ 1 file changed, 467 insertions(+) create mode 100644 guide/content/ko/guide/how-to/orm.md diff --git a/guide/content/ko/guide/how-to/orm.md b/guide/content/ko/guide/how-to/orm.md new file mode 100644 index 0000000000..5f7f188d9a --- /dev/null +++ b/guide/content/ko/guide/how-to/orm.md @@ -0,0 +1,467 @@ +# ORM + +> How do I use SQLAlchemy with Sanic ? + +All ORM tools can work with Sanic, but non-async ORM tool have a impact on Sanic performance. +There are some orm packages who support + +At present, there are many ORMs that support Python's `async`/`await` keywords. Some possible choices include： + +- [Mayim](https://ahopkins.github.io/mayim/) +- [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) +- [tortoise-orm](https://github.com/tortoise/tortoise-orm) + +Integration in to your Sanic application is fairly simple: + +## Mayim + +Mayim ships with [an extension for Sanic Extensions](https://ahopkins.github.io/mayim/guide/extensions.html#sanic), which makes it super simple to get started with Sanic. It is certainly possible to run Mayim with Sanic without the extension, but it is recommended because it handles all of the [lifecycle events](https://sanic.dev/en/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html). + +.. column:: + +``` +### Dependencies + +First, we need to install the required dependencies. See [Mayim docs](https://ahopkins.github.io/mayim/guide/install.html#postgres) for the installation needed for your DB driver. +``` + +.. column:: + +```` +```shell +pip install sanic-ext +pip install mayim[postgres] +``` +```` + +.. column:: + +``` +### Define ORM Model + +Mayim allows you to use whatever you want for models. Whether it is [dataclasses](https://docs.python.org/3/library/dataclasses.html), [pydantic](https://pydantic-docs.helpmanual.io/), [attrs](https://www.attrs.org/en/stable/), or even just plain `dict` objects. Since it works very nicely [out of the box with Pydantic](https://ahopkins.github.io/mayim/guide/pydantic.html), that is what we will use here. +``` + +.. column:: + +```` +```python +# ./models.py +from pydantic import BaseModel + +class City(BaseModel): + id: int + name: str + district: str + population: int + +class Country(BaseModel): + code: str + name: str + continent: str + region: str + capital: City +``` +```` + +.. column:: + +``` +### Define SQL + +If you are unfamiliar, Mayim is different from other ORMs in that it is one-way, SQL-first. This means you define your own queries either inline, or in a separate `.sql` file, which is what we will do here. +``` + +.. column:: + +```` +```sql +-- ./queries/select_all_countries.sql +SELECT country.code, + country.name, + country.continent, + country.region, + ( + SELECT row_to_json(q) + FROM ( + SELECT city.id, + city.name, + city.district, + city.population + ) q + ) capital +FROM country + JOIN city ON country.capital = city.id +ORDER BY country.name ASC +LIMIT $limit OFFSET $offset; +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +We need to create the app instance and attach the `SanicMayimExtension` with any executors. +``` + +.. column:: + +```` +```python +# ./server.py +from sanic import Sanic, Request, json +from sanic_ext import Extend +from mayim.executor import PostgresExecutor +from mayim.extensions import SanicMayimExtension +from models import Country + +class CountryExecutor(PostgresExecutor): + async def select_all_countries( + self, limit: int = 4, offset: int = 0 + ) -> list[Country]: + ... + +app = Sanic("Test") +Extend.register( + SanicMayimExtension( + executors=[CountryExecutor], + dsn="postgres://...", + ) +) +``` +```` + +.. column:: + +``` +### Register Routes + +Because we are using Mayim's extension for Sanic, we have the automatic `CountryExecutor` injection into the route handler. It makes for an easy, type-annotated development experience. +``` + +.. column:: + +```` +```python +@app.get("/") +async def handler(request: Request, executor: CountryExecutor): + countries = await executor.select_all_countries() + return json({"countries": [country.dict() for country in co +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl 'http://127.0.0.1:8000' +{"countries":[{"code":"AFG","name":"Afghanistan","continent":"Asia","region":"Southern and Central Asia","capital":{"id":1,"name":"Kabul","district":"Kabol","population":1780000}},{"code":"ALB","name":"Albania","continent":"Europe","region":"Southern Europe","capital":{"id":34,"name":"Tirana","district":"Tirana","population":270000}},{"code":"DZA","name":"Algeria","continent":"Africa","region":"Northern Africa","capital":{"id":35,"name":"Alger","district":"Alger","population":2168000}},{"code":"ASM","name":"American Samoa","continent":"Oceania","region":"Polynesia","capital":{"id":54,"name":"Fagatogo","district":"Tutuila","population":2323}}]} +``` +```` + +## SQLAlchemy + +Because [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) has added native support for `asyncio`, Sanic can finally work well with SQLAlchemy. Be aware that this functionality is still considered _beta_ by the SQLAlchemy project. + +.. column:: + +``` +### Dependencies + +First, we need to install the required dependencies. In the past, the dependencies installed were `sqlalchemy` and `pymysql`, but now `sqlalchemy` and `aiomysql` are needed. +``` + +.. column:: + +```` +```shell +pip install -U sqlalchemy +pip install -U aiomysql +``` +```` + +.. column:: + +``` +### Define ORM Model + +ORM model creation remains the same. +``` + +.. column:: + +```` +```python +# ./models.py +from sqlalchemy import INTEGER, Column, ForeignKey, String +from sqlalchemy.orm import declarative_base, relationship + +Base = declarative_base() + +class BaseModel(Base): + __abstract__ = True + id = Column(INTEGER(), primary_key=True) + +class Person(BaseModel): + __tablename__ = "person" + name = Column(String()) + cars = relationship("Car") + + def to_dict(self): + return {"name": self.name, "cars": [{"brand": car.brand} for car in self.cars]} + +class Car(BaseModel): + __tablename__ = "car" + + brand = Column(String()) + user_id = Column(ForeignKey("person.id")) + user = relationship("Person", back_populates="cars") +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +Here we use mysql as the database, and you can also choose PostgreSQL/SQLite. Pay attention to changing the driver from `aiomysql` to `asyncpg`/`aiosqlite`. +``` + +.. column:: + +```` +```python +# ./server.py +from sanic import Sanic +from sqlalchemy.ext.asyncio import create_async_engine + +app = Sanic("my_app") + +bind = create_async_engine("mysql+aiomysql://root:root@localhost/test", echo=True) +``` +```` + +.. column:: + +``` +### Register Middlewares + +The request middleware creates an usable `AsyncSession` object and set it to `request.ctx` and `_base_model_session_ctx`. + +Thread-safe variable `_base_model_session_ctx` helps you to use the session object instead of fetching it from `request.ctx`. +``` + +.. column:: + +```` +```python +# ./server.py +from contextvars import ContextVar + +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy.orm import sessionmaker + +_sessionmaker = sessionmaker(bind, AsyncSession, expire_on_commit=False) + +_base_model_session_ctx = ContextVar("session") + +@app.middleware("request") +async def inject_session(request): + request.ctx.session = _sessionmaker() + request.ctx.session_ctx_token = _base_model_session_ctx.set(request.ctx.session) + +@app.middleware("response") +async def close_session(request, response): + if hasattr(request.ctx, "session_ctx_token"): + _base_model_session_ctx.reset(request.ctx.session_ctx_token) + await request.ctx.session.close() +``` +```` + +.. column:: + +``` +### Register Routes + +According to sqlalchemy official docs, `session.query` will be legacy in 2.0, and the 2.0 way to query an ORM object is using `select`. +``` + +.. column:: + +```` +```python +# ./server.py +from sqlalchemy import select +from sqlalchemy.orm import selectinload +from sanic.response import json + +from models import Car, Person + +@app.post("/user") +async def create_user(request): + session = request.ctx.session + async with session.begin(): + car = Car(brand="Tesla") + person = Person(name="foo", cars=[car]) + session.add_all([person]) + return json(person.to_dict()) + +@app.get("/user/") +async def get_user(request, pk): + session = request.ctx.session + async with session.begin(): + stmt = select(Person).where(Person.id == pk).options(selectinload(Person.cars)) + result = await session.execute(stmt) + person = result.scalar() + + if not person: + return json({}) + + return json(person.to_dict()) +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl --location --request POST 'http://127.0.0.1:8000/user' +{"name":"foo","cars":[{"brand":"Tesla"}]} +``` + +```sh +curl --location --request GET 'http://127.0.0.1:8000/user/1' +{"name":"foo","cars":[{"brand":"Tesla"}]} +``` +```` + +## Tortoise-ORM + +.. column:: + +``` +### Dependencies + +tortoise-orm's dependency is very simple, you just need install tortoise-orm. +``` + +.. column:: + +```` +```shell +pip install -U tortoise-orm +``` +```` + +.. column:: + +``` +### Define ORM Model + +If you are familiar with Django, you should find this part very familiar. +``` + +.. column:: + +```` +```python +# ./models.py +from tortoise import Model, fields + +class Users(Model): + id = fields.IntField(pk=True) + name = fields.CharField(50) + + def __str__(self): + return f"I am {self.name}" +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +Tortoise-orm provides a set of registration interface, which is convenient for users, and you can use it to create database connection easily. +``` + +.. column:: + +```` +```python +# ./main.py + +from models import Users +from tortoise.contrib.sanic import register_tortoise + +app = Sanic(__name__) + +register_tortoise( + app, db_url="mysql://root:root@localhost/test", modules={"models": ["models"]}, generate_schemas=True +) + +``` +```` + +.. column:: + +``` +### Register Routes +``` + +.. column:: + +```` +```python +# ./main.py + +from models import Users +from sanic import Sanic, response + +@app.route("/user") +async def list_all(request): + users = await Users.all() + return response.json({"users": [str(user) for user in users]}) + +@app.route("/user/") +async def get_user(request, pk): + user = await Users.query(pk=pk) + return response.json({"user": str(user)}) + +if __name__ == "__main__": + app.run(port=5000) +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl --location --request POST 'http://127.0.0.1:8000/user' +{"users":["I am foo", "I am bar"]} +``` + +```sh +curl --location --request GET 'http://127.0.0.1:8000/user/1' +{"user": "I am foo"} +``` +```` From 54b9be5592f5a0ba5b4b407ae61b52f8f5aaeb3d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:02 +0200 Subject: [PATCH 111/698] New translations orm.md (Chinese Simplified) --- guide/content/zh/guide/how-to/orm.md | 467 +++++++++++++++++++++++++++ 1 file changed, 467 insertions(+) create mode 100644 guide/content/zh/guide/how-to/orm.md diff --git a/guide/content/zh/guide/how-to/orm.md b/guide/content/zh/guide/how-to/orm.md new file mode 100644 index 0000000000..5f7f188d9a --- /dev/null +++ b/guide/content/zh/guide/how-to/orm.md @@ -0,0 +1,467 @@ +# ORM + +> How do I use SQLAlchemy with Sanic ? + +All ORM tools can work with Sanic, but non-async ORM tool have a impact on Sanic performance. +There are some orm packages who support + +At present, there are many ORMs that support Python's `async`/`await` keywords. Some possible choices include： + +- [Mayim](https://ahopkins.github.io/mayim/) +- [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) +- [tortoise-orm](https://github.com/tortoise/tortoise-orm) + +Integration in to your Sanic application is fairly simple: + +## Mayim + +Mayim ships with [an extension for Sanic Extensions](https://ahopkins.github.io/mayim/guide/extensions.html#sanic), which makes it super simple to get started with Sanic. It is certainly possible to run Mayim with Sanic without the extension, but it is recommended because it handles all of the [lifecycle events](https://sanic.dev/en/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html). + +.. column:: + +``` +### Dependencies + +First, we need to install the required dependencies. See [Mayim docs](https://ahopkins.github.io/mayim/guide/install.html#postgres) for the installation needed for your DB driver. +``` + +.. column:: + +```` +```shell +pip install sanic-ext +pip install mayim[postgres] +``` +```` + +.. column:: + +``` +### Define ORM Model + +Mayim allows you to use whatever you want for models. Whether it is [dataclasses](https://docs.python.org/3/library/dataclasses.html), [pydantic](https://pydantic-docs.helpmanual.io/), [attrs](https://www.attrs.org/en/stable/), or even just plain `dict` objects. Since it works very nicely [out of the box with Pydantic](https://ahopkins.github.io/mayim/guide/pydantic.html), that is what we will use here. +``` + +.. column:: + +```` +```python +# ./models.py +from pydantic import BaseModel + +class City(BaseModel): + id: int + name: str + district: str + population: int + +class Country(BaseModel): + code: str + name: str + continent: str + region: str + capital: City +``` +```` + +.. column:: + +``` +### Define SQL + +If you are unfamiliar, Mayim is different from other ORMs in that it is one-way, SQL-first. This means you define your own queries either inline, or in a separate `.sql` file, which is what we will do here. +``` + +.. column:: + +```` +```sql +-- ./queries/select_all_countries.sql +SELECT country.code, + country.name, + country.continent, + country.region, + ( + SELECT row_to_json(q) + FROM ( + SELECT city.id, + city.name, + city.district, + city.population + ) q + ) capital +FROM country + JOIN city ON country.capital = city.id +ORDER BY country.name ASC +LIMIT $limit OFFSET $offset; +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +We need to create the app instance and attach the `SanicMayimExtension` with any executors. +``` + +.. column:: + +```` +```python +# ./server.py +from sanic import Sanic, Request, json +from sanic_ext import Extend +from mayim.executor import PostgresExecutor +from mayim.extensions import SanicMayimExtension +from models import Country + +class CountryExecutor(PostgresExecutor): + async def select_all_countries( + self, limit: int = 4, offset: int = 0 + ) -> list[Country]: + ... + +app = Sanic("Test") +Extend.register( + SanicMayimExtension( + executors=[CountryExecutor], + dsn="postgres://...", + ) +) +``` +```` + +.. column:: + +``` +### Register Routes + +Because we are using Mayim's extension for Sanic, we have the automatic `CountryExecutor` injection into the route handler. It makes for an easy, type-annotated development experience. +``` + +.. column:: + +```` +```python +@app.get("/") +async def handler(request: Request, executor: CountryExecutor): + countries = await executor.select_all_countries() + return json({"countries": [country.dict() for country in co +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl 'http://127.0.0.1:8000' +{"countries":[{"code":"AFG","name":"Afghanistan","continent":"Asia","region":"Southern and Central Asia","capital":{"id":1,"name":"Kabul","district":"Kabol","population":1780000}},{"code":"ALB","name":"Albania","continent":"Europe","region":"Southern Europe","capital":{"id":34,"name":"Tirana","district":"Tirana","population":270000}},{"code":"DZA","name":"Algeria","continent":"Africa","region":"Northern Africa","capital":{"id":35,"name":"Alger","district":"Alger","population":2168000}},{"code":"ASM","name":"American Samoa","continent":"Oceania","region":"Polynesia","capital":{"id":54,"name":"Fagatogo","district":"Tutuila","population":2323}}]} +``` +```` + +## SQLAlchemy + +Because [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) has added native support for `asyncio`, Sanic can finally work well with SQLAlchemy. Be aware that this functionality is still considered _beta_ by the SQLAlchemy project. + +.. column:: + +``` +### Dependencies + +First, we need to install the required dependencies. In the past, the dependencies installed were `sqlalchemy` and `pymysql`, but now `sqlalchemy` and `aiomysql` are needed. +``` + +.. column:: + +```` +```shell +pip install -U sqlalchemy +pip install -U aiomysql +``` +```` + +.. column:: + +``` +### Define ORM Model + +ORM model creation remains the same. +``` + +.. column:: + +```` +```python +# ./models.py +from sqlalchemy import INTEGER, Column, ForeignKey, String +from sqlalchemy.orm import declarative_base, relationship + +Base = declarative_base() + +class BaseModel(Base): + __abstract__ = True + id = Column(INTEGER(), primary_key=True) + +class Person(BaseModel): + __tablename__ = "person" + name = Column(String()) + cars = relationship("Car") + + def to_dict(self): + return {"name": self.name, "cars": [{"brand": car.brand} for car in self.cars]} + +class Car(BaseModel): + __tablename__ = "car" + + brand = Column(String()) + user_id = Column(ForeignKey("person.id")) + user = relationship("Person", back_populates="cars") +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +Here we use mysql as the database, and you can also choose PostgreSQL/SQLite. Pay attention to changing the driver from `aiomysql` to `asyncpg`/`aiosqlite`. +``` + +.. column:: + +```` +```python +# ./server.py +from sanic import Sanic +from sqlalchemy.ext.asyncio import create_async_engine + +app = Sanic("my_app") + +bind = create_async_engine("mysql+aiomysql://root:root@localhost/test", echo=True) +``` +```` + +.. column:: + +``` +### Register Middlewares + +The request middleware creates an usable `AsyncSession` object and set it to `request.ctx` and `_base_model_session_ctx`. + +Thread-safe variable `_base_model_session_ctx` helps you to use the session object instead of fetching it from `request.ctx`. +``` + +.. column:: + +```` +```python +# ./server.py +from contextvars import ContextVar + +from sqlalchemy.ext.asyncio import AsyncSession +from sqlalchemy.orm import sessionmaker + +_sessionmaker = sessionmaker(bind, AsyncSession, expire_on_commit=False) + +_base_model_session_ctx = ContextVar("session") + +@app.middleware("request") +async def inject_session(request): + request.ctx.session = _sessionmaker() + request.ctx.session_ctx_token = _base_model_session_ctx.set(request.ctx.session) + +@app.middleware("response") +async def close_session(request, response): + if hasattr(request.ctx, "session_ctx_token"): + _base_model_session_ctx.reset(request.ctx.session_ctx_token) + await request.ctx.session.close() +``` +```` + +.. column:: + +``` +### Register Routes + +According to sqlalchemy official docs, `session.query` will be legacy in 2.0, and the 2.0 way to query an ORM object is using `select`. +``` + +.. column:: + +```` +```python +# ./server.py +from sqlalchemy import select +from sqlalchemy.orm import selectinload +from sanic.response import json + +from models import Car, Person + +@app.post("/user") +async def create_user(request): + session = request.ctx.session + async with session.begin(): + car = Car(brand="Tesla") + person = Person(name="foo", cars=[car]) + session.add_all([person]) + return json(person.to_dict()) + +@app.get("/user/") +async def get_user(request, pk): + session = request.ctx.session + async with session.begin(): + stmt = select(Person).where(Person.id == pk).options(selectinload(Person.cars)) + result = await session.execute(stmt) + person = result.scalar() + + if not person: + return json({}) + + return json(person.to_dict()) +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl --location --request POST 'http://127.0.0.1:8000/user' +{"name":"foo","cars":[{"brand":"Tesla"}]} +``` + +```sh +curl --location --request GET 'http://127.0.0.1:8000/user/1' +{"name":"foo","cars":[{"brand":"Tesla"}]} +``` +```` + +## Tortoise-ORM + +.. column:: + +``` +### Dependencies + +tortoise-orm's dependency is very simple, you just need install tortoise-orm. +``` + +.. column:: + +```` +```shell +pip install -U tortoise-orm +``` +```` + +.. column:: + +``` +### Define ORM Model + +If you are familiar with Django, you should find this part very familiar. +``` + +.. column:: + +```` +```python +# ./models.py +from tortoise import Model, fields + +class Users(Model): + id = fields.IntField(pk=True) + name = fields.CharField(50) + + def __str__(self): + return f"I am {self.name}" +``` +```` + +.. column:: + +``` +### Create Sanic App and Async Engine + +Tortoise-orm provides a set of registration interface, which is convenient for users, and you can use it to create database connection easily. +``` + +.. column:: + +```` +```python +# ./main.py + +from models import Users +from tortoise.contrib.sanic import register_tortoise + +app = Sanic(__name__) + +register_tortoise( + app, db_url="mysql://root:root@localhost/test", modules={"models": ["models"]}, generate_schemas=True +) + +``` +```` + +.. column:: + +``` +### Register Routes +``` + +.. column:: + +```` +```python +# ./main.py + +from models import Users +from sanic import Sanic, response + +@app.route("/user") +async def list_all(request): + users = await Users.all() + return response.json({"users": [str(user) for user in users]}) + +@app.route("/user/") +async def get_user(request, pk): + user = await Users.query(pk=pk) + return response.json({"user": str(user)}) + +if __name__ == "__main__": + app.run(port=5000) +``` +```` + +.. column:: + +``` +### Send Requests +``` + +.. column:: + +```` +```sh +curl --location --request POST 'http://127.0.0.1:8000/user' +{"users":["I am foo", "I am bar"]} +``` + +```sh +curl --location --request GET 'http://127.0.0.1:8000/user/1' +{"user": "I am foo"} +``` +```` From 1b8d596beaf7b02220e9eb5a7b5d2b7c0499ff5c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:03 +0200 Subject: [PATCH 112/698] New translations serialization.md (Japanese) --- guide/content/ja/guide/how-to/serialization.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/serialization.md diff --git a/guide/content/ja/guide/how-to/serialization.md b/guide/content/ja/guide/how-to/serialization.md new file mode 100644 index 0000000000..0dfc62d35b --- /dev/null +++ b/guide/content/ja/guide/how-to/serialization.md @@ -0,0 +1 @@ +# Serialization From 70c3481bb1f03a8be9b0d9b995d68fdcb24c2f08 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:04 +0200 Subject: [PATCH 113/698] New translations serialization.md (Korean) --- guide/content/ko/guide/how-to/serialization.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/serialization.md diff --git a/guide/content/ko/guide/how-to/serialization.md b/guide/content/ko/guide/how-to/serialization.md new file mode 100644 index 0000000000..0dfc62d35b --- /dev/null +++ b/guide/content/ko/guide/how-to/serialization.md @@ -0,0 +1 @@ +# Serialization From deedf30d8f8658ca28b3f0e72e031d8d73284279 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:05 +0200 Subject: [PATCH 114/698] New translations serialization.md (Chinese Simplified) --- guide/content/zh/guide/how-to/serialization.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/serialization.md diff --git a/guide/content/zh/guide/how-to/serialization.md b/guide/content/zh/guide/how-to/serialization.md new file mode 100644 index 0000000000..0dfc62d35b --- /dev/null +++ b/guide/content/zh/guide/how-to/serialization.md @@ -0,0 +1 @@ +# Serialization From 08ba0a827380aef79aaec66400662f1d3d7be009 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:05 +0200 Subject: [PATCH 115/698] New translations server-sent-events.md (Japanese) --- guide/content/ja/guide/how-to/server-sent-events.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/server-sent-events.md diff --git a/guide/content/ja/guide/how-to/server-sent-events.md b/guide/content/ja/guide/how-to/server-sent-events.md new file mode 100644 index 0000000000..7daf86745e --- /dev/null +++ b/guide/content/ja/guide/how-to/server-sent-events.md @@ -0,0 +1 @@ +sse From 07f182cf56dbffda98eb3244f4e57d607414c1d1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:06 +0200 Subject: [PATCH 116/698] New translations server-sent-events.md (Korean) --- guide/content/ko/guide/how-to/server-sent-events.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/server-sent-events.md diff --git a/guide/content/ko/guide/how-to/server-sent-events.md b/guide/content/ko/guide/how-to/server-sent-events.md new file mode 100644 index 0000000000..7daf86745e --- /dev/null +++ b/guide/content/ko/guide/how-to/server-sent-events.md @@ -0,0 +1 @@ +sse From e7550d8da7d579e4058a355b621d1e5c2f7a98dd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:07 +0200 Subject: [PATCH 117/698] New translations server-sent-events.md (Chinese Simplified) --- guide/content/zh/guide/how-to/server-sent-events.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/server-sent-events.md diff --git a/guide/content/zh/guide/how-to/server-sent-events.md b/guide/content/zh/guide/how-to/server-sent-events.md new file mode 100644 index 0000000000..7daf86745e --- /dev/null +++ b/guide/content/zh/guide/how-to/server-sent-events.md @@ -0,0 +1 @@ +sse From d59983feaf60fd68930d4feb96c41ed7a99b0b13 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:08 +0200 Subject: [PATCH 118/698] New translations static-redirects.md (Japanese) --- .../ja/guide/how-to/static-redirects.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 guide/content/ja/guide/how-to/static-redirects.md diff --git a/guide/content/ja/guide/how-to/static-redirects.md b/guide/content/ja/guide/how-to/static-redirects.md new file mode 100644 index 0000000000..0fb99202bf --- /dev/null +++ b/guide/content/ja/guide/how-to/static-redirects.md @@ -0,0 +1,112 @@ +# "Static" Redirects + +> How do I configure static redirects? + +## `app.py` + +```python +### SETUP ### +import typing +import sanic, sanic.response + +# Create the Sanic app +app = sanic.Sanic(__name__) + +# This dictionary represents your "static" +# redirects. For example, these values +# could be pulled from a configuration file. +REDIRECTS = { + '/':'/hello_world', # Redirect '/' to '/hello_world' + '/hello_world':'/hello_world.html' # Redirect '/hello_world' to 'hello_world.html' +} + +# This function will return another function +# that will return the configured value +# regardless of the arguments passed to it. +def get_static_function(value:typing.Any) -> typing.Callable[..., typing.Any]: + return lambda *_, **__: value + +### ROUTING ### +# Iterate through the redirects +for src, dest in REDIRECTS.items(): + # Create the redirect response object + response:sanic.HTTPResponse = sanic.response.redirect(dest) + + # Create the handler function. Typically, + # only a sanic.Request object is passed + # to the function. This object will be + # ignored. + handler = get_static_function(response) + + # Route the src path to the handler + app.route(src)(handler) + +# Route some file and client resources +app.static('/files/', 'files') +app.static('/', 'client') + +### RUN ### +if __name__ == '__main__': + app.run( + '127.0.0.1', + 10000 + ) +``` + +## `client/hello_world.html` + +```html + + + + + + + Hello World + + + +
+ Hello world! +
+ + +``` + +## `client/hello_world.css` + +```css +#hello_world { + width: 1000px; + margin-left: auto; + margin-right: auto; + margin-top: 100px; + + padding: 100px; + color: aqua; + text-align: center; + font-size: 100px; + font-family: monospace; + + background-color: rgba(0, 0, 0, 0.75); + + border-radius: 10px; + box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.75); +} + +body { + background-image: url("/files/grottoes.jpg"); + background-repeat: no-repeat; + background-size: cover; +} +``` + +## `files/grottoes.jpg` + +![lake](/assets/images/grottoes.jpg) + +*** + +Also, checkout some resources from the community: + +- [Static Routing Example](https://github.com/Perzan/sanic-static-routing-example) From 6e1d57d080b008223e96ac1275bc2a441311805d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:09 +0200 Subject: [PATCH 119/698] New translations static-redirects.md (Korean) --- .../ko/guide/how-to/static-redirects.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 guide/content/ko/guide/how-to/static-redirects.md diff --git a/guide/content/ko/guide/how-to/static-redirects.md b/guide/content/ko/guide/how-to/static-redirects.md new file mode 100644 index 0000000000..0fb99202bf --- /dev/null +++ b/guide/content/ko/guide/how-to/static-redirects.md @@ -0,0 +1,112 @@ +# "Static" Redirects + +> How do I configure static redirects? + +## `app.py` + +```python +### SETUP ### +import typing +import sanic, sanic.response + +# Create the Sanic app +app = sanic.Sanic(__name__) + +# This dictionary represents your "static" +# redirects. For example, these values +# could be pulled from a configuration file. +REDIRECTS = { + '/':'/hello_world', # Redirect '/' to '/hello_world' + '/hello_world':'/hello_world.html' # Redirect '/hello_world' to 'hello_world.html' +} + +# This function will return another function +# that will return the configured value +# regardless of the arguments passed to it. +def get_static_function(value:typing.Any) -> typing.Callable[..., typing.Any]: + return lambda *_, **__: value + +### ROUTING ### +# Iterate through the redirects +for src, dest in REDIRECTS.items(): + # Create the redirect response object + response:sanic.HTTPResponse = sanic.response.redirect(dest) + + # Create the handler function. Typically, + # only a sanic.Request object is passed + # to the function. This object will be + # ignored. + handler = get_static_function(response) + + # Route the src path to the handler + app.route(src)(handler) + +# Route some file and client resources +app.static('/files/', 'files') +app.static('/', 'client') + +### RUN ### +if __name__ == '__main__': + app.run( + '127.0.0.1', + 10000 + ) +``` + +## `client/hello_world.html` + +```html + + + + + + + Hello World + + + +
+ Hello world! +
+ + +``` + +## `client/hello_world.css` + +```css +#hello_world { + width: 1000px; + margin-left: auto; + margin-right: auto; + margin-top: 100px; + + padding: 100px; + color: aqua; + text-align: center; + font-size: 100px; + font-family: monospace; + + background-color: rgba(0, 0, 0, 0.75); + + border-radius: 10px; + box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.75); +} + +body { + background-image: url("/files/grottoes.jpg"); + background-repeat: no-repeat; + background-size: cover; +} +``` + +## `files/grottoes.jpg` + +![lake](/assets/images/grottoes.jpg) + +*** + +Also, checkout some resources from the community: + +- [Static Routing Example](https://github.com/Perzan/sanic-static-routing-example) From 487b5354938789e2c9d8dcdc65cc735fe8454b92 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:10 +0200 Subject: [PATCH 120/698] New translations static-redirects.md (Chinese Simplified) --- .../zh/guide/how-to/static-redirects.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 guide/content/zh/guide/how-to/static-redirects.md diff --git a/guide/content/zh/guide/how-to/static-redirects.md b/guide/content/zh/guide/how-to/static-redirects.md new file mode 100644 index 0000000000..0fb99202bf --- /dev/null +++ b/guide/content/zh/guide/how-to/static-redirects.md @@ -0,0 +1,112 @@ +# "Static" Redirects + +> How do I configure static redirects? + +## `app.py` + +```python +### SETUP ### +import typing +import sanic, sanic.response + +# Create the Sanic app +app = sanic.Sanic(__name__) + +# This dictionary represents your "static" +# redirects. For example, these values +# could be pulled from a configuration file. +REDIRECTS = { + '/':'/hello_world', # Redirect '/' to '/hello_world' + '/hello_world':'/hello_world.html' # Redirect '/hello_world' to 'hello_world.html' +} + +# This function will return another function +# that will return the configured value +# regardless of the arguments passed to it. +def get_static_function(value:typing.Any) -> typing.Callable[..., typing.Any]: + return lambda *_, **__: value + +### ROUTING ### +# Iterate through the redirects +for src, dest in REDIRECTS.items(): + # Create the redirect response object + response:sanic.HTTPResponse = sanic.response.redirect(dest) + + # Create the handler function. Typically, + # only a sanic.Request object is passed + # to the function. This object will be + # ignored. + handler = get_static_function(response) + + # Route the src path to the handler + app.route(src)(handler) + +# Route some file and client resources +app.static('/files/', 'files') +app.static('/', 'client') + +### RUN ### +if __name__ == '__main__': + app.run( + '127.0.0.1', + 10000 + ) +``` + +## `client/hello_world.html` + +```html + + + + + + + Hello World + + + +
+ Hello world! +
+ + +``` + +## `client/hello_world.css` + +```css +#hello_world { + width: 1000px; + margin-left: auto; + margin-right: auto; + margin-top: 100px; + + padding: 100px; + color: aqua; + text-align: center; + font-size: 100px; + font-family: monospace; + + background-color: rgba(0, 0, 0, 0.75); + + border-radius: 10px; + box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.75); +} + +body { + background-image: url("/files/grottoes.jpg"); + background-repeat: no-repeat; + background-size: cover; +} +``` + +## `files/grottoes.jpg` + +![lake](/assets/images/grottoes.jpg) + +*** + +Also, checkout some resources from the community: + +- [Static Routing Example](https://github.com/Perzan/sanic-static-routing-example) From 1c0948a3573e04b49c76092ab43d2ff09eb1c8f8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:11 +0200 Subject: [PATCH 121/698] New translations table-of-contents.md (Japanese) --- .../ja/guide/how-to/table-of-contents.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 guide/content/ja/guide/how-to/table-of-contents.md diff --git a/guide/content/ja/guide/how-to/table-of-contents.md b/guide/content/ja/guide/how-to/table-of-contents.md new file mode 100644 index 0000000000..af8da93a77 --- /dev/null +++ b/guide/content/ja/guide/how-to/table-of-contents.md @@ -0,0 +1,17 @@ +--- +title: Table of Contents +--- + +# Table of Contents + +We have compiled fully working examples to answer common questions and user cases. For the most part, the examples are as minimal as possible, but should be complete and runnable solutions. + +| Page | How do I ... | +| :------------------------------------------ | :------------------------------------------------------------------ | +| [Application mounting](./mounting.md) | ... mount my application at some path above the root? | +| [Authentication](./authentication.md) | ... control authentication and authorization? | +| [Autodiscovery](./autodiscovery.md) | ... autodiscover the components I am using to build my application? | +| [CORS](./cors.md) | ... configure my application for CORS? | +| [ORM](./orm) | ... use an ORM with Sanic? | +| ["Static" Redirects](./static-redirects.md) | ... configure static redirects | +| [TLS/SSL/HTTPS](./tls.md) | ... run Sanic via HTTPS?
... redirect HTTP to HTTPS? | From 6b8f281c5dbdf38a2d2be2d3a1e290dd4ba682fb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:12 +0200 Subject: [PATCH 122/698] New translations table-of-contents.md (Korean) --- .../ko/guide/how-to/table-of-contents.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 guide/content/ko/guide/how-to/table-of-contents.md diff --git a/guide/content/ko/guide/how-to/table-of-contents.md b/guide/content/ko/guide/how-to/table-of-contents.md new file mode 100644 index 0000000000..af8da93a77 --- /dev/null +++ b/guide/content/ko/guide/how-to/table-of-contents.md @@ -0,0 +1,17 @@ +--- +title: Table of Contents +--- + +# Table of Contents + +We have compiled fully working examples to answer common questions and user cases. For the most part, the examples are as minimal as possible, but should be complete and runnable solutions. + +| Page | How do I ... | +| :------------------------------------------ | :------------------------------------------------------------------ | +| [Application mounting](./mounting.md) | ... mount my application at some path above the root? | +| [Authentication](./authentication.md) | ... control authentication and authorization? | +| [Autodiscovery](./autodiscovery.md) | ... autodiscover the components I am using to build my application? | +| [CORS](./cors.md) | ... configure my application for CORS? | +| [ORM](./orm) | ... use an ORM with Sanic? | +| ["Static" Redirects](./static-redirects.md) | ... configure static redirects | +| [TLS/SSL/HTTPS](./tls.md) | ... run Sanic via HTTPS?
... redirect HTTP to HTTPS? | From e3f459ac23d36964b5abc16da7131deadcb95d3d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:13 +0200 Subject: [PATCH 123/698] New translations table-of-contents.md (Chinese Simplified) --- .../zh/guide/how-to/table-of-contents.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 guide/content/zh/guide/how-to/table-of-contents.md diff --git a/guide/content/zh/guide/how-to/table-of-contents.md b/guide/content/zh/guide/how-to/table-of-contents.md new file mode 100644 index 0000000000..af8da93a77 --- /dev/null +++ b/guide/content/zh/guide/how-to/table-of-contents.md @@ -0,0 +1,17 @@ +--- +title: Table of Contents +--- + +# Table of Contents + +We have compiled fully working examples to answer common questions and user cases. For the most part, the examples are as minimal as possible, but should be complete and runnable solutions. + +| Page | How do I ... | +| :------------------------------------------ | :------------------------------------------------------------------ | +| [Application mounting](./mounting.md) | ... mount my application at some path above the root? | +| [Authentication](./authentication.md) | ... control authentication and authorization? | +| [Autodiscovery](./autodiscovery.md) | ... autodiscover the components I am using to build my application? | +| [CORS](./cors.md) | ... configure my application for CORS? | +| [ORM](./orm) | ... use an ORM with Sanic? | +| ["Static" Redirects](./static-redirects.md) | ... configure static redirects | +| [TLS/SSL/HTTPS](./tls.md) | ... run Sanic via HTTPS?
... redirect HTTP to HTTPS? | From e02701e27ff56fffae57625af7f658d1ad0f5cd1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:14 +0200 Subject: [PATCH 124/698] New translations task-queue.md (Japanese) --- guide/content/ja/guide/how-to/task-queue.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/task-queue.md diff --git a/guide/content/ja/guide/how-to/task-queue.md b/guide/content/ja/guide/how-to/task-queue.md new file mode 100644 index 0000000000..c5ee7c54a3 --- /dev/null +++ b/guide/content/ja/guide/how-to/task-queue.md @@ -0,0 +1 @@ +task queue From b3fe85637f3246c9ea0658ba1e7deb50b9d8f822 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:15 +0200 Subject: [PATCH 125/698] New translations task-queue.md (Korean) --- guide/content/ko/guide/how-to/task-queue.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/task-queue.md diff --git a/guide/content/ko/guide/how-to/task-queue.md b/guide/content/ko/guide/how-to/task-queue.md new file mode 100644 index 0000000000..c5ee7c54a3 --- /dev/null +++ b/guide/content/ko/guide/how-to/task-queue.md @@ -0,0 +1 @@ +task queue From 59c476113abf3fbae57ac2c5edfafea81e002ca1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:16 +0200 Subject: [PATCH 126/698] New translations task-queue.md (Chinese Simplified) --- guide/content/zh/guide/how-to/task-queue.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/task-queue.md diff --git a/guide/content/zh/guide/how-to/task-queue.md b/guide/content/zh/guide/how-to/task-queue.md new file mode 100644 index 0000000000..c5ee7c54a3 --- /dev/null +++ b/guide/content/zh/guide/how-to/task-queue.md @@ -0,0 +1 @@ +task queue From b8a46c89fd2620376e29114c8d4fa99aada46feb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:17 +0200 Subject: [PATCH 127/698] New translations tls.md (Japanese) --- guide/content/ja/guide/how-to/tls.md | 199 +++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/ja/guide/how-to/tls.md diff --git a/guide/content/ja/guide/how-to/tls.md b/guide/content/ja/guide/how-to/tls.md new file mode 100644 index 0000000000..5a4859598a --- /dev/null +++ b/guide/content/ja/guide/how-to/tls.md @@ -0,0 +1,199 @@ +--- +title: TLS/SSL/HTTPS +--- + +# TLS/SSL/HTTPS + +> How do I run Sanic via HTTPS? + +If you do not have TLS certificates yet, [see the end of this page](./tls.md#get-certificates-for-your-domain-names). + +## Single domain and single certificate + +.. column:: + +``` +Let Sanic automatically load your certificate files, which need to be named `fullchain.pem` and `privkey.pem` in the given folder: +``` + +.. column:: + +```` +```sh +sudo sanic myserver:app -H :: -p 443 \ + --tls /etc/letsencrypt/live/example.com/ +``` +```python +app.run("::", 443, ssl="/etc/letsencrypt/live/example.com/") +``` +```` + +.. column:: + +``` +Or, you can pass cert and key filenames separately as a dictionary: + +Additionally, `password` may be added if the key is encrypted, all fields except for the password are passed to `request.conn_info.cert`. +``` + +.. column:: + +```` +```python +ssl = { + "cert": "/path/to/fullchain.pem", + "key": "/path/to/privkey.pem", + "password": "for encrypted privkey file", # Optional +} +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```` + +.. column:: + +``` +Alternatively, [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html) may be passed, if you need full control over details such as which crypto algorithms are permitted. By default Sanic only allows secure algorithms, which may restrict access from very old devices. +``` + +.. column:: + +```` +```python +import ssl + +context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) +context.load_cert_chain("certs/fullchain.pem", "certs/privkey.pem") + +app.run(host="0.0.0.0", port=8443, ssl=context) +``` +```` + +## Multiple domains with separate certificates + +.. column:: + +``` +A list of multiple certificates may be provided, in which case Sanic chooses the one matching the hostname the user is connecting to. This occurs so early in the TLS handshake that Sanic has not sent any packets to the client yet. + +If the client sends no SNI (Server Name Indication), the first certificate on the list will be used even though on the client browser it will likely fail with a TLS error due to name mismatch. To prevent this fallback and to cause immediate disconnection of clients without a known hostname, add `None` as the first entry on the list. `--tls-strict-host` is the equivalent CLI option. +``` + +.. column:: + +```` +```python +ssl = ["certs/example.com/", "certs/bigcorp.test/"] +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```sh +sanic myserver:app + --tls certs/example.com/ + --tls certs/bigcorp.test/ + --tls-strict-host +``` +```` + +.. tip:: + +``` +You may also use `None` in front of a single certificate if you do not wish to reveal your certificate, true hostname or site content to anyone connecting to the IP address instead of the proper DNS name. +``` + +.. column:: + +``` +Dictionaries can be used on the list. This allows also specifying which domains a certificate matches to, although the names present on the certificate itself cannot be controlled from here. If names are not specified, the names from the certificate itself are used. + +To only allow connections to the main domain **example.com** and only to subdomains of **bigcorp.test**: +``` + +.. column:: + +```` +```python +ssl = [ + None, # No fallback if names do not match! + { + "cert": "certs/example.com/fullchain.pem", + "key": "certs/example.com/privkey.pem", + "names": ["example.com", "*.bigcorp.test"], + } +] +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```` + +## Accessing TLS information in handlers via `request.conn_info` fields + +- `.ssl` - is the connection secure (bool) +- `.cert` - certificate info and dict fields of the currently active cert (dict) +- `.server_name` - the SNI sent by the client (str, may be empty) + +Do note that all `conn_info` fields are per connection, where there may be many requests over time. If a proxy is used in front of your server, these requests on the same pipe may even come from different users. + +## Redirect HTTP to HTTPS, with certificate requests still over HTTP + +In addition to your normal server(s) running HTTPS, run another server for redirection, `http_redir.py`: + +```python +from sanic import Sanic, exceptions, response + +app = Sanic("http_redir") + +# Serve ACME/certbot files without HTTPS, for certificate renewals +app.static("/.well-known", "/var/www/.well-known", resource_type="dir") + +@app.exception(exceptions.NotFound, exceptions.MethodNotSupported) +def redirect_everything_else(request, exception): + server, path = request.server_name, request.path + if server and path.startswith("/"): + return response.redirect(f"https://{server}{path}", status=308) + return response.text("Bad Request. Please use HTTPS!", status=400) +``` + +It is best to setup this as a systemd unit separate of your HTTPS servers. You may need to run HTTP while initially requesting your certificates, while you cannot run the HTTPS server yet. Start for IPv4 and IPv6: + +``` +sanic http_redir:app -H 0.0.0.0 -p 80 +sanic http_redir:app -H :: -p 80 +``` + +Alternatively, it is possible to run the HTTP redirect application from the main application: + +```python +# app == Your main application +# redirect == Your http_redir application +@app.before_server_start +async def start(app, _): + app.ctx.redirect = await redirect.create_server( + port=80, return_asyncio_server=True + ) + app.add_task(runner(redirect, app.ctx.redirect)) + +@app.before_server_stop +async def stop(app, _): + await app.ctx.redirect.close() + +async def runner(app, app_server): + app.state.is_running = True + try: + app.signalize() + app.finalize() + app.state.is_started = True + await app_server.serve_forever() + finally: + app.state.is_running = False + app.state.is_stopping = True +``` + +## Get certificates for your domain names + +You can get free certificates from [Let's Encrypt](https://letsencrypt.org/). Install [certbot](https://certbot.eff.org/) via your package manager, and request a certificate: + +```sh +sudo certbot certonly --key-type ecdsa --preferred-chain "ISRG Root X1" -d example.com -d www.example.com +``` + +Multiple domain names may be added by further `-d` arguments, all stored into a single certificate which gets saved to `/etc/letsencrypt/live/example.com/` as per **the first domain** that you list here. + +The key type and preferred chain options are necessary for getting a minimal size certificate file, essential for making your server run as _fast_ as possible. The chain will still contain one RSA certificate until when Let's Encrypt gets their new EC chain trusted in all major browsers. From 38414cc3256e8458857240ff6c0e45bd80cbf809 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:18 +0200 Subject: [PATCH 128/698] New translations tls.md (Korean) --- guide/content/ko/guide/how-to/tls.md | 199 +++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/ko/guide/how-to/tls.md diff --git a/guide/content/ko/guide/how-to/tls.md b/guide/content/ko/guide/how-to/tls.md new file mode 100644 index 0000000000..5a4859598a --- /dev/null +++ b/guide/content/ko/guide/how-to/tls.md @@ -0,0 +1,199 @@ +--- +title: TLS/SSL/HTTPS +--- + +# TLS/SSL/HTTPS + +> How do I run Sanic via HTTPS? + +If you do not have TLS certificates yet, [see the end of this page](./tls.md#get-certificates-for-your-domain-names). + +## Single domain and single certificate + +.. column:: + +``` +Let Sanic automatically load your certificate files, which need to be named `fullchain.pem` and `privkey.pem` in the given folder: +``` + +.. column:: + +```` +```sh +sudo sanic myserver:app -H :: -p 443 \ + --tls /etc/letsencrypt/live/example.com/ +``` +```python +app.run("::", 443, ssl="/etc/letsencrypt/live/example.com/") +``` +```` + +.. column:: + +``` +Or, you can pass cert and key filenames separately as a dictionary: + +Additionally, `password` may be added if the key is encrypted, all fields except for the password are passed to `request.conn_info.cert`. +``` + +.. column:: + +```` +```python +ssl = { + "cert": "/path/to/fullchain.pem", + "key": "/path/to/privkey.pem", + "password": "for encrypted privkey file", # Optional +} +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```` + +.. column:: + +``` +Alternatively, [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html) may be passed, if you need full control over details such as which crypto algorithms are permitted. By default Sanic only allows secure algorithms, which may restrict access from very old devices. +``` + +.. column:: + +```` +```python +import ssl + +context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) +context.load_cert_chain("certs/fullchain.pem", "certs/privkey.pem") + +app.run(host="0.0.0.0", port=8443, ssl=context) +``` +```` + +## Multiple domains with separate certificates + +.. column:: + +``` +A list of multiple certificates may be provided, in which case Sanic chooses the one matching the hostname the user is connecting to. This occurs so early in the TLS handshake that Sanic has not sent any packets to the client yet. + +If the client sends no SNI (Server Name Indication), the first certificate on the list will be used even though on the client browser it will likely fail with a TLS error due to name mismatch. To prevent this fallback and to cause immediate disconnection of clients without a known hostname, add `None` as the first entry on the list. `--tls-strict-host` is the equivalent CLI option. +``` + +.. column:: + +```` +```python +ssl = ["certs/example.com/", "certs/bigcorp.test/"] +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```sh +sanic myserver:app + --tls certs/example.com/ + --tls certs/bigcorp.test/ + --tls-strict-host +``` +```` + +.. tip:: + +``` +You may also use `None` in front of a single certificate if you do not wish to reveal your certificate, true hostname or site content to anyone connecting to the IP address instead of the proper DNS name. +``` + +.. column:: + +``` +Dictionaries can be used on the list. This allows also specifying which domains a certificate matches to, although the names present on the certificate itself cannot be controlled from here. If names are not specified, the names from the certificate itself are used. + +To only allow connections to the main domain **example.com** and only to subdomains of **bigcorp.test**: +``` + +.. column:: + +```` +```python +ssl = [ + None, # No fallback if names do not match! + { + "cert": "certs/example.com/fullchain.pem", + "key": "certs/example.com/privkey.pem", + "names": ["example.com", "*.bigcorp.test"], + } +] +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```` + +## Accessing TLS information in handlers via `request.conn_info` fields + +- `.ssl` - is the connection secure (bool) +- `.cert` - certificate info and dict fields of the currently active cert (dict) +- `.server_name` - the SNI sent by the client (str, may be empty) + +Do note that all `conn_info` fields are per connection, where there may be many requests over time. If a proxy is used in front of your server, these requests on the same pipe may even come from different users. + +## Redirect HTTP to HTTPS, with certificate requests still over HTTP + +In addition to your normal server(s) running HTTPS, run another server for redirection, `http_redir.py`: + +```python +from sanic import Sanic, exceptions, response + +app = Sanic("http_redir") + +# Serve ACME/certbot files without HTTPS, for certificate renewals +app.static("/.well-known", "/var/www/.well-known", resource_type="dir") + +@app.exception(exceptions.NotFound, exceptions.MethodNotSupported) +def redirect_everything_else(request, exception): + server, path = request.server_name, request.path + if server and path.startswith("/"): + return response.redirect(f"https://{server}{path}", status=308) + return response.text("Bad Request. Please use HTTPS!", status=400) +``` + +It is best to setup this as a systemd unit separate of your HTTPS servers. You may need to run HTTP while initially requesting your certificates, while you cannot run the HTTPS server yet. Start for IPv4 and IPv6: + +``` +sanic http_redir:app -H 0.0.0.0 -p 80 +sanic http_redir:app -H :: -p 80 +``` + +Alternatively, it is possible to run the HTTP redirect application from the main application: + +```python +# app == Your main application +# redirect == Your http_redir application +@app.before_server_start +async def start(app, _): + app.ctx.redirect = await redirect.create_server( + port=80, return_asyncio_server=True + ) + app.add_task(runner(redirect, app.ctx.redirect)) + +@app.before_server_stop +async def stop(app, _): + await app.ctx.redirect.close() + +async def runner(app, app_server): + app.state.is_running = True + try: + app.signalize() + app.finalize() + app.state.is_started = True + await app_server.serve_forever() + finally: + app.state.is_running = False + app.state.is_stopping = True +``` + +## Get certificates for your domain names + +You can get free certificates from [Let's Encrypt](https://letsencrypt.org/). Install [certbot](https://certbot.eff.org/) via your package manager, and request a certificate: + +```sh +sudo certbot certonly --key-type ecdsa --preferred-chain "ISRG Root X1" -d example.com -d www.example.com +``` + +Multiple domain names may be added by further `-d` arguments, all stored into a single certificate which gets saved to `/etc/letsencrypt/live/example.com/` as per **the first domain** that you list here. + +The key type and preferred chain options are necessary for getting a minimal size certificate file, essential for making your server run as _fast_ as possible. The chain will still contain one RSA certificate until when Let's Encrypt gets their new EC chain trusted in all major browsers. From d967b1c614af37e602108815eecd029d399009aa Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:19 +0200 Subject: [PATCH 129/698] New translations tls.md (Chinese Simplified) --- guide/content/zh/guide/how-to/tls.md | 199 +++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/zh/guide/how-to/tls.md diff --git a/guide/content/zh/guide/how-to/tls.md b/guide/content/zh/guide/how-to/tls.md new file mode 100644 index 0000000000..5a4859598a --- /dev/null +++ b/guide/content/zh/guide/how-to/tls.md @@ -0,0 +1,199 @@ +--- +title: TLS/SSL/HTTPS +--- + +# TLS/SSL/HTTPS + +> How do I run Sanic via HTTPS? + +If you do not have TLS certificates yet, [see the end of this page](./tls.md#get-certificates-for-your-domain-names). + +## Single domain and single certificate + +.. column:: + +``` +Let Sanic automatically load your certificate files, which need to be named `fullchain.pem` and `privkey.pem` in the given folder: +``` + +.. column:: + +```` +```sh +sudo sanic myserver:app -H :: -p 443 \ + --tls /etc/letsencrypt/live/example.com/ +``` +```python +app.run("::", 443, ssl="/etc/letsencrypt/live/example.com/") +``` +```` + +.. column:: + +``` +Or, you can pass cert and key filenames separately as a dictionary: + +Additionally, `password` may be added if the key is encrypted, all fields except for the password are passed to `request.conn_info.cert`. +``` + +.. column:: + +```` +```python +ssl = { + "cert": "/path/to/fullchain.pem", + "key": "/path/to/privkey.pem", + "password": "for encrypted privkey file", # Optional +} +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```` + +.. column:: + +``` +Alternatively, [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html) may be passed, if you need full control over details such as which crypto algorithms are permitted. By default Sanic only allows secure algorithms, which may restrict access from very old devices. +``` + +.. column:: + +```` +```python +import ssl + +context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) +context.load_cert_chain("certs/fullchain.pem", "certs/privkey.pem") + +app.run(host="0.0.0.0", port=8443, ssl=context) +``` +```` + +## Multiple domains with separate certificates + +.. column:: + +``` +A list of multiple certificates may be provided, in which case Sanic chooses the one matching the hostname the user is connecting to. This occurs so early in the TLS handshake that Sanic has not sent any packets to the client yet. + +If the client sends no SNI (Server Name Indication), the first certificate on the list will be used even though on the client browser it will likely fail with a TLS error due to name mismatch. To prevent this fallback and to cause immediate disconnection of clients without a known hostname, add `None` as the first entry on the list. `--tls-strict-host` is the equivalent CLI option. +``` + +.. column:: + +```` +```python +ssl = ["certs/example.com/", "certs/bigcorp.test/"] +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```sh +sanic myserver:app + --tls certs/example.com/ + --tls certs/bigcorp.test/ + --tls-strict-host +``` +```` + +.. tip:: + +``` +You may also use `None` in front of a single certificate if you do not wish to reveal your certificate, true hostname or site content to anyone connecting to the IP address instead of the proper DNS name. +``` + +.. column:: + +``` +Dictionaries can be used on the list. This allows also specifying which domains a certificate matches to, although the names present on the certificate itself cannot be controlled from here. If names are not specified, the names from the certificate itself are used. + +To only allow connections to the main domain **example.com** and only to subdomains of **bigcorp.test**: +``` + +.. column:: + +```` +```python +ssl = [ + None, # No fallback if names do not match! + { + "cert": "certs/example.com/fullchain.pem", + "key": "certs/example.com/privkey.pem", + "names": ["example.com", "*.bigcorp.test"], + } +] +app.run(host="0.0.0.0", port=8443, ssl=ssl) +``` +```` + +## Accessing TLS information in handlers via `request.conn_info` fields + +- `.ssl` - is the connection secure (bool) +- `.cert` - certificate info and dict fields of the currently active cert (dict) +- `.server_name` - the SNI sent by the client (str, may be empty) + +Do note that all `conn_info` fields are per connection, where there may be many requests over time. If a proxy is used in front of your server, these requests on the same pipe may even come from different users. + +## Redirect HTTP to HTTPS, with certificate requests still over HTTP + +In addition to your normal server(s) running HTTPS, run another server for redirection, `http_redir.py`: + +```python +from sanic import Sanic, exceptions, response + +app = Sanic("http_redir") + +# Serve ACME/certbot files without HTTPS, for certificate renewals +app.static("/.well-known", "/var/www/.well-known", resource_type="dir") + +@app.exception(exceptions.NotFound, exceptions.MethodNotSupported) +def redirect_everything_else(request, exception): + server, path = request.server_name, request.path + if server and path.startswith("/"): + return response.redirect(f"https://{server}{path}", status=308) + return response.text("Bad Request. Please use HTTPS!", status=400) +``` + +It is best to setup this as a systemd unit separate of your HTTPS servers. You may need to run HTTP while initially requesting your certificates, while you cannot run the HTTPS server yet. Start for IPv4 and IPv6: + +``` +sanic http_redir:app -H 0.0.0.0 -p 80 +sanic http_redir:app -H :: -p 80 +``` + +Alternatively, it is possible to run the HTTP redirect application from the main application: + +```python +# app == Your main application +# redirect == Your http_redir application +@app.before_server_start +async def start(app, _): + app.ctx.redirect = await redirect.create_server( + port=80, return_asyncio_server=True + ) + app.add_task(runner(redirect, app.ctx.redirect)) + +@app.before_server_stop +async def stop(app, _): + await app.ctx.redirect.close() + +async def runner(app, app_server): + app.state.is_running = True + try: + app.signalize() + app.finalize() + app.state.is_started = True + await app_server.serve_forever() + finally: + app.state.is_running = False + app.state.is_stopping = True +``` + +## Get certificates for your domain names + +You can get free certificates from [Let's Encrypt](https://letsencrypt.org/). Install [certbot](https://certbot.eff.org/) via your package manager, and request a certificate: + +```sh +sudo certbot certonly --key-type ecdsa --preferred-chain "ISRG Root X1" -d example.com -d www.example.com +``` + +Multiple domain names may be added by further `-d` arguments, all stored into a single certificate which gets saved to `/etc/letsencrypt/live/example.com/` as per **the first domain** that you list here. + +The key type and preferred chain options are necessary for getting a minimal size certificate file, essential for making your server run as _fast_ as possible. The chain will still contain one RSA certificate until when Let's Encrypt gets their new EC chain trusted in all major browsers. From cacddf8952f2c98e5d0fa3741525479b08ac6e14 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:20 +0200 Subject: [PATCH 130/698] New translations validation.md (Japanese) --- guide/content/ja/guide/how-to/validation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/validation.md diff --git a/guide/content/ja/guide/how-to/validation.md b/guide/content/ja/guide/how-to/validation.md new file mode 100644 index 0000000000..d45b2dea4c --- /dev/null +++ b/guide/content/ja/guide/how-to/validation.md @@ -0,0 +1 @@ +validation From 54c6fe7429ac9bd7d80d18b38fb46d62fc103810 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:21 +0200 Subject: [PATCH 131/698] New translations validation.md (Korean) --- guide/content/ko/guide/how-to/validation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/validation.md diff --git a/guide/content/ko/guide/how-to/validation.md b/guide/content/ko/guide/how-to/validation.md new file mode 100644 index 0000000000..d45b2dea4c --- /dev/null +++ b/guide/content/ko/guide/how-to/validation.md @@ -0,0 +1 @@ +validation From 3bd9cb25d272fc627717cf58c6a8cdf80094eb9d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:22 +0200 Subject: [PATCH 132/698] New translations validation.md (Chinese Simplified) --- guide/content/zh/guide/how-to/validation.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/validation.md diff --git a/guide/content/zh/guide/how-to/validation.md b/guide/content/zh/guide/how-to/validation.md new file mode 100644 index 0000000000..d45b2dea4c --- /dev/null +++ b/guide/content/zh/guide/how-to/validation.md @@ -0,0 +1 @@ +validation From d9e6c7e7e9bf1e6b8d02ae3f06623fdac655996e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:22 +0200 Subject: [PATCH 133/698] New translations websocket-feed.md (Japanese) --- guide/content/ja/guide/how-to/websocket-feed.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ja/guide/how-to/websocket-feed.md diff --git a/guide/content/ja/guide/how-to/websocket-feed.md b/guide/content/ja/guide/how-to/websocket-feed.md new file mode 100644 index 0000000000..ae2abc2def --- /dev/null +++ b/guide/content/ja/guide/how-to/websocket-feed.md @@ -0,0 +1 @@ +websocket feed From ec0aa9072df38b2e046c699233705367d7722618 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:24 +0200 Subject: [PATCH 134/698] New translations websocket-feed.md (Korean) --- guide/content/ko/guide/how-to/websocket-feed.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/ko/guide/how-to/websocket-feed.md diff --git a/guide/content/ko/guide/how-to/websocket-feed.md b/guide/content/ko/guide/how-to/websocket-feed.md new file mode 100644 index 0000000000..ae2abc2def --- /dev/null +++ b/guide/content/ko/guide/how-to/websocket-feed.md @@ -0,0 +1 @@ +websocket feed From 5724a9ab814fa8e1cc564525f6db29221b31d7f8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:24 +0200 Subject: [PATCH 135/698] New translations websocket-feed.md (Chinese Simplified) --- guide/content/zh/guide/how-to/websocket-feed.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 guide/content/zh/guide/how-to/websocket-feed.md diff --git a/guide/content/zh/guide/how-to/websocket-feed.md b/guide/content/zh/guide/how-to/websocket-feed.md new file mode 100644 index 0000000000..ae2abc2def --- /dev/null +++ b/guide/content/zh/guide/how-to/websocket-feed.md @@ -0,0 +1 @@ +websocket feed From d86ffdab68cfdd80a6fb5d2514ab4aca9dd24d7b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:25 +0200 Subject: [PATCH 136/698] New translations introduction.md (Japanese) --- guide/content/ja/guide/introduction.md | 71 ++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 guide/content/ja/guide/introduction.md diff --git a/guide/content/ja/guide/introduction.md b/guide/content/ja/guide/introduction.md new file mode 100644 index 0000000000..2e0b730f54 --- /dev/null +++ b/guide/content/ja/guide/introduction.md @@ -0,0 +1,71 @@ +# Introduction + +Sanic is a Python 3.8+ web server and web framework that’s written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy. + +.. attrs:: +:class: introduction-table + +``` +| | | +|--|--| +| Build | [![Tests](https://github.com/sanic-org/sanic/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/sanic-org/sanic/actions/workflows/tests.yml) | +| Docs | [![User Guide](https://img.shields.io/badge/user%20guide-sanic-ff0068)](https://sanicframework.org/) [![Documentation](https://readthedocs.org/projects/sanic/badge/?version=latest)](http://sanic.readthedocs.io/en/latest/?badge=latest) | +| Package | [![PyPI](https://img.shields.io/pypi/v/sanic.svg)](https://pypi.python.org/pypi/sanic/) [![PyPI version](https://img.shields.io/pypi/pyversions/sanic.svg)](https://pypi.python.org/pypi/sanic/) [![Wheel](https://img.shields.io/pypi/wheel/sanic.svg)](https://pypi.python.org/pypi/sanic) [![Supported implementations](https://img.shields.io/pypi/implementation/sanic.svg)](https://pypi.python.org/pypi/sanic) [![Code style black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) | +| Support | [![Forums](https://img.shields.io/badge/forums-community-ff0068.svg)](https://community.sanicframework.org/) [![Discord](https://img.shields.io/discord/812221182594121728?logo=discord)](https://discord.gg/FARQzAEMAA) [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/mekicha/awesome-sanic) | +| Stats | [![Monthly Downloads](https://img.shields.io/pypi/dm/sanic.svg)](https://pepy.tech/project/sanic) [![Weekly Downloads](https://img.shields.io/pypi/dw/sanic.svg)](https://pepy.tech/project/sanic) [![Conda downloads](https://img.shields.io/conda/dn/conda-forge/sanic.svg)](https://anaconda.org/conda-forge/sanic) | +``` + +## What is it? + +First things first, before you jump in the water, you should know that Sanic is different than other frameworks. + +Right there in that first sentence there is a huge mistake because Sanic is _both_ a **framework** and a **web server**. In the deployment section we will talk a little bit more about this. + +But, remember, out of the box Sanic comes with everything you need to write, deploy, and scale a production grade web application. 🚀 + +## Goal + +> To provide a simple way to get up and running a highly performant HTTP server that is easy to build, to expand, and ultimately to scale. + +## Features + +.. column:: + +``` +### Core + +- Built in, **_fast_** web server +- Production ready +- Highly scalable +- ASGI compliant +- Simple and intuitive API design +- By the community, for the community +``` + +.. column:: + +``` +### Sanic Extensions [[learn more](../plugins/sanic-ext/getting-started.md)] + +- CORS protection +- Template rendering with Jinja +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Predefined, endpoint-specific response serializers +- Request query arguments and body input validation +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +``` + +## Sponsor + +Check out [open collective](https://opencollective.com/sanic-org) to learn more about helping to fund Sanic. + +## Join the Community + +The main channel for discussion is at the [community forums](https://community.sanicframework.org/). There also is a [Discord Server](https://discord.gg/FARQzAEMAA) for live discussion and chat. + +The Stackoverflow `[sanic]` tag is [actively monitored](https://stackoverflow.com/questions/tagged/sanic) by project maintainers. + +## Contribution + +We are always happy to have new contributions. We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). Please take a look at our [Contribution guidelines](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst). From e627704f08ba3d59a92c6eb9705a153b658f401b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:26 +0200 Subject: [PATCH 137/698] New translations introduction.md (Korean) --- guide/content/ko/guide/introduction.md | 71 ++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 guide/content/ko/guide/introduction.md diff --git a/guide/content/ko/guide/introduction.md b/guide/content/ko/guide/introduction.md new file mode 100644 index 0000000000..2e0b730f54 --- /dev/null +++ b/guide/content/ko/guide/introduction.md @@ -0,0 +1,71 @@ +# Introduction + +Sanic is a Python 3.8+ web server and web framework that’s written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy. + +.. attrs:: +:class: introduction-table + +``` +| | | +|--|--| +| Build | [![Tests](https://github.com/sanic-org/sanic/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/sanic-org/sanic/actions/workflows/tests.yml) | +| Docs | [![User Guide](https://img.shields.io/badge/user%20guide-sanic-ff0068)](https://sanicframework.org/) [![Documentation](https://readthedocs.org/projects/sanic/badge/?version=latest)](http://sanic.readthedocs.io/en/latest/?badge=latest) | +| Package | [![PyPI](https://img.shields.io/pypi/v/sanic.svg)](https://pypi.python.org/pypi/sanic/) [![PyPI version](https://img.shields.io/pypi/pyversions/sanic.svg)](https://pypi.python.org/pypi/sanic/) [![Wheel](https://img.shields.io/pypi/wheel/sanic.svg)](https://pypi.python.org/pypi/sanic) [![Supported implementations](https://img.shields.io/pypi/implementation/sanic.svg)](https://pypi.python.org/pypi/sanic) [![Code style black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) | +| Support | [![Forums](https://img.shields.io/badge/forums-community-ff0068.svg)](https://community.sanicframework.org/) [![Discord](https://img.shields.io/discord/812221182594121728?logo=discord)](https://discord.gg/FARQzAEMAA) [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/mekicha/awesome-sanic) | +| Stats | [![Monthly Downloads](https://img.shields.io/pypi/dm/sanic.svg)](https://pepy.tech/project/sanic) [![Weekly Downloads](https://img.shields.io/pypi/dw/sanic.svg)](https://pepy.tech/project/sanic) [![Conda downloads](https://img.shields.io/conda/dn/conda-forge/sanic.svg)](https://anaconda.org/conda-forge/sanic) | +``` + +## What is it? + +First things first, before you jump in the water, you should know that Sanic is different than other frameworks. + +Right there in that first sentence there is a huge mistake because Sanic is _both_ a **framework** and a **web server**. In the deployment section we will talk a little bit more about this. + +But, remember, out of the box Sanic comes with everything you need to write, deploy, and scale a production grade web application. 🚀 + +## Goal + +> To provide a simple way to get up and running a highly performant HTTP server that is easy to build, to expand, and ultimately to scale. + +## Features + +.. column:: + +``` +### Core + +- Built in, **_fast_** web server +- Production ready +- Highly scalable +- ASGI compliant +- Simple and intuitive API design +- By the community, for the community +``` + +.. column:: + +``` +### Sanic Extensions [[learn more](../plugins/sanic-ext/getting-started.md)] + +- CORS protection +- Template rendering with Jinja +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Predefined, endpoint-specific response serializers +- Request query arguments and body input validation +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +``` + +## Sponsor + +Check out [open collective](https://opencollective.com/sanic-org) to learn more about helping to fund Sanic. + +## Join the Community + +The main channel for discussion is at the [community forums](https://community.sanicframework.org/). There also is a [Discord Server](https://discord.gg/FARQzAEMAA) for live discussion and chat. + +The Stackoverflow `[sanic]` tag is [actively monitored](https://stackoverflow.com/questions/tagged/sanic) by project maintainers. + +## Contribution + +We are always happy to have new contributions. We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). Please take a look at our [Contribution guidelines](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst). From d3e6eaf274a8eefac9b9804bd3291b0eabc24589 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:27 +0200 Subject: [PATCH 138/698] New translations introduction.md (Chinese Simplified) --- guide/content/zh/guide/introduction.md | 71 ++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 guide/content/zh/guide/introduction.md diff --git a/guide/content/zh/guide/introduction.md b/guide/content/zh/guide/introduction.md new file mode 100644 index 0000000000..2e0b730f54 --- /dev/null +++ b/guide/content/zh/guide/introduction.md @@ -0,0 +1,71 @@ +# Introduction + +Sanic is a Python 3.8+ web server and web framework that’s written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy. + +.. attrs:: +:class: introduction-table + +``` +| | | +|--|--| +| Build | [![Tests](https://github.com/sanic-org/sanic/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/sanic-org/sanic/actions/workflows/tests.yml) | +| Docs | [![User Guide](https://img.shields.io/badge/user%20guide-sanic-ff0068)](https://sanicframework.org/) [![Documentation](https://readthedocs.org/projects/sanic/badge/?version=latest)](http://sanic.readthedocs.io/en/latest/?badge=latest) | +| Package | [![PyPI](https://img.shields.io/pypi/v/sanic.svg)](https://pypi.python.org/pypi/sanic/) [![PyPI version](https://img.shields.io/pypi/pyversions/sanic.svg)](https://pypi.python.org/pypi/sanic/) [![Wheel](https://img.shields.io/pypi/wheel/sanic.svg)](https://pypi.python.org/pypi/sanic) [![Supported implementations](https://img.shields.io/pypi/implementation/sanic.svg)](https://pypi.python.org/pypi/sanic) [![Code style black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black) | +| Support | [![Forums](https://img.shields.io/badge/forums-community-ff0068.svg)](https://community.sanicframework.org/) [![Discord](https://img.shields.io/discord/812221182594121728?logo=discord)](https://discord.gg/FARQzAEMAA) [![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/mekicha/awesome-sanic) | +| Stats | [![Monthly Downloads](https://img.shields.io/pypi/dm/sanic.svg)](https://pepy.tech/project/sanic) [![Weekly Downloads](https://img.shields.io/pypi/dw/sanic.svg)](https://pepy.tech/project/sanic) [![Conda downloads](https://img.shields.io/conda/dn/conda-forge/sanic.svg)](https://anaconda.org/conda-forge/sanic) | +``` + +## What is it? + +First things first, before you jump in the water, you should know that Sanic is different than other frameworks. + +Right there in that first sentence there is a huge mistake because Sanic is _both_ a **framework** and a **web server**. In the deployment section we will talk a little bit more about this. + +But, remember, out of the box Sanic comes with everything you need to write, deploy, and scale a production grade web application. 🚀 + +## Goal + +> To provide a simple way to get up and running a highly performant HTTP server that is easy to build, to expand, and ultimately to scale. + +## Features + +.. column:: + +``` +### Core + +- Built in, **_fast_** web server +- Production ready +- Highly scalable +- ASGI compliant +- Simple and intuitive API design +- By the community, for the community +``` + +.. column:: + +``` +### Sanic Extensions [[learn more](../plugins/sanic-ext/getting-started.md)] + +- CORS protection +- Template rendering with Jinja +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Predefined, endpoint-specific response serializers +- Request query arguments and body input validation +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +``` + +## Sponsor + +Check out [open collective](https://opencollective.com/sanic-org) to learn more about helping to fund Sanic. + +## Join the Community + +The main channel for discussion is at the [community forums](https://community.sanicframework.org/). There also is a [Discord Server](https://discord.gg/FARQzAEMAA) for live discussion and chat. + +The Stackoverflow `[sanic]` tag is [actively monitored](https://stackoverflow.com/questions/tagged/sanic) by project maintainers. + +## Contribution + +We are always happy to have new contributions. We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). Please take a look at our [Contribution guidelines](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst). From 1f613f3dd03d21ab2146080d8e3621829841db3f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:28 +0200 Subject: [PATCH 139/698] New translations app-loader.md (Japanese) --- guide/content/ja/guide/running/app-loader.md | 98 ++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 guide/content/ja/guide/running/app-loader.md diff --git a/guide/content/ja/guide/running/app-loader.md b/guide/content/ja/guide/running/app-loader.md new file mode 100644 index 0000000000..03f13e7ec7 --- /dev/null +++ b/guide/content/ja/guide/running/app-loader.md @@ -0,0 +1,98 @@ +--- +title: Dynamic Applications +--- + +# Dynamic Applications + +Running Sanic has been optimized to work with the CLI. If you have not read it yet, you should read [Running Sanic](./running.md#sanic-server) to become familiar with the options. + +.. column:: + +``` +This includes running it as a global scope object... +``` + +.. column:: + +```` +```sh +sanic path.to.server:app +``` +```python +# server.py +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + return json({"foo": "bar"}) +``` +```` + +.. column:: + +``` +...or, a factory function that creates the `Sanic` application object. +``` + +.. column:: + +```` +```sh +sanic path.to.server:create_app --factory +``` +```python +# server.py +def create_app(): + app = Sanic("TestApp") + + @app.get("/") + async def handler(request: Request): + return json({"foo": "bar"}) + + return app +``` +```` + +**Sometimes, this is not enough ... 🤔** + +Introduced in [v22.9](../release-notes/v22.9.md), Sanic has an `AppLoader` object that is responsible for creating an application in the various [worker processes](./manager.md#how-sanic-server-starts-processes). You can take advantage of this if you need to create a more dynamic startup experience for your application. + +.. column:: + +``` +An `AppLoader` can be passed a callable that returns a `Sanic` instance. That `AppLoader` could be used with the low-level application running API. +``` + +.. column:: + +```` +```python +import sys +from functools import partial + +from sanic import Request, Sanic, json +from sanic.worker.loader import AppLoader + +def attach_endpoints(app: Sanic): + @app.get("/") + async def handler(request: Request): + return json({"app_name": request.app.name}) + +def create_app(app_name: str) -> Sanic: + app = Sanic(app_name) + attach_endpoints(app) + return app + +if __name__ == "__main__": + app_name = sys.argv[-1] + loader = AppLoader(factory=partial(create_app, app_name)) + app = loader.load() + app.prepare(port=9999, dev=True) + Sanic.serve(primary=app, app_loader=loader) +``` +```sh +python path/to/server.py MyTestAppName +``` +```` + +In the above example, the `AppLoader` is created with a `factory` that can be used to create copies of the same application across processes. When doing this, you should explicitly use the `Sanic.serve` pattern shown above so that the `AppLoader` that you create is not replaced. From e9d00899938f93f9ea3d7eee2c70c17179e84131 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:29 +0200 Subject: [PATCH 140/698] New translations app-loader.md (Korean) --- guide/content/ko/guide/running/app-loader.md | 98 ++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 guide/content/ko/guide/running/app-loader.md diff --git a/guide/content/ko/guide/running/app-loader.md b/guide/content/ko/guide/running/app-loader.md new file mode 100644 index 0000000000..03f13e7ec7 --- /dev/null +++ b/guide/content/ko/guide/running/app-loader.md @@ -0,0 +1,98 @@ +--- +title: Dynamic Applications +--- + +# Dynamic Applications + +Running Sanic has been optimized to work with the CLI. If you have not read it yet, you should read [Running Sanic](./running.md#sanic-server) to become familiar with the options. + +.. column:: + +``` +This includes running it as a global scope object... +``` + +.. column:: + +```` +```sh +sanic path.to.server:app +``` +```python +# server.py +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + return json({"foo": "bar"}) +``` +```` + +.. column:: + +``` +...or, a factory function that creates the `Sanic` application object. +``` + +.. column:: + +```` +```sh +sanic path.to.server:create_app --factory +``` +```python +# server.py +def create_app(): + app = Sanic("TestApp") + + @app.get("/") + async def handler(request: Request): + return json({"foo": "bar"}) + + return app +``` +```` + +**Sometimes, this is not enough ... 🤔** + +Introduced in [v22.9](../release-notes/v22.9.md), Sanic has an `AppLoader` object that is responsible for creating an application in the various [worker processes](./manager.md#how-sanic-server-starts-processes). You can take advantage of this if you need to create a more dynamic startup experience for your application. + +.. column:: + +``` +An `AppLoader` can be passed a callable that returns a `Sanic` instance. That `AppLoader` could be used with the low-level application running API. +``` + +.. column:: + +```` +```python +import sys +from functools import partial + +from sanic import Request, Sanic, json +from sanic.worker.loader import AppLoader + +def attach_endpoints(app: Sanic): + @app.get("/") + async def handler(request: Request): + return json({"app_name": request.app.name}) + +def create_app(app_name: str) -> Sanic: + app = Sanic(app_name) + attach_endpoints(app) + return app + +if __name__ == "__main__": + app_name = sys.argv[-1] + loader = AppLoader(factory=partial(create_app, app_name)) + app = loader.load() + app.prepare(port=9999, dev=True) + Sanic.serve(primary=app, app_loader=loader) +``` +```sh +python path/to/server.py MyTestAppName +``` +```` + +In the above example, the `AppLoader` is created with a `factory` that can be used to create copies of the same application across processes. When doing this, you should explicitly use the `Sanic.serve` pattern shown above so that the `AppLoader` that you create is not replaced. From 54865403a7653ee022f4665a85437205dcf7c645 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:30 +0200 Subject: [PATCH 141/698] New translations app-loader.md (Chinese Simplified) --- guide/content/zh/guide/running/app-loader.md | 98 ++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 guide/content/zh/guide/running/app-loader.md diff --git a/guide/content/zh/guide/running/app-loader.md b/guide/content/zh/guide/running/app-loader.md new file mode 100644 index 0000000000..03f13e7ec7 --- /dev/null +++ b/guide/content/zh/guide/running/app-loader.md @@ -0,0 +1,98 @@ +--- +title: Dynamic Applications +--- + +# Dynamic Applications + +Running Sanic has been optimized to work with the CLI. If you have not read it yet, you should read [Running Sanic](./running.md#sanic-server) to become familiar with the options. + +.. column:: + +``` +This includes running it as a global scope object... +``` + +.. column:: + +```` +```sh +sanic path.to.server:app +``` +```python +# server.py +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + return json({"foo": "bar"}) +``` +```` + +.. column:: + +``` +...or, a factory function that creates the `Sanic` application object. +``` + +.. column:: + +```` +```sh +sanic path.to.server:create_app --factory +``` +```python +# server.py +def create_app(): + app = Sanic("TestApp") + + @app.get("/") + async def handler(request: Request): + return json({"foo": "bar"}) + + return app +``` +```` + +**Sometimes, this is not enough ... 🤔** + +Introduced in [v22.9](../release-notes/v22.9.md), Sanic has an `AppLoader` object that is responsible for creating an application in the various [worker processes](./manager.md#how-sanic-server-starts-processes). You can take advantage of this if you need to create a more dynamic startup experience for your application. + +.. column:: + +``` +An `AppLoader` can be passed a callable that returns a `Sanic` instance. That `AppLoader` could be used with the low-level application running API. +``` + +.. column:: + +```` +```python +import sys +from functools import partial + +from sanic import Request, Sanic, json +from sanic.worker.loader import AppLoader + +def attach_endpoints(app: Sanic): + @app.get("/") + async def handler(request: Request): + return json({"app_name": request.app.name}) + +def create_app(app_name: str) -> Sanic: + app = Sanic(app_name) + attach_endpoints(app) + return app + +if __name__ == "__main__": + app_name = sys.argv[-1] + loader = AppLoader(factory=partial(create_app, app_name)) + app = loader.load() + app.prepare(port=9999, dev=True) + Sanic.serve(primary=app, app_loader=loader) +``` +```sh +python path/to/server.py MyTestAppName +``` +```` + +In the above example, the `AppLoader` is created with a `factory` that can be used to create copies of the same application across processes. When doing this, you should explicitly use the `Sanic.serve` pattern shown above so that the `AppLoader` that you create is not replaced. From 62e57efe6982e4faba1d888b6dcde51cea194d8d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:32 +0200 Subject: [PATCH 142/698] New translations configuration.md (Japanese) --- .../content/ja/guide/running/configuration.md | 328 ++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 guide/content/ja/guide/running/configuration.md diff --git a/guide/content/ja/guide/running/configuration.md b/guide/content/ja/guide/running/configuration.md new file mode 100644 index 0000000000..89dacd7f7a --- /dev/null +++ b/guide/content/ja/guide/running/configuration.md @@ -0,0 +1,328 @@ +# Configuration + +## Basics + +.. column:: + +``` +Sanic holds the configuration in the config attribute of the application object. The configuration object is merely an object that can be modified either using dot-notation or like a dictionary. +``` + +.. column:: + +```` +```python +app = Sanic("myapp") +app.config.DB_NAME = "appdb" +app.config["DB_USER"] = "appuser" +``` +```` + +.. column:: + +``` +You can also use the `update()` method like on regular dictionaries. +``` + +.. column:: + +```` +```python +db_settings = { + 'DB_HOST': 'localhost', + 'DB_NAME': 'appdb', + 'DB_USER': 'appuser' +} +app.config.update(db_settings) +``` +```` + +.. note:: + +``` +It is standard practice in Sanic to name your config values in **uppercase letters**. Indeed, you may experience weird behaviors if you start mixing uppercase and lowercase names. +``` + +## Loading + +### Environment variables + +.. column:: + +``` +Any environment variables defined with the `SANIC_` prefix will be applied to the Sanic config. For example, setting `SANIC_REQUEST_TIMEOUT` will be loaded by the application automatically and fed into the `REQUEST_TIMEOUT` config variable. +``` + +.. column:: + +```` +```bash +$ export SANIC_REQUEST_TIMEOUT=10 +``` +```python +>>> print(app.config.REQUEST_TIMEOUT) +10 +``` +```` + +.. column:: + +``` +You can change the prefix that Sanic is expecting at startup. +``` + +.. column:: + +```` +```bash +$ export MYAPP_REQUEST_TIMEOUT=10 +``` +```python +>>> app = Sanic(__name__, env_prefix='MYAPP_') +>>> print(app.config.REQUEST_TIMEOUT) +10 +``` +```` + +.. column:: + +``` +You can also disable environment variable loading completely. +``` + +.. column:: + +```` +```python +app = Sanic(__name__, load_env=False) +``` +```` + +### Using Sanic.update_config + +The `Sanic` instance has a _very_ versatile method for loading config: `app.update_config`. You can feed it a path to a file, a dictionary, a class, or just about any other sort of object. + +#### From a file + +.. column:: + +``` +Let's say you have `my_config.py` file that looks like this. +``` + +.. column:: + +```` +```python +# my_config.py +A = 1 +B = 2 +``` +```` + +.. column:: + +``` +You can load this as config values by passing its path to `app.update_config`. +``` + +.. column:: + +```` +```python +>>> app.update_config("/path/to/my_config.py") +>>> print(app.config.A) +1 +``` +```` + +.. column:: + +``` +This path also accepts bash style environment variables. +``` + +.. column:: + +```` +```bash +$ export my_path="/path/to" +``` +```python +app.update_config("${my_path}/my_config.py") +``` +```` + +.. note:: + +``` +Just remember that you have to provide environment variables in the format `${environment_variable}` and that `$environment_variable` is not expanded (is treated as "plain" text). +``` + +#### From a dict + +.. column:: + +``` +The `app.update_config` method also works on plain dictionaries. +``` + +.. column:: + +```` +```python +app.update_config({"A": 1, "B": 2}) +``` +```` + +#### From a class or object + +.. column:: + +``` +You can define your own config class, and pass it to `app.update_config` +``` + +.. column:: + +```` +```python +class MyConfig: + A = 1 + B = 2 + +app.update_config(MyConfig) +``` +```` + +.. column:: + +``` +It even could be instantiated. +``` + +.. column:: + +```` +```python +app.update_config(MyConfig()) +``` +```` + +### Type casting + +When loading from environment variables, Sanic will attempt to cast the values to expected Python types. This particularly applies to: + +- `int` +- `float` +- `bool` + +In regards to `bool`, the following _case insensitive_ values are allowed: + +- **`True`**: `y`, `yes`, `yep`, `yup`, `t`, `true`, `on`, `enable`, `enabled`, `1` +- **`False`**: `n`, `no`, `f`, `false`, `off`, `disable`, `disabled`, `0` + +If a value cannot be cast, it will default to a `str`. + +.. column:: + +``` +Additionally, Sanic can be configured to cast additional types using additional type converters. This should be any callable that returns the value or raises a `ValueError`. + +*Added in v21.12* +``` + +.. column:: + +```` +```python +app = Sanic(..., config=Config(converters=[UUID])) +``` +```` + +## Builtin values + +| **Variable** | **Default** | **Description** | +| -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| ACCESS_LOG | True | Disable or enable access log | +| AUTO_EXTEND | True | Control whether [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) will load if it is in the existing virtual environment | +| AUTO_RELOAD | True | Control whether the application will automatically reload when a file changes | +| EVENT_AUTOREGISTER | True | When `True` using the `app.event()` method on a non-existing signal will automatically create it and not raise an exception | +| FALLBACK_ERROR_FORMAT | html | Format of error response if an exception is not caught and handled | +| FORWARDED_FOR_HEADER | X-Forwarded-For | The name of "X-Forwarded-For" HTTP header that contains client and proxy ip | +| FORWARDED_SECRET | None | Used to securely identify a specific proxy server (see below) | +| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | How long to wait to force close non-idle connection (sec) | +| INSPECTOR | False | Whether to enable the Inspector | +| INSPECTOR_HOST | localhost | The host for the Inspector | +| INSPECTOR_PORT | 6457 | The port for the Inspector | +| INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | +| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | +| INSPECTOR_API_KEY | - | The API key for the Inspector | +| KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | +| KEEP_ALIVE | True | Disables keep-alive when False | +| MOTD | True | Whether to display the MOTD (message of the day) at startup | +| MOTD_DISPLAY | {} | Key/value pairs to display additional, arbitrary data in the MOTD | +| NOISY_EXCEPTIONS | False | Force all `quiet` exceptions to be logged | +| PROXIES_COUNT | None | The number of proxy servers in front of the app (e.g. nginx; see below) | +| REAL_IP_HEADER | None | The name of "X-Real-IP" HTTP header that contains real client ip | +| REGISTER | True | Whether the app registry should be enabled | +| REQUEST_BUFFER_SIZE | 65536 | Request buffer size before request is paused, default is 64 Kib | +| REQUEST_ID_HEADER | X-Request-ID | The name of "X-Request-ID" HTTP header that contains request/correlation ID | +| REQUEST_MAX_SIZE | 100000000 | How big a request may be (bytes), default is 100 megabytes | +| REQUEST_MAX_HEADER_SIZE | 8192 | How big a request header may be (bytes), default is 8192 bytes | +| REQUEST_TIMEOUT | 60 | How long a request can take to arrive (sec) | +| RESPONSE_TIMEOUT | 60 | How long a response can take to process (sec) | +| USE_UVLOOP | True | Whether to override the loop policy to use `uvloop`. Supported only with `app.run`. | +| WEBSOCKET_MAX_SIZE | 2^20 | Maximum size for incoming messages (bytes) | +| WEBSOCKET_PING_INTERVAL | 20 | A Ping frame is sent every ping_interval seconds. | +| WEBSOCKET_PING_TIMEOUT | 20 | Connection is closed when Pong is not received after ping_timeout seconds | + +.. tip:: FYI + +``` +- The `USE_UVLOOP` value will be ignored if running with Gunicorn. Defaults to `False` on non-supported platforms (Windows). +- The `WEBSOCKET_` values will be ignored if in ASGI mode. +- v21.12 added: `AUTO_EXTEND`, `MOTD`, `MOTD_DISPLAY`, `NOISY_EXCEPTIONS` +- v22.9 added: `INSPECTOR` +- v22.12 added: `INSPECTOR_HOST`, `INSPECTOR_PORT`, `INSPECTOR_TLS_KEY`, `INSPECTOR_TLS_CERT`, `INSPECTOR_API_KEY` +``` + +## Timeouts + +### REQUEST_TIMEOUT + +A request timeout measures the duration of time between the instant when a new open TCP connection is passed to the +Sanic backend server, and the instant when the whole HTTP request is received. If the time taken exceeds the +`REQUEST_TIMEOUT` value (in seconds), this is considered a Client Error so Sanic generates an `HTTP 408` response +and sends that to the client. Set this parameter's value higher if your clients routinely pass very large request payloads +or upload requests very slowly. + +### RESPONSE_TIMEOUT + +A response timeout measures the duration of time between the instant the Sanic server passes the HTTP request to the Sanic App, and the instant a HTTP response is sent to the client. If the time taken exceeds the `RESPONSE_TIMEOUT` value (in seconds), this is considered a Server Error so Sanic generates an `HTTP 503` response and sends that to the client. Set this parameter's value higher if your application is likely to have long-running process that delay the +generation of a response. + +### KEEP_ALIVE_TIMEOUT + +#### What is Keep Alive? And what does the Keep Alive Timeout value do? + +`Keep-Alive` is a HTTP feature introduced in `HTTP 1.1`. When sending a HTTP request, the client (usually a web browser application) can set a `Keep-Alive` header to indicate the http server (Sanic) to not close the TCP connection after it has send the response. This allows the client to reuse the existing TCP connection to send subsequent HTTP requests, and ensures more efficient network traffic for both the client and the server. + +The `KEEP_ALIVE` config variable is set to `True` in Sanic by default. If you don't need this feature in your application, set it to `False` to cause all client connections to close immediately after a response is sent, regardless of the `Keep-Alive` header on the request. + +The amount of time the server holds the TCP connection open is decided by the server itself. In Sanic, that value is configured using the `KEEP_ALIVE_TIMEOUT` value. By default, **it is set to 120 seconds**. This means that if the client sends a `Keep-Alive` header, the server will hold the TCP connection open for 120 seconds after sending the response, and the client can reuse the connection to send another HTTP request within that time. + +For reference: + +- Apache httpd server default keepalive timeout = 5 seconds +- Nginx server default keepalive timeout = 75 seconds +- Nginx performance tuning guidelines uses keepalive = 15 seconds +- Caddy server default keepalive timeout = 120 seconds +- IE (5-9) client hard keepalive limit = 60 seconds +- Firefox client hard keepalive limit = 115 seconds +- Opera 11 client hard keepalive limit = 120 seconds +- Chrome 13+ client keepalive limit > 300+ seconds + +## Proxy configuration + +See [proxy configuration section](/guide/advanced/proxy-headers.md) From e79263f1dd524a392886d0e1728cf22296951f8c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:33 +0200 Subject: [PATCH 143/698] New translations configuration.md (Korean) --- .../content/ko/guide/running/configuration.md | 328 ++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 guide/content/ko/guide/running/configuration.md diff --git a/guide/content/ko/guide/running/configuration.md b/guide/content/ko/guide/running/configuration.md new file mode 100644 index 0000000000..89dacd7f7a --- /dev/null +++ b/guide/content/ko/guide/running/configuration.md @@ -0,0 +1,328 @@ +# Configuration + +## Basics + +.. column:: + +``` +Sanic holds the configuration in the config attribute of the application object. The configuration object is merely an object that can be modified either using dot-notation or like a dictionary. +``` + +.. column:: + +```` +```python +app = Sanic("myapp") +app.config.DB_NAME = "appdb" +app.config["DB_USER"] = "appuser" +``` +```` + +.. column:: + +``` +You can also use the `update()` method like on regular dictionaries. +``` + +.. column:: + +```` +```python +db_settings = { + 'DB_HOST': 'localhost', + 'DB_NAME': 'appdb', + 'DB_USER': 'appuser' +} +app.config.update(db_settings) +``` +```` + +.. note:: + +``` +It is standard practice in Sanic to name your config values in **uppercase letters**. Indeed, you may experience weird behaviors if you start mixing uppercase and lowercase names. +``` + +## Loading + +### Environment variables + +.. column:: + +``` +Any environment variables defined with the `SANIC_` prefix will be applied to the Sanic config. For example, setting `SANIC_REQUEST_TIMEOUT` will be loaded by the application automatically and fed into the `REQUEST_TIMEOUT` config variable. +``` + +.. column:: + +```` +```bash +$ export SANIC_REQUEST_TIMEOUT=10 +``` +```python +>>> print(app.config.REQUEST_TIMEOUT) +10 +``` +```` + +.. column:: + +``` +You can change the prefix that Sanic is expecting at startup. +``` + +.. column:: + +```` +```bash +$ export MYAPP_REQUEST_TIMEOUT=10 +``` +```python +>>> app = Sanic(__name__, env_prefix='MYAPP_') +>>> print(app.config.REQUEST_TIMEOUT) +10 +``` +```` + +.. column:: + +``` +You can also disable environment variable loading completely. +``` + +.. column:: + +```` +```python +app = Sanic(__name__, load_env=False) +``` +```` + +### Using Sanic.update_config + +The `Sanic` instance has a _very_ versatile method for loading config: `app.update_config`. You can feed it a path to a file, a dictionary, a class, or just about any other sort of object. + +#### From a file + +.. column:: + +``` +Let's say you have `my_config.py` file that looks like this. +``` + +.. column:: + +```` +```python +# my_config.py +A = 1 +B = 2 +``` +```` + +.. column:: + +``` +You can load this as config values by passing its path to `app.update_config`. +``` + +.. column:: + +```` +```python +>>> app.update_config("/path/to/my_config.py") +>>> print(app.config.A) +1 +``` +```` + +.. column:: + +``` +This path also accepts bash style environment variables. +``` + +.. column:: + +```` +```bash +$ export my_path="/path/to" +``` +```python +app.update_config("${my_path}/my_config.py") +``` +```` + +.. note:: + +``` +Just remember that you have to provide environment variables in the format `${environment_variable}` and that `$environment_variable` is not expanded (is treated as "plain" text). +``` + +#### From a dict + +.. column:: + +``` +The `app.update_config` method also works on plain dictionaries. +``` + +.. column:: + +```` +```python +app.update_config({"A": 1, "B": 2}) +``` +```` + +#### From a class or object + +.. column:: + +``` +You can define your own config class, and pass it to `app.update_config` +``` + +.. column:: + +```` +```python +class MyConfig: + A = 1 + B = 2 + +app.update_config(MyConfig) +``` +```` + +.. column:: + +``` +It even could be instantiated. +``` + +.. column:: + +```` +```python +app.update_config(MyConfig()) +``` +```` + +### Type casting + +When loading from environment variables, Sanic will attempt to cast the values to expected Python types. This particularly applies to: + +- `int` +- `float` +- `bool` + +In regards to `bool`, the following _case insensitive_ values are allowed: + +- **`True`**: `y`, `yes`, `yep`, `yup`, `t`, `true`, `on`, `enable`, `enabled`, `1` +- **`False`**: `n`, `no`, `f`, `false`, `off`, `disable`, `disabled`, `0` + +If a value cannot be cast, it will default to a `str`. + +.. column:: + +``` +Additionally, Sanic can be configured to cast additional types using additional type converters. This should be any callable that returns the value or raises a `ValueError`. + +*Added in v21.12* +``` + +.. column:: + +```` +```python +app = Sanic(..., config=Config(converters=[UUID])) +``` +```` + +## Builtin values + +| **Variable** | **Default** | **Description** | +| -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| ACCESS_LOG | True | Disable or enable access log | +| AUTO_EXTEND | True | Control whether [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) will load if it is in the existing virtual environment | +| AUTO_RELOAD | True | Control whether the application will automatically reload when a file changes | +| EVENT_AUTOREGISTER | True | When `True` using the `app.event()` method on a non-existing signal will automatically create it and not raise an exception | +| FALLBACK_ERROR_FORMAT | html | Format of error response if an exception is not caught and handled | +| FORWARDED_FOR_HEADER | X-Forwarded-For | The name of "X-Forwarded-For" HTTP header that contains client and proxy ip | +| FORWARDED_SECRET | None | Used to securely identify a specific proxy server (see below) | +| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | How long to wait to force close non-idle connection (sec) | +| INSPECTOR | False | Whether to enable the Inspector | +| INSPECTOR_HOST | localhost | The host for the Inspector | +| INSPECTOR_PORT | 6457 | The port for the Inspector | +| INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | +| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | +| INSPECTOR_API_KEY | - | The API key for the Inspector | +| KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | +| KEEP_ALIVE | True | Disables keep-alive when False | +| MOTD | True | Whether to display the MOTD (message of the day) at startup | +| MOTD_DISPLAY | {} | Key/value pairs to display additional, arbitrary data in the MOTD | +| NOISY_EXCEPTIONS | False | Force all `quiet` exceptions to be logged | +| PROXIES_COUNT | None | The number of proxy servers in front of the app (e.g. nginx; see below) | +| REAL_IP_HEADER | None | The name of "X-Real-IP" HTTP header that contains real client ip | +| REGISTER | True | Whether the app registry should be enabled | +| REQUEST_BUFFER_SIZE | 65536 | Request buffer size before request is paused, default is 64 Kib | +| REQUEST_ID_HEADER | X-Request-ID | The name of "X-Request-ID" HTTP header that contains request/correlation ID | +| REQUEST_MAX_SIZE | 100000000 | How big a request may be (bytes), default is 100 megabytes | +| REQUEST_MAX_HEADER_SIZE | 8192 | How big a request header may be (bytes), default is 8192 bytes | +| REQUEST_TIMEOUT | 60 | How long a request can take to arrive (sec) | +| RESPONSE_TIMEOUT | 60 | How long a response can take to process (sec) | +| USE_UVLOOP | True | Whether to override the loop policy to use `uvloop`. Supported only with `app.run`. | +| WEBSOCKET_MAX_SIZE | 2^20 | Maximum size for incoming messages (bytes) | +| WEBSOCKET_PING_INTERVAL | 20 | A Ping frame is sent every ping_interval seconds. | +| WEBSOCKET_PING_TIMEOUT | 20 | Connection is closed when Pong is not received after ping_timeout seconds | + +.. tip:: FYI + +``` +- The `USE_UVLOOP` value will be ignored if running with Gunicorn. Defaults to `False` on non-supported platforms (Windows). +- The `WEBSOCKET_` values will be ignored if in ASGI mode. +- v21.12 added: `AUTO_EXTEND`, `MOTD`, `MOTD_DISPLAY`, `NOISY_EXCEPTIONS` +- v22.9 added: `INSPECTOR` +- v22.12 added: `INSPECTOR_HOST`, `INSPECTOR_PORT`, `INSPECTOR_TLS_KEY`, `INSPECTOR_TLS_CERT`, `INSPECTOR_API_KEY` +``` + +## Timeouts + +### REQUEST_TIMEOUT + +A request timeout measures the duration of time between the instant when a new open TCP connection is passed to the +Sanic backend server, and the instant when the whole HTTP request is received. If the time taken exceeds the +`REQUEST_TIMEOUT` value (in seconds), this is considered a Client Error so Sanic generates an `HTTP 408` response +and sends that to the client. Set this parameter's value higher if your clients routinely pass very large request payloads +or upload requests very slowly. + +### RESPONSE_TIMEOUT + +A response timeout measures the duration of time between the instant the Sanic server passes the HTTP request to the Sanic App, and the instant a HTTP response is sent to the client. If the time taken exceeds the `RESPONSE_TIMEOUT` value (in seconds), this is considered a Server Error so Sanic generates an `HTTP 503` response and sends that to the client. Set this parameter's value higher if your application is likely to have long-running process that delay the +generation of a response. + +### KEEP_ALIVE_TIMEOUT + +#### What is Keep Alive? And what does the Keep Alive Timeout value do? + +`Keep-Alive` is a HTTP feature introduced in `HTTP 1.1`. When sending a HTTP request, the client (usually a web browser application) can set a `Keep-Alive` header to indicate the http server (Sanic) to not close the TCP connection after it has send the response. This allows the client to reuse the existing TCP connection to send subsequent HTTP requests, and ensures more efficient network traffic for both the client and the server. + +The `KEEP_ALIVE` config variable is set to `True` in Sanic by default. If you don't need this feature in your application, set it to `False` to cause all client connections to close immediately after a response is sent, regardless of the `Keep-Alive` header on the request. + +The amount of time the server holds the TCP connection open is decided by the server itself. In Sanic, that value is configured using the `KEEP_ALIVE_TIMEOUT` value. By default, **it is set to 120 seconds**. This means that if the client sends a `Keep-Alive` header, the server will hold the TCP connection open for 120 seconds after sending the response, and the client can reuse the connection to send another HTTP request within that time. + +For reference: + +- Apache httpd server default keepalive timeout = 5 seconds +- Nginx server default keepalive timeout = 75 seconds +- Nginx performance tuning guidelines uses keepalive = 15 seconds +- Caddy server default keepalive timeout = 120 seconds +- IE (5-9) client hard keepalive limit = 60 seconds +- Firefox client hard keepalive limit = 115 seconds +- Opera 11 client hard keepalive limit = 120 seconds +- Chrome 13+ client keepalive limit > 300+ seconds + +## Proxy configuration + +See [proxy configuration section](/guide/advanced/proxy-headers.md) From ad95edd5f183d63b20069d2e529c2fd87b4d378d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:34 +0200 Subject: [PATCH 144/698] New translations configuration.md (Chinese Simplified) --- .../content/zh/guide/running/configuration.md | 328 ++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 guide/content/zh/guide/running/configuration.md diff --git a/guide/content/zh/guide/running/configuration.md b/guide/content/zh/guide/running/configuration.md new file mode 100644 index 0000000000..89dacd7f7a --- /dev/null +++ b/guide/content/zh/guide/running/configuration.md @@ -0,0 +1,328 @@ +# Configuration + +## Basics + +.. column:: + +``` +Sanic holds the configuration in the config attribute of the application object. The configuration object is merely an object that can be modified either using dot-notation or like a dictionary. +``` + +.. column:: + +```` +```python +app = Sanic("myapp") +app.config.DB_NAME = "appdb" +app.config["DB_USER"] = "appuser" +``` +```` + +.. column:: + +``` +You can also use the `update()` method like on regular dictionaries. +``` + +.. column:: + +```` +```python +db_settings = { + 'DB_HOST': 'localhost', + 'DB_NAME': 'appdb', + 'DB_USER': 'appuser' +} +app.config.update(db_settings) +``` +```` + +.. note:: + +``` +It is standard practice in Sanic to name your config values in **uppercase letters**. Indeed, you may experience weird behaviors if you start mixing uppercase and lowercase names. +``` + +## Loading + +### Environment variables + +.. column:: + +``` +Any environment variables defined with the `SANIC_` prefix will be applied to the Sanic config. For example, setting `SANIC_REQUEST_TIMEOUT` will be loaded by the application automatically and fed into the `REQUEST_TIMEOUT` config variable. +``` + +.. column:: + +```` +```bash +$ export SANIC_REQUEST_TIMEOUT=10 +``` +```python +>>> print(app.config.REQUEST_TIMEOUT) +10 +``` +```` + +.. column:: + +``` +You can change the prefix that Sanic is expecting at startup. +``` + +.. column:: + +```` +```bash +$ export MYAPP_REQUEST_TIMEOUT=10 +``` +```python +>>> app = Sanic(__name__, env_prefix='MYAPP_') +>>> print(app.config.REQUEST_TIMEOUT) +10 +``` +```` + +.. column:: + +``` +You can also disable environment variable loading completely. +``` + +.. column:: + +```` +```python +app = Sanic(__name__, load_env=False) +``` +```` + +### Using Sanic.update_config + +The `Sanic` instance has a _very_ versatile method for loading config: `app.update_config`. You can feed it a path to a file, a dictionary, a class, or just about any other sort of object. + +#### From a file + +.. column:: + +``` +Let's say you have `my_config.py` file that looks like this. +``` + +.. column:: + +```` +```python +# my_config.py +A = 1 +B = 2 +``` +```` + +.. column:: + +``` +You can load this as config values by passing its path to `app.update_config`. +``` + +.. column:: + +```` +```python +>>> app.update_config("/path/to/my_config.py") +>>> print(app.config.A) +1 +``` +```` + +.. column:: + +``` +This path also accepts bash style environment variables. +``` + +.. column:: + +```` +```bash +$ export my_path="/path/to" +``` +```python +app.update_config("${my_path}/my_config.py") +``` +```` + +.. note:: + +``` +Just remember that you have to provide environment variables in the format `${environment_variable}` and that `$environment_variable` is not expanded (is treated as "plain" text). +``` + +#### From a dict + +.. column:: + +``` +The `app.update_config` method also works on plain dictionaries. +``` + +.. column:: + +```` +```python +app.update_config({"A": 1, "B": 2}) +``` +```` + +#### From a class or object + +.. column:: + +``` +You can define your own config class, and pass it to `app.update_config` +``` + +.. column:: + +```` +```python +class MyConfig: + A = 1 + B = 2 + +app.update_config(MyConfig) +``` +```` + +.. column:: + +``` +It even could be instantiated. +``` + +.. column:: + +```` +```python +app.update_config(MyConfig()) +``` +```` + +### Type casting + +When loading from environment variables, Sanic will attempt to cast the values to expected Python types. This particularly applies to: + +- `int` +- `float` +- `bool` + +In regards to `bool`, the following _case insensitive_ values are allowed: + +- **`True`**: `y`, `yes`, `yep`, `yup`, `t`, `true`, `on`, `enable`, `enabled`, `1` +- **`False`**: `n`, `no`, `f`, `false`, `off`, `disable`, `disabled`, `0` + +If a value cannot be cast, it will default to a `str`. + +.. column:: + +``` +Additionally, Sanic can be configured to cast additional types using additional type converters. This should be any callable that returns the value or raises a `ValueError`. + +*Added in v21.12* +``` + +.. column:: + +```` +```python +app = Sanic(..., config=Config(converters=[UUID])) +``` +```` + +## Builtin values + +| **Variable** | **Default** | **Description** | +| -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| ACCESS_LOG | True | Disable or enable access log | +| AUTO_EXTEND | True | Control whether [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) will load if it is in the existing virtual environment | +| AUTO_RELOAD | True | Control whether the application will automatically reload when a file changes | +| EVENT_AUTOREGISTER | True | When `True` using the `app.event()` method on a non-existing signal will automatically create it and not raise an exception | +| FALLBACK_ERROR_FORMAT | html | Format of error response if an exception is not caught and handled | +| FORWARDED_FOR_HEADER | X-Forwarded-For | The name of "X-Forwarded-For" HTTP header that contains client and proxy ip | +| FORWARDED_SECRET | None | Used to securely identify a specific proxy server (see below) | +| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | How long to wait to force close non-idle connection (sec) | +| INSPECTOR | False | Whether to enable the Inspector | +| INSPECTOR_HOST | localhost | The host for the Inspector | +| INSPECTOR_PORT | 6457 | The port for the Inspector | +| INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | +| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | +| INSPECTOR_API_KEY | - | The API key for the Inspector | +| KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | +| KEEP_ALIVE | True | Disables keep-alive when False | +| MOTD | True | Whether to display the MOTD (message of the day) at startup | +| MOTD_DISPLAY | {} | Key/value pairs to display additional, arbitrary data in the MOTD | +| NOISY_EXCEPTIONS | False | Force all `quiet` exceptions to be logged | +| PROXIES_COUNT | None | The number of proxy servers in front of the app (e.g. nginx; see below) | +| REAL_IP_HEADER | None | The name of "X-Real-IP" HTTP header that contains real client ip | +| REGISTER | True | Whether the app registry should be enabled | +| REQUEST_BUFFER_SIZE | 65536 | Request buffer size before request is paused, default is 64 Kib | +| REQUEST_ID_HEADER | X-Request-ID | The name of "X-Request-ID" HTTP header that contains request/correlation ID | +| REQUEST_MAX_SIZE | 100000000 | How big a request may be (bytes), default is 100 megabytes | +| REQUEST_MAX_HEADER_SIZE | 8192 | How big a request header may be (bytes), default is 8192 bytes | +| REQUEST_TIMEOUT | 60 | How long a request can take to arrive (sec) | +| RESPONSE_TIMEOUT | 60 | How long a response can take to process (sec) | +| USE_UVLOOP | True | Whether to override the loop policy to use `uvloop`. Supported only with `app.run`. | +| WEBSOCKET_MAX_SIZE | 2^20 | Maximum size for incoming messages (bytes) | +| WEBSOCKET_PING_INTERVAL | 20 | A Ping frame is sent every ping_interval seconds. | +| WEBSOCKET_PING_TIMEOUT | 20 | Connection is closed when Pong is not received after ping_timeout seconds | + +.. tip:: FYI + +``` +- The `USE_UVLOOP` value will be ignored if running with Gunicorn. Defaults to `False` on non-supported platforms (Windows). +- The `WEBSOCKET_` values will be ignored if in ASGI mode. +- v21.12 added: `AUTO_EXTEND`, `MOTD`, `MOTD_DISPLAY`, `NOISY_EXCEPTIONS` +- v22.9 added: `INSPECTOR` +- v22.12 added: `INSPECTOR_HOST`, `INSPECTOR_PORT`, `INSPECTOR_TLS_KEY`, `INSPECTOR_TLS_CERT`, `INSPECTOR_API_KEY` +``` + +## Timeouts + +### REQUEST_TIMEOUT + +A request timeout measures the duration of time between the instant when a new open TCP connection is passed to the +Sanic backend server, and the instant when the whole HTTP request is received. If the time taken exceeds the +`REQUEST_TIMEOUT` value (in seconds), this is considered a Client Error so Sanic generates an `HTTP 408` response +and sends that to the client. Set this parameter's value higher if your clients routinely pass very large request payloads +or upload requests very slowly. + +### RESPONSE_TIMEOUT + +A response timeout measures the duration of time between the instant the Sanic server passes the HTTP request to the Sanic App, and the instant a HTTP response is sent to the client. If the time taken exceeds the `RESPONSE_TIMEOUT` value (in seconds), this is considered a Server Error so Sanic generates an `HTTP 503` response and sends that to the client. Set this parameter's value higher if your application is likely to have long-running process that delay the +generation of a response. + +### KEEP_ALIVE_TIMEOUT + +#### What is Keep Alive? And what does the Keep Alive Timeout value do? + +`Keep-Alive` is a HTTP feature introduced in `HTTP 1.1`. When sending a HTTP request, the client (usually a web browser application) can set a `Keep-Alive` header to indicate the http server (Sanic) to not close the TCP connection after it has send the response. This allows the client to reuse the existing TCP connection to send subsequent HTTP requests, and ensures more efficient network traffic for both the client and the server. + +The `KEEP_ALIVE` config variable is set to `True` in Sanic by default. If you don't need this feature in your application, set it to `False` to cause all client connections to close immediately after a response is sent, regardless of the `Keep-Alive` header on the request. + +The amount of time the server holds the TCP connection open is decided by the server itself. In Sanic, that value is configured using the `KEEP_ALIVE_TIMEOUT` value. By default, **it is set to 120 seconds**. This means that if the client sends a `Keep-Alive` header, the server will hold the TCP connection open for 120 seconds after sending the response, and the client can reuse the connection to send another HTTP request within that time. + +For reference: + +- Apache httpd server default keepalive timeout = 5 seconds +- Nginx server default keepalive timeout = 75 seconds +- Nginx performance tuning guidelines uses keepalive = 15 seconds +- Caddy server default keepalive timeout = 120 seconds +- IE (5-9) client hard keepalive limit = 60 seconds +- Firefox client hard keepalive limit = 115 seconds +- Opera 11 client hard keepalive limit = 120 seconds +- Chrome 13+ client keepalive limit > 300+ seconds + +## Proxy configuration + +See [proxy configuration section](/guide/advanced/proxy-headers.md) From bb9defcc5044b9ac2d258b6c5096e24165b7f2ff Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:35 +0200 Subject: [PATCH 145/698] New translations development.md (Japanese) --- guide/content/ja/guide/running/development.md | 315 ++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 guide/content/ja/guide/running/development.md diff --git a/guide/content/ja/guide/running/development.md b/guide/content/ja/guide/running/development.md new file mode 100644 index 0000000000..03f7c5b47d --- /dev/null +++ b/guide/content/ja/guide/running/development.md @@ -0,0 +1,315 @@ +# Development + +The first thing that should be mentioned is that the webserver that is integrated into Sanic is **not** just a development server. + +It is production ready out-of-the-box, _unless you enable in debug mode_. + +## Debug mode + +By setting the debug mode, Sanic will be more verbose in its output and will disable several run-time optimizations. + +```python +# server.py +from sanic import Sanic +from sanic.response import json + +app = Sanic(__name__) + +@app.route("/") +async def hello_world(request): + return json({"hello": "world"}) +``` + +```sh +sanic server:app --host=0.0.0.0 --port=1234 --debug +``` + +.. danger:: + +``` +Sanic's debug mode will slow down the server's performance, and is **NOT** intended for production environments. + +**DO NOT** enable debug mode in production. +``` + +## Automatic Reloader + +.. column:: + +``` +Sanic offers a way to enable or disable the Automatic Reloader. The easiest way to enable it is using the CLI's `--reload` argument to activate the Automatic Reloader. Every time a Python file is changed, the reloader will restart your application automatically. This is very convenient while developing. + +.. note:: + + The reloader is only available when using Sanic's [worker manager](./manager.md). If you have disabled it using `--single-process` then the reloader will not be available to you. +``` + +.. column:: + +```` +```sh +sanic path.to:app --reload +``` +You can also use the shorthand property +```sh +sanic path.to:app -r +``` +```` + +.. column:: + +``` +If you have additional directories that you would like to automatically reload on file save (for example, a directory of HTML templates), you can add that using `--reload-dir`. +``` + +.. column:: + +```` +```sh +sanic path.to:app --reload --reload-dir=/path/to/templates +``` +Or multiple directories, shown here using the shorthand properties +```sh +sanic path.to:app -r -R /path/to/one -R /path/to/two +``` +```` + +## Development REPL + +.. new:: v23.12 + +``` +The Sanic CLI comes with a REPL (aka "read-eval-print loop") that can be used to interact with your application. This is useful for debugging and testing. A REPL is the interactive shell that you get when you run `python` without any arguments. +``` + +.. column:: + +``` +You can start the REPL by passing the `--repl` argument to the Sanic CLI. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --repl +``` +```` + +.. column:: + +``` +Or, perhaps more conveniently, when you run `--dev`, Sanic will automatically start the REPL for you. However, in this case you might be prompted to hit the "ENTER" key before actually starting the REPL. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --dev +``` +```` + +![](/assets/images/repl.png) + +As seen in the screenshot above, the REPL will automatically add a few variables to the global namespace. These are: + +- `app` - The Sanic application instance. This is the same instance that is passed to the `sanic` CLI. +- `sanic` - The `sanic` module. This is the same module that is imported when you run `import sanic`. +- `do` - A function that will create a mock `Request` object and pass it to your application. This is useful for testing your application from the REPL. +- `client` - An instance of `httpx.Client` that is configured to make requests to your application. This is useful for testing your application from the REPL. **Note:** This is only available if `httpx` is installed in your environment. + +### Async/Await support + +.. column:: + +``` +The REPL supports `async`/`await` syntax. This means that you can use `await` in the REPL to wait for asynchronous operations to complete. This is useful for testing asynchronous code. +``` + +.. column:: + +```` +```python +>>> await app.ctx.db.fetchval("SELECT 1") +1 +``` +```` + +### The `app` variable + +You need to keep in mind that the `app` variable is your app instance as it existed when the REPL was started. It is the instance that is loaded when running the CLI command. This means that any changes that are made to your source code and subsequently reloaded in the workers will not be reflected in the `app` variable. If you want to interact with the reloaded app instance, you will need to restart the REPL. + +However, it is also very useful to have access to the original app instance in the REPL for adhoc testing and debugging. + +### The `client` variable + +When [httpx](https://www.python-httpx.org/) is installed in your environment, the `client` variable will be available in the REPL. This is an instance of `httpx.Client` that is configured to make requests to your running application. + +.. column:: + +``` +To use it, simply call one of the HTTP methods on the client. See the [httpx documentation](https://www.python-httpx.org/api/#client) for more information. +``` + +.. column:: + +```` +```python +>>> client.get("/") + +``` +```` + +### The `do` function + +As discussed above, the `app` instance exists as it did at the time the REPL was started, and as was modified inside the REPL. Any changes to the instance that cause a server to be reloaded will not be reflected in the `app` variable. This is where the `do` function comes in. + +Let's say that you have modified your application inside the REPL to add a new route: + +```python +>>> @app.get("/new-route") +... async def new_route(request): +... return sanic.json({"hello": "world"}) +... +>>> +``` + +You can use the `do` function to mock out a request, and pass it to the application as if it were a real HTTP request. This will allow you to test your new route without having to restart the REPL. + +```python +>>> await do("/new-route") +Result(request=, response=) +``` + +The `do` function returns a `Result` object that contains the `Request` and `Response` objects that were returned by your application. It is a `NamedTuple`, so you can access the values by name: + +```python +>>> result = await do("/new-route") +>>> result.request + +>>> result.response + +``` + +Or, by destructuring the tuple: + +```python +>>> request, response = await do("/new-route") +>>> request + +>>> response + +``` + +### When to use `do` vs `client`? + +.. column:: + +``` +**Use `do` when ...** + +- You want to test a route that does not exist in the running application +- You want to test a route that has been modified in the REPL +- You make a change to your application inside the REPL +``` + +.. column:: + +``` +**Use `client` when ...** + +- You want to test a route that already exists in the running application +- You want to test a route that has been modified in your source code +- You want to send an actual HTTP request to your application +``` + +_Added in v23.12_ + +## Complete development mode + +.. column:: + +``` +If you would like to be in debug mode **and** have the Automatic Reloader running, you can pass `dev=True`. This is equivalent to **debug + auto reload**. + +*Added in v22.3* +``` + +.. column:: + +```` +```sh +sanic path.to:app --dev +``` +You can also use the shorthand property +```sh +sanic path.to:app -d +``` +```` + +.. new:: v23.12 + +``` +Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Development REPL](./development.md#development-repl) section for more information. + +As of v23.12, the `--dev` flag is roughly equivalent to `--debug --reload --repl`. Using `--dev` will require you to expressly begin the REPL by hitting "ENTER", while passing the `--repl` flag explicitly starts it. +``` + +.. column:: + +``` +If you would like to disable the REPL while using the `--dev` flag, you can pass `--no-repl`. +``` + +.. column:: + +```` +```sh +sanic path.to:app --dev --no-repl +``` +```` + +## Automatic TLS certificate + +When running in `DEBUG` mode, you can ask Sanic to handle setting up localhost temporary TLS certificates. This is helpful if you want to access your local development environment with `https://`. + +This functionality is provided by either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). Both are good choices, but there are some differences. `trustme` is a Python library and can be installed into your environment with `pip`. This makes for easy envrionment handling, but it is not compatible when running a HTTP/3 server. `mkcert` might be a more involved installation process, but can install a local CA and make it easier to use. + +.. column:: + +``` +You can choose which platform to use by setting `config.LOCAL_CERT_CREATOR`. When set to `"auto"`, it will select either option, preferring `mkcert` if possible. +``` + +.. column:: + +```` +```python +app.config.LOCAL_CERT_CREATOR = "auto" +app.config.LOCAL_CERT_CREATOR = "mkcert" +app.config.LOCAL_CERT_CREATOR = "trustme" +``` +```` + +.. column:: + +``` +Automatic TLS can be enabled at Sanic server run time: +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --auto-tls --debug +``` +```` + +.. warning:: + +``` +Localhost TLS certificates (like those generated by both `mkcert` and `trustme`) are **NOT** suitable for production environments. If you are not familiar with how to obtain a *real* TLS certificate, checkout the [How to...](../how-to/tls.md) section. +``` + +_Added in v22.6_ From 5d00fa4ac451694a5891fe9ca206c1d3359c27fe Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:36 +0200 Subject: [PATCH 146/698] New translations development.md (Korean) --- guide/content/ko/guide/running/development.md | 315 ++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 guide/content/ko/guide/running/development.md diff --git a/guide/content/ko/guide/running/development.md b/guide/content/ko/guide/running/development.md new file mode 100644 index 0000000000..03f7c5b47d --- /dev/null +++ b/guide/content/ko/guide/running/development.md @@ -0,0 +1,315 @@ +# Development + +The first thing that should be mentioned is that the webserver that is integrated into Sanic is **not** just a development server. + +It is production ready out-of-the-box, _unless you enable in debug mode_. + +## Debug mode + +By setting the debug mode, Sanic will be more verbose in its output and will disable several run-time optimizations. + +```python +# server.py +from sanic import Sanic +from sanic.response import json + +app = Sanic(__name__) + +@app.route("/") +async def hello_world(request): + return json({"hello": "world"}) +``` + +```sh +sanic server:app --host=0.0.0.0 --port=1234 --debug +``` + +.. danger:: + +``` +Sanic's debug mode will slow down the server's performance, and is **NOT** intended for production environments. + +**DO NOT** enable debug mode in production. +``` + +## Automatic Reloader + +.. column:: + +``` +Sanic offers a way to enable or disable the Automatic Reloader. The easiest way to enable it is using the CLI's `--reload` argument to activate the Automatic Reloader. Every time a Python file is changed, the reloader will restart your application automatically. This is very convenient while developing. + +.. note:: + + The reloader is only available when using Sanic's [worker manager](./manager.md). If you have disabled it using `--single-process` then the reloader will not be available to you. +``` + +.. column:: + +```` +```sh +sanic path.to:app --reload +``` +You can also use the shorthand property +```sh +sanic path.to:app -r +``` +```` + +.. column:: + +``` +If you have additional directories that you would like to automatically reload on file save (for example, a directory of HTML templates), you can add that using `--reload-dir`. +``` + +.. column:: + +```` +```sh +sanic path.to:app --reload --reload-dir=/path/to/templates +``` +Or multiple directories, shown here using the shorthand properties +```sh +sanic path.to:app -r -R /path/to/one -R /path/to/two +``` +```` + +## Development REPL + +.. new:: v23.12 + +``` +The Sanic CLI comes with a REPL (aka "read-eval-print loop") that can be used to interact with your application. This is useful for debugging and testing. A REPL is the interactive shell that you get when you run `python` without any arguments. +``` + +.. column:: + +``` +You can start the REPL by passing the `--repl` argument to the Sanic CLI. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --repl +``` +```` + +.. column:: + +``` +Or, perhaps more conveniently, when you run `--dev`, Sanic will automatically start the REPL for you. However, in this case you might be prompted to hit the "ENTER" key before actually starting the REPL. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --dev +``` +```` + +![](/assets/images/repl.png) + +As seen in the screenshot above, the REPL will automatically add a few variables to the global namespace. These are: + +- `app` - The Sanic application instance. This is the same instance that is passed to the `sanic` CLI. +- `sanic` - The `sanic` module. This is the same module that is imported when you run `import sanic`. +- `do` - A function that will create a mock `Request` object and pass it to your application. This is useful for testing your application from the REPL. +- `client` - An instance of `httpx.Client` that is configured to make requests to your application. This is useful for testing your application from the REPL. **Note:** This is only available if `httpx` is installed in your environment. + +### Async/Await support + +.. column:: + +``` +The REPL supports `async`/`await` syntax. This means that you can use `await` in the REPL to wait for asynchronous operations to complete. This is useful for testing asynchronous code. +``` + +.. column:: + +```` +```python +>>> await app.ctx.db.fetchval("SELECT 1") +1 +``` +```` + +### The `app` variable + +You need to keep in mind that the `app` variable is your app instance as it existed when the REPL was started. It is the instance that is loaded when running the CLI command. This means that any changes that are made to your source code and subsequently reloaded in the workers will not be reflected in the `app` variable. If you want to interact with the reloaded app instance, you will need to restart the REPL. + +However, it is also very useful to have access to the original app instance in the REPL for adhoc testing and debugging. + +### The `client` variable + +When [httpx](https://www.python-httpx.org/) is installed in your environment, the `client` variable will be available in the REPL. This is an instance of `httpx.Client` that is configured to make requests to your running application. + +.. column:: + +``` +To use it, simply call one of the HTTP methods on the client. See the [httpx documentation](https://www.python-httpx.org/api/#client) for more information. +``` + +.. column:: + +```` +```python +>>> client.get("/") + +``` +```` + +### The `do` function + +As discussed above, the `app` instance exists as it did at the time the REPL was started, and as was modified inside the REPL. Any changes to the instance that cause a server to be reloaded will not be reflected in the `app` variable. This is where the `do` function comes in. + +Let's say that you have modified your application inside the REPL to add a new route: + +```python +>>> @app.get("/new-route") +... async def new_route(request): +... return sanic.json({"hello": "world"}) +... +>>> +``` + +You can use the `do` function to mock out a request, and pass it to the application as if it were a real HTTP request. This will allow you to test your new route without having to restart the REPL. + +```python +>>> await do("/new-route") +Result(request=, response=) +``` + +The `do` function returns a `Result` object that contains the `Request` and `Response` objects that were returned by your application. It is a `NamedTuple`, so you can access the values by name: + +```python +>>> result = await do("/new-route") +>>> result.request + +>>> result.response + +``` + +Or, by destructuring the tuple: + +```python +>>> request, response = await do("/new-route") +>>> request + +>>> response + +``` + +### When to use `do` vs `client`? + +.. column:: + +``` +**Use `do` when ...** + +- You want to test a route that does not exist in the running application +- You want to test a route that has been modified in the REPL +- You make a change to your application inside the REPL +``` + +.. column:: + +``` +**Use `client` when ...** + +- You want to test a route that already exists in the running application +- You want to test a route that has been modified in your source code +- You want to send an actual HTTP request to your application +``` + +_Added in v23.12_ + +## Complete development mode + +.. column:: + +``` +If you would like to be in debug mode **and** have the Automatic Reloader running, you can pass `dev=True`. This is equivalent to **debug + auto reload**. + +*Added in v22.3* +``` + +.. column:: + +```` +```sh +sanic path.to:app --dev +``` +You can also use the shorthand property +```sh +sanic path.to:app -d +``` +```` + +.. new:: v23.12 + +``` +Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Development REPL](./development.md#development-repl) section for more information. + +As of v23.12, the `--dev` flag is roughly equivalent to `--debug --reload --repl`. Using `--dev` will require you to expressly begin the REPL by hitting "ENTER", while passing the `--repl` flag explicitly starts it. +``` + +.. column:: + +``` +If you would like to disable the REPL while using the `--dev` flag, you can pass `--no-repl`. +``` + +.. column:: + +```` +```sh +sanic path.to:app --dev --no-repl +``` +```` + +## Automatic TLS certificate + +When running in `DEBUG` mode, you can ask Sanic to handle setting up localhost temporary TLS certificates. This is helpful if you want to access your local development environment with `https://`. + +This functionality is provided by either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). Both are good choices, but there are some differences. `trustme` is a Python library and can be installed into your environment with `pip`. This makes for easy envrionment handling, but it is not compatible when running a HTTP/3 server. `mkcert` might be a more involved installation process, but can install a local CA and make it easier to use. + +.. column:: + +``` +You can choose which platform to use by setting `config.LOCAL_CERT_CREATOR`. When set to `"auto"`, it will select either option, preferring `mkcert` if possible. +``` + +.. column:: + +```` +```python +app.config.LOCAL_CERT_CREATOR = "auto" +app.config.LOCAL_CERT_CREATOR = "mkcert" +app.config.LOCAL_CERT_CREATOR = "trustme" +``` +```` + +.. column:: + +``` +Automatic TLS can be enabled at Sanic server run time: +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --auto-tls --debug +``` +```` + +.. warning:: + +``` +Localhost TLS certificates (like those generated by both `mkcert` and `trustme`) are **NOT** suitable for production environments. If you are not familiar with how to obtain a *real* TLS certificate, checkout the [How to...](../how-to/tls.md) section. +``` + +_Added in v22.6_ From 4fe921d0f5eda16b0c106adcf677f3164d9bb5c4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:37 +0200 Subject: [PATCH 147/698] New translations development.md (Chinese Simplified) --- guide/content/zh/guide/running/development.md | 315 ++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 guide/content/zh/guide/running/development.md diff --git a/guide/content/zh/guide/running/development.md b/guide/content/zh/guide/running/development.md new file mode 100644 index 0000000000..03f7c5b47d --- /dev/null +++ b/guide/content/zh/guide/running/development.md @@ -0,0 +1,315 @@ +# Development + +The first thing that should be mentioned is that the webserver that is integrated into Sanic is **not** just a development server. + +It is production ready out-of-the-box, _unless you enable in debug mode_. + +## Debug mode + +By setting the debug mode, Sanic will be more verbose in its output and will disable several run-time optimizations. + +```python +# server.py +from sanic import Sanic +from sanic.response import json + +app = Sanic(__name__) + +@app.route("/") +async def hello_world(request): + return json({"hello": "world"}) +``` + +```sh +sanic server:app --host=0.0.0.0 --port=1234 --debug +``` + +.. danger:: + +``` +Sanic's debug mode will slow down the server's performance, and is **NOT** intended for production environments. + +**DO NOT** enable debug mode in production. +``` + +## Automatic Reloader + +.. column:: + +``` +Sanic offers a way to enable or disable the Automatic Reloader. The easiest way to enable it is using the CLI's `--reload` argument to activate the Automatic Reloader. Every time a Python file is changed, the reloader will restart your application automatically. This is very convenient while developing. + +.. note:: + + The reloader is only available when using Sanic's [worker manager](./manager.md). If you have disabled it using `--single-process` then the reloader will not be available to you. +``` + +.. column:: + +```` +```sh +sanic path.to:app --reload +``` +You can also use the shorthand property +```sh +sanic path.to:app -r +``` +```` + +.. column:: + +``` +If you have additional directories that you would like to automatically reload on file save (for example, a directory of HTML templates), you can add that using `--reload-dir`. +``` + +.. column:: + +```` +```sh +sanic path.to:app --reload --reload-dir=/path/to/templates +``` +Or multiple directories, shown here using the shorthand properties +```sh +sanic path.to:app -r -R /path/to/one -R /path/to/two +``` +```` + +## Development REPL + +.. new:: v23.12 + +``` +The Sanic CLI comes with a REPL (aka "read-eval-print loop") that can be used to interact with your application. This is useful for debugging and testing. A REPL is the interactive shell that you get when you run `python` without any arguments. +``` + +.. column:: + +``` +You can start the REPL by passing the `--repl` argument to the Sanic CLI. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --repl +``` +```` + +.. column:: + +``` +Or, perhaps more conveniently, when you run `--dev`, Sanic will automatically start the REPL for you. However, in this case you might be prompted to hit the "ENTER" key before actually starting the REPL. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --dev +``` +```` + +![](/assets/images/repl.png) + +As seen in the screenshot above, the REPL will automatically add a few variables to the global namespace. These are: + +- `app` - The Sanic application instance. This is the same instance that is passed to the `sanic` CLI. +- `sanic` - The `sanic` module. This is the same module that is imported when you run `import sanic`. +- `do` - A function that will create a mock `Request` object and pass it to your application. This is useful for testing your application from the REPL. +- `client` - An instance of `httpx.Client` that is configured to make requests to your application. This is useful for testing your application from the REPL. **Note:** This is only available if `httpx` is installed in your environment. + +### Async/Await support + +.. column:: + +``` +The REPL supports `async`/`await` syntax. This means that you can use `await` in the REPL to wait for asynchronous operations to complete. This is useful for testing asynchronous code. +``` + +.. column:: + +```` +```python +>>> await app.ctx.db.fetchval("SELECT 1") +1 +``` +```` + +### The `app` variable + +You need to keep in mind that the `app` variable is your app instance as it existed when the REPL was started. It is the instance that is loaded when running the CLI command. This means that any changes that are made to your source code and subsequently reloaded in the workers will not be reflected in the `app` variable. If you want to interact with the reloaded app instance, you will need to restart the REPL. + +However, it is also very useful to have access to the original app instance in the REPL for adhoc testing and debugging. + +### The `client` variable + +When [httpx](https://www.python-httpx.org/) is installed in your environment, the `client` variable will be available in the REPL. This is an instance of `httpx.Client` that is configured to make requests to your running application. + +.. column:: + +``` +To use it, simply call one of the HTTP methods on the client. See the [httpx documentation](https://www.python-httpx.org/api/#client) for more information. +``` + +.. column:: + +```` +```python +>>> client.get("/") + +``` +```` + +### The `do` function + +As discussed above, the `app` instance exists as it did at the time the REPL was started, and as was modified inside the REPL. Any changes to the instance that cause a server to be reloaded will not be reflected in the `app` variable. This is where the `do` function comes in. + +Let's say that you have modified your application inside the REPL to add a new route: + +```python +>>> @app.get("/new-route") +... async def new_route(request): +... return sanic.json({"hello": "world"}) +... +>>> +``` + +You can use the `do` function to mock out a request, and pass it to the application as if it were a real HTTP request. This will allow you to test your new route without having to restart the REPL. + +```python +>>> await do("/new-route") +Result(request=, response=) +``` + +The `do` function returns a `Result` object that contains the `Request` and `Response` objects that were returned by your application. It is a `NamedTuple`, so you can access the values by name: + +```python +>>> result = await do("/new-route") +>>> result.request + +>>> result.response + +``` + +Or, by destructuring the tuple: + +```python +>>> request, response = await do("/new-route") +>>> request + +>>> response + +``` + +### When to use `do` vs `client`? + +.. column:: + +``` +**Use `do` when ...** + +- You want to test a route that does not exist in the running application +- You want to test a route that has been modified in the REPL +- You make a change to your application inside the REPL +``` + +.. column:: + +``` +**Use `client` when ...** + +- You want to test a route that already exists in the running application +- You want to test a route that has been modified in your source code +- You want to send an actual HTTP request to your application +``` + +_Added in v23.12_ + +## Complete development mode + +.. column:: + +``` +If you would like to be in debug mode **and** have the Automatic Reloader running, you can pass `dev=True`. This is equivalent to **debug + auto reload**. + +*Added in v22.3* +``` + +.. column:: + +```` +```sh +sanic path.to:app --dev +``` +You can also use the shorthand property +```sh +sanic path.to:app -d +``` +```` + +.. new:: v23.12 + +``` +Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Development REPL](./development.md#development-repl) section for more information. + +As of v23.12, the `--dev` flag is roughly equivalent to `--debug --reload --repl`. Using `--dev` will require you to expressly begin the REPL by hitting "ENTER", while passing the `--repl` flag explicitly starts it. +``` + +.. column:: + +``` +If you would like to disable the REPL while using the `--dev` flag, you can pass `--no-repl`. +``` + +.. column:: + +```` +```sh +sanic path.to:app --dev --no-repl +``` +```` + +## Automatic TLS certificate + +When running in `DEBUG` mode, you can ask Sanic to handle setting up localhost temporary TLS certificates. This is helpful if you want to access your local development environment with `https://`. + +This functionality is provided by either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). Both are good choices, but there are some differences. `trustme` is a Python library and can be installed into your environment with `pip`. This makes for easy envrionment handling, but it is not compatible when running a HTTP/3 server. `mkcert` might be a more involved installation process, but can install a local CA and make it easier to use. + +.. column:: + +``` +You can choose which platform to use by setting `config.LOCAL_CERT_CREATOR`. When set to `"auto"`, it will select either option, preferring `mkcert` if possible. +``` + +.. column:: + +```` +```python +app.config.LOCAL_CERT_CREATOR = "auto" +app.config.LOCAL_CERT_CREATOR = "mkcert" +app.config.LOCAL_CERT_CREATOR = "trustme" +``` +```` + +.. column:: + +``` +Automatic TLS can be enabled at Sanic server run time: +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --auto-tls --debug +``` +```` + +.. warning:: + +``` +Localhost TLS certificates (like those generated by both `mkcert` and `trustme`) are **NOT** suitable for production environments. If you are not familiar with how to obtain a *real* TLS certificate, checkout the [How to...](../how-to/tls.md) section. +``` + +_Added in v22.6_ From 31216991b517e5e3fa0817a035b51e720240ef33 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:38 +0200 Subject: [PATCH 148/698] New translations inspector.md (Japanese) --- guide/content/ja/guide/running/inspector.md | 245 ++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 guide/content/ja/guide/running/inspector.md diff --git a/guide/content/ja/guide/running/inspector.md b/guide/content/ja/guide/running/inspector.md new file mode 100644 index 0000000000..c8310877d9 --- /dev/null +++ b/guide/content/ja/guide/running/inspector.md @@ -0,0 +1,245 @@ +# Inspector + +The Sanic Inspector is a feature of Sanic Server. It is _only_ available when running Sanic with the built-in [worker manager](./manager.md). + +It is an HTTP application that _optionally_ runs in the background of your application to allow you to interact with the running instance of your application. + +.. tip:: INFO + +``` +The Inspector was introduced in limited capacity in v22.9, but the documentation on this page assumes you are using v22.12 or higher. +``` + +## Getting Started + +The inspector is disabled by default. To enable it, you have two options. + +.. column:: + +``` +Set a flag when creating your application instance. +``` + +.. column:: + +```` +```python +app = Sanic("TestApp", inspector=True) +``` +```` + +.. column:: + +``` +Or, set a configuration value. +``` + +.. column:: + +```` +```python +app = Sanic("TestApp") +app.config.INSPECTOR = True +``` +```` + +.. warning:: + +``` +If you are using the configuration value, it *must* be done early and before the main worker process starts. This means that it should either be an environment variable, or it should be set shortly after creating the application instance as shown above. +``` + +## Using the Inspector + +Once the inspector is running, you will have access to it via the CLI or by directly accessing its web API via HTTP. + +.. column:: + +```` +**Via CLI** +```sh +sanic inspect +``` +```` + +.. column:: + +```` +**Via HTTP** +```sh +curl http://localhost:6457 +``` +```` + +.. note:: + +``` +Remember, the Inspector is not running on your Sanic application. It is a seperate process, with a seperate application, and exposed on a seperate socket. +``` + +## Built-in Commands + +The Inspector comes with the following built-in commands. + +| CLI Command | HTTP Action | Description | +| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ | +| `inspect` | `GET /` | Display basic details about the running application. | +| `inspect reload` | `POST /reload` | Trigger a reload of all server workers. | +| `inspect shutdown` | `POST /shutdown` | Trigger a shutdown of all processes. | +| `inspect scale N` | `POST /scale`
`{"replicas": N}` | Scale the number of workers. Where `N` is the target number of replicas. | + +## Custom Commands + +The Inspector is easily extendable to add custom commands (and endpoints). + +.. column:: + +``` +Subclass the `Inspector` class and create arbitrary methods. As long as the method name is not preceded by an underscore (`_`), then the name of the method will be a new subcommand on the inspector. +``` + +.. column:: + +```` +```python +from sanic import json +from sanic.worker.inspector import Inspector + +class MyInspector(Inspector): + async def something(self, *args, **kwargs): + print(args) + print(kwargs) + +app = Sanic("TestApp", inspector_class=MyInspector, inspector=True) +``` +```` + +This will expose custom methods in the general pattern: + +- CLI: `sanic inspect ` +- HTTP: `POST /` + +It is important to note that the arguments that the new method accepts are derived from how you intend to use the command. For example, the above `something` method accepts all positional and keyword based parameters. + +.. column:: + +``` +In the CLI, the positional and keyword parameters are passed as either positional or keyword arguments to your method. All values will be a `str` with the following exceptions: + +- A keyword parameter with no assigned value will be: `True` +- Unless the parameter is prefixed with `no-`, then it will be: `False` +``` + +.. column:: + +```` +```sh +sanic inspect something one two three --four --no-five --six=6 +``` +In your application log console, you will see: +``` +('one', 'two', 'three') +{'four': True, 'five': False, 'six': '6'} +``` +```` + +.. column:: + +``` +The same can be achieved by hitting the API directly. You can pass arguments to the method by exposing them in a JSON payload. The only thing to note is that the positional arguments should be exposed as `{"args": [...]}`. +``` + +.. column:: + +```` +```sh +curl http://localhost:6457/something \ + --json '{"args":["one", "two", "three"], "four":true, "five":false, "six":6}' +``` +In your application log console, you will see: +``` +('one', 'two', 'three') +{'four': True, 'five': False, 'six': 6} +``` +```` + +## Using in production + +.. danger:: + +``` +Before exposing the Inspector on a product, please consider all of the options in this section carefully. +``` + +When running Inspector on a remote production instance, you can protect the endpoints by requiring TLS encryption, and requiring API key authentication. + +### TLS encryption + +.. column:: + +``` +To the Inspector HTTP instance over TLS, pass the paths to your certificate and key. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" +app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" +``` +```` + +.. column:: + +``` +This will require use of the `--secure` flag, or `https://`. +``` + +.. column:: + +```` +```sh +sanic inspect --secure --host= +``` +```sh +curl https://:6457 +``` +```` + +### API Key Authentication + +.. column:: + +``` +You can secure the API with bearer token authentication. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_API_KEY = "Super-Secret-200" +``` +```` + +.. column:: + +``` +This will require the `--api-key` parameter, or bearer token authorization header. +``` + +.. column:: + +```` +```sh +sanic inspect --api-key=Super-Secret-200 +``` +```sh +curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +``` +```` + +## Configuration + +See [configuration](./configuration.md) From 27702daa7c8ea90a7042536906394dab42158670 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:39 +0200 Subject: [PATCH 149/698] New translations inspector.md (Korean) --- guide/content/ko/guide/running/inspector.md | 245 ++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 guide/content/ko/guide/running/inspector.md diff --git a/guide/content/ko/guide/running/inspector.md b/guide/content/ko/guide/running/inspector.md new file mode 100644 index 0000000000..c8310877d9 --- /dev/null +++ b/guide/content/ko/guide/running/inspector.md @@ -0,0 +1,245 @@ +# Inspector + +The Sanic Inspector is a feature of Sanic Server. It is _only_ available when running Sanic with the built-in [worker manager](./manager.md). + +It is an HTTP application that _optionally_ runs in the background of your application to allow you to interact with the running instance of your application. + +.. tip:: INFO + +``` +The Inspector was introduced in limited capacity in v22.9, but the documentation on this page assumes you are using v22.12 or higher. +``` + +## Getting Started + +The inspector is disabled by default. To enable it, you have two options. + +.. column:: + +``` +Set a flag when creating your application instance. +``` + +.. column:: + +```` +```python +app = Sanic("TestApp", inspector=True) +``` +```` + +.. column:: + +``` +Or, set a configuration value. +``` + +.. column:: + +```` +```python +app = Sanic("TestApp") +app.config.INSPECTOR = True +``` +```` + +.. warning:: + +``` +If you are using the configuration value, it *must* be done early and before the main worker process starts. This means that it should either be an environment variable, or it should be set shortly after creating the application instance as shown above. +``` + +## Using the Inspector + +Once the inspector is running, you will have access to it via the CLI or by directly accessing its web API via HTTP. + +.. column:: + +```` +**Via CLI** +```sh +sanic inspect +``` +```` + +.. column:: + +```` +**Via HTTP** +```sh +curl http://localhost:6457 +``` +```` + +.. note:: + +``` +Remember, the Inspector is not running on your Sanic application. It is a seperate process, with a seperate application, and exposed on a seperate socket. +``` + +## Built-in Commands + +The Inspector comes with the following built-in commands. + +| CLI Command | HTTP Action | Description | +| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ | +| `inspect` | `GET /` | Display basic details about the running application. | +| `inspect reload` | `POST /reload` | Trigger a reload of all server workers. | +| `inspect shutdown` | `POST /shutdown` | Trigger a shutdown of all processes. | +| `inspect scale N` | `POST /scale`
`{"replicas": N}` | Scale the number of workers. Where `N` is the target number of replicas. | + +## Custom Commands + +The Inspector is easily extendable to add custom commands (and endpoints). + +.. column:: + +``` +Subclass the `Inspector` class and create arbitrary methods. As long as the method name is not preceded by an underscore (`_`), then the name of the method will be a new subcommand on the inspector. +``` + +.. column:: + +```` +```python +from sanic import json +from sanic.worker.inspector import Inspector + +class MyInspector(Inspector): + async def something(self, *args, **kwargs): + print(args) + print(kwargs) + +app = Sanic("TestApp", inspector_class=MyInspector, inspector=True) +``` +```` + +This will expose custom methods in the general pattern: + +- CLI: `sanic inspect ` +- HTTP: `POST /` + +It is important to note that the arguments that the new method accepts are derived from how you intend to use the command. For example, the above `something` method accepts all positional and keyword based parameters. + +.. column:: + +``` +In the CLI, the positional and keyword parameters are passed as either positional or keyword arguments to your method. All values will be a `str` with the following exceptions: + +- A keyword parameter with no assigned value will be: `True` +- Unless the parameter is prefixed with `no-`, then it will be: `False` +``` + +.. column:: + +```` +```sh +sanic inspect something one two three --four --no-five --six=6 +``` +In your application log console, you will see: +``` +('one', 'two', 'three') +{'four': True, 'five': False, 'six': '6'} +``` +```` + +.. column:: + +``` +The same can be achieved by hitting the API directly. You can pass arguments to the method by exposing them in a JSON payload. The only thing to note is that the positional arguments should be exposed as `{"args": [...]}`. +``` + +.. column:: + +```` +```sh +curl http://localhost:6457/something \ + --json '{"args":["one", "two", "three"], "four":true, "five":false, "six":6}' +``` +In your application log console, you will see: +``` +('one', 'two', 'three') +{'four': True, 'five': False, 'six': 6} +``` +```` + +## Using in production + +.. danger:: + +``` +Before exposing the Inspector on a product, please consider all of the options in this section carefully. +``` + +When running Inspector on a remote production instance, you can protect the endpoints by requiring TLS encryption, and requiring API key authentication. + +### TLS encryption + +.. column:: + +``` +To the Inspector HTTP instance over TLS, pass the paths to your certificate and key. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" +app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" +``` +```` + +.. column:: + +``` +This will require use of the `--secure` flag, or `https://`. +``` + +.. column:: + +```` +```sh +sanic inspect --secure --host= +``` +```sh +curl https://:6457 +``` +```` + +### API Key Authentication + +.. column:: + +``` +You can secure the API with bearer token authentication. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_API_KEY = "Super-Secret-200" +``` +```` + +.. column:: + +``` +This will require the `--api-key` parameter, or bearer token authorization header. +``` + +.. column:: + +```` +```sh +sanic inspect --api-key=Super-Secret-200 +``` +```sh +curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +``` +```` + +## Configuration + +See [configuration](./configuration.md) From 098646bbc29f01eb530f07e3c579682b17cea773 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:40 +0200 Subject: [PATCH 150/698] New translations inspector.md (Chinese Simplified) --- guide/content/zh/guide/running/inspector.md | 245 ++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 guide/content/zh/guide/running/inspector.md diff --git a/guide/content/zh/guide/running/inspector.md b/guide/content/zh/guide/running/inspector.md new file mode 100644 index 0000000000..c8310877d9 --- /dev/null +++ b/guide/content/zh/guide/running/inspector.md @@ -0,0 +1,245 @@ +# Inspector + +The Sanic Inspector is a feature of Sanic Server. It is _only_ available when running Sanic with the built-in [worker manager](./manager.md). + +It is an HTTP application that _optionally_ runs in the background of your application to allow you to interact with the running instance of your application. + +.. tip:: INFO + +``` +The Inspector was introduced in limited capacity in v22.9, but the documentation on this page assumes you are using v22.12 or higher. +``` + +## Getting Started + +The inspector is disabled by default. To enable it, you have two options. + +.. column:: + +``` +Set a flag when creating your application instance. +``` + +.. column:: + +```` +```python +app = Sanic("TestApp", inspector=True) +``` +```` + +.. column:: + +``` +Or, set a configuration value. +``` + +.. column:: + +```` +```python +app = Sanic("TestApp") +app.config.INSPECTOR = True +``` +```` + +.. warning:: + +``` +If you are using the configuration value, it *must* be done early and before the main worker process starts. This means that it should either be an environment variable, or it should be set shortly after creating the application instance as shown above. +``` + +## Using the Inspector + +Once the inspector is running, you will have access to it via the CLI or by directly accessing its web API via HTTP. + +.. column:: + +```` +**Via CLI** +```sh +sanic inspect +``` +```` + +.. column:: + +```` +**Via HTTP** +```sh +curl http://localhost:6457 +``` +```` + +.. note:: + +``` +Remember, the Inspector is not running on your Sanic application. It is a seperate process, with a seperate application, and exposed on a seperate socket. +``` + +## Built-in Commands + +The Inspector comes with the following built-in commands. + +| CLI Command | HTTP Action | Description | +| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ | +| `inspect` | `GET /` | Display basic details about the running application. | +| `inspect reload` | `POST /reload` | Trigger a reload of all server workers. | +| `inspect shutdown` | `POST /shutdown` | Trigger a shutdown of all processes. | +| `inspect scale N` | `POST /scale`
`{"replicas": N}` | Scale the number of workers. Where `N` is the target number of replicas. | + +## Custom Commands + +The Inspector is easily extendable to add custom commands (and endpoints). + +.. column:: + +``` +Subclass the `Inspector` class and create arbitrary methods. As long as the method name is not preceded by an underscore (`_`), then the name of the method will be a new subcommand on the inspector. +``` + +.. column:: + +```` +```python +from sanic import json +from sanic.worker.inspector import Inspector + +class MyInspector(Inspector): + async def something(self, *args, **kwargs): + print(args) + print(kwargs) + +app = Sanic("TestApp", inspector_class=MyInspector, inspector=True) +``` +```` + +This will expose custom methods in the general pattern: + +- CLI: `sanic inspect ` +- HTTP: `POST /` + +It is important to note that the arguments that the new method accepts are derived from how you intend to use the command. For example, the above `something` method accepts all positional and keyword based parameters. + +.. column:: + +``` +In the CLI, the positional and keyword parameters are passed as either positional or keyword arguments to your method. All values will be a `str` with the following exceptions: + +- A keyword parameter with no assigned value will be: `True` +- Unless the parameter is prefixed with `no-`, then it will be: `False` +``` + +.. column:: + +```` +```sh +sanic inspect something one two three --four --no-five --six=6 +``` +In your application log console, you will see: +``` +('one', 'two', 'three') +{'four': True, 'five': False, 'six': '6'} +``` +```` + +.. column:: + +``` +The same can be achieved by hitting the API directly. You can pass arguments to the method by exposing them in a JSON payload. The only thing to note is that the positional arguments should be exposed as `{"args": [...]}`. +``` + +.. column:: + +```` +```sh +curl http://localhost:6457/something \ + --json '{"args":["one", "two", "three"], "four":true, "five":false, "six":6}' +``` +In your application log console, you will see: +``` +('one', 'two', 'three') +{'four': True, 'five': False, 'six': 6} +``` +```` + +## Using in production + +.. danger:: + +``` +Before exposing the Inspector on a product, please consider all of the options in this section carefully. +``` + +When running Inspector on a remote production instance, you can protect the endpoints by requiring TLS encryption, and requiring API key authentication. + +### TLS encryption + +.. column:: + +``` +To the Inspector HTTP instance over TLS, pass the paths to your certificate and key. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" +app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" +``` +```` + +.. column:: + +``` +This will require use of the `--secure` flag, or `https://`. +``` + +.. column:: + +```` +```sh +sanic inspect --secure --host= +``` +```sh +curl https://:6457 +``` +```` + +### API Key Authentication + +.. column:: + +``` +You can secure the API with bearer token authentication. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_API_KEY = "Super-Secret-200" +``` +```` + +.. column:: + +``` +This will require the `--api-key` parameter, or bearer token authorization header. +``` + +.. column:: + +```` +```sh +sanic inspect --api-key=Super-Secret-200 +``` +```sh +curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +``` +```` + +## Configuration + +See [configuration](./configuration.md) From 7299866ddc59a105d46cfeecf6052237e8eb1341 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:42 +0200 Subject: [PATCH 151/698] New translations manager.md (Japanese) --- guide/content/ja/guide/running/manager.md | 669 ++++++++++++++++++++++ 1 file changed, 669 insertions(+) create mode 100644 guide/content/ja/guide/running/manager.md diff --git a/guide/content/ja/guide/running/manager.md b/guide/content/ja/guide/running/manager.md new file mode 100644 index 0000000000..b71685420e --- /dev/null +++ b/guide/content/ja/guide/running/manager.md @@ -0,0 +1,669 @@ +--- +title: Worker Manager +--- + +# Worker Manager + +The worker manager and its functionality was introduced in version 22.9. + +_The details of this section are intended for more advanced usages and **not** necessary to get started._ + +The purpose of the manager is to create consistency and flexibility between development and production environments. Whether you intend to run a single worker, or multiple workers, whether with, or without auto-reload: the experience will be the same. + +In general it looks like this: + +![](https://user-images.githubusercontent.com/166269/178677618-3b4089c3-6c6a-4ecc-8d7a-7eba2a7f29b0.png) + +When you run Sanic, the main process instantiates a `WorkerManager`. That manager is in charge of running one or more `WorkerProcess`. There generally are two kinds of processes: + +- server processes, and +- non-server processes. + +For the sake of ease, the User Guide generally will use the term "worker" or "worker process" to mean a server process, and "Manager" to mean the single worker manager running in your main process. + +## How Sanic Server starts processes + +Sanic will start processes using the [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) start method. This means that for every process/worker, the global scope of your application will be run on its own thread. The practical impact of this that _if_ you do not run Sanic with the CLI, you will need to nest the execution code inside a block to make sure it only runs on `__main__`. + +```python +if __name__ == "__main__": + app.run() +``` + +If you do not, you are likely to see an error message like this: + +``` +sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. + +This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. + +See more information: https://sanic.dev/en/guide/deployment/manager.html#how-sanic-server-starts-processes +``` + +The likely fix for this problem is nesting your Sanic run call inside of the `__name__ == "__main__"` block. If you continue to receive this message after nesting, or if you see this while using the CLI, then it means the port you are trying to use is not available on your machine and you must select another port. + +### Starting a worker + +All worker processes _must_ send an acknowledgement when starting. This happens under the hood, and you as a developer do not need to do anything. However, the Manager will exit with a status code `1` if one or more workers do not send that `ack` message, or a worker process throws an exception while trying to start. If no exceptions are encountered, the Manager will wait for up to thirty (30) seconds for the acknowledgement. + +.. column:: + +``` +In the situation when you know that you will need more time to start, you can monkeypatch the Manager. The threshold does not include anything inside of a listener, and is limited to the execution time of everything in the global scope of your application. + +If you run into this issue, it may indicate a need to look deeper into what is causing the slow startup. +``` + +.. column:: + +```` +```python +from sanic.worker.manager import WorkerManager + +WorkerManager.THRESHOLD = 100 # Value is in 0.1s +``` +```` + +See [worker ack](#worker-ack) for more information. + +.. column:: + +``` +As stated above, Sanic will use [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to start worker processes. If you would like to change this behavior and are aware of the implications of using different start methods, you can modify as shown here. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +### Worker ack + +When all of your workers are running in a subprocess a potential problem is created: deadlock. This can occur when the child processes cease to function, but the main process is unaware that this happened. Therefore, Sanic servers will automatically send an `ack` message (short for acknowledge) to the main process after startup. + +In version 22.9, the `ack` timeout was short and limited to `5s`. In version 22.12, the timeout was lengthened to `30s`. If your application is shutting down after thirty seconds then it might be necessary to manually increase this threshhold. + +.. column:: + +``` +The value of `WorkerManager.THRESHOLD` is in `0.1s` increments. Therefore, to set it to one minute, you should set the value to `600`. + +This value should be set as early as possible in your application, and should ideally happen in the global scope. Setting it after the main process has started will not work. +``` + +.. column:: + +```` +```python +from sanic.worker.manager import WorkerManager + +WorkerManager.THRESHOLD = 600 +``` +```` + +### Zero downtime restarts + +By default, when restarting workers, Sanic will teardown the existing process first before starting a new one. + +If you are intending to use the restart functionality in production then you may be interested in having zero-downtime reloading. This can be accomplished by forcing the reloader to change the order to start a new process, wait for it to [ack](#worker-ack), and then teardown the old process. + +.. column:: + +``` +From the multiplexer, use the `zero_downtime` argument +``` + +.. column:: + +```` +```python +app.m.restart(zero_downtime=True) +``` +```` + +_Added in v22.12_ + +## Using shared context between worker processes + +Python provides a few methods for [exchanging objects](https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes), [synchronizing](https://docs.python.org/3/library/multiprocessing.html#synchronization-between-processes), and [sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-between-processes) between processes. This usually involves objects from the `multiprocessing` and `ctypes` modules. + +If you are familiar with these objects and how to work with them, you will be happy to know that Sanic provides an API for sharing these objects between your worker processes. If you are not familiar, you are encouraged to read through the Python documentation linked above and try some of the examples before proceeding with implementing shared context. + +Similar to how [application context](../basics/app.md#application-context) allows an applicaiton to share state across the lifetime of the application with `app.ctx`, shared context provides the same for the special objects mentioned above. This context is available as `app.shared_ctx` and should **ONLY** be used to share objects intended for this purpose. + +The `shared_ctx` will: + +- _NOT_ share regular objects like `int`, `dict`, or `list` +- _NOT_ share state between Sanic instances running on different machines +- _NOT_ share state to non-worker processes +- **only** share state between server workers managed by the same Manager + +Attaching an inappropriate object to `shared_ctx` will likely result in a warning, and not an error. You should be careful to not accidentally add an unsafe object to `shared_ctx` as it may not work as expected. If you are directed here because of one of those warnings, you might have accidentally used an unsafe object in `shared_ctx`. + +.. column:: + +``` +In order to create a shared object you **must** create it in the main process and attach it inside of the `main_process_start` listener. +``` + +.. column:: + +```` +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` +```` + +Trying to attach to the `shared_ctx` object outside of this listener may result in a `RuntimeError`. + +.. column:: + +``` +After creating the objects in the `main_process_start` listener and attaching to the `shared_ctx`, they will be available in your workers wherever the application instance is available (example: listeners, middleware, request handlers). +``` + +.. column:: + +```` +```python +from multiprocessing import Queue + +@app.get("") +async def handler(request): + request.app.shared_ctx.queue.put(1) + ... +``` +```` + +## Access to the multiplexer + +The application instance has access to an object that provides access to interacting with the Manager and other worker processes. The object is attached as the `app.multiplexer` property, but it is more easily accessed by its alias: `app.m`. + +.. column:: + +``` +For example, you can get access to the current worker state. +``` + +.. column:: + +```` +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.name) + print(request.app.m.pid) + print(request.app.m.state) +``` +``` +Sanic-Server-0-0 +99999 +{'server': True, 'state': 'ACKED', 'pid': 99999, 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), 'starts': 2, 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc)} +``` +```` + +.. column:: + +``` +The `multiplexer` also has access to terminate the Manager, or restart worker processes +``` + +.. column:: + +```` +```python +# shutdown the entire application and all processes +app.m.name.terminate() + +# restart the current worker only +app.m.name.restart() + +# restart specific workers only (comma delimited) +app.m.name.restart("Sanic-Server-4-0,Sanic-Server-7-0") + +# restart ALL workers +app.m.name.restart(all_workers=True) # Available v22.12+ +``` +```` + +## Worker state + +.. column:: + +``` +As shown above, the `multiplexer` has access to report upon the state of the current running worker. However, it also contains the state for ALL processes running. +``` + +.. column:: + +```` +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.workers) +``` +``` +{ + 'Sanic-Main': {'pid': 99997}, + 'Sanic-Server-0-0': { + 'server': True, + 'state': 'ACKED', + 'pid': 9999, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 2, + 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc) + }, + 'Sanic-Reloader-0': { + 'server': False, + 'state': 'STARTED', + 'pid': 99998, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 1 + } +} +``` +```` + +The possible states are: + +- `NONE` - The worker has been created, but there is no process yet +- `IDLE` - The process has been created, but is not running yet +- `STARTING` - The process is starting +- `STARTED` - The process has started +- `ACKED` - The process has started and sent an acknowledgement (usually only for server processes) +- `JOINED` - The process has exited and joined the main process +- `TERMINATED` - The process has exited and terminated +- `RESTARTING` - The process is restarting +- `FAILED` - The process encountered an exception and is no longer running +- `COMPLETED` - The process has completed its work and exited successfully + +## Built-in non-server processes + +As mentioned, the Manager also has the ability to run non-server processes. Sanic comes with two built-in types of non-server processes, and allows for [creating custom processes](#running-custom-processes). + +The two built-in processes are + +- the [auto-reloader](./development.md#automatic-reloader), optionally enabled to watch the file system for changes and trigger a restart +- [inspector](#inspector), optionally enabled to provide external access to the state of the running instance + +## Inspector + +Sanic has the ability to expose the state and the functionality of the `multiplexer` to the CLI. Currently, this requires the CLI command to be run on the same machine as the running Sanic instance. By default the inspector is disabled. + +.. column:: + +``` +To enable it, set the config value to `True`. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR = True +``` +```` + +You will now have access to execute any of these CLI commands: + +``` +sanic inspect reload Trigger a reload of the server workers +sanic inspect shutdown Shutdown the application and all processes +sanic inspect scale N Scale the number of workers to N +sanic inspect Run a custom command +``` + +![](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) + +.. column:: + +``` +This works by exposing a small HTTP service on your machine. You can control the location using configuration values: +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_HOST = "localhost" +app.config.INSPECTOR_PORT = 6457 +``` +```` + +[Learn more](./inspector.md) to find out what is possible with the Inspector. + +## Running custom processes + +To run a managed custom process on Sanic, you must create a callable. If that process is meant to be long-running, then it should handle a shutdown call by a `SIGINT` or `SIGTERM` signal. + +.. column:: + +``` +The simplest method for doing that in Python will be to just wrap your loop in `KeyboardInterrupt`. + +If you intend to run another application, like a bot, then it is likely that it already has capability to handle this signal and you likely do not need to do anything. +``` + +.. column:: + +```` +```python +from time import sleep + +def my_process(foo): + try: + while True: + sleep(1) + except KeyboardInterrupt: + print("done") +``` +```` + +.. column:: + +``` +That callable must be registered in the `main_process_ready` listener. It is important to note that is is **NOT** the same location that you should register [shared context](#using-shared-context-between-worker-processes) objects. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): +# app.manager.manage(, , ) + app.manager.manage("MyProcess", my_process, {"foo": "bar"}) +``` +```` + +### Transient v. durable processes + +.. column:: + +``` +When you manage a process with the `manage` method, you have the option to make it transient or durable. A transient process will be restarted by the auto-reloader, and a durable process will not. + +By default, all processes are durable. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + transient=True, + ) +``` +```` + +### Tracked v. untracked processes + +.. new:: v23.12 + +``` +Out of the box, Sanic will track the state of all processes. This means that you can access the state of the process from the [multiplexer](./manager#access-to-the-multiplexer) object, or from the [Inspector](./manager#inspector). + +See [worker state](./manager#worker-state) for more information. + +Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. +``` + +.. column:: + +``` +When you are running a non-long-running process, you can opt out of tracking it by setting `tracked=False` in the `manage` method. This means that upon completion of the process it will be removed from the list of tracked processes. You will only be able to check the state of the process while it is running. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "OneAndDone", + do_once, + {}, + tracked=False, + ) +``` +```` + +_Added in v23.12_ + +### Restartable custom processes + +.. new:: v23.12 + +``` +A custom process that is transient will **always** be restartable. That means the auto-restart will work as expected. However, what if you want to be able to *manually* restart a process, but not have it be restarted by the auto-reloader? +``` + +.. column:: + +``` +In this scenario, you can set `restartable=True` in the `manage` method. This will allow you to manually restart the process, but it will not be restarted by the auto-reloader. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + restartable=True, + ) +``` +```` + +.. column:: + +``` +You could now manually restart that process from the multiplexer. +``` + +.. column:: + +```` +```python +@app.get("/restart") +async def restart_handler(request: Request): + request.app.m.restart("Sanic-MyProcess-0") + return json({"foo": request.app.m.name}) +``` +```` + +_Added in v23.12_ + +### On the fly process management + +.. new:: v23.12 + +``` +Custom processes are usually added in the `main_process_ready` listener. However, there may be times when you want to add a process after the application has started. For example, you may want to add a process from a request handler. The multiplexer provides a method for doing this. +``` + +.. column:: + +``` +Once you have a reference to the multiplexer, you can call `manage` to add a process. It works the same as the `manage` method on the Manager. +``` + +.. column:: + +```` +```python +@app.post("/start") +async def start_handler(request: Request): + request.app.m.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + workers=2, + ) + return json({"foo": request.app.m.name}) +``` +```` + +_Added in v23.12_ + +## Single process mode + +.. column:: + +``` +If you would like to opt out of running multiple processes, you can run Sanic in a single process only. In this case, the Manager will not run. You will also not have access to any features that require processes (auto-reload, the inspector, etc). +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --single-process +``` +```python +if __name__ == "__main__": + app.run(single_process=True) +``` +```python +if __name__ == "__main__": + app.prepare(single_process=True) + Sanic.serve_single() +``` +```` + +## Sanic and multiprocessing + +Sanic makes heavy use of the [`multiprocessing` module](https://docs.python.org/3/library/multiprocessing.html) to manage the worker processes. You should generally avoid lower level usage of this module (like setting the start method) as it may interfere with the functionality of Sanic. + +### Start methods in Python + +Before explaining what Sanic tries to do, it is important to understand what the `start_method` is and why it is important. Python generally allows for three different methods of starting a process: + +- `fork` +- `spawn` +- `forkserver` + +The `fork` and `forkserver` methods are only available on Unix systems, and `spawn` is the only method available on Windows. On Unix systems where you have a choice, `fork` is generally the default system method. + +You are encouraged to read the [Python documentation](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to learn more about the differences between these methods. However, the important thing to know is that `fork` basically copies the entire memory of the parent process into the child process, whereas `spawn` will create a new process and then load the application into that process. This is the reason why you need to nest your Sanic `run` call inside of the `__name__ == "__main__"` block if you are not using the CLI. + +### Sanic and start methods + +By default, Sanic will try and use `spawn` as the start method. This is because it is the only method available on Windows, and it is the safest method on Unix systems. + +.. column:: + +``` +However, if you are running Sanic on a Unix system and you would like to use `fork` instead, you can do so by setting the `start_method` on the `Sanic` class. You will want to do this as early as possible in your application, and ideally in the global scope before you import any other modules. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +### Overcoming a `RuntimeError` + +You might have received a `RuntimeError` that looks like this: + +``` +RuntimeError: Start method 'spawn' was requested, but 'fork' was already set. +``` + +If so, that means somewhere in your application you are trying to set the start method that conflicts with what Sanic is trying to do. You have a few options to resolve this: + +.. column:: + +``` +**OPTION 1:** You can tell Sanic that the start method has been set and to not try and set it again. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.START_METHOD_SET = True +``` +```` + +.. column:: + +``` +**OPTION 2:** You could tell Sanic that you intend to use `fork` and to not try and set it to `spawn`. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +.. column:: + +``` +**OPTION 3:** You can tell Python to use `spawn` instead of `fork` by setting the `multiprocessing` start method. +``` + +.. column:: + +```` +```python +import multiprocessing + +multiprocessing.set_start_method("spawn") +``` +```` + +In any of these options, you should run this code as early as possible in your application. Depending upon exactly what your specific scenario is, you may need to combine some of the options. + +.. note:: + +```` +The potential issues that arise from this problem are usually easily solved by just allowing Sanic to be in charge of multiprocessing. This usually means making use of the `main_process_start` and `main_process_ready` listeners to deal with multiprocessing issues. For example, you should move instantiating multiprocessing primitives that do a lot of work under the hood from the global scope and into a listener. + +```python +# This is BAD; avoid the global scope +from multiprocessing import Queue + +q = Queue() +``` + +```python +# This is GOOD; the queue is made in a listener and shared to all the processes on the shared_ctx +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.q = Queue() +``` +```` From fa600f8f3a69f621e4bff417701aa012c48f1310 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:43 +0200 Subject: [PATCH 152/698] New translations manager.md (Korean) --- guide/content/ko/guide/running/manager.md | 669 ++++++++++++++++++++++ 1 file changed, 669 insertions(+) create mode 100644 guide/content/ko/guide/running/manager.md diff --git a/guide/content/ko/guide/running/manager.md b/guide/content/ko/guide/running/manager.md new file mode 100644 index 0000000000..b71685420e --- /dev/null +++ b/guide/content/ko/guide/running/manager.md @@ -0,0 +1,669 @@ +--- +title: Worker Manager +--- + +# Worker Manager + +The worker manager and its functionality was introduced in version 22.9. + +_The details of this section are intended for more advanced usages and **not** necessary to get started._ + +The purpose of the manager is to create consistency and flexibility between development and production environments. Whether you intend to run a single worker, or multiple workers, whether with, or without auto-reload: the experience will be the same. + +In general it looks like this: + +![](https://user-images.githubusercontent.com/166269/178677618-3b4089c3-6c6a-4ecc-8d7a-7eba2a7f29b0.png) + +When you run Sanic, the main process instantiates a `WorkerManager`. That manager is in charge of running one or more `WorkerProcess`. There generally are two kinds of processes: + +- server processes, and +- non-server processes. + +For the sake of ease, the User Guide generally will use the term "worker" or "worker process" to mean a server process, and "Manager" to mean the single worker manager running in your main process. + +## How Sanic Server starts processes + +Sanic will start processes using the [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) start method. This means that for every process/worker, the global scope of your application will be run on its own thread. The practical impact of this that _if_ you do not run Sanic with the CLI, you will need to nest the execution code inside a block to make sure it only runs on `__main__`. + +```python +if __name__ == "__main__": + app.run() +``` + +If you do not, you are likely to see an error message like this: + +``` +sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. + +This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. + +See more information: https://sanic.dev/en/guide/deployment/manager.html#how-sanic-server-starts-processes +``` + +The likely fix for this problem is nesting your Sanic run call inside of the `__name__ == "__main__"` block. If you continue to receive this message after nesting, or if you see this while using the CLI, then it means the port you are trying to use is not available on your machine and you must select another port. + +### Starting a worker + +All worker processes _must_ send an acknowledgement when starting. This happens under the hood, and you as a developer do not need to do anything. However, the Manager will exit with a status code `1` if one or more workers do not send that `ack` message, or a worker process throws an exception while trying to start. If no exceptions are encountered, the Manager will wait for up to thirty (30) seconds for the acknowledgement. + +.. column:: + +``` +In the situation when you know that you will need more time to start, you can monkeypatch the Manager. The threshold does not include anything inside of a listener, and is limited to the execution time of everything in the global scope of your application. + +If you run into this issue, it may indicate a need to look deeper into what is causing the slow startup. +``` + +.. column:: + +```` +```python +from sanic.worker.manager import WorkerManager + +WorkerManager.THRESHOLD = 100 # Value is in 0.1s +``` +```` + +See [worker ack](#worker-ack) for more information. + +.. column:: + +``` +As stated above, Sanic will use [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to start worker processes. If you would like to change this behavior and are aware of the implications of using different start methods, you can modify as shown here. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +### Worker ack + +When all of your workers are running in a subprocess a potential problem is created: deadlock. This can occur when the child processes cease to function, but the main process is unaware that this happened. Therefore, Sanic servers will automatically send an `ack` message (short for acknowledge) to the main process after startup. + +In version 22.9, the `ack` timeout was short and limited to `5s`. In version 22.12, the timeout was lengthened to `30s`. If your application is shutting down after thirty seconds then it might be necessary to manually increase this threshhold. + +.. column:: + +``` +The value of `WorkerManager.THRESHOLD` is in `0.1s` increments. Therefore, to set it to one minute, you should set the value to `600`. + +This value should be set as early as possible in your application, and should ideally happen in the global scope. Setting it after the main process has started will not work. +``` + +.. column:: + +```` +```python +from sanic.worker.manager import WorkerManager + +WorkerManager.THRESHOLD = 600 +``` +```` + +### Zero downtime restarts + +By default, when restarting workers, Sanic will teardown the existing process first before starting a new one. + +If you are intending to use the restart functionality in production then you may be interested in having zero-downtime reloading. This can be accomplished by forcing the reloader to change the order to start a new process, wait for it to [ack](#worker-ack), and then teardown the old process. + +.. column:: + +``` +From the multiplexer, use the `zero_downtime` argument +``` + +.. column:: + +```` +```python +app.m.restart(zero_downtime=True) +``` +```` + +_Added in v22.12_ + +## Using shared context between worker processes + +Python provides a few methods for [exchanging objects](https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes), [synchronizing](https://docs.python.org/3/library/multiprocessing.html#synchronization-between-processes), and [sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-between-processes) between processes. This usually involves objects from the `multiprocessing` and `ctypes` modules. + +If you are familiar with these objects and how to work with them, you will be happy to know that Sanic provides an API for sharing these objects between your worker processes. If you are not familiar, you are encouraged to read through the Python documentation linked above and try some of the examples before proceeding with implementing shared context. + +Similar to how [application context](../basics/app.md#application-context) allows an applicaiton to share state across the lifetime of the application with `app.ctx`, shared context provides the same for the special objects mentioned above. This context is available as `app.shared_ctx` and should **ONLY** be used to share objects intended for this purpose. + +The `shared_ctx` will: + +- _NOT_ share regular objects like `int`, `dict`, or `list` +- _NOT_ share state between Sanic instances running on different machines +- _NOT_ share state to non-worker processes +- **only** share state between server workers managed by the same Manager + +Attaching an inappropriate object to `shared_ctx` will likely result in a warning, and not an error. You should be careful to not accidentally add an unsafe object to `shared_ctx` as it may not work as expected. If you are directed here because of one of those warnings, you might have accidentally used an unsafe object in `shared_ctx`. + +.. column:: + +``` +In order to create a shared object you **must** create it in the main process and attach it inside of the `main_process_start` listener. +``` + +.. column:: + +```` +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` +```` + +Trying to attach to the `shared_ctx` object outside of this listener may result in a `RuntimeError`. + +.. column:: + +``` +After creating the objects in the `main_process_start` listener and attaching to the `shared_ctx`, they will be available in your workers wherever the application instance is available (example: listeners, middleware, request handlers). +``` + +.. column:: + +```` +```python +from multiprocessing import Queue + +@app.get("") +async def handler(request): + request.app.shared_ctx.queue.put(1) + ... +``` +```` + +## Access to the multiplexer + +The application instance has access to an object that provides access to interacting with the Manager and other worker processes. The object is attached as the `app.multiplexer` property, but it is more easily accessed by its alias: `app.m`. + +.. column:: + +``` +For example, you can get access to the current worker state. +``` + +.. column:: + +```` +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.name) + print(request.app.m.pid) + print(request.app.m.state) +``` +``` +Sanic-Server-0-0 +99999 +{'server': True, 'state': 'ACKED', 'pid': 99999, 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), 'starts': 2, 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc)} +``` +```` + +.. column:: + +``` +The `multiplexer` also has access to terminate the Manager, or restart worker processes +``` + +.. column:: + +```` +```python +# shutdown the entire application and all processes +app.m.name.terminate() + +# restart the current worker only +app.m.name.restart() + +# restart specific workers only (comma delimited) +app.m.name.restart("Sanic-Server-4-0,Sanic-Server-7-0") + +# restart ALL workers +app.m.name.restart(all_workers=True) # Available v22.12+ +``` +```` + +## Worker state + +.. column:: + +``` +As shown above, the `multiplexer` has access to report upon the state of the current running worker. However, it also contains the state for ALL processes running. +``` + +.. column:: + +```` +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.workers) +``` +``` +{ + 'Sanic-Main': {'pid': 99997}, + 'Sanic-Server-0-0': { + 'server': True, + 'state': 'ACKED', + 'pid': 9999, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 2, + 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc) + }, + 'Sanic-Reloader-0': { + 'server': False, + 'state': 'STARTED', + 'pid': 99998, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 1 + } +} +``` +```` + +The possible states are: + +- `NONE` - The worker has been created, but there is no process yet +- `IDLE` - The process has been created, but is not running yet +- `STARTING` - The process is starting +- `STARTED` - The process has started +- `ACKED` - The process has started and sent an acknowledgement (usually only for server processes) +- `JOINED` - The process has exited and joined the main process +- `TERMINATED` - The process has exited and terminated +- `RESTARTING` - The process is restarting +- `FAILED` - The process encountered an exception and is no longer running +- `COMPLETED` - The process has completed its work and exited successfully + +## Built-in non-server processes + +As mentioned, the Manager also has the ability to run non-server processes. Sanic comes with two built-in types of non-server processes, and allows for [creating custom processes](#running-custom-processes). + +The two built-in processes are + +- the [auto-reloader](./development.md#automatic-reloader), optionally enabled to watch the file system for changes and trigger a restart +- [inspector](#inspector), optionally enabled to provide external access to the state of the running instance + +## Inspector + +Sanic has the ability to expose the state and the functionality of the `multiplexer` to the CLI. Currently, this requires the CLI command to be run on the same machine as the running Sanic instance. By default the inspector is disabled. + +.. column:: + +``` +To enable it, set the config value to `True`. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR = True +``` +```` + +You will now have access to execute any of these CLI commands: + +``` +sanic inspect reload Trigger a reload of the server workers +sanic inspect shutdown Shutdown the application and all processes +sanic inspect scale N Scale the number of workers to N +sanic inspect Run a custom command +``` + +![](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) + +.. column:: + +``` +This works by exposing a small HTTP service on your machine. You can control the location using configuration values: +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_HOST = "localhost" +app.config.INSPECTOR_PORT = 6457 +``` +```` + +[Learn more](./inspector.md) to find out what is possible with the Inspector. + +## Running custom processes + +To run a managed custom process on Sanic, you must create a callable. If that process is meant to be long-running, then it should handle a shutdown call by a `SIGINT` or `SIGTERM` signal. + +.. column:: + +``` +The simplest method for doing that in Python will be to just wrap your loop in `KeyboardInterrupt`. + +If you intend to run another application, like a bot, then it is likely that it already has capability to handle this signal and you likely do not need to do anything. +``` + +.. column:: + +```` +```python +from time import sleep + +def my_process(foo): + try: + while True: + sleep(1) + except KeyboardInterrupt: + print("done") +``` +```` + +.. column:: + +``` +That callable must be registered in the `main_process_ready` listener. It is important to note that is is **NOT** the same location that you should register [shared context](#using-shared-context-between-worker-processes) objects. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): +# app.manager.manage(, , ) + app.manager.manage("MyProcess", my_process, {"foo": "bar"}) +``` +```` + +### Transient v. durable processes + +.. column:: + +``` +When you manage a process with the `manage` method, you have the option to make it transient or durable. A transient process will be restarted by the auto-reloader, and a durable process will not. + +By default, all processes are durable. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + transient=True, + ) +``` +```` + +### Tracked v. untracked processes + +.. new:: v23.12 + +``` +Out of the box, Sanic will track the state of all processes. This means that you can access the state of the process from the [multiplexer](./manager#access-to-the-multiplexer) object, or from the [Inspector](./manager#inspector). + +See [worker state](./manager#worker-state) for more information. + +Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. +``` + +.. column:: + +``` +When you are running a non-long-running process, you can opt out of tracking it by setting `tracked=False` in the `manage` method. This means that upon completion of the process it will be removed from the list of tracked processes. You will only be able to check the state of the process while it is running. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "OneAndDone", + do_once, + {}, + tracked=False, + ) +``` +```` + +_Added in v23.12_ + +### Restartable custom processes + +.. new:: v23.12 + +``` +A custom process that is transient will **always** be restartable. That means the auto-restart will work as expected. However, what if you want to be able to *manually* restart a process, but not have it be restarted by the auto-reloader? +``` + +.. column:: + +``` +In this scenario, you can set `restartable=True` in the `manage` method. This will allow you to manually restart the process, but it will not be restarted by the auto-reloader. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + restartable=True, + ) +``` +```` + +.. column:: + +``` +You could now manually restart that process from the multiplexer. +``` + +.. column:: + +```` +```python +@app.get("/restart") +async def restart_handler(request: Request): + request.app.m.restart("Sanic-MyProcess-0") + return json({"foo": request.app.m.name}) +``` +```` + +_Added in v23.12_ + +### On the fly process management + +.. new:: v23.12 + +``` +Custom processes are usually added in the `main_process_ready` listener. However, there may be times when you want to add a process after the application has started. For example, you may want to add a process from a request handler. The multiplexer provides a method for doing this. +``` + +.. column:: + +``` +Once you have a reference to the multiplexer, you can call `manage` to add a process. It works the same as the `manage` method on the Manager. +``` + +.. column:: + +```` +```python +@app.post("/start") +async def start_handler(request: Request): + request.app.m.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + workers=2, + ) + return json({"foo": request.app.m.name}) +``` +```` + +_Added in v23.12_ + +## Single process mode + +.. column:: + +``` +If you would like to opt out of running multiple processes, you can run Sanic in a single process only. In this case, the Manager will not run. You will also not have access to any features that require processes (auto-reload, the inspector, etc). +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --single-process +``` +```python +if __name__ == "__main__": + app.run(single_process=True) +``` +```python +if __name__ == "__main__": + app.prepare(single_process=True) + Sanic.serve_single() +``` +```` + +## Sanic and multiprocessing + +Sanic makes heavy use of the [`multiprocessing` module](https://docs.python.org/3/library/multiprocessing.html) to manage the worker processes. You should generally avoid lower level usage of this module (like setting the start method) as it may interfere with the functionality of Sanic. + +### Start methods in Python + +Before explaining what Sanic tries to do, it is important to understand what the `start_method` is and why it is important. Python generally allows for three different methods of starting a process: + +- `fork` +- `spawn` +- `forkserver` + +The `fork` and `forkserver` methods are only available on Unix systems, and `spawn` is the only method available on Windows. On Unix systems where you have a choice, `fork` is generally the default system method. + +You are encouraged to read the [Python documentation](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to learn more about the differences between these methods. However, the important thing to know is that `fork` basically copies the entire memory of the parent process into the child process, whereas `spawn` will create a new process and then load the application into that process. This is the reason why you need to nest your Sanic `run` call inside of the `__name__ == "__main__"` block if you are not using the CLI. + +### Sanic and start methods + +By default, Sanic will try and use `spawn` as the start method. This is because it is the only method available on Windows, and it is the safest method on Unix systems. + +.. column:: + +``` +However, if you are running Sanic on a Unix system and you would like to use `fork` instead, you can do so by setting the `start_method` on the `Sanic` class. You will want to do this as early as possible in your application, and ideally in the global scope before you import any other modules. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +### Overcoming a `RuntimeError` + +You might have received a `RuntimeError` that looks like this: + +``` +RuntimeError: Start method 'spawn' was requested, but 'fork' was already set. +``` + +If so, that means somewhere in your application you are trying to set the start method that conflicts with what Sanic is trying to do. You have a few options to resolve this: + +.. column:: + +``` +**OPTION 1:** You can tell Sanic that the start method has been set and to not try and set it again. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.START_METHOD_SET = True +``` +```` + +.. column:: + +``` +**OPTION 2:** You could tell Sanic that you intend to use `fork` and to not try and set it to `spawn`. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +.. column:: + +``` +**OPTION 3:** You can tell Python to use `spawn` instead of `fork` by setting the `multiprocessing` start method. +``` + +.. column:: + +```` +```python +import multiprocessing + +multiprocessing.set_start_method("spawn") +``` +```` + +In any of these options, you should run this code as early as possible in your application. Depending upon exactly what your specific scenario is, you may need to combine some of the options. + +.. note:: + +```` +The potential issues that arise from this problem are usually easily solved by just allowing Sanic to be in charge of multiprocessing. This usually means making use of the `main_process_start` and `main_process_ready` listeners to deal with multiprocessing issues. For example, you should move instantiating multiprocessing primitives that do a lot of work under the hood from the global scope and into a listener. + +```python +# This is BAD; avoid the global scope +from multiprocessing import Queue + +q = Queue() +``` + +```python +# This is GOOD; the queue is made in a listener and shared to all the processes on the shared_ctx +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.q = Queue() +``` +```` From f9a1143bb8c966ee90cd1d11f396335271df9e03 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:44 +0200 Subject: [PATCH 153/698] New translations manager.md (Chinese Simplified) --- guide/content/zh/guide/running/manager.md | 669 ++++++++++++++++++++++ 1 file changed, 669 insertions(+) create mode 100644 guide/content/zh/guide/running/manager.md diff --git a/guide/content/zh/guide/running/manager.md b/guide/content/zh/guide/running/manager.md new file mode 100644 index 0000000000..b71685420e --- /dev/null +++ b/guide/content/zh/guide/running/manager.md @@ -0,0 +1,669 @@ +--- +title: Worker Manager +--- + +# Worker Manager + +The worker manager and its functionality was introduced in version 22.9. + +_The details of this section are intended for more advanced usages and **not** necessary to get started._ + +The purpose of the manager is to create consistency and flexibility between development and production environments. Whether you intend to run a single worker, or multiple workers, whether with, or without auto-reload: the experience will be the same. + +In general it looks like this: + +![](https://user-images.githubusercontent.com/166269/178677618-3b4089c3-6c6a-4ecc-8d7a-7eba2a7f29b0.png) + +When you run Sanic, the main process instantiates a `WorkerManager`. That manager is in charge of running one or more `WorkerProcess`. There generally are two kinds of processes: + +- server processes, and +- non-server processes. + +For the sake of ease, the User Guide generally will use the term "worker" or "worker process" to mean a server process, and "Manager" to mean the single worker manager running in your main process. + +## How Sanic Server starts processes + +Sanic will start processes using the [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) start method. This means that for every process/worker, the global scope of your application will be run on its own thread. The practical impact of this that _if_ you do not run Sanic with the CLI, you will need to nest the execution code inside a block to make sure it only runs on `__main__`. + +```python +if __name__ == "__main__": + app.run() +``` + +If you do not, you are likely to see an error message like this: + +``` +sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. + +This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. + +See more information: https://sanic.dev/en/guide/deployment/manager.html#how-sanic-server-starts-processes +``` + +The likely fix for this problem is nesting your Sanic run call inside of the `__name__ == "__main__"` block. If you continue to receive this message after nesting, or if you see this while using the CLI, then it means the port you are trying to use is not available on your machine and you must select another port. + +### Starting a worker + +All worker processes _must_ send an acknowledgement when starting. This happens under the hood, and you as a developer do not need to do anything. However, the Manager will exit with a status code `1` if one or more workers do not send that `ack` message, or a worker process throws an exception while trying to start. If no exceptions are encountered, the Manager will wait for up to thirty (30) seconds for the acknowledgement. + +.. column:: + +``` +In the situation when you know that you will need more time to start, you can monkeypatch the Manager. The threshold does not include anything inside of a listener, and is limited to the execution time of everything in the global scope of your application. + +If you run into this issue, it may indicate a need to look deeper into what is causing the slow startup. +``` + +.. column:: + +```` +```python +from sanic.worker.manager import WorkerManager + +WorkerManager.THRESHOLD = 100 # Value is in 0.1s +``` +```` + +See [worker ack](#worker-ack) for more information. + +.. column:: + +``` +As stated above, Sanic will use [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to start worker processes. If you would like to change this behavior and are aware of the implications of using different start methods, you can modify as shown here. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +### Worker ack + +When all of your workers are running in a subprocess a potential problem is created: deadlock. This can occur when the child processes cease to function, but the main process is unaware that this happened. Therefore, Sanic servers will automatically send an `ack` message (short for acknowledge) to the main process after startup. + +In version 22.9, the `ack` timeout was short and limited to `5s`. In version 22.12, the timeout was lengthened to `30s`. If your application is shutting down after thirty seconds then it might be necessary to manually increase this threshhold. + +.. column:: + +``` +The value of `WorkerManager.THRESHOLD` is in `0.1s` increments. Therefore, to set it to one minute, you should set the value to `600`. + +This value should be set as early as possible in your application, and should ideally happen in the global scope. Setting it after the main process has started will not work. +``` + +.. column:: + +```` +```python +from sanic.worker.manager import WorkerManager + +WorkerManager.THRESHOLD = 600 +``` +```` + +### Zero downtime restarts + +By default, when restarting workers, Sanic will teardown the existing process first before starting a new one. + +If you are intending to use the restart functionality in production then you may be interested in having zero-downtime reloading. This can be accomplished by forcing the reloader to change the order to start a new process, wait for it to [ack](#worker-ack), and then teardown the old process. + +.. column:: + +``` +From the multiplexer, use the `zero_downtime` argument +``` + +.. column:: + +```` +```python +app.m.restart(zero_downtime=True) +``` +```` + +_Added in v22.12_ + +## Using shared context between worker processes + +Python provides a few methods for [exchanging objects](https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes), [synchronizing](https://docs.python.org/3/library/multiprocessing.html#synchronization-between-processes), and [sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-between-processes) between processes. This usually involves objects from the `multiprocessing` and `ctypes` modules. + +If you are familiar with these objects and how to work with them, you will be happy to know that Sanic provides an API for sharing these objects between your worker processes. If you are not familiar, you are encouraged to read through the Python documentation linked above and try some of the examples before proceeding with implementing shared context. + +Similar to how [application context](../basics/app.md#application-context) allows an applicaiton to share state across the lifetime of the application with `app.ctx`, shared context provides the same for the special objects mentioned above. This context is available as `app.shared_ctx` and should **ONLY** be used to share objects intended for this purpose. + +The `shared_ctx` will: + +- _NOT_ share regular objects like `int`, `dict`, or `list` +- _NOT_ share state between Sanic instances running on different machines +- _NOT_ share state to non-worker processes +- **only** share state between server workers managed by the same Manager + +Attaching an inappropriate object to `shared_ctx` will likely result in a warning, and not an error. You should be careful to not accidentally add an unsafe object to `shared_ctx` as it may not work as expected. If you are directed here because of one of those warnings, you might have accidentally used an unsafe object in `shared_ctx`. + +.. column:: + +``` +In order to create a shared object you **must** create it in the main process and attach it inside of the `main_process_start` listener. +``` + +.. column:: + +```` +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` +```` + +Trying to attach to the `shared_ctx` object outside of this listener may result in a `RuntimeError`. + +.. column:: + +``` +After creating the objects in the `main_process_start` listener and attaching to the `shared_ctx`, they will be available in your workers wherever the application instance is available (example: listeners, middleware, request handlers). +``` + +.. column:: + +```` +```python +from multiprocessing import Queue + +@app.get("") +async def handler(request): + request.app.shared_ctx.queue.put(1) + ... +``` +```` + +## Access to the multiplexer + +The application instance has access to an object that provides access to interacting with the Manager and other worker processes. The object is attached as the `app.multiplexer` property, but it is more easily accessed by its alias: `app.m`. + +.. column:: + +``` +For example, you can get access to the current worker state. +``` + +.. column:: + +```` +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.name) + print(request.app.m.pid) + print(request.app.m.state) +``` +``` +Sanic-Server-0-0 +99999 +{'server': True, 'state': 'ACKED', 'pid': 99999, 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), 'starts': 2, 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc)} +``` +```` + +.. column:: + +``` +The `multiplexer` also has access to terminate the Manager, or restart worker processes +``` + +.. column:: + +```` +```python +# shutdown the entire application and all processes +app.m.name.terminate() + +# restart the current worker only +app.m.name.restart() + +# restart specific workers only (comma delimited) +app.m.name.restart("Sanic-Server-4-0,Sanic-Server-7-0") + +# restart ALL workers +app.m.name.restart(all_workers=True) # Available v22.12+ +``` +```` + +## Worker state + +.. column:: + +``` +As shown above, the `multiplexer` has access to report upon the state of the current running worker. However, it also contains the state for ALL processes running. +``` + +.. column:: + +```` +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.workers) +``` +``` +{ + 'Sanic-Main': {'pid': 99997}, + 'Sanic-Server-0-0': { + 'server': True, + 'state': 'ACKED', + 'pid': 9999, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 2, + 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc) + }, + 'Sanic-Reloader-0': { + 'server': False, + 'state': 'STARTED', + 'pid': 99998, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 1 + } +} +``` +```` + +The possible states are: + +- `NONE` - The worker has been created, but there is no process yet +- `IDLE` - The process has been created, but is not running yet +- `STARTING` - The process is starting +- `STARTED` - The process has started +- `ACKED` - The process has started and sent an acknowledgement (usually only for server processes) +- `JOINED` - The process has exited and joined the main process +- `TERMINATED` - The process has exited and terminated +- `RESTARTING` - The process is restarting +- `FAILED` - The process encountered an exception and is no longer running +- `COMPLETED` - The process has completed its work and exited successfully + +## Built-in non-server processes + +As mentioned, the Manager also has the ability to run non-server processes. Sanic comes with two built-in types of non-server processes, and allows for [creating custom processes](#running-custom-processes). + +The two built-in processes are + +- the [auto-reloader](./development.md#automatic-reloader), optionally enabled to watch the file system for changes and trigger a restart +- [inspector](#inspector), optionally enabled to provide external access to the state of the running instance + +## Inspector + +Sanic has the ability to expose the state and the functionality of the `multiplexer` to the CLI. Currently, this requires the CLI command to be run on the same machine as the running Sanic instance. By default the inspector is disabled. + +.. column:: + +``` +To enable it, set the config value to `True`. +``` + +.. column:: + +```` +```python +app.config.INSPECTOR = True +``` +```` + +You will now have access to execute any of these CLI commands: + +``` +sanic inspect reload Trigger a reload of the server workers +sanic inspect shutdown Shutdown the application and all processes +sanic inspect scale N Scale the number of workers to N +sanic inspect Run a custom command +``` + +![](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) + +.. column:: + +``` +This works by exposing a small HTTP service on your machine. You can control the location using configuration values: +``` + +.. column:: + +```` +```python +app.config.INSPECTOR_HOST = "localhost" +app.config.INSPECTOR_PORT = 6457 +``` +```` + +[Learn more](./inspector.md) to find out what is possible with the Inspector. + +## Running custom processes + +To run a managed custom process on Sanic, you must create a callable. If that process is meant to be long-running, then it should handle a shutdown call by a `SIGINT` or `SIGTERM` signal. + +.. column:: + +``` +The simplest method for doing that in Python will be to just wrap your loop in `KeyboardInterrupt`. + +If you intend to run another application, like a bot, then it is likely that it already has capability to handle this signal and you likely do not need to do anything. +``` + +.. column:: + +```` +```python +from time import sleep + +def my_process(foo): + try: + while True: + sleep(1) + except KeyboardInterrupt: + print("done") +``` +```` + +.. column:: + +``` +That callable must be registered in the `main_process_ready` listener. It is important to note that is is **NOT** the same location that you should register [shared context](#using-shared-context-between-worker-processes) objects. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): +# app.manager.manage(, , ) + app.manager.manage("MyProcess", my_process, {"foo": "bar"}) +``` +```` + +### Transient v. durable processes + +.. column:: + +``` +When you manage a process with the `manage` method, you have the option to make it transient or durable. A transient process will be restarted by the auto-reloader, and a durable process will not. + +By default, all processes are durable. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + transient=True, + ) +``` +```` + +### Tracked v. untracked processes + +.. new:: v23.12 + +``` +Out of the box, Sanic will track the state of all processes. This means that you can access the state of the process from the [multiplexer](./manager#access-to-the-multiplexer) object, or from the [Inspector](./manager#inspector). + +See [worker state](./manager#worker-state) for more information. + +Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. +``` + +.. column:: + +``` +When you are running a non-long-running process, you can opt out of tracking it by setting `tracked=False` in the `manage` method. This means that upon completion of the process it will be removed from the list of tracked processes. You will only be able to check the state of the process while it is running. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "OneAndDone", + do_once, + {}, + tracked=False, + ) +``` +```` + +_Added in v23.12_ + +### Restartable custom processes + +.. new:: v23.12 + +``` +A custom process that is transient will **always** be restartable. That means the auto-restart will work as expected. However, what if you want to be able to *manually* restart a process, but not have it be restarted by the auto-reloader? +``` + +.. column:: + +``` +In this scenario, you can set `restartable=True` in the `manage` method. This will allow you to manually restart the process, but it will not be restarted by the auto-reloader. +``` + +.. column:: + +```` +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + restartable=True, + ) +``` +```` + +.. column:: + +``` +You could now manually restart that process from the multiplexer. +``` + +.. column:: + +```` +```python +@app.get("/restart") +async def restart_handler(request: Request): + request.app.m.restart("Sanic-MyProcess-0") + return json({"foo": request.app.m.name}) +``` +```` + +_Added in v23.12_ + +### On the fly process management + +.. new:: v23.12 + +``` +Custom processes are usually added in the `main_process_ready` listener. However, there may be times when you want to add a process after the application has started. For example, you may want to add a process from a request handler. The multiplexer provides a method for doing this. +``` + +.. column:: + +``` +Once you have a reference to the multiplexer, you can call `manage` to add a process. It works the same as the `manage` method on the Manager. +``` + +.. column:: + +```` +```python +@app.post("/start") +async def start_handler(request: Request): + request.app.m.manage( + "MyProcess", + my_process, + {"foo": "bar"}, + workers=2, + ) + return json({"foo": request.app.m.name}) +``` +```` + +_Added in v23.12_ + +## Single process mode + +.. column:: + +``` +If you would like to opt out of running multiple processes, you can run Sanic in a single process only. In this case, the Manager will not run. You will also not have access to any features that require processes (auto-reload, the inspector, etc). +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --single-process +``` +```python +if __name__ == "__main__": + app.run(single_process=True) +``` +```python +if __name__ == "__main__": + app.prepare(single_process=True) + Sanic.serve_single() +``` +```` + +## Sanic and multiprocessing + +Sanic makes heavy use of the [`multiprocessing` module](https://docs.python.org/3/library/multiprocessing.html) to manage the worker processes. You should generally avoid lower level usage of this module (like setting the start method) as it may interfere with the functionality of Sanic. + +### Start methods in Python + +Before explaining what Sanic tries to do, it is important to understand what the `start_method` is and why it is important. Python generally allows for three different methods of starting a process: + +- `fork` +- `spawn` +- `forkserver` + +The `fork` and `forkserver` methods are only available on Unix systems, and `spawn` is the only method available on Windows. On Unix systems where you have a choice, `fork` is generally the default system method. + +You are encouraged to read the [Python documentation](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to learn more about the differences between these methods. However, the important thing to know is that `fork` basically copies the entire memory of the parent process into the child process, whereas `spawn` will create a new process and then load the application into that process. This is the reason why you need to nest your Sanic `run` call inside of the `__name__ == "__main__"` block if you are not using the CLI. + +### Sanic and start methods + +By default, Sanic will try and use `spawn` as the start method. This is because it is the only method available on Windows, and it is the safest method on Unix systems. + +.. column:: + +``` +However, if you are running Sanic on a Unix system and you would like to use `fork` instead, you can do so by setting the `start_method` on the `Sanic` class. You will want to do this as early as possible in your application, and ideally in the global scope before you import any other modules. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +### Overcoming a `RuntimeError` + +You might have received a `RuntimeError` that looks like this: + +``` +RuntimeError: Start method 'spawn' was requested, but 'fork' was already set. +``` + +If so, that means somewhere in your application you are trying to set the start method that conflicts with what Sanic is trying to do. You have a few options to resolve this: + +.. column:: + +``` +**OPTION 1:** You can tell Sanic that the start method has been set and to not try and set it again. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.START_METHOD_SET = True +``` +```` + +.. column:: + +``` +**OPTION 2:** You could tell Sanic that you intend to use `fork` and to not try and set it to `spawn`. +``` + +.. column:: + +```` +```python +from sanic import Sanic + +Sanic.start_method = "fork" +``` +```` + +.. column:: + +``` +**OPTION 3:** You can tell Python to use `spawn` instead of `fork` by setting the `multiprocessing` start method. +``` + +.. column:: + +```` +```python +import multiprocessing + +multiprocessing.set_start_method("spawn") +``` +```` + +In any of these options, you should run this code as early as possible in your application. Depending upon exactly what your specific scenario is, you may need to combine some of the options. + +.. note:: + +```` +The potential issues that arise from this problem are usually easily solved by just allowing Sanic to be in charge of multiprocessing. This usually means making use of the `main_process_start` and `main_process_ready` listeners to deal with multiprocessing issues. For example, you should move instantiating multiprocessing primitives that do a lot of work under the hood from the global scope and into a listener. + +```python +# This is BAD; avoid the global scope +from multiprocessing import Queue + +q = Queue() +``` + +```python +# This is GOOD; the queue is made in a listener and shared to all the processes on the shared_ctx +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.q = Queue() +``` +```` From 433417244632a5823b4a582ba53c7de71dc5e060 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:45 +0200 Subject: [PATCH 154/698] New translations running.md (Japanese) --- guide/content/ja/guide/running/running.md | 585 ++++++++++++++++++++++ 1 file changed, 585 insertions(+) create mode 100644 guide/content/ja/guide/running/running.md diff --git a/guide/content/ja/guide/running/running.md b/guide/content/ja/guide/running/running.md new file mode 100644 index 0000000000..4be2300da5 --- /dev/null +++ b/guide/content/ja/guide/running/running.md @@ -0,0 +1,585 @@ +--- +title: Running Sanic +--- + +# Running Sanic + +Sanic ships with its own internal web server. Under most circumstances, this is the preferred method for deployment. In addition, you can also deploy Sanic as an ASGI app bundled with an ASGI-able web server. + +## Sanic Server + +The main way to run Sanic is to use the included [CLI](#sanic-cli). + +```sh +sanic path.to.server:app +``` + +In this example, Sanic is instructed to look for a python module called `path.to.server`. Inside of that module, it will look for a global variable called `app`, which should be an instance of `Sanic(...)`. + +```python +# ./path/to/server.py +from sanic import Sanic, Request, json + +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + return json({"foo": "bar"}) +``` + +You may also dropdown to the [lower level API](#low-level-apprun) to call `app.run` as a script. However, if you choose this option you should be more comfortable handling issues that may arise with `multiprocessing`. + +### Workers + +.. column:: + +``` +By default, Sanic runs a main process and a single worker process (see [worker manager](./manager.md) for more details). + +To crank up the juice, just specify the number of workers in the run arguments. +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --workers=4 +``` +```` + +Sanic will automatically spin up multiple processes and route traffic between them. We recommend as many workers as you have available processors. + +.. column:: + +``` +The easiest way to get the maximum CPU performance is to use the `--fast` option. This will automatically run the maximum number of workers given the system constraints. + +*Added in v21.12* +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --fast +``` +```` + +In version 22.9, Sanic introduced a new worker manager to provide more consistency and flexibility between development and production servers. Read [about the manager](./manager.md) for more details about workers. + +.. column:: + +``` +If you only want to run Sanic with a single process, specify `single_process` in the run arguments. This means that auto-reload, and the worker manager will be unavailable. + +*Added in v22.9* +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --single-process +``` +```` + +### Running via command + +#### Sanic CLI + +Use `sanic --help` to see all the options. + +.. attrs:: +:title: Sanic CLI help output +:class: details + +```` +```text +$ sanic --help + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + + To start running a Sanic application, provide a path to the module, where + app is a Sanic() instance: + + $ sanic path.to.server:app + + Or, a path to a callable that returns a Sanic() instance: + + $ sanic path.to.factory:create_app --factory + + Or, a path to a directory to run as a simple HTTP server: + + $ sanic ./path/to/static --simple + +Required +======== + Positional: + module Path to your Sanic app. Example: path.to.server:app + If running a Simple Server, path to directory to serve. Example: ./ + +Optional +======== + General: + -h, --help show this help message and exit + --version show program's version number and exit + + Application: + --factory Treat app as an application factory, i.e. a () -> callable + -s, --simple Run Sanic as a Simple Server, and serve the contents of a directory + (module arg should be a path) + --inspect Inspect the state of a running instance, human readable + --inspect-raw Inspect the state of a running instance, JSON output + --trigger-reload Trigger worker processes to reload + --trigger-shutdown Trigger all processes to shutdown + + HTTP version: + --http {1,3} Which HTTP version to use: HTTP/1.1 or HTTP/3. Value should + be either 1, or 3. [default 1] + -1 Run Sanic server using HTTP/1.1 + -3 Run Sanic server using HTTP/3 + + Socket binding: + -H HOST, --host HOST + Host address [default 127.0.0.1] + -p PORT, --port PORT + Port to serve on [default 8000] + -u UNIX, --unix UNIX + location of unix socket + + TLS certificate: + --cert CERT Location of fullchain.pem, bundle.crt or equivalent + --key KEY Location of privkey.pem or equivalent .key file + --tls DIR TLS certificate folder with fullchain.pem and privkey.pem + May be specified multiple times to choose multiple certificates + --tls-strict-host Only allow clients that send an SNI matching server certs + + Worker: + -w WORKERS, --workers WORKERS + Number of worker processes [default 1] + --fast Set the number of workers to max allowed + --single-process Do not use multiprocessing, run server in a single process + --legacy Use the legacy server manager + --access-logs Display access logs + --no-access-logs No display access logs + + Development: + --debug Run the server in debug mode + -r, --reload, --auto-reload + Watch source directory for file changes and reload on changes + -R PATH, --reload-dir PATH + Extra directories to watch and reload on changes + -d, --dev debug + auto reload + --auto-tls Create a temporary TLS certificate for local development (requires mkcert or trustme) + + Output: + --coffee Uhm, coffee? + --no-coffee No uhm, coffee? + --motd Show the startup display + --no-motd No show the startup display + -v, --verbosity Control logging noise, eg. -vv or --verbosity=2 [default 0] + --noisy-exceptions Output stack traces for all exceptions + --no-noisy-exceptions + No output stack traces for all exceptions + +``` +```` + +#### As a module + +.. column:: + +``` +Sanic applications can also be called directly as a module. +``` + +.. column:: + +```` +```bash +python -m sanic server.app --host=0.0.0.0 --port=1337 --workers=4 +``` +```` + +#### Using a factory + +A very common solution is to develop your application _not_ as a global variable, but instead using the factory pattern. In this context, "factory" means a function that returns an instance of `Sanic(...)`. + +.. column:: + +``` +Suppose that you have this in your `server.py` +``` + +.. column:: + +```` +```python +from sanic import Sanic + +def create_app() -> Sanic: + app = Sanic("MyApp") + + return app +``` +```` + +.. column:: + +``` +You can run this application now by referencing it in the CLI explicitly as a factory: +``` + +.. column:: + +```` +```sh +sanic server:create_app --factory +``` +Or, explicitly like this: +```sh +sanic "server:create_app()" +``` +Or, implicitly like this: +```sh +sanic server:create_app +``` + +*Implicit command added in v23.3* +```` + +### Low level `app.run` + +When using `app.run` you will just call your Python file like any other script. + +.. column:: + +``` +`app.run` must be properly nested inside of a name-main block. +``` + +.. column:: + +```` +```python +# server.py +app = Sanic("MyApp") + +if __name__ == "__main__": + app.run() +``` +```` + +.. danger:: + +```` +Be *careful* when using this pattern. A very common mistake is to put too much logic inside of the `if __name__ == "__main__":` block. + +🚫 This is a mistake + +```python +from sanic import Sanic +from my.other.module import bp + +app = Sanic("MyApp") + +if __name__ == "__main__": + app.blueprint(bp) + app.run() +``` + +If you do this, your [blueprint](../best-practices/blueprints.md) will not be attached to your application. This is because the `__main__` block will only run on Sanic's main worker process, **NOT** any of its [worker processes](../deployment/manager.md). This goes for anything else that might impact your application (like attaching listeners, signals, middleware, etc). The only safe operations are anything that is meant for the main process, like the `app.main_*` listeners. + +Perhaps something like this is more appropriate: + +```python +from sanic import Sanic +from my.other.module import bp + +app = Sanic("MyApp") + +if __name__ == "__mp_main__": + app.blueprint(bp) +elif __name__ == "__main__": + app.run() +``` +```` + +To use the low-level `run` API, after defining an instance of `sanic.Sanic`, we can call the run method with the following keyword arguments: + +| Parameter | Default | Description | +| :---------------------------------------: | :--------------: | :---------------------------------------------------------------------------------------- | +| **host** | `"127.0.0.1"` | Address to host the server on. | +| **port** | `8000` | Port to host the server on. | +| **unix** | `None` | Unix socket name to host the server on (instead of TCP). | +| **dev** | `False` | Equivalent to `debug=True` and `auto_reload=True`. | +| **debug** | `False` | Enables debug output (slows server). | +| **ssl** | `None` | SSLContext for SSL encryption of worker(s). | +| **sock** | `None` | Socket for the server to accept connections from. | +| **workers** | `1` | Number of worker processes to spawn. Cannot be used with fast. | +| **loop** | `None` | An asyncio-compatible event loop. If none is specified, Sanic creates its own event loop. | +| **protocol** | `HttpProtocol` | Subclass of asyncio.protocol. | +| **version** | `HTTP.VERSION_1` | The HTTP version to use (`HTTP.VERSION_1` or `HTTP.VERSION_3`). | +| **access_log** | `True` | Enables log on handling requests (significantly slows server). | +| **auto_reload** | `None` | Enables auto-reload on the source directory. | +| **reload_dir** | `None` | A path or list of paths to directories the auto-reloader should watch. | +| **noisy_exceptions** | `None` | Whether to set noisy exceptions globally. None means leave as default. | +| **motd** | `True` | Whether to display the startup message. | +| **motd_display** | `None` | A dict with extra key/value information to display in the startup message | +| **fast** | `False` | Whether to maximize worker processes. Cannot be used with workers. | +| **verbosity** | `0` | Level of logging detail. Max is 2. | +| **auto_tls** | `False` | Whether to auto-create a TLS certificate for local development. Not for production. | +| **single_process** | `False` | Whether to run Sanic in a single process. | + +.. column:: + +``` +For example, we can turn off the access log in order to increase performance, and bind to a custom host and port. +``` + +.. column:: + +```` +```python +# server.py +app = Sanic("MyApp") + +if __name__ == "__main__": + app.run(host='0.0.0.0', port=1337, access_log=False) +``` +```` + +.. column:: + +``` +Now, just execute the python script that has `app.run(...)` +``` + +.. column:: + +```` +```sh +python server.py +``` +```` + +For a slightly more advanced implementation, it is good to know that `app.run` will call `app.prepare` and `Sanic.serve` under the hood. + +.. column:: + +``` +Therefore, these are equivalent: +``` + +.. column:: + +```` +```python +if __name__ == "__main__": + app.run(host='0.0.0.0', port=1337, access_log=False) +``` +```python +if __name__ == "__main__": + app.prepare(host='0.0.0.0', port=1337, access_log=False) + Sanic.serve() +``` +```` + +.. column:: + +``` +This can be useful if you need to bind your appliction(s) to multiple ports. +``` + +.. column:: + +```` +```python +if __name__ == "__main__": + app1.prepare(host='0.0.0.0', port=9990) + app1.prepare(host='0.0.0.0', port=9991) + app2.prepare(host='0.0.0.0', port=5555) + Sanic.serve() +``` +```` + +### Sanic Simple Server + +.. column:: + +``` +Sometimes you just have a directory of static files that need to be served. This especially can be handy for quickly standing up a localhost server. Sanic ships with a Simple Server, where you only need to point it at a directory. +``` + +.. column:: + +```` +```sh +sanic ./path/to/dir --simple +``` +```` + +.. column:: + +``` +This could also be paired with auto-reloading. +``` + +.. column:: + +```` +```sh +sanic ./path/to/dir --simple --reload --reload-dir=./path/to/dir +``` +```` + +_Added in v21.6_ + +### HTTP/3 + +Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed to use HTTP/3: + +```sh +pip install sanic aioquic +``` + +```sh +pip install sanic[http3] +``` + +To start HTTP/3, you must explicitly request it when running your application. + +.. column:: + +```` +```sh +sanic path.to.server:app --http=3 +``` + +```sh +sanic path.to.server:app -3 +``` +```` + +.. column:: + +```` +```python +app.run(version=3) +``` +```` + +To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](../release-notes/v22.3.html#application-multi-serve) introduced in v22.3. This will automatically add an [Alt-Svc](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc) header to your HTTP/1.1 requests to let the client know that it is also available as HTTP/3. + +.. column:: + +```` +```sh +sanic path.to.server:app --http=3 --http=1 +``` + +```sh +sanic path.to.server:app -3 -1 +``` +```` + +.. column:: + +```` +```python +app.prepare(version=3) +app.prepare(version=1) +Sanic.serve() +``` +```` + +Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. See [development](./development.md) for more details. + +_Added in v22.6_ + +## ASGI + +Sanic is also ASGI-compliant. This means you can use your preferred ASGI webserver to run Sanic. The three main implementations of ASGI are [Daphne](http://github.com/django/daphne), [Uvicorn](https://www.uvicorn.org/), and [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html). + +.. warning:: + +``` +Daphne does not support the ASGI `lifespan` protocol, and therefore cannot be used to run Sanic. See [Issue #264](https://github.com/django/daphne/issues/264) for more details. +``` + +Follow their documentation for the proper way to run them, but it should look something like: + +```sh +uvicorn myapp:app +``` + +```sh +hypercorn myapp:app +``` + +A couple things to note when using ASGI: + +1. When using the Sanic webserver, websockets will run using the `websockets` package. In ASGI mode, there is no need for this package since websockets are managed in the ASGI server. +2. The ASGI lifespan protocol https\://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. + +### Trio + +Sanic has experimental support for running on Trio with: + +```sh +hypercorn -k trio myapp:app +``` + +## Gunicorn + +[Gunicorn](http://gunicorn.org/) ("Green Unicorn") is a WSGI HTTP Server for UNIX based operating systems. It is a pre-fork worker model ported from Ruby’s Unicorn project. + +In order to run Sanic application with Gunicorn, you need to use it with the adapter from [uvicorn](https://www.uvicorn.org/). Make sure uvicorn is installed and run it with `uvicorn.workers.UvicornWorker` for Gunicorn worker-class argument: + +```sh +gunicorn myapp:app --bind 0.0.0.0:1337 --worker-class uvicorn.workers.UvicornWorker +``` + +See the [Gunicorn Docs](http://docs.gunicorn.org/en/latest/settings.html#max-requests) for more information. + +.. warning:: + +``` +It is generally advised to not use `gunicorn` unless you need it. The Sanic Server is primed for running Sanic in production. Weigh your considerations carefully before making this choice. Gunicorn does provide a lot of configuration options, but it is not the best choice for getting Sanic to run at its fastest. +``` + +## Performance considerations + +.. column:: + +``` +When running in production, make sure you turn off `debug`. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app +``` +```` + +.. column:: + +``` +Sanic will also perform fastest if you turn off `access_log`. + +If you still require access logs, but want to enjoy this performance boost, consider using [Nginx as a proxy](./nginx.md), and letting that handle your access logging. It will be much faster than anything Python can handle. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --no-access-logs +``` +```` From 3d040e20ae14014abfc9e629e57997564767e3b1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:47 +0200 Subject: [PATCH 155/698] New translations running.md (Korean) --- guide/content/ko/guide/running/running.md | 585 ++++++++++++++++++++++ 1 file changed, 585 insertions(+) create mode 100644 guide/content/ko/guide/running/running.md diff --git a/guide/content/ko/guide/running/running.md b/guide/content/ko/guide/running/running.md new file mode 100644 index 0000000000..4be2300da5 --- /dev/null +++ b/guide/content/ko/guide/running/running.md @@ -0,0 +1,585 @@ +--- +title: Running Sanic +--- + +# Running Sanic + +Sanic ships with its own internal web server. Under most circumstances, this is the preferred method for deployment. In addition, you can also deploy Sanic as an ASGI app bundled with an ASGI-able web server. + +## Sanic Server + +The main way to run Sanic is to use the included [CLI](#sanic-cli). + +```sh +sanic path.to.server:app +``` + +In this example, Sanic is instructed to look for a python module called `path.to.server`. Inside of that module, it will look for a global variable called `app`, which should be an instance of `Sanic(...)`. + +```python +# ./path/to/server.py +from sanic import Sanic, Request, json + +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + return json({"foo": "bar"}) +``` + +You may also dropdown to the [lower level API](#low-level-apprun) to call `app.run` as a script. However, if you choose this option you should be more comfortable handling issues that may arise with `multiprocessing`. + +### Workers + +.. column:: + +``` +By default, Sanic runs a main process and a single worker process (see [worker manager](./manager.md) for more details). + +To crank up the juice, just specify the number of workers in the run arguments. +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --workers=4 +``` +```` + +Sanic will automatically spin up multiple processes and route traffic between them. We recommend as many workers as you have available processors. + +.. column:: + +``` +The easiest way to get the maximum CPU performance is to use the `--fast` option. This will automatically run the maximum number of workers given the system constraints. + +*Added in v21.12* +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --fast +``` +```` + +In version 22.9, Sanic introduced a new worker manager to provide more consistency and flexibility between development and production servers. Read [about the manager](./manager.md) for more details about workers. + +.. column:: + +``` +If you only want to run Sanic with a single process, specify `single_process` in the run arguments. This means that auto-reload, and the worker manager will be unavailable. + +*Added in v22.9* +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --single-process +``` +```` + +### Running via command + +#### Sanic CLI + +Use `sanic --help` to see all the options. + +.. attrs:: +:title: Sanic CLI help output +:class: details + +```` +```text +$ sanic --help + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + + To start running a Sanic application, provide a path to the module, where + app is a Sanic() instance: + + $ sanic path.to.server:app + + Or, a path to a callable that returns a Sanic() instance: + + $ sanic path.to.factory:create_app --factory + + Or, a path to a directory to run as a simple HTTP server: + + $ sanic ./path/to/static --simple + +Required +======== + Positional: + module Path to your Sanic app. Example: path.to.server:app + If running a Simple Server, path to directory to serve. Example: ./ + +Optional +======== + General: + -h, --help show this help message and exit + --version show program's version number and exit + + Application: + --factory Treat app as an application factory, i.e. a () -> callable + -s, --simple Run Sanic as a Simple Server, and serve the contents of a directory + (module arg should be a path) + --inspect Inspect the state of a running instance, human readable + --inspect-raw Inspect the state of a running instance, JSON output + --trigger-reload Trigger worker processes to reload + --trigger-shutdown Trigger all processes to shutdown + + HTTP version: + --http {1,3} Which HTTP version to use: HTTP/1.1 or HTTP/3. Value should + be either 1, or 3. [default 1] + -1 Run Sanic server using HTTP/1.1 + -3 Run Sanic server using HTTP/3 + + Socket binding: + -H HOST, --host HOST + Host address [default 127.0.0.1] + -p PORT, --port PORT + Port to serve on [default 8000] + -u UNIX, --unix UNIX + location of unix socket + + TLS certificate: + --cert CERT Location of fullchain.pem, bundle.crt or equivalent + --key KEY Location of privkey.pem or equivalent .key file + --tls DIR TLS certificate folder with fullchain.pem and privkey.pem + May be specified multiple times to choose multiple certificates + --tls-strict-host Only allow clients that send an SNI matching server certs + + Worker: + -w WORKERS, --workers WORKERS + Number of worker processes [default 1] + --fast Set the number of workers to max allowed + --single-process Do not use multiprocessing, run server in a single process + --legacy Use the legacy server manager + --access-logs Display access logs + --no-access-logs No display access logs + + Development: + --debug Run the server in debug mode + -r, --reload, --auto-reload + Watch source directory for file changes and reload on changes + -R PATH, --reload-dir PATH + Extra directories to watch and reload on changes + -d, --dev debug + auto reload + --auto-tls Create a temporary TLS certificate for local development (requires mkcert or trustme) + + Output: + --coffee Uhm, coffee? + --no-coffee No uhm, coffee? + --motd Show the startup display + --no-motd No show the startup display + -v, --verbosity Control logging noise, eg. -vv or --verbosity=2 [default 0] + --noisy-exceptions Output stack traces for all exceptions + --no-noisy-exceptions + No output stack traces for all exceptions + +``` +```` + +#### As a module + +.. column:: + +``` +Sanic applications can also be called directly as a module. +``` + +.. column:: + +```` +```bash +python -m sanic server.app --host=0.0.0.0 --port=1337 --workers=4 +``` +```` + +#### Using a factory + +A very common solution is to develop your application _not_ as a global variable, but instead using the factory pattern. In this context, "factory" means a function that returns an instance of `Sanic(...)`. + +.. column:: + +``` +Suppose that you have this in your `server.py` +``` + +.. column:: + +```` +```python +from sanic import Sanic + +def create_app() -> Sanic: + app = Sanic("MyApp") + + return app +``` +```` + +.. column:: + +``` +You can run this application now by referencing it in the CLI explicitly as a factory: +``` + +.. column:: + +```` +```sh +sanic server:create_app --factory +``` +Or, explicitly like this: +```sh +sanic "server:create_app()" +``` +Or, implicitly like this: +```sh +sanic server:create_app +``` + +*Implicit command added in v23.3* +```` + +### Low level `app.run` + +When using `app.run` you will just call your Python file like any other script. + +.. column:: + +``` +`app.run` must be properly nested inside of a name-main block. +``` + +.. column:: + +```` +```python +# server.py +app = Sanic("MyApp") + +if __name__ == "__main__": + app.run() +``` +```` + +.. danger:: + +```` +Be *careful* when using this pattern. A very common mistake is to put too much logic inside of the `if __name__ == "__main__":` block. + +🚫 This is a mistake + +```python +from sanic import Sanic +from my.other.module import bp + +app = Sanic("MyApp") + +if __name__ == "__main__": + app.blueprint(bp) + app.run() +``` + +If you do this, your [blueprint](../best-practices/blueprints.md) will not be attached to your application. This is because the `__main__` block will only run on Sanic's main worker process, **NOT** any of its [worker processes](../deployment/manager.md). This goes for anything else that might impact your application (like attaching listeners, signals, middleware, etc). The only safe operations are anything that is meant for the main process, like the `app.main_*` listeners. + +Perhaps something like this is more appropriate: + +```python +from sanic import Sanic +from my.other.module import bp + +app = Sanic("MyApp") + +if __name__ == "__mp_main__": + app.blueprint(bp) +elif __name__ == "__main__": + app.run() +``` +```` + +To use the low-level `run` API, after defining an instance of `sanic.Sanic`, we can call the run method with the following keyword arguments: + +| Parameter | Default | Description | +| :---------------------------------------: | :--------------: | :---------------------------------------------------------------------------------------- | +| **host** | `"127.0.0.1"` | Address to host the server on. | +| **port** | `8000` | Port to host the server on. | +| **unix** | `None` | Unix socket name to host the server on (instead of TCP). | +| **dev** | `False` | Equivalent to `debug=True` and `auto_reload=True`. | +| **debug** | `False` | Enables debug output (slows server). | +| **ssl** | `None` | SSLContext for SSL encryption of worker(s). | +| **sock** | `None` | Socket for the server to accept connections from. | +| **workers** | `1` | Number of worker processes to spawn. Cannot be used with fast. | +| **loop** | `None` | An asyncio-compatible event loop. If none is specified, Sanic creates its own event loop. | +| **protocol** | `HttpProtocol` | Subclass of asyncio.protocol. | +| **version** | `HTTP.VERSION_1` | The HTTP version to use (`HTTP.VERSION_1` or `HTTP.VERSION_3`). | +| **access_log** | `True` | Enables log on handling requests (significantly slows server). | +| **auto_reload** | `None` | Enables auto-reload on the source directory. | +| **reload_dir** | `None` | A path or list of paths to directories the auto-reloader should watch. | +| **noisy_exceptions** | `None` | Whether to set noisy exceptions globally. None means leave as default. | +| **motd** | `True` | Whether to display the startup message. | +| **motd_display** | `None` | A dict with extra key/value information to display in the startup message | +| **fast** | `False` | Whether to maximize worker processes. Cannot be used with workers. | +| **verbosity** | `0` | Level of logging detail. Max is 2. | +| **auto_tls** | `False` | Whether to auto-create a TLS certificate for local development. Not for production. | +| **single_process** | `False` | Whether to run Sanic in a single process. | + +.. column:: + +``` +For example, we can turn off the access log in order to increase performance, and bind to a custom host and port. +``` + +.. column:: + +```` +```python +# server.py +app = Sanic("MyApp") + +if __name__ == "__main__": + app.run(host='0.0.0.0', port=1337, access_log=False) +``` +```` + +.. column:: + +``` +Now, just execute the python script that has `app.run(...)` +``` + +.. column:: + +```` +```sh +python server.py +``` +```` + +For a slightly more advanced implementation, it is good to know that `app.run` will call `app.prepare` and `Sanic.serve` under the hood. + +.. column:: + +``` +Therefore, these are equivalent: +``` + +.. column:: + +```` +```python +if __name__ == "__main__": + app.run(host='0.0.0.0', port=1337, access_log=False) +``` +```python +if __name__ == "__main__": + app.prepare(host='0.0.0.0', port=1337, access_log=False) + Sanic.serve() +``` +```` + +.. column:: + +``` +This can be useful if you need to bind your appliction(s) to multiple ports. +``` + +.. column:: + +```` +```python +if __name__ == "__main__": + app1.prepare(host='0.0.0.0', port=9990) + app1.prepare(host='0.0.0.0', port=9991) + app2.prepare(host='0.0.0.0', port=5555) + Sanic.serve() +``` +```` + +### Sanic Simple Server + +.. column:: + +``` +Sometimes you just have a directory of static files that need to be served. This especially can be handy for quickly standing up a localhost server. Sanic ships with a Simple Server, where you only need to point it at a directory. +``` + +.. column:: + +```` +```sh +sanic ./path/to/dir --simple +``` +```` + +.. column:: + +``` +This could also be paired with auto-reloading. +``` + +.. column:: + +```` +```sh +sanic ./path/to/dir --simple --reload --reload-dir=./path/to/dir +``` +```` + +_Added in v21.6_ + +### HTTP/3 + +Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed to use HTTP/3: + +```sh +pip install sanic aioquic +``` + +```sh +pip install sanic[http3] +``` + +To start HTTP/3, you must explicitly request it when running your application. + +.. column:: + +```` +```sh +sanic path.to.server:app --http=3 +``` + +```sh +sanic path.to.server:app -3 +``` +```` + +.. column:: + +```` +```python +app.run(version=3) +``` +```` + +To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](../release-notes/v22.3.html#application-multi-serve) introduced in v22.3. This will automatically add an [Alt-Svc](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc) header to your HTTP/1.1 requests to let the client know that it is also available as HTTP/3. + +.. column:: + +```` +```sh +sanic path.to.server:app --http=3 --http=1 +``` + +```sh +sanic path.to.server:app -3 -1 +``` +```` + +.. column:: + +```` +```python +app.prepare(version=3) +app.prepare(version=1) +Sanic.serve() +``` +```` + +Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. See [development](./development.md) for more details. + +_Added in v22.6_ + +## ASGI + +Sanic is also ASGI-compliant. This means you can use your preferred ASGI webserver to run Sanic. The three main implementations of ASGI are [Daphne](http://github.com/django/daphne), [Uvicorn](https://www.uvicorn.org/), and [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html). + +.. warning:: + +``` +Daphne does not support the ASGI `lifespan` protocol, and therefore cannot be used to run Sanic. See [Issue #264](https://github.com/django/daphne/issues/264) for more details. +``` + +Follow their documentation for the proper way to run them, but it should look something like: + +```sh +uvicorn myapp:app +``` + +```sh +hypercorn myapp:app +``` + +A couple things to note when using ASGI: + +1. When using the Sanic webserver, websockets will run using the `websockets` package. In ASGI mode, there is no need for this package since websockets are managed in the ASGI server. +2. The ASGI lifespan protocol https\://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. + +### Trio + +Sanic has experimental support for running on Trio with: + +```sh +hypercorn -k trio myapp:app +``` + +## Gunicorn + +[Gunicorn](http://gunicorn.org/) ("Green Unicorn") is a WSGI HTTP Server for UNIX based operating systems. It is a pre-fork worker model ported from Ruby’s Unicorn project. + +In order to run Sanic application with Gunicorn, you need to use it with the adapter from [uvicorn](https://www.uvicorn.org/). Make sure uvicorn is installed and run it with `uvicorn.workers.UvicornWorker` for Gunicorn worker-class argument: + +```sh +gunicorn myapp:app --bind 0.0.0.0:1337 --worker-class uvicorn.workers.UvicornWorker +``` + +See the [Gunicorn Docs](http://docs.gunicorn.org/en/latest/settings.html#max-requests) for more information. + +.. warning:: + +``` +It is generally advised to not use `gunicorn` unless you need it. The Sanic Server is primed for running Sanic in production. Weigh your considerations carefully before making this choice. Gunicorn does provide a lot of configuration options, but it is not the best choice for getting Sanic to run at its fastest. +``` + +## Performance considerations + +.. column:: + +``` +When running in production, make sure you turn off `debug`. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app +``` +```` + +.. column:: + +``` +Sanic will also perform fastest if you turn off `access_log`. + +If you still require access logs, but want to enjoy this performance boost, consider using [Nginx as a proxy](./nginx.md), and letting that handle your access logging. It will be much faster than anything Python can handle. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --no-access-logs +``` +```` From 73582341b5089b2439492b3b027e64ee5257d126 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:48 +0200 Subject: [PATCH 156/698] New translations running.md (Chinese Simplified) --- guide/content/zh/guide/running/running.md | 585 ++++++++++++++++++++++ 1 file changed, 585 insertions(+) create mode 100644 guide/content/zh/guide/running/running.md diff --git a/guide/content/zh/guide/running/running.md b/guide/content/zh/guide/running/running.md new file mode 100644 index 0000000000..4be2300da5 --- /dev/null +++ b/guide/content/zh/guide/running/running.md @@ -0,0 +1,585 @@ +--- +title: Running Sanic +--- + +# Running Sanic + +Sanic ships with its own internal web server. Under most circumstances, this is the preferred method for deployment. In addition, you can also deploy Sanic as an ASGI app bundled with an ASGI-able web server. + +## Sanic Server + +The main way to run Sanic is to use the included [CLI](#sanic-cli). + +```sh +sanic path.to.server:app +``` + +In this example, Sanic is instructed to look for a python module called `path.to.server`. Inside of that module, it will look for a global variable called `app`, which should be an instance of `Sanic(...)`. + +```python +# ./path/to/server.py +from sanic import Sanic, Request, json + +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + return json({"foo": "bar"}) +``` + +You may also dropdown to the [lower level API](#low-level-apprun) to call `app.run` as a script. However, if you choose this option you should be more comfortable handling issues that may arise with `multiprocessing`. + +### Workers + +.. column:: + +``` +By default, Sanic runs a main process and a single worker process (see [worker manager](./manager.md) for more details). + +To crank up the juice, just specify the number of workers in the run arguments. +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --workers=4 +``` +```` + +Sanic will automatically spin up multiple processes and route traffic between them. We recommend as many workers as you have available processors. + +.. column:: + +``` +The easiest way to get the maximum CPU performance is to use the `--fast` option. This will automatically run the maximum number of workers given the system constraints. + +*Added in v21.12* +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --fast +``` +```` + +In version 22.9, Sanic introduced a new worker manager to provide more consistency and flexibility between development and production servers. Read [about the manager](./manager.md) for more details about workers. + +.. column:: + +``` +If you only want to run Sanic with a single process, specify `single_process` in the run arguments. This means that auto-reload, and the worker manager will be unavailable. + +*Added in v22.9* +``` + +.. column:: + +```` +```sh +sanic server:app --host=0.0.0.0 --port=1337 --single-process +``` +```` + +### Running via command + +#### Sanic CLI + +Use `sanic --help` to see all the options. + +.. attrs:: +:title: Sanic CLI help output +:class: details + +```` +```text +$ sanic --help + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + + To start running a Sanic application, provide a path to the module, where + app is a Sanic() instance: + + $ sanic path.to.server:app + + Or, a path to a callable that returns a Sanic() instance: + + $ sanic path.to.factory:create_app --factory + + Or, a path to a directory to run as a simple HTTP server: + + $ sanic ./path/to/static --simple + +Required +======== + Positional: + module Path to your Sanic app. Example: path.to.server:app + If running a Simple Server, path to directory to serve. Example: ./ + +Optional +======== + General: + -h, --help show this help message and exit + --version show program's version number and exit + + Application: + --factory Treat app as an application factory, i.e. a () -> callable + -s, --simple Run Sanic as a Simple Server, and serve the contents of a directory + (module arg should be a path) + --inspect Inspect the state of a running instance, human readable + --inspect-raw Inspect the state of a running instance, JSON output + --trigger-reload Trigger worker processes to reload + --trigger-shutdown Trigger all processes to shutdown + + HTTP version: + --http {1,3} Which HTTP version to use: HTTP/1.1 or HTTP/3. Value should + be either 1, or 3. [default 1] + -1 Run Sanic server using HTTP/1.1 + -3 Run Sanic server using HTTP/3 + + Socket binding: + -H HOST, --host HOST + Host address [default 127.0.0.1] + -p PORT, --port PORT + Port to serve on [default 8000] + -u UNIX, --unix UNIX + location of unix socket + + TLS certificate: + --cert CERT Location of fullchain.pem, bundle.crt or equivalent + --key KEY Location of privkey.pem or equivalent .key file + --tls DIR TLS certificate folder with fullchain.pem and privkey.pem + May be specified multiple times to choose multiple certificates + --tls-strict-host Only allow clients that send an SNI matching server certs + + Worker: + -w WORKERS, --workers WORKERS + Number of worker processes [default 1] + --fast Set the number of workers to max allowed + --single-process Do not use multiprocessing, run server in a single process + --legacy Use the legacy server manager + --access-logs Display access logs + --no-access-logs No display access logs + + Development: + --debug Run the server in debug mode + -r, --reload, --auto-reload + Watch source directory for file changes and reload on changes + -R PATH, --reload-dir PATH + Extra directories to watch and reload on changes + -d, --dev debug + auto reload + --auto-tls Create a temporary TLS certificate for local development (requires mkcert or trustme) + + Output: + --coffee Uhm, coffee? + --no-coffee No uhm, coffee? + --motd Show the startup display + --no-motd No show the startup display + -v, --verbosity Control logging noise, eg. -vv or --verbosity=2 [default 0] + --noisy-exceptions Output stack traces for all exceptions + --no-noisy-exceptions + No output stack traces for all exceptions + +``` +```` + +#### As a module + +.. column:: + +``` +Sanic applications can also be called directly as a module. +``` + +.. column:: + +```` +```bash +python -m sanic server.app --host=0.0.0.0 --port=1337 --workers=4 +``` +```` + +#### Using a factory + +A very common solution is to develop your application _not_ as a global variable, but instead using the factory pattern. In this context, "factory" means a function that returns an instance of `Sanic(...)`. + +.. column:: + +``` +Suppose that you have this in your `server.py` +``` + +.. column:: + +```` +```python +from sanic import Sanic + +def create_app() -> Sanic: + app = Sanic("MyApp") + + return app +``` +```` + +.. column:: + +``` +You can run this application now by referencing it in the CLI explicitly as a factory: +``` + +.. column:: + +```` +```sh +sanic server:create_app --factory +``` +Or, explicitly like this: +```sh +sanic "server:create_app()" +``` +Or, implicitly like this: +```sh +sanic server:create_app +``` + +*Implicit command added in v23.3* +```` + +### Low level `app.run` + +When using `app.run` you will just call your Python file like any other script. + +.. column:: + +``` +`app.run` must be properly nested inside of a name-main block. +``` + +.. column:: + +```` +```python +# server.py +app = Sanic("MyApp") + +if __name__ == "__main__": + app.run() +``` +```` + +.. danger:: + +```` +Be *careful* when using this pattern. A very common mistake is to put too much logic inside of the `if __name__ == "__main__":` block. + +🚫 This is a mistake + +```python +from sanic import Sanic +from my.other.module import bp + +app = Sanic("MyApp") + +if __name__ == "__main__": + app.blueprint(bp) + app.run() +``` + +If you do this, your [blueprint](../best-practices/blueprints.md) will not be attached to your application. This is because the `__main__` block will only run on Sanic's main worker process, **NOT** any of its [worker processes](../deployment/manager.md). This goes for anything else that might impact your application (like attaching listeners, signals, middleware, etc). The only safe operations are anything that is meant for the main process, like the `app.main_*` listeners. + +Perhaps something like this is more appropriate: + +```python +from sanic import Sanic +from my.other.module import bp + +app = Sanic("MyApp") + +if __name__ == "__mp_main__": + app.blueprint(bp) +elif __name__ == "__main__": + app.run() +``` +```` + +To use the low-level `run` API, after defining an instance of `sanic.Sanic`, we can call the run method with the following keyword arguments: + +| Parameter | Default | Description | +| :---------------------------------------: | :--------------: | :---------------------------------------------------------------------------------------- | +| **host** | `"127.0.0.1"` | Address to host the server on. | +| **port** | `8000` | Port to host the server on. | +| **unix** | `None` | Unix socket name to host the server on (instead of TCP). | +| **dev** | `False` | Equivalent to `debug=True` and `auto_reload=True`. | +| **debug** | `False` | Enables debug output (slows server). | +| **ssl** | `None` | SSLContext for SSL encryption of worker(s). | +| **sock** | `None` | Socket for the server to accept connections from. | +| **workers** | `1` | Number of worker processes to spawn. Cannot be used with fast. | +| **loop** | `None` | An asyncio-compatible event loop. If none is specified, Sanic creates its own event loop. | +| **protocol** | `HttpProtocol` | Subclass of asyncio.protocol. | +| **version** | `HTTP.VERSION_1` | The HTTP version to use (`HTTP.VERSION_1` or `HTTP.VERSION_3`). | +| **access_log** | `True` | Enables log on handling requests (significantly slows server). | +| **auto_reload** | `None` | Enables auto-reload on the source directory. | +| **reload_dir** | `None` | A path or list of paths to directories the auto-reloader should watch. | +| **noisy_exceptions** | `None` | Whether to set noisy exceptions globally. None means leave as default. | +| **motd** | `True` | Whether to display the startup message. | +| **motd_display** | `None` | A dict with extra key/value information to display in the startup message | +| **fast** | `False` | Whether to maximize worker processes. Cannot be used with workers. | +| **verbosity** | `0` | Level of logging detail. Max is 2. | +| **auto_tls** | `False` | Whether to auto-create a TLS certificate for local development. Not for production. | +| **single_process** | `False` | Whether to run Sanic in a single process. | + +.. column:: + +``` +For example, we can turn off the access log in order to increase performance, and bind to a custom host and port. +``` + +.. column:: + +```` +```python +# server.py +app = Sanic("MyApp") + +if __name__ == "__main__": + app.run(host='0.0.0.0', port=1337, access_log=False) +``` +```` + +.. column:: + +``` +Now, just execute the python script that has `app.run(...)` +``` + +.. column:: + +```` +```sh +python server.py +``` +```` + +For a slightly more advanced implementation, it is good to know that `app.run` will call `app.prepare` and `Sanic.serve` under the hood. + +.. column:: + +``` +Therefore, these are equivalent: +``` + +.. column:: + +```` +```python +if __name__ == "__main__": + app.run(host='0.0.0.0', port=1337, access_log=False) +``` +```python +if __name__ == "__main__": + app.prepare(host='0.0.0.0', port=1337, access_log=False) + Sanic.serve() +``` +```` + +.. column:: + +``` +This can be useful if you need to bind your appliction(s) to multiple ports. +``` + +.. column:: + +```` +```python +if __name__ == "__main__": + app1.prepare(host='0.0.0.0', port=9990) + app1.prepare(host='0.0.0.0', port=9991) + app2.prepare(host='0.0.0.0', port=5555) + Sanic.serve() +``` +```` + +### Sanic Simple Server + +.. column:: + +``` +Sometimes you just have a directory of static files that need to be served. This especially can be handy for quickly standing up a localhost server. Sanic ships with a Simple Server, where you only need to point it at a directory. +``` + +.. column:: + +```` +```sh +sanic ./path/to/dir --simple +``` +```` + +.. column:: + +``` +This could also be paired with auto-reloading. +``` + +.. column:: + +```` +```sh +sanic ./path/to/dir --simple --reload --reload-dir=./path/to/dir +``` +```` + +_Added in v21.6_ + +### HTTP/3 + +Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed to use HTTP/3: + +```sh +pip install sanic aioquic +``` + +```sh +pip install sanic[http3] +``` + +To start HTTP/3, you must explicitly request it when running your application. + +.. column:: + +```` +```sh +sanic path.to.server:app --http=3 +``` + +```sh +sanic path.to.server:app -3 +``` +```` + +.. column:: + +```` +```python +app.run(version=3) +``` +```` + +To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](../release-notes/v22.3.html#application-multi-serve) introduced in v22.3. This will automatically add an [Alt-Svc](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc) header to your HTTP/1.1 requests to let the client know that it is also available as HTTP/3. + +.. column:: + +```` +```sh +sanic path.to.server:app --http=3 --http=1 +``` + +```sh +sanic path.to.server:app -3 -1 +``` +```` + +.. column:: + +```` +```python +app.prepare(version=3) +app.prepare(version=1) +Sanic.serve() +``` +```` + +Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. See [development](./development.md) for more details. + +_Added in v22.6_ + +## ASGI + +Sanic is also ASGI-compliant. This means you can use your preferred ASGI webserver to run Sanic. The three main implementations of ASGI are [Daphne](http://github.com/django/daphne), [Uvicorn](https://www.uvicorn.org/), and [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html). + +.. warning:: + +``` +Daphne does not support the ASGI `lifespan` protocol, and therefore cannot be used to run Sanic. See [Issue #264](https://github.com/django/daphne/issues/264) for more details. +``` + +Follow their documentation for the proper way to run them, but it should look something like: + +```sh +uvicorn myapp:app +``` + +```sh +hypercorn myapp:app +``` + +A couple things to note when using ASGI: + +1. When using the Sanic webserver, websockets will run using the `websockets` package. In ASGI mode, there is no need for this package since websockets are managed in the ASGI server. +2. The ASGI lifespan protocol https\://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. + +### Trio + +Sanic has experimental support for running on Trio with: + +```sh +hypercorn -k trio myapp:app +``` + +## Gunicorn + +[Gunicorn](http://gunicorn.org/) ("Green Unicorn") is a WSGI HTTP Server for UNIX based operating systems. It is a pre-fork worker model ported from Ruby’s Unicorn project. + +In order to run Sanic application with Gunicorn, you need to use it with the adapter from [uvicorn](https://www.uvicorn.org/). Make sure uvicorn is installed and run it with `uvicorn.workers.UvicornWorker` for Gunicorn worker-class argument: + +```sh +gunicorn myapp:app --bind 0.0.0.0:1337 --worker-class uvicorn.workers.UvicornWorker +``` + +See the [Gunicorn Docs](http://docs.gunicorn.org/en/latest/settings.html#max-requests) for more information. + +.. warning:: + +``` +It is generally advised to not use `gunicorn` unless you need it. The Sanic Server is primed for running Sanic in production. Weigh your considerations carefully before making this choice. Gunicorn does provide a lot of configuration options, but it is not the best choice for getting Sanic to run at its fastest. +``` + +## Performance considerations + +.. column:: + +``` +When running in production, make sure you turn off `debug`. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app +``` +```` + +.. column:: + +``` +Sanic will also perform fastest if you turn off `access_log`. + +If you still require access logs, but want to enjoy this performance boost, consider using [Nginx as a proxy](./nginx.md), and letting that handle your access logging. It will be much faster than anything Python can handle. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --no-access-logs +``` +```` From 9d717765f1feb238481de27f4f8d522e62f50845 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:49 +0200 Subject: [PATCH 157/698] New translations help.md (Japanese) --- guide/content/ja/help.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 guide/content/ja/help.md diff --git a/guide/content/ja/help.md b/guide/content/ja/help.md new file mode 100644 index 0000000000..f84355e054 --- /dev/null +++ b/guide/content/ja/help.md @@ -0,0 +1,32 @@ +--- +title: Need some help? +layout: main +--- + +# Need some help? + +As an active community of developers, we try to support each other. If you need some help, try one of the following: + +.. column:: + +``` +### Discord 💬 + +Best place to turn for quick answers and live chat + +`#sanic-support` channel on the [Discord server](https://discord.gg/FARQzAEMAA) +``` + +.. column:: + +``` +### Community Forums 👥 + +Good for sharing snippets of code and longer support queries + +`Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) +``` + +*** + +We also actively monitor the `[sanic]` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic). From 9420c2d49464ce6413a65262eb4de8f72c5ffada Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:50 +0200 Subject: [PATCH 158/698] New translations help.md (Korean) --- guide/content/ko/help.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 guide/content/ko/help.md diff --git a/guide/content/ko/help.md b/guide/content/ko/help.md new file mode 100644 index 0000000000..f84355e054 --- /dev/null +++ b/guide/content/ko/help.md @@ -0,0 +1,32 @@ +--- +title: Need some help? +layout: main +--- + +# Need some help? + +As an active community of developers, we try to support each other. If you need some help, try one of the following: + +.. column:: + +``` +### Discord 💬 + +Best place to turn for quick answers and live chat + +`#sanic-support` channel on the [Discord server](https://discord.gg/FARQzAEMAA) +``` + +.. column:: + +``` +### Community Forums 👥 + +Good for sharing snippets of code and longer support queries + +`Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) +``` + +*** + +We also actively monitor the `[sanic]` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic). From 96fda4f3e6ee2f0e70d32c7fb473ce0880bc099f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:51 +0200 Subject: [PATCH 159/698] New translations help.md (Chinese Simplified) --- guide/content/zh/help.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 guide/content/zh/help.md diff --git a/guide/content/zh/help.md b/guide/content/zh/help.md new file mode 100644 index 0000000000..f84355e054 --- /dev/null +++ b/guide/content/zh/help.md @@ -0,0 +1,32 @@ +--- +title: Need some help? +layout: main +--- + +# Need some help? + +As an active community of developers, we try to support each other. If you need some help, try one of the following: + +.. column:: + +``` +### Discord 💬 + +Best place to turn for quick answers and live chat + +`#sanic-support` channel on the [Discord server](https://discord.gg/FARQzAEMAA) +``` + +.. column:: + +``` +### Community Forums 👥 + +Good for sharing snippets of code and longer support queries + +`Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) +``` + +*** + +We also actively monitor the `[sanic]` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic). From 5541484c4dcf4039750e9dd6a3ef2bc151b240d5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:52 +0200 Subject: [PATCH 160/698] New translations index.md (Japanese) --- guide/content/ja/index.md | 334 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 guide/content/ja/index.md diff --git a/guide/content/ja/index.md b/guide/content/ja/index.md new file mode 100644 index 0000000000..3c09f07788 --- /dev/null +++ b/guide/content/ja/index.md @@ -0,0 +1,334 @@ +--- +title: The lightning-fast asynchronous Python web framework +layout: home +features: + - title: Simple and lightweight + details: Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. + - title: Unopinionated and flexible + details: Build the way you want to build without letting your tooling constrain you. + - title: Performant and scalable + details: Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. + - title: Production ready + details: Out of the box, it comes bundled with a web server ready to power your web applications. + - title: Trusted by millions + details: Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework + - title: Community driven + details: The project is maintained and run by the community for the community. +--- + +### ⚡ The lightning-fast asynchronous Python web framework + +.. attrs:: +:class: columns is-multiline mt-6 + +``` +.. attrs:: + :class: column is-4 + + #### Simple and lightweight + + Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. + +.. attrs:: + :class: column is-4 + + #### Unopinionated and flexible + + Build the way you want to build without letting your tooling constrain you. + +.. attrs:: + :class: column is-4 + + #### Performant and scalable + + Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. + +.. attrs:: + :class: column is-4 + + #### Production ready + + Out of the box, it comes bundled with a web server ready to power your web applications. + +.. attrs:: + :class: column is-4 + + #### Trusted by millions + + Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework + +.. attrs:: + :class: column is-4 + + #### Community driven + + The project is maintained and run by the community for the community. +``` + +.. attrs:: +:class: is-size-3 mt-6 + +``` +**With the features and tools you'd expect.** +``` + +.. attrs:: +:class: is-size-3 ml-6 + +``` +**And some {span:has-text-primary:you wouldn't believe}.** +``` + +.. tab:: Production-grade + +```` +After installing, Sanic has all the tools you need for a scalable, production-grade server—out of the box! + +Including [full TLS support](/en/guide/how-to/tls). + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +```sh +sanic path.to.server:app +[2023-01-31 12:34:56 +0000] [999996] [INFO] Sanic v22.12.0 +[2023-01-31 12:34:56 +0000] [999996] [INFO] Goin' Fast @ http://127.0.0.1:8000 +[2023-01-31 12:34:56 +0000] [999996] [INFO] mode: production, single worker +[2023-01-31 12:34:56 +0000] [999996] [INFO] server: sanic, HTTP/1.1 +[2023-01-31 12:34:56 +0000] [999996] [INFO] python: 3.10.9 +[2023-01-31 12:34:56 +0000] [999996] [INFO] platform: SomeOS-9.8.7 +[2023-01-31 12:34:56 +0000] [999996] [INFO] packages: sanic-routing==22.8.0 +[2023-01-31 12:34:56 +0000] [999997] [INFO] Starting worker [999997] +``` +```` + +.. tab:: TLS server + +```` +Running Sanic with TLS enabled is as simple as passing it the file paths... +```sh +sanic path.to.server:app --cert=/path/to/bundle.crt --key=/path/to/privkey.pem +``` + +... or the a directory containing `fullchain.pem` and `privkey.pem` + +```sh +sanic path.to.server:app --tls=/path/to/certs +``` + +**Even better**, while you are developing, let Sanic handle setting up local TLS certificates so you can access your site over TLS at [https://localhost:8443](https://localhost:8443) + +```sh +sanic path.to.server:app --dev --auto-tls +``` +```` + +.. tab:: Websockets + +```` +Up and running with websockets in no time using the [websockets](https://websockets.readthedocs.io) package. +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` +```` + +.. tab:: Static files + +```` +Serving static files is of course intuitive and easy. Just name an endpoint and either a file or directory that should be served. + +```python +app.static("/", "/path/to/index.html") +app.static("/uploads/", "/path/to/uploads/") +``` + +Moreover, serving a directory has two additional features: automatically serving an index, and automatically serving a file browser. + +Sanic can automatically serve `index.html` (or any other named file) as an index page in a directory or its subdirectories. + +```python +app.static( + "/uploads/", + "/path/to/uploads/", + index="index.html" +) +``` + +And/or, setup Sanic to display a file browser. + + +![image](/assets/images/directory-view.png) + +```python +app.static( + "/uploads/", + "/path/to/uploads/", + directory_view=True +) +``` +```` + +.. tab:: Lifecycle + +```` +Beginning or ending a route with functionality is as simple as adding a decorator. + +```python +@app.on_request +async def add_key(request): + request.ctx.foo = "bar" + +@app.on_response +async def custom_banner(request, response): + response.headers["X-Foo"] = request.ctx.foo +``` + +Same with server events. + +```python +@app.before_server_start +async def setup_db(app): + app.ctx.db_pool = await db_setup() + +@app.after_server_stop +async def setup_db(app): + await app.ctx.db_pool.shutdown() +``` + +But, Sanic also allows you to tie into a bunch of built-in events (called signals), or create and dispatch your own. + +```python +@app.signal("http.lifecycle.complete") # built-in +async def my_signal_handler(conn_info): + print("Connection has been closed") + +@app.signal("something.happened.ohmy") # custom +async def my_signal_handler(): + print("something happened") + +await app.dispatch("something.happened.ohmy") +``` +```` + +.. tab:: Smart error handling + +```` +Raising errors will intuitively result in proper HTTP errors: + +```python +raise sanic.exceptions.NotFound # Automatically responds with HTTP 404 +``` + +Or, make your own: + +```python +from sanic.exceptions import SanicException + +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +And, when an error does happen, Sanic's beautiful DEV mode error page will help you drill down to the bug quickly. + +![image](../assets/images/error-div-by-zero.png) + +Regardless, Sanic comes with an algorithm that attempts to respond with HTML, JSON, or text-based errors as appropriate. Don't worry, it is super easy to setup and customize your error handling to your exact needs. +```` + +.. tab:: App Inspector + +```` +Check in on your live, running applications (whether local or remote). +```sh +sanic inspect + +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Sanic │ +│ Inspecting @ http://localhost:6457 │ +├───────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────┤ +│ │ mode: production, single worker │ +│ ▄███ █████ ██ │ server: unknown │ +│ ██ │ python: 3.10.9 │ +│ ▀███████ ███▄ │ platform: SomeOS-9.8.7 +│ ██ │ packages: sanic==22.12.0, sanic-routing==22.8.0, sanic-testing==22.12.0, sanic-ext==22.12.0 │ +│ ████ ████████▀ │ │ +│ │ │ +│ Build Fast. Run Fast. │ │ +└───────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────┘ + +Sanic-Main + pid: 999996 + +Sanic-Server-0-0 + server: True + state: ACKED + pid: 999997 + start_at: 2023-01-31T12:34:56.00000+00:00 + starts: 1 + +Sanic-Inspector-0 + server: False + state: STARTED + pid: 999998 + start_at: 2023-01-31T12:34:56.00000+00:00 + starts: 1 +``` + +And, issue commands like `reload`, `shutdown`, `scale`... + +```sh +sanic inspect scale 4 +``` + +... or even create your own! + +```sh +sanic inspect migrations +``` +```` + +.. tab:: Extendable + +``` +In addition to the tools that Sanic comes with, the officially supported [Sanic Extensions](./plugins/sanic-ext/getting-started.md) provides lots of extra goodies to make development easier. + +- **CORS** protection +- Template rendering with **Jinja** +- **Dependency injection** into route handlers +- OpenAPI documentation with **Redoc** and/or **Swagger** +- Predefined, endpoint-specific response **serializers** +- Request query arguments and body input **validation** +- **Auto create** HEAD, OPTIONS, and TRACE endpoints +- Live **health monitor** +``` + +.. tab:: Developer Experience + +``` +Sanic is **built for building**. + +From the moment it is installed, Sanic includes helpful tools to help the developer get their job done. + +- **One server** - Develop locally in DEV mode on the same server that will run your PRODUCTION application +- **Auto reload** - Reload running applications every time you save a Python file, but also auto-reload **on any arbitrary directory** like HTML template directories +- **Debugging tools** - Super helpful (and beautiful) [error pages](/en/guide/best-practices/exceptions) that help you traverse the trace stack easily +- **Auto TLS** - Running a localhost website with `https` can be difficult, [Sanic makes it easy](/en/guide/how-to/tls) +- **Streamlined testing** - Built-in testing capabilities, making it easier for developers to create and run tests, ensuring the quality and reliability of their services +- **Modern Python** - Thoughtful use of type hints to help the developer IDE experience +``` From 8eefe19c08f99de0b0051bfac5f68b064222f08c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:53 +0200 Subject: [PATCH 161/698] New translations index.md (Korean) --- guide/content/ko/index.md | 334 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 guide/content/ko/index.md diff --git a/guide/content/ko/index.md b/guide/content/ko/index.md new file mode 100644 index 0000000000..3c09f07788 --- /dev/null +++ b/guide/content/ko/index.md @@ -0,0 +1,334 @@ +--- +title: The lightning-fast asynchronous Python web framework +layout: home +features: + - title: Simple and lightweight + details: Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. + - title: Unopinionated and flexible + details: Build the way you want to build without letting your tooling constrain you. + - title: Performant and scalable + details: Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. + - title: Production ready + details: Out of the box, it comes bundled with a web server ready to power your web applications. + - title: Trusted by millions + details: Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework + - title: Community driven + details: The project is maintained and run by the community for the community. +--- + +### ⚡ The lightning-fast asynchronous Python web framework + +.. attrs:: +:class: columns is-multiline mt-6 + +``` +.. attrs:: + :class: column is-4 + + #### Simple and lightweight + + Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. + +.. attrs:: + :class: column is-4 + + #### Unopinionated and flexible + + Build the way you want to build without letting your tooling constrain you. + +.. attrs:: + :class: column is-4 + + #### Performant and scalable + + Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. + +.. attrs:: + :class: column is-4 + + #### Production ready + + Out of the box, it comes bundled with a web server ready to power your web applications. + +.. attrs:: + :class: column is-4 + + #### Trusted by millions + + Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework + +.. attrs:: + :class: column is-4 + + #### Community driven + + The project is maintained and run by the community for the community. +``` + +.. attrs:: +:class: is-size-3 mt-6 + +``` +**With the features and tools you'd expect.** +``` + +.. attrs:: +:class: is-size-3 ml-6 + +``` +**And some {span:has-text-primary:you wouldn't believe}.** +``` + +.. tab:: Production-grade + +```` +After installing, Sanic has all the tools you need for a scalable, production-grade server—out of the box! + +Including [full TLS support](/en/guide/how-to/tls). + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +```sh +sanic path.to.server:app +[2023-01-31 12:34:56 +0000] [999996] [INFO] Sanic v22.12.0 +[2023-01-31 12:34:56 +0000] [999996] [INFO] Goin' Fast @ http://127.0.0.1:8000 +[2023-01-31 12:34:56 +0000] [999996] [INFO] mode: production, single worker +[2023-01-31 12:34:56 +0000] [999996] [INFO] server: sanic, HTTP/1.1 +[2023-01-31 12:34:56 +0000] [999996] [INFO] python: 3.10.9 +[2023-01-31 12:34:56 +0000] [999996] [INFO] platform: SomeOS-9.8.7 +[2023-01-31 12:34:56 +0000] [999996] [INFO] packages: sanic-routing==22.8.0 +[2023-01-31 12:34:56 +0000] [999997] [INFO] Starting worker [999997] +``` +```` + +.. tab:: TLS server + +```` +Running Sanic with TLS enabled is as simple as passing it the file paths... +```sh +sanic path.to.server:app --cert=/path/to/bundle.crt --key=/path/to/privkey.pem +``` + +... or the a directory containing `fullchain.pem` and `privkey.pem` + +```sh +sanic path.to.server:app --tls=/path/to/certs +``` + +**Even better**, while you are developing, let Sanic handle setting up local TLS certificates so you can access your site over TLS at [https://localhost:8443](https://localhost:8443) + +```sh +sanic path.to.server:app --dev --auto-tls +``` +```` + +.. tab:: Websockets + +```` +Up and running with websockets in no time using the [websockets](https://websockets.readthedocs.io) package. +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` +```` + +.. tab:: Static files + +```` +Serving static files is of course intuitive and easy. Just name an endpoint and either a file or directory that should be served. + +```python +app.static("/", "/path/to/index.html") +app.static("/uploads/", "/path/to/uploads/") +``` + +Moreover, serving a directory has two additional features: automatically serving an index, and automatically serving a file browser. + +Sanic can automatically serve `index.html` (or any other named file) as an index page in a directory or its subdirectories. + +```python +app.static( + "/uploads/", + "/path/to/uploads/", + index="index.html" +) +``` + +And/or, setup Sanic to display a file browser. + + +![image](/assets/images/directory-view.png) + +```python +app.static( + "/uploads/", + "/path/to/uploads/", + directory_view=True +) +``` +```` + +.. tab:: Lifecycle + +```` +Beginning or ending a route with functionality is as simple as adding a decorator. + +```python +@app.on_request +async def add_key(request): + request.ctx.foo = "bar" + +@app.on_response +async def custom_banner(request, response): + response.headers["X-Foo"] = request.ctx.foo +``` + +Same with server events. + +```python +@app.before_server_start +async def setup_db(app): + app.ctx.db_pool = await db_setup() + +@app.after_server_stop +async def setup_db(app): + await app.ctx.db_pool.shutdown() +``` + +But, Sanic also allows you to tie into a bunch of built-in events (called signals), or create and dispatch your own. + +```python +@app.signal("http.lifecycle.complete") # built-in +async def my_signal_handler(conn_info): + print("Connection has been closed") + +@app.signal("something.happened.ohmy") # custom +async def my_signal_handler(): + print("something happened") + +await app.dispatch("something.happened.ohmy") +``` +```` + +.. tab:: Smart error handling + +```` +Raising errors will intuitively result in proper HTTP errors: + +```python +raise sanic.exceptions.NotFound # Automatically responds with HTTP 404 +``` + +Or, make your own: + +```python +from sanic.exceptions import SanicException + +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +And, when an error does happen, Sanic's beautiful DEV mode error page will help you drill down to the bug quickly. + +![image](../assets/images/error-div-by-zero.png) + +Regardless, Sanic comes with an algorithm that attempts to respond with HTML, JSON, or text-based errors as appropriate. Don't worry, it is super easy to setup and customize your error handling to your exact needs. +```` + +.. tab:: App Inspector + +```` +Check in on your live, running applications (whether local or remote). +```sh +sanic inspect + +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Sanic │ +│ Inspecting @ http://localhost:6457 │ +├───────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────┤ +│ │ mode: production, single worker │ +│ ▄███ █████ ██ │ server: unknown │ +│ ██ │ python: 3.10.9 │ +│ ▀███████ ███▄ │ platform: SomeOS-9.8.7 +│ ██ │ packages: sanic==22.12.0, sanic-routing==22.8.0, sanic-testing==22.12.0, sanic-ext==22.12.0 │ +│ ████ ████████▀ │ │ +│ │ │ +│ Build Fast. Run Fast. │ │ +└───────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────┘ + +Sanic-Main + pid: 999996 + +Sanic-Server-0-0 + server: True + state: ACKED + pid: 999997 + start_at: 2023-01-31T12:34:56.00000+00:00 + starts: 1 + +Sanic-Inspector-0 + server: False + state: STARTED + pid: 999998 + start_at: 2023-01-31T12:34:56.00000+00:00 + starts: 1 +``` + +And, issue commands like `reload`, `shutdown`, `scale`... + +```sh +sanic inspect scale 4 +``` + +... or even create your own! + +```sh +sanic inspect migrations +``` +```` + +.. tab:: Extendable + +``` +In addition to the tools that Sanic comes with, the officially supported [Sanic Extensions](./plugins/sanic-ext/getting-started.md) provides lots of extra goodies to make development easier. + +- **CORS** protection +- Template rendering with **Jinja** +- **Dependency injection** into route handlers +- OpenAPI documentation with **Redoc** and/or **Swagger** +- Predefined, endpoint-specific response **serializers** +- Request query arguments and body input **validation** +- **Auto create** HEAD, OPTIONS, and TRACE endpoints +- Live **health monitor** +``` + +.. tab:: Developer Experience + +``` +Sanic is **built for building**. + +From the moment it is installed, Sanic includes helpful tools to help the developer get their job done. + +- **One server** - Develop locally in DEV mode on the same server that will run your PRODUCTION application +- **Auto reload** - Reload running applications every time you save a Python file, but also auto-reload **on any arbitrary directory** like HTML template directories +- **Debugging tools** - Super helpful (and beautiful) [error pages](/en/guide/best-practices/exceptions) that help you traverse the trace stack easily +- **Auto TLS** - Running a localhost website with `https` can be difficult, [Sanic makes it easy](/en/guide/how-to/tls) +- **Streamlined testing** - Built-in testing capabilities, making it easier for developers to create and run tests, ensuring the quality and reliability of their services +- **Modern Python** - Thoughtful use of type hints to help the developer IDE experience +``` From f7331b796b9a2f841f34819f7d3bfaf0c0a6ed12 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:54 +0200 Subject: [PATCH 162/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 334 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 guide/content/zh/index.md diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md new file mode 100644 index 0000000000..3c09f07788 --- /dev/null +++ b/guide/content/zh/index.md @@ -0,0 +1,334 @@ +--- +title: The lightning-fast asynchronous Python web framework +layout: home +features: + - title: Simple and lightweight + details: Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. + - title: Unopinionated and flexible + details: Build the way you want to build without letting your tooling constrain you. + - title: Performant and scalable + details: Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. + - title: Production ready + details: Out of the box, it comes bundled with a web server ready to power your web applications. + - title: Trusted by millions + details: Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework + - title: Community driven + details: The project is maintained and run by the community for the community. +--- + +### ⚡ The lightning-fast asynchronous Python web framework + +.. attrs:: +:class: columns is-multiline mt-6 + +``` +.. attrs:: + :class: column is-4 + + #### Simple and lightweight + + Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. + +.. attrs:: + :class: column is-4 + + #### Unopinionated and flexible + + Build the way you want to build without letting your tooling constrain you. + +.. attrs:: + :class: column is-4 + + #### Performant and scalable + + Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. + +.. attrs:: + :class: column is-4 + + #### Production ready + + Out of the box, it comes bundled with a web server ready to power your web applications. + +.. attrs:: + :class: column is-4 + + #### Trusted by millions + + Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework + +.. attrs:: + :class: column is-4 + + #### Community driven + + The project is maintained and run by the community for the community. +``` + +.. attrs:: +:class: is-size-3 mt-6 + +``` +**With the features and tools you'd expect.** +``` + +.. attrs:: +:class: is-size-3 ml-6 + +``` +**And some {span:has-text-primary:you wouldn't believe}.** +``` + +.. tab:: Production-grade + +```` +After installing, Sanic has all the tools you need for a scalable, production-grade server—out of the box! + +Including [full TLS support](/en/guide/how-to/tls). + +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +```sh +sanic path.to.server:app +[2023-01-31 12:34:56 +0000] [999996] [INFO] Sanic v22.12.0 +[2023-01-31 12:34:56 +0000] [999996] [INFO] Goin' Fast @ http://127.0.0.1:8000 +[2023-01-31 12:34:56 +0000] [999996] [INFO] mode: production, single worker +[2023-01-31 12:34:56 +0000] [999996] [INFO] server: sanic, HTTP/1.1 +[2023-01-31 12:34:56 +0000] [999996] [INFO] python: 3.10.9 +[2023-01-31 12:34:56 +0000] [999996] [INFO] platform: SomeOS-9.8.7 +[2023-01-31 12:34:56 +0000] [999996] [INFO] packages: sanic-routing==22.8.0 +[2023-01-31 12:34:56 +0000] [999997] [INFO] Starting worker [999997] +``` +```` + +.. tab:: TLS server + +```` +Running Sanic with TLS enabled is as simple as passing it the file paths... +```sh +sanic path.to.server:app --cert=/path/to/bundle.crt --key=/path/to/privkey.pem +``` + +... or the a directory containing `fullchain.pem` and `privkey.pem` + +```sh +sanic path.to.server:app --tls=/path/to/certs +``` + +**Even better**, while you are developing, let Sanic handle setting up local TLS certificates so you can access your site over TLS at [https://localhost:8443](https://localhost:8443) + +```sh +sanic path.to.server:app --dev --auto-tls +``` +```` + +.. tab:: Websockets + +```` +Up and running with websockets in no time using the [websockets](https://websockets.readthedocs.io) package. +```python +from sanic import Request, Websocket + +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` +```` + +.. tab:: Static files + +```` +Serving static files is of course intuitive and easy. Just name an endpoint and either a file or directory that should be served. + +```python +app.static("/", "/path/to/index.html") +app.static("/uploads/", "/path/to/uploads/") +``` + +Moreover, serving a directory has two additional features: automatically serving an index, and automatically serving a file browser. + +Sanic can automatically serve `index.html` (or any other named file) as an index page in a directory or its subdirectories. + +```python +app.static( + "/uploads/", + "/path/to/uploads/", + index="index.html" +) +``` + +And/or, setup Sanic to display a file browser. + + +![image](/assets/images/directory-view.png) + +```python +app.static( + "/uploads/", + "/path/to/uploads/", + directory_view=True +) +``` +```` + +.. tab:: Lifecycle + +```` +Beginning or ending a route with functionality is as simple as adding a decorator. + +```python +@app.on_request +async def add_key(request): + request.ctx.foo = "bar" + +@app.on_response +async def custom_banner(request, response): + response.headers["X-Foo"] = request.ctx.foo +``` + +Same with server events. + +```python +@app.before_server_start +async def setup_db(app): + app.ctx.db_pool = await db_setup() + +@app.after_server_stop +async def setup_db(app): + await app.ctx.db_pool.shutdown() +``` + +But, Sanic also allows you to tie into a bunch of built-in events (called signals), or create and dispatch your own. + +```python +@app.signal("http.lifecycle.complete") # built-in +async def my_signal_handler(conn_info): + print("Connection has been closed") + +@app.signal("something.happened.ohmy") # custom +async def my_signal_handler(): + print("something happened") + +await app.dispatch("something.happened.ohmy") +``` +```` + +.. tab:: Smart error handling + +```` +Raising errors will intuitively result in proper HTTP errors: + +```python +raise sanic.exceptions.NotFound # Automatically responds with HTTP 404 +``` + +Or, make your own: + +```python +from sanic.exceptions import SanicException + +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +And, when an error does happen, Sanic's beautiful DEV mode error page will help you drill down to the bug quickly. + +![image](../assets/images/error-div-by-zero.png) + +Regardless, Sanic comes with an algorithm that attempts to respond with HTML, JSON, or text-based errors as appropriate. Don't worry, it is super easy to setup and customize your error handling to your exact needs. +```` + +.. tab:: App Inspector + +```` +Check in on your live, running applications (whether local or remote). +```sh +sanic inspect + +┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ Sanic │ +│ Inspecting @ http://localhost:6457 │ +├───────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────┤ +│ │ mode: production, single worker │ +│ ▄███ █████ ██ │ server: unknown │ +│ ██ │ python: 3.10.9 │ +│ ▀███████ ███▄ │ platform: SomeOS-9.8.7 +│ ██ │ packages: sanic==22.12.0, sanic-routing==22.8.0, sanic-testing==22.12.0, sanic-ext==22.12.0 │ +│ ████ ████████▀ │ │ +│ │ │ +│ Build Fast. Run Fast. │ │ +└───────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────┘ + +Sanic-Main + pid: 999996 + +Sanic-Server-0-0 + server: True + state: ACKED + pid: 999997 + start_at: 2023-01-31T12:34:56.00000+00:00 + starts: 1 + +Sanic-Inspector-0 + server: False + state: STARTED + pid: 999998 + start_at: 2023-01-31T12:34:56.00000+00:00 + starts: 1 +``` + +And, issue commands like `reload`, `shutdown`, `scale`... + +```sh +sanic inspect scale 4 +``` + +... or even create your own! + +```sh +sanic inspect migrations +``` +```` + +.. tab:: Extendable + +``` +In addition to the tools that Sanic comes with, the officially supported [Sanic Extensions](./plugins/sanic-ext/getting-started.md) provides lots of extra goodies to make development easier. + +- **CORS** protection +- Template rendering with **Jinja** +- **Dependency injection** into route handlers +- OpenAPI documentation with **Redoc** and/or **Swagger** +- Predefined, endpoint-specific response **serializers** +- Request query arguments and body input **validation** +- **Auto create** HEAD, OPTIONS, and TRACE endpoints +- Live **health monitor** +``` + +.. tab:: Developer Experience + +``` +Sanic is **built for building**. + +From the moment it is installed, Sanic includes helpful tools to help the developer get their job done. + +- **One server** - Develop locally in DEV mode on the same server that will run your PRODUCTION application +- **Auto reload** - Reload running applications every time you save a Python file, but also auto-reload **on any arbitrary directory** like HTML template directories +- **Debugging tools** - Super helpful (and beautiful) [error pages](/en/guide/best-practices/exceptions) that help you traverse the trace stack easily +- **Auto TLS** - Running a localhost website with `https` can be difficult, [Sanic makes it easy](/en/guide/how-to/tls) +- **Streamlined testing** - Built-in testing capabilities, making it easier for developers to create and run tests, ensuring the quality and reliability of their services +- **Modern Python** - Thoughtful use of type hints to help the developer IDE experience +``` From 0e11365236001f75de5e436778575fd80d28a7f0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:55 +0200 Subject: [PATCH 163/698] New translations code-of-conduct.md (Japanese) --- .../ja/organization/code-of-conduct.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 guide/content/ja/organization/code-of-conduct.md diff --git a/guide/content/ja/organization/code-of-conduct.md b/guide/content/ja/organization/code-of-conduct.md new file mode 100644 index 0000000000..84f0f12d5f --- /dev/null +++ b/guide/content/ja/organization/code-of-conduct.md @@ -0,0 +1,75 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at adam\@sanicframework.org. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org + +[version]: http://contributor-covenant.org/version/1/4/ From abe3ff436cbf56ec192b87ed05dc86b334deeea4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:56 +0200 Subject: [PATCH 164/698] New translations code-of-conduct.md (Korean) --- .../ko/organization/code-of-conduct.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 guide/content/ko/organization/code-of-conduct.md diff --git a/guide/content/ko/organization/code-of-conduct.md b/guide/content/ko/organization/code-of-conduct.md new file mode 100644 index 0000000000..84f0f12d5f --- /dev/null +++ b/guide/content/ko/organization/code-of-conduct.md @@ -0,0 +1,75 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at adam\@sanicframework.org. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org + +[version]: http://contributor-covenant.org/version/1/4/ From 03dacf96278fd50537542f12fefb5dd70f662a24 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:57 +0200 Subject: [PATCH 165/698] New translations code-of-conduct.md (Chinese Simplified) --- .../zh/organization/code-of-conduct.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 guide/content/zh/organization/code-of-conduct.md diff --git a/guide/content/zh/organization/code-of-conduct.md b/guide/content/zh/organization/code-of-conduct.md new file mode 100644 index 0000000000..84f0f12d5f --- /dev/null +++ b/guide/content/zh/organization/code-of-conduct.md @@ -0,0 +1,75 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at adam\@sanicframework.org. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org + +[version]: http://contributor-covenant.org/version/1/4/ From de3d1721382b8093aa757d5a9a000e41a6d7311c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:58 +0200 Subject: [PATCH 166/698] New translations contributing.md (Japanese) --- guide/content/ja/organization/contributing.md | 166 ++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 guide/content/ja/organization/contributing.md diff --git a/guide/content/ja/organization/contributing.md b/guide/content/ja/organization/contributing.md new file mode 100644 index 0000000000..fc38154f48 --- /dev/null +++ b/guide/content/ja/organization/contributing.md @@ -0,0 +1,166 @@ +# Contributing + +Thank you for your interest! Sanic is always looking for contributors. If you don't feel comfortable contributing code, adding docstrings to the source files, or helping with the [Sanic User Guide](https://github.com/sanic-org/sanic-guide) by providing documentation or implementation examples would be appreciated! + +We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Our [code of conduct](https://github.com/sanic-org/sanic/blob/master/CONDUCT.md) sets the standards for behavior. + +## Installation + +To develop on Sanic (and mainly to just run the tests) it is highly recommend to install from sources. + +So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run: + +```sh +pip install -e ".[dev]" +``` + +## Dependency Changes + +`Sanic` doesn't use `requirements*.txt` files to manage any kind of dependencies related to it in order to simplify the effort required in managing the dependencies. Please make sure you have read and understood the following section of the document that explains the way `sanic` manages dependencies inside the `setup.py` file. + +| Dependency Type | Usage | Installation | +| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------- | +| requirements | Bare minimum dependencies required for sanic to function | `pip3 install -e .` | +| tests_require / extras_require['test'] | Dependencies required to run the Unit Tests for `sanic` | `pip3 install -e '.[test]'` | +| extras_require['dev'] | Additional Development requirements to add contributing | `pip3 install -e '.[dev]'` | +| extras_require['docs'] | Dependencies required to enable building and enhancing sanic documentation | `pip3 install -e '.[docs]'` | + +## Running all tests + +To run the tests for Sanic it is recommended to use tox like so: + +```sh +tox +``` + +See it's that simple! + +`tox.ini` contains different environments. Running `tox` without any arguments will +run all unittests, perform lint and other checks. + +## Run unittests + +`tox` environment -> `[testenv]` + +To execute only unittests, run `tox` with environment like so: + +```sh + +tox -e py37 -v -- tests/test_config.py +# or +tox -e py310 -v -- tests/test_config.py +``` + +## Run lint checks + +`tox` environment -> `[testenv:lint]` + +Permform `flake8`\ , `black` and `isort` checks. + +```sh +tox -e lint +``` + +## Run type annotation checks + +`tox` environment -> `[testenv:type-checking]` + +Permform `mypy` checks. + +```sh +tox -e type-checking +``` + +## Run other checks + +`tox` environment -> `[testenv:check]` + +Perform other checks. + +```sh +tox -e check +``` + +## Run Static Analysis + +`tox` environment -> `[testenv:security]` + +Perform static analysis security scan + +```sh +tox -e security +``` + +## Run Documentation sanity check + +`tox` environment -> `[testenv:docs]` + +Perform sanity check on documentation + +```sh +tox -e docs +``` + +## Code Style + +To maintain the code consistency, Sanic uses the following tools: + +1. [isort](https://github.com/timothycrosley/isort) +2. [black](https://github.com/python/black) +3. [flake8](https://github.com/PyCQA/flake8) +4. [slotscheck](https://github.com/ariebovenberg/slotscheck) + +### isort + +`isort` sorts Python imports. It divides imports into three categories sorted each in alphabetical order: + +1. built-in +2. third-party +3. project-specific + +### black + +`black` is a Python code formatter. + +### flake8 + +`flake8` is a Python style guide that wraps the following tools into one: + +1. PyFlakes +2. pycodestyle +3. Ned Batchelder's McCabe script + +### slotscheck + +`slotscheck` ensures that there are no problems with `__slots__` (e.g., overlaps, or missing slots in base classes). + +`isort`, `black`, `flake8`, and `slotscheck` checks are performed during `tox` lint checks. + +The **easiest** way to make your code conform is to run the following before committing: + +```bash +make pretty +``` + +Refer to [tox documentation](https://tox.readthedocs.io/en/latest/index.html) for more details. + +## Pull requests + +So the pull request approval rules are pretty simple: + +1. All pull requests must pass unit tests. +2. All pull requests must be reviewed and approved by at least one current member of the Core Developer team. +3. All pull requests must pass flake8 checks. +4. All pull requests must match `isort` and `black` requirements. +5. All pull requests must be **PROPERLY** type annotated, unless exemption is given. +6. All pull requests must be consistent with the existing code. +7. If you decide to remove/change anything from any common interface a deprecation message should accompany it in accordance with our [deprecation policy](https://sanicframework.org/en/guide/project/policies.html#deprecation). +8. If you implement a new feature you should have at least one unit test to accompany it. +9. An example must be one of the following: + - Example of how to use Sanic + - Example of how to use Sanic extensions + - Example of how to use Sanic and asynchronous library + +## Documentation + +_Check back. We are reworking our documentation so this will change._ From 1ba6e36c3bc917f015c77147263b103fa67b1f4d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:21:59 +0200 Subject: [PATCH 167/698] New translations contributing.md (Korean) --- guide/content/ko/organization/contributing.md | 166 ++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 guide/content/ko/organization/contributing.md diff --git a/guide/content/ko/organization/contributing.md b/guide/content/ko/organization/contributing.md new file mode 100644 index 0000000000..fc38154f48 --- /dev/null +++ b/guide/content/ko/organization/contributing.md @@ -0,0 +1,166 @@ +# Contributing + +Thank you for your interest! Sanic is always looking for contributors. If you don't feel comfortable contributing code, adding docstrings to the source files, or helping with the [Sanic User Guide](https://github.com/sanic-org/sanic-guide) by providing documentation or implementation examples would be appreciated! + +We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Our [code of conduct](https://github.com/sanic-org/sanic/blob/master/CONDUCT.md) sets the standards for behavior. + +## Installation + +To develop on Sanic (and mainly to just run the tests) it is highly recommend to install from sources. + +So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run: + +```sh +pip install -e ".[dev]" +``` + +## Dependency Changes + +`Sanic` doesn't use `requirements*.txt` files to manage any kind of dependencies related to it in order to simplify the effort required in managing the dependencies. Please make sure you have read and understood the following section of the document that explains the way `sanic` manages dependencies inside the `setup.py` file. + +| Dependency Type | Usage | Installation | +| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------- | +| requirements | Bare minimum dependencies required for sanic to function | `pip3 install -e .` | +| tests_require / extras_require['test'] | Dependencies required to run the Unit Tests for `sanic` | `pip3 install -e '.[test]'` | +| extras_require['dev'] | Additional Development requirements to add contributing | `pip3 install -e '.[dev]'` | +| extras_require['docs'] | Dependencies required to enable building and enhancing sanic documentation | `pip3 install -e '.[docs]'` | + +## Running all tests + +To run the tests for Sanic it is recommended to use tox like so: + +```sh +tox +``` + +See it's that simple! + +`tox.ini` contains different environments. Running `tox` without any arguments will +run all unittests, perform lint and other checks. + +## Run unittests + +`tox` environment -> `[testenv]` + +To execute only unittests, run `tox` with environment like so: + +```sh + +tox -e py37 -v -- tests/test_config.py +# or +tox -e py310 -v -- tests/test_config.py +``` + +## Run lint checks + +`tox` environment -> `[testenv:lint]` + +Permform `flake8`\ , `black` and `isort` checks. + +```sh +tox -e lint +``` + +## Run type annotation checks + +`tox` environment -> `[testenv:type-checking]` + +Permform `mypy` checks. + +```sh +tox -e type-checking +``` + +## Run other checks + +`tox` environment -> `[testenv:check]` + +Perform other checks. + +```sh +tox -e check +``` + +## Run Static Analysis + +`tox` environment -> `[testenv:security]` + +Perform static analysis security scan + +```sh +tox -e security +``` + +## Run Documentation sanity check + +`tox` environment -> `[testenv:docs]` + +Perform sanity check on documentation + +```sh +tox -e docs +``` + +## Code Style + +To maintain the code consistency, Sanic uses the following tools: + +1. [isort](https://github.com/timothycrosley/isort) +2. [black](https://github.com/python/black) +3. [flake8](https://github.com/PyCQA/flake8) +4. [slotscheck](https://github.com/ariebovenberg/slotscheck) + +### isort + +`isort` sorts Python imports. It divides imports into three categories sorted each in alphabetical order: + +1. built-in +2. third-party +3. project-specific + +### black + +`black` is a Python code formatter. + +### flake8 + +`flake8` is a Python style guide that wraps the following tools into one: + +1. PyFlakes +2. pycodestyle +3. Ned Batchelder's McCabe script + +### slotscheck + +`slotscheck` ensures that there are no problems with `__slots__` (e.g., overlaps, or missing slots in base classes). + +`isort`, `black`, `flake8`, and `slotscheck` checks are performed during `tox` lint checks. + +The **easiest** way to make your code conform is to run the following before committing: + +```bash +make pretty +``` + +Refer to [tox documentation](https://tox.readthedocs.io/en/latest/index.html) for more details. + +## Pull requests + +So the pull request approval rules are pretty simple: + +1. All pull requests must pass unit tests. +2. All pull requests must be reviewed and approved by at least one current member of the Core Developer team. +3. All pull requests must pass flake8 checks. +4. All pull requests must match `isort` and `black` requirements. +5. All pull requests must be **PROPERLY** type annotated, unless exemption is given. +6. All pull requests must be consistent with the existing code. +7. If you decide to remove/change anything from any common interface a deprecation message should accompany it in accordance with our [deprecation policy](https://sanicframework.org/en/guide/project/policies.html#deprecation). +8. If you implement a new feature you should have at least one unit test to accompany it. +9. An example must be one of the following: + - Example of how to use Sanic + - Example of how to use Sanic extensions + - Example of how to use Sanic and asynchronous library + +## Documentation + +_Check back. We are reworking our documentation so this will change._ From 0544c0909afd0909900a7bac67991b048fe7dd22 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:00 +0200 Subject: [PATCH 168/698] New translations contributing.md (Chinese Simplified) --- guide/content/zh/organization/contributing.md | 166 ++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 guide/content/zh/organization/contributing.md diff --git a/guide/content/zh/organization/contributing.md b/guide/content/zh/organization/contributing.md new file mode 100644 index 0000000000..fc38154f48 --- /dev/null +++ b/guide/content/zh/organization/contributing.md @@ -0,0 +1,166 @@ +# Contributing + +Thank you for your interest! Sanic is always looking for contributors. If you don't feel comfortable contributing code, adding docstrings to the source files, or helping with the [Sanic User Guide](https://github.com/sanic-org/sanic-guide) by providing documentation or implementation examples would be appreciated! + +We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Our [code of conduct](https://github.com/sanic-org/sanic/blob/master/CONDUCT.md) sets the standards for behavior. + +## Installation + +To develop on Sanic (and mainly to just run the tests) it is highly recommend to install from sources. + +So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run: + +```sh +pip install -e ".[dev]" +``` + +## Dependency Changes + +`Sanic` doesn't use `requirements*.txt` files to manage any kind of dependencies related to it in order to simplify the effort required in managing the dependencies. Please make sure you have read and understood the following section of the document that explains the way `sanic` manages dependencies inside the `setup.py` file. + +| Dependency Type | Usage | Installation | +| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------- | +| requirements | Bare minimum dependencies required for sanic to function | `pip3 install -e .` | +| tests_require / extras_require['test'] | Dependencies required to run the Unit Tests for `sanic` | `pip3 install -e '.[test]'` | +| extras_require['dev'] | Additional Development requirements to add contributing | `pip3 install -e '.[dev]'` | +| extras_require['docs'] | Dependencies required to enable building and enhancing sanic documentation | `pip3 install -e '.[docs]'` | + +## Running all tests + +To run the tests for Sanic it is recommended to use tox like so: + +```sh +tox +``` + +See it's that simple! + +`tox.ini` contains different environments. Running `tox` without any arguments will +run all unittests, perform lint and other checks. + +## Run unittests + +`tox` environment -> `[testenv]` + +To execute only unittests, run `tox` with environment like so: + +```sh + +tox -e py37 -v -- tests/test_config.py +# or +tox -e py310 -v -- tests/test_config.py +``` + +## Run lint checks + +`tox` environment -> `[testenv:lint]` + +Permform `flake8`\ , `black` and `isort` checks. + +```sh +tox -e lint +``` + +## Run type annotation checks + +`tox` environment -> `[testenv:type-checking]` + +Permform `mypy` checks. + +```sh +tox -e type-checking +``` + +## Run other checks + +`tox` environment -> `[testenv:check]` + +Perform other checks. + +```sh +tox -e check +``` + +## Run Static Analysis + +`tox` environment -> `[testenv:security]` + +Perform static analysis security scan + +```sh +tox -e security +``` + +## Run Documentation sanity check + +`tox` environment -> `[testenv:docs]` + +Perform sanity check on documentation + +```sh +tox -e docs +``` + +## Code Style + +To maintain the code consistency, Sanic uses the following tools: + +1. [isort](https://github.com/timothycrosley/isort) +2. [black](https://github.com/python/black) +3. [flake8](https://github.com/PyCQA/flake8) +4. [slotscheck](https://github.com/ariebovenberg/slotscheck) + +### isort + +`isort` sorts Python imports. It divides imports into three categories sorted each in alphabetical order: + +1. built-in +2. third-party +3. project-specific + +### black + +`black` is a Python code formatter. + +### flake8 + +`flake8` is a Python style guide that wraps the following tools into one: + +1. PyFlakes +2. pycodestyle +3. Ned Batchelder's McCabe script + +### slotscheck + +`slotscheck` ensures that there are no problems with `__slots__` (e.g., overlaps, or missing slots in base classes). + +`isort`, `black`, `flake8`, and `slotscheck` checks are performed during `tox` lint checks. + +The **easiest** way to make your code conform is to run the following before committing: + +```bash +make pretty +``` + +Refer to [tox documentation](https://tox.readthedocs.io/en/latest/index.html) for more details. + +## Pull requests + +So the pull request approval rules are pretty simple: + +1. All pull requests must pass unit tests. +2. All pull requests must be reviewed and approved by at least one current member of the Core Developer team. +3. All pull requests must pass flake8 checks. +4. All pull requests must match `isort` and `black` requirements. +5. All pull requests must be **PROPERLY** type annotated, unless exemption is given. +6. All pull requests must be consistent with the existing code. +7. If you decide to remove/change anything from any common interface a deprecation message should accompany it in accordance with our [deprecation policy](https://sanicframework.org/en/guide/project/policies.html#deprecation). +8. If you implement a new feature you should have at least one unit test to accompany it. +9. An example must be one of the following: + - Example of how to use Sanic + - Example of how to use Sanic extensions + - Example of how to use Sanic and asynchronous library + +## Documentation + +_Check back. We are reworking our documentation so this will change._ From aee3f0d66474d831df1b0a9cc979fe21738c90c9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:01 +0200 Subject: [PATCH 169/698] New translations policies.md (Japanese) --- guide/content/ja/organization/policies.md | 78 +++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 guide/content/ja/organization/policies.md diff --git a/guide/content/ja/organization/policies.md b/guide/content/ja/organization/policies.md new file mode 100644 index 0000000000..5870095910 --- /dev/null +++ b/guide/content/ja/organization/policies.md @@ -0,0 +1,78 @@ +# Policies + +## Versioning + +Sanic uses [calendar versioning](https://calver.org/), aka "calver". To be more specific, the pattern follows: + +``` +YY.MM.MICRO +``` + +Generally, versions are referred to in their `YY.MM` form. The `MICRO` number indicates an incremental patch version, starting at `0`. + +## Reporting a Vulnerability + +If you discover a security vulnerability, we ask that you **do not** create an issue on GitHub. Instead, please [send a message to the core-devs](https://community.sanicframework.org/g/core-devs) on the community forums. Once logged in, you can send a message to the core-devs by clicking the message button. + +Alternatively, you can send a private message to Adam Hopkins on Discord. Find him on the [Sanic discord server](https://discord.gg/FARQzAEMAA). + +This will help to not publicize the issue until the team can address it and resolve it. + +## Release Schedule + +There are four (4) scheduled releases per year: March, June, September, and December. Therefore, there are four (4) released versions per year: `YY.3`, `YY.6`, `YY.9`, and `YY.12`. + +This release schedule provides: + +- a predictable release cadence, +- relatively short development windows allowing features to be regularly released, +- controlled [deprecations](#deprecation), and +- consistent stability with a yearly LTS. + +We also use the yearly release cycle in conjunction with our governance model, covered by the [S.C.O.P.E.](./scope.md) + +### Long term support v Interim releases + +Sanic releases a long term support release (aka "LTS") once a year in December. The LTS releases receive bug fixes and security updates for **24 months**. Interim releases throughout the year occur every three months, and are supported until the subsequent release. + +| Version | Release | LTS | Supported | +| ------- | ---------- | ------------- | --------- | +| 23.12 | 2023-12-31 | until 2025-12 | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | +| 0.8.3 | 2018-09-13 | | ⚪ | +| 0.7.0 | 2017-12-06 | | ⚪ | +| 0.6.0 | 2017-08-03 | | ⚪ | +| 0.5.4 | 2017-05-09 | | ⚪ | +| 0.4.1 | 2017-02-28 | | ⚪ | +| 0.3.1 | 2017-02-09 | | ⚪ | +| 0.2.0 | 2017-01-14 | | ⚪ | +| 0.1.9 | 2016-12-25 | | ⚪ | +| 0.1.0 | 2016-10-16 | | ⚪ | + +☑️ = security fixes\ +✅ = full support\ +⚪ = no support + +## Deprecation + +Before a feature is deprecated, or breaking changes are introduced into the API, it shall be publicized and shall appear with deprecation warnings through two release cycles. No deprecations shall be made in an LTS release. + +Breaking changes or feature removal may happen outside of these guidelines when absolutely warranted. These circumstances should be rare. For example, it might happen when no alternative is available to curtail a major security issue. From b1c3363b8ea0fe5f190da02c9ec6bd7253ab52d2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:02 +0200 Subject: [PATCH 170/698] New translations policies.md (Korean) --- guide/content/ko/organization/policies.md | 78 +++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 guide/content/ko/organization/policies.md diff --git a/guide/content/ko/organization/policies.md b/guide/content/ko/organization/policies.md new file mode 100644 index 0000000000..5870095910 --- /dev/null +++ b/guide/content/ko/organization/policies.md @@ -0,0 +1,78 @@ +# Policies + +## Versioning + +Sanic uses [calendar versioning](https://calver.org/), aka "calver". To be more specific, the pattern follows: + +``` +YY.MM.MICRO +``` + +Generally, versions are referred to in their `YY.MM` form. The `MICRO` number indicates an incremental patch version, starting at `0`. + +## Reporting a Vulnerability + +If you discover a security vulnerability, we ask that you **do not** create an issue on GitHub. Instead, please [send a message to the core-devs](https://community.sanicframework.org/g/core-devs) on the community forums. Once logged in, you can send a message to the core-devs by clicking the message button. + +Alternatively, you can send a private message to Adam Hopkins on Discord. Find him on the [Sanic discord server](https://discord.gg/FARQzAEMAA). + +This will help to not publicize the issue until the team can address it and resolve it. + +## Release Schedule + +There are four (4) scheduled releases per year: March, June, September, and December. Therefore, there are four (4) released versions per year: `YY.3`, `YY.6`, `YY.9`, and `YY.12`. + +This release schedule provides: + +- a predictable release cadence, +- relatively short development windows allowing features to be regularly released, +- controlled [deprecations](#deprecation), and +- consistent stability with a yearly LTS. + +We also use the yearly release cycle in conjunction with our governance model, covered by the [S.C.O.P.E.](./scope.md) + +### Long term support v Interim releases + +Sanic releases a long term support release (aka "LTS") once a year in December. The LTS releases receive bug fixes and security updates for **24 months**. Interim releases throughout the year occur every three months, and are supported until the subsequent release. + +| Version | Release | LTS | Supported | +| ------- | ---------- | ------------- | --------- | +| 23.12 | 2023-12-31 | until 2025-12 | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | +| 0.8.3 | 2018-09-13 | | ⚪ | +| 0.7.0 | 2017-12-06 | | ⚪ | +| 0.6.0 | 2017-08-03 | | ⚪ | +| 0.5.4 | 2017-05-09 | | ⚪ | +| 0.4.1 | 2017-02-28 | | ⚪ | +| 0.3.1 | 2017-02-09 | | ⚪ | +| 0.2.0 | 2017-01-14 | | ⚪ | +| 0.1.9 | 2016-12-25 | | ⚪ | +| 0.1.0 | 2016-10-16 | | ⚪ | + +☑️ = security fixes\ +✅ = full support\ +⚪ = no support + +## Deprecation + +Before a feature is deprecated, or breaking changes are introduced into the API, it shall be publicized and shall appear with deprecation warnings through two release cycles. No deprecations shall be made in an LTS release. + +Breaking changes or feature removal may happen outside of these guidelines when absolutely warranted. These circumstances should be rare. For example, it might happen when no alternative is available to curtail a major security issue. From 786559a5e11b003ac9a7eb6368b47f845dfb1de6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:03 +0200 Subject: [PATCH 171/698] New translations policies.md (Chinese Simplified) --- guide/content/zh/organization/policies.md | 78 +++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 guide/content/zh/organization/policies.md diff --git a/guide/content/zh/organization/policies.md b/guide/content/zh/organization/policies.md new file mode 100644 index 0000000000..5870095910 --- /dev/null +++ b/guide/content/zh/organization/policies.md @@ -0,0 +1,78 @@ +# Policies + +## Versioning + +Sanic uses [calendar versioning](https://calver.org/), aka "calver". To be more specific, the pattern follows: + +``` +YY.MM.MICRO +``` + +Generally, versions are referred to in their `YY.MM` form. The `MICRO` number indicates an incremental patch version, starting at `0`. + +## Reporting a Vulnerability + +If you discover a security vulnerability, we ask that you **do not** create an issue on GitHub. Instead, please [send a message to the core-devs](https://community.sanicframework.org/g/core-devs) on the community forums. Once logged in, you can send a message to the core-devs by clicking the message button. + +Alternatively, you can send a private message to Adam Hopkins on Discord. Find him on the [Sanic discord server](https://discord.gg/FARQzAEMAA). + +This will help to not publicize the issue until the team can address it and resolve it. + +## Release Schedule + +There are four (4) scheduled releases per year: March, June, September, and December. Therefore, there are four (4) released versions per year: `YY.3`, `YY.6`, `YY.9`, and `YY.12`. + +This release schedule provides: + +- a predictable release cadence, +- relatively short development windows allowing features to be regularly released, +- controlled [deprecations](#deprecation), and +- consistent stability with a yearly LTS. + +We also use the yearly release cycle in conjunction with our governance model, covered by the [S.C.O.P.E.](./scope.md) + +### Long term support v Interim releases + +Sanic releases a long term support release (aka "LTS") once a year in December. The LTS releases receive bug fixes and security updates for **24 months**. Interim releases throughout the year occur every three months, and are supported until the subsequent release. + +| Version | Release | LTS | Supported | +| ------- | ---------- | ------------- | --------- | +| 23.12 | 2023-12-31 | until 2025-12 | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | +| 0.8.3 | 2018-09-13 | | ⚪ | +| 0.7.0 | 2017-12-06 | | ⚪ | +| 0.6.0 | 2017-08-03 | | ⚪ | +| 0.5.4 | 2017-05-09 | | ⚪ | +| 0.4.1 | 2017-02-28 | | ⚪ | +| 0.3.1 | 2017-02-09 | | ⚪ | +| 0.2.0 | 2017-01-14 | | ⚪ | +| 0.1.9 | 2016-12-25 | | ⚪ | +| 0.1.0 | 2016-10-16 | | ⚪ | + +☑️ = security fixes\ +✅ = full support\ +⚪ = no support + +## Deprecation + +Before a feature is deprecated, or breaking changes are introduced into the API, it shall be publicized and shall appear with deprecation warnings through two release cycles. No deprecations shall be made in an LTS release. + +Breaking changes or feature removal may happen outside of these guidelines when absolutely warranted. These circumstances should be rare. For example, it might happen when no alternative is available to curtail a major security issue. From ac9d826c5cce08671d2250e2e9a28be2b3f667ac Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:05 +0200 Subject: [PATCH 172/698] New translations scope.md (Japanese) --- guide/content/ja/organization/scope.md | 257 +++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 guide/content/ja/organization/scope.md diff --git a/guide/content/ja/organization/scope.md b/guide/content/ja/organization/scope.md new file mode 100644 index 0000000000..47a1c4f085 --- /dev/null +++ b/guide/content/ja/organization/scope.md @@ -0,0 +1,257 @@ +# Sanic Community Organization Policy E-manual (SCOPE) + +.. attrs:: +:class: is-size-7 + +``` +_December 2019, version 1_ +``` + +## Goals + +To create a sustainable, community-driven organization around the Sanic projects that promote: (1) stability and predictability, (2) quick iteration and enhancement cycles, (3) engagement from outside contributors, (4) overall reliable software, and (5) a safe, rewarding environment for the community members. + +## Overview + +This Policy is the governance model for the Sanic Community Organization (“SCO”). The SCO is a meritocratic, consensus-based community organization responsible for all projects adopted by it. Anyone with an interest in one of the projects can join the community, contribute to the community or projects, and participate in the decision making process. This document describes how that participation takes place and how to set about earning merit within the project community. + +## Structure + +The SCO has multiple **projects**. Each project is represented by a single GitHub repository under the Sanic community umbrella. These projects are used by **users**, developed by **contributors**, governed by **core developers**, released by **release managers**, and ultimately overseen by a **steering council**. If this sounds similar to the Python project and PEP 8016 that is because it is intentionally designed that way. + +## Roles and responsibilities + +### Users + +Users are community members who have a need for the projects. They are the developers and personnel that download and install the packages. Users are the **most important** members of the community and without them the projects would have no purpose. Anyone can be a user and the licenses adopted by the projects shall be appropriate open source licenses. + +_The SCO asks its users to participate in the project and community as much as possible._ + +User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to): + +- evangelizing about the project (e.g. a link on a website and word-of-mouth awareness raising) +- informing developers of strengths and weaknesses from a new user perspective +- providing moral support (a ‘thank you’ goes a long way) +- providing financial support (the software is open source, but its developers need to eat) + +Users who continue to engage with the SCO, its projects, and its community will often become more and more involved. Such users may find themselves becoming contributors, as described in the next section. + +### Contributors + +Contributors are community members who contribute in concrete ways to one or more of the projects. Anyone can become a contributor and contributions can take many forms. Contributions and requirements are governed by each project separately by a contribution policy. + +There is **no expectation** of commitment to the project, **no specific skill requirements** and **no selection process**. + +In addition to their actions as users, contributors may also find themselves doing one or more of the following: + +- supporting new users (existing users are often the best people to support new users) +- reporting bugs +- identifying requirements +- providing graphics and web design +- Programming +- example use cases +- assisting with project infrastructure +- writing documentation +- fixing bugs +- adding features +- providing constructive opinions and engaging in community discourse + +Contributors engage with the projects through GitHub and the Community Forums. They submit changes to the projects itself via pull requests, which will be considered for inclusion in the project by the community at large. The Community Forums are the most appropriate place to ask for help when making that first contribution. + +Indeed one of the most important roles of a contributor may be to **simply engage in the community conversation**. Most decisions about the direction of a project are made by consensus. This is discussed in more detail below. In general, however, it is helpful for the health and direction of the projects for the contributors to **speak freely** (within the confines of the code of conduct) and **express their opinions and experiences** to help drive the consensus building. + +As contributors gain experience and familiarity with a project, their profile within, and commitment to, the community will increase. At some stage, they may find themselves being nominated for a core developer team. + +### Core Developer + +Each project under the SCO umbrella has its own team of core developers. They are the people in charge of that project. + +_What is a core developer?_ + +Core developers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Being a core developer allows contributors to more easily carry on with their project related activities by giving them direct access to the project’s resources. They can make changes directly to the project repository without having to submit changes via pull requests from a fork. + +This does not mean that a core developer is free to do what they want. In fact, core developers have no more direct authority over the final release of a package than do contributors. While this honor does indicate a valued member of the community who has demonstrated a healthy respect for the project’s aims and objectives, their work continues to be reviewed by the community before acceptance in an official release. + +_What can a core developer do on a project?_ + +Each project might define this role slightly differently. However, the general usage of this designation is that an individual has risen to a level of trust within the community such that they now are given some control. This comes in the form of push rights to non-protected branches, and the ability to have a voice in the approval of pull requests. + +The projects employ various communication mechanisms to ensure that all contributions are reviewed by the community as a whole. This includes tools provided by GitHub, as well as the Community Forums. By the time a contributor is invited to become a core developer, they should be familiar with the various tools and workflows as a user and then as a contributor. + +_How to become a core developer?_ + +Anyone can become a core developer; there are no special requirements, other than to have shown a willingness and ability to positively participate in the project as a team player. + +Typically, a potential core developer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time. However, there is **no technical or other skill** requirement for eligibility. + +New core developers can be **nominated by any existing core developer** at any time. At least twice a year (April and October) there will be a ballot process run by the Steering Council. Voting should be done by secret ballot. Each existing core developer for that project receives a number of votes equivalent to the number of nominees on the ballot. For example, if there are four nominees, then each existing core developer has four votes. The core developer may cast those votes however they choose, but may not vote for a single nominee more than once. A nominee must receive two-thirds approval from the number of cast ballots (not the number of eligible ballots). Once accepted by the core developers, it is the responsibility of the Steering Council to approve and finalize the nomination. The Steering Council does not have the right to determine whether a nominee is meritorious enough to receive the core developer title. However, they do retain the right to override a vote in cases where the health of the community would so require. + +Once the vote has been held, the aggregated voting results are published on the Community Forums. The nominee is entitled to request an explanation of any override against them. A nominee that fails to be admitted as a core developer may be nominated again in the future. + +It is important to recognize that being a core developer is a privilege, not a right. That privilege must be earned and once earned it can be removed by the Steering Council (see next section) in extreme circumstances. However, under normal circumstances the core developer title exists for as long as the individual wishes to continue engaging with the project and community. + +A committer who shows an above-average level of contribution to the project, particularly with respect to its strategic direction and long-term health, may be nominated to become a member of the Steering Council, or a Release Manager. This role is described below. + +_What are the rights and responsibilities of core developers?_ + +As discussed, the majority of decisions to be made are by consensus building. In certain circumstances where an issue has become more contentious, or a major decision needs to be made, the Release Manager or Steering Council may decide (or be required) to implement the RFC process, which is outlined in more detail below. + +It is also incumbent upon core developers to have a voice in the governance of the community. All core developers for all of the projects have the ability to be nominated to be on the Steering Council and vote in their elections. + +This Policy (the “SCOPE”) may only be changed under the authority of two-thirds of active core developers, except that in the first six (6) months after adoption, the core developers reserve the right to make changes under the authority of a simple majority of active core developers. + +_What if a core developer becomes inactive?_ + +It is hoped that all core developers participate and remain active on a regular basis in their projects. However, it is also understood that such commitments may not be realistic or possible from time to time. + +Therefore, the Steering Council has the duty to encourage participation and the responsibility to place core developers into an inactive status if they are no longer willing or capable to participate. The main purpose of this is **not to punish** a person for behavior, but to help the development process to continue for those that do remain active. + +To this end, a core developer that becomes “inactive” shall not have commit rights to a repository, and shall not participate in any votes. To be eligible to vote in an election, a core developer **must have been active** at the time of the previous scheduled project release. + +Inactive members may ask the Steering Council to reinstate their status at any time, and upon such request the Steering Council shall make the core developer active again. + +Individuals that know they will be unable to maintain their active status for a period are asked to be in communication with the Steering Council and declare themselves inactive if necessary. + +An “active” core developer is an individual that has participated in a meaningful way during the previous six months. Any further definition is within the discretion of the Steering Council. + +### Release Manager + +Core developers shall have access only to make commits and merges on non-protected branches. The “master” branch and other protected branches are controlled by the release management team for that project. Release managers shall be elected from the core development team by the core development team, and shall serve for a full release cycle. + +Each core developer team may decide how many release managers to have for each release cycle. It is highly encouraged that there be at least two release managers for a release cycle to help divide the responsibilities and not force too much effort upon a single person. However, there also should not be so many managers that their efforts are impeded. + +The main responsibilities of the release management team include: + +- push the development cycle forward by monitoring and facilitating technical discussions +- establish a release calendar and perform actions required to release packages +- approve pull requests to the master branch and other protected branches +- merge pull requests to the master branch and other protected branches + +The release managers **do not have the authority to veto or withhold a merge** of a pull request that otherwise meets contribution criteria and has been accepted by the community. It is not their responsibility to decide what should be developed, but rather that the decisions of the community are carried out and that the project is being moved forward. + +From time to time, a decision may need to be made that cannot be achieved through consensus. In that case, the release managers have the authority to call upon the removal of the decision to the RFC process. This should not occur regularly (unless required as discussed below), and its use should be discouraged in favor of the more communal consensus building strategy. + +Since not all projects have the same requirements, the specifics governing release managers on a project shall be set forth in an Appendix to this Policy, or in the project’s contribution guidelines. + +If necessary, the Steering Council has the right to remove a release manager that is derelict in their duties, or for other good cause. + +### Steering Council + +The Steering Council is the governing body consisting of those individuals identified as the “project owner” and having control of the resources and assets of the SCO. Their ultimate goal is to ensure the smooth operation of the projects by removing impediments, and assisting the members as needed. It is expected that they will be regular voices in the community. + +_What can the Steering Council do?_ + +The members of the Steering Council **do not individually have any more authority than any other core developer**, and shall not have any additional rights to make decisions, commits, merges, or the like on a project. + +However, as a body, the Steering Council has the following capacity: + +- accept, remand, and reject all RFCs +- enforce the community code of conduct +- administer community assets such as repositories, servers, forums, integration services, and the like (or, to delegate such authority to someone else) +- place core developers into inactive status where appropriate take any other enforcement measures afforded to it in this Policy, including, in extreme cases, removing core developers +- adopt or remove projects from the community umbrella + +It is highly encouraged that the Steering Council delegate its authority as much as possible, and where appropriate, to other willing community members. + +The Steering Council **does not have the authority** to change this Policy. + +_How many members are on the Steering Council?_ + +Four. + +While it seems like a committee with four votes may potentially end in a deadlock with no way to break a majority vote, the Steering Council is discouraged from voting as much as possible. Instead, it should try to work by consensus, and requires three consenting votes when it is necessary to vote on a matter. + +_How long do members serve on the Steering Council?_ + +A single term shall be for two calendar years starting in January. Terms shall be staggered so that each year there are two members continuing from the previous year’s council. + +Therefore, the inaugural vote shall have two positions available for a two year term, and two positions available for a one year term. + +There are no limits to the number of terms that can be served, and it is possible for an individual to serve consecutive terms. + +_Who runs the Steering Council?_ + +After the Steering Council is elected, the group shall collectively decide upon one person to act as the Chair. The Chair does not have any additional rights or authority over any other member of the Steering Council. + +The role of the Chair is merely as a coordinator and facilitator. The Chair is expected to ensure that all governance processes are adhered to. The position is more administrative and clerical, and is expected that the Chair sets agendas and coordinates discussion of the group. + +_How are council members elected?_ + +Once a year, **all eligible core developers** for each of the projects shall have the right to elect members to the Steering Council. + +Nominations shall be open from September 1 and shall close on September 30. After that, voting shall begin on October 1 and shall close on October 31. Every core developer active on the date of the June release of the Sanic Framework for that year shall be eligible to receive one vote per vacant seat on the Steering Council. For the sake of clarity, to be eligible to vote, a core developer **does not** need to be a core developer on Sanic Framework, but rather just have been active within their respective project on that date. + +The top recipients of votes shall be declared the winners. If there is any tie, it is highly encouraged that the tied nominees themselves resolve the dispute before a decision is made at random. + +In regards to the inaugural vote of the Steering Council, the top two vote-recipients shall serve for two years, and the next two vote-recipients shall assume the one-year seats. + +To be an eligible candidate for the Steering Council, the individual must have been a core developer in active status on at least one project for the previous twelve months. + +_What if there is a vacancy?_ + +If a vacancy on the Steering Council exists during a term, then the next highest vote-recipient in the previous election shall be offered to complete the remainder of the term. If one cannot be found this way, the Steering Council may decide the most appropriate course of action to fill the seat (whether by appointment, vote, or other means). + +If a member of the Steering Council becomes inactive, then that individual shall be removed from the Steering Council immediately and the seat shall become vacant. + +In extreme cases, the body of all core developers has the right to bring a vote to remove a member of the Steering Council for cause by a two-thirds majority of all eligible voting core developers. + +_How shall the Steering Council conduct its business?_ + +As much as possible, the Steering Council shall conduct its business and discussions in the open. Any member of the community should be allowed to enter the conversation with them. However, at times it may be necessary or appropriate for discussions to be held privately. Selecting the proper venue for conversations is part of the administrative duties of the Chair. + +While the specifics of how to operate are beyond the scope of the Policy, it is encouraged that the Steering Council attempt to meet at least one time per quarter in a “real-time” discussion. This could be achieved via video conferencing, live chatting, or other appropriate means. + +## Support + +All participants in the community are encouraged to provide support for users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a community member. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal. + +## Decision making process + +Decisions about the future of the projects are made through discussion with all members of the community, from the newest user to the most experienced member. Everyone has a voice. + +All non-sensitive project management discussion takes place on the community forums, or other designated channels. Occasionally, sensitive discussions may occur in private. + +In order to ensure that the project is not bogged down by endless discussion and continual voting, the project operates a policy of **lazy consensus**. This allows the majority of decisions to be made without resorting to a formal vote. For any **major decision** (as defined below), there is a separate Request for Comment (RFC) process. + +### Technical decisions + +Pull requests and technical decisions should generally fall into the following categories. + +- **Routine**: Documentation fixes, code changes that are for cleanup or additional testing. No functionality changes. +- **Minor**: Changes to the code base that either fix a bug, or introduce a trivial feature. No breaking changes. +- **Major**: Any change to the code base that breaks or deprecates existing API, alters operation in a non-trivial manner, or adds a significant feature. + +It is generally the responsibility of the release managers to make sure that changes to the repositories receive the proper authorization before merge. + +The release managers retain the authority to individually review and accept routine decisions that meet standards for code quality without additional input. + +### Lazy consensus + +Decision making (whether by the community or Steering Council) typically involves the following steps: + +- proposal +- discussion +- vote (if consensus is not reached through discussion) +- decision + +Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should post a message on the appropriate channel on the Community forums, or submit a pull request implementing the idea on GitHub. This will prompt a review and, if necessary, a discussion of the idea. + +The goal of this review and discussion is to gain approval for the contribution. Since most people in the project community have a shared vision, there is often little need for discussion in order to reach consensus. + +In general, as long as nobody explicitly opposes a proposal or patch, it is recognized as having the support of the community. This is called lazy consensus; that is, those who have not stated their opinion explicitly have implicitly agreed to the implementation of the proposal. + +Lazy consensus is a very important concept within the SCO. It is this process that allows a large group of people to efficiently reach consensus, as someone with no objections to a proposal need not spend time stating their position, and others need not spend time reading such messages. + +For lazy consensus to be effective, it is necessary to allow an appropriate amount of time before assuming that there are no objections to the proposal. This is somewhat dependent upon the circumstances, but it is generally assumed that 72 hours is reasonable. This requirement ensures that everyone is given enough time to read, digest and respond to the proposal. This time period is chosen so as to be as inclusive as possible of all participants, regardless of their location and time commitments. The facilitators of discussion (whether it be the Chair or the Release Managers, where applicable) shall be charged with determining the proper length of time for such consensus to be reached. + +As discussed above regarding so-called routine decisions, the release managers have the right to make decisions within a shorter period of time. In such cases, lazy consensus shall be implied. + +### Request for Comment (RFC) + +The Steering Council shall be in charge of overseeing the RFC process. It shall be a process that remains open to debate to all members of the community, and shall allow for ample time to consider a proposal and for members to respond and engage in meaningful discussion. + +The final decision is vested with the Steering Council. However, it is strongly discouraged that the Steering Council adopt a decision that is contrary to any consensus that may exist in the community. From time to time this may happen if there is a conflict between consensus and the overall project and community goals. + +An RFC shall be initiated by submission to the Steering Council in the public manner as set forth by the Steering Council. Debate shall continue and be facilitated by the Steering Council in general, and the Chair specifically. + +In circumstances that the Steering Council feels it is appropriate, the RFC process may be waived in favor of lazy consensus. From b519a4e0b9ba599b37f72aad47b8c7e2bd2d4dcd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:06 +0200 Subject: [PATCH 173/698] New translations scope.md (Korean) --- guide/content/ko/organization/scope.md | 257 +++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 guide/content/ko/organization/scope.md diff --git a/guide/content/ko/organization/scope.md b/guide/content/ko/organization/scope.md new file mode 100644 index 0000000000..47a1c4f085 --- /dev/null +++ b/guide/content/ko/organization/scope.md @@ -0,0 +1,257 @@ +# Sanic Community Organization Policy E-manual (SCOPE) + +.. attrs:: +:class: is-size-7 + +``` +_December 2019, version 1_ +``` + +## Goals + +To create a sustainable, community-driven organization around the Sanic projects that promote: (1) stability and predictability, (2) quick iteration and enhancement cycles, (3) engagement from outside contributors, (4) overall reliable software, and (5) a safe, rewarding environment for the community members. + +## Overview + +This Policy is the governance model for the Sanic Community Organization (“SCO”). The SCO is a meritocratic, consensus-based community organization responsible for all projects adopted by it. Anyone with an interest in one of the projects can join the community, contribute to the community or projects, and participate in the decision making process. This document describes how that participation takes place and how to set about earning merit within the project community. + +## Structure + +The SCO has multiple **projects**. Each project is represented by a single GitHub repository under the Sanic community umbrella. These projects are used by **users**, developed by **contributors**, governed by **core developers**, released by **release managers**, and ultimately overseen by a **steering council**. If this sounds similar to the Python project and PEP 8016 that is because it is intentionally designed that way. + +## Roles and responsibilities + +### Users + +Users are community members who have a need for the projects. They are the developers and personnel that download and install the packages. Users are the **most important** members of the community and without them the projects would have no purpose. Anyone can be a user and the licenses adopted by the projects shall be appropriate open source licenses. + +_The SCO asks its users to participate in the project and community as much as possible._ + +User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to): + +- evangelizing about the project (e.g. a link on a website and word-of-mouth awareness raising) +- informing developers of strengths and weaknesses from a new user perspective +- providing moral support (a ‘thank you’ goes a long way) +- providing financial support (the software is open source, but its developers need to eat) + +Users who continue to engage with the SCO, its projects, and its community will often become more and more involved. Such users may find themselves becoming contributors, as described in the next section. + +### Contributors + +Contributors are community members who contribute in concrete ways to one or more of the projects. Anyone can become a contributor and contributions can take many forms. Contributions and requirements are governed by each project separately by a contribution policy. + +There is **no expectation** of commitment to the project, **no specific skill requirements** and **no selection process**. + +In addition to their actions as users, contributors may also find themselves doing one or more of the following: + +- supporting new users (existing users are often the best people to support new users) +- reporting bugs +- identifying requirements +- providing graphics and web design +- Programming +- example use cases +- assisting with project infrastructure +- writing documentation +- fixing bugs +- adding features +- providing constructive opinions and engaging in community discourse + +Contributors engage with the projects through GitHub and the Community Forums. They submit changes to the projects itself via pull requests, which will be considered for inclusion in the project by the community at large. The Community Forums are the most appropriate place to ask for help when making that first contribution. + +Indeed one of the most important roles of a contributor may be to **simply engage in the community conversation**. Most decisions about the direction of a project are made by consensus. This is discussed in more detail below. In general, however, it is helpful for the health and direction of the projects for the contributors to **speak freely** (within the confines of the code of conduct) and **express their opinions and experiences** to help drive the consensus building. + +As contributors gain experience and familiarity with a project, their profile within, and commitment to, the community will increase. At some stage, they may find themselves being nominated for a core developer team. + +### Core Developer + +Each project under the SCO umbrella has its own team of core developers. They are the people in charge of that project. + +_What is a core developer?_ + +Core developers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Being a core developer allows contributors to more easily carry on with their project related activities by giving them direct access to the project’s resources. They can make changes directly to the project repository without having to submit changes via pull requests from a fork. + +This does not mean that a core developer is free to do what they want. In fact, core developers have no more direct authority over the final release of a package than do contributors. While this honor does indicate a valued member of the community who has demonstrated a healthy respect for the project’s aims and objectives, their work continues to be reviewed by the community before acceptance in an official release. + +_What can a core developer do on a project?_ + +Each project might define this role slightly differently. However, the general usage of this designation is that an individual has risen to a level of trust within the community such that they now are given some control. This comes in the form of push rights to non-protected branches, and the ability to have a voice in the approval of pull requests. + +The projects employ various communication mechanisms to ensure that all contributions are reviewed by the community as a whole. This includes tools provided by GitHub, as well as the Community Forums. By the time a contributor is invited to become a core developer, they should be familiar with the various tools and workflows as a user and then as a contributor. + +_How to become a core developer?_ + +Anyone can become a core developer; there are no special requirements, other than to have shown a willingness and ability to positively participate in the project as a team player. + +Typically, a potential core developer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time. However, there is **no technical or other skill** requirement for eligibility. + +New core developers can be **nominated by any existing core developer** at any time. At least twice a year (April and October) there will be a ballot process run by the Steering Council. Voting should be done by secret ballot. Each existing core developer for that project receives a number of votes equivalent to the number of nominees on the ballot. For example, if there are four nominees, then each existing core developer has four votes. The core developer may cast those votes however they choose, but may not vote for a single nominee more than once. A nominee must receive two-thirds approval from the number of cast ballots (not the number of eligible ballots). Once accepted by the core developers, it is the responsibility of the Steering Council to approve and finalize the nomination. The Steering Council does not have the right to determine whether a nominee is meritorious enough to receive the core developer title. However, they do retain the right to override a vote in cases where the health of the community would so require. + +Once the vote has been held, the aggregated voting results are published on the Community Forums. The nominee is entitled to request an explanation of any override against them. A nominee that fails to be admitted as a core developer may be nominated again in the future. + +It is important to recognize that being a core developer is a privilege, not a right. That privilege must be earned and once earned it can be removed by the Steering Council (see next section) in extreme circumstances. However, under normal circumstances the core developer title exists for as long as the individual wishes to continue engaging with the project and community. + +A committer who shows an above-average level of contribution to the project, particularly with respect to its strategic direction and long-term health, may be nominated to become a member of the Steering Council, or a Release Manager. This role is described below. + +_What are the rights and responsibilities of core developers?_ + +As discussed, the majority of decisions to be made are by consensus building. In certain circumstances where an issue has become more contentious, or a major decision needs to be made, the Release Manager or Steering Council may decide (or be required) to implement the RFC process, which is outlined in more detail below. + +It is also incumbent upon core developers to have a voice in the governance of the community. All core developers for all of the projects have the ability to be nominated to be on the Steering Council and vote in their elections. + +This Policy (the “SCOPE”) may only be changed under the authority of two-thirds of active core developers, except that in the first six (6) months after adoption, the core developers reserve the right to make changes under the authority of a simple majority of active core developers. + +_What if a core developer becomes inactive?_ + +It is hoped that all core developers participate and remain active on a regular basis in their projects. However, it is also understood that such commitments may not be realistic or possible from time to time. + +Therefore, the Steering Council has the duty to encourage participation and the responsibility to place core developers into an inactive status if they are no longer willing or capable to participate. The main purpose of this is **not to punish** a person for behavior, but to help the development process to continue for those that do remain active. + +To this end, a core developer that becomes “inactive” shall not have commit rights to a repository, and shall not participate in any votes. To be eligible to vote in an election, a core developer **must have been active** at the time of the previous scheduled project release. + +Inactive members may ask the Steering Council to reinstate their status at any time, and upon such request the Steering Council shall make the core developer active again. + +Individuals that know they will be unable to maintain their active status for a period are asked to be in communication with the Steering Council and declare themselves inactive if necessary. + +An “active” core developer is an individual that has participated in a meaningful way during the previous six months. Any further definition is within the discretion of the Steering Council. + +### Release Manager + +Core developers shall have access only to make commits and merges on non-protected branches. The “master” branch and other protected branches are controlled by the release management team for that project. Release managers shall be elected from the core development team by the core development team, and shall serve for a full release cycle. + +Each core developer team may decide how many release managers to have for each release cycle. It is highly encouraged that there be at least two release managers for a release cycle to help divide the responsibilities and not force too much effort upon a single person. However, there also should not be so many managers that their efforts are impeded. + +The main responsibilities of the release management team include: + +- push the development cycle forward by monitoring and facilitating technical discussions +- establish a release calendar and perform actions required to release packages +- approve pull requests to the master branch and other protected branches +- merge pull requests to the master branch and other protected branches + +The release managers **do not have the authority to veto or withhold a merge** of a pull request that otherwise meets contribution criteria and has been accepted by the community. It is not their responsibility to decide what should be developed, but rather that the decisions of the community are carried out and that the project is being moved forward. + +From time to time, a decision may need to be made that cannot be achieved through consensus. In that case, the release managers have the authority to call upon the removal of the decision to the RFC process. This should not occur regularly (unless required as discussed below), and its use should be discouraged in favor of the more communal consensus building strategy. + +Since not all projects have the same requirements, the specifics governing release managers on a project shall be set forth in an Appendix to this Policy, or in the project’s contribution guidelines. + +If necessary, the Steering Council has the right to remove a release manager that is derelict in their duties, or for other good cause. + +### Steering Council + +The Steering Council is the governing body consisting of those individuals identified as the “project owner” and having control of the resources and assets of the SCO. Their ultimate goal is to ensure the smooth operation of the projects by removing impediments, and assisting the members as needed. It is expected that they will be regular voices in the community. + +_What can the Steering Council do?_ + +The members of the Steering Council **do not individually have any more authority than any other core developer**, and shall not have any additional rights to make decisions, commits, merges, or the like on a project. + +However, as a body, the Steering Council has the following capacity: + +- accept, remand, and reject all RFCs +- enforce the community code of conduct +- administer community assets such as repositories, servers, forums, integration services, and the like (or, to delegate such authority to someone else) +- place core developers into inactive status where appropriate take any other enforcement measures afforded to it in this Policy, including, in extreme cases, removing core developers +- adopt or remove projects from the community umbrella + +It is highly encouraged that the Steering Council delegate its authority as much as possible, and where appropriate, to other willing community members. + +The Steering Council **does not have the authority** to change this Policy. + +_How many members are on the Steering Council?_ + +Four. + +While it seems like a committee with four votes may potentially end in a deadlock with no way to break a majority vote, the Steering Council is discouraged from voting as much as possible. Instead, it should try to work by consensus, and requires three consenting votes when it is necessary to vote on a matter. + +_How long do members serve on the Steering Council?_ + +A single term shall be for two calendar years starting in January. Terms shall be staggered so that each year there are two members continuing from the previous year’s council. + +Therefore, the inaugural vote shall have two positions available for a two year term, and two positions available for a one year term. + +There are no limits to the number of terms that can be served, and it is possible for an individual to serve consecutive terms. + +_Who runs the Steering Council?_ + +After the Steering Council is elected, the group shall collectively decide upon one person to act as the Chair. The Chair does not have any additional rights or authority over any other member of the Steering Council. + +The role of the Chair is merely as a coordinator and facilitator. The Chair is expected to ensure that all governance processes are adhered to. The position is more administrative and clerical, and is expected that the Chair sets agendas and coordinates discussion of the group. + +_How are council members elected?_ + +Once a year, **all eligible core developers** for each of the projects shall have the right to elect members to the Steering Council. + +Nominations shall be open from September 1 and shall close on September 30. After that, voting shall begin on October 1 and shall close on October 31. Every core developer active on the date of the June release of the Sanic Framework for that year shall be eligible to receive one vote per vacant seat on the Steering Council. For the sake of clarity, to be eligible to vote, a core developer **does not** need to be a core developer on Sanic Framework, but rather just have been active within their respective project on that date. + +The top recipients of votes shall be declared the winners. If there is any tie, it is highly encouraged that the tied nominees themselves resolve the dispute before a decision is made at random. + +In regards to the inaugural vote of the Steering Council, the top two vote-recipients shall serve for two years, and the next two vote-recipients shall assume the one-year seats. + +To be an eligible candidate for the Steering Council, the individual must have been a core developer in active status on at least one project for the previous twelve months. + +_What if there is a vacancy?_ + +If a vacancy on the Steering Council exists during a term, then the next highest vote-recipient in the previous election shall be offered to complete the remainder of the term. If one cannot be found this way, the Steering Council may decide the most appropriate course of action to fill the seat (whether by appointment, vote, or other means). + +If a member of the Steering Council becomes inactive, then that individual shall be removed from the Steering Council immediately and the seat shall become vacant. + +In extreme cases, the body of all core developers has the right to bring a vote to remove a member of the Steering Council for cause by a two-thirds majority of all eligible voting core developers. + +_How shall the Steering Council conduct its business?_ + +As much as possible, the Steering Council shall conduct its business and discussions in the open. Any member of the community should be allowed to enter the conversation with them. However, at times it may be necessary or appropriate for discussions to be held privately. Selecting the proper venue for conversations is part of the administrative duties of the Chair. + +While the specifics of how to operate are beyond the scope of the Policy, it is encouraged that the Steering Council attempt to meet at least one time per quarter in a “real-time” discussion. This could be achieved via video conferencing, live chatting, or other appropriate means. + +## Support + +All participants in the community are encouraged to provide support for users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a community member. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal. + +## Decision making process + +Decisions about the future of the projects are made through discussion with all members of the community, from the newest user to the most experienced member. Everyone has a voice. + +All non-sensitive project management discussion takes place on the community forums, or other designated channels. Occasionally, sensitive discussions may occur in private. + +In order to ensure that the project is not bogged down by endless discussion and continual voting, the project operates a policy of **lazy consensus**. This allows the majority of decisions to be made without resorting to a formal vote. For any **major decision** (as defined below), there is a separate Request for Comment (RFC) process. + +### Technical decisions + +Pull requests and technical decisions should generally fall into the following categories. + +- **Routine**: Documentation fixes, code changes that are for cleanup or additional testing. No functionality changes. +- **Minor**: Changes to the code base that either fix a bug, or introduce a trivial feature. No breaking changes. +- **Major**: Any change to the code base that breaks or deprecates existing API, alters operation in a non-trivial manner, or adds a significant feature. + +It is generally the responsibility of the release managers to make sure that changes to the repositories receive the proper authorization before merge. + +The release managers retain the authority to individually review and accept routine decisions that meet standards for code quality without additional input. + +### Lazy consensus + +Decision making (whether by the community or Steering Council) typically involves the following steps: + +- proposal +- discussion +- vote (if consensus is not reached through discussion) +- decision + +Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should post a message on the appropriate channel on the Community forums, or submit a pull request implementing the idea on GitHub. This will prompt a review and, if necessary, a discussion of the idea. + +The goal of this review and discussion is to gain approval for the contribution. Since most people in the project community have a shared vision, there is often little need for discussion in order to reach consensus. + +In general, as long as nobody explicitly opposes a proposal or patch, it is recognized as having the support of the community. This is called lazy consensus; that is, those who have not stated their opinion explicitly have implicitly agreed to the implementation of the proposal. + +Lazy consensus is a very important concept within the SCO. It is this process that allows a large group of people to efficiently reach consensus, as someone with no objections to a proposal need not spend time stating their position, and others need not spend time reading such messages. + +For lazy consensus to be effective, it is necessary to allow an appropriate amount of time before assuming that there are no objections to the proposal. This is somewhat dependent upon the circumstances, but it is generally assumed that 72 hours is reasonable. This requirement ensures that everyone is given enough time to read, digest and respond to the proposal. This time period is chosen so as to be as inclusive as possible of all participants, regardless of their location and time commitments. The facilitators of discussion (whether it be the Chair or the Release Managers, where applicable) shall be charged with determining the proper length of time for such consensus to be reached. + +As discussed above regarding so-called routine decisions, the release managers have the right to make decisions within a shorter period of time. In such cases, lazy consensus shall be implied. + +### Request for Comment (RFC) + +The Steering Council shall be in charge of overseeing the RFC process. It shall be a process that remains open to debate to all members of the community, and shall allow for ample time to consider a proposal and for members to respond and engage in meaningful discussion. + +The final decision is vested with the Steering Council. However, it is strongly discouraged that the Steering Council adopt a decision that is contrary to any consensus that may exist in the community. From time to time this may happen if there is a conflict between consensus and the overall project and community goals. + +An RFC shall be initiated by submission to the Steering Council in the public manner as set forth by the Steering Council. Debate shall continue and be facilitated by the Steering Council in general, and the Chair specifically. + +In circumstances that the Steering Council feels it is appropriate, the RFC process may be waived in favor of lazy consensus. From d9977c050b189e6caef04725e52f75673b7008bc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:07 +0200 Subject: [PATCH 174/698] New translations scope.md (Chinese Simplified) --- guide/content/zh/organization/scope.md | 257 +++++++++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 guide/content/zh/organization/scope.md diff --git a/guide/content/zh/organization/scope.md b/guide/content/zh/organization/scope.md new file mode 100644 index 0000000000..47a1c4f085 --- /dev/null +++ b/guide/content/zh/organization/scope.md @@ -0,0 +1,257 @@ +# Sanic Community Organization Policy E-manual (SCOPE) + +.. attrs:: +:class: is-size-7 + +``` +_December 2019, version 1_ +``` + +## Goals + +To create a sustainable, community-driven organization around the Sanic projects that promote: (1) stability and predictability, (2) quick iteration and enhancement cycles, (3) engagement from outside contributors, (4) overall reliable software, and (5) a safe, rewarding environment for the community members. + +## Overview + +This Policy is the governance model for the Sanic Community Organization (“SCO”). The SCO is a meritocratic, consensus-based community organization responsible for all projects adopted by it. Anyone with an interest in one of the projects can join the community, contribute to the community or projects, and participate in the decision making process. This document describes how that participation takes place and how to set about earning merit within the project community. + +## Structure + +The SCO has multiple **projects**. Each project is represented by a single GitHub repository under the Sanic community umbrella. These projects are used by **users**, developed by **contributors**, governed by **core developers**, released by **release managers**, and ultimately overseen by a **steering council**. If this sounds similar to the Python project and PEP 8016 that is because it is intentionally designed that way. + +## Roles and responsibilities + +### Users + +Users are community members who have a need for the projects. They are the developers and personnel that download and install the packages. Users are the **most important** members of the community and without them the projects would have no purpose. Anyone can be a user and the licenses adopted by the projects shall be appropriate open source licenses. + +_The SCO asks its users to participate in the project and community as much as possible._ + +User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to): + +- evangelizing about the project (e.g. a link on a website and word-of-mouth awareness raising) +- informing developers of strengths and weaknesses from a new user perspective +- providing moral support (a ‘thank you’ goes a long way) +- providing financial support (the software is open source, but its developers need to eat) + +Users who continue to engage with the SCO, its projects, and its community will often become more and more involved. Such users may find themselves becoming contributors, as described in the next section. + +### Contributors + +Contributors are community members who contribute in concrete ways to one or more of the projects. Anyone can become a contributor and contributions can take many forms. Contributions and requirements are governed by each project separately by a contribution policy. + +There is **no expectation** of commitment to the project, **no specific skill requirements** and **no selection process**. + +In addition to their actions as users, contributors may also find themselves doing one or more of the following: + +- supporting new users (existing users are often the best people to support new users) +- reporting bugs +- identifying requirements +- providing graphics and web design +- Programming +- example use cases +- assisting with project infrastructure +- writing documentation +- fixing bugs +- adding features +- providing constructive opinions and engaging in community discourse + +Contributors engage with the projects through GitHub and the Community Forums. They submit changes to the projects itself via pull requests, which will be considered for inclusion in the project by the community at large. The Community Forums are the most appropriate place to ask for help when making that first contribution. + +Indeed one of the most important roles of a contributor may be to **simply engage in the community conversation**. Most decisions about the direction of a project are made by consensus. This is discussed in more detail below. In general, however, it is helpful for the health and direction of the projects for the contributors to **speak freely** (within the confines of the code of conduct) and **express their opinions and experiences** to help drive the consensus building. + +As contributors gain experience and familiarity with a project, their profile within, and commitment to, the community will increase. At some stage, they may find themselves being nominated for a core developer team. + +### Core Developer + +Each project under the SCO umbrella has its own team of core developers. They are the people in charge of that project. + +_What is a core developer?_ + +Core developers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Being a core developer allows contributors to more easily carry on with their project related activities by giving them direct access to the project’s resources. They can make changes directly to the project repository without having to submit changes via pull requests from a fork. + +This does not mean that a core developer is free to do what they want. In fact, core developers have no more direct authority over the final release of a package than do contributors. While this honor does indicate a valued member of the community who has demonstrated a healthy respect for the project’s aims and objectives, their work continues to be reviewed by the community before acceptance in an official release. + +_What can a core developer do on a project?_ + +Each project might define this role slightly differently. However, the general usage of this designation is that an individual has risen to a level of trust within the community such that they now are given some control. This comes in the form of push rights to non-protected branches, and the ability to have a voice in the approval of pull requests. + +The projects employ various communication mechanisms to ensure that all contributions are reviewed by the community as a whole. This includes tools provided by GitHub, as well as the Community Forums. By the time a contributor is invited to become a core developer, they should be familiar with the various tools and workflows as a user and then as a contributor. + +_How to become a core developer?_ + +Anyone can become a core developer; there are no special requirements, other than to have shown a willingness and ability to positively participate in the project as a team player. + +Typically, a potential core developer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time. However, there is **no technical or other skill** requirement for eligibility. + +New core developers can be **nominated by any existing core developer** at any time. At least twice a year (April and October) there will be a ballot process run by the Steering Council. Voting should be done by secret ballot. Each existing core developer for that project receives a number of votes equivalent to the number of nominees on the ballot. For example, if there are four nominees, then each existing core developer has four votes. The core developer may cast those votes however they choose, but may not vote for a single nominee more than once. A nominee must receive two-thirds approval from the number of cast ballots (not the number of eligible ballots). Once accepted by the core developers, it is the responsibility of the Steering Council to approve and finalize the nomination. The Steering Council does not have the right to determine whether a nominee is meritorious enough to receive the core developer title. However, they do retain the right to override a vote in cases where the health of the community would so require. + +Once the vote has been held, the aggregated voting results are published on the Community Forums. The nominee is entitled to request an explanation of any override against them. A nominee that fails to be admitted as a core developer may be nominated again in the future. + +It is important to recognize that being a core developer is a privilege, not a right. That privilege must be earned and once earned it can be removed by the Steering Council (see next section) in extreme circumstances. However, under normal circumstances the core developer title exists for as long as the individual wishes to continue engaging with the project and community. + +A committer who shows an above-average level of contribution to the project, particularly with respect to its strategic direction and long-term health, may be nominated to become a member of the Steering Council, or a Release Manager. This role is described below. + +_What are the rights and responsibilities of core developers?_ + +As discussed, the majority of decisions to be made are by consensus building. In certain circumstances where an issue has become more contentious, or a major decision needs to be made, the Release Manager or Steering Council may decide (or be required) to implement the RFC process, which is outlined in more detail below. + +It is also incumbent upon core developers to have a voice in the governance of the community. All core developers for all of the projects have the ability to be nominated to be on the Steering Council and vote in their elections. + +This Policy (the “SCOPE”) may only be changed under the authority of two-thirds of active core developers, except that in the first six (6) months after adoption, the core developers reserve the right to make changes under the authority of a simple majority of active core developers. + +_What if a core developer becomes inactive?_ + +It is hoped that all core developers participate and remain active on a regular basis in their projects. However, it is also understood that such commitments may not be realistic or possible from time to time. + +Therefore, the Steering Council has the duty to encourage participation and the responsibility to place core developers into an inactive status if they are no longer willing or capable to participate. The main purpose of this is **not to punish** a person for behavior, but to help the development process to continue for those that do remain active. + +To this end, a core developer that becomes “inactive” shall not have commit rights to a repository, and shall not participate in any votes. To be eligible to vote in an election, a core developer **must have been active** at the time of the previous scheduled project release. + +Inactive members may ask the Steering Council to reinstate their status at any time, and upon such request the Steering Council shall make the core developer active again. + +Individuals that know they will be unable to maintain their active status for a period are asked to be in communication with the Steering Council and declare themselves inactive if necessary. + +An “active” core developer is an individual that has participated in a meaningful way during the previous six months. Any further definition is within the discretion of the Steering Council. + +### Release Manager + +Core developers shall have access only to make commits and merges on non-protected branches. The “master” branch and other protected branches are controlled by the release management team for that project. Release managers shall be elected from the core development team by the core development team, and shall serve for a full release cycle. + +Each core developer team may decide how many release managers to have for each release cycle. It is highly encouraged that there be at least two release managers for a release cycle to help divide the responsibilities and not force too much effort upon a single person. However, there also should not be so many managers that their efforts are impeded. + +The main responsibilities of the release management team include: + +- push the development cycle forward by monitoring and facilitating technical discussions +- establish a release calendar and perform actions required to release packages +- approve pull requests to the master branch and other protected branches +- merge pull requests to the master branch and other protected branches + +The release managers **do not have the authority to veto or withhold a merge** of a pull request that otherwise meets contribution criteria and has been accepted by the community. It is not their responsibility to decide what should be developed, but rather that the decisions of the community are carried out and that the project is being moved forward. + +From time to time, a decision may need to be made that cannot be achieved through consensus. In that case, the release managers have the authority to call upon the removal of the decision to the RFC process. This should not occur regularly (unless required as discussed below), and its use should be discouraged in favor of the more communal consensus building strategy. + +Since not all projects have the same requirements, the specifics governing release managers on a project shall be set forth in an Appendix to this Policy, or in the project’s contribution guidelines. + +If necessary, the Steering Council has the right to remove a release manager that is derelict in their duties, or for other good cause. + +### Steering Council + +The Steering Council is the governing body consisting of those individuals identified as the “project owner” and having control of the resources and assets of the SCO. Their ultimate goal is to ensure the smooth operation of the projects by removing impediments, and assisting the members as needed. It is expected that they will be regular voices in the community. + +_What can the Steering Council do?_ + +The members of the Steering Council **do not individually have any more authority than any other core developer**, and shall not have any additional rights to make decisions, commits, merges, or the like on a project. + +However, as a body, the Steering Council has the following capacity: + +- accept, remand, and reject all RFCs +- enforce the community code of conduct +- administer community assets such as repositories, servers, forums, integration services, and the like (or, to delegate such authority to someone else) +- place core developers into inactive status where appropriate take any other enforcement measures afforded to it in this Policy, including, in extreme cases, removing core developers +- adopt or remove projects from the community umbrella + +It is highly encouraged that the Steering Council delegate its authority as much as possible, and where appropriate, to other willing community members. + +The Steering Council **does not have the authority** to change this Policy. + +_How many members are on the Steering Council?_ + +Four. + +While it seems like a committee with four votes may potentially end in a deadlock with no way to break a majority vote, the Steering Council is discouraged from voting as much as possible. Instead, it should try to work by consensus, and requires three consenting votes when it is necessary to vote on a matter. + +_How long do members serve on the Steering Council?_ + +A single term shall be for two calendar years starting in January. Terms shall be staggered so that each year there are two members continuing from the previous year’s council. + +Therefore, the inaugural vote shall have two positions available for a two year term, and two positions available for a one year term. + +There are no limits to the number of terms that can be served, and it is possible for an individual to serve consecutive terms. + +_Who runs the Steering Council?_ + +After the Steering Council is elected, the group shall collectively decide upon one person to act as the Chair. The Chair does not have any additional rights or authority over any other member of the Steering Council. + +The role of the Chair is merely as a coordinator and facilitator. The Chair is expected to ensure that all governance processes are adhered to. The position is more administrative and clerical, and is expected that the Chair sets agendas and coordinates discussion of the group. + +_How are council members elected?_ + +Once a year, **all eligible core developers** for each of the projects shall have the right to elect members to the Steering Council. + +Nominations shall be open from September 1 and shall close on September 30. After that, voting shall begin on October 1 and shall close on October 31. Every core developer active on the date of the June release of the Sanic Framework for that year shall be eligible to receive one vote per vacant seat on the Steering Council. For the sake of clarity, to be eligible to vote, a core developer **does not** need to be a core developer on Sanic Framework, but rather just have been active within their respective project on that date. + +The top recipients of votes shall be declared the winners. If there is any tie, it is highly encouraged that the tied nominees themselves resolve the dispute before a decision is made at random. + +In regards to the inaugural vote of the Steering Council, the top two vote-recipients shall serve for two years, and the next two vote-recipients shall assume the one-year seats. + +To be an eligible candidate for the Steering Council, the individual must have been a core developer in active status on at least one project for the previous twelve months. + +_What if there is a vacancy?_ + +If a vacancy on the Steering Council exists during a term, then the next highest vote-recipient in the previous election shall be offered to complete the remainder of the term. If one cannot be found this way, the Steering Council may decide the most appropriate course of action to fill the seat (whether by appointment, vote, or other means). + +If a member of the Steering Council becomes inactive, then that individual shall be removed from the Steering Council immediately and the seat shall become vacant. + +In extreme cases, the body of all core developers has the right to bring a vote to remove a member of the Steering Council for cause by a two-thirds majority of all eligible voting core developers. + +_How shall the Steering Council conduct its business?_ + +As much as possible, the Steering Council shall conduct its business and discussions in the open. Any member of the community should be allowed to enter the conversation with them. However, at times it may be necessary or appropriate for discussions to be held privately. Selecting the proper venue for conversations is part of the administrative duties of the Chair. + +While the specifics of how to operate are beyond the scope of the Policy, it is encouraged that the Steering Council attempt to meet at least one time per quarter in a “real-time” discussion. This could be achieved via video conferencing, live chatting, or other appropriate means. + +## Support + +All participants in the community are encouraged to provide support for users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a community member. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal. + +## Decision making process + +Decisions about the future of the projects are made through discussion with all members of the community, from the newest user to the most experienced member. Everyone has a voice. + +All non-sensitive project management discussion takes place on the community forums, or other designated channels. Occasionally, sensitive discussions may occur in private. + +In order to ensure that the project is not bogged down by endless discussion and continual voting, the project operates a policy of **lazy consensus**. This allows the majority of decisions to be made without resorting to a formal vote. For any **major decision** (as defined below), there is a separate Request for Comment (RFC) process. + +### Technical decisions + +Pull requests and technical decisions should generally fall into the following categories. + +- **Routine**: Documentation fixes, code changes that are for cleanup or additional testing. No functionality changes. +- **Minor**: Changes to the code base that either fix a bug, or introduce a trivial feature. No breaking changes. +- **Major**: Any change to the code base that breaks or deprecates existing API, alters operation in a non-trivial manner, or adds a significant feature. + +It is generally the responsibility of the release managers to make sure that changes to the repositories receive the proper authorization before merge. + +The release managers retain the authority to individually review and accept routine decisions that meet standards for code quality without additional input. + +### Lazy consensus + +Decision making (whether by the community or Steering Council) typically involves the following steps: + +- proposal +- discussion +- vote (if consensus is not reached through discussion) +- decision + +Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should post a message on the appropriate channel on the Community forums, or submit a pull request implementing the idea on GitHub. This will prompt a review and, if necessary, a discussion of the idea. + +The goal of this review and discussion is to gain approval for the contribution. Since most people in the project community have a shared vision, there is often little need for discussion in order to reach consensus. + +In general, as long as nobody explicitly opposes a proposal or patch, it is recognized as having the support of the community. This is called lazy consensus; that is, those who have not stated their opinion explicitly have implicitly agreed to the implementation of the proposal. + +Lazy consensus is a very important concept within the SCO. It is this process that allows a large group of people to efficiently reach consensus, as someone with no objections to a proposal need not spend time stating their position, and others need not spend time reading such messages. + +For lazy consensus to be effective, it is necessary to allow an appropriate amount of time before assuming that there are no objections to the proposal. This is somewhat dependent upon the circumstances, but it is generally assumed that 72 hours is reasonable. This requirement ensures that everyone is given enough time to read, digest and respond to the proposal. This time period is chosen so as to be as inclusive as possible of all participants, regardless of their location and time commitments. The facilitators of discussion (whether it be the Chair or the Release Managers, where applicable) shall be charged with determining the proper length of time for such consensus to be reached. + +As discussed above regarding so-called routine decisions, the release managers have the right to make decisions within a shorter period of time. In such cases, lazy consensus shall be implied. + +### Request for Comment (RFC) + +The Steering Council shall be in charge of overseeing the RFC process. It shall be a process that remains open to debate to all members of the community, and shall allow for ample time to consider a proposal and for members to respond and engage in meaningful discussion. + +The final decision is vested with the Steering Council. However, it is strongly discouraged that the Steering Council adopt a decision that is contrary to any consensus that may exist in the community. From time to time this may happen if there is a conflict between consensus and the overall project and community goals. + +An RFC shall be initiated by submission to the Steering Council in the public manner as set forth by the Steering Council. Debate shall continue and be facilitated by the Steering Council in general, and the Chair specifically. + +In circumstances that the Steering Council feels it is appropriate, the RFC process may be waived in favor of lazy consensus. From a8611bc69e7dd3f95d15e0f6eda7f3c2b927e6d3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:09 +0200 Subject: [PATCH 175/698] New translations configuration.md (Japanese) --- .../ja/plugins/sanic-ext/configuration.md | 288 ++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/configuration.md diff --git a/guide/content/ja/plugins/sanic-ext/configuration.md b/guide/content/ja/plugins/sanic-ext/configuration.md new file mode 100644 index 0000000000..1443cfc6e9 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/configuration.md @@ -0,0 +1,288 @@ +--- +title: Sanic Extensions - Configuration +--- + +# Configuration + +Sanic Extensions can be configured in all of the same ways that [you can configure Sanic](../../guide/deployment/configuration.md). That makes configuring Sanic Extensions very easy. + +```python +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` + +However, there are a few more configuration options that should be considered. + +## Manual `extend` + +.. column:: + +``` +Even though Sanic Extensions will automatically attach to your application, you can manually choose `extend`. When you do that, you can pass all of the configuration values as a keyword arguments (lowercase). +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.extend(oas_url_prefix="/apidocs") +``` +```` + +.. column:: + +``` +Or, alternatively they could be passed all at once as a single `dict`. +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.extend(config={"oas_url_prefix": "/apidocs"}) +``` +```` + +.. column:: + +``` +Both of these solutions suffers from the fact that the names of the configuration settings are not discoverable by an IDE. Therefore, there is also a type annotated object that you can use. This should help the development experience. +``` + +.. column:: + +```` +```python +from sanic_ext import Config + +app = Sanic("MyApp") +app.extend(config=Config(oas_url_prefix="/apidocs")) +``` +```` + +## Settings + +.. note:: + +```` +Often, the easiest way to change these for an application (since they likely are not going to change dependent upon an environment), is to set them directly on the `app.config` object. + +Simply use the capitalized version of the configuration key as shown here: + +```python +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` +```` + +### `cors` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable CORS protection + +### `cors_allow_headers` + +- **Type**: `str` +- **Default**: `"*"` +- **Description**: Value of the header: `access-control-allow-headers` + +### `cors_always_send` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to always send the header: `access-control-allow-origin` + +### `cors_automatic_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to automatically generate `OPTIONS` endpoints for routes that do _not_ already have one defined + +### `cors_expose_headers` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-expose-headers` + +### `cors_max_age` + +- **Type**: `int` +- **Default**: `5` +- **Description**: Value of the header: `access-control-max-age` + +### `cors_methods` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-access-control-allow-methods` + +### `cors_origins` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-allow-origin` + +.. warning:: + +``` +Be very careful if you place `*` here. Do not do this unless you know what you are doing as it can be a security issue. +``` + +### `cors_send_wildcard` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Whether to send a wildcard origin instead of the incoming request origin + +### `cors_supports_credentials` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Value of the header: `access-control-allow-credentials` + +### `cors_vary_header` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to add the `vary` header + +### `http_all_methods` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Adds the HTTP `CONNECT` and `TRACE` methods as allowable + +### `http_auto_head` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Automatically adds `HEAD` handlers to any `GET` routes + +### `http_auto_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Automatically adds `OPTIONS` handlers to any routes without + +### `http_auto_trace` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Automatically adds `TRACE` handlers to any routes without + +### `oas` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable OpenAPI specification generation + +### `oas_autodoc` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to automatically extract OpenAPI details from the docstring of a route function + +### `oas_ignore_head` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: WHen `True`, it will not add `HEAD` endpoints into the OpenAPI specification + +### `oas_ignore_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: WHen `True`, it will not add `OPTIONS` endpoints into the OpenAPI specification + +### `oas_path_to_redoc_html` + +- **Type**: `Optional[str]` +- **Default**: `None` +- **Description**: Path to HTML file to override the existing Redoc HTML + +### `oas_path_to_swagger_html` + +- **Type**: `Optional[str]` +- **Default**: `None` +- **Description**: Path to HTML file to override the existing Swagger HTML + +### `oas_ui_default` + +- **Type**: `Optional[str]` +- **Default**: `"redoc"` +- **Description**: Which OAS documentation to serve on the bare `oas_url_prefix` endpoint; when `None` there will be no documentation at that location + +### `oas_ui_redoc` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable the Redoc UI + +### `oas_ui_swagger` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable the Swagger UI + +### `oas_ui_swagger_version` + +- **Type**: `str` +- **Default**: `"4.1.0"` +- **Description**: Which Swagger version to use + +### `oas_uri_to_config` + +- **Type**: `str` +- **Default**: `"/swagger-config"` +- **Description**: Path to serve the Swagger configurtaion + +### `oas_uri_to_json` + +- **Type**: `str` +- **Default**: `"/openapi.json"` +- **Description**: Path to serve the OpenAPI JSON + +### `oas_uri_to_redoc` + +- **Type**: `str` +- **Default**: `"/redoc"` +- **Description**: Path to Redoc + +### `oas_uri_to_swagger` + +- **Type**: `str` +- **Default**: `"/swagger"` +- **Description**: Path to Swagger + +### `oas_url_prefix` + +- **Type**: `str` +- **Default**: `"/docs"` +- **Description**: URL prefix for the Blueprint that all of the OAS documentation witll attach to + +### `swagger_ui_configuration` + +- **Type**: `Dict[str, Any]` +- **Default**: `{"apisSorter": "alpha", "operationsSorter": "alpha", "docExpansion": "full"}` +- **Description**: The Swagger documentation to be served to the frontend + +### `templating_enable_async` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to set `enable_async` on the Jinja `Environment` + +### `templating_path_to_templates` + +- **Type**: `Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]] ` +- **Default**: `templates` +- **Description**: A single path, or multiple paths to where your template files are located + +### `trace_excluded_headers` + +- **Type**: `Sequence[str]` +- **Default**: `("authorization", "cookie")` +- **Description**: Which headers should be suppresed from responses to `TRACE` requests From c09029c913945585effbfa74b6b021dfbd0a7add Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:10 +0200 Subject: [PATCH 176/698] New translations configuration.md (Korean) --- .../ko/plugins/sanic-ext/configuration.md | 288 ++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/configuration.md diff --git a/guide/content/ko/plugins/sanic-ext/configuration.md b/guide/content/ko/plugins/sanic-ext/configuration.md new file mode 100644 index 0000000000..1443cfc6e9 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/configuration.md @@ -0,0 +1,288 @@ +--- +title: Sanic Extensions - Configuration +--- + +# Configuration + +Sanic Extensions can be configured in all of the same ways that [you can configure Sanic](../../guide/deployment/configuration.md). That makes configuring Sanic Extensions very easy. + +```python +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` + +However, there are a few more configuration options that should be considered. + +## Manual `extend` + +.. column:: + +``` +Even though Sanic Extensions will automatically attach to your application, you can manually choose `extend`. When you do that, you can pass all of the configuration values as a keyword arguments (lowercase). +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.extend(oas_url_prefix="/apidocs") +``` +```` + +.. column:: + +``` +Or, alternatively they could be passed all at once as a single `dict`. +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.extend(config={"oas_url_prefix": "/apidocs"}) +``` +```` + +.. column:: + +``` +Both of these solutions suffers from the fact that the names of the configuration settings are not discoverable by an IDE. Therefore, there is also a type annotated object that you can use. This should help the development experience. +``` + +.. column:: + +```` +```python +from sanic_ext import Config + +app = Sanic("MyApp") +app.extend(config=Config(oas_url_prefix="/apidocs")) +``` +```` + +## Settings + +.. note:: + +```` +Often, the easiest way to change these for an application (since they likely are not going to change dependent upon an environment), is to set them directly on the `app.config` object. + +Simply use the capitalized version of the configuration key as shown here: + +```python +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` +```` + +### `cors` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable CORS protection + +### `cors_allow_headers` + +- **Type**: `str` +- **Default**: `"*"` +- **Description**: Value of the header: `access-control-allow-headers` + +### `cors_always_send` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to always send the header: `access-control-allow-origin` + +### `cors_automatic_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to automatically generate `OPTIONS` endpoints for routes that do _not_ already have one defined + +### `cors_expose_headers` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-expose-headers` + +### `cors_max_age` + +- **Type**: `int` +- **Default**: `5` +- **Description**: Value of the header: `access-control-max-age` + +### `cors_methods` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-access-control-allow-methods` + +### `cors_origins` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-allow-origin` + +.. warning:: + +``` +Be very careful if you place `*` here. Do not do this unless you know what you are doing as it can be a security issue. +``` + +### `cors_send_wildcard` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Whether to send a wildcard origin instead of the incoming request origin + +### `cors_supports_credentials` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Value of the header: `access-control-allow-credentials` + +### `cors_vary_header` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to add the `vary` header + +### `http_all_methods` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Adds the HTTP `CONNECT` and `TRACE` methods as allowable + +### `http_auto_head` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Automatically adds `HEAD` handlers to any `GET` routes + +### `http_auto_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Automatically adds `OPTIONS` handlers to any routes without + +### `http_auto_trace` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Automatically adds `TRACE` handlers to any routes without + +### `oas` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable OpenAPI specification generation + +### `oas_autodoc` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to automatically extract OpenAPI details from the docstring of a route function + +### `oas_ignore_head` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: WHen `True`, it will not add `HEAD` endpoints into the OpenAPI specification + +### `oas_ignore_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: WHen `True`, it will not add `OPTIONS` endpoints into the OpenAPI specification + +### `oas_path_to_redoc_html` + +- **Type**: `Optional[str]` +- **Default**: `None` +- **Description**: Path to HTML file to override the existing Redoc HTML + +### `oas_path_to_swagger_html` + +- **Type**: `Optional[str]` +- **Default**: `None` +- **Description**: Path to HTML file to override the existing Swagger HTML + +### `oas_ui_default` + +- **Type**: `Optional[str]` +- **Default**: `"redoc"` +- **Description**: Which OAS documentation to serve on the bare `oas_url_prefix` endpoint; when `None` there will be no documentation at that location + +### `oas_ui_redoc` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable the Redoc UI + +### `oas_ui_swagger` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable the Swagger UI + +### `oas_ui_swagger_version` + +- **Type**: `str` +- **Default**: `"4.1.0"` +- **Description**: Which Swagger version to use + +### `oas_uri_to_config` + +- **Type**: `str` +- **Default**: `"/swagger-config"` +- **Description**: Path to serve the Swagger configurtaion + +### `oas_uri_to_json` + +- **Type**: `str` +- **Default**: `"/openapi.json"` +- **Description**: Path to serve the OpenAPI JSON + +### `oas_uri_to_redoc` + +- **Type**: `str` +- **Default**: `"/redoc"` +- **Description**: Path to Redoc + +### `oas_uri_to_swagger` + +- **Type**: `str` +- **Default**: `"/swagger"` +- **Description**: Path to Swagger + +### `oas_url_prefix` + +- **Type**: `str` +- **Default**: `"/docs"` +- **Description**: URL prefix for the Blueprint that all of the OAS documentation witll attach to + +### `swagger_ui_configuration` + +- **Type**: `Dict[str, Any]` +- **Default**: `{"apisSorter": "alpha", "operationsSorter": "alpha", "docExpansion": "full"}` +- **Description**: The Swagger documentation to be served to the frontend + +### `templating_enable_async` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to set `enable_async` on the Jinja `Environment` + +### `templating_path_to_templates` + +- **Type**: `Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]] ` +- **Default**: `templates` +- **Description**: A single path, or multiple paths to where your template files are located + +### `trace_excluded_headers` + +- **Type**: `Sequence[str]` +- **Default**: `("authorization", "cookie")` +- **Description**: Which headers should be suppresed from responses to `TRACE` requests From 83e54645b9a55b975e6c857642ab086bd39c280a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:11 +0200 Subject: [PATCH 177/698] New translations configuration.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/configuration.md | 288 ++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/configuration.md diff --git a/guide/content/zh/plugins/sanic-ext/configuration.md b/guide/content/zh/plugins/sanic-ext/configuration.md new file mode 100644 index 0000000000..1443cfc6e9 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/configuration.md @@ -0,0 +1,288 @@ +--- +title: Sanic Extensions - Configuration +--- + +# Configuration + +Sanic Extensions can be configured in all of the same ways that [you can configure Sanic](../../guide/deployment/configuration.md). That makes configuring Sanic Extensions very easy. + +```python +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` + +However, there are a few more configuration options that should be considered. + +## Manual `extend` + +.. column:: + +``` +Even though Sanic Extensions will automatically attach to your application, you can manually choose `extend`. When you do that, you can pass all of the configuration values as a keyword arguments (lowercase). +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.extend(oas_url_prefix="/apidocs") +``` +```` + +.. column:: + +``` +Or, alternatively they could be passed all at once as a single `dict`. +``` + +.. column:: + +```` +```python +app = Sanic("MyApp") +app.extend(config={"oas_url_prefix": "/apidocs"}) +``` +```` + +.. column:: + +``` +Both of these solutions suffers from the fact that the names of the configuration settings are not discoverable by an IDE. Therefore, there is also a type annotated object that you can use. This should help the development experience. +``` + +.. column:: + +```` +```python +from sanic_ext import Config + +app = Sanic("MyApp") +app.extend(config=Config(oas_url_prefix="/apidocs")) +``` +```` + +## Settings + +.. note:: + +```` +Often, the easiest way to change these for an application (since they likely are not going to change dependent upon an environment), is to set them directly on the `app.config` object. + +Simply use the capitalized version of the configuration key as shown here: + +```python +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` +```` + +### `cors` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable CORS protection + +### `cors_allow_headers` + +- **Type**: `str` +- **Default**: `"*"` +- **Description**: Value of the header: `access-control-allow-headers` + +### `cors_always_send` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to always send the header: `access-control-allow-origin` + +### `cors_automatic_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to automatically generate `OPTIONS` endpoints for routes that do _not_ already have one defined + +### `cors_expose_headers` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-expose-headers` + +### `cors_max_age` + +- **Type**: `int` +- **Default**: `5` +- **Description**: Value of the header: `access-control-max-age` + +### `cors_methods` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-access-control-allow-methods` + +### `cors_origins` + +- **Type**: `str` +- **Default**: `""` +- **Description**: Value of the header: `access-control-allow-origin` + +.. warning:: + +``` +Be very careful if you place `*` here. Do not do this unless you know what you are doing as it can be a security issue. +``` + +### `cors_send_wildcard` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Whether to send a wildcard origin instead of the incoming request origin + +### `cors_supports_credentials` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Value of the header: `access-control-allow-credentials` + +### `cors_vary_header` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to add the `vary` header + +### `http_all_methods` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Adds the HTTP `CONNECT` and `TRACE` methods as allowable + +### `http_auto_head` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Automatically adds `HEAD` handlers to any `GET` routes + +### `http_auto_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Automatically adds `OPTIONS` handlers to any routes without + +### `http_auto_trace` + +- **Type**: `bool` +- **Default**: `False` +- **Description**: Automatically adds `TRACE` handlers to any routes without + +### `oas` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable OpenAPI specification generation + +### `oas_autodoc` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to automatically extract OpenAPI details from the docstring of a route function + +### `oas_ignore_head` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: WHen `True`, it will not add `HEAD` endpoints into the OpenAPI specification + +### `oas_ignore_options` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: WHen `True`, it will not add `OPTIONS` endpoints into the OpenAPI specification + +### `oas_path_to_redoc_html` + +- **Type**: `Optional[str]` +- **Default**: `None` +- **Description**: Path to HTML file to override the existing Redoc HTML + +### `oas_path_to_swagger_html` + +- **Type**: `Optional[str]` +- **Default**: `None` +- **Description**: Path to HTML file to override the existing Swagger HTML + +### `oas_ui_default` + +- **Type**: `Optional[str]` +- **Default**: `"redoc"` +- **Description**: Which OAS documentation to serve on the bare `oas_url_prefix` endpoint; when `None` there will be no documentation at that location + +### `oas_ui_redoc` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable the Redoc UI + +### `oas_ui_swagger` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to enable the Swagger UI + +### `oas_ui_swagger_version` + +- **Type**: `str` +- **Default**: `"4.1.0"` +- **Description**: Which Swagger version to use + +### `oas_uri_to_config` + +- **Type**: `str` +- **Default**: `"/swagger-config"` +- **Description**: Path to serve the Swagger configurtaion + +### `oas_uri_to_json` + +- **Type**: `str` +- **Default**: `"/openapi.json"` +- **Description**: Path to serve the OpenAPI JSON + +### `oas_uri_to_redoc` + +- **Type**: `str` +- **Default**: `"/redoc"` +- **Description**: Path to Redoc + +### `oas_uri_to_swagger` + +- **Type**: `str` +- **Default**: `"/swagger"` +- **Description**: Path to Swagger + +### `oas_url_prefix` + +- **Type**: `str` +- **Default**: `"/docs"` +- **Description**: URL prefix for the Blueprint that all of the OAS documentation witll attach to + +### `swagger_ui_configuration` + +- **Type**: `Dict[str, Any]` +- **Default**: `{"apisSorter": "alpha", "operationsSorter": "alpha", "docExpansion": "full"}` +- **Description**: The Swagger documentation to be served to the frontend + +### `templating_enable_async` + +- **Type**: `bool` +- **Default**: `True` +- **Description**: Whether to set `enable_async` on the Jinja `Environment` + +### `templating_path_to_templates` + +- **Type**: `Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]] ` +- **Default**: `templates` +- **Description**: A single path, or multiple paths to where your template files are located + +### `trace_excluded_headers` + +- **Type**: `Sequence[str]` +- **Default**: `("authorization", "cookie")` +- **Description**: Which headers should be suppresed from responses to `TRACE` requests From 09671eb444a1b4a04e6a5c03c6bbc5cb09594858 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:12 +0200 Subject: [PATCH 178/698] New translations convenience.md (Japanese) --- .../ja/plugins/sanic-ext/convenience.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/convenience.md diff --git a/guide/content/ja/plugins/sanic-ext/convenience.md b/guide/content/ja/plugins/sanic-ext/convenience.md new file mode 100644 index 0000000000..7aaef2aa75 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/convenience.md @@ -0,0 +1,134 @@ +--- +title: Sanic Extensions - Convenience +--- + +# Convenience + +## Fixed serializer + +.. column:: + +``` +Often when developing an application, there will be certain routes that always return the same sort of response. When this is the case, you can predefine the return serializer and on the endpoint, and then all that needs to be returned is the content. +``` + +.. column:: + +```` +```python +from sanic_ext import serializer + +@app.get("/") +@serializer(text) +async def hello_world(request, name: str): + if name.isnumeric(): + return "hello " * int(name) + return f"Hello, {name}" +``` +```` + +.. column:: + +``` +The `serializer` decorator also can add status codes. +``` + +.. column:: + +```` +```python +from sanic_ext import serializer + +@app.post("/") +@serializer(text, status=202) +async def create_something(request): + ... +``` +```` + +## Custom serializer + +.. column:: + +``` +Using the `@serializer` decorator, you can also pass your own custom functions as long as they also return a valid type (`HTTPResonse`). +``` + +.. column:: + +```` +```python +def message(retval, request, action, status): + return json( + { + "request_id": str(request.id), + "action": action, + "message": retval, + }, + status=status, + ) + +@app.post("/") +@serializer(message) +async def do_action(request, action: str): + return "This is a message" +``` +```` + +.. column:: + +``` +Now, returning just a string should return a nice serialized output. +``` + +.. column:: + +```` +```python +$ curl localhost:8000/eat_cookies -X POST +{ + "request_id": "ef81c45b-235c-46dd-9dbd-b550f8fa77f9", + "action": "eat_cookies", + "message": "This is a message" +} + +``` +```` + +## Request counter + +.. column:: + +``` +Sanic Extensions comes with a subclass of `Request` that can be setup to automatically keep track of the number of requests processed per worker process. To enable this, you should pass the `CountedRequest` class to your application contructor. +``` + +.. column:: + +```` +```python +from sanic_ext import CountedRequest + +app = Sanic(..., request_class=CountedRequest) +``` +```` + +.. column:: + +``` +You will now have access to the number of requests served during the lifetime of the worker process. +``` + +.. column:: + +```` +```python +@app.get("/") +async def handler(request: CountedRequest): + return json({"count": request.count}) +``` +```` + +If possible, the request count will also be added to the [worker state](../../guide/deployment/manager.md#worker-state). + +![](https://user-images.githubusercontent.com/166269/190922460-43bd2cfc-f81a-443b-b84f-07b6ce475cbf.png) From 02f62bea3a49c16894ce1bc0a86b9d3cfd1aa958 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:13 +0200 Subject: [PATCH 179/698] New translations convenience.md (Korean) --- .../ko/plugins/sanic-ext/convenience.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/convenience.md diff --git a/guide/content/ko/plugins/sanic-ext/convenience.md b/guide/content/ko/plugins/sanic-ext/convenience.md new file mode 100644 index 0000000000..7aaef2aa75 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/convenience.md @@ -0,0 +1,134 @@ +--- +title: Sanic Extensions - Convenience +--- + +# Convenience + +## Fixed serializer + +.. column:: + +``` +Often when developing an application, there will be certain routes that always return the same sort of response. When this is the case, you can predefine the return serializer and on the endpoint, and then all that needs to be returned is the content. +``` + +.. column:: + +```` +```python +from sanic_ext import serializer + +@app.get("/") +@serializer(text) +async def hello_world(request, name: str): + if name.isnumeric(): + return "hello " * int(name) + return f"Hello, {name}" +``` +```` + +.. column:: + +``` +The `serializer` decorator also can add status codes. +``` + +.. column:: + +```` +```python +from sanic_ext import serializer + +@app.post("/") +@serializer(text, status=202) +async def create_something(request): + ... +``` +```` + +## Custom serializer + +.. column:: + +``` +Using the `@serializer` decorator, you can also pass your own custom functions as long as they also return a valid type (`HTTPResonse`). +``` + +.. column:: + +```` +```python +def message(retval, request, action, status): + return json( + { + "request_id": str(request.id), + "action": action, + "message": retval, + }, + status=status, + ) + +@app.post("/") +@serializer(message) +async def do_action(request, action: str): + return "This is a message" +``` +```` + +.. column:: + +``` +Now, returning just a string should return a nice serialized output. +``` + +.. column:: + +```` +```python +$ curl localhost:8000/eat_cookies -X POST +{ + "request_id": "ef81c45b-235c-46dd-9dbd-b550f8fa77f9", + "action": "eat_cookies", + "message": "This is a message" +} + +``` +```` + +## Request counter + +.. column:: + +``` +Sanic Extensions comes with a subclass of `Request` that can be setup to automatically keep track of the number of requests processed per worker process. To enable this, you should pass the `CountedRequest` class to your application contructor. +``` + +.. column:: + +```` +```python +from sanic_ext import CountedRequest + +app = Sanic(..., request_class=CountedRequest) +``` +```` + +.. column:: + +``` +You will now have access to the number of requests served during the lifetime of the worker process. +``` + +.. column:: + +```` +```python +@app.get("/") +async def handler(request: CountedRequest): + return json({"count": request.count}) +``` +```` + +If possible, the request count will also be added to the [worker state](../../guide/deployment/manager.md#worker-state). + +![](https://user-images.githubusercontent.com/166269/190922460-43bd2cfc-f81a-443b-b84f-07b6ce475cbf.png) From f3160ebf1404818f43445ffde901ce1d480466c1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:14 +0200 Subject: [PATCH 180/698] New translations convenience.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/convenience.md | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/convenience.md diff --git a/guide/content/zh/plugins/sanic-ext/convenience.md b/guide/content/zh/plugins/sanic-ext/convenience.md new file mode 100644 index 0000000000..7aaef2aa75 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/convenience.md @@ -0,0 +1,134 @@ +--- +title: Sanic Extensions - Convenience +--- + +# Convenience + +## Fixed serializer + +.. column:: + +``` +Often when developing an application, there will be certain routes that always return the same sort of response. When this is the case, you can predefine the return serializer and on the endpoint, and then all that needs to be returned is the content. +``` + +.. column:: + +```` +```python +from sanic_ext import serializer + +@app.get("/") +@serializer(text) +async def hello_world(request, name: str): + if name.isnumeric(): + return "hello " * int(name) + return f"Hello, {name}" +``` +```` + +.. column:: + +``` +The `serializer` decorator also can add status codes. +``` + +.. column:: + +```` +```python +from sanic_ext import serializer + +@app.post("/") +@serializer(text, status=202) +async def create_something(request): + ... +``` +```` + +## Custom serializer + +.. column:: + +``` +Using the `@serializer` decorator, you can also pass your own custom functions as long as they also return a valid type (`HTTPResonse`). +``` + +.. column:: + +```` +```python +def message(retval, request, action, status): + return json( + { + "request_id": str(request.id), + "action": action, + "message": retval, + }, + status=status, + ) + +@app.post("/") +@serializer(message) +async def do_action(request, action: str): + return "This is a message" +``` +```` + +.. column:: + +``` +Now, returning just a string should return a nice serialized output. +``` + +.. column:: + +```` +```python +$ curl localhost:8000/eat_cookies -X POST +{ + "request_id": "ef81c45b-235c-46dd-9dbd-b550f8fa77f9", + "action": "eat_cookies", + "message": "This is a message" +} + +``` +```` + +## Request counter + +.. column:: + +``` +Sanic Extensions comes with a subclass of `Request` that can be setup to automatically keep track of the number of requests processed per worker process. To enable this, you should pass the `CountedRequest` class to your application contructor. +``` + +.. column:: + +```` +```python +from sanic_ext import CountedRequest + +app = Sanic(..., request_class=CountedRequest) +``` +```` + +.. column:: + +``` +You will now have access to the number of requests served during the lifetime of the worker process. +``` + +.. column:: + +```` +```python +@app.get("/") +async def handler(request: CountedRequest): + return json({"count": request.count}) +``` +```` + +If possible, the request count will also be added to the [worker state](../../guide/deployment/manager.md#worker-state). + +![](https://user-images.githubusercontent.com/166269/190922460-43bd2cfc-f81a-443b-b84f-07b6ce475cbf.png) From a2d34803e5b0ad662ec044c1d91bec7dd1fa2eef Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:15 +0200 Subject: [PATCH 181/698] New translations custom.md (Japanese) --- guide/content/ja/plugins/sanic-ext/custom.md | 92 ++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/custom.md diff --git a/guide/content/ja/plugins/sanic-ext/custom.md b/guide/content/ja/plugins/sanic-ext/custom.md new file mode 100644 index 0000000000..6facab3f66 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/custom.md @@ -0,0 +1,92 @@ +--- +title: Sanic Extensions - Custom +--- + +# Custom extensions + +It is possible to create your own custom extensions. + +Version 22.9 added the `Extend.register` [method](#extension-preregistration). This makes it extremely easy to add custom expensions to an application. + +## Anatomy of an extension + +All extensions must subclass `Extension`. + +### Required + +- `name`: By convention, the name is an all-lowercase string +- `startup`: A method that runs when the extension is added + +### Optional + +- `label`: A method that returns additional information about the extension in the MOTD +- `included`: A method that returns a boolean whether the extension should be enabled or not (could be used for example to check config state) + +### Example + +```python +from sanic import Request, Sanic, json +from sanic_ext import Extend, Extension + +app = Sanic(__name__) +app.config.MONITOR = True + +class AutoMonitor(Extension): + name = "automonitor" + + def startup(self, bootstrap) -> None: + if self.included(): + self.app.before_server_start(self.ensure_monitor_set) + self.app.on_request(self.monitor) + + @staticmethod + async def monitor(request: Request): + if request.route and request.route.ctx.monitor: + print("....") + + @staticmethod + async def ensure_monitor_set(app: Sanic): + for route in app.router.routes: + if not hasattr(route.ctx, "monitor"): + route.ctx.monitor = False + + def label(self): + has_monitor = [ + route + for route in self.app.router.routes + if getattr(route.ctx, "monitor", None) + ] + return f"{len(has_monitor)} endpoint(s)" + + def included(self): + return self.app.config.MONITOR + +Extend.register(AutoMonitor) + +@app.get("/", ctx_monitor=True) +async def handler(request: Request): + return json({"foo": "bar"}) +``` + +## Extension preregistration + +.. column:: + +``` +`Extend.register` simplifies the addition of custom extensions. +``` + +.. column:: + +```` +```python +from sanic_ext import Extend, Extension + +class MyCustomExtension(Extension): + ... + +Extend.register(MyCustomExtension()) +``` +```` + +_Added in v22.9_ From f61a2c2e7b554aaa4b75fe94756658004f51a016 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:16 +0200 Subject: [PATCH 182/698] New translations custom.md (Korean) --- guide/content/ko/plugins/sanic-ext/custom.md | 92 ++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/custom.md diff --git a/guide/content/ko/plugins/sanic-ext/custom.md b/guide/content/ko/plugins/sanic-ext/custom.md new file mode 100644 index 0000000000..6facab3f66 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/custom.md @@ -0,0 +1,92 @@ +--- +title: Sanic Extensions - Custom +--- + +# Custom extensions + +It is possible to create your own custom extensions. + +Version 22.9 added the `Extend.register` [method](#extension-preregistration). This makes it extremely easy to add custom expensions to an application. + +## Anatomy of an extension + +All extensions must subclass `Extension`. + +### Required + +- `name`: By convention, the name is an all-lowercase string +- `startup`: A method that runs when the extension is added + +### Optional + +- `label`: A method that returns additional information about the extension in the MOTD +- `included`: A method that returns a boolean whether the extension should be enabled or not (could be used for example to check config state) + +### Example + +```python +from sanic import Request, Sanic, json +from sanic_ext import Extend, Extension + +app = Sanic(__name__) +app.config.MONITOR = True + +class AutoMonitor(Extension): + name = "automonitor" + + def startup(self, bootstrap) -> None: + if self.included(): + self.app.before_server_start(self.ensure_monitor_set) + self.app.on_request(self.monitor) + + @staticmethod + async def monitor(request: Request): + if request.route and request.route.ctx.monitor: + print("....") + + @staticmethod + async def ensure_monitor_set(app: Sanic): + for route in app.router.routes: + if not hasattr(route.ctx, "monitor"): + route.ctx.monitor = False + + def label(self): + has_monitor = [ + route + for route in self.app.router.routes + if getattr(route.ctx, "monitor", None) + ] + return f"{len(has_monitor)} endpoint(s)" + + def included(self): + return self.app.config.MONITOR + +Extend.register(AutoMonitor) + +@app.get("/", ctx_monitor=True) +async def handler(request: Request): + return json({"foo": "bar"}) +``` + +## Extension preregistration + +.. column:: + +``` +`Extend.register` simplifies the addition of custom extensions. +``` + +.. column:: + +```` +```python +from sanic_ext import Extend, Extension + +class MyCustomExtension(Extension): + ... + +Extend.register(MyCustomExtension()) +``` +```` + +_Added in v22.9_ From d5bc9506d3155864f3b8fd17e55a1315a3bc12ff Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:17 +0200 Subject: [PATCH 183/698] New translations custom.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/custom.md | 92 ++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/custom.md diff --git a/guide/content/zh/plugins/sanic-ext/custom.md b/guide/content/zh/plugins/sanic-ext/custom.md new file mode 100644 index 0000000000..6facab3f66 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/custom.md @@ -0,0 +1,92 @@ +--- +title: Sanic Extensions - Custom +--- + +# Custom extensions + +It is possible to create your own custom extensions. + +Version 22.9 added the `Extend.register` [method](#extension-preregistration). This makes it extremely easy to add custom expensions to an application. + +## Anatomy of an extension + +All extensions must subclass `Extension`. + +### Required + +- `name`: By convention, the name is an all-lowercase string +- `startup`: A method that runs when the extension is added + +### Optional + +- `label`: A method that returns additional information about the extension in the MOTD +- `included`: A method that returns a boolean whether the extension should be enabled or not (could be used for example to check config state) + +### Example + +```python +from sanic import Request, Sanic, json +from sanic_ext import Extend, Extension + +app = Sanic(__name__) +app.config.MONITOR = True + +class AutoMonitor(Extension): + name = "automonitor" + + def startup(self, bootstrap) -> None: + if self.included(): + self.app.before_server_start(self.ensure_monitor_set) + self.app.on_request(self.monitor) + + @staticmethod + async def monitor(request: Request): + if request.route and request.route.ctx.monitor: + print("....") + + @staticmethod + async def ensure_monitor_set(app: Sanic): + for route in app.router.routes: + if not hasattr(route.ctx, "monitor"): + route.ctx.monitor = False + + def label(self): + has_monitor = [ + route + for route in self.app.router.routes + if getattr(route.ctx, "monitor", None) + ] + return f"{len(has_monitor)} endpoint(s)" + + def included(self): + return self.app.config.MONITOR + +Extend.register(AutoMonitor) + +@app.get("/", ctx_monitor=True) +async def handler(request: Request): + return json({"foo": "bar"}) +``` + +## Extension preregistration + +.. column:: + +``` +`Extend.register` simplifies the addition of custom extensions. +``` + +.. column:: + +```` +```python +from sanic_ext import Extend, Extension + +class MyCustomExtension(Extension): + ... + +Extend.register(MyCustomExtension()) +``` +```` + +_Added in v22.9_ From 405b12b1d66c67af8806f7b15a9f21378e9e3c03 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:17 +0200 Subject: [PATCH 184/698] New translations getting-started.md (Japanese) --- .../ja/plugins/sanic-ext/getting-started.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/getting-started.md diff --git a/guide/content/ja/plugins/sanic-ext/getting-started.md b/guide/content/ja/plugins/sanic-ext/getting-started.md new file mode 100644 index 0000000000..bf49796ec7 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/getting-started.md @@ -0,0 +1,92 @@ +--- +title: Sanic Extensions - Getting Started +--- + +# Getting Started + +Sanic Extensions is an _officially supported_ plugin developed, and maintained by the SCO. The primary goal of this project is to add additional features to help Web API and Web application development easier. + +## Features + +- CORS protection +- Template rendering with Jinja +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Predefined, endpoint-specific response serializers +- Request query arguments and body input validation +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints + +## Minimum requirements + +- **Python**: 3.8+ +- **Sanic**: 21.9+ + +## Install + +The best method is to just install Sanic Extensions along with Sanic itself: + +```bash +pip install sanic[ext] +``` + +You can of course also just install it by itself. + +```bash +pip install sanic-ext +``` + +## Extend your application + +Out of the box, Sanic Extensions will enable a bunch of features for you. + +.. column:: + +``` +To setup Sanic Extensions (v21.12+), you need to do: **nothing**. If it is installed in the environment, it is setup and ready to go. + +This code is the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md) _without any changes_, but using Sanic Extensions with `sanic-ext` installed in the background. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +.. column:: + +``` +**_OLD DEPRECATED SETUP_** + +In v21.9, the easiest way to get started is to instantiate it with `Extend`. + +If you look back at the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md), you will see the only additions here are the two highlighted lines. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text +from sanic_ext import Extend + +app = Sanic("MyHelloWorldApp") +Extend(app) + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +Regardless of how it is setup, you should now be able to view the OpenAPI documentation and see some of the functionality in action: [http://localhost:8000/docs](http://localhost:8000/docs). From 8b366c13b44401f17532c57b7b45aea9934009ae Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:18 +0200 Subject: [PATCH 185/698] New translations getting-started.md (Korean) --- .../ko/plugins/sanic-ext/getting-started.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/getting-started.md diff --git a/guide/content/ko/plugins/sanic-ext/getting-started.md b/guide/content/ko/plugins/sanic-ext/getting-started.md new file mode 100644 index 0000000000..bf49796ec7 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/getting-started.md @@ -0,0 +1,92 @@ +--- +title: Sanic Extensions - Getting Started +--- + +# Getting Started + +Sanic Extensions is an _officially supported_ plugin developed, and maintained by the SCO. The primary goal of this project is to add additional features to help Web API and Web application development easier. + +## Features + +- CORS protection +- Template rendering with Jinja +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Predefined, endpoint-specific response serializers +- Request query arguments and body input validation +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints + +## Minimum requirements + +- **Python**: 3.8+ +- **Sanic**: 21.9+ + +## Install + +The best method is to just install Sanic Extensions along with Sanic itself: + +```bash +pip install sanic[ext] +``` + +You can of course also just install it by itself. + +```bash +pip install sanic-ext +``` + +## Extend your application + +Out of the box, Sanic Extensions will enable a bunch of features for you. + +.. column:: + +``` +To setup Sanic Extensions (v21.12+), you need to do: **nothing**. If it is installed in the environment, it is setup and ready to go. + +This code is the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md) _without any changes_, but using Sanic Extensions with `sanic-ext` installed in the background. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +.. column:: + +``` +**_OLD DEPRECATED SETUP_** + +In v21.9, the easiest way to get started is to instantiate it with `Extend`. + +If you look back at the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md), you will see the only additions here are the two highlighted lines. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text +from sanic_ext import Extend + +app = Sanic("MyHelloWorldApp") +Extend(app) + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +Regardless of how it is setup, you should now be able to view the OpenAPI documentation and see some of the functionality in action: [http://localhost:8000/docs](http://localhost:8000/docs). From a3e7dafedfb0cdfaeccfa85653a884b78d49adae Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:20 +0200 Subject: [PATCH 186/698] New translations getting-started.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/getting-started.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/getting-started.md diff --git a/guide/content/zh/plugins/sanic-ext/getting-started.md b/guide/content/zh/plugins/sanic-ext/getting-started.md new file mode 100644 index 0000000000..bf49796ec7 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/getting-started.md @@ -0,0 +1,92 @@ +--- +title: Sanic Extensions - Getting Started +--- + +# Getting Started + +Sanic Extensions is an _officially supported_ plugin developed, and maintained by the SCO. The primary goal of this project is to add additional features to help Web API and Web application development easier. + +## Features + +- CORS protection +- Template rendering with Jinja +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Predefined, endpoint-specific response serializers +- Request query arguments and body input validation +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints + +## Minimum requirements + +- **Python**: 3.8+ +- **Sanic**: 21.9+ + +## Install + +The best method is to just install Sanic Extensions along with Sanic itself: + +```bash +pip install sanic[ext] +``` + +You can of course also just install it by itself. + +```bash +pip install sanic-ext +``` + +## Extend your application + +Out of the box, Sanic Extensions will enable a bunch of features for you. + +.. column:: + +``` +To setup Sanic Extensions (v21.12+), you need to do: **nothing**. If it is installed in the environment, it is setup and ready to go. + +This code is the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md) _without any changes_, but using Sanic Extensions with `sanic-ext` installed in the background. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text + +app = Sanic("MyHelloWorldApp") + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +.. column:: + +``` +**_OLD DEPRECATED SETUP_** + +In v21.9, the easiest way to get started is to instantiate it with `Extend`. + +If you look back at the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md), you will see the only additions here are the two highlighted lines. +``` + +.. column:: + +```` +```python +from sanic import Sanic +from sanic.response import text +from sanic_ext import Extend + +app = Sanic("MyHelloWorldApp") +Extend(app) + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` +```` + +Regardless of how it is setup, you should now be able to view the OpenAPI documentation and see some of the functionality in action: [http://localhost:8000/docs](http://localhost:8000/docs). From af19e9d35f631791859a5a4741c6395e808e411c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:21 +0200 Subject: [PATCH 187/698] New translations health-monitor.md (Japanese) --- .../ja/plugins/sanic-ext/health-monitor.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/health-monitor.md diff --git a/guide/content/ja/plugins/sanic-ext/health-monitor.md b/guide/content/ja/plugins/sanic-ext/health-monitor.md new file mode 100644 index 0000000000..82b8271f95 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/health-monitor.md @@ -0,0 +1,80 @@ +--- +title: Sanic Extensions - Health Monitor +--- + +# Health monitor + +The health monitor requires both `sanic>=22.9` and `sanic-ext>=22.9`. + +You can setup Sanic Extensions to monitor the health of your worker processes. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). + +## Setup + +.. column:: + +``` +Out of the box, the health monitor is disabled. You will need to opt-in if you would like to use it. +``` + +.. column:: + +```` +```python +app.config.HEALTH = True +``` +```` + +## How does it work + +The monitor sets up a new background process that will periodically receive acknowledgements of liveliness from each worker process. If a worker process misses a report too many times, then the monitor will restart that one worker. + +## Diagnostics endpoint + +.. column:: + +``` +The health monitor will also enable a diagnostics endpoint that outputs the [worker state](../../guide/deployment/manager.md#worker-state). By default is id disabled. + +.. danger:: + + The diagnostics endpoint is not secured. If you are deploying it in a production environment, you should take steps to protect it with a proxy server if you are using one. If not, you may want to consider disabling this feature in production since it will leak details about your server state. +``` + +.. column:: + +```` +``` +$ curl http://localhost:8000/__health__ +{ + 'Sanic-Main': {'pid': 99997}, + 'Sanic-Server-0-0': { + 'server': True, + 'state': 'ACKED', + 'pid': 9999, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 2, + 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc) + }, + 'Sanic-Reloader-0': { + 'server': False, + 'state': 'STARTED', + 'pid': 99998, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 1 + } +} +``` +```` + +## Configuration + +| Key | Type | Default | Description | +| --------------------------------------------------------------------------------- | ------ | --------------- | --------------------------------------------------------------------------- | +| HEALTH | `bool` | `False` | Whether to enable this extension. | +| HEALTH_ENDPOINT | `bool` | `False` | Whether to enable the diagnostics endpoint. | +| HEALTH_MAX_MISSES | `int` | `3` | The number of consecutive misses before a worker process is restarted. | +| HEALTH_MISSED_THRESHHOLD | `int` | `10` | The number of seconds the monitor checks for worker process health. | +| HEALTH_MONITOR | `bool` | `True` | Whether to enable the health monitor. | +| HEALTH_REPORT_INTERVAL | `int` | `5` | The number of seconds between reporting each acknowledgement of liveliness. | +| HEALTH_URI_TO_INFO | `str` | `""` | The URI path of the diagnostics endpoint. | +| HEALTH_URL_PREFIX | `str` | `"/__health__"` | The URI prefix of the diagnostics blueprint. | From 47b0ff2f6ad36dedd65615ba37268429e2ed7f35 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:21 +0200 Subject: [PATCH 188/698] New translations health-monitor.md (Korean) --- .../ko/plugins/sanic-ext/health-monitor.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/health-monitor.md diff --git a/guide/content/ko/plugins/sanic-ext/health-monitor.md b/guide/content/ko/plugins/sanic-ext/health-monitor.md new file mode 100644 index 0000000000..82b8271f95 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/health-monitor.md @@ -0,0 +1,80 @@ +--- +title: Sanic Extensions - Health Monitor +--- + +# Health monitor + +The health monitor requires both `sanic>=22.9` and `sanic-ext>=22.9`. + +You can setup Sanic Extensions to monitor the health of your worker processes. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). + +## Setup + +.. column:: + +``` +Out of the box, the health monitor is disabled. You will need to opt-in if you would like to use it. +``` + +.. column:: + +```` +```python +app.config.HEALTH = True +``` +```` + +## How does it work + +The monitor sets up a new background process that will periodically receive acknowledgements of liveliness from each worker process. If a worker process misses a report too many times, then the monitor will restart that one worker. + +## Diagnostics endpoint + +.. column:: + +``` +The health monitor will also enable a diagnostics endpoint that outputs the [worker state](../../guide/deployment/manager.md#worker-state). By default is id disabled. + +.. danger:: + + The diagnostics endpoint is not secured. If you are deploying it in a production environment, you should take steps to protect it with a proxy server if you are using one. If not, you may want to consider disabling this feature in production since it will leak details about your server state. +``` + +.. column:: + +```` +``` +$ curl http://localhost:8000/__health__ +{ + 'Sanic-Main': {'pid': 99997}, + 'Sanic-Server-0-0': { + 'server': True, + 'state': 'ACKED', + 'pid': 9999, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 2, + 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc) + }, + 'Sanic-Reloader-0': { + 'server': False, + 'state': 'STARTED', + 'pid': 99998, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 1 + } +} +``` +```` + +## Configuration + +| Key | Type | Default | Description | +| --------------------------------------------------------------------------------- | ------ | --------------- | --------------------------------------------------------------------------- | +| HEALTH | `bool` | `False` | Whether to enable this extension. | +| HEALTH_ENDPOINT | `bool` | `False` | Whether to enable the diagnostics endpoint. | +| HEALTH_MAX_MISSES | `int` | `3` | The number of consecutive misses before a worker process is restarted. | +| HEALTH_MISSED_THRESHHOLD | `int` | `10` | The number of seconds the monitor checks for worker process health. | +| HEALTH_MONITOR | `bool` | `True` | Whether to enable the health monitor. | +| HEALTH_REPORT_INTERVAL | `int` | `5` | The number of seconds between reporting each acknowledgement of liveliness. | +| HEALTH_URI_TO_INFO | `str` | `""` | The URI path of the diagnostics endpoint. | +| HEALTH_URL_PREFIX | `str` | `"/__health__"` | The URI prefix of the diagnostics blueprint. | From de8267e9362ef05d13e80859ccd321f322b0ce7f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:23 +0200 Subject: [PATCH 189/698] New translations health-monitor.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/health-monitor.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/health-monitor.md diff --git a/guide/content/zh/plugins/sanic-ext/health-monitor.md b/guide/content/zh/plugins/sanic-ext/health-monitor.md new file mode 100644 index 0000000000..82b8271f95 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/health-monitor.md @@ -0,0 +1,80 @@ +--- +title: Sanic Extensions - Health Monitor +--- + +# Health monitor + +The health monitor requires both `sanic>=22.9` and `sanic-ext>=22.9`. + +You can setup Sanic Extensions to monitor the health of your worker processes. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). + +## Setup + +.. column:: + +``` +Out of the box, the health monitor is disabled. You will need to opt-in if you would like to use it. +``` + +.. column:: + +```` +```python +app.config.HEALTH = True +``` +```` + +## How does it work + +The monitor sets up a new background process that will periodically receive acknowledgements of liveliness from each worker process. If a worker process misses a report too many times, then the monitor will restart that one worker. + +## Diagnostics endpoint + +.. column:: + +``` +The health monitor will also enable a diagnostics endpoint that outputs the [worker state](../../guide/deployment/manager.md#worker-state). By default is id disabled. + +.. danger:: + + The diagnostics endpoint is not secured. If you are deploying it in a production environment, you should take steps to protect it with a proxy server if you are using one. If not, you may want to consider disabling this feature in production since it will leak details about your server state. +``` + +.. column:: + +```` +``` +$ curl http://localhost:8000/__health__ +{ + 'Sanic-Main': {'pid': 99997}, + 'Sanic-Server-0-0': { + 'server': True, + 'state': 'ACKED', + 'pid': 9999, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 2, + 'restart_at': datetime.datetime(2022, 10, 1, 0, 0, 12, 861332, tzinfo=datetime.timezone.utc) + }, + 'Sanic-Reloader-0': { + 'server': False, + 'state': 'STARTED', + 'pid': 99998, + 'start_at': datetime.datetime(2022, 10, 1, 0, 0, 0, 0, tzinfo=datetime.timezone.utc), + 'starts': 1 + } +} +``` +```` + +## Configuration + +| Key | Type | Default | Description | +| --------------------------------------------------------------------------------- | ------ | --------------- | --------------------------------------------------------------------------- | +| HEALTH | `bool` | `False` | Whether to enable this extension. | +| HEALTH_ENDPOINT | `bool` | `False` | Whether to enable the diagnostics endpoint. | +| HEALTH_MAX_MISSES | `int` | `3` | The number of consecutive misses before a worker process is restarted. | +| HEALTH_MISSED_THRESHHOLD | `int` | `10` | The number of seconds the monitor checks for worker process health. | +| HEALTH_MONITOR | `bool` | `True` | Whether to enable the health monitor. | +| HEALTH_REPORT_INTERVAL | `int` | `5` | The number of seconds between reporting each acknowledgement of liveliness. | +| HEALTH_URI_TO_INFO | `str` | `""` | The URI path of the diagnostics endpoint. | +| HEALTH_URL_PREFIX | `str` | `"/__health__"` | The URI prefix of the diagnostics blueprint. | From 2c50ebd867007d062edeefd0e6d96730a2edc0e7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:24 +0200 Subject: [PATCH 190/698] New translations cors.md (Japanese) --- .../content/ja/plugins/sanic-ext/http/cors.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/http/cors.md diff --git a/guide/content/ja/plugins/sanic-ext/http/cors.md b/guide/content/ja/plugins/sanic-ext/http/cors.md new file mode 100644 index 0000000000..d5e4f2ba4e --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/http/cors.md @@ -0,0 +1,97 @@ +--- +title: Sanic Extensions - CORS protection +--- + +# CORS protection + +Cross-Origin Resource Sharing (aka CORS) is a _huge_ topic by itself. The documentation here cannot go into enough detail about _what_ it is. You are highly encouraged to do some research on your own to understand the security problem presented by it, and the theory behind the solutions. [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are a great first step. + +In super brief terms, CORS protection is a framework that browsers use to facilitate how and when a web page can access information from another domain. It is extremely relevant to anyone building a single-page application. Often times your frontend might be on a domain like `https://portal.myapp.com`, but it needs to access the backend from `https://api.myapp.com`. + +The implementation here is heavily inspired by [`sanic-cors`](https://github.com/ashleysommer/sanic-cors), which is in turn based upon [`flask-cors`](https://github.com/corydolphin/flask-cors). It is therefore very likely that you can achieve a near drop-in replacement of `sanic-cors` with `sanic-ext`. + +## Basic implementation + +.. column:: + +``` +As shown in the example in the [auto-endpoints example](methods.md#options), Sanic Extensions will automatically enable CORS protection without further action. But, it does not offer too much out of the box. + +At a *bare minimum*, it is **highly** recommended that you set `config.CORS_ORIGINS` to the intended origin(s) that will be accessing the application. +``` + +.. column:: + +```` +```python +from sanic import Sanic, text +from sanic_ext import Extend + +app = Sanic(__name__) +app.config.CORS_ORIGINS = "http://foobar.com,http://bar.com" +Extend(app) + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +``` +$ curl localhost:8000 -X OPTIONS -i +HTTP/1.1 204 No Content +allow: GET,HEAD,OPTIONS +access-control-allow-origin: http://foobar.com +connection: keep-alive +``` +```` + +## Configuration + +The true power of CORS protection, however, comes into play once you start configuring it. Here is a table of all of the options. + +| Key | Type | Default | Description | +| --------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `CORS_ALLOW_HEADERS` | `str` or `List[str]` | `"*"` | The list of headers that will appear in `access-control-allow-headers`. | +| `CORS_ALWAYS_SEND` | `bool` | `True` | When `True`, will always set a value for `access-control-allow-origin`. When `False`, will only set it if there is an `Origin` header. | +| `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | When the incoming preflight request is received, whether to automatically set values for `access-control-allow-headers`, `access-control-max-age`, and `access-control-allow-methods` headers. If `False` these values will only be set on routes that are decorated with the `@cors` decorator. | +| `CORS_EXPOSE_HEADERS` | `str` or `List[str]` | `""` | Specific list of headers to be set in `access-control-expose-headers` header. | +| `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | The maximum number of seconds the preflight response may be cached using the `access-control-max-age` header. A falsey value will cause the header to not be set. | +| `CORS_METHODS` | `str` or `List[str]` | `""` | The HTTP methods that the allowed origins can access, as set on the `access-control-allow-methods` header. | +| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | The origins that are allowed to access the resource, as set on the `access-control-allow-origin` header. | +| `CORS_SEND_WILDCARD` | `bool` | `False` | If `True`, will send the wildcard `*` origin instead of the `origin` request header. | +| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | Whether to set the `access-control-allow-credentials` header. | +| `CORS_VARY_HEADER` | `bool` | `True` | Whether to add `vary` header, when appropriate. | + +_For the sake of brevity, where the above says `List[str]` any instance of a `list`, `set`, `frozenset`, or `tuple` will be acceptable. Alternatively, if the value is a `str`, it can be a comma delimited list._ + +## Route level overrides + +.. column:: + +``` +It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. + +The values that can be overridden with this decorator are: + +- `origins` +- `expose_headers` +- `allow_headers` +- `allow_methods` +- `supports_credentials` +- `max_age` +``` + +.. column:: + +```` +```python +from sanic_ext import cors + +app.config.CORS_ORIGINS = "https://foo.com" + +@app.get("/", host="bar.com") +@cors(origins="https://bar.com") +async def hello_world(request): + return text("Hello, world.") +``` +```` From 0f1e88ed7ad766071874876703813675a1f281f0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:25 +0200 Subject: [PATCH 191/698] New translations cors.md (Korean) --- .../content/ko/plugins/sanic-ext/http/cors.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/http/cors.md diff --git a/guide/content/ko/plugins/sanic-ext/http/cors.md b/guide/content/ko/plugins/sanic-ext/http/cors.md new file mode 100644 index 0000000000..d5e4f2ba4e --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/http/cors.md @@ -0,0 +1,97 @@ +--- +title: Sanic Extensions - CORS protection +--- + +# CORS protection + +Cross-Origin Resource Sharing (aka CORS) is a _huge_ topic by itself. The documentation here cannot go into enough detail about _what_ it is. You are highly encouraged to do some research on your own to understand the security problem presented by it, and the theory behind the solutions. [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are a great first step. + +In super brief terms, CORS protection is a framework that browsers use to facilitate how and when a web page can access information from another domain. It is extremely relevant to anyone building a single-page application. Often times your frontend might be on a domain like `https://portal.myapp.com`, but it needs to access the backend from `https://api.myapp.com`. + +The implementation here is heavily inspired by [`sanic-cors`](https://github.com/ashleysommer/sanic-cors), which is in turn based upon [`flask-cors`](https://github.com/corydolphin/flask-cors). It is therefore very likely that you can achieve a near drop-in replacement of `sanic-cors` with `sanic-ext`. + +## Basic implementation + +.. column:: + +``` +As shown in the example in the [auto-endpoints example](methods.md#options), Sanic Extensions will automatically enable CORS protection without further action. But, it does not offer too much out of the box. + +At a *bare minimum*, it is **highly** recommended that you set `config.CORS_ORIGINS` to the intended origin(s) that will be accessing the application. +``` + +.. column:: + +```` +```python +from sanic import Sanic, text +from sanic_ext import Extend + +app = Sanic(__name__) +app.config.CORS_ORIGINS = "http://foobar.com,http://bar.com" +Extend(app) + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +``` +$ curl localhost:8000 -X OPTIONS -i +HTTP/1.1 204 No Content +allow: GET,HEAD,OPTIONS +access-control-allow-origin: http://foobar.com +connection: keep-alive +``` +```` + +## Configuration + +The true power of CORS protection, however, comes into play once you start configuring it. Here is a table of all of the options. + +| Key | Type | Default | Description | +| --------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `CORS_ALLOW_HEADERS` | `str` or `List[str]` | `"*"` | The list of headers that will appear in `access-control-allow-headers`. | +| `CORS_ALWAYS_SEND` | `bool` | `True` | When `True`, will always set a value for `access-control-allow-origin`. When `False`, will only set it if there is an `Origin` header. | +| `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | When the incoming preflight request is received, whether to automatically set values for `access-control-allow-headers`, `access-control-max-age`, and `access-control-allow-methods` headers. If `False` these values will only be set on routes that are decorated with the `@cors` decorator. | +| `CORS_EXPOSE_HEADERS` | `str` or `List[str]` | `""` | Specific list of headers to be set in `access-control-expose-headers` header. | +| `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | The maximum number of seconds the preflight response may be cached using the `access-control-max-age` header. A falsey value will cause the header to not be set. | +| `CORS_METHODS` | `str` or `List[str]` | `""` | The HTTP methods that the allowed origins can access, as set on the `access-control-allow-methods` header. | +| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | The origins that are allowed to access the resource, as set on the `access-control-allow-origin` header. | +| `CORS_SEND_WILDCARD` | `bool` | `False` | If `True`, will send the wildcard `*` origin instead of the `origin` request header. | +| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | Whether to set the `access-control-allow-credentials` header. | +| `CORS_VARY_HEADER` | `bool` | `True` | Whether to add `vary` header, when appropriate. | + +_For the sake of brevity, where the above says `List[str]` any instance of a `list`, `set`, `frozenset`, or `tuple` will be acceptable. Alternatively, if the value is a `str`, it can be a comma delimited list._ + +## Route level overrides + +.. column:: + +``` +It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. + +The values that can be overridden with this decorator are: + +- `origins` +- `expose_headers` +- `allow_headers` +- `allow_methods` +- `supports_credentials` +- `max_age` +``` + +.. column:: + +```` +```python +from sanic_ext import cors + +app.config.CORS_ORIGINS = "https://foo.com" + +@app.get("/", host="bar.com") +@cors(origins="https://bar.com") +async def hello_world(request): + return text("Hello, world.") +``` +```` From 83cfe89b3622f0632da11cae43a755d95fcc21f4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:26 +0200 Subject: [PATCH 192/698] New translations cors.md (Chinese Simplified) --- .../content/zh/plugins/sanic-ext/http/cors.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/http/cors.md diff --git a/guide/content/zh/plugins/sanic-ext/http/cors.md b/guide/content/zh/plugins/sanic-ext/http/cors.md new file mode 100644 index 0000000000..d5e4f2ba4e --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/http/cors.md @@ -0,0 +1,97 @@ +--- +title: Sanic Extensions - CORS protection +--- + +# CORS protection + +Cross-Origin Resource Sharing (aka CORS) is a _huge_ topic by itself. The documentation here cannot go into enough detail about _what_ it is. You are highly encouraged to do some research on your own to understand the security problem presented by it, and the theory behind the solutions. [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are a great first step. + +In super brief terms, CORS protection is a framework that browsers use to facilitate how and when a web page can access information from another domain. It is extremely relevant to anyone building a single-page application. Often times your frontend might be on a domain like `https://portal.myapp.com`, but it needs to access the backend from `https://api.myapp.com`. + +The implementation here is heavily inspired by [`sanic-cors`](https://github.com/ashleysommer/sanic-cors), which is in turn based upon [`flask-cors`](https://github.com/corydolphin/flask-cors). It is therefore very likely that you can achieve a near drop-in replacement of `sanic-cors` with `sanic-ext`. + +## Basic implementation + +.. column:: + +``` +As shown in the example in the [auto-endpoints example](methods.md#options), Sanic Extensions will automatically enable CORS protection without further action. But, it does not offer too much out of the box. + +At a *bare minimum*, it is **highly** recommended that you set `config.CORS_ORIGINS` to the intended origin(s) that will be accessing the application. +``` + +.. column:: + +```` +```python +from sanic import Sanic, text +from sanic_ext import Extend + +app = Sanic(__name__) +app.config.CORS_ORIGINS = "http://foobar.com,http://bar.com" +Extend(app) + +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +``` +$ curl localhost:8000 -X OPTIONS -i +HTTP/1.1 204 No Content +allow: GET,HEAD,OPTIONS +access-control-allow-origin: http://foobar.com +connection: keep-alive +``` +```` + +## Configuration + +The true power of CORS protection, however, comes into play once you start configuring it. Here is a table of all of the options. + +| Key | Type | Default | Description | +| --------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `CORS_ALLOW_HEADERS` | `str` or `List[str]` | `"*"` | The list of headers that will appear in `access-control-allow-headers`. | +| `CORS_ALWAYS_SEND` | `bool` | `True` | When `True`, will always set a value for `access-control-allow-origin`. When `False`, will only set it if there is an `Origin` header. | +| `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | When the incoming preflight request is received, whether to automatically set values for `access-control-allow-headers`, `access-control-max-age`, and `access-control-allow-methods` headers. If `False` these values will only be set on routes that are decorated with the `@cors` decorator. | +| `CORS_EXPOSE_HEADERS` | `str` or `List[str]` | `""` | Specific list of headers to be set in `access-control-expose-headers` header. | +| `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | The maximum number of seconds the preflight response may be cached using the `access-control-max-age` header. A falsey value will cause the header to not be set. | +| `CORS_METHODS` | `str` or `List[str]` | `""` | The HTTP methods that the allowed origins can access, as set on the `access-control-allow-methods` header. | +| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | The origins that are allowed to access the resource, as set on the `access-control-allow-origin` header. | +| `CORS_SEND_WILDCARD` | `bool` | `False` | If `True`, will send the wildcard `*` origin instead of the `origin` request header. | +| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | Whether to set the `access-control-allow-credentials` header. | +| `CORS_VARY_HEADER` | `bool` | `True` | Whether to add `vary` header, when appropriate. | + +_For the sake of brevity, where the above says `List[str]` any instance of a `list`, `set`, `frozenset`, or `tuple` will be acceptable. Alternatively, if the value is a `str`, it can be a comma delimited list._ + +## Route level overrides + +.. column:: + +``` +It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. + +The values that can be overridden with this decorator are: + +- `origins` +- `expose_headers` +- `allow_headers` +- `allow_methods` +- `supports_credentials` +- `max_age` +``` + +.. column:: + +```` +```python +from sanic_ext import cors + +app.config.CORS_ORIGINS = "https://foo.com" + +@app.get("/", host="bar.com") +@cors(origins="https://bar.com") +async def hello_world(request): + return text("Hello, world.") +``` +```` From b2064e2343ef67ac6edcc926ce6782521427f9ff Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:27 +0200 Subject: [PATCH 193/698] New translations methods.md (Japanese) --- .../ja/plugins/sanic-ext/http/methods.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/http/methods.md diff --git a/guide/content/ja/plugins/sanic-ext/http/methods.md b/guide/content/ja/plugins/sanic-ext/http/methods.md new file mode 100644 index 0000000000..34e841d723 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/http/methods.md @@ -0,0 +1,165 @@ +--- +title: Sanic Extensions - HTTP Methods +--- + +# HTTP Methods + +## Auto-endpoints + +The default behavior is to automatically generate `HEAD` endpoints for all `GET` routes, and `OPTIONS` endpoints for all +routes. Additionally, there is the option to automatically generate `TRACE` endpoints. However, these are not enabled by +default. + +### HEAD + +.. column:: + +``` +- **Configuration**: `AUTO_HEAD` (default `True`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) + +A `HEAD` request provides the headers and an otherwise identical response to what a `GET` request would provide. +However, it does not actually return the body. +``` + +.. column:: + +```` +```python +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +Given the above route definition, Sanic Extensions will enable `HEAD` responses, as seen here. + +``` +$ curl localhost:8000 --head +HTTP/1.1 200 OK +access-control-allow-origin: * +content-length: 13 +connection: keep-alive +content-type: text/plain; charset=utf-8 +``` +```` + +### OPTIONS + +.. column:: + +``` +- **Configuration**: `AUTO_OPTIONS` (default `True`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) + +`OPTIONS` requests provide the recipient with details about how the client is allowed to communicate with a given +endpoint. +``` + +.. column:: + +```` +```python +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +Given the above route definition, Sanic Extensions will enable `OPTIONS` responses, as seen here. + +It is important to note that we also see `access-control-allow-origins` in this example. This is because +the [CORS protection](cors.md) is enabled by default. + +``` +$ curl localhost:8000 -X OPTIONS -i +HTTP/1.1 204 No Content +allow: GET,HEAD,OPTIONS +access-control-allow-origin: * +connection: keep-alive +``` +```` + +.. tip:: + +``` +Even though Sanic Extensions will setup these routes for you automatically, if you decide to manually create an `@app.options` route, it will *not* be overridden. +``` + +### TRACE + +.. column:: + +``` +- **Configuration**: `AUTO_TRACE` (default `False`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE) + +By default, `TRACE` endpoints will **not** be automatically created. However, Sanic Extensions **will allow** you to +create them if you wanted. This is something that is not allowed in vanilla Sanic. +``` + +.. column:: + +```` +```python +@app.route("/", methods=["trace"]) +async def handler(request): + ... +``` + +To enable auto-creation of these endpoints, you must first enable them when extending Sanic. + +```python +from sanic_ext import Extend, Config + +app.extend(config=Config(http_auto_trace=True)) +``` + +Now, assuming you have some endpoints setup, you can trace them as shown here: + +``` +$ curl localhost:8000 -X TRACE +TRACE / HTTP/1.1 +Host: localhost:9999 +User-Agent: curl/7.76.1 +Accept: */* +``` +```` + +.. tip:: + +``` +Setting up `AUTO_TRACE` can be super helpful, especially when your application is deployed behind a proxy since it will help you determine how the proxy is behaving. +``` + +## Additional method support + +Vanilla Sanic allows you to build endpoints with the following HTTP methods: + +- [GET](/en/guide/basics/routing.html#get) +- [POST](/en/guide/basics/routing.html#post) +- [PUT](/en/guide/basics/routing.html#put) +- [HEAD](/en/guide/basics/routing.html#head) +- [OPTIONS](/en/guide/basics/routing.html#options) +- [PATCH](/en/guide/basics/routing.html#patch) +- [DELETE](/en/guide/basics/routing.html#delete) + +See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more. + +.. column:: + +``` +There are, however, two more "standard" HTTP methods: `TRACE` and `CONNECT`. Sanic Extensions will allow you to build +endpoints using these methods, which would otherwise not be allowed. + +It is worth pointing out that this will *NOT* enable convenience methods: `@app.trace` or `@app.connect`. You need to +use `@app.route` as shown in the example here. +``` + +.. column:: + +```` +```python +@app.route("/", methods=["trace", "connect"]) +async def handler(_): + return empty() +``` +```` From 948644f64e7623004baa100a58f552b2e39f2cd8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:28 +0200 Subject: [PATCH 194/698] New translations methods.md (Korean) --- .../ko/plugins/sanic-ext/http/methods.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/http/methods.md diff --git a/guide/content/ko/plugins/sanic-ext/http/methods.md b/guide/content/ko/plugins/sanic-ext/http/methods.md new file mode 100644 index 0000000000..34e841d723 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/http/methods.md @@ -0,0 +1,165 @@ +--- +title: Sanic Extensions - HTTP Methods +--- + +# HTTP Methods + +## Auto-endpoints + +The default behavior is to automatically generate `HEAD` endpoints for all `GET` routes, and `OPTIONS` endpoints for all +routes. Additionally, there is the option to automatically generate `TRACE` endpoints. However, these are not enabled by +default. + +### HEAD + +.. column:: + +``` +- **Configuration**: `AUTO_HEAD` (default `True`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) + +A `HEAD` request provides the headers and an otherwise identical response to what a `GET` request would provide. +However, it does not actually return the body. +``` + +.. column:: + +```` +```python +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +Given the above route definition, Sanic Extensions will enable `HEAD` responses, as seen here. + +``` +$ curl localhost:8000 --head +HTTP/1.1 200 OK +access-control-allow-origin: * +content-length: 13 +connection: keep-alive +content-type: text/plain; charset=utf-8 +``` +```` + +### OPTIONS + +.. column:: + +``` +- **Configuration**: `AUTO_OPTIONS` (default `True`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) + +`OPTIONS` requests provide the recipient with details about how the client is allowed to communicate with a given +endpoint. +``` + +.. column:: + +```` +```python +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +Given the above route definition, Sanic Extensions will enable `OPTIONS` responses, as seen here. + +It is important to note that we also see `access-control-allow-origins` in this example. This is because +the [CORS protection](cors.md) is enabled by default. + +``` +$ curl localhost:8000 -X OPTIONS -i +HTTP/1.1 204 No Content +allow: GET,HEAD,OPTIONS +access-control-allow-origin: * +connection: keep-alive +``` +```` + +.. tip:: + +``` +Even though Sanic Extensions will setup these routes for you automatically, if you decide to manually create an `@app.options` route, it will *not* be overridden. +``` + +### TRACE + +.. column:: + +``` +- **Configuration**: `AUTO_TRACE` (default `False`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE) + +By default, `TRACE` endpoints will **not** be automatically created. However, Sanic Extensions **will allow** you to +create them if you wanted. This is something that is not allowed in vanilla Sanic. +``` + +.. column:: + +```` +```python +@app.route("/", methods=["trace"]) +async def handler(request): + ... +``` + +To enable auto-creation of these endpoints, you must first enable them when extending Sanic. + +```python +from sanic_ext import Extend, Config + +app.extend(config=Config(http_auto_trace=True)) +``` + +Now, assuming you have some endpoints setup, you can trace them as shown here: + +``` +$ curl localhost:8000 -X TRACE +TRACE / HTTP/1.1 +Host: localhost:9999 +User-Agent: curl/7.76.1 +Accept: */* +``` +```` + +.. tip:: + +``` +Setting up `AUTO_TRACE` can be super helpful, especially when your application is deployed behind a proxy since it will help you determine how the proxy is behaving. +``` + +## Additional method support + +Vanilla Sanic allows you to build endpoints with the following HTTP methods: + +- [GET](/en/guide/basics/routing.html#get) +- [POST](/en/guide/basics/routing.html#post) +- [PUT](/en/guide/basics/routing.html#put) +- [HEAD](/en/guide/basics/routing.html#head) +- [OPTIONS](/en/guide/basics/routing.html#options) +- [PATCH](/en/guide/basics/routing.html#patch) +- [DELETE](/en/guide/basics/routing.html#delete) + +See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more. + +.. column:: + +``` +There are, however, two more "standard" HTTP methods: `TRACE` and `CONNECT`. Sanic Extensions will allow you to build +endpoints using these methods, which would otherwise not be allowed. + +It is worth pointing out that this will *NOT* enable convenience methods: `@app.trace` or `@app.connect`. You need to +use `@app.route` as shown in the example here. +``` + +.. column:: + +```` +```python +@app.route("/", methods=["trace", "connect"]) +async def handler(_): + return empty() +``` +```` From fa9c2831d19cc898f62e35075aebb1894ee306ac Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:28 +0200 Subject: [PATCH 195/698] New translations methods.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/http/methods.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/http/methods.md diff --git a/guide/content/zh/plugins/sanic-ext/http/methods.md b/guide/content/zh/plugins/sanic-ext/http/methods.md new file mode 100644 index 0000000000..34e841d723 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/http/methods.md @@ -0,0 +1,165 @@ +--- +title: Sanic Extensions - HTTP Methods +--- + +# HTTP Methods + +## Auto-endpoints + +The default behavior is to automatically generate `HEAD` endpoints for all `GET` routes, and `OPTIONS` endpoints for all +routes. Additionally, there is the option to automatically generate `TRACE` endpoints. However, these are not enabled by +default. + +### HEAD + +.. column:: + +``` +- **Configuration**: `AUTO_HEAD` (default `True`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) + +A `HEAD` request provides the headers and an otherwise identical response to what a `GET` request would provide. +However, it does not actually return the body. +``` + +.. column:: + +```` +```python +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +Given the above route definition, Sanic Extensions will enable `HEAD` responses, as seen here. + +``` +$ curl localhost:8000 --head +HTTP/1.1 200 OK +access-control-allow-origin: * +content-length: 13 +connection: keep-alive +content-type: text/plain; charset=utf-8 +``` +```` + +### OPTIONS + +.. column:: + +``` +- **Configuration**: `AUTO_OPTIONS` (default `True`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) + +`OPTIONS` requests provide the recipient with details about how the client is allowed to communicate with a given +endpoint. +``` + +.. column:: + +```` +```python +@app.get("/") +async def hello_world(request): + return text("Hello, world.") +``` + +Given the above route definition, Sanic Extensions will enable `OPTIONS` responses, as seen here. + +It is important to note that we also see `access-control-allow-origins` in this example. This is because +the [CORS protection](cors.md) is enabled by default. + +``` +$ curl localhost:8000 -X OPTIONS -i +HTTP/1.1 204 No Content +allow: GET,HEAD,OPTIONS +access-control-allow-origin: * +connection: keep-alive +``` +```` + +.. tip:: + +``` +Even though Sanic Extensions will setup these routes for you automatically, if you decide to manually create an `@app.options` route, it will *not* be overridden. +``` + +### TRACE + +.. column:: + +``` +- **Configuration**: `AUTO_TRACE` (default `False`) +- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE) + +By default, `TRACE` endpoints will **not** be automatically created. However, Sanic Extensions **will allow** you to +create them if you wanted. This is something that is not allowed in vanilla Sanic. +``` + +.. column:: + +```` +```python +@app.route("/", methods=["trace"]) +async def handler(request): + ... +``` + +To enable auto-creation of these endpoints, you must first enable them when extending Sanic. + +```python +from sanic_ext import Extend, Config + +app.extend(config=Config(http_auto_trace=True)) +``` + +Now, assuming you have some endpoints setup, you can trace them as shown here: + +``` +$ curl localhost:8000 -X TRACE +TRACE / HTTP/1.1 +Host: localhost:9999 +User-Agent: curl/7.76.1 +Accept: */* +``` +```` + +.. tip:: + +``` +Setting up `AUTO_TRACE` can be super helpful, especially when your application is deployed behind a proxy since it will help you determine how the proxy is behaving. +``` + +## Additional method support + +Vanilla Sanic allows you to build endpoints with the following HTTP methods: + +- [GET](/en/guide/basics/routing.html#get) +- [POST](/en/guide/basics/routing.html#post) +- [PUT](/en/guide/basics/routing.html#put) +- [HEAD](/en/guide/basics/routing.html#head) +- [OPTIONS](/en/guide/basics/routing.html#options) +- [PATCH](/en/guide/basics/routing.html#patch) +- [DELETE](/en/guide/basics/routing.html#delete) + +See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more. + +.. column:: + +``` +There are, however, two more "standard" HTTP methods: `TRACE` and `CONNECT`. Sanic Extensions will allow you to build +endpoints using these methods, which would otherwise not be allowed. + +It is worth pointing out that this will *NOT* enable convenience methods: `@app.trace` or `@app.connect`. You need to +use `@app.route` as shown in the example here. +``` + +.. column:: + +```` +```python +@app.route("/", methods=["trace", "connect"]) +async def handler(_): + return empty() +``` +```` From 479461fa5d9cb5d8ac92d3c308704eafadcdafcf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:30 +0200 Subject: [PATCH 196/698] New translations injection.md (Japanese) --- .../content/ja/plugins/sanic-ext/injection.md | 396 ++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/injection.md diff --git a/guide/content/ja/plugins/sanic-ext/injection.md b/guide/content/ja/plugins/sanic-ext/injection.md new file mode 100644 index 0000000000..7e9711d749 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/injection.md @@ -0,0 +1,396 @@ +--- +title: Sanic Extensions - Dependency Injection +--- + +# Dependency Injection + +Dependency injection is a method to add arguments to a route handler based upon the defined function signature. Specifically, it looks at the **type annotations** of the arguments in the handler. This can be useful in a number of cases like: + +- Fetching an object based upon request headers (like the current session user) +- Recasting certain objects into a specific type +- Using the request object to prefetch data +- Auto inject services + +The `Extend` instance has two basic methods on it used for dependency injection: a lower level `add_dependency`, and a higher level `dependency`. + +**Lower level**: `app.ext.add_dependency(...)` + +- `type: Type,`: some unique class that will be the type of the object +- `constructor: Optional[Callable[..., Any]],` (OPTIONAL): a function that will return that type + +**Higher level**: `app.ext.dependency(...)` + +- `obj: Any`: any object that you would like injected +- `name: Optional[str]`: some name that could alternately be used as a reference + +Let's explore some use cases here. + +.. warning:: + +``` +If you used dependency injection prior to v21.12, the lower level API method was called `injection`. It has since been renamed to `add_dependency` and starting in v21.12 `injection` is an alias for `add_dependency`. The `injection` method has been deprecated for removal in v22.6. +``` + +## Basic implementation + +The simplest use case would be simply to recast a value. + +.. column:: + +``` +This could be useful if you have a model that you want to generate based upon the matched path parameters. +``` + +.. column:: + +```` +```python +@dataclass +class IceCream: + flavor: str + + def __str__(self) -> str: + return f"{self.flavor.title()} (Yum!)" + +app.ext.add_dependency(IceCream) + +@app.get("/") +async def ice_cream(request, flavor: IceCream): + return text(f"You chose: {flavor}") +``` + +``` +$ curl localhost:8000/chocolate +You chose Chocolate (Yum!) +``` +```` + +.. column:: + +``` +This works by passing a keyword argument to the constructor of the `type` argument. The previous example is equivalent to this. +``` + +.. column:: + +```` +```python +flavor = IceCream(flavor="chocolate") +``` +```` + +## Additional constructors + +.. column:: + +``` +Sometimes you may need to also pass a constructor. This could be a function, or perhaps even a classmethod that acts as a constructor. In this example, we are creating an injection that will call `Person.create` first. + +Also important to note on this example, we are actually injecting **two (2)** objects! It of course does not need to be this way, but we will inject objects based upon the function signature. +``` + +.. column:: + +```` +```python +@dataclass +class PersonID: + person_id: int + +@dataclass +class Person: + person_id: PersonID + name: str + age: int + + @classmethod + async def create(cls, request: Request, person_id: int): + return cls(person_id=PersonID(person_id), name="noname", age=111) + + +app.ext.add_dependency(Person, Person.create) +app.ext.add_dependency(PersonID) + +@app.get("/person/") +async def person_details( + request: Request, person_id: PersonID, person: Person +): + return text(f"{person_id}\n{person}") +``` + +``` +$ curl localhost:8000/person/123 +PersonID(person_id=123) +Person(person_id=PersonID(person_id=123), name='noname', age=111) +``` +```` + +When a `constructor` is passed to `ext.add_dependency` (like in this example) that will be called. If not, then the object will be created by calling the `type`. A couple of important things to note about passing a `constructor`: + +1. A positional `request: Request` argument is _usually_ expected. See the `Person.create` method above as an example using a `request` and [arbitrary constructors](#arbitrary-constructors) for how to use a callable that does not require a `request`. +2. All matched path parameters are injected as keyword arguments. +3. Dependencies can be chained and nested. Notice how in the previous example the `Person` dataclass has a `PersonID`? That means that `PersonID` will be called first, and that value is added to the keyword arguments when calling `Person.create`. + +## Arbitrary constructors + +.. column:: + +``` +Sometimes you may want to construct your injectable _without_ the `Request` object. This is useful if you have arbitrary classes or functions that create your objects. If the callable does have any required arguments, then they should themselves be injectable objects. + +This is very useful if you have services or other types of objects that should only exist for the lifetime of a single request. For example, you might use this pattern to pull a single connection from your database pool. +``` + +.. column:: + +```` +```python +class Alpha: + ... + +class Beta: + def __init__(self, alpha: Alpha) -> None: + self.alpha = alpha + +app.ext.add_dependency(Alpha) +app.ext.add_dependency(Beta) + +@app.get("/beta") +async def handler(request: Request, beta: Beta): + assert isinstance(beta.alpha, Alpha) +``` +```` + +_Added in v22.9_ + +## Objects from the `Request` + +.. column:: + +```` +Sometimes you may want to extract details from the request and preprocess them. You could, for example, cast the request JSON to a Python object, and then add some additional logic based upon DB queries. + +.. warning:: + + If you plan to use this method, you should note that the injection actually happens *before* Sanic has had a chance to read the request body. The headers should already have been consumed. So, if you do want access to the body, you will need to manually consume as seen in this example. + + ```python + await request.receive_body() + ``` + + + This could be used in cases where you otherwise might: + + - use middleware to preprocess and add something to the `request.ctx` + - use decorators to preprocess and inject arguments into the request handler + + In this example, we are using the `Request` object in the `compile_profile` constructor to run a fake DB query to generate and return a `UserProfile` object. +```` + +.. column:: + +```` +```python +@dataclass +class User: + name: str + +@dataclass +class UserProfile: + user: User + age: int = field(default=0) + email: str = field(default="") + + def __json__(self): + return ujson.dumps( + { + "name": self.user.name, + "age": self.age, + "email": self.email, + } + ) + +async def fake_request_to_db(body): + today = date.today() + email = f'{body["name"]}@something.com'.lower() + difference = today - date.fromisoformat(body["birthday"]) + age = int(difference.days / 365) + return UserProfile( + User(body["name"]), + age=age, + email=email, + ) + +async def compile_profile(request: Request): + await request.receive_body() + profile = await fake_request_to_db(request.json) + return profile + +app.ext.add_dependency(UserProfile, compile_profile) + +@app.patch("/profile") +async def update_profile(request, profile: UserProfile): + return json(profile) +``` + +``` +$ curl localhost:8000/profile -X PATCH -d '{"name": "Alice", "birthday": "2000-01-01"}' +{ + "name":"Alice", + "age":21, + "email":"alice@something.com" +} +``` +```` + +## Injecting services + +It is a common pattern to create things like database connection pools and store them on the `app.ctx` object. This makes them available throughout your application, which is certainly a convenience. One downside, however, is that you no longer have a typed object to work with. You can use dependency injections to fix this. First we will show the concept using the lower level `add_dependency` like we have been using in the previous examples. But, there is a better way using the higher level `dependency` method. + +### The lower level API using `add_dependency` + +.. column:: + +``` +This works very similar to the [last example](#objects-from-the-request) where the goal is the extract something from the `Request` object. In this example, a database object was created on the `app.ctx` instance, and is being returned in the dependency injection constructor. +``` + +.. column:: + +```` +```python +class FakeConnection: + async def execute(self, query: str, **arguments): + return "result" + +@app.before_server_start +async def setup_db(app, _): + app.ctx.db_conn = FakeConnection() + app.ext.add_dependency(FakeConnection, get_db) + +def get_db(request: Request): + return request.app.ctx.db_conn + + + +@app.get("/") +async def handler(request, conn: FakeConnection): + response = await conn.execute("...") + return text(response) +``` +``` +$ curl localhost:8000/ +result +``` +```` + +### The higher level API using `dependency` + +.. column:: + +``` +Since we have an actual *object* that is available when adding the dependency injection, we can use the higher level `dependency` method. This will make the pattern much easier to write. + +This method should always be used when you want to inject something that exists throughout the lifetime of the application instance and is not request specific. It is very useful for services, third party clients, and connection pools since they are not request specific. +``` + +.. column:: + +```` +```python +class FakeConnection: + async def execute(self, query: str, **arguments): + return "result" + +@app.before_server_start +async def setup_db(app, _): + db_conn = FakeConnection() + app.ext.dependency(db_conn) + +@app.get("/") +async def handler(request, conn: FakeConnection): + response = await conn.execute("...") + return text(response) +``` +``` +$ curl localhost:8000/ +result +``` +```` + +## Generic types + +Be carefule when using a [generic type](https://docs.python.org/3/library/typing.html#typing.Generic). The way that Sanic's dependency injection works is by matching the entire type definition. Therefore, `Foo` is not the same as `Foo[str]`. This can be particularly tricky when trying to use the [higher-level `dependency` method](#the-higher-level-api-using-dependency) since the type is inferred. + +.. column:: + +``` +For example, this will **NOT** work as expected since there is no definition for `Test[str]`. +``` + +.. column:: + +```` +```python +import typing +from sanic import Sanic, text + +T = typing.TypeVar("T") + +class Test(typing.Generic[T]): + test: T + +app = Sanic("testapp") +app.ext.dependency(Test()) + +@app.get("/") +def test(request, test: Test[str]): + ... +``` +```` + +.. column:: + +``` +To get this example to work, you will need to add an explicit definition for the type you intend to be injected. +``` + +.. column:: + +```` +```python +import typing +from sanic import Sanic, text + +T = typing.TypeVar("T") + +class Test(typing.Generic[T]): + test: T + +app = Sanic("testapp") +_singleton = Test() +app.ext.add_dependency(Test[str], lambda: _singleton) + +@app.get("/") +def test(request, test: Test[str]): + ... +``` +```` + +## Configuration + +.. column:: + +``` +By default, dependencies will be injected after the `http.routing.after` [signal](../../guide/advanced/signals.md#built-in-signals). Starting in v22.9, you can change this to the `http.handler.before` signal. +``` + +.. column:: + +```` +```python +app.config.INJECTION_SIGNAL = "http.handler.before" +``` +```` + +_Added in v22.9_ From 2e49b62d3ee6af39468a673caeffcf7a5c4841b0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:31 +0200 Subject: [PATCH 197/698] New translations injection.md (Korean) --- .../content/ko/plugins/sanic-ext/injection.md | 396 ++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/injection.md diff --git a/guide/content/ko/plugins/sanic-ext/injection.md b/guide/content/ko/plugins/sanic-ext/injection.md new file mode 100644 index 0000000000..7e9711d749 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/injection.md @@ -0,0 +1,396 @@ +--- +title: Sanic Extensions - Dependency Injection +--- + +# Dependency Injection + +Dependency injection is a method to add arguments to a route handler based upon the defined function signature. Specifically, it looks at the **type annotations** of the arguments in the handler. This can be useful in a number of cases like: + +- Fetching an object based upon request headers (like the current session user) +- Recasting certain objects into a specific type +- Using the request object to prefetch data +- Auto inject services + +The `Extend` instance has two basic methods on it used for dependency injection: a lower level `add_dependency`, and a higher level `dependency`. + +**Lower level**: `app.ext.add_dependency(...)` + +- `type: Type,`: some unique class that will be the type of the object +- `constructor: Optional[Callable[..., Any]],` (OPTIONAL): a function that will return that type + +**Higher level**: `app.ext.dependency(...)` + +- `obj: Any`: any object that you would like injected +- `name: Optional[str]`: some name that could alternately be used as a reference + +Let's explore some use cases here. + +.. warning:: + +``` +If you used dependency injection prior to v21.12, the lower level API method was called `injection`. It has since been renamed to `add_dependency` and starting in v21.12 `injection` is an alias for `add_dependency`. The `injection` method has been deprecated for removal in v22.6. +``` + +## Basic implementation + +The simplest use case would be simply to recast a value. + +.. column:: + +``` +This could be useful if you have a model that you want to generate based upon the matched path parameters. +``` + +.. column:: + +```` +```python +@dataclass +class IceCream: + flavor: str + + def __str__(self) -> str: + return f"{self.flavor.title()} (Yum!)" + +app.ext.add_dependency(IceCream) + +@app.get("/") +async def ice_cream(request, flavor: IceCream): + return text(f"You chose: {flavor}") +``` + +``` +$ curl localhost:8000/chocolate +You chose Chocolate (Yum!) +``` +```` + +.. column:: + +``` +This works by passing a keyword argument to the constructor of the `type` argument. The previous example is equivalent to this. +``` + +.. column:: + +```` +```python +flavor = IceCream(flavor="chocolate") +``` +```` + +## Additional constructors + +.. column:: + +``` +Sometimes you may need to also pass a constructor. This could be a function, or perhaps even a classmethod that acts as a constructor. In this example, we are creating an injection that will call `Person.create` first. + +Also important to note on this example, we are actually injecting **two (2)** objects! It of course does not need to be this way, but we will inject objects based upon the function signature. +``` + +.. column:: + +```` +```python +@dataclass +class PersonID: + person_id: int + +@dataclass +class Person: + person_id: PersonID + name: str + age: int + + @classmethod + async def create(cls, request: Request, person_id: int): + return cls(person_id=PersonID(person_id), name="noname", age=111) + + +app.ext.add_dependency(Person, Person.create) +app.ext.add_dependency(PersonID) + +@app.get("/person/") +async def person_details( + request: Request, person_id: PersonID, person: Person +): + return text(f"{person_id}\n{person}") +``` + +``` +$ curl localhost:8000/person/123 +PersonID(person_id=123) +Person(person_id=PersonID(person_id=123), name='noname', age=111) +``` +```` + +When a `constructor` is passed to `ext.add_dependency` (like in this example) that will be called. If not, then the object will be created by calling the `type`. A couple of important things to note about passing a `constructor`: + +1. A positional `request: Request` argument is _usually_ expected. See the `Person.create` method above as an example using a `request` and [arbitrary constructors](#arbitrary-constructors) for how to use a callable that does not require a `request`. +2. All matched path parameters are injected as keyword arguments. +3. Dependencies can be chained and nested. Notice how in the previous example the `Person` dataclass has a `PersonID`? That means that `PersonID` will be called first, and that value is added to the keyword arguments when calling `Person.create`. + +## Arbitrary constructors + +.. column:: + +``` +Sometimes you may want to construct your injectable _without_ the `Request` object. This is useful if you have arbitrary classes or functions that create your objects. If the callable does have any required arguments, then they should themselves be injectable objects. + +This is very useful if you have services or other types of objects that should only exist for the lifetime of a single request. For example, you might use this pattern to pull a single connection from your database pool. +``` + +.. column:: + +```` +```python +class Alpha: + ... + +class Beta: + def __init__(self, alpha: Alpha) -> None: + self.alpha = alpha + +app.ext.add_dependency(Alpha) +app.ext.add_dependency(Beta) + +@app.get("/beta") +async def handler(request: Request, beta: Beta): + assert isinstance(beta.alpha, Alpha) +``` +```` + +_Added in v22.9_ + +## Objects from the `Request` + +.. column:: + +```` +Sometimes you may want to extract details from the request and preprocess them. You could, for example, cast the request JSON to a Python object, and then add some additional logic based upon DB queries. + +.. warning:: + + If you plan to use this method, you should note that the injection actually happens *before* Sanic has had a chance to read the request body. The headers should already have been consumed. So, if you do want access to the body, you will need to manually consume as seen in this example. + + ```python + await request.receive_body() + ``` + + + This could be used in cases where you otherwise might: + + - use middleware to preprocess and add something to the `request.ctx` + - use decorators to preprocess and inject arguments into the request handler + + In this example, we are using the `Request` object in the `compile_profile` constructor to run a fake DB query to generate and return a `UserProfile` object. +```` + +.. column:: + +```` +```python +@dataclass +class User: + name: str + +@dataclass +class UserProfile: + user: User + age: int = field(default=0) + email: str = field(default="") + + def __json__(self): + return ujson.dumps( + { + "name": self.user.name, + "age": self.age, + "email": self.email, + } + ) + +async def fake_request_to_db(body): + today = date.today() + email = f'{body["name"]}@something.com'.lower() + difference = today - date.fromisoformat(body["birthday"]) + age = int(difference.days / 365) + return UserProfile( + User(body["name"]), + age=age, + email=email, + ) + +async def compile_profile(request: Request): + await request.receive_body() + profile = await fake_request_to_db(request.json) + return profile + +app.ext.add_dependency(UserProfile, compile_profile) + +@app.patch("/profile") +async def update_profile(request, profile: UserProfile): + return json(profile) +``` + +``` +$ curl localhost:8000/profile -X PATCH -d '{"name": "Alice", "birthday": "2000-01-01"}' +{ + "name":"Alice", + "age":21, + "email":"alice@something.com" +} +``` +```` + +## Injecting services + +It is a common pattern to create things like database connection pools and store them on the `app.ctx` object. This makes them available throughout your application, which is certainly a convenience. One downside, however, is that you no longer have a typed object to work with. You can use dependency injections to fix this. First we will show the concept using the lower level `add_dependency` like we have been using in the previous examples. But, there is a better way using the higher level `dependency` method. + +### The lower level API using `add_dependency` + +.. column:: + +``` +This works very similar to the [last example](#objects-from-the-request) where the goal is the extract something from the `Request` object. In this example, a database object was created on the `app.ctx` instance, and is being returned in the dependency injection constructor. +``` + +.. column:: + +```` +```python +class FakeConnection: + async def execute(self, query: str, **arguments): + return "result" + +@app.before_server_start +async def setup_db(app, _): + app.ctx.db_conn = FakeConnection() + app.ext.add_dependency(FakeConnection, get_db) + +def get_db(request: Request): + return request.app.ctx.db_conn + + + +@app.get("/") +async def handler(request, conn: FakeConnection): + response = await conn.execute("...") + return text(response) +``` +``` +$ curl localhost:8000/ +result +``` +```` + +### The higher level API using `dependency` + +.. column:: + +``` +Since we have an actual *object* that is available when adding the dependency injection, we can use the higher level `dependency` method. This will make the pattern much easier to write. + +This method should always be used when you want to inject something that exists throughout the lifetime of the application instance and is not request specific. It is very useful for services, third party clients, and connection pools since they are not request specific. +``` + +.. column:: + +```` +```python +class FakeConnection: + async def execute(self, query: str, **arguments): + return "result" + +@app.before_server_start +async def setup_db(app, _): + db_conn = FakeConnection() + app.ext.dependency(db_conn) + +@app.get("/") +async def handler(request, conn: FakeConnection): + response = await conn.execute("...") + return text(response) +``` +``` +$ curl localhost:8000/ +result +``` +```` + +## Generic types + +Be carefule when using a [generic type](https://docs.python.org/3/library/typing.html#typing.Generic). The way that Sanic's dependency injection works is by matching the entire type definition. Therefore, `Foo` is not the same as `Foo[str]`. This can be particularly tricky when trying to use the [higher-level `dependency` method](#the-higher-level-api-using-dependency) since the type is inferred. + +.. column:: + +``` +For example, this will **NOT** work as expected since there is no definition for `Test[str]`. +``` + +.. column:: + +```` +```python +import typing +from sanic import Sanic, text + +T = typing.TypeVar("T") + +class Test(typing.Generic[T]): + test: T + +app = Sanic("testapp") +app.ext.dependency(Test()) + +@app.get("/") +def test(request, test: Test[str]): + ... +``` +```` + +.. column:: + +``` +To get this example to work, you will need to add an explicit definition for the type you intend to be injected. +``` + +.. column:: + +```` +```python +import typing +from sanic import Sanic, text + +T = typing.TypeVar("T") + +class Test(typing.Generic[T]): + test: T + +app = Sanic("testapp") +_singleton = Test() +app.ext.add_dependency(Test[str], lambda: _singleton) + +@app.get("/") +def test(request, test: Test[str]): + ... +``` +```` + +## Configuration + +.. column:: + +``` +By default, dependencies will be injected after the `http.routing.after` [signal](../../guide/advanced/signals.md#built-in-signals). Starting in v22.9, you can change this to the `http.handler.before` signal. +``` + +.. column:: + +```` +```python +app.config.INJECTION_SIGNAL = "http.handler.before" +``` +```` + +_Added in v22.9_ From 8e8ad8f32a0d45d3f22d5766048be80c4896ef66 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:32 +0200 Subject: [PATCH 198/698] New translations injection.md (Chinese Simplified) --- .../content/zh/plugins/sanic-ext/injection.md | 396 ++++++++++++++++++ 1 file changed, 396 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/injection.md diff --git a/guide/content/zh/plugins/sanic-ext/injection.md b/guide/content/zh/plugins/sanic-ext/injection.md new file mode 100644 index 0000000000..7e9711d749 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/injection.md @@ -0,0 +1,396 @@ +--- +title: Sanic Extensions - Dependency Injection +--- + +# Dependency Injection + +Dependency injection is a method to add arguments to a route handler based upon the defined function signature. Specifically, it looks at the **type annotations** of the arguments in the handler. This can be useful in a number of cases like: + +- Fetching an object based upon request headers (like the current session user) +- Recasting certain objects into a specific type +- Using the request object to prefetch data +- Auto inject services + +The `Extend` instance has two basic methods on it used for dependency injection: a lower level `add_dependency`, and a higher level `dependency`. + +**Lower level**: `app.ext.add_dependency(...)` + +- `type: Type,`: some unique class that will be the type of the object +- `constructor: Optional[Callable[..., Any]],` (OPTIONAL): a function that will return that type + +**Higher level**: `app.ext.dependency(...)` + +- `obj: Any`: any object that you would like injected +- `name: Optional[str]`: some name that could alternately be used as a reference + +Let's explore some use cases here. + +.. warning:: + +``` +If you used dependency injection prior to v21.12, the lower level API method was called `injection`. It has since been renamed to `add_dependency` and starting in v21.12 `injection` is an alias for `add_dependency`. The `injection` method has been deprecated for removal in v22.6. +``` + +## Basic implementation + +The simplest use case would be simply to recast a value. + +.. column:: + +``` +This could be useful if you have a model that you want to generate based upon the matched path parameters. +``` + +.. column:: + +```` +```python +@dataclass +class IceCream: + flavor: str + + def __str__(self) -> str: + return f"{self.flavor.title()} (Yum!)" + +app.ext.add_dependency(IceCream) + +@app.get("/") +async def ice_cream(request, flavor: IceCream): + return text(f"You chose: {flavor}") +``` + +``` +$ curl localhost:8000/chocolate +You chose Chocolate (Yum!) +``` +```` + +.. column:: + +``` +This works by passing a keyword argument to the constructor of the `type` argument. The previous example is equivalent to this. +``` + +.. column:: + +```` +```python +flavor = IceCream(flavor="chocolate") +``` +```` + +## Additional constructors + +.. column:: + +``` +Sometimes you may need to also pass a constructor. This could be a function, or perhaps even a classmethod that acts as a constructor. In this example, we are creating an injection that will call `Person.create` first. + +Also important to note on this example, we are actually injecting **two (2)** objects! It of course does not need to be this way, but we will inject objects based upon the function signature. +``` + +.. column:: + +```` +```python +@dataclass +class PersonID: + person_id: int + +@dataclass +class Person: + person_id: PersonID + name: str + age: int + + @classmethod + async def create(cls, request: Request, person_id: int): + return cls(person_id=PersonID(person_id), name="noname", age=111) + + +app.ext.add_dependency(Person, Person.create) +app.ext.add_dependency(PersonID) + +@app.get("/person/") +async def person_details( + request: Request, person_id: PersonID, person: Person +): + return text(f"{person_id}\n{person}") +``` + +``` +$ curl localhost:8000/person/123 +PersonID(person_id=123) +Person(person_id=PersonID(person_id=123), name='noname', age=111) +``` +```` + +When a `constructor` is passed to `ext.add_dependency` (like in this example) that will be called. If not, then the object will be created by calling the `type`. A couple of important things to note about passing a `constructor`: + +1. A positional `request: Request` argument is _usually_ expected. See the `Person.create` method above as an example using a `request` and [arbitrary constructors](#arbitrary-constructors) for how to use a callable that does not require a `request`. +2. All matched path parameters are injected as keyword arguments. +3. Dependencies can be chained and nested. Notice how in the previous example the `Person` dataclass has a `PersonID`? That means that `PersonID` will be called first, and that value is added to the keyword arguments when calling `Person.create`. + +## Arbitrary constructors + +.. column:: + +``` +Sometimes you may want to construct your injectable _without_ the `Request` object. This is useful if you have arbitrary classes or functions that create your objects. If the callable does have any required arguments, then they should themselves be injectable objects. + +This is very useful if you have services or other types of objects that should only exist for the lifetime of a single request. For example, you might use this pattern to pull a single connection from your database pool. +``` + +.. column:: + +```` +```python +class Alpha: + ... + +class Beta: + def __init__(self, alpha: Alpha) -> None: + self.alpha = alpha + +app.ext.add_dependency(Alpha) +app.ext.add_dependency(Beta) + +@app.get("/beta") +async def handler(request: Request, beta: Beta): + assert isinstance(beta.alpha, Alpha) +``` +```` + +_Added in v22.9_ + +## Objects from the `Request` + +.. column:: + +```` +Sometimes you may want to extract details from the request and preprocess them. You could, for example, cast the request JSON to a Python object, and then add some additional logic based upon DB queries. + +.. warning:: + + If you plan to use this method, you should note that the injection actually happens *before* Sanic has had a chance to read the request body. The headers should already have been consumed. So, if you do want access to the body, you will need to manually consume as seen in this example. + + ```python + await request.receive_body() + ``` + + + This could be used in cases where you otherwise might: + + - use middleware to preprocess and add something to the `request.ctx` + - use decorators to preprocess and inject arguments into the request handler + + In this example, we are using the `Request` object in the `compile_profile` constructor to run a fake DB query to generate and return a `UserProfile` object. +```` + +.. column:: + +```` +```python +@dataclass +class User: + name: str + +@dataclass +class UserProfile: + user: User + age: int = field(default=0) + email: str = field(default="") + + def __json__(self): + return ujson.dumps( + { + "name": self.user.name, + "age": self.age, + "email": self.email, + } + ) + +async def fake_request_to_db(body): + today = date.today() + email = f'{body["name"]}@something.com'.lower() + difference = today - date.fromisoformat(body["birthday"]) + age = int(difference.days / 365) + return UserProfile( + User(body["name"]), + age=age, + email=email, + ) + +async def compile_profile(request: Request): + await request.receive_body() + profile = await fake_request_to_db(request.json) + return profile + +app.ext.add_dependency(UserProfile, compile_profile) + +@app.patch("/profile") +async def update_profile(request, profile: UserProfile): + return json(profile) +``` + +``` +$ curl localhost:8000/profile -X PATCH -d '{"name": "Alice", "birthday": "2000-01-01"}' +{ + "name":"Alice", + "age":21, + "email":"alice@something.com" +} +``` +```` + +## Injecting services + +It is a common pattern to create things like database connection pools and store them on the `app.ctx` object. This makes them available throughout your application, which is certainly a convenience. One downside, however, is that you no longer have a typed object to work with. You can use dependency injections to fix this. First we will show the concept using the lower level `add_dependency` like we have been using in the previous examples. But, there is a better way using the higher level `dependency` method. + +### The lower level API using `add_dependency` + +.. column:: + +``` +This works very similar to the [last example](#objects-from-the-request) where the goal is the extract something from the `Request` object. In this example, a database object was created on the `app.ctx` instance, and is being returned in the dependency injection constructor. +``` + +.. column:: + +```` +```python +class FakeConnection: + async def execute(self, query: str, **arguments): + return "result" + +@app.before_server_start +async def setup_db(app, _): + app.ctx.db_conn = FakeConnection() + app.ext.add_dependency(FakeConnection, get_db) + +def get_db(request: Request): + return request.app.ctx.db_conn + + + +@app.get("/") +async def handler(request, conn: FakeConnection): + response = await conn.execute("...") + return text(response) +``` +``` +$ curl localhost:8000/ +result +``` +```` + +### The higher level API using `dependency` + +.. column:: + +``` +Since we have an actual *object* that is available when adding the dependency injection, we can use the higher level `dependency` method. This will make the pattern much easier to write. + +This method should always be used when you want to inject something that exists throughout the lifetime of the application instance and is not request specific. It is very useful for services, third party clients, and connection pools since they are not request specific. +``` + +.. column:: + +```` +```python +class FakeConnection: + async def execute(self, query: str, **arguments): + return "result" + +@app.before_server_start +async def setup_db(app, _): + db_conn = FakeConnection() + app.ext.dependency(db_conn) + +@app.get("/") +async def handler(request, conn: FakeConnection): + response = await conn.execute("...") + return text(response) +``` +``` +$ curl localhost:8000/ +result +``` +```` + +## Generic types + +Be carefule when using a [generic type](https://docs.python.org/3/library/typing.html#typing.Generic). The way that Sanic's dependency injection works is by matching the entire type definition. Therefore, `Foo` is not the same as `Foo[str]`. This can be particularly tricky when trying to use the [higher-level `dependency` method](#the-higher-level-api-using-dependency) since the type is inferred. + +.. column:: + +``` +For example, this will **NOT** work as expected since there is no definition for `Test[str]`. +``` + +.. column:: + +```` +```python +import typing +from sanic import Sanic, text + +T = typing.TypeVar("T") + +class Test(typing.Generic[T]): + test: T + +app = Sanic("testapp") +app.ext.dependency(Test()) + +@app.get("/") +def test(request, test: Test[str]): + ... +``` +```` + +.. column:: + +``` +To get this example to work, you will need to add an explicit definition for the type you intend to be injected. +``` + +.. column:: + +```` +```python +import typing +from sanic import Sanic, text + +T = typing.TypeVar("T") + +class Test(typing.Generic[T]): + test: T + +app = Sanic("testapp") +_singleton = Test() +app.ext.add_dependency(Test[str], lambda: _singleton) + +@app.get("/") +def test(request, test: Test[str]): + ... +``` +```` + +## Configuration + +.. column:: + +``` +By default, dependencies will be injected after the `http.routing.after` [signal](../../guide/advanced/signals.md#built-in-signals). Starting in v22.9, you can change this to the `http.handler.before` signal. +``` + +.. column:: + +```` +```python +app.config.INJECTION_SIGNAL = "http.handler.before" +``` +```` + +_Added in v22.9_ From f649a73c776abd6c942323a53425b739301394fa Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:33 +0200 Subject: [PATCH 199/698] New translations logger.md (Japanese) --- guide/content/ja/plugins/sanic-ext/logger.md | 38 ++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/logger.md diff --git a/guide/content/ja/plugins/sanic-ext/logger.md b/guide/content/ja/plugins/sanic-ext/logger.md new file mode 100644 index 0000000000..0ea5f309b8 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/logger.md @@ -0,0 +1,38 @@ +--- +title: Sanic Extensions - Background logger +--- + +# Background logger + +The background logger requires both `sanic>=22.9` and `sanic-ext>=22.9`. + +You can setup Sanic Extensions to log all of your messages from a background process. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). + +Logging can sometimes be an expensive operation. By pushing all logging off to a background process, you can potentially gain some performance benefits. + +## Setup + +.. column:: + +``` +Out of the box, the background logger is disabled. You will need to opt-in if you would like to use it. +``` + +.. column:: + +```` +```python +app.config.LOGGING = True +``` +```` + +## How does it work + +When enabled, the extension will create a `multoprocessing.Queue`. It will remove all handlers on the [default Sanic loggers](../../guide/best-practices/logging.md) and replace them with a [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler). When a message is logged, it will be pushed into the queue by the handler, and read by the background process to the log handlers that were originally in place. This means you can still configure logging as normal and it should "just work." + +## Configuration + +| Key | Type | Default | Description | +| ------------------------------------------------------------------------------------- | ------ | ------- | ------------------------------------------------------- | +| LOGGING | `bool` | `False` | Whether to enable this extension. | +| LOGGING_QUEUE_MAX_SIZE | `int` | `4096` | The max size of the queue before messages are rejected. | From 6c303269a9d81f271a04db10674cd7371df860c0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:34 +0200 Subject: [PATCH 200/698] New translations logger.md (Korean) --- guide/content/ko/plugins/sanic-ext/logger.md | 38 ++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/logger.md diff --git a/guide/content/ko/plugins/sanic-ext/logger.md b/guide/content/ko/plugins/sanic-ext/logger.md new file mode 100644 index 0000000000..0ea5f309b8 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/logger.md @@ -0,0 +1,38 @@ +--- +title: Sanic Extensions - Background logger +--- + +# Background logger + +The background logger requires both `sanic>=22.9` and `sanic-ext>=22.9`. + +You can setup Sanic Extensions to log all of your messages from a background process. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). + +Logging can sometimes be an expensive operation. By pushing all logging off to a background process, you can potentially gain some performance benefits. + +## Setup + +.. column:: + +``` +Out of the box, the background logger is disabled. You will need to opt-in if you would like to use it. +``` + +.. column:: + +```` +```python +app.config.LOGGING = True +``` +```` + +## How does it work + +When enabled, the extension will create a `multoprocessing.Queue`. It will remove all handlers on the [default Sanic loggers](../../guide/best-practices/logging.md) and replace them with a [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler). When a message is logged, it will be pushed into the queue by the handler, and read by the background process to the log handlers that were originally in place. This means you can still configure logging as normal and it should "just work." + +## Configuration + +| Key | Type | Default | Description | +| ------------------------------------------------------------------------------------- | ------ | ------- | ------------------------------------------------------- | +| LOGGING | `bool` | `False` | Whether to enable this extension. | +| LOGGING_QUEUE_MAX_SIZE | `int` | `4096` | The max size of the queue before messages are rejected. | From 9129f1dc22d44f855673082a2ef5a6ad3d36aebf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:35 +0200 Subject: [PATCH 201/698] New translations logger.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/logger.md | 38 ++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/logger.md diff --git a/guide/content/zh/plugins/sanic-ext/logger.md b/guide/content/zh/plugins/sanic-ext/logger.md new file mode 100644 index 0000000000..0ea5f309b8 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/logger.md @@ -0,0 +1,38 @@ +--- +title: Sanic Extensions - Background logger +--- + +# Background logger + +The background logger requires both `sanic>=22.9` and `sanic-ext>=22.9`. + +You can setup Sanic Extensions to log all of your messages from a background process. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). + +Logging can sometimes be an expensive operation. By pushing all logging off to a background process, you can potentially gain some performance benefits. + +## Setup + +.. column:: + +``` +Out of the box, the background logger is disabled. You will need to opt-in if you would like to use it. +``` + +.. column:: + +```` +```python +app.config.LOGGING = True +``` +```` + +## How does it work + +When enabled, the extension will create a `multoprocessing.Queue`. It will remove all handlers on the [default Sanic loggers](../../guide/best-practices/logging.md) and replace them with a [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler). When a message is logged, it will be pushed into the queue by the handler, and read by the background process to the log handlers that were originally in place. This means you can still configure logging as normal and it should "just work." + +## Configuration + +| Key | Type | Default | Description | +| ------------------------------------------------------------------------------------- | ------ | ------- | ------------------------------------------------------- | +| LOGGING | `bool` | `False` | Whether to enable this extension. | +| LOGGING_QUEUE_MAX_SIZE | `int` | `4096` | The max size of the queue before messages are rejected. | From cfb1630e07b34dea08cb23d0189914744adc7d23 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:35 +0200 Subject: [PATCH 202/698] New translations openapi.md (Japanese) --- guide/content/ja/plugins/sanic-ext/openapi.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/openapi.md diff --git a/guide/content/ja/plugins/sanic-ext/openapi.md b/guide/content/ja/plugins/sanic-ext/openapi.md new file mode 100644 index 0000000000..acf33139b1 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/openapi.md @@ -0,0 +1,11 @@ +--- +title: Sanic Extensions - OAS +--- + +# Openapi + +- Adding documentation with decorators +- Documenting CBV +- Using autodoc +- Rendering docs with redoc/swagger +- Validation From 6f85cbf4efeff018702e26b4f090e0dff78e6835 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:36 +0200 Subject: [PATCH 203/698] New translations openapi.md (Korean) --- guide/content/ko/plugins/sanic-ext/openapi.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/openapi.md diff --git a/guide/content/ko/plugins/sanic-ext/openapi.md b/guide/content/ko/plugins/sanic-ext/openapi.md new file mode 100644 index 0000000000..acf33139b1 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/openapi.md @@ -0,0 +1,11 @@ +--- +title: Sanic Extensions - OAS +--- + +# Openapi + +- Adding documentation with decorators +- Documenting CBV +- Using autodoc +- Rendering docs with redoc/swagger +- Validation From 261b9c410a5c2ea60ce3b58df67b27f694341733 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:37 +0200 Subject: [PATCH 204/698] New translations openapi.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/openapi.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/openapi.md diff --git a/guide/content/zh/plugins/sanic-ext/openapi.md b/guide/content/zh/plugins/sanic-ext/openapi.md new file mode 100644 index 0000000000..acf33139b1 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/openapi.md @@ -0,0 +1,11 @@ +--- +title: Sanic Extensions - OAS +--- + +# Openapi + +- Adding documentation with decorators +- Documenting CBV +- Using autodoc +- Rendering docs with redoc/swagger +- Validation From c457417172fc7f98ad58e8a7e6c0a6ea99563464 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:38 +0200 Subject: [PATCH 205/698] New translations advanced.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/advanced.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/openapi/advanced.md diff --git a/guide/content/ja/plugins/sanic-ext/openapi/advanced.md b/guide/content/ja/plugins/sanic-ext/openapi/advanced.md new file mode 100644 index 0000000000..b83b905741 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/openapi/advanced.md @@ -0,0 +1,13 @@ +--- +title: Sanic Extensions - Advanced OAS +--- + +# Advanced + +_Documentation in progress_ + +## CBV + +## Blueprints + +## Components From 78b43d2fea4fcd59668fca636b612a3a2602c6b3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:39 +0200 Subject: [PATCH 206/698] New translations advanced.md (Korean) --- .../ko/plugins/sanic-ext/openapi/advanced.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/openapi/advanced.md diff --git a/guide/content/ko/plugins/sanic-ext/openapi/advanced.md b/guide/content/ko/plugins/sanic-ext/openapi/advanced.md new file mode 100644 index 0000000000..b83b905741 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/openapi/advanced.md @@ -0,0 +1,13 @@ +--- +title: Sanic Extensions - Advanced OAS +--- + +# Advanced + +_Documentation in progress_ + +## CBV + +## Blueprints + +## Components From 5a28f4528196110c9d88851cdbfbb7f1324670d2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:40 +0200 Subject: [PATCH 207/698] New translations advanced.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/advanced.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/openapi/advanced.md diff --git a/guide/content/zh/plugins/sanic-ext/openapi/advanced.md b/guide/content/zh/plugins/sanic-ext/openapi/advanced.md new file mode 100644 index 0000000000..b83b905741 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/openapi/advanced.md @@ -0,0 +1,13 @@ +--- +title: Sanic Extensions - Advanced OAS +--- + +# Advanced + +_Documentation in progress_ + +## CBV + +## Blueprints + +## Components From 9c340fb93af710e03728f38b824c02278be258fd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:41 +0200 Subject: [PATCH 208/698] New translations autodoc.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/autodoc.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/openapi/autodoc.md diff --git a/guide/content/ja/plugins/sanic-ext/openapi/autodoc.md b/guide/content/ja/plugins/sanic-ext/openapi/autodoc.md new file mode 100644 index 0000000000..e5c962aced --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/openapi/autodoc.md @@ -0,0 +1,154 @@ +--- +title: Sanic Extensions - Auto-documentation +--- + +# Auto-documentation + +To make documenting endpoints easier, Sanic Extensions will use a function's docstring to populate your documentation. + +## Summary and description + +.. column:: + +``` +A function's docstring will be used to create the summary and description. As you can see from this example here, the docstring has been parsed to use the first line as the summary, and the remainder of the string as the description. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def handler(request, something: str): + """This is a simple foo handler + + It is helpful to know that you could also use **markdown** inside your + docstrings. + + - one + - two + - three""" + return text(">>>") +``` +```json +"paths": { + "/foo": { + "get": { + "summary": "This is a simple foo handler", + "description": "It is helpful to know that you could also use **markdown** inside your
docstrings.

- one
- two
- three", + "responses": { + "default": { + "description": "OK" + } + }, + "operationId": "get_handler" + } + } +} +``` +```` + +## Operation level YAML + +.. column:: + +``` +You can expand upon this by adding valid OpenAPI YAML to the docstring. Simply add a line that contains `openapi:`, followed by your YAML. + +The `---` shown in the example is *not* necessary. It is just there to help visually identify the YAML as a distinct section of the docstring. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def handler(request, something: str): + """This is a simple foo handler + + Now we will add some more details + + openapi: + --- + operationId: fooDots + tags: + - one + - two + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + required: false + schema: + type: integer + format: int32 + responses: + '200': + description: Just some dots + """ + return text("...") +``` +```json +"paths": { + "/foo": { + "get": { + "operationId": "fooDots", + "summary": "This is a simple foo handler", + "description": "Now we will add some more details", + "tags": [ + "one", + "two" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "How many items to return at one time (max 100)", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "Just some dots" + } + } + } + } +} +``` +```` + +.. note:: + +``` +When both YAML documentation and decorators are used, it is the content from the decorators that will take priority when generating the documentation. +``` + +## Excluding docstrings + +.. column:: + +``` +Sometimes a function may contain a docstring that is not meant to be consumed inside the documentation. + +**Option 1**: Globally turn off auto-documentation `app.config.OAS_AUTODOC = False` + +**Option 2**: Disable it for the single handler with the `@openapi.no_autodoc` decorator +``` + +.. column:: + +```` +```python +@app.get("/foo") +@openapi.no_autodoc +async def handler(request, something: str): + """This is a docstring about internal info only. Do not parse it. + """ + return text("...") +``` +```` From 32092eaac2503a20fcc2001ec0fd968a1bd8c23c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:42 +0200 Subject: [PATCH 209/698] New translations autodoc.md (Korean) --- .../ko/plugins/sanic-ext/openapi/autodoc.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/openapi/autodoc.md diff --git a/guide/content/ko/plugins/sanic-ext/openapi/autodoc.md b/guide/content/ko/plugins/sanic-ext/openapi/autodoc.md new file mode 100644 index 0000000000..e5c962aced --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/openapi/autodoc.md @@ -0,0 +1,154 @@ +--- +title: Sanic Extensions - Auto-documentation +--- + +# Auto-documentation + +To make documenting endpoints easier, Sanic Extensions will use a function's docstring to populate your documentation. + +## Summary and description + +.. column:: + +``` +A function's docstring will be used to create the summary and description. As you can see from this example here, the docstring has been parsed to use the first line as the summary, and the remainder of the string as the description. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def handler(request, something: str): + """This is a simple foo handler + + It is helpful to know that you could also use **markdown** inside your + docstrings. + + - one + - two + - three""" + return text(">>>") +``` +```json +"paths": { + "/foo": { + "get": { + "summary": "This is a simple foo handler", + "description": "It is helpful to know that you could also use **markdown** inside your
docstrings.

- one
- two
- three", + "responses": { + "default": { + "description": "OK" + } + }, + "operationId": "get_handler" + } + } +} +``` +```` + +## Operation level YAML + +.. column:: + +``` +You can expand upon this by adding valid OpenAPI YAML to the docstring. Simply add a line that contains `openapi:`, followed by your YAML. + +The `---` shown in the example is *not* necessary. It is just there to help visually identify the YAML as a distinct section of the docstring. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def handler(request, something: str): + """This is a simple foo handler + + Now we will add some more details + + openapi: + --- + operationId: fooDots + tags: + - one + - two + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + required: false + schema: + type: integer + format: int32 + responses: + '200': + description: Just some dots + """ + return text("...") +``` +```json +"paths": { + "/foo": { + "get": { + "operationId": "fooDots", + "summary": "This is a simple foo handler", + "description": "Now we will add some more details", + "tags": [ + "one", + "two" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "How many items to return at one time (max 100)", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "Just some dots" + } + } + } + } +} +``` +```` + +.. note:: + +``` +When both YAML documentation and decorators are used, it is the content from the decorators that will take priority when generating the documentation. +``` + +## Excluding docstrings + +.. column:: + +``` +Sometimes a function may contain a docstring that is not meant to be consumed inside the documentation. + +**Option 1**: Globally turn off auto-documentation `app.config.OAS_AUTODOC = False` + +**Option 2**: Disable it for the single handler with the `@openapi.no_autodoc` decorator +``` + +.. column:: + +```` +```python +@app.get("/foo") +@openapi.no_autodoc +async def handler(request, something: str): + """This is a docstring about internal info only. Do not parse it. + """ + return text("...") +``` +```` From c4e5f12f3b39fa44eca4ae3fe1d480ac98f6f1a9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:43 +0200 Subject: [PATCH 210/698] New translations autodoc.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/autodoc.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/openapi/autodoc.md diff --git a/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md new file mode 100644 index 0000000000..e5c962aced --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md @@ -0,0 +1,154 @@ +--- +title: Sanic Extensions - Auto-documentation +--- + +# Auto-documentation + +To make documenting endpoints easier, Sanic Extensions will use a function's docstring to populate your documentation. + +## Summary and description + +.. column:: + +``` +A function's docstring will be used to create the summary and description. As you can see from this example here, the docstring has been parsed to use the first line as the summary, and the remainder of the string as the description. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def handler(request, something: str): + """This is a simple foo handler + + It is helpful to know that you could also use **markdown** inside your + docstrings. + + - one + - two + - three""" + return text(">>>") +``` +```json +"paths": { + "/foo": { + "get": { + "summary": "This is a simple foo handler", + "description": "It is helpful to know that you could also use **markdown** inside your
docstrings.

- one
- two
- three", + "responses": { + "default": { + "description": "OK" + } + }, + "operationId": "get_handler" + } + } +} +``` +```` + +## Operation level YAML + +.. column:: + +``` +You can expand upon this by adding valid OpenAPI YAML to the docstring. Simply add a line that contains `openapi:`, followed by your YAML. + +The `---` shown in the example is *not* necessary. It is just there to help visually identify the YAML as a distinct section of the docstring. +``` + +.. column:: + +```` +```python +@app.get("/foo") +async def handler(request, something: str): + """This is a simple foo handler + + Now we will add some more details + + openapi: + --- + operationId: fooDots + tags: + - one + - two + parameters: + - name: limit + in: query + description: How many items to return at one time (max 100) + required: false + schema: + type: integer + format: int32 + responses: + '200': + description: Just some dots + """ + return text("...") +``` +```json +"paths": { + "/foo": { + "get": { + "operationId": "fooDots", + "summary": "This is a simple foo handler", + "description": "Now we will add some more details", + "tags": [ + "one", + "two" + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "description": "How many items to return at one time (max 100)", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "200": { + "description": "Just some dots" + } + } + } + } +} +``` +```` + +.. note:: + +``` +When both YAML documentation and decorators are used, it is the content from the decorators that will take priority when generating the documentation. +``` + +## Excluding docstrings + +.. column:: + +``` +Sometimes a function may contain a docstring that is not meant to be consumed inside the documentation. + +**Option 1**: Globally turn off auto-documentation `app.config.OAS_AUTODOC = False` + +**Option 2**: Disable it for the single handler with the `@openapi.no_autodoc` decorator +``` + +.. column:: + +```` +```python +@app.get("/foo") +@openapi.no_autodoc +async def handler(request, something: str): + """This is a docstring about internal info only. Do not parse it. + """ + return text("...") +``` +```` From 2c52ab22cbaefd02575414e2b3aaf90c12ab81ab Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:44 +0200 Subject: [PATCH 211/698] New translations basics.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/basics.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/openapi/basics.md diff --git a/guide/content/ja/plugins/sanic-ext/openapi/basics.md b/guide/content/ja/plugins/sanic-ext/openapi/basics.md new file mode 100644 index 0000000000..e461fa2c49 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/openapi/basics.md @@ -0,0 +1,84 @@ +--- +title: Sanic Extensions - Basic OAS +--- + +# Basics + +.. note:: + +``` +The OpenAPI implementation in Sanic Extensions is based upon the OAS3 implementation from [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi). In fact, Sanic Extensions is in a large way the successor to that project, which entered maintenance mode upon the release of Sanic Extensions. If you were previously using OAS3 with `sanic-openapi` you should have an easy path to upgrading to Sanic Extensions. Unfortunately, this project does *NOT* support the OAS2 specification. +``` + +.. column:: + +``` +Out of the box, Sanic Extensions provides automatically generated API documentation using the [v3.0 OpenAPI specification](https://swagger.io/specification/). There is nothing special that you need to do +``` + +.. column:: + +```` +```python +from sanic import Sanic + +app = Sanic("MyApp") + +# Add all of your views +``` +```` + +After doing this, you will now have beautiful documentation already generated for you based upon your existing application: + +- [http://localhost:8000/docs](http://localhost:8000/docs) +- [http://localhost:8000/docs/redoc](http://localhost:8000/docs/redoc) +- [http://localhost:8000/docs/swagger](http://localhost:8000/docs/swagger) + +Checkout the [section on configuration](../configuration.md) to learn about changing the routes for the docs. You can also turn off one of the two UIs, and customize which UI will be available on the `/docs` route. + +.. column:: + +``` +Using [Redoc](https://github.com/Redocly/redoc) + +![Redoc](/assets/images/sanic-ext-redoc.png) +``` + +.. column:: + +``` +or [Swagger UI](https://github.com/swagger-api/swagger-ui) + +![Swagger UI](/assets/images/sanic-ext-swagger.png) +``` + +## Changing specification metadata + +.. column:: + +``` +If you want to change any of the metada, you should use the `describe` method. + +In this example `dedent` is being used with the `description` argument to make multi-line strings a little cleaner. This is not necessary, you can pass any string value here. +``` + +.. column:: + +```` +```python +from textwrap import dedent + +app.ext.openapi.describe( + "Testing API", + version="1.2.3", + description=dedent( + """ + # Info + This is a description. It is a good place to add some _extra_ doccumentation. + + **MARKDOWN** is supported. + """ + ), +) +``` +```` From 6823e44fcac49e328365cd1fb0ff402115ed468e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:45 +0200 Subject: [PATCH 212/698] New translations basics.md (Korean) --- .../ko/plugins/sanic-ext/openapi/basics.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/openapi/basics.md diff --git a/guide/content/ko/plugins/sanic-ext/openapi/basics.md b/guide/content/ko/plugins/sanic-ext/openapi/basics.md new file mode 100644 index 0000000000..e461fa2c49 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/openapi/basics.md @@ -0,0 +1,84 @@ +--- +title: Sanic Extensions - Basic OAS +--- + +# Basics + +.. note:: + +``` +The OpenAPI implementation in Sanic Extensions is based upon the OAS3 implementation from [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi). In fact, Sanic Extensions is in a large way the successor to that project, which entered maintenance mode upon the release of Sanic Extensions. If you were previously using OAS3 with `sanic-openapi` you should have an easy path to upgrading to Sanic Extensions. Unfortunately, this project does *NOT* support the OAS2 specification. +``` + +.. column:: + +``` +Out of the box, Sanic Extensions provides automatically generated API documentation using the [v3.0 OpenAPI specification](https://swagger.io/specification/). There is nothing special that you need to do +``` + +.. column:: + +```` +```python +from sanic import Sanic + +app = Sanic("MyApp") + +# Add all of your views +``` +```` + +After doing this, you will now have beautiful documentation already generated for you based upon your existing application: + +- [http://localhost:8000/docs](http://localhost:8000/docs) +- [http://localhost:8000/docs/redoc](http://localhost:8000/docs/redoc) +- [http://localhost:8000/docs/swagger](http://localhost:8000/docs/swagger) + +Checkout the [section on configuration](../configuration.md) to learn about changing the routes for the docs. You can also turn off one of the two UIs, and customize which UI will be available on the `/docs` route. + +.. column:: + +``` +Using [Redoc](https://github.com/Redocly/redoc) + +![Redoc](/assets/images/sanic-ext-redoc.png) +``` + +.. column:: + +``` +or [Swagger UI](https://github.com/swagger-api/swagger-ui) + +![Swagger UI](/assets/images/sanic-ext-swagger.png) +``` + +## Changing specification metadata + +.. column:: + +``` +If you want to change any of the metada, you should use the `describe` method. + +In this example `dedent` is being used with the `description` argument to make multi-line strings a little cleaner. This is not necessary, you can pass any string value here. +``` + +.. column:: + +```` +```python +from textwrap import dedent + +app.ext.openapi.describe( + "Testing API", + version="1.2.3", + description=dedent( + """ + # Info + This is a description. It is a good place to add some _extra_ doccumentation. + + **MARKDOWN** is supported. + """ + ), +) +``` +```` From 28931a3fe6ba26e8042cfdf9eb4678a9e330ec9d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:46 +0200 Subject: [PATCH 213/698] New translations basics.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/basics.md | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/openapi/basics.md diff --git a/guide/content/zh/plugins/sanic-ext/openapi/basics.md b/guide/content/zh/plugins/sanic-ext/openapi/basics.md new file mode 100644 index 0000000000..e461fa2c49 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/openapi/basics.md @@ -0,0 +1,84 @@ +--- +title: Sanic Extensions - Basic OAS +--- + +# Basics + +.. note:: + +``` +The OpenAPI implementation in Sanic Extensions is based upon the OAS3 implementation from [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi). In fact, Sanic Extensions is in a large way the successor to that project, which entered maintenance mode upon the release of Sanic Extensions. If you were previously using OAS3 with `sanic-openapi` you should have an easy path to upgrading to Sanic Extensions. Unfortunately, this project does *NOT* support the OAS2 specification. +``` + +.. column:: + +``` +Out of the box, Sanic Extensions provides automatically generated API documentation using the [v3.0 OpenAPI specification](https://swagger.io/specification/). There is nothing special that you need to do +``` + +.. column:: + +```` +```python +from sanic import Sanic + +app = Sanic("MyApp") + +# Add all of your views +``` +```` + +After doing this, you will now have beautiful documentation already generated for you based upon your existing application: + +- [http://localhost:8000/docs](http://localhost:8000/docs) +- [http://localhost:8000/docs/redoc](http://localhost:8000/docs/redoc) +- [http://localhost:8000/docs/swagger](http://localhost:8000/docs/swagger) + +Checkout the [section on configuration](../configuration.md) to learn about changing the routes for the docs. You can also turn off one of the two UIs, and customize which UI will be available on the `/docs` route. + +.. column:: + +``` +Using [Redoc](https://github.com/Redocly/redoc) + +![Redoc](/assets/images/sanic-ext-redoc.png) +``` + +.. column:: + +``` +or [Swagger UI](https://github.com/swagger-api/swagger-ui) + +![Swagger UI](/assets/images/sanic-ext-swagger.png) +``` + +## Changing specification metadata + +.. column:: + +``` +If you want to change any of the metada, you should use the `describe` method. + +In this example `dedent` is being used with the `description` argument to make multi-line strings a little cleaner. This is not necessary, you can pass any string value here. +``` + +.. column:: + +```` +```python +from textwrap import dedent + +app.ext.openapi.describe( + "Testing API", + version="1.2.3", + description=dedent( + """ + # Info + This is a description. It is a good place to add some _extra_ doccumentation. + + **MARKDOWN** is supported. + """ + ), +) +``` +```` From d9b7c9b5d07d772513cc984ed4a9f05455eab568 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:47 +0200 Subject: [PATCH 214/698] New translations decorators.md (Japanese) --- .../plugins/sanic-ext/openapi/decorators.md | 520 ++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/openapi/decorators.md diff --git a/guide/content/ja/plugins/sanic-ext/openapi/decorators.md b/guide/content/ja/plugins/sanic-ext/openapi/decorators.md new file mode 100644 index 0000000000..63af9849ef --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/openapi/decorators.md @@ -0,0 +1,520 @@ +--- +title: Sanic Extensions - OAS Decorators +--- + +# Decorators + +The primary mechanism for adding content to your schema is by decorating your endpoints. If you have +used `sanic-openapi` in the past, this should be familiar to you. The decorators and their arguments match closely +the [OAS v3.0 specification](https://swagger.io/specification/). + +.. column:: + +``` +All of the examples show will wrap around a route definition. When you are creating these, you should make sure that +your Sanic route decorator (`@app.route`, `@app.get`, etc) is the outermost decorator. That is to say that you should +put that first and then one or more of the below decorators after. +``` + +.. column:: + +```` +```python +from sanic_ext import openapi + +@app.get("/path/to/") +@openapi.summary("This is a summary") +@openapi.description("This is a description") +async def handler(request, something: str): + ... +``` +```` + +.. column:: + +``` +You will also see a lot of the below examples reference a model object. For the sake of simplicity, the examples will +use `UserProfile` that will look like this. The point is that it can be any well-typed class. You could easily imagine +this being a `dataclass` or some other kind of model object. +``` + +.. column:: + +```` +```python +class UserProfile: + name: str + age: int + email: str +``` +```` + +## Definition decorator + +### `@openapi.definition` + +The `@openapi.definition` decorator allows you to define all parts of an operations on a path at once. It is an omnibums +decorator in that it has the same capabilities to create operation definitions as the rest of the decorators. Using +multiple field-specific decorators or a single decorator is a style choice for you the developer. + +The fields are purposely permissive in accepting multiple types to make it easiest for you to define your operation. + +**Arguments** + +| Field | Type | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `body` | **dict, RequestBody, _YourModel_** | +| `deprecated` | **bool** | +| `description` | **str** | +| `document` | **str, ExternalDocumentation** | +| `exclude` | **bool** | +| `operation` | **str** | +| `parameter` | **str, dict, Parameter, [str], [dict], [Parameter]** | +| `response` | **dict, Response, _YourModel_, [dict], [Response]** | +| `summary` | **str** | +| `tag` | **str, Tag, [str], [Tag]** | +| `secured` | **Dict[str, Any]** | + +**Examples** + +.. column:: + +```` +```python +@openapi.definition( + body=RequestBody(UserProfile, required=True), + summary="User profile update", + tag="one", + response=[Success, Response(Failure, status=400)], +) +``` +```` + +.. column:: + +_See below examples for more examples. Any of the values for the below decorators can be used in the corresponding +keyword argument._ + +## Field-specific decorators + +All the following decorators are based on `@openapi` + +### body + +**Arguments** + +| Field | Type | +| ----------- | ---------------------------------- | +| **content** | **_YourModel_, dict, RequestBody** | + +**Examples** + +.. column:: + +```` +```python +@openapi.body(UserProfile) +``` + +```python +@openapi.body({"application/json": UserProfile}) +``` + +```python +@openapi.body(RequestBody({"application/json": UserProfile})) +``` +```` + +.. column:: + +```` +```python +@openapi.body({"content": UserProfile}) +``` + +```python +@openapi.body(RequestBody(UserProfile)) +``` + +```python +@openapi.body({"application/json": {"description": ...}}) +``` +```` + +### deprecated + +**Arguments** + +_None_ + +**Examples** + +.. column:: + +```` +```python +@openapi.deprecated() +``` +```` + +.. column:: + +```` +```python +@openapi.deprecated +``` +```` + +### description + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `text` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.description( + """This is a **description**. + +## You can use `markdown` + +- And +- make +- lists. +""" +) +``` +```` + +.. column:: + +### document + +**Arguments** + +| Field | Type | +| ------------- | ------- | +| `url` | **str** | +| `description` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.document("http://example.com/docs") +``` +```` + +.. column:: + +```` +```python +@openapi.document(ExternalDocumentation("http://example.com/more")) +``` +```` + +### exclude + +Can be used on route definitions like all of the other decorators, or can be called on a Blueprint + +**Arguments** + +| Field | Type | Default | +| ------ | ------------- | -------- | +| `flag` | **bool** | **True** | +| `bp` | **Blueprint** | | + +**Examples** + +.. column:: + +```` +```python +@openapi.exclude() +``` +```` + +.. column:: + +```` +```python +openapi.exclude(bp=some_blueprint) +``` +```` + +### operation + +Sets the operation ID. + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `name` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.operation("doNothing") +``` +```` + +.. column:: + +**Arguments** + +| Field | Type | Default | +| ---------- | ----------------------------------------- | ----------- | +| `name` | **str** | | +| `schema` | _**type**_ | **str** | +| `location` | **"query", "header", "path" or "cookie"** | **"query"** | + +**Examples** + +.. column:: + +```` +```python +@openapi.parameter("thing") +``` + +```python +@openapi.parameter(parameter=Parameter("foobar", deprecated=True)) +``` +```` + +.. column:: + +```` +```python +@openapi.parameter("Authorization", str, "header") +``` + +```python +@openapi.parameter("thing", required=True, allowEmptyValue=False) +``` +```` + +### response + +**Arguments** + +If using a `Response` object, you should not pass any other arguments. + +| Field | Type | +| ------------- | ----------------------------- | +| `status` | **int** | +| `content` | **_type_, _YourModel_, dict** | +| `description` | **str** | +| `response` | **Response** | + +**Examples** + +.. column:: + +```` +```python +@openapi.response(200, str, "This is endpoint returns a string") +``` + +```python +@openapi.response(200, {"text/plain": str}, "...") +``` + +```python +@openapi.response(response=Response(UserProfile, description="...")) +``` + +```python +@openapi.response( + response=Response( + { + "application/json": UserProfile, + }, + description="...", + status=201, + ) +) +``` +```` + +.. column:: + +```` +```python +@openapi.response(200, UserProfile, "...") +``` + +```python +@openapi.response( + 200, + { + "application/json": UserProfile, + }, + "Description...", +) +``` +```` + +### summary + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `text` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.summary("This is an endpoint") +``` +```` + +.. column:: + +### tag + +**Arguments** + +| Field | Type | +| ------- | ------------ | +| `*args` | **str, Tag** | + +**Examples** + +.. column:: + +```` +```python +@openapi.tag("foo") +``` +```` + +.. column:: + +```` +```python +@openapi.tag("foo", Tag("bar")) +``` +```` + +### secured + +**Arguments** + +| Field | Type | +| ----------------- | --------------------------------------------------------------------------- | +| `*args, **kwargs` | **str, Dict[str, Any]** | + +**Examples** + +.. column:: + +```` +```python +@openapi.secured() +``` +```` + +.. column:: + +.. column:: + +```` +```python +@openapi.secured("foo") +``` +```` + +.. column:: + +```` +```python +@openapi.secured("token1", "token2") +``` +```` + +.. column:: + +```` +```python +@openapi.secured({"my_api_key": []}) +``` +```` + +.. column:: + +```` +```python +@openapi.secured(my_api_key=[]) +``` +```` + +Do not forget to use `add_security_scheme`. See [security](./security.md) for more details. +\`\` + +## Integration with Pydantic + +Pydantic models have the ability to [generate OpenAPI schema](https://pydantic-docs.helpmanual.io/usage/schema/). + +.. column:: + +``` +To take advantage of Pydantic model schema generation, pass the output in place of the schema. +``` + +.. column:: + +```` +```python +from sanic import Sanic, json +from sanic_ext import validate, openapi +from pydantic import BaseModel, Field + +@openapi.component +class Item(BaseModel): + name: str + description: str = None + price: float + tax: float = None + +class ItemList(BaseModel): + items: List[Item] + +app = Sanic("test") + +@app.get("/") +@openapi.definition( + body={ + "application/json": ItemList.schema( + ref_template="#/components/schemas/{model}" + ) + }, +) +async def get(request): + return json({}) +``` +```` + +.. note:: + +``` +It is important to set that `ref_template`. By default Pydantic will select a template that is not standard OAS. This will cause the schema to not be found when generating the final document. +``` + +_Added in v22.9_ From 06123716f8f99aaaf1e77d7c7c5aae8e86cff117 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:49 +0200 Subject: [PATCH 215/698] New translations decorators.md (Korean) --- .../plugins/sanic-ext/openapi/decorators.md | 520 ++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/openapi/decorators.md diff --git a/guide/content/ko/plugins/sanic-ext/openapi/decorators.md b/guide/content/ko/plugins/sanic-ext/openapi/decorators.md new file mode 100644 index 0000000000..63af9849ef --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/openapi/decorators.md @@ -0,0 +1,520 @@ +--- +title: Sanic Extensions - OAS Decorators +--- + +# Decorators + +The primary mechanism for adding content to your schema is by decorating your endpoints. If you have +used `sanic-openapi` in the past, this should be familiar to you. The decorators and their arguments match closely +the [OAS v3.0 specification](https://swagger.io/specification/). + +.. column:: + +``` +All of the examples show will wrap around a route definition. When you are creating these, you should make sure that +your Sanic route decorator (`@app.route`, `@app.get`, etc) is the outermost decorator. That is to say that you should +put that first and then one or more of the below decorators after. +``` + +.. column:: + +```` +```python +from sanic_ext import openapi + +@app.get("/path/to/") +@openapi.summary("This is a summary") +@openapi.description("This is a description") +async def handler(request, something: str): + ... +``` +```` + +.. column:: + +``` +You will also see a lot of the below examples reference a model object. For the sake of simplicity, the examples will +use `UserProfile` that will look like this. The point is that it can be any well-typed class. You could easily imagine +this being a `dataclass` or some other kind of model object. +``` + +.. column:: + +```` +```python +class UserProfile: + name: str + age: int + email: str +``` +```` + +## Definition decorator + +### `@openapi.definition` + +The `@openapi.definition` decorator allows you to define all parts of an operations on a path at once. It is an omnibums +decorator in that it has the same capabilities to create operation definitions as the rest of the decorators. Using +multiple field-specific decorators or a single decorator is a style choice for you the developer. + +The fields are purposely permissive in accepting multiple types to make it easiest for you to define your operation. + +**Arguments** + +| Field | Type | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `body` | **dict, RequestBody, _YourModel_** | +| `deprecated` | **bool** | +| `description` | **str** | +| `document` | **str, ExternalDocumentation** | +| `exclude` | **bool** | +| `operation` | **str** | +| `parameter` | **str, dict, Parameter, [str], [dict], [Parameter]** | +| `response` | **dict, Response, _YourModel_, [dict], [Response]** | +| `summary` | **str** | +| `tag` | **str, Tag, [str], [Tag]** | +| `secured` | **Dict[str, Any]** | + +**Examples** + +.. column:: + +```` +```python +@openapi.definition( + body=RequestBody(UserProfile, required=True), + summary="User profile update", + tag="one", + response=[Success, Response(Failure, status=400)], +) +``` +```` + +.. column:: + +_See below examples for more examples. Any of the values for the below decorators can be used in the corresponding +keyword argument._ + +## Field-specific decorators + +All the following decorators are based on `@openapi` + +### body + +**Arguments** + +| Field | Type | +| ----------- | ---------------------------------- | +| **content** | **_YourModel_, dict, RequestBody** | + +**Examples** + +.. column:: + +```` +```python +@openapi.body(UserProfile) +``` + +```python +@openapi.body({"application/json": UserProfile}) +``` + +```python +@openapi.body(RequestBody({"application/json": UserProfile})) +``` +```` + +.. column:: + +```` +```python +@openapi.body({"content": UserProfile}) +``` + +```python +@openapi.body(RequestBody(UserProfile)) +``` + +```python +@openapi.body({"application/json": {"description": ...}}) +``` +```` + +### deprecated + +**Arguments** + +_None_ + +**Examples** + +.. column:: + +```` +```python +@openapi.deprecated() +``` +```` + +.. column:: + +```` +```python +@openapi.deprecated +``` +```` + +### description + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `text` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.description( + """This is a **description**. + +## You can use `markdown` + +- And +- make +- lists. +""" +) +``` +```` + +.. column:: + +### document + +**Arguments** + +| Field | Type | +| ------------- | ------- | +| `url` | **str** | +| `description` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.document("http://example.com/docs") +``` +```` + +.. column:: + +```` +```python +@openapi.document(ExternalDocumentation("http://example.com/more")) +``` +```` + +### exclude + +Can be used on route definitions like all of the other decorators, or can be called on a Blueprint + +**Arguments** + +| Field | Type | Default | +| ------ | ------------- | -------- | +| `flag` | **bool** | **True** | +| `bp` | **Blueprint** | | + +**Examples** + +.. column:: + +```` +```python +@openapi.exclude() +``` +```` + +.. column:: + +```` +```python +openapi.exclude(bp=some_blueprint) +``` +```` + +### operation + +Sets the operation ID. + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `name` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.operation("doNothing") +``` +```` + +.. column:: + +**Arguments** + +| Field | Type | Default | +| ---------- | ----------------------------------------- | ----------- | +| `name` | **str** | | +| `schema` | _**type**_ | **str** | +| `location` | **"query", "header", "path" or "cookie"** | **"query"** | + +**Examples** + +.. column:: + +```` +```python +@openapi.parameter("thing") +``` + +```python +@openapi.parameter(parameter=Parameter("foobar", deprecated=True)) +``` +```` + +.. column:: + +```` +```python +@openapi.parameter("Authorization", str, "header") +``` + +```python +@openapi.parameter("thing", required=True, allowEmptyValue=False) +``` +```` + +### response + +**Arguments** + +If using a `Response` object, you should not pass any other arguments. + +| Field | Type | +| ------------- | ----------------------------- | +| `status` | **int** | +| `content` | **_type_, _YourModel_, dict** | +| `description` | **str** | +| `response` | **Response** | + +**Examples** + +.. column:: + +```` +```python +@openapi.response(200, str, "This is endpoint returns a string") +``` + +```python +@openapi.response(200, {"text/plain": str}, "...") +``` + +```python +@openapi.response(response=Response(UserProfile, description="...")) +``` + +```python +@openapi.response( + response=Response( + { + "application/json": UserProfile, + }, + description="...", + status=201, + ) +) +``` +```` + +.. column:: + +```` +```python +@openapi.response(200, UserProfile, "...") +``` + +```python +@openapi.response( + 200, + { + "application/json": UserProfile, + }, + "Description...", +) +``` +```` + +### summary + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `text` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.summary("This is an endpoint") +``` +```` + +.. column:: + +### tag + +**Arguments** + +| Field | Type | +| ------- | ------------ | +| `*args` | **str, Tag** | + +**Examples** + +.. column:: + +```` +```python +@openapi.tag("foo") +``` +```` + +.. column:: + +```` +```python +@openapi.tag("foo", Tag("bar")) +``` +```` + +### secured + +**Arguments** + +| Field | Type | +| ----------------- | --------------------------------------------------------------------------- | +| `*args, **kwargs` | **str, Dict[str, Any]** | + +**Examples** + +.. column:: + +```` +```python +@openapi.secured() +``` +```` + +.. column:: + +.. column:: + +```` +```python +@openapi.secured("foo") +``` +```` + +.. column:: + +```` +```python +@openapi.secured("token1", "token2") +``` +```` + +.. column:: + +```` +```python +@openapi.secured({"my_api_key": []}) +``` +```` + +.. column:: + +```` +```python +@openapi.secured(my_api_key=[]) +``` +```` + +Do not forget to use `add_security_scheme`. See [security](./security.md) for more details. +\`\` + +## Integration with Pydantic + +Pydantic models have the ability to [generate OpenAPI schema](https://pydantic-docs.helpmanual.io/usage/schema/). + +.. column:: + +``` +To take advantage of Pydantic model schema generation, pass the output in place of the schema. +``` + +.. column:: + +```` +```python +from sanic import Sanic, json +from sanic_ext import validate, openapi +from pydantic import BaseModel, Field + +@openapi.component +class Item(BaseModel): + name: str + description: str = None + price: float + tax: float = None + +class ItemList(BaseModel): + items: List[Item] + +app = Sanic("test") + +@app.get("/") +@openapi.definition( + body={ + "application/json": ItemList.schema( + ref_template="#/components/schemas/{model}" + ) + }, +) +async def get(request): + return json({}) +``` +```` + +.. note:: + +``` +It is important to set that `ref_template`. By default Pydantic will select a template that is not standard OAS. This will cause the schema to not be found when generating the final document. +``` + +_Added in v22.9_ From 3281151711bb591e56286815128e3d7d18acec02 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:50 +0200 Subject: [PATCH 216/698] New translations decorators.md (Chinese Simplified) --- .../plugins/sanic-ext/openapi/decorators.md | 520 ++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/openapi/decorators.md diff --git a/guide/content/zh/plugins/sanic-ext/openapi/decorators.md b/guide/content/zh/plugins/sanic-ext/openapi/decorators.md new file mode 100644 index 0000000000..63af9849ef --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/openapi/decorators.md @@ -0,0 +1,520 @@ +--- +title: Sanic Extensions - OAS Decorators +--- + +# Decorators + +The primary mechanism for adding content to your schema is by decorating your endpoints. If you have +used `sanic-openapi` in the past, this should be familiar to you. The decorators and their arguments match closely +the [OAS v3.0 specification](https://swagger.io/specification/). + +.. column:: + +``` +All of the examples show will wrap around a route definition. When you are creating these, you should make sure that +your Sanic route decorator (`@app.route`, `@app.get`, etc) is the outermost decorator. That is to say that you should +put that first and then one or more of the below decorators after. +``` + +.. column:: + +```` +```python +from sanic_ext import openapi + +@app.get("/path/to/") +@openapi.summary("This is a summary") +@openapi.description("This is a description") +async def handler(request, something: str): + ... +``` +```` + +.. column:: + +``` +You will also see a lot of the below examples reference a model object. For the sake of simplicity, the examples will +use `UserProfile` that will look like this. The point is that it can be any well-typed class. You could easily imagine +this being a `dataclass` or some other kind of model object. +``` + +.. column:: + +```` +```python +class UserProfile: + name: str + age: int + email: str +``` +```` + +## Definition decorator + +### `@openapi.definition` + +The `@openapi.definition` decorator allows you to define all parts of an operations on a path at once. It is an omnibums +decorator in that it has the same capabilities to create operation definitions as the rest of the decorators. Using +multiple field-specific decorators or a single decorator is a style choice for you the developer. + +The fields are purposely permissive in accepting multiple types to make it easiest for you to define your operation. + +**Arguments** + +| Field | Type | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `body` | **dict, RequestBody, _YourModel_** | +| `deprecated` | **bool** | +| `description` | **str** | +| `document` | **str, ExternalDocumentation** | +| `exclude` | **bool** | +| `operation` | **str** | +| `parameter` | **str, dict, Parameter, [str], [dict], [Parameter]** | +| `response` | **dict, Response, _YourModel_, [dict], [Response]** | +| `summary` | **str** | +| `tag` | **str, Tag, [str], [Tag]** | +| `secured` | **Dict[str, Any]** | + +**Examples** + +.. column:: + +```` +```python +@openapi.definition( + body=RequestBody(UserProfile, required=True), + summary="User profile update", + tag="one", + response=[Success, Response(Failure, status=400)], +) +``` +```` + +.. column:: + +_See below examples for more examples. Any of the values for the below decorators can be used in the corresponding +keyword argument._ + +## Field-specific decorators + +All the following decorators are based on `@openapi` + +### body + +**Arguments** + +| Field | Type | +| ----------- | ---------------------------------- | +| **content** | **_YourModel_, dict, RequestBody** | + +**Examples** + +.. column:: + +```` +```python +@openapi.body(UserProfile) +``` + +```python +@openapi.body({"application/json": UserProfile}) +``` + +```python +@openapi.body(RequestBody({"application/json": UserProfile})) +``` +```` + +.. column:: + +```` +```python +@openapi.body({"content": UserProfile}) +``` + +```python +@openapi.body(RequestBody(UserProfile)) +``` + +```python +@openapi.body({"application/json": {"description": ...}}) +``` +```` + +### deprecated + +**Arguments** + +_None_ + +**Examples** + +.. column:: + +```` +```python +@openapi.deprecated() +``` +```` + +.. column:: + +```` +```python +@openapi.deprecated +``` +```` + +### description + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `text` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.description( + """This is a **description**. + +## You can use `markdown` + +- And +- make +- lists. +""" +) +``` +```` + +.. column:: + +### document + +**Arguments** + +| Field | Type | +| ------------- | ------- | +| `url` | **str** | +| `description` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.document("http://example.com/docs") +``` +```` + +.. column:: + +```` +```python +@openapi.document(ExternalDocumentation("http://example.com/more")) +``` +```` + +### exclude + +Can be used on route definitions like all of the other decorators, or can be called on a Blueprint + +**Arguments** + +| Field | Type | Default | +| ------ | ------------- | -------- | +| `flag` | **bool** | **True** | +| `bp` | **Blueprint** | | + +**Examples** + +.. column:: + +```` +```python +@openapi.exclude() +``` +```` + +.. column:: + +```` +```python +openapi.exclude(bp=some_blueprint) +``` +```` + +### operation + +Sets the operation ID. + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `name` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.operation("doNothing") +``` +```` + +.. column:: + +**Arguments** + +| Field | Type | Default | +| ---------- | ----------------------------------------- | ----------- | +| `name` | **str** | | +| `schema` | _**type**_ | **str** | +| `location` | **"query", "header", "path" or "cookie"** | **"query"** | + +**Examples** + +.. column:: + +```` +```python +@openapi.parameter("thing") +``` + +```python +@openapi.parameter(parameter=Parameter("foobar", deprecated=True)) +``` +```` + +.. column:: + +```` +```python +@openapi.parameter("Authorization", str, "header") +``` + +```python +@openapi.parameter("thing", required=True, allowEmptyValue=False) +``` +```` + +### response + +**Arguments** + +If using a `Response` object, you should not pass any other arguments. + +| Field | Type | +| ------------- | ----------------------------- | +| `status` | **int** | +| `content` | **_type_, _YourModel_, dict** | +| `description` | **str** | +| `response` | **Response** | + +**Examples** + +.. column:: + +```` +```python +@openapi.response(200, str, "This is endpoint returns a string") +``` + +```python +@openapi.response(200, {"text/plain": str}, "...") +``` + +```python +@openapi.response(response=Response(UserProfile, description="...")) +``` + +```python +@openapi.response( + response=Response( + { + "application/json": UserProfile, + }, + description="...", + status=201, + ) +) +``` +```` + +.. column:: + +```` +```python +@openapi.response(200, UserProfile, "...") +``` + +```python +@openapi.response( + 200, + { + "application/json": UserProfile, + }, + "Description...", +) +``` +```` + +### summary + +**Arguments** + +| Field | Type | +| ------ | ------- | +| `text` | **str** | + +**Examples** + +.. column:: + +```` +```python +@openapi.summary("This is an endpoint") +``` +```` + +.. column:: + +### tag + +**Arguments** + +| Field | Type | +| ------- | ------------ | +| `*args` | **str, Tag** | + +**Examples** + +.. column:: + +```` +```python +@openapi.tag("foo") +``` +```` + +.. column:: + +```` +```python +@openapi.tag("foo", Tag("bar")) +``` +```` + +### secured + +**Arguments** + +| Field | Type | +| ----------------- | --------------------------------------------------------------------------- | +| `*args, **kwargs` | **str, Dict[str, Any]** | + +**Examples** + +.. column:: + +```` +```python +@openapi.secured() +``` +```` + +.. column:: + +.. column:: + +```` +```python +@openapi.secured("foo") +``` +```` + +.. column:: + +```` +```python +@openapi.secured("token1", "token2") +``` +```` + +.. column:: + +```` +```python +@openapi.secured({"my_api_key": []}) +``` +```` + +.. column:: + +```` +```python +@openapi.secured(my_api_key=[]) +``` +```` + +Do not forget to use `add_security_scheme`. See [security](./security.md) for more details. +\`\` + +## Integration with Pydantic + +Pydantic models have the ability to [generate OpenAPI schema](https://pydantic-docs.helpmanual.io/usage/schema/). + +.. column:: + +``` +To take advantage of Pydantic model schema generation, pass the output in place of the schema. +``` + +.. column:: + +```` +```python +from sanic import Sanic, json +from sanic_ext import validate, openapi +from pydantic import BaseModel, Field + +@openapi.component +class Item(BaseModel): + name: str + description: str = None + price: float + tax: float = None + +class ItemList(BaseModel): + items: List[Item] + +app = Sanic("test") + +@app.get("/") +@openapi.definition( + body={ + "application/json": ItemList.schema( + ref_template="#/components/schemas/{model}" + ) + }, +) +async def get(request): + return json({}) +``` +```` + +.. note:: + +``` +It is important to set that `ref_template`. By default Pydantic will select a template that is not standard OAS. This will cause the schema to not be found when generating the final document. +``` + +_Added in v22.9_ From e9a5bf209bf6ab73d1fd7f9aa01bc0d96c2bd4b3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:51 +0200 Subject: [PATCH 217/698] New translations security.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/security.md | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/openapi/security.md diff --git a/guide/content/ja/plugins/sanic-ext/openapi/security.md b/guide/content/ja/plugins/sanic-ext/openapi/security.md new file mode 100644 index 0000000000..416e794bf5 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/openapi/security.md @@ -0,0 +1,110 @@ +--- +title: Sanic Extensions - OAS Security Schemes +--- + +# Security Schemes + +To document authentication schemes, there are two steps. + +_Security is only available starting in v21.12.2_ + +## Document the scheme + +.. column:: + +```` +The first thing that you need to do is define one or more security schemes. The basic pattern will be to define it as: + +```python +add_security_scheme("", "") +``` + +The `type` should correspond to one of the allowed security schemes: `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. You can then pass appropriate keyword arguments as allowed by the specification. + +You should consult the [OpenAPI Specification](https://swagger.io/specification/) for details on what values are appropriate. +```` + +.. column:: + +```` +```python +app.ext.openapi.add_security_scheme("api_key", "apiKey") +app.ext.openapi.add_security_scheme( + "token", + "http", + scheme="bearer", + bearer_format="JWT", +) +app.ext.openapi.add_security_scheme("token2", "http") +app.ext.openapi.add_security_scheme( + "oldschool", + "http", + scheme="basic", +) +app.ext.openapi.add_security_scheme( + "oa2", + "oauth2", + flows={ + "implicit": { + "authorizationUrl": "http://example.com/auth", + "scopes": { + "on:two": "something", + "three:four": "something else", + "threefour": "something else...", + }, + } + }, +) +``` +```` + +## Document the endpoints + +.. column:: + +``` +There are two options, document _all_ endpoints. +``` + +.. column:: + +```` +```python +app.ext.openapi.secured() +app.ext.openapi.secured("token") +``` +```` + +.. column:: + +``` +Or, document only specific routes. +``` + +.. column:: + +```` +```python +@app.route("/one") +async def handler1(request): + """ + openapi: + --- + security: + - foo: [] + """ + +@app.route("/two") +@openapi.secured("foo") +@openapi.secured({"bar": []}) +@openapi.secured(baz=[]) +async def handler2(request): + ... + +@app.route("/three") +@openapi.definition(secured="foo") +@openapi.definition(secured={"bar": []}) +async def handler3(request): + ... +``` +```` From 66a197911cbf7dcab898001842022b3bdb4b5d0c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:52 +0200 Subject: [PATCH 218/698] New translations security.md (Korean) --- .../ko/plugins/sanic-ext/openapi/security.md | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/openapi/security.md diff --git a/guide/content/ko/plugins/sanic-ext/openapi/security.md b/guide/content/ko/plugins/sanic-ext/openapi/security.md new file mode 100644 index 0000000000..416e794bf5 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/openapi/security.md @@ -0,0 +1,110 @@ +--- +title: Sanic Extensions - OAS Security Schemes +--- + +# Security Schemes + +To document authentication schemes, there are two steps. + +_Security is only available starting in v21.12.2_ + +## Document the scheme + +.. column:: + +```` +The first thing that you need to do is define one or more security schemes. The basic pattern will be to define it as: + +```python +add_security_scheme("", "") +``` + +The `type` should correspond to one of the allowed security schemes: `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. You can then pass appropriate keyword arguments as allowed by the specification. + +You should consult the [OpenAPI Specification](https://swagger.io/specification/) for details on what values are appropriate. +```` + +.. column:: + +```` +```python +app.ext.openapi.add_security_scheme("api_key", "apiKey") +app.ext.openapi.add_security_scheme( + "token", + "http", + scheme="bearer", + bearer_format="JWT", +) +app.ext.openapi.add_security_scheme("token2", "http") +app.ext.openapi.add_security_scheme( + "oldschool", + "http", + scheme="basic", +) +app.ext.openapi.add_security_scheme( + "oa2", + "oauth2", + flows={ + "implicit": { + "authorizationUrl": "http://example.com/auth", + "scopes": { + "on:two": "something", + "three:four": "something else", + "threefour": "something else...", + }, + } + }, +) +``` +```` + +## Document the endpoints + +.. column:: + +``` +There are two options, document _all_ endpoints. +``` + +.. column:: + +```` +```python +app.ext.openapi.secured() +app.ext.openapi.secured("token") +``` +```` + +.. column:: + +``` +Or, document only specific routes. +``` + +.. column:: + +```` +```python +@app.route("/one") +async def handler1(request): + """ + openapi: + --- + security: + - foo: [] + """ + +@app.route("/two") +@openapi.secured("foo") +@openapi.secured({"bar": []}) +@openapi.secured(baz=[]) +async def handler2(request): + ... + +@app.route("/three") +@openapi.definition(secured="foo") +@openapi.definition(secured={"bar": []}) +async def handler3(request): + ... +``` +```` From 923ca39c199d3a5a5fbd541ad51fb0a248d6cd71 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:53 +0200 Subject: [PATCH 219/698] New translations security.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/security.md | 110 ++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/openapi/security.md diff --git a/guide/content/zh/plugins/sanic-ext/openapi/security.md b/guide/content/zh/plugins/sanic-ext/openapi/security.md new file mode 100644 index 0000000000..416e794bf5 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/openapi/security.md @@ -0,0 +1,110 @@ +--- +title: Sanic Extensions - OAS Security Schemes +--- + +# Security Schemes + +To document authentication schemes, there are two steps. + +_Security is only available starting in v21.12.2_ + +## Document the scheme + +.. column:: + +```` +The first thing that you need to do is define one or more security schemes. The basic pattern will be to define it as: + +```python +add_security_scheme("", "") +``` + +The `type` should correspond to one of the allowed security schemes: `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. You can then pass appropriate keyword arguments as allowed by the specification. + +You should consult the [OpenAPI Specification](https://swagger.io/specification/) for details on what values are appropriate. +```` + +.. column:: + +```` +```python +app.ext.openapi.add_security_scheme("api_key", "apiKey") +app.ext.openapi.add_security_scheme( + "token", + "http", + scheme="bearer", + bearer_format="JWT", +) +app.ext.openapi.add_security_scheme("token2", "http") +app.ext.openapi.add_security_scheme( + "oldschool", + "http", + scheme="basic", +) +app.ext.openapi.add_security_scheme( + "oa2", + "oauth2", + flows={ + "implicit": { + "authorizationUrl": "http://example.com/auth", + "scopes": { + "on:two": "something", + "three:four": "something else", + "threefour": "something else...", + }, + } + }, +) +``` +```` + +## Document the endpoints + +.. column:: + +``` +There are two options, document _all_ endpoints. +``` + +.. column:: + +```` +```python +app.ext.openapi.secured() +app.ext.openapi.secured("token") +``` +```` + +.. column:: + +``` +Or, document only specific routes. +``` + +.. column:: + +```` +```python +@app.route("/one") +async def handler1(request): + """ + openapi: + --- + security: + - foo: [] + """ + +@app.route("/two") +@openapi.secured("foo") +@openapi.secured({"bar": []}) +@openapi.secured(baz=[]) +async def handler2(request): + ... + +@app.route("/three") +@openapi.definition(secured="foo") +@openapi.definition(secured={"bar": []}) +async def handler3(request): + ... +``` +```` From a9475c74a2a16056ddd260dc375bc0872632c98e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:54 +0200 Subject: [PATCH 220/698] New translations ui.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/ui.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/openapi/ui.md diff --git a/guide/content/ja/plugins/sanic-ext/openapi/ui.md b/guide/content/ja/plugins/sanic-ext/openapi/ui.md new file mode 100644 index 0000000000..fd1f4182e6 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/openapi/ui.md @@ -0,0 +1,30 @@ +--- +title: Sanic Extensions - OAS UI +--- + +# UI + +Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice to use one, or both of them. Out of the box, the following endpoints are setup for you, with the bare `/docs` displaying Redoc. + +- `/docs` +- `/docs/openapi.json` +- `/docs/redoc` +- `/docs/swagger` +- `/docs/openapi-config` + +## Config options + +| **Key** | **Type** | **Default** | **Desctiption** | +| -------------------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `OAS_IGNORE_HEAD` | `bool` | `True` | Whether to display `HEAD` endpoints. | +| `OAS_IGNORE_OPTIONS` | `bool` | `True` | Whether to display `OPTIONS` endpoints. | +| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Redoc HTML | +| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Swagger HTML | +| `OAS_UI_DEFAULT` | `Optional[str]` | `"redoc"` | Can be set to `redoc` or `swagger`. Controls which UI to display on the base route. If set to `None`, then the base route will not be setup. | +| `OAS_UI_REDOC` | `bool` | `True` | Whether to enable Redoc UI. | +| `OAS_UI_SWAGGER` | `bool` | `True` | Whether to enable Swagger UI. | +| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | URI path to the OpenAPI config used by Swagger | +| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | URI path to the JSON document. | +| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | URI path to Redoc. | +| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI path to Swagger. | +| `OAS_URL_PREFIX` | `str` | `"/docs"` | URL prefix to use for the Blueprint for OpenAPI docs. | From e1eaeb6c448c2ea801e89b05ba830a3593c06ecb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:55 +0200 Subject: [PATCH 221/698] New translations ui.md (Korean) --- .../ko/plugins/sanic-ext/openapi/ui.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/openapi/ui.md diff --git a/guide/content/ko/plugins/sanic-ext/openapi/ui.md b/guide/content/ko/plugins/sanic-ext/openapi/ui.md new file mode 100644 index 0000000000..fd1f4182e6 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/openapi/ui.md @@ -0,0 +1,30 @@ +--- +title: Sanic Extensions - OAS UI +--- + +# UI + +Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice to use one, or both of them. Out of the box, the following endpoints are setup for you, with the bare `/docs` displaying Redoc. + +- `/docs` +- `/docs/openapi.json` +- `/docs/redoc` +- `/docs/swagger` +- `/docs/openapi-config` + +## Config options + +| **Key** | **Type** | **Default** | **Desctiption** | +| -------------------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `OAS_IGNORE_HEAD` | `bool` | `True` | Whether to display `HEAD` endpoints. | +| `OAS_IGNORE_OPTIONS` | `bool` | `True` | Whether to display `OPTIONS` endpoints. | +| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Redoc HTML | +| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Swagger HTML | +| `OAS_UI_DEFAULT` | `Optional[str]` | `"redoc"` | Can be set to `redoc` or `swagger`. Controls which UI to display on the base route. If set to `None`, then the base route will not be setup. | +| `OAS_UI_REDOC` | `bool` | `True` | Whether to enable Redoc UI. | +| `OAS_UI_SWAGGER` | `bool` | `True` | Whether to enable Swagger UI. | +| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | URI path to the OpenAPI config used by Swagger | +| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | URI path to the JSON document. | +| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | URI path to Redoc. | +| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI path to Swagger. | +| `OAS_URL_PREFIX` | `str` | `"/docs"` | URL prefix to use for the Blueprint for OpenAPI docs. | From 1984b98e485566b60d0bb05b10aaa4d2b5219b59 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:56 +0200 Subject: [PATCH 222/698] New translations ui.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/ui.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/openapi/ui.md diff --git a/guide/content/zh/plugins/sanic-ext/openapi/ui.md b/guide/content/zh/plugins/sanic-ext/openapi/ui.md new file mode 100644 index 0000000000..fd1f4182e6 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/openapi/ui.md @@ -0,0 +1,30 @@ +--- +title: Sanic Extensions - OAS UI +--- + +# UI + +Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice to use one, or both of them. Out of the box, the following endpoints are setup for you, with the bare `/docs` displaying Redoc. + +- `/docs` +- `/docs/openapi.json` +- `/docs/redoc` +- `/docs/swagger` +- `/docs/openapi-config` + +## Config options + +| **Key** | **Type** | **Default** | **Desctiption** | +| -------------------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `OAS_IGNORE_HEAD` | `bool` | `True` | Whether to display `HEAD` endpoints. | +| `OAS_IGNORE_OPTIONS` | `bool` | `True` | Whether to display `OPTIONS` endpoints. | +| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Redoc HTML | +| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Swagger HTML | +| `OAS_UI_DEFAULT` | `Optional[str]` | `"redoc"` | Can be set to `redoc` or `swagger`. Controls which UI to display on the base route. If set to `None`, then the base route will not be setup. | +| `OAS_UI_REDOC` | `bool` | `True` | Whether to enable Redoc UI. | +| `OAS_UI_SWAGGER` | `bool` | `True` | Whether to enable Swagger UI. | +| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | URI path to the OpenAPI config used by Swagger | +| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | URI path to the JSON document. | +| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | URI path to Redoc. | +| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI path to Swagger. | +| `OAS_URL_PREFIX` | `str` | `"/docs"` | URL prefix to use for the Blueprint for OpenAPI docs. | From 13aa211182c21cf2c694daeda0eee5d27dff4094 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:57 +0200 Subject: [PATCH 223/698] New translations html5tagger.md (Japanese) --- .../content/ja/plugins/sanic-ext/templating/html5tagger.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/templating/html5tagger.md diff --git a/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md b/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md new file mode 100644 index 0000000000..ab2c64ccdb --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md @@ -0,0 +1,7 @@ +--- +title: Sanic Extensions - html5tagger +--- + +# Coming soon + +See [GitHub])(https\://github.com/sanic-org/html5tagger/) From 752fb5af99bb0fa4b7dcd86768656d16050d5c7b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:58 +0200 Subject: [PATCH 224/698] New translations html5tagger.md (Korean) --- .../content/ko/plugins/sanic-ext/templating/html5tagger.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/templating/html5tagger.md diff --git a/guide/content/ko/plugins/sanic-ext/templating/html5tagger.md b/guide/content/ko/plugins/sanic-ext/templating/html5tagger.md new file mode 100644 index 0000000000..ab2c64ccdb --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/templating/html5tagger.md @@ -0,0 +1,7 @@ +--- +title: Sanic Extensions - html5tagger +--- + +# Coming soon + +See [GitHub])(https\://github.com/sanic-org/html5tagger/) From fe8ae428fd43ae7d92dafec017236377a0834f44 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:58 +0200 Subject: [PATCH 225/698] New translations html5tagger.md (Chinese Simplified) --- .../content/zh/plugins/sanic-ext/templating/html5tagger.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/templating/html5tagger.md diff --git a/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md b/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md new file mode 100644 index 0000000000..ab2c64ccdb --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md @@ -0,0 +1,7 @@ +--- +title: Sanic Extensions - html5tagger +--- + +# Coming soon + +See [GitHub])(https\://github.com/sanic-org/html5tagger/) From 56380a99289f29932b0b25e9cc4ed470255dee0c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:22:59 +0200 Subject: [PATCH 226/698] New translations jinja.md (Japanese) --- .../ja/plugins/sanic-ext/templating/jinja.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/templating/jinja.md diff --git a/guide/content/ja/plugins/sanic-ext/templating/jinja.md b/guide/content/ja/plugins/sanic-ext/templating/jinja.md new file mode 100644 index 0000000000..1f3cefbb22 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/templating/jinja.md @@ -0,0 +1,171 @@ +--- +title: Sanic Extensions - Jinja +--- + +# Templating + +Sanic Extensions can easily help you integrate templates into your route handlers. + +## Dependencies + +**Currently, we only support [Jinja](https://github.com/pallets/jinja/).** + +[Read the Jinja docs first](https://jinja.palletsprojects.com/en/3.1.x/) if you are unfamiliar with how to create templates. + +Sanic Extensions will automatically setup and load Jinja for you if it is installed in your environment. Therefore, the only setup that you need to do is install Jinja: + +``` +pip install Jinja2 +``` + +## Rendering a template from a file + +There are three (3) ways for you: + +1. Using a decorator to pre-load the template file +2. Returning a rendered `HTTPResponse` object +3. Hybrid pattern that creates a `LazyResponse` + +Let's imagine you have a file called `./templates/foo.html`: + +```html + + + + + My Webpage + + + +

Hello, world!!!!

+
    + {% for item in seq %} +
  • {{ item }}
    • + {% endfor %} +
+ + + +``` + +Let's see how you could render it with Sanic + Jinja. + +### Option 1 - as a decorator + +.. column:: + +``` +The benefit of this approach is that the templates can be predefined at startup time. This will mean that less fetching needs to happen in the handler, and should therefore be the fastest option. +``` + +.. column:: + +```` +```python +@app.get("/") +@app.ext.template("foo.html") +async def handler(request: Request): + return {"seq": ["one", "two"]} +``` +```` + +### Option 2 - as a return object + +.. column:: + +``` +This is meant to mimic the `text`, `json`, `html`, `file`, etc pattern of core Sanic. It will allow the most customization to the response object since it has direct control of it. Just like in other `HTTPResponse` objects, you can control headers, cookies, etc. +``` + +.. column:: + +```` +```python +from sanic_ext import render + +@app.get("/alt") +async def handler(request: Request): + return await render( + "foo.html", context={"seq": ["three", "four"]}, status=400 + ) +``` +```` + +### Option 3 - hybrid/lazy + +.. column:: + +``` +In this approach, the template is defined up front and not inside the handler (for performance). Then, the `render` function returns a `LazyResponse` that can be used to build a proper `HTTPResponse` inside the decorator. +``` + +.. column:: + +```` +```python +from sanic_ext import render + +@app.get("/") +@app.ext.template("foo.html") +async def handler(request: Request): + return await render(context={"seq": ["five", "six"]}, status=400) +``` +```` + +## Rendering a template from a string + +.. column:: + +``` +Sometimes you may want to write (or generate) your template inside of Python code and _not_ read it from an HTML file. In this case, you can still use the `render` function we saw above. Just use `template_source`. +``` + +.. column:: + +```` +```python +from sanic_ext import render +from textwrap import dedent + +@app.get("/") +async def handler(request): + template = dedent(""" + + + + + My Webpage + + + +

Hello, world!!!!

+
    + {% for item in seq %} +
  • {{ item }}
    • + {% endfor %} +
+ + + + """) + return await render( + template_source=template, + context={"seq": ["three", "four"]}, + app=app, + ) +``` +```` + +.. note:: + +``` +In this example, we use `textwrap.dedent` to remove the whitespace in the beginning of each line of the multi-line string. It is not necessary, but just a nice touch to keep both the code and the generated source clean. +``` + +## Development and auto-reload + +If auto-reload is turned on, then changes to your template files should trigger a reload of the server. + +## Configuration + +See `templating_enable_async` and `templating_path_to_templates` in [settings](./configuration.md#settings). From 6d0a1bf674f882c0691e5d908bbd7424376e2c12 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:00 +0200 Subject: [PATCH 227/698] New translations jinja.md (Korean) --- .../ko/plugins/sanic-ext/templating/jinja.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/templating/jinja.md diff --git a/guide/content/ko/plugins/sanic-ext/templating/jinja.md b/guide/content/ko/plugins/sanic-ext/templating/jinja.md new file mode 100644 index 0000000000..1f3cefbb22 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/templating/jinja.md @@ -0,0 +1,171 @@ +--- +title: Sanic Extensions - Jinja +--- + +# Templating + +Sanic Extensions can easily help you integrate templates into your route handlers. + +## Dependencies + +**Currently, we only support [Jinja](https://github.com/pallets/jinja/).** + +[Read the Jinja docs first](https://jinja.palletsprojects.com/en/3.1.x/) if you are unfamiliar with how to create templates. + +Sanic Extensions will automatically setup and load Jinja for you if it is installed in your environment. Therefore, the only setup that you need to do is install Jinja: + +``` +pip install Jinja2 +``` + +## Rendering a template from a file + +There are three (3) ways for you: + +1. Using a decorator to pre-load the template file +2. Returning a rendered `HTTPResponse` object +3. Hybrid pattern that creates a `LazyResponse` + +Let's imagine you have a file called `./templates/foo.html`: + +```html + + + + + My Webpage + + + +

Hello, world!!!!

+
    + {% for item in seq %} +
  • {{ item }}
    • + {% endfor %} +
+ + + +``` + +Let's see how you could render it with Sanic + Jinja. + +### Option 1 - as a decorator + +.. column:: + +``` +The benefit of this approach is that the templates can be predefined at startup time. This will mean that less fetching needs to happen in the handler, and should therefore be the fastest option. +``` + +.. column:: + +```` +```python +@app.get("/") +@app.ext.template("foo.html") +async def handler(request: Request): + return {"seq": ["one", "two"]} +``` +```` + +### Option 2 - as a return object + +.. column:: + +``` +This is meant to mimic the `text`, `json`, `html`, `file`, etc pattern of core Sanic. It will allow the most customization to the response object since it has direct control of it. Just like in other `HTTPResponse` objects, you can control headers, cookies, etc. +``` + +.. column:: + +```` +```python +from sanic_ext import render + +@app.get("/alt") +async def handler(request: Request): + return await render( + "foo.html", context={"seq": ["three", "four"]}, status=400 + ) +``` +```` + +### Option 3 - hybrid/lazy + +.. column:: + +``` +In this approach, the template is defined up front and not inside the handler (for performance). Then, the `render` function returns a `LazyResponse` that can be used to build a proper `HTTPResponse` inside the decorator. +``` + +.. column:: + +```` +```python +from sanic_ext import render + +@app.get("/") +@app.ext.template("foo.html") +async def handler(request: Request): + return await render(context={"seq": ["five", "six"]}, status=400) +``` +```` + +## Rendering a template from a string + +.. column:: + +``` +Sometimes you may want to write (or generate) your template inside of Python code and _not_ read it from an HTML file. In this case, you can still use the `render` function we saw above. Just use `template_source`. +``` + +.. column:: + +```` +```python +from sanic_ext import render +from textwrap import dedent + +@app.get("/") +async def handler(request): + template = dedent(""" + + + + + My Webpage + + + +

Hello, world!!!!

+
    + {% for item in seq %} +
  • {{ item }}
    • + {% endfor %} +
+ + + + """) + return await render( + template_source=template, + context={"seq": ["three", "four"]}, + app=app, + ) +``` +```` + +.. note:: + +``` +In this example, we use `textwrap.dedent` to remove the whitespace in the beginning of each line of the multi-line string. It is not necessary, but just a nice touch to keep both the code and the generated source clean. +``` + +## Development and auto-reload + +If auto-reload is turned on, then changes to your template files should trigger a reload of the server. + +## Configuration + +See `templating_enable_async` and `templating_path_to_templates` in [settings](./configuration.md#settings). From 87be42eef17314bc61c19636dfe38e6f5e8a9a80 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:01 +0200 Subject: [PATCH 228/698] New translations jinja.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/templating/jinja.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/templating/jinja.md diff --git a/guide/content/zh/plugins/sanic-ext/templating/jinja.md b/guide/content/zh/plugins/sanic-ext/templating/jinja.md new file mode 100644 index 0000000000..1f3cefbb22 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/templating/jinja.md @@ -0,0 +1,171 @@ +--- +title: Sanic Extensions - Jinja +--- + +# Templating + +Sanic Extensions can easily help you integrate templates into your route handlers. + +## Dependencies + +**Currently, we only support [Jinja](https://github.com/pallets/jinja/).** + +[Read the Jinja docs first](https://jinja.palletsprojects.com/en/3.1.x/) if you are unfamiliar with how to create templates. + +Sanic Extensions will automatically setup and load Jinja for you if it is installed in your environment. Therefore, the only setup that you need to do is install Jinja: + +``` +pip install Jinja2 +``` + +## Rendering a template from a file + +There are three (3) ways for you: + +1. Using a decorator to pre-load the template file +2. Returning a rendered `HTTPResponse` object +3. Hybrid pattern that creates a `LazyResponse` + +Let's imagine you have a file called `./templates/foo.html`: + +```html + + + + + My Webpage + + + +

Hello, world!!!!

+
    + {% for item in seq %} +
  • {{ item }}
    • + {% endfor %} +
+ + + +``` + +Let's see how you could render it with Sanic + Jinja. + +### Option 1 - as a decorator + +.. column:: + +``` +The benefit of this approach is that the templates can be predefined at startup time. This will mean that less fetching needs to happen in the handler, and should therefore be the fastest option. +``` + +.. column:: + +```` +```python +@app.get("/") +@app.ext.template("foo.html") +async def handler(request: Request): + return {"seq": ["one", "two"]} +``` +```` + +### Option 2 - as a return object + +.. column:: + +``` +This is meant to mimic the `text`, `json`, `html`, `file`, etc pattern of core Sanic. It will allow the most customization to the response object since it has direct control of it. Just like in other `HTTPResponse` objects, you can control headers, cookies, etc. +``` + +.. column:: + +```` +```python +from sanic_ext import render + +@app.get("/alt") +async def handler(request: Request): + return await render( + "foo.html", context={"seq": ["three", "four"]}, status=400 + ) +``` +```` + +### Option 3 - hybrid/lazy + +.. column:: + +``` +In this approach, the template is defined up front and not inside the handler (for performance). Then, the `render` function returns a `LazyResponse` that can be used to build a proper `HTTPResponse` inside the decorator. +``` + +.. column:: + +```` +```python +from sanic_ext import render + +@app.get("/") +@app.ext.template("foo.html") +async def handler(request: Request): + return await render(context={"seq": ["five", "six"]}, status=400) +``` +```` + +## Rendering a template from a string + +.. column:: + +``` +Sometimes you may want to write (or generate) your template inside of Python code and _not_ read it from an HTML file. In this case, you can still use the `render` function we saw above. Just use `template_source`. +``` + +.. column:: + +```` +```python +from sanic_ext import render +from textwrap import dedent + +@app.get("/") +async def handler(request): + template = dedent(""" + + + + + My Webpage + + + +

Hello, world!!!!

+
    + {% for item in seq %} +
  • {{ item }}
    • + {% endfor %} +
+ + + + """) + return await render( + template_source=template, + context={"seq": ["three", "four"]}, + app=app, + ) +``` +```` + +.. note:: + +``` +In this example, we use `textwrap.dedent` to remove the whitespace in the beginning of each line of the multi-line string. It is not necessary, but just a nice touch to keep both the code and the generated source clean. +``` + +## Development and auto-reload + +If auto-reload is turned on, then changes to your template files should trigger a reload of the server. + +## Configuration + +See `templating_enable_async` and `templating_path_to_templates` in [settings](./configuration.md#settings). From b6a7feb5919d077d1427007090e1af1a70c14018 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:02 +0200 Subject: [PATCH 229/698] New translations validation.md (Japanese) --- .../ja/plugins/sanic-ext/validation.md | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-ext/validation.md diff --git a/guide/content/ja/plugins/sanic-ext/validation.md b/guide/content/ja/plugins/sanic-ext/validation.md new file mode 100644 index 0000000000..504c931a88 --- /dev/null +++ b/guide/content/ja/plugins/sanic-ext/validation.md @@ -0,0 +1,201 @@ +--- +title: Sanic Extensions - Validation +--- + +# Validation + +One of the most commonly implemented features of a web application is user-input validation. For obvious reasons, this is not only a security issue, but also just plain good practice. You want to make sure your data conforms to expectations, and throw a `400` response when it does not. + +## Implementation + +### Validation with Dataclasses + +With the introduction of [Data Classes](https://docs.python.org/3/library/dataclasses.html), Python made it super simple to create objects that meet a defined schema. However, the standard library only supports type checking validation, **not** runtime validation. Sanic Extensions adds the ability to do runtime validations on incoming requests using `dataclasses` out of the box. If you also have either `pydantic` or `attrs` installed, you can alternatively use one of those libraries. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +@dataclass +class SearchParams: + q: str +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.route("/search") +@validate(query=SearchParams) +async def handler(request, query: SearchParams): + return json(asdict(query)) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/search +⚠️ 400 — Bad Request +==================== +Invalid request body: SearchParams. Error: missing a required argument: 'q' +``` +``` +$ curl localhost:8000/search\?q=python +{"q":"python"} +``` +```` + +### Validation with Pydantic + +You can use Pydantic models also. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +class Person(BaseModel): + name: str + age: int +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.post("/person") +@validate(json=Person) +async def handler(request, body: Person): + return json(body.dict()) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +{"name":"Alice","age":21} +``` +```` + +### Validation with Attrs + +You can use Attrs also. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +@attrs.define +class Person: + name: str + age: int + +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.post("/person") +@validate(json=Person) +async def handler(request, body: Person): + return json(attrs.asdict(body)) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +{"name":"Alice","age":21} +``` +```` + +## What can be validated? + +The `validate` decorator can be used to validate incoming user data from three places: JSON body data (`request.json`), form body data (`request.form`), and query parameters (`request.args`). + +.. column:: + +``` +As you might expect, you can attach your model using the keyword arguments of the decorator. +``` + +.. column:: + +```` +```python +@validate( + json=ModelA, + query=ModelB, + form=ModelC, +) +``` +```` From e30c787f45f38a601ccda3ccb20ca8ee1fa3a393 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:04 +0200 Subject: [PATCH 230/698] New translations validation.md (Korean) --- .../ko/plugins/sanic-ext/validation.md | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-ext/validation.md diff --git a/guide/content/ko/plugins/sanic-ext/validation.md b/guide/content/ko/plugins/sanic-ext/validation.md new file mode 100644 index 0000000000..504c931a88 --- /dev/null +++ b/guide/content/ko/plugins/sanic-ext/validation.md @@ -0,0 +1,201 @@ +--- +title: Sanic Extensions - Validation +--- + +# Validation + +One of the most commonly implemented features of a web application is user-input validation. For obvious reasons, this is not only a security issue, but also just plain good practice. You want to make sure your data conforms to expectations, and throw a `400` response when it does not. + +## Implementation + +### Validation with Dataclasses + +With the introduction of [Data Classes](https://docs.python.org/3/library/dataclasses.html), Python made it super simple to create objects that meet a defined schema. However, the standard library only supports type checking validation, **not** runtime validation. Sanic Extensions adds the ability to do runtime validations on incoming requests using `dataclasses` out of the box. If you also have either `pydantic` or `attrs` installed, you can alternatively use one of those libraries. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +@dataclass +class SearchParams: + q: str +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.route("/search") +@validate(query=SearchParams) +async def handler(request, query: SearchParams): + return json(asdict(query)) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/search +⚠️ 400 — Bad Request +==================== +Invalid request body: SearchParams. Error: missing a required argument: 'q' +``` +``` +$ curl localhost:8000/search\?q=python +{"q":"python"} +``` +```` + +### Validation with Pydantic + +You can use Pydantic models also. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +class Person(BaseModel): + name: str + age: int +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.post("/person") +@validate(json=Person) +async def handler(request, body: Person): + return json(body.dict()) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +{"name":"Alice","age":21} +``` +```` + +### Validation with Attrs + +You can use Attrs also. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +@attrs.define +class Person: + name: str + age: int + +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.post("/person") +@validate(json=Person) +async def handler(request, body: Person): + return json(attrs.asdict(body)) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +{"name":"Alice","age":21} +``` +```` + +## What can be validated? + +The `validate` decorator can be used to validate incoming user data from three places: JSON body data (`request.json`), form body data (`request.form`), and query parameters (`request.args`). + +.. column:: + +``` +As you might expect, you can attach your model using the keyword arguments of the decorator. +``` + +.. column:: + +```` +```python +@validate( + json=ModelA, + query=ModelB, + form=ModelC, +) +``` +```` From f3c1da10cc8ba1ca6a325b0c1a22bfbd5e9db31e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:05 +0200 Subject: [PATCH 231/698] New translations validation.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/validation.md | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-ext/validation.md diff --git a/guide/content/zh/plugins/sanic-ext/validation.md b/guide/content/zh/plugins/sanic-ext/validation.md new file mode 100644 index 0000000000..504c931a88 --- /dev/null +++ b/guide/content/zh/plugins/sanic-ext/validation.md @@ -0,0 +1,201 @@ +--- +title: Sanic Extensions - Validation +--- + +# Validation + +One of the most commonly implemented features of a web application is user-input validation. For obvious reasons, this is not only a security issue, but also just plain good practice. You want to make sure your data conforms to expectations, and throw a `400` response when it does not. + +## Implementation + +### Validation with Dataclasses + +With the introduction of [Data Classes](https://docs.python.org/3/library/dataclasses.html), Python made it super simple to create objects that meet a defined schema. However, the standard library only supports type checking validation, **not** runtime validation. Sanic Extensions adds the ability to do runtime validations on incoming requests using `dataclasses` out of the box. If you also have either `pydantic` or `attrs` installed, you can alternatively use one of those libraries. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +@dataclass +class SearchParams: + q: str +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.route("/search") +@validate(query=SearchParams) +async def handler(request, query: SearchParams): + return json(asdict(query)) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/search +⚠️ 400 — Bad Request +==================== +Invalid request body: SearchParams. Error: missing a required argument: 'q' +``` +``` +$ curl localhost:8000/search\?q=python +{"q":"python"} +``` +```` + +### Validation with Pydantic + +You can use Pydantic models also. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +class Person(BaseModel): + name: str + age: int +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.post("/person") +@validate(json=Person) +async def handler(request, body: Person): + return json(body.dict()) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +{"name":"Alice","age":21} +``` +```` + +### Validation with Attrs + +You can use Attrs also. + +.. column:: + +``` +First, define a model. +``` + +.. column:: + +```` +```python +@attrs.define +class Person: + name: str + age: int + +``` +```` + +.. column:: + +``` +Then, attach it to your route +``` + +.. column:: + +```` +```python +from sanic_ext import validate + +@app.post("/person") +@validate(json=Person) +async def handler(request, body: Person): + return json(attrs.asdict(body)) +``` +```` + +.. column:: + +``` +You should now have validation on the incoming request. +``` + +.. column:: + +```` +``` +$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +{"name":"Alice","age":21} +``` +```` + +## What can be validated? + +The `validate` decorator can be used to validate incoming user data from three places: JSON body data (`request.json`), form body data (`request.form`), and query parameters (`request.args`). + +.. column:: + +``` +As you might expect, you can attach your model using the keyword arguments of the decorator. +``` + +.. column:: + +```` +```python +@validate( + json=ModelA, + query=ModelB, + form=ModelC, +) +``` +```` From 40a8ea84f588b445f47fcba298c07c2c9174b1a0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:05 +0200 Subject: [PATCH 232/698] New translations clients.md (Japanese) --- .../ja/plugins/sanic-testing/clients.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-testing/clients.md diff --git a/guide/content/ja/plugins/sanic-testing/clients.md b/guide/content/ja/plugins/sanic-testing/clients.md new file mode 100644 index 0000000000..7dfa3ea8c7 --- /dev/null +++ b/guide/content/ja/plugins/sanic-testing/clients.md @@ -0,0 +1,152 @@ +--- +title: Sanic Testing - Test Clients +--- + +# Test Clients + +There are three different test clients available to you, each of them presents different capabilities. + +## Regular sync client: `SanicTestClient` + +The `SanicTestClient` runs an actual version of the Sanic Server on your local network to run its tests. Each time it calls an endpoint it will spin up a version of the application and bind it to a socket on the host OS. Then, it will use `httpx` to make calls directly to that application. + +This is the typical way that Sanic applications are tested. + +.. column:: + +``` +Once installing Sanic Testing, the regular `SanicTestClient` can be used without further setup. This is because Sanic does the leg work for you under the hood. +``` + +.. column:: + +```` +```python +app.test_client.get("/path/to/endpoint") +``` +```` + +.. column:: + +``` +However, you may find it desirable to instantiate the client yourself. +``` + +.. column:: + +```` +```python +from sanic_testing.testing import SanicTestClient + +test_client = SanicTestClient(app) +test_client.get("/path/to/endpoint") +``` +```` + +.. column:: + +``` +A third option for starting the test client is to use the `TestManager`. This is a convenience object that sets up both the `SanicTestClient` and the `SanicASGITestClient`. +``` + +.. column:: + +```` +```python +from sanic_testing import TestManager + +mgr = TestManager(app) +app.test_client.get("/path/to/endpoint") +# or +mgr.test_client.get("/path/to/endpoint") +``` +```` + +You can make a request by using one of the following methods + +- `SanicTestClient.get` +- `SanicTestClient.post` +- `SanicTestClient.put` +- `SanicTestClient.patch` +- `SanicTestClient.delete` +- `SanicTestClient.options` +- `SanicTestClient.head` +- `SanicTestClient.websocket` +- `SanicTestClient.request` + +You can use these methods _almost_ identically as you would when using `httpx`. Any argument that you would pass to `httpx` will be accepted, **with one caveat**: If you are using `test_client.request` and want to manually specify the HTTP method, you should use: `http_method`: + +```python +test_client.request("/path/to/endpoint", http_method="get") +``` + +## ASGI async client: `SanicASGITestClient` + +Unlike the `SanicTestClient` that spins up a server on every request, the `SanicASGITestClient` does not. Instead it makes use of the `httpx` library to execute Sanic as an ASGI application to reach inside and execute the route handlers. + +.. column:: + +``` +This test client provides all of the same methods and generally works as the `SanicTestClient`. The only difference is that you will need to add an `await` to each call: +``` + +.. column:: + +```` +```python +await app.test_client.get("/path/to/endpoint") +``` +```` + +The `SanicASGITestClient` can be used in the exact same three ways as the `SanicTestClient`. + +.. note:: + +``` +The `SanicASGITestClient` does not need to only be used with ASGI applications. The same way that the `SanicTestClient` does not need to only test sync endpoints. Both of these clients are capable of testing *any* Sanic application. +``` + +## Persistent service client: `ReusableClient` + +This client works under a similar premise as the `SanicTestClient` in that it stands up an instance of your application and makes real HTTP requests to it. However, unlike the `SanicTestClient`, when using the `ReusableClient` you control the lifecycle of the application. + +That means that every request **does not** start a new web server. Instead you will start the server and stop it as needed and can make multiple requests to the same running instance. + +.. column:: + +``` +Unlike the other two clients, you **must** instantiate this client for use: +``` + +.. column:: + +```` +```python +from sanic_testing.reusable import ReusableClient + +client = ReusableClient(app) +``` +```` + +.. column:: + +``` +Once created, you will use the client inside of a context manager. Once outside of the scope of the manager, the server will shutdown. +``` + +.. column:: + +```` +```python +from sanic_testing.reusable import ReusableClient + +def test_multiple_endpoints_on_same_server(app): + client = ReusableClient(app) + with client: + _, response = client.get("/path/to/1") + assert response.status == 200 + + _, response = client.get("/path/to/2") + assert response.status == 200 +``` +```` From 40b57d31c086d9d1b62675b68bfbd04fec2eb58e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:07 +0200 Subject: [PATCH 233/698] New translations clients.md (Korean) --- .../ko/plugins/sanic-testing/clients.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-testing/clients.md diff --git a/guide/content/ko/plugins/sanic-testing/clients.md b/guide/content/ko/plugins/sanic-testing/clients.md new file mode 100644 index 0000000000..7dfa3ea8c7 --- /dev/null +++ b/guide/content/ko/plugins/sanic-testing/clients.md @@ -0,0 +1,152 @@ +--- +title: Sanic Testing - Test Clients +--- + +# Test Clients + +There are three different test clients available to you, each of them presents different capabilities. + +## Regular sync client: `SanicTestClient` + +The `SanicTestClient` runs an actual version of the Sanic Server on your local network to run its tests. Each time it calls an endpoint it will spin up a version of the application and bind it to a socket on the host OS. Then, it will use `httpx` to make calls directly to that application. + +This is the typical way that Sanic applications are tested. + +.. column:: + +``` +Once installing Sanic Testing, the regular `SanicTestClient` can be used without further setup. This is because Sanic does the leg work for you under the hood. +``` + +.. column:: + +```` +```python +app.test_client.get("/path/to/endpoint") +``` +```` + +.. column:: + +``` +However, you may find it desirable to instantiate the client yourself. +``` + +.. column:: + +```` +```python +from sanic_testing.testing import SanicTestClient + +test_client = SanicTestClient(app) +test_client.get("/path/to/endpoint") +``` +```` + +.. column:: + +``` +A third option for starting the test client is to use the `TestManager`. This is a convenience object that sets up both the `SanicTestClient` and the `SanicASGITestClient`. +``` + +.. column:: + +```` +```python +from sanic_testing import TestManager + +mgr = TestManager(app) +app.test_client.get("/path/to/endpoint") +# or +mgr.test_client.get("/path/to/endpoint") +``` +```` + +You can make a request by using one of the following methods + +- `SanicTestClient.get` +- `SanicTestClient.post` +- `SanicTestClient.put` +- `SanicTestClient.patch` +- `SanicTestClient.delete` +- `SanicTestClient.options` +- `SanicTestClient.head` +- `SanicTestClient.websocket` +- `SanicTestClient.request` + +You can use these methods _almost_ identically as you would when using `httpx`. Any argument that you would pass to `httpx` will be accepted, **with one caveat**: If you are using `test_client.request` and want to manually specify the HTTP method, you should use: `http_method`: + +```python +test_client.request("/path/to/endpoint", http_method="get") +``` + +## ASGI async client: `SanicASGITestClient` + +Unlike the `SanicTestClient` that spins up a server on every request, the `SanicASGITestClient` does not. Instead it makes use of the `httpx` library to execute Sanic as an ASGI application to reach inside and execute the route handlers. + +.. column:: + +``` +This test client provides all of the same methods and generally works as the `SanicTestClient`. The only difference is that you will need to add an `await` to each call: +``` + +.. column:: + +```` +```python +await app.test_client.get("/path/to/endpoint") +``` +```` + +The `SanicASGITestClient` can be used in the exact same three ways as the `SanicTestClient`. + +.. note:: + +``` +The `SanicASGITestClient` does not need to only be used with ASGI applications. The same way that the `SanicTestClient` does not need to only test sync endpoints. Both of these clients are capable of testing *any* Sanic application. +``` + +## Persistent service client: `ReusableClient` + +This client works under a similar premise as the `SanicTestClient` in that it stands up an instance of your application and makes real HTTP requests to it. However, unlike the `SanicTestClient`, when using the `ReusableClient` you control the lifecycle of the application. + +That means that every request **does not** start a new web server. Instead you will start the server and stop it as needed and can make multiple requests to the same running instance. + +.. column:: + +``` +Unlike the other two clients, you **must** instantiate this client for use: +``` + +.. column:: + +```` +```python +from sanic_testing.reusable import ReusableClient + +client = ReusableClient(app) +``` +```` + +.. column:: + +``` +Once created, you will use the client inside of a context manager. Once outside of the scope of the manager, the server will shutdown. +``` + +.. column:: + +```` +```python +from sanic_testing.reusable import ReusableClient + +def test_multiple_endpoints_on_same_server(app): + client = ReusableClient(app) + with client: + _, response = client.get("/path/to/1") + assert response.status == 200 + + _, response = client.get("/path/to/2") + assert response.status == 200 +``` +```` From 424cf5bba2d2c7de11e1448bc8ad204992a85bf1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:08 +0200 Subject: [PATCH 234/698] New translations clients.md (Chinese Simplified) --- .../zh/plugins/sanic-testing/clients.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-testing/clients.md diff --git a/guide/content/zh/plugins/sanic-testing/clients.md b/guide/content/zh/plugins/sanic-testing/clients.md new file mode 100644 index 0000000000..7dfa3ea8c7 --- /dev/null +++ b/guide/content/zh/plugins/sanic-testing/clients.md @@ -0,0 +1,152 @@ +--- +title: Sanic Testing - Test Clients +--- + +# Test Clients + +There are three different test clients available to you, each of them presents different capabilities. + +## Regular sync client: `SanicTestClient` + +The `SanicTestClient` runs an actual version of the Sanic Server on your local network to run its tests. Each time it calls an endpoint it will spin up a version of the application and bind it to a socket on the host OS. Then, it will use `httpx` to make calls directly to that application. + +This is the typical way that Sanic applications are tested. + +.. column:: + +``` +Once installing Sanic Testing, the regular `SanicTestClient` can be used without further setup. This is because Sanic does the leg work for you under the hood. +``` + +.. column:: + +```` +```python +app.test_client.get("/path/to/endpoint") +``` +```` + +.. column:: + +``` +However, you may find it desirable to instantiate the client yourself. +``` + +.. column:: + +```` +```python +from sanic_testing.testing import SanicTestClient + +test_client = SanicTestClient(app) +test_client.get("/path/to/endpoint") +``` +```` + +.. column:: + +``` +A third option for starting the test client is to use the `TestManager`. This is a convenience object that sets up both the `SanicTestClient` and the `SanicASGITestClient`. +``` + +.. column:: + +```` +```python +from sanic_testing import TestManager + +mgr = TestManager(app) +app.test_client.get("/path/to/endpoint") +# or +mgr.test_client.get("/path/to/endpoint") +``` +```` + +You can make a request by using one of the following methods + +- `SanicTestClient.get` +- `SanicTestClient.post` +- `SanicTestClient.put` +- `SanicTestClient.patch` +- `SanicTestClient.delete` +- `SanicTestClient.options` +- `SanicTestClient.head` +- `SanicTestClient.websocket` +- `SanicTestClient.request` + +You can use these methods _almost_ identically as you would when using `httpx`. Any argument that you would pass to `httpx` will be accepted, **with one caveat**: If you are using `test_client.request` and want to manually specify the HTTP method, you should use: `http_method`: + +```python +test_client.request("/path/to/endpoint", http_method="get") +``` + +## ASGI async client: `SanicASGITestClient` + +Unlike the `SanicTestClient` that spins up a server on every request, the `SanicASGITestClient` does not. Instead it makes use of the `httpx` library to execute Sanic as an ASGI application to reach inside and execute the route handlers. + +.. column:: + +``` +This test client provides all of the same methods and generally works as the `SanicTestClient`. The only difference is that you will need to add an `await` to each call: +``` + +.. column:: + +```` +```python +await app.test_client.get("/path/to/endpoint") +``` +```` + +The `SanicASGITestClient` can be used in the exact same three ways as the `SanicTestClient`. + +.. note:: + +``` +The `SanicASGITestClient` does not need to only be used with ASGI applications. The same way that the `SanicTestClient` does not need to only test sync endpoints. Both of these clients are capable of testing *any* Sanic application. +``` + +## Persistent service client: `ReusableClient` + +This client works under a similar premise as the `SanicTestClient` in that it stands up an instance of your application and makes real HTTP requests to it. However, unlike the `SanicTestClient`, when using the `ReusableClient` you control the lifecycle of the application. + +That means that every request **does not** start a new web server. Instead you will start the server and stop it as needed and can make multiple requests to the same running instance. + +.. column:: + +``` +Unlike the other two clients, you **must** instantiate this client for use: +``` + +.. column:: + +```` +```python +from sanic_testing.reusable import ReusableClient + +client = ReusableClient(app) +``` +```` + +.. column:: + +``` +Once created, you will use the client inside of a context manager. Once outside of the scope of the manager, the server will shutdown. +``` + +.. column:: + +```` +```python +from sanic_testing.reusable import ReusableClient + +def test_multiple_endpoints_on_same_server(app): + client = ReusableClient(app) + with client: + _, response = client.get("/path/to/1") + assert response.status == 200 + + _, response = client.get("/path/to/2") + assert response.status == 200 +``` +```` From 29174db374e732f3d48cecd26dd92345d6e74a54 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:08 +0200 Subject: [PATCH 235/698] New translations getting-started.md (Japanese) --- .../plugins/sanic-testing/getting-started.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 guide/content/ja/plugins/sanic-testing/getting-started.md diff --git a/guide/content/ja/plugins/sanic-testing/getting-started.md b/guide/content/ja/plugins/sanic-testing/getting-started.md new file mode 100644 index 0000000000..5dcdb0e38f --- /dev/null +++ b/guide/content/ja/plugins/sanic-testing/getting-started.md @@ -0,0 +1,85 @@ +--- +title: Sanic Testing - Getting Started +--- + +# Getting Started + +Sanic Testing is the _official_ testing client for Sanic. Its primary use is to power the tests of the Sanic project itself. However, it is also meant as an easy-to-use client for getting your API tests up and running quickly. + +## Minimum requirements + +- **Python**: 3.7+ +- **Sanic**: 21.3+ + +Versions of Sanic older than 21.3 have this module integrated into Sanic itself as `sanic.testing`. + +## Install + +Sanic Testing can be installed from PyPI: + +``` +pip install sanic-testing +``` + +## Basic Usage + +As long as the `sanic-testing` package is in the environment, there is nothing you need to do to start using it. + +### Writing a sync test + +In order to use the test client, you just need to access the property `test_client` on your application instance: + +```python +import pytest +from sanic import Sanic, response + +@pytest.fixture +def app(): + sanic_app = Sanic("TestSanic") + + @sanic_app.get("/") + def basic(request): + return response.text("foo") + + return sanic_app + +def test_basic_test_client(app): + request, response = app.test_client.get("/") + + assert request.method.lower() == "get" + assert response.body == b"foo" + assert response.status == 200 +``` + +### Writing an async test + +In order to use the async test client in `pytest`, you should install the `pytest-asyncio` plugin. + +``` +pip install pytest-asyncio +``` + +You can then create an async test and use the ASGI client: + +```python +import pytest +from sanic import Sanic, response + +@pytest.fixture +def app(): + sanic_app = Sanic(__name__) + + @sanic_app.get("/") + def basic(request): + return response.text("foo") + + return sanic_app + +@pytest.mark.asyncio +async def test_basic_asgi_client(app): + request, response = await app.asgi_client.get("/") + + assert request.method.lower() == "get" + assert response.body == b"foo" + assert response.status == 200 +``` From fb5f558e77abf2b3a28452bc90ead06d4cefbf1a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:10 +0200 Subject: [PATCH 236/698] New translations getting-started.md (Korean) --- .../plugins/sanic-testing/getting-started.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 guide/content/ko/plugins/sanic-testing/getting-started.md diff --git a/guide/content/ko/plugins/sanic-testing/getting-started.md b/guide/content/ko/plugins/sanic-testing/getting-started.md new file mode 100644 index 0000000000..5dcdb0e38f --- /dev/null +++ b/guide/content/ko/plugins/sanic-testing/getting-started.md @@ -0,0 +1,85 @@ +--- +title: Sanic Testing - Getting Started +--- + +# Getting Started + +Sanic Testing is the _official_ testing client for Sanic. Its primary use is to power the tests of the Sanic project itself. However, it is also meant as an easy-to-use client for getting your API tests up and running quickly. + +## Minimum requirements + +- **Python**: 3.7+ +- **Sanic**: 21.3+ + +Versions of Sanic older than 21.3 have this module integrated into Sanic itself as `sanic.testing`. + +## Install + +Sanic Testing can be installed from PyPI: + +``` +pip install sanic-testing +``` + +## Basic Usage + +As long as the `sanic-testing` package is in the environment, there is nothing you need to do to start using it. + +### Writing a sync test + +In order to use the test client, you just need to access the property `test_client` on your application instance: + +```python +import pytest +from sanic import Sanic, response + +@pytest.fixture +def app(): + sanic_app = Sanic("TestSanic") + + @sanic_app.get("/") + def basic(request): + return response.text("foo") + + return sanic_app + +def test_basic_test_client(app): + request, response = app.test_client.get("/") + + assert request.method.lower() == "get" + assert response.body == b"foo" + assert response.status == 200 +``` + +### Writing an async test + +In order to use the async test client in `pytest`, you should install the `pytest-asyncio` plugin. + +``` +pip install pytest-asyncio +``` + +You can then create an async test and use the ASGI client: + +```python +import pytest +from sanic import Sanic, response + +@pytest.fixture +def app(): + sanic_app = Sanic(__name__) + + @sanic_app.get("/") + def basic(request): + return response.text("foo") + + return sanic_app + +@pytest.mark.asyncio +async def test_basic_asgi_client(app): + request, response = await app.asgi_client.get("/") + + assert request.method.lower() == "get" + assert response.body == b"foo" + assert response.status == 200 +``` From 0d8c74c60781e44dd7f70116b0ae88fa5ebc0434 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:11 +0200 Subject: [PATCH 237/698] New translations getting-started.md (Chinese Simplified) --- .../plugins/sanic-testing/getting-started.md | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 guide/content/zh/plugins/sanic-testing/getting-started.md diff --git a/guide/content/zh/plugins/sanic-testing/getting-started.md b/guide/content/zh/plugins/sanic-testing/getting-started.md new file mode 100644 index 0000000000..5dcdb0e38f --- /dev/null +++ b/guide/content/zh/plugins/sanic-testing/getting-started.md @@ -0,0 +1,85 @@ +--- +title: Sanic Testing - Getting Started +--- + +# Getting Started + +Sanic Testing is the _official_ testing client for Sanic. Its primary use is to power the tests of the Sanic project itself. However, it is also meant as an easy-to-use client for getting your API tests up and running quickly. + +## Minimum requirements + +- **Python**: 3.7+ +- **Sanic**: 21.3+ + +Versions of Sanic older than 21.3 have this module integrated into Sanic itself as `sanic.testing`. + +## Install + +Sanic Testing can be installed from PyPI: + +``` +pip install sanic-testing +``` + +## Basic Usage + +As long as the `sanic-testing` package is in the environment, there is nothing you need to do to start using it. + +### Writing a sync test + +In order to use the test client, you just need to access the property `test_client` on your application instance: + +```python +import pytest +from sanic import Sanic, response + +@pytest.fixture +def app(): + sanic_app = Sanic("TestSanic") + + @sanic_app.get("/") + def basic(request): + return response.text("foo") + + return sanic_app + +def test_basic_test_client(app): + request, response = app.test_client.get("/") + + assert request.method.lower() == "get" + assert response.body == b"foo" + assert response.status == 200 +``` + +### Writing an async test + +In order to use the async test client in `pytest`, you should install the `pytest-asyncio` plugin. + +``` +pip install pytest-asyncio +``` + +You can then create an async test and use the ASGI client: + +```python +import pytest +from sanic import Sanic, response + +@pytest.fixture +def app(): + sanic_app = Sanic(__name__) + + @sanic_app.get("/") + def basic(request): + return response.text("foo") + + return sanic_app + +@pytest.mark.asyncio +async def test_basic_asgi_client(app): + request, response = await app.asgi_client.get("/") + + assert request.method.lower() == "get" + assert response.body == b"foo" + assert response.status == 200 +``` From 6ee77f33fd7cb128d10462c1bde3346547a98642 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:12 +0200 Subject: [PATCH 238/698] New translations v21.12.md (Japanese) --- guide/content/ja/release-notes/2021/v21.12.md | 531 ++++++++++++++++++ 1 file changed, 531 insertions(+) create mode 100644 guide/content/ja/release-notes/2021/v21.12.md diff --git a/guide/content/ja/release-notes/2021/v21.12.md b/guide/content/ja/release-notes/2021/v21.12.md new file mode 100644 index 0000000000..2b80536a32 --- /dev/null +++ b/guide/content/ja/release-notes/2021/v21.12.md @@ -0,0 +1,531 @@ +--- +title: Version 21.12 (LTS) +--- + +# Version 21.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will now enter long-term support and will be supported for two years until December 2023. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Strict application and blueprint names + +In [v21.6](./v21.6.md#stricter-application-and-blueprint-names-and-deprecation) application and blueprint names were required to conform to a new set of restrictions. That change is now being enforced at startup time. + +Names **must**: + +1. Only use alphanumeric characters (`a-zA-Z0-9`) +2. May contain a hyphen (`-`) or an underscore (`_`) +3. Must begin with a letter or underscore (`a-zA-Z_`) + +### Strict application and blueprint properties + +The old leniency to allow directly setting properties of a `Sanic` or `Blueprint` object was deprecated and no longer allowed. You must use the `ctx` object. + +```python +app = Sanic("MyApp") +app.ctx.db = Database() +``` + +### Removals + +The following deprecated features no longer exist: + +- `sanic.exceptions.abort` +- `sanic.views.CompositionView` +- `sanic.response.StreamingHTTPResponse` + +### Upgrade your streaming responses (if not already) + +The `sanic.response.stream` response method has been **deprecated** and will be removed in v22.6. If you are sill using an old school streaming response, please upgrade it. + +**OLD - Deprecated** + +```python +async def sample_streaming_fn(response): + await response.write("foo,") + await response.write("bar") + +@app.route("/") +async def test(request: Request): + return stream(sample_streaming_fn, content_type="text/csv") +``` + +**Current** + +```python +async def sample_streaming_fn(response): + await response.write("foo,") + await response.write("bar") + +@app.route("/") +async def test(request: Request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") +``` + +### CLI overhaul and MOTD (Message of the Day) + +The Sanic CLI has received a fairly extensive upgrade. It adds a bunch of new features to make it on par with `app.run()`. It also includes a new MOTD display to provide quick, at-a-glance highlights about your running environment. The MOTD is TTY-aware, and therefore will be less verbose in server logs. It is mainly intended as a convenience during application development. + +``` +$ sanic --help +usage: sanic [-h] [--version] [--factory] [-s] [-H HOST] [-p PORT] [-u UNIX] [--cert CERT] [--key KEY] [--tls DIR] [--tls-strict-host] + [-w WORKERS | --fast] [--access-logs | --no-access-logs] [--debug] [-d] [-r] [-R PATH] [--motd | --no-motd] [-v] + [--noisy-exceptions | --no-noisy-exceptions] + module + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + + To start running a Sanic application, provide a path to the module, where + app is a Sanic() instance: + + $ sanic path.to.server:app + + Or, a path to a callable that returns a Sanic() instance: + + $ sanic path.to.factory:create_app --factory + + Or, a path to a directory to run as a simple HTTP server: + + $ sanic ./path/to/static --simple + +Required +======== + Positional: + module Path to your Sanic app. Example: path.to.server:app + If running a Simple Server, path to directory to serve. Example: ./ + +Optional +======== + General: + -h, --help show this help message and exit + --version show program's version number and exit + + Application: + --factory Treat app as an application factory, i.e. a () -> callable + -s, --simple Run Sanic as a Simple Server, and serve the contents of a directory + (module arg should be a path) + + Socket binding: + -H HOST, --host HOST Host address [default 127.0.0.1] + -p PORT, --port PORT Port to serve on [default 8000] + -u UNIX, --unix UNIX location of unix socket + + TLS certificate: + --cert CERT Location of fullchain.pem, bundle.crt or equivalent + --key KEY Location of privkey.pem or equivalent .key file + --tls DIR TLS certificate folder with fullchain.pem and privkey.pem + May be specified multiple times to choose multiple certificates + --tls-strict-host Only allow clients that send an SNI matching server certs + + Worker: + -w WORKERS, --workers WORKERS Number of worker processes [default 1] + --fast Set the number of workers to max allowed + --access-logs Display access logs + --no-access-logs No display access logs + + Development: + --debug Run the server in debug mode + -d, --dev Currently is an alias for --debug. But starting in v22.3, + --debug will no longer automatically trigger auto_restart. + However, --dev will continue, effectively making it the + same as debug + auto_reload. + -r, --reload, --auto-reload Watch source directory for file changes and reload on changes + -R PATH, --reload-dir PATH Extra directories to watch and reload on changes + + Output: + --motd Show the startup display + --no-motd No show the startup display + -v, --verbosity Control logging noise, eg. -vv or --verbosity=2 [default 0] + --noisy-exceptions Output stack traces for all exceptions + --no-noisy-exceptions No output stack traces for all exceptions +``` + +### Server running modes and changes coming to `debug` + +There are now two running modes: `DEV` and `PRODUCTION`. By default, Sanic server will run under `PRODUCTION` mode. This is intended for deployments. + +Currently, `DEV` mode will operate very similarly to how `debug=True` does in older Sanic versions. However, in v22.3. `debug=True` will **no longer** enable auto-reload. If you would like to have debugging and auto-reload, you should enable `DEV` mode. + +**DEVELOPMENT** + +``` +$ sanic server:app --dev +``` + +```python +app.run(debug=True, auto_reload=True) +``` + +**PRODUCTION** + +``` +$ sanic server:app +``` + +```python +app.run() +``` + +Beginning in v22.3, `PRODUCTION` mode will no longer enable access logs by default. + +A summary of the changes are as follows: + +| Flag | Mode | Tracebacks | Logging | Access logs | Reload | Max workers | +| ------- | ----- | ---------- | ------- | ----------- | ------ | ----------- | +| --debug | DEBUG | yes | DEBUG | yes | ^1 | | +| | PROD | no | INFO ^2 | ^3 | | | +| --dev | DEBUG | yes | DEBUG | yes | yes | | +| --fast | | | | | | yes | + +- ^1 `--debug` to deprecate auto-reloading and remove in 22.3 +- ^2 After 22.3 this moves to WARNING +- ^3 After 22.3: no + +### Max allowed workers + +You can easily spin up the maximum number of allowed workers using `--fast`. + +``` +$ sanic server:app --fast +``` + +```python +app.run(fast=True) +``` + +### First-class Sanic Extensions support + +[Sanic Extensions](../../plugins/sanic-ext/getting-started.md) provides a number of additional features specifically intended for API developers. You can now easily implement all of the functionality it has to offer without additional setup as long as the package is in the environment. These features include: + +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- CORS protection +- Predefined, endpoint-specific response serializers +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Request query arguments and body input validation + +The preferred method is to install it along with Sanic, but you can also install the packages on their own. + +.. column:: + +```` +``` +$ pip install sanic[ext] +``` +```` + +.. column:: + +```` +``` +$ pip install sanic sanic-ext +``` +```` + +After that, no additional configuration is required. Sanic Extensions will be attached to your application and provide all of the additional functionality with **no further configuration**. + +If you want to change how it works, or provide additional configuration, you can change Sanic extensions using `app.extend`. The following examples are equivalent. The `Config` object is to provide helpful type annotations for IDE development. + +.. column:: + +```` +```python +# This is optional, not required +app = Sanic("MyApp") +app.extend(config={"oas_url_prefix": "/apidocs"}) +``` +```` + +.. column:: + +```` +```python +# This is optional, not required +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` +```` + +.. column:: + +```` +```python +# This is optional, not required +from sanic_ext import Config + +app = Sanic("MyApp") +app.extend(config=Config(oas_url_prefix="/apidocs")) +``` +```` + +.. column:: + +### Contextual exceptions + +In [v21.9](./v21.9.md#default-exception-messages) we added default messages to exceptions that simplify the ability to consistently raise exceptions throughout your application. + +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +But this lacked two things: + +1. A dynamic and predictable message format +2. The ability to add additional context to an error message (more on this in a moment) + +The current release allows any Sanic exception to have additional information to when raised to provide context when writing an error message: + +```python +class TeapotError(SanicException): + status_code = 418 + + @property + def message(self): + return f"Sorry {self.extra['name']}, I cannot make you coffee" + +raise TeapotError(extra={"name": "Adam"}) +``` + +The new feature allows the passing of `extra` meta to the exception instance. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. + +.. column:: + +``` +**PRODUCTION** + +![image](https://user-images.githubusercontent.com/166269/139014161-cda67cd1-843f-4ad2-9fa1-acb94a59fc4d.png) +``` + +.. column:: + +``` +**DEVELOPMENT** + +![image](https://user-images.githubusercontent.com/166269/139014121-0596b084-b3c5-4adb-994e-31ba6eba6dad.png) +``` + +Getting back to item 2 from above: _The ability to add additional context to an error message_ + +This is particularly useful when creating microservices or an API that you intend to pass error messages back in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. + +```python +raise TeapotError(context={"foo": "bar"}) +``` + +This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: + +.. column:: + +```` +**PRODUCTION** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + } +} +``` +```` + +.. column:: + +```` +**DEVELOPMENT** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + }, + "extra": { + "name": "Adam", + "more": "lines", + "complex": { + "one": "two" + } + }, + "path": "/", + "args": {}, + "exceptions": [ + { + "type": "TeapotError", + "exception": "Sorry Adam, I cannot make you coffee", + "frames": [ + { + "file": "handle_request", + "line": 83, + "name": "handle_request", + "src": "" + }, + { + "file": "/tmp/p.py", + "line": 17, + "name": "handler", + "src": "raise TeapotError(" + } + ] + } + ] +} +``` +```` + +### Background task management + +When using the `app.add_task` method to create a background task, there now is the option to pass an optional `name` keyword argument that allows it to be fetched, or cancelled. + +```python +app.add_task(dummy, name="dummy_task") +task = app.get_task("dummy_task") + +app.cancel_task("dummy_task") +``` + +### Route context kwargs in definitions + +When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. + +```python +@app.get("/1", ctx_label="something") +async def handler1(request): + ... + +@app.get("/2", ctx_label="something") +async def handler2(request): + ... + +@app.get("/99") +async def handler99(request): + ... + +@app.on_request +async def do_something(request): + if request.route.ctx.label == "something": + ... +``` + +### Blueprints can be registered at any time + +In previous versions of Sanic, there was a strict ordering of when a Blueprint could be attached to an application. If you ran `app.blueprint(bp)` _before_ attaching all objects to the Blueprint instance, they would be missed. + +Now, you can attach a Blueprint at anytime and everything attached to it will be included at startup. + +### Noisy exceptions (force all exceptions to logs) + +There is a new `NOISY_EXCEPTIONS` config value. When it is `False` (which is the default), Sanic will respect the `quiet` property of any `SanicException`. This means that an exception with `quiet=True` will not be displayed to the log output. + +However, when setting `NOISY_EXCEPTIONS=True`, all exceptions will be logged regardless of the `quiet` value. + +This can be helpful when debugging. + +```python +app.config.NOISY_EXCEPTIONS = True +``` + +### Signal events as `Enum` + +There is an `Enum` with all of the built-in signal values for convenience. + +```python +from sanic.signals import Event + +@app.signal(Event.HTTP_LIFECYCLE_BEGIN) +async def connection_opened(conn_info): + ... +``` + +### Custom type casting of environment variables + +By default, Sanic will convert an `int`, `float`, or a `bool` value when applying environment variables to the `config` instance. You can extend this with your own converter: + +```python +app = Sanic(..., config=Config(converters=[UUID])) +``` + +### Disable `uvloop` by configuration value + +The usage of `uvloop` can be controlled by configuration value: + +```python +app.config.USE_UVLOOP = False +``` + +### Run Sanic server with multiple TLS certificates + +Sanic can be run with multiple TLS certificates: + +```python +app.run( + ssl=[ + "/etc/letsencrypt/live/example.com/", + "/etc/letsencrypt/live/mysite.example/", + ] +) +``` + +## News + +### Coming Soon: Python Web Development with Sanic + +A book about Sanic is coming soon by one of the core developers, [@ahopkins](https://github.com/ahopkins). + +Learn more at [sanicbook.com](https://sanicbook.com). + +> Get equipped with the practical knowledge of working with Sanic to increase the performance and scalability of your web applications. While doing that, we will level-up your development skills as you learn to customize your application to meet the changing business needs without having to significantly over-engineer the app. + +A portion of book proceeds goes into the Sanic Community Organization to help fund the development and operation of Sanic. So, buying the book is another way you can support Sanic. + +### Dark mode for the docs + +If you have not already noticed, this Sanic website is now available in a native dark mode. You can toggle the theme at the top right of the page. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@adarsharegmi](https://github.com/adarsharegmi) +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@cnicodeme](https://github.com/cnicodeme) +[@kianmeng](https://github.com/kianmeng) +[@meysam81](https://github.com/meysam81) +[@nuxion](https://github.com/nuxion) +[@prryplatypus](https://github.com/prryplatypus) +[@realDragonium](https://github.com/realDragonium) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@Tronic](https://github.com/tronic) +[@Varriount](https://github.com/Varriount) +[@vltr](https://github.com/vltr) +[@whos4n3](https://github.com/whos4n3) + +And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From ac619d1867fa38973709877b27026364ba371321 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:13 +0200 Subject: [PATCH 239/698] New translations v21.12.md (Korean) --- guide/content/ko/release-notes/2021/v21.12.md | 531 ++++++++++++++++++ 1 file changed, 531 insertions(+) create mode 100644 guide/content/ko/release-notes/2021/v21.12.md diff --git a/guide/content/ko/release-notes/2021/v21.12.md b/guide/content/ko/release-notes/2021/v21.12.md new file mode 100644 index 0000000000..2b80536a32 --- /dev/null +++ b/guide/content/ko/release-notes/2021/v21.12.md @@ -0,0 +1,531 @@ +--- +title: Version 21.12 (LTS) +--- + +# Version 21.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will now enter long-term support and will be supported for two years until December 2023. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Strict application and blueprint names + +In [v21.6](./v21.6.md#stricter-application-and-blueprint-names-and-deprecation) application and blueprint names were required to conform to a new set of restrictions. That change is now being enforced at startup time. + +Names **must**: + +1. Only use alphanumeric characters (`a-zA-Z0-9`) +2. May contain a hyphen (`-`) or an underscore (`_`) +3. Must begin with a letter or underscore (`a-zA-Z_`) + +### Strict application and blueprint properties + +The old leniency to allow directly setting properties of a `Sanic` or `Blueprint` object was deprecated and no longer allowed. You must use the `ctx` object. + +```python +app = Sanic("MyApp") +app.ctx.db = Database() +``` + +### Removals + +The following deprecated features no longer exist: + +- `sanic.exceptions.abort` +- `sanic.views.CompositionView` +- `sanic.response.StreamingHTTPResponse` + +### Upgrade your streaming responses (if not already) + +The `sanic.response.stream` response method has been **deprecated** and will be removed in v22.6. If you are sill using an old school streaming response, please upgrade it. + +**OLD - Deprecated** + +```python +async def sample_streaming_fn(response): + await response.write("foo,") + await response.write("bar") + +@app.route("/") +async def test(request: Request): + return stream(sample_streaming_fn, content_type="text/csv") +``` + +**Current** + +```python +async def sample_streaming_fn(response): + await response.write("foo,") + await response.write("bar") + +@app.route("/") +async def test(request: Request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") +``` + +### CLI overhaul and MOTD (Message of the Day) + +The Sanic CLI has received a fairly extensive upgrade. It adds a bunch of new features to make it on par with `app.run()`. It also includes a new MOTD display to provide quick, at-a-glance highlights about your running environment. The MOTD is TTY-aware, and therefore will be less verbose in server logs. It is mainly intended as a convenience during application development. + +``` +$ sanic --help +usage: sanic [-h] [--version] [--factory] [-s] [-H HOST] [-p PORT] [-u UNIX] [--cert CERT] [--key KEY] [--tls DIR] [--tls-strict-host] + [-w WORKERS | --fast] [--access-logs | --no-access-logs] [--debug] [-d] [-r] [-R PATH] [--motd | --no-motd] [-v] + [--noisy-exceptions | --no-noisy-exceptions] + module + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + + To start running a Sanic application, provide a path to the module, where + app is a Sanic() instance: + + $ sanic path.to.server:app + + Or, a path to a callable that returns a Sanic() instance: + + $ sanic path.to.factory:create_app --factory + + Or, a path to a directory to run as a simple HTTP server: + + $ sanic ./path/to/static --simple + +Required +======== + Positional: + module Path to your Sanic app. Example: path.to.server:app + If running a Simple Server, path to directory to serve. Example: ./ + +Optional +======== + General: + -h, --help show this help message and exit + --version show program's version number and exit + + Application: + --factory Treat app as an application factory, i.e. a () -> callable + -s, --simple Run Sanic as a Simple Server, and serve the contents of a directory + (module arg should be a path) + + Socket binding: + -H HOST, --host HOST Host address [default 127.0.0.1] + -p PORT, --port PORT Port to serve on [default 8000] + -u UNIX, --unix UNIX location of unix socket + + TLS certificate: + --cert CERT Location of fullchain.pem, bundle.crt or equivalent + --key KEY Location of privkey.pem or equivalent .key file + --tls DIR TLS certificate folder with fullchain.pem and privkey.pem + May be specified multiple times to choose multiple certificates + --tls-strict-host Only allow clients that send an SNI matching server certs + + Worker: + -w WORKERS, --workers WORKERS Number of worker processes [default 1] + --fast Set the number of workers to max allowed + --access-logs Display access logs + --no-access-logs No display access logs + + Development: + --debug Run the server in debug mode + -d, --dev Currently is an alias for --debug. But starting in v22.3, + --debug will no longer automatically trigger auto_restart. + However, --dev will continue, effectively making it the + same as debug + auto_reload. + -r, --reload, --auto-reload Watch source directory for file changes and reload on changes + -R PATH, --reload-dir PATH Extra directories to watch and reload on changes + + Output: + --motd Show the startup display + --no-motd No show the startup display + -v, --verbosity Control logging noise, eg. -vv or --verbosity=2 [default 0] + --noisy-exceptions Output stack traces for all exceptions + --no-noisy-exceptions No output stack traces for all exceptions +``` + +### Server running modes and changes coming to `debug` + +There are now two running modes: `DEV` and `PRODUCTION`. By default, Sanic server will run under `PRODUCTION` mode. This is intended for deployments. + +Currently, `DEV` mode will operate very similarly to how `debug=True` does in older Sanic versions. However, in v22.3. `debug=True` will **no longer** enable auto-reload. If you would like to have debugging and auto-reload, you should enable `DEV` mode. + +**DEVELOPMENT** + +``` +$ sanic server:app --dev +``` + +```python +app.run(debug=True, auto_reload=True) +``` + +**PRODUCTION** + +``` +$ sanic server:app +``` + +```python +app.run() +``` + +Beginning in v22.3, `PRODUCTION` mode will no longer enable access logs by default. + +A summary of the changes are as follows: + +| Flag | Mode | Tracebacks | Logging | Access logs | Reload | Max workers | +| ------- | ----- | ---------- | ------- | ----------- | ------ | ----------- | +| --debug | DEBUG | yes | DEBUG | yes | ^1 | | +| | PROD | no | INFO ^2 | ^3 | | | +| --dev | DEBUG | yes | DEBUG | yes | yes | | +| --fast | | | | | | yes | + +- ^1 `--debug` to deprecate auto-reloading and remove in 22.3 +- ^2 After 22.3 this moves to WARNING +- ^3 After 22.3: no + +### Max allowed workers + +You can easily spin up the maximum number of allowed workers using `--fast`. + +``` +$ sanic server:app --fast +``` + +```python +app.run(fast=True) +``` + +### First-class Sanic Extensions support + +[Sanic Extensions](../../plugins/sanic-ext/getting-started.md) provides a number of additional features specifically intended for API developers. You can now easily implement all of the functionality it has to offer without additional setup as long as the package is in the environment. These features include: + +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- CORS protection +- Predefined, endpoint-specific response serializers +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Request query arguments and body input validation + +The preferred method is to install it along with Sanic, but you can also install the packages on their own. + +.. column:: + +```` +``` +$ pip install sanic[ext] +``` +```` + +.. column:: + +```` +``` +$ pip install sanic sanic-ext +``` +```` + +After that, no additional configuration is required. Sanic Extensions will be attached to your application and provide all of the additional functionality with **no further configuration**. + +If you want to change how it works, or provide additional configuration, you can change Sanic extensions using `app.extend`. The following examples are equivalent. The `Config` object is to provide helpful type annotations for IDE development. + +.. column:: + +```` +```python +# This is optional, not required +app = Sanic("MyApp") +app.extend(config={"oas_url_prefix": "/apidocs"}) +``` +```` + +.. column:: + +```` +```python +# This is optional, not required +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` +```` + +.. column:: + +```` +```python +# This is optional, not required +from sanic_ext import Config + +app = Sanic("MyApp") +app.extend(config=Config(oas_url_prefix="/apidocs")) +``` +```` + +.. column:: + +### Contextual exceptions + +In [v21.9](./v21.9.md#default-exception-messages) we added default messages to exceptions that simplify the ability to consistently raise exceptions throughout your application. + +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +But this lacked two things: + +1. A dynamic and predictable message format +2. The ability to add additional context to an error message (more on this in a moment) + +The current release allows any Sanic exception to have additional information to when raised to provide context when writing an error message: + +```python +class TeapotError(SanicException): + status_code = 418 + + @property + def message(self): + return f"Sorry {self.extra['name']}, I cannot make you coffee" + +raise TeapotError(extra={"name": "Adam"}) +``` + +The new feature allows the passing of `extra` meta to the exception instance. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. + +.. column:: + +``` +**PRODUCTION** + +![image](https://user-images.githubusercontent.com/166269/139014161-cda67cd1-843f-4ad2-9fa1-acb94a59fc4d.png) +``` + +.. column:: + +``` +**DEVELOPMENT** + +![image](https://user-images.githubusercontent.com/166269/139014121-0596b084-b3c5-4adb-994e-31ba6eba6dad.png) +``` + +Getting back to item 2 from above: _The ability to add additional context to an error message_ + +This is particularly useful when creating microservices or an API that you intend to pass error messages back in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. + +```python +raise TeapotError(context={"foo": "bar"}) +``` + +This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: + +.. column:: + +```` +**PRODUCTION** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + } +} +``` +```` + +.. column:: + +```` +**DEVELOPMENT** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + }, + "extra": { + "name": "Adam", + "more": "lines", + "complex": { + "one": "two" + } + }, + "path": "/", + "args": {}, + "exceptions": [ + { + "type": "TeapotError", + "exception": "Sorry Adam, I cannot make you coffee", + "frames": [ + { + "file": "handle_request", + "line": 83, + "name": "handle_request", + "src": "" + }, + { + "file": "/tmp/p.py", + "line": 17, + "name": "handler", + "src": "raise TeapotError(" + } + ] + } + ] +} +``` +```` + +### Background task management + +When using the `app.add_task` method to create a background task, there now is the option to pass an optional `name` keyword argument that allows it to be fetched, or cancelled. + +```python +app.add_task(dummy, name="dummy_task") +task = app.get_task("dummy_task") + +app.cancel_task("dummy_task") +``` + +### Route context kwargs in definitions + +When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. + +```python +@app.get("/1", ctx_label="something") +async def handler1(request): + ... + +@app.get("/2", ctx_label="something") +async def handler2(request): + ... + +@app.get("/99") +async def handler99(request): + ... + +@app.on_request +async def do_something(request): + if request.route.ctx.label == "something": + ... +``` + +### Blueprints can be registered at any time + +In previous versions of Sanic, there was a strict ordering of when a Blueprint could be attached to an application. If you ran `app.blueprint(bp)` _before_ attaching all objects to the Blueprint instance, they would be missed. + +Now, you can attach a Blueprint at anytime and everything attached to it will be included at startup. + +### Noisy exceptions (force all exceptions to logs) + +There is a new `NOISY_EXCEPTIONS` config value. When it is `False` (which is the default), Sanic will respect the `quiet` property of any `SanicException`. This means that an exception with `quiet=True` will not be displayed to the log output. + +However, when setting `NOISY_EXCEPTIONS=True`, all exceptions will be logged regardless of the `quiet` value. + +This can be helpful when debugging. + +```python +app.config.NOISY_EXCEPTIONS = True +``` + +### Signal events as `Enum` + +There is an `Enum` with all of the built-in signal values for convenience. + +```python +from sanic.signals import Event + +@app.signal(Event.HTTP_LIFECYCLE_BEGIN) +async def connection_opened(conn_info): + ... +``` + +### Custom type casting of environment variables + +By default, Sanic will convert an `int`, `float`, or a `bool` value when applying environment variables to the `config` instance. You can extend this with your own converter: + +```python +app = Sanic(..., config=Config(converters=[UUID])) +``` + +### Disable `uvloop` by configuration value + +The usage of `uvloop` can be controlled by configuration value: + +```python +app.config.USE_UVLOOP = False +``` + +### Run Sanic server with multiple TLS certificates + +Sanic can be run with multiple TLS certificates: + +```python +app.run( + ssl=[ + "/etc/letsencrypt/live/example.com/", + "/etc/letsencrypt/live/mysite.example/", + ] +) +``` + +## News + +### Coming Soon: Python Web Development with Sanic + +A book about Sanic is coming soon by one of the core developers, [@ahopkins](https://github.com/ahopkins). + +Learn more at [sanicbook.com](https://sanicbook.com). + +> Get equipped with the practical knowledge of working with Sanic to increase the performance and scalability of your web applications. While doing that, we will level-up your development skills as you learn to customize your application to meet the changing business needs without having to significantly over-engineer the app. + +A portion of book proceeds goes into the Sanic Community Organization to help fund the development and operation of Sanic. So, buying the book is another way you can support Sanic. + +### Dark mode for the docs + +If you have not already noticed, this Sanic website is now available in a native dark mode. You can toggle the theme at the top right of the page. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@adarsharegmi](https://github.com/adarsharegmi) +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@cnicodeme](https://github.com/cnicodeme) +[@kianmeng](https://github.com/kianmeng) +[@meysam81](https://github.com/meysam81) +[@nuxion](https://github.com/nuxion) +[@prryplatypus](https://github.com/prryplatypus) +[@realDragonium](https://github.com/realDragonium) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@Tronic](https://github.com/tronic) +[@Varriount](https://github.com/Varriount) +[@vltr](https://github.com/vltr) +[@whos4n3](https://github.com/whos4n3) + +And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From f1497480baac547b1af23fc1f0f514a948dea26c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:15 +0200 Subject: [PATCH 240/698] New translations v21.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.12.md | 531 ++++++++++++++++++ 1 file changed, 531 insertions(+) create mode 100644 guide/content/zh/release-notes/2021/v21.12.md diff --git a/guide/content/zh/release-notes/2021/v21.12.md b/guide/content/zh/release-notes/2021/v21.12.md new file mode 100644 index 0000000000..2b80536a32 --- /dev/null +++ b/guide/content/zh/release-notes/2021/v21.12.md @@ -0,0 +1,531 @@ +--- +title: Version 21.12 (LTS) +--- + +# Version 21.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will now enter long-term support and will be supported for two years until December 2023. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Strict application and blueprint names + +In [v21.6](./v21.6.md#stricter-application-and-blueprint-names-and-deprecation) application and blueprint names were required to conform to a new set of restrictions. That change is now being enforced at startup time. + +Names **must**: + +1. Only use alphanumeric characters (`a-zA-Z0-9`) +2. May contain a hyphen (`-`) or an underscore (`_`) +3. Must begin with a letter or underscore (`a-zA-Z_`) + +### Strict application and blueprint properties + +The old leniency to allow directly setting properties of a `Sanic` or `Blueprint` object was deprecated and no longer allowed. You must use the `ctx` object. + +```python +app = Sanic("MyApp") +app.ctx.db = Database() +``` + +### Removals + +The following deprecated features no longer exist: + +- `sanic.exceptions.abort` +- `sanic.views.CompositionView` +- `sanic.response.StreamingHTTPResponse` + +### Upgrade your streaming responses (if not already) + +The `sanic.response.stream` response method has been **deprecated** and will be removed in v22.6. If you are sill using an old school streaming response, please upgrade it. + +**OLD - Deprecated** + +```python +async def sample_streaming_fn(response): + await response.write("foo,") + await response.write("bar") + +@app.route("/") +async def test(request: Request): + return stream(sample_streaming_fn, content_type="text/csv") +``` + +**Current** + +```python +async def sample_streaming_fn(response): + await response.write("foo,") + await response.write("bar") + +@app.route("/") +async def test(request: Request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") +``` + +### CLI overhaul and MOTD (Message of the Day) + +The Sanic CLI has received a fairly extensive upgrade. It adds a bunch of new features to make it on par with `app.run()`. It also includes a new MOTD display to provide quick, at-a-glance highlights about your running environment. The MOTD is TTY-aware, and therefore will be less verbose in server logs. It is mainly intended as a convenience during application development. + +``` +$ sanic --help +usage: sanic [-h] [--version] [--factory] [-s] [-H HOST] [-p PORT] [-u UNIX] [--cert CERT] [--key KEY] [--tls DIR] [--tls-strict-host] + [-w WORKERS | --fast] [--access-logs | --no-access-logs] [--debug] [-d] [-r] [-R PATH] [--motd | --no-motd] [-v] + [--noisy-exceptions | --no-noisy-exceptions] + module + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + + To start running a Sanic application, provide a path to the module, where + app is a Sanic() instance: + + $ sanic path.to.server:app + + Or, a path to a callable that returns a Sanic() instance: + + $ sanic path.to.factory:create_app --factory + + Or, a path to a directory to run as a simple HTTP server: + + $ sanic ./path/to/static --simple + +Required +======== + Positional: + module Path to your Sanic app. Example: path.to.server:app + If running a Simple Server, path to directory to serve. Example: ./ + +Optional +======== + General: + -h, --help show this help message and exit + --version show program's version number and exit + + Application: + --factory Treat app as an application factory, i.e. a () -> callable + -s, --simple Run Sanic as a Simple Server, and serve the contents of a directory + (module arg should be a path) + + Socket binding: + -H HOST, --host HOST Host address [default 127.0.0.1] + -p PORT, --port PORT Port to serve on [default 8000] + -u UNIX, --unix UNIX location of unix socket + + TLS certificate: + --cert CERT Location of fullchain.pem, bundle.crt or equivalent + --key KEY Location of privkey.pem or equivalent .key file + --tls DIR TLS certificate folder with fullchain.pem and privkey.pem + May be specified multiple times to choose multiple certificates + --tls-strict-host Only allow clients that send an SNI matching server certs + + Worker: + -w WORKERS, --workers WORKERS Number of worker processes [default 1] + --fast Set the number of workers to max allowed + --access-logs Display access logs + --no-access-logs No display access logs + + Development: + --debug Run the server in debug mode + -d, --dev Currently is an alias for --debug. But starting in v22.3, + --debug will no longer automatically trigger auto_restart. + However, --dev will continue, effectively making it the + same as debug + auto_reload. + -r, --reload, --auto-reload Watch source directory for file changes and reload on changes + -R PATH, --reload-dir PATH Extra directories to watch and reload on changes + + Output: + --motd Show the startup display + --no-motd No show the startup display + -v, --verbosity Control logging noise, eg. -vv or --verbosity=2 [default 0] + --noisy-exceptions Output stack traces for all exceptions + --no-noisy-exceptions No output stack traces for all exceptions +``` + +### Server running modes and changes coming to `debug` + +There are now two running modes: `DEV` and `PRODUCTION`. By default, Sanic server will run under `PRODUCTION` mode. This is intended for deployments. + +Currently, `DEV` mode will operate very similarly to how `debug=True` does in older Sanic versions. However, in v22.3. `debug=True` will **no longer** enable auto-reload. If you would like to have debugging and auto-reload, you should enable `DEV` mode. + +**DEVELOPMENT** + +``` +$ sanic server:app --dev +``` + +```python +app.run(debug=True, auto_reload=True) +``` + +**PRODUCTION** + +``` +$ sanic server:app +``` + +```python +app.run() +``` + +Beginning in v22.3, `PRODUCTION` mode will no longer enable access logs by default. + +A summary of the changes are as follows: + +| Flag | Mode | Tracebacks | Logging | Access logs | Reload | Max workers | +| ------- | ----- | ---------- | ------- | ----------- | ------ | ----------- | +| --debug | DEBUG | yes | DEBUG | yes | ^1 | | +| | PROD | no | INFO ^2 | ^3 | | | +| --dev | DEBUG | yes | DEBUG | yes | yes | | +| --fast | | | | | | yes | + +- ^1 `--debug` to deprecate auto-reloading and remove in 22.3 +- ^2 After 22.3 this moves to WARNING +- ^3 After 22.3: no + +### Max allowed workers + +You can easily spin up the maximum number of allowed workers using `--fast`. + +``` +$ sanic server:app --fast +``` + +```python +app.run(fast=True) +``` + +### First-class Sanic Extensions support + +[Sanic Extensions](../../plugins/sanic-ext/getting-started.md) provides a number of additional features specifically intended for API developers. You can now easily implement all of the functionality it has to offer without additional setup as long as the package is in the environment. These features include: + +- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- CORS protection +- Predefined, endpoint-specific response serializers +- Dependency injection into route handlers +- OpenAPI documentation with Redoc and/or Swagger +- Request query arguments and body input validation + +The preferred method is to install it along with Sanic, but you can also install the packages on their own. + +.. column:: + +```` +``` +$ pip install sanic[ext] +``` +```` + +.. column:: + +```` +``` +$ pip install sanic sanic-ext +``` +```` + +After that, no additional configuration is required. Sanic Extensions will be attached to your application and provide all of the additional functionality with **no further configuration**. + +If you want to change how it works, or provide additional configuration, you can change Sanic extensions using `app.extend`. The following examples are equivalent. The `Config` object is to provide helpful type annotations for IDE development. + +.. column:: + +```` +```python +# This is optional, not required +app = Sanic("MyApp") +app.extend(config={"oas_url_prefix": "/apidocs"}) +``` +```` + +.. column:: + +```` +```python +# This is optional, not required +app = Sanic("MyApp") +app.config.OAS_URL_PREFIX = "/apidocs" +``` +```` + +.. column:: + +```` +```python +# This is optional, not required +from sanic_ext import Config + +app = Sanic("MyApp") +app.extend(config=Config(oas_url_prefix="/apidocs")) +``` +```` + +.. column:: + +### Contextual exceptions + +In [v21.9](./v21.9.md#default-exception-messages) we added default messages to exceptions that simplify the ability to consistently raise exceptions throughout your application. + +```python +class TeapotError(SanicException): + status_code = 418 + message = "Sorry, I cannot brew coffee" + +raise TeapotError +``` + +But this lacked two things: + +1. A dynamic and predictable message format +2. The ability to add additional context to an error message (more on this in a moment) + +The current release allows any Sanic exception to have additional information to when raised to provide context when writing an error message: + +```python +class TeapotError(SanicException): + status_code = 418 + + @property + def message(self): + return f"Sorry {self.extra['name']}, I cannot make you coffee" + +raise TeapotError(extra={"name": "Adam"}) +``` + +The new feature allows the passing of `extra` meta to the exception instance. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. + +.. column:: + +``` +**PRODUCTION** + +![image](https://user-images.githubusercontent.com/166269/139014161-cda67cd1-843f-4ad2-9fa1-acb94a59fc4d.png) +``` + +.. column:: + +``` +**DEVELOPMENT** + +![image](https://user-images.githubusercontent.com/166269/139014121-0596b084-b3c5-4adb-994e-31ba6eba6dad.png) +``` + +Getting back to item 2 from above: _The ability to add additional context to an error message_ + +This is particularly useful when creating microservices or an API that you intend to pass error messages back in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. + +```python +raise TeapotError(context={"foo": "bar"}) +``` + +This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: + +.. column:: + +```` +**PRODUCTION** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + } +} +``` +```` + +.. column:: + +```` +**DEVELOPMENT** + +```json +{ + "description": "I'm a teapot", + "status": 418, + "message": "Sorry Adam, I cannot make you coffee", + "context": { + "foo": "bar" + }, + "extra": { + "name": "Adam", + "more": "lines", + "complex": { + "one": "two" + } + }, + "path": "/", + "args": {}, + "exceptions": [ + { + "type": "TeapotError", + "exception": "Sorry Adam, I cannot make you coffee", + "frames": [ + { + "file": "handle_request", + "line": 83, + "name": "handle_request", + "src": "" + }, + { + "file": "/tmp/p.py", + "line": 17, + "name": "handler", + "src": "raise TeapotError(" + } + ] + } + ] +} +``` +```` + +### Background task management + +When using the `app.add_task` method to create a background task, there now is the option to pass an optional `name` keyword argument that allows it to be fetched, or cancelled. + +```python +app.add_task(dummy, name="dummy_task") +task = app.get_task("dummy_task") + +app.cancel_task("dummy_task") +``` + +### Route context kwargs in definitions + +When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. + +```python +@app.get("/1", ctx_label="something") +async def handler1(request): + ... + +@app.get("/2", ctx_label="something") +async def handler2(request): + ... + +@app.get("/99") +async def handler99(request): + ... + +@app.on_request +async def do_something(request): + if request.route.ctx.label == "something": + ... +``` + +### Blueprints can be registered at any time + +In previous versions of Sanic, there was a strict ordering of when a Blueprint could be attached to an application. If you ran `app.blueprint(bp)` _before_ attaching all objects to the Blueprint instance, they would be missed. + +Now, you can attach a Blueprint at anytime and everything attached to it will be included at startup. + +### Noisy exceptions (force all exceptions to logs) + +There is a new `NOISY_EXCEPTIONS` config value. When it is `False` (which is the default), Sanic will respect the `quiet` property of any `SanicException`. This means that an exception with `quiet=True` will not be displayed to the log output. + +However, when setting `NOISY_EXCEPTIONS=True`, all exceptions will be logged regardless of the `quiet` value. + +This can be helpful when debugging. + +```python +app.config.NOISY_EXCEPTIONS = True +``` + +### Signal events as `Enum` + +There is an `Enum` with all of the built-in signal values for convenience. + +```python +from sanic.signals import Event + +@app.signal(Event.HTTP_LIFECYCLE_BEGIN) +async def connection_opened(conn_info): + ... +``` + +### Custom type casting of environment variables + +By default, Sanic will convert an `int`, `float`, or a `bool` value when applying environment variables to the `config` instance. You can extend this with your own converter: + +```python +app = Sanic(..., config=Config(converters=[UUID])) +``` + +### Disable `uvloop` by configuration value + +The usage of `uvloop` can be controlled by configuration value: + +```python +app.config.USE_UVLOOP = False +``` + +### Run Sanic server with multiple TLS certificates + +Sanic can be run with multiple TLS certificates: + +```python +app.run( + ssl=[ + "/etc/letsencrypt/live/example.com/", + "/etc/letsencrypt/live/mysite.example/", + ] +) +``` + +## News + +### Coming Soon: Python Web Development with Sanic + +A book about Sanic is coming soon by one of the core developers, [@ahopkins](https://github.com/ahopkins). + +Learn more at [sanicbook.com](https://sanicbook.com). + +> Get equipped with the practical knowledge of working with Sanic to increase the performance and scalability of your web applications. While doing that, we will level-up your development skills as you learn to customize your application to meet the changing business needs without having to significantly over-engineer the app. + +A portion of book proceeds goes into the Sanic Community Organization to help fund the development and operation of Sanic. So, buying the book is another way you can support Sanic. + +### Dark mode for the docs + +If you have not already noticed, this Sanic website is now available in a native dark mode. You can toggle the theme at the top right of the page. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@adarsharegmi](https://github.com/adarsharegmi) +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@cnicodeme](https://github.com/cnicodeme) +[@kianmeng](https://github.com/kianmeng) +[@meysam81](https://github.com/meysam81) +[@nuxion](https://github.com/nuxion) +[@prryplatypus](https://github.com/prryplatypus) +[@realDragonium](https://github.com/realDragonium) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@Tronic](https://github.com/tronic) +[@Varriount](https://github.com/Varriount) +[@vltr](https://github.com/vltr) +[@whos4n3](https://github.com/whos4n3) + +And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 41581e545260300e53a202dabc6938c7c786edc9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:16 +0200 Subject: [PATCH 241/698] New translations v21.3.md (Japanese) --- guide/content/ja/release-notes/2021/v21.3.md | 272 +++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 guide/content/ja/release-notes/2021/v21.3.md diff --git a/guide/content/ja/release-notes/2021/v21.3.md b/guide/content/ja/release-notes/2021/v21.3.md new file mode 100644 index 0000000000..2539e750b2 --- /dev/null +++ b/guide/content/ja/release-notes/2021/v21.3.md @@ -0,0 +1,272 @@ +--- +title: Version 21.3 +--- + +# Version 21.3 + +.. toc:: + +## Introduction + +Sanic is now faster. + +Well, it already was fast. But with the first iteration of the v21 release, we incorporated a few major milestones that have made some tangible improvements. These encompass some ideas that have been in the works for years, and have finally made it into the released version. + +.. warning:: Breaking changes + +```` +Version 21.3 introduces a lot of new features. But, it also includes some breaking changes. This is why these changes were introduced after the last LTS. If you rely upon something that has been removed, you should continue to use v20.12LTS until you are able to upgrade. + +```bash +pip install "sanic>=20.12,<20.13" +pip freeze > requirements.txt +``` + +For most typical installations, you should be able to upgrade without a problem. +```` + +## What to know + +Notable new or breaking features, and what to upgrade... + +### Python 3.7+ Only + +This version drops Python 3.6 support. Version 20.12LTS will continue to support Python 3.6 until its EOL in December, 2022, and version 19.12LTS will support it until its EOL in December, 2021. + +Read more about our [LTS policy](../project/policies.md#long-term-support-v-interim-releases). + +### Streaming as first class citizen + +The biggest speed improvement came from unifying the request/response cycle into a single flow. Previously, there was a difference between regular cycles, and streaming cycles. This has been simplified under the hood, even though the API is staying the same right now for compatibility. The net benefit is that **all** requests now should see a new benefit. + +Read more about [streaming changes](../advanced/streaming.md#response-streaming). + +### Router overhaul + +The old Sanic router was based upon regular expressions. In addition it suffered from a number of quirks that made it hard to modify at run time, and resulted in some performance issues. This change has been years in the making and now [converts the router to a compiled tree at startup](https://community.sanicframework.org/t/a-fast-new-router/649/41). Look for additional improvements throughout the year. + +The outward facing API has kept backwards compatibility. However, if you were accessing anything inside the router specifically, you many notice some changes. For example: + +1. `Router.get()` has a new return value +2. `Route` is now a proper class object and not a `namedtuple` +3. If building the router manually, you will need to call `Router.finalize()` before it is usable +4. There is a new `` pattern that can be matched in your routes +5. You cannot startup an application without at least one route defined + +The router is now located in its own repository: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-routing/). + +### Signals API ⭐️ + +_BETA Feature: API to be finalized in v21.6_ + +A side benefit of the new router is that it can do double duty also powering the [new signals API](https://github.com/sanic-org/sanic/issues/1630). This feature is being released for public usage now, and likely the public API will not change in its final form. + +The core ideas of this feature are: + +1. to allow the developer greater control and access to plugging into the server and request lifecycles, +2. to provide new tools to synchronize and send messages through your application, and +3. to ultimately further increase performance. + +The API introduces three new methods: + +- `@app.signal(...)` - For defining a signal handler. It looks and operates very much like a route. Whenever that signal is dispatched, this handler will be executed. +- `app.event(...)` - An awaitable that can be used anywhere in your application to pause execution until the event is triggered. +- `app.dispatch(...)` - Trigger an event and cause the signal handlers to execute. + +```python +@app.signal("foo.bar.") +async def signal_handler(thing, **kwargs): + print(f"[signal_handler] {thing=}", kwargs) + +async def wait_for_event(app): + while True: + print("> waiting") + await app.event("foo.bar.*") + print("> event found\n") + +@app.after_server_start +async def after_server_start(app, loop): + app.add_task(wait_for_event(app)) + +@app.get("/") +async def trigger(request): + await app.dispatch("foo.bar.baz") + return response.text("Done.") +``` + +### Route naming + +Routes used to be referenced by both `route.name` and `route.endpoint`. While similar, they were slightly different. Now, all routes will be **consistently** namespaced and referenced. + +```text +.[optional:.] +``` + +This new "name" is assigned to the property `route.name`. We are deprecating `route.endpoint`, and will remove that property in v21.9. Until then, it will be an alias for `route.name`. + +In addition, naming prefixes that had been in use for things like static, websocket, and blueprint routes have been removed. + +### New decorators + +Several new convenience decorators to help IDEs with autocomplete. + +```python +# Alias to @app.listener("...") +@app.before_server_start +@app.after_server_stop +@app.before_server_start +@app.after_server_stop + +# Alias to @app.middleware("...") +@app.on_request +@app.on_response +``` + +### Unquote in route + +If you have a route that uses non-ascii characters, Sanic will no longer `unquote` the text for you. You will need to specifically tell the route definition that it should do so. + +```python +@app.route("/overload/", methods=["GET"], unquote=True) +async def handler2(request, param): + return text("OK2 " + param) + +request, response = app.test_client.get("/overload/您好") +assert response.text == "OK2 您好" +``` + +If you forget to do so, your text will remain encoded. + +### Alter `Request.match_info` + +The `match_info` has always provided the data for the matched path parameters. You now have access to modify that, for example in middleware. + +```python +@app.on_request +def convert_to_snake_case(request): + request.match_info = to_snake(request.match_info) +``` + +### Version types in routes + +The `version` argument in routes can now be: + +- `str` +- `int` +- `float` + +```python +@app.route("/foo", version="2.1.1") +@app.route("/foo", version=2) +@app.route("/foo", version=2.1) +``` + +### Safe method handling with body + +Route handlers for `GET`, `HEAD`, `OPTIONS` and `DELETE` will not decode any HTTP body passed to it. You can override this: + +```python +@app.delete(..., ignore_body=False) +``` + +### Application, Blueprint and Blueprint Group parity + +The `Sanic` and `Blueprint` classes share a common base. Previously they duplicated a lot of functionality, that lead to slightly different implementations between them. Now that they both inherit the same base class, developers and plugins should have a more consistent API to work with. + +Also, Blueprint Groups now also support common URL extensions like the `version` and `strict_slashes` keyword arguments. + +### Dropped `httpx` from dependencies + +There is no longer a dependency on `httpx`. + +### Removed `testing` library + +Sanic internal testing client has been removed. It is now located in its own repository: [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-testing/). + +If you have `sanic-testing` installed, it will be available and usable on your `Sanic()` application instances as before. So, the **only** change you will need to make is to add `sanic-testing` to your test suite requirements. + +### Application and connection level context (`ctx`) objects + +Version 19.9 [added ](https://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API. This helpful construct easily allows for attaching properties and data to a request object (for example, in middleware), and reusing the information elsewhere int he application. + +Similarly, this concept is being extended in two places: + +1. the application instance, and +2. a transport connection. + +#### Application context + +A common use case is to attach properties to the app instance. For the sake of consistency, and to avoid the issue of name collision with Sanic properties, the `ctx` object now exists on `Sanic` instances. + +```python +@app.before_server_startup +async def startup_db(app, _): + # WRONG + app.db = await connect_to_db() + + # CORRECT + app.ctx.db = await connect_to_db() +``` + +#### Connection context + +When a client sends a keep alive header, Sanic will attempt to keep the transport socket [open for a period of time](../deployment/configuration.md#keep-alive-timeout). That transport object now has a `ctx` object available on it. This effectively means that multiple requests from a single client (where the transport layer is being reused) may share state. + +```python +@app.on_request +async def increment_foo(request): + if not hasattr(request.conn_info.ctx, "foo"): + request.conn_info.ctx.foo = 0 + request.conn_info.ctx.foo += 1 + +@app.get("/") +async def count_foo(request): + return text(f"request.conn_info.ctx.foo={request.conn_info.ctx.foo}") +``` + +```bash +$ curl localhost:8000 localhost:8000 localhost:8000 +request.conn_info.ctx.foo=1 +request.conn_info.ctx.foo=2 +request.conn_info.ctx.foo=3 +``` + +.. warning:: + +``` +Connection level context is an experimental feature, and should be finalized in v21.6. +``` + +## News + +### A NEW frontpage 🎉 + +We have split the documentation into two. The docstrings inside the codebase will still continue to build sphinx docs to ReadTheDocs. However, it will be limited to API documentation. The new frontpage will house the "Sanic User Guide". + +The new site runs on Vuepress. Contributions are welcome. We also invite help in translating the documents. + +As a part of this, we also freshened up the RTD documentation and changed it to API docs only. + +### Chat has moved to Discord + +The Gitter chatroom has taken one step closer to being phased out. In its place we opened a [Discord server](https://discord.gg/FARQzAEMAA). + +### Open Collective + +The Sanic Community Organization has [opened a page on Open Collective](https://opencollective.com/sanic-org) to enable anyone that would like to financially support the development of Sanic. + +### 2021 Release Managers + +Thank you to @sjsadowski and @yunstanford for acting as release managers for both 2019 and 2020. This year's release managers are @ahopkins and @vltr. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) [@akshgpt7](https://github.com/akshgpt7) [@artcg](https://github.com/artcg) [@ashleysommer](https://github.com/ashleysommer) [@elis-k](https://github.com/elis-k) [@harshanarayana](https://github.com/harshanarayana) [@sjsadowski](https://github.com/sjsadowski) [@tronic](https://github.com/tronic) [@vltr](https://github.com/vltr), + +To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for translating our documents into Chinese, + +*** + +Make sure to checkout the changelog to get links to all the PRs, etc. From be65c3fda26cc8ed08499b2e0bd28ec184f2e0b3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:17 +0200 Subject: [PATCH 242/698] New translations v21.3.md (Korean) --- guide/content/ko/release-notes/2021/v21.3.md | 272 +++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 guide/content/ko/release-notes/2021/v21.3.md diff --git a/guide/content/ko/release-notes/2021/v21.3.md b/guide/content/ko/release-notes/2021/v21.3.md new file mode 100644 index 0000000000..2539e750b2 --- /dev/null +++ b/guide/content/ko/release-notes/2021/v21.3.md @@ -0,0 +1,272 @@ +--- +title: Version 21.3 +--- + +# Version 21.3 + +.. toc:: + +## Introduction + +Sanic is now faster. + +Well, it already was fast. But with the first iteration of the v21 release, we incorporated a few major milestones that have made some tangible improvements. These encompass some ideas that have been in the works for years, and have finally made it into the released version. + +.. warning:: Breaking changes + +```` +Version 21.3 introduces a lot of new features. But, it also includes some breaking changes. This is why these changes were introduced after the last LTS. If you rely upon something that has been removed, you should continue to use v20.12LTS until you are able to upgrade. + +```bash +pip install "sanic>=20.12,<20.13" +pip freeze > requirements.txt +``` + +For most typical installations, you should be able to upgrade without a problem. +```` + +## What to know + +Notable new or breaking features, and what to upgrade... + +### Python 3.7+ Only + +This version drops Python 3.6 support. Version 20.12LTS will continue to support Python 3.6 until its EOL in December, 2022, and version 19.12LTS will support it until its EOL in December, 2021. + +Read more about our [LTS policy](../project/policies.md#long-term-support-v-interim-releases). + +### Streaming as first class citizen + +The biggest speed improvement came from unifying the request/response cycle into a single flow. Previously, there was a difference between regular cycles, and streaming cycles. This has been simplified under the hood, even though the API is staying the same right now for compatibility. The net benefit is that **all** requests now should see a new benefit. + +Read more about [streaming changes](../advanced/streaming.md#response-streaming). + +### Router overhaul + +The old Sanic router was based upon regular expressions. In addition it suffered from a number of quirks that made it hard to modify at run time, and resulted in some performance issues. This change has been years in the making and now [converts the router to a compiled tree at startup](https://community.sanicframework.org/t/a-fast-new-router/649/41). Look for additional improvements throughout the year. + +The outward facing API has kept backwards compatibility. However, if you were accessing anything inside the router specifically, you many notice some changes. For example: + +1. `Router.get()` has a new return value +2. `Route` is now a proper class object and not a `namedtuple` +3. If building the router manually, you will need to call `Router.finalize()` before it is usable +4. There is a new `` pattern that can be matched in your routes +5. You cannot startup an application without at least one route defined + +The router is now located in its own repository: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-routing/). + +### Signals API ⭐️ + +_BETA Feature: API to be finalized in v21.6_ + +A side benefit of the new router is that it can do double duty also powering the [new signals API](https://github.com/sanic-org/sanic/issues/1630). This feature is being released for public usage now, and likely the public API will not change in its final form. + +The core ideas of this feature are: + +1. to allow the developer greater control and access to plugging into the server and request lifecycles, +2. to provide new tools to synchronize and send messages through your application, and +3. to ultimately further increase performance. + +The API introduces three new methods: + +- `@app.signal(...)` - For defining a signal handler. It looks and operates very much like a route. Whenever that signal is dispatched, this handler will be executed. +- `app.event(...)` - An awaitable that can be used anywhere in your application to pause execution until the event is triggered. +- `app.dispatch(...)` - Trigger an event and cause the signal handlers to execute. + +```python +@app.signal("foo.bar.") +async def signal_handler(thing, **kwargs): + print(f"[signal_handler] {thing=}", kwargs) + +async def wait_for_event(app): + while True: + print("> waiting") + await app.event("foo.bar.*") + print("> event found\n") + +@app.after_server_start +async def after_server_start(app, loop): + app.add_task(wait_for_event(app)) + +@app.get("/") +async def trigger(request): + await app.dispatch("foo.bar.baz") + return response.text("Done.") +``` + +### Route naming + +Routes used to be referenced by both `route.name` and `route.endpoint`. While similar, they were slightly different. Now, all routes will be **consistently** namespaced and referenced. + +```text +.[optional:.] +``` + +This new "name" is assigned to the property `route.name`. We are deprecating `route.endpoint`, and will remove that property in v21.9. Until then, it will be an alias for `route.name`. + +In addition, naming prefixes that had been in use for things like static, websocket, and blueprint routes have been removed. + +### New decorators + +Several new convenience decorators to help IDEs with autocomplete. + +```python +# Alias to @app.listener("...") +@app.before_server_start +@app.after_server_stop +@app.before_server_start +@app.after_server_stop + +# Alias to @app.middleware("...") +@app.on_request +@app.on_response +``` + +### Unquote in route + +If you have a route that uses non-ascii characters, Sanic will no longer `unquote` the text for you. You will need to specifically tell the route definition that it should do so. + +```python +@app.route("/overload/", methods=["GET"], unquote=True) +async def handler2(request, param): + return text("OK2 " + param) + +request, response = app.test_client.get("/overload/您好") +assert response.text == "OK2 您好" +``` + +If you forget to do so, your text will remain encoded. + +### Alter `Request.match_info` + +The `match_info` has always provided the data for the matched path parameters. You now have access to modify that, for example in middleware. + +```python +@app.on_request +def convert_to_snake_case(request): + request.match_info = to_snake(request.match_info) +``` + +### Version types in routes + +The `version` argument in routes can now be: + +- `str` +- `int` +- `float` + +```python +@app.route("/foo", version="2.1.1") +@app.route("/foo", version=2) +@app.route("/foo", version=2.1) +``` + +### Safe method handling with body + +Route handlers for `GET`, `HEAD`, `OPTIONS` and `DELETE` will not decode any HTTP body passed to it. You can override this: + +```python +@app.delete(..., ignore_body=False) +``` + +### Application, Blueprint and Blueprint Group parity + +The `Sanic` and `Blueprint` classes share a common base. Previously they duplicated a lot of functionality, that lead to slightly different implementations between them. Now that they both inherit the same base class, developers and plugins should have a more consistent API to work with. + +Also, Blueprint Groups now also support common URL extensions like the `version` and `strict_slashes` keyword arguments. + +### Dropped `httpx` from dependencies + +There is no longer a dependency on `httpx`. + +### Removed `testing` library + +Sanic internal testing client has been removed. It is now located in its own repository: [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-testing/). + +If you have `sanic-testing` installed, it will be available and usable on your `Sanic()` application instances as before. So, the **only** change you will need to make is to add `sanic-testing` to your test suite requirements. + +### Application and connection level context (`ctx`) objects + +Version 19.9 [added ](https://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API. This helpful construct easily allows for attaching properties and data to a request object (for example, in middleware), and reusing the information elsewhere int he application. + +Similarly, this concept is being extended in two places: + +1. the application instance, and +2. a transport connection. + +#### Application context + +A common use case is to attach properties to the app instance. For the sake of consistency, and to avoid the issue of name collision with Sanic properties, the `ctx` object now exists on `Sanic` instances. + +```python +@app.before_server_startup +async def startup_db(app, _): + # WRONG + app.db = await connect_to_db() + + # CORRECT + app.ctx.db = await connect_to_db() +``` + +#### Connection context + +When a client sends a keep alive header, Sanic will attempt to keep the transport socket [open for a period of time](../deployment/configuration.md#keep-alive-timeout). That transport object now has a `ctx` object available on it. This effectively means that multiple requests from a single client (where the transport layer is being reused) may share state. + +```python +@app.on_request +async def increment_foo(request): + if not hasattr(request.conn_info.ctx, "foo"): + request.conn_info.ctx.foo = 0 + request.conn_info.ctx.foo += 1 + +@app.get("/") +async def count_foo(request): + return text(f"request.conn_info.ctx.foo={request.conn_info.ctx.foo}") +``` + +```bash +$ curl localhost:8000 localhost:8000 localhost:8000 +request.conn_info.ctx.foo=1 +request.conn_info.ctx.foo=2 +request.conn_info.ctx.foo=3 +``` + +.. warning:: + +``` +Connection level context is an experimental feature, and should be finalized in v21.6. +``` + +## News + +### A NEW frontpage 🎉 + +We have split the documentation into two. The docstrings inside the codebase will still continue to build sphinx docs to ReadTheDocs. However, it will be limited to API documentation. The new frontpage will house the "Sanic User Guide". + +The new site runs on Vuepress. Contributions are welcome. We also invite help in translating the documents. + +As a part of this, we also freshened up the RTD documentation and changed it to API docs only. + +### Chat has moved to Discord + +The Gitter chatroom has taken one step closer to being phased out. In its place we opened a [Discord server](https://discord.gg/FARQzAEMAA). + +### Open Collective + +The Sanic Community Organization has [opened a page on Open Collective](https://opencollective.com/sanic-org) to enable anyone that would like to financially support the development of Sanic. + +### 2021 Release Managers + +Thank you to @sjsadowski and @yunstanford for acting as release managers for both 2019 and 2020. This year's release managers are @ahopkins and @vltr. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) [@akshgpt7](https://github.com/akshgpt7) [@artcg](https://github.com/artcg) [@ashleysommer](https://github.com/ashleysommer) [@elis-k](https://github.com/elis-k) [@harshanarayana](https://github.com/harshanarayana) [@sjsadowski](https://github.com/sjsadowski) [@tronic](https://github.com/tronic) [@vltr](https://github.com/vltr), + +To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for translating our documents into Chinese, + +*** + +Make sure to checkout the changelog to get links to all the PRs, etc. From a3923e3bb715fd3a8d25fa56cafbefebdd3082c2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:18 +0200 Subject: [PATCH 243/698] New translations v21.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.3.md | 272 +++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 guide/content/zh/release-notes/2021/v21.3.md diff --git a/guide/content/zh/release-notes/2021/v21.3.md b/guide/content/zh/release-notes/2021/v21.3.md new file mode 100644 index 0000000000..2539e750b2 --- /dev/null +++ b/guide/content/zh/release-notes/2021/v21.3.md @@ -0,0 +1,272 @@ +--- +title: Version 21.3 +--- + +# Version 21.3 + +.. toc:: + +## Introduction + +Sanic is now faster. + +Well, it already was fast. But with the first iteration of the v21 release, we incorporated a few major milestones that have made some tangible improvements. These encompass some ideas that have been in the works for years, and have finally made it into the released version. + +.. warning:: Breaking changes + +```` +Version 21.3 introduces a lot of new features. But, it also includes some breaking changes. This is why these changes were introduced after the last LTS. If you rely upon something that has been removed, you should continue to use v20.12LTS until you are able to upgrade. + +```bash +pip install "sanic>=20.12,<20.13" +pip freeze > requirements.txt +``` + +For most typical installations, you should be able to upgrade without a problem. +```` + +## What to know + +Notable new or breaking features, and what to upgrade... + +### Python 3.7+ Only + +This version drops Python 3.6 support. Version 20.12LTS will continue to support Python 3.6 until its EOL in December, 2022, and version 19.12LTS will support it until its EOL in December, 2021. + +Read more about our [LTS policy](../project/policies.md#long-term-support-v-interim-releases). + +### Streaming as first class citizen + +The biggest speed improvement came from unifying the request/response cycle into a single flow. Previously, there was a difference between regular cycles, and streaming cycles. This has been simplified under the hood, even though the API is staying the same right now for compatibility. The net benefit is that **all** requests now should see a new benefit. + +Read more about [streaming changes](../advanced/streaming.md#response-streaming). + +### Router overhaul + +The old Sanic router was based upon regular expressions. In addition it suffered from a number of quirks that made it hard to modify at run time, and resulted in some performance issues. This change has been years in the making and now [converts the router to a compiled tree at startup](https://community.sanicframework.org/t/a-fast-new-router/649/41). Look for additional improvements throughout the year. + +The outward facing API has kept backwards compatibility. However, if you were accessing anything inside the router specifically, you many notice some changes. For example: + +1. `Router.get()` has a new return value +2. `Route` is now a proper class object and not a `namedtuple` +3. If building the router manually, you will need to call `Router.finalize()` before it is usable +4. There is a new `` pattern that can be matched in your routes +5. You cannot startup an application without at least one route defined + +The router is now located in its own repository: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-routing/). + +### Signals API ⭐️ + +_BETA Feature: API to be finalized in v21.6_ + +A side benefit of the new router is that it can do double duty also powering the [new signals API](https://github.com/sanic-org/sanic/issues/1630). This feature is being released for public usage now, and likely the public API will not change in its final form. + +The core ideas of this feature are: + +1. to allow the developer greater control and access to plugging into the server and request lifecycles, +2. to provide new tools to synchronize and send messages through your application, and +3. to ultimately further increase performance. + +The API introduces three new methods: + +- `@app.signal(...)` - For defining a signal handler. It looks and operates very much like a route. Whenever that signal is dispatched, this handler will be executed. +- `app.event(...)` - An awaitable that can be used anywhere in your application to pause execution until the event is triggered. +- `app.dispatch(...)` - Trigger an event and cause the signal handlers to execute. + +```python +@app.signal("foo.bar.") +async def signal_handler(thing, **kwargs): + print(f"[signal_handler] {thing=}", kwargs) + +async def wait_for_event(app): + while True: + print("> waiting") + await app.event("foo.bar.*") + print("> event found\n") + +@app.after_server_start +async def after_server_start(app, loop): + app.add_task(wait_for_event(app)) + +@app.get("/") +async def trigger(request): + await app.dispatch("foo.bar.baz") + return response.text("Done.") +``` + +### Route naming + +Routes used to be referenced by both `route.name` and `route.endpoint`. While similar, they were slightly different. Now, all routes will be **consistently** namespaced and referenced. + +```text +.[optional:.] +``` + +This new "name" is assigned to the property `route.name`. We are deprecating `route.endpoint`, and will remove that property in v21.9. Until then, it will be an alias for `route.name`. + +In addition, naming prefixes that had been in use for things like static, websocket, and blueprint routes have been removed. + +### New decorators + +Several new convenience decorators to help IDEs with autocomplete. + +```python +# Alias to @app.listener("...") +@app.before_server_start +@app.after_server_stop +@app.before_server_start +@app.after_server_stop + +# Alias to @app.middleware("...") +@app.on_request +@app.on_response +``` + +### Unquote in route + +If you have a route that uses non-ascii characters, Sanic will no longer `unquote` the text for you. You will need to specifically tell the route definition that it should do so. + +```python +@app.route("/overload/", methods=["GET"], unquote=True) +async def handler2(request, param): + return text("OK2 " + param) + +request, response = app.test_client.get("/overload/您好") +assert response.text == "OK2 您好" +``` + +If you forget to do so, your text will remain encoded. + +### Alter `Request.match_info` + +The `match_info` has always provided the data for the matched path parameters. You now have access to modify that, for example in middleware. + +```python +@app.on_request +def convert_to_snake_case(request): + request.match_info = to_snake(request.match_info) +``` + +### Version types in routes + +The `version` argument in routes can now be: + +- `str` +- `int` +- `float` + +```python +@app.route("/foo", version="2.1.1") +@app.route("/foo", version=2) +@app.route("/foo", version=2.1) +``` + +### Safe method handling with body + +Route handlers for `GET`, `HEAD`, `OPTIONS` and `DELETE` will not decode any HTTP body passed to it. You can override this: + +```python +@app.delete(..., ignore_body=False) +``` + +### Application, Blueprint and Blueprint Group parity + +The `Sanic` and `Blueprint` classes share a common base. Previously they duplicated a lot of functionality, that lead to slightly different implementations between them. Now that they both inherit the same base class, developers and plugins should have a more consistent API to work with. + +Also, Blueprint Groups now also support common URL extensions like the `version` and `strict_slashes` keyword arguments. + +### Dropped `httpx` from dependencies + +There is no longer a dependency on `httpx`. + +### Removed `testing` library + +Sanic internal testing client has been removed. It is now located in its own repository: [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-testing/). + +If you have `sanic-testing` installed, it will be available and usable on your `Sanic()` application instances as before. So, the **only** change you will need to make is to add `sanic-testing` to your test suite requirements. + +### Application and connection level context (`ctx`) objects + +Version 19.9 [added ](https://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API. This helpful construct easily allows for attaching properties and data to a request object (for example, in middleware), and reusing the information elsewhere int he application. + +Similarly, this concept is being extended in two places: + +1. the application instance, and +2. a transport connection. + +#### Application context + +A common use case is to attach properties to the app instance. For the sake of consistency, and to avoid the issue of name collision with Sanic properties, the `ctx` object now exists on `Sanic` instances. + +```python +@app.before_server_startup +async def startup_db(app, _): + # WRONG + app.db = await connect_to_db() + + # CORRECT + app.ctx.db = await connect_to_db() +``` + +#### Connection context + +When a client sends a keep alive header, Sanic will attempt to keep the transport socket [open for a period of time](../deployment/configuration.md#keep-alive-timeout). That transport object now has a `ctx` object available on it. This effectively means that multiple requests from a single client (where the transport layer is being reused) may share state. + +```python +@app.on_request +async def increment_foo(request): + if not hasattr(request.conn_info.ctx, "foo"): + request.conn_info.ctx.foo = 0 + request.conn_info.ctx.foo += 1 + +@app.get("/") +async def count_foo(request): + return text(f"request.conn_info.ctx.foo={request.conn_info.ctx.foo}") +``` + +```bash +$ curl localhost:8000 localhost:8000 localhost:8000 +request.conn_info.ctx.foo=1 +request.conn_info.ctx.foo=2 +request.conn_info.ctx.foo=3 +``` + +.. warning:: + +``` +Connection level context is an experimental feature, and should be finalized in v21.6. +``` + +## News + +### A NEW frontpage 🎉 + +We have split the documentation into two. The docstrings inside the codebase will still continue to build sphinx docs to ReadTheDocs. However, it will be limited to API documentation. The new frontpage will house the "Sanic User Guide". + +The new site runs on Vuepress. Contributions are welcome. We also invite help in translating the documents. + +As a part of this, we also freshened up the RTD documentation and changed it to API docs only. + +### Chat has moved to Discord + +The Gitter chatroom has taken one step closer to being phased out. In its place we opened a [Discord server](https://discord.gg/FARQzAEMAA). + +### Open Collective + +The Sanic Community Organization has [opened a page on Open Collective](https://opencollective.com/sanic-org) to enable anyone that would like to financially support the development of Sanic. + +### 2021 Release Managers + +Thank you to @sjsadowski and @yunstanford for acting as release managers for both 2019 and 2020. This year's release managers are @ahopkins and @vltr. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) [@akshgpt7](https://github.com/akshgpt7) [@artcg](https://github.com/artcg) [@ashleysommer](https://github.com/ashleysommer) [@elis-k](https://github.com/elis-k) [@harshanarayana](https://github.com/harshanarayana) [@sjsadowski](https://github.com/sjsadowski) [@tronic](https://github.com/tronic) [@vltr](https://github.com/vltr), + +To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for translating our documents into Chinese, + +*** + +Make sure to checkout the changelog to get links to all the PRs, etc. From 74a6e5714814631e08c5d548fa1f34aaf00e0310 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:19 +0200 Subject: [PATCH 244/698] New translations v21.6.md (Japanese) --- guide/content/ja/release-notes/2021/v21.6.md | 352 +++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 guide/content/ja/release-notes/2021/v21.6.md diff --git a/guide/content/ja/release-notes/2021/v21.6.md b/guide/content/ja/release-notes/2021/v21.6.md new file mode 100644 index 0000000000..98453a86f4 --- /dev/null +++ b/guide/content/ja/release-notes/2021/v21.6.md @@ -0,0 +1,352 @@ +--- +title: Version 21.6 +--- + +# Version 21.6 + +.. toc:: + +## Introduction + +This is the second release of the version 21 [release cycle](../project/policies.md#release-schedule). There will be one more release in September before version 21 is "finalized" in the December long-term support version. One thing users may have noticed starting in 21.3, the router was moved to its own package: [`sanic-routing`](https://pypi.org/project/sanic-routing). This change is likely to stay for now. Starting with this release, the minimum required version is 0.7.0. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Deprecation of `StreamingHTTPResponse` + +The use of `StreamingHTTPResponse` has been deprecated and will be removed in the 21.12 release. This impacts both `sanic.response.stream` and `sanic.response.file_stream`, which both under the hood instantiate `StreamingHTTPResponse`. + +Although the exact migration path has yet to be determined, `sanic.response.stream` and `sanic.response.file_stream` will continue to exist in v21.12 in some form as convenience operators. Look for more details throughout this Summer as we hope to have this finalized by the September release. + +### Deprecation of `CompositionView` + +Usage of `CompositionView` has been deprecated and will be removed in 21.12. + +### Deprecation of path parameter types: `string` and `number` + +Going forward, you should use `str` and `float` for path param types instead of `string` and `number`. + +```python +@app.get("//") +async def handler(request, foo: str, bar: float): + ... +``` + +Existing `string` and `number` types are aliased and will continue to work, but will be removed in v21.12. + +### Version 0.7 router upgrades + +This includes a number of bug fixes and more gracefully handles a wider array of edge cases than v0.6. If you experience any patterns that are not supported, [please report them](https://github.com/sanic-org/sanic-routing/issues). You can see some of the issues resolved on the `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases). + +### Inline streaming with `eof()` + +Version 21.3 included [big changes in how streaming is handled](https://sanic.dev/en/guide/release-notes/v21.3.html#what-to-know). The pattern introduced will become the default (see below). As a convenience, a new `response.eof()` method has been included. It should be called once the final data has been pushed to the client: + +```python +@app.route("/") +async def test(request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") + await response.eof() + return response +``` + +### New path parameter type: `slug` + +You can now specify a dynamic path segment as a `slug` with appropriate matching: + +```python +@app.get("/articles/") +async def article(request, article_slug: str): + ... +``` + +Slugs must consist of lowercase letters or digits. They may contain a hyphen (`-`), but it cannot be the first character. + +``` +this-is-a-slug +with-123-is-also-a-slug +111-at-start-is-a-slug +NOT-a-slug +-NOT-a-slug +``` + +### Stricter application and blueprint names, and deprecation + +Your application and `Blueprint` instances must conform to a stricter set of requirements: + +1. Only consisting of alphanumeric characters +2. May contain a hyphen (`-`) or an underscore (`_`) +3. Must begin with a letter (uppercase or lowercase) + +The naming convention is similar to Python variable naming conventions, with the addition of allowing hyphens (`-`). + +The looser standard has been deprecatated. Beginning in 21.12, non-conformance will be a startup time error. + +### A new access on `Route` object: `route.uri` + +The `Route` object in v21.3 no longer had a `uri` attribute. Instead, the closes you could get was `route.path`. However, because of how `sanic-routing` works, the `path` property does _not_ have a leading `/`. This has been corrected so that now there is a `route.uri` with a leading slash: + +```python +route.uri == f"/{route.path}" +``` + +### A new accessor on `Request` object impacting IPs + +To access the IP address of the incoming request, Sanic has had a convenience accessor on the request object: `request.ip`. That is not new, and comes from an underlying object that provides details about the open HTTP connection: `request.conn_info`. + +The current version adds a new `client_ip` accessor to that `conn_info` object. For IPv4, you will not notice a difference. However, for IPv6 applications, the new accessor will provide an "unwrapped" version of the address. Consider the following example: + +```python +@app.get("/") +async def handler(request): + return json( + { + "request.ip": request.ip, + "request.conn_info.client": request.conn_info.client, + "request.conn_info.client_ip": request.conn_info.client_ip, + } + ) + +app.run(sock=my_ipv6_sock) +``` + +```bash +$ curl http://\[::1\]:8000 +{ + "request.ip": "::1", + "request.conn_info.client": "[::1]", + "request.conn_info.client_ip": "::1" +} + +``` + +### Alternate `Config` and `Sanic.ctx` objects + +You can now pass your own config and context objects to your Sanic applications. A custom configuration _should_ be a subclass of `sanic.config.Config`. The context object can be anything you want, with no restrictions whatsoever. + +```python +class CustomConfig(Config): + ... + +config = CustomConfig() +app = Sanic("custom", config=config) +assert isinstance(app.config, CustomConfig) +``` + +And... + +```python +class CustomContext: + ... + +ctx = CustomContext() +app = Sanic("custom", ctx=ctx) +assert isinstance(app.ctx, CustomContext) +``` + +### Sanic CLI improvements + +1. New flag for existing feature: `--auto-reload` +2. Some new shorthand flags for existing arguments +3. New feature: `--factory` +4. New feature: `--simple` +5. New feature: `--reload-dir` + +#### Factory applications + +For applications that follow the factory pattern (a function that returns a `sanic.Sanic` instance), you can now launch your application from the Sanic CLI using the `--factory` flag. + +```python +from sanic import Blueprint, Sanic, text + +bp = Blueprint(__file__) + +@bp.get("/") +async def handler(request): + return text("😎") + +def create_app() -> Sanic: + app = Sanic(__file__) + app.blueprint(bp) + return app +``` + +You can now run it: + +```bash +$ sanic path.to:create_app --factory +``` + +#### Sanic Simple Server + +Sanic CLI now includes a simple pattern to serve a directory as a web server. It will look for an `index.html` at the directory root. + +```bash +$ sanic ./path/to/dir --simple +``` + +.. warning:: + +``` +This feature is still in early *beta* mode. It is likely to change in scope. +``` + +#### Additional reload directories + +When using either `debug` or `auto-reload`, you can include additional directories for Sanic to watch for new files. + +```bash +sanic ... --reload-dir=/path/to/foo --reload-dir=/path/to/bar +``` + +.. tip:: + +``` +You do *NOT* need to include this on your application directory. Sanic will automatically reload when any Python file in your application changes. You should use the `reload-dir` argument when you want to listen and update your application when static files are updated. +``` + +### Version prefix + +When adding `version`, your route is prefixed with `/v`. This will always be at the beginning of the path. This is not new. + +```python +# /v1/my/path +app.route("/my/path", version=1) +``` + +Now, you can alter the prefix (and therefore add path segments _before_ the version). + +```python +# /api/v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` + +The `version_prefix` argument is can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +### Signal event auto-registration + +Setting `config.EVENT_AUTOREGISTER` to `True` will allow you to await any signal event even if it has not previously been defined with a signal handler. + +```python +@app.signal("do.something.start") +async def signal_handler(): + await do_something() + await app.dispatch("do.something.complete") + +# somethere else in your app: +await app.event("do.something.complete") +``` + +### Infinitely reusable and nestable `Blueprint` and `BlueprintGroup` + +A single `Blueprint` may not be assigned and reused to multiple groups. The groups themselves can also by infinitely nested into one or more other groups. This allows for an unlimited range of composition. + +### HTTP methods as `Enum` + +Sanic now has `sanic.HTTPMethod`, which is an `Enum`. It can be used interchangeably with strings: + +```python +from sanic import Sanic, HTTPMethod + +@app.route("/", methods=["post", "PUT", HTTPMethod.PATCH]) +async def handler(...): + ... +``` + +### Expansion of `HTTPMethodView` + +Class based views may be attached now in one of three ways: + +**Option 1 - Existing** + +```python +class DummyView(HTTPMethodView): + ... + +app.add_route(DummyView.as_view(), "/dummy") +``` + +**Option 2 - From `attach` method** + +```python +class DummyView(HTTPMethodView): + ... + +DummyView.attach(app, "/") +``` + +**Option 3 - From class definition at `__init_subclass__`** + +```python +class DummyView(HTTPMethodView, attach=app, uri="/"): + ... +``` + +Options 2 and 3 are useful if your CBV is located in another file: + +```python +from sanic import Sanic, HTTPMethodView + +class DummyView(HTTPMethodView, attach=Sanic.get_app(), uri="/"): + ... +``` + +## News + +### Discord and support forums + +If you have not already joined our community, you can become a part by joining the [Discord server](https://discord.gg/FARQzAEMAA) and the [Community Forums](https://community.sanicframework.org/). Also, follow [@sanicframework](https://twitter.com/sanicframework) on Twitter. + +### SCO 2022 elections + +The Summer 🏝/Winter ❄️ (choose your Hemisphere) is upon us. That means we will be holding elections for the SCO. This year, we will have the following positions to fill: + +- Steering Council Member (2 year term) +- Steering Council Member (2 year term) +- Steering Council Member (1 year term) +- Release Manager v22 +- Release Manager v22 + +[@vltr](https://github.com/vltr) will be staying on to complete his second year on the Steering Council. + +If you are interested in learning more, you can read about the SCO [roles and responsibilities](../project/scope.md#roles-and-responsibilities), or Adam Hopkins on Discord. + +Nominations will begin September 1. More details will be available on the Forums as we get closer. + +### New project underway + +We have added a new project to the SCO umbrella: [`sanic-ext`](https://github.com/sanic-org/sanic-ext). It is not yet released, and in heavy active development. The goal for the project will ultimately be to replace [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi) with something that provides more features for web application developers, including input validation, CORS handling, and HTTP auto-method handlers. If you are interested in helping out, let us know on Discord. Look for an initial release of this project sometime (hopefully) before the September release. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ajaygupta2790](https://github.com/ajaygupta2790) +[@ashleysommer](https://github.com/ashleysommer) +[@ENT8R](https://github.com/ent8r) +[@fredlllll](https://github.com/fredlllll) +[@graingert](https://github.com/graingert) +[@harshanarayana](https://github.com/harshanarayana) +[@jdraymon](https://github.com/jdraymon) +[@Kyle-Verhoog](https://github.com/kyle-verhoog) +[@sanjeevanahilan](https://github.com/sanjeevanahilan) +[@sjsadowski](https://github.com/sjsadowski) +[@Tronic](https://github.com/tronic) +[@vltr](https://github.com/vltr) +[@ZinkLu](https://github.com/zinklu) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From 284944862ee6f2c12eda94151f724130c9ea1aba Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:20 +0200 Subject: [PATCH 245/698] New translations v21.6.md (Korean) --- guide/content/ko/release-notes/2021/v21.6.md | 352 +++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 guide/content/ko/release-notes/2021/v21.6.md diff --git a/guide/content/ko/release-notes/2021/v21.6.md b/guide/content/ko/release-notes/2021/v21.6.md new file mode 100644 index 0000000000..98453a86f4 --- /dev/null +++ b/guide/content/ko/release-notes/2021/v21.6.md @@ -0,0 +1,352 @@ +--- +title: Version 21.6 +--- + +# Version 21.6 + +.. toc:: + +## Introduction + +This is the second release of the version 21 [release cycle](../project/policies.md#release-schedule). There will be one more release in September before version 21 is "finalized" in the December long-term support version. One thing users may have noticed starting in 21.3, the router was moved to its own package: [`sanic-routing`](https://pypi.org/project/sanic-routing). This change is likely to stay for now. Starting with this release, the minimum required version is 0.7.0. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Deprecation of `StreamingHTTPResponse` + +The use of `StreamingHTTPResponse` has been deprecated and will be removed in the 21.12 release. This impacts both `sanic.response.stream` and `sanic.response.file_stream`, which both under the hood instantiate `StreamingHTTPResponse`. + +Although the exact migration path has yet to be determined, `sanic.response.stream` and `sanic.response.file_stream` will continue to exist in v21.12 in some form as convenience operators. Look for more details throughout this Summer as we hope to have this finalized by the September release. + +### Deprecation of `CompositionView` + +Usage of `CompositionView` has been deprecated and will be removed in 21.12. + +### Deprecation of path parameter types: `string` and `number` + +Going forward, you should use `str` and `float` for path param types instead of `string` and `number`. + +```python +@app.get("//") +async def handler(request, foo: str, bar: float): + ... +``` + +Existing `string` and `number` types are aliased and will continue to work, but will be removed in v21.12. + +### Version 0.7 router upgrades + +This includes a number of bug fixes and more gracefully handles a wider array of edge cases than v0.6. If you experience any patterns that are not supported, [please report them](https://github.com/sanic-org/sanic-routing/issues). You can see some of the issues resolved on the `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases). + +### Inline streaming with `eof()` + +Version 21.3 included [big changes in how streaming is handled](https://sanic.dev/en/guide/release-notes/v21.3.html#what-to-know). The pattern introduced will become the default (see below). As a convenience, a new `response.eof()` method has been included. It should be called once the final data has been pushed to the client: + +```python +@app.route("/") +async def test(request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") + await response.eof() + return response +``` + +### New path parameter type: `slug` + +You can now specify a dynamic path segment as a `slug` with appropriate matching: + +```python +@app.get("/articles/") +async def article(request, article_slug: str): + ... +``` + +Slugs must consist of lowercase letters or digits. They may contain a hyphen (`-`), but it cannot be the first character. + +``` +this-is-a-slug +with-123-is-also-a-slug +111-at-start-is-a-slug +NOT-a-slug +-NOT-a-slug +``` + +### Stricter application and blueprint names, and deprecation + +Your application and `Blueprint` instances must conform to a stricter set of requirements: + +1. Only consisting of alphanumeric characters +2. May contain a hyphen (`-`) or an underscore (`_`) +3. Must begin with a letter (uppercase or lowercase) + +The naming convention is similar to Python variable naming conventions, with the addition of allowing hyphens (`-`). + +The looser standard has been deprecatated. Beginning in 21.12, non-conformance will be a startup time error. + +### A new access on `Route` object: `route.uri` + +The `Route` object in v21.3 no longer had a `uri` attribute. Instead, the closes you could get was `route.path`. However, because of how `sanic-routing` works, the `path` property does _not_ have a leading `/`. This has been corrected so that now there is a `route.uri` with a leading slash: + +```python +route.uri == f"/{route.path}" +``` + +### A new accessor on `Request` object impacting IPs + +To access the IP address of the incoming request, Sanic has had a convenience accessor on the request object: `request.ip`. That is not new, and comes from an underlying object that provides details about the open HTTP connection: `request.conn_info`. + +The current version adds a new `client_ip` accessor to that `conn_info` object. For IPv4, you will not notice a difference. However, for IPv6 applications, the new accessor will provide an "unwrapped" version of the address. Consider the following example: + +```python +@app.get("/") +async def handler(request): + return json( + { + "request.ip": request.ip, + "request.conn_info.client": request.conn_info.client, + "request.conn_info.client_ip": request.conn_info.client_ip, + } + ) + +app.run(sock=my_ipv6_sock) +``` + +```bash +$ curl http://\[::1\]:8000 +{ + "request.ip": "::1", + "request.conn_info.client": "[::1]", + "request.conn_info.client_ip": "::1" +} + +``` + +### Alternate `Config` and `Sanic.ctx` objects + +You can now pass your own config and context objects to your Sanic applications. A custom configuration _should_ be a subclass of `sanic.config.Config`. The context object can be anything you want, with no restrictions whatsoever. + +```python +class CustomConfig(Config): + ... + +config = CustomConfig() +app = Sanic("custom", config=config) +assert isinstance(app.config, CustomConfig) +``` + +And... + +```python +class CustomContext: + ... + +ctx = CustomContext() +app = Sanic("custom", ctx=ctx) +assert isinstance(app.ctx, CustomContext) +``` + +### Sanic CLI improvements + +1. New flag for existing feature: `--auto-reload` +2. Some new shorthand flags for existing arguments +3. New feature: `--factory` +4. New feature: `--simple` +5. New feature: `--reload-dir` + +#### Factory applications + +For applications that follow the factory pattern (a function that returns a `sanic.Sanic` instance), you can now launch your application from the Sanic CLI using the `--factory` flag. + +```python +from sanic import Blueprint, Sanic, text + +bp = Blueprint(__file__) + +@bp.get("/") +async def handler(request): + return text("😎") + +def create_app() -> Sanic: + app = Sanic(__file__) + app.blueprint(bp) + return app +``` + +You can now run it: + +```bash +$ sanic path.to:create_app --factory +``` + +#### Sanic Simple Server + +Sanic CLI now includes a simple pattern to serve a directory as a web server. It will look for an `index.html` at the directory root. + +```bash +$ sanic ./path/to/dir --simple +``` + +.. warning:: + +``` +This feature is still in early *beta* mode. It is likely to change in scope. +``` + +#### Additional reload directories + +When using either `debug` or `auto-reload`, you can include additional directories for Sanic to watch for new files. + +```bash +sanic ... --reload-dir=/path/to/foo --reload-dir=/path/to/bar +``` + +.. tip:: + +``` +You do *NOT* need to include this on your application directory. Sanic will automatically reload when any Python file in your application changes. You should use the `reload-dir` argument when you want to listen and update your application when static files are updated. +``` + +### Version prefix + +When adding `version`, your route is prefixed with `/v`. This will always be at the beginning of the path. This is not new. + +```python +# /v1/my/path +app.route("/my/path", version=1) +``` + +Now, you can alter the prefix (and therefore add path segments _before_ the version). + +```python +# /api/v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` + +The `version_prefix` argument is can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +### Signal event auto-registration + +Setting `config.EVENT_AUTOREGISTER` to `True` will allow you to await any signal event even if it has not previously been defined with a signal handler. + +```python +@app.signal("do.something.start") +async def signal_handler(): + await do_something() + await app.dispatch("do.something.complete") + +# somethere else in your app: +await app.event("do.something.complete") +``` + +### Infinitely reusable and nestable `Blueprint` and `BlueprintGroup` + +A single `Blueprint` may not be assigned and reused to multiple groups. The groups themselves can also by infinitely nested into one or more other groups. This allows for an unlimited range of composition. + +### HTTP methods as `Enum` + +Sanic now has `sanic.HTTPMethod`, which is an `Enum`. It can be used interchangeably with strings: + +```python +from sanic import Sanic, HTTPMethod + +@app.route("/", methods=["post", "PUT", HTTPMethod.PATCH]) +async def handler(...): + ... +``` + +### Expansion of `HTTPMethodView` + +Class based views may be attached now in one of three ways: + +**Option 1 - Existing** + +```python +class DummyView(HTTPMethodView): + ... + +app.add_route(DummyView.as_view(), "/dummy") +``` + +**Option 2 - From `attach` method** + +```python +class DummyView(HTTPMethodView): + ... + +DummyView.attach(app, "/") +``` + +**Option 3 - From class definition at `__init_subclass__`** + +```python +class DummyView(HTTPMethodView, attach=app, uri="/"): + ... +``` + +Options 2 and 3 are useful if your CBV is located in another file: + +```python +from sanic import Sanic, HTTPMethodView + +class DummyView(HTTPMethodView, attach=Sanic.get_app(), uri="/"): + ... +``` + +## News + +### Discord and support forums + +If you have not already joined our community, you can become a part by joining the [Discord server](https://discord.gg/FARQzAEMAA) and the [Community Forums](https://community.sanicframework.org/). Also, follow [@sanicframework](https://twitter.com/sanicframework) on Twitter. + +### SCO 2022 elections + +The Summer 🏝/Winter ❄️ (choose your Hemisphere) is upon us. That means we will be holding elections for the SCO. This year, we will have the following positions to fill: + +- Steering Council Member (2 year term) +- Steering Council Member (2 year term) +- Steering Council Member (1 year term) +- Release Manager v22 +- Release Manager v22 + +[@vltr](https://github.com/vltr) will be staying on to complete his second year on the Steering Council. + +If you are interested in learning more, you can read about the SCO [roles and responsibilities](../project/scope.md#roles-and-responsibilities), or Adam Hopkins on Discord. + +Nominations will begin September 1. More details will be available on the Forums as we get closer. + +### New project underway + +We have added a new project to the SCO umbrella: [`sanic-ext`](https://github.com/sanic-org/sanic-ext). It is not yet released, and in heavy active development. The goal for the project will ultimately be to replace [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi) with something that provides more features for web application developers, including input validation, CORS handling, and HTTP auto-method handlers. If you are interested in helping out, let us know on Discord. Look for an initial release of this project sometime (hopefully) before the September release. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ajaygupta2790](https://github.com/ajaygupta2790) +[@ashleysommer](https://github.com/ashleysommer) +[@ENT8R](https://github.com/ent8r) +[@fredlllll](https://github.com/fredlllll) +[@graingert](https://github.com/graingert) +[@harshanarayana](https://github.com/harshanarayana) +[@jdraymon](https://github.com/jdraymon) +[@Kyle-Verhoog](https://github.com/kyle-verhoog) +[@sanjeevanahilan](https://github.com/sanjeevanahilan) +[@sjsadowski](https://github.com/sjsadowski) +[@Tronic](https://github.com/tronic) +[@vltr](https://github.com/vltr) +[@ZinkLu](https://github.com/zinklu) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From bde8e52bba4617a06ef8d6acdadf73e8ed199fba Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:22 +0200 Subject: [PATCH 246/698] New translations v21.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.6.md | 352 +++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100644 guide/content/zh/release-notes/2021/v21.6.md diff --git a/guide/content/zh/release-notes/2021/v21.6.md b/guide/content/zh/release-notes/2021/v21.6.md new file mode 100644 index 0000000000..98453a86f4 --- /dev/null +++ b/guide/content/zh/release-notes/2021/v21.6.md @@ -0,0 +1,352 @@ +--- +title: Version 21.6 +--- + +# Version 21.6 + +.. toc:: + +## Introduction + +This is the second release of the version 21 [release cycle](../project/policies.md#release-schedule). There will be one more release in September before version 21 is "finalized" in the December long-term support version. One thing users may have noticed starting in 21.3, the router was moved to its own package: [`sanic-routing`](https://pypi.org/project/sanic-routing). This change is likely to stay for now. Starting with this release, the minimum required version is 0.7.0. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Deprecation of `StreamingHTTPResponse` + +The use of `StreamingHTTPResponse` has been deprecated and will be removed in the 21.12 release. This impacts both `sanic.response.stream` and `sanic.response.file_stream`, which both under the hood instantiate `StreamingHTTPResponse`. + +Although the exact migration path has yet to be determined, `sanic.response.stream` and `sanic.response.file_stream` will continue to exist in v21.12 in some form as convenience operators. Look for more details throughout this Summer as we hope to have this finalized by the September release. + +### Deprecation of `CompositionView` + +Usage of `CompositionView` has been deprecated and will be removed in 21.12. + +### Deprecation of path parameter types: `string` and `number` + +Going forward, you should use `str` and `float` for path param types instead of `string` and `number`. + +```python +@app.get("//") +async def handler(request, foo: str, bar: float): + ... +``` + +Existing `string` and `number` types are aliased and will continue to work, but will be removed in v21.12. + +### Version 0.7 router upgrades + +This includes a number of bug fixes and more gracefully handles a wider array of edge cases than v0.6. If you experience any patterns that are not supported, [please report them](https://github.com/sanic-org/sanic-routing/issues). You can see some of the issues resolved on the `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases). + +### Inline streaming with `eof()` + +Version 21.3 included [big changes in how streaming is handled](https://sanic.dev/en/guide/release-notes/v21.3.html#what-to-know). The pattern introduced will become the default (see below). As a convenience, a new `response.eof()` method has been included. It should be called once the final data has been pushed to the client: + +```python +@app.route("/") +async def test(request): + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") + await response.eof() + return response +``` + +### New path parameter type: `slug` + +You can now specify a dynamic path segment as a `slug` with appropriate matching: + +```python +@app.get("/articles/") +async def article(request, article_slug: str): + ... +``` + +Slugs must consist of lowercase letters or digits. They may contain a hyphen (`-`), but it cannot be the first character. + +``` +this-is-a-slug +with-123-is-also-a-slug +111-at-start-is-a-slug +NOT-a-slug +-NOT-a-slug +``` + +### Stricter application and blueprint names, and deprecation + +Your application and `Blueprint` instances must conform to a stricter set of requirements: + +1. Only consisting of alphanumeric characters +2. May contain a hyphen (`-`) or an underscore (`_`) +3. Must begin with a letter (uppercase or lowercase) + +The naming convention is similar to Python variable naming conventions, with the addition of allowing hyphens (`-`). + +The looser standard has been deprecatated. Beginning in 21.12, non-conformance will be a startup time error. + +### A new access on `Route` object: `route.uri` + +The `Route` object in v21.3 no longer had a `uri` attribute. Instead, the closes you could get was `route.path`. However, because of how `sanic-routing` works, the `path` property does _not_ have a leading `/`. This has been corrected so that now there is a `route.uri` with a leading slash: + +```python +route.uri == f"/{route.path}" +``` + +### A new accessor on `Request` object impacting IPs + +To access the IP address of the incoming request, Sanic has had a convenience accessor on the request object: `request.ip`. That is not new, and comes from an underlying object that provides details about the open HTTP connection: `request.conn_info`. + +The current version adds a new `client_ip` accessor to that `conn_info` object. For IPv4, you will not notice a difference. However, for IPv6 applications, the new accessor will provide an "unwrapped" version of the address. Consider the following example: + +```python +@app.get("/") +async def handler(request): + return json( + { + "request.ip": request.ip, + "request.conn_info.client": request.conn_info.client, + "request.conn_info.client_ip": request.conn_info.client_ip, + } + ) + +app.run(sock=my_ipv6_sock) +``` + +```bash +$ curl http://\[::1\]:8000 +{ + "request.ip": "::1", + "request.conn_info.client": "[::1]", + "request.conn_info.client_ip": "::1" +} + +``` + +### Alternate `Config` and `Sanic.ctx` objects + +You can now pass your own config and context objects to your Sanic applications. A custom configuration _should_ be a subclass of `sanic.config.Config`. The context object can be anything you want, with no restrictions whatsoever. + +```python +class CustomConfig(Config): + ... + +config = CustomConfig() +app = Sanic("custom", config=config) +assert isinstance(app.config, CustomConfig) +``` + +And... + +```python +class CustomContext: + ... + +ctx = CustomContext() +app = Sanic("custom", ctx=ctx) +assert isinstance(app.ctx, CustomContext) +``` + +### Sanic CLI improvements + +1. New flag for existing feature: `--auto-reload` +2. Some new shorthand flags for existing arguments +3. New feature: `--factory` +4. New feature: `--simple` +5. New feature: `--reload-dir` + +#### Factory applications + +For applications that follow the factory pattern (a function that returns a `sanic.Sanic` instance), you can now launch your application from the Sanic CLI using the `--factory` flag. + +```python +from sanic import Blueprint, Sanic, text + +bp = Blueprint(__file__) + +@bp.get("/") +async def handler(request): + return text("😎") + +def create_app() -> Sanic: + app = Sanic(__file__) + app.blueprint(bp) + return app +``` + +You can now run it: + +```bash +$ sanic path.to:create_app --factory +``` + +#### Sanic Simple Server + +Sanic CLI now includes a simple pattern to serve a directory as a web server. It will look for an `index.html` at the directory root. + +```bash +$ sanic ./path/to/dir --simple +``` + +.. warning:: + +``` +This feature is still in early *beta* mode. It is likely to change in scope. +``` + +#### Additional reload directories + +When using either `debug` or `auto-reload`, you can include additional directories for Sanic to watch for new files. + +```bash +sanic ... --reload-dir=/path/to/foo --reload-dir=/path/to/bar +``` + +.. tip:: + +``` +You do *NOT* need to include this on your application directory. Sanic will automatically reload when any Python file in your application changes. You should use the `reload-dir` argument when you want to listen and update your application when static files are updated. +``` + +### Version prefix + +When adding `version`, your route is prefixed with `/v`. This will always be at the beginning of the path. This is not new. + +```python +# /v1/my/path +app.route("/my/path", version=1) +``` + +Now, you can alter the prefix (and therefore add path segments _before_ the version). + +```python +# /api/v1/my/path +app.route("/my/path", version=1, version_prefix="/api/v") +``` + +The `version_prefix` argument is can be defined in: + +- `app.route` and `bp.route` decorators (and all the convenience decorators also) +- `Blueprint` instantiation +- `Blueprint.group` constructor +- `BlueprintGroup` instantiation +- `app.blueprint` registration + +### Signal event auto-registration + +Setting `config.EVENT_AUTOREGISTER` to `True` will allow you to await any signal event even if it has not previously been defined with a signal handler. + +```python +@app.signal("do.something.start") +async def signal_handler(): + await do_something() + await app.dispatch("do.something.complete") + +# somethere else in your app: +await app.event("do.something.complete") +``` + +### Infinitely reusable and nestable `Blueprint` and `BlueprintGroup` + +A single `Blueprint` may not be assigned and reused to multiple groups. The groups themselves can also by infinitely nested into one or more other groups. This allows for an unlimited range of composition. + +### HTTP methods as `Enum` + +Sanic now has `sanic.HTTPMethod`, which is an `Enum`. It can be used interchangeably with strings: + +```python +from sanic import Sanic, HTTPMethod + +@app.route("/", methods=["post", "PUT", HTTPMethod.PATCH]) +async def handler(...): + ... +``` + +### Expansion of `HTTPMethodView` + +Class based views may be attached now in one of three ways: + +**Option 1 - Existing** + +```python +class DummyView(HTTPMethodView): + ... + +app.add_route(DummyView.as_view(), "/dummy") +``` + +**Option 2 - From `attach` method** + +```python +class DummyView(HTTPMethodView): + ... + +DummyView.attach(app, "/") +``` + +**Option 3 - From class definition at `__init_subclass__`** + +```python +class DummyView(HTTPMethodView, attach=app, uri="/"): + ... +``` + +Options 2 and 3 are useful if your CBV is located in another file: + +```python +from sanic import Sanic, HTTPMethodView + +class DummyView(HTTPMethodView, attach=Sanic.get_app(), uri="/"): + ... +``` + +## News + +### Discord and support forums + +If you have not already joined our community, you can become a part by joining the [Discord server](https://discord.gg/FARQzAEMAA) and the [Community Forums](https://community.sanicframework.org/). Also, follow [@sanicframework](https://twitter.com/sanicframework) on Twitter. + +### SCO 2022 elections + +The Summer 🏝/Winter ❄️ (choose your Hemisphere) is upon us. That means we will be holding elections for the SCO. This year, we will have the following positions to fill: + +- Steering Council Member (2 year term) +- Steering Council Member (2 year term) +- Steering Council Member (1 year term) +- Release Manager v22 +- Release Manager v22 + +[@vltr](https://github.com/vltr) will be staying on to complete his second year on the Steering Council. + +If you are interested in learning more, you can read about the SCO [roles and responsibilities](../project/scope.md#roles-and-responsibilities), or Adam Hopkins on Discord. + +Nominations will begin September 1. More details will be available on the Forums as we get closer. + +### New project underway + +We have added a new project to the SCO umbrella: [`sanic-ext`](https://github.com/sanic-org/sanic-ext). It is not yet released, and in heavy active development. The goal for the project will ultimately be to replace [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi) with something that provides more features for web application developers, including input validation, CORS handling, and HTTP auto-method handlers. If you are interested in helping out, let us know on Discord. Look for an initial release of this project sometime (hopefully) before the September release. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ajaygupta2790](https://github.com/ajaygupta2790) +[@ashleysommer](https://github.com/ashleysommer) +[@ENT8R](https://github.com/ent8r) +[@fredlllll](https://github.com/fredlllll) +[@graingert](https://github.com/graingert) +[@harshanarayana](https://github.com/harshanarayana) +[@jdraymon](https://github.com/jdraymon) +[@Kyle-Verhoog](https://github.com/kyle-verhoog) +[@sanjeevanahilan](https://github.com/sanjeevanahilan) +[@sjsadowski](https://github.com/sjsadowski) +[@Tronic](https://github.com/tronic) +[@vltr](https://github.com/vltr) +[@ZinkLu](https://github.com/zinklu) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From f8d0371b3310fb119493f8740e53326cef63aa6f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:23 +0200 Subject: [PATCH 247/698] New translations v21.9.md (Japanese) --- guide/content/ja/release-notes/2021/v21.9.md | 240 +++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 guide/content/ja/release-notes/2021/v21.9.md diff --git a/guide/content/ja/release-notes/2021/v21.9.md b/guide/content/ja/release-notes/2021/v21.9.md new file mode 100644 index 0000000000..8b3b8149de --- /dev/null +++ b/guide/content/ja/release-notes/2021/v21.9.md @@ -0,0 +1,240 @@ +--- +title: Version 21.9 +--- + +# Version 21.9 + +.. toc:: + +## Introduction + +This is the third release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Removal of config values: `WEBSOCKET_READ_LIMIT`, `WEBSOCKET_WRITE_LIMIT` and `WEBSOCKET_MAX_QUEUE` + +With the complete overhaul of the websocket implementation, these configuration values were removed. There currently is not a plan to replace them. + +### Deprecation of default value of `FALLBACK_ERROR_FORMAT` + +When no error handler is attached, Sanic has used `html` as the fallback format-type. This has been deprecated and will change to `text` starting in v22.3. While the value of this has changed to `auto`, it will still continue to use HTML as the last resort thru v21.12LTS before changing. + +### `ErrorHandler.lookup` signature deprecation + +The `ErrorHandler.lookup` now **requires** two positional arguments: + +```python +def lookup(self, exception, route_name: Optional[str]): +``` + +A non-conforming method will cause Blueprint-specific exception handlers to not properly attach. + +### Reminder of upcoming removals + +As a reminder, the following items have already been deprecated, and will be removed in version 21.12LTS + +- `CompositionView` +- `load_env` (use `env_prefix` instead) +- Sanic objects (application instances, blueprints, and routes) must by alphanumeric conforming to: `^[a-zA-Z][a-zA-Z0-9_\-]*$` +- Arbitrary assignment of objects to application and blueprint instances (use `ctx` instead; removal of this has been bumped from 21.9 to 21.12) + +### Overhaul of websockets + +There has been a huge overhaul to the handling of websocket connections. Thanks to [@aaugustin](https://github.com/aaugustin) the [`websockets`](https://websockets.readthedocs.io/en/stable/index.html) now has a new implementation that allows Sanic to handle the I/O of websocket connections on its own. Therefore, Sanic has bumped the minimum version to `websockets>=10.0`. + +The change should mostly be unnoticeable to developers, except that some of the oddities around websocket handlers in Sanic have been corrected. For example, you now should be able to catch the `CancellError` yourself when someone disconnects: + +```python +@app.websocket("/") +async def handler(request, ws): + try: + while True: + await asyncio.sleep(0.25) + except asyncio.CancelledError: + print("User closed connection") +``` + +### Built-in signals + +Version [21.3](./v21.3.md) introduced [signals](../advanced/signals.md). Now, Sanic dispatches signal events **from within the codebase** itself. This means that developers now have the ability to hook into the request/response cycle at a much closer level than before. + +Previously, if you wanted to inject some logic you were limited to middleware. Think of integrated signals as _super_-middleware. The events that are dispatched now include: + +- `http.lifecycle.begin` +- `http.lifecycle.complete` +- `http.lifecycle.exception` +- `http.lifecycle.handle` +- `http.lifecycle.read_body` +- `http.lifecycle.read_head` +- `http.lifecycle.request` +- `http.lifecycle.response` +- `http.lifecycle.send` +- `http.middleware.after` +- `http.middleware.before` +- `http.routing.after` +- `http.routing.before` +- `server.init.after` +- `server.init.before` +- `server.shutdown.after` +- `server.shutdown.before` + +.. note:: + +``` +The `server` signals are the same as the four (4) main server listener events. In fact, those listeners themselves are now just convenience wrappers to signal implementations. +``` + +### Smarter `auto` exception formatting + +Sanic will now try to respond with an appropriate exception format based upon the endpoint and the client. For example, if your endpoint always returns a `sanic.response.json` object, then any exceptions will automatically be formatted in JSON. The same is true for `text` and `html` responses. + +Furthermore, you now can _explicitly_ control which formatter to use on a route-by-route basis using the route definition: + +```python +@app.route("/", error_format="json") +async def handler(request): + pass +``` + +### Blueprint copying + +Blueprints can be copied to new instances. This will carry forward everything attached to it, like routes, middleware, etc. + +```python +v1 = Blueprint("Version1", version=1) + +@v1.route("/something") +def something(request): + pass + +v2 = v1.copy("Version2", version=2) + +app.blueprint(v1) +app.blueprint(v2) +``` + +``` +/v1/something +/v2/something +``` + +### Blueprint group convenience methods + +Blueprint groups should now have all of the same methods available to them as regular Blueprints. With this, along with Blueprint copying, Blueprints should now be very composable and flexible. + +### Accept header parsing + +Sanic `Request` objects can parse an `Accept` header to provide an ordered list of the client's content-type preference. You can simply access it as an accessor: + +```python +print(request.accept) +# ["*/*"] +``` + +It also is capable of handling wildcard matching. For example, assuming the incoming request included: + +``` +Accept: */* +``` + +Then, the following is `True`: + +```python +"text/plain" in request.accept +``` + +### Default exception messages + +Any exception that derives from `SanicException` can now define a default exception message. This makes it more convenient and maintainable to reuse the same exception in multiple places without running into DRY issues with the message that the exception provides. + +```python +class TeaError(SanicException): + message = "Tempest in a teapot" + +raise TeaError +``` + +### Type annotation conveniences + +It is now possible to control the path parameter types using Python's type annotations. Instead of doing this: + +```python +@app.route("///") +def handler(request: Request, one: int, two: float, three: UUID): + ... +``` + +You can now simply do this: + +```python +@app.route("///") +def handler(request: Request, one: int, two: float, three: UUID): + ... +``` + +Both of these examples will result in the same routing principles to be applied. + +### Explicit static resource type + +You can now explicitly tell a `static` endpoint whether it is supposed to treat the resource as a file or a directory: + +```python +static("/", "/path/to/some/file", resource_type="file")) +``` + +## News + +### Release of `sanic-ext` and deprecation of `sanic-openapi` + +One of the core principles of Sanic is that it is meant to be a tool, not a dictator. As the frontpage of this website states: + +> Build the way you want to build without letting your tooling constrain you. + +This means that a lot of common features used (specifically by Web API developers) do not exist in the `sanic` repository. This is for good reason. Being unopinionated provides the developer freedom and flexibility. + +But, sometimes you do not want to have to build and rebuild the same things. Sanic has until now really relied upon the awesome support of the community to fill in the gaps with plugins. + +From the early days, there has been an official `sanic-openapi` package that offered the ability to create OpenAPI documentation based upon your application. But, that project has been plagued over the years and has not been given as much priority as the main project. + +Starting with the release of v21.9, the SCO is deprecating the `sanic-openapi` package and moving it to maintenance mode. This means that it will continue to get updates as needed to maintain it for the current future, but it will not receive any new feature enhancements. + +A new project called `sanic-ext` is taking its place. This package provides not only the ability to build OAS3 documentation, but fills in many of the gaps that API developers may want in their applications. For example, out of the box it will setup CORS, and auto enable `HEAD` and `OPTIONS` responses where needed. It also has the ability validate incoming data using either standard library Dataclasses or Pydantic models. + +The list of goodies includes: + +- CORS protection +- incoming request validation +- auto OAS3 documentation using Redoc and/or Swagger UI +- auto `HEAD`, `OPTIONS`, and `TRACE` responses +- dependency injection +- response serialization + +This project is still in `alpha` mode for now and is subject to change. While it is considered to be production capable, there may be some need to change the API as we continue to add features. + +Checkout the [documentation](../../plugins/sanic-ext/getting-started.md) for more details. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@cansarigol3megawatt](https://github.com/cansarigol3megawatt) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@gluhar2006](https://github.com/gluhar2006) +[@komar007](https://github.com/komar007) +[@ombe1229](https://github.com/ombe1229) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@Tronic](https://github.com/tronic) +[@vltr](https://github.com/vltr) + +And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From bc4cd1a5bac894d223e62cbaa6d24ba3c67a58a7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:24 +0200 Subject: [PATCH 248/698] New translations v21.9.md (Korean) --- guide/content/ko/release-notes/2021/v21.9.md | 240 +++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 guide/content/ko/release-notes/2021/v21.9.md diff --git a/guide/content/ko/release-notes/2021/v21.9.md b/guide/content/ko/release-notes/2021/v21.9.md new file mode 100644 index 0000000000..8b3b8149de --- /dev/null +++ b/guide/content/ko/release-notes/2021/v21.9.md @@ -0,0 +1,240 @@ +--- +title: Version 21.9 +--- + +# Version 21.9 + +.. toc:: + +## Introduction + +This is the third release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Removal of config values: `WEBSOCKET_READ_LIMIT`, `WEBSOCKET_WRITE_LIMIT` and `WEBSOCKET_MAX_QUEUE` + +With the complete overhaul of the websocket implementation, these configuration values were removed. There currently is not a plan to replace them. + +### Deprecation of default value of `FALLBACK_ERROR_FORMAT` + +When no error handler is attached, Sanic has used `html` as the fallback format-type. This has been deprecated and will change to `text` starting in v22.3. While the value of this has changed to `auto`, it will still continue to use HTML as the last resort thru v21.12LTS before changing. + +### `ErrorHandler.lookup` signature deprecation + +The `ErrorHandler.lookup` now **requires** two positional arguments: + +```python +def lookup(self, exception, route_name: Optional[str]): +``` + +A non-conforming method will cause Blueprint-specific exception handlers to not properly attach. + +### Reminder of upcoming removals + +As a reminder, the following items have already been deprecated, and will be removed in version 21.12LTS + +- `CompositionView` +- `load_env` (use `env_prefix` instead) +- Sanic objects (application instances, blueprints, and routes) must by alphanumeric conforming to: `^[a-zA-Z][a-zA-Z0-9_\-]*$` +- Arbitrary assignment of objects to application and blueprint instances (use `ctx` instead; removal of this has been bumped from 21.9 to 21.12) + +### Overhaul of websockets + +There has been a huge overhaul to the handling of websocket connections. Thanks to [@aaugustin](https://github.com/aaugustin) the [`websockets`](https://websockets.readthedocs.io/en/stable/index.html) now has a new implementation that allows Sanic to handle the I/O of websocket connections on its own. Therefore, Sanic has bumped the minimum version to `websockets>=10.0`. + +The change should mostly be unnoticeable to developers, except that some of the oddities around websocket handlers in Sanic have been corrected. For example, you now should be able to catch the `CancellError` yourself when someone disconnects: + +```python +@app.websocket("/") +async def handler(request, ws): + try: + while True: + await asyncio.sleep(0.25) + except asyncio.CancelledError: + print("User closed connection") +``` + +### Built-in signals + +Version [21.3](./v21.3.md) introduced [signals](../advanced/signals.md). Now, Sanic dispatches signal events **from within the codebase** itself. This means that developers now have the ability to hook into the request/response cycle at a much closer level than before. + +Previously, if you wanted to inject some logic you were limited to middleware. Think of integrated signals as _super_-middleware. The events that are dispatched now include: + +- `http.lifecycle.begin` +- `http.lifecycle.complete` +- `http.lifecycle.exception` +- `http.lifecycle.handle` +- `http.lifecycle.read_body` +- `http.lifecycle.read_head` +- `http.lifecycle.request` +- `http.lifecycle.response` +- `http.lifecycle.send` +- `http.middleware.after` +- `http.middleware.before` +- `http.routing.after` +- `http.routing.before` +- `server.init.after` +- `server.init.before` +- `server.shutdown.after` +- `server.shutdown.before` + +.. note:: + +``` +The `server` signals are the same as the four (4) main server listener events. In fact, those listeners themselves are now just convenience wrappers to signal implementations. +``` + +### Smarter `auto` exception formatting + +Sanic will now try to respond with an appropriate exception format based upon the endpoint and the client. For example, if your endpoint always returns a `sanic.response.json` object, then any exceptions will automatically be formatted in JSON. The same is true for `text` and `html` responses. + +Furthermore, you now can _explicitly_ control which formatter to use on a route-by-route basis using the route definition: + +```python +@app.route("/", error_format="json") +async def handler(request): + pass +``` + +### Blueprint copying + +Blueprints can be copied to new instances. This will carry forward everything attached to it, like routes, middleware, etc. + +```python +v1 = Blueprint("Version1", version=1) + +@v1.route("/something") +def something(request): + pass + +v2 = v1.copy("Version2", version=2) + +app.blueprint(v1) +app.blueprint(v2) +``` + +``` +/v1/something +/v2/something +``` + +### Blueprint group convenience methods + +Blueprint groups should now have all of the same methods available to them as regular Blueprints. With this, along with Blueprint copying, Blueprints should now be very composable and flexible. + +### Accept header parsing + +Sanic `Request` objects can parse an `Accept` header to provide an ordered list of the client's content-type preference. You can simply access it as an accessor: + +```python +print(request.accept) +# ["*/*"] +``` + +It also is capable of handling wildcard matching. For example, assuming the incoming request included: + +``` +Accept: */* +``` + +Then, the following is `True`: + +```python +"text/plain" in request.accept +``` + +### Default exception messages + +Any exception that derives from `SanicException` can now define a default exception message. This makes it more convenient and maintainable to reuse the same exception in multiple places without running into DRY issues with the message that the exception provides. + +```python +class TeaError(SanicException): + message = "Tempest in a teapot" + +raise TeaError +``` + +### Type annotation conveniences + +It is now possible to control the path parameter types using Python's type annotations. Instead of doing this: + +```python +@app.route("///") +def handler(request: Request, one: int, two: float, three: UUID): + ... +``` + +You can now simply do this: + +```python +@app.route("///") +def handler(request: Request, one: int, two: float, three: UUID): + ... +``` + +Both of these examples will result in the same routing principles to be applied. + +### Explicit static resource type + +You can now explicitly tell a `static` endpoint whether it is supposed to treat the resource as a file or a directory: + +```python +static("/", "/path/to/some/file", resource_type="file")) +``` + +## News + +### Release of `sanic-ext` and deprecation of `sanic-openapi` + +One of the core principles of Sanic is that it is meant to be a tool, not a dictator. As the frontpage of this website states: + +> Build the way you want to build without letting your tooling constrain you. + +This means that a lot of common features used (specifically by Web API developers) do not exist in the `sanic` repository. This is for good reason. Being unopinionated provides the developer freedom and flexibility. + +But, sometimes you do not want to have to build and rebuild the same things. Sanic has until now really relied upon the awesome support of the community to fill in the gaps with plugins. + +From the early days, there has been an official `sanic-openapi` package that offered the ability to create OpenAPI documentation based upon your application. But, that project has been plagued over the years and has not been given as much priority as the main project. + +Starting with the release of v21.9, the SCO is deprecating the `sanic-openapi` package and moving it to maintenance mode. This means that it will continue to get updates as needed to maintain it for the current future, but it will not receive any new feature enhancements. + +A new project called `sanic-ext` is taking its place. This package provides not only the ability to build OAS3 documentation, but fills in many of the gaps that API developers may want in their applications. For example, out of the box it will setup CORS, and auto enable `HEAD` and `OPTIONS` responses where needed. It also has the ability validate incoming data using either standard library Dataclasses or Pydantic models. + +The list of goodies includes: + +- CORS protection +- incoming request validation +- auto OAS3 documentation using Redoc and/or Swagger UI +- auto `HEAD`, `OPTIONS`, and `TRACE` responses +- dependency injection +- response serialization + +This project is still in `alpha` mode for now and is subject to change. While it is considered to be production capable, there may be some need to change the API as we continue to add features. + +Checkout the [documentation](../../plugins/sanic-ext/getting-started.md) for more details. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@cansarigol3megawatt](https://github.com/cansarigol3megawatt) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@gluhar2006](https://github.com/gluhar2006) +[@komar007](https://github.com/komar007) +[@ombe1229](https://github.com/ombe1229) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@Tronic](https://github.com/tronic) +[@vltr](https://github.com/vltr) + +And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From 7264515d5ea29fcfda819245cbdccd82ece8b4a4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:25 +0200 Subject: [PATCH 249/698] New translations v21.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.9.md | 240 +++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 guide/content/zh/release-notes/2021/v21.9.md diff --git a/guide/content/zh/release-notes/2021/v21.9.md b/guide/content/zh/release-notes/2021/v21.9.md new file mode 100644 index 0000000000..8b3b8149de --- /dev/null +++ b/guide/content/zh/release-notes/2021/v21.9.md @@ -0,0 +1,240 @@ +--- +title: Version 21.9 +--- + +# Version 21.9 + +.. toc:: + +## Introduction + +This is the third release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Removal of config values: `WEBSOCKET_READ_LIMIT`, `WEBSOCKET_WRITE_LIMIT` and `WEBSOCKET_MAX_QUEUE` + +With the complete overhaul of the websocket implementation, these configuration values were removed. There currently is not a plan to replace them. + +### Deprecation of default value of `FALLBACK_ERROR_FORMAT` + +When no error handler is attached, Sanic has used `html` as the fallback format-type. This has been deprecated and will change to `text` starting in v22.3. While the value of this has changed to `auto`, it will still continue to use HTML as the last resort thru v21.12LTS before changing. + +### `ErrorHandler.lookup` signature deprecation + +The `ErrorHandler.lookup` now **requires** two positional arguments: + +```python +def lookup(self, exception, route_name: Optional[str]): +``` + +A non-conforming method will cause Blueprint-specific exception handlers to not properly attach. + +### Reminder of upcoming removals + +As a reminder, the following items have already been deprecated, and will be removed in version 21.12LTS + +- `CompositionView` +- `load_env` (use `env_prefix` instead) +- Sanic objects (application instances, blueprints, and routes) must by alphanumeric conforming to: `^[a-zA-Z][a-zA-Z0-9_\-]*$` +- Arbitrary assignment of objects to application and blueprint instances (use `ctx` instead; removal of this has been bumped from 21.9 to 21.12) + +### Overhaul of websockets + +There has been a huge overhaul to the handling of websocket connections. Thanks to [@aaugustin](https://github.com/aaugustin) the [`websockets`](https://websockets.readthedocs.io/en/stable/index.html) now has a new implementation that allows Sanic to handle the I/O of websocket connections on its own. Therefore, Sanic has bumped the minimum version to `websockets>=10.0`. + +The change should mostly be unnoticeable to developers, except that some of the oddities around websocket handlers in Sanic have been corrected. For example, you now should be able to catch the `CancellError` yourself when someone disconnects: + +```python +@app.websocket("/") +async def handler(request, ws): + try: + while True: + await asyncio.sleep(0.25) + except asyncio.CancelledError: + print("User closed connection") +``` + +### Built-in signals + +Version [21.3](./v21.3.md) introduced [signals](../advanced/signals.md). Now, Sanic dispatches signal events **from within the codebase** itself. This means that developers now have the ability to hook into the request/response cycle at a much closer level than before. + +Previously, if you wanted to inject some logic you were limited to middleware. Think of integrated signals as _super_-middleware. The events that are dispatched now include: + +- `http.lifecycle.begin` +- `http.lifecycle.complete` +- `http.lifecycle.exception` +- `http.lifecycle.handle` +- `http.lifecycle.read_body` +- `http.lifecycle.read_head` +- `http.lifecycle.request` +- `http.lifecycle.response` +- `http.lifecycle.send` +- `http.middleware.after` +- `http.middleware.before` +- `http.routing.after` +- `http.routing.before` +- `server.init.after` +- `server.init.before` +- `server.shutdown.after` +- `server.shutdown.before` + +.. note:: + +``` +The `server` signals are the same as the four (4) main server listener events. In fact, those listeners themselves are now just convenience wrappers to signal implementations. +``` + +### Smarter `auto` exception formatting + +Sanic will now try to respond with an appropriate exception format based upon the endpoint and the client. For example, if your endpoint always returns a `sanic.response.json` object, then any exceptions will automatically be formatted in JSON. The same is true for `text` and `html` responses. + +Furthermore, you now can _explicitly_ control which formatter to use on a route-by-route basis using the route definition: + +```python +@app.route("/", error_format="json") +async def handler(request): + pass +``` + +### Blueprint copying + +Blueprints can be copied to new instances. This will carry forward everything attached to it, like routes, middleware, etc. + +```python +v1 = Blueprint("Version1", version=1) + +@v1.route("/something") +def something(request): + pass + +v2 = v1.copy("Version2", version=2) + +app.blueprint(v1) +app.blueprint(v2) +``` + +``` +/v1/something +/v2/something +``` + +### Blueprint group convenience methods + +Blueprint groups should now have all of the same methods available to them as regular Blueprints. With this, along with Blueprint copying, Blueprints should now be very composable and flexible. + +### Accept header parsing + +Sanic `Request` objects can parse an `Accept` header to provide an ordered list of the client's content-type preference. You can simply access it as an accessor: + +```python +print(request.accept) +# ["*/*"] +``` + +It also is capable of handling wildcard matching. For example, assuming the incoming request included: + +``` +Accept: */* +``` + +Then, the following is `True`: + +```python +"text/plain" in request.accept +``` + +### Default exception messages + +Any exception that derives from `SanicException` can now define a default exception message. This makes it more convenient and maintainable to reuse the same exception in multiple places without running into DRY issues with the message that the exception provides. + +```python +class TeaError(SanicException): + message = "Tempest in a teapot" + +raise TeaError +``` + +### Type annotation conveniences + +It is now possible to control the path parameter types using Python's type annotations. Instead of doing this: + +```python +@app.route("///") +def handler(request: Request, one: int, two: float, three: UUID): + ... +``` + +You can now simply do this: + +```python +@app.route("///") +def handler(request: Request, one: int, two: float, three: UUID): + ... +``` + +Both of these examples will result in the same routing principles to be applied. + +### Explicit static resource type + +You can now explicitly tell a `static` endpoint whether it is supposed to treat the resource as a file or a directory: + +```python +static("/", "/path/to/some/file", resource_type="file")) +``` + +## News + +### Release of `sanic-ext` and deprecation of `sanic-openapi` + +One of the core principles of Sanic is that it is meant to be a tool, not a dictator. As the frontpage of this website states: + +> Build the way you want to build without letting your tooling constrain you. + +This means that a lot of common features used (specifically by Web API developers) do not exist in the `sanic` repository. This is for good reason. Being unopinionated provides the developer freedom and flexibility. + +But, sometimes you do not want to have to build and rebuild the same things. Sanic has until now really relied upon the awesome support of the community to fill in the gaps with plugins. + +From the early days, there has been an official `sanic-openapi` package that offered the ability to create OpenAPI documentation based upon your application. But, that project has been plagued over the years and has not been given as much priority as the main project. + +Starting with the release of v21.9, the SCO is deprecating the `sanic-openapi` package and moving it to maintenance mode. This means that it will continue to get updates as needed to maintain it for the current future, but it will not receive any new feature enhancements. + +A new project called `sanic-ext` is taking its place. This package provides not only the ability to build OAS3 documentation, but fills in many of the gaps that API developers may want in their applications. For example, out of the box it will setup CORS, and auto enable `HEAD` and `OPTIONS` responses where needed. It also has the ability validate incoming data using either standard library Dataclasses or Pydantic models. + +The list of goodies includes: + +- CORS protection +- incoming request validation +- auto OAS3 documentation using Redoc and/or Swagger UI +- auto `HEAD`, `OPTIONS`, and `TRACE` responses +- dependency injection +- response serialization + +This project is still in `alpha` mode for now and is subject to change. While it is considered to be production capable, there may be some need to change the API as we continue to add features. + +Checkout the [documentation](../../plugins/sanic-ext/getting-started.md) for more details. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@cansarigol3megawatt](https://github.com/cansarigol3megawatt) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@gluhar2006](https://github.com/gluhar2006) +[@komar007](https://github.com/komar007) +[@ombe1229](https://github.com/ombe1229) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@Tronic](https://github.com/tronic) +[@vltr](https://github.com/vltr) + +And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From dd623cb6120bb38c7e0f5f7e51c6f51a390e5260 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:26 +0200 Subject: [PATCH 250/698] New translations v22.12.md (Japanese) --- guide/content/ja/release-notes/2022/v22.12.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 guide/content/ja/release-notes/2022/v22.12.md diff --git a/guide/content/ja/release-notes/2022/v22.12.md b/guide/content/ja/release-notes/2022/v22.12.md new file mode 100644 index 0000000000..0134d40494 --- /dev/null +++ b/guide/content/ja/release-notes/2022/v22.12.md @@ -0,0 +1,190 @@ +--- +title: Version 22.12 (LTS) +--- + +# Version 22.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 22 [release cycle](../../org/policies.md#release-schedule). As such it is a **long-term support** release, and will be supported as stated in the [policies](../../org/policies.md#long-term-support-v-interim-releases). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### 🚨 _BREAKING CHANGE_ - Sanic Inspector is now an HTTP server + +Sanic v22.9 introduced the [Inspector](./v22.9.md#inspector) to allow live inspection of a running Sanic instance. This feature relied upon opening a TCP socket and communicating over a custom protocol. That basic TCP protocol has been dropped in favor of running a full HTTP service in its place. [Learn more about the Inspector](../deployment/inspector.md). + +The current release introduces a new HTTP server and a refreshed CLI experience. This enables several new features highlighted here. Perhaps the most significant change, however, is to move all of the Inspector's commands to a subparser on the CLI instance. + +``` +$ sanic inspect --help + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + +Optional +======== + General: + -h, --help show this help message and exit + --host HOST, -H HOST Inspector host address [default 127.0.0.1] + --port PORT, -p PORT Inspector port [default 6457] + --secure, -s Whether to access the Inspector via TLS encryption + --api-key API_KEY, -k API_KEY Inspector authentication key + --raw Whether to output the raw response information + + Subcommands: + Run one or none of the below subcommands. Using inspect without a subcommand will fetch general information about the state of the application instance. + + Or, you can optionally follow inspect with a subcommand. If you have created a custom Inspector instance, then you can run custom commands. See https://sanic.dev/en/guide/deployment/inspector.html for more details. + + {reload,shutdown,scale,} + reload Trigger a reload of the server workers + shutdown Shutdown the application and all processes + scale Scale the number of workers + Run a custom command +``` + +#### CLI remote access now available + +The `host` and `port` of the Inspector are now explicitly exposed on the CLI as shown above. Previously in v22.9, they were inferred by reference to the application instance. Because of this change, it will be more possible to expose the Inspector on live production instances and access from a remote installation of the CLI. + +For example, you can check your running production deployment from your local development machine. + +``` +$ sanic inspect --host=1.2.3.4 +``` + +.. warning:: + +``` +For **production** instances, make sure you are _using TLS and authentication_ described below. +``` + +#### TLS encryption now available + +You can secure your remote Inspector access by providing a TLS certificate to encrypt the web traffic. + +```python +app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" +app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" +``` + +To access an encrypted installation via the CLI, use the `--secure` flag. + +``` +$ sanic inspect --secure +``` + +#### Authentication now available + +To control access to the remote Inspector, you can protect the endpoints using an API key. + +```python +app.config.INSPECTOR_API_KEY = "Super-Secret-200" +``` + +To access a protected installation via the CLI, use the `--api-key` flag. + +``` +$ sanic inspect --api-key=Super-Secret-200 +``` + +This is equivalent to the header: `Authorization: Bearer `. + +``` +$ curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +``` + +### Scale number of running server workers + +The Inspector is now capable of scaling the number of worker processes. For example, to scale to 3 replicas, use the following command: + +``` +$ sanic inspect scale 3 +``` + +### Extend Inspector with custom commands + +The Inspector is now fully extendable to allow for adding custom commands to the CLI. For more information see [Custom Commands](../deployment/inspector.md#custom-commands). + +``` +$ sanic inspect foo --bar +``` + +### Early worker exit on failure + +The process manager shipped with v22.9 had a very short startup timeout. This was to protect against deadlock. This was increased to 30s, and a new mechanism has been added to fail early if there is a crash in a worker process on startup. + +### Introduce `JSONResponse` with convenience methods to update a JSON response body + +The `sanic.response.json` convenience method now returns a new subclass of `HTTPResponse` appropriately named: `JSONResponse`. This new type has some convenient methods for handling changes to a response body after its creation. + +```python +resp = json({"foo": "bar"}) +resp.update({"another": "value"}) +``` + +See [Returning JSON Data](../basics/response.md#returning-json-data) for more information. + +### Updates to downstream requirements: `uvloop` and `websockets` + +Minimum `uvloop` was set to `0.15.0`. Changes were added to make Sanic compliant with `websockets` version `11.0`. + +### Force exit on 2nd `ctrl+c` + +On supporting operating systems, the existing behavior is for Sanic server to try to perform a graceful shutdown when hitting `ctrl+c`. This new release will perform an immediate shutdown on subsequent `ctrl+c` after the initial shutdown has begun. + +### Deprecations and Removals + +1. _DEPRECATED_ - The `--inspect*` commands introduced in v22.9 have been replaced with a new subcommand parser available as `inspect`. The flag versions will continue to operate until v23.3. You are encouraged to use the replacements. While this short deprecation period is a deviation from the standard two-cycles, we hope this change will be minimally disruptive. + ``` + OLD sanic ... --inspect + NEW sanic ... inspect + + OLD sanic ... --inspect-raw + NEW sanic ... inspect --raw + + OLD sanic ... --inspect-reload + NEW sanic ... inspect reload + + OLD sanic ... --inspect-shutdown + NEW sanic ... inspect shutdown + ``` + +## News + +The Sanic Community Organization will be headed by a new Steering Council for 2023. There are two returning and two new members. + +[@ahopkins](https://github.com/ahopkins) _returning_ \ +[@prryplatypus](https://github.com/prryplatypus) _returning_ \ +[@sjsadowski](https://github.com/sjsadowski) _NEW_ \ +[@Tronic](https://github.com/Tronic) _NEW_ + +The 2023 release managers are [@ahopkins](https://github.com/ahopkins) and [@sjsadowski](https://github.com/sjsadowski). + +If you are interested in getting more involved with Sanic, contact us on the [Discord server](https://discord.gg/FARQzAEMAA). + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@kijk2869](https://github.com/kijk2869) +[@LiraNuna](https://github.com/LiraNuna) +[@prryplatypus](https://github.com/prryplatypus) +[@sjsadowski](https://github.com/sjsadowski) +[@todddialpad](https://github.com/todddialpad) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From c5750b35cc4361c997a5a47c7bfec2d117702012 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:27 +0200 Subject: [PATCH 251/698] New translations v22.12.md (Korean) --- guide/content/ko/release-notes/2022/v22.12.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 guide/content/ko/release-notes/2022/v22.12.md diff --git a/guide/content/ko/release-notes/2022/v22.12.md b/guide/content/ko/release-notes/2022/v22.12.md new file mode 100644 index 0000000000..0134d40494 --- /dev/null +++ b/guide/content/ko/release-notes/2022/v22.12.md @@ -0,0 +1,190 @@ +--- +title: Version 22.12 (LTS) +--- + +# Version 22.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 22 [release cycle](../../org/policies.md#release-schedule). As such it is a **long-term support** release, and will be supported as stated in the [policies](../../org/policies.md#long-term-support-v-interim-releases). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### 🚨 _BREAKING CHANGE_ - Sanic Inspector is now an HTTP server + +Sanic v22.9 introduced the [Inspector](./v22.9.md#inspector) to allow live inspection of a running Sanic instance. This feature relied upon opening a TCP socket and communicating over a custom protocol. That basic TCP protocol has been dropped in favor of running a full HTTP service in its place. [Learn more about the Inspector](../deployment/inspector.md). + +The current release introduces a new HTTP server and a refreshed CLI experience. This enables several new features highlighted here. Perhaps the most significant change, however, is to move all of the Inspector's commands to a subparser on the CLI instance. + +``` +$ sanic inspect --help + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + +Optional +======== + General: + -h, --help show this help message and exit + --host HOST, -H HOST Inspector host address [default 127.0.0.1] + --port PORT, -p PORT Inspector port [default 6457] + --secure, -s Whether to access the Inspector via TLS encryption + --api-key API_KEY, -k API_KEY Inspector authentication key + --raw Whether to output the raw response information + + Subcommands: + Run one or none of the below subcommands. Using inspect without a subcommand will fetch general information about the state of the application instance. + + Or, you can optionally follow inspect with a subcommand. If you have created a custom Inspector instance, then you can run custom commands. See https://sanic.dev/en/guide/deployment/inspector.html for more details. + + {reload,shutdown,scale,} + reload Trigger a reload of the server workers + shutdown Shutdown the application and all processes + scale Scale the number of workers + Run a custom command +``` + +#### CLI remote access now available + +The `host` and `port` of the Inspector are now explicitly exposed on the CLI as shown above. Previously in v22.9, they were inferred by reference to the application instance. Because of this change, it will be more possible to expose the Inspector on live production instances and access from a remote installation of the CLI. + +For example, you can check your running production deployment from your local development machine. + +``` +$ sanic inspect --host=1.2.3.4 +``` + +.. warning:: + +``` +For **production** instances, make sure you are _using TLS and authentication_ described below. +``` + +#### TLS encryption now available + +You can secure your remote Inspector access by providing a TLS certificate to encrypt the web traffic. + +```python +app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" +app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" +``` + +To access an encrypted installation via the CLI, use the `--secure` flag. + +``` +$ sanic inspect --secure +``` + +#### Authentication now available + +To control access to the remote Inspector, you can protect the endpoints using an API key. + +```python +app.config.INSPECTOR_API_KEY = "Super-Secret-200" +``` + +To access a protected installation via the CLI, use the `--api-key` flag. + +``` +$ sanic inspect --api-key=Super-Secret-200 +``` + +This is equivalent to the header: `Authorization: Bearer `. + +``` +$ curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +``` + +### Scale number of running server workers + +The Inspector is now capable of scaling the number of worker processes. For example, to scale to 3 replicas, use the following command: + +``` +$ sanic inspect scale 3 +``` + +### Extend Inspector with custom commands + +The Inspector is now fully extendable to allow for adding custom commands to the CLI. For more information see [Custom Commands](../deployment/inspector.md#custom-commands). + +``` +$ sanic inspect foo --bar +``` + +### Early worker exit on failure + +The process manager shipped with v22.9 had a very short startup timeout. This was to protect against deadlock. This was increased to 30s, and a new mechanism has been added to fail early if there is a crash in a worker process on startup. + +### Introduce `JSONResponse` with convenience methods to update a JSON response body + +The `sanic.response.json` convenience method now returns a new subclass of `HTTPResponse` appropriately named: `JSONResponse`. This new type has some convenient methods for handling changes to a response body after its creation. + +```python +resp = json({"foo": "bar"}) +resp.update({"another": "value"}) +``` + +See [Returning JSON Data](../basics/response.md#returning-json-data) for more information. + +### Updates to downstream requirements: `uvloop` and `websockets` + +Minimum `uvloop` was set to `0.15.0`. Changes were added to make Sanic compliant with `websockets` version `11.0`. + +### Force exit on 2nd `ctrl+c` + +On supporting operating systems, the existing behavior is for Sanic server to try to perform a graceful shutdown when hitting `ctrl+c`. This new release will perform an immediate shutdown on subsequent `ctrl+c` after the initial shutdown has begun. + +### Deprecations and Removals + +1. _DEPRECATED_ - The `--inspect*` commands introduced in v22.9 have been replaced with a new subcommand parser available as `inspect`. The flag versions will continue to operate until v23.3. You are encouraged to use the replacements. While this short deprecation period is a deviation from the standard two-cycles, we hope this change will be minimally disruptive. + ``` + OLD sanic ... --inspect + NEW sanic ... inspect + + OLD sanic ... --inspect-raw + NEW sanic ... inspect --raw + + OLD sanic ... --inspect-reload + NEW sanic ... inspect reload + + OLD sanic ... --inspect-shutdown + NEW sanic ... inspect shutdown + ``` + +## News + +The Sanic Community Organization will be headed by a new Steering Council for 2023. There are two returning and two new members. + +[@ahopkins](https://github.com/ahopkins) _returning_ \ +[@prryplatypus](https://github.com/prryplatypus) _returning_ \ +[@sjsadowski](https://github.com/sjsadowski) _NEW_ \ +[@Tronic](https://github.com/Tronic) _NEW_ + +The 2023 release managers are [@ahopkins](https://github.com/ahopkins) and [@sjsadowski](https://github.com/sjsadowski). + +If you are interested in getting more involved with Sanic, contact us on the [Discord server](https://discord.gg/FARQzAEMAA). + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@kijk2869](https://github.com/kijk2869) +[@LiraNuna](https://github.com/LiraNuna) +[@prryplatypus](https://github.com/prryplatypus) +[@sjsadowski](https://github.com/sjsadowski) +[@todddialpad](https://github.com/todddialpad) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 50cef0029f51a246bc34c7609db847b6f141f31d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:29 +0200 Subject: [PATCH 252/698] New translations v22.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.12.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 guide/content/zh/release-notes/2022/v22.12.md diff --git a/guide/content/zh/release-notes/2022/v22.12.md b/guide/content/zh/release-notes/2022/v22.12.md new file mode 100644 index 0000000000..0134d40494 --- /dev/null +++ b/guide/content/zh/release-notes/2022/v22.12.md @@ -0,0 +1,190 @@ +--- +title: Version 22.12 (LTS) +--- + +# Version 22.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 22 [release cycle](../../org/policies.md#release-schedule). As such it is a **long-term support** release, and will be supported as stated in the [policies](../../org/policies.md#long-term-support-v-interim-releases). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### 🚨 _BREAKING CHANGE_ - Sanic Inspector is now an HTTP server + +Sanic v22.9 introduced the [Inspector](./v22.9.md#inspector) to allow live inspection of a running Sanic instance. This feature relied upon opening a TCP socket and communicating over a custom protocol. That basic TCP protocol has been dropped in favor of running a full HTTP service in its place. [Learn more about the Inspector](../deployment/inspector.md). + +The current release introduces a new HTTP server and a refreshed CLI experience. This enables several new features highlighted here. Perhaps the most significant change, however, is to move all of the Inspector's commands to a subparser on the CLI instance. + +``` +$ sanic inspect --help + + ▄███ █████ ██ ▄█▄ ██ █ █ ▄██████████ + ██ █ █ █ ██ █ █ ██ + ▀███████ ███▄ ▀ █ █ ██ ▄ █ ██ + ██ █████████ █ ██ █ █ ▄▄ + ████ ████████▀ █ █ █ ██ █ ▀██ ███████ + +Optional +======== + General: + -h, --help show this help message and exit + --host HOST, -H HOST Inspector host address [default 127.0.0.1] + --port PORT, -p PORT Inspector port [default 6457] + --secure, -s Whether to access the Inspector via TLS encryption + --api-key API_KEY, -k API_KEY Inspector authentication key + --raw Whether to output the raw response information + + Subcommands: + Run one or none of the below subcommands. Using inspect without a subcommand will fetch general information about the state of the application instance. + + Or, you can optionally follow inspect with a subcommand. If you have created a custom Inspector instance, then you can run custom commands. See https://sanic.dev/en/guide/deployment/inspector.html for more details. + + {reload,shutdown,scale,} + reload Trigger a reload of the server workers + shutdown Shutdown the application and all processes + scale Scale the number of workers + Run a custom command +``` + +#### CLI remote access now available + +The `host` and `port` of the Inspector are now explicitly exposed on the CLI as shown above. Previously in v22.9, they were inferred by reference to the application instance. Because of this change, it will be more possible to expose the Inspector on live production instances and access from a remote installation of the CLI. + +For example, you can check your running production deployment from your local development machine. + +``` +$ sanic inspect --host=1.2.3.4 +``` + +.. warning:: + +``` +For **production** instances, make sure you are _using TLS and authentication_ described below. +``` + +#### TLS encryption now available + +You can secure your remote Inspector access by providing a TLS certificate to encrypt the web traffic. + +```python +app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" +app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" +``` + +To access an encrypted installation via the CLI, use the `--secure` flag. + +``` +$ sanic inspect --secure +``` + +#### Authentication now available + +To control access to the remote Inspector, you can protect the endpoints using an API key. + +```python +app.config.INSPECTOR_API_KEY = "Super-Secret-200" +``` + +To access a protected installation via the CLI, use the `--api-key` flag. + +``` +$ sanic inspect --api-key=Super-Secret-200 +``` + +This is equivalent to the header: `Authorization: Bearer `. + +``` +$ curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +``` + +### Scale number of running server workers + +The Inspector is now capable of scaling the number of worker processes. For example, to scale to 3 replicas, use the following command: + +``` +$ sanic inspect scale 3 +``` + +### Extend Inspector with custom commands + +The Inspector is now fully extendable to allow for adding custom commands to the CLI. For more information see [Custom Commands](../deployment/inspector.md#custom-commands). + +``` +$ sanic inspect foo --bar +``` + +### Early worker exit on failure + +The process manager shipped with v22.9 had a very short startup timeout. This was to protect against deadlock. This was increased to 30s, and a new mechanism has been added to fail early if there is a crash in a worker process on startup. + +### Introduce `JSONResponse` with convenience methods to update a JSON response body + +The `sanic.response.json` convenience method now returns a new subclass of `HTTPResponse` appropriately named: `JSONResponse`. This new type has some convenient methods for handling changes to a response body after its creation. + +```python +resp = json({"foo": "bar"}) +resp.update({"another": "value"}) +``` + +See [Returning JSON Data](../basics/response.md#returning-json-data) for more information. + +### Updates to downstream requirements: `uvloop` and `websockets` + +Minimum `uvloop` was set to `0.15.0`. Changes were added to make Sanic compliant with `websockets` version `11.0`. + +### Force exit on 2nd `ctrl+c` + +On supporting operating systems, the existing behavior is for Sanic server to try to perform a graceful shutdown when hitting `ctrl+c`. This new release will perform an immediate shutdown on subsequent `ctrl+c` after the initial shutdown has begun. + +### Deprecations and Removals + +1. _DEPRECATED_ - The `--inspect*` commands introduced in v22.9 have been replaced with a new subcommand parser available as `inspect`. The flag versions will continue to operate until v23.3. You are encouraged to use the replacements. While this short deprecation period is a deviation from the standard two-cycles, we hope this change will be minimally disruptive. + ``` + OLD sanic ... --inspect + NEW sanic ... inspect + + OLD sanic ... --inspect-raw + NEW sanic ... inspect --raw + + OLD sanic ... --inspect-reload + NEW sanic ... inspect reload + + OLD sanic ... --inspect-shutdown + NEW sanic ... inspect shutdown + ``` + +## News + +The Sanic Community Organization will be headed by a new Steering Council for 2023. There are two returning and two new members. + +[@ahopkins](https://github.com/ahopkins) _returning_ \ +[@prryplatypus](https://github.com/prryplatypus) _returning_ \ +[@sjsadowski](https://github.com/sjsadowski) _NEW_ \ +[@Tronic](https://github.com/Tronic) _NEW_ + +The 2023 release managers are [@ahopkins](https://github.com/ahopkins) and [@sjsadowski](https://github.com/sjsadowski). + +If you are interested in getting more involved with Sanic, contact us on the [Discord server](https://discord.gg/FARQzAEMAA). + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aaugustin](https://github.com/aaugustin) +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@kijk2869](https://github.com/kijk2869) +[@LiraNuna](https://github.com/LiraNuna) +[@prryplatypus](https://github.com/prryplatypus) +[@sjsadowski](https://github.com/sjsadowski) +[@todddialpad](https://github.com/todddialpad) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 2d1d5c6d9a9f5a2586481dd9303ad679daf0a7f6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:30 +0200 Subject: [PATCH 253/698] New translations v22.3.md (Japanese) --- guide/content/ja/release-notes/2022/v22.3.md | 230 +++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 guide/content/ja/release-notes/2022/v22.3.md diff --git a/guide/content/ja/release-notes/2022/v22.3.md b/guide/content/ja/release-notes/2022/v22.3.md new file mode 100644 index 0000000000..90efaa047d --- /dev/null +++ b/guide/content/ja/release-notes/2022/v22.3.md @@ -0,0 +1,230 @@ +--- +title: Version 22.3 +--- + +# Version 22.3 + +.. toc:: + +## Introduction + +This is the first release of the version 22 [release cycle](../../org/policies.md#release-schedule). All of the standard SCO libraries are now entering the same release cycle and will follow the same versioning pattern. Those packages are: + +- [`sanic-routing`](https://github.com/sanic-org/sanic-routing) +- [`sanic-testing`](https://github.com/sanic-org/sanic-testing) +- [`sanic-ext`](https://github.com/sanic-org/sanic-ext) + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Application multi-serve + +The Sanic server now has an API to allow you to run multiple applications side-by-side in the same process. This is done by calling `app.prepare(...)` on one or more application instances, one or many times. Each time it should be bound to a unique host/port combination. Then, you begin serving the applications by calling `Sanic.serve()`. + +```python +app = Sanic("One") +app2 = Sanic("Two") + +app.prepare(port=9999) +app.prepare(port=9998) +app.prepare(port=9997) +app2.prepare(port=8888) +app2.prepare(port=8887) + +Sanic.serve() +``` + +In the above snippet, there are two applications that will be run concurrently and bound to multiple ports. This feature is _not_ supported in the CLI. + +This pattern is meant to be an alternative to running `app.run(...)`. It should be noted that `app.run` is now just a shorthand for the above pattern and is still fully supported. + +### 👶 _BETA FEATURE_ - New path parameter type: file extensions + +A very common pattern is to create a route that dynamically generates a file. The endpoint is meant to match on a file with an extension. There is a new path parameter to match files: ``. + +```python +@app.get("/path/to/") +async def handler(request, filename, ext): + ... +``` + +This will catch any pattern that ends with a file extension. You may, however want to expand this by specifying which extensions, and also by using other path parameter types for the file name. + +For example, if you want to catch a `.jpg` file that is only numbers: + +```python +@app.get("/path/to/") +async def handler(request, filename, ext): + ... +``` + +Some potential examples: + +| definition | example | filename | extension | +| ---------------------------------- | ----------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | + +### 🚨 _BREAKING CHANGE_ - Path parameter matching of non-empty strings + +A dynamic path parameter will only match on a non-empty string. + +Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now only match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. + +```python +@app.get("/path/to/") +async def handler(request, foo) + ... +``` + +### 🚨 _BREAKING CHANGE_ - `sanic.worker.GunicornWorker` has been removed + +Departing from our normal deprecation policy, the `GunicornWorker` was removed as a part of the process of upgrading the Sanic server to include multi-serve. This decision was made largely in part because even while it existed it was not an optimal strategy for deploying Sanic. + +If you want to deploy Sanic using `gunicorn`, then you are advised to do it using [the strategy implemented by `uvicorn`](https://www.uvicorn.org/#running-with-gunicorn). This will effectively run Sanic as an ASGI application through `uvicorn`. You can upgrade to this pattern by installing `uvicorn`: + +``` +pip install uvicorn +``` + +Then, you should be able to run it with a pattern like this: + +``` +gunicorn path.to.sanic:app -k uvicorn.workers.UvicornWorker +``` + +### Authorization header parsing + +The `Authorization` header has been partially parseable for some time now. You have been able to use `request.token` to gain access to a header that was in one of the following two forms: + +``` +Authorization: Token +Authorization: Bearer +``` + +Sanic can now parse more credential types like `BASIC`: + +``` +Authorization: Basic Z2lsLWJhdGVzOnBhc3N3b3JkMTIz +``` + +This can be accessed now as `request.credentials`: + +```python +print(request.credentials) +# Credentials(auth_type='Basic', token='Z2lsLWJhdGVzOnBhc3N3b3JkMTIz', _username='gil-bates', _password='password123') +``` + +### CLI arguments optionally injected into application factory + +Sanic will now attempt to inject the parsed CLI arguments into your factory if you are using one. + +```python +def create_app(args): + app = Sanic("MyApp") + print(args) + return app +``` + +``` +$sanic p:create_app --factory +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False) +``` + +If you are running the CLI with `--factory`, you also have the option of passing arbitrary arguments to the command, which will be injected into the argument `Namespace`. + +``` +sanic p:create_app --factory --foo=bar +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False, foo='bar') +``` + +### New reloader process listener events + +When running Sanic server with auto-reload, there are two new events that trigger a listener _only_ on the reloader process: + +- `reload_process_start` +- `reload_process_stop` + +These are only triggered if the reloader is running. + +```python +@app.reload_process_start +async def reload_start(*_): + print(">>>>>> reload_start <<<<<<") + +@app.reload_process_stop +async def reload_stop(*_): + print(">>>>>> reload_stop <<<<<<") +``` + +### The event loop is no longer a required argument of a listener + +You can leave out the `loop` argument of a listener. Both of these examples work as expected: + +```python +@app.before_server_start +async def without(app): + ... + +@app.before_server_start +async def with(app, loop): + ... +``` + +### Removal - Debug mode does not automatically start the reloader + +When running with `--debug` or `debug=True`, the Sanic server will not automatically start the auto-reloader. This feature of doing both on debug was deprecated in v21 and removed in this release. If you would like to have _both_ debug mode and auto-reload, you can use `--dev` or `dev=True`. + +**dev = debug mode + auto reloader** + +### Deprecation - Loading of lower case environment variables + +Sanic loads prefixed environment variables as configuration values. It has not distinguished between uppercase and lowercase as long as the prefix matches. However, it has always been the convention that the keys should be uppercase. This is deprecated and you will receive a warning if the value is not uppercase. In v22.9 only uppercase and prefixed keys will be loaded. + +## News + +### Packt publishes new book on Sanic web development + +.. column:: + +``` +There is a new book on **Python Web Development with Sanic** by [@ahopkins](https://github.com/ahopkins). The book is endorsed by the SCO and part of the proceeds of all sales go directly to the SCO for further development of Sanic. + +You can learn more at [sanicbook.com](https://sanicbook.com/) +``` + +.. column:: + +``` +![Python Web Development with Sanic](https://sanicbook.com/images/SanicCoverFinal.png) +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aericson](https://github.com/aericson) +[@ahankinson](https://github.com/ahankinson) +[@ahopkins](https://github.com/ahopkins) +[@ariebovenberg](https://github.com/ariebovenberg) +[@ashleysommer](https://github.com/ashleysommer) +[@Bluenix2](https://github.com/Bluenix2) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@dotlambda](https://github.com/dotlambda) +[@eric-spitler](https://github.com/eric-spitler) +[@howzitcdf](https://github.com/howzitcdf) +[@jonra1993](https://github.com/jonra1993) +[@prryplatypus](https://github.com/prryplatypus) +[@raphaelauv](https://github.com/raphaelauv) +[@SaidBySolo](https://github.com/SaidBySolo) +[@SerGeRybakov](https://github.com/SerGeRybakov) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From fcccdab48c63587182da2dc04b11b425467f8cb7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:31 +0200 Subject: [PATCH 254/698] New translations v22.3.md (Korean) --- guide/content/ko/release-notes/2022/v22.3.md | 230 +++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 guide/content/ko/release-notes/2022/v22.3.md diff --git a/guide/content/ko/release-notes/2022/v22.3.md b/guide/content/ko/release-notes/2022/v22.3.md new file mode 100644 index 0000000000..90efaa047d --- /dev/null +++ b/guide/content/ko/release-notes/2022/v22.3.md @@ -0,0 +1,230 @@ +--- +title: Version 22.3 +--- + +# Version 22.3 + +.. toc:: + +## Introduction + +This is the first release of the version 22 [release cycle](../../org/policies.md#release-schedule). All of the standard SCO libraries are now entering the same release cycle and will follow the same versioning pattern. Those packages are: + +- [`sanic-routing`](https://github.com/sanic-org/sanic-routing) +- [`sanic-testing`](https://github.com/sanic-org/sanic-testing) +- [`sanic-ext`](https://github.com/sanic-org/sanic-ext) + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Application multi-serve + +The Sanic server now has an API to allow you to run multiple applications side-by-side in the same process. This is done by calling `app.prepare(...)` on one or more application instances, one or many times. Each time it should be bound to a unique host/port combination. Then, you begin serving the applications by calling `Sanic.serve()`. + +```python +app = Sanic("One") +app2 = Sanic("Two") + +app.prepare(port=9999) +app.prepare(port=9998) +app.prepare(port=9997) +app2.prepare(port=8888) +app2.prepare(port=8887) + +Sanic.serve() +``` + +In the above snippet, there are two applications that will be run concurrently and bound to multiple ports. This feature is _not_ supported in the CLI. + +This pattern is meant to be an alternative to running `app.run(...)`. It should be noted that `app.run` is now just a shorthand for the above pattern and is still fully supported. + +### 👶 _BETA FEATURE_ - New path parameter type: file extensions + +A very common pattern is to create a route that dynamically generates a file. The endpoint is meant to match on a file with an extension. There is a new path parameter to match files: ``. + +```python +@app.get("/path/to/") +async def handler(request, filename, ext): + ... +``` + +This will catch any pattern that ends with a file extension. You may, however want to expand this by specifying which extensions, and also by using other path parameter types for the file name. + +For example, if you want to catch a `.jpg` file that is only numbers: + +```python +@app.get("/path/to/") +async def handler(request, filename, ext): + ... +``` + +Some potential examples: + +| definition | example | filename | extension | +| ---------------------------------- | ----------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | + +### 🚨 _BREAKING CHANGE_ - Path parameter matching of non-empty strings + +A dynamic path parameter will only match on a non-empty string. + +Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now only match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. + +```python +@app.get("/path/to/") +async def handler(request, foo) + ... +``` + +### 🚨 _BREAKING CHANGE_ - `sanic.worker.GunicornWorker` has been removed + +Departing from our normal deprecation policy, the `GunicornWorker` was removed as a part of the process of upgrading the Sanic server to include multi-serve. This decision was made largely in part because even while it existed it was not an optimal strategy for deploying Sanic. + +If you want to deploy Sanic using `gunicorn`, then you are advised to do it using [the strategy implemented by `uvicorn`](https://www.uvicorn.org/#running-with-gunicorn). This will effectively run Sanic as an ASGI application through `uvicorn`. You can upgrade to this pattern by installing `uvicorn`: + +``` +pip install uvicorn +``` + +Then, you should be able to run it with a pattern like this: + +``` +gunicorn path.to.sanic:app -k uvicorn.workers.UvicornWorker +``` + +### Authorization header parsing + +The `Authorization` header has been partially parseable for some time now. You have been able to use `request.token` to gain access to a header that was in one of the following two forms: + +``` +Authorization: Token +Authorization: Bearer +``` + +Sanic can now parse more credential types like `BASIC`: + +``` +Authorization: Basic Z2lsLWJhdGVzOnBhc3N3b3JkMTIz +``` + +This can be accessed now as `request.credentials`: + +```python +print(request.credentials) +# Credentials(auth_type='Basic', token='Z2lsLWJhdGVzOnBhc3N3b3JkMTIz', _username='gil-bates', _password='password123') +``` + +### CLI arguments optionally injected into application factory + +Sanic will now attempt to inject the parsed CLI arguments into your factory if you are using one. + +```python +def create_app(args): + app = Sanic("MyApp") + print(args) + return app +``` + +``` +$sanic p:create_app --factory +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False) +``` + +If you are running the CLI with `--factory`, you also have the option of passing arbitrary arguments to the command, which will be injected into the argument `Namespace`. + +``` +sanic p:create_app --factory --foo=bar +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False, foo='bar') +``` + +### New reloader process listener events + +When running Sanic server with auto-reload, there are two new events that trigger a listener _only_ on the reloader process: + +- `reload_process_start` +- `reload_process_stop` + +These are only triggered if the reloader is running. + +```python +@app.reload_process_start +async def reload_start(*_): + print(">>>>>> reload_start <<<<<<") + +@app.reload_process_stop +async def reload_stop(*_): + print(">>>>>> reload_stop <<<<<<") +``` + +### The event loop is no longer a required argument of a listener + +You can leave out the `loop` argument of a listener. Both of these examples work as expected: + +```python +@app.before_server_start +async def without(app): + ... + +@app.before_server_start +async def with(app, loop): + ... +``` + +### Removal - Debug mode does not automatically start the reloader + +When running with `--debug` or `debug=True`, the Sanic server will not automatically start the auto-reloader. This feature of doing both on debug was deprecated in v21 and removed in this release. If you would like to have _both_ debug mode and auto-reload, you can use `--dev` or `dev=True`. + +**dev = debug mode + auto reloader** + +### Deprecation - Loading of lower case environment variables + +Sanic loads prefixed environment variables as configuration values. It has not distinguished between uppercase and lowercase as long as the prefix matches. However, it has always been the convention that the keys should be uppercase. This is deprecated and you will receive a warning if the value is not uppercase. In v22.9 only uppercase and prefixed keys will be loaded. + +## News + +### Packt publishes new book on Sanic web development + +.. column:: + +``` +There is a new book on **Python Web Development with Sanic** by [@ahopkins](https://github.com/ahopkins). The book is endorsed by the SCO and part of the proceeds of all sales go directly to the SCO for further development of Sanic. + +You can learn more at [sanicbook.com](https://sanicbook.com/) +``` + +.. column:: + +``` +![Python Web Development with Sanic](https://sanicbook.com/images/SanicCoverFinal.png) +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aericson](https://github.com/aericson) +[@ahankinson](https://github.com/ahankinson) +[@ahopkins](https://github.com/ahopkins) +[@ariebovenberg](https://github.com/ariebovenberg) +[@ashleysommer](https://github.com/ashleysommer) +[@Bluenix2](https://github.com/Bluenix2) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@dotlambda](https://github.com/dotlambda) +[@eric-spitler](https://github.com/eric-spitler) +[@howzitcdf](https://github.com/howzitcdf) +[@jonra1993](https://github.com/jonra1993) +[@prryplatypus](https://github.com/prryplatypus) +[@raphaelauv](https://github.com/raphaelauv) +[@SaidBySolo](https://github.com/SaidBySolo) +[@SerGeRybakov](https://github.com/SerGeRybakov) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From afd1b0af9d7391a2f348b64d775a27a475fef2b6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:32 +0200 Subject: [PATCH 255/698] New translations v22.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.3.md | 230 +++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 guide/content/zh/release-notes/2022/v22.3.md diff --git a/guide/content/zh/release-notes/2022/v22.3.md b/guide/content/zh/release-notes/2022/v22.3.md new file mode 100644 index 0000000000..90efaa047d --- /dev/null +++ b/guide/content/zh/release-notes/2022/v22.3.md @@ -0,0 +1,230 @@ +--- +title: Version 22.3 +--- + +# Version 22.3 + +.. toc:: + +## Introduction + +This is the first release of the version 22 [release cycle](../../org/policies.md#release-schedule). All of the standard SCO libraries are now entering the same release cycle and will follow the same versioning pattern. Those packages are: + +- [`sanic-routing`](https://github.com/sanic-org/sanic-routing) +- [`sanic-testing`](https://github.com/sanic-org/sanic-testing) +- [`sanic-ext`](https://github.com/sanic-org/sanic-ext) + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Application multi-serve + +The Sanic server now has an API to allow you to run multiple applications side-by-side in the same process. This is done by calling `app.prepare(...)` on one or more application instances, one or many times. Each time it should be bound to a unique host/port combination. Then, you begin serving the applications by calling `Sanic.serve()`. + +```python +app = Sanic("One") +app2 = Sanic("Two") + +app.prepare(port=9999) +app.prepare(port=9998) +app.prepare(port=9997) +app2.prepare(port=8888) +app2.prepare(port=8887) + +Sanic.serve() +``` + +In the above snippet, there are two applications that will be run concurrently and bound to multiple ports. This feature is _not_ supported in the CLI. + +This pattern is meant to be an alternative to running `app.run(...)`. It should be noted that `app.run` is now just a shorthand for the above pattern and is still fully supported. + +### 👶 _BETA FEATURE_ - New path parameter type: file extensions + +A very common pattern is to create a route that dynamically generates a file. The endpoint is meant to match on a file with an extension. There is a new path parameter to match files: ``. + +```python +@app.get("/path/to/") +async def handler(request, filename, ext): + ... +``` + +This will catch any pattern that ends with a file extension. You may, however want to expand this by specifying which extensions, and also by using other path parameter types for the file name. + +For example, if you want to catch a `.jpg` file that is only numbers: + +```python +@app.get("/path/to/") +async def handler(request, filename, ext): + ... +``` + +Some potential examples: + +| definition | example | filename | extension | +| ---------------------------------- | ----------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | + +### 🚨 _BREAKING CHANGE_ - Path parameter matching of non-empty strings + +A dynamic path parameter will only match on a non-empty string. + +Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now only match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. + +```python +@app.get("/path/to/") +async def handler(request, foo) + ... +``` + +### 🚨 _BREAKING CHANGE_ - `sanic.worker.GunicornWorker` has been removed + +Departing from our normal deprecation policy, the `GunicornWorker` was removed as a part of the process of upgrading the Sanic server to include multi-serve. This decision was made largely in part because even while it existed it was not an optimal strategy for deploying Sanic. + +If you want to deploy Sanic using `gunicorn`, then you are advised to do it using [the strategy implemented by `uvicorn`](https://www.uvicorn.org/#running-with-gunicorn). This will effectively run Sanic as an ASGI application through `uvicorn`. You can upgrade to this pattern by installing `uvicorn`: + +``` +pip install uvicorn +``` + +Then, you should be able to run it with a pattern like this: + +``` +gunicorn path.to.sanic:app -k uvicorn.workers.UvicornWorker +``` + +### Authorization header parsing + +The `Authorization` header has been partially parseable for some time now. You have been able to use `request.token` to gain access to a header that was in one of the following two forms: + +``` +Authorization: Token +Authorization: Bearer +``` + +Sanic can now parse more credential types like `BASIC`: + +``` +Authorization: Basic Z2lsLWJhdGVzOnBhc3N3b3JkMTIz +``` + +This can be accessed now as `request.credentials`: + +```python +print(request.credentials) +# Credentials(auth_type='Basic', token='Z2lsLWJhdGVzOnBhc3N3b3JkMTIz', _username='gil-bates', _password='password123') +``` + +### CLI arguments optionally injected into application factory + +Sanic will now attempt to inject the parsed CLI arguments into your factory if you are using one. + +```python +def create_app(args): + app = Sanic("MyApp") + print(args) + return app +``` + +``` +$sanic p:create_app --factory +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False) +``` + +If you are running the CLI with `--factory`, you also have the option of passing arbitrary arguments to the command, which will be injected into the argument `Namespace`. + +``` +sanic p:create_app --factory --foo=bar +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False, foo='bar') +``` + +### New reloader process listener events + +When running Sanic server with auto-reload, there are two new events that trigger a listener _only_ on the reloader process: + +- `reload_process_start` +- `reload_process_stop` + +These are only triggered if the reloader is running. + +```python +@app.reload_process_start +async def reload_start(*_): + print(">>>>>> reload_start <<<<<<") + +@app.reload_process_stop +async def reload_stop(*_): + print(">>>>>> reload_stop <<<<<<") +``` + +### The event loop is no longer a required argument of a listener + +You can leave out the `loop` argument of a listener. Both of these examples work as expected: + +```python +@app.before_server_start +async def without(app): + ... + +@app.before_server_start +async def with(app, loop): + ... +``` + +### Removal - Debug mode does not automatically start the reloader + +When running with `--debug` or `debug=True`, the Sanic server will not automatically start the auto-reloader. This feature of doing both on debug was deprecated in v21 and removed in this release. If you would like to have _both_ debug mode and auto-reload, you can use `--dev` or `dev=True`. + +**dev = debug mode + auto reloader** + +### Deprecation - Loading of lower case environment variables + +Sanic loads prefixed environment variables as configuration values. It has not distinguished between uppercase and lowercase as long as the prefix matches. However, it has always been the convention that the keys should be uppercase. This is deprecated and you will receive a warning if the value is not uppercase. In v22.9 only uppercase and prefixed keys will be loaded. + +## News + +### Packt publishes new book on Sanic web development + +.. column:: + +``` +There is a new book on **Python Web Development with Sanic** by [@ahopkins](https://github.com/ahopkins). The book is endorsed by the SCO and part of the proceeds of all sales go directly to the SCO for further development of Sanic. + +You can learn more at [sanicbook.com](https://sanicbook.com/) +``` + +.. column:: + +``` +![Python Web Development with Sanic](https://sanicbook.com/images/SanicCoverFinal.png) +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@aericson](https://github.com/aericson) +[@ahankinson](https://github.com/ahankinson) +[@ahopkins](https://github.com/ahopkins) +[@ariebovenberg](https://github.com/ariebovenberg) +[@ashleysommer](https://github.com/ashleysommer) +[@Bluenix2](https://github.com/Bluenix2) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@dotlambda](https://github.com/dotlambda) +[@eric-spitler](https://github.com/eric-spitler) +[@howzitcdf](https://github.com/howzitcdf) +[@jonra1993](https://github.com/jonra1993) +[@prryplatypus](https://github.com/prryplatypus) +[@raphaelauv](https://github.com/raphaelauv) +[@SaidBySolo](https://github.com/SaidBySolo) +[@SerGeRybakov](https://github.com/SerGeRybakov) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From a9c4736d10d909d8e2a55ad3b0074772426b31a7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:33 +0200 Subject: [PATCH 256/698] New translations v22.6.md (Japanese) --- guide/content/ja/release-notes/2022/v22.6.md | 173 +++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 guide/content/ja/release-notes/2022/v22.6.md diff --git a/guide/content/ja/release-notes/2022/v22.6.md b/guide/content/ja/release-notes/2022/v22.6.md new file mode 100644 index 0000000000..73b893c498 --- /dev/null +++ b/guide/content/ja/release-notes/2022/v22.6.md @@ -0,0 +1,173 @@ +--- +title: Version 22.6 +--- + +# Version 22.6 + +.. toc:: + +## Introduction + +This is the second release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Automatic TLS setup in `DEBUG` mode + +The Sanic server can automatically setup a TLS certificate using either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). This certificate will enable `https://localhost` (or another local address) for local development environments. You must install either `mkcert` or `trustme` on your own for this to work. + +.. column:: + +```` +``` +$ sanic path.to.server:app --auto-tls --debug +``` +```` + +.. column:: + +```` +```python +app.run(debug=True, auto_tls=True) +``` +```` + +This feature is not available when running in `ASGI` mode, or in `PRODUCTION` mode. When running Sanic in production, you should be using a real TLS certificate either purchased through a legitimate vendor, or using [Let's Encrypt](https://letsencrypt.org/). + +### HTTP/3 Server 🚀 + +In June 2022, the IETF finalized and published [RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html), the specification for HTTP/3. In short, HTTP/3 is a **very** different protocol than HTTP/1.1 and HTTP/2 because it implements HTTP over UDP instead of TCP. The new HTTP protocol promises faster webpage load times and solving some of the problems of the older standards. You are encouraged to [read more about](https://http3-explained.haxx.se/) this new web technology. You likely will need to install a [capable client](https://curl.se/docs/http3.html) as traditional tooling will not work. + +Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed: + +``` +pip install sanic aioquic +``` + +``` +pip install sanic[http3] +``` + +To start HTTP/3, you must explicitly request it when running your application. + +.. column:: + +```` +``` +$ sanic path.to.server:app --http=3 +``` + +``` +$ sanic path.to.server:app -3 +``` +```` + +.. column:: + +```` +```python +app.run(version=3) +``` +```` + +To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](./v22.3.html#application-multi-serve) introduced in v22.3. + +.. column:: + +```` +``` +$ sanic path.to.server:app --http=3 --http=1 +``` + +``` +$ sanic path.to.server:app -3 -1 +``` +```` + +.. column:: + +```` +```python +app.prepre(version=3) +app.prepre(version=1) +Sanic.serve() +``` +```` + +Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. + +**👶 This feature is being released as an _EARLY RELEASE FEATURE_.** It is **not** yet fully compliant with the HTTP/3 specification, lacking some features like [websockets](https://websockets.spec.whatwg.org/), [webtransport](https://w3c.github.io/webtransport/), and [push responses](https://http3-explained.haxx.se/en/h3/h3-push). Instead the intent of this release is to bring the existing HTTP request/response cycle towards feature parity with HTTP/3. Over the next several releases, more HTTP/3 features will be added and the API for it finalized. + +### Consistent exception naming + +Some of the Sanic exceptions have been renamed to be more compliant with standard HTTP response names. + +- `InvalidUsage` >> `BadRequest` +- `MethodNotSupported` >> `MethodNotAllowed` +- `ContentRangeError` >> `RangeNotSatisfiable` + +All old names have been aliased and will remain backwards compatible. + +### Current request getter + +Similar to the API to access an application (`Sanic.get_app()`), there is a new method for retrieving the current request when outside of a request handler. + +```python +from sanic import Request + +Request.get_current() +``` + +### Improved API support for setting cache control headers + +The `file` response helper has some added parameters to make it easier to handle setting of the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header. + +```python +file( + ..., + last_modified=..., + max_age=..., + no_store=..., +) +``` + +### Custom `loads` function + +Just like Sanic supports globally setting a custom `dumps`, you can now set a global custom `loads`. + +```python +from orjson import loads + +app = Sanic("Test", loads=loads) +``` + +### Deprecations and Removals + +1. _REMOVED_ - Applications may no longer opt-out of the application registry +2. _REMOVED_ - Custom exception handlers will no longer run after some part of an exception has been sent +3. _REMOVED_ - Fallback error formats cannot be set on the `ErrorHandler` and must **only** be set in the `Config` +4. _REMOVED_ - Setting a custom `LOGO` for startup is no longer allowed +5. _REMOVED_ - The old `stream` response convenience method has been removed +6. _REMOVED_ - `AsyncServer.init` is removed and no longer an alias of `AsyncServer.app.state.is_started` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@amitay87](https://github.com/amitay87) +[@ashleysommer](https://github.com/ashleysommer) +[@azimovMichael](https://github.com/azimovMichael) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@kijk2869](https://github.com/kijk2869) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@timmo001](https://github.com/timmo001) +[@zozzz](https://github.com/zozzz) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 49adc10499942ae172b35014812defed0204d52a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:34 +0200 Subject: [PATCH 257/698] New translations v22.6.md (Korean) --- guide/content/ko/release-notes/2022/v22.6.md | 173 +++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 guide/content/ko/release-notes/2022/v22.6.md diff --git a/guide/content/ko/release-notes/2022/v22.6.md b/guide/content/ko/release-notes/2022/v22.6.md new file mode 100644 index 0000000000..73b893c498 --- /dev/null +++ b/guide/content/ko/release-notes/2022/v22.6.md @@ -0,0 +1,173 @@ +--- +title: Version 22.6 +--- + +# Version 22.6 + +.. toc:: + +## Introduction + +This is the second release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Automatic TLS setup in `DEBUG` mode + +The Sanic server can automatically setup a TLS certificate using either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). This certificate will enable `https://localhost` (or another local address) for local development environments. You must install either `mkcert` or `trustme` on your own for this to work. + +.. column:: + +```` +``` +$ sanic path.to.server:app --auto-tls --debug +``` +```` + +.. column:: + +```` +```python +app.run(debug=True, auto_tls=True) +``` +```` + +This feature is not available when running in `ASGI` mode, or in `PRODUCTION` mode. When running Sanic in production, you should be using a real TLS certificate either purchased through a legitimate vendor, or using [Let's Encrypt](https://letsencrypt.org/). + +### HTTP/3 Server 🚀 + +In June 2022, the IETF finalized and published [RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html), the specification for HTTP/3. In short, HTTP/3 is a **very** different protocol than HTTP/1.1 and HTTP/2 because it implements HTTP over UDP instead of TCP. The new HTTP protocol promises faster webpage load times and solving some of the problems of the older standards. You are encouraged to [read more about](https://http3-explained.haxx.se/) this new web technology. You likely will need to install a [capable client](https://curl.se/docs/http3.html) as traditional tooling will not work. + +Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed: + +``` +pip install sanic aioquic +``` + +``` +pip install sanic[http3] +``` + +To start HTTP/3, you must explicitly request it when running your application. + +.. column:: + +```` +``` +$ sanic path.to.server:app --http=3 +``` + +``` +$ sanic path.to.server:app -3 +``` +```` + +.. column:: + +```` +```python +app.run(version=3) +``` +```` + +To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](./v22.3.html#application-multi-serve) introduced in v22.3. + +.. column:: + +```` +``` +$ sanic path.to.server:app --http=3 --http=1 +``` + +``` +$ sanic path.to.server:app -3 -1 +``` +```` + +.. column:: + +```` +```python +app.prepre(version=3) +app.prepre(version=1) +Sanic.serve() +``` +```` + +Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. + +**👶 This feature is being released as an _EARLY RELEASE FEATURE_.** It is **not** yet fully compliant with the HTTP/3 specification, lacking some features like [websockets](https://websockets.spec.whatwg.org/), [webtransport](https://w3c.github.io/webtransport/), and [push responses](https://http3-explained.haxx.se/en/h3/h3-push). Instead the intent of this release is to bring the existing HTTP request/response cycle towards feature parity with HTTP/3. Over the next several releases, more HTTP/3 features will be added and the API for it finalized. + +### Consistent exception naming + +Some of the Sanic exceptions have been renamed to be more compliant with standard HTTP response names. + +- `InvalidUsage` >> `BadRequest` +- `MethodNotSupported` >> `MethodNotAllowed` +- `ContentRangeError` >> `RangeNotSatisfiable` + +All old names have been aliased and will remain backwards compatible. + +### Current request getter + +Similar to the API to access an application (`Sanic.get_app()`), there is a new method for retrieving the current request when outside of a request handler. + +```python +from sanic import Request + +Request.get_current() +``` + +### Improved API support for setting cache control headers + +The `file` response helper has some added parameters to make it easier to handle setting of the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header. + +```python +file( + ..., + last_modified=..., + max_age=..., + no_store=..., +) +``` + +### Custom `loads` function + +Just like Sanic supports globally setting a custom `dumps`, you can now set a global custom `loads`. + +```python +from orjson import loads + +app = Sanic("Test", loads=loads) +``` + +### Deprecations and Removals + +1. _REMOVED_ - Applications may no longer opt-out of the application registry +2. _REMOVED_ - Custom exception handlers will no longer run after some part of an exception has been sent +3. _REMOVED_ - Fallback error formats cannot be set on the `ErrorHandler` and must **only** be set in the `Config` +4. _REMOVED_ - Setting a custom `LOGO` for startup is no longer allowed +5. _REMOVED_ - The old `stream` response convenience method has been removed +6. _REMOVED_ - `AsyncServer.init` is removed and no longer an alias of `AsyncServer.app.state.is_started` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@amitay87](https://github.com/amitay87) +[@ashleysommer](https://github.com/ashleysommer) +[@azimovMichael](https://github.com/azimovMichael) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@kijk2869](https://github.com/kijk2869) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@timmo001](https://github.com/timmo001) +[@zozzz](https://github.com/zozzz) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From aae66ea81ddd8951cd199ce5899505d2ea3ab56f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:35 +0200 Subject: [PATCH 258/698] New translations v22.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.6.md | 173 +++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 guide/content/zh/release-notes/2022/v22.6.md diff --git a/guide/content/zh/release-notes/2022/v22.6.md b/guide/content/zh/release-notes/2022/v22.6.md new file mode 100644 index 0000000000..73b893c498 --- /dev/null +++ b/guide/content/zh/release-notes/2022/v22.6.md @@ -0,0 +1,173 @@ +--- +title: Version 22.6 +--- + +# Version 22.6 + +.. toc:: + +## Introduction + +This is the second release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Automatic TLS setup in `DEBUG` mode + +The Sanic server can automatically setup a TLS certificate using either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). This certificate will enable `https://localhost` (or another local address) for local development environments. You must install either `mkcert` or `trustme` on your own for this to work. + +.. column:: + +```` +``` +$ sanic path.to.server:app --auto-tls --debug +``` +```` + +.. column:: + +```` +```python +app.run(debug=True, auto_tls=True) +``` +```` + +This feature is not available when running in `ASGI` mode, or in `PRODUCTION` mode. When running Sanic in production, you should be using a real TLS certificate either purchased through a legitimate vendor, or using [Let's Encrypt](https://letsencrypt.org/). + +### HTTP/3 Server 🚀 + +In June 2022, the IETF finalized and published [RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html), the specification for HTTP/3. In short, HTTP/3 is a **very** different protocol than HTTP/1.1 and HTTP/2 because it implements HTTP over UDP instead of TCP. The new HTTP protocol promises faster webpage load times and solving some of the problems of the older standards. You are encouraged to [read more about](https://http3-explained.haxx.se/) this new web technology. You likely will need to install a [capable client](https://curl.se/docs/http3.html) as traditional tooling will not work. + +Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed: + +``` +pip install sanic aioquic +``` + +``` +pip install sanic[http3] +``` + +To start HTTP/3, you must explicitly request it when running your application. + +.. column:: + +```` +``` +$ sanic path.to.server:app --http=3 +``` + +``` +$ sanic path.to.server:app -3 +``` +```` + +.. column:: + +```` +```python +app.run(version=3) +``` +```` + +To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](./v22.3.html#application-multi-serve) introduced in v22.3. + +.. column:: + +```` +``` +$ sanic path.to.server:app --http=3 --http=1 +``` + +``` +$ sanic path.to.server:app -3 -1 +``` +```` + +.. column:: + +```` +```python +app.prepre(version=3) +app.prepre(version=1) +Sanic.serve() +``` +```` + +Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. + +**👶 This feature is being released as an _EARLY RELEASE FEATURE_.** It is **not** yet fully compliant with the HTTP/3 specification, lacking some features like [websockets](https://websockets.spec.whatwg.org/), [webtransport](https://w3c.github.io/webtransport/), and [push responses](https://http3-explained.haxx.se/en/h3/h3-push). Instead the intent of this release is to bring the existing HTTP request/response cycle towards feature parity with HTTP/3. Over the next several releases, more HTTP/3 features will be added and the API for it finalized. + +### Consistent exception naming + +Some of the Sanic exceptions have been renamed to be more compliant with standard HTTP response names. + +- `InvalidUsage` >> `BadRequest` +- `MethodNotSupported` >> `MethodNotAllowed` +- `ContentRangeError` >> `RangeNotSatisfiable` + +All old names have been aliased and will remain backwards compatible. + +### Current request getter + +Similar to the API to access an application (`Sanic.get_app()`), there is a new method for retrieving the current request when outside of a request handler. + +```python +from sanic import Request + +Request.get_current() +``` + +### Improved API support for setting cache control headers + +The `file` response helper has some added parameters to make it easier to handle setting of the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header. + +```python +file( + ..., + last_modified=..., + max_age=..., + no_store=..., +) +``` + +### Custom `loads` function + +Just like Sanic supports globally setting a custom `dumps`, you can now set a global custom `loads`. + +```python +from orjson import loads + +app = Sanic("Test", loads=loads) +``` + +### Deprecations and Removals + +1. _REMOVED_ - Applications may no longer opt-out of the application registry +2. _REMOVED_ - Custom exception handlers will no longer run after some part of an exception has been sent +3. _REMOVED_ - Fallback error formats cannot be set on the `ErrorHandler` and must **only** be set in the `Config` +4. _REMOVED_ - Setting a custom `LOGO` for startup is no longer allowed +5. _REMOVED_ - The old `stream` response convenience method has been removed +6. _REMOVED_ - `AsyncServer.init` is removed and no longer an alias of `AsyncServer.app.state.is_started` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@amitay87](https://github.com/amitay87) +[@ashleysommer](https://github.com/ashleysommer) +[@azimovMichael](https://github.com/azimovMichael) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@kijk2869](https://github.com/kijk2869) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@timmo001](https://github.com/timmo001) +[@zozzz](https://github.com/zozzz) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 12830ae40586059c21ad6d7c1b07df3b1a3ffc67 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:36 +0200 Subject: [PATCH 259/698] New translations v22.9.md (Japanese) --- guide/content/ja/release-notes/2022/v22.9.md | 349 +++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 guide/content/ja/release-notes/2022/v22.9.md diff --git a/guide/content/ja/release-notes/2022/v22.9.md b/guide/content/ja/release-notes/2022/v22.9.md new file mode 100644 index 0000000000..b1ea8bf5d1 --- /dev/null +++ b/guide/content/ja/release-notes/2022/v22.9.md @@ -0,0 +1,349 @@ +--- +title: Version 22.9 +--- + +# Version 22.9 + +.. toc:: + +## Introduction + +This is the third release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### ⚠ _IMPORTANT_ - New worker manager 🚀 + +Sanic server has been overhauled to provide more consistency and flexbility in how it operates. More details about the motivations are outlined in [PR #2499](https://github.com/sanic-org/sanic/pull/2499) and discussed in a live stream [discussion held on YouTube](https://youtu.be/m8HCO8NK7HE). + +This **does NOT apply** to Sanic in ASGI mode + +#### Overview of the changes + +- The worker servers will **always** run in a child process. + - Previously this could change depending upon one versus many workers, and the usage or not of the reloader. This should lead to much more predictable development environments that more closely match their production counterparts. +- Multi-workers is **now supported on Windows**. + - This was impossible because Sanic relied upon the `multiprocessing` module using `fork`, which is not available on Windows. + - Now, Sanic will always use `spawn`. This does have some noticeable differences, particularly if you are running Sanic in the global scope with `app.run` (see below re: upgrade issues). +- The application instance now has a new `multiplexer` object that can be used to restart one or many workers. This could, for example, be triggered by a request. +- There is a new Inspector that can provide details on the state of your server. +- Sanic worker manager can run arbitrary processes. + - This allows developers to add any process they want from within Sanic. + - Possible use cases: + - Health monitor, see Sanic Extensions + - Logging queue, see Sanic Extensions + - Background worker queue in a seperate process + - Running another application, like a bot +- There is a new listener called: `main_process_ready`. It really should only be used for adding arbitrary processes to Sanic. +- Passing shared objects between workers. + - Python does allow some types of objects to share state between processes, whether through shared memory, pipes, etc. + - Sanic will now allow these types of object to be shared on the `app.shared_ctx` object. + - Since this feature relies upon Pythons `multiprocessing` library, it obviously will only work to share state between Sanic worker instances that are instantiated from the same execution. This is _not_ meant to provide an API for horizontal scaling across multiple machines for example. + +#### Adding a shared context object + +To share an object between worker processes, it _MUST_ be assigned inside of the `main_process_start` listener. + +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` + +All objects on `shared_ctx` will be available now within each worker process. + +```python +@app.before_server_starts +async def before_server_starts(app): + assert isinstance(app.shared_ctx.queue, Queue) + +@app.on_request +async def on_request(request): + assert isinstance(request.app.shared_ctx.queue, Queue) + +@app.get("/") +async def handler(request): + assert isinstance(request.app.shared_ctx.queue, Queue) +``` + +_NOTE: Sanic will not stop you from registering an unsafe object, but may warn you. Be careful not to just add a regular list object, for example, and expect it to work. You should have an understanding of how to share state between processes._ + +#### Running arbitrary processes + +Sanic can run any arbitrary process for you. It should be capable of being stopped by a `SIGINT` or `SIGTERM` OS signal. + +These processes should be registered inside of the `main_process_ready` listener. + +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage("MyProcess", my_process, {"foo": "bar"}) +# app.manager.manage(, , ) +``` + +#### Inspector + +Sanic ships with an optional Inspector, which is a special process that allows for the CLI to inspect the running state of an application and issue commands. It currently will only work if the CLI is being run on the same machine as the Sanic instance. + +``` +sanic path.to:app --inspect +``` + +![Sanic inspector](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) + +The new CLI commands are: + +``` + --inspect Inspect the state of a running instance, human readable + --inspect-raw Inspect the state of a running instance, JSON output + --trigger-reload Trigger worker processes to reload + --trigger-shutdown Trigger all processes to shutdown +``` + +This is not enabled by default. In order to have it available, you must opt in: + +```python +app.config.INSPECTOR = True +``` + +\*Note: Sanic Extensions provides a [custom request](../basics/app.md#custom-requests) class that will add a request counter to the server state. + +#### Application multiplexer + +Many of the same information and functionality is available on the application instance itself. There is a new `multiplexer` object on the application instance that has the ability to restart one or more workers, and fetch information about the current state. + +You can access it as `app.multiplexer`, or more likely by its short alias `app.m`. + +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.state) +``` + +#### Potential upgrade issues + +Because of the switch from `fork` to `spawn`, if you try running the server in the global scope you will receive an error. If you see something like this: + +``` +sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. +This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. +``` + +... then the change is simple. Make sure `app.run` is inside a block. + +```python +if __name__ == "__main__": + app.run(port=9999, dev=True) +``` + +#### Opting out of the new functionality + +If you would like to run Sanic without the new process manager, you may easily use the legacy runners. Please note that support for them **will be removed** in the future. A date has not yet been set, but will likely be sometime in 2023. + +To opt out of the new server and use the legacy, choose the appropriate method depending upon how you run Sanic: + +.. column:: + +``` +If you use the CLI... +``` + +.. column:: + +```` +``` +sanic path.to:app --legacy +``` +```` + +.. column:: + +``` +If you use `app.run`... +``` + +.. column:: + +```` +``` +app.run(..., legacy=True) +``` +```` + +.. column:: + +``` +If you `app.prepare`... +``` + +.. column:: + +```` +``` +app.prepare(...) +Sanic.serve_legacy() +``` +```` + +Similarly, you can force Sanic to run in a single process. This however means there will not be any access to the auto-reloader. + +.. column:: + +``` +If you use the CLI... +``` + +.. column:: + +```` +``` +sanic path.to:app --single-process +``` +```` + +.. column:: + +``` +If you use `app.run`... +``` + +.. column:: + +```` +``` +app.run(..., single_process=True) +``` +```` + +.. column:: + +``` +If you `app.prepare`... +``` + +.. column:: + +```` +``` +app.prepare(...) +Sanic.serve_single() +``` +```` + +### Middleware priority + +Middleware is executed in an order based upon when it was defined. Request middleware are executed in sequence and response middleware in reverse. This could have an unfortunate impact if your ordering is strictly based upon import ordering with global variables for example. + +A new addition is to break-out of the strict construct and allow a priority to be assigned to a middleware. The higher the number for a middleware definition, the earlier in the sequence it will be executed. This applies to **both** request and response middleware. + +```python +@app.on_request +async def low_priority(_): + ... + +@app.on_request(priority=10) +async def high_priority(_): + ... +``` + +In the above example, even though `low_priority` is defined first, `high_priority` will run first. + +### Custom `loads` function + +Sanic has supported the ability to add a [custom `dumps` function](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic) when instantiating an app. The same functionality has been extended to `loads`, which will be used when deserializing. + +```python +from json import loads + +Sanic("Test", loads=loads) +``` + +### Websocket objects are now iterable + +Rather than calling `recv` in a loop on a `Websocket` object, you can iterate on it in a `for` loop. + +```python +from sanic import Request, Websocket + +@app.websocket("/ws") +async def ws_echo_handler(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` + +### Appropriately respond with 304 on static files + +When serving a static file, the Sanic server can respond appropriately to a request with `If-Modified-Since` using a `304` response instead of resending a file. + +### Two new signals to wrap handler execution + +Two new [signals](../advanced/signals.md) have been added that wrap the execution of a request handler. + +- `http.handler.before` - runs after request middleware but before the route handler +- `http.handler.after` - runs after the route handler + - In _most_ circumstances, this also means that it will run before response middleware. However, if you call `request.respond` from inside of a route handler, then your middleware will come first + +### New Request properties for HTTP method information + +The HTTP specification defines which HTTP methods are: safe, idempotent, and cacheable. New properties have been added that will respond with a boolean flag to help identify the request property based upon the method. + +```python +request.is_safe +request.is_idempotent +request.is_cacheable +``` + +### 🚨 _BREAKING CHANGE_ - Improved cancel request exception + +In prior version of Sanic, if a `CancelledError` was caught it could bubble up and cause the server to respond with a `503`. This is not always the desired outcome, and it prevented the usage of that error in other circumstances. As a result, Sanic will now use a subclass of `CancelledError` called: `RequestCancelled` for this functionality. It likely should have little impact unless you were explicitly relying upon the old behavior. + +For more details on the specifics of these properties, checkout the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). + +### New deprecation warning filter + +You can control the level of deprecation warnings from Sanic using [standard library warning filter values](https://docs.python.org/3/library/warnings.html#the-warnings-filter). Default is `"once"`. + +```python +app.config.DEPRECATION_FILTER = "ignore" +``` + +### Deprecations and Removals + +1. _DEPRECATED_ - Duplicate route names have been deprecated and will be removed in v23.3 +2. _DEPRECATED_ - Registering duplicate exception handlers has been deprecated and will be removed in v23.3 +3. _REMOVED_ - `route.ctx` not set by Sanic, and is a blank object for users, therefore ... + - `route.ctx.ignore_body` >> `route.extra.ignore_body` + - `route.ctx.stream` >> `route.extra.stream` + - `route.ctx.hosts` >> `route.extra.hosts` + - `route.ctx.static` >> `route.extra.static` + - `route.ctx.error_format` >> `route.extra.error_format` + - `route.ctx.websocket` >> `route.extra.websocket` +4. _REMOVED_ - `app.debug` is READ-ONLY +5. _REMOVED_ - `app.is_running` removed +6. _REMOVED_ - `app.is_stopping` removed +7. _REMOVED_ - `Sanic._uvloop_setting` removed +8. _REMOVED_ - Prefixed environment variables will be ignored if not uppercase + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@azimovMichael](https://github.com/azimovMichael) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@huntzhan](https://github.com/huntzhan) +[@monosans](https://github.com/monosans) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@seemethere](https://github.com/seemethere) +[@sjsadowski](https://github.com/sjsadowski) +[@timgates42](https://github.com/timgates42) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 7915ed30a0c4897fb38b907971367bc6919a4a30 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:37 +0200 Subject: [PATCH 260/698] New translations v22.9.md (Korean) --- guide/content/ko/release-notes/2022/v22.9.md | 349 +++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 guide/content/ko/release-notes/2022/v22.9.md diff --git a/guide/content/ko/release-notes/2022/v22.9.md b/guide/content/ko/release-notes/2022/v22.9.md new file mode 100644 index 0000000000..b1ea8bf5d1 --- /dev/null +++ b/guide/content/ko/release-notes/2022/v22.9.md @@ -0,0 +1,349 @@ +--- +title: Version 22.9 +--- + +# Version 22.9 + +.. toc:: + +## Introduction + +This is the third release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### ⚠ _IMPORTANT_ - New worker manager 🚀 + +Sanic server has been overhauled to provide more consistency and flexbility in how it operates. More details about the motivations are outlined in [PR #2499](https://github.com/sanic-org/sanic/pull/2499) and discussed in a live stream [discussion held on YouTube](https://youtu.be/m8HCO8NK7HE). + +This **does NOT apply** to Sanic in ASGI mode + +#### Overview of the changes + +- The worker servers will **always** run in a child process. + - Previously this could change depending upon one versus many workers, and the usage or not of the reloader. This should lead to much more predictable development environments that more closely match their production counterparts. +- Multi-workers is **now supported on Windows**. + - This was impossible because Sanic relied upon the `multiprocessing` module using `fork`, which is not available on Windows. + - Now, Sanic will always use `spawn`. This does have some noticeable differences, particularly if you are running Sanic in the global scope with `app.run` (see below re: upgrade issues). +- The application instance now has a new `multiplexer` object that can be used to restart one or many workers. This could, for example, be triggered by a request. +- There is a new Inspector that can provide details on the state of your server. +- Sanic worker manager can run arbitrary processes. + - This allows developers to add any process they want from within Sanic. + - Possible use cases: + - Health monitor, see Sanic Extensions + - Logging queue, see Sanic Extensions + - Background worker queue in a seperate process + - Running another application, like a bot +- There is a new listener called: `main_process_ready`. It really should only be used for adding arbitrary processes to Sanic. +- Passing shared objects between workers. + - Python does allow some types of objects to share state between processes, whether through shared memory, pipes, etc. + - Sanic will now allow these types of object to be shared on the `app.shared_ctx` object. + - Since this feature relies upon Pythons `multiprocessing` library, it obviously will only work to share state between Sanic worker instances that are instantiated from the same execution. This is _not_ meant to provide an API for horizontal scaling across multiple machines for example. + +#### Adding a shared context object + +To share an object between worker processes, it _MUST_ be assigned inside of the `main_process_start` listener. + +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` + +All objects on `shared_ctx` will be available now within each worker process. + +```python +@app.before_server_starts +async def before_server_starts(app): + assert isinstance(app.shared_ctx.queue, Queue) + +@app.on_request +async def on_request(request): + assert isinstance(request.app.shared_ctx.queue, Queue) + +@app.get("/") +async def handler(request): + assert isinstance(request.app.shared_ctx.queue, Queue) +``` + +_NOTE: Sanic will not stop you from registering an unsafe object, but may warn you. Be careful not to just add a regular list object, for example, and expect it to work. You should have an understanding of how to share state between processes._ + +#### Running arbitrary processes + +Sanic can run any arbitrary process for you. It should be capable of being stopped by a `SIGINT` or `SIGTERM` OS signal. + +These processes should be registered inside of the `main_process_ready` listener. + +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage("MyProcess", my_process, {"foo": "bar"}) +# app.manager.manage(, , ) +``` + +#### Inspector + +Sanic ships with an optional Inspector, which is a special process that allows for the CLI to inspect the running state of an application and issue commands. It currently will only work if the CLI is being run on the same machine as the Sanic instance. + +``` +sanic path.to:app --inspect +``` + +![Sanic inspector](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) + +The new CLI commands are: + +``` + --inspect Inspect the state of a running instance, human readable + --inspect-raw Inspect the state of a running instance, JSON output + --trigger-reload Trigger worker processes to reload + --trigger-shutdown Trigger all processes to shutdown +``` + +This is not enabled by default. In order to have it available, you must opt in: + +```python +app.config.INSPECTOR = True +``` + +\*Note: Sanic Extensions provides a [custom request](../basics/app.md#custom-requests) class that will add a request counter to the server state. + +#### Application multiplexer + +Many of the same information and functionality is available on the application instance itself. There is a new `multiplexer` object on the application instance that has the ability to restart one or more workers, and fetch information about the current state. + +You can access it as `app.multiplexer`, or more likely by its short alias `app.m`. + +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.state) +``` + +#### Potential upgrade issues + +Because of the switch from `fork` to `spawn`, if you try running the server in the global scope you will receive an error. If you see something like this: + +``` +sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. +This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. +``` + +... then the change is simple. Make sure `app.run` is inside a block. + +```python +if __name__ == "__main__": + app.run(port=9999, dev=True) +``` + +#### Opting out of the new functionality + +If you would like to run Sanic without the new process manager, you may easily use the legacy runners. Please note that support for them **will be removed** in the future. A date has not yet been set, but will likely be sometime in 2023. + +To opt out of the new server and use the legacy, choose the appropriate method depending upon how you run Sanic: + +.. column:: + +``` +If you use the CLI... +``` + +.. column:: + +```` +``` +sanic path.to:app --legacy +``` +```` + +.. column:: + +``` +If you use `app.run`... +``` + +.. column:: + +```` +``` +app.run(..., legacy=True) +``` +```` + +.. column:: + +``` +If you `app.prepare`... +``` + +.. column:: + +```` +``` +app.prepare(...) +Sanic.serve_legacy() +``` +```` + +Similarly, you can force Sanic to run in a single process. This however means there will not be any access to the auto-reloader. + +.. column:: + +``` +If you use the CLI... +``` + +.. column:: + +```` +``` +sanic path.to:app --single-process +``` +```` + +.. column:: + +``` +If you use `app.run`... +``` + +.. column:: + +```` +``` +app.run(..., single_process=True) +``` +```` + +.. column:: + +``` +If you `app.prepare`... +``` + +.. column:: + +```` +``` +app.prepare(...) +Sanic.serve_single() +``` +```` + +### Middleware priority + +Middleware is executed in an order based upon when it was defined. Request middleware are executed in sequence and response middleware in reverse. This could have an unfortunate impact if your ordering is strictly based upon import ordering with global variables for example. + +A new addition is to break-out of the strict construct and allow a priority to be assigned to a middleware. The higher the number for a middleware definition, the earlier in the sequence it will be executed. This applies to **both** request and response middleware. + +```python +@app.on_request +async def low_priority(_): + ... + +@app.on_request(priority=10) +async def high_priority(_): + ... +``` + +In the above example, even though `low_priority` is defined first, `high_priority` will run first. + +### Custom `loads` function + +Sanic has supported the ability to add a [custom `dumps` function](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic) when instantiating an app. The same functionality has been extended to `loads`, which will be used when deserializing. + +```python +from json import loads + +Sanic("Test", loads=loads) +``` + +### Websocket objects are now iterable + +Rather than calling `recv` in a loop on a `Websocket` object, you can iterate on it in a `for` loop. + +```python +from sanic import Request, Websocket + +@app.websocket("/ws") +async def ws_echo_handler(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` + +### Appropriately respond with 304 on static files + +When serving a static file, the Sanic server can respond appropriately to a request with `If-Modified-Since` using a `304` response instead of resending a file. + +### Two new signals to wrap handler execution + +Two new [signals](../advanced/signals.md) have been added that wrap the execution of a request handler. + +- `http.handler.before` - runs after request middleware but before the route handler +- `http.handler.after` - runs after the route handler + - In _most_ circumstances, this also means that it will run before response middleware. However, if you call `request.respond` from inside of a route handler, then your middleware will come first + +### New Request properties for HTTP method information + +The HTTP specification defines which HTTP methods are: safe, idempotent, and cacheable. New properties have been added that will respond with a boolean flag to help identify the request property based upon the method. + +```python +request.is_safe +request.is_idempotent +request.is_cacheable +``` + +### 🚨 _BREAKING CHANGE_ - Improved cancel request exception + +In prior version of Sanic, if a `CancelledError` was caught it could bubble up and cause the server to respond with a `503`. This is not always the desired outcome, and it prevented the usage of that error in other circumstances. As a result, Sanic will now use a subclass of `CancelledError` called: `RequestCancelled` for this functionality. It likely should have little impact unless you were explicitly relying upon the old behavior. + +For more details on the specifics of these properties, checkout the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). + +### New deprecation warning filter + +You can control the level of deprecation warnings from Sanic using [standard library warning filter values](https://docs.python.org/3/library/warnings.html#the-warnings-filter). Default is `"once"`. + +```python +app.config.DEPRECATION_FILTER = "ignore" +``` + +### Deprecations and Removals + +1. _DEPRECATED_ - Duplicate route names have been deprecated and will be removed in v23.3 +2. _DEPRECATED_ - Registering duplicate exception handlers has been deprecated and will be removed in v23.3 +3. _REMOVED_ - `route.ctx` not set by Sanic, and is a blank object for users, therefore ... + - `route.ctx.ignore_body` >> `route.extra.ignore_body` + - `route.ctx.stream` >> `route.extra.stream` + - `route.ctx.hosts` >> `route.extra.hosts` + - `route.ctx.static` >> `route.extra.static` + - `route.ctx.error_format` >> `route.extra.error_format` + - `route.ctx.websocket` >> `route.extra.websocket` +4. _REMOVED_ - `app.debug` is READ-ONLY +5. _REMOVED_ - `app.is_running` removed +6. _REMOVED_ - `app.is_stopping` removed +7. _REMOVED_ - `Sanic._uvloop_setting` removed +8. _REMOVED_ - Prefixed environment variables will be ignored if not uppercase + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@azimovMichael](https://github.com/azimovMichael) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@huntzhan](https://github.com/huntzhan) +[@monosans](https://github.com/monosans) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@seemethere](https://github.com/seemethere) +[@sjsadowski](https://github.com/sjsadowski) +[@timgates42](https://github.com/timgates42) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 77d6d881824d8b1b0e7cedb15f8045155bdbfef2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:38 +0200 Subject: [PATCH 261/698] New translations v22.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.9.md | 349 +++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 guide/content/zh/release-notes/2022/v22.9.md diff --git a/guide/content/zh/release-notes/2022/v22.9.md b/guide/content/zh/release-notes/2022/v22.9.md new file mode 100644 index 0000000000..b1ea8bf5d1 --- /dev/null +++ b/guide/content/zh/release-notes/2022/v22.9.md @@ -0,0 +1,349 @@ +--- +title: Version 22.9 +--- + +# Version 22.9 + +.. toc:: + +## Introduction + +This is the third release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### ⚠ _IMPORTANT_ - New worker manager 🚀 + +Sanic server has been overhauled to provide more consistency and flexbility in how it operates. More details about the motivations are outlined in [PR #2499](https://github.com/sanic-org/sanic/pull/2499) and discussed in a live stream [discussion held on YouTube](https://youtu.be/m8HCO8NK7HE). + +This **does NOT apply** to Sanic in ASGI mode + +#### Overview of the changes + +- The worker servers will **always** run in a child process. + - Previously this could change depending upon one versus many workers, and the usage or not of the reloader. This should lead to much more predictable development environments that more closely match their production counterparts. +- Multi-workers is **now supported on Windows**. + - This was impossible because Sanic relied upon the `multiprocessing` module using `fork`, which is not available on Windows. + - Now, Sanic will always use `spawn`. This does have some noticeable differences, particularly if you are running Sanic in the global scope with `app.run` (see below re: upgrade issues). +- The application instance now has a new `multiplexer` object that can be used to restart one or many workers. This could, for example, be triggered by a request. +- There is a new Inspector that can provide details on the state of your server. +- Sanic worker manager can run arbitrary processes. + - This allows developers to add any process they want from within Sanic. + - Possible use cases: + - Health monitor, see Sanic Extensions + - Logging queue, see Sanic Extensions + - Background worker queue in a seperate process + - Running another application, like a bot +- There is a new listener called: `main_process_ready`. It really should only be used for adding arbitrary processes to Sanic. +- Passing shared objects between workers. + - Python does allow some types of objects to share state between processes, whether through shared memory, pipes, etc. + - Sanic will now allow these types of object to be shared on the `app.shared_ctx` object. + - Since this feature relies upon Pythons `multiprocessing` library, it obviously will only work to share state between Sanic worker instances that are instantiated from the same execution. This is _not_ meant to provide an API for horizontal scaling across multiple machines for example. + +#### Adding a shared context object + +To share an object between worker processes, it _MUST_ be assigned inside of the `main_process_start` listener. + +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` + +All objects on `shared_ctx` will be available now within each worker process. + +```python +@app.before_server_starts +async def before_server_starts(app): + assert isinstance(app.shared_ctx.queue, Queue) + +@app.on_request +async def on_request(request): + assert isinstance(request.app.shared_ctx.queue, Queue) + +@app.get("/") +async def handler(request): + assert isinstance(request.app.shared_ctx.queue, Queue) +``` + +_NOTE: Sanic will not stop you from registering an unsafe object, but may warn you. Be careful not to just add a regular list object, for example, and expect it to work. You should have an understanding of how to share state between processes._ + +#### Running arbitrary processes + +Sanic can run any arbitrary process for you. It should be capable of being stopped by a `SIGINT` or `SIGTERM` OS signal. + +These processes should be registered inside of the `main_process_ready` listener. + +```python +@app.main_process_ready +async def ready(app: Sanic, _): + app.manager.manage("MyProcess", my_process, {"foo": "bar"}) +# app.manager.manage(, , ) +``` + +#### Inspector + +Sanic ships with an optional Inspector, which is a special process that allows for the CLI to inspect the running state of an application and issue commands. It currently will only work if the CLI is being run on the same machine as the Sanic instance. + +``` +sanic path.to:app --inspect +``` + +![Sanic inspector](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) + +The new CLI commands are: + +``` + --inspect Inspect the state of a running instance, human readable + --inspect-raw Inspect the state of a running instance, JSON output + --trigger-reload Trigger worker processes to reload + --trigger-shutdown Trigger all processes to shutdown +``` + +This is not enabled by default. In order to have it available, you must opt in: + +```python +app.config.INSPECTOR = True +``` + +\*Note: Sanic Extensions provides a [custom request](../basics/app.md#custom-requests) class that will add a request counter to the server state. + +#### Application multiplexer + +Many of the same information and functionality is available on the application instance itself. There is a new `multiplexer` object on the application instance that has the ability to restart one or more workers, and fetch information about the current state. + +You can access it as `app.multiplexer`, or more likely by its short alias `app.m`. + +```python +@app.on_request +async def print_state(request: Request): + print(request.app.m.state) +``` + +#### Potential upgrade issues + +Because of the switch from `fork` to `spawn`, if you try running the server in the global scope you will receive an error. If you see something like this: + +``` +sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. +This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. +``` + +... then the change is simple. Make sure `app.run` is inside a block. + +```python +if __name__ == "__main__": + app.run(port=9999, dev=True) +``` + +#### Opting out of the new functionality + +If you would like to run Sanic without the new process manager, you may easily use the legacy runners. Please note that support for them **will be removed** in the future. A date has not yet been set, but will likely be sometime in 2023. + +To opt out of the new server and use the legacy, choose the appropriate method depending upon how you run Sanic: + +.. column:: + +``` +If you use the CLI... +``` + +.. column:: + +```` +``` +sanic path.to:app --legacy +``` +```` + +.. column:: + +``` +If you use `app.run`... +``` + +.. column:: + +```` +``` +app.run(..., legacy=True) +``` +```` + +.. column:: + +``` +If you `app.prepare`... +``` + +.. column:: + +```` +``` +app.prepare(...) +Sanic.serve_legacy() +``` +```` + +Similarly, you can force Sanic to run in a single process. This however means there will not be any access to the auto-reloader. + +.. column:: + +``` +If you use the CLI... +``` + +.. column:: + +```` +``` +sanic path.to:app --single-process +``` +```` + +.. column:: + +``` +If you use `app.run`... +``` + +.. column:: + +```` +``` +app.run(..., single_process=True) +``` +```` + +.. column:: + +``` +If you `app.prepare`... +``` + +.. column:: + +```` +``` +app.prepare(...) +Sanic.serve_single() +``` +```` + +### Middleware priority + +Middleware is executed in an order based upon when it was defined. Request middleware are executed in sequence and response middleware in reverse. This could have an unfortunate impact if your ordering is strictly based upon import ordering with global variables for example. + +A new addition is to break-out of the strict construct and allow a priority to be assigned to a middleware. The higher the number for a middleware definition, the earlier in the sequence it will be executed. This applies to **both** request and response middleware. + +```python +@app.on_request +async def low_priority(_): + ... + +@app.on_request(priority=10) +async def high_priority(_): + ... +``` + +In the above example, even though `low_priority` is defined first, `high_priority` will run first. + +### Custom `loads` function + +Sanic has supported the ability to add a [custom `dumps` function](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic) when instantiating an app. The same functionality has been extended to `loads`, which will be used when deserializing. + +```python +from json import loads + +Sanic("Test", loads=loads) +``` + +### Websocket objects are now iterable + +Rather than calling `recv` in a loop on a `Websocket` object, you can iterate on it in a `for` loop. + +```python +from sanic import Request, Websocket + +@app.websocket("/ws") +async def ws_echo_handler(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) +``` + +### Appropriately respond with 304 on static files + +When serving a static file, the Sanic server can respond appropriately to a request with `If-Modified-Since` using a `304` response instead of resending a file. + +### Two new signals to wrap handler execution + +Two new [signals](../advanced/signals.md) have been added that wrap the execution of a request handler. + +- `http.handler.before` - runs after request middleware but before the route handler +- `http.handler.after` - runs after the route handler + - In _most_ circumstances, this also means that it will run before response middleware. However, if you call `request.respond` from inside of a route handler, then your middleware will come first + +### New Request properties for HTTP method information + +The HTTP specification defines which HTTP methods are: safe, idempotent, and cacheable. New properties have been added that will respond with a boolean flag to help identify the request property based upon the method. + +```python +request.is_safe +request.is_idempotent +request.is_cacheable +``` + +### 🚨 _BREAKING CHANGE_ - Improved cancel request exception + +In prior version of Sanic, if a `CancelledError` was caught it could bubble up and cause the server to respond with a `503`. This is not always the desired outcome, and it prevented the usage of that error in other circumstances. As a result, Sanic will now use a subclass of `CancelledError` called: `RequestCancelled` for this functionality. It likely should have little impact unless you were explicitly relying upon the old behavior. + +For more details on the specifics of these properties, checkout the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). + +### New deprecation warning filter + +You can control the level of deprecation warnings from Sanic using [standard library warning filter values](https://docs.python.org/3/library/warnings.html#the-warnings-filter). Default is `"once"`. + +```python +app.config.DEPRECATION_FILTER = "ignore" +``` + +### Deprecations and Removals + +1. _DEPRECATED_ - Duplicate route names have been deprecated and will be removed in v23.3 +2. _DEPRECATED_ - Registering duplicate exception handlers has been deprecated and will be removed in v23.3 +3. _REMOVED_ - `route.ctx` not set by Sanic, and is a blank object for users, therefore ... + - `route.ctx.ignore_body` >> `route.extra.ignore_body` + - `route.ctx.stream` >> `route.extra.stream` + - `route.ctx.hosts` >> `route.extra.hosts` + - `route.ctx.static` >> `route.extra.static` + - `route.ctx.error_format` >> `route.extra.error_format` + - `route.ctx.websocket` >> `route.extra.websocket` +4. _REMOVED_ - `app.debug` is READ-ONLY +5. _REMOVED_ - `app.is_running` removed +6. _REMOVED_ - `app.is_stopping` removed +7. _REMOVED_ - `Sanic._uvloop_setting` removed +8. _REMOVED_ - Prefixed environment variables will be ignored if not uppercase + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@azimovMichael](https://github.com/azimovMichael) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@huntzhan](https://github.com/huntzhan) +[@monosans](https://github.com/monosans) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@seemethere](https://github.com/seemethere) +[@sjsadowski](https://github.com/sjsadowski) +[@timgates42](https://github.com/timgates42) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 16356c8157ea1e377d4261f981d038c3b1e7372a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:40 +0200 Subject: [PATCH 262/698] New translations v23.12.md (Japanese) --- guide/content/ja/release-notes/2023/v23.12.md | 185 ++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 guide/content/ja/release-notes/2023/v23.12.md diff --git a/guide/content/ja/release-notes/2023/v23.12.md b/guide/content/ja/release-notes/2023/v23.12.md new file mode 100644 index 0000000000..6694a10d2e --- /dev/null +++ b/guide/content/ja/release-notes/2023/v23.12.md @@ -0,0 +1,185 @@ +--- +title: Version 23.12 +--- + +# Version 23.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 23 [release cycle](../../organization/policies.md#release-schedule). It is designated as a **long-term support ("LTS") release**, which means it will receive support for two years as stated in the support policy. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose.) + +## What to know + +More details in the [Changelog](../changelog.html). Notable new or breaking features, and what to upgrade: + +### 🎉 Documentation now using {span:has-text-primary:Sanic} + +![](http://127.0.0.1:8000/assets/images/sanic-framework-logo-circle-128x128.png) + +You can read [all about how](/en/built-with-sanic.html), but we converted this documentation site to using the SHH 🤫 stack. + +- [Sanic](https://sanic.dev) +- [html5tagger](https://github.com/sanic-org/html5tagger) +- [HTMX](https://htmx.org/) + +### 👶 _BETA_ Welcome to the Sanic interactive console + +That's right, Sanic now ships with a REPL! + +![](/assets/images/repl.png) + +When using the Sanic CLI, you can pass the `--repl` argument to automatically run an interactive console along side your application. This is extremely helpful while developing, and allows you access to the application instance, as well as a built-in client enabled to send HTTP requests to the running instance. + +If you use the `--dev` flag, this feature is quasi-enabled by default. While it will not outright run the REPL, it will start the process and allow you to enter the REPL at anytime by hitting `` on your keyboard. + +_This is still in BETA mode. We would appreciate you letting us know about any any enhancement requests or issues._ + +### Python 3.12 support + +We have added Python 3.12 to the supported versions. + +### Start and restart arbitrary processes + +Using the [multiplexer](../../guide/running/manager.md#access-to-the-multiplexer), you can now start and restart arbitrary or pre-existing processes. This enabled the following new features in the way the multiplexer and worker manager operate: + +1. `multiplexer.restart("")` will now restart a targeted single process +2. `multiplexer.manage(...)` is a new method that works exactly like `manager.manage(...)` +3. The `manage` methods now have additional keyword arguments: + - `tracked` - whether the state of the process is tracked after the process completes + - `restartable` - whether the process should be allowed to be restarted + - `auto_start` - whether the process should be started immediately after it is created + +```python +def task(n: int = 10, **kwargs): + print("TASK STARTED", kwargs) + for i in range(n): + print(f"Running task - Step {i+1} of {n}") + sleep(1) + +@app.get("/restart") +async def restart_handler(request: Request): + request.app.m.restart("Sanic-TEST-0") + return json({"foo": request.app.m.name}) + + +@app.get("/start") +async def start_handler(request: Request): + request.app.m.manage("NEW", task, kwargs={"n": 7}, workers=2) + return json({"foo": request.app.m.name}) + +@app.main_process_ready +def start_process(app: Sanic): + app.manager.manage("TEST", task, kwargs={"n": 3}, restartable=True) +``` + +### Prioritized listeners and signals + +In [v22.9](../2022/v22.9.md) Sanic added prioritization to middleware to allow arbitrary ordering of middleware. This same concept has now been extended to listeners and signals. This will allow a priority number to be assigned at creation time that will override its default position in the execution timeline. + +```python +@app.before_server_start(priority=3) +async def sample(app): + ... +``` + +The higher the number, the higher priority it will receive. Overall the rules for deciding the order of execution are as follows: + +1. Priority in descending order +2. Application listeners before Blueprint listeners +3. Registration order + +_Remember, some listeners are executed in reverse order_ + +### Websocket signals + +We have added three new signals for websockets: + +1. `websocket.handler.before` +2. `websocket.handler.after` +3. `websocket.handler.exception` + +```python +@app.signal("websocket.handler.before") +async def ws_before(request: Request, websocket: Websocket): + ... + +@app.signal("websocket.handler.after") +async def ws_after(request: Request, websocket: Websocket): + ... + +@app.signal("websocket.handler.exception") +async def ws_exception( + request: Request, websocket: Websocket, exception: Exception +): + ... +``` + +![](https://camo.githubusercontent.com/ea2894c88bedf37a4f12f129569e8fd14bfceaa36d4452c7b7a1869d2f1cdb18/68747470733a2f2f7a692e66692f77732d7369676e616c732e706e67) + +### Simplified signals + +Sanic has always enforced a three part naming convention for signals: `one.two.three`. However, now you can create simpler names that are only a single part. + +```python +@app.signal("foo") +async def foo(): + ... +``` + +You can make that part dynamic just like with regular signals and routes: + +```python +@app.signal("") +async def handler(**kwargs): + print("foobar signal received") + print(kwargs) + + +@app.route("/") +async def test(request: Request): + await request.app.dispatch("foobar") + return json({"hello": "world"}) +``` + +If you need to have multiple dynamic signals, then you should use the longer three-part format. + +### The `event` method has been updated + +A number of changes have been made to both `app.event()` and `blueprint.event()`. + +- `condition` and `exclusive` are keywords to control matching conditions (similar to the `signal()` methods) +- You can pass either a `str` or an `Enum` (just like `signal()`) +- returns a copy of the context that was passed to the `dispatch()` method + +### Reload trigger gets changed files + +The files changed by the reloader are now injected into the listener. This will allow the trigger to do something with knowledge of what those changed files were. + +```python +@app.after_reload_trigger +async def after_reload_trigger(_, changed): + print(changed) +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@freddiewanah](https://github.com/freddiewanah) +[@gluhar2006](https://github.com/gluhar2006) +[@iAndriy](https://github.com/iAndriy) +[@MichaelHinrichs](https://github.com/MichaelHinrichs) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@talljosh](https://github.com/talljosh) +[@tjni](https://github.com/tjni) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From a3405d48a9e5987590d42e63e31319ddd56dd683 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:41 +0200 Subject: [PATCH 263/698] New translations v23.12.md (Korean) --- guide/content/ko/release-notes/2023/v23.12.md | 185 ++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 guide/content/ko/release-notes/2023/v23.12.md diff --git a/guide/content/ko/release-notes/2023/v23.12.md b/guide/content/ko/release-notes/2023/v23.12.md new file mode 100644 index 0000000000..6694a10d2e --- /dev/null +++ b/guide/content/ko/release-notes/2023/v23.12.md @@ -0,0 +1,185 @@ +--- +title: Version 23.12 +--- + +# Version 23.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 23 [release cycle](../../organization/policies.md#release-schedule). It is designated as a **long-term support ("LTS") release**, which means it will receive support for two years as stated in the support policy. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose.) + +## What to know + +More details in the [Changelog](../changelog.html). Notable new or breaking features, and what to upgrade: + +### 🎉 Documentation now using {span:has-text-primary:Sanic} + +![](http://127.0.0.1:8000/assets/images/sanic-framework-logo-circle-128x128.png) + +You can read [all about how](/en/built-with-sanic.html), but we converted this documentation site to using the SHH 🤫 stack. + +- [Sanic](https://sanic.dev) +- [html5tagger](https://github.com/sanic-org/html5tagger) +- [HTMX](https://htmx.org/) + +### 👶 _BETA_ Welcome to the Sanic interactive console + +That's right, Sanic now ships with a REPL! + +![](/assets/images/repl.png) + +When using the Sanic CLI, you can pass the `--repl` argument to automatically run an interactive console along side your application. This is extremely helpful while developing, and allows you access to the application instance, as well as a built-in client enabled to send HTTP requests to the running instance. + +If you use the `--dev` flag, this feature is quasi-enabled by default. While it will not outright run the REPL, it will start the process and allow you to enter the REPL at anytime by hitting `` on your keyboard. + +_This is still in BETA mode. We would appreciate you letting us know about any any enhancement requests or issues._ + +### Python 3.12 support + +We have added Python 3.12 to the supported versions. + +### Start and restart arbitrary processes + +Using the [multiplexer](../../guide/running/manager.md#access-to-the-multiplexer), you can now start and restart arbitrary or pre-existing processes. This enabled the following new features in the way the multiplexer and worker manager operate: + +1. `multiplexer.restart("")` will now restart a targeted single process +2. `multiplexer.manage(...)` is a new method that works exactly like `manager.manage(...)` +3. The `manage` methods now have additional keyword arguments: + - `tracked` - whether the state of the process is tracked after the process completes + - `restartable` - whether the process should be allowed to be restarted + - `auto_start` - whether the process should be started immediately after it is created + +```python +def task(n: int = 10, **kwargs): + print("TASK STARTED", kwargs) + for i in range(n): + print(f"Running task - Step {i+1} of {n}") + sleep(1) + +@app.get("/restart") +async def restart_handler(request: Request): + request.app.m.restart("Sanic-TEST-0") + return json({"foo": request.app.m.name}) + + +@app.get("/start") +async def start_handler(request: Request): + request.app.m.manage("NEW", task, kwargs={"n": 7}, workers=2) + return json({"foo": request.app.m.name}) + +@app.main_process_ready +def start_process(app: Sanic): + app.manager.manage("TEST", task, kwargs={"n": 3}, restartable=True) +``` + +### Prioritized listeners and signals + +In [v22.9](../2022/v22.9.md) Sanic added prioritization to middleware to allow arbitrary ordering of middleware. This same concept has now been extended to listeners and signals. This will allow a priority number to be assigned at creation time that will override its default position in the execution timeline. + +```python +@app.before_server_start(priority=3) +async def sample(app): + ... +``` + +The higher the number, the higher priority it will receive. Overall the rules for deciding the order of execution are as follows: + +1. Priority in descending order +2. Application listeners before Blueprint listeners +3. Registration order + +_Remember, some listeners are executed in reverse order_ + +### Websocket signals + +We have added three new signals for websockets: + +1. `websocket.handler.before` +2. `websocket.handler.after` +3. `websocket.handler.exception` + +```python +@app.signal("websocket.handler.before") +async def ws_before(request: Request, websocket: Websocket): + ... + +@app.signal("websocket.handler.after") +async def ws_after(request: Request, websocket: Websocket): + ... + +@app.signal("websocket.handler.exception") +async def ws_exception( + request: Request, websocket: Websocket, exception: Exception +): + ... +``` + +![](https://camo.githubusercontent.com/ea2894c88bedf37a4f12f129569e8fd14bfceaa36d4452c7b7a1869d2f1cdb18/68747470733a2f2f7a692e66692f77732d7369676e616c732e706e67) + +### Simplified signals + +Sanic has always enforced a three part naming convention for signals: `one.two.three`. However, now you can create simpler names that are only a single part. + +```python +@app.signal("foo") +async def foo(): + ... +``` + +You can make that part dynamic just like with regular signals and routes: + +```python +@app.signal("") +async def handler(**kwargs): + print("foobar signal received") + print(kwargs) + + +@app.route("/") +async def test(request: Request): + await request.app.dispatch("foobar") + return json({"hello": "world"}) +``` + +If you need to have multiple dynamic signals, then you should use the longer three-part format. + +### The `event` method has been updated + +A number of changes have been made to both `app.event()` and `blueprint.event()`. + +- `condition` and `exclusive` are keywords to control matching conditions (similar to the `signal()` methods) +- You can pass either a `str` or an `Enum` (just like `signal()`) +- returns a copy of the context that was passed to the `dispatch()` method + +### Reload trigger gets changed files + +The files changed by the reloader are now injected into the listener. This will allow the trigger to do something with knowledge of what those changed files were. + +```python +@app.after_reload_trigger +async def after_reload_trigger(_, changed): + print(changed) +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@freddiewanah](https://github.com/freddiewanah) +[@gluhar2006](https://github.com/gluhar2006) +[@iAndriy](https://github.com/iAndriy) +[@MichaelHinrichs](https://github.com/MichaelHinrichs) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@talljosh](https://github.com/talljosh) +[@tjni](https://github.com/tjni) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From a0ad2f1ed37b969149f49769dede40f274ff8d36 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:42 +0200 Subject: [PATCH 264/698] New translations v23.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.12.md | 185 ++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 guide/content/zh/release-notes/2023/v23.12.md diff --git a/guide/content/zh/release-notes/2023/v23.12.md b/guide/content/zh/release-notes/2023/v23.12.md new file mode 100644 index 0000000000..6694a10d2e --- /dev/null +++ b/guide/content/zh/release-notes/2023/v23.12.md @@ -0,0 +1,185 @@ +--- +title: Version 23.12 +--- + +# Version 23.12 (LTS) + +.. toc:: + +## Introduction + +This is the final release of the version 23 [release cycle](../../organization/policies.md#release-schedule). It is designated as a **long-term support ("LTS") release**, which means it will receive support for two years as stated in the support policy. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose.) + +## What to know + +More details in the [Changelog](../changelog.html). Notable new or breaking features, and what to upgrade: + +### 🎉 Documentation now using {span:has-text-primary:Sanic} + +![](http://127.0.0.1:8000/assets/images/sanic-framework-logo-circle-128x128.png) + +You can read [all about how](/en/built-with-sanic.html), but we converted this documentation site to using the SHH 🤫 stack. + +- [Sanic](https://sanic.dev) +- [html5tagger](https://github.com/sanic-org/html5tagger) +- [HTMX](https://htmx.org/) + +### 👶 _BETA_ Welcome to the Sanic interactive console + +That's right, Sanic now ships with a REPL! + +![](/assets/images/repl.png) + +When using the Sanic CLI, you can pass the `--repl` argument to automatically run an interactive console along side your application. This is extremely helpful while developing, and allows you access to the application instance, as well as a built-in client enabled to send HTTP requests to the running instance. + +If you use the `--dev` flag, this feature is quasi-enabled by default. While it will not outright run the REPL, it will start the process and allow you to enter the REPL at anytime by hitting `` on your keyboard. + +_This is still in BETA mode. We would appreciate you letting us know about any any enhancement requests or issues._ + +### Python 3.12 support + +We have added Python 3.12 to the supported versions. + +### Start and restart arbitrary processes + +Using the [multiplexer](../../guide/running/manager.md#access-to-the-multiplexer), you can now start and restart arbitrary or pre-existing processes. This enabled the following new features in the way the multiplexer and worker manager operate: + +1. `multiplexer.restart("")` will now restart a targeted single process +2. `multiplexer.manage(...)` is a new method that works exactly like `manager.manage(...)` +3. The `manage` methods now have additional keyword arguments: + - `tracked` - whether the state of the process is tracked after the process completes + - `restartable` - whether the process should be allowed to be restarted + - `auto_start` - whether the process should be started immediately after it is created + +```python +def task(n: int = 10, **kwargs): + print("TASK STARTED", kwargs) + for i in range(n): + print(f"Running task - Step {i+1} of {n}") + sleep(1) + +@app.get("/restart") +async def restart_handler(request: Request): + request.app.m.restart("Sanic-TEST-0") + return json({"foo": request.app.m.name}) + + +@app.get("/start") +async def start_handler(request: Request): + request.app.m.manage("NEW", task, kwargs={"n": 7}, workers=2) + return json({"foo": request.app.m.name}) + +@app.main_process_ready +def start_process(app: Sanic): + app.manager.manage("TEST", task, kwargs={"n": 3}, restartable=True) +``` + +### Prioritized listeners and signals + +In [v22.9](../2022/v22.9.md) Sanic added prioritization to middleware to allow arbitrary ordering of middleware. This same concept has now been extended to listeners and signals. This will allow a priority number to be assigned at creation time that will override its default position in the execution timeline. + +```python +@app.before_server_start(priority=3) +async def sample(app): + ... +``` + +The higher the number, the higher priority it will receive. Overall the rules for deciding the order of execution are as follows: + +1. Priority in descending order +2. Application listeners before Blueprint listeners +3. Registration order + +_Remember, some listeners are executed in reverse order_ + +### Websocket signals + +We have added three new signals for websockets: + +1. `websocket.handler.before` +2. `websocket.handler.after` +3. `websocket.handler.exception` + +```python +@app.signal("websocket.handler.before") +async def ws_before(request: Request, websocket: Websocket): + ... + +@app.signal("websocket.handler.after") +async def ws_after(request: Request, websocket: Websocket): + ... + +@app.signal("websocket.handler.exception") +async def ws_exception( + request: Request, websocket: Websocket, exception: Exception +): + ... +``` + +![](https://camo.githubusercontent.com/ea2894c88bedf37a4f12f129569e8fd14bfceaa36d4452c7b7a1869d2f1cdb18/68747470733a2f2f7a692e66692f77732d7369676e616c732e706e67) + +### Simplified signals + +Sanic has always enforced a three part naming convention for signals: `one.two.three`. However, now you can create simpler names that are only a single part. + +```python +@app.signal("foo") +async def foo(): + ... +``` + +You can make that part dynamic just like with regular signals and routes: + +```python +@app.signal("") +async def handler(**kwargs): + print("foobar signal received") + print(kwargs) + + +@app.route("/") +async def test(request: Request): + await request.app.dispatch("foobar") + return json({"hello": "world"}) +``` + +If you need to have multiple dynamic signals, then you should use the longer three-part format. + +### The `event` method has been updated + +A number of changes have been made to both `app.event()` and `blueprint.event()`. + +- `condition` and `exclusive` are keywords to control matching conditions (similar to the `signal()` methods) +- You can pass either a `str` or an `Enum` (just like `signal()`) +- returns a copy of the context that was passed to the `dispatch()` method + +### Reload trigger gets changed files + +The files changed by the reloader are now injected into the listener. This will allow the trigger to do something with knowledge of what those changed files were. + +```python +@app.after_reload_trigger +async def after_reload_trigger(_, changed): + print(changed) +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@freddiewanah](https://github.com/freddiewanah) +[@gluhar2006](https://github.com/gluhar2006) +[@iAndriy](https://github.com/iAndriy) +[@MichaelHinrichs](https://github.com/MichaelHinrichs) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@talljosh](https://github.com/talljosh) +[@tjni](https://github.com/tjni) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 8b17151e911170c55d335973b94c1e292fc13475 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:43 +0200 Subject: [PATCH 265/698] New translations v23.3.md (Japanese) --- guide/content/ja/release-notes/2023/v23.3.md | 421 +++++++++++++++++++ 1 file changed, 421 insertions(+) create mode 100644 guide/content/ja/release-notes/2023/v23.3.md diff --git a/guide/content/ja/release-notes/2023/v23.3.md b/guide/content/ja/release-notes/2023/v23.3.md new file mode 100644 index 0000000000..70dc746698 --- /dev/null +++ b/guide/content/ja/release-notes/2023/v23.3.md @@ -0,0 +1,421 @@ +--- +title: Version 23.3 +--- + +# Version 23.3 + +.. toc:: + +## Introduction + +This is the first release of the version 23 [release cycle](../../org/policies.md#release-schedule). As such contains some deprecations and hopefully some _small_ breaking changes. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Nicer traceback formatting + +The SCO adopted two projects into the Sanic namespace on GitHub: [tracerite](https://github.com/sanic-org/tracerite) and [html5tagger](https://github.com/sanic-org/html5tagger). These projects team up to provide and incredible new error page with more details to help the debugging process. + +This is provided out of the box, and will adjust to display only relevant information whether in DEBUG more or PROD mode. + +.. column:: + +``` +**Using PROD mode** +![image](/assets/images/error-html-no-debug.png) +``` + +.. column:: + +``` +**Using DEBUG mode** +![image](/assets/images/error-html-debug.png) +``` + +Light and dark mode HTML pages are available and will be used implicitly. + +### Basic file browser on directories + +When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. + +.. column:: + +```` +```python +app.static("/uploads/", "/path/to/dir/", directory_view=True) +``` +```` + +.. column:: + +``` +![image](/assets/images/directory-view.png) +``` + +Light and dark mode HTML pages are available and will be used implicitly. + +### HTML templating with Python + +Because Sanic is using [html5tagger](https://github.com/sanic-org/html5tagger) under the hood to render the [new error pages](#nicer-traceback-formatting), you now have the package available to you to easily generate HTML pages in Python code: + +.. column:: + +```` +```python +from html5tagger import Document +from sanic import Request, Sanic, html + +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + doc = Document("My Website") + doc.h1("Hello, world.") + with doc.table(id="data"): + doc.tr.th("First").th("Second").th("Third") + doc.tr.td(1).td(2).td(3) + doc.p(class_="text")("A paragraph with ") + doc.a(href="/files")("a link")(" and ").em("formatting") + return html(doc) +``` +```` + +.. column:: + +```` +```html + + +My Website +

Hello, world.

+ + + +
First + Second + Third +
1 + 2 + 3 +
+

+ A paragraph with a link and formatting +``` +```` + +### Auto-index serving is available on static handlers + +Sanic can now be configured to serve an index file when serving a static directory. + +```python +app.static("/assets/", "/path/to/some/dir", index="index.html") +``` + +When using the above, requests to `http://example.com/assets/` will automatically serve the `index.html` file located in that directory. + +### Simpler CLI targets + +It is common practice for Sanic applications to use the variable `app` as the application instance. Because of this, the CLI application target (the second value of the `sanic` CLI command) now tries to infer the application instance based upon what the target is. If the target is a module that contains an `app` variable, it will use that. + +There are now four possible ways to launch a Sanic application from the CLI. + +#### 1. Application instance + +As normal, providing a path to a module and an application instance will work as expected. + +```sh +sanic path.to.module:app # global app instance +``` + +#### 2. Application factory + +Previously, to serve the factory pattern, you would need to use the `--factory` flag. This can be omitted now. + +```sh +sanic path.to.module:create_app # factory pattern +``` + +#### 3. Path to launch Sanic Simple Server + +Similarly, to launch the Sanic simple server (serve static directory), you previously needed to use the `--simple` flag. This can be omitted now, and instead simply provide the path to the directory. + +```sh +sanic ./path/to/directory/ # simple serve +``` + +#### 4. Python module containing an `app` variable + +As stated above, if the target is a module that contains an `app` variable, it will use that (assuming that `app` variable is a `Sanic` instance). + +```sh +sanic path.to.module # module with app instance +``` + +### More convenient methods for setting and deleting cookies + +The old cookie pattern was awkward and clunky. It didn't look like regular Python because of the "magic" going on under the hood. + +.. column:: + +``` +😱 This is not intuitive and is confusing for newcomers. +``` + +.. column:: + +```` +```python +response = text("There's a cookie up in this response") +response.cookies["test"] = "It worked!" +response.cookies["test"]["domain"] = ".yummy-yummy-cookie.com" +response.cookies["test"]["httponly"] = True +``` +```` + +There are now new methods (and completely overhauled `Cookie` and `CookieJar` objects) to make this process more convenient. + +.. column:: + +``` +😌 Ahh... Much nicer. +``` + +.. column:: + +```` +```python +response = text("There's a cookie up in this response") +response.add_cookie( + "test", + "It worked!", + domain=".yummy-yummy-cookie.com", + httponly=True +) +``` +```` + +### Better cookie compatibility + +Sanic has added support for [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes), making it seemless and easy to read and write cookies with the values. + +While setting the cookie... + +```py +response.cookies.add_cookie("foo", "bar", host_prefix=True) +``` + +This will create the prefixed cookie: `__Host-foo`. However, when accessing the cookie on an incoming request, you can do so without knowing about the existence of the header. + +```py +request.cookies.get("foo") +``` + +It should also be noted, cookies can be accessed as properties just like [headers](#access-any-header-as-a-property). + +```python +request.cookies.foo +``` + +And, cookies are similar to the `request.args` and `request.form` objects in that multiple values can be retrieved using `getlist`. + +```py +request.cookies.getlist("foo") +``` + +Also added is support for creating [partitioned cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie). + +```py +response.cookies.add_cookie(..., partitioned=True) +``` + +### 🚨 _BREAKING CHANGE_ - More consistent and powerful `SanicException` + +Sanic has for a while included the `SanicException` as a base class exception. This could be extended to add `status_code`, etc. [See more details](http://localhost:8080/en/guide/best-practices/exceptions.html). + +**NOW**, using all of the various exceptions has become easier. The commonly used exceptions can be imported directly from the root level module. + +```python +from sanic import NotFound, Unauthorized, BadRequest, ServerError +``` + +In addition, all of these arguments are available as keyword arguments on every exception type: + +| argument | type | description | +| --------- | ------ | ----------------------------------------------------------- | +| `quiet` | `bool` | Suppress the traceback from the logs | +| `context` | `dict` | Additional information shown in error pages _always_ | +| `extra` | `dict` | Additional information shown in error pages in _DEBUG_ mode | +| `headers` | `dict` | Additional headers sent in the response | + +None of these are themselves new features. However, they are more consistent in how you can use them, thus creating a powerful way to control error responses directly. + +```py +raise ServerError(headers={"foo": "bar"}) +``` + +The part of this that is a breaking change is that some formerly positional arguments are now keyword only. + +You are encouraged to look at the specific implementations for each error in the [API documents](https://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions). + +### 🚨 _BREAKING CHANGE_ - Refresh `Request.accept` functionality to be more performant and spec-compliant + +Parsing od the `Accept` headers into the `Request.accept` accessor has been improved. If you were using this property and relying upon its equality operation, this has changed. You should probably transition to using the `request.accept.match()` method. + +### Access any header as a property + +To simplify access to headers, you can access a raw (unparsed) version of the header as a property. The name of the header is the name of the property in all lowercase letters, and switching any hyphens (`-`) to underscores (`_`). + +For example: + +.. column:: + +```` +``` +GET /foo/bar HTTP/1.1 +Host: localhost +User-Agent: curl/7.88.1 +X-Request-ID: 123ABC +``` +```` + +.. column:: + +```` +```py +request.headers.host +request.headers.user_agent +request.headers.x_request_id +``` +```` + +### Consume `DELETE` body by default + +By default, the body of a `DELETE` request will now be consumed and read onto the `Request` object. This will make `body` available like on `POST`, `PUT`, and `PATCH` requests without any further action. + +### Custom `CertLoader` for direct control of creating `SSLContext` + +Sometimes you may want to create your own `SSLContext` object. To do this, you can create your own subclass of `CertLoader` that will generate your desired context object. + +```python +from sanic.worker.loader import CertLoader + +class MyCertLoader(CertLoader): + def load(self, app: Sanic) -> SSLContext: + ... + +app = Sanic(..., certloader_class=MyCertLoader) +``` + +### Deprecations and Removals + +1. _DEPRECATED_ - Dict-style cookie setting +2. _DEPRECATED_ - Using existence of JSON data on the request for one factor in using JSON error formatter +3. _REMOVED_ - Remove deprecated `__blueprintname__` property +4. _REMOVED_ - duplicate route names +5. _REMOVED_ - duplicate exception handler definitions +6. _REMOVED_ - inspector CLI with flags +7. _REMOVED_ - legacy server (including `sanic.server.serve_single` and `sanic.server.serve_multiple`) +8. _REMOVED_ - serving directory with bytes string +9. _REMOVED_ - `Request.request_middleware_started` +10. _REMOVED_ - `Websocket.connection` + +#### Duplicated route names are no longer allowed + +In version 22.9, Sanic announced that v23.3 would deprecate allowing routes to be registered with duplicate names. If you see the following error, it is because of that change: + +> sanic.exceptions.ServerError: Duplicate route names detected: SomeApp.some_handler. You should rename one or more of them explicitly by using the `name` param, or changing the implicit name derived from the class and function name. For more details, please see https\://sanic.dev/en/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed + +If you are seeing this, you should opt-in to using explicit names for your routes. + +.. column:: + +```` +**BAD** +```python +app = Sanic("SomeApp") + +@app.get("/") +@app.get("/foo") +async def handler(request: Request): +``` +```` + +.. column:: + +```` +**GOOD** +```python +app = Sanic("SomeApp") + +@app.get("/", name="root") +@app.get("/foo", name="foo") +async def handler(request: Request): +``` +```` + +#### Response cookies + +Response cookies act as a `dict` for compatibility purposes only. In version 24.3, all `dict` methods will be removed and response cookies will be objects only. + +Therefore, if you are using this pattern to set cookie properties, you will need to upgrade it before version 24.3. + +```python +resp = HTTPResponse() +resp.cookies["foo"] = "bar" +resp.cookies["foo"]["httponly"] = True +``` + +Instead, you should be using the `add_cookie` method: + +```python +resp = HTTPResponse() +resp.add_cookie("foo", "bar", httponly=True) +``` + +#### Request cookies + +Sanic has added support for reading duplicated cookie keys to be more in compliance with RFC specifications. To retain backwards compatibility, accessing a cookie value using `__getitem__` will continue to work to fetch the first value sent. Therefore, in version 23.3 and prior versions this will be `True`. + +```python +assert request.cookies["foo"] == "bar" +assert request.cookies.get("foo") == "bar" +``` + +Version 23.3 added `getlist` + +```python +assert request.cookies.getlist("foo") == ["bar"] +``` + +As stated above, the `get` and `getlist` methods are available similar to how they exist on other request properties (`request.args`, `request.form`, etc). Starting in v24.3, the `__getitem__` method for cookies will work exactly like those properties. This means that `__getitem__` will return a list of values. + +Therefore, if you are relying upon this functionality to return only one value, you should upgrade to the following pattern before v24.3. + +```python +assert request.cookies["foo"] == ["bar"] +assert request.cookies.get("foo") == "bar" +assert request.cookies.getlist("foo") == ["bar"] +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@deounix](https://github.com/deounix) +[@Kludex](https://github.com/Kludex) +[@mbendiksen](https://github.com/mbendiksen) +[@prryplatypus](https://github.com/prryplatypus) +[@r0x0d](https://github.com/r0x0d) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@stricaud](https://github.com/stricaud) +[@Tracyca209](https://github.com/Tracyca209) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From eb8a96c00dbfcefa913858627c6222e5d3470374 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:44 +0200 Subject: [PATCH 266/698] New translations v23.3.md (Korean) --- guide/content/ko/release-notes/2023/v23.3.md | 421 +++++++++++++++++++ 1 file changed, 421 insertions(+) create mode 100644 guide/content/ko/release-notes/2023/v23.3.md diff --git a/guide/content/ko/release-notes/2023/v23.3.md b/guide/content/ko/release-notes/2023/v23.3.md new file mode 100644 index 0000000000..70dc746698 --- /dev/null +++ b/guide/content/ko/release-notes/2023/v23.3.md @@ -0,0 +1,421 @@ +--- +title: Version 23.3 +--- + +# Version 23.3 + +.. toc:: + +## Introduction + +This is the first release of the version 23 [release cycle](../../org/policies.md#release-schedule). As such contains some deprecations and hopefully some _small_ breaking changes. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Nicer traceback formatting + +The SCO adopted two projects into the Sanic namespace on GitHub: [tracerite](https://github.com/sanic-org/tracerite) and [html5tagger](https://github.com/sanic-org/html5tagger). These projects team up to provide and incredible new error page with more details to help the debugging process. + +This is provided out of the box, and will adjust to display only relevant information whether in DEBUG more or PROD mode. + +.. column:: + +``` +**Using PROD mode** +![image](/assets/images/error-html-no-debug.png) +``` + +.. column:: + +``` +**Using DEBUG mode** +![image](/assets/images/error-html-debug.png) +``` + +Light and dark mode HTML pages are available and will be used implicitly. + +### Basic file browser on directories + +When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. + +.. column:: + +```` +```python +app.static("/uploads/", "/path/to/dir/", directory_view=True) +``` +```` + +.. column:: + +``` +![image](/assets/images/directory-view.png) +``` + +Light and dark mode HTML pages are available and will be used implicitly. + +### HTML templating with Python + +Because Sanic is using [html5tagger](https://github.com/sanic-org/html5tagger) under the hood to render the [new error pages](#nicer-traceback-formatting), you now have the package available to you to easily generate HTML pages in Python code: + +.. column:: + +```` +```python +from html5tagger import Document +from sanic import Request, Sanic, html + +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + doc = Document("My Website") + doc.h1("Hello, world.") + with doc.table(id="data"): + doc.tr.th("First").th("Second").th("Third") + doc.tr.td(1).td(2).td(3) + doc.p(class_="text")("A paragraph with ") + doc.a(href="/files")("a link")(" and ").em("formatting") + return html(doc) +``` +```` + +.. column:: + +```` +```html + + +My Website +

Hello, world.

+ + + +
First + Second + Third +
1 + 2 + 3 +
+

+ A paragraph with a link and formatting +``` +```` + +### Auto-index serving is available on static handlers + +Sanic can now be configured to serve an index file when serving a static directory. + +```python +app.static("/assets/", "/path/to/some/dir", index="index.html") +``` + +When using the above, requests to `http://example.com/assets/` will automatically serve the `index.html` file located in that directory. + +### Simpler CLI targets + +It is common practice for Sanic applications to use the variable `app` as the application instance. Because of this, the CLI application target (the second value of the `sanic` CLI command) now tries to infer the application instance based upon what the target is. If the target is a module that contains an `app` variable, it will use that. + +There are now four possible ways to launch a Sanic application from the CLI. + +#### 1. Application instance + +As normal, providing a path to a module and an application instance will work as expected. + +```sh +sanic path.to.module:app # global app instance +``` + +#### 2. Application factory + +Previously, to serve the factory pattern, you would need to use the `--factory` flag. This can be omitted now. + +```sh +sanic path.to.module:create_app # factory pattern +``` + +#### 3. Path to launch Sanic Simple Server + +Similarly, to launch the Sanic simple server (serve static directory), you previously needed to use the `--simple` flag. This can be omitted now, and instead simply provide the path to the directory. + +```sh +sanic ./path/to/directory/ # simple serve +``` + +#### 4. Python module containing an `app` variable + +As stated above, if the target is a module that contains an `app` variable, it will use that (assuming that `app` variable is a `Sanic` instance). + +```sh +sanic path.to.module # module with app instance +``` + +### More convenient methods for setting and deleting cookies + +The old cookie pattern was awkward and clunky. It didn't look like regular Python because of the "magic" going on under the hood. + +.. column:: + +``` +😱 This is not intuitive and is confusing for newcomers. +``` + +.. column:: + +```` +```python +response = text("There's a cookie up in this response") +response.cookies["test"] = "It worked!" +response.cookies["test"]["domain"] = ".yummy-yummy-cookie.com" +response.cookies["test"]["httponly"] = True +``` +```` + +There are now new methods (and completely overhauled `Cookie` and `CookieJar` objects) to make this process more convenient. + +.. column:: + +``` +😌 Ahh... Much nicer. +``` + +.. column:: + +```` +```python +response = text("There's a cookie up in this response") +response.add_cookie( + "test", + "It worked!", + domain=".yummy-yummy-cookie.com", + httponly=True +) +``` +```` + +### Better cookie compatibility + +Sanic has added support for [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes), making it seemless and easy to read and write cookies with the values. + +While setting the cookie... + +```py +response.cookies.add_cookie("foo", "bar", host_prefix=True) +``` + +This will create the prefixed cookie: `__Host-foo`. However, when accessing the cookie on an incoming request, you can do so without knowing about the existence of the header. + +```py +request.cookies.get("foo") +``` + +It should also be noted, cookies can be accessed as properties just like [headers](#access-any-header-as-a-property). + +```python +request.cookies.foo +``` + +And, cookies are similar to the `request.args` and `request.form` objects in that multiple values can be retrieved using `getlist`. + +```py +request.cookies.getlist("foo") +``` + +Also added is support for creating [partitioned cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie). + +```py +response.cookies.add_cookie(..., partitioned=True) +``` + +### 🚨 _BREAKING CHANGE_ - More consistent and powerful `SanicException` + +Sanic has for a while included the `SanicException` as a base class exception. This could be extended to add `status_code`, etc. [See more details](http://localhost:8080/en/guide/best-practices/exceptions.html). + +**NOW**, using all of the various exceptions has become easier. The commonly used exceptions can be imported directly from the root level module. + +```python +from sanic import NotFound, Unauthorized, BadRequest, ServerError +``` + +In addition, all of these arguments are available as keyword arguments on every exception type: + +| argument | type | description | +| --------- | ------ | ----------------------------------------------------------- | +| `quiet` | `bool` | Suppress the traceback from the logs | +| `context` | `dict` | Additional information shown in error pages _always_ | +| `extra` | `dict` | Additional information shown in error pages in _DEBUG_ mode | +| `headers` | `dict` | Additional headers sent in the response | + +None of these are themselves new features. However, they are more consistent in how you can use them, thus creating a powerful way to control error responses directly. + +```py +raise ServerError(headers={"foo": "bar"}) +``` + +The part of this that is a breaking change is that some formerly positional arguments are now keyword only. + +You are encouraged to look at the specific implementations for each error in the [API documents](https://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions). + +### 🚨 _BREAKING CHANGE_ - Refresh `Request.accept` functionality to be more performant and spec-compliant + +Parsing od the `Accept` headers into the `Request.accept` accessor has been improved. If you were using this property and relying upon its equality operation, this has changed. You should probably transition to using the `request.accept.match()` method. + +### Access any header as a property + +To simplify access to headers, you can access a raw (unparsed) version of the header as a property. The name of the header is the name of the property in all lowercase letters, and switching any hyphens (`-`) to underscores (`_`). + +For example: + +.. column:: + +```` +``` +GET /foo/bar HTTP/1.1 +Host: localhost +User-Agent: curl/7.88.1 +X-Request-ID: 123ABC +``` +```` + +.. column:: + +```` +```py +request.headers.host +request.headers.user_agent +request.headers.x_request_id +``` +```` + +### Consume `DELETE` body by default + +By default, the body of a `DELETE` request will now be consumed and read onto the `Request` object. This will make `body` available like on `POST`, `PUT`, and `PATCH` requests without any further action. + +### Custom `CertLoader` for direct control of creating `SSLContext` + +Sometimes you may want to create your own `SSLContext` object. To do this, you can create your own subclass of `CertLoader` that will generate your desired context object. + +```python +from sanic.worker.loader import CertLoader + +class MyCertLoader(CertLoader): + def load(self, app: Sanic) -> SSLContext: + ... + +app = Sanic(..., certloader_class=MyCertLoader) +``` + +### Deprecations and Removals + +1. _DEPRECATED_ - Dict-style cookie setting +2. _DEPRECATED_ - Using existence of JSON data on the request for one factor in using JSON error formatter +3. _REMOVED_ - Remove deprecated `__blueprintname__` property +4. _REMOVED_ - duplicate route names +5. _REMOVED_ - duplicate exception handler definitions +6. _REMOVED_ - inspector CLI with flags +7. _REMOVED_ - legacy server (including `sanic.server.serve_single` and `sanic.server.serve_multiple`) +8. _REMOVED_ - serving directory with bytes string +9. _REMOVED_ - `Request.request_middleware_started` +10. _REMOVED_ - `Websocket.connection` + +#### Duplicated route names are no longer allowed + +In version 22.9, Sanic announced that v23.3 would deprecate allowing routes to be registered with duplicate names. If you see the following error, it is because of that change: + +> sanic.exceptions.ServerError: Duplicate route names detected: SomeApp.some_handler. You should rename one or more of them explicitly by using the `name` param, or changing the implicit name derived from the class and function name. For more details, please see https\://sanic.dev/en/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed + +If you are seeing this, you should opt-in to using explicit names for your routes. + +.. column:: + +```` +**BAD** +```python +app = Sanic("SomeApp") + +@app.get("/") +@app.get("/foo") +async def handler(request: Request): +``` +```` + +.. column:: + +```` +**GOOD** +```python +app = Sanic("SomeApp") + +@app.get("/", name="root") +@app.get("/foo", name="foo") +async def handler(request: Request): +``` +```` + +#### Response cookies + +Response cookies act as a `dict` for compatibility purposes only. In version 24.3, all `dict` methods will be removed and response cookies will be objects only. + +Therefore, if you are using this pattern to set cookie properties, you will need to upgrade it before version 24.3. + +```python +resp = HTTPResponse() +resp.cookies["foo"] = "bar" +resp.cookies["foo"]["httponly"] = True +``` + +Instead, you should be using the `add_cookie` method: + +```python +resp = HTTPResponse() +resp.add_cookie("foo", "bar", httponly=True) +``` + +#### Request cookies + +Sanic has added support for reading duplicated cookie keys to be more in compliance with RFC specifications. To retain backwards compatibility, accessing a cookie value using `__getitem__` will continue to work to fetch the first value sent. Therefore, in version 23.3 and prior versions this will be `True`. + +```python +assert request.cookies["foo"] == "bar" +assert request.cookies.get("foo") == "bar" +``` + +Version 23.3 added `getlist` + +```python +assert request.cookies.getlist("foo") == ["bar"] +``` + +As stated above, the `get` and `getlist` methods are available similar to how they exist on other request properties (`request.args`, `request.form`, etc). Starting in v24.3, the `__getitem__` method for cookies will work exactly like those properties. This means that `__getitem__` will return a list of values. + +Therefore, if you are relying upon this functionality to return only one value, you should upgrade to the following pattern before v24.3. + +```python +assert request.cookies["foo"] == ["bar"] +assert request.cookies.get("foo") == "bar" +assert request.cookies.getlist("foo") == ["bar"] +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@deounix](https://github.com/deounix) +[@Kludex](https://github.com/Kludex) +[@mbendiksen](https://github.com/mbendiksen) +[@prryplatypus](https://github.com/prryplatypus) +[@r0x0d](https://github.com/r0x0d) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@stricaud](https://github.com/stricaud) +[@Tracyca209](https://github.com/Tracyca209) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 0542c4c22ca421442fdde783f4de829197d474c2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:45 +0200 Subject: [PATCH 267/698] New translations v23.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.3.md | 421 +++++++++++++++++++ 1 file changed, 421 insertions(+) create mode 100644 guide/content/zh/release-notes/2023/v23.3.md diff --git a/guide/content/zh/release-notes/2023/v23.3.md b/guide/content/zh/release-notes/2023/v23.3.md new file mode 100644 index 0000000000..70dc746698 --- /dev/null +++ b/guide/content/zh/release-notes/2023/v23.3.md @@ -0,0 +1,421 @@ +--- +title: Version 23.3 +--- + +# Version 23.3 + +.. toc:: + +## Introduction + +This is the first release of the version 23 [release cycle](../../org/policies.md#release-schedule). As such contains some deprecations and hopefully some _small_ breaking changes. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Nicer traceback formatting + +The SCO adopted two projects into the Sanic namespace on GitHub: [tracerite](https://github.com/sanic-org/tracerite) and [html5tagger](https://github.com/sanic-org/html5tagger). These projects team up to provide and incredible new error page with more details to help the debugging process. + +This is provided out of the box, and will adjust to display only relevant information whether in DEBUG more or PROD mode. + +.. column:: + +``` +**Using PROD mode** +![image](/assets/images/error-html-no-debug.png) +``` + +.. column:: + +``` +**Using DEBUG mode** +![image](/assets/images/error-html-debug.png) +``` + +Light and dark mode HTML pages are available and will be used implicitly. + +### Basic file browser on directories + +When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. + +.. column:: + +```` +```python +app.static("/uploads/", "/path/to/dir/", directory_view=True) +``` +```` + +.. column:: + +``` +![image](/assets/images/directory-view.png) +``` + +Light and dark mode HTML pages are available and will be used implicitly. + +### HTML templating with Python + +Because Sanic is using [html5tagger](https://github.com/sanic-org/html5tagger) under the hood to render the [new error pages](#nicer-traceback-formatting), you now have the package available to you to easily generate HTML pages in Python code: + +.. column:: + +```` +```python +from html5tagger import Document +from sanic import Request, Sanic, html + +app = Sanic("TestApp") + +@app.get("/") +async def handler(request: Request): + doc = Document("My Website") + doc.h1("Hello, world.") + with doc.table(id="data"): + doc.tr.th("First").th("Second").th("Third") + doc.tr.td(1).td(2).td(3) + doc.p(class_="text")("A paragraph with ") + doc.a(href="/files")("a link")(" and ").em("formatting") + return html(doc) +``` +```` + +.. column:: + +```` +```html + + +My Website +

Hello, world.

+ + + +
First + Second + Third +
1 + 2 + 3 +
+

+ A paragraph with a link and formatting +``` +```` + +### Auto-index serving is available on static handlers + +Sanic can now be configured to serve an index file when serving a static directory. + +```python +app.static("/assets/", "/path/to/some/dir", index="index.html") +``` + +When using the above, requests to `http://example.com/assets/` will automatically serve the `index.html` file located in that directory. + +### Simpler CLI targets + +It is common practice for Sanic applications to use the variable `app` as the application instance. Because of this, the CLI application target (the second value of the `sanic` CLI command) now tries to infer the application instance based upon what the target is. If the target is a module that contains an `app` variable, it will use that. + +There are now four possible ways to launch a Sanic application from the CLI. + +#### 1. Application instance + +As normal, providing a path to a module and an application instance will work as expected. + +```sh +sanic path.to.module:app # global app instance +``` + +#### 2. Application factory + +Previously, to serve the factory pattern, you would need to use the `--factory` flag. This can be omitted now. + +```sh +sanic path.to.module:create_app # factory pattern +``` + +#### 3. Path to launch Sanic Simple Server + +Similarly, to launch the Sanic simple server (serve static directory), you previously needed to use the `--simple` flag. This can be omitted now, and instead simply provide the path to the directory. + +```sh +sanic ./path/to/directory/ # simple serve +``` + +#### 4. Python module containing an `app` variable + +As stated above, if the target is a module that contains an `app` variable, it will use that (assuming that `app` variable is a `Sanic` instance). + +```sh +sanic path.to.module # module with app instance +``` + +### More convenient methods for setting and deleting cookies + +The old cookie pattern was awkward and clunky. It didn't look like regular Python because of the "magic" going on under the hood. + +.. column:: + +``` +😱 This is not intuitive and is confusing for newcomers. +``` + +.. column:: + +```` +```python +response = text("There's a cookie up in this response") +response.cookies["test"] = "It worked!" +response.cookies["test"]["domain"] = ".yummy-yummy-cookie.com" +response.cookies["test"]["httponly"] = True +``` +```` + +There are now new methods (and completely overhauled `Cookie` and `CookieJar` objects) to make this process more convenient. + +.. column:: + +``` +😌 Ahh... Much nicer. +``` + +.. column:: + +```` +```python +response = text("There's a cookie up in this response") +response.add_cookie( + "test", + "It worked!", + domain=".yummy-yummy-cookie.com", + httponly=True +) +``` +```` + +### Better cookie compatibility + +Sanic has added support for [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes), making it seemless and easy to read and write cookies with the values. + +While setting the cookie... + +```py +response.cookies.add_cookie("foo", "bar", host_prefix=True) +``` + +This will create the prefixed cookie: `__Host-foo`. However, when accessing the cookie on an incoming request, you can do so without knowing about the existence of the header. + +```py +request.cookies.get("foo") +``` + +It should also be noted, cookies can be accessed as properties just like [headers](#access-any-header-as-a-property). + +```python +request.cookies.foo +``` + +And, cookies are similar to the `request.args` and `request.form` objects in that multiple values can be retrieved using `getlist`. + +```py +request.cookies.getlist("foo") +``` + +Also added is support for creating [partitioned cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie). + +```py +response.cookies.add_cookie(..., partitioned=True) +``` + +### 🚨 _BREAKING CHANGE_ - More consistent and powerful `SanicException` + +Sanic has for a while included the `SanicException` as a base class exception. This could be extended to add `status_code`, etc. [See more details](http://localhost:8080/en/guide/best-practices/exceptions.html). + +**NOW**, using all of the various exceptions has become easier. The commonly used exceptions can be imported directly from the root level module. + +```python +from sanic import NotFound, Unauthorized, BadRequest, ServerError +``` + +In addition, all of these arguments are available as keyword arguments on every exception type: + +| argument | type | description | +| --------- | ------ | ----------------------------------------------------------- | +| `quiet` | `bool` | Suppress the traceback from the logs | +| `context` | `dict` | Additional information shown in error pages _always_ | +| `extra` | `dict` | Additional information shown in error pages in _DEBUG_ mode | +| `headers` | `dict` | Additional headers sent in the response | + +None of these are themselves new features. However, they are more consistent in how you can use them, thus creating a powerful way to control error responses directly. + +```py +raise ServerError(headers={"foo": "bar"}) +``` + +The part of this that is a breaking change is that some formerly positional arguments are now keyword only. + +You are encouraged to look at the specific implementations for each error in the [API documents](https://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions). + +### 🚨 _BREAKING CHANGE_ - Refresh `Request.accept` functionality to be more performant and spec-compliant + +Parsing od the `Accept` headers into the `Request.accept` accessor has been improved. If you were using this property and relying upon its equality operation, this has changed. You should probably transition to using the `request.accept.match()` method. + +### Access any header as a property + +To simplify access to headers, you can access a raw (unparsed) version of the header as a property. The name of the header is the name of the property in all lowercase letters, and switching any hyphens (`-`) to underscores (`_`). + +For example: + +.. column:: + +```` +``` +GET /foo/bar HTTP/1.1 +Host: localhost +User-Agent: curl/7.88.1 +X-Request-ID: 123ABC +``` +```` + +.. column:: + +```` +```py +request.headers.host +request.headers.user_agent +request.headers.x_request_id +``` +```` + +### Consume `DELETE` body by default + +By default, the body of a `DELETE` request will now be consumed and read onto the `Request` object. This will make `body` available like on `POST`, `PUT`, and `PATCH` requests without any further action. + +### Custom `CertLoader` for direct control of creating `SSLContext` + +Sometimes you may want to create your own `SSLContext` object. To do this, you can create your own subclass of `CertLoader` that will generate your desired context object. + +```python +from sanic.worker.loader import CertLoader + +class MyCertLoader(CertLoader): + def load(self, app: Sanic) -> SSLContext: + ... + +app = Sanic(..., certloader_class=MyCertLoader) +``` + +### Deprecations and Removals + +1. _DEPRECATED_ - Dict-style cookie setting +2. _DEPRECATED_ - Using existence of JSON data on the request for one factor in using JSON error formatter +3. _REMOVED_ - Remove deprecated `__blueprintname__` property +4. _REMOVED_ - duplicate route names +5. _REMOVED_ - duplicate exception handler definitions +6. _REMOVED_ - inspector CLI with flags +7. _REMOVED_ - legacy server (including `sanic.server.serve_single` and `sanic.server.serve_multiple`) +8. _REMOVED_ - serving directory with bytes string +9. _REMOVED_ - `Request.request_middleware_started` +10. _REMOVED_ - `Websocket.connection` + +#### Duplicated route names are no longer allowed + +In version 22.9, Sanic announced that v23.3 would deprecate allowing routes to be registered with duplicate names. If you see the following error, it is because of that change: + +> sanic.exceptions.ServerError: Duplicate route names detected: SomeApp.some_handler. You should rename one or more of them explicitly by using the `name` param, or changing the implicit name derived from the class and function name. For more details, please see https\://sanic.dev/en/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed + +If you are seeing this, you should opt-in to using explicit names for your routes. + +.. column:: + +```` +**BAD** +```python +app = Sanic("SomeApp") + +@app.get("/") +@app.get("/foo") +async def handler(request: Request): +``` +```` + +.. column:: + +```` +**GOOD** +```python +app = Sanic("SomeApp") + +@app.get("/", name="root") +@app.get("/foo", name="foo") +async def handler(request: Request): +``` +```` + +#### Response cookies + +Response cookies act as a `dict` for compatibility purposes only. In version 24.3, all `dict` methods will be removed and response cookies will be objects only. + +Therefore, if you are using this pattern to set cookie properties, you will need to upgrade it before version 24.3. + +```python +resp = HTTPResponse() +resp.cookies["foo"] = "bar" +resp.cookies["foo"]["httponly"] = True +``` + +Instead, you should be using the `add_cookie` method: + +```python +resp = HTTPResponse() +resp.add_cookie("foo", "bar", httponly=True) +``` + +#### Request cookies + +Sanic has added support for reading duplicated cookie keys to be more in compliance with RFC specifications. To retain backwards compatibility, accessing a cookie value using `__getitem__` will continue to work to fetch the first value sent. Therefore, in version 23.3 and prior versions this will be `True`. + +```python +assert request.cookies["foo"] == "bar" +assert request.cookies.get("foo") == "bar" +``` + +Version 23.3 added `getlist` + +```python +assert request.cookies.getlist("foo") == ["bar"] +``` + +As stated above, the `get` and `getlist` methods are available similar to how they exist on other request properties (`request.args`, `request.form`, etc). Starting in v24.3, the `__getitem__` method for cookies will work exactly like those properties. This means that `__getitem__` will return a list of values. + +Therefore, if you are relying upon this functionality to return only one value, you should upgrade to the following pattern before v24.3. + +```python +assert request.cookies["foo"] == ["bar"] +assert request.cookies.get("foo") == "bar" +assert request.cookies.getlist("foo") == ["bar"] +``` + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@deounix](https://github.com/deounix) +[@Kludex](https://github.com/Kludex) +[@mbendiksen](https://github.com/mbendiksen) +[@prryplatypus](https://github.com/prryplatypus) +[@r0x0d](https://github.com/r0x0d) +[@SaidBySolo](https://github.com/SaidBySolo) +[@sjsadowski](https://github.com/sjsadowski) +[@stricaud](https://github.com/stricaud) +[@Tracyca209](https://github.com/Tracyca209) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From e5009749ceac852fb03a143a452c1c60b464df75 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:46 +0200 Subject: [PATCH 268/698] New translations v23.6.md (Japanese) --- guide/content/ja/release-notes/2023/v23.6.md | 199 +++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/ja/release-notes/2023/v23.6.md diff --git a/guide/content/ja/release-notes/2023/v23.6.md b/guide/content/ja/release-notes/2023/v23.6.md new file mode 100644 index 0000000000..74a3260c2b --- /dev/null +++ b/guide/content/ja/release-notes/2023/v23.6.md @@ -0,0 +1,199 @@ +--- +title: Version 23.6 +--- + +# Version 23.6 + +.. toc:: + +## Introduction + +This is the second release of the version 23 [release cycle](../../org/policies.md#release-schedule). If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Remove Python 3.7 support + +Python 3.7 is due to reach its scheduled upstream end-of-life on 2023-06-27. Sanic is now dropping support for Python 3.7, and requires Python 3.8 or newer. + +See [#2777](https://github.com/sanic-org/sanic/pull/2777). + +### Resolve pypy compatibility issues + +A small patch was added to the `os` module to once again allow for Sanic to run with PyPy. This workaround replaces the missing `readlink` function (missing in PyPy `os` module) with the function `os.path.realpath`, which serves to the same purpose. + +See [#2782](https://github.com/sanic-org/sanic/pull/2782). + +### Add custom typing to config and ctx objects + +The `sanic.Sanic` and `sanic.Request` object have become generic types that will make it more convenient to have fully typed `config` and `ctx` objects. + +In the most simple form, the `Sanic` object is typed as: + +```python +from sanic import Sanic +app = Sanic("test") +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]" +``` + +.. tip:: Note + +``` +It should be noted, there is *no* requirement to use the generic types. The default types are `sanic.config.Config` and `types.SimpleNamespace`. This new feature is just an option for those that want to use it and existing types of `app: Sanic` and `request: Request` should work just fine. +``` + +Now it is possible to have a fully-type `app.config`, `app.ctx`, and `request.ctx` objects though generics. This allows for better integration with auto completion tools in IDEs improving the developer experience. + +```python +from sanic import Request, Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +class RequestContext: + foo: Foo + +class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]): + @staticmethod + def make_context() -> RequestContext: + ctx = RequestContext() + ctx.foo = Foo() + return ctx + +app = Sanic( + "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest +) + +@app.get("/") +async def handler(request: CustomRequest): + ... +``` + +As a side effect, now `request.ctx` is lazy initialized, which should reduce some overhead when the `request.ctx` is unused. + +One further change you may have noticed in the above snippet is the `make_context` method. This new method can be used by custom `Request` types to inject an object different from a `SimpleNamespace` similar to how Sanic has allowed custom application context objects for a while. + +For a more thorough discussion, see [custom typed application](../basics/app.md#custom-typed-application) and [custom typed request](../basics/app.md#custom-typed-request). + +See [#2785](https://github.com/sanic-org/sanic/pull/2785). + +### Universal exception signal + +A new exception signal added for **ALL** exceptions raised while the server is running: `"server.exception.reporting"`. This is a universal signal that will be emitted for any exception raised, and dispatched as its own task. This means that it will _not_ block the request handler, and will _not_ be affected by any middleware. + +This is useful for catching exceptions that may occur outside of the request handler (for example in signals, or in a background task), and it intended for use to create a consistent error handling experience for the user. + +```python +from sanic.signals import Event + +@app.signal(Event.SERVER_LIFECYCLE_EXCEPTION) +async def catch_any_exception(app: Sanic, exception: Exception): + app.ctx.my_error_reporter_utility.error(exception) +``` + +This pattern can be simplified with a new decorator `@app.report_exception`: + +```python +@app.report_exception +async def catch_any_exception(app: Sanic, exception: Exception): + print("Caught exception:", exception) +``` + +It should be pointed out that this happens in a background task and is **NOT** for manipulation of an error response. It is only for reporting, logging, or other purposes that should be triggered when an application error occurs. + +See [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792). + +### Add name prefixing to BP groups + +Sanic had been raising a warning on duplicate route names for a while, and started to enforce route name uniqueness in [v23.3](https://sanic.dev/en/guide/release-notes/v23.3.html#deprecations-and-removals). This created a complication for blueprint composition. + +New name prefixing parameter for blueprints groups has been added to alleviate this issue. It allows nesting of blueprints and groups to make them composable. + +The addition is the new `name_prefix` parameter as shown in this snippet. + +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +bp1.add_route(lambda _: ..., "/", name="route1") +bp2.add_route(lambda _: ..., "/", name="route2") + +group_a = Blueprint.group( + bp1, bp2, url_prefix="/group-a", name_prefix="group-a" +) +group_b = Blueprint.group( + bp1, bp2, url_prefix="/group-b", name_prefix="group-b" +) + +app = Sanic("TestApp") +app.blueprint(group_a) +app.blueprint(group_b) +``` + +The routes built will be named as follows: + +- `TestApp.group-a_bp1.route1` +- `TestApp.group-a_bp2.route2` +- `TestApp.group-b_bp1.route1` +- `TestApp.group-b_bp2.route2` + +See [#2727](https://github.com/sanic-org/sanic/pull/2727). + +### Add `request.client_ip` + +Sanic has introduced `request.client_ip`, a new accessor that provides client's IP address from both local and proxy data. It allows running the application directly on Internet or behind a proxy. This is equivalent to `request.remote_addr or request.ip`, providing the client IP regardless of how the application is deployed. + +See [#2790](https://github.com/sanic-org/sanic/pull/2790). + +### Increase of `KEEP_ALIVE_TIMEOUT` default to 120 seconds + +The default `KEEP_ALIVE_TIMEOUT` value changed from 5 seconds to 120 seconds. It is of course still configurable, but this change should improve performance on long latency connections, where reconnecting is expensive, and better fits typical user flow browsing pages with longer-than-5-second intervals. + +Sanic has historically used 5 second timeouts to quickly close idle connections. The chosen value of **120 seconds** is indeed larger than Nginx default of 75, and is the same value that Caddy server has by default. + +Related to [#2531](https://github.com/sanic-org/sanic/issues/2531) and +[#2681](https://github.com/sanic-org/sanic/issues/2681). + +See [#2670](https://github.com/sanic-org/sanic/pull/2670). + +### Set multiprocessing start method early + +Due to how Python handles `multiprocessing`, it may be confusing to some users how to properly create synchronization primitives. This is due to how Sanic creates the `multiprocessing` context. This change sets the start method early so that any primitives created will properly attach to the correct context. + +For most users, this should not be noticeable or impactful. But, it should make creation of something like this easier and work as expected. + +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` + +See [#2776](https://github.com/sanic-org/sanic/pull/2776). + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@chuckds](https://github.com/chuckds) +[@deounix](https://github.com/deounix) +[@guacs](https://github.com/guacs) +[@liamcoatman](https://github.com/liamcoatman) +[@moshe742](https://github.com/moshe742) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@Thirumalai](https://github.com/Thirumalai) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 71bfe4cc4d50627995f86ec2f9cd6fee62e8a424 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:48 +0200 Subject: [PATCH 269/698] New translations v23.6.md (Korean) --- guide/content/ko/release-notes/2023/v23.6.md | 199 +++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/ko/release-notes/2023/v23.6.md diff --git a/guide/content/ko/release-notes/2023/v23.6.md b/guide/content/ko/release-notes/2023/v23.6.md new file mode 100644 index 0000000000..74a3260c2b --- /dev/null +++ b/guide/content/ko/release-notes/2023/v23.6.md @@ -0,0 +1,199 @@ +--- +title: Version 23.6 +--- + +# Version 23.6 + +.. toc:: + +## Introduction + +This is the second release of the version 23 [release cycle](../../org/policies.md#release-schedule). If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Remove Python 3.7 support + +Python 3.7 is due to reach its scheduled upstream end-of-life on 2023-06-27. Sanic is now dropping support for Python 3.7, and requires Python 3.8 or newer. + +See [#2777](https://github.com/sanic-org/sanic/pull/2777). + +### Resolve pypy compatibility issues + +A small patch was added to the `os` module to once again allow for Sanic to run with PyPy. This workaround replaces the missing `readlink` function (missing in PyPy `os` module) with the function `os.path.realpath`, which serves to the same purpose. + +See [#2782](https://github.com/sanic-org/sanic/pull/2782). + +### Add custom typing to config and ctx objects + +The `sanic.Sanic` and `sanic.Request` object have become generic types that will make it more convenient to have fully typed `config` and `ctx` objects. + +In the most simple form, the `Sanic` object is typed as: + +```python +from sanic import Sanic +app = Sanic("test") +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]" +``` + +.. tip:: Note + +``` +It should be noted, there is *no* requirement to use the generic types. The default types are `sanic.config.Config` and `types.SimpleNamespace`. This new feature is just an option for those that want to use it and existing types of `app: Sanic` and `request: Request` should work just fine. +``` + +Now it is possible to have a fully-type `app.config`, `app.ctx`, and `request.ctx` objects though generics. This allows for better integration with auto completion tools in IDEs improving the developer experience. + +```python +from sanic import Request, Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +class RequestContext: + foo: Foo + +class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]): + @staticmethod + def make_context() -> RequestContext: + ctx = RequestContext() + ctx.foo = Foo() + return ctx + +app = Sanic( + "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest +) + +@app.get("/") +async def handler(request: CustomRequest): + ... +``` + +As a side effect, now `request.ctx` is lazy initialized, which should reduce some overhead when the `request.ctx` is unused. + +One further change you may have noticed in the above snippet is the `make_context` method. This new method can be used by custom `Request` types to inject an object different from a `SimpleNamespace` similar to how Sanic has allowed custom application context objects for a while. + +For a more thorough discussion, see [custom typed application](../basics/app.md#custom-typed-application) and [custom typed request](../basics/app.md#custom-typed-request). + +See [#2785](https://github.com/sanic-org/sanic/pull/2785). + +### Universal exception signal + +A new exception signal added for **ALL** exceptions raised while the server is running: `"server.exception.reporting"`. This is a universal signal that will be emitted for any exception raised, and dispatched as its own task. This means that it will _not_ block the request handler, and will _not_ be affected by any middleware. + +This is useful for catching exceptions that may occur outside of the request handler (for example in signals, or in a background task), and it intended for use to create a consistent error handling experience for the user. + +```python +from sanic.signals import Event + +@app.signal(Event.SERVER_LIFECYCLE_EXCEPTION) +async def catch_any_exception(app: Sanic, exception: Exception): + app.ctx.my_error_reporter_utility.error(exception) +``` + +This pattern can be simplified with a new decorator `@app.report_exception`: + +```python +@app.report_exception +async def catch_any_exception(app: Sanic, exception: Exception): + print("Caught exception:", exception) +``` + +It should be pointed out that this happens in a background task and is **NOT** for manipulation of an error response. It is only for reporting, logging, or other purposes that should be triggered when an application error occurs. + +See [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792). + +### Add name prefixing to BP groups + +Sanic had been raising a warning on duplicate route names for a while, and started to enforce route name uniqueness in [v23.3](https://sanic.dev/en/guide/release-notes/v23.3.html#deprecations-and-removals). This created a complication for blueprint composition. + +New name prefixing parameter for blueprints groups has been added to alleviate this issue. It allows nesting of blueprints and groups to make them composable. + +The addition is the new `name_prefix` parameter as shown in this snippet. + +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +bp1.add_route(lambda _: ..., "/", name="route1") +bp2.add_route(lambda _: ..., "/", name="route2") + +group_a = Blueprint.group( + bp1, bp2, url_prefix="/group-a", name_prefix="group-a" +) +group_b = Blueprint.group( + bp1, bp2, url_prefix="/group-b", name_prefix="group-b" +) + +app = Sanic("TestApp") +app.blueprint(group_a) +app.blueprint(group_b) +``` + +The routes built will be named as follows: + +- `TestApp.group-a_bp1.route1` +- `TestApp.group-a_bp2.route2` +- `TestApp.group-b_bp1.route1` +- `TestApp.group-b_bp2.route2` + +See [#2727](https://github.com/sanic-org/sanic/pull/2727). + +### Add `request.client_ip` + +Sanic has introduced `request.client_ip`, a new accessor that provides client's IP address from both local and proxy data. It allows running the application directly on Internet or behind a proxy. This is equivalent to `request.remote_addr or request.ip`, providing the client IP regardless of how the application is deployed. + +See [#2790](https://github.com/sanic-org/sanic/pull/2790). + +### Increase of `KEEP_ALIVE_TIMEOUT` default to 120 seconds + +The default `KEEP_ALIVE_TIMEOUT` value changed from 5 seconds to 120 seconds. It is of course still configurable, but this change should improve performance on long latency connections, where reconnecting is expensive, and better fits typical user flow browsing pages with longer-than-5-second intervals. + +Sanic has historically used 5 second timeouts to quickly close idle connections. The chosen value of **120 seconds** is indeed larger than Nginx default of 75, and is the same value that Caddy server has by default. + +Related to [#2531](https://github.com/sanic-org/sanic/issues/2531) and +[#2681](https://github.com/sanic-org/sanic/issues/2681). + +See [#2670](https://github.com/sanic-org/sanic/pull/2670). + +### Set multiprocessing start method early + +Due to how Python handles `multiprocessing`, it may be confusing to some users how to properly create synchronization primitives. This is due to how Sanic creates the `multiprocessing` context. This change sets the start method early so that any primitives created will properly attach to the correct context. + +For most users, this should not be noticeable or impactful. But, it should make creation of something like this easier and work as expected. + +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` + +See [#2776](https://github.com/sanic-org/sanic/pull/2776). + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@chuckds](https://github.com/chuckds) +[@deounix](https://github.com/deounix) +[@guacs](https://github.com/guacs) +[@liamcoatman](https://github.com/liamcoatman) +[@moshe742](https://github.com/moshe742) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@Thirumalai](https://github.com/Thirumalai) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 6123d152d74d000f269ab0e119d8ad9d622e99b5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:49 +0200 Subject: [PATCH 270/698] New translations v23.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.6.md | 199 +++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 guide/content/zh/release-notes/2023/v23.6.md diff --git a/guide/content/zh/release-notes/2023/v23.6.md b/guide/content/zh/release-notes/2023/v23.6.md new file mode 100644 index 0000000000..74a3260c2b --- /dev/null +++ b/guide/content/zh/release-notes/2023/v23.6.md @@ -0,0 +1,199 @@ +--- +title: Version 23.6 +--- + +# Version 23.6 + +.. toc:: + +## Introduction + +This is the second release of the version 23 [release cycle](../../org/policies.md#release-schedule). If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... + +### Remove Python 3.7 support + +Python 3.7 is due to reach its scheduled upstream end-of-life on 2023-06-27. Sanic is now dropping support for Python 3.7, and requires Python 3.8 or newer. + +See [#2777](https://github.com/sanic-org/sanic/pull/2777). + +### Resolve pypy compatibility issues + +A small patch was added to the `os` module to once again allow for Sanic to run with PyPy. This workaround replaces the missing `readlink` function (missing in PyPy `os` module) with the function `os.path.realpath`, which serves to the same purpose. + +See [#2782](https://github.com/sanic-org/sanic/pull/2782). + +### Add custom typing to config and ctx objects + +The `sanic.Sanic` and `sanic.Request` object have become generic types that will make it more convenient to have fully typed `config` and `ctx` objects. + +In the most simple form, the `Sanic` object is typed as: + +```python +from sanic import Sanic +app = Sanic("test") +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]" +``` + +.. tip:: Note + +``` +It should be noted, there is *no* requirement to use the generic types. The default types are `sanic.config.Config` and `types.SimpleNamespace`. This new feature is just an option for those that want to use it and existing types of `app: Sanic` and `request: Request` should work just fine. +``` + +Now it is possible to have a fully-type `app.config`, `app.ctx`, and `request.ctx` objects though generics. This allows for better integration with auto completion tools in IDEs improving the developer experience. + +```python +from sanic import Request, Sanic +from sanic.config import Config + +class CustomConfig(Config): + pass + +class Foo: + pass + +class RequestContext: + foo: Foo + +class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]): + @staticmethod + def make_context() -> RequestContext: + ctx = RequestContext() + ctx.foo = Foo() + return ctx + +app = Sanic( + "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest +) + +@app.get("/") +async def handler(request: CustomRequest): + ... +``` + +As a side effect, now `request.ctx` is lazy initialized, which should reduce some overhead when the `request.ctx` is unused. + +One further change you may have noticed in the above snippet is the `make_context` method. This new method can be used by custom `Request` types to inject an object different from a `SimpleNamespace` similar to how Sanic has allowed custom application context objects for a while. + +For a more thorough discussion, see [custom typed application](../basics/app.md#custom-typed-application) and [custom typed request](../basics/app.md#custom-typed-request). + +See [#2785](https://github.com/sanic-org/sanic/pull/2785). + +### Universal exception signal + +A new exception signal added for **ALL** exceptions raised while the server is running: `"server.exception.reporting"`. This is a universal signal that will be emitted for any exception raised, and dispatched as its own task. This means that it will _not_ block the request handler, and will _not_ be affected by any middleware. + +This is useful for catching exceptions that may occur outside of the request handler (for example in signals, or in a background task), and it intended for use to create a consistent error handling experience for the user. + +```python +from sanic.signals import Event + +@app.signal(Event.SERVER_LIFECYCLE_EXCEPTION) +async def catch_any_exception(app: Sanic, exception: Exception): + app.ctx.my_error_reporter_utility.error(exception) +``` + +This pattern can be simplified with a new decorator `@app.report_exception`: + +```python +@app.report_exception +async def catch_any_exception(app: Sanic, exception: Exception): + print("Caught exception:", exception) +``` + +It should be pointed out that this happens in a background task and is **NOT** for manipulation of an error response. It is only for reporting, logging, or other purposes that should be triggered when an application error occurs. + +See [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792). + +### Add name prefixing to BP groups + +Sanic had been raising a warning on duplicate route names for a while, and started to enforce route name uniqueness in [v23.3](https://sanic.dev/en/guide/release-notes/v23.3.html#deprecations-and-removals). This created a complication for blueprint composition. + +New name prefixing parameter for blueprints groups has been added to alleviate this issue. It allows nesting of blueprints and groups to make them composable. + +The addition is the new `name_prefix` parameter as shown in this snippet. + +```python +bp1 = Blueprint("bp1", url_prefix="/bp1") +bp2 = Blueprint("bp2", url_prefix="/bp2") + +bp1.add_route(lambda _: ..., "/", name="route1") +bp2.add_route(lambda _: ..., "/", name="route2") + +group_a = Blueprint.group( + bp1, bp2, url_prefix="/group-a", name_prefix="group-a" +) +group_b = Blueprint.group( + bp1, bp2, url_prefix="/group-b", name_prefix="group-b" +) + +app = Sanic("TestApp") +app.blueprint(group_a) +app.blueprint(group_b) +``` + +The routes built will be named as follows: + +- `TestApp.group-a_bp1.route1` +- `TestApp.group-a_bp2.route2` +- `TestApp.group-b_bp1.route1` +- `TestApp.group-b_bp2.route2` + +See [#2727](https://github.com/sanic-org/sanic/pull/2727). + +### Add `request.client_ip` + +Sanic has introduced `request.client_ip`, a new accessor that provides client's IP address from both local and proxy data. It allows running the application directly on Internet or behind a proxy. This is equivalent to `request.remote_addr or request.ip`, providing the client IP regardless of how the application is deployed. + +See [#2790](https://github.com/sanic-org/sanic/pull/2790). + +### Increase of `KEEP_ALIVE_TIMEOUT` default to 120 seconds + +The default `KEEP_ALIVE_TIMEOUT` value changed from 5 seconds to 120 seconds. It is of course still configurable, but this change should improve performance on long latency connections, where reconnecting is expensive, and better fits typical user flow browsing pages with longer-than-5-second intervals. + +Sanic has historically used 5 second timeouts to quickly close idle connections. The chosen value of **120 seconds** is indeed larger than Nginx default of 75, and is the same value that Caddy server has by default. + +Related to [#2531](https://github.com/sanic-org/sanic/issues/2531) and +[#2681](https://github.com/sanic-org/sanic/issues/2681). + +See [#2670](https://github.com/sanic-org/sanic/pull/2670). + +### Set multiprocessing start method early + +Due to how Python handles `multiprocessing`, it may be confusing to some users how to properly create synchronization primitives. This is due to how Sanic creates the `multiprocessing` context. This change sets the start method early so that any primitives created will properly attach to the correct context. + +For most users, this should not be noticeable or impactful. But, it should make creation of something like this easier and work as expected. + +```python +from multiprocessing import Queue + +@app.main_process_start +async def main_process_start(app): + app.shared_ctx.queue = Queue() +``` + +See [#2776](https://github.com/sanic-org/sanic/pull/2776). + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@chuckds](https://github.com/chuckds) +[@deounix](https://github.com/deounix) +[@guacs](https://github.com/guacs) +[@liamcoatman](https://github.com/liamcoatman) +[@moshe742](https://github.com/moshe742) +[@prryplatypus](https://github.com/prryplatypus) +[@SaidBySolo](https://github.com/SaidBySolo) +[@Thirumalai](https://github.com/Thirumalai) +[@Tronic](https://github.com/Tronic) + +*** + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 549dcf43ebe4b3cabea27c7465a25cc0d1a1ceb6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:50 +0200 Subject: [PATCH 271/698] New translations v23.9.md (Japanese) --- guide/content/ja/release-notes/2023/v23.9.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 guide/content/ja/release-notes/2023/v23.9.md diff --git a/guide/content/ja/release-notes/2023/v23.9.md b/guide/content/ja/release-notes/2023/v23.9.md new file mode 100644 index 0000000000..630da3625b --- /dev/null +++ b/guide/content/ja/release-notes/2023/v23.9.md @@ -0,0 +1,7 @@ +--- +title: Version 23.9 +--- + +# Version 23.9 + +_Due to circumstances at the time, v.23.9 was skipped._ From f8c0b7acf67d3cb75ceb93c65e1af774a2f33374 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:50 +0200 Subject: [PATCH 272/698] New translations v23.9.md (Korean) --- guide/content/ko/release-notes/2023/v23.9.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 guide/content/ko/release-notes/2023/v23.9.md diff --git a/guide/content/ko/release-notes/2023/v23.9.md b/guide/content/ko/release-notes/2023/v23.9.md new file mode 100644 index 0000000000..630da3625b --- /dev/null +++ b/guide/content/ko/release-notes/2023/v23.9.md @@ -0,0 +1,7 @@ +--- +title: Version 23.9 +--- + +# Version 23.9 + +_Due to circumstances at the time, v.23.9 was skipped._ From b285310209f8e3fee78d79fee257bb9c9f3513d3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:51 +0200 Subject: [PATCH 273/698] New translations v23.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.9.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 guide/content/zh/release-notes/2023/v23.9.md diff --git a/guide/content/zh/release-notes/2023/v23.9.md b/guide/content/zh/release-notes/2023/v23.9.md new file mode 100644 index 0000000000..630da3625b --- /dev/null +++ b/guide/content/zh/release-notes/2023/v23.9.md @@ -0,0 +1,7 @@ +--- +title: Version 23.9 +--- + +# Version 23.9 + +_Due to circumstances at the time, v.23.9 was skipped._ From f797a5f597363f3229d845c90dfd00a26b6cfff5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:23:56 +0200 Subject: [PATCH 274/698] New translations changelog.md (Japanese) --- guide/content/ja/release-notes/changelog.md | 1531 +++++++++++++++++++ 1 file changed, 1531 insertions(+) create mode 100644 guide/content/ja/release-notes/changelog.md diff --git a/guide/content/ja/release-notes/changelog.md b/guide/content/ja/release-notes/changelog.md new file mode 100644 index 0000000000..b98df20c9e --- /dev/null +++ b/guide/content/ja/release-notes/changelog.md @@ -0,0 +1,1531 @@ +--- +content_class: changelog +--- + +# Changelog + +🔶 Current release\ +🔷 In support LTS release + +## Version 23.12.0 🔶🔷 + +_Current version_ + +### Features + +- [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes +- [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown +- [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket +- [#2822](https://github.com/sanic-org/sanic/pull/2822) Listener and signal prioritization +- [#2831](https://github.com/sanic-org/sanic/pull/2831) Reduce memory consumption +- [#2837](https://github.com/sanic-org/sanic/pull/2837) Accept bare cookies +- [#2841](https://github.com/sanic-org/sanic/pull/2841) Add `websocket.handler.` signals +- [#2805](https://github.com/sanic-org/sanic/pull/2805) Add changed files to reload trigger listeners +- [#2813](https://github.com/sanic-org/sanic/pull/2813) Allow for simple signals +- [#2827](https://github.com/sanic-org/sanic/pull/2827) Improve functionality and consistency of `Sanic.event()` +- [#2851](https://github.com/sanic-org/sanic/pull/2851) Allow range requests for a single byte +- [#2854](https://github.com/sanic-org/sanic/pull/2854) Better `Request.scheme` for websocket requests +- [#2858](https://github.com/sanic-org/sanic/pull/2858) Convert Sanic `Request` to a Websockets `Request` for handshake +- [#2859](https://github.com/sanic-org/sanic/pull/2859) Add a REPL to the `sanic` CLI +- [#2870](https://github.com/sanic-org/sanic/pull/2870) Add Python 3.12 support +- [#2875](https://github.com/sanic-org/sanic/pull/2875) Better exception on multiprocessing context conflicts + +### Bugfixes + +- [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data + +### Deprecations and Removals + +### Developer infrastructure + +- [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases +- [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU +- [#2807](https://github.com/sanic-org/sanic/pull/2807) Add constraint for autodocsum (lint issue in old package version) +- [#2808](https://github.com/sanic-org/sanic/pull/2808) Refactor GitHub Actions +- [#2814](https://github.com/sanic-org/sanic/pull/2814) Run CI pipeline on git push +- [#2846](https://github.com/sanic-org/sanic/pull/2846) Drop old performance tests/benchmarks +- [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile cleanup +- [#2865](https://github.com/sanic-org/sanic/pull/2865) + [#2869](https://github.com/sanic-org/sanic/pull/2869) + [#2872](https://github.com/sanic-org/sanic/pull/2872) + [#2879](https://github.com/sanic-org/sanic/pull/2879) + Add ruff to toolchain +- [#2866](https://github.com/sanic-org/sanic/pull/2866) Fix the alt svc test to run locally with explicit buffer nbytes +- [#2877](https://github.com/sanic-org/sanic/pull/2877) Use Python's trusted publisher in deployments +- [#2882](https://github.com/sanic-org/sanic/pull/2882) Introduce dynamic port fixture in targeted locations in the test suite + +### Improved Documentation + +- [#2781](https://github.com/sanic-org/sanic/pull/2781) + [#2821](https://github.com/sanic-org/sanic/pull/2821) + [#2861](https://github.com/sanic-org/sanic/pull/2861) + [#2863](https://github.com/sanic-org/sanic/pull/2863) + Conversion of User Guide to the SHH (Sanic, html5tagger, HTMX) stack +- [#2810](https://github.com/sanic-org/sanic/pull/2810) Update README +- [#2855](https://github.com/sanic-org/sanic/pull/2855) Edit Discord badge +- [#2864](https://github.com/sanic-org/sanic/pull/2864) Adjust documentation for using state properties within http/https redirection document + +## Version 23.9.0 + +_Due to circumstances at the time, v.23.9 was skipped._ + +## Version 23.6.0 + +### Features + +- [#2670](https://github.com/sanic-org/sanic/pull/2670) Increase `KEEP_ALIVE_TIMEOUT` default to 120 seconds +- [#2716](https://github.com/sanic-org/sanic/pull/2716) Adding allow route overwrite option in blueprint +- [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792) Add a new exception signal for ALL exceptions raised anywhere in application +- [#2727](https://github.com/sanic-org/sanic/pull/2727) Add name prefixing to BP groups +- [#2754](https://github.com/sanic-org/sanic/pull/2754) Update request type on middleware types +- [#2770](https://github.com/sanic-org/sanic/pull/2770) Better exception message on startup time application induced import error +- [#2776](https://github.com/sanic-org/sanic/pull/2776) Set multiprocessing start method early +- [#2785](https://github.com/sanic-org/sanic/pull/2785) Add custom typing to config and ctx objects +- [#2790](https://github.com/sanic-org/sanic/pull/2790) Add `request.client_ip` + +### Bugfixes + +- [#2728](https://github.com/sanic-org/sanic/pull/2728) Fix traversals for intended results +- [#2729](https://github.com/sanic-org/sanic/pull/2729) Handle case when headers argument of ResponseStream constructor is None +- [#2737](https://github.com/sanic-org/sanic/pull/2737) Fix type annotation for `JSONREsponse` default content type +- [#2740](https://github.com/sanic-org/sanic/pull/2740) Use Sanic's serializer for JSON responses in the Inspector +- [#2760](https://github.com/sanic-org/sanic/pull/2760) Support for `Request.get_current` in ASGI mode +- [#2773](https://github.com/sanic-org/sanic/pull/2773) Alow Blueprint routes to explicitly define error_format +- [#2774](https://github.com/sanic-org/sanic/pull/2774) Resolve headers on different renderers +- [#2782](https://github.com/sanic-org/sanic/pull/2782) Resolve pypy compatibility issues + +### Deprecations and Removals + +- [#2777](https://github.com/sanic-org/sanic/pull/2777) Remove Python 3.7 support + +### Developer infrastructure + +- [#2766](https://github.com/sanic-org/sanic/pull/2766) Unpin setuptools version +- [#2779](https://github.com/sanic-org/sanic/pull/2779) Run keep alive tests in loop to get available port + +### Improved Documentation + +- [#2741](https://github.com/sanic-org/sanic/pull/2741) Better documentation examples about running Sanic + From that list, the items to highlight in the release notes: + +## Version 23.3.0 + +### Features + +- [#2545](https://github.com/sanic-org/sanic/pull/2545) Standardize init of exceptions for more consistent control of HTTP responses using exceptions +- [#2606](https://github.com/sanic-org/sanic/pull/2606) Decode headers as UTF-8 also in ASGI +- [#2646](https://github.com/sanic-org/sanic/pull/2646) Separate ASGI request and lifespan callables +- [#2659](https://github.com/sanic-org/sanic/pull/2659) Use `FALLBACK_ERROR_FORMAT` for handlers that return `empty()` +- [#2662](https://github.com/sanic-org/sanic/pull/2662) Add basic file browser (HTML page) and auto-index serving +- [#2667](https://github.com/sanic-org/sanic/pull/2667) Nicer traceback formatting (HTML page) +- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter error page rendering format selection; more reliant upon header and "common sense" defaults +- [#2680](https://github.com/sanic-org/sanic/pull/2680) Check the status of socket before shutting down with `SHUT_RDWR` +- [#2687](https://github.com/sanic-org/sanic/pull/2687) Refresh `Request.accept` functionality to be more performant and spec-compliant +- [#2696](https://github.com/sanic-org/sanic/pull/2696) Add header accessors as properties + ``` + Example-Field: Foo, Bar + Example-Field: Baz + ``` + ```python + request.headers.example_field == "Foo, Bar,Baz" + ``` +- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simpler CLI targets + + ```sh + $ sanic path.to.module:app # global app instance + $ sanic path.to.module:create_app # factory pattern + $ sanic ./path/to/directory/ # simple serve + ``` +- [#2701](https://github.com/sanic-org/sanic/pull/2701) API to define a number of workers in managed processes +- [#2704](https://github.com/sanic-org/sanic/pull/2704) Add convenience for dynamic changes to routing +- [#2706](https://github.com/sanic-org/sanic/pull/2706) Add convenience methods for cookie creation and deletion + + ```python + response = text("...") + response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com") + ``` +- [#2707](https://github.com/sanic-org/sanic/pull/2707) Simplified `parse_content_header` escaping to be RFC-compliant and remove outdated FF hack +- [#2710](https://github.com/sanic-org/sanic/pull/2710) Stricter charset handling and escaping of request URLs +- [#2711](https://github.com/sanic-org/sanic/pull/2711) Consume body on `DELETE` by default +- [#2719](https://github.com/sanic-org/sanic/pull/2719) Allow `password` to be passed to TLS context +- [#2720](https://github.com/sanic-org/sanic/pull/2720) Skip middleware on `RequestCancelled` +- [#2721](https://github.com/sanic-org/sanic/pull/2721) Change access logging format to `%s` +- [#2722](https://github.com/sanic-org/sanic/pull/2722) Add `CertLoader` as application option for directly controlling `SSLContext` objects +- [#2725](https://github.com/sanic-org/sanic/pull/2725) Worker sync state tolerance on race condition + +### Bugfixes + +- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket to pass thru bytes as is +- [#2697](https://github.com/sanic-org/sanic/pull/2697) Fix comparison between datetime aware and naive in `file` when using `If-Modified-Since` + +### Deprecations and Removals + +- [#2666](https://github.com/sanic-org/sanic/pull/2666) Remove deprecated `__blueprintname__` property + +### Improved Documentation + +- [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect + +## Version 22.12.0 🔷 + +_Current LTS version_ + +### Features + +- [#2569](https://github.com/sanic-org/sanic/pull/2569) Add `JSONResponse` class with some convenient methods when updating a response object +- [#2598](https://github.com/sanic-org/sanic/pull/2598) Change `uvloop` requirement to `>=0.15.0` +- [#2609](https://github.com/sanic-org/sanic/pull/2609) Add compatibility with `websockets` v11.0 +- [#2610](https://github.com/sanic-org/sanic/pull/2610) Kill server early on worker error + - Raise deadlock timeout to 30s +- [#2617](https://github.com/sanic-org/sanic/pull/2617) Scale number of running server workers +- [#2621](https://github.com/sanic-org/sanic/pull/2621) [#2634](https://github.com/sanic-org/sanic/pull/2634) Send `SIGKILL` on subsequent `ctrl+c` to force worker exit +- [#2622](https://github.com/sanic-org/sanic/pull/2622) Add API to restart all workers from the multiplexer +- [#2624](https://github.com/sanic-org/sanic/pull/2624) Default to `spawn` for all subprocesses unless specifically set: + ```python + from sanic import Sanic + + Sanic.start_method = "fork" + ``` +- [#2625](https://github.com/sanic-org/sanic/pull/2625) Filename normalisation of form-data/multipart file uploads +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector: + - Remote access to inspect running Sanic instances + - TLS support for encrypted calls to Inspector + - Authentication to Inspector with API key + - Ability to extend Inspector with custom commands +- [#2632](https://github.com/sanic-org/sanic/pull/2632) Control order of restart operations +- [#2633](https://github.com/sanic-org/sanic/pull/2633) Move reload interval to class variable +- [#2636](https://github.com/sanic-org/sanic/pull/2636) Add `priority` to `register_middleware` method +- [#2639](https://github.com/sanic-org/sanic/pull/2639) Add `unquote` to `add_route` method +- [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets to receive `text` or `bytes` + +### Bugfixes + +- [#2607](https://github.com/sanic-org/sanic/pull/2607) Force socket shutdown before close to allow rebinding +- [#2590](https://github.com/sanic-org/sanic/pull/2590) Use actual `StrEnum` in Python 3.11+ +- [#2615](https://github.com/sanic-org/sanic/pull/2615) Ensure middleware executes only once per request timeout +- [#2627](https://github.com/sanic-org/sanic/pull/2627) Crash ASGI application on lifespan failure +- [#2635](https://github.com/sanic-org/sanic/pull/2635) Resolve error with low-level server creation on Windows + +### Deprecations and Removals + +- [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) Signal conditions and triggers saved on `signal.extra` +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector + - 🚨 _BREAKING CHANGE_: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol + - _DEPRECATE_: The `--inspect*` commands have been deprecated in favor of `inspect ...` commands +- [#2628](https://github.com/sanic-org/sanic/pull/2628) Replace deprecated `distutils.strtobool` + +### Developer infrastructure + +- [#2612](https://github.com/sanic-org/sanic/pull/2612) Add CI testing for Python 3.11 + +## Version 22.9.1 + +### Features + +- [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered + +### Bugfixes + +- [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation +- [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility +- [#2592](https://github.com/sanic-org/sanic/pull/2592) Fix properties in nested blueprint groups +- [#2595](https://github.com/sanic-org/sanic/pull/2595) Introduce sleep interval on new worker reloader + +### Deprecations and Removals + +### Developer infrastructure + +- [#2588](https://github.com/sanic-org/sanic/pull/2588) Markdown templates on issue forms + +### Improved Documentation + +- [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 documentation +- [#2582](https://github.com/sanic-org/sanic/pull/2582) Cleanup documentation on Windows support + +## Version 22.9.0 + +### Features + +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom loads function +- [#2490](https://github.com/sanic-org/sanic/pull/2490) Make `WebsocketImplProtocol` async iterable +- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refactor +- [#2506](https://github.com/sanic-org/sanic/pull/2506) Use `pathlib` for path resolution (for static file serving) +- [#2508](https://github.com/sanic-org/sanic/pull/2508) Use `path.parts` instead of `match` (for static file serving) +- [#2513](https://github.com/sanic-org/sanic/pull/2513) Better request cancel handling +- [#2516](https://github.com/sanic-org/sanic/pull/2516) Add request properties for HTTP method info: + - `request.is_safe` + - `request.is_idempotent` + - `request.is_cacheable` + - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _for more information about when these apply_ +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI +- [#2526](https://github.com/sanic-org/sanic/pull/2526) Cache control support for static files for returning 304 when appropriate +- [#2533](https://github.com/sanic-org/sanic/pull/2533) Refactor `_static_request_handler` +- [#2540](https://github.com/sanic-org/sanic/pull/2540) Add signals before and after handler execution + - `http.handler.before` + - `http.handler.after` +- [#2542](https://github.com/sanic-org/sanic/pull/2542) Add _[redacted]_ to CLI :) +- [#2546](https://github.com/sanic-org/sanic/pull/2546) Add deprecation warning filter +- [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware priority and performance enhancements + +### Bugfixes + +- [#2495](https://github.com/sanic-org/sanic/pull/2495) Prevent directory traversion with static files +- [#2515](https://github.com/sanic-org/sanic/pull/2515) Do not apply double slash to paths in certain static dirs in Blueprints + +### Deprecations and Removals + +- [#2525](https://github.com/sanic-org/sanic/pull/2525) Warn on duplicate route names, will be prevented outright in v23.3 +- [#2537](https://github.com/sanic-org/sanic/pull/2537) Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3 + +### Developer infrastructure + +- [#2504](https://github.com/sanic-org/sanic/pull/2504) Cleanup test suite +- [#2505](https://github.com/sanic-org/sanic/pull/2505) Replace Unsupported Python Version Number from the Contributing Doc +- [#2530](https://github.com/sanic-org/sanic/pull/2530) Do not include tests folder in installed package resolver + +### Improved Documentation + +- [#2502](https://github.com/sanic-org/sanic/pull/2502) Fix a few typos +- [#2517](https://github.com/sanic-org/sanic/pull/2517) [#2536](https://github.com/sanic-org/sanic/pull/2536) Add some type hints + +## Version 22.6.2 + +### Bugfixes + +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI + +## Version 22.6.1 + +### Bugfixes + +- [#2477](https://github.com/sanic-org/sanic/pull/2477) Sanic static directory fails when folder name ends with ".." + +## Version 22.6.0 + +### Features + +- [#2378](https://github.com/sanic-org/sanic/pull/2378) Introduce HTTP/3 and autogeneration of TLS certificates in `DEBUG` mode + - 👶 _EARLY RELEASE FEATURE_: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented. + - 📦 _EXTRA REQUIREMENT_: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a [HTTP/3 capable client](https://curl.se/docs/http3.html). + - 📦 _EXTRA REQUIREMENT_: In order to use TLS autogeneration, you must install either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). +- [#2416](https://github.com/sanic-org/sanic/pull/2416) Add message to `task.cancel` +- [#2420](https://github.com/sanic-org/sanic/pull/2420) Add exception aliases for more consistent naming with standard HTTP response types (`BadRequest`, `MethodNotAllowed`, `RangeNotSatisfiable`) +- [#2432](https://github.com/sanic-org/sanic/pull/2432) Expose ASGI `scope` as a property on the `Request` object +- [#2438](https://github.com/sanic-org/sanic/pull/2438) Easier access to websocket class for annotation: `from sanic import Websocket` +- [#2439](https://github.com/sanic-org/sanic/pull/2439) New API for reading form values with options: `Request.get_form` +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom `loads` function +- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) Improved API to support setting cache control headers +- [#2453](https://github.com/sanic-org/sanic/pull/2453) Move verbosity filtering to logger +- [#2475](https://github.com/sanic-org/sanic/pull/2475) Expose getter for current request using `Request.get_current()` + +### Bugfixes + +- [#2448](https://github.com/sanic-org/sanic/pull/2448) Fix to allow running with `pythonw.exe` or places where there is no `sys.stdout` +- [#2451](https://github.com/sanic-org/sanic/pull/2451) Trigger `http.lifecycle.request` signal in ASGI mode +- [#2455](https://github.com/sanic-org/sanic/pull/2455) Resolve typing of stacked route definitions +- [#2463](https://github.com/sanic-org/sanic/pull/2463) Properly catch websocket CancelledError in websocket handler in Python 3.7 + +### Deprecations and Removals + +- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 deprecations and changes + 1. Optional application registry + 2. Execution of custom handlers after some part of response was sent + 3. Configuring fallback handlers on the `ErrorHandler` + 4. Custom `LOGO` setting + 5. `sanic.response.stream` + 6. `AsyncioServer.init` + +### Developer infrastructure + +- [#2449](https://github.com/sanic-org/sanic/pull/2449) Clean up `black` and `isort` config +- [#2479](https://github.com/sanic-org/sanic/pull/2479) Fix some flappy tests + +### Improved Documentation + +- [#2461](https://github.com/sanic-org/sanic/pull/2461) Update example to match current application naming standards +- [#2466](https://github.com/sanic-org/sanic/pull/2466) Better type annotation for `Extend` +- [#2485](https://github.com/sanic-org/sanic/pull/2485) Improved help messages in CLI + +## Version 22.3.0 + +### Features + +- [#2347](https://github.com/sanic-org/sanic/pull/2347) API for multi-application server + - 🚨 _BREAKING CHANGE_: The old `sanic.worker.GunicornWorker` has been **removed**. To run Sanic with `gunicorn`, you should use it thru `uvicorn` [as described in their docs](https://www.uvicorn.org/#running-with-gunicorn). + - 🧁 _SIDE EFFECT_: Named background tasks are now supported, even in Python 3.7 +- [#2357](https://github.com/sanic-org/sanic/pull/2357) Parse `Authorization` header as `Request.credentials` +- [#2361](https://github.com/sanic-org/sanic/pull/2361) Add config option to skip `Touchup` step in application startup +- [#2372](https://github.com/sanic-org/sanic/pull/2372) Updates to CLI help messaging +- [#2382](https://github.com/sanic-org/sanic/pull/2382) Downgrade warnings to backwater debug messages +- [#2396](https://github.com/sanic-org/sanic/pull/2396) Allow for `multidict` v0.6 +- [#2401](https://github.com/sanic-org/sanic/pull/2401) Upgrade CLI catching for alternative application run types +- [#2402](https://github.com/sanic-org/sanic/pull/2402) Conditionally inject CLI arguments into factory +- [#2413](https://github.com/sanic-org/sanic/pull/2413) Add new start and stop event listeners to reloader process +- [#2414](https://github.com/sanic-org/sanic/pull/2414) Remove loop as required listener arg +- [#2415](https://github.com/sanic-org/sanic/pull/2415) Better exception for bad URL parsing +- [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) Add a new extention parameter type: ``, ``, ``, ``, ``, `` + - 👶 _BETA FEATURE_: This feature will not work with `path` type matching, and is being released as a beta feature only. +- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) Change `register_pattern` to accept a `str` or `Pattern` +- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) Default matching on non-empty strings only, and new `strorempty` pattern type + - 🚨 _BREAKING CHANGE_: Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now **only** match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. + +### Bugfixes + +- [#2373](https://github.com/sanic-org/sanic/pull/2373) Remove `error_logger` on websockets +- [#2381](https://github.com/sanic-org/sanic/pull/2381) Fix newly assigned `None` in task registry +- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) Add type casting to regex route matching +- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) Add requirements check on regex routes (this resolves, for example, multiple static directories with differing `host` values) + +### Deprecations and Removals + +- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 Deprecations and changes + 1. `debug=True` and `--debug` do _NOT_ automatically run `auto_reload` + 2. Default error render is with plain text (browsers still get HTML by default because `auto` looks at headers) + 3. `config` is required for `ErrorHandler.finalize` + 4. `ErrorHandler.lookup` requires two positional args + 5. Unused websocket protocol args removed +- [#2344](https://github.com/sanic-org/sanic/pull/2344) Deprecate loading of lowercase environment variables + +### Developer infrastructure + +- [#2363](https://github.com/sanic-org/sanic/pull/2363) Revert code coverage back to Codecov +- [#2405](https://github.com/sanic-org/sanic/pull/2405) Upgrade tests for `sanic-routing` changes +- [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) Allow for httpx v0.22 + +### Improved Documentation + +- [#2350](https://github.com/sanic-org/sanic/pull/2350) Fix link in README for ASGI +- [#2398](https://github.com/sanic-org/sanic/pull/2398) Document middleware on_request and on_response +- [#2409](https://github.com/sanic-org/sanic/pull/2409) Add missing documentation for `Request.respond` + +### Miscellaneous + +- [#2376](https://github.com/sanic-org/sanic/pull/2376) Fix typing for `ListenerMixin.listener` +- [#2383](https://github.com/sanic-org/sanic/pull/2383) Clear deprecation warning in `asyncio.wait` +- [#2387](https://github.com/sanic-org/sanic/pull/2387) Cleanup `__slots__` implementations +- [#2390](https://github.com/sanic-org/sanic/pull/2390) Clear deprecation warning in `asyncio.get_event_loop` + +## Version 21.12.1 + +- [#2349](https://github.com/sanic-org/sanic/pull/2349) Only display MOTD on startup +- [#2354](https://github.com/sanic-org/sanic/pull/2354) Ignore name argument in Python 3.7 +- [#2355](https://github.com/sanic-org/sanic/pull/2355) Add config.update support for all config values + +## Version 21.12.0 + +### Features + +- [#2260](https://github.com/sanic-org/sanic/pull/2260) Allow early Blueprint registrations to still apply later added objects +- [#2262](https://github.com/sanic-org/sanic/pull/2262) Noisy exceptions - force logging of all exceptions +- [#2264](https://github.com/sanic-org/sanic/pull/2264) Optional `uvloop` by configuration +- [#2270](https://github.com/sanic-org/sanic/pull/2270) Vhost support using multiple TLS certificates +- [#2277](https://github.com/sanic-org/sanic/pull/2277) Change signal routing for increased consistency + - _BREAKING CHANGE_: If you were manually routing signals there is a breaking change. The signal router's `get` is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using `app.dispatch` or `bp.dispatch`, there is no change. +- [#2290](https://github.com/sanic-org/sanic/pull/2290) Add contextual exceptions +- [#2291](https://github.com/sanic-org/sanic/pull/2291) Increase join concat performance +- [#2295](https://github.com/sanic-org/sanic/pull/2295), [#2316](https://github.com/sanic-org/sanic/pull/2316), [#2331](https://github.com/sanic-org/sanic/pull/2331) Restructure of CLI and application state with new displays and more command parity with `app.run` +- [#2302](https://github.com/sanic-org/sanic/pull/2302) Add route context at definition time +- [#2304](https://github.com/sanic-org/sanic/pull/2304) Named tasks and new API for managing background tasks +- [#2307](https://github.com/sanic-org/sanic/pull/2307) On app auto-reload, provide insight of changed files +- [#2308](https://github.com/sanic-org/sanic/pull/2308) Auto extend application with [Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) if it is installed, and provide first class support for accessing the extensions +- [#2309](https://github.com/sanic-org/sanic/pull/2309) Builtin signals changed to `Enum` +- [#2313](https://github.com/sanic-org/sanic/pull/2313) Support additional config implementation use case +- [#2321](https://github.com/sanic-org/sanic/pull/2321) Refactor environment variable hydration logic +- [#2327](https://github.com/sanic-org/sanic/pull/2327) Prevent sending multiple or mixed responses on a single request +- [#2330](https://github.com/sanic-org/sanic/pull/2330) Custom type casting on environment variables +- [#2332](https://github.com/sanic-org/sanic/pull/2332) Make all deprecation notices consistent +- [#2335](https://github.com/sanic-org/sanic/pull/2335) Allow underscore to start instance names + +### Bugfixes + +- [#2273](https://github.com/sanic-org/sanic/pull/2273) Replace assignation by typing for `websocket_handshake` +- [#2285](https://github.com/sanic-org/sanic/pull/2285) Fix IPv6 display in startup logs +- [#2299](https://github.com/sanic-org/sanic/pull/2299) Dispatch `http.lifecyle.response` from exception handler + +### Deprecations and Removals + +- [#2306](https://github.com/sanic-org/sanic/pull/2306) Removal of deprecated items + - `Sanic` and `Blueprint` may no longer have arbitrary properties attached to them + - `Sanic` and `Blueprint` forced to have compliant names + - alphanumeric + `_` + `-` + - must start with letter or `_` + - `load_env` keyword argument of `Sanic` + - `sanic.exceptions.abort` + - `sanic.views.CompositionView` + - `sanic.response.StreamingHTTPResponse` + - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming +- [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting + +### Developer infrastructure + +- [#2251](https://github.com/sanic-org/sanic/pull/2251) Change dev install command +- [#2286](https://github.com/sanic-org/sanic/pull/2286) Change codeclimate complexity threshold from 5 to 10 +- [#2287](https://github.com/sanic-org/sanic/pull/2287) Update host test function names so they are not overwritten +- [#2292](https://github.com/sanic-org/sanic/pull/2292) Fail CI on error +- [#2311](https://github.com/sanic-org/sanic/pull/2311), [#2324](https://github.com/sanic-org/sanic/pull/2324) Do not run tests for draft PRs +- [#2336](https://github.com/sanic-org/sanic/pull/2336) Remove paths from coverage checks +- [#2338](https://github.com/sanic-org/sanic/pull/2338) Cleanup ports on tests + +### Improved Documentation + +- [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2329), [#2333](https://github.com/sanic-org/sanic/pull/2333) Cleanup typos and fix language + +### Miscellaneous + +- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) Add Python 3.10 support +- [#2279](https://github.com/sanic-org/sanic/pull/2279), [#2317](https://github.com/sanic-org/sanic/pull/2317), [#2322](https://github.com/sanic-org/sanic/pull/2322) Add/correct missing type annotations +- [#2305](https://github.com/sanic-org/sanic/pull/2305) Fix examples to use modern implementations + +## Version 21.9.3 + +_Rerelease of v21.9.2 with some cleanup_ + +## Version 21.9.2 + +- [#2268](https://github.com/sanic-org/sanic/pull/2268) Make HTTP connections start in IDLE stage, avoiding delays and error messages +- [#2310](https://github.com/sanic-org/sanic/pull/2310) More consistent config setting with post-FALLBACK_ERROR_FORMAT apply + +## Version 21.9.1 + +- [#2259](https://github.com/sanic-org/sanic/pull/2259) Allow non-conforming ErrorHandlers + +## Version 21.9.0 + +### Features + +- [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) Complete overhaul of I/O to websockets +- [#2160](https://github.com/sanic-org/sanic/pull/2160) Add new 17 signals into server and request lifecycles +- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto` fallback formatting upon exception +- [#2184](https://github.com/sanic-org/sanic/pull/2184) Introduce implementation for copying a Blueprint +- [#2200](https://github.com/sanic-org/sanic/pull/2200) Accept header parsing +- [#2207](https://github.com/sanic-org/sanic/pull/2207) Log remote address if available +- [#2209](https://github.com/sanic-org/sanic/pull/2209) Add convenience methods to BP groups +- [#2216](https://github.com/sanic-org/sanic/pull/2216) Add default messages to SanicExceptions +- [#2225](https://github.com/sanic-org/sanic/pull/2225) Type annotation convenience for annotated handlers with path parameters +- [#2236](https://github.com/sanic-org/sanic/pull/2236) Allow Falsey (but not-None) responses from route handlers +- [#2238](https://github.com/sanic-org/sanic/pull/2238) Add `exception` decorator to Blueprint Groups +- [#2244](https://github.com/sanic-org/sanic/pull/2244) Explicit static directive for serving file or dir (ex: `static(..., resource_type="file")`) +- [#2245](https://github.com/sanic-org/sanic/pull/2245) Close HTTP loop when connection task cancelled + +### Bugfixes + +- [#2188](https://github.com/sanic-org/sanic/pull/2188) Fix the handling of the end of a chunked request +- [#2195](https://github.com/sanic-org/sanic/pull/2195) Resolve unexpected error handling on static requests +- [#2208](https://github.com/sanic-org/sanic/pull/2208) Make blueprint-based exceptions attach and trigger in a more intuitive manner +- [#2211](https://github.com/sanic-org/sanic/pull/2211) Fixed for handling exceptions of asgi app call +- [#2213](https://github.com/sanic-org/sanic/pull/2213) Fix bug where ws exceptions not being logged +- [#2231](https://github.com/sanic-org/sanic/pull/2231) Cleaner closing of tasks by using `abort()` in strategic places to avoid dangling sockets +- [#2247](https://github.com/sanic-org/sanic/pull/2247) Fix logging of auto-reload status in debug mode +- [#2246](https://github.com/sanic-org/sanic/pull/2246) Account for BP with exception handler but no routes + +### Developer infrastructure + +- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP unit tests with raw client +- [#2199](https://github.com/sanic-org/sanic/pull/2199) Switch to codeclimate +- [#2214](https://github.com/sanic-org/sanic/pull/2214) Try Reopening Windows Tests +- [#2229](https://github.com/sanic-org/sanic/pull/2229) Refactor `HttpProtocol` into a base class +- [#2230](https://github.com/sanic-org/sanic/pull/2230) Refactor `server.py` into multi-file module + +### Miscellaneous + +- [#2173](https://github.com/sanic-org/sanic/pull/2173) Remove Duplicated Dependencies and PEP 517 Support +- [#2193](https://github.com/sanic-org/sanic/pull/2193), [#2196](https://github.com/sanic-org/sanic/pull/2196), [#2217](https://github.com/sanic-org/sanic/pull/2217) Type annotation changes + +## Version 21.6.1 + +**Bugfixes** + +- [#2178](https://github.com/sanic-org/sanic/pull/2178) Update + sanic-routing to allow for better splitting of complex URI + templates +- [#2183](https://github.com/sanic-org/sanic/pull/2183) Proper + handling of chunked request bodies to resolve phantom 503 in logs +- [#2181](https://github.com/sanic-org/sanic/pull/2181) Resolve + regression in exception logging +- [#2201](https://github.com/sanic-org/sanic/pull/2201) Cleanup + request info in pipelined requests + +## Version 21.6.0 + +**Features** + +- [#2094](https://github.com/sanic-org/sanic/pull/2094) Add + `response.eof()` method for closing a stream in a handler + +- [#2097](https://github.com/sanic-org/sanic/pull/2097) Allow + case-insensitive HTTP Upgrade header + +- [#2104](https://github.com/sanic-org/sanic/pull/2104) Explicit + usage of CIMultiDict getters + +- [#2109](https://github.com/sanic-org/sanic/pull/2109) Consistent + use of error loggers + +- [#2114](https://github.com/sanic-org/sanic/pull/2114) New + `client_ip` access of connection info instance + +- [#2119](https://github.com/sanic-org/sanic/pull/2119) Alternatate + classes on instantiation for `Config` and `Sanic.ctx` + +- [#2133](https://github.com/sanic-org/sanic/pull/2133) Implement + new version of AST router + + - Proper differentiation between `alpha` and `string` param + types + - Adds a `slug` param type, example: `` + - Deprecates `` in favor of `` + - Deprecates `` in favor of `` + - Adds a `route.uri` accessor + +- [#2136](https://github.com/sanic-org/sanic/pull/2136) CLI + improvements with new optional params + +- [#2137](https://github.com/sanic-org/sanic/pull/2137) Add + `version_prefix` to URL builders + +- [#2140](https://github.com/sanic-org/sanic/pull/2140) Event + autoregistration with `EVENT_AUTOREGISTER` + +- [#2146](https://github.com/sanic-org/sanic/pull/2146), + [#2147](https://github.com/sanic-org/sanic/pull/2147) Require + stricter names on `Sanic()` and `Blueprint()` + +- [#2150](https://github.com/sanic-org/sanic/pull/2150) Infinitely + reusable and nestable `Blueprint` and `BlueprintGroup` + +- [#2154](https://github.com/sanic-org/sanic/pull/2154) Upgrade + `websockets` dependency to min version + +- [#2155](https://github.com/sanic-org/sanic/pull/2155) Allow for + maximum header sizes to be increased: `REQUEST_MAX_HEADER_SIZE` + +- [#2157](https://github.com/sanic-org/sanic/pull/2157) Allow app + factory pattern in CLI + +- [#2165](https://github.com/sanic-org/sanic/pull/2165) Change HTTP + methods to enums + +- [#2167](https://github.com/sanic-org/sanic/pull/2167) Allow + auto-reloading on additional directories + +- [#2168](https://github.com/sanic-org/sanic/pull/2168) Add simple + HTTP server to CLI + +- [#2170](https://github.com/sanic-org/sanic/pull/2170) Additional + methods for attaching `HTTPMethodView` + +**Bugfixes** + +- [#2091](https://github.com/sanic-org/sanic/pull/2091) Fix + `UserWarning` in ASGI mode for missing `__slots__` +- [#2099](https://github.com/sanic-org/sanic/pull/2099) Fix static + request handler logging exception on 404 +- [#2110](https://github.com/sanic-org/sanic/pull/2110) Fix + request.args.pop removes parameters inconsistently +- [#2107](https://github.com/sanic-org/sanic/pull/2107) Fix type + hinting for load_env +- [#2127](https://github.com/sanic-org/sanic/pull/2127) Make sure + ASGI ws subprotocols is a list +- [#2128](https://github.com/sanic-org/sanic/pull/2128) Fix issue + where Blueprint exception handlers do not consistently route to + proper handler + +**Deprecations and Removals** + +- [#2156](https://github.com/sanic-org/sanic/pull/2156) Remove + config value `REQUEST_BUFFER_QUEUE_SIZE` +- [#2170](https://github.com/sanic-org/sanic/pull/2170) + `CompositionView` deprecated and marked for removal in 21.12 +- [#2172](https://github.com/sanic-org/sanic/pull/2170) Deprecate + StreamingHTTPResponse + +**Developer infrastructure** + +- [#2149](https://github.com/sanic-org/sanic/pull/2149) Remove + Travis CI in favor of GitHub Actions + +**Improved Documentation** + +- [#2164](https://github.com/sanic-org/sanic/pull/2164) Fix typo in + documentation +- [#2100](https://github.com/sanic-org/sanic/pull/2100) Remove + documentation for non-existent arguments + +## Version 21.3.2 + +**Bugfixes** + +- [#2081](https://github.com/sanic-org/sanic/pull/2081) Disable + response timeout on websocket connections +- [#2085](https://github.com/sanic-org/sanic/pull/2085) Make sure + that blueprints with no slash is maintained when applied + +## Version 21.3.1 + +**Bugfixes** + +- [#2076](https://github.com/sanic-org/sanic/pull/2076) Static files + inside subfolders are not accessible (404) + +## Version 21.3.0 + +Release +Notes + +**Features** + +- [#1876](https://github.com/sanic-org/sanic/pull/1876) Unified + streaming server +- [#2005](https://github.com/sanic-org/sanic/pull/2005) New + `Request.id` property +- [#2008](https://github.com/sanic-org/sanic/pull/2008) Allow + Pathlib Path objects to be passed to `app.static()` helper +- [#2010](https://github.com/sanic-org/sanic/pull/2010), + [#2031](https://github.com/sanic-org/sanic/pull/2031) New + startup-optimized router +- [#2018](https://github.com/sanic-org/sanic/pull/2018) + [#2064](https://github.com/sanic-org/sanic/pull/2064) Listeners + for main server process +- [#2032](https://github.com/sanic-org/sanic/pull/2032) Add raw + header info to request object +- [#2042](https://github.com/sanic-org/sanic/pull/2042) + [#2060](https://github.com/sanic-org/sanic/pull/2060) + [#2061](https://github.com/sanic-org/sanic/pull/2061) Introduce + Signals API +- [#2043](https://github.com/sanic-org/sanic/pull/2043) Add + `__str__` and `__repr__` to Sanic and Blueprint +- [#2047](https://github.com/sanic-org/sanic/pull/2047) Enable + versioning and strict slash on BlueprintGroup +- [#2053](https://github.com/sanic-org/sanic/pull/2053) Make + `get_app` name argument optional +- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON encoder + change via app +- [#2063](https://github.com/sanic-org/sanic/pull/2063) App and + connection level context objects + +**Bugfixes** + +- Resolve [#1420](https://github.com/sanic-org/sanic/pull/1420) + `url_for` where `strict_slashes` are on for a path ending in `/` +- Resolve [#1525](https://github.com/sanic-org/sanic/pull/1525) + Routing is incorrect with some special characters +- Resolve [#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI + headers in body +- Resolve [#1722](https://github.com/sanic-org/sanic/pull/1722) + Using curl in chunk mode +- Resolve [#1730](https://github.com/sanic-org/sanic/pull/1730) + Extra content in ASGI streaming response +- Resolve [#1749](https://github.com/sanic-org/sanic/pull/1749) + Restore broken middleware edge cases +- Resolve [#1785](https://github.com/sanic-org/sanic/pull/1785) + [#1804](https://github.com/sanic-org/sanic/pull/1804) Synchronous + error handlers +- Resolve [#1790](https://github.com/sanic-org/sanic/pull/1790) + Protocol errors did not support async error handlers #1790 +- Resolve [#1824](https://github.com/sanic-org/sanic/pull/1824) + Timeout on specific methods +- Resolve [#1875](https://github.com/sanic-org/sanic/pull/1875) + Response timeout error from all routes after returning several + timeouts from a specific route +- Resolve [#1988](https://github.com/sanic-org/sanic/pull/1988) + Handling of safe methods with body +- [#2001](https://github.com/sanic-org/sanic/pull/2001) Raise + ValueError when cookie max-age is not an integer + +**Deprecations and Removals** + +- [#2007](https://github.com/sanic-org/sanic/pull/2007) \* Config + using `from_envvar` \* Config using `from_pyfile` \* Config using + `from_object` +- [#2009](https://github.com/sanic-org/sanic/pull/2009) Remove Sanic + test client to its own package +- [#2036](https://github.com/sanic-org/sanic/pull/2036), + [#2037](https://github.com/sanic-org/sanic/pull/2037) Drop Python + 3.6 support +- `Request.endpoint` deprecated in favor of `Request.name` +- handler type name prefixes removed (static, websocket, etc) + +**Developer infrastructure** + +- [#1995](https://github.com/sanic-org/sanic/pull/1995) Create + FUNDING.yml +- [#2013](https://github.com/sanic-org/sanic/pull/2013) Add codeql + to CI pipeline +- [#2038](https://github.com/sanic-org/sanic/pull/2038) Codecov + configuration updates +- [#2049](https://github.com/sanic-org/sanic/pull/2049) Updated + setup.py to use `find_packages` + +**Improved Documentation** + +- [#1218](https://github.com/sanic-org/sanic/pull/1218) + Documentation for sanic.log.\* is missing +- [#1608](https://github.com/sanic-org/sanic/pull/1608) Add + documentation on calver and LTS +- [#1731](https://github.com/sanic-org/sanic/pull/1731) Support + mounting application elsewhere than at root path +- [#2006](https://github.com/sanic-org/sanic/pull/2006) Upgraded + type annotations and improved docstrings and API documentation +- [#2052](https://github.com/sanic-org/sanic/pull/2052) Fix some + examples and docs + +**Miscellaneous** + +- `Request.route` property +- Better websocket subprotocols support +- Resolve bug with middleware in Blueprint Group when passed + callable +- Moves common logic between Blueprint and Sanic into mixins +- Route naming changed to be more consistent + - request endpoint is the route name + - route names are fully namespaced +- Some new convenience decorators: + - `@app.main_process_start` + - `@app.main_process_stop` + - `@app.before_server_start` + - `@app.after_server_start` + - `@app.before_server_stop` + - `@app.after_server_stop` + - `@app.on_request` + - `@app.on_response` +- Fixes `Allow` header that did not include `HEAD` +- Using "name" keyword in `url_for` for a "static" route where + name does not exist +- Cannot have multiple `app.static()` without using the named param +- Using "filename" keyword in `url_for` on a file route +- `unquote` in route def (not automatic) +- `routes_all` is tuples +- Handler arguments are kwarg only +- `request.match_info` is now a cached (and not computed) property +- Unknown static file mimetype is sent as `application/octet-stream` +- `_host` keyword in `url_for` +- Add charset default to `utf-8` for text and js content types if + not specified +- Version for a route can be str, float, or int +- Route has ctx property +- App has `routes_static`, `routes_dynamic`, `routes_regex` +- [#2044](https://github.com/sanic-org/sanic/pull/2044) Code cleanup + and refactoring +- [#2072](https://github.com/sanic-org/sanic/pull/2072) Remove + `BaseSanic` metaclass +- [#2074](https://github.com/sanic-org/sanic/pull/2074) Performance + adjustments in `handle_request_` + +## Version 20.12.3 + +**Bugfixes** + +- [#2021](https://github.com/sanic-org/sanic/pull/2021) Remove + prefix from websocket handler name + +## Version 20.12.2 + +**Dependencies** + +- [#2026](https://github.com/sanic-org/sanic/pull/2026) Fix uvloop + to 0.14 because 0.15 drops Python 3.6 support +- [#2029](https://github.com/sanic-org/sanic/pull/2029) Remove old + chardet requirement, add in hard multidict requirement + +## Version 19.12.5 + +**Dependencies** + +- [#2025](https://github.com/sanic-org/sanic/pull/2025) Fix uvloop + to 0.14 because 0.15 drops Python 3.6 support +- [#2027](https://github.com/sanic-org/sanic/pull/2027) Remove old + chardet requirement, add in hard multidict requirement + +## Version 20.12.0 + +**Features** + +- [#1993](https://github.com/sanic-org/sanic/pull/1993) Add disable + app registry +- [#1945](https://github.com/sanic-org/sanic/pull/1945) Static route + more verbose if file not found +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + routes registration on a blueprint +- [#1961](https://github.com/sanic-org/sanic/pull/1961) Add Python + 3.9 support +- [#1962](https://github.com/sanic-org/sanic/pull/1962) Sanic CLI + upgrade +- [#1967](https://github.com/sanic-org/sanic/pull/1967) Update + aiofile version requirements +- [#1969](https://github.com/sanic-org/sanic/pull/1969) Update + multidict version requirements +- [#1970](https://github.com/sanic-org/sanic/pull/1970) Add py.typed + file +- [#1972](https://github.com/sanic-org/sanic/pull/1972) Speed + optimization in request handler +- [#1979](https://github.com/sanic-org/sanic/pull/1979) Add app + registry and Sanic class level app retrieval + +**Bugfixes** + +- [#1965](https://github.com/sanic-org/sanic/pull/1965) Fix Chunked + Transport-Encoding in ASGI streaming response + +**Deprecations and Removals** + +- [#1981](https://github.com/sanic-org/sanic/pull/1981) Cleanup and + remove deprecated code + +**Developer infrastructure** + +- [#1956](https://github.com/sanic-org/sanic/pull/1956) Fix load + module test +- [#1973](https://github.com/sanic-org/sanic/pull/1973) Transition + Travis from .org to .com +- [#1986](https://github.com/sanic-org/sanic/pull/1986) Update tox + requirements + +**Improved Documentation** + +- [#1951](https://github.com/sanic-org/sanic/pull/1951) + Documentation improvements +- [#1983](https://github.com/sanic-org/sanic/pull/1983) Remove + duplicate contents in testing.rst +- [#1984](https://github.com/sanic-org/sanic/pull/1984) Fix typo in + routing.rst + +## Version 20.9.1 + +**Bugfixes** + +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + route registration on blueprints +- [#1957](https://github.com/sanic-org/sanic/pull/1957) Removes + duplicate headers in ASGI streaming body + +## Version 19.12.3 + +**Bugfixes** + +- [#1959](https://github.com/sanic-org/sanic/pull/1959) Removes + duplicate headers in ASGI streaming body + +## Version 20.9.0 + +**Features** + +- [#1887](https://github.com/sanic-org/sanic/pull/1887) Pass + subprotocols in websockets (both sanic server and ASGI) +- [#1894](https://github.com/sanic-org/sanic/pull/1894) + Automatically set `test_mode` flag on app instance +- [#1903](https://github.com/sanic-org/sanic/pull/1903) Add new + unified method for updating app values +- [#1906](https://github.com/sanic-org/sanic/pull/1906), + [#1909](https://github.com/sanic-org/sanic/pull/1909) Adds + WEBSOCKET_PING_TIMEOUT and WEBSOCKET_PING_INTERVAL configuration + values +- [#1935](https://github.com/sanic-org/sanic/pull/1935) httpx + version dependency updated, it is slated for removal as a + dependency in v20.12 +- [#1937](https://github.com/sanic-org/sanic/pull/1937) Added auto, + text, and json fallback error handlers (in v21.3, the default will + change form html to auto) + +**Bugfixes** + +- [#1897](https://github.com/sanic-org/sanic/pull/1897) Resolves + exception from unread bytes in stream + +**Deprecations and Removals** + +- [#1903](https://github.com/sanic-org/sanic/pull/1903) + config.from_envar, config.from_pyfile, and config.from_object are + deprecated and set to be removed in v21.3 + +**Developer infrastructure** + +- [#1890](https://github.com/sanic-org/sanic/pull/1890), + [#1891](https://github.com/sanic-org/sanic/pull/1891) Update isort + calls to be compatible with new API +- [#1893](https://github.com/sanic-org/sanic/pull/1893) Remove + version section from setup.cfg +- [#1924](https://github.com/sanic-org/sanic/pull/1924) Adding + \--strict-markers for pytest + +**Improved Documentation** + +- [#1922](https://github.com/sanic-org/sanic/pull/1922) Add explicit + ASGI compliance to the README + +## Version 20.6.3 + +**Bugfixes** + +- [#1884](https://github.com/sanic-org/sanic/pull/1884) Revert + change to multiprocessing mode + +## Version 20.6.2 + +**Features** + +- [#1641](https://github.com/sanic-org/sanic/pull/1641) Socket + binding implemented properly for IPv6 and UNIX sockets + +## Version 20.6.1 + +**Features** + +- [#1760](https://github.com/sanic-org/sanic/pull/1760) Add version + parameter to websocket routes +- [#1866](https://github.com/sanic-org/sanic/pull/1866) Add `sanic` + as an entry point command +- [#1880](https://github.com/sanic-org/sanic/pull/1880) Add handler + names for websockets for url_for usage + +**Bugfixes** + +- [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for + host parameter issue with lists +- [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static + _handler pickling error +- [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader + on OSX py38 and Windows +- [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse + named_response_middlware execution order, to match normal response + middleware execution order +- [#1853](https://github.com/sanic-org/sanic/pull/1853) Fix pickle + error when attempting to pickle an application which contains + websocket routes + +**Deprecations and Removals** + +- [#1739](https://github.com/sanic-org/sanic/pull/1739) Deprecate + body_bytes to merge into body + +**Developer infrastructure** + +- [#1852](https://github.com/sanic-org/sanic/pull/1852) Fix naming + of CI test env on Python nightlies +- [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust + websockets version to setup.py +- [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap + run()'s "protocol" type annotation in Optional[] + +**Improved Documentation** + +- [#1846](https://github.com/sanic-org/sanic/pull/1846) Update docs + to clarify response middleware execution order +- [#1865](https://github.com/sanic-org/sanic/pull/1865) Fixing rst + format issue that was hiding documentation + +## Version 20.6.0 + +_Released, but unintentionally omitting PR #1880, so was replaced by +20.6.1_ + +## Version 20.3.0 + +**Features** + +- [#1762](https://github.com/sanic-org/sanic/pull/1762) Add + `srv.start_serving()` and `srv.serve_forever()` to `AsyncioServer` +- [#1767](https://github.com/sanic-org/sanic/pull/1767) Make Sanic + usable on `hypercorn -k trio myweb.app` +- [#1768](https://github.com/sanic-org/sanic/pull/1768) No + tracebacks on normal errors and prettier error pages +- [#1769](https://github.com/sanic-org/sanic/pull/1769) Code cleanup + in file responses +- [#1793](https://github.com/sanic-org/sanic/pull/1793) and + [#1819](https://github.com/sanic-org/sanic/pull/1819) Upgrade + `str.format()` to f-strings +- [#1798](https://github.com/sanic-org/sanic/pull/1798) Allow + multiple workers on MacOS with Python 3.8 +- [#1820](https://github.com/sanic-org/sanic/pull/1820) Do not set + content-type and content-length headers in exceptions + +**Bugfixes** + +- [#1748](https://github.com/sanic-org/sanic/pull/1748) Remove loop + argument in `asyncio.Event` in Python 3.8 +- [#1764](https://github.com/sanic-org/sanic/pull/1764) Allow route + decorators to stack up again +- [#1789](https://github.com/sanic-org/sanic/pull/1789) Fix tests + using hosts yielding incorrect `url_for` +- [#1808](https://github.com/sanic-org/sanic/pull/1808) Fix Ctrl+C + and tests on Windows + +**Deprecations and Removals** + +- [#1800](https://github.com/sanic-org/sanic/pull/1800) Begin + deprecation in way of first-class streaming, removal of + `body_init`, `body_push`, and `body_finish` +- [#1801](https://github.com/sanic-org/sanic/pull/1801) Complete + deprecation from + [#1666](https://github.com/sanic-org/sanic/pull/1666) of + dictionary context on `request` objects. +- [#1807](https://github.com/sanic-org/sanic/pull/1807) Remove + server config args that can be read directly from app +- [#1818](https://github.com/sanic-org/sanic/pull/1818) Complete + deprecation of `app.remove_route` and `request.raw_args` + +**Dependencies** + +- [#1794](https://github.com/sanic-org/sanic/pull/1794) Bump `httpx` + to 0.11.1 +- [#1806](https://github.com/sanic-org/sanic/pull/1806) Import + `ASGIDispatch` from top-level `httpx` (from third-party + deprecation) + +**Developer infrastructure** + +- [#1833](https://github.com/sanic-org/sanic/pull/1833) Resolve + broken documentation builds + +**Improved Documentation** + +- [#1755](https://github.com/sanic-org/sanic/pull/1755) Usage of + `response.empty()` +- [#1778](https://github.com/sanic-org/sanic/pull/1778) Update + README +- [#1783](https://github.com/sanic-org/sanic/pull/1783) Fix typo +- [#1784](https://github.com/sanic-org/sanic/pull/1784) Corrected + changelog for docs move of MD to RST + ([#1691](https://github.com/sanic-org/sanic/pull/1691)) +- [#1803](https://github.com/sanic-org/sanic/pull/1803) Update + config docs to match DEFAULT_CONFIG +- [#1814](https://github.com/sanic-org/sanic/pull/1814) Update + getting_started.rst +- [#1821](https://github.com/sanic-org/sanic/pull/1821) Update to + deployment +- [#1822](https://github.com/sanic-org/sanic/pull/1822) Update docs + with changes done in 20.3 +- [#1834](https://github.com/sanic-org/sanic/pull/1834) Order of + listeners + +## Version 19.12.0 + +**Bugfixes** + +- Fix blueprint middleware application + + Currently, any blueprint middleware registered, irrespective of + which blueprint was used to do so, was being applied to all of the + routes created by the `@app` and `@blueprint` alike. + + As part of this change, the blueprint based middleware application + is enforced based on where they are registered. + + - If you register a middleware via `@blueprint.middleware` then it + will apply only to the routes defined by the blueprint. + - If you register a middleware via `@blueprint_group.middleware` + then it will apply to all blueprint based routes that are part + of the group. + - If you define a middleware via `@app.middleware` then it will be + applied on all available routes + ([#37](https://github.com/sanic-org/sanic/issues/37)) + +- Fix [url_for]{.title-ref} behavior with missing SERVER_NAME + + If the [SERVER_NAME]{.title-ref} was missing in the + [app.config]{.title-ref} entity, the [url_for]{.title-ref} on the + [request]{.title-ref} and [app]{.title-ref} were failing due to an + [AttributeError]{.title-ref}. This fix makes the availability of + [SERVER_NAME]{.title-ref} on our [app.config]{.title-ref} an + optional behavior. + ([#1707](https://github.com/sanic-org/sanic/issues/1707)) + +**Improved Documentation** + +- Move docs from MD to RST + + Moved all docs from markdown to restructured text like the rest of + the docs to unify the scheme and make it easier in the future to + update documentation. + ([#1691](https://github.com/sanic-org/sanic/issues/1691)) + +- Fix documentation for [get]{.title-ref} and [getlist]{.title-ref} of + the [request.args]{.title-ref} + + Add additional example for showing the usage of + [getlist]{.title-ref} and fix the documentation string for + [request.args]{.title-ref} behavior + ([#1704](https://github.com/sanic-org/sanic/issues/1704)) + +## Version 19.6.3 + +**Features** + +- Enable Towncrier Support + + As part of this feature, [towncrier]{.title-ref} is being introduced + as a mechanism to partially automate the process of generating and + managing change logs as part of each of pull requests. + ([#1631](https://github.com/sanic-org/sanic/issues/1631)) + +**Improved Documentation** + +- Documentation infrastructure changes + - Enable having a single common [CHANGELOG]{.title-ref} file for + both GitHub page and documentation + - Fix Sphinix deprecation warnings + - Fix documentation warnings due to invalid [rst]{.title-ref} + indentation + - Enable common contribution guidelines file across GitHub and + documentation via [CONTRIBUTING.rst]{.title-ref} + ([#1631](https://github.com/sanic-org/sanic/issues/1631)) + +## Version 19.6.2 + +**Features** + +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Remove + `aiohttp` dependency and create new `SanicTestClient` based upon + [requests-async](https://github.com/encode/requests-async) +- [#1475](https://github.com/sanic-org/sanic/pull/1475) Added ASGI + support (Beta) +- [#1436](https://github.com/sanic-org/sanic/pull/1436) Add + Configure support from object string + +**Bugfixes** + +- [#1587](https://github.com/sanic-org/sanic/pull/1587) Add missing + handle for Expect header. +- [#1560](https://github.com/sanic-org/sanic/pull/1560) Allow to + disable Transfer-Encoding: chunked. +- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix graceful + shutdown. +- [#1594](https://github.com/sanic-org/sanic/pull/1594) Strict + Slashes behavior fix + +**Deprecations and Removals** + +- [#1544](https://github.com/sanic-org/sanic/pull/1544) Drop + dependency on distutil +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Drop support + for Python 3.5 +- [#1568](https://github.com/sanic-org/sanic/pull/1568) Deprecate + route removal. + +.. warning:: Warning + +``` +Sanic will not support Python 3.5 from version 19.6 and forward. +However, version 18.12LTS will have its support period extended thru +December 2020, and therefore passing Python\'s official support version +3.5, which is set to expire in September 2020. +``` + +## Version 19.3 + +**Features** + +- [#1497](https://github.com/sanic-org/sanic/pull/1497) Add support + for zero-length and RFC 5987 encoded filename for + multipart/form-data requests. + +- [#1484](https://github.com/sanic-org/sanic/pull/1484) The type of + `expires` attribute of `sanic.cookies.Cookie` is now enforced to + be of type `datetime`. + +- [#1482](https://github.com/sanic-org/sanic/pull/1482) Add support + for the `stream` parameter of `sanic.Sanic.add_route()` available + to `sanic.Blueprint.add_route()`. + +- [#1481](https://github.com/sanic-org/sanic/pull/1481) Accept + negative values for route parameters with type `int` or `number`. + +- [#1476](https://github.com/sanic-org/sanic/pull/1476) Deprecated + the use of `sanic.request.Request.raw_args` - it has a fundamental + flaw in which is drops repeated query string parameters. Added + `sanic.request.Request.query_args` as a replacement for the + original use-case. + +- [#1472](https://github.com/sanic-org/sanic/pull/1472) Remove an + unwanted `None` check in Request class `repr` implementation. This + changes the default `repr` of a Request from `` to + `` + +- [#1470](https://github.com/sanic-org/sanic/pull/1470) Added 2 new + parameters to `sanic.app.Sanic.create_server`: + + - `return_asyncio_server` - whether to return an + asyncio.Server. + - `asyncio_server_kwargs` - kwargs to pass to + `loop.create_server` for the event loop that sanic is using. + + > + + This is a breaking change. + +- [#1499](https://github.com/sanic-org/sanic/pull/1499) Added a set + of test cases that test and benchmark route resolution. + +- [#1457](https://github.com/sanic-org/sanic/pull/1457) The type of + the `"max-age"` value in a `sanic.cookies.Cookie` is now enforced + to be an integer. Non-integer values are replaced with `0`. + +- [#1445](https://github.com/sanic-org/sanic/pull/1445) Added the + `endpoint` attribute to an incoming `request`, containing the name + of the handler function. + +- [#1423](https://github.com/sanic-org/sanic/pull/1423) Improved + request streaming. `request.stream` is now a bounded-size buffer + instead of an unbounded queue. Callers must now call + `await request.stream.read()` instead of + `await request.stream.get()` to read each portion of the body. + + This is a breaking change. + +**Bugfixes** + +- [#1502](https://github.com/sanic-org/sanic/pull/1502) Sanic was + prefetching `time.time()` and updating it once per second to avoid + excessive `time.time()` calls. The implementation was observed to + cause memory leaks in some cases. The benefit of the prefetch + appeared to negligible, so this has been removed. Fixes + [#1500](https://github.com/sanic-org/sanic/pull/1500) +- [#1501](https://github.com/sanic-org/sanic/pull/1501) Fix a bug in + the auto-reloader when the process was launched as a module i.e. + `python -m init0.mod1` where the sanic server is started in + `init0/mod1.py` with `debug` enabled and imports another module in + `init0`. +- [#1376](https://github.com/sanic-org/sanic/pull/1376) Allow sanic + test client to bind to a random port by specifying `port=None` + when constructing a `SanicTestClient` +- [#1399](https://github.com/sanic-org/sanic/pull/1399) Added the + ability to specify middleware on a blueprint group, so that all + routes produced from the blueprints in the group have the + middleware applied. +- [#1442](https://github.com/sanic-org/sanic/pull/1442) Allow the + the use the `SANIC_ACCESS_LOG` environment variable to + enable/disable the access log when not explicitly passed to + `app.run()`. This allows the access log to be disabled for example + when running via gunicorn. + +**Developer infrastructure** + +- [#1529](https://github.com/sanic-org/sanic/pull/1529) Update + project PyPI credentials +- [#1515](https://github.com/sanic-org/sanic/pull/1515) fix linter + issue causing travis build failures (fix #1514) +- [#1490](https://github.com/sanic-org/sanic/pull/1490) Fix python + version in doc build +- [#1478](https://github.com/sanic-org/sanic/pull/1478) Upgrade + setuptools version and use native docutils in doc build +- [#1464](https://github.com/sanic-org/sanic/pull/1464) Upgrade + pytest, and fix caplog unit tests + +**Improved Documentation** + +- [#1516](https://github.com/sanic-org/sanic/pull/1516) Fix typo at + the exception documentation +- [#1510](https://github.com/sanic-org/sanic/pull/1510) fix typo in + Asyncio example +- [#1486](https://github.com/sanic-org/sanic/pull/1486) + Documentation typo +- [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar + in README.md +- [#1489](https://github.com/sanic-org/sanic/pull/1489) Added + "databases" to the extensions list +- [#1483](https://github.com/sanic-org/sanic/pull/1483) Add + sanic-zipkin to extensions list +- [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link + to deleted repo, Sanic-OAuth, from the extensions list +- [#1460](https://github.com/sanic-org/sanic/pull/1460) 18.12 + changelog +- [#1449](https://github.com/sanic-org/sanic/pull/1449) Add example + of amending request object +- [#1446](https://github.com/sanic-org/sanic/pull/1446) Update + README +- [#1444](https://github.com/sanic-org/sanic/pull/1444) Update + README +- [#1443](https://github.com/sanic-org/sanic/pull/1443) Update + README, including new logo +- [#1440](https://github.com/sanic-org/sanic/pull/1440) fix minor + type and pip install instruction mismatch +- [#1424](https://github.com/sanic-org/sanic/pull/1424) + Documentation Enhancements + +Note: 19.3.0 was skipped for packagement purposes and not released on +PyPI + +## Version 18.12 + +### 18.12.0 + +- Changes: + + - Improved codebase test coverage from 81% to 91%. + - Added stream_large_files and host examples in static_file + document + - Added methods to append and finish body content on Request + (#1379) + - Integrated with .appveyor.yml for windows ci support + - Added documentation for AF_INET6 and AF_UNIX socket usage + - Adopt black/isort for codestyle + - Cancel task when connection_lost + - Simplify request ip and port retrieval logic + - Handle config error in load config file. + - Integrate with codecov for CI + - Add missed documentation for config section. + - Deprecate Handler.log + - Pinned httptools requirement to version 0.0.10+ + +- Fixes: + + - Fix `remove_entity_headers` helper function (#1415) + - Fix TypeError when use Blueprint.group() to group blueprint + with default url_prefix, Use os.path.normpath to avoid invalid + url_prefix like api//v1 f8a6af1 Rename the `http` module to + `helpers` to prevent conflicts with the built-in Python http + library (fixes #1323) + - Fix unittests on windows + - Fix Namespacing of sanic logger + - Fix missing quotes in decorator example + - Fix redirect with quoted param + - Fix doc for latest blueprint code + - Fix build of latex documentation relating to markdown lists + - Fix loop exception handling in app.py + - Fix content length mismatch in windows and other platform + - Fix Range header handling for static files (#1402) + - Fix the logger and make it work (#1397) + - Fix type pikcle->pickle in multiprocessing test + - Fix pickling blueprints Change the string passed in the + "name" section of the namedtuples in Blueprint to match the + name of the Blueprint module attribute name. This allows + blueprints to be pickled and unpickled, without errors, which + is a requirement of running Sanic in multiprocessing mode in + Windows. Added a test for pickling and unpickling blueprints + Added a test for pickling and unpickling sanic itself Added a + test for enabling multiprocessing on an app with a blueprint + (only useful to catch this bug if the tests are run on + Windows). + - Fix document for logging + +## Version 0.8 + +**0.8.3** + +- Changes: + - Ownership changed to org 'sanic-org' + +**0.8.0** + +- Changes: + - Add Server-Sent Events extension (Innokenty Lebedev) + - Graceful handling of request_handler_task cancellation (Ashley + Sommer) + - Sanitize URL before redirection (aveao) + - Add url_bytes to request (johndoe46) + - py37 support for travisci (yunstanford) + - Auto reloader support for OSX (garyo) + - Add UUID route support (Volodymyr Maksymiv) + - Add pausable response streams (Ashley Sommer) + - Add weakref to request slots (vopankov) + - remove ubuntu 12.04 from test fixture due to deprecation + (yunstanford) + - Allow streaming handlers in add_route (kinware) + - use travis_retry for tox (Raphael Deem) + - update aiohttp version for test client (yunstanford) + - add redirect import for clarity (yingshaoxo) + - Update HTTP Entity headers (Arnulfo Solís) + - Add register_listener method (Stephan Fitzpatrick) + - Remove uvloop/ujson dependencies for Windows (abuckenheimer) + - Content-length header on 204/304 responses (Arnulfo Solís) + - Extend WebSocketProtocol arguments and add docs (Bob Olde + Hampsink, yunstanford) + - Update development status from pre-alpha to beta (Maksim + Anisenkov) + - KeepAlive Timeout log level changed to debug (Arnulfo Solís) + - Pin pytest to 3.3.2 because of pytest-dev/pytest#3170 (Maksim + Aniskenov) + - Install Python 3.5 and 3.6 on docker container for tests (Shahin + Azad) + - Add support for blueprint groups and nesting (Elias Tarhini) + - Remove uvloop for windows setup (Aleksandr Kurlov) + - Auto Reload (Yaser Amari) + - Documentation updates/fixups (multiple contributors) +- Fixes: + - Fix: auto_reload in Linux (Ashley Sommer) + - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) + - Fix: disable auto_reload by default on windows (abuckenheimer) + - Fix (1143): Turn off access log with gunicorn (hqy) + - Fix (1268): Support status code for file response (Cosmo Borsky) + - Fix (1266): Add content_type flag to Sanic.static (Cosmo Borsky) + - Fix: subprotocols parameter missing from add_websocket_route + (ciscorn) + - Fix (1242): Responses for CI header (yunstanford) + - Fix (1237): add version constraint for websockets (yunstanford) + - Fix (1231): memory leak - always release resource (Phillip Xu) + - Fix (1221): make request truthy if transport exists (Raphael + Deem) + - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) + - Fix try_everything examples (PyManiacGR, kot83) + - Fix (1158): default to auto_reload in debug mode (Raphael Deem) + - Fix (1136): ErrorHandler.response handler call too restrictive + (Julien Castiaux) + - Fix: raw requires bytes-like object (cloudship) + - Fix (1120): passing a list in to a route decorator's host arg + (Timothy Ebiuwhe) + - Fix: Bug in multipart/form-data parser (DirkGuijt) + - Fix: Exception for missing parameter when value is null + (NyanKiyoshi) + - Fix: Parameter check (Howie Hu) + - Fix (1089): Routing issue with named parameters and different + methods (yunstanford) + - Fix (1085): Signal handling in multi-worker mode (yunstanford) + - Fix: single quote in readme.rst (Cosven) + - Fix: method typos (Dmitry Dygalo) + - Fix: log_response correct output for ip and port (Wibowo + Arindrarto) + - Fix (1042): Exception Handling (Raphael Deem) + - Fix: Chinese URIs (Howie Hu) + - Fix (1079): timeout bug when self.transport is None (Raphael + Deem) + - Fix (1074): fix strict_slashes when route has slash (Raphael + Deem) + - Fix (1050): add samesite cookie to cookie keys (Raphael Deem) + - Fix (1065): allow add_task after server starts (Raphael Deem) + - Fix (1061): double quotes in unauthorized exception (Raphael + Deem) + - Fix (1062): inject the app in add_task method (Raphael Deem) + - Fix: update environment.yml for readthedocs (Eli Uriegas) + - Fix: Cancel request task when response timeout is triggered + (Jeong YunWon) + - Fix (1052): Method not allowed response for RFC7231 compliance + (Raphael Deem) + - Fix: IPv6 Address and Socket Data Format (Dan Palmer) + +Note: Changelog was unmaintained between 0.1 and 0.7 + +## Version 0.1 + +**0.1.7** + +- Reversed static url and directory arguments to meet spec + +**0.1.6** + +- Static files +- Lazy Cookie Loading + +**0.1.5** + +- Cookies +- Blueprint listeners and ordering +- Faster Router +- Fix: Incomplete file reads on medium+ sized post requests +- Breaking: after_start and before_stop now pass sanic as their + first argument + +**0.1.4** + +- Multiprocessing + +**0.1.3** + +- Blueprint support +- Faster Response processing + +**0.1.1 - 0.1.2** + +- Struggling to update pypi via CI + +**0.1.0** + +- Released to public From d240ca87370c61b62d2d3d98087ed247438a4461 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:24:02 +0200 Subject: [PATCH 275/698] New translations changelog.md (Korean) --- guide/content/ko/release-notes/changelog.md | 1531 +++++++++++++++++++ 1 file changed, 1531 insertions(+) create mode 100644 guide/content/ko/release-notes/changelog.md diff --git a/guide/content/ko/release-notes/changelog.md b/guide/content/ko/release-notes/changelog.md new file mode 100644 index 0000000000..b98df20c9e --- /dev/null +++ b/guide/content/ko/release-notes/changelog.md @@ -0,0 +1,1531 @@ +--- +content_class: changelog +--- + +# Changelog + +🔶 Current release\ +🔷 In support LTS release + +## Version 23.12.0 🔶🔷 + +_Current version_ + +### Features + +- [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes +- [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown +- [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket +- [#2822](https://github.com/sanic-org/sanic/pull/2822) Listener and signal prioritization +- [#2831](https://github.com/sanic-org/sanic/pull/2831) Reduce memory consumption +- [#2837](https://github.com/sanic-org/sanic/pull/2837) Accept bare cookies +- [#2841](https://github.com/sanic-org/sanic/pull/2841) Add `websocket.handler.` signals +- [#2805](https://github.com/sanic-org/sanic/pull/2805) Add changed files to reload trigger listeners +- [#2813](https://github.com/sanic-org/sanic/pull/2813) Allow for simple signals +- [#2827](https://github.com/sanic-org/sanic/pull/2827) Improve functionality and consistency of `Sanic.event()` +- [#2851](https://github.com/sanic-org/sanic/pull/2851) Allow range requests for a single byte +- [#2854](https://github.com/sanic-org/sanic/pull/2854) Better `Request.scheme` for websocket requests +- [#2858](https://github.com/sanic-org/sanic/pull/2858) Convert Sanic `Request` to a Websockets `Request` for handshake +- [#2859](https://github.com/sanic-org/sanic/pull/2859) Add a REPL to the `sanic` CLI +- [#2870](https://github.com/sanic-org/sanic/pull/2870) Add Python 3.12 support +- [#2875](https://github.com/sanic-org/sanic/pull/2875) Better exception on multiprocessing context conflicts + +### Bugfixes + +- [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data + +### Deprecations and Removals + +### Developer infrastructure + +- [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases +- [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU +- [#2807](https://github.com/sanic-org/sanic/pull/2807) Add constraint for autodocsum (lint issue in old package version) +- [#2808](https://github.com/sanic-org/sanic/pull/2808) Refactor GitHub Actions +- [#2814](https://github.com/sanic-org/sanic/pull/2814) Run CI pipeline on git push +- [#2846](https://github.com/sanic-org/sanic/pull/2846) Drop old performance tests/benchmarks +- [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile cleanup +- [#2865](https://github.com/sanic-org/sanic/pull/2865) + [#2869](https://github.com/sanic-org/sanic/pull/2869) + [#2872](https://github.com/sanic-org/sanic/pull/2872) + [#2879](https://github.com/sanic-org/sanic/pull/2879) + Add ruff to toolchain +- [#2866](https://github.com/sanic-org/sanic/pull/2866) Fix the alt svc test to run locally with explicit buffer nbytes +- [#2877](https://github.com/sanic-org/sanic/pull/2877) Use Python's trusted publisher in deployments +- [#2882](https://github.com/sanic-org/sanic/pull/2882) Introduce dynamic port fixture in targeted locations in the test suite + +### Improved Documentation + +- [#2781](https://github.com/sanic-org/sanic/pull/2781) + [#2821](https://github.com/sanic-org/sanic/pull/2821) + [#2861](https://github.com/sanic-org/sanic/pull/2861) + [#2863](https://github.com/sanic-org/sanic/pull/2863) + Conversion of User Guide to the SHH (Sanic, html5tagger, HTMX) stack +- [#2810](https://github.com/sanic-org/sanic/pull/2810) Update README +- [#2855](https://github.com/sanic-org/sanic/pull/2855) Edit Discord badge +- [#2864](https://github.com/sanic-org/sanic/pull/2864) Adjust documentation for using state properties within http/https redirection document + +## Version 23.9.0 + +_Due to circumstances at the time, v.23.9 was skipped._ + +## Version 23.6.0 + +### Features + +- [#2670](https://github.com/sanic-org/sanic/pull/2670) Increase `KEEP_ALIVE_TIMEOUT` default to 120 seconds +- [#2716](https://github.com/sanic-org/sanic/pull/2716) Adding allow route overwrite option in blueprint +- [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792) Add a new exception signal for ALL exceptions raised anywhere in application +- [#2727](https://github.com/sanic-org/sanic/pull/2727) Add name prefixing to BP groups +- [#2754](https://github.com/sanic-org/sanic/pull/2754) Update request type on middleware types +- [#2770](https://github.com/sanic-org/sanic/pull/2770) Better exception message on startup time application induced import error +- [#2776](https://github.com/sanic-org/sanic/pull/2776) Set multiprocessing start method early +- [#2785](https://github.com/sanic-org/sanic/pull/2785) Add custom typing to config and ctx objects +- [#2790](https://github.com/sanic-org/sanic/pull/2790) Add `request.client_ip` + +### Bugfixes + +- [#2728](https://github.com/sanic-org/sanic/pull/2728) Fix traversals for intended results +- [#2729](https://github.com/sanic-org/sanic/pull/2729) Handle case when headers argument of ResponseStream constructor is None +- [#2737](https://github.com/sanic-org/sanic/pull/2737) Fix type annotation for `JSONREsponse` default content type +- [#2740](https://github.com/sanic-org/sanic/pull/2740) Use Sanic's serializer for JSON responses in the Inspector +- [#2760](https://github.com/sanic-org/sanic/pull/2760) Support for `Request.get_current` in ASGI mode +- [#2773](https://github.com/sanic-org/sanic/pull/2773) Alow Blueprint routes to explicitly define error_format +- [#2774](https://github.com/sanic-org/sanic/pull/2774) Resolve headers on different renderers +- [#2782](https://github.com/sanic-org/sanic/pull/2782) Resolve pypy compatibility issues + +### Deprecations and Removals + +- [#2777](https://github.com/sanic-org/sanic/pull/2777) Remove Python 3.7 support + +### Developer infrastructure + +- [#2766](https://github.com/sanic-org/sanic/pull/2766) Unpin setuptools version +- [#2779](https://github.com/sanic-org/sanic/pull/2779) Run keep alive tests in loop to get available port + +### Improved Documentation + +- [#2741](https://github.com/sanic-org/sanic/pull/2741) Better documentation examples about running Sanic + From that list, the items to highlight in the release notes: + +## Version 23.3.0 + +### Features + +- [#2545](https://github.com/sanic-org/sanic/pull/2545) Standardize init of exceptions for more consistent control of HTTP responses using exceptions +- [#2606](https://github.com/sanic-org/sanic/pull/2606) Decode headers as UTF-8 also in ASGI +- [#2646](https://github.com/sanic-org/sanic/pull/2646) Separate ASGI request and lifespan callables +- [#2659](https://github.com/sanic-org/sanic/pull/2659) Use `FALLBACK_ERROR_FORMAT` for handlers that return `empty()` +- [#2662](https://github.com/sanic-org/sanic/pull/2662) Add basic file browser (HTML page) and auto-index serving +- [#2667](https://github.com/sanic-org/sanic/pull/2667) Nicer traceback formatting (HTML page) +- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter error page rendering format selection; more reliant upon header and "common sense" defaults +- [#2680](https://github.com/sanic-org/sanic/pull/2680) Check the status of socket before shutting down with `SHUT_RDWR` +- [#2687](https://github.com/sanic-org/sanic/pull/2687) Refresh `Request.accept` functionality to be more performant and spec-compliant +- [#2696](https://github.com/sanic-org/sanic/pull/2696) Add header accessors as properties + ``` + Example-Field: Foo, Bar + Example-Field: Baz + ``` + ```python + request.headers.example_field == "Foo, Bar,Baz" + ``` +- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simpler CLI targets + + ```sh + $ sanic path.to.module:app # global app instance + $ sanic path.to.module:create_app # factory pattern + $ sanic ./path/to/directory/ # simple serve + ``` +- [#2701](https://github.com/sanic-org/sanic/pull/2701) API to define a number of workers in managed processes +- [#2704](https://github.com/sanic-org/sanic/pull/2704) Add convenience for dynamic changes to routing +- [#2706](https://github.com/sanic-org/sanic/pull/2706) Add convenience methods for cookie creation and deletion + + ```python + response = text("...") + response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com") + ``` +- [#2707](https://github.com/sanic-org/sanic/pull/2707) Simplified `parse_content_header` escaping to be RFC-compliant and remove outdated FF hack +- [#2710](https://github.com/sanic-org/sanic/pull/2710) Stricter charset handling and escaping of request URLs +- [#2711](https://github.com/sanic-org/sanic/pull/2711) Consume body on `DELETE` by default +- [#2719](https://github.com/sanic-org/sanic/pull/2719) Allow `password` to be passed to TLS context +- [#2720](https://github.com/sanic-org/sanic/pull/2720) Skip middleware on `RequestCancelled` +- [#2721](https://github.com/sanic-org/sanic/pull/2721) Change access logging format to `%s` +- [#2722](https://github.com/sanic-org/sanic/pull/2722) Add `CertLoader` as application option for directly controlling `SSLContext` objects +- [#2725](https://github.com/sanic-org/sanic/pull/2725) Worker sync state tolerance on race condition + +### Bugfixes + +- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket to pass thru bytes as is +- [#2697](https://github.com/sanic-org/sanic/pull/2697) Fix comparison between datetime aware and naive in `file` when using `If-Modified-Since` + +### Deprecations and Removals + +- [#2666](https://github.com/sanic-org/sanic/pull/2666) Remove deprecated `__blueprintname__` property + +### Improved Documentation + +- [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect + +## Version 22.12.0 🔷 + +_Current LTS version_ + +### Features + +- [#2569](https://github.com/sanic-org/sanic/pull/2569) Add `JSONResponse` class with some convenient methods when updating a response object +- [#2598](https://github.com/sanic-org/sanic/pull/2598) Change `uvloop` requirement to `>=0.15.0` +- [#2609](https://github.com/sanic-org/sanic/pull/2609) Add compatibility with `websockets` v11.0 +- [#2610](https://github.com/sanic-org/sanic/pull/2610) Kill server early on worker error + - Raise deadlock timeout to 30s +- [#2617](https://github.com/sanic-org/sanic/pull/2617) Scale number of running server workers +- [#2621](https://github.com/sanic-org/sanic/pull/2621) [#2634](https://github.com/sanic-org/sanic/pull/2634) Send `SIGKILL` on subsequent `ctrl+c` to force worker exit +- [#2622](https://github.com/sanic-org/sanic/pull/2622) Add API to restart all workers from the multiplexer +- [#2624](https://github.com/sanic-org/sanic/pull/2624) Default to `spawn` for all subprocesses unless specifically set: + ```python + from sanic import Sanic + + Sanic.start_method = "fork" + ``` +- [#2625](https://github.com/sanic-org/sanic/pull/2625) Filename normalisation of form-data/multipart file uploads +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector: + - Remote access to inspect running Sanic instances + - TLS support for encrypted calls to Inspector + - Authentication to Inspector with API key + - Ability to extend Inspector with custom commands +- [#2632](https://github.com/sanic-org/sanic/pull/2632) Control order of restart operations +- [#2633](https://github.com/sanic-org/sanic/pull/2633) Move reload interval to class variable +- [#2636](https://github.com/sanic-org/sanic/pull/2636) Add `priority` to `register_middleware` method +- [#2639](https://github.com/sanic-org/sanic/pull/2639) Add `unquote` to `add_route` method +- [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets to receive `text` or `bytes` + +### Bugfixes + +- [#2607](https://github.com/sanic-org/sanic/pull/2607) Force socket shutdown before close to allow rebinding +- [#2590](https://github.com/sanic-org/sanic/pull/2590) Use actual `StrEnum` in Python 3.11+ +- [#2615](https://github.com/sanic-org/sanic/pull/2615) Ensure middleware executes only once per request timeout +- [#2627](https://github.com/sanic-org/sanic/pull/2627) Crash ASGI application on lifespan failure +- [#2635](https://github.com/sanic-org/sanic/pull/2635) Resolve error with low-level server creation on Windows + +### Deprecations and Removals + +- [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) Signal conditions and triggers saved on `signal.extra` +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector + - 🚨 _BREAKING CHANGE_: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol + - _DEPRECATE_: The `--inspect*` commands have been deprecated in favor of `inspect ...` commands +- [#2628](https://github.com/sanic-org/sanic/pull/2628) Replace deprecated `distutils.strtobool` + +### Developer infrastructure + +- [#2612](https://github.com/sanic-org/sanic/pull/2612) Add CI testing for Python 3.11 + +## Version 22.9.1 + +### Features + +- [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered + +### Bugfixes + +- [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation +- [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility +- [#2592](https://github.com/sanic-org/sanic/pull/2592) Fix properties in nested blueprint groups +- [#2595](https://github.com/sanic-org/sanic/pull/2595) Introduce sleep interval on new worker reloader + +### Deprecations and Removals + +### Developer infrastructure + +- [#2588](https://github.com/sanic-org/sanic/pull/2588) Markdown templates on issue forms + +### Improved Documentation + +- [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 documentation +- [#2582](https://github.com/sanic-org/sanic/pull/2582) Cleanup documentation on Windows support + +## Version 22.9.0 + +### Features + +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom loads function +- [#2490](https://github.com/sanic-org/sanic/pull/2490) Make `WebsocketImplProtocol` async iterable +- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refactor +- [#2506](https://github.com/sanic-org/sanic/pull/2506) Use `pathlib` for path resolution (for static file serving) +- [#2508](https://github.com/sanic-org/sanic/pull/2508) Use `path.parts` instead of `match` (for static file serving) +- [#2513](https://github.com/sanic-org/sanic/pull/2513) Better request cancel handling +- [#2516](https://github.com/sanic-org/sanic/pull/2516) Add request properties for HTTP method info: + - `request.is_safe` + - `request.is_idempotent` + - `request.is_cacheable` + - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _for more information about when these apply_ +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI +- [#2526](https://github.com/sanic-org/sanic/pull/2526) Cache control support for static files for returning 304 when appropriate +- [#2533](https://github.com/sanic-org/sanic/pull/2533) Refactor `_static_request_handler` +- [#2540](https://github.com/sanic-org/sanic/pull/2540) Add signals before and after handler execution + - `http.handler.before` + - `http.handler.after` +- [#2542](https://github.com/sanic-org/sanic/pull/2542) Add _[redacted]_ to CLI :) +- [#2546](https://github.com/sanic-org/sanic/pull/2546) Add deprecation warning filter +- [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware priority and performance enhancements + +### Bugfixes + +- [#2495](https://github.com/sanic-org/sanic/pull/2495) Prevent directory traversion with static files +- [#2515](https://github.com/sanic-org/sanic/pull/2515) Do not apply double slash to paths in certain static dirs in Blueprints + +### Deprecations and Removals + +- [#2525](https://github.com/sanic-org/sanic/pull/2525) Warn on duplicate route names, will be prevented outright in v23.3 +- [#2537](https://github.com/sanic-org/sanic/pull/2537) Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3 + +### Developer infrastructure + +- [#2504](https://github.com/sanic-org/sanic/pull/2504) Cleanup test suite +- [#2505](https://github.com/sanic-org/sanic/pull/2505) Replace Unsupported Python Version Number from the Contributing Doc +- [#2530](https://github.com/sanic-org/sanic/pull/2530) Do not include tests folder in installed package resolver + +### Improved Documentation + +- [#2502](https://github.com/sanic-org/sanic/pull/2502) Fix a few typos +- [#2517](https://github.com/sanic-org/sanic/pull/2517) [#2536](https://github.com/sanic-org/sanic/pull/2536) Add some type hints + +## Version 22.6.2 + +### Bugfixes + +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI + +## Version 22.6.1 + +### Bugfixes + +- [#2477](https://github.com/sanic-org/sanic/pull/2477) Sanic static directory fails when folder name ends with ".." + +## Version 22.6.0 + +### Features + +- [#2378](https://github.com/sanic-org/sanic/pull/2378) Introduce HTTP/3 and autogeneration of TLS certificates in `DEBUG` mode + - 👶 _EARLY RELEASE FEATURE_: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented. + - 📦 _EXTRA REQUIREMENT_: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a [HTTP/3 capable client](https://curl.se/docs/http3.html). + - 📦 _EXTRA REQUIREMENT_: In order to use TLS autogeneration, you must install either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). +- [#2416](https://github.com/sanic-org/sanic/pull/2416) Add message to `task.cancel` +- [#2420](https://github.com/sanic-org/sanic/pull/2420) Add exception aliases for more consistent naming with standard HTTP response types (`BadRequest`, `MethodNotAllowed`, `RangeNotSatisfiable`) +- [#2432](https://github.com/sanic-org/sanic/pull/2432) Expose ASGI `scope` as a property on the `Request` object +- [#2438](https://github.com/sanic-org/sanic/pull/2438) Easier access to websocket class for annotation: `from sanic import Websocket` +- [#2439](https://github.com/sanic-org/sanic/pull/2439) New API for reading form values with options: `Request.get_form` +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom `loads` function +- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) Improved API to support setting cache control headers +- [#2453](https://github.com/sanic-org/sanic/pull/2453) Move verbosity filtering to logger +- [#2475](https://github.com/sanic-org/sanic/pull/2475) Expose getter for current request using `Request.get_current()` + +### Bugfixes + +- [#2448](https://github.com/sanic-org/sanic/pull/2448) Fix to allow running with `pythonw.exe` or places where there is no `sys.stdout` +- [#2451](https://github.com/sanic-org/sanic/pull/2451) Trigger `http.lifecycle.request` signal in ASGI mode +- [#2455](https://github.com/sanic-org/sanic/pull/2455) Resolve typing of stacked route definitions +- [#2463](https://github.com/sanic-org/sanic/pull/2463) Properly catch websocket CancelledError in websocket handler in Python 3.7 + +### Deprecations and Removals + +- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 deprecations and changes + 1. Optional application registry + 2. Execution of custom handlers after some part of response was sent + 3. Configuring fallback handlers on the `ErrorHandler` + 4. Custom `LOGO` setting + 5. `sanic.response.stream` + 6. `AsyncioServer.init` + +### Developer infrastructure + +- [#2449](https://github.com/sanic-org/sanic/pull/2449) Clean up `black` and `isort` config +- [#2479](https://github.com/sanic-org/sanic/pull/2479) Fix some flappy tests + +### Improved Documentation + +- [#2461](https://github.com/sanic-org/sanic/pull/2461) Update example to match current application naming standards +- [#2466](https://github.com/sanic-org/sanic/pull/2466) Better type annotation for `Extend` +- [#2485](https://github.com/sanic-org/sanic/pull/2485) Improved help messages in CLI + +## Version 22.3.0 + +### Features + +- [#2347](https://github.com/sanic-org/sanic/pull/2347) API for multi-application server + - 🚨 _BREAKING CHANGE_: The old `sanic.worker.GunicornWorker` has been **removed**. To run Sanic with `gunicorn`, you should use it thru `uvicorn` [as described in their docs](https://www.uvicorn.org/#running-with-gunicorn). + - 🧁 _SIDE EFFECT_: Named background tasks are now supported, even in Python 3.7 +- [#2357](https://github.com/sanic-org/sanic/pull/2357) Parse `Authorization` header as `Request.credentials` +- [#2361](https://github.com/sanic-org/sanic/pull/2361) Add config option to skip `Touchup` step in application startup +- [#2372](https://github.com/sanic-org/sanic/pull/2372) Updates to CLI help messaging +- [#2382](https://github.com/sanic-org/sanic/pull/2382) Downgrade warnings to backwater debug messages +- [#2396](https://github.com/sanic-org/sanic/pull/2396) Allow for `multidict` v0.6 +- [#2401](https://github.com/sanic-org/sanic/pull/2401) Upgrade CLI catching for alternative application run types +- [#2402](https://github.com/sanic-org/sanic/pull/2402) Conditionally inject CLI arguments into factory +- [#2413](https://github.com/sanic-org/sanic/pull/2413) Add new start and stop event listeners to reloader process +- [#2414](https://github.com/sanic-org/sanic/pull/2414) Remove loop as required listener arg +- [#2415](https://github.com/sanic-org/sanic/pull/2415) Better exception for bad URL parsing +- [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) Add a new extention parameter type: ``, ``, ``, ``, ``, `` + - 👶 _BETA FEATURE_: This feature will not work with `path` type matching, and is being released as a beta feature only. +- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) Change `register_pattern` to accept a `str` or `Pattern` +- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) Default matching on non-empty strings only, and new `strorempty` pattern type + - 🚨 _BREAKING CHANGE_: Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now **only** match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. + +### Bugfixes + +- [#2373](https://github.com/sanic-org/sanic/pull/2373) Remove `error_logger` on websockets +- [#2381](https://github.com/sanic-org/sanic/pull/2381) Fix newly assigned `None` in task registry +- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) Add type casting to regex route matching +- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) Add requirements check on regex routes (this resolves, for example, multiple static directories with differing `host` values) + +### Deprecations and Removals + +- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 Deprecations and changes + 1. `debug=True` and `--debug` do _NOT_ automatically run `auto_reload` + 2. Default error render is with plain text (browsers still get HTML by default because `auto` looks at headers) + 3. `config` is required for `ErrorHandler.finalize` + 4. `ErrorHandler.lookup` requires two positional args + 5. Unused websocket protocol args removed +- [#2344](https://github.com/sanic-org/sanic/pull/2344) Deprecate loading of lowercase environment variables + +### Developer infrastructure + +- [#2363](https://github.com/sanic-org/sanic/pull/2363) Revert code coverage back to Codecov +- [#2405](https://github.com/sanic-org/sanic/pull/2405) Upgrade tests for `sanic-routing` changes +- [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) Allow for httpx v0.22 + +### Improved Documentation + +- [#2350](https://github.com/sanic-org/sanic/pull/2350) Fix link in README for ASGI +- [#2398](https://github.com/sanic-org/sanic/pull/2398) Document middleware on_request and on_response +- [#2409](https://github.com/sanic-org/sanic/pull/2409) Add missing documentation for `Request.respond` + +### Miscellaneous + +- [#2376](https://github.com/sanic-org/sanic/pull/2376) Fix typing for `ListenerMixin.listener` +- [#2383](https://github.com/sanic-org/sanic/pull/2383) Clear deprecation warning in `asyncio.wait` +- [#2387](https://github.com/sanic-org/sanic/pull/2387) Cleanup `__slots__` implementations +- [#2390](https://github.com/sanic-org/sanic/pull/2390) Clear deprecation warning in `asyncio.get_event_loop` + +## Version 21.12.1 + +- [#2349](https://github.com/sanic-org/sanic/pull/2349) Only display MOTD on startup +- [#2354](https://github.com/sanic-org/sanic/pull/2354) Ignore name argument in Python 3.7 +- [#2355](https://github.com/sanic-org/sanic/pull/2355) Add config.update support for all config values + +## Version 21.12.0 + +### Features + +- [#2260](https://github.com/sanic-org/sanic/pull/2260) Allow early Blueprint registrations to still apply later added objects +- [#2262](https://github.com/sanic-org/sanic/pull/2262) Noisy exceptions - force logging of all exceptions +- [#2264](https://github.com/sanic-org/sanic/pull/2264) Optional `uvloop` by configuration +- [#2270](https://github.com/sanic-org/sanic/pull/2270) Vhost support using multiple TLS certificates +- [#2277](https://github.com/sanic-org/sanic/pull/2277) Change signal routing for increased consistency + - _BREAKING CHANGE_: If you were manually routing signals there is a breaking change. The signal router's `get` is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using `app.dispatch` or `bp.dispatch`, there is no change. +- [#2290](https://github.com/sanic-org/sanic/pull/2290) Add contextual exceptions +- [#2291](https://github.com/sanic-org/sanic/pull/2291) Increase join concat performance +- [#2295](https://github.com/sanic-org/sanic/pull/2295), [#2316](https://github.com/sanic-org/sanic/pull/2316), [#2331](https://github.com/sanic-org/sanic/pull/2331) Restructure of CLI and application state with new displays and more command parity with `app.run` +- [#2302](https://github.com/sanic-org/sanic/pull/2302) Add route context at definition time +- [#2304](https://github.com/sanic-org/sanic/pull/2304) Named tasks and new API for managing background tasks +- [#2307](https://github.com/sanic-org/sanic/pull/2307) On app auto-reload, provide insight of changed files +- [#2308](https://github.com/sanic-org/sanic/pull/2308) Auto extend application with [Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) if it is installed, and provide first class support for accessing the extensions +- [#2309](https://github.com/sanic-org/sanic/pull/2309) Builtin signals changed to `Enum` +- [#2313](https://github.com/sanic-org/sanic/pull/2313) Support additional config implementation use case +- [#2321](https://github.com/sanic-org/sanic/pull/2321) Refactor environment variable hydration logic +- [#2327](https://github.com/sanic-org/sanic/pull/2327) Prevent sending multiple or mixed responses on a single request +- [#2330](https://github.com/sanic-org/sanic/pull/2330) Custom type casting on environment variables +- [#2332](https://github.com/sanic-org/sanic/pull/2332) Make all deprecation notices consistent +- [#2335](https://github.com/sanic-org/sanic/pull/2335) Allow underscore to start instance names + +### Bugfixes + +- [#2273](https://github.com/sanic-org/sanic/pull/2273) Replace assignation by typing for `websocket_handshake` +- [#2285](https://github.com/sanic-org/sanic/pull/2285) Fix IPv6 display in startup logs +- [#2299](https://github.com/sanic-org/sanic/pull/2299) Dispatch `http.lifecyle.response` from exception handler + +### Deprecations and Removals + +- [#2306](https://github.com/sanic-org/sanic/pull/2306) Removal of deprecated items + - `Sanic` and `Blueprint` may no longer have arbitrary properties attached to them + - `Sanic` and `Blueprint` forced to have compliant names + - alphanumeric + `_` + `-` + - must start with letter or `_` + - `load_env` keyword argument of `Sanic` + - `sanic.exceptions.abort` + - `sanic.views.CompositionView` + - `sanic.response.StreamingHTTPResponse` + - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming +- [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting + +### Developer infrastructure + +- [#2251](https://github.com/sanic-org/sanic/pull/2251) Change dev install command +- [#2286](https://github.com/sanic-org/sanic/pull/2286) Change codeclimate complexity threshold from 5 to 10 +- [#2287](https://github.com/sanic-org/sanic/pull/2287) Update host test function names so they are not overwritten +- [#2292](https://github.com/sanic-org/sanic/pull/2292) Fail CI on error +- [#2311](https://github.com/sanic-org/sanic/pull/2311), [#2324](https://github.com/sanic-org/sanic/pull/2324) Do not run tests for draft PRs +- [#2336](https://github.com/sanic-org/sanic/pull/2336) Remove paths from coverage checks +- [#2338](https://github.com/sanic-org/sanic/pull/2338) Cleanup ports on tests + +### Improved Documentation + +- [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2329), [#2333](https://github.com/sanic-org/sanic/pull/2333) Cleanup typos and fix language + +### Miscellaneous + +- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) Add Python 3.10 support +- [#2279](https://github.com/sanic-org/sanic/pull/2279), [#2317](https://github.com/sanic-org/sanic/pull/2317), [#2322](https://github.com/sanic-org/sanic/pull/2322) Add/correct missing type annotations +- [#2305](https://github.com/sanic-org/sanic/pull/2305) Fix examples to use modern implementations + +## Version 21.9.3 + +_Rerelease of v21.9.2 with some cleanup_ + +## Version 21.9.2 + +- [#2268](https://github.com/sanic-org/sanic/pull/2268) Make HTTP connections start in IDLE stage, avoiding delays and error messages +- [#2310](https://github.com/sanic-org/sanic/pull/2310) More consistent config setting with post-FALLBACK_ERROR_FORMAT apply + +## Version 21.9.1 + +- [#2259](https://github.com/sanic-org/sanic/pull/2259) Allow non-conforming ErrorHandlers + +## Version 21.9.0 + +### Features + +- [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) Complete overhaul of I/O to websockets +- [#2160](https://github.com/sanic-org/sanic/pull/2160) Add new 17 signals into server and request lifecycles +- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto` fallback formatting upon exception +- [#2184](https://github.com/sanic-org/sanic/pull/2184) Introduce implementation for copying a Blueprint +- [#2200](https://github.com/sanic-org/sanic/pull/2200) Accept header parsing +- [#2207](https://github.com/sanic-org/sanic/pull/2207) Log remote address if available +- [#2209](https://github.com/sanic-org/sanic/pull/2209) Add convenience methods to BP groups +- [#2216](https://github.com/sanic-org/sanic/pull/2216) Add default messages to SanicExceptions +- [#2225](https://github.com/sanic-org/sanic/pull/2225) Type annotation convenience for annotated handlers with path parameters +- [#2236](https://github.com/sanic-org/sanic/pull/2236) Allow Falsey (but not-None) responses from route handlers +- [#2238](https://github.com/sanic-org/sanic/pull/2238) Add `exception` decorator to Blueprint Groups +- [#2244](https://github.com/sanic-org/sanic/pull/2244) Explicit static directive for serving file or dir (ex: `static(..., resource_type="file")`) +- [#2245](https://github.com/sanic-org/sanic/pull/2245) Close HTTP loop when connection task cancelled + +### Bugfixes + +- [#2188](https://github.com/sanic-org/sanic/pull/2188) Fix the handling of the end of a chunked request +- [#2195](https://github.com/sanic-org/sanic/pull/2195) Resolve unexpected error handling on static requests +- [#2208](https://github.com/sanic-org/sanic/pull/2208) Make blueprint-based exceptions attach and trigger in a more intuitive manner +- [#2211](https://github.com/sanic-org/sanic/pull/2211) Fixed for handling exceptions of asgi app call +- [#2213](https://github.com/sanic-org/sanic/pull/2213) Fix bug where ws exceptions not being logged +- [#2231](https://github.com/sanic-org/sanic/pull/2231) Cleaner closing of tasks by using `abort()` in strategic places to avoid dangling sockets +- [#2247](https://github.com/sanic-org/sanic/pull/2247) Fix logging of auto-reload status in debug mode +- [#2246](https://github.com/sanic-org/sanic/pull/2246) Account for BP with exception handler but no routes + +### Developer infrastructure + +- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP unit tests with raw client +- [#2199](https://github.com/sanic-org/sanic/pull/2199) Switch to codeclimate +- [#2214](https://github.com/sanic-org/sanic/pull/2214) Try Reopening Windows Tests +- [#2229](https://github.com/sanic-org/sanic/pull/2229) Refactor `HttpProtocol` into a base class +- [#2230](https://github.com/sanic-org/sanic/pull/2230) Refactor `server.py` into multi-file module + +### Miscellaneous + +- [#2173](https://github.com/sanic-org/sanic/pull/2173) Remove Duplicated Dependencies and PEP 517 Support +- [#2193](https://github.com/sanic-org/sanic/pull/2193), [#2196](https://github.com/sanic-org/sanic/pull/2196), [#2217](https://github.com/sanic-org/sanic/pull/2217) Type annotation changes + +## Version 21.6.1 + +**Bugfixes** + +- [#2178](https://github.com/sanic-org/sanic/pull/2178) Update + sanic-routing to allow for better splitting of complex URI + templates +- [#2183](https://github.com/sanic-org/sanic/pull/2183) Proper + handling of chunked request bodies to resolve phantom 503 in logs +- [#2181](https://github.com/sanic-org/sanic/pull/2181) Resolve + regression in exception logging +- [#2201](https://github.com/sanic-org/sanic/pull/2201) Cleanup + request info in pipelined requests + +## Version 21.6.0 + +**Features** + +- [#2094](https://github.com/sanic-org/sanic/pull/2094) Add + `response.eof()` method for closing a stream in a handler + +- [#2097](https://github.com/sanic-org/sanic/pull/2097) Allow + case-insensitive HTTP Upgrade header + +- [#2104](https://github.com/sanic-org/sanic/pull/2104) Explicit + usage of CIMultiDict getters + +- [#2109](https://github.com/sanic-org/sanic/pull/2109) Consistent + use of error loggers + +- [#2114](https://github.com/sanic-org/sanic/pull/2114) New + `client_ip` access of connection info instance + +- [#2119](https://github.com/sanic-org/sanic/pull/2119) Alternatate + classes on instantiation for `Config` and `Sanic.ctx` + +- [#2133](https://github.com/sanic-org/sanic/pull/2133) Implement + new version of AST router + + - Proper differentiation between `alpha` and `string` param + types + - Adds a `slug` param type, example: `` + - Deprecates `` in favor of `` + - Deprecates `` in favor of `` + - Adds a `route.uri` accessor + +- [#2136](https://github.com/sanic-org/sanic/pull/2136) CLI + improvements with new optional params + +- [#2137](https://github.com/sanic-org/sanic/pull/2137) Add + `version_prefix` to URL builders + +- [#2140](https://github.com/sanic-org/sanic/pull/2140) Event + autoregistration with `EVENT_AUTOREGISTER` + +- [#2146](https://github.com/sanic-org/sanic/pull/2146), + [#2147](https://github.com/sanic-org/sanic/pull/2147) Require + stricter names on `Sanic()` and `Blueprint()` + +- [#2150](https://github.com/sanic-org/sanic/pull/2150) Infinitely + reusable and nestable `Blueprint` and `BlueprintGroup` + +- [#2154](https://github.com/sanic-org/sanic/pull/2154) Upgrade + `websockets` dependency to min version + +- [#2155](https://github.com/sanic-org/sanic/pull/2155) Allow for + maximum header sizes to be increased: `REQUEST_MAX_HEADER_SIZE` + +- [#2157](https://github.com/sanic-org/sanic/pull/2157) Allow app + factory pattern in CLI + +- [#2165](https://github.com/sanic-org/sanic/pull/2165) Change HTTP + methods to enums + +- [#2167](https://github.com/sanic-org/sanic/pull/2167) Allow + auto-reloading on additional directories + +- [#2168](https://github.com/sanic-org/sanic/pull/2168) Add simple + HTTP server to CLI + +- [#2170](https://github.com/sanic-org/sanic/pull/2170) Additional + methods for attaching `HTTPMethodView` + +**Bugfixes** + +- [#2091](https://github.com/sanic-org/sanic/pull/2091) Fix + `UserWarning` in ASGI mode for missing `__slots__` +- [#2099](https://github.com/sanic-org/sanic/pull/2099) Fix static + request handler logging exception on 404 +- [#2110](https://github.com/sanic-org/sanic/pull/2110) Fix + request.args.pop removes parameters inconsistently +- [#2107](https://github.com/sanic-org/sanic/pull/2107) Fix type + hinting for load_env +- [#2127](https://github.com/sanic-org/sanic/pull/2127) Make sure + ASGI ws subprotocols is a list +- [#2128](https://github.com/sanic-org/sanic/pull/2128) Fix issue + where Blueprint exception handlers do not consistently route to + proper handler + +**Deprecations and Removals** + +- [#2156](https://github.com/sanic-org/sanic/pull/2156) Remove + config value `REQUEST_BUFFER_QUEUE_SIZE` +- [#2170](https://github.com/sanic-org/sanic/pull/2170) + `CompositionView` deprecated and marked for removal in 21.12 +- [#2172](https://github.com/sanic-org/sanic/pull/2170) Deprecate + StreamingHTTPResponse + +**Developer infrastructure** + +- [#2149](https://github.com/sanic-org/sanic/pull/2149) Remove + Travis CI in favor of GitHub Actions + +**Improved Documentation** + +- [#2164](https://github.com/sanic-org/sanic/pull/2164) Fix typo in + documentation +- [#2100](https://github.com/sanic-org/sanic/pull/2100) Remove + documentation for non-existent arguments + +## Version 21.3.2 + +**Bugfixes** + +- [#2081](https://github.com/sanic-org/sanic/pull/2081) Disable + response timeout on websocket connections +- [#2085](https://github.com/sanic-org/sanic/pull/2085) Make sure + that blueprints with no slash is maintained when applied + +## Version 21.3.1 + +**Bugfixes** + +- [#2076](https://github.com/sanic-org/sanic/pull/2076) Static files + inside subfolders are not accessible (404) + +## Version 21.3.0 + +Release +Notes + +**Features** + +- [#1876](https://github.com/sanic-org/sanic/pull/1876) Unified + streaming server +- [#2005](https://github.com/sanic-org/sanic/pull/2005) New + `Request.id` property +- [#2008](https://github.com/sanic-org/sanic/pull/2008) Allow + Pathlib Path objects to be passed to `app.static()` helper +- [#2010](https://github.com/sanic-org/sanic/pull/2010), + [#2031](https://github.com/sanic-org/sanic/pull/2031) New + startup-optimized router +- [#2018](https://github.com/sanic-org/sanic/pull/2018) + [#2064](https://github.com/sanic-org/sanic/pull/2064) Listeners + for main server process +- [#2032](https://github.com/sanic-org/sanic/pull/2032) Add raw + header info to request object +- [#2042](https://github.com/sanic-org/sanic/pull/2042) + [#2060](https://github.com/sanic-org/sanic/pull/2060) + [#2061](https://github.com/sanic-org/sanic/pull/2061) Introduce + Signals API +- [#2043](https://github.com/sanic-org/sanic/pull/2043) Add + `__str__` and `__repr__` to Sanic and Blueprint +- [#2047](https://github.com/sanic-org/sanic/pull/2047) Enable + versioning and strict slash on BlueprintGroup +- [#2053](https://github.com/sanic-org/sanic/pull/2053) Make + `get_app` name argument optional +- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON encoder + change via app +- [#2063](https://github.com/sanic-org/sanic/pull/2063) App and + connection level context objects + +**Bugfixes** + +- Resolve [#1420](https://github.com/sanic-org/sanic/pull/1420) + `url_for` where `strict_slashes` are on for a path ending in `/` +- Resolve [#1525](https://github.com/sanic-org/sanic/pull/1525) + Routing is incorrect with some special characters +- Resolve [#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI + headers in body +- Resolve [#1722](https://github.com/sanic-org/sanic/pull/1722) + Using curl in chunk mode +- Resolve [#1730](https://github.com/sanic-org/sanic/pull/1730) + Extra content in ASGI streaming response +- Resolve [#1749](https://github.com/sanic-org/sanic/pull/1749) + Restore broken middleware edge cases +- Resolve [#1785](https://github.com/sanic-org/sanic/pull/1785) + [#1804](https://github.com/sanic-org/sanic/pull/1804) Synchronous + error handlers +- Resolve [#1790](https://github.com/sanic-org/sanic/pull/1790) + Protocol errors did not support async error handlers #1790 +- Resolve [#1824](https://github.com/sanic-org/sanic/pull/1824) + Timeout on specific methods +- Resolve [#1875](https://github.com/sanic-org/sanic/pull/1875) + Response timeout error from all routes after returning several + timeouts from a specific route +- Resolve [#1988](https://github.com/sanic-org/sanic/pull/1988) + Handling of safe methods with body +- [#2001](https://github.com/sanic-org/sanic/pull/2001) Raise + ValueError when cookie max-age is not an integer + +**Deprecations and Removals** + +- [#2007](https://github.com/sanic-org/sanic/pull/2007) \* Config + using `from_envvar` \* Config using `from_pyfile` \* Config using + `from_object` +- [#2009](https://github.com/sanic-org/sanic/pull/2009) Remove Sanic + test client to its own package +- [#2036](https://github.com/sanic-org/sanic/pull/2036), + [#2037](https://github.com/sanic-org/sanic/pull/2037) Drop Python + 3.6 support +- `Request.endpoint` deprecated in favor of `Request.name` +- handler type name prefixes removed (static, websocket, etc) + +**Developer infrastructure** + +- [#1995](https://github.com/sanic-org/sanic/pull/1995) Create + FUNDING.yml +- [#2013](https://github.com/sanic-org/sanic/pull/2013) Add codeql + to CI pipeline +- [#2038](https://github.com/sanic-org/sanic/pull/2038) Codecov + configuration updates +- [#2049](https://github.com/sanic-org/sanic/pull/2049) Updated + setup.py to use `find_packages` + +**Improved Documentation** + +- [#1218](https://github.com/sanic-org/sanic/pull/1218) + Documentation for sanic.log.\* is missing +- [#1608](https://github.com/sanic-org/sanic/pull/1608) Add + documentation on calver and LTS +- [#1731](https://github.com/sanic-org/sanic/pull/1731) Support + mounting application elsewhere than at root path +- [#2006](https://github.com/sanic-org/sanic/pull/2006) Upgraded + type annotations and improved docstrings and API documentation +- [#2052](https://github.com/sanic-org/sanic/pull/2052) Fix some + examples and docs + +**Miscellaneous** + +- `Request.route` property +- Better websocket subprotocols support +- Resolve bug with middleware in Blueprint Group when passed + callable +- Moves common logic between Blueprint and Sanic into mixins +- Route naming changed to be more consistent + - request endpoint is the route name + - route names are fully namespaced +- Some new convenience decorators: + - `@app.main_process_start` + - `@app.main_process_stop` + - `@app.before_server_start` + - `@app.after_server_start` + - `@app.before_server_stop` + - `@app.after_server_stop` + - `@app.on_request` + - `@app.on_response` +- Fixes `Allow` header that did not include `HEAD` +- Using "name" keyword in `url_for` for a "static" route where + name does not exist +- Cannot have multiple `app.static()` without using the named param +- Using "filename" keyword in `url_for` on a file route +- `unquote` in route def (not automatic) +- `routes_all` is tuples +- Handler arguments are kwarg only +- `request.match_info` is now a cached (and not computed) property +- Unknown static file mimetype is sent as `application/octet-stream` +- `_host` keyword in `url_for` +- Add charset default to `utf-8` for text and js content types if + not specified +- Version for a route can be str, float, or int +- Route has ctx property +- App has `routes_static`, `routes_dynamic`, `routes_regex` +- [#2044](https://github.com/sanic-org/sanic/pull/2044) Code cleanup + and refactoring +- [#2072](https://github.com/sanic-org/sanic/pull/2072) Remove + `BaseSanic` metaclass +- [#2074](https://github.com/sanic-org/sanic/pull/2074) Performance + adjustments in `handle_request_` + +## Version 20.12.3 + +**Bugfixes** + +- [#2021](https://github.com/sanic-org/sanic/pull/2021) Remove + prefix from websocket handler name + +## Version 20.12.2 + +**Dependencies** + +- [#2026](https://github.com/sanic-org/sanic/pull/2026) Fix uvloop + to 0.14 because 0.15 drops Python 3.6 support +- [#2029](https://github.com/sanic-org/sanic/pull/2029) Remove old + chardet requirement, add in hard multidict requirement + +## Version 19.12.5 + +**Dependencies** + +- [#2025](https://github.com/sanic-org/sanic/pull/2025) Fix uvloop + to 0.14 because 0.15 drops Python 3.6 support +- [#2027](https://github.com/sanic-org/sanic/pull/2027) Remove old + chardet requirement, add in hard multidict requirement + +## Version 20.12.0 + +**Features** + +- [#1993](https://github.com/sanic-org/sanic/pull/1993) Add disable + app registry +- [#1945](https://github.com/sanic-org/sanic/pull/1945) Static route + more verbose if file not found +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + routes registration on a blueprint +- [#1961](https://github.com/sanic-org/sanic/pull/1961) Add Python + 3.9 support +- [#1962](https://github.com/sanic-org/sanic/pull/1962) Sanic CLI + upgrade +- [#1967](https://github.com/sanic-org/sanic/pull/1967) Update + aiofile version requirements +- [#1969](https://github.com/sanic-org/sanic/pull/1969) Update + multidict version requirements +- [#1970](https://github.com/sanic-org/sanic/pull/1970) Add py.typed + file +- [#1972](https://github.com/sanic-org/sanic/pull/1972) Speed + optimization in request handler +- [#1979](https://github.com/sanic-org/sanic/pull/1979) Add app + registry and Sanic class level app retrieval + +**Bugfixes** + +- [#1965](https://github.com/sanic-org/sanic/pull/1965) Fix Chunked + Transport-Encoding in ASGI streaming response + +**Deprecations and Removals** + +- [#1981](https://github.com/sanic-org/sanic/pull/1981) Cleanup and + remove deprecated code + +**Developer infrastructure** + +- [#1956](https://github.com/sanic-org/sanic/pull/1956) Fix load + module test +- [#1973](https://github.com/sanic-org/sanic/pull/1973) Transition + Travis from .org to .com +- [#1986](https://github.com/sanic-org/sanic/pull/1986) Update tox + requirements + +**Improved Documentation** + +- [#1951](https://github.com/sanic-org/sanic/pull/1951) + Documentation improvements +- [#1983](https://github.com/sanic-org/sanic/pull/1983) Remove + duplicate contents in testing.rst +- [#1984](https://github.com/sanic-org/sanic/pull/1984) Fix typo in + routing.rst + +## Version 20.9.1 + +**Bugfixes** + +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + route registration on blueprints +- [#1957](https://github.com/sanic-org/sanic/pull/1957) Removes + duplicate headers in ASGI streaming body + +## Version 19.12.3 + +**Bugfixes** + +- [#1959](https://github.com/sanic-org/sanic/pull/1959) Removes + duplicate headers in ASGI streaming body + +## Version 20.9.0 + +**Features** + +- [#1887](https://github.com/sanic-org/sanic/pull/1887) Pass + subprotocols in websockets (both sanic server and ASGI) +- [#1894](https://github.com/sanic-org/sanic/pull/1894) + Automatically set `test_mode` flag on app instance +- [#1903](https://github.com/sanic-org/sanic/pull/1903) Add new + unified method for updating app values +- [#1906](https://github.com/sanic-org/sanic/pull/1906), + [#1909](https://github.com/sanic-org/sanic/pull/1909) Adds + WEBSOCKET_PING_TIMEOUT and WEBSOCKET_PING_INTERVAL configuration + values +- [#1935](https://github.com/sanic-org/sanic/pull/1935) httpx + version dependency updated, it is slated for removal as a + dependency in v20.12 +- [#1937](https://github.com/sanic-org/sanic/pull/1937) Added auto, + text, and json fallback error handlers (in v21.3, the default will + change form html to auto) + +**Bugfixes** + +- [#1897](https://github.com/sanic-org/sanic/pull/1897) Resolves + exception from unread bytes in stream + +**Deprecations and Removals** + +- [#1903](https://github.com/sanic-org/sanic/pull/1903) + config.from_envar, config.from_pyfile, and config.from_object are + deprecated and set to be removed in v21.3 + +**Developer infrastructure** + +- [#1890](https://github.com/sanic-org/sanic/pull/1890), + [#1891](https://github.com/sanic-org/sanic/pull/1891) Update isort + calls to be compatible with new API +- [#1893](https://github.com/sanic-org/sanic/pull/1893) Remove + version section from setup.cfg +- [#1924](https://github.com/sanic-org/sanic/pull/1924) Adding + \--strict-markers for pytest + +**Improved Documentation** + +- [#1922](https://github.com/sanic-org/sanic/pull/1922) Add explicit + ASGI compliance to the README + +## Version 20.6.3 + +**Bugfixes** + +- [#1884](https://github.com/sanic-org/sanic/pull/1884) Revert + change to multiprocessing mode + +## Version 20.6.2 + +**Features** + +- [#1641](https://github.com/sanic-org/sanic/pull/1641) Socket + binding implemented properly for IPv6 and UNIX sockets + +## Version 20.6.1 + +**Features** + +- [#1760](https://github.com/sanic-org/sanic/pull/1760) Add version + parameter to websocket routes +- [#1866](https://github.com/sanic-org/sanic/pull/1866) Add `sanic` + as an entry point command +- [#1880](https://github.com/sanic-org/sanic/pull/1880) Add handler + names for websockets for url_for usage + +**Bugfixes** + +- [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for + host parameter issue with lists +- [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static + _handler pickling error +- [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader + on OSX py38 and Windows +- [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse + named_response_middlware execution order, to match normal response + middleware execution order +- [#1853](https://github.com/sanic-org/sanic/pull/1853) Fix pickle + error when attempting to pickle an application which contains + websocket routes + +**Deprecations and Removals** + +- [#1739](https://github.com/sanic-org/sanic/pull/1739) Deprecate + body_bytes to merge into body + +**Developer infrastructure** + +- [#1852](https://github.com/sanic-org/sanic/pull/1852) Fix naming + of CI test env on Python nightlies +- [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust + websockets version to setup.py +- [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap + run()'s "protocol" type annotation in Optional[] + +**Improved Documentation** + +- [#1846](https://github.com/sanic-org/sanic/pull/1846) Update docs + to clarify response middleware execution order +- [#1865](https://github.com/sanic-org/sanic/pull/1865) Fixing rst + format issue that was hiding documentation + +## Version 20.6.0 + +_Released, but unintentionally omitting PR #1880, so was replaced by +20.6.1_ + +## Version 20.3.0 + +**Features** + +- [#1762](https://github.com/sanic-org/sanic/pull/1762) Add + `srv.start_serving()` and `srv.serve_forever()` to `AsyncioServer` +- [#1767](https://github.com/sanic-org/sanic/pull/1767) Make Sanic + usable on `hypercorn -k trio myweb.app` +- [#1768](https://github.com/sanic-org/sanic/pull/1768) No + tracebacks on normal errors and prettier error pages +- [#1769](https://github.com/sanic-org/sanic/pull/1769) Code cleanup + in file responses +- [#1793](https://github.com/sanic-org/sanic/pull/1793) and + [#1819](https://github.com/sanic-org/sanic/pull/1819) Upgrade + `str.format()` to f-strings +- [#1798](https://github.com/sanic-org/sanic/pull/1798) Allow + multiple workers on MacOS with Python 3.8 +- [#1820](https://github.com/sanic-org/sanic/pull/1820) Do not set + content-type and content-length headers in exceptions + +**Bugfixes** + +- [#1748](https://github.com/sanic-org/sanic/pull/1748) Remove loop + argument in `asyncio.Event` in Python 3.8 +- [#1764](https://github.com/sanic-org/sanic/pull/1764) Allow route + decorators to stack up again +- [#1789](https://github.com/sanic-org/sanic/pull/1789) Fix tests + using hosts yielding incorrect `url_for` +- [#1808](https://github.com/sanic-org/sanic/pull/1808) Fix Ctrl+C + and tests on Windows + +**Deprecations and Removals** + +- [#1800](https://github.com/sanic-org/sanic/pull/1800) Begin + deprecation in way of first-class streaming, removal of + `body_init`, `body_push`, and `body_finish` +- [#1801](https://github.com/sanic-org/sanic/pull/1801) Complete + deprecation from + [#1666](https://github.com/sanic-org/sanic/pull/1666) of + dictionary context on `request` objects. +- [#1807](https://github.com/sanic-org/sanic/pull/1807) Remove + server config args that can be read directly from app +- [#1818](https://github.com/sanic-org/sanic/pull/1818) Complete + deprecation of `app.remove_route` and `request.raw_args` + +**Dependencies** + +- [#1794](https://github.com/sanic-org/sanic/pull/1794) Bump `httpx` + to 0.11.1 +- [#1806](https://github.com/sanic-org/sanic/pull/1806) Import + `ASGIDispatch` from top-level `httpx` (from third-party + deprecation) + +**Developer infrastructure** + +- [#1833](https://github.com/sanic-org/sanic/pull/1833) Resolve + broken documentation builds + +**Improved Documentation** + +- [#1755](https://github.com/sanic-org/sanic/pull/1755) Usage of + `response.empty()` +- [#1778](https://github.com/sanic-org/sanic/pull/1778) Update + README +- [#1783](https://github.com/sanic-org/sanic/pull/1783) Fix typo +- [#1784](https://github.com/sanic-org/sanic/pull/1784) Corrected + changelog for docs move of MD to RST + ([#1691](https://github.com/sanic-org/sanic/pull/1691)) +- [#1803](https://github.com/sanic-org/sanic/pull/1803) Update + config docs to match DEFAULT_CONFIG +- [#1814](https://github.com/sanic-org/sanic/pull/1814) Update + getting_started.rst +- [#1821](https://github.com/sanic-org/sanic/pull/1821) Update to + deployment +- [#1822](https://github.com/sanic-org/sanic/pull/1822) Update docs + with changes done in 20.3 +- [#1834](https://github.com/sanic-org/sanic/pull/1834) Order of + listeners + +## Version 19.12.0 + +**Bugfixes** + +- Fix blueprint middleware application + + Currently, any blueprint middleware registered, irrespective of + which blueprint was used to do so, was being applied to all of the + routes created by the `@app` and `@blueprint` alike. + + As part of this change, the blueprint based middleware application + is enforced based on where they are registered. + + - If you register a middleware via `@blueprint.middleware` then it + will apply only to the routes defined by the blueprint. + - If you register a middleware via `@blueprint_group.middleware` + then it will apply to all blueprint based routes that are part + of the group. + - If you define a middleware via `@app.middleware` then it will be + applied on all available routes + ([#37](https://github.com/sanic-org/sanic/issues/37)) + +- Fix [url_for]{.title-ref} behavior with missing SERVER_NAME + + If the [SERVER_NAME]{.title-ref} was missing in the + [app.config]{.title-ref} entity, the [url_for]{.title-ref} on the + [request]{.title-ref} and [app]{.title-ref} were failing due to an + [AttributeError]{.title-ref}. This fix makes the availability of + [SERVER_NAME]{.title-ref} on our [app.config]{.title-ref} an + optional behavior. + ([#1707](https://github.com/sanic-org/sanic/issues/1707)) + +**Improved Documentation** + +- Move docs from MD to RST + + Moved all docs from markdown to restructured text like the rest of + the docs to unify the scheme and make it easier in the future to + update documentation. + ([#1691](https://github.com/sanic-org/sanic/issues/1691)) + +- Fix documentation for [get]{.title-ref} and [getlist]{.title-ref} of + the [request.args]{.title-ref} + + Add additional example for showing the usage of + [getlist]{.title-ref} and fix the documentation string for + [request.args]{.title-ref} behavior + ([#1704](https://github.com/sanic-org/sanic/issues/1704)) + +## Version 19.6.3 + +**Features** + +- Enable Towncrier Support + + As part of this feature, [towncrier]{.title-ref} is being introduced + as a mechanism to partially automate the process of generating and + managing change logs as part of each of pull requests. + ([#1631](https://github.com/sanic-org/sanic/issues/1631)) + +**Improved Documentation** + +- Documentation infrastructure changes + - Enable having a single common [CHANGELOG]{.title-ref} file for + both GitHub page and documentation + - Fix Sphinix deprecation warnings + - Fix documentation warnings due to invalid [rst]{.title-ref} + indentation + - Enable common contribution guidelines file across GitHub and + documentation via [CONTRIBUTING.rst]{.title-ref} + ([#1631](https://github.com/sanic-org/sanic/issues/1631)) + +## Version 19.6.2 + +**Features** + +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Remove + `aiohttp` dependency and create new `SanicTestClient` based upon + [requests-async](https://github.com/encode/requests-async) +- [#1475](https://github.com/sanic-org/sanic/pull/1475) Added ASGI + support (Beta) +- [#1436](https://github.com/sanic-org/sanic/pull/1436) Add + Configure support from object string + +**Bugfixes** + +- [#1587](https://github.com/sanic-org/sanic/pull/1587) Add missing + handle for Expect header. +- [#1560](https://github.com/sanic-org/sanic/pull/1560) Allow to + disable Transfer-Encoding: chunked. +- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix graceful + shutdown. +- [#1594](https://github.com/sanic-org/sanic/pull/1594) Strict + Slashes behavior fix + +**Deprecations and Removals** + +- [#1544](https://github.com/sanic-org/sanic/pull/1544) Drop + dependency on distutil +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Drop support + for Python 3.5 +- [#1568](https://github.com/sanic-org/sanic/pull/1568) Deprecate + route removal. + +.. warning:: Warning + +``` +Sanic will not support Python 3.5 from version 19.6 and forward. +However, version 18.12LTS will have its support period extended thru +December 2020, and therefore passing Python\'s official support version +3.5, which is set to expire in September 2020. +``` + +## Version 19.3 + +**Features** + +- [#1497](https://github.com/sanic-org/sanic/pull/1497) Add support + for zero-length and RFC 5987 encoded filename for + multipart/form-data requests. + +- [#1484](https://github.com/sanic-org/sanic/pull/1484) The type of + `expires` attribute of `sanic.cookies.Cookie` is now enforced to + be of type `datetime`. + +- [#1482](https://github.com/sanic-org/sanic/pull/1482) Add support + for the `stream` parameter of `sanic.Sanic.add_route()` available + to `sanic.Blueprint.add_route()`. + +- [#1481](https://github.com/sanic-org/sanic/pull/1481) Accept + negative values for route parameters with type `int` or `number`. + +- [#1476](https://github.com/sanic-org/sanic/pull/1476) Deprecated + the use of `sanic.request.Request.raw_args` - it has a fundamental + flaw in which is drops repeated query string parameters. Added + `sanic.request.Request.query_args` as a replacement for the + original use-case. + +- [#1472](https://github.com/sanic-org/sanic/pull/1472) Remove an + unwanted `None` check in Request class `repr` implementation. This + changes the default `repr` of a Request from `` to + `` + +- [#1470](https://github.com/sanic-org/sanic/pull/1470) Added 2 new + parameters to `sanic.app.Sanic.create_server`: + + - `return_asyncio_server` - whether to return an + asyncio.Server. + - `asyncio_server_kwargs` - kwargs to pass to + `loop.create_server` for the event loop that sanic is using. + + > + + This is a breaking change. + +- [#1499](https://github.com/sanic-org/sanic/pull/1499) Added a set + of test cases that test and benchmark route resolution. + +- [#1457](https://github.com/sanic-org/sanic/pull/1457) The type of + the `"max-age"` value in a `sanic.cookies.Cookie` is now enforced + to be an integer. Non-integer values are replaced with `0`. + +- [#1445](https://github.com/sanic-org/sanic/pull/1445) Added the + `endpoint` attribute to an incoming `request`, containing the name + of the handler function. + +- [#1423](https://github.com/sanic-org/sanic/pull/1423) Improved + request streaming. `request.stream` is now a bounded-size buffer + instead of an unbounded queue. Callers must now call + `await request.stream.read()` instead of + `await request.stream.get()` to read each portion of the body. + + This is a breaking change. + +**Bugfixes** + +- [#1502](https://github.com/sanic-org/sanic/pull/1502) Sanic was + prefetching `time.time()` and updating it once per second to avoid + excessive `time.time()` calls. The implementation was observed to + cause memory leaks in some cases. The benefit of the prefetch + appeared to negligible, so this has been removed. Fixes + [#1500](https://github.com/sanic-org/sanic/pull/1500) +- [#1501](https://github.com/sanic-org/sanic/pull/1501) Fix a bug in + the auto-reloader when the process was launched as a module i.e. + `python -m init0.mod1` where the sanic server is started in + `init0/mod1.py` with `debug` enabled and imports another module in + `init0`. +- [#1376](https://github.com/sanic-org/sanic/pull/1376) Allow sanic + test client to bind to a random port by specifying `port=None` + when constructing a `SanicTestClient` +- [#1399](https://github.com/sanic-org/sanic/pull/1399) Added the + ability to specify middleware on a blueprint group, so that all + routes produced from the blueprints in the group have the + middleware applied. +- [#1442](https://github.com/sanic-org/sanic/pull/1442) Allow the + the use the `SANIC_ACCESS_LOG` environment variable to + enable/disable the access log when not explicitly passed to + `app.run()`. This allows the access log to be disabled for example + when running via gunicorn. + +**Developer infrastructure** + +- [#1529](https://github.com/sanic-org/sanic/pull/1529) Update + project PyPI credentials +- [#1515](https://github.com/sanic-org/sanic/pull/1515) fix linter + issue causing travis build failures (fix #1514) +- [#1490](https://github.com/sanic-org/sanic/pull/1490) Fix python + version in doc build +- [#1478](https://github.com/sanic-org/sanic/pull/1478) Upgrade + setuptools version and use native docutils in doc build +- [#1464](https://github.com/sanic-org/sanic/pull/1464) Upgrade + pytest, and fix caplog unit tests + +**Improved Documentation** + +- [#1516](https://github.com/sanic-org/sanic/pull/1516) Fix typo at + the exception documentation +- [#1510](https://github.com/sanic-org/sanic/pull/1510) fix typo in + Asyncio example +- [#1486](https://github.com/sanic-org/sanic/pull/1486) + Documentation typo +- [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar + in README.md +- [#1489](https://github.com/sanic-org/sanic/pull/1489) Added + "databases" to the extensions list +- [#1483](https://github.com/sanic-org/sanic/pull/1483) Add + sanic-zipkin to extensions list +- [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link + to deleted repo, Sanic-OAuth, from the extensions list +- [#1460](https://github.com/sanic-org/sanic/pull/1460) 18.12 + changelog +- [#1449](https://github.com/sanic-org/sanic/pull/1449) Add example + of amending request object +- [#1446](https://github.com/sanic-org/sanic/pull/1446) Update + README +- [#1444](https://github.com/sanic-org/sanic/pull/1444) Update + README +- [#1443](https://github.com/sanic-org/sanic/pull/1443) Update + README, including new logo +- [#1440](https://github.com/sanic-org/sanic/pull/1440) fix minor + type and pip install instruction mismatch +- [#1424](https://github.com/sanic-org/sanic/pull/1424) + Documentation Enhancements + +Note: 19.3.0 was skipped for packagement purposes and not released on +PyPI + +## Version 18.12 + +### 18.12.0 + +- Changes: + + - Improved codebase test coverage from 81% to 91%. + - Added stream_large_files and host examples in static_file + document + - Added methods to append and finish body content on Request + (#1379) + - Integrated with .appveyor.yml for windows ci support + - Added documentation for AF_INET6 and AF_UNIX socket usage + - Adopt black/isort for codestyle + - Cancel task when connection_lost + - Simplify request ip and port retrieval logic + - Handle config error in load config file. + - Integrate with codecov for CI + - Add missed documentation for config section. + - Deprecate Handler.log + - Pinned httptools requirement to version 0.0.10+ + +- Fixes: + + - Fix `remove_entity_headers` helper function (#1415) + - Fix TypeError when use Blueprint.group() to group blueprint + with default url_prefix, Use os.path.normpath to avoid invalid + url_prefix like api//v1 f8a6af1 Rename the `http` module to + `helpers` to prevent conflicts with the built-in Python http + library (fixes #1323) + - Fix unittests on windows + - Fix Namespacing of sanic logger + - Fix missing quotes in decorator example + - Fix redirect with quoted param + - Fix doc for latest blueprint code + - Fix build of latex documentation relating to markdown lists + - Fix loop exception handling in app.py + - Fix content length mismatch in windows and other platform + - Fix Range header handling for static files (#1402) + - Fix the logger and make it work (#1397) + - Fix type pikcle->pickle in multiprocessing test + - Fix pickling blueprints Change the string passed in the + "name" section of the namedtuples in Blueprint to match the + name of the Blueprint module attribute name. This allows + blueprints to be pickled and unpickled, without errors, which + is a requirement of running Sanic in multiprocessing mode in + Windows. Added a test for pickling and unpickling blueprints + Added a test for pickling and unpickling sanic itself Added a + test for enabling multiprocessing on an app with a blueprint + (only useful to catch this bug if the tests are run on + Windows). + - Fix document for logging + +## Version 0.8 + +**0.8.3** + +- Changes: + - Ownership changed to org 'sanic-org' + +**0.8.0** + +- Changes: + - Add Server-Sent Events extension (Innokenty Lebedev) + - Graceful handling of request_handler_task cancellation (Ashley + Sommer) + - Sanitize URL before redirection (aveao) + - Add url_bytes to request (johndoe46) + - py37 support for travisci (yunstanford) + - Auto reloader support for OSX (garyo) + - Add UUID route support (Volodymyr Maksymiv) + - Add pausable response streams (Ashley Sommer) + - Add weakref to request slots (vopankov) + - remove ubuntu 12.04 from test fixture due to deprecation + (yunstanford) + - Allow streaming handlers in add_route (kinware) + - use travis_retry for tox (Raphael Deem) + - update aiohttp version for test client (yunstanford) + - add redirect import for clarity (yingshaoxo) + - Update HTTP Entity headers (Arnulfo Solís) + - Add register_listener method (Stephan Fitzpatrick) + - Remove uvloop/ujson dependencies for Windows (abuckenheimer) + - Content-length header on 204/304 responses (Arnulfo Solís) + - Extend WebSocketProtocol arguments and add docs (Bob Olde + Hampsink, yunstanford) + - Update development status from pre-alpha to beta (Maksim + Anisenkov) + - KeepAlive Timeout log level changed to debug (Arnulfo Solís) + - Pin pytest to 3.3.2 because of pytest-dev/pytest#3170 (Maksim + Aniskenov) + - Install Python 3.5 and 3.6 on docker container for tests (Shahin + Azad) + - Add support for blueprint groups and nesting (Elias Tarhini) + - Remove uvloop for windows setup (Aleksandr Kurlov) + - Auto Reload (Yaser Amari) + - Documentation updates/fixups (multiple contributors) +- Fixes: + - Fix: auto_reload in Linux (Ashley Sommer) + - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) + - Fix: disable auto_reload by default on windows (abuckenheimer) + - Fix (1143): Turn off access log with gunicorn (hqy) + - Fix (1268): Support status code for file response (Cosmo Borsky) + - Fix (1266): Add content_type flag to Sanic.static (Cosmo Borsky) + - Fix: subprotocols parameter missing from add_websocket_route + (ciscorn) + - Fix (1242): Responses for CI header (yunstanford) + - Fix (1237): add version constraint for websockets (yunstanford) + - Fix (1231): memory leak - always release resource (Phillip Xu) + - Fix (1221): make request truthy if transport exists (Raphael + Deem) + - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) + - Fix try_everything examples (PyManiacGR, kot83) + - Fix (1158): default to auto_reload in debug mode (Raphael Deem) + - Fix (1136): ErrorHandler.response handler call too restrictive + (Julien Castiaux) + - Fix: raw requires bytes-like object (cloudship) + - Fix (1120): passing a list in to a route decorator's host arg + (Timothy Ebiuwhe) + - Fix: Bug in multipart/form-data parser (DirkGuijt) + - Fix: Exception for missing parameter when value is null + (NyanKiyoshi) + - Fix: Parameter check (Howie Hu) + - Fix (1089): Routing issue with named parameters and different + methods (yunstanford) + - Fix (1085): Signal handling in multi-worker mode (yunstanford) + - Fix: single quote in readme.rst (Cosven) + - Fix: method typos (Dmitry Dygalo) + - Fix: log_response correct output for ip and port (Wibowo + Arindrarto) + - Fix (1042): Exception Handling (Raphael Deem) + - Fix: Chinese URIs (Howie Hu) + - Fix (1079): timeout bug when self.transport is None (Raphael + Deem) + - Fix (1074): fix strict_slashes when route has slash (Raphael + Deem) + - Fix (1050): add samesite cookie to cookie keys (Raphael Deem) + - Fix (1065): allow add_task after server starts (Raphael Deem) + - Fix (1061): double quotes in unauthorized exception (Raphael + Deem) + - Fix (1062): inject the app in add_task method (Raphael Deem) + - Fix: update environment.yml for readthedocs (Eli Uriegas) + - Fix: Cancel request task when response timeout is triggered + (Jeong YunWon) + - Fix (1052): Method not allowed response for RFC7231 compliance + (Raphael Deem) + - Fix: IPv6 Address and Socket Data Format (Dan Palmer) + +Note: Changelog was unmaintained between 0.1 and 0.7 + +## Version 0.1 + +**0.1.7** + +- Reversed static url and directory arguments to meet spec + +**0.1.6** + +- Static files +- Lazy Cookie Loading + +**0.1.5** + +- Cookies +- Blueprint listeners and ordering +- Faster Router +- Fix: Incomplete file reads on medium+ sized post requests +- Breaking: after_start and before_stop now pass sanic as their + first argument + +**0.1.4** + +- Multiprocessing + +**0.1.3** + +- Blueprint support +- Faster Response processing + +**0.1.1 - 0.1.2** + +- Struggling to update pypi via CI + +**0.1.0** + +- Released to public From 16fdaacc8bb38effd76cdaa4b1e8f44d71ec26a3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 15:24:07 +0200 Subject: [PATCH 276/698] New translations changelog.md (Chinese Simplified) --- guide/content/zh/release-notes/changelog.md | 1531 +++++++++++++++++++ 1 file changed, 1531 insertions(+) create mode 100644 guide/content/zh/release-notes/changelog.md diff --git a/guide/content/zh/release-notes/changelog.md b/guide/content/zh/release-notes/changelog.md new file mode 100644 index 0000000000..b98df20c9e --- /dev/null +++ b/guide/content/zh/release-notes/changelog.md @@ -0,0 +1,1531 @@ +--- +content_class: changelog +--- + +# Changelog + +🔶 Current release\ +🔷 In support LTS release + +## Version 23.12.0 🔶🔷 + +_Current version_ + +### Features + +- [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes +- [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown +- [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket +- [#2822](https://github.com/sanic-org/sanic/pull/2822) Listener and signal prioritization +- [#2831](https://github.com/sanic-org/sanic/pull/2831) Reduce memory consumption +- [#2837](https://github.com/sanic-org/sanic/pull/2837) Accept bare cookies +- [#2841](https://github.com/sanic-org/sanic/pull/2841) Add `websocket.handler.` signals +- [#2805](https://github.com/sanic-org/sanic/pull/2805) Add changed files to reload trigger listeners +- [#2813](https://github.com/sanic-org/sanic/pull/2813) Allow for simple signals +- [#2827](https://github.com/sanic-org/sanic/pull/2827) Improve functionality and consistency of `Sanic.event()` +- [#2851](https://github.com/sanic-org/sanic/pull/2851) Allow range requests for a single byte +- [#2854](https://github.com/sanic-org/sanic/pull/2854) Better `Request.scheme` for websocket requests +- [#2858](https://github.com/sanic-org/sanic/pull/2858) Convert Sanic `Request` to a Websockets `Request` for handshake +- [#2859](https://github.com/sanic-org/sanic/pull/2859) Add a REPL to the `sanic` CLI +- [#2870](https://github.com/sanic-org/sanic/pull/2870) Add Python 3.12 support +- [#2875](https://github.com/sanic-org/sanic/pull/2875) Better exception on multiprocessing context conflicts + +### Bugfixes + +- [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data + +### Deprecations and Removals + +### Developer infrastructure + +- [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases +- [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU +- [#2807](https://github.com/sanic-org/sanic/pull/2807) Add constraint for autodocsum (lint issue in old package version) +- [#2808](https://github.com/sanic-org/sanic/pull/2808) Refactor GitHub Actions +- [#2814](https://github.com/sanic-org/sanic/pull/2814) Run CI pipeline on git push +- [#2846](https://github.com/sanic-org/sanic/pull/2846) Drop old performance tests/benchmarks +- [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile cleanup +- [#2865](https://github.com/sanic-org/sanic/pull/2865) + [#2869](https://github.com/sanic-org/sanic/pull/2869) + [#2872](https://github.com/sanic-org/sanic/pull/2872) + [#2879](https://github.com/sanic-org/sanic/pull/2879) + Add ruff to toolchain +- [#2866](https://github.com/sanic-org/sanic/pull/2866) Fix the alt svc test to run locally with explicit buffer nbytes +- [#2877](https://github.com/sanic-org/sanic/pull/2877) Use Python's trusted publisher in deployments +- [#2882](https://github.com/sanic-org/sanic/pull/2882) Introduce dynamic port fixture in targeted locations in the test suite + +### Improved Documentation + +- [#2781](https://github.com/sanic-org/sanic/pull/2781) + [#2821](https://github.com/sanic-org/sanic/pull/2821) + [#2861](https://github.com/sanic-org/sanic/pull/2861) + [#2863](https://github.com/sanic-org/sanic/pull/2863) + Conversion of User Guide to the SHH (Sanic, html5tagger, HTMX) stack +- [#2810](https://github.com/sanic-org/sanic/pull/2810) Update README +- [#2855](https://github.com/sanic-org/sanic/pull/2855) Edit Discord badge +- [#2864](https://github.com/sanic-org/sanic/pull/2864) Adjust documentation for using state properties within http/https redirection document + +## Version 23.9.0 + +_Due to circumstances at the time, v.23.9 was skipped._ + +## Version 23.6.0 + +### Features + +- [#2670](https://github.com/sanic-org/sanic/pull/2670) Increase `KEEP_ALIVE_TIMEOUT` default to 120 seconds +- [#2716](https://github.com/sanic-org/sanic/pull/2716) Adding allow route overwrite option in blueprint +- [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792) Add a new exception signal for ALL exceptions raised anywhere in application +- [#2727](https://github.com/sanic-org/sanic/pull/2727) Add name prefixing to BP groups +- [#2754](https://github.com/sanic-org/sanic/pull/2754) Update request type on middleware types +- [#2770](https://github.com/sanic-org/sanic/pull/2770) Better exception message on startup time application induced import error +- [#2776](https://github.com/sanic-org/sanic/pull/2776) Set multiprocessing start method early +- [#2785](https://github.com/sanic-org/sanic/pull/2785) Add custom typing to config and ctx objects +- [#2790](https://github.com/sanic-org/sanic/pull/2790) Add `request.client_ip` + +### Bugfixes + +- [#2728](https://github.com/sanic-org/sanic/pull/2728) Fix traversals for intended results +- [#2729](https://github.com/sanic-org/sanic/pull/2729) Handle case when headers argument of ResponseStream constructor is None +- [#2737](https://github.com/sanic-org/sanic/pull/2737) Fix type annotation for `JSONREsponse` default content type +- [#2740](https://github.com/sanic-org/sanic/pull/2740) Use Sanic's serializer for JSON responses in the Inspector +- [#2760](https://github.com/sanic-org/sanic/pull/2760) Support for `Request.get_current` in ASGI mode +- [#2773](https://github.com/sanic-org/sanic/pull/2773) Alow Blueprint routes to explicitly define error_format +- [#2774](https://github.com/sanic-org/sanic/pull/2774) Resolve headers on different renderers +- [#2782](https://github.com/sanic-org/sanic/pull/2782) Resolve pypy compatibility issues + +### Deprecations and Removals + +- [#2777](https://github.com/sanic-org/sanic/pull/2777) Remove Python 3.7 support + +### Developer infrastructure + +- [#2766](https://github.com/sanic-org/sanic/pull/2766) Unpin setuptools version +- [#2779](https://github.com/sanic-org/sanic/pull/2779) Run keep alive tests in loop to get available port + +### Improved Documentation + +- [#2741](https://github.com/sanic-org/sanic/pull/2741) Better documentation examples about running Sanic + From that list, the items to highlight in the release notes: + +## Version 23.3.0 + +### Features + +- [#2545](https://github.com/sanic-org/sanic/pull/2545) Standardize init of exceptions for more consistent control of HTTP responses using exceptions +- [#2606](https://github.com/sanic-org/sanic/pull/2606) Decode headers as UTF-8 also in ASGI +- [#2646](https://github.com/sanic-org/sanic/pull/2646) Separate ASGI request and lifespan callables +- [#2659](https://github.com/sanic-org/sanic/pull/2659) Use `FALLBACK_ERROR_FORMAT` for handlers that return `empty()` +- [#2662](https://github.com/sanic-org/sanic/pull/2662) Add basic file browser (HTML page) and auto-index serving +- [#2667](https://github.com/sanic-org/sanic/pull/2667) Nicer traceback formatting (HTML page) +- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter error page rendering format selection; more reliant upon header and "common sense" defaults +- [#2680](https://github.com/sanic-org/sanic/pull/2680) Check the status of socket before shutting down with `SHUT_RDWR` +- [#2687](https://github.com/sanic-org/sanic/pull/2687) Refresh `Request.accept` functionality to be more performant and spec-compliant +- [#2696](https://github.com/sanic-org/sanic/pull/2696) Add header accessors as properties + ``` + Example-Field: Foo, Bar + Example-Field: Baz + ``` + ```python + request.headers.example_field == "Foo, Bar,Baz" + ``` +- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simpler CLI targets + + ```sh + $ sanic path.to.module:app # global app instance + $ sanic path.to.module:create_app # factory pattern + $ sanic ./path/to/directory/ # simple serve + ``` +- [#2701](https://github.com/sanic-org/sanic/pull/2701) API to define a number of workers in managed processes +- [#2704](https://github.com/sanic-org/sanic/pull/2704) Add convenience for dynamic changes to routing +- [#2706](https://github.com/sanic-org/sanic/pull/2706) Add convenience methods for cookie creation and deletion + + ```python + response = text("...") + response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com") + ``` +- [#2707](https://github.com/sanic-org/sanic/pull/2707) Simplified `parse_content_header` escaping to be RFC-compliant and remove outdated FF hack +- [#2710](https://github.com/sanic-org/sanic/pull/2710) Stricter charset handling and escaping of request URLs +- [#2711](https://github.com/sanic-org/sanic/pull/2711) Consume body on `DELETE` by default +- [#2719](https://github.com/sanic-org/sanic/pull/2719) Allow `password` to be passed to TLS context +- [#2720](https://github.com/sanic-org/sanic/pull/2720) Skip middleware on `RequestCancelled` +- [#2721](https://github.com/sanic-org/sanic/pull/2721) Change access logging format to `%s` +- [#2722](https://github.com/sanic-org/sanic/pull/2722) Add `CertLoader` as application option for directly controlling `SSLContext` objects +- [#2725](https://github.com/sanic-org/sanic/pull/2725) Worker sync state tolerance on race condition + +### Bugfixes + +- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket to pass thru bytes as is +- [#2697](https://github.com/sanic-org/sanic/pull/2697) Fix comparison between datetime aware and naive in `file` when using `If-Modified-Since` + +### Deprecations and Removals + +- [#2666](https://github.com/sanic-org/sanic/pull/2666) Remove deprecated `__blueprintname__` property + +### Improved Documentation + +- [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect + +## Version 22.12.0 🔷 + +_Current LTS version_ + +### Features + +- [#2569](https://github.com/sanic-org/sanic/pull/2569) Add `JSONResponse` class with some convenient methods when updating a response object +- [#2598](https://github.com/sanic-org/sanic/pull/2598) Change `uvloop` requirement to `>=0.15.0` +- [#2609](https://github.com/sanic-org/sanic/pull/2609) Add compatibility with `websockets` v11.0 +- [#2610](https://github.com/sanic-org/sanic/pull/2610) Kill server early on worker error + - Raise deadlock timeout to 30s +- [#2617](https://github.com/sanic-org/sanic/pull/2617) Scale number of running server workers +- [#2621](https://github.com/sanic-org/sanic/pull/2621) [#2634](https://github.com/sanic-org/sanic/pull/2634) Send `SIGKILL` on subsequent `ctrl+c` to force worker exit +- [#2622](https://github.com/sanic-org/sanic/pull/2622) Add API to restart all workers from the multiplexer +- [#2624](https://github.com/sanic-org/sanic/pull/2624) Default to `spawn` for all subprocesses unless specifically set: + ```python + from sanic import Sanic + + Sanic.start_method = "fork" + ``` +- [#2625](https://github.com/sanic-org/sanic/pull/2625) Filename normalisation of form-data/multipart file uploads +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector: + - Remote access to inspect running Sanic instances + - TLS support for encrypted calls to Inspector + - Authentication to Inspector with API key + - Ability to extend Inspector with custom commands +- [#2632](https://github.com/sanic-org/sanic/pull/2632) Control order of restart operations +- [#2633](https://github.com/sanic-org/sanic/pull/2633) Move reload interval to class variable +- [#2636](https://github.com/sanic-org/sanic/pull/2636) Add `priority` to `register_middleware` method +- [#2639](https://github.com/sanic-org/sanic/pull/2639) Add `unquote` to `add_route` method +- [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets to receive `text` or `bytes` + +### Bugfixes + +- [#2607](https://github.com/sanic-org/sanic/pull/2607) Force socket shutdown before close to allow rebinding +- [#2590](https://github.com/sanic-org/sanic/pull/2590) Use actual `StrEnum` in Python 3.11+ +- [#2615](https://github.com/sanic-org/sanic/pull/2615) Ensure middleware executes only once per request timeout +- [#2627](https://github.com/sanic-org/sanic/pull/2627) Crash ASGI application on lifespan failure +- [#2635](https://github.com/sanic-org/sanic/pull/2635) Resolve error with low-level server creation on Windows + +### Deprecations and Removals + +- [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) Signal conditions and triggers saved on `signal.extra` +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector + - 🚨 _BREAKING CHANGE_: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol + - _DEPRECATE_: The `--inspect*` commands have been deprecated in favor of `inspect ...` commands +- [#2628](https://github.com/sanic-org/sanic/pull/2628) Replace deprecated `distutils.strtobool` + +### Developer infrastructure + +- [#2612](https://github.com/sanic-org/sanic/pull/2612) Add CI testing for Python 3.11 + +## Version 22.9.1 + +### Features + +- [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered + +### Bugfixes + +- [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation +- [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility +- [#2592](https://github.com/sanic-org/sanic/pull/2592) Fix properties in nested blueprint groups +- [#2595](https://github.com/sanic-org/sanic/pull/2595) Introduce sleep interval on new worker reloader + +### Deprecations and Removals + +### Developer infrastructure + +- [#2588](https://github.com/sanic-org/sanic/pull/2588) Markdown templates on issue forms + +### Improved Documentation + +- [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 documentation +- [#2582](https://github.com/sanic-org/sanic/pull/2582) Cleanup documentation on Windows support + +## Version 22.9.0 + +### Features + +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom loads function +- [#2490](https://github.com/sanic-org/sanic/pull/2490) Make `WebsocketImplProtocol` async iterable +- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refactor +- [#2506](https://github.com/sanic-org/sanic/pull/2506) Use `pathlib` for path resolution (for static file serving) +- [#2508](https://github.com/sanic-org/sanic/pull/2508) Use `path.parts` instead of `match` (for static file serving) +- [#2513](https://github.com/sanic-org/sanic/pull/2513) Better request cancel handling +- [#2516](https://github.com/sanic-org/sanic/pull/2516) Add request properties for HTTP method info: + - `request.is_safe` + - `request.is_idempotent` + - `request.is_cacheable` + - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _for more information about when these apply_ +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI +- [#2526](https://github.com/sanic-org/sanic/pull/2526) Cache control support for static files for returning 304 when appropriate +- [#2533](https://github.com/sanic-org/sanic/pull/2533) Refactor `_static_request_handler` +- [#2540](https://github.com/sanic-org/sanic/pull/2540) Add signals before and after handler execution + - `http.handler.before` + - `http.handler.after` +- [#2542](https://github.com/sanic-org/sanic/pull/2542) Add _[redacted]_ to CLI :) +- [#2546](https://github.com/sanic-org/sanic/pull/2546) Add deprecation warning filter +- [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware priority and performance enhancements + +### Bugfixes + +- [#2495](https://github.com/sanic-org/sanic/pull/2495) Prevent directory traversion with static files +- [#2515](https://github.com/sanic-org/sanic/pull/2515) Do not apply double slash to paths in certain static dirs in Blueprints + +### Deprecations and Removals + +- [#2525](https://github.com/sanic-org/sanic/pull/2525) Warn on duplicate route names, will be prevented outright in v23.3 +- [#2537](https://github.com/sanic-org/sanic/pull/2537) Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3 + +### Developer infrastructure + +- [#2504](https://github.com/sanic-org/sanic/pull/2504) Cleanup test suite +- [#2505](https://github.com/sanic-org/sanic/pull/2505) Replace Unsupported Python Version Number from the Contributing Doc +- [#2530](https://github.com/sanic-org/sanic/pull/2530) Do not include tests folder in installed package resolver + +### Improved Documentation + +- [#2502](https://github.com/sanic-org/sanic/pull/2502) Fix a few typos +- [#2517](https://github.com/sanic-org/sanic/pull/2517) [#2536](https://github.com/sanic-org/sanic/pull/2536) Add some type hints + +## Version 22.6.2 + +### Bugfixes + +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI + +## Version 22.6.1 + +### Bugfixes + +- [#2477](https://github.com/sanic-org/sanic/pull/2477) Sanic static directory fails when folder name ends with ".." + +## Version 22.6.0 + +### Features + +- [#2378](https://github.com/sanic-org/sanic/pull/2378) Introduce HTTP/3 and autogeneration of TLS certificates in `DEBUG` mode + - 👶 _EARLY RELEASE FEATURE_: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented. + - 📦 _EXTRA REQUIREMENT_: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a [HTTP/3 capable client](https://curl.se/docs/http3.html). + - 📦 _EXTRA REQUIREMENT_: In order to use TLS autogeneration, you must install either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). +- [#2416](https://github.com/sanic-org/sanic/pull/2416) Add message to `task.cancel` +- [#2420](https://github.com/sanic-org/sanic/pull/2420) Add exception aliases for more consistent naming with standard HTTP response types (`BadRequest`, `MethodNotAllowed`, `RangeNotSatisfiable`) +- [#2432](https://github.com/sanic-org/sanic/pull/2432) Expose ASGI `scope` as a property on the `Request` object +- [#2438](https://github.com/sanic-org/sanic/pull/2438) Easier access to websocket class for annotation: `from sanic import Websocket` +- [#2439](https://github.com/sanic-org/sanic/pull/2439) New API for reading form values with options: `Request.get_form` +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom `loads` function +- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) Improved API to support setting cache control headers +- [#2453](https://github.com/sanic-org/sanic/pull/2453) Move verbosity filtering to logger +- [#2475](https://github.com/sanic-org/sanic/pull/2475) Expose getter for current request using `Request.get_current()` + +### Bugfixes + +- [#2448](https://github.com/sanic-org/sanic/pull/2448) Fix to allow running with `pythonw.exe` or places where there is no `sys.stdout` +- [#2451](https://github.com/sanic-org/sanic/pull/2451) Trigger `http.lifecycle.request` signal in ASGI mode +- [#2455](https://github.com/sanic-org/sanic/pull/2455) Resolve typing of stacked route definitions +- [#2463](https://github.com/sanic-org/sanic/pull/2463) Properly catch websocket CancelledError in websocket handler in Python 3.7 + +### Deprecations and Removals + +- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 deprecations and changes + 1. Optional application registry + 2. Execution of custom handlers after some part of response was sent + 3. Configuring fallback handlers on the `ErrorHandler` + 4. Custom `LOGO` setting + 5. `sanic.response.stream` + 6. `AsyncioServer.init` + +### Developer infrastructure + +- [#2449](https://github.com/sanic-org/sanic/pull/2449) Clean up `black` and `isort` config +- [#2479](https://github.com/sanic-org/sanic/pull/2479) Fix some flappy tests + +### Improved Documentation + +- [#2461](https://github.com/sanic-org/sanic/pull/2461) Update example to match current application naming standards +- [#2466](https://github.com/sanic-org/sanic/pull/2466) Better type annotation for `Extend` +- [#2485](https://github.com/sanic-org/sanic/pull/2485) Improved help messages in CLI + +## Version 22.3.0 + +### Features + +- [#2347](https://github.com/sanic-org/sanic/pull/2347) API for multi-application server + - 🚨 _BREAKING CHANGE_: The old `sanic.worker.GunicornWorker` has been **removed**. To run Sanic with `gunicorn`, you should use it thru `uvicorn` [as described in their docs](https://www.uvicorn.org/#running-with-gunicorn). + - 🧁 _SIDE EFFECT_: Named background tasks are now supported, even in Python 3.7 +- [#2357](https://github.com/sanic-org/sanic/pull/2357) Parse `Authorization` header as `Request.credentials` +- [#2361](https://github.com/sanic-org/sanic/pull/2361) Add config option to skip `Touchup` step in application startup +- [#2372](https://github.com/sanic-org/sanic/pull/2372) Updates to CLI help messaging +- [#2382](https://github.com/sanic-org/sanic/pull/2382) Downgrade warnings to backwater debug messages +- [#2396](https://github.com/sanic-org/sanic/pull/2396) Allow for `multidict` v0.6 +- [#2401](https://github.com/sanic-org/sanic/pull/2401) Upgrade CLI catching for alternative application run types +- [#2402](https://github.com/sanic-org/sanic/pull/2402) Conditionally inject CLI arguments into factory +- [#2413](https://github.com/sanic-org/sanic/pull/2413) Add new start and stop event listeners to reloader process +- [#2414](https://github.com/sanic-org/sanic/pull/2414) Remove loop as required listener arg +- [#2415](https://github.com/sanic-org/sanic/pull/2415) Better exception for bad URL parsing +- [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) Add a new extention parameter type: ``, ``, ``, ``, ``, `` + - 👶 _BETA FEATURE_: This feature will not work with `path` type matching, and is being released as a beta feature only. +- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) Change `register_pattern` to accept a `str` or `Pattern` +- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) Default matching on non-empty strings only, and new `strorempty` pattern type + - 🚨 _BREAKING CHANGE_: Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now **only** match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. + +### Bugfixes + +- [#2373](https://github.com/sanic-org/sanic/pull/2373) Remove `error_logger` on websockets +- [#2381](https://github.com/sanic-org/sanic/pull/2381) Fix newly assigned `None` in task registry +- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) Add type casting to regex route matching +- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) Add requirements check on regex routes (this resolves, for example, multiple static directories with differing `host` values) + +### Deprecations and Removals + +- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 Deprecations and changes + 1. `debug=True` and `--debug` do _NOT_ automatically run `auto_reload` + 2. Default error render is with plain text (browsers still get HTML by default because `auto` looks at headers) + 3. `config` is required for `ErrorHandler.finalize` + 4. `ErrorHandler.lookup` requires two positional args + 5. Unused websocket protocol args removed +- [#2344](https://github.com/sanic-org/sanic/pull/2344) Deprecate loading of lowercase environment variables + +### Developer infrastructure + +- [#2363](https://github.com/sanic-org/sanic/pull/2363) Revert code coverage back to Codecov +- [#2405](https://github.com/sanic-org/sanic/pull/2405) Upgrade tests for `sanic-routing` changes +- [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) Allow for httpx v0.22 + +### Improved Documentation + +- [#2350](https://github.com/sanic-org/sanic/pull/2350) Fix link in README for ASGI +- [#2398](https://github.com/sanic-org/sanic/pull/2398) Document middleware on_request and on_response +- [#2409](https://github.com/sanic-org/sanic/pull/2409) Add missing documentation for `Request.respond` + +### Miscellaneous + +- [#2376](https://github.com/sanic-org/sanic/pull/2376) Fix typing for `ListenerMixin.listener` +- [#2383](https://github.com/sanic-org/sanic/pull/2383) Clear deprecation warning in `asyncio.wait` +- [#2387](https://github.com/sanic-org/sanic/pull/2387) Cleanup `__slots__` implementations +- [#2390](https://github.com/sanic-org/sanic/pull/2390) Clear deprecation warning in `asyncio.get_event_loop` + +## Version 21.12.1 + +- [#2349](https://github.com/sanic-org/sanic/pull/2349) Only display MOTD on startup +- [#2354](https://github.com/sanic-org/sanic/pull/2354) Ignore name argument in Python 3.7 +- [#2355](https://github.com/sanic-org/sanic/pull/2355) Add config.update support for all config values + +## Version 21.12.0 + +### Features + +- [#2260](https://github.com/sanic-org/sanic/pull/2260) Allow early Blueprint registrations to still apply later added objects +- [#2262](https://github.com/sanic-org/sanic/pull/2262) Noisy exceptions - force logging of all exceptions +- [#2264](https://github.com/sanic-org/sanic/pull/2264) Optional `uvloop` by configuration +- [#2270](https://github.com/sanic-org/sanic/pull/2270) Vhost support using multiple TLS certificates +- [#2277](https://github.com/sanic-org/sanic/pull/2277) Change signal routing for increased consistency + - _BREAKING CHANGE_: If you were manually routing signals there is a breaking change. The signal router's `get` is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using `app.dispatch` or `bp.dispatch`, there is no change. +- [#2290](https://github.com/sanic-org/sanic/pull/2290) Add contextual exceptions +- [#2291](https://github.com/sanic-org/sanic/pull/2291) Increase join concat performance +- [#2295](https://github.com/sanic-org/sanic/pull/2295), [#2316](https://github.com/sanic-org/sanic/pull/2316), [#2331](https://github.com/sanic-org/sanic/pull/2331) Restructure of CLI and application state with new displays and more command parity with `app.run` +- [#2302](https://github.com/sanic-org/sanic/pull/2302) Add route context at definition time +- [#2304](https://github.com/sanic-org/sanic/pull/2304) Named tasks and new API for managing background tasks +- [#2307](https://github.com/sanic-org/sanic/pull/2307) On app auto-reload, provide insight of changed files +- [#2308](https://github.com/sanic-org/sanic/pull/2308) Auto extend application with [Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) if it is installed, and provide first class support for accessing the extensions +- [#2309](https://github.com/sanic-org/sanic/pull/2309) Builtin signals changed to `Enum` +- [#2313](https://github.com/sanic-org/sanic/pull/2313) Support additional config implementation use case +- [#2321](https://github.com/sanic-org/sanic/pull/2321) Refactor environment variable hydration logic +- [#2327](https://github.com/sanic-org/sanic/pull/2327) Prevent sending multiple or mixed responses on a single request +- [#2330](https://github.com/sanic-org/sanic/pull/2330) Custom type casting on environment variables +- [#2332](https://github.com/sanic-org/sanic/pull/2332) Make all deprecation notices consistent +- [#2335](https://github.com/sanic-org/sanic/pull/2335) Allow underscore to start instance names + +### Bugfixes + +- [#2273](https://github.com/sanic-org/sanic/pull/2273) Replace assignation by typing for `websocket_handshake` +- [#2285](https://github.com/sanic-org/sanic/pull/2285) Fix IPv6 display in startup logs +- [#2299](https://github.com/sanic-org/sanic/pull/2299) Dispatch `http.lifecyle.response` from exception handler + +### Deprecations and Removals + +- [#2306](https://github.com/sanic-org/sanic/pull/2306) Removal of deprecated items + - `Sanic` and `Blueprint` may no longer have arbitrary properties attached to them + - `Sanic` and `Blueprint` forced to have compliant names + - alphanumeric + `_` + `-` + - must start with letter or `_` + - `load_env` keyword argument of `Sanic` + - `sanic.exceptions.abort` + - `sanic.views.CompositionView` + - `sanic.response.StreamingHTTPResponse` + - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming +- [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting + +### Developer infrastructure + +- [#2251](https://github.com/sanic-org/sanic/pull/2251) Change dev install command +- [#2286](https://github.com/sanic-org/sanic/pull/2286) Change codeclimate complexity threshold from 5 to 10 +- [#2287](https://github.com/sanic-org/sanic/pull/2287) Update host test function names so they are not overwritten +- [#2292](https://github.com/sanic-org/sanic/pull/2292) Fail CI on error +- [#2311](https://github.com/sanic-org/sanic/pull/2311), [#2324](https://github.com/sanic-org/sanic/pull/2324) Do not run tests for draft PRs +- [#2336](https://github.com/sanic-org/sanic/pull/2336) Remove paths from coverage checks +- [#2338](https://github.com/sanic-org/sanic/pull/2338) Cleanup ports on tests + +### Improved Documentation + +- [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2329), [#2333](https://github.com/sanic-org/sanic/pull/2333) Cleanup typos and fix language + +### Miscellaneous + +- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) Add Python 3.10 support +- [#2279](https://github.com/sanic-org/sanic/pull/2279), [#2317](https://github.com/sanic-org/sanic/pull/2317), [#2322](https://github.com/sanic-org/sanic/pull/2322) Add/correct missing type annotations +- [#2305](https://github.com/sanic-org/sanic/pull/2305) Fix examples to use modern implementations + +## Version 21.9.3 + +_Rerelease of v21.9.2 with some cleanup_ + +## Version 21.9.2 + +- [#2268](https://github.com/sanic-org/sanic/pull/2268) Make HTTP connections start in IDLE stage, avoiding delays and error messages +- [#2310](https://github.com/sanic-org/sanic/pull/2310) More consistent config setting with post-FALLBACK_ERROR_FORMAT apply + +## Version 21.9.1 + +- [#2259](https://github.com/sanic-org/sanic/pull/2259) Allow non-conforming ErrorHandlers + +## Version 21.9.0 + +### Features + +- [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) Complete overhaul of I/O to websockets +- [#2160](https://github.com/sanic-org/sanic/pull/2160) Add new 17 signals into server and request lifecycles +- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto` fallback formatting upon exception +- [#2184](https://github.com/sanic-org/sanic/pull/2184) Introduce implementation for copying a Blueprint +- [#2200](https://github.com/sanic-org/sanic/pull/2200) Accept header parsing +- [#2207](https://github.com/sanic-org/sanic/pull/2207) Log remote address if available +- [#2209](https://github.com/sanic-org/sanic/pull/2209) Add convenience methods to BP groups +- [#2216](https://github.com/sanic-org/sanic/pull/2216) Add default messages to SanicExceptions +- [#2225](https://github.com/sanic-org/sanic/pull/2225) Type annotation convenience for annotated handlers with path parameters +- [#2236](https://github.com/sanic-org/sanic/pull/2236) Allow Falsey (but not-None) responses from route handlers +- [#2238](https://github.com/sanic-org/sanic/pull/2238) Add `exception` decorator to Blueprint Groups +- [#2244](https://github.com/sanic-org/sanic/pull/2244) Explicit static directive for serving file or dir (ex: `static(..., resource_type="file")`) +- [#2245](https://github.com/sanic-org/sanic/pull/2245) Close HTTP loop when connection task cancelled + +### Bugfixes + +- [#2188](https://github.com/sanic-org/sanic/pull/2188) Fix the handling of the end of a chunked request +- [#2195](https://github.com/sanic-org/sanic/pull/2195) Resolve unexpected error handling on static requests +- [#2208](https://github.com/sanic-org/sanic/pull/2208) Make blueprint-based exceptions attach and trigger in a more intuitive manner +- [#2211](https://github.com/sanic-org/sanic/pull/2211) Fixed for handling exceptions of asgi app call +- [#2213](https://github.com/sanic-org/sanic/pull/2213) Fix bug where ws exceptions not being logged +- [#2231](https://github.com/sanic-org/sanic/pull/2231) Cleaner closing of tasks by using `abort()` in strategic places to avoid dangling sockets +- [#2247](https://github.com/sanic-org/sanic/pull/2247) Fix logging of auto-reload status in debug mode +- [#2246](https://github.com/sanic-org/sanic/pull/2246) Account for BP with exception handler but no routes + +### Developer infrastructure + +- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP unit tests with raw client +- [#2199](https://github.com/sanic-org/sanic/pull/2199) Switch to codeclimate +- [#2214](https://github.com/sanic-org/sanic/pull/2214) Try Reopening Windows Tests +- [#2229](https://github.com/sanic-org/sanic/pull/2229) Refactor `HttpProtocol` into a base class +- [#2230](https://github.com/sanic-org/sanic/pull/2230) Refactor `server.py` into multi-file module + +### Miscellaneous + +- [#2173](https://github.com/sanic-org/sanic/pull/2173) Remove Duplicated Dependencies and PEP 517 Support +- [#2193](https://github.com/sanic-org/sanic/pull/2193), [#2196](https://github.com/sanic-org/sanic/pull/2196), [#2217](https://github.com/sanic-org/sanic/pull/2217) Type annotation changes + +## Version 21.6.1 + +**Bugfixes** + +- [#2178](https://github.com/sanic-org/sanic/pull/2178) Update + sanic-routing to allow for better splitting of complex URI + templates +- [#2183](https://github.com/sanic-org/sanic/pull/2183) Proper + handling of chunked request bodies to resolve phantom 503 in logs +- [#2181](https://github.com/sanic-org/sanic/pull/2181) Resolve + regression in exception logging +- [#2201](https://github.com/sanic-org/sanic/pull/2201) Cleanup + request info in pipelined requests + +## Version 21.6.0 + +**Features** + +- [#2094](https://github.com/sanic-org/sanic/pull/2094) Add + `response.eof()` method for closing a stream in a handler + +- [#2097](https://github.com/sanic-org/sanic/pull/2097) Allow + case-insensitive HTTP Upgrade header + +- [#2104](https://github.com/sanic-org/sanic/pull/2104) Explicit + usage of CIMultiDict getters + +- [#2109](https://github.com/sanic-org/sanic/pull/2109) Consistent + use of error loggers + +- [#2114](https://github.com/sanic-org/sanic/pull/2114) New + `client_ip` access of connection info instance + +- [#2119](https://github.com/sanic-org/sanic/pull/2119) Alternatate + classes on instantiation for `Config` and `Sanic.ctx` + +- [#2133](https://github.com/sanic-org/sanic/pull/2133) Implement + new version of AST router + + - Proper differentiation between `alpha` and `string` param + types + - Adds a `slug` param type, example: `` + - Deprecates `` in favor of `` + - Deprecates `` in favor of `` + - Adds a `route.uri` accessor + +- [#2136](https://github.com/sanic-org/sanic/pull/2136) CLI + improvements with new optional params + +- [#2137](https://github.com/sanic-org/sanic/pull/2137) Add + `version_prefix` to URL builders + +- [#2140](https://github.com/sanic-org/sanic/pull/2140) Event + autoregistration with `EVENT_AUTOREGISTER` + +- [#2146](https://github.com/sanic-org/sanic/pull/2146), + [#2147](https://github.com/sanic-org/sanic/pull/2147) Require + stricter names on `Sanic()` and `Blueprint()` + +- [#2150](https://github.com/sanic-org/sanic/pull/2150) Infinitely + reusable and nestable `Blueprint` and `BlueprintGroup` + +- [#2154](https://github.com/sanic-org/sanic/pull/2154) Upgrade + `websockets` dependency to min version + +- [#2155](https://github.com/sanic-org/sanic/pull/2155) Allow for + maximum header sizes to be increased: `REQUEST_MAX_HEADER_SIZE` + +- [#2157](https://github.com/sanic-org/sanic/pull/2157) Allow app + factory pattern in CLI + +- [#2165](https://github.com/sanic-org/sanic/pull/2165) Change HTTP + methods to enums + +- [#2167](https://github.com/sanic-org/sanic/pull/2167) Allow + auto-reloading on additional directories + +- [#2168](https://github.com/sanic-org/sanic/pull/2168) Add simple + HTTP server to CLI + +- [#2170](https://github.com/sanic-org/sanic/pull/2170) Additional + methods for attaching `HTTPMethodView` + +**Bugfixes** + +- [#2091](https://github.com/sanic-org/sanic/pull/2091) Fix + `UserWarning` in ASGI mode for missing `__slots__` +- [#2099](https://github.com/sanic-org/sanic/pull/2099) Fix static + request handler logging exception on 404 +- [#2110](https://github.com/sanic-org/sanic/pull/2110) Fix + request.args.pop removes parameters inconsistently +- [#2107](https://github.com/sanic-org/sanic/pull/2107) Fix type + hinting for load_env +- [#2127](https://github.com/sanic-org/sanic/pull/2127) Make sure + ASGI ws subprotocols is a list +- [#2128](https://github.com/sanic-org/sanic/pull/2128) Fix issue + where Blueprint exception handlers do not consistently route to + proper handler + +**Deprecations and Removals** + +- [#2156](https://github.com/sanic-org/sanic/pull/2156) Remove + config value `REQUEST_BUFFER_QUEUE_SIZE` +- [#2170](https://github.com/sanic-org/sanic/pull/2170) + `CompositionView` deprecated and marked for removal in 21.12 +- [#2172](https://github.com/sanic-org/sanic/pull/2170) Deprecate + StreamingHTTPResponse + +**Developer infrastructure** + +- [#2149](https://github.com/sanic-org/sanic/pull/2149) Remove + Travis CI in favor of GitHub Actions + +**Improved Documentation** + +- [#2164](https://github.com/sanic-org/sanic/pull/2164) Fix typo in + documentation +- [#2100](https://github.com/sanic-org/sanic/pull/2100) Remove + documentation for non-existent arguments + +## Version 21.3.2 + +**Bugfixes** + +- [#2081](https://github.com/sanic-org/sanic/pull/2081) Disable + response timeout on websocket connections +- [#2085](https://github.com/sanic-org/sanic/pull/2085) Make sure + that blueprints with no slash is maintained when applied + +## Version 21.3.1 + +**Bugfixes** + +- [#2076](https://github.com/sanic-org/sanic/pull/2076) Static files + inside subfolders are not accessible (404) + +## Version 21.3.0 + +Release +Notes + +**Features** + +- [#1876](https://github.com/sanic-org/sanic/pull/1876) Unified + streaming server +- [#2005](https://github.com/sanic-org/sanic/pull/2005) New + `Request.id` property +- [#2008](https://github.com/sanic-org/sanic/pull/2008) Allow + Pathlib Path objects to be passed to `app.static()` helper +- [#2010](https://github.com/sanic-org/sanic/pull/2010), + [#2031](https://github.com/sanic-org/sanic/pull/2031) New + startup-optimized router +- [#2018](https://github.com/sanic-org/sanic/pull/2018) + [#2064](https://github.com/sanic-org/sanic/pull/2064) Listeners + for main server process +- [#2032](https://github.com/sanic-org/sanic/pull/2032) Add raw + header info to request object +- [#2042](https://github.com/sanic-org/sanic/pull/2042) + [#2060](https://github.com/sanic-org/sanic/pull/2060) + [#2061](https://github.com/sanic-org/sanic/pull/2061) Introduce + Signals API +- [#2043](https://github.com/sanic-org/sanic/pull/2043) Add + `__str__` and `__repr__` to Sanic and Blueprint +- [#2047](https://github.com/sanic-org/sanic/pull/2047) Enable + versioning and strict slash on BlueprintGroup +- [#2053](https://github.com/sanic-org/sanic/pull/2053) Make + `get_app` name argument optional +- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON encoder + change via app +- [#2063](https://github.com/sanic-org/sanic/pull/2063) App and + connection level context objects + +**Bugfixes** + +- Resolve [#1420](https://github.com/sanic-org/sanic/pull/1420) + `url_for` where `strict_slashes` are on for a path ending in `/` +- Resolve [#1525](https://github.com/sanic-org/sanic/pull/1525) + Routing is incorrect with some special characters +- Resolve [#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI + headers in body +- Resolve [#1722](https://github.com/sanic-org/sanic/pull/1722) + Using curl in chunk mode +- Resolve [#1730](https://github.com/sanic-org/sanic/pull/1730) + Extra content in ASGI streaming response +- Resolve [#1749](https://github.com/sanic-org/sanic/pull/1749) + Restore broken middleware edge cases +- Resolve [#1785](https://github.com/sanic-org/sanic/pull/1785) + [#1804](https://github.com/sanic-org/sanic/pull/1804) Synchronous + error handlers +- Resolve [#1790](https://github.com/sanic-org/sanic/pull/1790) + Protocol errors did not support async error handlers #1790 +- Resolve [#1824](https://github.com/sanic-org/sanic/pull/1824) + Timeout on specific methods +- Resolve [#1875](https://github.com/sanic-org/sanic/pull/1875) + Response timeout error from all routes after returning several + timeouts from a specific route +- Resolve [#1988](https://github.com/sanic-org/sanic/pull/1988) + Handling of safe methods with body +- [#2001](https://github.com/sanic-org/sanic/pull/2001) Raise + ValueError when cookie max-age is not an integer + +**Deprecations and Removals** + +- [#2007](https://github.com/sanic-org/sanic/pull/2007) \* Config + using `from_envvar` \* Config using `from_pyfile` \* Config using + `from_object` +- [#2009](https://github.com/sanic-org/sanic/pull/2009) Remove Sanic + test client to its own package +- [#2036](https://github.com/sanic-org/sanic/pull/2036), + [#2037](https://github.com/sanic-org/sanic/pull/2037) Drop Python + 3.6 support +- `Request.endpoint` deprecated in favor of `Request.name` +- handler type name prefixes removed (static, websocket, etc) + +**Developer infrastructure** + +- [#1995](https://github.com/sanic-org/sanic/pull/1995) Create + FUNDING.yml +- [#2013](https://github.com/sanic-org/sanic/pull/2013) Add codeql + to CI pipeline +- [#2038](https://github.com/sanic-org/sanic/pull/2038) Codecov + configuration updates +- [#2049](https://github.com/sanic-org/sanic/pull/2049) Updated + setup.py to use `find_packages` + +**Improved Documentation** + +- [#1218](https://github.com/sanic-org/sanic/pull/1218) + Documentation for sanic.log.\* is missing +- [#1608](https://github.com/sanic-org/sanic/pull/1608) Add + documentation on calver and LTS +- [#1731](https://github.com/sanic-org/sanic/pull/1731) Support + mounting application elsewhere than at root path +- [#2006](https://github.com/sanic-org/sanic/pull/2006) Upgraded + type annotations and improved docstrings and API documentation +- [#2052](https://github.com/sanic-org/sanic/pull/2052) Fix some + examples and docs + +**Miscellaneous** + +- `Request.route` property +- Better websocket subprotocols support +- Resolve bug with middleware in Blueprint Group when passed + callable +- Moves common logic between Blueprint and Sanic into mixins +- Route naming changed to be more consistent + - request endpoint is the route name + - route names are fully namespaced +- Some new convenience decorators: + - `@app.main_process_start` + - `@app.main_process_stop` + - `@app.before_server_start` + - `@app.after_server_start` + - `@app.before_server_stop` + - `@app.after_server_stop` + - `@app.on_request` + - `@app.on_response` +- Fixes `Allow` header that did not include `HEAD` +- Using "name" keyword in `url_for` for a "static" route where + name does not exist +- Cannot have multiple `app.static()` without using the named param +- Using "filename" keyword in `url_for` on a file route +- `unquote` in route def (not automatic) +- `routes_all` is tuples +- Handler arguments are kwarg only +- `request.match_info` is now a cached (and not computed) property +- Unknown static file mimetype is sent as `application/octet-stream` +- `_host` keyword in `url_for` +- Add charset default to `utf-8` for text and js content types if + not specified +- Version for a route can be str, float, or int +- Route has ctx property +- App has `routes_static`, `routes_dynamic`, `routes_regex` +- [#2044](https://github.com/sanic-org/sanic/pull/2044) Code cleanup + and refactoring +- [#2072](https://github.com/sanic-org/sanic/pull/2072) Remove + `BaseSanic` metaclass +- [#2074](https://github.com/sanic-org/sanic/pull/2074) Performance + adjustments in `handle_request_` + +## Version 20.12.3 + +**Bugfixes** + +- [#2021](https://github.com/sanic-org/sanic/pull/2021) Remove + prefix from websocket handler name + +## Version 20.12.2 + +**Dependencies** + +- [#2026](https://github.com/sanic-org/sanic/pull/2026) Fix uvloop + to 0.14 because 0.15 drops Python 3.6 support +- [#2029](https://github.com/sanic-org/sanic/pull/2029) Remove old + chardet requirement, add in hard multidict requirement + +## Version 19.12.5 + +**Dependencies** + +- [#2025](https://github.com/sanic-org/sanic/pull/2025) Fix uvloop + to 0.14 because 0.15 drops Python 3.6 support +- [#2027](https://github.com/sanic-org/sanic/pull/2027) Remove old + chardet requirement, add in hard multidict requirement + +## Version 20.12.0 + +**Features** + +- [#1993](https://github.com/sanic-org/sanic/pull/1993) Add disable + app registry +- [#1945](https://github.com/sanic-org/sanic/pull/1945) Static route + more verbose if file not found +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + routes registration on a blueprint +- [#1961](https://github.com/sanic-org/sanic/pull/1961) Add Python + 3.9 support +- [#1962](https://github.com/sanic-org/sanic/pull/1962) Sanic CLI + upgrade +- [#1967](https://github.com/sanic-org/sanic/pull/1967) Update + aiofile version requirements +- [#1969](https://github.com/sanic-org/sanic/pull/1969) Update + multidict version requirements +- [#1970](https://github.com/sanic-org/sanic/pull/1970) Add py.typed + file +- [#1972](https://github.com/sanic-org/sanic/pull/1972) Speed + optimization in request handler +- [#1979](https://github.com/sanic-org/sanic/pull/1979) Add app + registry and Sanic class level app retrieval + +**Bugfixes** + +- [#1965](https://github.com/sanic-org/sanic/pull/1965) Fix Chunked + Transport-Encoding in ASGI streaming response + +**Deprecations and Removals** + +- [#1981](https://github.com/sanic-org/sanic/pull/1981) Cleanup and + remove deprecated code + +**Developer infrastructure** + +- [#1956](https://github.com/sanic-org/sanic/pull/1956) Fix load + module test +- [#1973](https://github.com/sanic-org/sanic/pull/1973) Transition + Travis from .org to .com +- [#1986](https://github.com/sanic-org/sanic/pull/1986) Update tox + requirements + +**Improved Documentation** + +- [#1951](https://github.com/sanic-org/sanic/pull/1951) + Documentation improvements +- [#1983](https://github.com/sanic-org/sanic/pull/1983) Remove + duplicate contents in testing.rst +- [#1984](https://github.com/sanic-org/sanic/pull/1984) Fix typo in + routing.rst + +## Version 20.9.1 + +**Bugfixes** + +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + route registration on blueprints +- [#1957](https://github.com/sanic-org/sanic/pull/1957) Removes + duplicate headers in ASGI streaming body + +## Version 19.12.3 + +**Bugfixes** + +- [#1959](https://github.com/sanic-org/sanic/pull/1959) Removes + duplicate headers in ASGI streaming body + +## Version 20.9.0 + +**Features** + +- [#1887](https://github.com/sanic-org/sanic/pull/1887) Pass + subprotocols in websockets (both sanic server and ASGI) +- [#1894](https://github.com/sanic-org/sanic/pull/1894) + Automatically set `test_mode` flag on app instance +- [#1903](https://github.com/sanic-org/sanic/pull/1903) Add new + unified method for updating app values +- [#1906](https://github.com/sanic-org/sanic/pull/1906), + [#1909](https://github.com/sanic-org/sanic/pull/1909) Adds + WEBSOCKET_PING_TIMEOUT and WEBSOCKET_PING_INTERVAL configuration + values +- [#1935](https://github.com/sanic-org/sanic/pull/1935) httpx + version dependency updated, it is slated for removal as a + dependency in v20.12 +- [#1937](https://github.com/sanic-org/sanic/pull/1937) Added auto, + text, and json fallback error handlers (in v21.3, the default will + change form html to auto) + +**Bugfixes** + +- [#1897](https://github.com/sanic-org/sanic/pull/1897) Resolves + exception from unread bytes in stream + +**Deprecations and Removals** + +- [#1903](https://github.com/sanic-org/sanic/pull/1903) + config.from_envar, config.from_pyfile, and config.from_object are + deprecated and set to be removed in v21.3 + +**Developer infrastructure** + +- [#1890](https://github.com/sanic-org/sanic/pull/1890), + [#1891](https://github.com/sanic-org/sanic/pull/1891) Update isort + calls to be compatible with new API +- [#1893](https://github.com/sanic-org/sanic/pull/1893) Remove + version section from setup.cfg +- [#1924](https://github.com/sanic-org/sanic/pull/1924) Adding + \--strict-markers for pytest + +**Improved Documentation** + +- [#1922](https://github.com/sanic-org/sanic/pull/1922) Add explicit + ASGI compliance to the README + +## Version 20.6.3 + +**Bugfixes** + +- [#1884](https://github.com/sanic-org/sanic/pull/1884) Revert + change to multiprocessing mode + +## Version 20.6.2 + +**Features** + +- [#1641](https://github.com/sanic-org/sanic/pull/1641) Socket + binding implemented properly for IPv6 and UNIX sockets + +## Version 20.6.1 + +**Features** + +- [#1760](https://github.com/sanic-org/sanic/pull/1760) Add version + parameter to websocket routes +- [#1866](https://github.com/sanic-org/sanic/pull/1866) Add `sanic` + as an entry point command +- [#1880](https://github.com/sanic-org/sanic/pull/1880) Add handler + names for websockets for url_for usage + +**Bugfixes** + +- [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for + host parameter issue with lists +- [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static + _handler pickling error +- [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader + on OSX py38 and Windows +- [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse + named_response_middlware execution order, to match normal response + middleware execution order +- [#1853](https://github.com/sanic-org/sanic/pull/1853) Fix pickle + error when attempting to pickle an application which contains + websocket routes + +**Deprecations and Removals** + +- [#1739](https://github.com/sanic-org/sanic/pull/1739) Deprecate + body_bytes to merge into body + +**Developer infrastructure** + +- [#1852](https://github.com/sanic-org/sanic/pull/1852) Fix naming + of CI test env on Python nightlies +- [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust + websockets version to setup.py +- [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap + run()'s "protocol" type annotation in Optional[] + +**Improved Documentation** + +- [#1846](https://github.com/sanic-org/sanic/pull/1846) Update docs + to clarify response middleware execution order +- [#1865](https://github.com/sanic-org/sanic/pull/1865) Fixing rst + format issue that was hiding documentation + +## Version 20.6.0 + +_Released, but unintentionally omitting PR #1880, so was replaced by +20.6.1_ + +## Version 20.3.0 + +**Features** + +- [#1762](https://github.com/sanic-org/sanic/pull/1762) Add + `srv.start_serving()` and `srv.serve_forever()` to `AsyncioServer` +- [#1767](https://github.com/sanic-org/sanic/pull/1767) Make Sanic + usable on `hypercorn -k trio myweb.app` +- [#1768](https://github.com/sanic-org/sanic/pull/1768) No + tracebacks on normal errors and prettier error pages +- [#1769](https://github.com/sanic-org/sanic/pull/1769) Code cleanup + in file responses +- [#1793](https://github.com/sanic-org/sanic/pull/1793) and + [#1819](https://github.com/sanic-org/sanic/pull/1819) Upgrade + `str.format()` to f-strings +- [#1798](https://github.com/sanic-org/sanic/pull/1798) Allow + multiple workers on MacOS with Python 3.8 +- [#1820](https://github.com/sanic-org/sanic/pull/1820) Do not set + content-type and content-length headers in exceptions + +**Bugfixes** + +- [#1748](https://github.com/sanic-org/sanic/pull/1748) Remove loop + argument in `asyncio.Event` in Python 3.8 +- [#1764](https://github.com/sanic-org/sanic/pull/1764) Allow route + decorators to stack up again +- [#1789](https://github.com/sanic-org/sanic/pull/1789) Fix tests + using hosts yielding incorrect `url_for` +- [#1808](https://github.com/sanic-org/sanic/pull/1808) Fix Ctrl+C + and tests on Windows + +**Deprecations and Removals** + +- [#1800](https://github.com/sanic-org/sanic/pull/1800) Begin + deprecation in way of first-class streaming, removal of + `body_init`, `body_push`, and `body_finish` +- [#1801](https://github.com/sanic-org/sanic/pull/1801) Complete + deprecation from + [#1666](https://github.com/sanic-org/sanic/pull/1666) of + dictionary context on `request` objects. +- [#1807](https://github.com/sanic-org/sanic/pull/1807) Remove + server config args that can be read directly from app +- [#1818](https://github.com/sanic-org/sanic/pull/1818) Complete + deprecation of `app.remove_route` and `request.raw_args` + +**Dependencies** + +- [#1794](https://github.com/sanic-org/sanic/pull/1794) Bump `httpx` + to 0.11.1 +- [#1806](https://github.com/sanic-org/sanic/pull/1806) Import + `ASGIDispatch` from top-level `httpx` (from third-party + deprecation) + +**Developer infrastructure** + +- [#1833](https://github.com/sanic-org/sanic/pull/1833) Resolve + broken documentation builds + +**Improved Documentation** + +- [#1755](https://github.com/sanic-org/sanic/pull/1755) Usage of + `response.empty()` +- [#1778](https://github.com/sanic-org/sanic/pull/1778) Update + README +- [#1783](https://github.com/sanic-org/sanic/pull/1783) Fix typo +- [#1784](https://github.com/sanic-org/sanic/pull/1784) Corrected + changelog for docs move of MD to RST + ([#1691](https://github.com/sanic-org/sanic/pull/1691)) +- [#1803](https://github.com/sanic-org/sanic/pull/1803) Update + config docs to match DEFAULT_CONFIG +- [#1814](https://github.com/sanic-org/sanic/pull/1814) Update + getting_started.rst +- [#1821](https://github.com/sanic-org/sanic/pull/1821) Update to + deployment +- [#1822](https://github.com/sanic-org/sanic/pull/1822) Update docs + with changes done in 20.3 +- [#1834](https://github.com/sanic-org/sanic/pull/1834) Order of + listeners + +## Version 19.12.0 + +**Bugfixes** + +- Fix blueprint middleware application + + Currently, any blueprint middleware registered, irrespective of + which blueprint was used to do so, was being applied to all of the + routes created by the `@app` and `@blueprint` alike. + + As part of this change, the blueprint based middleware application + is enforced based on where they are registered. + + - If you register a middleware via `@blueprint.middleware` then it + will apply only to the routes defined by the blueprint. + - If you register a middleware via `@blueprint_group.middleware` + then it will apply to all blueprint based routes that are part + of the group. + - If you define a middleware via `@app.middleware` then it will be + applied on all available routes + ([#37](https://github.com/sanic-org/sanic/issues/37)) + +- Fix [url_for]{.title-ref} behavior with missing SERVER_NAME + + If the [SERVER_NAME]{.title-ref} was missing in the + [app.config]{.title-ref} entity, the [url_for]{.title-ref} on the + [request]{.title-ref} and [app]{.title-ref} were failing due to an + [AttributeError]{.title-ref}. This fix makes the availability of + [SERVER_NAME]{.title-ref} on our [app.config]{.title-ref} an + optional behavior. + ([#1707](https://github.com/sanic-org/sanic/issues/1707)) + +**Improved Documentation** + +- Move docs from MD to RST + + Moved all docs from markdown to restructured text like the rest of + the docs to unify the scheme and make it easier in the future to + update documentation. + ([#1691](https://github.com/sanic-org/sanic/issues/1691)) + +- Fix documentation for [get]{.title-ref} and [getlist]{.title-ref} of + the [request.args]{.title-ref} + + Add additional example for showing the usage of + [getlist]{.title-ref} and fix the documentation string for + [request.args]{.title-ref} behavior + ([#1704](https://github.com/sanic-org/sanic/issues/1704)) + +## Version 19.6.3 + +**Features** + +- Enable Towncrier Support + + As part of this feature, [towncrier]{.title-ref} is being introduced + as a mechanism to partially automate the process of generating and + managing change logs as part of each of pull requests. + ([#1631](https://github.com/sanic-org/sanic/issues/1631)) + +**Improved Documentation** + +- Documentation infrastructure changes + - Enable having a single common [CHANGELOG]{.title-ref} file for + both GitHub page and documentation + - Fix Sphinix deprecation warnings + - Fix documentation warnings due to invalid [rst]{.title-ref} + indentation + - Enable common contribution guidelines file across GitHub and + documentation via [CONTRIBUTING.rst]{.title-ref} + ([#1631](https://github.com/sanic-org/sanic/issues/1631)) + +## Version 19.6.2 + +**Features** + +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Remove + `aiohttp` dependency and create new `SanicTestClient` based upon + [requests-async](https://github.com/encode/requests-async) +- [#1475](https://github.com/sanic-org/sanic/pull/1475) Added ASGI + support (Beta) +- [#1436](https://github.com/sanic-org/sanic/pull/1436) Add + Configure support from object string + +**Bugfixes** + +- [#1587](https://github.com/sanic-org/sanic/pull/1587) Add missing + handle for Expect header. +- [#1560](https://github.com/sanic-org/sanic/pull/1560) Allow to + disable Transfer-Encoding: chunked. +- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix graceful + shutdown. +- [#1594](https://github.com/sanic-org/sanic/pull/1594) Strict + Slashes behavior fix + +**Deprecations and Removals** + +- [#1544](https://github.com/sanic-org/sanic/pull/1544) Drop + dependency on distutil +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Drop support + for Python 3.5 +- [#1568](https://github.com/sanic-org/sanic/pull/1568) Deprecate + route removal. + +.. warning:: Warning + +``` +Sanic will not support Python 3.5 from version 19.6 and forward. +However, version 18.12LTS will have its support period extended thru +December 2020, and therefore passing Python\'s official support version +3.5, which is set to expire in September 2020. +``` + +## Version 19.3 + +**Features** + +- [#1497](https://github.com/sanic-org/sanic/pull/1497) Add support + for zero-length and RFC 5987 encoded filename for + multipart/form-data requests. + +- [#1484](https://github.com/sanic-org/sanic/pull/1484) The type of + `expires` attribute of `sanic.cookies.Cookie` is now enforced to + be of type `datetime`. + +- [#1482](https://github.com/sanic-org/sanic/pull/1482) Add support + for the `stream` parameter of `sanic.Sanic.add_route()` available + to `sanic.Blueprint.add_route()`. + +- [#1481](https://github.com/sanic-org/sanic/pull/1481) Accept + negative values for route parameters with type `int` or `number`. + +- [#1476](https://github.com/sanic-org/sanic/pull/1476) Deprecated + the use of `sanic.request.Request.raw_args` - it has a fundamental + flaw in which is drops repeated query string parameters. Added + `sanic.request.Request.query_args` as a replacement for the + original use-case. + +- [#1472](https://github.com/sanic-org/sanic/pull/1472) Remove an + unwanted `None` check in Request class `repr` implementation. This + changes the default `repr` of a Request from `` to + `` + +- [#1470](https://github.com/sanic-org/sanic/pull/1470) Added 2 new + parameters to `sanic.app.Sanic.create_server`: + + - `return_asyncio_server` - whether to return an + asyncio.Server. + - `asyncio_server_kwargs` - kwargs to pass to + `loop.create_server` for the event loop that sanic is using. + + > + + This is a breaking change. + +- [#1499](https://github.com/sanic-org/sanic/pull/1499) Added a set + of test cases that test and benchmark route resolution. + +- [#1457](https://github.com/sanic-org/sanic/pull/1457) The type of + the `"max-age"` value in a `sanic.cookies.Cookie` is now enforced + to be an integer. Non-integer values are replaced with `0`. + +- [#1445](https://github.com/sanic-org/sanic/pull/1445) Added the + `endpoint` attribute to an incoming `request`, containing the name + of the handler function. + +- [#1423](https://github.com/sanic-org/sanic/pull/1423) Improved + request streaming. `request.stream` is now a bounded-size buffer + instead of an unbounded queue. Callers must now call + `await request.stream.read()` instead of + `await request.stream.get()` to read each portion of the body. + + This is a breaking change. + +**Bugfixes** + +- [#1502](https://github.com/sanic-org/sanic/pull/1502) Sanic was + prefetching `time.time()` and updating it once per second to avoid + excessive `time.time()` calls. The implementation was observed to + cause memory leaks in some cases. The benefit of the prefetch + appeared to negligible, so this has been removed. Fixes + [#1500](https://github.com/sanic-org/sanic/pull/1500) +- [#1501](https://github.com/sanic-org/sanic/pull/1501) Fix a bug in + the auto-reloader when the process was launched as a module i.e. + `python -m init0.mod1` where the sanic server is started in + `init0/mod1.py` with `debug` enabled and imports another module in + `init0`. +- [#1376](https://github.com/sanic-org/sanic/pull/1376) Allow sanic + test client to bind to a random port by specifying `port=None` + when constructing a `SanicTestClient` +- [#1399](https://github.com/sanic-org/sanic/pull/1399) Added the + ability to specify middleware on a blueprint group, so that all + routes produced from the blueprints in the group have the + middleware applied. +- [#1442](https://github.com/sanic-org/sanic/pull/1442) Allow the + the use the `SANIC_ACCESS_LOG` environment variable to + enable/disable the access log when not explicitly passed to + `app.run()`. This allows the access log to be disabled for example + when running via gunicorn. + +**Developer infrastructure** + +- [#1529](https://github.com/sanic-org/sanic/pull/1529) Update + project PyPI credentials +- [#1515](https://github.com/sanic-org/sanic/pull/1515) fix linter + issue causing travis build failures (fix #1514) +- [#1490](https://github.com/sanic-org/sanic/pull/1490) Fix python + version in doc build +- [#1478](https://github.com/sanic-org/sanic/pull/1478) Upgrade + setuptools version and use native docutils in doc build +- [#1464](https://github.com/sanic-org/sanic/pull/1464) Upgrade + pytest, and fix caplog unit tests + +**Improved Documentation** + +- [#1516](https://github.com/sanic-org/sanic/pull/1516) Fix typo at + the exception documentation +- [#1510](https://github.com/sanic-org/sanic/pull/1510) fix typo in + Asyncio example +- [#1486](https://github.com/sanic-org/sanic/pull/1486) + Documentation typo +- [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar + in README.md +- [#1489](https://github.com/sanic-org/sanic/pull/1489) Added + "databases" to the extensions list +- [#1483](https://github.com/sanic-org/sanic/pull/1483) Add + sanic-zipkin to extensions list +- [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link + to deleted repo, Sanic-OAuth, from the extensions list +- [#1460](https://github.com/sanic-org/sanic/pull/1460) 18.12 + changelog +- [#1449](https://github.com/sanic-org/sanic/pull/1449) Add example + of amending request object +- [#1446](https://github.com/sanic-org/sanic/pull/1446) Update + README +- [#1444](https://github.com/sanic-org/sanic/pull/1444) Update + README +- [#1443](https://github.com/sanic-org/sanic/pull/1443) Update + README, including new logo +- [#1440](https://github.com/sanic-org/sanic/pull/1440) fix minor + type and pip install instruction mismatch +- [#1424](https://github.com/sanic-org/sanic/pull/1424) + Documentation Enhancements + +Note: 19.3.0 was skipped for packagement purposes and not released on +PyPI + +## Version 18.12 + +### 18.12.0 + +- Changes: + + - Improved codebase test coverage from 81% to 91%. + - Added stream_large_files and host examples in static_file + document + - Added methods to append and finish body content on Request + (#1379) + - Integrated with .appveyor.yml for windows ci support + - Added documentation for AF_INET6 and AF_UNIX socket usage + - Adopt black/isort for codestyle + - Cancel task when connection_lost + - Simplify request ip and port retrieval logic + - Handle config error in load config file. + - Integrate with codecov for CI + - Add missed documentation for config section. + - Deprecate Handler.log + - Pinned httptools requirement to version 0.0.10+ + +- Fixes: + + - Fix `remove_entity_headers` helper function (#1415) + - Fix TypeError when use Blueprint.group() to group blueprint + with default url_prefix, Use os.path.normpath to avoid invalid + url_prefix like api//v1 f8a6af1 Rename the `http` module to + `helpers` to prevent conflicts with the built-in Python http + library (fixes #1323) + - Fix unittests on windows + - Fix Namespacing of sanic logger + - Fix missing quotes in decorator example + - Fix redirect with quoted param + - Fix doc for latest blueprint code + - Fix build of latex documentation relating to markdown lists + - Fix loop exception handling in app.py + - Fix content length mismatch in windows and other platform + - Fix Range header handling for static files (#1402) + - Fix the logger and make it work (#1397) + - Fix type pikcle->pickle in multiprocessing test + - Fix pickling blueprints Change the string passed in the + "name" section of the namedtuples in Blueprint to match the + name of the Blueprint module attribute name. This allows + blueprints to be pickled and unpickled, without errors, which + is a requirement of running Sanic in multiprocessing mode in + Windows. Added a test for pickling and unpickling blueprints + Added a test for pickling and unpickling sanic itself Added a + test for enabling multiprocessing on an app with a blueprint + (only useful to catch this bug if the tests are run on + Windows). + - Fix document for logging + +## Version 0.8 + +**0.8.3** + +- Changes: + - Ownership changed to org 'sanic-org' + +**0.8.0** + +- Changes: + - Add Server-Sent Events extension (Innokenty Lebedev) + - Graceful handling of request_handler_task cancellation (Ashley + Sommer) + - Sanitize URL before redirection (aveao) + - Add url_bytes to request (johndoe46) + - py37 support for travisci (yunstanford) + - Auto reloader support for OSX (garyo) + - Add UUID route support (Volodymyr Maksymiv) + - Add pausable response streams (Ashley Sommer) + - Add weakref to request slots (vopankov) + - remove ubuntu 12.04 from test fixture due to deprecation + (yunstanford) + - Allow streaming handlers in add_route (kinware) + - use travis_retry for tox (Raphael Deem) + - update aiohttp version for test client (yunstanford) + - add redirect import for clarity (yingshaoxo) + - Update HTTP Entity headers (Arnulfo Solís) + - Add register_listener method (Stephan Fitzpatrick) + - Remove uvloop/ujson dependencies for Windows (abuckenheimer) + - Content-length header on 204/304 responses (Arnulfo Solís) + - Extend WebSocketProtocol arguments and add docs (Bob Olde + Hampsink, yunstanford) + - Update development status from pre-alpha to beta (Maksim + Anisenkov) + - KeepAlive Timeout log level changed to debug (Arnulfo Solís) + - Pin pytest to 3.3.2 because of pytest-dev/pytest#3170 (Maksim + Aniskenov) + - Install Python 3.5 and 3.6 on docker container for tests (Shahin + Azad) + - Add support for blueprint groups and nesting (Elias Tarhini) + - Remove uvloop for windows setup (Aleksandr Kurlov) + - Auto Reload (Yaser Amari) + - Documentation updates/fixups (multiple contributors) +- Fixes: + - Fix: auto_reload in Linux (Ashley Sommer) + - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) + - Fix: disable auto_reload by default on windows (abuckenheimer) + - Fix (1143): Turn off access log with gunicorn (hqy) + - Fix (1268): Support status code for file response (Cosmo Borsky) + - Fix (1266): Add content_type flag to Sanic.static (Cosmo Borsky) + - Fix: subprotocols parameter missing from add_websocket_route + (ciscorn) + - Fix (1242): Responses for CI header (yunstanford) + - Fix (1237): add version constraint for websockets (yunstanford) + - Fix (1231): memory leak - always release resource (Phillip Xu) + - Fix (1221): make request truthy if transport exists (Raphael + Deem) + - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) + - Fix try_everything examples (PyManiacGR, kot83) + - Fix (1158): default to auto_reload in debug mode (Raphael Deem) + - Fix (1136): ErrorHandler.response handler call too restrictive + (Julien Castiaux) + - Fix: raw requires bytes-like object (cloudship) + - Fix (1120): passing a list in to a route decorator's host arg + (Timothy Ebiuwhe) + - Fix: Bug in multipart/form-data parser (DirkGuijt) + - Fix: Exception for missing parameter when value is null + (NyanKiyoshi) + - Fix: Parameter check (Howie Hu) + - Fix (1089): Routing issue with named parameters and different + methods (yunstanford) + - Fix (1085): Signal handling in multi-worker mode (yunstanford) + - Fix: single quote in readme.rst (Cosven) + - Fix: method typos (Dmitry Dygalo) + - Fix: log_response correct output for ip and port (Wibowo + Arindrarto) + - Fix (1042): Exception Handling (Raphael Deem) + - Fix: Chinese URIs (Howie Hu) + - Fix (1079): timeout bug when self.transport is None (Raphael + Deem) + - Fix (1074): fix strict_slashes when route has slash (Raphael + Deem) + - Fix (1050): add samesite cookie to cookie keys (Raphael Deem) + - Fix (1065): allow add_task after server starts (Raphael Deem) + - Fix (1061): double quotes in unauthorized exception (Raphael + Deem) + - Fix (1062): inject the app in add_task method (Raphael Deem) + - Fix: update environment.yml for readthedocs (Eli Uriegas) + - Fix: Cancel request task when response timeout is triggered + (Jeong YunWon) + - Fix (1052): Method not allowed response for RFC7231 compliance + (Raphael Deem) + - Fix: IPv6 Address and Socket Data Format (Dan Palmer) + +Note: Changelog was unmaintained between 0.1 and 0.7 + +## Version 0.1 + +**0.1.7** + +- Reversed static url and directory arguments to meet spec + +**0.1.6** + +- Static files +- Lazy Cookie Loading + +**0.1.5** + +- Cookies +- Blueprint listeners and ordering +- Faster Router +- Fix: Incomplete file reads on medium+ sized post requests +- Breaking: after_start and before_stop now pass sanic as their + first argument + +**0.1.4** + +- Multiprocessing + +**0.1.3** + +- Blueprint support +- Faster Response processing + +**0.1.1 - 0.1.2** + +- Struggling to update pypi via CI + +**0.1.0** + +- Released to public From 5c16de9af3631086d10162b548257677904a607f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 16:17:23 +0200 Subject: [PATCH 277/698] New translations class-based-views.md (Chinese Simplified) --- guide/content/zh/guide/advanced/class-based-views.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/zh/guide/advanced/class-based-views.md b/guide/content/zh/guide/advanced/class-based-views.md index 901e0848bf..f63164713c 100644 --- a/guide/content/zh/guide/advanced/class-based-views.md +++ b/guide/content/zh/guide/advanced/class-based-views.md @@ -1,6 +1,6 @@ -# Class Based Views +# 基于类的视图(Class Based Views) -## Why use them? +## 为什么要使用它？ .. column:: @@ -69,7 +69,7 @@ app.add_route(FooBar.as_view(), "/foobar") ``` ```` -## Defining a view +## 定义视图(Defining a view) A class-based view should subclass :class:`sanic.views.HTTPMethodView`. You can then implement class methods with the name of the corresponding HTTP method. If a request is received that has no defined method, a `405: Method not allowed` response will be generated. From b46d71688273b580e9a4edc85c8bfa94a0a7985c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 18:54:22 +0200 Subject: [PATCH 278/698] New translations class-based-views.md (Japanese) --- .../ja/guide/advanced/class-based-views.md | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/guide/content/ja/guide/advanced/class-based-views.md b/guide/content/ja/guide/advanced/class-based-views.md index 901e0848bf..869ade3599 100644 --- a/guide/content/ja/guide/advanced/class-based-views.md +++ b/guide/content/ja/guide/advanced/class-based-views.md @@ -1,15 +1,15 @@ -# Class Based Views +# クラスベースビュー -## Why use them? +## なぜ使うのか？ .. column:: ``` -### The problem +### 問題点 -A common pattern when designing an API is to have multiple functionality on the same endpoint that depends upon the HTTP method. +APIを設計する際の一般的なパターンは、同じエンドポイントに対してHTTPメソッドによって複数の機能を持つことです。 -While both of these options work, they are not good design practices and may be hard to maintain over time as your project grows. +これらのオプションは両方とも機能しますが、優れた設計慣行ではなく、プロジェクトが成長するにつれて時間の経過とともに維持するのが難しい場合があります。 ``` .. column:: @@ -44,9 +44,9 @@ async def bar(request): .. column:: ``` -### The solution +### 解決策 -Class-based views are simply classes that implement response behavior to requests. They provide a way to compartmentalize handling of different HTTP request types at the same endpoint. +クラスベースのビューは、要求に対する応答動作を完結に実装するクラスです。これらは、同じエンドポイントで異なるHTTPリクエストタイプの処理を区分する方法を提供します。 ``` .. column:: @@ -69,16 +69,16 @@ app.add_route(FooBar.as_view(), "/foobar") ``` ```` -## Defining a view +## ビューの定義 -A class-based view should subclass :class:`sanic.views.HTTPMethodView`. You can then implement class methods with the name of the corresponding HTTP method. If a request is received that has no defined method, a `405: Method not allowed` response will be generated. +クラスベースのビューは、 :class:`sanic.views.HTTPMethodView` のサブクラスでなければなりません。 その後、対応するHTTPメソッドの名前でクラスメソッドを実装できます。 定義されたメソッドを持たない要求を受信すると、 `405: Method not allowed` 応答が生成されます。 .. column:: ``` -To register a class-based view on an endpoint, the `app.add_route` method is used. The first argument should be the defined class with the method `as_view` invoked, and the second should be the URL endpoint. +エンドポイントにクラスベースのビューを登録するために、`app.add_route`メソッドが使用できます。最初の引数は、メソッド`as_view`が呼び出された定義済みクラスで、2番目の引数はURLエンドポイントである必要があります。 -The available methods are: +利用可能なメソッドは: - get - post @@ -101,7 +101,7 @@ class SimpleView(HTTPMethodView): def get(self, request): return text("I am get method") - # You can also use async syntax + # 非同期構文も利用可能 async def post(self, request): return text("I am post method") @@ -118,12 +118,12 @@ app.add_route(SimpleView.as_view(), "/") ``` ```` -## Path parameters +## pathパラメータ .. column:: ``` -You can use path parameters exactly as discussed in [the routing section](/guide/basics/routing.md). +[ルーティングセクション](/guide/basics/routing.md)で説明されているとおりにpathパラメータを使用できます。 ``` .. column:: @@ -133,27 +133,27 @@ You can use path parameters exactly as discussed in [the routing section](/guide class NameView(HTTPMethodView): def get(self, request, name): - return text("Hello {}".format(name)) + return text("こんにちは、{}さん".format(name)) app.add_route(NameView.as_view(), "/") ``` ```` -## Decorators +## デコレータ -As discussed in [the decorators section](/guide/best-practices/decorators.md), often you will need to add functionality to endpoints with the use of decorators. You have two options with CBV: +[デコレータのページ](/guide/best-practices/decorators.md)で説明したように、デコレータを使用してエンドポイントに機能を追加する必要があるかもしれません。 CBVによる二つの選択肢があります: -1. Apply to _all_ HTTP methods in the view -2. Apply individually to HTTP methods in the view +1. ビュー内の _全ての_ HTTPメソッドに適用する +2. ビュー内のHTTPメソッドに個別に適用する -Let's see what the options look like: +これらがどのように動作するか見てみましょう: .. column:: ``` -### Apply to all methods +### すべてのメソッドに適用する -If you want to add any decorators to the class, you can set the `decorators` class variable. These will be applied to the class when `as_view` is called. +クラスにデコレータを追加する場合は、`decorators`クラス変数を設定できます。 これらは、`as_view`が呼び出された時にクラスに適用されます。 ``` .. column:: @@ -164,10 +164,10 @@ class ViewWithDecorator(HTTPMethodView): decorators = [some_decorator_here] def get(self, request, name): - return text("Hello I have a decorator") + return text("やあ、僕はデコレータを持ってるよ") def post(self, request, name): - return text("Hello I also have a decorator") + return text("やあ、僕もデコレータを持ってるよ") app.add_route(ViewWithDecorator.as_view(), "/url") ``` @@ -176,9 +176,9 @@ app.add_route(ViewWithDecorator.as_view(), "/url") .. column:: ``` -### Apply to individual methods +### 個々のメソッドに適用する -But if you just want to decorate some methods and not all methods, you can as shown here. +しかし、すべてのメソッドではなく、いくつかのメソッドにデコレータをつけたい場合は、ここに示すように記述できます。 ``` .. column:: @@ -190,23 +190,23 @@ class ViewWithSomeDecorator(HTTPMethodView): @staticmethod @some_decorator_here def get(request, name): - return text("Hello I have a decorator") + return text("やあ、僕はデコレータを持ってるよ") def post(self, request, name): - return text("Hello I do not have any decorators") + return text("やあ、僕はデコレータを持っていないよ") @some_decorator_here def patch(self, request, name): - return text("Hello I have a decorator") + return text("やあ、僕もデコレータを持っているよ") ``` ```` -## Generating a URL +## URLの生成 .. column:: ``` -This works just like [generating any other URL](/guide/basics/routing.md#generating-a-url), except that the class name is a part of the endpoint. +これは、クラス名がエンドポイントの一部であることを除いて、[他のURLの生成](/guide/basics/routing.md#generating-a-url)と同じように機能します。 ``` .. column:: From e169326e9680ac31ce728bad5643e741717dd3c1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 18:54:23 +0200 Subject: [PATCH 279/698] New translations proxy-headers.md (Japanese) --- .../ja/guide/advanced/proxy-headers.md | 82 +++++++++---------- 1 file changed, 40 insertions(+), 42 deletions(-) diff --git a/guide/content/ja/guide/advanced/proxy-headers.md b/guide/content/ja/guide/advanced/proxy-headers.md index ff151b592b..0b1a95ec27 100644 --- a/guide/content/ja/guide/advanced/proxy-headers.md +++ b/guide/content/ja/guide/advanced/proxy-headers.md @@ -1,19 +1,19 @@ -# Proxy configuration +# プロキシ設定 -When you use a reverse proxy server (e.g. nginx), the value of `request.ip` will contain the IP of a proxy, typically `127.0.0.1`. Almost always, this is **not** what you will want. +リバースプロキシサーバー(nginxなど)を使用する場合、`request.ip`の値にはプロキシのIP(通常は`127.0.0.1`)が含まれます。 ほとんどの場合、これはあなたが望むもの**ではありません**。 -Sanic may be configured to use proxy headers for determining the true client IP, available as `request.remote_addr`. The full external URL is also constructed from header fields _if available_. +Sanicは、`request.remote_addr`として利用可能な本当のクライアントIPを決定するためにプロキシヘッダーを使用するように構成できます。 完全な外部URLは、_使用できれば_ヘッダーフィールドからも構築されます。 -.. tip:: Heads up +.. tip:: ヒント ``` -Without proper precautions, a malicious client may use proxy headers to spoof its own IP. To avoid such issues, Sanic does not use any proxy headers unless explicitly enabled. +適切な予防措置がなければ、悪意のあるクライアントはプロキシヘッダーを使用して独自のIPを偽装することができます。このような問題を回避するために、Sanicは明示的に有効になっていない限り、プロキシヘッダーを使用しません。 ``` .. column:: ``` -Services behind reverse proxies must configure one or more of the following [configuration values](/guide/deployment/configuration.md): +リバースプロキシを使うサービスは、次の[構成値](/guide/deployment/configuration.md)の1つ以上を設定する必要があります。 - `FORWARDED_SECRET` - `REAL_IP_HEADER` @@ -30,29 +30,29 @@ app.config.PROXIES_COUNT = 2 ``` ```` -## Forwarded header +## Forwarded ヘッダー -In order to use the `Forwarded` header, you should set `app.config.FORWARDED_SECRET` to a value known to the trusted proxy server. The secret is used to securely identify a specific proxy server. +`Forwarded`ヘッダーを使用するには、信頼できるプロキシサーバーに設定されている値を`app.config.FORWARDED_SECRET`に設定する必要があります。 このシークレットは、特定のプロキシサーバーを安全に識別するために使用されます。 -Sanic ignores any elements without the secret key, and will not even parse the header if no secret is set. +Sanicはシークレットキーのない要素を無視し、シークレットが設定されていない場合はヘッダーを解析することもありません。 -All other proxy headers are ignored once a trusted forwarded element is found, as it already carries complete information about the client. +信頼された転送要素が見つかると、他のすべてのプロキシヘッダは無視されます。クライアントに関する完全な情報をすでに運んでいるからです。 -To learn more about the `Forwarded` header, read the related [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) and [Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) articles. +`Forwarded`ヘッダーの詳細については、関連する[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded)および[Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/)の記事を参照してください。(訳注: 両方とも英語です) -## Traditional proxy headers +## 従来のプロキシヘッダー -### IP Headers +### IP ヘッダー -When your proxy forwards you the IP address in a known header, you can tell Sanic what that is with the `REAL_IP_HEADER` config value. +プロキシが既知のヘッダーにIPアドレスを転送するとき`REAL_IP_HEADER`の値を指定すると、Sanicにそれが何かを教えることができます。 ### X-Forwarded-For -This header typically contains a chain of IP addresses through each layer of a proxy. Setting `PROXIES_COUNT` tells Sanic how deep to look to get an actual IP address for the client. This value should equal the _expected_ number of IP addresses in the chain. +このヘッダーには、通常、プロキシの各レイヤーを介したIPアドレスのチェーンが含まれています。 `PROXIES_COUNT`を設定すると、クライアントの実際のIPアドレスを取得する深さがSanicに指示されます。 この値は、チェーン内のIPアドレスの _期待される_ 数に等しいはずです。 -### Other X-headers +### その他のXヘッダー -If a client IP is found by one of these methods, Sanic uses the following headers for URL parts: +クライアントIPがこれらのメソッドのいずれかで見つかった場合、Sanicは以下のURLパーツのヘッダを使用します: - x-forwarded-proto - x-forwarded-host @@ -60,9 +60,9 @@ If a client IP is found by one of these methods, Sanic uses the following header - x-forwarded-path - x-scheme -## Examples +## 例 -In the following examples, all requests will assume that the endpoint looks like this: +以下の例では、すべてのリクエストはエンドポイントが次のようになると仮定します。 ```python @app.route("/fwd") @@ -80,9 +80,9 @@ async def forwarded(request): *** -##### Example 1 +##### 例1 -Without configured FORWARDED_SECRET, x-headers should be respected +FORWARDED_SECRETが設定されていない場合、Xヘッダは尊重されます。 ```sh curl localhost:8000/fwd \ @@ -107,7 +107,7 @@ app.config.REAL_IP_HEADER = "x-real-ip" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "127.0.0.2", "scheme": "ws", @@ -123,9 +123,9 @@ app.config.REAL_IP_HEADER = "x-real-ip" *** -##### Example 2 +##### 例2 -FORWARDED_SECRET now configured +FORWARDED_SECRETが設定された場合 ```sh curl localhost:8000/fwd \ @@ -150,8 +150,7 @@ app.config.FORWARDED_SECRET = "mySecret" .. column:: ```` -```bash -# curl response +```curlの応答 { "remote_addr": "[::2]", "scheme": "https", @@ -164,15 +163,14 @@ app.config.FORWARDED_SECRET = "mySecret" "path": "/app/", "secret": "mySecret" } -} ``` ```` *** -##### Example 3 +##### 例3 -Empty Forwarded header -> use X-headers +空の転送ヘッダー - > Xヘッダーを使用する ```sh curl localhost:8000/fwd \ @@ -197,7 +195,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "127.0.0.2", "scheme": "ws", @@ -213,9 +211,9 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 4 +##### 例4 -Header present but not matching anything +ヘッダーは存在するのに何も一致しない場合。 ```sh curl localhost:8000/fwd \ @@ -237,7 +235,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "", "scheme": "http", @@ -251,9 +249,9 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 5 +##### 例5 -Forwarded header present but no matching secret -> use X-headers +Forwarded ヘッダーは存在するが、一致するシークレットはない場合 -> Xヘッダを使用 ```sh curl localhost:8000/fwd \ @@ -276,7 +274,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "127.0.0.2", "scheme": "http", @@ -291,9 +289,9 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 6 +##### 例6 -Different formatting and hitting both ends of the header +フォーマットが異なり、ヘッダーの両端がヒットする場合 ```sh curl localhost:8000/fwd \ @@ -315,7 +313,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "127.0.0.4", "scheme": "http", @@ -332,9 +330,9 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 7 +##### 例7 -Test escapes (modify this if you see anyone implementing quoted-pairs) +エスケープをテストする場合(quoted-pairsを実装しているのを見かけたら修正してあげてください)。 ```sh curl localhost:8000/fwd \ @@ -356,7 +354,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "test", "scheme": "http", From ba98a1570f6dfcb380eda7a23ec7fdc3971c6007 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 31 Dec 2023 19:57:23 +0200 Subject: [PATCH 280/698] New translations proxy-headers.md (Japanese) --- guide/content/ja/guide/advanced/proxy-headers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/guide/advanced/proxy-headers.md b/guide/content/ja/guide/advanced/proxy-headers.md index 0b1a95ec27..f1a58ec764 100644 --- a/guide/content/ja/guide/advanced/proxy-headers.md +++ b/guide/content/ja/guide/advanced/proxy-headers.md @@ -371,9 +371,9 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 8 +##### 例8 -Secret insulated by malformed field #1 +不正なフィールドによってシークレットが隔離される例 #1 ```sh curl localhost:8000/fwd \ @@ -395,7 +395,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "test", "scheme": "http", From 47808dcfbd467c550923009131593bbbebcd3d9e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 06:56:37 +0200 Subject: [PATCH 281/698] New translations proxy-headers.md (Japanese) --- .../content/ja/guide/advanced/proxy-headers.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/ja/guide/advanced/proxy-headers.md b/guide/content/ja/guide/advanced/proxy-headers.md index f1a58ec764..4e9b45f87b 100644 --- a/guide/content/ja/guide/advanced/proxy-headers.md +++ b/guide/content/ja/guide/advanced/proxy-headers.md @@ -411,9 +411,9 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 9 +##### 例9 -Secret insulated by malformed field #2 +不正なフィールドによってシークレットが隔離される例 #2 ```sh curl localhost:8000/fwd \ @@ -435,7 +435,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "", "scheme": "wss", @@ -451,7 +451,7 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 10 +##### 例10 Unexpected termination should not lose existing acceptable values @@ -475,7 +475,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "", "scheme": "wss", @@ -491,7 +491,7 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 11 +##### 例11 Field normalization @@ -515,7 +515,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "", "scheme": "wss", @@ -534,7 +534,7 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 12 +##### 例12 Using "by" field as secret @@ -558,7 +558,7 @@ app.config.FORWARDED_SECRET = "_proxySecret" ```` ```bash -# curl response +# curlの応答 { "remote_addr": "1.2.3.4", "scheme": "http", From cef63781a8727818130c5af951fbdc68be40dd92 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 06:56:38 +0200 Subject: [PATCH 282/698] New translations signals.md (Japanese) --- guide/content/ja/guide/advanced/signals.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/ja/guide/advanced/signals.md b/guide/content/ja/guide/advanced/signals.md index 971582bb1e..43e2849ced 100644 --- a/guide/content/ja/guide/advanced/signals.md +++ b/guide/content/ja/guide/advanced/signals.md @@ -1,6 +1,6 @@ -# Signals +# シグナル -Signals provide a way for one part of your application to tell another part that something happened. +シグナルは、アプリケーションのある部分が別の部分に何かが起こったことを伝える方法を提供します。 ```python @app.signal("user.registration.created") @@ -16,12 +16,12 @@ async def handle_registration(request): }) ``` -## Adding a signal +## シグナルを追加する .. column:: ``` -The API for adding a signal is very similar to adding a route. +シグナルを追加するためのAPIは、ルートの追加と非常によく似ています。 ``` .. column:: From 31ad115b0ce1281704fa1d507782d915fa057551 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:18:56 +0200 Subject: [PATCH 283/698] New translations built-with-sanic.md (Japanese) --- guide/content/ja/built-with-sanic.md | 58 ++++++++++++++-------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/guide/content/ja/built-with-sanic.md b/guide/content/ja/built-with-sanic.md index fa5d78e1cf..3294ba15e6 100644 --- a/guide/content/ja/built-with-sanic.md +++ b/guide/content/ja/built-with-sanic.md @@ -1,67 +1,67 @@ --- -title: Full Speed Ahead - How We Built This Site with Sanic -layout: main +title: 前方の全速度-私たちはどのように我々はサニックでこのサイトを構築しました +layout: メイン --- .. attrs:: -:class: title +:class: タイトル ``` -Full Speed Ahead: +全速力: ``` .. attrs:: :class: subtitle ``` -How We Built This Site with Sanic +どのように私たちはサニックでこのサイトを構築しました ``` -Welcome to our little corner of the Internet where we proudly say, "Yes, we built this with Sanic!" This isn't just a website; it's our playground, our test lab, our battlefield, and, well, our home. +私たちが誇らしげに言うインターネットの小さなコーナーへようこそ、「はい、私たちはこれをSanicで構築しました!」と。 これは単なるウェブサイトではありません。私たちの遊び場、テストラボ、戦場、そして自宅です。 ![](/assets/images/built-with-sanic.png) -### The Story: "We Drink Our Own Champagne" +### 物語: "我々は自分のシャンパンを飲む" -We believe in Sanic so much that we decided to put it to the ultimate test—running our own website. It's like a chef eating at their own restaurant, only with less risk of food poisoning. +私たちはSanicをあまりにも信じているので、私たち自身のウェブサイトを運営する究極のテストにしようと決めました。 食中毒のリスクが少ないだけで、自分のレストランでシェフが食事をするようなものです。 -Why? Because building a website or web application is hard. There are countless moving parts, a plethora of challenges, and the ever-present need for speed and reliability. We want to show you just one of the many ways you _could_ do it. +なぜでしょう？ ウェブサイトやウェブアプリケーションを構築することは難しいので。 無数の可動部品、多くの挑戦、そして常に存在するスピードと信頼性の必要性があります。 私たちはあなたが_できる_多くの方法の一つをお見せしたいと思います。 -In this high-stakes digital kitchen, Sanic is our secret ingredient. By deploying our own website on Sanic, we're not just showcasing its capabilities; we're stress-testing them in the real world. This is our chance to walk the walk, proving that Sanic isn't just good on paper—it's a robust, high-performance framework that can handle everything from the smallest blog to the busiest e-commerce site. +このハイステークスのデジタルキッチンでは、Sanicは私たちの秘密の食材です。 Sanicに自社のウェブサイトを導入することで、私たちはその機能を紹介するだけではなく、現実世界でストレステストを行っています。 これは、Sanicが紙に良いだけではないことを証明する私たちの歩くチャンスです。それは堅牢です。 最小のブログから最も忙しいeコマースサイトまであらゆるものを扱える高性能なフレームワークです -So, here we are, sipping our own champagne, confident in the knowledge that if Sanic can run our site, it can power yours too. Cheers to coding at the speed of thought! 🥂 +だから、ここで私たちは、Sanicが私たちのサイトを運営することができれば、それもあなたの力になるという知識に自信を持って、私たち自身のシャンパンをすすります。 思考の速さでコーディングに乾杯! 🥂 -### The Setup: Digital Ocean, Ahoy! +### セットアップ：デジタルオーシャン、アホイ！ -We launched our site on Digital Ocean's App Platform because we love high-performance cloud sailing. Think of it as having a Ferrari in the cloud—fast, sleek, but way easier to handle. +私たちは高性能なクラウドセーリングが大好きなので、Digital OceanのApp Platformでサイトを立ち上げました。 フェラーリをクラウドに搭載していると考えてみてください。高速で洗練されていますが、扱いやすいです。 -Why go for simplicity? With a lean team and no DevOps gurus, we needed a no-fuss, straightforward solution. Digital Ocean gives us that smooth sailing platform-as-a-service (PaaS) experience. It’s perfect for our needs: easy setup, automatic deployments, and the kind of reliability that lets you sleep soundly. +なぜシンプルになるのでしょうか？ リーンなチームで、DevOpsの指導者がいない私たちには、簡単で簡単なソリューションが必要でした。 Digital Oceanは、サービスとしてのスムーズなセーリングプラットフォーム(PaaS)を提供してくれます。 簡単なセットアップ、自動展開、そして健全に眠れるような信頼性など、当社のニーズに最適です。 -Our choice reflects our ethos: focus on your strengths and let the platform do the heavy lifting. For us, it means creating amazing web experiences with Sanic, supported by a deployment solution that's simple yet powerful. ⛵ +私たちの選択は私たちの精神を反映しています: あなたの強みに焦点を当て、プラットフォームは重い持ち上げを行いましょう. 私たちにとって、それはシンプルでありながら強力な展開ソリューションによってサポートされているSanicで素晴らしいWebエクスペリエンスを作成することを意味します。 ⛵ -### The Code: GitHub's Where It's At +### コード：GitHubの場所 -All our code is out in the open, basking in the glory of public scrutiny on GitHub. Why hide the magic? It's right there, in full view, at [our GitHub repository](https://github.com/sanic-org/sanic/tree/main/guide). Go ahead, take a peek, fork it, play with it, break it (and then kindly fix it). +私たちのコードはすべてオープンで、GitHubの公開審査の栄光を浴びています。 なぜ魔法を隠すのですか? 詳細は format@@0(https\://github.com/sanic-org/sanic/tree/main/guide) をご覧ください。 先に進み、覗き見を取る、フォーク、それで遊ぶ、それを壊す(そして親切にそれを修正する)。 -Open-source isn't just a buzzword for us; it's our ethos. It's about building something bigger than ourselves, together. Our code is a testament to collaborative innovation, a playground for development, and a real-life example of Sanic in action. +オープンソースは単なる流行語ではありません私たちの精神です 私たち自身よりも大きなものを一緒に作ることです 私たちのコードは、共同でのイノベーション、開発のための遊び場、そして実際のSanicの実例を証明しています。 -Every line of code, every commit, reflects our journey with Sanic, showcasing how we leverage its speed and scalability. Your contributions, whether fixing a bug, suggesting a feature, or enhancing documentation, are what propel this project forward. +コードのすべての行、すべてのコミットは、Sanicとの私たちの旅を反映しており、そのスピードとスケーラビリティをどのように活用しているかを示しています。 バグを修正したり、機能を提案したり、ドキュメントを強化したりしても、あなたの貢献はこのプロジェクトを前進させるものです。 -So, dive in, contribute your genius, and let's keep shaping the future of web development with Sanic. Together, we're not just coding – we're creating a community-driven powerhouse. 🚀 +では、ダイブイン、あなたの天才に貢献し、SanicとWeb開発の未来を形作っていきましょう。 一緒にコーディングするだけでなく、コミュニティ主導のパワーハウスを作っています。 🚀 -### The Invitation: Write, Code, Break, Fix! +### 招待状：書き込み、コード、ブレイク、修正！ -- **Documentarians**: Love making complex stuff sound easy? Our docs are your canvas. Paint away in words! 🎨 +- **ドキュメンタリー作家**: 複雑なものを簡単に作る愛？ 私たちのドキュメントはあなたのキャンバスです。 言葉で絵を描いてみよう! 🎨 -- **Code Ninjas**: Find bugs? Squash 'em. Got ideas? Code 'em. Make pull requests rain! 🥷 +- **コードニンジャ**：バグを見つけますか？ Squash 'em. アイデアはありますか？ Code 'em. プルリクエストを雨にしましょう！ 🥷 -- **Bug Hunters**: If you find bugs, don't just stare. Let us know. We love a good bug hunt. 🐛 +- **バグハンター**: バグを見つけたら、じっと見つめるだけではありません。 お知らせください。 私たちは良い虫狩りが大好きです。 🐛 -### The Bottom Line +### ボトムライン -We built this site with Sanic to show off what it can do. It's fast, it's fun, and it's what we use. So, if things load swiftly, pat us on the back. If they don't, well, uh... we blame cosmic rays? +私たちはSanicとこのサイトを構築し、それが何ができるかを示しました。 速くて楽しくて私たちが使うものです だから、物事が迅速にロードされる場合は、背面に私たちを軽く叩いてください。 そうでなければ、ええと... 宇宙線を責めるのか? -Join us in making Sanic not just good, but "I-can't-believe-it's-not-butter" good! +サニックを作るだけでなく、良いことにご参加ください, しかし、「私はできません-それは-バターではありません」良い! -Cheers, -The Sanic Team (who occasionally wear capes) +乾杯、 +サニックチーム（時にはマントを着用） From a93acb836fc222584cda1b0989ae8adcfb883a1d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:18:58 +0200 Subject: [PATCH 284/698] New translations built-with-sanic.md (Chinese Simplified) --- guide/content/zh/built-with-sanic.md | 58 ++++++++++++++-------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/guide/content/zh/built-with-sanic.md b/guide/content/zh/built-with-sanic.md index fa5d78e1cf..72b8f3445d 100644 --- a/guide/content/zh/built-with-sanic.md +++ b/guide/content/zh/built-with-sanic.md @@ -1,67 +1,67 @@ --- -title: Full Speed Ahead - How We Built This Site with Sanic -layout: main +title: 全速前进-我们如何用Sanic 构建这个站点 +layout: 主要的 --- .. attrs:: :class: title ``` -Full Speed Ahead: +前方全速： ``` .. attrs:: :class: subtitle ``` -How We Built This Site with Sanic +我们如何用Sanic构建这个站点 ``` -Welcome to our little corner of the Internet where we proudly say, "Yes, we built this with Sanic!" This isn't just a website; it's our playground, our test lab, our battlefield, and, well, our home. +欢迎来到我们的互联网的小角落，我们自豪地说，“是的，我们用Sanic建造了这个！” 这不仅仅是一个网站；它是我们的游戏场、我们的测试实验室、我们的战场以及我们的家中。 -![](/assets/images/built-with-sanic.png) +![](/assets/images/build-sanic.png) -### The Story: "We Drink Our Own Champagne" +### 故事：“我们喝我们自己的冠军” -We believe in Sanic so much that we decided to put it to the ultimate test—running our own website. It's like a chef eating at their own restaurant, only with less risk of food poisoning. +我们非常相信萨尼克语，我们决定对它进行最终测试——运行我们自己的网站。 它就像在他们自己的餐馆吃奶酪，只有在食物中毒的风险较低的情况下才能吃饭。 -Why? Because building a website or web application is hard. There are countless moving parts, a plethora of challenges, and the ever-present need for speed and reliability. We want to show you just one of the many ways you _could_ do it. +为什么？ 因为建立网站或网页应用程序是硬性的。 现在有无数令人感动的部分，挑战太多，始终需要速度和可靠性。 我们只想向你展示你的很多方法之一。 -In this high-stakes digital kitchen, Sanic is our secret ingredient. By deploying our own website on Sanic, we're not just showcasing its capabilities; we're stress-testing them in the real world. This is our chance to walk the walk, proving that Sanic isn't just good on paper—it's a robust, high-performance framework that can handle everything from the smallest blog to the busiest e-commerce site. +在这个高风险的数字厨房中，萨尼克是我们的秘密成分。 通过在Sanic上部署我们自己的网站，我们不只是展示自己的能力；我们正在现实世界中对它们进行压力测试。 这是我们走路的机会，证明萨尼克在纸面上不是好事——这是一种强有力的， 从最小的博客到最繁忙的电子商务站点都能够处理所有的问题，这种框架可以是高性能的框架。 -So, here we are, sipping our own champagne, confident in the knowledge that if Sanic can run our site, it can power yours too. Cheers to coding at the speed of thought! 🥂 +因此，我们在这里打着我们自己的旗手，相信我们知道如果萨尼克能够管理我们的场地，它也能够为你提供电力。 喜欢按思考的速度编程！ 🥂 -### The Setup: Digital Ocean, Ahoy! +### 设置：数字大洋，奥霍！ -We launched our site on Digital Ocean's App Platform because we love high-performance cloud sailing. Think of it as having a Ferrari in the cloud—fast, sleek, but way easier to handle. +我们启动了我们在数字大洋应用平台上的网站，因为我们喜欢高性能的云端航行。 认为它在云端有一个Ferrari-快速、睡觉，但更容易处理。 -Why go for simplicity? With a lean team and no DevOps gurus, we needed a no-fuss, straightforward solution. Digital Ocean gives us that smooth sailing platform-as-a-service (PaaS) experience. It’s perfect for our needs: easy setup, automatic deployments, and the kind of reliability that lets you sleep soundly. +为什么要简化？ 有了一个精干的团队，没有德沃普斯大家，我们需要一种不引信、直截了当的解决办法。 数字海洋为我们提供了顺利航行平台作为服务的经验。 它对满足我们的需要是完美的：轻松设置、自动部署以及让你睡觉的可靠性。 -Our choice reflects our ethos: focus on your strengths and let the platform do the heavy lifting. For us, it means creating amazing web experiences with Sanic, supported by a deployment solution that's simple yet powerful. ⛵ +我们的选择反映了我们的精神：注重你的优势，让平台进行繁重的提升。 对我们来说，这意味着用萨尼克创造惊人的网络经验，辅之以一个简单但强有力的部署解决办法。 ⛵ -### The Code: GitHub's Where It's At +### 代码: GitHub的位置 -All our code is out in the open, basking in the glory of public scrutiny on GitHub. Why hide the magic? It's right there, in full view, at [our GitHub repository](https://github.com/sanic-org/sanic/tree/main/guide). Go ahead, take a peek, fork it, play with it, break it (and then kindly fix it). +我们的所有代码都在开放式中，将公众审查的光荣放在GitHub 上。 为什么隐藏魔法？ 它正好在这里，全文看到[我们的GitHub 仓库](https://github.com/sanic-org/sanic/tree/main/guide)。 继续前进，拿起宠物，派生它，用它玩游戏，打断它(然后修复它)。 -Open-source isn't just a buzzword for us; it's our ethos. It's about building something bigger than ourselves, together. Our code is a testament to collaborative innovation, a playground for development, and a real-life example of Sanic in action. +开放源码不仅仅是我们的蜂窝；这是我们的灵魂。 这是为了共同建立比我们更大的东西。 我们的守则证明了合作创新，是发展的游乐场，也是实际行动中的“圣经”的例子。 -Every line of code, every commit, reflects our journey with Sanic, showcasing how we leverage its speed and scalability. Your contributions, whether fixing a bug, suggesting a feature, or enhancing documentation, are what propel this project forward. +每一行代码，每项承诺都反映出我们用Sanic的旅程，展示我们如何利用其速度和可扩展性。 您的贡献，不管是修复bug，建议一个功能，还是改进文档，都是推动这个项目前进的因素。 -So, dive in, contribute your genius, and let's keep shaping the future of web development with Sanic. Together, we're not just coding – we're creating a community-driven powerhouse. 🚀 +所以，潜入，贡献你的基因，让我们继续以萨尼语塑造网络发展的未来。 我们一起不仅仅是编码——我们正在创建一个社区驱动的电台。 🚀 -### The Invitation: Write, Code, Break, Fix! +### 邀请：写入，代码，Break，Fix！ -- **Documentarians**: Love making complex stuff sound easy? Our docs are your canvas. Paint away in words! 🎨 +- **Documentarians**：喜欢制作复杂的物品很容易？ 我们的文档是你的画布。 用文字涂掉！ 🎨 -- **Code Ninjas**: Find bugs? Squash 'em. Got ideas? Code 'em. Make pull requests rain! 🥷 +- **Code Ninjas**: 查找bug? Squash 'em. 有主意？ Code 'em. 让拉取请求降雨！ 🥷 -- **Bug Hunters**: If you find bugs, don't just stare. Let us know. We love a good bug hunt. 🐛 +- **Bug Hunters**：如果你发现了缺陷，不只是污点。 让我们知道吧。 我们很喜欢寻找一个很好的漏洞。 🐛 -### The Bottom Line +### 底线 -We built this site with Sanic to show off what it can do. It's fast, it's fun, and it's what we use. So, if things load swiftly, pat us on the back. If they don't, well, uh... we blame cosmic rays? +我们用萨尼克建造这个网站来显示它可以做些什么。 它很快，很有趣，是我们使用的。 因此，如果事物迅速负荷，就把我们推倒在后面。 如果他们不是，好吧... 我们指责宇宙射线吗？ -Join us in making Sanic not just good, but "I-can't-believe-it's-not-butter" good! +加入我们不仅是好的，而且是好的！ -Cheers, -The Sanic Team (who occasionally wear capes) +欢呼， +Sanic 团队(有时戴帽子) From 3ade4fb4abf77e524cdc986ee5299d489a9bdd34 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:01 +0200 Subject: [PATCH 285/698] New translations class-based-views.md (Chinese Simplified) --- .../zh/guide/advanced/class-based-views.md | 122 +++++++++--------- 1 file changed, 61 insertions(+), 61 deletions(-) diff --git a/guide/content/zh/guide/advanced/class-based-views.md b/guide/content/zh/guide/advanced/class-based-views.md index f63164713c..94d5c9dd94 100644 --- a/guide/content/zh/guide/advanced/class-based-views.md +++ b/guide/content/zh/guide/advanced/class-based-views.md @@ -2,17 +2,17 @@ ## 为什么要使用它？ -.. column:: +.. 列: ``` -### The problem +### 问题 -A common pattern when designing an API is to have multiple functionality on the same endpoint that depends upon the HTTP method. +设计一个 API 时常见的模式是在依赖HTTP 方法的同一个端点上具有多个功能。 -While both of these options work, they are not good design practices and may be hard to maintain over time as your project grows. +虽然这两种选项都起作用，但它们并不是良好的设计做法，随着你的项目的发展，可能很难长期维持。 ``` -.. column:: +.. 列: ```` ```python @@ -41,15 +41,15 @@ async def bar(request): ``` ```` -.. column:: +.. 列: ``` -### The solution +### 解析器 -Class-based views are simply classes that implement response behavior to requests. They provide a way to compartmentalize handling of different HTTP request types at the same endpoint. +基于类的视图只是实现回应行为的类类。 它们为在同一端点将不同HTTP请求类型的处理分割开来提供了一条途径。 ``` -.. column:: +.. 列: ```` ```python @@ -71,25 +71,25 @@ app.add_route(FooBar.as_view(), "/foobar") ## 定义视图(Defining a view) -A class-based view should subclass :class:`sanic.views.HTTPMethodView`. You can then implement class methods with the name of the corresponding HTTP method. If a request is received that has no defined method, a `405: Method not allowed` response will be generated. +A class-based view should subclass :class:`sanic.views.HTTPMethodView`. 然后您可以执行具有相应的 HTTP 方法名称的类方法。 如果收到一个没有定义方法的请求，将生成一个 \`405: 方法不允许' 响应。 -.. column:: +.. 列: ``` -To register a class-based view on an endpoint, the `app.add_route` method is used. The first argument should be the defined class with the method `as_view` invoked, and the second should be the URL endpoint. +要在端点注册一个基于类的视图，将使用 `app.add_route` 方法。 第一个参数应该是使用`as_view`方法的定义类，第二个参数应该是URL终点。 -The available methods are: +可用的方法是： - get -- post -- put -- patch -- delete -- head -- options +- 发表 +- 放置 +- 补丁 +- 删除 +- 首长 +- 选项 ``` -.. column:: +.. 列: ```` ```python @@ -118,110 +118,110 @@ app.add_route(SimpleView.as_view(), "/") ``` ```` -## Path parameters +## 路径参数 -.. column:: +.. 列: ``` -You can use path parameters exactly as discussed in [the routing section](/guide/basics/routing.md). +您可以使用路径参数就像[路由部分](/guide/basics/routing.md)中讨论过的路径参数。 ``` -.. column:: +.. 列: ```` ```python class NameView(HTTPMethodView): def get(self, request, name): - return text("Hello {}".format(name)) + return text("Hello {}".format (name)) -app.add_route(NameView.as_view(), "/") +app.add_route(NameView.asp.as_view(), "/") ``` ```` -## Decorators +## 装饰符 -As discussed in [the decorators section](/guide/best-practices/decorators.md), often you will need to add functionality to endpoints with the use of decorators. You have two options with CBV: +正如在[装饰物部分](/guide/best practices/decorators.md)中所讨论的那样，您常常需要在终点中添加使用装饰物的功能。 您与 CBV 有两个选项： -1. Apply to _all_ HTTP methods in the view -2. Apply individually to HTTP methods in the view +1. 应用于视图中的 _all_ HTTP 方法 +2. 单独应用于视图中的 HTTP 方法 -Let's see what the options look like: +让我们看看这些选项是什么样子： -.. column:: +.. 列: ``` -### Apply to all methods +### 应用于所有方法 -If you want to add any decorators to the class, you can set the `decorators` class variable. These will be applied to the class when `as_view` is called. +如果您想要将任何装饰符添加到类中，您可以设置 "装饰符" 类变量。 当调用`as_view`时，这些将应用于该类。 ``` -.. column:: +.. 列: ```` ```python -class ViewWithDecorator(HTTPMethodView): +class ViewWidDecorator(HTTPMethodView): decorators = [some_decorator_here] - def get(self, request, name): - return text("Hello I have a decorator") + def get(self, request, pass). 姓名: + 退货文本("Hello I have a decorator") - def post(self, request, name): - return text("Hello I also have a decorator") + def post(self, 请求，名称： + return text("Hello I also a Decorator") -app.add_route(ViewWithDecorator.as_view(), "/url") +app dd_route(ViewWidDecorator.as_view(), "/url") ``` ```` -.. column:: +.. 列: ``` -### Apply to individual methods +### 应用于个别方法 -But if you just want to decorate some methods and not all methods, you can as shown here. +但是如果你只想装饰一些方法而不是所有方法，你可以如这里所示。 ``` -.. column:: +.. 列: ```` ```python -class ViewWithSomeDecorator(HTTPMethodView): +class Viewwitwithout Decorator(HTTPMethodView): - @staticmethod + @static方法 @some_decorator_here - def get(request, name): - return text("Hello I have a decorator") + def get(request 姓名: + 退货文本("Hello I have a decorator") - def post(self, request, name): - return text("Hello I do not have any decorators") + def post(self, 请求 姓名： + return text("Hello I no some decorators") @some_decorator_here - def patch(self, request, name): - return text("Hello I have a decorator") + def patch(self, 请求，名称： + 返回文本("Hello I have a decorator") ``` ```` -## Generating a URL +## 正在生成 URL -.. column:: +.. 列: ``` -This works just like [generating any other URL](/guide/basics/routing.md#generating-a-url), except that the class name is a part of the endpoint. +这就像[生成任何其它URL](/guide/basics/routing.md#generating-a-url)一样，只是类名称是端点的一部分。 ``` -.. column:: +.. 列: ```` ```python @app.route("/") def index(request): - url = app.url_for("SpecialClassView") + url = app. rl_for("SpecialClassView") return redirect(url) class SpecialClassView(HTTPMethodView): - def get(self, request): - return text("Hello from the Special Class View!") + def get(self, 请求: + 返回文本("您好，来自特殊类视图! -app.add_route(SpecialClassView.as_view(), "/special_class_view") +应用。 dd_route(SpecialClassView.as_view), "/special_class_view") ``` ```` From 5c949f277bfe15d0f9de31198be63fc7c2125649 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:02 +0200 Subject: [PATCH 286/698] New translations proxy-headers.md (Japanese) --- guide/content/ja/guide/advanced/proxy-headers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/guide/advanced/proxy-headers.md b/guide/content/ja/guide/advanced/proxy-headers.md index 4e9b45f87b..4aaca3d313 100644 --- a/guide/content/ja/guide/advanced/proxy-headers.md +++ b/guide/content/ja/guide/advanced/proxy-headers.md @@ -453,7 +453,7 @@ app.config.FORWARDED_SECRET = "mySecret" ##### 例10 -Unexpected termination should not lose existing acceptable values +予期しない終了は、既存の許容可能な値を失うことはありません ```sh curl localhost:8000/fwd \ @@ -493,7 +493,7 @@ app.config.FORWARDED_SECRET = "mySecret" ##### 例11 -Field normalization +フィールドの正規化 ```sh curl localhost:8000/fwd \ @@ -536,7 +536,7 @@ app.config.FORWARDED_SECRET = "mySecret" ##### 例12 -Using "by" field as secret +「by」フィールドを秘密として使用する ```sh curl localhost:8000/fwd \ From c6816fdc76227e0e65b83f2f4ff05c3d47ea79ad Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:04 +0200 Subject: [PATCH 287/698] New translations proxy-headers.md (Chinese Simplified) --- .../zh/guide/advanced/proxy-headers.md | 286 +++++++++--------- 1 file changed, 143 insertions(+), 143 deletions(-) diff --git a/guide/content/zh/guide/advanced/proxy-headers.md b/guide/content/zh/guide/advanced/proxy-headers.md index ff151b592b..557a701d34 100644 --- a/guide/content/zh/guide/advanced/proxy-headers.md +++ b/guide/content/zh/guide/advanced/proxy-headers.md @@ -1,68 +1,68 @@ -# Proxy configuration +# 代理配置 -When you use a reverse proxy server (e.g. nginx), the value of `request.ip` will contain the IP of a proxy, typically `127.0.0.1`. Almost always, this is **not** what you will want. +当您使用反向代理服务器 (例如nginx) 时，`request.ip` 的值将包含代理的 IP，通常是 `127.0.0.1` 。 几乎总是**不是**你想要的。 -Sanic may be configured to use proxy headers for determining the true client IP, available as `request.remote_addr`. The full external URL is also constructed from header fields _if available_. +Sanic 可能被配置为使用代理头来确定真正的客户端 IP，可用于“request.remote_addr”。 完整的外部 URL 也是从标题字段 _如果可用的话_构建的。 -.. tip:: Heads up +.. 提示：浮动通知 ``` -Without proper precautions, a malicious client may use proxy headers to spoof its own IP. To avoid such issues, Sanic does not use any proxy headers unless explicitly enabled. +如果没有适当的防范措施，恶意客户可能会使用代理头来歪曲自己的IP。 为了避免这种问题，除非明确启用，否则Sanic不会使用任何代理标题。 ``` -.. column:: +.. 列: ``` -Services behind reverse proxies must configure one or more of the following [configuration values](/guide/deployment/configuration.md): +逆向代理后面的服务必须配置以下[配置值](/guide/deplement/configuration.md): - `FORWARDED_SECRET` - `REAL_IP_HEADER` - `PROXIES_COUNT` ``` -.. column:: +.. 列: ```` ```python -app.config.FORWARDED_SECRET = "super-duper-secret" +app.config.FORWARDED_SECRET = "超级duper-secret" app.config.REAL_IP_HEADER = "CF-Connecting-IP" -app.config.PROXIES_COUNT = 2 +app.config.PROXIEs_COUNT = 2 ``` ```` -## Forwarded header +## 转发标题 -In order to use the `Forwarded` header, you should set `app.config.FORWARDED_SECRET` to a value known to the trusted proxy server. The secret is used to securely identify a specific proxy server. +为了使用 `Forwarded` 标题，您应该将 `app.config.FORWARDED_SECRET` 设置为信任的代理服务器已知的值。 此密钥用于安全识别特定代理服务器。 -Sanic ignores any elements without the secret key, and will not even parse the header if no secret is set. +神秘忽略任何没有密钥的元素，如果没有设置秘密，甚至不会解析标题。 -All other proxy headers are ignored once a trusted forwarded element is found, as it already carries complete information about the client. +所有其它代理头在找到可信任的转发元素时被忽略，因为它已经包含了有关客户端的完整信息。 -To learn more about the `Forwarded` header, read the related [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) and [Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) articles. +若要了解更多关于 `Forwarded` 标题，请阅读相关的 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) 和 [Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) 文章。 -## Traditional proxy headers +## 传统代理信头 -### IP Headers +### IP 头 -When your proxy forwards you the IP address in a known header, you can tell Sanic what that is with the `REAL_IP_HEADER` config value. +当你的代理转发你已知的标题中的 IP 地址时，你可以告诉Sanic 什么是 `REAL_IP_HEADER` 配置值。 -### X-Forwarded-For +### X-转发-输入 -This header typically contains a chain of IP addresses through each layer of a proxy. Setting `PROXIES_COUNT` tells Sanic how deep to look to get an actual IP address for the client. This value should equal the _expected_ number of IP addresses in the chain. +此页眉通常包含一个通过代理服务器的每层IP地址链。 设置 `PROXIES_COUNT` 告诉Sanic寻找客户端的实际IP地址。 此值应等于 _expected_number 的 IP 地址。 -### Other X-headers +### 其他X-headers -If a client IP is found by one of these methods, Sanic uses the following headers for URL parts: +如果客户端IP找到这些方法之一，Sanic对URL部分使用以下标题： -- x-forwarded-proto -- x-forwarded-host -- x-forwarded-port -- x-forwarded-path -- x-scheme +- x-转发-proto +- x转发主机 +- x转发端口 +- x转发路径 +- x 方案 -## Examples +## 示例： -In the following examples, all requests will assume that the endpoint looks like this: +在下面的例子中，所有请求都将假定终点看起来像这样： ```python @app.route("/fwd") @@ -80,20 +80,20 @@ async def forwarded(request): *** -##### Example 1 +##### 例1 -Without configured FORWARDED_SECRET, x-headers should be respected +如果没有配置FORWARDED_SECRET, X-headers 应该受到尊重。 ```sh curl localhost:8000/fwd \ - -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ - -H "X-Real-IP: 127.0.0.2" \ - -H "X-Forwarded-For: 127.0.1.1" \ - -H "X-Scheme: ws" \ - -H "Host: local.site" | jq + -H 'Forwar: for=1.1.1, for=injected;host="[:2]";proto=https://;host=me.tld;path="/app/";secret=mySecret,for=brochen;secret=b0rked, for=127。 .0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" + -H "X-For: 127.0.1" + - H "X-Scheme: w" + - H "Host: local.site" | jq ``` -.. column:: +.. 列: ```` ```python @@ -103,18 +103,18 @@ app.config.REAL_IP_HEADER = "x-real-ip" ``` ```` -.. column:: +.. 列: ```` ```bash -# curl response -{ - "remote_addr": "127.0.0.2", +# curl replacement +Paper + "remote_addr": "127.0.0.0.2", "scheme": "ws", - "server_name": "local.site", + "server_name": "local. ite”, "server_port": 80, - "forwarded": { - "for": "127.0.0.2", + "forwarded": 许诺, + "for": "127. .0.2", "proto": "ws" } } @@ -123,20 +123,20 @@ app.config.REAL_IP_HEADER = "x-real-ip" *** -##### Example 2 +##### 例2 -FORWARDED_SECRET now configured +FORWARDED_SECRET 已配置 ```sh curl localhost:8000/fwd \ - -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ - -H "X-Real-IP: 127.0.0.2" \ - -H "X-Forwarded-For: 127.0.1.1" \ - -H "X-Scheme: ws" \ - -H "Host: local.site" | jq + -H 'Forwar: for=1.1.1, for=injected;host="[:2]";proto=https://;host=me.tld;path="/app/";secret=mySecret,for=brochen;secret=b0rked, for=127。 .0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" + -H "X-For: 127.0.1" + - H "X-Scheme: w" + - H "Host: local.site" | jq ``` -.. column:: +.. 列: ```` ```python @@ -147,7 +147,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash @@ -170,19 +170,19 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 3 +##### 例3 -Empty Forwarded header -> use X-headers +空转发头 -> 使用 X-headers ```sh curl localhost:8000/fwd \ -H "X-Real-IP: 127.0.0.2" \ - -H "X-Forwarded-For: 127.0.1.1" \ - -H "X-Scheme: ws" \ + -H "X-For: 127.0.1" \ + -H "X-Scheme: w" -H "Host: local.site" | jq ``` -.. column:: +.. 列: ```` ```python @@ -193,18 +193,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash -# curl response -{ - "remote_addr": "127.0.0.2", +# curl replacement +Paper + "remote_addr": "127.0.0.0.2", "scheme": "ws", - "server_name": "local.site", + "server_name": "local. ite”, "server_port": 80, - "forwarded": { - "for": "127.0.0.2", + "forwarded": 许诺, + "for": "127. .0.2", "proto": "ws" } } @@ -213,16 +213,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 4 +##### 例4 -Header present but not matching anything +页眉已存在，但不匹配任何内容 ```sh curl localhost:8000/fwd \ - -H "Forwarded: nomatch" | jq + -H "Forwar: nomatch" | jq ``` -.. column:: +.. 列: ```` ```python @@ -233,12 +233,12 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash # curl response -{ +Power "remote_addr": "", "scheme": "http", "server_name": "localhost", @@ -251,17 +251,17 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 5 +##### 例5 -Forwarded header present but no matching secret -> use X-headers +转发头，但没有匹配的密钥 -> 使用 X-headers ```sh curl localhost:8000/fwd \ - -H "Forwarded: for=1.1.1.1;secret=x, for=127.0.0.1" \ + -H "Forwar: for=1.1.1;secret=x, for=127.0.0.1" -H "X-Real-IP: 127.0.0.2" | jq ``` -.. column:: +.. 列: ```` ```python @@ -272,18 +272,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash -# curl response -{ - "remote_addr": "127.0.0.2", +# curl reply +Power + "remote_addr": "127.0.0.0 ", "scheme": "http", "server_name": "localhost", "server_port": 8000, - "forwarded": { - "for": "127.0.0.2" + "forwarded": 许诺, + "for": "127. 0.2" } } ``` @@ -291,16 +291,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 6 +##### 例6 -Different formatting and hitting both ends of the header +不同格式化并击中标题两端的标题 ```sh curl localhost:8000/fwd \ - -H 'Forwarded: Secret="mySecret";For=127.0.0.4;Port=1234' | jq + -H 'Forward: Secret="mysecret";For=127.0.0.4;Port=1234' | jq ``` -.. column:: +.. 列: ```` ```python @@ -311,19 +311,19 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash -# curl response -{ - "remote_addr": "127.0.0.4", +# curl reply +Power + "remote_addr": "127.0.0.0 ", "scheme": "http", "server_name": "localhost", "server_port": 1234, - "forwarded": { - "secret": "mySecret", - "for": "127.0.0.4", + "forwarded": Power + "secret": "mysecret", + "for": "127. .0.4", "port": 1234 } } @@ -332,16 +332,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 7 +##### 例7 -Test escapes (modify this if you see anyone implementing quoted-pairs) +测试逃逸(如果你看到有人正在执行引用的对等内容，请修改此选项) ```sh curl localhost:8000/fwd \ - -H 'Forwarded: for=test;quoted="\,x=x;y=\";secret=mySecret' | jq + -H 'Forwar: for=test;quoted="\,x=x;y=\";secret=mysecret' | jq ``` -.. column:: +.. 列: ```` ```python @@ -352,20 +352,20 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash -# curl response -{ +# curl replacement +Paper "remote_addr": "test", "scheme": "http", "server_name": "localhost", "server_port": 8000, - "forwarded": { + "forwarded": 许诺, "for": "test", - "quoted": "\\,x=x;y=\\", - "secret": "mySecret" + "quoted": "\,x=x; =\\", + "secret": "mysecret" } } ``` @@ -373,16 +373,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 8 +##### 例8 -Secret insulated by malformed field #1 +由格式错误的字段 #1 隔绝的绝密项 ```sh curl localhost:8000/fwd \ - -H 'Forwarded: for=test;secret=mySecret;b0rked;proto=wss;' | jq + -H 'Forwar: for=test;secret=mySecret;b0rked;proto=wss;' | jq ``` -.. column:: +.. 列: ```` ```python @@ -393,7 +393,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash @@ -413,16 +413,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 9 +##### 例9 -Secret insulated by malformed field #2 +由格式不正确的字段 #2 隔热绝的密钥 ```sh curl localhost:8000/fwd \ - -H 'Forwarded: for=test;b0rked;secret=mySecret;proto=wss' | jq + -H 'Forwar: for=test;b0rked;secret=mySecret;proto=wss' | jq ``` -.. column:: +.. 列: ```` ```python @@ -433,18 +433,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash # curl response -{ +WP "remote_addr": "", "scheme": "wss", "server_name": "localhost", "server_port": 8000, - "forwarded": { - "secret": "mySecret", + "forwarded": 许诺 + "secret": "mysecret", "proto": "wss" } } @@ -453,16 +453,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 10 +##### 例10 -Unexpected termination should not lose existing acceptable values +意外终止不应丢失现有可接受的值 ```sh curl localhost:8000/fwd \ - -H 'Forwarded: b0rked;secret=mySecret;proto=wss' | jq + -H 'Forwar: b0rked;secret=mySecret;proto=wss' | jq ``` -.. column:: +.. 列: ```` ```python @@ -473,18 +473,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash # curl response -{ +WP "remote_addr": "", "scheme": "wss", "server_name": "localhost", "server_port": 8000, - "forwarded": { - "secret": "mySecret", + "forwarded": 许诺 + "secret": "mysecret", "proto": "wss" } } @@ -493,16 +493,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 11 +##### 例11 -Field normalization +实地正常化 ```sh curl localhost:8000/fwd \ -H 'Forwarded: PROTO=WSS;BY="CAFE::8000";FOR=unknown;PORT=X;HOST="A:2";PATH="/With%20Spaces%22Quoted%22/sanicApp?key=val";SECRET=mySecret' | jq ``` -.. column:: +.. 列: ```` ```python @@ -513,22 +513,22 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. column:: +.. 列: ```` ```bash # curl response -{ +Power "remote_addr": "", "scheme": "wss", "server_name": "a", "server_port": 2, - "forwarded": { - "proto": "wss", - "by": "[cafe::8000]", - "host": "a:2", - "path": "/With Spaces\"Quoted\"/sanicApp?key=val", - "secret": "mySecret" + "转发": Power + "原始": "wss", + "by": "[cafe:8000]", + "主机": "a:2", + "路径": "/With Spaces\"Quoted\"/sanicApp? ey=val", + "secret": "mysecret" } } ``` @@ -536,16 +536,16 @@ app.config.FORWARDED_SECRET = "mySecret" *** -##### Example 12 +##### 例12 -Using "by" field as secret +使用“by”字段作为密钥 ```sh curl localhost:8000/fwd \ - -H 'Forwarded: for=1.2.3.4; by=_proxySecret' | jq + -H 'Forward: for=1.2.3.4; by=_proxySecret' | jq ``` -.. column:: +.. 列: ```` ```python @@ -556,18 +556,18 @@ app.config.FORWARDED_SECRET = "_proxySecret" ``` ```` -.. column:: +.. 列: ```` ```bash # curl response -{ - "remote_addr": "1.2.3.4", +Power + "remote_addr": "1.2.3。 ", "scheme": "http", "server_name": "localhost", "server_port": 8000, - "forwarded": { - "for": "1.2.3.4", + "forwarded": 许诺, + "for": "1. .3.4", "by": "_proxySecret" } } From bcf893dd99d4d0bab90bf35ebd142b17e840305b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:05 +0200 Subject: [PATCH 288/698] New translations signals.md (Japanese) --- guide/content/ja/guide/advanced/signals.md | 164 ++++++++++----------- 1 file changed, 82 insertions(+), 82 deletions(-) diff --git a/guide/content/ja/guide/advanced/signals.md b/guide/content/ja/guide/advanced/signals.md index 43e2849ced..16a24871cf 100644 --- a/guide/content/ja/guide/advanced/signals.md +++ b/guide/content/ja/guide/advanced/signals.md @@ -29,40 +29,40 @@ async def handle_registration(request): ```` ```python async def my_signal_handler(): - print("something happened") + print("何かが起こった") -app.add_signal(my_signal_handler, "something.happened.ohmy") +app.add_signal(my_signal_handler, "something.happed.ohmy") ``` ```` -.. column:: +.. 列:: ``` -But, perhaps a slightly more convenient method is to use the built-in decorators. +しかし、おそらくもう少し便利な方法は、組み込みのデコレータを使用することです。 ``` -.. column:: +.. 列:: ```` ```python @app.signal("something.happened.ohmy") async def my_signal_handler(): - print("something happened") + print("something") ``` ```` -.. column:: +.. 列:: ``` -If the signal requires conditions, make sure to add them while adding the handler. +シグナルに条件(conditions)が必要な場合は、ハンドラを追加する際に必ず追加してください。 ``` -.. column:: +.. 列:: ```` ```python async def my_signal_handler1(): - print("something happened") + print("何かが起こった") app.add_signal( my_signal_handler, @@ -72,17 +72,17 @@ app.add_signal( @app.signal("something.happened.ohmy2", conditions={"some_condition": "value"}) async def my_signal_handler2(): - print("something happened") + print("何かが起こった") ``` ```` -.. column:: +.. 列:: ``` -Signals can also be declared on blueprints +シグナルはblueprintsで宣言することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -90,74 +90,74 @@ bp = Blueprint("foo") @bp.signal("something.happened.ohmy") async def my_signal_handler(): - print("something happened") + print("何かが起こった") ``` ```` -## Built-in signals +## ビルトインシグナル -In addition to creating a new signal, there are a number of built-in signals that are dispatched from Sanic itself. These signals exist to provide developers with more opportunities to add functionality into the request and server lifecycles. +新しいシグナルを作成することに加えて、Sanic自体からディスパッチされる組み込みシグナルがいくつかあります。 これらのシグナルは、開発者に要求とサーバーのライフサイクルに機能を追加する機会を増やすために存在します。 -_Added in v21.9_ +_v21.9で追加_ .. column:: ``` -You can attach them just like any other signal to an application or blueprint instance. +他のシグナルと同じように、アプリケーションまたはブループリントインスタンスにアタッチできます。 ``` .. column:: ```` ```python -@app.signal("http.lifecycle.complete") +@app.signal("http.lifycle.complete") async def my_signal_handler(conn_info): print("Connection has been closed") ``` ```` -These signals are the signals that are available, along with the arguments that the handlers take, and the conditions that attach (if any). - -| Event name | Arguments | Conditions | -| -------------------------- | ------------------------------- | --------------------------------------------------------- | -| `http.routing.before` | request | | -| `http.routing.after` | request, route, kwargs, handler | | -| `http.handler.before` | request | | -| `http.handler.after` | request | | -| `http.lifecycle.begin` | conn_info | | -| `http.lifecycle.read_head` | head | | -| `http.lifecycle.request` | request | | -| `http.lifecycle.handle` | request | | -| `http.lifecycle.read_body` | body | | -| `http.lifecycle.exception` | request, exception | | -| `http.lifecycle.response` | request, response | | -| `http.lifecycle.send` | data | | -| `http.lifecycle.complete` | conn_info | | -| `http.middleware.before` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | -| `http.middleware.after` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | -| `server.exception.report` | app, exception | | -| `server.init.before` | app, loop | | -| `server.init.after` | app, loop | | -| `server.shutdown.before` | app, loop | | -| `server.shutdown.after` | app, loop | | - -Version 22.9 added `http.handler.before` and `http.handler.after`. - -Version 23.6 added `server.exception.report`. +これらのシグナルは、ハンドラが取る引数、およびアタッチする条件(存在する場合)とともに、利用可能なシグナルです。 + +| イベント名 | 引数 | 条件 | +| ------------------------- | ------------------------------- | ---------------------------------------------------------- | +| `http.routing.before` | request | | +| `http.routing.after` | request, route, kwargs, handler | | +| `http.handler.before` | request | | +| `http.handler.after` | request | | +| `http.lifycle.begin` | conn_info | | +| `http.lifycle.read_head` | head | | +| `http.lifycle.request` | request | | +| `http.lifycle.handle` | request | | +| `http.lifycle.read_body` | body | | +| `http.lifycle.exception` | request, exception | | +| `http.lifycle.response` | request, response | | +| `http.lifycle.send` | data | | +| `http.lifycle.complete` | conn_info | | +| `http.middleware.before` | request, response | `{"attach_to": "request"}` または `{"attach_to": "response"}` | +| `http.middleware.after` | request, response | `{"attach_to": "request"}` または `{"attach_to": "response"}` | +| `server.exception.report` | app, exception | | +| `server.init.before` | app, loop | | +| `server.init.after` | app, loop | | +| `server.shutdown.before` | app, loop | | +| `server.shutdown.after` | app, loop | | + +バージョン22.9で`http.handler.before`と`http.handler.after`が追加されました。 + +バージョン23.6で`server.exception.report`が追加されました。 .. column:: ``` -To make using the built-in signals easier, there is an `Enum` object that contains all of the allowed built-ins. With a modern IDE this will help so that you do not need to remember the full list of event names as strings. +ビルトインシグナルを使いやすくするために、許可されたビルトインをすべて含む `Enum` オブジェクトが用意されています。 最近の IDE では、イベント名の完全なリストを文字列として覚えておく必要がないので、これは便利です。 -*Added in v21.12* +*v21.12で追加* ``` .. column:: ```` ```python -from sanic.signals import Event +from sanic.signal import Event @app.signal(Event.HTTP_LIFECYCLE_COMPLETE) async def my_signal_handler(conn_info): @@ -165,12 +165,12 @@ async def my_signal_handler(conn_info): ``` ```` -## Events +## イベント .. column:: ``` -Signals are based off of an _event_. An event, is simply a string in the following pattern: +シグナルは _event_ に基づいています。イベントは以下のパターンの単なる文字列です。 ``` .. column:: @@ -181,22 +181,22 @@ namespace.reference.action ``` ```` -.. tip:: Events must have three parts. If you do not know what to use, try these patterns: +.. tip:: イベントには3つの部分が必要です。 何を使っていいかわからない場合は、次のパターンを試してみてください。 ``` - `my_app.something.happened` - `sanic.notice.hello` ``` -### Event parameters +### イベントパラメータ .. column:: ``` -An event can be "dynamic" and declared using the same syntax as [path parameters](../basics/routing.md#path-parameters). This allows matching based upon arbitrary values. +イベントは「動的」であり、[pathパラメータ](../basics/routing.md#path-parameters)と同じ構文を使用して宣言できます。これにより、任意の値に基づいてマッチングできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -207,25 +207,25 @@ async def signal_handler(thing): @app.get("/") async def trigger(request): await app.dispatch("foo.bar.baz") - return response.text("Done.") + return response.text("完了。") ``` ```` -Checkout [path parameters](../basics/routing.md#path-parameters) for more information on allowed type definitions. +利用可能な型定義に関する詳細は[pathパラメータ](../basics/routing.md#path-parameters)を参照してください。 -.. info:: Only the third part of an event (the action) may be dynamic: +.. info:: イベントの3番目の部分(アクション)のみが動的です。 ``` - `foo.bar.` 🆗 - `foo..baz` ❌ ``` -### Waiting +### 待つ .. column:: ``` -In addition to executing a signal handler, your application can wait for an event to be triggered. +アプリケーションは、シグナルハンドラを実行するだけでなく、イベントがトリガーされるのを待つこともできます。 ``` .. column:: @@ -239,7 +239,7 @@ await app.event("foo.bar.baz") .. column:: ``` -**IMPORTANT**: waiting is a blocking function. Therefore, you likely will want this to run in a [background task](../basics/tasks.md). +**重要**: 待つことはブロッキング機能です。したがって、これを[バックグラウンドタスク](../basics/tasks.md)で実行する必要があります。 ``` .. column:: @@ -248,9 +248,9 @@ await app.event("foo.bar.baz") ```python async def wait_for_event(app): while True: - print("> waiting") + print("> 待機中") await app.event("foo.bar.baz") - print("> event found\n") + print("> イベント発見\n") @app.after_server_start async def after_server_start(app, loop): @@ -261,7 +261,7 @@ async def after_server_start(app, loop): .. column:: ``` -If your event was defined with a dynamic path, you can use `*` to catch any action. +イベントが動的パスで定義されている場合は、`*`を使用して任意のアクションをキャッチできます。 ``` .. column:: @@ -276,17 +276,17 @@ await app.event("foo.bar.*") ``` ```` -## Dispatching +## ディスパッチ -_In the future, Sanic will dispatch some events automatically to assist developers to hook into life cycle events._ +_将来的には、Sanicは開発者がライフサイクルイベントに参加するのを支援するために、いくつかのイベントを自動的にディスパッチするようになります。_ .. column:: ``` -Dispatching an event will do two things: +イベントをディスパッチすると、2つのことを行います。 -1. execute any signal handlers defined on the event, and -2. resolve anything that is "waiting" for the event to complete. +1. イベントで定義されたシグナルハンドラを実行し、 +2. イベントが完了するまで「待っている」ことをすべて解決します。 ``` .. column:: @@ -304,12 +304,12 @@ thing=baz ``` ```` -### Context +### コンテキスト .. column:: ``` -Sometimes you may find the need to pass extra information into the signal handler. In our first example above, we wanted our email registration process to have the email address for the user. +シグナルハンドラに追加情報を渡す必要がある場合があります。 上記の最初の例では、ユーザーのメールアドレスを持つようにメール登録プロセスを望んでいました。 ``` .. column:: @@ -330,20 +330,20 @@ await app.dispatch( ``` ```` -.. tip:: FYI +.. tip:: 参考 ``` -Signals are dispatched in a background task. +シグナルはバックグラウンドタスクでディスパッチされます。 ``` ### Blueprints -Dispatching blueprint signals works similar in concept to [middleware](../basics/middleware.md). Anything that is done from the app level, will trickle down to the blueprints. However, dispatching on a blueprint, will only execute the signals that are defined on that blueprint. +Blueprintシグナルのディスパッチは、[ミドルウェア](../basics/middleware.md)と同様に機能します。 appレベルから行われるシグナルは、blueprintにも伝播します。 ただし、blueprintでディスパッチすると、そのblueprintで定義されているシグナルのみが実行されます。 .. column:: ``` -Perhaps an example is easier to explain: +おそらく、例は説明しやすいでしょう: ``` .. column:: @@ -370,7 +370,7 @@ def bp_signal(): .. column:: ``` -Running `app.dispatch("foo.bar.baz")` will execute both signals. +`app.dispatch("foo.bar.baz")`を実行すると、両方のシグナルが実行されます。 ``` .. column:: @@ -379,14 +379,14 @@ Running `app.dispatch("foo.bar.baz")` will execute both signals. ```python await app.dispatch("foo.bar.baz") assert app_counter == 1 -assert bp_counter == 1 +assertt bp_counter == 1 ``` ```` .. column:: ``` -Running `bp.dispatch("foo.bar.baz")` will execute only the blueprint signal. +`bp.dispatch("foo.bar.baz")`を実行すると、Blueprintシグナルのみが実行されます。 ``` .. column:: @@ -394,7 +394,7 @@ Running `bp.dispatch("foo.bar.baz")` will execute only the blueprint signal. ```` ```python await bp.dispatch("foo.bar.baz") -assert app_counter == 1 -assert bp_counter == 2 +assertt app_counter == 1 +assertt bp_counter == 2 ``` ```` From 41599b9420616f3d05069cb88d75f3bc02d239bd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:08 +0200 Subject: [PATCH 289/698] New translations signals.md (Chinese Simplified) --- guide/content/zh/guide/advanced/signals.md | 284 ++++++++++----------- 1 file changed, 142 insertions(+), 142 deletions(-) diff --git a/guide/content/zh/guide/advanced/signals.md b/guide/content/zh/guide/advanced/signals.md index 971582bb1e..c403988adc 100644 --- a/guide/content/zh/guide/advanced/signals.md +++ b/guide/content/zh/guide/advanced/signals.md @@ -1,63 +1,63 @@ -# Signals +# 信号 -Signals provide a way for one part of your application to tell another part that something happened. +信号为您的应用程序的一部分提供了一种方法来告诉另一个部分发生了一些事情。 ```python @app.signal("user.registration.created") async def send_registration_email(**context): - await send_email(context["email"], template="registration") + 等待 send_email(context["email"], template="registration") -@app.post("/register") +@app. ost("/register") async def handle_registration(request): - await do_registration(request) - await request.app.dispatch( - "user.registration.created", + 等待do_registration(request) + 等待请求。 pp.apparch( + "user.registration" 恢复了", context={"email": request.json.email} - }) +}) ``` -## Adding a signal +## 添加信号 -.. column:: +.. 列: ``` -The API for adding a signal is very similar to adding a route. +用于添加信号的 API 与添加路由非常相似。 ``` -.. column:: +.. 列: ```` ```python async def my_signal_handler(): - print("something happened") + print("发生了什么") -app.add_signal(my_signal_handler, "something.happened.ohmy") +app.add_signal(my_signal_handler, "something.oced.ohmy") ``` ```` -.. column:: +.. 列: ``` -But, perhaps a slightly more convenient method is to use the built-in decorators. +但也许一种略为方便的方法是使用内置装饰器。 ``` -.. column:: +.. 列: ```` ```python -@app.signal("something.happened.ohmy") -async def my_signal_handler(): - print("something happened") +@app.signal("something.semed.ohmy") +async def my_signal_handler(: + print("发生什么") ``` ```` -.. column:: +.. 列: ``` -If the signal requires conditions, make sure to add them while adding the handler. +如果信号需要条件，请确保在添加处理器时添加它们。 ``` -.. column:: +.. 列: ```` ```python @@ -76,104 +76,104 @@ async def my_signal_handler2(): ``` ```` -.. column:: +.. 列: ``` -Signals can also be declared on blueprints +信号也可以在蓝图上声明 ``` -.. column:: +.. 列: ```` ```python bp = Blueprint("foo") -@bp.signal("something.happened.ohmy") +@bp.signal("something.semed.ohmy") async def my_signal_handler(): - print("something happened") + print("发生什么") ``` ```` -## Built-in signals +## 内置信号 -In addition to creating a new signal, there are a number of built-in signals that are dispatched from Sanic itself. These signals exist to provide developers with more opportunities to add functionality into the request and server lifecycles. +除了发出新的信号外，还有一些内在信号是从萨尼克本身发出的。 这些信号的存在为开发者提供了更多的机会，可以将功能添加到请求和服务器的周期中。 -_Added in v21.9_ +\*添加于 v21.9 \* -.. column:: +.. 列: ``` -You can attach them just like any other signal to an application or blueprint instance. +您可以像其他任何信号一样将它们附加到应用程序或蓝图实例。 ``` -.. column:: +.. 列: ```` ```python @app.signal("http.lifecycle.complete") async def my_signal_handler(conn_info): - print("Connection has been closed") + print("连接已关闭") ``` ```` -These signals are the signals that are available, along with the arguments that the handlers take, and the conditions that attach (if any). +这些信号是现有的信号，以及处理者的论据和附加条件（如有）。 -| Event name | Arguments | Conditions | -| -------------------------- | ------------------------------- | --------------------------------------------------------- | -| `http.routing.before` | request | | -| `http.routing.after` | request, route, kwargs, handler | | -| `http.handler.before` | request | | -| `http.handler.after` | request | | -| `http.lifecycle.begin` | conn_info | | -| `http.lifecycle.read_head` | head | | -| `http.lifecycle.request` | request | | -| `http.lifecycle.handle` | request | | -| `http.lifecycle.read_body` | body | | -| `http.lifecycle.exception` | request, exception | | -| `http.lifecycle.response` | request, response | | -| `http.lifecycle.send` | data | | -| `http.lifecycle.complete` | conn_info | | -| `http.middleware.before` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | -| `http.middleware.after` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | -| `server.exception.report` | app, exception | | -| `server.init.before` | app, loop | | -| `server.init.after` | app, loop | | -| `server.shutdown.before` | app, loop | | -| `server.shutdown.after` | app, loop | | +| 事件名称 | 参数 | 条件 | +| -------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- | +| `http.routing.before` | 请求 | | +| `http.routing.after ` | 请求, 路由, kwargs, 处理程序 | | +| `http.handler.befor` | 请求 | | +| `http.handler.after ` | 请求 | | +| `http.lifecycle.begin` | conn_info | | +| `http.lifecycle.read_head` | 头部 | | +| `http.lifecycle.request` | 请求 | | +| `http.lifecycle.handle` | 请求 | | +| `http.lifecycle.read_body` | 正文内容 | | +| `http.lifecycle.excition` | 请求异常 | | +| `http.lifecycle.response` | 请求回复 | | +| `http.lifecycle.send` | 数据 | | +| `http.lifecycle.complete` | conn_info | | +| `http.midleware.before` | 请求回复 | \`{"attach_to": "request"}" 或 "{"attach_to": "response"}" | +| `http.midleware.after ` | 请求回复 | \`{"attach_to": "request"}" 或 "{"attach_to": "response"}" | +| `server.exception.report` | 应用，异常 | | +| `server.init.before` | 应用，循环 | | +| `server.init.after ` | 应用，循环 | | +| `server.shutdown.before` | 应用，循环 | | +| `server.shutdown.after ` | 应用，循环 | | -Version 22.9 added `http.handler.before` and `http.handler.after`. +22.9版本增加了`http.handler.before`和`http.handler.after`。 -Version 23.6 added `server.exception.report`. +版本23.6增加了“server.exception.report”。 -.. column:: +.. 列: ``` -To make using the built-in signals easier, there is an `Enum` object that contains all of the allowed built-ins. With a modern IDE this will help so that you do not need to remember the full list of event names as strings. +为了更容易使用内置信号，有一个 `Enum` 对象包含所有允许的内嵌。 使用现代IDE，这将有助于您不需要记住事件名称的完整列表作为字符串。 -*Added in v21.12* +*添加于 v21.12* ``` -.. column:: +.. 列: ```` ```python -from sanic.signals import Event +from sanic.signs import Event -@app.signal(Event.HTTP_LIFECYCLE_COMPLETE) +@app.signal(Event.HTTP_LIFECYCLE_COMPerTE) async def my_signal_handler(conn_info): - print("Connection has been closed") + print("连接已关闭") ``` ```` -## Events +## 事件 -.. column:: +.. 列: ``` -Signals are based off of an _event_. An event, is simply a string in the following pattern: +信号来自一个 _event_。事件只是以下模式中的一个字符串： ``` -.. column:: +.. 列: ```` ``` @@ -181,22 +181,22 @@ namespace.reference.action ``` ```` -.. tip:: Events must have three parts. If you do not know what to use, try these patterns: +.. 提示：事件必须有三个部分。 如果您不知道要使用什么，请尝试这些模式： ``` -- `my_app.something.happened` -- `sanic.notice.hello` +- `my_app.something.oced` +- `sanic.notific.hello` ``` -### Event parameters +### 事件参数 -.. column:: +.. 列: ``` -An event can be "dynamic" and declared using the same syntax as [path parameters](../basics/routing.md#path-parameters). This allows matching based upon arbitrary values. +事件可以是“动态”并声明使用与 [路径参数] (../basics/routing.md#path参数)相同的语法。这允许根据任意值进行匹配。 ``` -.. column:: +.. 列: ```` ```python @@ -204,92 +204,92 @@ An event can be "dynamic" and declared using the same syntax as [path parameters async def signal_handler(thing): print(f"[signal_handler] {thing=}") -@app.get("/") -async def trigger(request): - await app.dispatch("foo.bar.baz") - return response.text("Done.") +@appp. et("/") +async def 触发器(请求): + 等待app.prespatch("foo.bar.baz") + return response.text("完成") ``` ```` -Checkout [path parameters](../basics/routing.md#path-parameters) for more information on allowed type definitions. +签出[路径参数](../basics/routing.md#path参数)以获取关于允许类型定义的更多信息。 -.. info:: Only the third part of an event (the action) may be dynamic: +.. 信息：事件的第三部分 (动作) 可能是动态的： ``` - `foo.bar.` 🆗 - `foo..baz` ❌ ``` -### Waiting +### 等待中 -.. column:: +.. 列: ``` -In addition to executing a signal handler, your application can wait for an event to be triggered. +除了执行信号处理程序外，您的应用程序可以等待事件触发的时间。 ``` -.. column:: +.. 列: ```` ```python -await app.event("foo.bar.baz") -``` +等待app.event("foo.bar.baz") + ```` -.. column:: +.. 列: ``` -**IMPORTANT**: waiting is a blocking function. Therefore, you likely will want this to run in a [background task](../basics/tasks.md). +**IMPORTANT**：等待是一个阻止函数。因此，你很可能想要这个函数在[背景任务](../basics/tasks.md)中运行。 ``` -.. column:: +.. 列: ```` ```python async def wait_for_event(app): while True: - print("> waiting") - await app.event("foo.bar.baz") + print("> 等待") + 等待应用。 vent("foo.bar. 日") print("> event found\n") -@app.after_server_start -async def after_server_start(app, loop): +@app. fter_server_start +async def after _server_start(app, loop): app.add_task(wait_for_event(app)) ``` ```` -.. column:: +.. 列: ``` -If your event was defined with a dynamic path, you can use `*` to catch any action. +如果你的事件是用动态路径定义的，你可以使用 "*" 来捕捉任何动作。 ``` -.. column:: +.. 列: ```` ```python -@app.signal("foo.bar.") +@app.signal("foo.bar. ... -await app.event("foo.bar.*") +等待app.event("foo.bar.*") ``` ```` -## Dispatching +## 正在发送 -_In the future, Sanic will dispatch some events automatically to assist developers to hook into life cycle events._ +_今后，Sanic将自动发送一些事件以帮助开发人员将其绑定到生命周期活动中。_ -.. column:: +.. 列: ``` -Dispatching an event will do two things: +调度一个事件会做两个事情： -1. execute any signal handlers defined on the event, and -2. resolve anything that is "waiting" for the event to complete. +1，执行事件定义的任何信号处理和 +2。 解决“等待”事件完成的任何问题。 ``` -.. column:: +.. 列: ```` ```python @@ -297,22 +297,22 @@ Dispatching an event will do two things: async def foo_bar(thing): print(f"{thing=}") -await app.dispatch("foo.bar.baz") +等待app.appailch("foo.bar.baz") ``` ``` thing=baz ``` ```` -### Context +### 二. 背景 -.. column:: +.. 列: ``` -Sometimes you may find the need to pass extra information into the signal handler. In our first example above, we wanted our email registration process to have the email address for the user. +有时您可能会发现需要将额外信息传递到信号处理器。 在我们上面的第一个例子中，我们希望我们的电子邮件注册过程有用户的电子邮件地址。 ``` -.. column:: +.. 列: ```` ```python @@ -320,8 +320,8 @@ Sometimes you may find the need to pass extra information into the signal handle async def send_registration_email(**context): print(context) -await app.dispatch( - "user.registration.created", +等待应用。 ispatch( + "user.registration" 恢复了", context={"hello": "world"} ) ``` @@ -333,68 +333,68 @@ await app.dispatch( .. tip:: FYI ``` -Signals are dispatched in a background task. +在后台任务中发出信号。 ``` -### Blueprints +### 蓝图 -Dispatching blueprint signals works similar in concept to [middleware](../basics/middleware.md). Anything that is done from the app level, will trickle down to the blueprints. However, dispatching on a blueprint, will only execute the signals that are defined on that blueprint. +正在发送蓝图信号的概念与 [middleware]相似(../basics/midleware.md)。 从应用层面做的任何事情都会被推到蓝图。 然而，在蓝图上派遣部队只会执行该蓝图上所确定的信号。 -.. column:: +.. 列: ``` -Perhaps an example is easier to explain: +或许一个例子更容易解释： ``` -.. column:: +.. 列: ```` ```python bp = Blueprint("bp") -app_counter = 0 -bp_counter = 0 +app_count = 0 +bp_count = 0 -@app.signal("foo.bar.baz") +@app.signal("foo). ar.baz") def app_signal(): - nonlocal app_counter - app_counter += 1 + non-local app_count + app_count += 1 -@bp.signal("foo.bar.baz") +@bp. ignal("foo.bar.baz") def bp_signal(): - nonlocal bp_counter - bp_counter += 1 + non-local bp_count + bp_count += 1 ``` ```` -.. column:: +.. 列: ``` -Running `app.dispatch("foo.bar.baz")` will execute both signals. +正在运行 `app.appotich("foo.bar.baz")` 将执行两个信号。 ``` -.. column:: +.. 列: ```` ```python -await app.dispatch("foo.bar.baz") -assert app_counter == 1 -assert bp_counter == 1 +正在等待 app.appoquarch("foo.bar.baz") +确认app_count == 1 +申述bp_count == 1 ``` ```` -.. column:: +.. 列: ``` -Running `bp.dispatch("foo.bar.baz")` will execute only the blueprint signal. +运行 `bp.apparch("foo.bar.baz")` 只会执行蓝图信号。 ``` -.. column:: +.. 列: ```` ```python -await bp.dispatch("foo.bar.baz") -assert app_counter == 1 -assert bp_counter == 2 +等待bp.apparch("foo.bar.baz") +conflict app_count == 1 +conflict bp_count == 2 ``` ```` From c8ddab7ff23f451e7b03c4fe334ead4afcbe0073 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:09 +0200 Subject: [PATCH 290/698] New translations streaming.md (Japanese) --- guide/content/ja/guide/advanced/streaming.md | 48 ++++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/guide/content/ja/guide/advanced/streaming.md b/guide/content/ja/guide/advanced/streaming.md index 646e645137..71fb38b808 100644 --- a/guide/content/ja/guide/advanced/streaming.md +++ b/guide/content/ja/guide/advanced/streaming.md @@ -1,18 +1,18 @@ -# Streaming +# ストリーミング -## Request streaming +## ストリーミングのリクエスト -Sanic allows you to stream data sent by the client to begin processing data as the bytes arrive. +Sanicでは、クライアントから送信されたデータをストリーミングして、バイトが到着するとデータの処理を開始することができます。 .. column:: ``` -When enabled on an endpoint, you can stream the request body using `await request.stream.read()`. +エンドポイントで有効にすると、`await request.stream.read()`を使ってリクエストボディをストリーミングできます。 -That method will return `None` when the body is completed. +このメソッドは、ボディが完了すると`None`を返します。 ``` -.. column:: +.. 列:: ```` ```python @@ -34,7 +34,7 @@ class SimpleView(HTTPMethodView): .. column:: ``` -It also can be enabled with a keyword argument in the decorator... +また、デコレータのキーワード引数で有効にすることも... ``` .. column:: @@ -52,7 +52,7 @@ async def handler(request): .. column:: ``` -... or the `add_route()` method. +...`add_route()`メソッドを使うこともできます。 ``` .. column:: @@ -68,18 +68,18 @@ bp.add_route( ``` ```` -.. tip:: FYI +.. tip:: 参考 ``` -Only post, put and patch decorators have stream argument. +post、put、patchデコレータのみが stream 引数を持っています。 ``` -## Response streaming +## Response ストリーミング .. column:: ``` -Sanic allows you to stream content to the client. +Sanicでは、クライアントにコンテンツをストリーミングできます。 ``` .. column:: @@ -92,12 +92,12 @@ async def test(request): await response.send("foo,") await response.send("bar") - # Optionally, you can explicitly end the stream by calling: + # 以下の関数を呼び出して、ストリームを明示的に終了することもできます: await response.eof() ``` ```` -This is useful in situations where you want to stream content to the client that originates in an external service, like a database. For example, you can stream database records to the client with the asynchronous cursor that `asyncpg` provides. +これは、データベースのような外部サービスで発生するクライアントにコンテンツをストリーミングしたい場合に便利です。 たとえば、`asyncpg` が提供する非同期カーソルを使用して、データベースレコードをクライアントにストリーミングできます。 ```python @app.route("/") @@ -109,21 +109,21 @@ async def index(request): await response.send(record[0]) ``` -You can explicitly end a stream by calling `await response.eof()`. It a convenience method to replace `await response.send("", True)`. It should be called **one time** _after_ your handler has determined that it has nothing left to send back to the client. While it is _optional_ to use with Sanic server, if you are running Sanic in ASGI mode, then you **must** explicitly terminate the stream. +`await response.eof()` を呼び出すことで、ストリームを明示的に終了させることができます。 これは `await response.send("", True)` を置き換える便利なメソッドです。 ハンドラがクライアントに送り返すものが何も残っていないと判断した _後に_ **1度だけ** 呼び出されるべきです。 Sanic サーバーで使用するのは_任意_ですが、Sanic を ASGI モードで実行している場合は、ストリームを明示的に終了させる必要があります。 -_Calling `eof` became optional in v21.6_ +_v21.6_で`eof`を呼び出すことがオプションになりました -## File streaming +## ファイルストリーミング -.. column:: +.. 列:: ``` -Sanic provides `sanic.response.file_stream` function that is useful when you want to send a large file. It returns a `StreamingHTTPResponse` object and will use chunked transfer encoding by default; for this reason Sanic doesn’t add `Content-Length` HTTP header in the response. +Sanic は `sanic.response.file_stream` 関数を提供しており、大きなファイルを送信したいときに便利です。 `StreamingHTTPResponse` オブジェクトを返し、デフォルトではチャンクされた転送エンコーディングを使用します。このため、Sanicはレスポンスに`Content-Length` HTTPヘッダーを追加しません。 -A typical use case might be streaming an video file. +典型的なユースケースは、ビデオファイルをストリーミングすることでしょう。 ``` -.. column:: +.. 列:: ```` ```python @@ -141,13 +141,13 @@ async def handler_file_stream(request): ``` ```` -.. column:: +.. 列:: ``` -If you want to use the `Content-Length` header, you can disable chunked transfer encoding and add it manually simply by adding the `Content-Length` header. +`Content-Length` ヘッダーを使用したい場合は、チャンク付き転送エンコーディングを無効にし、`Content-Length` ヘッダーを追加するだけで手動で追加できます。 ``` -.. column:: +.. 列:: ```` ```python From 38af06823ebad537cdd616cc7023afff86cb0390 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:10 +0200 Subject: [PATCH 291/698] New translations streaming.md (Chinese Simplified) --- guide/content/zh/guide/advanced/streaming.md | 94 ++++++++++---------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/guide/content/zh/guide/advanced/streaming.md b/guide/content/zh/guide/advanced/streaming.md index 646e645137..d6956695ff 100644 --- a/guide/content/zh/guide/advanced/streaming.md +++ b/guide/content/zh/guide/advanced/streaming.md @@ -1,18 +1,18 @@ -# Streaming +# 流流 -## Request streaming +## 请求流 -Sanic allows you to stream data sent by the client to begin processing data as the bytes arrive. +Sanic 允许您在字节到达时开始处理客户端发送的数据。 -.. column:: +.. 列: ``` -When enabled on an endpoint, you can stream the request body using `await request.stream.read()`. +当在端点启用时，您可以使用 `request.stream.read()`。 -That method will return `None` when the body is completed. +这个方法将在身体完成后返回 `None` 。 ``` -.. column:: +.. 列: ```` ```python @@ -31,38 +31,38 @@ class SimpleView(HTTPMethodView): ``` ```` -.. column:: +.. 列: ``` -It also can be enabled with a keyword argument in the decorator... +它也可以在装饰器中用关键字参数启用... ``` -.. column:: +.. 列: ```` ```python @app.post("/stream", stream=True) async def handler(request): ... - body = await request.stream.read() + body = 等待request.stream.read() ... ``` ```` -.. column:: +.. 列: ``` -... or the `add_route()` method. +... 或 "add_route()" 方法。 ``` -.. column:: +.. 列: ```` ```python bp.add_route( bp_handler, "/bp_stream", - methods=["POST"], + meths=["POST"], stream=True, ) ``` @@ -71,59 +71,59 @@ bp.add_route( .. tip:: FYI ``` -Only post, put and patch decorators have stream argument. +只有帖子、放置和补丁装饰者有流参数。 ``` -## Response streaming +## 响应串流 -.. column:: +.. 列: ``` -Sanic allows you to stream content to the client. +Sanic 允许您将内容流到客户端。 ``` -.. column:: +.. 列: ```` ```python @app.route("/") async def test(request): - response = await request.respond(content_type="text/csv") - await response.send("foo,") - await response.send("bar") + response = request.reply (content_type="text/csv") + 等待响应。 end("foo,") + 正在等待答复。 end("bar") - # Optionally, you can explicitly end the stream by calling: - await response.eof() + # 可选，您可以通过调用来明确结束流： + 等待响应.eof() ``` ```` -This is useful in situations where you want to stream content to the client that originates in an external service, like a database. For example, you can stream database records to the client with the asynchronous cursor that `asyncpg` provides. +这在您想要将内容流到外部服务的客户端（如数据库）时是有用的。 例如，您可以通过 "asyncpg" 提供的异步光标将数据库记录流到客户端。 ```python @app.route("/") async def index(request): - response = await request.respond() - conn = await asyncpg.connect(database='test') - async with conn.transaction(): - async for record in conn.cursor('SELECT generate_series(0, 10)'): - await response.send(record[0]) + response = 等待请求。 espond() + conn = 等待 asyncpg.connect(database='test') + 带有con的异步值。 赎金(): + 异步以内嵌方式记录。 ursor('SELECT generate_series(0, 10)'): + 等待响应.send(records[0]) ``` -You can explicitly end a stream by calling `await response.eof()`. It a convenience method to replace `await response.send("", True)`. It should be called **one time** _after_ your handler has determined that it has nothing left to send back to the client. While it is _optional_ to use with Sanic server, if you are running Sanic in ASGI mode, then you **must** explicitly terminate the stream. +您可以通过调用 "等待响应.eof()" 来明确结束一个流。 它是一个替换"等待响应.send("", True)"的方便方法。 应该调用 **一次** 之后\* 你的处理程序确定它没有什么可以发送到客户端。 当它是可选的 \* 与 Sanic 服务器使用时，如果您在 ASGI 模式中运行 Sanic ，那么您**必须** 明确终止流。 -_Calling `eof` became optional in v21.6_ +_在 v21.6_ 中，调用 `eof` 变成可选的 -## File streaming +## 文件串流 -.. column:: +.. 列: ``` -Sanic provides `sanic.response.file_stream` function that is useful when you want to send a large file. It returns a `StreamingHTTPResponse` object and will use chunked transfer encoding by default; for this reason Sanic doesn’t add `Content-Length` HTTP header in the response. +Sanic 提供 `sanic.response.file_stream` 函数，在您想要发送一个大文件时是有用的。 它返回一个 `StreamingHTTPResponse` 对象，默认情况下将使用区块传输编码；因此Sanic 不在响应中添加 `Content-Length` HTTP头部。 -A typical use case might be streaming an video file. +典型的使用案例可能是将视频文件串流。 ``` -.. column:: +.. 列: ```` ```python @@ -141,29 +141,29 @@ async def handler_file_stream(request): ``` ```` -.. column:: +.. 列: ``` -If you want to use the `Content-Length` header, you can disable chunked transfer encoding and add it manually simply by adding the `Content-Length` header. +如果你想要使用 `Content-Length` 标题，你可以仅仅通过添加 `Content-Length` 标题来禁用区块传输编码并手动添加它。 ``` -.. column:: +.. 列: ```` ```python -from aiofiles import os as async_os +from aiofiles importos as async_os from sanic.response import file_stream -@app.route("/") +@app. oute("/") async def index(request): file_path = "/srv/www/whatever.png" - file_stat = await async_os.stat(file_path) - headers = {"Content-Length": str(file_stat.st_size)} + file_stat = 等待async_os. tat(file_path) + headers = {"Content-Length": str(file_stat. t_size)} - return await file_stream( + 返回等待文件流( file_path, headers=headers, - ) + ``` ```` From 253d911d118f125de85288b145dd074099f037f7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:12 +0200 Subject: [PATCH 292/698] New translations versioning.md (Japanese) --- guide/content/ja/guide/advanced/versioning.md | 74 +++++++++---------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/guide/content/ja/guide/advanced/versioning.md b/guide/content/ja/guide/advanced/versioning.md index 9225c23622..42120439fe 100644 --- a/guide/content/ja/guide/advanced/versioning.md +++ b/guide/content/ja/guide/advanced/versioning.md @@ -1,31 +1,31 @@ # Versioning -It is standard practice in API building to add versions to your endpoints. This allows you to easily differentiate incompatible endpoints when you try and change your API down the road in a breaking manner. +エンドポイントにバージョンを追加するためのAPI構築の標準的な方法です。 これにより、互換性のないエンドポイントを簡単に区別することができます。 -Adding a version will add a `/v{version}` url prefix to your endpoints. +バージョンを追加すると、`/v{version}`のURLプレフィックスがエンドポイントに追加されます。 -The version can be a `int`, `float`, or `str`. Acceptable values: +バージョンは `int` 、`float` 、または `str` です。 許容可能な値: - `1`, `2`, `3` - `1.1`, `2.25`, `3.0` -- `"1"`, `"v1"`, `"v1.1"` +- `"1"`、`"v1"`、`"v1.1"` -## Per route +## ルートごと -.. column:: +.. 列:: ``` -You can pass a version number to the routes directly. +バージョン番号をルートに直接渡すことができます。 ``` -.. column:: +.. 列:: ```` ```python # /v1/text @app.route("/text", version=1) def handle_request(request): - return response.text("Hello world! Version 1") + return response. ext("Hello world! Version 1") # /v2/text @app.route("/text", version=2) @@ -34,15 +34,15 @@ def handle_request(request): ``` ```` -## Per Blueprint +## 設計図ごと -.. column:: +.. 列:: ``` -You can also pass a version number to the blueprint, which will apply to all routes in that blueprint. +また、バージョン番号を blueprint に渡すこともできます。blueprint 内のすべてのルートに適用されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -51,13 +51,13 @@ bp = Blueprint("test", url_prefix="/foo", version=1) # /v1/foo/html @bp.route("/html") def handle_request(request): - return response.html("

Hello world!

") + return response.html(" "

Hello world!

") ``` ```` -## Per Blueprint Group +## ブループリントグループごと -.. column:: +.. 列:: ``` In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint @@ -75,7 +75,7 @@ If we find a more pointed versioning specification, we will pick that over the m provided under the Blueprint or Blueprint Group ``` -.. column:: +.. 列:: ```` ```python @@ -115,29 +115,29 @@ async def handle_endpoint_2_bp2(request): ``` ```` -## Version prefix +## バージョン接頭辞： -As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. +上記のように、ルートに適用される`version`は、生成されたURIパスの最初のセグメントである**常に**です。 したがって、バージョンの前にパスセグメントを追加するために、 `version` 引数が渡されるすべての場所を渡すことができます。`version_prefix` も渡すことができます。 -The `version_prefix` argument can be defined in: +引数 `version_prefix` は以下のように定義できます： -- `app.route` and `bp.route` decorators (and all the convenience decorators also) -- `Blueprint` instantiation -- `Blueprint.group` constructor -- `BlueprintGroup` instantiation -- `app.blueprint` registration +- `app.route` と `bp.route` デコレーター （そしてすべてのコンビニエンスデコレーターも） +- `Blueprint` インスタンス +- `Blueprint.group` コンストラクター +- `BlueprintGroup` インスタンス +- `app.blueprint` 登録 -If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. +複数の場所に定義がある場合、より具体的な定義はより一般的に優先されます。 このリストはその階層を提供します。 -The default value of `version_prefix` is `/v`. +`version_prefix` のデフォルト値は `/v` です。 -.. column:: +.. 列:: ``` -An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. +`/api` にバージョン管理されたルートをマウントできる機能がよくあります。これは `version_prefix` で簡単に実現できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -146,13 +146,13 @@ app.route("/my/path", version=1, version_prefix="/api/v") ``` ```` -.. column:: +.. 列:: ``` -Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. +おそらく、`/api` ルートを単一の `BlueprintGroup` にロードすることでしょう。 ``` -.. column:: +.. 列:: ```` ```python @@ -170,20 +170,20 @@ app.blueprint(api) ``` ```` -We can therefore learn that a route's URI is: +そのため、ルートのURIは以下のようになります。 ``` -version_prefix + version + url_prefix + URI definition +version_prefix + version + url_prefix + URI 定義 ``` .. tip:: ```` -Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. +`url_prefix` と同じように、 `version_prefix` 内でパスパラメータを定義することができます。 すべてのルートがハンドラにそのパラメータを注入することを覚えておいてください。 ```python version_prefix="//v" ``` ```` -_Added in v21.6_ +_V21.6_に追加されました From f388ac3c2c6eebb6b8f8035677d3d711db0d23e6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:13 +0200 Subject: [PATCH 293/698] New translations versioning.md (Chinese Simplified) --- guide/content/zh/guide/advanced/versioning.md | 91 +++++++++---------- 1 file changed, 45 insertions(+), 46 deletions(-) diff --git a/guide/content/zh/guide/advanced/versioning.md b/guide/content/zh/guide/advanced/versioning.md index 9225c23622..4999d9a2da 100644 --- a/guide/content/zh/guide/advanced/versioning.md +++ b/guide/content/zh/guide/advanced/versioning.md @@ -1,31 +1,31 @@ # Versioning -It is standard practice in API building to add versions to your endpoints. This allows you to easily differentiate incompatible endpoints when you try and change your API down the road in a breaking manner. +API 构建中的标准做法是将版本添加到您的端点。 这使您能够轻松区分不兼容的端点，当您尝试并以破解的方式更改您的 API。 Adding a version will add a `/v{version}` url prefix to your endpoints. -The version can be a `int`, `float`, or `str`. Acceptable values: +版本可以是 `int`、`float`、`str`。 可接受值： - `1`, `2`, `3` - `1.1`, `2.25`, `3.0` -- `"1"`, `"v1"`, `"v1.1"` +- `"1", `v1", `"v1.1"` -## Per route +## 每条路由 -.. column:: +.. 列: ``` -You can pass a version number to the routes directly. +您可以直接将版本号传递给路由。 ``` -.. column:: +.. 列: ```` ```python # /v1/text @app.route("/text", version=1) def handle_request(request): - return response.text("Hello world! Version 1") + return response. ext("Hello world! 版本 1") # /v2/text @app.route("/text", version=2) @@ -34,30 +34,30 @@ def handle_request(request): ``` ```` -## Per Blueprint +## 每个蓝图 -.. column:: +.. 列: ``` -You can also pass a version number to the blueprint, which will apply to all routes in that blueprint. +您也可以将版本号传递到蓝图，这将适用于该蓝图中的所有路线。 ``` -.. column:: +.. 列: ```` ```python -bp = Blueprint("test", url_prefix="/foo", version=1) +bp = Blueprint("test", url_prefix="/fo", version=1) -# /v1/foo/html +# /v1/fo/html @bp.route("/html") def handle_request(request): return response.html("

Hello world!

") ``` ```` -## Per Blueprint Group +## 每个蓝图组 -.. column:: +.. 列: ``` In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint @@ -75,69 +75,68 @@ If we find a more pointed versioning specification, we will pick that over the m provided under the Blueprint or Blueprint Group ``` -.. column:: +.. 列: ```` ```python -from sanic.blueprints import Blueprint -from sanic.response import json +从 sanic.blueprints 导入蓝图A.format@@1 esponse import json bp1 = Blueprint( name="blueprint-1", url_prefix="/bp1", - version=1.25, + version=1。 5 , ) bp2 = Blueprint( name="blueprint-2", url_prefix="/bp2", -) -group = Blueprint.group( + +group = Blueprint. 路由( [bp1, bp2], url_prefix="/bp-group", version="v2", ) -# GET /v1.25/bp-group/bp1/endpoint-1 -@bp1.get("/endpoint-1") +# GET /v1。 5/bp-group/bp1/endpoint-1 +@bp1。 et("/endpoint-1") async def handle_endpoint_1_bp1(request): - return json({"Source": "blueprint-1/endpoint-1"}) + return json({"Source": "bluprint-1/endpoint-1"}) # GET /v2/bp-group/bp2/endpoint-2 -@bp2.get("/endpoint-1") +@bp2. et("/endpoint-1") async def handle_endpoint_1_bp2(request): return json({"Source": "blueprint-2/endpoint-1"}) # GET /v1/bp-group/bp2/endpoint-2 -@bp2.get("/endpoint-2", version=1) +@bp2. et("/endpoint-2", version=1) async def handle_endpoint_2_bp2(request): return json({"Source": "blueprint-2/endpoint-2"}) ``` ```` -## Version prefix +## 版本前缀 -As seen above, the `version` that is applied to a route is **always** the first segment in the generated URI path. Therefore, to make it possible to add path segments before the version, every place that a `version` argument is passed, you can also pass `version_prefix`. +如上文所见，适用于路由的 `version` 总是生成的 URI 路径中的第一个部分。 因此，为了能够在版本之前添加路径段, 每个传递`version`参数的地方, 你也可以通过 `version_prefix`. -The `version_prefix` argument can be defined in: +`version_prefix`参数可以定义于： -- `app.route` and `bp.route` decorators (and all the convenience decorators also) -- `Blueprint` instantiation -- `Blueprint.group` constructor -- `BlueprintGroup` instantiation -- `app.blueprint` registration +- `app.route` 和 `bp.route` 装饰符 (也包括所有方便装饰师) +- `Blueprint` 实例 +- `Blueprint.group` 构造函数 +- `BlueprintGroup` 实例 +- `app.bluprint` 注册 -If there are definitions in multiple places, a more specific definition overrides a more general. This list provides that hierarchy. +如果在多个地方有定义，则更具体的定义优先于较一般的定义。 这个列表提供了这个等级。 -The default value of `version_prefix` is `/v`. +`version_prefix`的默认值是 `/v`。 -.. column:: +.. 列: ``` -An often requested feature is to be able to mount versioned routes on `/api`. This can easily be accomplished with `version_prefix`. +一个经常请求的功能是能够在`/api`上挂载版本路由。这可以很容易地通过`version_prefix`来完成。 ``` -.. column:: +.. 列: ```` ```python @@ -146,13 +145,13 @@ app.route("/my/path", version=1, version_prefix="/api/v") ``` ```` -.. column:: +.. 列: ``` -Perhaps a more compelling usage is to load all `/api` routes into a single `BlueprintGroup`. +或许一个更令人信服的用法是将所有的`/api`路由加载到一个单一的`蓝图组'。 ``` -.. column:: +.. 列: ```` ```python @@ -170,10 +169,10 @@ app.blueprint(api) ``` ```` -We can therefore learn that a route's URI is: +因此，我们可以了解到路由的 URI 是： ``` -version_prefix + version + url_prefix + URI definition +version_prefix + 版本 + url_prefix + URI 定义 ``` .. tip:: @@ -186,4 +185,4 @@ version_prefix="//v" ``` ```` -_Added in v21.6_ +\*添加于 v21.6 \* From d5fe0e2b4a7c5af6ef62d60c73de72d0022bd3a2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:14 +0200 Subject: [PATCH 294/698] New translations websockets.md (Japanese) --- guide/content/ja/guide/advanced/websockets.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/guide/content/ja/guide/advanced/websockets.md b/guide/content/ja/guide/advanced/websockets.md index 71e5b1dbfa..afba802505 100644 --- a/guide/content/ja/guide/advanced/websockets.md +++ b/guide/content/ja/guide/advanced/websockets.md @@ -1,16 +1,16 @@ # Websockets -Sanic provides an easy to use abstraction on top of [websockets](https://websockets.readthedocs.io/en/stable/). +Sanic は [websockets](https://websockets.readthedocs.io/en/stable/) の上に簡単に使える抽象化を提供します。 -## Routing +## ルーティング -.. column:: +.. 列:: ``` -Websocket handlers can be hooked up to the router similar to regular handlers. +Websocket ハンドラは、通常のハンドラと同様にルータにフックアップできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -32,7 +32,7 @@ async def feed(request: Request, ws: Websocket): ## Handler -.. column:: +.. 列:: ``` Typically, a websocket handler will want to hold open a loop. @@ -42,7 +42,7 @@ It can then use the `send()` and `recv()` methods on the second object injected This example is a simple endpoint that echos back to the client messages that it receives. ``` -.. column:: +.. 列:: ```` ```python @@ -59,15 +59,15 @@ async def feed(request: Request, ws: Websocket): ``` ```` -.. column:: +.. 列:: ``` -You can simplify your loop by just iterating over the `Websocket` object in a for loop. +forループ内の`Websocket`オブジェクトを繰り返すだけで、ループを簡素化できます。 -*Added in v22.9* +*v22.9*に追加されました ``` -.. column:: +.. 列:: ```` ```python @@ -80,9 +80,9 @@ async def feed(request: Request, ws: Websocket): ``` ```` -## Configuration +## 設定 -See [configuration section](/guide/deployment/configuration.md) for more details, however the defaults are shown below. +詳細は [configuration section](/guide/deployment/configuration.md) をご覧ください。 ```python app.config.WEBSOCKET_MAX_SIZE = 2 ** 20 From df71a615c37a826c4d6fc2317acab553838445dc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:16 +0200 Subject: [PATCH 295/698] New translations websockets.md (Chinese Simplified) --- guide/content/zh/guide/advanced/websockets.md | 66 +++++++++---------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/guide/content/zh/guide/advanced/websockets.md b/guide/content/zh/guide/advanced/websockets.md index 71e5b1dbfa..57d4c9c86c 100644 --- a/guide/content/zh/guide/advanced/websockets.md +++ b/guide/content/zh/guide/advanced/websockets.md @@ -1,65 +1,65 @@ # Websockets -Sanic provides an easy to use abstraction on top of [websockets](https://websockets.readthedocs.io/en/stable/). +Sanic 提供了一个易于使用的 [websockets]顶部的摘要(https\://websockets.readthedocs.io/en/stable/)。 -## Routing +## 路由 -.. column:: +.. 列: ``` -Websocket handlers can be hooked up to the router similar to regular handlers. +Websocket 处理程序可以绑定到路由器，类似于常规处理程序。 ``` -.. column:: +.. 列: ```` ```python from sanic import Request, Websocket -async def feed(request: Request, ws: Websocket): - pass +async def Feed(request: Request, ws: Websocket): + pask -app.add_websocket_route(feed, "/feed") +appp dd_websocket_route(feed, "/feed") ``` ```python from sanic import Request, Websocket -@app.websocket("/feed") -async def feed(request: Request, ws: Websocket): - pass +@app. ebsocket("/feed") +async def Feed(request, ws: Websocket): + passe ``` ```` ## Handler -.. column:: +.. 列: ``` -Typically, a websocket handler will want to hold open a loop. +通常情况下，一个 websocket 处理程序将会保持打开一个循环。 -It can then use the `send()` and `recv()` methods on the second object injected into the handler. +然后它可以在注入处理器的第二个对象上使用 `send()` 和 `recv()` 方法。 -This example is a simple endpoint that echos back to the client messages that it receives. +这个示例是一个简单的端点，回溯到它收到的客户端消息。 ``` -.. column:: +.. 列: ```` ```python -from sanic import Request, Websocket +来自sanic import Request, Websocket -@app.websocket("/feed") -async def feed(request: Request, ws: Websocket): +@app. ebsocket("/feed") +async def Feed(请求: 请求, ws: Websocket: while True: - data = "hello!" - print("Sending: " + data) - await ws.send(data) - data = await ws.recv() - print("Received: " + data) + data = "hello! + 打印("发送：" + 数据) + 等待ws。 end(data) + data = 等待ws。 ecv() + 打印("接收：" + 数据) ``` ```` -.. column:: +.. 列: ``` You can simplify your loop by just iterating over the `Websocket` object in a for loop. @@ -67,22 +67,22 @@ You can simplify your loop by just iterating over the `Websocket` object in a fo *Added in v22.9* ``` -.. column:: +.. 列: ```` ```python -from sanic import Request, Websocket +来自sanic import Request, Websocket -@app.websocket("/feed") -async def feed(request: Request, ws: Websocket): - async for msg in ws: - await ws.send(msg) +@app. ebsocket("/feed") +async def Feed(请求: 请求, ws: Websocket: + async for msg in w: + 等待w. end(msg) ``` ```` -## Configuration +## 配置 -See [configuration section](/guide/deployment/configuration.md) for more details, however the defaults are shown below. +详见[配置部分](/guide/deplement/configuration.md)，但默认值显示在下面。 ```python app.config.WEBSOCKET_MAX_SIZE = 2 ** 20 From dfca31939761658b12b9080d49239cf0f752c36b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:17 +0200 Subject: [PATCH 296/698] New translations readme.md (Japanese) --- guide/content/ja/guide/basics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/basics/README.md b/guide/content/ja/guide/basics/README.md index 25dcc52044..bb73f348aa 100644 --- a/guide/content/ja/guide/basics/README.md +++ b/guide/content/ja/guide/basics/README.md @@ -1 +1 @@ -# Basics +# 基本 From 5a9210622ba920c2d72adaa9a3abb85745bac935 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:18 +0200 Subject: [PATCH 297/698] New translations readme.md (Chinese Simplified) --- guide/content/zh/guide/basics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/basics/README.md b/guide/content/zh/guide/basics/README.md index 25dcc52044..bf31ab2555 100644 --- a/guide/content/zh/guide/basics/README.md +++ b/guide/content/zh/guide/basics/README.md @@ -1 +1 @@ -# Basics +# 基础知识 From 5b72d77d3cd7f12fee27884132099796955832f5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:20 +0200 Subject: [PATCH 298/698] New translations app.md (Japanese) --- guide/content/ja/guide/basics/app.md | 216 +++++++++++++-------------- 1 file changed, 108 insertions(+), 108 deletions(-) diff --git a/guide/content/ja/guide/basics/app.md b/guide/content/ja/guide/basics/app.md index 4cded1f51a..a02d7ede41 100644 --- a/guide/content/ja/guide/basics/app.md +++ b/guide/content/ja/guide/basics/app.md @@ -1,20 +1,20 @@ --- -title: Sanic Application +title: サニック・アプリケーション --- -# Sanic Application +# サニック・アプリケーション -See API docs: [sanic.app](/api/sanic.app) +API ドキュメント: [sanic.app](/api/sanic.app) を参照してください。 -## Instance +## インスタンス -.. column:: +.. 列:: ``` -The most basic building block is the :class:`sanic.app.Sanic` instance. It is not required, but the custom is to instantiate this in a file called `server.py`. +最も基本的なビルディングブロックは、 :class:`sanic.app.Sanic`インスタンスです。 これは必須ではありませんが、カスタムは `server.py` という名前のファイルでインスタンス化します。 ``` -.. column:: +.. 列:: ```` ```python @@ -26,17 +26,17 @@ app = Sanic("MyHelloWorldApp") ``` ```` -## Application context +## アプリケーションのコンテキスト -Most applications will have the need to share/reuse data or objects across different parts of the code base. Sanic helps be providing the `ctx` object on application instances. It is a free space for the developer to attach any objects or data that should existe throughout the lifetime of the application. +ほとんどのアプリケーションは、コードベースの異なる部分にわたってデータやオブジェクトを共有/再利用する必要があります。 Sanicはアプリケーションインスタンスに`ctx`オブジェクトを提供するのに役立ちます。 開発者がアプリケーションの寿命を通じて存在すべきあらゆるオブジェクトやデータを添付するための空き領域です。 -.. column:: +.. 列:: ``` -The most common pattern is to attach a database instance to the application. +最も一般的なパターンは、アプリケーションにデータベース・インスタンスをアタッチすることです。 ``` -.. column:: +.. 列:: ```` ```python @@ -45,13 +45,13 @@ app.ctx.db = Database() ``` ```` -.. column:: +.. 列:: ``` While the previous example will work and is illustrative, it is typically considered best practice to attach objects in one of the two application startup [listeners](./listeners). ``` -.. column:: +.. 列:: ```` ```python @@ -63,15 +63,15 @@ async def attach_db(app, loop): ``` ```` -## App Registry +## アプリのレジストリ -.. column:: +.. 列:: ``` -When you instantiate a Sanic instance, that can be retrieved at a later time from the Sanic app registry. This can be useful, for example, if you need to access your Sanic instance from a location where it is not otherwise accessible. +Sanicインスタンスをインスタンス化すると、Sanicアプリレジストリから後で取得できます。 たとえば、Sanicインスタンスにアクセスする必要がある場合には、Sanicインスタンスにアクセスできない場合などに便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -87,13 +87,13 @@ app = Sanic.get_app("my_awesome_server") ``` ```` -.. column:: +.. 列:: ``` -If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name. +存在しないアプリで `Sanic.get_app("non-existing")` を呼び出すと、 :class:`sanic.exceptions が発生します。 anicException`はデフォルトです。代わりに、その名前を持つSanicの新しいインスタンスを強制的に返すことができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -104,13 +104,13 @@ app = Sanic.get_app( ``` ```` -.. column:: +.. 列:: ``` -If there is **only one** Sanic instance registered, then calling `Sanic.get_app()` with no arguments will return that instance +Sanic インスタンスが登録されている場合は、引数のない`Sanic.get_app()`を呼び出すと、そのインスタンスが返されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -120,15 +120,15 @@ app = Sanic.get_app() ``` ```` -## Configuration +## 設定 -.. column:: +.. 列:: ``` -Sanic holds the configuration in the `config` attribute of the `Sanic` instance. Configuration can be modified **either** using dot-notation **OR** like a dictionary. +Sanicは`Sanic`インスタンスの`config`属性の設定を保持しています。設定は辞書のようにドット表記を使って**どちらか**変更できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -146,31 +146,31 @@ app.config.update(db_settings) ``` ```` -.. note:: Heads up +.. Note:: Heads Up ```` -Config keys _should_ be uppercase. But, this is mainly by convention, and lowercase will work most of the time. +設定キー _should_ は大文字ですが、これは主に規則によって行われ、小文字はほとんどの場合動作します。 ```python app.config.GOOD = "yay!" app.config.bad = "boo" ``` ```` -There is much [more detail about configuration](../running/configuration.md) later on. +後ほど、format@@0(../running/configuration.md) があります。 -## Factory pattern +## 出荷時のパターン -Many of the examples in these docs will show the instantiation of the :class:`sanic.app.Sanic` instance in a file called `server.py` in the "global scope" (i.e. not inside a function). This is a common pattern for very simple "hello world" style applications, but it is often beneficial to use a factory pattern instead. +これらのドキュメントの多くの例では、 :class:`sanic.appのインスタンス化が表示されます。 グローバルスコープ内の `server.py` というファイル内の anic` インスタンス（すなわち関数内ではない）。 これは非常に単純な "hello world" スタイルのアプリケーションでは一般的なパターンですが、代わりにファクトリパターンを使用することはしばしば有益です。 -A "factory" is just a function that returns an instance of the object you want to use. This allows you to abstract the instantiation of the object, but also may make it easier to isolate the application instance. +"factory" は、使用したいオブジェクトのインスタンスを返す関数です。 これにより、オブジェクトのインスタンス化を抽象化できますが、アプリケーションインスタンスを簡単に分離できるようになります。 -.. column:: +.. 列:: ``` -A super simple factory pattern could look like this: +超単純なファクトリパターンは次のようになります: ``` -.. column:: +.. 列:: ```` ```python @@ -187,13 +187,13 @@ def create_app(config=MyConfig) -> Sanic: ``` ```` -.. column:: +.. 列:: ``` -When we get to running Sanic later, you will learn that the Sanic CLI can detect this pattern and use it to run your application. +Sanic を後で実行すると、Sanic CLI がこのパターンを検出し、アプリケーションを実行するために使用できることがわかります。 ``` -.. column:: +.. 列:: ```` ```sh @@ -201,15 +201,15 @@ sanic path.to.server:create_app ``` ```` -## Customization +## カスタマイズ -The Sanic application instance can be customized for your application needs in a variety of ways at instantiation. +Sanicアプリケーションインスタンスは、インスタンス化時にさまざまな方法でアプリケーションのニーズに合わせてカスタマイズできます。 -For complete details, see the [API docs](/api/sanic.app). +詳細については、[API docs](/api/sanic.app) を参照してください。 -### Custom configuration +### カスタム構成 -.. column:: +.. 列:: ``` This simplest form of custom configuration would be to pass your own object directly into that Sanic application instance @@ -219,7 +219,7 @@ If you create a custom configuration object, it is *highly* recommended that you *Added in v21.6* ``` -.. column:: +.. 列:: ```` ```python @@ -232,13 +232,13 @@ app = Sanic(..., config=MyConfig()) ``` ```` -.. column:: +.. 列:: ``` -A useful example of this feature would be if you wanted to use a config file in a form that differs from what is [supported](../running/configuration.md#using-sanicupdateconfig). +この機能の有用な例として、 [supported]とは異なる形式で設定ファイルを使用したい場合があります。 /running/configuration.md#using-sanicupdateconfig). ``` -.. column:: +.. 列:: ```` ```python @@ -274,17 +274,17 @@ app = Sanic(toml_config.APP_NAME, config=toml_config) ``` ```` -### Custom context +### カスタム コンテキスト -.. column:: +.. 列:: ``` -By default, the application context is a [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) that allows you to set any properties you want on it. However, you also have the option of passing any object whatsoever instead. +デフォルトでは、アプリケーションのコンテキストは[`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types)です。 任意のプロパティを設定することができます。 ただし、任意のオブジェクトを渡すオプションもあります。 -*Added in v21.6* +*v21.6*に追加されました ``` -.. column:: +.. 列:: ```` ```python @@ -303,9 +303,9 @@ app = Sanic(..., ctx=MyContext()) ``` ```` -### Custom requests +### カスタムリクエスト -.. column:: +.. 列:: ``` It is sometimes helpful to have your own `Request` class, and tell Sanic to use that instead of the default. One example is if you wanted to modify the default `request.id` generator. @@ -317,7 +317,7 @@ It is sometimes helpful to have your own `Request` class, and tell Sanic to use It is important to remember that you are passing the *class* not an instance of the class. ``` -.. column:: +.. 列:: ```` ```python @@ -338,15 +338,15 @@ async def handler(request): ``` ```` -### Custom error handler +### カスタムエラーハンドラの設定 -.. column:: +.. 列:: ``` -See [exception handling](../best-practices/exceptions.md#custom-error-handling) for more +詳細については format@@0(../best-practices/exceptions.md#custom-error-handling) を参照してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -362,52 +362,52 @@ app = Sanic(..., error_handler=CustomErrorHandler()) ``` ```` -### Custom dumps function +### カスタムダンプ 関数 -.. column:: +.. 列:: ``` -It may sometimes be necessary or desirable to provide a custom function that serializes an object to JSON data. +JSONデータにオブジェクトをシリアライズするカスタム関数を提供することが必要な場合や望ましい場合もあります。 ``` -.. column:: +.. 列:: ```` ```python import ujson -dumps = partial(ujson.dumps, escape_forward_slashes=False) +dump = partial(ujson.dumps, escape_forward_slashes=False) app = Sanic(__name__, dumps=dumps) ``` ```` -.. column:: +.. 列:: ``` -Or, perhaps use another library or create your own. +または、おそらく別のライブラリを使用するか、独自のライブラリを作成します。 ``` -.. column:: +.. 列:: ```` ```python -from orjson import dumps +from orjson import dump app = Sanic("MyApp", dumps=dumps) ``` ```` -### Custom loads function +### カスタム読み込み機能 -.. column:: +.. 列:: ``` -Similar to `dumps`, you can also provide a custom function for deserializing data. +`dumps`と同様に、データをデシリアライズするためのカスタム関数を提供することもできます。 -*Added in v22.9* +*v22.9*に追加されました ``` -.. column:: +.. 列:: ```` ```python @@ -417,28 +417,28 @@ app = Sanic("MyApp", loads=loads) ``` ```` -### Custom typed application +### カスタムタイプされたアプリケーション -Beginning in v23.6, the correct type annotation of a default Sanic application instance is: +デフォルトの Sanic アプリケーションインスタンスの正しい型アノテーションは v23.6 で始まります。 ```python sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace] ``` -It refers to two generic types: +2つの一般的な型を指します。 -1. The first is the type of the configuration object. It defaults to :class:`sanic.config.Config`, but can be any subclass of that. -2. The second is the type of the application context. It defaults to [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace), but can be **any object** as show above. +1. 最初は、構成オブジェクトのタイプです。 デフォルトでは、 :class:`sanic.config.Config` になっていますが、そのサブクラスにすることができます。 +2. 二つ目はアプリケーションコンテキストのタイプです。 デフォルトは [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) ですが、上記のように**任意のオブジェクト** にできます。 -Let's look at some examples of how the type will change. +型がどのように変化するかの例を見てみましょう。 -.. column:: +.. 列:: ``` -Consider this example where we pass a custom subclass of :class:`sanic.config.Config` and a custom context object. +:class:`sanic.config.Config` のカスタムサブクラスとカスタムコンテキストオブジェクトを渡す例を考えてみましょう。 ``` -.. column:: +.. 列:: ```` ```python @@ -456,13 +456,13 @@ sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace] ``` ```` -.. column:: +.. 列:: ``` -Similarly, when passing a custom context object, the type will change to reflect that. +同様に、カスタムコンテキストオブジェクトを渡す場合、型はそれを反映するように変更されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -479,13 +479,13 @@ sanic.app.Sanic[sanic.config.Config, main.Foo] ``` ```` -.. column:: +.. 列:: ``` -Of course, you can set both the config and context to custom types. +もちろん、設定とコンテキストの両方をカスタムタイプに設定できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -506,7 +506,7 @@ sanic.app.Sanic[main.CustomConfig, main.Foo] ``` ```` -This pattern is particularly useful if you create a custom type alias for your application instance so that you can use it to annotate listeners and handlers. +このパターンは、アプリケーションインスタンスにカスタム型エイリアスを作成し、リスナーやハンドラに注釈を付けるために使用する場合に特に便利です。 ```python # ./path/to/types.py @@ -540,13 +540,13 @@ app = Sanic("myapp", config=MyConfig(), ctx=MyContext()) add_listeners(app) ``` -_Added in v23.6_ +_V23.6_に追加されました -### Custom typed request +### カスタムタイプのリクエスト -Sanic also allows you to customize the type of the request object. This is useful if you want to add custom properties to the request object, or be able to access your custom properties of a typed application instance. +Sanicでは、リクエストオブジェクトのタイプをカスタマイズすることもできます。 これは、リクエストオブジェクトにカスタムプロパティを追加する場合に便利です。 または型付けされたアプリケーションインスタンスのカスタムプロパティにアクセスできます。 -The correct, default type of a Sanic request instance is: +サイニックリクエストインスタンスの正しいデフォルトタイプは次のとおりです: ```python sanic.request.Request[ @@ -555,22 +555,22 @@ sanic.request.Request[ ] ``` -It refers to two generic types: +2つの一般的な型を指します。 -1. The first is the type of the application instance. It defaults to `sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]`, but can be any subclass of that. -2. The second is the type of the request context. It defaults to `types.SimpleNamespace`, but can be **any object** as show above in [custom requests](#custom-requests). +1. 最初はアプリケーションインスタンスのタイプです。 デフォルトは `sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]` ですが、そのサブクラスは任意です。 +2. 二つ目は、リクエストコンテキストのタイプです。 デフォルトは `types.SimpleNamespace` ですが、上記の [custom requests](#custom-requests) で表示されるように、 **任意のオブジェクト** にすることができます。 -Let's look at some examples of how the type will change. +型がどのように変化するかの例を見てみましょう。 -.. column:: +.. 列:: ``` -Expanding upon the full example above where there is a type alias for a customized application instance, we can also create a custom request type so that we can access those same type annotations. +カスタマイズされたアプリケーションインスタンスに型エイリアスがある上記の完全な例を展開します 同じタイプの注釈にアクセスできるようにカスタムリクエストタイプを作成することもできます -Of course, you do not need type aliases for this to work. We are only showing them here to cut down on the amount of code shown. +もちろん、これを動作させるためにタイプエイリアスは必要ありません。 私たちは、表示されているコードの量を削減するためにそれらをここに示しているだけです。 ``` -.. column:: +.. 列:: ```` ```python @@ -586,13 +586,13 @@ def add_routes(app: MyApp): ``` ```` -.. column:: +.. 列:: ``` -Perhaps you have a custom request object that generates a custom context object. You can type annotate it to properly access those properties with your IDE as shown here. +カスタムコンテキストオブジェクトを生成するカスタムリクエストオブジェクトがあるかもしれません。 ここに示すように、注釈を入力してIDEでこれらのプロパティに適切にアクセスできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -629,6 +629,6 @@ async def handler(request: CustomRequest): ``` ```` -See more information in the [custom request context](./request#custom-request-context) section. +format@@0(./request#custom-request-context) セクションを参照してください。 -_Added in v23.6_ +_V23.6_に追加されました From 0f8e0b5b825561cca780c1a2071f152b05e82ddf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:22 +0200 Subject: [PATCH 299/698] New translations app.md (Chinese Simplified) --- guide/content/zh/guide/basics/app.md | 280 +++++++++++++-------------- 1 file changed, 140 insertions(+), 140 deletions(-) diff --git a/guide/content/zh/guide/basics/app.md b/guide/content/zh/guide/basics/app.md index 4cded1f51a..76f971ee8b 100644 --- a/guide/content/zh/guide/basics/app.md +++ b/guide/content/zh/guide/basics/app.md @@ -1,20 +1,20 @@ --- -title: Sanic Application +title: Sanic 应用程序 --- -# Sanic Application +# Sanic 应用程序 -See API docs: [sanic.app](/api/sanic.app) +请参阅API文档： [sanic.app](/api/sanic.app) -## Instance +## 实例 -.. column:: +.. 列: ``` The most basic building block is the :class:`sanic.app.Sanic` instance. It is not required, but the custom is to instantiate this in a file called `server.py`. ``` -.. column:: +.. 列: ```` ```python @@ -26,17 +26,17 @@ app = Sanic("MyHelloWorldApp") ``` ```` -## Application context +## 应用程序上下文： -Most applications will have the need to share/reuse data or objects across different parts of the code base. Sanic helps be providing the `ctx` object on application instances. It is a free space for the developer to attach any objects or data that should existe throughout the lifetime of the application. +大多数应用程序将需要在代码库的不同部分之间共享/再利用数据或物体。 Sanic 帮助在应用程序实例上提供 `ctx` 对象。 它是开发者附加应用整个生命周期中应该存在的任何对象或数据的可用空间。 -.. column:: +.. 列: ``` -The most common pattern is to attach a database instance to the application. +最常见的模式是将数据库实例附加到应用程序中。 ``` -.. column:: +.. 列: ```` ```python @@ -45,13 +45,13 @@ app.ctx.db = Database() ``` ```` -.. column:: +.. 列: ``` While the previous example will work and is illustrative, it is typically considered best practice to attach objects in one of the two application startup [listeners](./listeners). ``` -.. column:: +.. 列: ```` ```python @@ -63,15 +63,15 @@ async def attach_db(app, loop): ``` ```` -## App Registry +## 应用程序注册表 -.. column:: +.. 列: ``` -When you instantiate a Sanic instance, that can be retrieved at a later time from the Sanic app registry. This can be useful, for example, if you need to access your Sanic instance from a location where it is not otherwise accessible. +当您实例化一个 Sanic 实例时，它可以稍后从 Sanic 应用程序注册表中检索。 例如，如果您需要从无法访问的地方访问您的 Sanic 实例，这可能是有用的。 ``` -.. column:: +.. 列: ```` ```python @@ -80,55 +80,55 @@ from sanic import Sanic app = Sanic("my_awesome_server") -# ./path/to/somewhere_else.py +# 路径/to/some where_else.py from sanic import Sanic app = Sanic.get_app("my_awesome_server") ``` ```` -.. column:: +.. 列: ``` If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name. ``` -.. column:: +.. 列: ```` ```python app = Sanic.get_app( - "non-existing", + "不存在", force_create=True, ) ``` ```` -.. column:: +.. 列: ``` -If there is **only one** Sanic instance registered, then calling `Sanic.get_app()` with no arguments will return that instance +如果有 **只有** 个Sanic 实例注册，那么调用 `Sanic.get_app()` 但没有参数将返回这个实例 ``` -.. column:: +.. 列: ```` ```python -Sanic("My only app") +Sanic("我唯一的应用") app = Sanic.get_app() ``` ```` -## Configuration +## 配置 -.. column:: +.. 列: ``` -Sanic holds the configuration in the `config` attribute of the `Sanic` instance. Configuration can be modified **either** using dot-notation **OR** like a dictionary. +Sanic 持有`Sanic` 实例的 `config` 属性中的配置。配置可以像字典一样使用 do-notation **OR** 进行修改。 ``` -.. column:: +.. 列: ```` ```python @@ -137,7 +137,7 @@ app = Sanic('myapp') app.config.DB_NAME = 'appdb' app.config['DB_USER'] = 'appuser' -db_settings = { +db_setting= { 'DB_HOST': 'localhost', 'DB_NAME': 'appdb', 'DB_USER': 'appuser' @@ -146,54 +146,54 @@ app.config.update(db_settings) ``` ```` -.. note:: Heads up +.. 注：浮动通知 ```` -Config keys _should_ be uppercase. But, this is mainly by convention, and lowercase will work most of the time. +config key _should_ 是上层的，但这主要是通过公约进行的，小写将大部分时间起作用。 ```python -app.config.GOOD = "yay!" -app.config.bad = "boo" +app.config.GOD = "yay!" +app.config.bad = "board" ``` ```` -There is much [more detail about configuration](../running/configuration.md) later on. +稍后会有很多[更详细的配置](../running/configuration.md)。 -## Factory pattern +## 工厂模式 -Many of the examples in these docs will show the instantiation of the :class:`sanic.app.Sanic` instance in a file called `server.py` in the "global scope" (i.e. not inside a function). This is a common pattern for very simple "hello world" style applications, but it is often beneficial to use a factory pattern instead. +Many of the examples in these docs will show the instantiation of the :class:`sanic.app.Sanic` instance in a file called `server.py` in the "global scope" (i.e. not inside a function). 这是非常简单的“hello world”风格应用程序的常见模式，但使用工厂模式往往是有益的。 -A "factory" is just a function that returns an instance of the object you want to use. This allows you to abstract the instantiation of the object, but also may make it easier to isolate the application instance. +"工厂" 只是一个函数返回你想要使用的对象的实例。 这允许您抽象对象的实例化, 但也可能使它更容易隔离应用程序实例。 -.. column:: +.. 列: ``` -A super simple factory pattern could look like this: +超级简单的出厂模式看起来像这样： ``` -.. column:: +.. 列: ```` ```python # ./path/to/server.py -from sanic import Sanic -from .path.to.config import MyConfig -from .path.to.some.blueprint import bp +从.path.to.config 从.path.to.some中导入 Sanic +中导入MyConfig +lueprint导入bp def create_app(config=MyConfig) -> Sanic: app = Sanic("MyApp", config=config) - app.blueprint(bp) + app. lueprint(bp) return app ``` ```` -.. column:: +.. 列: ``` -When we get to running Sanic later, you will learn that the Sanic CLI can detect this pattern and use it to run your application. +当我们稍后开始运行 Sanic时，你会知道Sanic CLI 可以检测到这种模式并使用它来运行你的应用程序。 ``` -.. column:: +.. 列: ```` ```sh @@ -201,15 +201,15 @@ sanic path.to.server:create_app ``` ```` -## Customization +## 自定义 -The Sanic application instance can be customized for your application needs in a variety of ways at instantiation. +Sanic 应用程序实例可以通过各种不同的实例实例为您的应用程序需要量身定制的。 -For complete details, see the [API docs](/api/sanic.app). +详情请查看[API 文档](/api/sanic.app)。 -### Custom configuration +### 自定义配置 -.. column:: +.. 列: ``` This simplest form of custom configuration would be to pass your own object directly into that Sanic application instance @@ -219,11 +219,11 @@ If you create a custom configuration object, it is *highly* recommended that you *Added in v21.6* ``` -.. column:: +.. 列: ```` ```python -from sanic.config import Config +from sanic.config 导入配置 class MyConfig(Config): FOO = "bar" @@ -232,13 +232,13 @@ app = Sanic(..., config=MyConfig()) ``` ```` -.. column:: +.. 列: ``` -A useful example of this feature would be if you wanted to use a config file in a form that differs from what is [supported](../running/configuration.md#using-sanicupdateconfig). +此功能的一个有用例子是如果您想使用一个格式不同于 [supported]的配置文件 (. /running/configuration.md#using-sanicupdateconfig)。 ``` -.. column:: +.. 列: ```` ```python @@ -274,9 +274,9 @@ app = Sanic(toml_config.APP_NAME, config=toml_config) ``` ```` -### Custom context +### 自定义环境 -.. column:: +.. 列: ``` By default, the application context is a [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) that allows you to set any properties you want on it. However, you also have the option of passing any object whatsoever instead. @@ -284,7 +284,7 @@ By default, the application context is a [`SimpleNamespace()`](https://docs.pyth *Added in v21.6* ``` -.. column:: +.. 列: ```` ```python @@ -303,74 +303,74 @@ app = Sanic(..., ctx=MyContext()) ``` ```` -### Custom requests +### 自定义请求 -.. column:: +.. 列: ``` -It is sometimes helpful to have your own `Request` class, and tell Sanic to use that instead of the default. One example is if you wanted to modify the default `request.id` generator. +有时有你自己的 `Request` 类并告诉Sanic 使用它而不是默认值是有帮助的。 一个例子是如果您想修改默认“请求”。 d`生成器。 -.. note:: Important +... 注意：重要的 - It is important to remember that you are passing the *class* not an instance of the class. + 必须记住，您正在通过 *class* 而不是类的实例。 ``` -.. column:: +.. 列: ```` ```python -import time +导入时间 -from sanic import Request, Sanic, text +from sanic import Request, Sanic, 文本 -class NanoSecondRequest(Request): - @classmethod +class NanoSecondRequest(请求): + @classmethodology def generate_id(*_): - return time.time_ns() + 返回时间 ime_ns() app = Sanic(..., request_class=NanoSecondRequest) @app.get("/") async def handler(request): - return text(str(request.id)) + retext(str(request.id)) ``` ```` -### Custom error handler +### 自定义错误处理程序 -.. column:: +.. 列: ``` -See [exception handling](../best-practices/exceptions.md#custom-error-handling) for more +查看[异常处理](../best practices/exceptions.md#custom-error-handling) ``` -.. column:: +.. 列: ```` ```python -from sanic.handlers import ErrorHandler +来自病原体。 andlers 导入 ErrorHandler class CustomErrorHandler(ErrorHandler): - def default(self, request, exception): - ''' handles errors that have no error handlers assigned ''' - # You custom error handling logic... - return super().default(request, exception) + def default(自己，请求，请求) 异常: + '' 处理错误, 没有分配给''' + # 你自定义错误处理逻辑。 .. + return super().default(请求，异常) app = Sanic(..., error_handler=CustomErrorHandler()) ``` ```` -### Custom dumps function +### 自定义转储函数 -.. column:: +.. 列: ``` -It may sometimes be necessary or desirable to provide a custom function that serializes an object to JSON data. +有时可能需要或需要提供一个自定义函数来序列一个 JSON 数据对象。 ``` -.. column:: +.. 列: ```` ```python @@ -381,13 +381,13 @@ app = Sanic(__name__, dumps=dumps) ``` ```` -.. column:: +.. 列: ``` -Or, perhaps use another library or create your own. +或者，或许使用另一个库或创建您自己的库。 ``` -.. column:: +.. 列: ```` ```python @@ -397,72 +397,72 @@ app = Sanic("MyApp", dumps=dumps) ``` ```` -### Custom loads function +### 自定义负载函数 -.. column:: +.. 列: ``` -Similar to `dumps`, you can also provide a custom function for deserializing data. +类似于“dumps”，您也可以为反序列化数据提供自定义函数。 -*Added in v22.9* +*添加于v22.9* ``` -.. column:: +.. 列: ```` ```python -from orjson import loads +from orjson import load app = Sanic("MyApp", loads=loads) ``` ```` -### Custom typed application +### 自定义类型的应用程序 -Beginning in v23.6, the correct type annotation of a default Sanic application instance is: +从 v23.6开始，默认Sanic 应用程序实例的正确类型注释是： ```python sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace] ``` -It refers to two generic types: +它指的是两种一般类型： -1. The first is the type of the configuration object. It defaults to :class:`sanic.config.Config`, but can be any subclass of that. -2. The second is the type of the application context. It defaults to [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace), but can be **any object** as show above. +1. 第一个是配置对象的类型。 It defaults to :class:`sanic.config.Config`, but can be any subclass of that. +2. 第二种是应用程序上下文的类型。 它默认了 [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace)，但上面显示的 **任何对象** 。 -Let's look at some examples of how the type will change. +让我们看看如何改变类型的一些例子。 -.. column:: +.. 列: ``` Consider this example where we pass a custom subclass of :class:`sanic.config.Config` and a custom context object. ``` -.. column:: +.. 列: ```` ```python -from sanic import Sanic -from sanic.config import Config +从病原体导入Sanic +onfig importing config -class CustomConfig(Config): +clusive Config(Config): pass -app = Sanic("test", config=CustomConfig()) -reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]" +appp = Sanic("test", config=CustomConfig()) +reenal_type(app) # N: 公开类型是 "sanic" pp.Sanic[main.CustomConfig, types.SimpleNamespace]" ``` ``` sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace] ``` ```` -.. column:: +.. 列: ``` -Similarly, when passing a custom context object, the type will change to reflect that. +同样，当传递自定义上下文对象时，类型将会改变以反映这一点。 ``` -.. column:: +.. 列: ```` ```python @@ -479,13 +479,13 @@ sanic.app.Sanic[sanic.config.Config, main.Foo] ``` ```` -.. column:: +.. 列: ``` -Of course, you can set both the config and context to custom types. +当然，您可以将配置和上下文设置为自定义类型。 ``` -.. column:: +.. 列: ```` ```python @@ -506,7 +506,7 @@ sanic.app.Sanic[main.CustomConfig, main.Foo] ``` ```` -This pattern is particularly useful if you create a custom type alias for your application instance so that you can use it to annotate listeners and handlers. +如果您为应用程序实例创建一个自定义类型别名，以便您可以使用它来批注听器和处理器，此模式就特别有用。 ```python # ./path/to/types.py @@ -520,33 +520,33 @@ MyApp = TypeAlias("MyApp", Sanic[Config, MyContext]) ```python # ./path/to/listeners.py -from myapp.types import MyApp +from myapp.types importing MyApp def add_listeners(app: MyApp): - @app.before_server_start + @app. efor_server_start async def before_server_start(app: MyApp): - # do something with your fully typed app instance - await app.ctx.db.connect() + # 使用您完全输入的应用程序实例 + 正在等待应用。 tx.db.connect() ``` ```python # ./path/to/server.py -from myapp.types import MyApp -from myapp.context import MyContext -from myapp.config import MyConfig -from myapp.listeners import add_listeners +从 myapp.types 导入 MyApp +从myapp.context 从myapp 导入 MyContext +onfig importer MyConfig +from myapp.listeners importing add_listeners app = Sanic("myapp", config=MyConfig(), ctx=MyContext()) add_listeners(app) ``` -_Added in v23.6_ +_添加于 v23.6_ -### Custom typed request +### 自定义已输入请求 -Sanic also allows you to customize the type of the request object. This is useful if you want to add custom properties to the request object, or be able to access your custom properties of a typed application instance. +Sanic还允许您自定义请求对象的类型。 如果您想要将自定义属性添加到请求对象，这是有用的， 或者能够访问您输入的应用程序实例的自定义属性。 -The correct, default type of a Sanic request instance is: +Sanic 请求实例的正确、默认类型是： ```python sanic.request.Request[ @@ -555,22 +555,22 @@ sanic.request.Request[ ] ``` -It refers to two generic types: +它指的是两种一般类型： -1. The first is the type of the application instance. It defaults to `sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]`, but can be any subclass of that. -2. The second is the type of the request context. It defaults to `types.SimpleNamespace`, but can be **any object** as show above in [custom requests](#custom-requests). +1. 第一个是应用程序实例的类型。 默认为`sanic.app.Sanic[sanic.config.Config、types.SimpleNamespace]`，但可以是这个分类中的任何一个子类。 +2. 第二种是请求上下文的类型。 它默认了 `types.SimpleNamespace`，但可以在 [自定义请求](#custom-requests) 中显示**任何对象** 。 -Let's look at some examples of how the type will change. +让我们看看如何改变类型的一些例子。 -.. column:: +.. 列: ``` -Expanding upon the full example above where there is a type alias for a customized application instance, we can also create a custom request type so that we can access those same type annotations. +扩展到上面的完整示例，在这个示例中有一个自定义应用程序实例的类型别名， 我们还可以创建一个自定义请求类型，以便我们可以访问这些类型的注释。 -Of course, you do not need type aliases for this to work. We are only showing them here to cut down on the amount of code shown. +当然，您不需要输入别名才能工作。 我们只是在这里显示它们来削减显示的代码数量。 ``` -.. column:: +.. 列: ```` ```python @@ -586,13 +586,13 @@ def add_routes(app: MyApp): ``` ```` -.. column:: +.. 列: ``` -Perhaps you have a custom request object that generates a custom context object. You can type annotate it to properly access those properties with your IDE as shown here. +也许您有一个生成自定义上下文对象的自定义请求对象。 您可以输入注解来正确访问这些属性，如这里所示。 ``` -.. column:: +.. 列: ```` ```python @@ -629,6 +629,6 @@ async def handler(request: CustomRequest): ``` ```` -See more information in the [custom request context](./request#custom-request-context) section. +在[自定义请求上下文](./request#custom-request-context)部分查看更多信息。 -_Added in v23.6_ +_添加于 v23.6_ From 6ad58f303c66d8f56cb15046fc6b9a908b36e7df Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:23 +0200 Subject: [PATCH 300/698] New translations cookies.md (Japanese) --- guide/content/ja/guide/basics/cookies.md | 66 ++++++++++++------------ 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/guide/content/ja/guide/basics/cookies.md b/guide/content/ja/guide/basics/cookies.md index a4d60b504c..d31d7a0c9f 100644 --- a/guide/content/ja/guide/basics/cookies.md +++ b/guide/content/ja/guide/basics/cookies.md @@ -1,14 +1,14 @@ -# Cookies +# Cookie -## Reading +## 読書中 -.. column:: +.. 列:: ``` -Cookies can be accessed via the `Request` object’s `cookies` dictionary. +Cookie は `Request` オブジェクトの `cookies` 辞書からアクセスできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -29,15 +29,15 @@ Most of the time you will want to use the `.get()` method to access the first el *Added in v23.3* ``` -## Writing +## 執筆中 -.. column:: +.. 列:: ``` -When returning a response, cookies can be set on the `Response` object: `response.cookies`. This object is an instance of `CookieJar` which is a special sort of dictionary that automatically will write the response headers for you. +レスポンスを返すときは、`Response` オブジェクト: `response.cookies` にクッキーを設定できます。 このオブジェクトは `CookieJar` のインスタンスで、自動的にレスポンスヘッダーを書き込む特別な種類の辞書です。 ``` -.. column:: +.. 列:: ```` ```python @@ -54,37 +54,37 @@ async def test(request): ``` ```` -Response cookies can be set like dictionary values and have the following parameters available: +Response Cookieは辞書の値のように設定でき、次のパラメータを使用できます。 -- `path: str` - The subset of URLs to which this cookie applies. Defaults to `/`. -- `domain: str` - Specifies the domain for which the cookie is valid. An explicitly specified domain must always start with a dot. -- `max_age: int` - Number of seconds the cookie should live for. -- `expires: datetime` - The time for the cookie to expire on the client’s browser. Usually it is better to use max-age instead. -- `secure: bool` - Specifies whether the cookie will only be sent via HTTPS. Defaults to `True`. -- `httponly: bool` - Specifies whether the cookie cannot be read by JavaScript. -- `samesite: str` - Available values: Lax, Strict, and None. Defaults to `Lax`. -- `comment: str` - A comment (metadata). -- `host_prefix: bool` - Whether to add the `__Host-` prefix to the cookie. -- `secure_prefix: bool` - Whether to add the `__Secure-` prefix to the cookie. -- `partitioned: bool` - Whether to mark the cookie as partitioned. +- `path: str` - このクッキーが適用される URL のサブセット。 デフォルトは `/` です。 +- `domain: str` - クッキーが有効なドメインを指定します。 明示的に指定されたドメインは常にドットで始まる必要があります。 +- `max_age: int` - クッキーが生き残るべき秒数。 +- `expires: datetime` - クッキーがクライアントのブラウザで期限切れになる時間。 通常、max-age を代わりに使用する方が良いです。 +- `secure: bool` - HTTPS でのみクッキーを送信するかどうかを指定します。 デフォルトは `True` です。 +- `httponly: bool` - クッキーをJavaScriptで読み取れないかどうかを指定します。 +- `samesite: str` - 利用可能な値: Lax, Strict, None。 デフォルトは `Lax` です。 +- `comment: str` - コメント (metadata) +- `host_prefix: bool` - Cookieに`__Host-`プレフィックスを追加するかどうか。 +- `secure_prefix: bool` - Cookieに`__Secure-`プレフィックスを追加するかどうか。 +- `partitioned: bool` - クッキーをパーティションとしてマークするかどうか。 -To better understand the implications and usage of these values, it might be helpful to read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) on [setting cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie). +これらの値の意味と使用状況をよりよく理解するためには、format@@0(https\://developer.mozilla.org/en-US/docs/Web/HTTP/Cookie)のformat@@1(https\://developer.mozilla.org/docs/Web/HTTP/Cookie)を読むと便利かもしれません。 .. tip:: FYI ``` -By default, Sanic will set the `secure` flag to `True` to ensure that cookies are only sent over HTTPS as a sensible default. This should not be impactful for local development since secure cookies over HTTP should still be sent to `localhost`. For more information, you should read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) on [secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure). +デフォルトでは、Sanicは`secure`フラグを`True`に設定し、HTTPS経由でのみクッキーが正常なデフォルトとして送信されるようにします。 これはローカル開発にとって影響を与えるべきではありません。なぜなら、HTTP を介した セキュアな Cookie は `localhost` に送られるべきだからです。 詳細については、[secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookie#restrict_access_to_cookies) の[secure cookies](https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie#Secure)をご覧ください。 ``` -## Deleting +## 削除中 -.. column:: +.. 列:: ``` -Cookies can be removed semantically or explicitly. +クッキーは意味的または明示的に削除することができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -104,19 +104,19 @@ async def test(request): *Don't forget to add `path` or `domain` if needed!* ```` -## Eating +## 食べる -.. column:: +.. 列:: ``` -Sanic likes cookies +Sanicはクッキーが好き ``` -.. column:: +.. 列:: ``` -.. attrs:: +.. attrs: :class: is-size-1 has-text-centered - 🍪 +🍪 ``` From 1ff0758378c52c6ea3341f9c7fb855733037ee0b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:24 +0200 Subject: [PATCH 301/698] New translations cookies.md (Chinese Simplified) --- guide/content/zh/guide/basics/cookies.md | 82 ++++++++++++------------ 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/guide/content/zh/guide/basics/cookies.md b/guide/content/zh/guide/basics/cookies.md index a4d60b504c..464b955ccf 100644 --- a/guide/content/zh/guide/basics/cookies.md +++ b/guide/content/zh/guide/basics/cookies.md @@ -1,14 +1,14 @@ -# Cookies +# Cookie -## Reading +## 正在阅读 -.. column:: +.. 列: ``` -Cookies can be accessed via the `Request` object’s `cookies` dictionary. +Cookie 可以通过 `Request` 对象的 `cookies` 字典访问。 ``` -.. column:: +.. 列: ```` ```python @@ -22,69 +22,69 @@ async def test(request): .. tip:: FYI ``` -💡 The `request.cookies` object is one of a few types that is a dictionary with each value being a `list`. This is because HTTP allows a single key to be reused to send multiple values. +💡 "request.cookies"对象是几种类型的字典之一，每个值都是 "list"。 这是因为HTTP允许重用单个键来发送多个值。 -Most of the time you will want to use the `.get()` method to access the first element and not a `list`. If you do want a `list` of all items, you can use `.getlist()`. +大部分时间你想使用 `.get()` 方法来访问第一个元素，而不是一个 `list` 。 如果你确实想要一个所有项目的 `list` ，你可以使用 `.getlist()` 。 -*Added in v23.3* +*添加于v23.3* ``` -## Writing +## 写入中 -.. column:: +.. 列: ``` -When returning a response, cookies can be set on the `Response` object: `response.cookies`. This object is an instance of `CookieJar` which is a special sort of dictionary that automatically will write the response headers for you. +返回响应时，cookie可以在 "Response" 对象上设置: "response.cookies" 此对象是 `CookieJar` 的一个实例，这是一个特殊的词典，它将自动为您写出响应标题。 ``` -.. column:: +.. 列: ```` ```python -@app.route("/cookie") +@app。 oute("/cookie") async def test(request): - response = text("There's a cookie up in this response") - response.add_cookie( + response = text("在此响应中有cookie") + 响应。 dd_cookie( "test", - "It worked!", - domain=".yummy-yummy-cookie.com", + "它正常工作! , + domain=". umyummy-cookie。 om", httponly=True - ) - return response + + 返回响应 ``` ```` -Response cookies can be set like dictionary values and have the following parameters available: +响应 cookie 可以设置为字典值，并且有以下参数可用： -- `path: str` - The subset of URLs to which this cookie applies. Defaults to `/`. -- `domain: str` - Specifies the domain for which the cookie is valid. An explicitly specified domain must always start with a dot. -- `max_age: int` - Number of seconds the cookie should live for. -- `expires: datetime` - The time for the cookie to expire on the client’s browser. Usually it is better to use max-age instead. -- `secure: bool` - Specifies whether the cookie will only be sent via HTTPS. Defaults to `True`. -- `httponly: bool` - Specifies whether the cookie cannot be read by JavaScript. -- `samesite: str` - Available values: Lax, Strict, and None. Defaults to `Lax`. -- `comment: str` - A comment (metadata). -- `host_prefix: bool` - Whether to add the `__Host-` prefix to the cookie. -- `secure_prefix: bool` - Whether to add the `__Secure-` prefix to the cookie. -- `partitioned: bool` - Whether to mark the cookie as partitioned. +- `路径：str` - 此 cookie 适用的 URL 的子集。 默认值为 `/`。 +- `domain: str` - 指定 cookie 有效的域名。 一个明确指定的域必须始终以点开始。 +- `max_age: int` - cookie 应该使用的秒数。 +- `过期：日期时间` - 客户端浏览器过期的 cookie 时间。 通常最好使用最大年龄。 +- `secure: bool` - 指定是否只能通过 HTTPS 发送 cookie 默认值为“True”。 +- `http：ool` - 指定 cookie 是否被 JavaScript 读取。 +- `samesite: str` - 可用值: Lax, Strict and None 默认为\`Lax'。 +- `comment: str` - 备注(metadata)。 +- `host_prefix: bool` - 是否将 `__Host-` 前缀添加到 cookie。 +- `secure_prefix: bool` - 是否将 `__Secure-` 前缀添加到 cookie。 +- `分区：bool` - 是否将 cookie 标记为分区。 -To better understand the implications and usage of these values, it might be helpful to read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) on [setting cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie). +为了更好地理解这些数值的影响和用法，阅读[MDN文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)[setting cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie)可能会有帮助。 .. tip:: FYI ``` -By default, Sanic will set the `secure` flag to `True` to ensure that cookies are only sent over HTTPS as a sensible default. This should not be impactful for local development since secure cookies over HTTP should still be sent to `localhost`. For more information, you should read the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) on [secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure). +默认情况下，Sanic会将 `secure` 标志设置为 `True` ，以确保只能通过 HTTPS 发送cookie 作为合理的默认值。 这不应对本地发展产生影响，因为通过 HTTP 提供安全的 cookie 仍应发送至 `localhost` 。 欲了解更多信息，您应该在[secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies)上阅读[MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure)。 ``` -## Deleting +## 删除中 -.. column:: +.. 列: ``` -Cookies can be removed semantically or explicitly. +Cookie 可以用语义或明确的方式移除。 ``` -.. column:: +.. 列: ```` ```python @@ -104,15 +104,15 @@ async def test(request): *Don't forget to add `path` or `domain` if needed!* ```` -## Eating +## 吃了 -.. column:: +.. 列: ``` -Sanic likes cookies +Sanic 喜欢cookie ``` -.. column:: +.. 列: ``` .. attrs:: From a783279cda2ebf3683e1486f39b9eb13f6b85432 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:26 +0200 Subject: [PATCH 302/698] New translations handlers.md (Japanese) --- guide/content/ja/guide/basics/handlers.md | 76 +++++++++++------------ 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/guide/content/ja/guide/basics/handlers.md b/guide/content/ja/guide/basics/handlers.md index dd9e98b21b..e433c9a24a 100644 --- a/guide/content/ja/guide/basics/handlers.md +++ b/guide/content/ja/guide/basics/handlers.md @@ -1,10 +1,10 @@ # Handlers -The next important building block are your _handlers_. These are also sometimes called "views". +次に重要なビルディングブロックは _handlers_ です。 これらは"views"とも呼ばれます。 In Sanic, a handler is any callable that takes at least a :class:`sanic.request.Request` instance as an argument, and returns either an :class:`sanic.response.HTTPResponse` instance, or a coroutine that does the same. -.. column:: +.. 列:: ``` Huh? 😕 @@ -14,7 +14,7 @@ It is a **function**; either synchronous or asynchronous. The job of the handler is to respond to an endpoint and do something. This is where the majority of your business logic will go. ``` -.. column:: +.. 列:: ```` ```python @@ -26,27 +26,27 @@ async def i_am_ALSO_a_handler(request): ``` ```` -Two more important items to note: +さらに2つの重要な注意事項: -1. You almost _never_ will want to use :class:`sanic.response.HTTPresponse` directly. It is much simpler to use one of the [convenience methods](./response#methods). +1. あなたは :class:`sanic.response.HTTPresponse` を直接使用したくないでしょう。 format@@0(./response#methods) のいずれかを使う方が簡単です。 - `from sanic import json` - `from sanic import html` - `from sanic import redirect` - _etc_ -2. As we will see in [the streaming section](../advanced/streaming#response-streaming), you do not always need to return an object. If you use this lower-level API, you can control the flow of the response from within the handler, and a return object is not used. +2. format@@0(../advanced/streaming#response-streaming)で見るように、オブジェクトを返す必要はありません。 この下位レベルの API を使用する場合は、ハンドラ内からのレスポンスのフローを制御することができ、戻り値オブジェクトは使用されません。 -.. tip:: Heads up +.. tip:: Heads Up ``` -If you want to learn more about encapsulating your logic, checkout [class based views](../advanced/class-based-views.md). For now, we will continue forward with just function-based views. +ロジックのカプセル化についてもっと知りたい場合は、[class based views](../advanced/class-based-views.md) をチェックしてください。今後は関数ベースのビューだけで進めていきます。 ``` -### A simple function-based handler +### シンプルな関数ベースのハンドラです -The most common way to create a route handler is to decorate the function. It creates a visually simple identification of a route definition. We'll learn more about [routing soon](./routing.md). +ルートハンドラを作成する最も一般的な方法は、関数を飾ることです。 ルート定義の視覚的に簡単な識別を作成します。 format@@0(./routing.md) の詳細について学びます。 -.. column:: +.. 列:: ``` Let's look at a practical example. @@ -57,7 +57,7 @@ Let's look at a practical example. Mission accomplished 💪 ``` -.. column:: +.. 列:: ```` ```python @@ -71,9 +71,9 @@ async def foo_handler(request): *** -## A word about _async_... +## _async_についての単語。 -.. column:: +.. 列:: ``` It is entirely possible to write handlers that are synchronous. @@ -86,18 +86,18 @@ Using four (4) worker processes and a common benchmarking tool: - Or, about **31.76** requests/second ``` -.. column:: +.. 列:: ```` ```python @app.get("/sync") def sync_handler(request): time.sleep(0.1) - return text("Done.") + return text("Done") ``` ```` -.. column:: +.. 列:: ``` Just by changing to the asynchronous alternative `asyncio.sleep()`, we see an incredible change in performance. 🚀 @@ -113,24 +113,24 @@ Using the same four (4) worker processes: 🤯 ``` -.. column:: +.. 列:: ```` ```python @app.get("/async") async def async_handler(request): await asyncio.sleep(0.1) - return text("Done.") + return text("Done") ``` ```` -Okay... this is a ridiculously overdramatic result. And any benchmark you see is inherently very biased. This example is meant to over-the-top show the benefit of `async/await` in the web world. Results will certainly vary. Tools like Sanic and other async Python libraries are not magic bullets that make things faster. They make them _more efficient_. +わかりました... これは途方もなく過大な結果です どんなベンチマークでも本質的に偏っています この例では、ウェブの世界での `async/await` の利点を紹介します。 結果は確かに異なります。 Sanicや他の非同期Pythonライブラリのようなツールは、物事をより速くする魔法の弾丸ではありません。 これらは _more efficient_ にします。 -In our example, the asynchronous version is so much better because while one request is sleeping, it is able to start another one, and another one, and another one, and another one... +この例では、1つのリクエストがスリープ状態になっているため、非同期バージョンが非常に優れています。 別のものと別のものと別のものと別のものを始めることができます -But, this is the point! Sanic is fast because it takes the available resources and squeezes performance out of them. It can handle many requests concurrently, which means more requests per second. +しかし、これはポイントである! Sanicは利用可能なリソースを取り出し、パフォーマンスを絞り出すため、高速です。 同時に多くのリクエストを処理することができます。つまり、1秒あたりのリクエストが多くなります。 -.. tip:: A common mistake! +.. tip:: よくある間違い! ``` Don't do this! You need to ping a website. What do you use? `pip install your-fav-request-library` 🙈 @@ -142,9 +142,9 @@ Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package *** -## A fully annotated handler +## 完全に注釈を付けられたハンドラです -For those that are using type annotations... +型アノテーションを使用している人のために... ```python from sanic.response import HTTPResponse, text @@ -152,20 +152,20 @@ from sanic.request import Request @app.get("/typed") async def typed_handler(request: Request) -> HTTPResponse: - return text("Done.") + return text("Done") ``` -## Naming your handlers +## ハンドラーに名前を付けています -All handlers are named automatically. This is useful for debugging, and for generating URLs in templates. When not specified, the name that will be used is the name of the function. +すべてのハンドラは自動的に名前が付けられます。 これは、デバッグやテンプレート内の URL を生成する際に便利です。 指定しない場合、使用される名前は関数の名前です。 -.. column:: +.. 列:: ``` -For example, this handler will be named `foo_handler`. +例えば、このハンドラは `foo_handler` という名前になります。 ``` -.. column:: +.. 列:: ```` ```python @@ -176,13 +176,13 @@ async def foo_handler(request): ``` ```` -.. column:: +.. 列:: ``` -However, you can override this by passing the `name` argument to the decorator. +しかし、デコレータに `name` 引数を渡すことで上書きできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -193,15 +193,15 @@ async def foo_handler(request): ``` ```` -.. column:: +.. 列:: ``` -In fact, as you will, there may be times when you **MUST** supply a name. For example, if you use two decorators on the same function, you will need to supply a name for at least one of them. +実際には、**注意** が名前を与えなければならないことがあります。 例えば、同じ関数に 2 つのデコレータを使用する場合、少なくとも 1 つの名前を指定する必要があります。 -If you do not, you will get an error and your app will not start. Names **must** be unique within your app. +しないとエラーが発生し、アプリが起動しません。名前は **必ず**一意でなければなりません。 ``` -.. column:: +.. 列:: ```` ```python From ad4a4cad07d15eb226244fcb95101e016ccbe5f3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:27 +0200 Subject: [PATCH 303/698] New translations handlers.md (Chinese Simplified) --- guide/content/zh/guide/basics/handlers.md | 120 +++++++++++----------- 1 file changed, 60 insertions(+), 60 deletions(-) diff --git a/guide/content/zh/guide/basics/handlers.md b/guide/content/zh/guide/basics/handlers.md index dd9e98b21b..442db8913e 100644 --- a/guide/content/zh/guide/basics/handlers.md +++ b/guide/content/zh/guide/basics/handlers.md @@ -1,20 +1,20 @@ # Handlers -The next important building block are your _handlers_. These are also sometimes called "views". +下一个重要的构件块是你的 _handlers_。 它们有时也被称为“视野”。 In Sanic, a handler is any callable that takes at least a :class:`sanic.request.Request` instance as an argument, and returns either an :class:`sanic.response.HTTPResponse` instance, or a coroutine that does the same. -.. column:: +.. 列: ``` -Huh? 😕 +啊？😕 -It is a **function**; either synchronous or asynchronous. +是一个 **函数**; 要么同步，要么异步函数。 -The job of the handler is to respond to an endpoint and do something. This is where the majority of your business logic will go. +处理程序的任务是响应一个端点并做一些事情。 这是您的大多数业务逻辑将要走的地方。 ``` -.. column:: +.. 列: ```` ```python @@ -26,27 +26,27 @@ async def i_am_ALSO_a_handler(request): ``` ```` -Two more important items to note: +需要注意的另外两个重要项目： -1. You almost _never_ will want to use :class:`sanic.response.HTTPresponse` directly. It is much simpler to use one of the [convenience methods](./response#methods). +1. You almost _never_ will want to use :class:`sanic.response.HTTPresponse` directly. 使用[方便方法](./response#methods)非常简单。 - - `from sanic import json` - - `from sanic import html` - - `from sanic import redirect` - - _etc_ -2. As we will see in [the streaming section](../advanced/streaming#response-streaming), you do not always need to return an object. If you use this lower-level API, you can control the flow of the response from within the handler, and a return object is not used. + - `从 sanic import json` + - `从 sanic import html` + - `从 Sanic 导入重定向` + - _等_ +2. 我们会在[串流部分](../advanced/streaming#response-streaming)中看到的，您并不总是需要返回一个对象。 如果您使用此较低级别的 API，您可以控制处理器内响应的流量，并且返回对象未被使用。 -.. tip:: Heads up +.. 提示：浮动通知 ``` -If you want to learn more about encapsulating your logic, checkout [class based views](../advanced/class-based-views.md). For now, we will continue forward with just function-based views. +如果你想了解更多关于封装你的逻辑的信息，结帐[基于类的视图](../advanced/class-based-views.md)。现在，我们将继续只是基于函数的视图。 ``` -### A simple function-based handler +### 一个简单的基于功能的处理程序 -The most common way to create a route handler is to decorate the function. It creates a visually simple identification of a route definition. We'll learn more about [routing soon](./routing.md). +创建路由处理程序的最常见方式是装饰函数。 它为路线定义建立简单的视觉标识。 我们将了解更多关于[路由](./routing.md) -.. column:: +.. 列: ``` Let's look at a practical example. @@ -57,7 +57,7 @@ Let's look at a practical example. Mission accomplished 💪 ``` -.. column:: +.. 列: ```` ```python @@ -65,39 +65,39 @@ from sanic import text @app.get("/foo") async def foo_handler(request): - return text("I said foo!") + return text("我说了！") ``` ```` *** -## A word about _async_... +## 关于 _async_... -.. column:: +.. 列: ``` -It is entirely possible to write handlers that are synchronous. +完全可以写入同步处理程序。 -In this example, we are using the _blocking_ `time.sleep()` to simulate 100ms of processing time. Perhaps this represents fetching data from a DB, or a 3rd-party website. +在此示例中，我们正在使用 _blocking_ `time.sleep()` 模拟100毫秒的处理时间。 也许这意味着从数据库或第三方网站获取数据。 -Using four (4) worker processes and a common benchmarking tool: +使用四(4)个工序和一个共同的基准工具： -- **956** requests in 30.10s -- Or, about **31.76** requests/second +- **956** 在 30.10s +- 或大约**31.76** 请求/秒 ``` -.. column:: +.. 列: ```` ```python @app.get("/sync") def sync_handler(request): time.sleep(0.1) - return text("Done.") + return text("完成") ``` ```` -.. column:: +.. 列: ``` Just by changing to the asynchronous alternative `asyncio.sleep()`, we see an incredible change in performance. 🚀 @@ -113,24 +113,24 @@ Using the same four (4) worker processes: 🤯 ``` -.. column:: +.. 列: ```` ```python @app.get("/async") async def async_handler(request): - await asyncio.sleep(0.1) - return text("Done.") + 等待asyncio.sleep(0.1) + return text("完成") ``` ```` -Okay... this is a ridiculously overdramatic result. And any benchmark you see is inherently very biased. This example is meant to over-the-top show the benefit of `async/await` in the web world. Results will certainly vary. Tools like Sanic and other async Python libraries are not magic bullets that make things faster. They make them _more efficient_. +好的... 这是一个荒谬的过于戏剧性的结果。 你们所看到的任何基准都本质上是非常偏颇的。 这个示例是为了在网上显示`async/await`的好处。 结果肯定会有所不同。 诸如Sanic和其他异步Python图书馆之类的工具不是使事情变得更快的神奇子弹。 它们使它们更有效率。 -In our example, the asynchronous version is so much better because while one request is sleeping, it is able to start another one, and another one, and another one, and another one... +在我们的例子中，异步版本要好得多，因为当一个请求正在睡觉时， 它能够开始另一个和另一个，以及另一个... -But, this is the point! Sanic is fast because it takes the available resources and squeezes performance out of them. It can handle many requests concurrently, which means more requests per second. +但这是要点！ 沙漠之所以迅速，是因为它需要现有的资源，并挤压了可用资源的业绩。 它可以同时处理许多请求，这意味着每秒要有更多的请求。 -.. tip:: A common mistake! +.. 提示：常见错误！ ``` Don't do this! You need to ping a website. What do you use? `pip install your-fav-request-library` 🙈 @@ -142,9 +142,9 @@ Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package *** -## A fully annotated handler +## 一个完整注释的处理程序 -For those that are using type annotations... +对于那些使用类型注释的人... ```python from sanic.response import HTTPResponse, text @@ -155,63 +155,63 @@ async def typed_handler(request: Request) -> HTTPResponse: return text("Done.") ``` -## Naming your handlers +## 命名您的处理程序 -All handlers are named automatically. This is useful for debugging, and for generating URLs in templates. When not specified, the name that will be used is the name of the function. +所有处理程序都是自动命名的。 这对调试和生成模板中的 URL非常有用。 未指定时，将使用的名称是函数的名称。 -.. column:: +.. 列: ``` -For example, this handler will be named `foo_handler`. +例如，这个处理程序将被命名为“foo_handler”。 ``` -.. column:: +.. 列: ```` ```python -# Handler name will be "foo_handler" +# Handler 名称将是“foo_handler” @app.get("/foo") async def foo_handler(request): - return text("I said foo!") + return text("我说了！") ``` ```` -.. column:: +.. 列: ``` -However, you can override this by passing the `name` argument to the decorator. +然而，你可以把`name`的参数传递给装饰师来覆盖这个问题。 ``` -.. column:: +.. 列: ```` ```python -# Handler name will be "foo" +# Handler 名称将是“foo” @app.get("/foo", name="foo") async def foo_handler(request): - return text("I said foo!") + return text("我说了！") ``` ```` -.. column:: +.. 列: ``` -In fact, as you will, there may be times when you **MUST** supply a name. For example, if you use two decorators on the same function, you will need to supply a name for at least one of them. +事实上，正如你将要做的那样，可能有时候你**MUST** 提供一个名称。 例如，如果你在同一函数上使用两个装饰器，你需要为其中至少一个提供一个名称。 -If you do not, you will get an error and your app will not start. Names **must** be unique within your app. +如果您不这样做，您将会遇到一个错误，您的应用程序将不会启动。名称**必须** 在您的应用程序中是唯一的。 ``` -.. column:: +.. 列: ```` ```python -# Two handlers, same function, -# different names: +# 两个处理器，相同的函数， +# 不同的名字： # - "foo_arg" # - "foo" -@app.get("/foo/", name="foo_arg") +@app。 et("/foo/", name="foo_arg") @app.get("/foo") -async def foo(request, arg=None): - return text("I said foo!") +异步脚(请求，arg=Non): + return text("我说了！") ``` ```` From 5ae4a7988f4388c5deadff7730cb94e7f546949d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:28 +0200 Subject: [PATCH 304/698] New translations headers.md (Japanese) --- guide/content/ja/guide/basics/headers.md | 64 ++++++++++++------------ 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/guide/content/ja/guide/basics/headers.md b/guide/content/ja/guide/basics/headers.md index 1e85f926d2..873194ab56 100644 --- a/guide/content/ja/guide/basics/headers.md +++ b/guide/content/ja/guide/basics/headers.md @@ -1,26 +1,26 @@ -# Headers +# ヘッダー -Request and response headers are available in the `Request` and `HTTPResponse` objects, respectively. They make use of the [`multidict` package](https://multidict.readthedocs.io/en/stable/multidict.html#cimultidict) that allows a single key to have multiple values. +リクエストヘッダーとレスポンスヘッダーは `Request` オブジェクトと `HTTPResponse` オブジェクトでそれぞれ使用できます。 1つのキーが複数の値を持つことを可能にする[`multidict` package](https://multidict.io/en/stable/multidict.html#cimmultidict) を使用します。 .. tip:: FYI ``` -Header keys are converted to *lowercase* when parsed. Capitalization is not considered for headers. +ヘッダキーは解析時に *小文字* に変換されます。ヘッダの場合は大文字化は考慮されません。 ``` -## Request +## リクエスト -Sanic does attempt to do some normalization on request headers before presenting them to the developer, and also make some potentially meaningful extractions for common use cases. +Sanic は、リクエストヘッダの正規化を開発者に提示する前に試みています。 一般的なユースケースに意味のある抽出物を作ることもできます -.. column:: +.. 列:: ``` -#### Tokens +#### トークン -Authorization tokens in the form `Token ` or `Bearer ` are extracted to the request object: `request.token`. +`トークン `または `ベアラー `の形式の承認トークンは、リクエストオブジェクト`request.token`に抽出されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -42,13 +42,13 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 ``` ```` -### Proxy headers +### プロキシヘッダー -Sanic has special handling for proxy headers. See the [proxy headers](/guide/advanced/proxy-headers.md) section for more details. +Sanicはプロキシヘッダーのための特別な扱いを持っています。 詳細は [プロキシ ヘッダー](/guide/advanced/proxy-headers.md) をご覧ください。 -### Host header and dynamic URL construction +### ホストヘッダーと動的なURLの構築 -.. column:: +.. 列:: ``` The *effective host* is available via `request.host`. This is not necessarily the same as the host header, as it prefers proxy-forwarded host and can be forced by the server name setting. @@ -62,7 +62,7 @@ The effective host is also used in dynamic URL construction via `request.url_for These URLs can be manipulated by sending misleading host headers. `app.url_for` should be used instead if this is a concern. ``` -.. column:: +.. 列:: ```` ```python @@ -91,15 +91,15 @@ curl localhost:8000/hosts ``` ```` -### Other headers +### その他のヘッダー -.. column:: +.. 列:: ``` -All request headers are available on `request.headers`, and can be accessed in dictionary form. Capitalization is not considered for headers, and can be accessed using either uppercase or lowercase keys. +すべてのリクエストヘッダは `request.headers` 上で利用可能で、辞書形式でアクセスできます。 大文字化はヘッダとは見なされず、大文字または小文字のいずれかのキーでアクセスできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -155,20 +155,20 @@ curl localhost:9999/headers -H "Foo: one" -H "FOO: two"|jq .. tip:: FYI ``` -💡 The request.headers object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. +💡 request.headers オブジェクトは、それぞれの値がリストになる辞書である数少ない型の1つです。 これは、HTTP が 1 つのキーを再利用して複数の値を送信することを可能にするためです。 -Most of the time you will want to use the .get() or .getone() methods to access the first element and not a list. If you do want a list of all items, you can use .getall(). +ほとんどの場合、.get() または . を使用します。 etone() メソッドは、リストではなく最初の要素にアクセスします。すべての要素のリストが必要な場合は、.getall() を使用できます。 ``` -### Request ID +### 要求ID -.. column:: +.. 列:: ``` -Often it is convenient or necessary to track a request by its `X-Request-ID` header. You can easily access that as: `request.id`. +`X-Request-ID` ヘッダーでリクエストを追跡するのは便利なことや必要なことがよくあります。`request.id` に簡単にアクセスできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -184,24 +184,24 @@ ABCDEF12345679 ``` ```` -## Response +## 回答 -Sanic will automatically set the following response headers (when appropriate) for you: +Sanicは次のレスポンスヘッダーを自動的に設定します（適切な場合）： - `content-length` - `content-type` - `connection` - `transfer-encoding` -In most circumstances, you should never need to worry about setting these headers. +ほとんどの状況では、これらのヘッダーを設定することを心配する必要はありません。 -.. column:: +.. 列:: ``` -Any other header that you would like to set can be done either in the route handler, or a response middleware. +設定したい他のヘッダーは、route (ルート)ハンドラか、レスポンスミドルウェアのどちらかで行うことができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -215,7 +215,7 @@ async def add_csp(request, response): ``` ```` -.. column:: +.. 列:: ``` A common [middleware](middleware.md) you might want is to add a `X-Request-ID` header to every response. As stated above: `request.id` will provide the ID from the incoming request. But, even if no ID was supplied in the request headers, one will be automatically supplied for you. @@ -223,7 +223,7 @@ A common [middleware](middleware.md) you might want is to add a `X-Request-ID` h [See API docs for more details](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#sanic.request.Request.id) ``` -.. column:: +.. 列:: ```` ```python From 11dc132a45bf219ebf708c1040833836ccb23b1d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:30 +0200 Subject: [PATCH 305/698] New translations headers.md (Chinese Simplified) --- guide/content/zh/guide/basics/headers.md | 96 ++++++++++++------------ 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/guide/content/zh/guide/basics/headers.md b/guide/content/zh/guide/basics/headers.md index 1e85f926d2..f2f31c746a 100644 --- a/guide/content/zh/guide/basics/headers.md +++ b/guide/content/zh/guide/basics/headers.md @@ -1,26 +1,26 @@ -# Headers +# 信头 -Request and response headers are available in the `Request` and `HTTPResponse` objects, respectively. They make use of the [`multidict` package](https://multidict.readthedocs.io/en/stable/multidict.html#cimultidict) that allows a single key to have multiple values. +请求和响应头分别在 `Request` 和 `HTTPResponse` 对象中可用。 他们使用 [`multidict` 包](https://multidict.readthocs.io/en/stable/multidict.html#cimultidict) 让单个键有多个值。 .. tip:: FYI ``` -Header keys are converted to *lowercase* when parsed. Capitalization is not considered for headers. +解析后头键会转换为 *lowercase*。头部不考虑大小写。 ``` -## Request +## 请求 -Sanic does attempt to do some normalization on request headers before presenting them to the developer, and also make some potentially meaningful extractions for common use cases. +Sanic确实试图在请求头上实现某种正常化，然后将它们提交给开发者。 并为普通用途案件进行一些可能有意义的抽查。 -.. column:: +.. 列: ``` #### Tokens -Authorization tokens in the form `Token ` or `Bearer ` are extracted to the request object: `request.token`. +认证令牌在 `Token ` 或 `Wearer 中被提取到请求对象： `request.token` 。 ``` -.. column:: +.. 列: ```` ```python @@ -42,27 +42,27 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 ``` ```` -### Proxy headers +### 代理信头 -Sanic has special handling for proxy headers. See the [proxy headers](/guide/advanced/proxy-headers.md) section for more details. +Sanic对代理头有特殊处理。 详情请查看[代理头](/guide/advanced/proxy-headers.md)部分。 -### Host header and dynamic URL construction +### 主机头和动态URL设计 -.. column:: +.. 列: ``` -The *effective host* is available via `request.host`. This is not necessarily the same as the host header, as it prefers proxy-forwarded host and can be forced by the server name setting. +有效主机*可通过 `request.host`获取。 这不一定与主机头相同，因为它喜欢代理转发的主机，并且可以通过服务器名称设置强制执行。 -Webapps should generally use this accessor so that they can function the same no matter how they are deployed. The actual host header, if needed, can be found via `request.headers` +网络应用通常应使用此访问器，以便不论如何部署，它们都能够正常运行。 如果需要，实际主机头可以通过“请求”找到。 eaders` -The effective host is also used in dynamic URL construction via `request.url_for`, which uses the request to determine the external address of a handler. +有效主机也用于通过 `required 构造动态 URL 。 rl_for`, 它使用请求来确定处理程序的外部地址。 -.. tip:: Be wary of malicious clients +提示：请警惕恶意客户端 - These URLs can be manipulated by sending misleading host headers. `app.url_for` should be used instead if this is a concern. + 这些URL可以通过发送误导的主机头来操纵。 `app.url_for` 如果是关注的话应该被使用。 ``` -.. column:: +.. 列: ```` ```python @@ -91,15 +91,15 @@ curl localhost:8000/hosts ``` ```` -### Other headers +### 其他标题 -.. column:: +.. 列: ``` -All request headers are available on `request.headers`, and can be accessed in dictionary form. Capitalization is not considered for headers, and can be accessed using either uppercase or lowercase keys. +所有请求标题都在 `request.headers` 上可用，可以用字典形式访问。 大写不被视为头件，可以使用大写或小写键访问。 ``` -.. column:: +.. 列: ```` ```python @@ -155,67 +155,67 @@ curl localhost:9999/headers -H "Foo: one" -H "FOO: two"|jq .. tip:: FYI ``` -💡 The request.headers object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. +💡 request.headers对象是几种类型的字典之一，每个值都是一个列表。 这是因为HTTP允许重用单个键来发送多个值。 -Most of the time you will want to use the .get() or .getone() methods to access the first element and not a list. If you do want a list of all items, you can use .getall(). +您想要使用 .get() 或 . 的大部分时间。 etone() 方法来访问第一个元素而不是列表。如果你确实想要一个所有项目的列表，你可以使用 .getall()。 ``` -### Request ID +### 请求ID -.. column:: +.. 列: ``` -Often it is convenient or necessary to track a request by its `X-Request-ID` header. You can easily access that as: `request.id`. +通常，跟踪通过 `X-Request-ID` 文件头的请求是方便或必要的。您可以轻松访问 `request.id` 。 ``` -.. column:: +.. 列: ```` ```python @app.route("/") -async def handler(request): - return text(request.id) +async def 处理器(请求): + return text(request). d) ``` ```sh curl localhost:8000 \ - -H "X-Request-ID: ABCDEF12345679" + - H "X-Request-ID: ABCDEF12345679" ABCDEF12345679 ``` ```` -## Response +## 答复 -Sanic will automatically set the following response headers (when appropriate) for you: +Sanic 将自动为您设置以下响应头(在适当时)： - `content-length` - `content-type` - `connection` - `transfer-encoding` -In most circumstances, you should never need to worry about setting these headers. +在大多数情况下，您永远不必担心设置这些信头。 -.. column:: +.. 列: ``` -Any other header that you would like to set can be done either in the route handler, or a response middleware. +您想要设置的任何其他页眉都可以在路由处理器或响应中间件中完成。 ``` -.. column:: +.. 列: ```` ```python @app.route("/") async def handler(request): - return text("Done.", headers={"content-language": "en-US"}) + return text("完成"). , headers={"content-language": "en-US"}) @app.middleware("response") async def add_csp(request, response): - response.headers["content-security-policy"] = "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'" + 响应。 eaders["content-security policy"] = "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'' ``` ```` -.. column:: +.. 列: ``` A common [middleware](middleware.md) you might want is to add a `X-Request-ID` header to every response. As stated above: `request.id` will provide the ID from the incoming request. But, even if no ID was supplied in the request headers, one will be automatically supplied for you. @@ -223,7 +223,7 @@ A common [middleware](middleware.md) you might want is to add a `X-Request-ID` h [See API docs for more details](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#sanic.request.Request.id) ``` -.. column:: +.. 列: ```` ```python @@ -231,18 +231,18 @@ A common [middleware](middleware.md) you might want is to add a `X-Request-ID` h async def handler(request): return text(str(request.id)) -@app.on_response +@app. n_response async def add_request_id_header(request, response): - response.headers["X-Request-ID"] = request.id + response.headers["X-Request-ID"] = request。 d ``` ```sh curl localhost:8000 -i -HTTP/1.1 200 OK -X-Request-ID: 805a958e-9906-4e7a-8fe0-cbe83590431b -content-length: 36 -connection: keep-alive -content-type: text/plain; charset=utf-8 +HTTP/1。 200 OK +X-Request-ID： 805a958e-9906-4e7a-8fe0-cbe83590431b +内容长度： 36 +连接： 保持 +内容类型： text/pla；charset=utf-8 805a958e-9906-4e7a-8fe0-cbe83590431b ``` From e0234babbb973e999ca6afb41bf06c1dfa6fc01c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:31 +0200 Subject: [PATCH 306/698] New translations listeners.md (Japanese) --- guide/content/ja/guide/basics/listeners.md | 106 ++++++++++----------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/guide/content/ja/guide/basics/listeners.md b/guide/content/ja/guide/basics/listeners.md index 33a20b379a..9afa449294 100644 --- a/guide/content/ja/guide/basics/listeners.md +++ b/guide/content/ja/guide/basics/listeners.md @@ -1,27 +1,27 @@ -# Listeners +# リスナー -Sanic provides you with eight (8) opportunities to inject an operation into the life cycle of your application server. This does not include the [signals](../advanced/signals.md), which allow further injection customization. +Sanicは、アプリケーションサーバーのライフサイクルにオペレーションを注入する8つの(8)機会を提供します。 これには [signals](../advanced/signals.md) は含まれません。 -There are two (2) that run **only** on your main Sanic process (ie, once per call to `sanic server.app`.) +メインの Sanic プロセスで **のみ** を実行する (2) が2つあります (例: `sanic server.app` を呼び出すごとに1回です)。 - `main_process_start` - `main_process_stop` -There are also two (2) that run **only** in a reloader process if auto-reload has been turned on. +自動リロードがオンになっている場合、リローダープロセスで **のみ** 動作する (2) もあります。 - `reload_process_start` - `reload_process_stop` -_Added `reload_process_start` and `reload_process_stop` in v22.3_ +_v22.3_ に `reload_process_start` と `reload_process_stop` を追加しました -There are four (4) that enable you to execute startup/teardown code as your server starts or closes. +サーバーが起動または終了すると、起動/分解コードを実行することができる4つの(4)があります。 - `before_server_start` - `after_server_start` - `before_server_stop` - `after_server_stop` -The life cycle of a worker process looks like this: +ワーカープロセスのライフサイクルは次のようになります。 .. mermaid:: @@ -70,7 +70,7 @@ end Note over Process: exit ``` -The reloader process live outside of this worker process inside of a process that is responsible for starting and stopping the Sanic processes. Consider the following example: +Sanicプロセスの開始と停止を担当するプロセスの中で、このワーカープロセスの外で再ローダープロセスが稼働しています。 次の例を考えてみましょう: ```python @app.reload_process_start @@ -86,19 +86,19 @@ async def before_start(*_): print(">>>>>> before_start <<<<<<") ``` -If this application were run with auto-reload turned on, the `reload_start` function would be called once when the reloader process starts. The `main_start` function would also be called once when the main process starts. **HOWEVER**, the `before_start` function would be called once for each worker process that is started, and subsequently every time that a file is saved and the worker is restarted. +このアプリケーションが自動再読み込みをオンにして実行された場合、`reload_start` 関数は、リローダーのプロセスが開始されたときに呼び出されます。 メインプロセスが開始されると、 `main_start` 関数も呼び出されます。 **HOWEVER**、`before_start` 関数は、開始されるワーカープロセスごとに1回呼び出されます。 その後、ファイルが保存されワーカーが再起動されるたびに実行されます。 -## Attaching a listener +## リスナーをアタッチする -.. column:: +.. 列:: ``` -The process to setup a function as a listener is similar to declaring a route. +リスナーとして関数をセットアップするプロセスは、route (ルート)を宣言するプロセスと似ています。 -The currently running `Sanic()` instance is injected into the listener. +現在実行されている `Sanic()` インスタンスはリスナーに挿入されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -109,13 +109,13 @@ app.register_listener(setup_db, "before_server_start") ``` ```` -.. column:: +.. 列:: ``` -The `Sanic` app instance also has a convenience decorator. +`Sanic`アプリインスタンスには、利便性のデコレータもあります。 ``` -.. column:: +.. 列:: ```` ```python @@ -125,13 +125,13 @@ async def setup_db(app): ``` ```` -.. column:: +.. 列:: ``` -Prior to v22.3, both the application instance and the current event loop were injected into the function. However, only the application instance is injected by default. If your function signature will accept both, then both the application and the loop will be injected as shown here. +v22.3 より前には、アプリケーションインスタンスとカレントイベントループの両方が関数に注入されました。 ただし、デフォルトではアプリケーションインスタンスのみが注入されます。 関数署名が両方を受け入れる場合は、ここで示すようにアプリケーションとループの両方が注入されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -141,13 +141,13 @@ async def setup_db(app, loop): ``` ```` -.. column:: +.. 列:: ``` -You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. +デコレータをさらに短くすることができます。オートコンプリート付きの IDE がある場合に便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -157,22 +157,22 @@ async def setup_db(app): ``` ```` -## Order of execution +## 実行の順序 -Listeners are executed in the order they are declared during startup, and reverse order of declaration during teardown +リスナーは起動時に宣言された順に実行され、分解中に宣言された順に逆順になります。 -| | Phase | Order | -| --------------------- | --------------- | ------------- | -| `main_process_start` | main startup | regular 🙂 ⬇️ | -| `before_server_start` | worker startup | regular 🙂 ⬇️ | -| `after_server_start` | worker startup | regular 🙂 ⬇️ | -| `before_server_stop` | worker shutdown | 🙃 ⬆️ reverse | -| `after_server_stop` | worker shutdown | 🙃 ⬆️ reverse | -| `main_process_stop` | main shutdown | 🙃 ⬆️ reverse | +| | 段階 | ご注文 | +| --------------------- | ------- | ------------- | +| `main_process_start` | メインの起動 | regular 🙂 ⬇️ | +| `before_server_start` | ワーカーの起動 | regular 🙂 ⬇️ | +| `after_server_start` | ワーカーの起動 | regular 🙂 ⬇️ | +| `before_server_stop` | ワーカーの停止 | 🙃 ⬆️ | +| `after_server_stop` | ワーカーの停止 | 🙃 ⬆️ | +| `main_process_stop` | メインシャット | 🙃 ⬆️ | -Given the following setup, we should expect to see this in the console if we run two workers. +次の設定を考えると、2つのworker を実行した場合、コンソールでこれを確認する必要があります。 -.. column:: +.. 列:: ```` ```python @@ -210,7 +210,7 @@ async def listener_8(app, loop): ``` ```` -.. column:: +.. 列:: ```` ```bash @@ -251,27 +251,27 @@ In the above example, notice how there are three processes running: .. tip:: FYI ``` -The practical result of this is that if the first listener in `before_server_start` handler setups a database connection, listeners that are registered after it can rely upon that connection being alive both when they are started and stopped. +実際の結果は、 `before_server_start` ハンドラの最初のリスナーがデータベース接続を設定する場合です。 その後登録されたリスナーはその接続が生きていることに頼ることができます 開始時と停止時の両方。 ``` -### Priority +### 優先度 .. new:: v23.12 ``` -In v23.12, the `priority` keyword argument was added to listeners. This allows for fine-tuning the order of execution of listeners. The default priority is `0`. Listeners with a higher priority will be executed first. Listeners with the same priority will be executed in the order they were registered. Furthermore, listeners attached to the `app` instance will be executed before listeners attached to a `Blueprint` instance. +v23.12 では `priority` キーワード引数がリスナーに追加されました。これによりリスナーの実行順序を微調整できます。 デフォルトの優先度は `0` です。優先度が高いリスナーは最初に実行されます。 同じ優先度を持つリスナーは、登録された順に実行されます。 さらに、 `app` インスタンスにアタッチされたリスナーは、 `Blueprint` インスタンスにアタッチされたリスナーの前に実行されます。 ``` -Overall the rules for deciding the order of execution are as follows: +全体的に実行の順序を決定するためのルールは次のとおりです。 -1. Priority in descending order -2. Application listeners before Blueprint listeners -3. Registration order +1. 降順の優先度 +2. Blueprint リスナーより前のアプリのリスナー +3. 登録注文 -.. column:: +.. 列:: ```` -As an example, consider the following, which will print: +一例として、以下のようなものを考えてみましょう。 これは ```bash third @@ -279,12 +279,12 @@ bp_third second bp_second first -fourth +fth bp_first ``` ```` -.. column:: +.. 列:: ```` ```python @@ -320,11 +320,11 @@ app.blueprint(bp) ``` ```` -## ASGI Mode +## ASGI モード -If you are running your application with an ASGI server, then make note of the following changes: +ASGI サーバーでアプリケーションを実行している場合は、次の変更を確認してください。 -- `reload_process_start` and `reload_process_stop` will be **ignored** -- `main_process_start` and `main_process_stop` will be **ignored** -- `before_server_start` will run as early as it can, and will be before `after_server_start`, but technically, the server is already running at that point -- `after_server_stop` will run as late as it can, and will be after `before_server_stop`, but technically, the server is still running at that point +- `reload_process_start` と `reload_process_stop` は **無視されます** +- `main_process_start` と `main_process_stop` は **無視されます** +- `before_server_start` はできるだけ早く実行され、`after_server_start` の前に実行されますが、技術的にはその時点で既に実行されています +- `after_server_stop` はできるだけ遅く実行され、`before_server_stop` の後になりますが、技術的には、サーバーはその時点で動作しています。 From 09a70da0fcf2a2370d68be7df8bea97b587d8311 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:33 +0200 Subject: [PATCH 307/698] New translations listeners.md (Chinese Simplified) --- guide/content/zh/guide/basics/listeners.md | 232 ++++++++++----------- 1 file changed, 116 insertions(+), 116 deletions(-) diff --git a/guide/content/zh/guide/basics/listeners.md b/guide/content/zh/guide/basics/listeners.md index 33a20b379a..c4f68b9ea3 100644 --- a/guide/content/zh/guide/basics/listeners.md +++ b/guide/content/zh/guide/basics/listeners.md @@ -1,76 +1,76 @@ -# Listeners +# 监听器 -Sanic provides you with eight (8) opportunities to inject an operation into the life cycle of your application server. This does not include the [signals](../advanced/signals.md), which allow further injection customization. +Sanic为您提供了八(8)个机会，将操作注入到您的应用程序服务器的生命周期。 这不包括 [signals](../advanced/signals.md)，它允许进一步的自定义注入。 -There are two (2) that run **only** on your main Sanic process (ie, once per call to `sanic server.app`.) +在你的主要Sanic 进程上\*\*只运行两个(2)(每次通话一次) - `main_process_start` - `main_process_stop` -There are also two (2) that run **only** in a reloader process if auto-reload has been turned on. +还有两（2）如果自动重新加载已打开，则只在读取过程中运行 \*\*。 - `reload_process_start` - `reload_process_stop` -_Added `reload_process_start` and `reload_process_stop` in v22.3_ +\*在 v22.3中添加 `reload_process_start` 和 `reload_process_stop` \* -There are four (4) that enable you to execute startup/teardown code as your server starts or closes. +有四(4)使您能够在服务器启动或关闭时执行启动/拆解代码。 -- `before_server_start` -- `after_server_start` +- `befor_server_start` +- `After _server_start` - `before_server_stop` -- `after_server_stop` +- `After _server_stop` -The life cycle of a worker process looks like this: +工序的生命周期看起来就像这样： -.. mermaid:: +.. mermaid: ``` -sequenceDiagram +序列图 autonumber -participant Process -participant Worker -participant Listener -participant Handler -Note over Process: sanic server.app -loop - Process->>Listener: @app.main_process_start - Listener->>Handler: Invoke event handler +参与进程 +参与员工 +参与者监听器 +参与者处理器 +进程注释：无声服务器。 pp +循环 + 进程->列表: @app。 ain_process_start + Listener->>>Handler: Invoke event manager end -Process->>Worker: Run workers -loop Start each worker - loop - Worker->>Listener: @app.before_server_start - Listener->>Handler: Invoke event handler - end +Process->> Workers: Run workers +roop starting each worker + roop + Worker->Listener: @app. efore_server_start + Listener->>>Handler: Invoke event handler + Note over Worker: Server status: started - loop - Worker->>Listener: @app.after_server_start - Listener->>Handler: Invoke event handler + roop + Worker->Listener: @app. fter_server_start + Listener->>>Handler: Invoke Event Event end - Note over Worker: Server status: ready + Note over Worker: Server status: possible end -Process->>Worker: Graceful shutdown -loop Stop each worker - loop - Worker->>Listener: @app.before_server_stop - Listener->>Handler: Invoke event handler +Process->Workers: Graceful shutdown +roop Stop each worker + roop + Worker->Listener: @app. efore_server_stop + Listener->>>Handler: Invoke event handler end - Note over Worker: Server status: stopped - loop - Worker->>Listener: @app.after_server_stop + Note over Worker: Server status: 停止 + 循环 + Worker->Listener: @app. fter_server_stop Listener->>Handler: Invoke event handler - end - Note over Worker: Server status: closed + ender + Note over Work: Server status: closed end loop - Process->>Listener: @app.main_process_stop - Listener->>Handler: Invoke event handler -end -Note over Process: exit + Process->>Listener: @app. ain_process_stop + Listener->>>处理程序：Invoke 事件处理程序 +结尾 +进程注释：退出 ``` -The reloader process live outside of this worker process inside of a process that is responsible for starting and stopping the Sanic processes. Consider the following example: +读取器进程在这个工人进程之外生活在负责启动和停止萨尼克进程的进程内。 请考虑以下示例： ```python @app.reload_process_start @@ -86,93 +86,93 @@ async def before_start(*_): print(">>>>>> before_start <<<<<<") ``` -If this application were run with auto-reload turned on, the `reload_start` function would be called once when the reloader process starts. The `main_start` function would also be called once when the main process starts. **HOWEVER**, the `before_start` function would be called once for each worker process that is started, and subsequently every time that a file is saved and the worker is restarted. +如果此应用程序运行时启用自动重新加载功能，当读取器进程开始时将调用 "reload_start" 函数。 "main_start" 函数也会在主进程开始时调用。 **HOWEVER**，每次启动的工作流程将调用一次`before_start`函数， 并且随后每次保存一个文件并重启该工作人员。 -## Attaching a listener +## 正在附加侦听器 -.. column:: +.. 列: ``` -The process to setup a function as a listener is similar to declaring a route. +作为侦听器设置函数的过程类似于声明路由。 -The currently running `Sanic()` instance is injected into the listener. +正在运行的 `Sanic()` 实例被注入到侦听器中。 ``` -.. column:: +.. 列: ```` ```python async def setup_db(app): - app.ctx.db = await db_setup() + app.ctx.db = 等待db_setup() -app.register_listener(setup_db, "before_server_start") +app.register_listener(setup_db, "previ_server_start") ``` ```` -.. column:: +.. 列: ``` -The `Sanic` app instance also has a convenience decorator. +“Sanic”应用实例也有一个方便装饰器。 ``` -.. column:: +.. 列: ```` ```python -@app.listener("before_server_start") +@app.listener("prev_server_start") async def setup_db(app): - app.ctx.db = await db_setup() + app.ctx.db = 等待db_setup() ``` ```` -.. column:: +.. 列: ``` -Prior to v22.3, both the application instance and the current event loop were injected into the function. However, only the application instance is injected by default. If your function signature will accept both, then both the application and the loop will be injected as shown here. +在 v22.3 之前，应用程序实例和当前事件循环都被注入到函数中。 然而，默认情况下只注入应用程序实例。 如果您的函数签名同时接受，那么应用程序和循环都会像这里显示的那样被注入。 ``` -.. column:: +.. 列: ```` ```python -@app.listener("before_server_start") +@app.listener("prev_server_start") async def setup_db(app, loop): - app.ctx.db = await db_setup() + app.ctx.db = 等待db_setup() ``` ```` -.. column:: +.. 列: ``` -You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. +您可以进一步缩短装饰。如果您拥有一个自动完成的 IDE，这将是很有帮助的。 ``` -.. column:: +.. 列: ```` ```python @app.before_server_start async def setup_db(app): - app.ctx.db = await db_setup() + app.ctx.db = 等待db_setup() ``` ```` -## Order of execution +## 执行顺序 -Listeners are executed in the order they are declared during startup, and reverse order of declaration during teardown +侦听器按启动时的申报顺序执行，并在拆解时反向排序。 -| | Phase | Order | -| --------------------- | --------------- | ------------- | -| `main_process_start` | main startup | regular 🙂 ⬇️ | -| `before_server_start` | worker startup | regular 🙂 ⬇️ | -| `after_server_start` | worker startup | regular 🙂 ⬇️ | -| `before_server_stop` | worker shutdown | 🙃 ⬆️ reverse | -| `after_server_stop` | worker shutdown | 🙃 ⬆️ reverse | -| `main_process_stop` | main shutdown | 🙃 ⬆️ reverse | +| | 阶段 | 订单 | +| --------------------- | ------ | ------------------------------------------------------------------ | +| `main_process_start` | 主要启动 | 普通:稍微ly_smiling_face: ⬇️ | +| `befor_server_start` | 工作人员启动 | 普通:稍微ly_smiling_face: ⬇️ | +| `After _server_start` | 工作人员启动 | 普通:稍微ly_smiling_face: ⬇️ | +| `before_server_stop` | 工人关机 | 🙃 ⬆️ reverse | +| `After _server_stop` | 工人关机 | 🙃 ⬆️ reverse | +| `main_process_stop` | 主要关机 | 🙃 ⬆️ reverse | -Given the following setup, we should expect to see this in the console if we run two workers. +鉴于以下情况，如果我们运行两名工人，我们应该在控制台中看到这一点。 -.. column:: +.. 列: ```` ```python @@ -180,37 +180,37 @@ Given the following setup, we should expect to see this in the console if we run async def listener_1(app, loop): print("listener_1") -@app.before_server_start -async def listener_2(app, loop): +@appp efor_server_start +async def listener_2(app, loor): print("listener_2") -@app.listener("after_server_start") -async def listener_3(app, loop): +@app. istener("after_server_start") +async def listener_3(app, rol): print("listener_3") -@app.after_server_start -async def listener_4(app, loop): +@app. fter_server_start +async def listener_4(app, loor): print("listener_4") -@app.listener("before_server_stop") -async def listener_5(app, loop): +@app. istener("before_server_stop") +async def listener_5(app, rol): print("listener_5") -@app.before_server_stop -async def listener_6(app, loop): +@app. efor_server_stop +async def listener_6(app, loor): print("listener_6") -@app.listener("after_server_stop") -async def listener_7(app, loop): +@app. istener("after_server_stop") +async def listener_7(app, rol): print("listener_7") -@app.after_server_stop -async def listener_8(app, loop): +@app. fter_server_stop +async def listener_8(app, loor): print("listener_8") ``` ```` -.. column:: +.. 列: ```` ```bash @@ -251,24 +251,24 @@ In the above example, notice how there are three processes running: .. tip:: FYI ``` -The practical result of this is that if the first listener in `before_server_start` handler setups a database connection, listeners that are registered after it can rely upon that connection being alive both when they are started and stopped. +这个结果的实际结果是，如果`pre_server_start`中的第一个监听器设置了数据库连接。 注册后的侦听器可以在启动和停止时依靠该连接存活。 ``` -### Priority +### 优先权 -.. new:: v23.12 +.. 新：v23.12 ``` -In v23.12, the `priority` keyword argument was added to listeners. This allows for fine-tuning the order of execution of listeners. The default priority is `0`. Listeners with a higher priority will be executed first. Listeners with the same priority will be executed in the order they were registered. Furthermore, listeners attached to the `app` instance will be executed before listeners attached to a `Blueprint` instance. +在 v23.12，监听器中添加了 `priority` 关键字参数。这允许调整监听器的执行顺序。 默认优先级是 `0`。优先级较高的侦听器将先执行。 具有相同优先级的侦听器将按照他们注册的顺序执行。 此外，连接到 `app` 实例的侦听器将在连接到 `Blueprint` 实例的侦听器之前执行。 ``` -Overall the rules for deciding the order of execution are as follows: +总体上，决定执行顺序的规则如下： -1. Priority in descending order -2. Application listeners before Blueprint listeners -3. Registration order +1. 按降序排序 +2. 蓝图监听器之前的应用程序监听器 +3. 注册订单 -.. column:: +.. 列: ```` As an example, consider the following, which will print: @@ -284,7 +284,7 @@ bp_first ``` ```` -.. column:: +.. 列: ```` ```python @@ -292,27 +292,27 @@ bp_first async def first(app): print("first") -@app.listener("before_server_start", priority=2) +@app。 istener("before_server_start", priority=2) async def second(app): print("second") -@app.before_server_start(priority=3) +@app. efor_server_start(priority=3) async def third(app): print("third") -@bp.before_server_start +@bp.befor_server_start async def bp_first(app): print("bp_first") -@bp.listener("before_server_start", priority=2) +@bp. istener("before_server_start", priority=2) async def bp_second(app): print("bp_second") -@bp.before_server_start(priority=3) +@bp. efor_server_start(priority=3) async def bp_third(app): print("bp_third") -@app.before_server_start +@app。 efore_server_start async def fourth(app): print("fourth") @@ -320,11 +320,11 @@ app.blueprint(bp) ``` ```` -## ASGI Mode +## ASGI 模式 -If you are running your application with an ASGI server, then make note of the following changes: +如果您正在使用 ASGI 服务器运行您的应用程序，请注意以下变化： -- `reload_process_start` and `reload_process_stop` will be **ignored** -- `main_process_start` and `main_process_stop` will be **ignored** -- `before_server_start` will run as early as it can, and will be before `after_server_start`, but technically, the server is already running at that point -- `after_server_stop` will run as late as it can, and will be after `before_server_stop`, but technically, the server is still running at that point +- `reload_process_start` 和 `reload_process_stop` 将被**忽略** +- `main_process_start` 和 `main_process_stop` 将被**忽略** +- `befor_server_start` 将尽早运行，并且将在 `After _server_start` 之前运行，但是从技术上讲，服务器已经在那个地点运行。 +- `after _server_stop`将会尽早运行，并且会在 `before_server_stop` 之后运行，但从技术上讲，服务器仍然在那个地点运行 From 15e6fc70857d0235f927e3a29aa87aed030edfbc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:34 +0200 Subject: [PATCH 308/698] New translations middleware.md (Japanese) --- guide/content/ja/guide/basics/middleware.md | 92 ++++++++++----------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/guide/content/ja/guide/basics/middleware.md b/guide/content/ja/guide/basics/middleware.md index 7352f175ca..18687a1014 100644 --- a/guide/content/ja/guide/basics/middleware.md +++ b/guide/content/ja/guide/basics/middleware.md @@ -1,19 +1,19 @@ -# Middleware +# ミドルウェア -Whereas listeners allow you to attach functionality to the lifecycle of a worker process, middleware allows you to attach functionality to the lifecycle of an HTTP stream. +一方、リスナーはワーカープロセスのライフサイクルに機能を付加することができます。 ミドルウェアを使用すると、HTTPストリームのライフサイクルに機能を追加できます。 ```python @app.on_request async def example(request): - print("I execute before the handler.") + print("I execute before the handler") ``` -You can execute middleware either _before_ the handler is executed, or _after_. +ミドルウェアは _before_ ハンドラが実行されるか、_after_ のどちらかで実行できます。 ```python @app.on_response async def example(request, response): - print("I execute after the handler.") + print("I execute after the handler") ``` .. mermaid:: @@ -43,15 +43,15 @@ end Note over Worker: Deliver response ``` -## Attaching middleware +## ミドルウェアをアタッチ中 -.. column:: +.. 列:: ``` -This should probably look familiar by now. All you need to do is declare when you would like the middleware to execute: on the `request` or on the `response`. +これはおそらく今ごろはよく見覚えがあるはずです。 ミドルウェアに`request`または`response`を実行させたいときに宣言するだけです。 ``` -.. column:: +.. 列:: ```` ```python @@ -62,13 +62,13 @@ app.register_middleware(extract_user, "request") ``` ```` -.. column:: +.. 列:: ``` -Again, the `Sanic` app instance also has a convenience decorator. +繰り返しになりますが、`Sanic`アプリインスタンスには利便性デコレータもあります。 ``` -.. column:: +.. 列:: ```` ```python @@ -78,13 +78,13 @@ async def extract_user(request): ``` ```` -.. column:: +.. 列:: ``` -Response middleware receives both the `request` and `response` arguments. +Response middleware は `request` と `response` の両方の引数を受け取ります。 ``` -.. column:: +.. 列:: ```` ```python @@ -94,15 +94,15 @@ async def prevent_xss(request, response): ``` ```` -.. column:: +.. 列:: ``` -You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. +デコレータをさらに短くすることができます。オートコンプリート付きの IDE がある場合に便利です。 -This is the preferred usage, and is what we will use going forward. +これが好ましい用途であり、今後使用するものです。 ``` -.. column:: +.. 列:: ```` ```python @@ -118,20 +118,20 @@ async def prevent_xss(request, response): ## Modification -Middleware can modify the request or response parameter it is given, _as long as it does not return it_. +ミドルウェアは与えられたリクエストやレスポンスのパラメータを変更することができます。 -.. column:: +.. 列:: ``` -#### Order of execution +#### 実行順序 -1. Request middleware: `add_key` -2. Route handler: `index` -3. Response middleware: `prevent_xss` -4. Response middleware: `custom_banner` +1. リクエストミドルウェア: `add_key` +2. ルートハンドラ: `index` +3. レスポンスミドルウェア: `prevent_xss` +4. レスポンスミドルウェア: `custom_banner` ``` -.. column:: +.. 列:: ```` ```python @@ -155,13 +155,13 @@ async def index(request): ``` ```` -.. column:: +.. 列:: ``` -You can modify the `request.match_info`. A useful feature that could be used, for example, in middleware to convert `a-slug` to `a_slug`. +`request.match_info`を変更することができます。例えばミドルウェアで`a-slug`をa_slug`に変換するのに役立つ機能です。 ``` -.. column:: +.. 列:: ```` ```python @@ -179,22 +179,22 @@ foo_bar_baz ``` ```` -## Responding early +## 早期対応 -.. column:: +.. 列:: ``` -If middleware returns a `HTTPResponse` object, the request will stop processing and the response will be returned. If this occurs to a request before the route handler is reached, the handler will **not** be called. Returning a response will also prevent any further middleware from running. +middleware が `HTTPResponse` オブジェクトを返す場合、リクエストは処理を停止し、レスポンスが返されます。 ルートハンドラに到達する前にリクエストにこれが発生した場合、ハンドラは **呼び出されません** 。 応答を返すと、さらにミドルウェアが実行されなくなります。 ``` .. tip:: ``` -You can return a `None` value to stop the execution of the middleware handler to allow the request to process as normal. This can be useful when using early return to avoid processing requests inside of that middleware handler. +`None` を返すと、ミドルウェアハンドラの実行が停止し、リクエストが通常通り処理できるようになります。 これは、ミドルウェアハンドラ内のリクエスト処理を避けるために早期の戻り値を使用する場合に便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -208,13 +208,13 @@ async def halt_response(request, response): ``` ```` -## Order of execution +## 実行の順序 -Request middleware is executed in the order declared. Response middleware is executed in **reverse order**. +リクエストミドルウェアは宣言された順序で実行されます。 レスポンスミドルウェアは**逆順**で実行されます。 -Given the following setup, we should expect to see this in the console. +以下の設定では、コンソールでこれを確認する必要があります。 -.. column:: +.. 列:: ```` ```python @@ -241,7 +241,7 @@ async def handler(request): ``` ```` -.. column:: +.. 列:: ```` ```bash @@ -250,19 +250,19 @@ middleware_2 ~ handler ~ middleware_4 middleware_3 -[INFO][127.0.0.1:44788]: GET http://localhost:8000/handler 200 5 +[INFO][127.0.0.1:44788]: GET http://localhost:8000/handler 200 5 ``` ```` -### Middleware priority +### ミドルウェアの優先度 -.. column:: +.. 列:: ``` -You can modify the order of execution of middleware by assigning it a higher priority. This happens inside of the middleware definition. The higher the value, the earlier it will execute relative to other middleware. The default priority for middleware is `0`. +ミドルウェアの実行順序は、より高い優先度を割り当てることで変更できます。ミドルウェア定義の内部で発生します。 値が高いほど、他のミドルウェアから相対的に実行されます。ミドルウェアのデフォルトの優先度は `0` です。 ``` -.. column:: +.. 列:: ```` ```python @@ -276,4 +276,4 @@ async def high_priority(request): ``` ```` -_Added in v22.9_ +_v22.9_に追加されました From ab23fdee0205571da4c434fe28f190a0772c80b8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:36 +0200 Subject: [PATCH 309/698] New translations middleware.md (Chinese Simplified) --- guide/content/zh/guide/basics/middleware.md | 134 ++++++++++---------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/guide/content/zh/guide/basics/middleware.md b/guide/content/zh/guide/basics/middleware.md index 7352f175ca..80bfcfd838 100644 --- a/guide/content/zh/guide/basics/middleware.md +++ b/guide/content/zh/guide/basics/middleware.md @@ -1,6 +1,6 @@ -# Middleware +# 中间件 -Whereas listeners allow you to attach functionality to the lifecycle of a worker process, middleware allows you to attach functionality to the lifecycle of an HTTP stream. +听众允许您在工作流程的生命周期中附加功能， 中间件允许您在HTTP流的生命周期中附加功能。 ```python @app.on_request @@ -8,7 +8,7 @@ async def example(request): print("I execute before the handler.") ``` -You can execute middleware either _before_ the handler is executed, or _after_. +您可以执行 _befor_ 的处理程序或者执行 _after _。 ```python @app.on_response @@ -16,7 +16,7 @@ async def example(request, response): print("I execute after the handler.") ``` -.. mermaid:: +.. mermaid: ``` sequenceDiagram @@ -43,66 +43,66 @@ end Note over Worker: Deliver response ``` -## Attaching middleware +## 附加中间件 -.. column:: +.. 列: ``` -This should probably look familiar by now. All you need to do is declare when you would like the middleware to execute: on the `request` or on the `response`. +现在也许应该看起来很熟悉。 您需要做的只是当您想要执行中间件时声明：在 "request" 或 "response" 上。 ``` -.. column:: +.. 列: ```` ```python async def extract_user(request): - request.ctx.user = await extract_user_from_request(request) + request.ctx.user = request_user_from_request(request) app.register_middleware(extract_user, "request") ``` ```` -.. column:: +.. 列: ``` -Again, the `Sanic` app instance also has a convenience decorator. +同样，“Sanic”应用实例也有一个方便装饰器。 ``` -.. column:: +.. 列: ```` ```python -@app.middleware("request") +@app.midleware("request") async def extract_user(request): - request.ctx.user = await extract_user_from_request(request) + request.ctx.user = request_user_from_request(request) ``` ```` -.. column:: +.. 列: ``` -Response middleware receives both the `request` and `response` arguments. +响应中间件同时收到“request”和“response”两个参数。 ``` -.. column:: +.. 列: ```` ```python -@app.middleware('response') +@app.midleware('response') async def prevent_xss(request, response): response.headers["x-xss-protection"] = "1; mode=block" ``` ```` -.. column:: +.. 列: ``` -You can shorten the decorator even further. This is helpful if you have an IDE with autocomplete. +您可以进一步缩短装饰。如果您拥有一个自动完成的 IDE，这将是很有帮助的。 -This is the preferred usage, and is what we will use going forward. +这是首选用法，这是我们今后使用的方法。 ``` -.. column:: +.. 列: ```` ```python @@ -116,37 +116,37 @@ async def prevent_xss(request, response): ``` ```` -## Modification +## 修改 -Middleware can modify the request or response parameter it is given, _as long as it does not return it_. +中间件可以修改它被指定的请求或响应参数，只要它不返回它。 -.. column:: +.. 列: ``` -#### Order of execution +#### 执行顺序 -1. Request middleware: `add_key` -2. Route handler: `index` -3. Response middleware: `prevent_xss` -4. Response middleware: `custom_banner` +1. 请求中间行：`add_key` +2. 路由处理：`index` +3. 响应中间行：`prevent_xss` +4. 响应中间行程：`cust_banner` ``` -.. column:: +.. 列: ```` ```python -@app.on_request -async def add_key(request): - # Arbitrary data may be stored in request context: - request.ctx.foo = "bar" +@app。 n_request +async def add_key(请求): + # 任意数据可能存储在请求的上下文中: + 请求。 tx.foo = "bar" @app.on_response async def custom_banner(request, response): - response.headers["Server"] = "Fake-Server" + response. eaders["Server"] = "Fake-Server" @app.on_response async def prevent_xss(request, response): - response.headers["x-xss-protection"] = "1; mode=block" + response. eaders["x-xss-protection"] = "1; mode=block" @app.get("/") async def index(request): @@ -155,33 +155,33 @@ async def index(request): ``` ```` -.. column:: +.. 列: ``` -You can modify the `request.match_info`. A useful feature that could be used, for example, in middleware to convert `a-slug` to `a_slug`. +您可以修改 `request.match_info` 。例如，一个有用的功能可以用于中间件将`a-slug` 转换为 `a_slug` 。 ``` -.. column:: +.. 列: ```` ```python @app.on_request -def convert_slug_to_underscore(request: Request): - request.match_info["slug"] = request.match_info["slug"].replace("-", "_") +def convert_slug_to_underly(request: + request.match_info["slug"] = request.match_info["slug"].replace("-"_") -@app.get("/") -async def handler(request, slug): +@app. et("/") +async def 处理器(请求) slug): return text(slug) ``` ``` -$ curl localhost:9999/foo-bar-baz +$ curl localhost:99999/foo-bar-baz foo_bar_baz ``` ```` -## Responding early +## 早期响应 -.. column:: +.. 列: ``` If middleware returns a `HTTPResponse` object, the request will stop processing and the response will be returned. If this occurs to a request before the route handler is reached, the handler will **not** be called. Returning a response will also prevent any further middleware from running. @@ -191,10 +191,10 @@ If middleware returns a `HTTPResponse` object, the request will stop processing .. tip:: ``` -You can return a `None` value to stop the execution of the middleware handler to allow the request to process as normal. This can be useful when using early return to avoid processing requests inside of that middleware handler. +您可以返回 `None` 值来停止执行中间件处理程序，以允许请求正常处理。 这可能有助于早日返回以避免处理中间件处理器内的请求。 ``` -.. column:: +.. 列: ```` ```python @@ -208,13 +208,13 @@ async def halt_response(request, response): ``` ```` -## Order of execution +## 执行顺序 -Request middleware is executed in the order declared. Response middleware is executed in **reverse order**. +请求中间件在已声明的订单中执行。 响应中间件在 **逆序** 中执行。 -Given the following setup, we should expect to see this in the console. +鉴于以下情况，我们应该在控制台上看到这一点。 -.. column:: +.. 列: ```` ```python @@ -222,47 +222,47 @@ Given the following setup, we should expect to see this in the console. async def middleware_1(request): print("middleware_1") -@app.on_request +@appp. n_request async def middleware_2(request): print("middleware_2") -@app.on_response +@app. n_response async def middleware_3(request, response): print("middleware_3") -@app.on_response +@app. n_response async def middleware_4(request, response): print("middleware_4") -@app.get("/handler") +@app. et("/handler") async def handler(request): - print("~ handler ~") - return text("Done.") + print("~handler ~") + return text("完成") ``` ```` -.. column:: +.. 列: ```` ```bash middleware_1 middleware_2 -~ handler ~ +~ middleware_4 middleware_3 -[INFO][127.0.0.1:44788]: GET http://localhost:8000/handler 200 5 +[INFO][127.0.0.1:4478]: GET http://localhost:8000/handler 200 5 ``` ```` -### Middleware priority +### 中间件优先级 -.. column:: +.. 列: ``` -You can modify the order of execution of middleware by assigning it a higher priority. This happens inside of the middleware definition. The higher the value, the earlier it will execute relative to other middleware. The default priority for middleware is `0`. +您可以通过赋予它更高的优先级来修改中间件的执行顺序。这发生在中间件定义内。 值越高，相对于其他中间件执行的越早。中间件的默认优先级是 `0'。 ``` -.. column:: +.. 列: ```` ```python @@ -276,4 +276,4 @@ async def high_priority(request): ``` ```` -_Added in v22.9_ +_添加于 v22.9_ From 05972b00d95c10f9f9c2dee18e1a24dd2aea2b2b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:37 +0200 Subject: [PATCH 310/698] New translations request.md (Japanese) --- guide/content/ja/guide/basics/request.md | 164 +++++++++++------------ 1 file changed, 82 insertions(+), 82 deletions(-) diff --git a/guide/content/ja/guide/basics/request.md b/guide/content/ja/guide/basics/request.md index c3dd8d08d9..5a942b473b 100644 --- a/guide/content/ja/guide/basics/request.md +++ b/guide/content/ja/guide/basics/request.md @@ -1,18 +1,18 @@ -# Request +# リクエスト -See API docs: [sanic.request](/api/sanic.request) +API ドキュメント: [sanic.request](/api/sanic.request) を参照してください。 -The :class:`sanic.request.Request` instance contains **a lot** of helpful information available on its parameters. Refer to the [API documentation](https://sanic.readthedocs.io/) for full details. +:class:`sanic.request.Request`インスタンスには、パラメータで入手可能な役立つ情報がたくさん含まれています。 詳細については、format@@0(https\://sanic.readthedocs.io/)を参照してください。 -As we saw in the section on [handlers](./handlers), the first argument in a route handler is usually the :class:`sanic.request.Request` object. Because Sanic is an async framework, the handler will run inside of a [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) and will be scheduled by the event loop. This means that the handler will be executed in an isolated context and the request object will be unique to that handler's task. +[handlers](./handlers) のセクションで見たとおり、ルートハンドラの最初の引数は通常、 :class:`sanic.request.Request` オブジェクトです。 Sanic は非同期フレームワークなので、ハンドラは[`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task)の中で実行され、イベントループによってスケジュールされます。 これは、ハンドラが分離されたコンテキストで実行され、リクエストオブジェクトはそのハンドラのタスクに固有であることを意味します。 -.. column:: +.. 列:: ``` -By convention, the argument is named `request`, but you can name it whatever you want. The name of the argument is not important. Both of the following handlers are valid. +規約により、引数は `request` という名前になりますが、好きな名前を付けることができます。 引数の名前は重要ではありません。以下のハンドラの両方が有効です。 ``` -.. column:: +.. 列:: ```` ```python @@ -28,14 +28,14 @@ async def atypical_use_case(req): ``` ```` -.. column:: +.. 列:: ``` -Annotating a request object is super simple. +リクエストオブジェクトに注釈を付けるのはとても簡単です。 ``` -.. column:: +.. 列:: ```` ```python @@ -51,25 +51,25 @@ async def typed_handler(request: Request): .. tip:: ``` -For your convenience, assuming you are using a modern IDE, you should leverage type annotations to help with code completion and documentation. This is especially helpful when using the `request` object as it has **MANY** properties and methods. +最新のIDEを使用していると仮定すると、コード補完とドキュメントを支援するために型注釈を活用する必要があります。 これは特に、 **MANY** のプロパティとメソッドがあるので、 `request` オブジェクトを使用する場合に便利です。 -To see the full list of available properties and methods, refer to the [API documentation](/api/sanic.request). +利用可能なプロパティとメソッドの完全なリストは、[API ドキュメント](/api/sanic.request) を参照してください。 ``` -## Body +## 本文 -The `Request` object allows you to access the content of the request body in a few different ways. +`Request`オブジェクトは、いくつかの方法でリクエストボディのコンテンツにアクセスできます。 ### JSON -.. column:: +.. 列:: ``` **Parameter**: `request.json` -**Description**: The parsed JSON object +**Description**: 解析されたJSONオブジェクト ``` -.. column:: +.. 列:: ```` ```bash @@ -84,14 +84,14 @@ $ curl localhost:8000 -d '{"foo": "bar"}' ### Raw -.. column:: +.. 列:: ``` **Parameter**: `request.body` -**Description**: The raw bytes from the request body +**Description**: リクエストボディからの生のバイト ``` -.. column:: +.. 列:: ```` ```bash @@ -104,9 +104,9 @@ b'{"foo": "bar"}' ``` ```` -### Form +### フォーム -.. column:: +.. 列:: ``` **Parameter**: `request.form` @@ -119,7 +119,7 @@ b'{"foo": "bar"}' Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. ``` -.. column:: +.. 列:: ```` ```bash @@ -141,9 +141,9 @@ bar ``` ```` -### Uploaded +### アップロードしました -.. column:: +.. 列:: ``` **Parameter**: `request.files` @@ -156,7 +156,7 @@ bar Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. ``` -.. column:: +.. 列:: ```` ```bash @@ -178,15 +178,15 @@ File(type='application/octet-stream', body=b'hello\n', name='TEST') ``` ```` -## Context +## コンテキスト -### Request context +### コンテキストをリクエスト -The `request.ctx` object is your playground to store whatever information you need to about the request. This lives only for the duration of the request and is unique to the request. +`request.ctx`オブジェクトは、リクエストに関して必要な情報を保存するためのプレイグラウンドです。 これはリクエストの期間のみ有効で、リクエストに固有のものです。 -This can be constrasted with the `app.ctx` object which is shared across all requests. Be careful not to confuse them! +これはすべてのリクエストで共有される `app.ctx` オブジェクトで解釈できます。 それらを混乱させないように注意してください! -The `request.ctx` object by default is a `SimpleNamespace` object allowing you to set arbitrary attributes on it. Sanic will not use this object for anything, so you are free to use it however you want without worrying about name clashes. +デフォルトでは `request.ctx` オブジェクトは `SimpleNamespace` オブジェクトで、任意の属性を設定できます。 Sanicはこのオブジェクトを何にも使用しないので、名前の衝突を心配することなく自由に使用できます。 ````python @@ -206,11 +206,11 @@ async def hi_my_name_is(request): return text(f"Hi, my name is {request.ctx.user.name}") ```` -As you can see, the `request.ctx` object is a great place to store information that you need to access in multiple handlers making your code more DRY and easier to maintain. But, as we will learn in the [middleware section](./middleware.md), you can also use it to store information from one middleware that will be used in another. +ご覧のとおり、 `request. tx`オブジェクトは、複数のハンドラにアクセスするために必要な情報を格納するのに最適な場所です。 しかし、format@@0(./middleware) で学びます。 d)を使用して、別のミドルウェアから情報を保存することもできます。 -### Connection context +### 接続の内容 -.. column:: +.. 列:: ``` Often times your API will need to serve multiple concurrent (or consecutive) requests to the same client. This happens, for example, very often with progressive web apps that need to query multiple endpoints to get data. @@ -220,7 +220,7 @@ The HTTP protocol calls for an easing of overhead time caused by the connection When multiple requests share a single connection, Sanic provides a context object to allow those requests to share state. ``` -.. column:: +.. 列:: ```` ```python @@ -243,25 +243,25 @@ request.conn_info.ctx.foo=3 ``` ```` -.. warning:: +.. 警告:: ``` -While this looks like a convenient place to store information between requests by a single HTTP connection, do not assume that all requests on a single connection came from a single end user. This is because HTTP proxies and load balancers can multiplex multiple connections into a single connection to your server. +リクエスト間の情報を1つのHTTP接続で保存するのに便利な場所に見えます。 単一の接続上のすべてのリクエストが単一のエンドユーザーから来たと仮定しないでください。 これは、HTTP プロキシとロードバランサが複数の接続をサーバに複数回接続できるためです。 -**DO NOT** use this to store information about a single user. Use the `request.ctx` object for that. +**単一のユーザーに関する情報を保存するには、これを使用しないでください** 。 `request.ctx` オブジェクトを使用してください。 ``` -### Custom Request Objects +### カスタムリクエストオブジェクト -As dicussed in [application customization](./app.md#custom-requests), you can create a subclass of :class:`sanic.request.Request` to add additional functionality to the request object. This is useful for adding additional attributes or methods that are specific to your application. +[application customization](./app.md#custom-requests)で説明されているように、 :class:`sanic.request.Request` のサブクラスを作成して、リクエストオブジェクトに追加機能を追加できます。 これは、アプリケーションに固有の追加の属性やメソッドを追加する場合に便利です。 -.. column:: +.. 列:: ``` -For example, imagine your application sends a custom header that contains a user ID. You can create a custom request object that will parse that header and store the user ID for you. +たとえば、アプリケーションがユーザー ID を含むカスタム ヘッダーを送信するとします。 そのヘッダーを解析し、ユーザーIDを保存するカスタムリクエストオブジェクトを作成できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -276,13 +276,13 @@ app = Sanic("Example", request_class=CustomRequest) ``` ```` -.. column:: +.. 列:: ``` -Now, in your handlers, you can access the `user_id` attribute. +ハンドラで `user_id` 属性にアクセスできるようになりました。 ``` -.. column:: +.. 列:: ```` ```python @@ -292,19 +292,19 @@ async def handler(request: CustomRequest): ``` ```` -### Custom Request Context +### カスタムリクエストのコンテキスト -By default, the request context (`request.ctx`) is a [`Simplenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) object allowing you to set arbitrary attributes on it. While this is super helpful to reuse logic across your application, it can be difficult in the development experience since the IDE will not know what attributes are available. +デフォルトでは、リクエスト コンテキスト (`request.ctx`) は [`Simplenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) オブジェクトで、任意の属性を設定できます。 これはアプリケーション全体でロジックを再利用するのに非常に役立ちます。 IDEで利用可能な属性がわからないため、開発経験では困難な場合があります。 -To help with this, you can create a custom request context object that will be used instead of the default `SimpleNamespace`. This allows you to add type hints to the context object and have them be available in your IDE. +これを支援するために、デフォルトの `SimpleNamespace` の代わりに使用されるカスタムリクエストコンテキストオブジェクトを作成できます。 これにより、型ヒントをコンテキストオブジェクトに追加し、それらをIDEで使用できるようにできます。 -.. column:: +.. 列:: ``` -Start by subclassing the :class:`sanic.request.Request` class to create a custom request type. Then, you will need to add a `make_context()` method that returns an instance of your custom context object. *NOTE: the `make_context` method should be a static method.* +:class:`sanic.request.Request`クラスをサブクラス化し、カスタムリクエストタイプを作成します。 次に、カスタムコンテキストオブジェクトのインスタンスを返す、 `make_context()` メソッドを追加する必要があります。 *注意: `make_context` メソッドは静的メソッドである必要があります。* ``` -.. column:: +.. 列:: ```` ```python @@ -329,20 +329,20 @@ class CustomContext: .. note:: ``` -This is a Sanic poweruser feature that makes it super convenient in large codebases to have typed request context objects. It is of course not required, but can be very helpful. +これはSanic poweruser 機能で、大きなコードベースでリクエストコンテキストオブジェクトを入力するのに非常に便利です。 それはもちろん必要ではありませんが、非常に役に立ちます。 ``` -_Added in v23.6_ +_V23.6_に追加されました -## Parameters +## パラメータ -.. column:: +.. 列:: ``` -Values that are extracted from the path parameters are injected into the handler as argumets, or more specifically as keyword arguments. There is much more detail about this in the [Routing section](./routing.md). +パスパラメータから抽出された値は、引数としてハンドラに注入され、より具体的にはキーワード引数として注入されます。 format@@0(./routing.md) には詳細が記載されています。 ``` -.. column:: +.. 列:: ```` ```python @@ -357,28 +357,28 @@ async def tag_handler(request, *, tag): ``` ```` -## Arguments +## 引数 -There are two attributes on the `request` instance to get query parameters: +`request`インスタンスには、クエリパラメータを取得するための2つの属性があります。 - `request.args` - `request.query_args` -These allow you to access the query parameters from the request path (the part after the `?` in the URL). +これにより、リクエストパス（URL内の `?` の後の部分）からクエリパラメータにアクセスできます。 -### Typical use case +### 典型的な使用例 -In most use cases, you will want to use the `request.args` object to access the query parameters. This will be the parsed query string as a dictionary. +ほとんどの場合、`request.args` オブジェクトを使用してクエリパラメータにアクセスします。 これは解析されたクエリ文字列を辞書として使用します。 -This is by far the most common pattern. +これははるかに一般的なパターンです。 -.. column:: +.. 列:: ``` -Consider the example where we have a `/search` endpoint with a `q` parameter that we want to use to search for something. +何かを検索するために使用する `q` パラメータを持つ `/search` エンドポイントがある例を考えてみましょう。 ``` -.. column:: +.. 列:: ```` ```python @@ -391,17 +391,17 @@ async def search(request): ``` ```` -### Parsing the query string +### クエリ文字列の解析 -Sometimes, however, you may want to access the query string as a raw string or as a list of tuples. For this, you can use the `request.query_string` and `request.query_args` attributes. +場合によっては、クエリ文字列に生の文字列またはタプルのリストとしてアクセスしたい場合があります。 これには、 `request.query_string` と `request.query_args` 属性を使用できます。 -It also should be noted that HTTP allows multiple values for a single key. Although `request.args` may seem like a regular dictionary, it is actually a special type that allows for multiple values for a single key. You can access this by using the `request.args.getlist()` method. +また、HTTP は 1 つのキーに対して複数の値を許可することに注意する必要があります。 `request.args` は通常の辞書のように見えるかもしれませんが、実際には1つのキーに対して複数の値を与える特別な型です。 `request.args.getlist()`メソッドを使用することでアクセスできます。 -- `request.query_string` - The raw query string -- `request.query_args` - The parsed query string as a list of tuples -- `request.args` - The parsed query string as a _special_ dictionary - - `request.args.get()` - Get the first value for a key (behaves like a regular dictionary) - - `request.args.getlist()` - Get all values for a key +- `request.query_string` - 生クエリ文字列 +- `request.query_args` - タプルのリストとして解析されたクエリー文字列。 +- `request.args` - _special_辞書として解析されたクエリ文字列。 + - `request.args.get()` - キーの最初の値を取得します (通常の辞書のように動作します) + - `request.args.getlist()` - キーの値をすべて取得します ```sh curl "http://localhost:8000?key1=val1&key2=val2&key1=val3" @@ -428,16 +428,16 @@ key1=val1&key2=val2&key1=val3 .. tip:: FYI ``` -The `request.args` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. +`request.args` オブジェクトは、それぞれの値がリストになる辞書である数少ない型の1つです。 これは、HTTP が 1 つのキーを再利用して複数の値を送信することを可能にするためです。 -Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +ほとんどの場合、リストではなく最初の要素にアクセスするために `.get()` メソッドを使用します。 全てのアイテムのリストが必要な場合は、 `.getlist()` を使用します。 ``` -## Current request getter +## 現在のリクエスト取得 -Sometimes you may find that you need access to the current request in your application in a location where it is not accessible. A typical example might be in a `logging` format. You can use `Request.get_current()` to fetch the current request (if any). +場合によっては、アプリケーション内の現在のリクエストにアクセスできない場所でアクセスする必要があることがあります。 典型的な例は、`logging`形式です。 `Request.get_current()`を使用して、現在のリクエストをフェッチすることができます (もしあれば)。 -Remember, the request object is confined to the single [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) that is running the handler. If you are not in that task, there is no request object. +リクエストオブジェクトは、ハンドラを実行している単一の[`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task)に制限されていることを覚えておいてください。 そのタスクに参加していない場合、リクエストオブジェクトはありません。 ```python import logging @@ -473,6 +473,6 @@ LOGGING_CONFIG_DEFAULTS["formatters"]["access"]["format"] = LOGGING_FORMAT app = Sanic("Example", log_config=LOGGING_CONFIG_DEFAULTS) ``` -In this example, we are adding the `request.id` to every access log message. +この例では、すべてのアクセスログメッセージに `request.id` を追加しています。 -_Added in v22.6_ +_v22.6_に追加されました From c9bc103d0c117e330605d8ce05a35884d25b7846 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:40 +0200 Subject: [PATCH 311/698] New translations request.md (Chinese Simplified) --- guide/content/zh/guide/basics/request.md | 226 +++++++++++------------ 1 file changed, 113 insertions(+), 113 deletions(-) diff --git a/guide/content/zh/guide/basics/request.md b/guide/content/zh/guide/basics/request.md index c3dd8d08d9..e79725308b 100644 --- a/guide/content/zh/guide/basics/request.md +++ b/guide/content/zh/guide/basics/request.md @@ -1,75 +1,75 @@ -# Request +# 请求 -See API docs: [sanic.request](/api/sanic.request) +查看 API 文档： [sanic.request](/api/sanic.request) -The :class:`sanic.request.Request` instance contains **a lot** of helpful information available on its parameters. Refer to the [API documentation](https://sanic.readthedocs.io/) for full details. +The :class:`sanic.request.Request` instance contains **a lot** of helpful information available on its parameters. 详情请参阅[API 文档](https://sanic.readthedocs.io/)。 -As we saw in the section on [handlers](./handlers), the first argument in a route handler is usually the :class:`sanic.request.Request` object. Because Sanic is an async framework, the handler will run inside of a [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) and will be scheduled by the event loop. This means that the handler will be executed in an isolated context and the request object will be unique to that handler's task. +As we saw in the section on [handlers](./handlers), the first argument in a route handler is usually the :class:`sanic.request.Request` object. 因为Sanic 是一个异步框架，处理程序将运行在一个[asyncio.Task\`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task)内，并将由事件循环进行安排。 这意味着处理程序将在一个孤立的环境中执行，而请求对象将是该处理程序的唯一任务。 -.. column:: +.. 列: ``` -By convention, the argument is named `request`, but you can name it whatever you want. The name of the argument is not important. Both of the following handlers are valid. +根据惯例，这个论点叫做`request`，但你可以给它命名你想要的。 参数的名称不重要。以下两个处理程序都是有效的。 ``` -.. column:: +.. 列: ```` ```python @app.get("/foo") async def typical_use_case(request): - return text("I said foo!") + return text("我说了！") ``` ```python -@app.get("/foo") +@app. et("/foo") async def atypical_use_case(req): - return text("I said foo!") + return text("我说了！") ``` ```` -.. column:: +.. 列: ``` -Annotating a request object is super simple. +注释请求对象是超级简单。 ``` -.. column:: +.. 列: ```` ```python -from sanic.request import Request -from sanic.response import text +来自sanic.request +from sanic.request import text -@app.get("/typed") +@app.get("/输入") async def typed_handler(request: Request): - return text("Done.") + return text("完成") ``` ```` .. tip:: ``` -For your convenience, assuming you are using a modern IDE, you should leverage type annotations to help with code completion and documentation. This is especially helpful when using the `request` object as it has **MANY** properties and methods. +为方便起见，假定您正在使用一个现代的 IDE，您应该利用类型注释来帮助代码完成和文档。 这在使用 "request" 对象时特别有用，因为它有 **MANY** 属性和方法。 -To see the full list of available properties and methods, refer to the [API documentation](/api/sanic.request). +要查看可用属性和方法的完整清单，请参阅[API 文档](/api/sanic.request)。 ``` -## Body +## 正文内容 -The `Request` object allows you to access the content of the request body in a few different ways. +`Request`对象允许您以几种不同方式访问请求主体的内容。 ### JSON -.. column:: +.. 列: ``` -**Parameter**: `request.json` -**Description**: The parsed JSON object +**参数**: `request.json` +**Description**: 已解析的 JSON 对象 ``` -.. column:: +.. 列: ```` ```bash @@ -82,31 +82,31 @@ $ curl localhost:8000 -d '{"foo": "bar"}' ``` ```` -### Raw +### 原始文件 -.. column:: +.. 列: ``` -**Parameter**: `request.body` -**Description**: The raw bytes from the request body +**参数**: `request.body` +**描述**: 请求正文中的原始字节 ``` -.. column:: +.. 列: ```` ```bash -$ curl localhost:8000 -d '{"foo": "bar"}' -``` +$ curl localhost:8000 -d '{"foo": "bar"}" +``' ```python ->>> print(request.body) -b'{"foo": "bar"}' +>> print(request.body) +b'{"foo": "bar"}" ``` ```` -### Form +### 形式 -.. column:: +.. 列: ``` **Parameter**: `request.form` @@ -119,7 +119,7 @@ b'{"foo": "bar"}' Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. ``` -.. column:: +.. 列: ```` ```bash @@ -127,23 +127,23 @@ $ curl localhost:8000 -d 'foo=bar' ``` ```python ->>> print(request.body) +>> > print(request.body) b'foo=bar' ->>> print(request.form) -{'foo': ['bar']} +>> Print(request). orm) +{'foot': ['bar']} ->>> print(request.form.get("foo")) +>> Print(request.form.get("foo")) bar ->>> print(request.form.getlist("foo")) +>> Print(request.form.getlist("foo")) ['bar'] ``` ```` -### Uploaded +### 上传完成 -.. column:: +.. 列: ``` **Parameter**: `request.files` @@ -156,7 +156,7 @@ bar Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. ``` -.. column:: +.. 列: ```` ```bash @@ -178,15 +178,15 @@ File(type='application/octet-stream', body=b'hello\n', name='TEST') ``` ```` -## Context +## 二. 背景 -### Request context +### 请求上下文内容 -The `request.ctx` object is your playground to store whatever information you need to about the request. This lives only for the duration of the request and is unique to the request. +`request.ctx`对象是您的游戏场，可以存储您需要的关于请求的任何信息。 这只适用于请求的持续时间，是请求独有的。 -This can be constrasted with the `app.ctx` object which is shared across all requests. Be careful not to confuse them! +这可以与所有请求共享的 `app.ctx` 对象混合。 请注意不要混淆他们！ -The `request.ctx` object by default is a `SimpleNamespace` object allowing you to set arbitrary attributes on it. Sanic will not use this object for anything, so you are free to use it however you want without worrying about name clashes. +默认情况下，`request.ctx`对象是 `SimpleNamespace`，允许您在它上设置任意属性。 Sanic将不会为任何东西使用此对象，所以你可以自由地使用它，不管你想不必担心名称冲突。 ````python @@ -206,11 +206,11 @@ async def hi_my_name_is(request): return text(f"Hi, my name is {request.ctx.user.name}") ```` -As you can see, the `request.ctx` object is a great place to store information that you need to access in multiple handlers making your code more DRY and easier to maintain. But, as we will learn in the [middleware section](./middleware.md), you can also use it to store information from one middleware that will be used in another. +正如你可以看到的那样，`请求'。 tx`对象是一个很好的地方来存储您需要在多个处理程序中访问的信息，使您的代码更加DRY和更容易维护。 但是，我们将在[中间件部分](./中间件部分)中学习。 您也可以使用它来存储来自一个中间件的信息，这些信息将用于另一个中间件中。 -### Connection context +### 连接环境 -.. column:: +.. 列: ``` Often times your API will need to serve multiple concurrent (or consecutive) requests to the same client. This happens, for example, very often with progressive web apps that need to query multiple endpoints to get data. @@ -220,7 +220,7 @@ The HTTP protocol calls for an easing of overhead time caused by the connection When multiple requests share a single connection, Sanic provides a context object to allow those requests to share state. ``` -.. column:: +.. 列: ```` ```python @@ -243,25 +243,25 @@ request.conn_info.ctx.foo=3 ``` ```` -.. warning:: +.. 警告：: ``` -While this looks like a convenient place to store information between requests by a single HTTP connection, do not assume that all requests on a single connection came from a single end user. This is because HTTP proxies and load balancers can multiplex multiple connections into a single connection to your server. +虽然这看起来是一个方便的地方来存储通过单个HTTP连接请求之间的信息。 不假设单个连接上的所有请求来自单个终端用户。 这是因为HTTP 代理和负载均衡器可以将多个多个连接连接到您的服务器。 -**DO NOT** use this to store information about a single user. Use the `request.ctx` object for that. +**DO Not** 使用它来存储有关单个用户的信息。为此使用 `request.ctx` 对象。 ``` -### Custom Request Objects +### 自定义请求对象 -As dicussed in [application customization](./app.md#custom-requests), you can create a subclass of :class:`sanic.request.Request` to add additional functionality to the request object. This is useful for adding additional attributes or methods that are specific to your application. +As dicussed in [application customization](./app.md#custom-requests), you can create a subclass of :class:`sanic.request.Request` to add additional functionality to the request object. 这有助于添加特定于您应用程序的附加属性或方法。 -.. column:: +.. 列: ``` -For example, imagine your application sends a custom header that contains a user ID. You can create a custom request object that will parse that header and store the user ID for you. +例如，请想象您的应用程序发送一个包含用户ID的自定义标题。 您可以创建一个自定义请求对象，解析该标头并为您存储用户 ID。 ``` -.. column:: +.. 列: ```` ```python @@ -276,13 +276,13 @@ app = Sanic("Example", request_class=CustomRequest) ``` ```` -.. column:: +.. 列: ``` -Now, in your handlers, you can access the `user_id` attribute. +现在，您可以在处理器中访问 `user_id` 属性。 ``` -.. column:: +.. 列: ```` ```python @@ -292,19 +292,19 @@ async def handler(request: CustomRequest): ``` ```` -### Custom Request Context +### 自定义请求内容 -By default, the request context (`request.ctx`) is a [`Simplenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) object allowing you to set arbitrary attributes on it. While this is super helpful to reuse logic across your application, it can be difficult in the development experience since the IDE will not know what attributes are available. +默认情况下，请求上下文(`request.ctx`) 是一个[`Simpenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) 对象，允许您在它上设置任意属性。 虽然这对于在您的应用程序中重新使用逻辑非常有用， 在发展经验中可能很困难，因为IDE将不知道有哪些属性。 -To help with this, you can create a custom request context object that will be used instead of the default `SimpleNamespace`. This allows you to add type hints to the context object and have them be available in your IDE. +为了帮助解决这个问题，您可以创建一个将被使用的自定义请求上下文对象，而不是默认的\`SimpleNamespace'。 这可以让您在上下文对象中添加提示并让它们在您的 IDE 中可用。 -.. column:: +.. 列: ``` Start by subclassing the :class:`sanic.request.Request` class to create a custom request type. Then, you will need to add a `make_context()` method that returns an instance of your custom context object. *NOTE: the `make_context` method should be a static method.* ``` -.. column:: +.. 列: ```` ```python @@ -326,59 +326,59 @@ class CustomContext: ``` ```` -.. note:: +.. 注： ``` -This is a Sanic poweruser feature that makes it super convenient in large codebases to have typed request context objects. It is of course not required, but can be very helpful. +这是一个神秘的电源用户功能，它使得在大代码折叠中具有请求上下文对象变得非常方便。 当然，这是不需要的，但可能很有帮助。 ``` -_Added in v23.6_ +_添加于 v23.6_ -## Parameters +## 参数 -.. column:: +.. 列: ``` -Values that are extracted from the path parameters are injected into the handler as argumets, or more specifically as keyword arguments. There is much more detail about this in the [Routing section](./routing.md). +从路径参数中提取的值作为参数注入到处理程序中，或更具体地作为关键字参数注入。 [路由部分](./routing.md) 中有更多关于这一点的详细信息。 ``` -.. column:: +.. 列: ```` ```python @app.route('/tag/') -async def tag_handler(request, tag): - return text("Tag - {}".format(tag)) +Async def tag_handler(请求，标签): + return text("Tag - {}"。 ormat(标签)) -# or, explicitly as keyword arguments -@app.route('/tag/') -async def tag_handler(request, *, tag): - return text("Tag - {}".format(tag)) +# 或明确作为关键词参数 +@app。 oute('/tag/') +async def tag_handler(请求, *, 标签): + return text("Tag - {}".format (tag)) ``` ```` -## Arguments +## 参数 -There are two attributes on the `request` instance to get query parameters: +在 "request" 实例上有两个属性来获取查询参数： - `request.args` -- `request.query_args` +- `requery_args` -These allow you to access the query parameters from the request path (the part after the `?` in the URL). +这些允许您访问请求路径中的查询参数(URL中`?`后面的部分)。 -### Typical use case +### 典型的使用情况 -In most use cases, you will want to use the `request.args` object to access the query parameters. This will be the parsed query string as a dictionary. +在大多数情况下，您将想使用 `request.args` 对象来访问查询参数。 这将是解析的查询字符串。 -This is by far the most common pattern. +这是迄今最常见的模式。 -.. column:: +.. 列: ``` -Consider the example where we have a `/search` endpoint with a `q` parameter that we want to use to search for something. +考虑一个我们想要用来搜索某些东西的 `/search` 端点的例子。 ``` -.. column:: +.. 列: ```` ```python @@ -391,36 +391,36 @@ async def search(request): ``` ```` -### Parsing the query string +### 解析查询字符串 -Sometimes, however, you may want to access the query string as a raw string or as a list of tuples. For this, you can use the `request.query_string` and `request.query_args` attributes. +但有时您可能想要以原始字符串或导管列表的形式访问查询字符串。 为此，您可以使用 `request.query_string` 和 `request.query_args` 属性。 -It also should be noted that HTTP allows multiple values for a single key. Although `request.args` may seem like a regular dictionary, it is actually a special type that allows for multiple values for a single key. You can access this by using the `request.args.getlist()` method. +还应该注意的是，HTTP允许单个键的多个值。 虽然`request.args`看起来像一个常规字典，但它实际上是一种特殊的类型，允许一个单个键的多个值。 您可以使用 `request.args.getlist()` 方法访问这个。 -- `request.query_string` - The raw query string -- `request.query_args` - The parsed query string as a list of tuples -- `request.args` - The parsed query string as a _special_ dictionary - - `request.args.get()` - Get the first value for a key (behaves like a regular dictionary) - - `request.args.getlist()` - Get all values for a key +- `requery_string` - 原始查询字符串 +- `requery_args` - 解析的查询字符串为导游列表 +- `request.args` - 解析的查询字符串为 _特殊_ 字典 + - `request.args.get()` - 获取关键字的第一个值 (像普通字典一样) + - `request.args.getlist()` - 获取所有键值 ```sh curl "http://localhost:8000?key1=val1&key2=val2&key1=val3" ``` ```python ->>> print(request.args) +>>> Print(request.args) {'key1': ['val1', 'val3'], 'key2': ['val2']} ->>> print(request.args.get("key1")) +>> print(request.args.get("key1")) val1 ->>> print(request.args.getlist("key1")) +>> print(request.args. etlist("key1")) ['val1', 'val3'] ->>> print(request.query_args) +>> Print(request.query_args) [('key1', 'val1'), ('key2', 'val2'), ('key1', 'val3')] ->>> print(request.query_string) +>> > 打印(request.query_string) key1=val1&key2=val2&key1=val3 ``` @@ -428,16 +428,16 @@ key1=val1&key2=val2&key1=val3 .. tip:: FYI ``` -The `request.args` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. +"request.args"对象是几种类型的字典之一，每个值都是一个列表。 这是因为HTTP允许重用单个键来发送多个值。 -Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +大多数您想使用 `.get()` 方法访问第一个元素而不是列表的时间。 如果您确实想要列出所有项目，您可以使用 `.getlist()` 。 ``` -## Current request getter +## 当前请求获取 -Sometimes you may find that you need access to the current request in your application in a location where it is not accessible. A typical example might be in a `logging` format. You can use `Request.get_current()` to fetch the current request (if any). +有时您可能会在无法访问的地方发现您需要访问您的应用程序中的当前请求。 一个典型的例子可能是 `logging` 格式。 您可以使用 `Request.get_current()` 方法获取当前请求(如果有)。 -Remember, the request object is confined to the single [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) that is running the handler. If you are not in that task, there is no request object. +记住，请求对象仅限于正在运行处理程序的单个[[asyncio.Task\`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task)。 如果你没有执行这项任务，没有请求对象。 ```python import logging @@ -473,6 +473,6 @@ LOGGING_CONFIG_DEFAULTS["formatters"]["access"]["format"] = LOGGING_FORMAT app = Sanic("Example", log_config=LOGGING_CONFIG_DEFAULTS) ``` -In this example, we are adding the `request.id` to every access log message. +在此示例中，我们正在将`request.id`添加到每个访问日志消息中。 -_Added in v22.6_ +_添加于 v22.6_ From 841ec0001b3a4dd55eb4e07dea3a7008775e8211 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:41 +0200 Subject: [PATCH 312/698] New translations response.md (Japanese) --- guide/content/ja/guide/basics/response.md | 130 +++++++++++----------- 1 file changed, 65 insertions(+), 65 deletions(-) diff --git a/guide/content/ja/guide/basics/response.md b/guide/content/ja/guide/basics/response.md index 5efe8c3ad3..d3216aa913 100644 --- a/guide/content/ja/guide/basics/response.md +++ b/guide/content/ja/guide/basics/response.md @@ -1,13 +1,13 @@ -# Response +# 回答 -All [handlers](./handlers.md) _usually_ return a response object, and [middleware](./middleware.md) may optionally return a response object. +すべての [handlers](./handlers.md) _通常_ レスポンスオブジェクトを返し、 [middleware](./middleware.md) は任意でレスポンスオブジェクトを返すことができます。 -To clarify that statement: +そのステートメントを明確にするには: -- unless the handler is a streaming endpoint handling its own pattern for sending bytes to the client, the return value must be an instance of :class:`sanic.response.HTTPResponse` (to learn more about this exception see [streaming responses](../advanced/streaming.md#response-streaming)). In **most** use cases, you will need to return a response. -- if a middleware does return a response object, that will be used instead of whatever the handler would do (see [middleware](./middleware.md) to learn more). +- ハンドラがクライアントにバイトを送信するための独自のパターンを処理するストリーミングエンドポイントでない限り、 戻り値は :class:`sanic のインスタンスでなければなりません。 esponse.HTTPResponse` (format@@0(../advanced/streaming.md#response-streaming)を参照してください)。 **ほとんどの** ユースケースでは、レスポンスを返す必要があります。 +- ミドルウェアがレスポンスオブジェクトを返す場合は、ハンドラが何でも代わりに使用されます (詳細については、 [middleware](./middleware.md) を参照)。 -A most basic handler would look like the following. The :class:`sanic.response.HTTPResponse` object will allow you to set the status, body, and headers to be returned to the client. +基本的なハンドラーは以下のようになります。 :class:`sanic.response.HTTPResponse` オブジェクトは、クライアントに返されるステータス、本文、およびヘッダーを設定できます。 ```python from sanic import HTTPResponse, Sanic @@ -19,22 +19,22 @@ def handler(_): return HTTPResponse() ``` -However, usually it is easier to use one of the convenience methods discussed below. +ただし、通常、以下で説明する便利な方法のいずれかを使用する方が簡単です。 -## Methods +## メソッド -The easiest way to generate a response object is to use one of the convenience functions. +レスポンスオブジェクトを生成する最も簡単な方法は、コンビニエンス関数のいずれかを使用することです。 -### Text +### テキスト -.. column:: +.. 列:: ``` -**Default Content-Type**: `text/plain; charset=utf-8` -**Description**: Returns plain text +**デフォルト Content-Type**: `text/plain; charset=utf-8` +**Description**: プレーン テキストを返す ``` -.. column:: +.. 列:: ```` ```python @@ -42,20 +42,20 @@ from sanic import text @app.route("/") async def handler(request): - return text("Hi 😎") + return text("Hi 😎) ``` ```` ### HTML -.. column:: +.. 列:: ``` **Default Content-Type**: `text/html; charset=utf-8` -**Description**: Returns an HTML document +**Description**: HTML ドキュメントを返す ``` -.. column:: +.. 列:: ```` ```python @@ -69,14 +69,14 @@ async def handler(request): ### JSON -.. column:: +.. 列:: ``` -**Default Content-Type**: `application/json` -**Description**: Returns a JSON document +**デフォルト Content-Type**: `application/json` +**Description**: JSON ドキュメントを返す ``` -.. column:: +.. 列:: ```` ```python @@ -88,35 +88,35 @@ async def handler(request): ``` ```` -By default, Sanic ships with [`ujson`](https://github.com/ultrajson/ultrajson) as its JSON encoder of choice. If `ujson` is not installed, it will fall back to the standard library `json` module. +デフォルトでは、Sanic は [`ujson`](https://github.com/ultrajson/ultrajson) を JSON エンコーダとして出荷します。 `ujson` がインストールされていない場合、標準ライブラリ `json` に戻ります。 -It is super simple to change this if you want. +あなたが望むならば、これを変更するのは超簡単です。 ```python from sanic import json -from orjson import dumps +from orjson import dump json({"foo": "bar"}, dumps=dumps) ``` -You may additionally declare which implementation to use globally across your application at initialization: +また、アプリケーション全体で使用する実装を初期化時に宣言することもできます。 ```python -from orjson import dumps +from orjson import dump app = Sanic(..., dumps=dumps) ``` -### File +### ファイル -.. column:: +.. 列:: ``` **Default Content-Type**: N/A -**Description**: Returns a file +**Description**: ファイルを返す ``` -.. column:: +.. 列:: ```` ```python @@ -128,28 +128,28 @@ async def handler(request): ``` ```` -Sanic will examine the file, and try and guess its mime type and use an appropriate value for the content type. You could be explicit, if you would like: +Sanicはファイルを調べ、MIMEタイプを推測し、コンテンツ型に適切な値を使用します。 必要に応じて、次のように説明できます。 ```python file("/path/to/whatever.png", mime_type="image/png") ``` -You can also choose to override the file name: +ファイル名を上書きすることもできます: ```python -file("/path/to/whatever.png", filename="super-awesome-incredible.png") +file("/path/to/whatever.png", filename="super-awesome-increverble.png") ``` -### File Streaming +### ファイルストリーミング -.. column:: +.. 列:: ``` **Default Content-Type**: N/A -**Description**: Streams a file to a client, useful when streaming large files, like a video +**Description**: クライアントにファイルをストリーミングします。ビデオのような大きなファイルをストリーミングするときに便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -161,18 +161,18 @@ async def handler(request): ``` ```` -Like the `file()` method, `file_stream()` will attempt to determine the mime type of the file. +`file()`メソッドと同様に、`file_stream()`はファイルのMIMEタイプを決定しようとします。 ### Raw -.. column:: +.. 列:: ``` **Default Content-Type**: `application/octet-stream` -**Description**: Send raw bytes without encoding the body +**Description**: body をエンコードせずに raw bytes を送る ``` -.. column:: +.. 列:: ```` ```python @@ -184,16 +184,16 @@ async def handler(request): ``` ```` -### Redirect +### リダイレクト -.. column:: +.. 列:: ``` -**Default Content-Type**: `text/html; charset=utf-8` -**Description**: Send a `302` response to redirect the client to a different path +**デフォルトのContent-Type**: `text/html; charset=utf-8` +**Description**: クライアントを別のパスにリダイレクトするために `302` レスポンスを送信する ``` -.. column:: +.. 列:: ```` ```python @@ -205,16 +205,16 @@ async def handler(request): ``` ```` -### Empty +### なし -.. column:: +.. 列:: ``` **Default Content-Type**: N/A -**Description**: For responding with an empty message as defined by [RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) +**Description**: [RFC 2616] (https://tools.ietf.org/search/rfc2616#section-7.2.1) で定義されている空のメッセージで応答するためのものです。 ``` -.. column:: +.. 列:: ```` ```python @@ -225,12 +225,12 @@ async def handler(request): return empty() ``` -Defaults to a `204` status. +デフォルトは `204` ステータスです。 ```` -## Default status +## 既定のステータス -The default HTTP status code for the response is `200`. If you need to change it, it can be done by the response method. +レスポンスのデフォルトの HTTP ステータスコードは `200` です。 変更が必要な場合は、responseメソッドで行うことができます。 ```python @app.post("/") @@ -239,10 +239,10 @@ async def create_new(request): return json({"created": True, "id": new_thing.thing_id}, status=201) ``` -## Returning JSON data +## JSON データを返す -Starting in v22.12, When you use the `sanic.json` convenience method, it will return a subclass of `HTTPResponse` called :class:`sanic.response.types.JSONResponse`. This object will -have several convenient methods available to modify common JSON body. +v22.12 から始まります。`sanic.json` コンビニエンスメソッドを使用すると、 :class:`sanic.response.types.JSONResponse` という `HTTPResponse` のサブクラスが返されます。 このオブジェクト +には、一般的なJSONボディを変更するための便利なメソッドがいくつかあります。 ```python from sanic import json @@ -250,16 +250,16 @@ from sanic import json resp = json(...) ``` -- `resp.set_body()` - Set the body of the JSON object to the value passed -- `resp.append()` - Append a value to the body like `list.append` (only works if the root JSON is an array) -- `resp.extend()` - Extend a value to the body like `list.extend` (only works if the root JSON is an array) -- `resp.update()` - Update the body with a value like `dict.update` (only works if the root JSON is an object) -- `resp.pop()` - Pop a value like `list.pop` or `dict.pop` (only works if the root JSON is an array or an object) +- `resp.set_body()` - JSONオブジェクトの本体を渡された値に設定します。 +- `resp.append()` - `list.append` のようにボディに値を追加します（ルートJSONが配列の場合のみ動作します） +- `resp.extend()` - `list.extend` のように値をボディに拡張します（ルートJSONが配列の場合のみ動作します） +- `resp.update()` - `dict.update` のような値で本文を更新します (ルートJSONがオブジェクトの場合のみ動作します) +- `resp.pop()` - `list.pop` や `dict.pop` のような値をポップします (ルートJSONが配列またはオブジェクトの場合にのみ動作します) -.. warning:: +.. 警告:: ``` -The raw Python object is stored on the `JSONResponse` object as `raw_body`. While it is safe to overwrite this value with a new one, you should **not** attempt to mutate it. You should instead use the methods listed above. +生の Python オブジェクトは `JSONResponse` オブジェクトに `raw_body` として保存されます。 この値を新しい値で上書きしても安全ですが、変更しようとしないでください。 代わりに上記の方法を使用する必要があります。 ``` ```python @@ -296,4 +296,4 @@ resp.append("else") resp.raw_body.append("something") ``` -_Added in v22.9_ +_v22.9_に追加されました From d478319f6c4029bbd3b704b2f5c2445785e05175 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:43 +0200 Subject: [PATCH 313/698] New translations response.md (Chinese Simplified) --- guide/content/zh/guide/basics/response.md | 164 +++++++++++----------- 1 file changed, 82 insertions(+), 82 deletions(-) diff --git a/guide/content/zh/guide/basics/response.md b/guide/content/zh/guide/basics/response.md index 5efe8c3ad3..e5fb104e35 100644 --- a/guide/content/zh/guide/basics/response.md +++ b/guide/content/zh/guide/basics/response.md @@ -1,16 +1,16 @@ -# Response +# 答复 -All [handlers](./handlers.md) _usually_ return a response object, and [middleware](./middleware.md) may optionally return a response object. +所有 [handlers](./handlers.md) _通常_返回一个响应对象， [middleware](./midd) 可以选择返回一个响应对象。 -To clarify that statement: +2. 澄清该陈述： -- unless the handler is a streaming endpoint handling its own pattern for sending bytes to the client, the return value must be an instance of :class:`sanic.response.HTTPResponse` (to learn more about this exception see [streaming responses](../advanced/streaming.md#response-streaming)). In **most** use cases, you will need to return a response. -- if a middleware does return a response object, that will be used instead of whatever the handler would do (see [middleware](./middleware.md) to learn more). +- unless the handler is a streaming endpoint handling its own pattern for sending bytes to the client, the return value must be an instance of :class:`sanic.response.HTTPResponse` (to learn more about this exception see [streaming responses](../advanced/streaming.md#response-streaming)). 在 **最多** 个案件中，您需要返回响应。 +- 如果中间件返回响应对象，这将被用来代替处理程序所做的任何(见 [middleware](./midd) 来了解更多)。 -A most basic handler would look like the following. The :class:`sanic.response.HTTPResponse` object will allow you to set the status, body, and headers to be returned to the client. +最基本的处理程序看起来就像下面一样。 The :class:`sanic.response.HTTPResponse` object will allow you to set the status, body, and headers to be returned to the client. ```python -from sanic import HTTPResponse, Sanic +从 HTTPResponse, Sanic app = Sanic("TestApp") @@ -19,22 +19,22 @@ def handler(_): return HTTPResponse() ``` -However, usually it is easier to use one of the convenience methods discussed below. +然而，通常较容易使用下文讨论的一种方便方法。 -## Methods +## 方法 -The easiest way to generate a response object is to use one of the convenience functions. +生成响应对象的最简单方法是使用一个方便函数。 -### Text +### 文本 -.. column:: +.. 列: ``` -**Default Content-Type**: `text/plain; charset=utf-8` -**Description**: Returns plain text +**默认内容类型**: `text/plain; charset=utf-8` +**描述**: 返回纯文本 ``` -.. column:: +.. 列: ```` ```python @@ -48,14 +48,14 @@ async def handler(request): ### HTML -.. column:: +.. 列: ``` -**Default Content-Type**: `text/html; charset=utf-8` -**Description**: Returns an HTML document +**默认内容类型**: `text/html; charset=utf-8` +**描述**: 返回一个 HTML 文档 ``` -.. column:: +.. 列: ```` ```python @@ -69,14 +69,14 @@ async def handler(request): ### JSON -.. column:: +.. 列: ``` -**Default Content-Type**: `application/json` -**Description**: Returns a JSON document +**默认 Content-Type**: `application/json` +**Description**: 返回 JSON 文档 ``` -.. column:: +.. 列: ```` ```python @@ -88,9 +88,9 @@ async def handler(request): ``` ```` -By default, Sanic ships with [`ujson`](https://github.com/ultrajson/ultrajson) as its JSON encoder of choice. If `ujson` is not installed, it will fall back to the standard library `json` module. +默认情况下，是 [`ujson`](https://github.com/ultrajson/ultrajson)的 Sanic 船舶，作为其JSON 编码器。 如果未安装 `ujson` ，它将返回到标准库`json` 模块。 -It is super simple to change this if you want. +如果你想要更改这一点是非常简单的。 ```python from sanic import json @@ -99,24 +99,24 @@ from orjson import dumps json({"foo": "bar"}, dumps=dumps) ``` -You may additionally declare which implementation to use globally across your application at initialization: +您还可以声明在初始化时在全局使用哪些实现： ```python -from orjson import dumps +从 orjson 导入转储 -app = Sanic(..., dumps=dumps) +应用 = Sanic(..., dumps=dumps) ``` -### File +### 文件 -.. column:: +.. 列: ``` -**Default Content-Type**: N/A -**Description**: Returns a file +**默认内容类型**：N/ +**描述**：返回一个文件 ``` -.. column:: +.. 列: ```` ```python @@ -124,32 +124,32 @@ from sanic import file @app.route("/") async def handler(request): - return await file("/path/to/whatever.png") + return 等待文件 ("/path/to/whatever.png") ``` ```` -Sanic will examine the file, and try and guess its mime type and use an appropriate value for the content type. You could be explicit, if you would like: +Sanic 将检查该文件，并尝试和猜其mime 类型并使用一个适当的内容类型值。 如果您想要： ```python file("/path/to/whatever.png", mime_type="image/png") ``` -You can also choose to override the file name: +您也可以选择覆盖文件名称： ```python -file("/path/to/whatever.png", filename="super-awesome-incredible.png") +file("/path/to/whatever.png", filename="超级超棒不可思议的.png") ``` -### File Streaming +### 文件流 -.. column:: +.. 列: ``` -**Default Content-Type**: N/A -**Description**: Streams a file to a client, useful when streaming large files, like a video +**默认内容类型**: N/A +**描述**: 流一个文件到一个客户端, 当像视频一样流出大文件时有用。 ``` -.. column:: +.. 列: ```` ```python @@ -161,18 +161,18 @@ async def handler(request): ``` ```` -Like the `file()` method, `file_stream()` will attempt to determine the mime type of the file. +和`file()`方法一样，`file_stream()`会尝试确定文件的 mime 类型。 -### Raw +### 原始文件 -.. column:: +.. 列: ``` -**Default Content-Type**: `application/octet-stream` -**Description**: Send raw bytes without encoding the body +**默认Content-Type**: `application/octet-stream` +**Description**: 发送原始字节而不对正文进行编码 ``` -.. column:: +.. 列: ```` ```python @@ -180,24 +180,24 @@ from sanic import raw @app.route("/") async def handler(request): - return raw(b"raw bytes") + return raw(B"raw bytes") ``` ```` -### Redirect +### 重定向 -.. column:: +.. 列: ``` -**Default Content-Type**: `text/html; charset=utf-8` -**Description**: Send a `302` response to redirect the client to a different path +**默认Content-Type**: `text/html; charset=utf-8` +**Description**: 发送一个 `302` 响应来将客户重定向到另一个路径 ``` -.. column:: +.. 列: ```` ```python -from sanic import redirect +from sanic import redirecte @app.route("/") async def handler(request): @@ -205,61 +205,61 @@ async def handler(request): ``` ```` -### Empty +### 空的 -.. column:: +.. 列: ``` -**Default Content-Type**: N/A -**Description**: For responding with an empty message as defined by [RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) +**默认 Content-Type**: N/A +**Description**: 为响应[RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) ``` -.. column:: +.. 列: ```` ```python -from sanic import empty +来自sanic import 空 @app.route("/") async def handler(request): return empty() ``` -Defaults to a `204` status. +默认`204` 状态。 ```` -## Default status +## 默认状态 -The default HTTP status code for the response is `200`. If you need to change it, it can be done by the response method. +响应默认的 HTTP 状态代码是 \`200'。 如果您需要更改它，它可以通过响应方式完成。 ```python @app.post("/") async def create_new(request): - new_thing = await do_create(request) + new_thing = 等待do_create(request) return json({"created": True, "id": new_thing.thing_id}, status=201) ``` -## Returning JSON data +## 返回 JSON 数据 Starting in v22.12, When you use the `sanic.json` convenience method, it will return a subclass of `HTTPResponse` called :class:`sanic.response.types.JSONResponse`. This object will have several convenient methods available to modify common JSON body. ```python -from sanic import json +从沙尼导入 json resp = json(...) ``` -- `resp.set_body()` - Set the body of the JSON object to the value passed -- `resp.append()` - Append a value to the body like `list.append` (only works if the root JSON is an array) -- `resp.extend()` - Extend a value to the body like `list.extend` (only works if the root JSON is an array) -- `resp.update()` - Update the body with a value like `dict.update` (only works if the root JSON is an object) -- `resp.pop()` - Pop a value like `list.pop` or `dict.pop` (only works if the root JSON is an array or an object) +- `resp.set_body()` - 设定JSON对象的正文到传递的值 +- `resp.append()` - 追加一个 `list.append` 这个物体的值(仅当root JSON 是一个数组时才起作用) +- `resp.extend()` - 将一个值扩展到物体像`list.extend` (仅当root JSON 是一个数组时才能工作) +- `resp.update()` - 更新像`dict.update` 这样的物体(仅当root JSON是一个对象时才工作) +- `resp.pop()` - 弹出一个 `list.pop` 或 `dict.pop` 等值(仅当root JSON 是数组或对象时才起作用) -.. warning:: +.. 警告：: ``` -The raw Python object is stored on the `JSONResponse` object as `raw_body`. While it is safe to overwrite this value with a new one, you should **not** attempt to mutate it. You should instead use the methods listed above. +原生的 Python 对象作为`raw_body` 存储在 `JSONResponse` 对象上。 虽然用新值覆盖此值是安全的，但是你应该**不应该**试图变换它。 你应该使用上面列出的方法。 ``` ```python @@ -279,21 +279,21 @@ resp.raw_body.update({"something": "else"}) ``` ```python -# Or, even treat it like a list +# 或者，甚至将其视为列表 resp = json(["foo", "bar"]) -# This is OKAY -resp.raw_body = ["foo", "bar", "something", "else"] +# 这是非常重要的 +resp. aw_body = ["foo", "bar", "something", "else"] -# This is better -resp.extend(["something", "else"]) +# 这是更好的 +resp. xtend(["something", "else"]) -# This is also works well +# 这也很适合 resp.append("something") resp.append("else") -# This is NOT OKAY +# 这不是很重要的 resp.raw_body.append("something") ``` -_Added in v22.9_ +_添加于 v22.9_ From 6bb93d1abd86d2f93a1585e11bf58cc9df16b5f2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:44 +0200 Subject: [PATCH 314/698] New translations routing.md (Japanese) --- guide/content/ja/guide/basics/routing.md | 322 +++++++++++------------ 1 file changed, 161 insertions(+), 161 deletions(-) diff --git a/guide/content/ja/guide/basics/routing.md b/guide/content/ja/guide/basics/routing.md index 243b8a0e9a..bc77198980 100644 --- a/guide/content/ja/guide/basics/routing.md +++ b/guide/content/ja/guide/basics/routing.md @@ -1,18 +1,18 @@ -# Routing +# ルーティング -.. column:: +.. 列:: ``` -So far we have seen a lot of this decorator in different forms. +これまで、様々な形でこのデコレータをたくさん見てきました。 -But what is it? And how do we use it? +しかし、それは何ですか？そして、どのように使うのですか？ ``` -.. column:: +.. 列:: ```` ```python -@app.route("/stairway") +@app.route("/storeway") ... @app.get("/to") @@ -23,17 +23,17 @@ But what is it? And how do we use it? ``` ```` -## Adding a route +## ルートの追加 -.. column:: +.. 列:: ``` -The most basic way to wire up a handler to an endpoint is with `app.add_route()`. +ハンドラをエンドポイントに接続する最も基本的な方法は、 `app.add_route()` です。 -See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.Sanic.url_for) for more details. +詳細は [API docs](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.url_for) を参照してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -44,13 +44,13 @@ app.add_route(handler, "/test") ``` ```` -.. column:: +.. 列:: ``` -By default, routes are available as an HTTP `GET` call. You can change a handler to respond to one or more HTTP methods. +デフォルトでは、ルートは HTTP `GET` 呼び出しとして使用できます。ハンドラーを1つまたは複数の HTTP メソッドに応答するように変更できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -62,13 +62,13 @@ app.add_route( ``` ```` -.. column:: +.. 列:: ``` -Using the decorator syntax, the previous example is identical to this. +デコレータ構文を使用すると、前の例はこれと同じです。 ``` -.. column:: +.. 列:: ```` ```python @@ -78,11 +78,11 @@ async def handler(request): ``` ```` -## HTTP methods +## HTTPメソッド -Each of the standard HTTP methods has a convenience decorator. +それぞれの標準的な HTTP メソッドには、利便性のデコレータがあります。 -### GET +### 取得 ```python @app.get('/test') @@ -100,7 +100,7 @@ async def handler(request): return text('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) +[MDN Docs](https\://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST ### PUT @@ -122,7 +122,7 @@ async def handler(request): [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) -### DELETE +### 削除 ```python @app.delete('/test') @@ -132,7 +132,7 @@ async def handler(request): [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) -### HEAD +### 頭 ```python @app.head('/test') @@ -142,7 +142,7 @@ async def handler(request): [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) -### OPTIONS +### オプション ```python @app.options('/test') @@ -152,7 +152,7 @@ async def handler(request): [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) -.. warning:: +.. 警告:: ```` By default, Sanic will **only** consume the incoming request body on non-safe HTTP methods: `POST`, `PUT`, `PATCH`, `DELETE`. If you want to receive data in the HTTP request on any other method, you will need to do one of the following two options: @@ -172,15 +172,15 @@ async def handler(request: Request): ``` ```` -## Path parameters +## パスパラメータ -.. column:: +.. 列:: ``` -Sanic allows for pattern matching, and for extracting values from URL paths. These parameters are then injected as keyword arguments in the route handler. +SanicはパターンマッチングとURLパスからの値抽出を可能にします。これらのパラメータはルートハンドラのキーワード引数として注入されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -190,13 +190,13 @@ async def tag_handler(request, tag): ``` ```` -.. column:: +.. 列:: ``` -You can declare a type for the parameter. This will be enforced when matching, and also will type cast the variable. +パラメータの型を宣言できます。これはマッチング時に強制され、変数をキャストします。 ``` -.. column:: +.. 列:: ```` ```python @@ -206,13 +206,13 @@ async def uuid_handler(request, foo_id: UUID): ``` ```` -.. column:: +.. 列:: ``` -For some standard types like `str`, `int`, and `UUID`, Sanic can infer the path parameter type from the function signature. This means that it may not always be necessary to include the type in the path parameter definition. +`str`、`int`、`UUID`のようないくつかの標準型では、Sanicは関数のシグネチャからパスパラメータ型を推測することができます。 つまり、pathパラメータ定義に型を含める必要があるわけではありません。 ``` -.. column:: +.. 列:: ```` ```python @@ -222,24 +222,24 @@ async def uuid_handler(request, foo_id: UUID): ``` ```` -### Supported types +### サポートされているタイプ ### `str` -.. column:: +.. 列:: ``` -**Regular expression applied**: `r"[^/]+"` -**Cast type**: `str` -**Example matches**: +**正規表現が適用されました**: `r"[^/]+"` +**キャストタイプ**: `str` +**一致例**: - `/path/to/Bob` - `/path/to/Python%203` -Beginning in v22.3 `str` will *not* match on empty strings. See `strorempty` for this behavior. +v22から始まります。 `str`は空の文字列では*マッチしません*。この動作については`strorempty`を参照してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -251,7 +251,7 @@ async def handler(request, foo: str): ### `strorempty` -.. column:: +.. 列:: ``` **Regular expression applied**: `r"[^/]*"` @@ -267,7 +267,7 @@ Unlike the `str` path parameter type, `strorempty` can also match on an empty st *Added in v22.3* ``` -.. column:: +.. 列:: ```` ```python @@ -279,20 +279,20 @@ async def handler(request, foo: str): ### `int` -.. column:: +.. 列:: ``` -**Regular expression applied**: `r"-?\d+"` -**Cast type**: `int` -**Example matches**: +**正規表現が適用されます**: `r"-?\d+"` +**キャストタイプ**: `int` +**一致例**: - `/path/to/10` - `/path/to/-10` -_Does not match float, hex, octal, etc_ +_float, hex, octal, etc_ ``` -.. column:: +.. 列:: ```` ```python @@ -304,19 +304,19 @@ async def handler(request, foo: int): ### `float` -.. column:: +.. 列:: ``` -**Regular expression applied**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)"` -**Cast type**: `float` -**Example matches**: +**正規表現が適用されます**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)"` +**キャストタイプ**: `float` +**マッチ例**: - `/path/to/10` - `/path/to/-10` - `/path/to/1.5` ``` -.. column:: +.. 列:: ```` ```python @@ -328,20 +328,20 @@ async def handler(request, foo: float): ### `alpha` -.. column:: +.. 列:: ``` -**Regular expression applied**: `r"[A-Za-z]+"` -**Cast type**: `str` -**Example matches**: +**正規表現が適用されました**: `r"[A-Za-z]+"` +**キャストタイプ**: `str` +**一致例**: - `/path/to/Bob` - `/path/to/Python` -_Does not match a digit, or a space or other special character_ +_数字と一致しません。 またはスペースまたはその他の特殊文字_ ``` -.. column:: +.. 列:: ```` ```python @@ -353,20 +353,20 @@ async def handler(request, foo: str): ### `slug` -.. column:: +.. 列:: ``` -**Regular expression applied**: `r"[a-z0-9]+(?:-[a-z0-9]+)*"` -**Cast type**: `str` -**Example matches**: +**正規表現が適用されます**: `r"[a-z0-9]+(?:-[a-z0-9]+)*"` +**キャストタイプ**: `str` +**一致例**: - `/path/to/some-news-story` - `/path/to/or-has-digits-123` -*Added in v21.6* +*v21.6* に追加されました ``` -.. column:: +.. 列:: ```` ```python @@ -378,18 +378,18 @@ async def handler(request, article: str): ### `path` -.. column:: +.. 列:: ``` -**Regular expression applied**: `r"[^/].*?"` -**Cast type**: `str` -**Example matches**: +**正規表現が適用されます**: `r"[^/].*?"` +**キャストタイプ**: `str` +**一致例**: - `/path/to/hello` - `/path/to/hello.txt` - `/path/to/hello/world.txt` ``` -.. column:: +.. 列:: ```` ```python @@ -399,15 +399,15 @@ async def handler(request, foo: str): ``` ```` -.. warning:: +.. 警告:: ``` -Because this will match on `/`, you should be careful and thoroughly test your patterns that use `path` so they do not capture traffic intended for another endpoint. Additionally, depending on how you use this type, you may be creating a path traversal vulnerability in your application. It is your job to protect your endpoint against this, but feel free to ask in our community channels for help if you need it :) +これは `/` にマッチするためです。 `path`を使ってパターンをテストすれば、別の端点に向かってトラフィックを捕まえることができません。 さらに、このタイプの使い方に応じて、アプリケーションにパストラバーサルの脆弱性を作成する可能性があります。 これに対してエンドポイントを保護するのはあなたの仕事です。 でも必要な場合はコミュニティチャンネルでお気軽にお問い合わせください :) ``` ### `ymd` -.. column:: +.. 列:: ``` **Regular expression applied**: `r"^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))"` @@ -417,7 +417,7 @@ Because this will match on `/`, you should be careful and thoroughly test your p - `/path/to/2021-03-28` ``` -.. column:: +.. 列:: ```` ```python @@ -429,7 +429,7 @@ async def handler(request, foo: datetime.date): ### `uuid` -.. column:: +.. 列:: ``` **Regular expression applied**: `r"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}"` @@ -439,7 +439,7 @@ async def handler(request, foo: datetime.date): - `/path/to/123a123a-a12a-1a1a-a1a1-1a12a1a12345` ``` -.. column:: +.. 列:: ```` ```python @@ -451,15 +451,15 @@ async def handler(request, foo: UUID): ### ext -.. column:: +.. 列:: ``` -**Regular expression applied**: n/a -**Cast type**: *varies* -**Example matches**: +**正規表現が適用されました**: n/a +**キャストタイプ**: *varies* +**一致例**: ``` -.. column:: +.. 列:: ```` ```python @@ -469,7 +469,7 @@ async def handler(request, foo: str, ext: str): ``` ```` -| definition | example | filename | extension | +| 定義 | 例 | ファイル名 | 拡張 | | ---------------------------------- | ----------- | -------- | ---------- | | \ | page.txt | `"page"` | `"txt"` | | \ | cat.jpg | `"cat"` | `"jpg"` | @@ -478,15 +478,15 @@ async def handler(request, foo: str, ext: str): | \ | 123.svg | `123` | `"svg"` | | \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | -File extensions can be matched using the special `ext` parameter type. It uses a special format that allows you to specify other types of parameter types as the file name, and one or more specific extensions as shown in the example table above. +ファイル拡張子は、特別なパラメータタイプ`ext`を使用して一致させることができます。 これは、ファイル名として他のタイプのパラメータを指定することができる特別な形式を使用します。 上の表に示されているように、1つまたは複数の特定の拡張子を指定します。 -It does _not_ support the `path` parameter type. +`path`パラメータ型は\*サポートしていません。 -_Added in v22.3_ +_v22.3_に追加されました -### regex +### Regex -.. column:: +.. 列:: ``` **Regular expression applied**: _whatever you insert_ @@ -500,7 +500,7 @@ This gives you the freedom to define specific matching patterns for your use cas In the example shown, we are looking for a date that is in `YYYY-MM-DD` format. ``` -.. column:: +.. 列:: ```` ```python @@ -510,23 +510,23 @@ async def handler(request, foo: str): ``` ```` -### Regex Matching +### 正規表現の一致 -More often than not, compared with complex routing, the above example is too simple, and we use a completely different routing matching pattern, so here we will explain the advanced usage of regex matching in detail. +多くの場合、複雑なルーティングと比較して、上記の例は単純すぎます。 我々は全く異なるルーティングマッチングパターンを使っています ここではRegexマッチングの高度な使い方を詳しく説明します -Sometimes, you want to match a part of a route: +ルートの一部をマッチさせたい場合もあります。 ```text /image/123456789.jpg ``` -If you wanted to match the file pattern, but only capture the numeric portion, you need to do some regex fun 😄: +ファイルパターンを一致させたいが、数値部分だけをキャプチャしたい場合は、正規表現の楽しみ😄: ```python app.route(r"/image/\d+)\.jpg>") ``` -Further, these should all be acceptable: +さらに、これらはすべて許容されるべきです: ```python @app.get(r"/") # matching on the full pattern @@ -535,24 +535,24 @@ Further, these should all be acceptable: @app.get(r"/[a-z]{3}).(?:txt)>") # defining a single named matching group, with one or more non-matching groups ``` -Also, if using a named matching group, it must be the same as the segment label. +また、名前付きの一致グループを使用する場合は、セグメント ラベルと同じでなければなりません。 ```python @app.get(r"/\d+).jpg>") # OK @app.get(r"/\d+).jpg>") # NOT OK ``` -For more regular usage methods, please refer to [Regular expression operations](https://docs.python.org/3/library/re.html) +format@@0(https\://docs.python.org/3/library/re.html) を参照してください。 -## Generating a URL +## URLの生成 -.. column:: +.. 列:: ``` -Sanic provides a method to generate URLs based on the handler method name: `app.url_for()`. This is useful if you want to avoid hardcoding url paths into your app; instead, you can just reference the handler name. +Sanicはハンドラメソッド名`app.url_for()`に基づいてURLを生成するメソッドを提供しています。 これは、アプリケーション内のハードコーディングの url パスを避けたい場合に便利です。代わりに、ハンドラ名を参照するだけです。 ``` -.. column:: +.. 列:: ```` ```python @@ -570,13 +570,13 @@ async def post_handler(request, post_id): ``` ```` -.. column:: +.. 列:: ``` -You can pass any arbitrary number of keyword arguments. Anything that is _not_ a request parameter will be implemented as a part of the query string. +任意の数のキーワード引数を渡せます。 リクエストパラメータでないものは、クエリ文字列の一部として実装されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -584,18 +584,18 @@ assert app.url_for( "post_handler", post_id=5, arg_one="one", - arg_two="two", -) == "/posts/5?arg_one=one&arg_two=two" + arg_two", +) == "/posts/5?arg_one=one&arg_two" ``` ```` -.. column:: +.. 列:: ``` -Also supported is passing multiple values for a single query key. +また、単一のクエリキーに複数の値を渡すこともサポートされています。 ``` -.. column:: +.. 列:: ```` ```python @@ -603,13 +603,13 @@ assert app.url_for( "post_handler", post_id=5, arg_one=["one", "two"], -) == "/posts/5?arg_one=one&arg_one=two" +) == "/posts/5?arg_one=one_one=two" ``` ```` -### Special keyword arguments +### 特殊キーワード引数 -See API Docs for more details. +詳細は API Docs を参照してください。 ```python app.url_for("post_handler", post_id=5, arg_one="one", _anchor="anchor") @@ -628,15 +628,15 @@ app.url_for("post_handler", post_id=5, arg_one=["one", "two"], arg_two=2, _ancho # 'http://another_server:8888/posts/5?arg_one=one&arg_one=two&arg_two=2#anchor' ``` -### Customizing a route name +### ルート名をカスタマイズ -.. column:: +.. 列:: ``` -A custom route name can be used by passing a `name` argument while registering the route. +route (ルート)を登録する際に `name` 引数を渡すことで、カスタムルート名を使用できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -646,13 +646,13 @@ def handler(request): ``` ```` -.. column:: +.. 列:: ``` -Now, use this custom name to retrieve the URL +このカスタム名を使用してURLを取得する ``` -.. column:: +.. 列:: ```` ```python @@ -662,13 +662,13 @@ assert app.url_for("get_handler", foo="bar") == "/get?foo=bar" ## Websockets routes -.. column:: +.. 列:: ``` -Websocket routing works similar to HTTP methods. +Websocket ルーティングは HTTP メソッドに似ています。 ``` -.. column:: +.. 列:: ```` ```python @@ -682,18 +682,18 @@ app.add_websocket_route(handler, "/test") ``` ```` -.. column:: +.. 列:: ``` -It also has a convenience decorator. +それはまた、コンビニエンスデコレータを持っています。 ``` -.. column:: +.. 列:: ```` ```python @app.websocket("/test") -async def handler(request, ws): +async def handler(request, ws: message = "Start" while True: await ws.send(message) @@ -701,11 +701,11 @@ async def handler(request, ws): ``` ```` -Read the [websockets section](/guide/advanced/websockets.md) to learn more about how they work. +動作の詳細については、[websockets section](/guide/advanced/websockets.md) をご覧ください。 -## Strict slashes +## 厳密なスラッシュ -.. column:: +.. 列:: ``` Sanic routes can be configured to strictly match on whether or not there is a trailing slash: `/`. This can be configured at a few levels and follows this order of precedence: @@ -716,7 +716,7 @@ Sanic routes can be configured to strictly match on whether or not there is a tr 4. Application ``` -.. column:: +.. 列:: ```` ```python @@ -755,9 +755,9 @@ group = Blueprint.group([bp1, bp2], strict_slashes=True) ``` ```` -## Static files +## 静的ファイル -.. column:: +.. 列:: ``` In order to serve static files from Sanic, use `app.static()`. @@ -770,7 +770,7 @@ The order of arguments is important: See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic.static) for more details. ``` -.. column:: +.. 列:: ```` ```python @@ -781,16 +781,16 @@ app.static("/static/", "/path/to/directory/") .. tip:: ``` -It is generally best practice to end your directory paths with a trailing slash (`/this/is/a/directory/`). This removes ambiguity by being more explicit. +一般的には、ディレクトリパスをスラッシュ(`/this/is/a/directory/`)で終わらせることをお勧めします。これにより、より明示的に曖昧さを削除します。 ``` -.. column:: +.. 列:: ``` -You can also serve individual files. +個々のファイルを提供することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -798,13 +798,13 @@ app.static("/", "/path/to/index.html") ``` ```` -.. column:: +.. 列:: ``` -It is also sometimes helpful to name your endpoint +エンドポイントに名前を付けることも時々役に立ちます ``` -.. column:: +.. 列:: ```` ```python @@ -816,13 +816,13 @@ app.static( ``` ```` -.. column:: +.. 列:: ``` -Retrieving the URLs works similar to handlers. But, we can also add the `filename` argument when we need a specific file inside a directory. +URL の取得はハンドラに似ていますが、ディレクトリ内に特定のファイルが必要な場合は、 `filename` 引数を追加することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -845,7 +845,7 @@ assert app.url_for( .. tip:: ```` -If you are going to have multiple `static()` routes, then it is *highly* suggested that you manually name them. This will almost certainly alleviate potential hard to discover bugs. +複数の `static()`ルートを持つ場合は、手動で名前を付けることを提案されています。 これはバグを発見することが難しい可能性をほぼ確実に緩和します。 ```python app.static("/user/uploads/", "/path/to/uploads/", name="uploads") @@ -853,33 +853,33 @@ app.static("/user/profile/", "/path/to/profile/", name="profile_pics") ``` ```` -#### Auto index serving +#### 自動インデックス作成 -.. column:: +.. 列:: ``` -If you have a directory of static files that should be served by an index page, you can provide the filename of the index. Now, when reaching that directory URL, the index page will be served. +indexページによって提供されるべき静的ファイルのディレクトリがある場合は、indexのファイル名を指定できます。 ディレクトリの URL に到達すると、インデックス ページが表示されます。 ``` -.. column:: +.. 列:: ```` ```python -app.static("/foo/", "/path/to/foo/", index="index.html") +app.static("/foo/", "/path/to/foo/", index="index="html") ``` ```` -_Added in v23.3_ +_V23.3_に追加されました -#### File browser +#### ファイルブラウザー -.. column:: +.. 列:: ``` -When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. +静的ハンドラからディレクトリを提供する場合、Sanic は `directory_view=True` を使用して基本的なファイルブラウザーを表示するように設定することができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -887,21 +887,21 @@ app.static("/uploads/", "/path/to/dir", directory_view=True) ``` ```` -You now have a browsable directory in your web browser: +ブラウザーにブラウザーが表示されるようになりました： ![image](/assets/images/directory-view.png) -_Added in v23.3_ +_V23.3_に追加されました -## Route context +## ルートの説明 -.. column:: +.. 列:: ``` -When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. +route (ルート)が定義された場合、任意の数のキーワード引数を `ctx_` プレフィックスで追加できます。 これらの値はルート `ctx` オブジェクトに注入されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -924,4 +924,4 @@ async def do_something(request): ``` ```` -_Added in v21.12_ +_v21.12_ に追加されました From 7145b3bc3e8d521e00d822200a885ea71476ff90 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:46 +0200 Subject: [PATCH 315/698] New translations routing.md (Chinese Simplified) --- guide/content/zh/guide/basics/routing.md | 472 +++++++++++------------ 1 file changed, 236 insertions(+), 236 deletions(-) diff --git a/guide/content/zh/guide/basics/routing.md b/guide/content/zh/guide/basics/routing.md index 243b8a0e9a..da121a5fca 100644 --- a/guide/content/zh/guide/basics/routing.md +++ b/guide/content/zh/guide/basics/routing.md @@ -1,6 +1,6 @@ -# Routing +# 路由 -.. column:: +.. 列: ``` So far we have seen a lot of this decorator in different forms. @@ -8,7 +8,7 @@ So far we have seen a lot of this decorator in different forms. But what is it? And how do we use it? ``` -.. column:: +.. 列: ```` ```python @@ -23,9 +23,9 @@ But what is it? And how do we use it? ``` ```` -## Adding a route +## 添加路由 -.. column:: +.. 列: ``` The most basic way to wire up a handler to an endpoint is with `app.add_route()`. @@ -33,42 +33,42 @@ The most basic way to wire up a handler to an endpoint is with `app.add_route()` See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.Sanic.url_for) for more details. ``` -.. column:: +.. 列: ```` ```python -async def handler(request): +async def 处理器(请求): return text("OK") app.add_route(handler, "/test") ``` ```` -.. column:: +.. 列: ``` -By default, routes are available as an HTTP `GET` call. You can change a handler to respond to one or more HTTP methods. +默认情况下，路由是可用的 HTTP `GET` 调用。您可以更改处理程序来响应一个或多个HTTP方法。 ``` -.. column:: +.. 列: ```` ```python app.add_route( handler, '/test', - methods=["POST", "PUT"], + meths=["POST", "PUT", ) ``` ```` -.. column:: +.. 列: ``` -Using the decorator syntax, the previous example is identical to this. +使用装饰符语法, 前面的示例与此相同。 ``` -.. column:: +.. 列: ```` ```python @@ -78,21 +78,21 @@ async def handler(request): ``` ```` -## HTTP methods +## HTTP 方法 -Each of the standard HTTP methods has a convenience decorator. +每种标准HTTP方法都有一个方便装饰器。 -### GET +### 获取 ```python @app.get('/test') -async def handler(request): - return text('OK') +async def 处理器(请求): + 返回文本('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/GET) -### POST +### 帖子 ```python @app.post('/test') @@ -100,14 +100,14 @@ async def handler(request): return text('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/POST) -### PUT +### 弹出 ```python @app.put('/test') -async def handler(request): - return text('OK') +async def 处理器(请求): + 返回文本('OK') ``` [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) @@ -116,117 +116,117 @@ async def handler(request): ```python @app.patch('/test') -async def handler(request): - return text('OK') +async def 处理器(请求): + 返回文本('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/PATCH) -### DELETE +### 删除 ```python @app.delete('/test') -async def handler(request): - return text('OK') +async def 处理器(请求): + 返回文本('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/DELETE) -### HEAD +### 黑色 ```python @app.head('/test') -async def handler(request): +async def 处理器(请求): return empty() ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/HEAD) -### OPTIONS +### 选项 ```python @app.options('/test') -async def handler(request): +async def 处理器(请求): return empty() ``` [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) -.. warning:: +.. 警告：: ```` -By default, Sanic will **only** consume the incoming request body on non-safe HTTP methods: `POST`, `PUT`, `PATCH`, `DELETE`. If you want to receive data in the HTTP request on any other method, you will need to do one of the following two options: +默认情况下，Sanic **只**在不安全的 HTTP 方法上消耗传入的请求机构：“POST`、`PUT`、`PATCH`、`DELETE`”。 如果您想要在 HTTP 请求中在任何其他方法上接收数据，， 您将需要做以下两个选项之一： -**Option #1 - Tell Sanic to consume the body using `ignore_body`** +**选项#1 - 告诉Sanic使用`ignore_body`** ```python -@app.request("/path", ignore_body=False) +@app。 赤道("/path", ignore_body=False) async def handler(_): ... ``` -**Option #2 - Manually consume the body in the handler using `receive_body`** +**Option #2 - 手动使用 `receive_body`** ```python -@app.get("/path") -async def handler(request: Request): - await request.receive_body() +@app. et("/path") +async def 处理器(请求: 请求): + 等待request.receive_body() ``` ```` -## Path parameters +## 路径参数 -.. column:: +.. 列: ``` -Sanic allows for pattern matching, and for extracting values from URL paths. These parameters are then injected as keyword arguments in the route handler. +Sanic 允许模式匹配，也允许从 URL 路径中提取值。然后这些参数作为关键词参数在路由处理器中注入。 ``` -.. column:: +.. 列: ```` ```python @app.get("/tag/") -async def tag_handler(request, tag): - return text("Tag - {}".format(tag)) +async def tag_handler(请求，标签): + return text("Tag - {}".form(标签)) ``` ```` -.. column:: +.. 列: ``` -You can declare a type for the parameter. This will be enforced when matching, and also will type cast the variable. +您可以声明参数类型。匹配时将强制执行，并且还将输入变量。 ``` -.. column:: +.. 列: ```` ```python -@app.get("/foo/") +@app.get("/fo/") async def uuid_handler(request, foo_id: UUID): - return text("UUID - {}".format(foo_id)) + return text("UUUID - {}".format (fo_id)) ``` ```` -.. column:: +.. 列: ``` -For some standard types like `str`, `int`, and `UUID`, Sanic can infer the path parameter type from the function signature. This means that it may not always be necessary to include the type in the path parameter definition. +对于一些标准类型，如`str`、`int`和`UUID`，Sanic可以从函数签名中推断路径参数类型。 这意味着可能并非总是需要在路径参数定义中包含类型。 ``` -.. column:: +.. 列: ```` ```python -@app.get("/foo/") # Notice there is no :uuid in the path parameter -async def uuid_handler(request, foo_id: UUID): - return text("UUID - {}".format(foo_id)) +@app。 et("/foo/") # 路径参数 +async def uuid_handler不存在:uuid (请求) foo_id: UUID: + return text("UUID - {}" ormat(fo_id)) ``` ```` -### Supported types +### 支持的类型 ### `str` -.. column:: +.. 列: ``` **Regular expression applied**: `r"[^/]+"` @@ -239,19 +239,19 @@ async def uuid_handler(request, foo_id: UUID): Beginning in v22.3 `str` will *not* match on empty strings. See `strorempty` for this behavior. ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: str): +Async def 处理器(请求, foo: str): ... ``` ```` ### `strorempty` -.. column:: +.. 列: ``` **Regular expression applied**: `r"[^/]*"` @@ -267,169 +267,169 @@ Unlike the `str` path parameter type, `strorempty` can also match on an empty st *Added in v22.3* ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: str): +Async def 处理器(请求, foo: str): ... ``` ```` ### `int` -.. column:: +.. 列: ``` -**Regular expression applied**: `r"-?\d+"` -**Cast type**: `int` -**Example matches**: +**正则表达式已应用**: `r"-?\d+" +**Cast 类型**: `int` +**示例匹配** : - `/path/to/10` - `/path/to/-10` -_Does not match float, hex, octal, etc_ +_不匹配浮点, 十六进制, octal等_ ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: int): +Async def 处理器(请求, foo: int): ... ``` ```` ### `float` -.. column:: +.. 列: ``` -**Regular expression applied**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)"` -**Cast type**: `float` -**Example matches**: +**正则表达式已应用**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)" +**投射类型**: `float` +**示例匹配**: - `/path/to/10` - `/path/to/-10` - `/path/to/1.5` ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: float): +Async def 处理器(请求，foo: float): ... ``` ```` ### `alpha` -.. column:: +.. 列: ``` -**Regular expression applied**: `r"[A-Za-z]+"` -**Cast type**: `str` -**Example matches**: +**正则表达式已应用**：`r'[A-Za-z]+"` +**快速类型**：`str` +**示例匹配**： - `/path/to/Bob` - `/path/to/Python` -_Does not match a digit, or a space or other special character_ +_不匹配数字， 或空格或其他特殊字符_ ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: str): +Async def 处理器(请求, foo: str): ... ``` ```` ### `slug` -.. column:: +.. 列: ``` -**Regular expression applied**: `r"[a-z0-9]+(?:-[a-z0-9]+)*"` -**Cast type**: `str` -**Example matches**: +**正则表达式**：`r'[a-z0-9]+(?:-[a-z0-9]+)*" +**快速类型**：`str` +**示例匹配**： - `/path/to/some-news-story` - `/path/to/or-has-digits-123` -*Added in v21.6* +*添加于v21.6* ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, article: str): +async def 处理器(请求，文章: str): ... ``` ```` ### `path` -.. column:: +.. 列: ``` -**Regular expression applied**: `r"[^/].*?"` -**Cast type**: `str` -**Example matches**: +**正则表达式已应用**: `r"[^/].*?" +**快速类型**: `str` +**示例匹配**: - `/path/to/hello` - `/path/to/hello.txt` - `/path/to/hello/world.txt` ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: str): +Async def 处理器(请求, foo: str): ... ``` ```` -.. warning:: +.. 警告：: ``` -Because this will match on `/`, you should be careful and thoroughly test your patterns that use `path` so they do not capture traffic intended for another endpoint. Additionally, depending on how you use this type, you may be creating a path traversal vulnerability in your application. It is your job to protect your endpoint against this, but feel free to ask in our community channels for help if you need it :) +因为这将在`/`上匹配， 你应该仔细和彻底地测试你使用`path`的模式，这样他们就不会捕获打算用于另一端点的流量。 此外，根据您如何使用这种类型，您可能会在应用程序中创建一条横向脆弱性。 你的任务是保护你的终点不受这种影响。 但如果您需要帮助，请在我们的社区频道中寻求帮助:) ``` ### `ymd` -.. column:: +.. 列: ``` -**Regular expression applied**: `r"^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))"` -**Cast type**: `datetime.date` -**Example matches**: +**正则表达式已应用**: `r"^([12]\d{3}( 0[1-9]|1[0-2])-( 0[1-9]|[12]\d|3[01])"" +**Cast类型**: `datetime. +**示例匹配**: - `/path/to/2021-03-28` ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: datetime.date): +Async def 处理程序(请求，foo: datetime.date): ... ``` ```` ### `uuid` -.. column:: +.. 列: ``` **Regular expression applied**: `r"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}"` @@ -439,94 +439,94 @@ async def handler(request, foo: datetime.date): - `/path/to/123a123a-a12a-1a1a-a1a1-1a12a1a12345` ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: UUID): +Async def 处理器(请求, foo: UUID): ... ``` ```` ### ext -.. column:: +.. 列: ``` -**Regular expression applied**: n/a -**Cast type**: *varies* -**Example matches**: +**正则表达式**：n/a +**铸造类型**：*varies* +**示例匹配**： ``` -.. column:: +.. 列: ```` ```python @app.route("/path/to/") -async def handler(request, foo: str, ext: str): +Async def 处理程序(请求，foo: str, ext: str): ... ``` ```` -| definition | example | filename | extension | -| ---------------------------------- | ----------- | -------- | ---------- | -| \ | page.txt | `"page"` | `"txt"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| 定义 | 示例 | 文件名 | 扩展 | +| ---------------------------------- | ----------- | -------- | ----------- | +| \ | 页次 | `"page"` | `"txt"` | +| \ | jpg | `"cat"` | \`"jpg"" | +| \ | jpg | `"cat"` | \`"jpg"" | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | -File extensions can be matched using the special `ext` parameter type. It uses a special format that allows you to specify other types of parameter types as the file name, and one or more specific extensions as shown in the example table above. +文件扩展名可以使用特殊的 `ext` 参数类型匹配。 它使用特殊格式，允许您指定其他类型的参数类型作为文件名。 和上面的示例表所示的一个或多个具体扩展。 -It does _not_ support the `path` parameter type. +它不支持 `path` 参数类型。 -_Added in v22.3_ +_添加于 v22.3_ -### regex +### 正则表达式 -.. column:: +.. 列: ``` -**Regular expression applied**: _whatever you insert_ -**Cast type**: `str` -**Example matches**: +**正则表达式已应用**：_无论你插入了什么样的 +**投射类型**：`str` +**示例匹配**： - `/path/to/2021-01-01` -This gives you the freedom to define specific matching patterns for your use case. +这使你能够自由地定义你使用的特定匹配模式。 -In the example shown, we are looking for a date that is in `YYYY-MM-DD` format. +在所显示的示例中，我们正在寻找一个 `YYYY-MM-DD` 格式的日期。 ``` -.. column:: +.. 列: ```` ```python @app.route(r"/path/to/") -async def handler(request, foo: str): +async def 处理程序(请求，foo: str): ... ``` ```` -### Regex Matching +### 正则表达式匹配 -More often than not, compared with complex routing, the above example is too simple, and we use a completely different routing matching pattern, so here we will explain the advanced usage of regex matching in detail. +与复杂的路由相比，上述例子往往太简单， 我们使用完全不同的路由匹配模式，所以我们将在这里详细解释正则表达式匹配的高级用途。 -Sometimes, you want to match a part of a route: +有时候你想要匹配路由的一部分： ```text /image/123456789.jpg ``` -If you wanted to match the file pattern, but only capture the numeric portion, you need to do some regex fun 😄: +如果你想要匹配文件模式，但仅捕获数字部分，你需要做一些regex funn 😄: ```python app.route(r"/image/\d+)\.jpg>") ``` -Further, these should all be acceptable: +此外，所有这些都应当是可以接受的： ```python @app.get(r"/") # matching on the full pattern @@ -535,81 +535,81 @@ Further, these should all be acceptable: @app.get(r"/[a-z]{3}).(?:txt)>") # defining a single named matching group, with one or more non-matching groups ``` -Also, if using a named matching group, it must be the same as the segment label. +而且，如果使用一个命名匹配组，它必须与段标签相同。 ```python @app.get(r"/\d+).jpg>") # OK @app.get(r"/\d+).jpg>") # NOT OK ``` -For more regular usage methods, please refer to [Regular expression operations](https://docs.python.org/3/library/re.html) +更多常规使用方法，请参阅[正则表达式操作](https://docs.python.org/3/library/re.html) -## Generating a URL +## 正在生成 URL -.. column:: +.. 列: ``` -Sanic provides a method to generate URLs based on the handler method name: `app.url_for()`. This is useful if you want to avoid hardcoding url paths into your app; instead, you can just reference the handler name. +Sanic 提供了一个基于处理方法名称：`app.url_for()`生成URL的方法。 如果你想要避免硬编码URL路径到你的应用，那么这将是有用的；相反，你只能引用处理程序名称。 ``` -.. column:: +.. 列: ```` ```python -@app.route('/') +@app。 oute('/') async def index(request): - # generate a URL for the endpoint `post_handler` - url = app.url_for('post_handler', post_id=5) + # 为端点 `post_handler` + url = app. rl_for('post_handler', post_id=5) - # Redirect to `/posts/5` + # 重定向到 "/posts/5" return redirect(url) -@app.route('/posts/') +@app. oute('/posts/') async def post_handler(request, post_id): ... ``` ```` -.. column:: +.. 列: ``` -You can pass any arbitrary number of keyword arguments. Anything that is _not_ a request parameter will be implemented as a part of the query string. +您可以传递任意数量的关键字参数。 任何为 _not_ 的请求参数都将作为查询字符串的一部分实现。 ``` -.. column:: +.. 列: ```` ```python -assert app.url_for( +claim app.url_for( "post_handler", post_id=5, arg_one="one", arg_two="two", -) == "/posts/5?arg_one=one&arg_two=two" +) =="/posts/5?arg_one=one&arg_two=two" ``` ```` -.. column:: +.. 列: ``` -Also supported is passing multiple values for a single query key. +还支持通过单个查询键的多个值。 ``` -.. column:: +.. 列: ```` ```python -assert app.url_for( +claim app.url_for( "post_handler", post_id=5, - arg_one=["one", "two"], -) == "/posts/5?arg_one=one&arg_one=two" + arg_one=["one", "two", +) =="/posts/5?arg_one=one=one&arg_one=two" ``` ```` -### Special keyword arguments +### 特殊关键字参数 -See API Docs for more details. +详见API Docs。 ```python app.url_for("post_handler", post_id=5, arg_one="one", _anchor="anchor") @@ -628,15 +628,15 @@ app.url_for("post_handler", post_id=5, arg_one=["one", "two"], arg_two=2, _ancho # 'http://another_server:8888/posts/5?arg_one=one&arg_one=two&arg_two=2#anchor' ``` -### Customizing a route name +### 自定义路由名称 -.. column:: +.. 列: ``` -A custom route name can be used by passing a `name` argument while registering the route. +在注册路由时可以通过 `name` 参数使用自定义路由名称。 ``` -.. column:: +.. 列: ```` ```python @@ -646,13 +646,13 @@ def handler(request): ``` ```` -.. column:: +.. 列: ``` -Now, use this custom name to retrieve the URL +现在，使用此自定义名称检索URL ``` -.. column:: +.. 列: ```` ```python @@ -660,63 +660,63 @@ assert app.url_for("get_handler", foo="bar") == "/get?foo=bar" ``` ```` -## Websockets routes +## Websockets路由 -.. column:: +.. 列: ``` -Websocket routing works similar to HTTP methods. +Websocket 路由器类似于HTTP方法。 ``` -.. column:: +.. 列: ```` ```python -async def handler(request, ws): +async def 处理器(请求) ws： message = "Start" - while True: - await ws.send(message) - message = await ws.recv() + 而True： + 等待w。 end(message) + message = 等待ws.recv() app.add_websocket_route(handler, "/test") ``` ```` -.. column:: +.. 列: ``` -It also has a convenience decorator. +它还有一个方便装饰器。 ``` -.. column:: +.. 列: ```` ```python @app.websocket("/test") -async def handler(request, ws): +async def handler(request, w): message = "Start" while True: - await ws.send(message) - message = await ws.recv() + request ws.send(message) + message = 等待ws.recv() ``` ```` -Read the [websockets section](/guide/advanced/websockets.md) to learn more about how they work. +阅读[websockets部分](/guide/advanced/websockets.md)以了解如何工作的更多信息。 -## Strict slashes +## 严格斜线 -.. column:: +.. 列: ``` -Sanic routes can be configured to strictly match on whether or not there is a trailing slash: `/`. This can be configured at a few levels and follows this order of precedence: +Sanic 路由可以被配置为完全匹配是否存在尾随斜线： `/`。 这可以在几个级别上进行配置，按照这个先后顺序排列： -1. Route -2. Blueprint -3. BlueprintGroup -4. Application +1。 Route +2. 蓝图 +3. 蓝图组 +4 应用程序 ``` -.. column:: +.. 列: ```` ```python @@ -755,9 +755,9 @@ group = Blueprint.group([bp1, bp2], strict_slashes=True) ``` ```` -## Static files +## 静态文件 -.. column:: +.. 列: ``` In order to serve static files from Sanic, use `app.static()`. @@ -770,27 +770,27 @@ The order of arguments is important: See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic.static) for more details. ``` -.. column:: +.. 列: ```` ```python -app.static("/static/", "/path/to/directory/") +app.static("/static/", "/path/to/directory") ``` ```` .. tip:: ``` -It is generally best practice to end your directory paths with a trailing slash (`/this/is/a/directory/`). This removes ambiguity by being more explicit. +通常最佳做法是以斜杠结束您的目录路径(`/this/is/a/directory/`)。这会通过更明确地去除模糊性。 ``` -.. column:: +.. 列: ``` -You can also serve individual files. +您也可以为个别文件服务。 ``` -.. column:: +.. 列: ```` ```python @@ -798,44 +798,44 @@ app.static("/", "/path/to/index.html") ``` ```` -.. column:: +.. 列: ``` -It is also sometimes helpful to name your endpoint +命名您的端点有时也是有用的 ``` -.. column:: +.. 列: ```` ```python app.static( "/user/uploads/", "/path/to/uploads/", - name="uploads", + name="上传", ) ``` ```` -.. column:: +.. 列: ``` -Retrieving the URLs works similar to handlers. But, we can also add the `filename` argument when we need a specific file inside a directory. +检索URL与处理程序相似。但当我们需要一个目录中的特定文件时，我们也可以添加 `filename` 参数。 ``` -.. column:: +.. 列: ```` ```python -assert app.url_for( +claim app.url_for( "static", name="static", - filename="file.txt", + filename="filename="文件。 xt", ) == "/static/file.txt" ``` ```python -assert app.url_for( +sapp. rl_for( "static", - name="uploads", + name="上传", filename="image.png", ) == "/user/uploads/image.png" @@ -845,23 +845,23 @@ assert app.url_for( .. tip:: ```` -If you are going to have multiple `static()` routes, then it is *highly* suggested that you manually name them. This will almost certainly alleviate potential hard to discover bugs. +如果你要多道`static()`路由，那么*强烈*建议你手动命名。 这几乎肯定会缓解发现缺陷的可能性。 ```python -app.static("/user/uploads/", "/path/to/uploads/", name="uploads") +app.static("/user/uploads/", "/path/to/uploads/", name="上传") app.static("/user/profile/", "/path/to/profile/", name="profile_pics") ``` ```` -#### Auto index serving +#### 自动索引服务 -.. column:: +.. 列: ``` -If you have a directory of static files that should be served by an index page, you can provide the filename of the index. Now, when reaching that directory URL, the index page will be served. +如果你有一个静态文件目录，应该通过索引页面来使用，你可以提供索引的文件名。 现在，当到达该目录 URL 时，索引页面将被服务。 ``` -.. column:: +.. 列: ```` ```python @@ -869,39 +869,39 @@ app.static("/foo/", "/path/to/foo/", index="index.html") ``` ```` -_Added in v23.3_ +_添加于 v23.3_ -#### File browser +#### 文件浏览器 -.. column:: +.. 列: ``` -When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. +当使用静态处理器的目录时，Sanic可以被配置为显示基本文件浏览器，而不是使用 `directory_view=True`。 ``` -.. column:: +.. 列: ```` ```python app.static("/uploads/", "/path/to/dir", directory_view=True) -``` + ```` -You now have a browsable directory in your web browser: +您的浏览器现在有一个可浏览的目录： ![image](/assets/images/directory-view.png) -_Added in v23.3_ +_添加于 v23.3_ -## Route context +## 路由环境 -.. column:: +.. 列: ``` -When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. +当路由被定义时，您可以添加任何数量的关键字参数与 `ctx_` 前缀。 这些值将被注入到路由 `ctx` 对象中。 ``` -.. column:: +.. 列: ```` ```python @@ -924,4 +924,4 @@ async def do_something(request): ``` ```` -_Added in v21.12_ +_添加于 v21.12_ From e02a9c9bbdf0627f2f0a1516b30f4aa7f81417c2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:47 +0200 Subject: [PATCH 316/698] New translations tasks.md (Japanese) --- guide/content/ja/guide/basics/tasks.md | 64 +++++++++++++------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/guide/content/ja/guide/basics/tasks.md b/guide/content/ja/guide/basics/tasks.md index dd37abf98e..68461f5642 100644 --- a/guide/content/ja/guide/basics/tasks.md +++ b/guide/content/ja/guide/basics/tasks.md @@ -1,28 +1,28 @@ --- -title: Background tasks +title: バックグラウンドタスク --- -# Background tasks +# バックグラウンドタスク -## Creating Tasks +## タスクの作成 -It is often desirable and very convenient to make usage of [tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) in async Python. Sanic provides a convenient method to add tasks to the currently **running** loop. It is somewhat similar to `asyncio.create_task`. For adding tasks before the 'App' loop is running, see next section. +async Pythonで [tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) を利用するのはとても便利です。 Sanicは、現在の**実行中**ループにタスクを追加する便利な方法を提供します。 これは `asyncio.create_task` に似ています。 'App' ループが実行される前にタスクを追加する場合は、次のセクションを参照してください。 ```python -async def notify_server_started_after_five_seconds(): +async def notify_server_started_after_five_secondss(): await asyncio.sleep(5) print('Server successfully started!') app.add_task(notify_server_started_after_five_seconds()) ``` -.. column:: +.. 列:: ``` -Sanic will attempt to automatically inject the app, passing it as an argument to the task. +Sanicは自動的にアプリを注入しようとし、タスクに引数として渡します。 ``` -.. column:: +.. 列:: ```` ```python @@ -34,13 +34,13 @@ app.add_task(auto_inject) ``` ```` -.. column:: +.. 列:: ``` -Or you can pass the `app` argument explicitly. +もしくは、`app`引数を明示的に渡すこともできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -52,19 +52,19 @@ app.add_task(explicit_inject(app)) ``` ```` -## Adding tasks before `app.run` +## `app.run`の前にタスクを追加する -It is possible to add background tasks before the App is run ie. before `app.run`. To add a task before the App is run, it is recommended to not pass the coroutine object (ie. one created by calling the `async` callable), but instead just pass the callable and Sanic will create the coroutine object on **each worker**. Note: the tasks that are added such are run as `before_server_start` jobs and thus run on every worker (and not in the main process). This has certain consequences, please read [this comment](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668) on [this issue](https://github.com/sanic-org/sanic/issues/2139) for further details. +`app.run`の前にバックグラウンドタスクを追加することができます。 アプリを実行する前にタスクを追加するには、コルーチンオブジェクトを渡さないことをお勧めします (すなわち。 `async`呼び出し可能を呼び出すことで作成されたものですが、代わりに呼び出し可能ファイルを渡すだけで、Sanicは**各ワーカー**にコルーチンオブジェクトを作成します。 注意: このように追加されたタスクは、 `before_server_start` ジョブとして実行されます。そのため、すべてのワーカーで実行されます (メインプロセスでは実行されません)。 これには一定の影響があります。詳細については、[このissue](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668)の[このissue](https://github.com/sanic-org/sanic/issues/2139)をご覧ください。 -To add work on the main process, consider adding work to [`@app.main_process_start`](./listeners.md). Note: the workers won't start until this work is completed. +メインプロセスで作業を追加するには、[`@app.main_process_start`](./listeners.md)に作業を追加することを検討してください。 注意: この作業が完了するまでワーカーは起動しません。 -.. column:: +.. 列:: ``` -Example to add a task before `app.run` +`app.run`の前にタスクを追加する例 ``` -.. column:: +.. 列:: ```` ```python @@ -81,15 +81,15 @@ app.run(...) ``` ```` -## Named tasks +## 名前付きタスク -.. column:: +.. 列:: ``` -When creating a task, you can ask Sanic to keep track of it for you by providing a `name`. +タスクを作成するときは、`name`を指定することで、Sanicにそのタスクを追跡させることができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -97,13 +97,13 @@ app.add_task(slow_work, name="slow_task") ``` ```` -.. column:: +.. 列:: ``` -You can now retrieve that task instance from anywhere in your application using `get_task`. +`get_task` を使用して、アプリケーションのどこからでもタスクインスタンスを取得できるようになりました。 ``` -.. column:: +.. 列:: ```` ```python @@ -111,13 +111,13 @@ task = app.get_task("slow_task") ``` ```` -.. column:: +.. 列:: ``` -If that task needs to be cancelled, you can do that with `cancel_task`. Make sure that you `await` it. +そのタスクをキャンセルする必要がある場合は、`cancel_task` でそれを行うことができます。`await` を確認してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -125,13 +125,13 @@ await app.cancel_task("slow_task") ``` ```` -.. column:: +.. 列:: ``` -All registered tasks can be found in the `app.tasks` property. To prevent cancelled tasks from filling up, you may want to run `app.purge_tasks` that will clear out any completed or cancelled tasks. +登録されたすべてのタスクは `app.tasks` プロパティにあります。キャンセルされたタスクがいっぱいになるのを防ぐため、`app` を実行します。 完了またはキャンセルされたタスクをクリアする urge_tasks` 。 ``` -.. column:: +.. 列:: ```` ```python @@ -139,7 +139,7 @@ app.purge_tasks() ``` ```` -This pattern can be particularly useful with `websockets`: +このパターンは `websockets` で特に役立ちます。 ```python async def receiver(ws): @@ -163,4 +163,4 @@ async def feed(request, ws): request.app.purge_tasks() ``` -_Added in v21.12_ +_v21.12_ に追加されました From d67975a690fba9452d06c3c4d5eb3b309d204a51 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:49 +0200 Subject: [PATCH 317/698] New translations tasks.md (Chinese Simplified) --- guide/content/zh/guide/basics/tasks.md | 76 +++++++++++++------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/guide/content/zh/guide/basics/tasks.md b/guide/content/zh/guide/basics/tasks.md index dd37abf98e..25359e7ad9 100644 --- a/guide/content/zh/guide/basics/tasks.md +++ b/guide/content/zh/guide/basics/tasks.md @@ -1,70 +1,70 @@ --- -title: Background tasks +title: 背景任务 --- -# Background tasks +# 背景任务 -## Creating Tasks +## 创建任务 -It is often desirable and very convenient to make usage of [tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) in async Python. Sanic provides a convenient method to add tasks to the currently **running** loop. It is somewhat similar to `asyncio.create_task`. For adding tasks before the 'App' loop is running, see next section. +在异步Python中使用 [tasks]通常是可取和非常方便的。 (https\://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) Sanic 提供了一种方便的方法，可以将任务添加到当前的 **running** 循环中。 它与`asyncio.create_task`有些相似。 在 'App' 循环运行之前添加任务, 见下一个部分。 ```python -async def notify_server_started_after_five_seconds(): - await asyncio.sleep(5) - print('Server successfully started!') +async def notify_server_started_after _fif_seconds(): + 等待asyncio.sleep(5) + print('Server successful started!') -app.add_task(notify_server_started_after_five_seconds()) +app.add_task(notify_server_started_after_first_five _seconds()) ``` -.. column:: +.. 列: ``` -Sanic will attempt to automatically inject the app, passing it as an argument to the task. +Sanic 会尝试自动注入应用，将其作为参数传递给任务。 ``` -.. column:: +.. 列: ```` ```python async def auto_inject(app): - await asyncio.sleep(5) + 等待 asyncio.sleep(5) print(app.name) app.add_task(auto_inject) ``` ```` -.. column:: +.. 列: ``` -Or you can pass the `app` argument explicitly. +或者你可以明确传递`app`的参数。 ``` -.. column:: +.. 列: ```` ```python async def explicit_inject(app): - await asyncio.sleep(5) + required asyncio.sleep(5) print(app.name) app.add_task(explicit_inject(app)) ``` ```` -## Adding tasks before `app.run` +## 在 `app.run` 之前添加任务 -It is possible to add background tasks before the App is run ie. before `app.run`. To add a task before the App is run, it is recommended to not pass the coroutine object (ie. one created by calling the `async` callable), but instead just pass the callable and Sanic will create the coroutine object on **each worker**. Note: the tasks that are added such are run as `before_server_start` jobs and thus run on every worker (and not in the main process). This has certain consequences, please read [this comment](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668) on [this issue](https://github.com/sanic-org/sanic/issues/2139) for further details. +在“app.run”之前添加后台任务是可能的。 若要在应用程序运行前添加任务，建议不要通过Coroutine对象 (e)。 一个通过调用 `async` 调用来创建的东西，但只是传递可调用和 Sanic将在 **每个工人** 上创建可调用物体。 注意：添加的任务将以 `before_server_start` 的形式运行，从而在每个工人（而不是主工）上运行。 这对[这个问题](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668)[这个问题](https://github.com/sanic-org/sanic/issues/2139)有某些后果，详情请参阅。 -To add work on the main process, consider adding work to [`@app.main_process_start`](./listeners.md). Note: the workers won't start until this work is completed. +要添加主进程的工作，请考虑将工作添加到[`@app.main_process_start`](./listeners.md)。 注意：工人在完成此工作之前不会开始工作。 -.. column:: +.. 列: ``` -Example to add a task before `app.run` +在 `app.run` 之前添加任务的示例 ``` -.. column:: +.. 列: ```` ```python @@ -81,29 +81,29 @@ app.run(...) ``` ```` -## Named tasks +## 命名的任务 -.. column:: +.. 列: ``` -When creating a task, you can ask Sanic to keep track of it for you by providing a `name`. +创建任务时，您可以通过 "name" 要求Sanic 为您记录它。 ``` -.. column:: +.. 列: ```` ```python -app.add_task(slow_work, name="slow_task") +app.add_task(troub_work, name="low_task") ``` ```` -.. column:: +.. 列: ``` -You can now retrieve that task instance from anywhere in your application using `get_task`. +您现在可以使用`get_task`从应用程序中的任何地方检索该任务实例。 ``` -.. column:: +.. 列: ```` ```python @@ -111,13 +111,13 @@ task = app.get_task("slow_task") ``` ```` -.. column:: +.. 列: ``` -If that task needs to be cancelled, you can do that with `cancel_task`. Make sure that you `await` it. +如果该任务需要取消，你可以使用 "cancel_task" 来完成。请确保你"等待"。 ``` -.. column:: +.. 列: ```` ```python @@ -125,13 +125,13 @@ await app.cancel_task("slow_task") ``` ```` -.. column:: +.. 列: ``` -All registered tasks can be found in the `app.tasks` property. To prevent cancelled tasks from filling up, you may want to run `app.purge_tasks` that will clear out any completed or cancelled tasks. +所有注册的任务都可以在 `app.tasks` 属性中找到。为了防止被取消的任务填充，您可能想要运行 `app。 urge_tasks`将清除任何已完成或已取消的任务。 ``` -.. column:: +.. 列: ```` ```python @@ -139,7 +139,7 @@ app.purge_tasks() ``` ```` -This pattern can be particularly useful with `websockets`: +这种模式在 `websockets` 中特别有用： ```python async def receiver(ws): @@ -163,4 +163,4 @@ async def feed(request, ws): request.app.purge_tasks() ``` -_Added in v21.12_ +_添加于 v21.12_ From 7bd1b21ae0a8cafb35e0e4c4b9d078e964281f08 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:51 +0200 Subject: [PATCH 318/698] New translations blueprints.md (Japanese) --- .../ja/guide/best-practices/blueprints.md | 190 +++++++++--------- 1 file changed, 95 insertions(+), 95 deletions(-) diff --git a/guide/content/ja/guide/best-practices/blueprints.md b/guide/content/ja/guide/best-practices/blueprints.md index 7a3571058c..7f895bb7fb 100644 --- a/guide/content/ja/guide/best-practices/blueprints.md +++ b/guide/content/ja/guide/best-practices/blueprints.md @@ -1,20 +1,20 @@ -# Blueprints +# 建設計画 -## Overview +## 概要 -Blueprints are objects that can be used for sub-routing within an application. Instead of adding routes to the application instance, blueprints define similar methods for adding routes, which are then registered with the application in a flexible and pluggable manner. +設計図は、アプリケーション内のサブルーティングに使用できるオブジェクトです。 アプリケーションインスタンスにルートを追加する代わりに、blueprintsはルートを追加するための同様のメソッドを定義します。 柔軟でプラガブルな方法でアプリケーションに登録されます -Blueprints are especially useful for larger applications, where your application logic can be broken down into several groups or areas of responsibility. +ブループリントは、アプリケーションのロジックをいくつかのグループまたは責任領域に分割することができる大規模なアプリケーションに特に便利です。 -## Creating and registering +## 作成と登録 -.. column:: +.. 列:: ``` -First, you must create a blueprint. It has a very similar API as the `Sanic()` app instance with many of the same decorators. +まず、青写真を作成する必要があります。同じデコレータの多くを持つ`Sanic()`アプリインスタンスと非常によく似たAPIを持っています。 ``` -.. column:: +.. 列:: ```` ```python @@ -30,13 +30,13 @@ async def bp_root(request): ``` ```` -.. column:: +.. 列:: ``` -Next, you register it with the app instance. +次に、アプリインスタンスに登録します。 ``` -.. column:: +.. 列:: ```` ```python @@ -48,15 +48,15 @@ app.blueprint(bp) ``` ```` -Blueprints also have the same `websocket()` decorator and `add_websocket_route` method for implementing websockets. +ブループリントには、websocket()のデコレータとwebsocketを実装するための`add_websocket_route`メソッドもあります。 -.. column:: +.. 列:: ``` -Beginning in v21.12, a Blueprint may be registered before or after adding objects to it. Previously, only objects attached to the Blueprint at the time of registration would be loaded into application instance. +v21.12 以降では、オブジェクトを追加する前後にブループリントを登録することができます。 以前は、登録時にブループリントに添付されたオブジェクトのみがアプリケーションインスタンスにロードされていました。 ``` -.. column:: +.. 列:: ```` ```python @@ -68,15 +68,15 @@ async def bp_root(request): ``` ```` -## Copying +## コピー中 -.. column:: +.. 列:: ``` -Blueprints along with everything that is attached to them can be copied to new instances using the `copy()` method. The only required argument is to pass it a new `name`. However, you could also use this to override any of the values from the old blueprint. +ブループリントとそれに付随するすべてのものは、 `copy()`メソッドを使用して新しいインスタンスにコピーできます。 唯一必要な引数は新しい`name`を渡すことです。 ただし、これを使用して、古い設計図から任意の値を上書きすることもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -100,11 +100,11 @@ Available routes: ``` ```` -_Added in v21.9_ +_v21.9_に追加されました -## Blueprint groups +## 建設計画グループ -Blueprints may also be registered as part of a list or tuple, where the registrar will recursively cycle through any sub-sequences of blueprints and register them accordingly. The Blueprint.group method is provided to simplify this process, allowing a ‘mock’ backend directory structure mimicking what’s seen from the front end. Consider this (quite contrived) example: +設計図は、リストやタプルの一部として登録することもできます。 登録者は再帰的に設計図の任意のサブシーケンスを循環し、それに応じて登録します。 ブループリント.groupメソッドは、このプロセスを簡素化するために提供されており、フロントエンドから見たものを模倣した「モック」バックエンドディレクトリ構造を可能にします。 これを考えてみましょう(かなり非対称な例) ```text api/ @@ -117,30 +117,30 @@ api/ app.py ``` -.. column:: +.. 列:: ``` -#### First blueprint +#### 最初の建設計画 ``` -.. column:: +.. 列:: ```` ```python # api/content/authors.py from sanic import Blueprint -authors = Blueprint("content_authors", url_prefix="/authors") +author = Blueprint("content_authors", url_prefix="/authors") ``` ```` -.. column:: +.. 列:: ``` -#### Second blueprint +#### 2番目の建設計画 ``` -.. column:: +.. 列:: ```` ```python @@ -151,13 +151,13 @@ static = Blueprint("content_static", url_prefix="/static") ``` ```` -.. column:: +.. 列:: ``` -#### Blueprint group +#### ブループリントグループ ``` -.. column:: +.. 列:: ```` ```python @@ -170,13 +170,13 @@ content = Blueprint.group(static, authors, url_prefix="/content") ``` ```` -.. column:: +.. 列:: ``` -#### Third blueprint +#### 3番目の建設計画 ``` -.. column:: +.. 列:: ```` ```python @@ -187,13 +187,13 @@ info = Blueprint("info", url_prefix="/info") ``` ```` -.. column:: +.. 列:: ``` -#### Another blueprint group +#### ブループリントグループ ``` -.. column:: +.. 列:: ```` ```python @@ -206,15 +206,15 @@ api = Blueprint.group(content, info, url_prefix="/api") ``` ```` -.. column:: +.. 列:: ``` -#### Main server +#### メインサーバー -All blueprints are now registered +ブループリントがすべて登録されました ``` -.. column:: +.. 列:: ```` ```python @@ -227,23 +227,23 @@ app.blueprint(api) ``` ```` -### Blueprint group prefixes and composability +### ブループリントグループのプレフィックスとコンポジション -As shown in the code above, when you create a group of blueprints you can extend the URL prefix of all the blueprints in the group by passing the `url_prefix` argument to the `Blueprint.group` method. This is useful for creating a mock directory structure for your API. +上のコードに示すように。 ブループリントのグループを作成するときは、`Blueprint に引数`url_prefix`を渡すことで、グループ内のすべてのブループリントのURLプレフィックスを拡張できます。 roup`メソッド。 これは、API のモックディレクトリ構造を作成するときに便利です。 -In addition, there is a `name_prefix` argument that can be used to make blueprints reusable and composable. The is specifically necessary when applying a single blueprint to multiple groups. By doing this, the blueprint will be registered with a unique name for each group, which allows the blueprint to be registered multiple times and have its routes each properly named with a unique identifier. +さらに、`name_prefix`引数があり、設計図を再利用可能で構成可能にします。 これは、複数のグループに単一の設計図を適用するときに特に必要です。 これを行うことで、ブループリントは各グループごとに固有の名前で登録されます。 青写真を複数回登録しルートごとに固有の識別子で適切な名前を付けることができます -.. column:: +.. 列:: ``` -Consider this example. The routes built will be named as follows: +以下の例を考えてみましょう。 - `TestApp.group-a_bp1.route1` - `TestApp.group-a_bp2.route2` -- `TestApp.group-b_bp1.route1` -- `TestApp.group-b_bp2.route2` +- `TestApp.group-a_bp1.route1` +- `TestApp.group-bp2.route2` ``` -.. column:: +.. 列:: ```` ```python @@ -266,17 +266,17 @@ app.blueprint(group_b) ``` ```` -_Name prefixing added in v23.6_ +_v23.6_ にプレフィックスが追加されました -## Middleware +## ミドルウェア -.. column:: +.. 列:: ``` -Blueprints can also have middleware that is specifically registered for its endpoints only. +ブループリントはエンドポイントのみに特別に登録されているミドルウェアを持つこともできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -294,13 +294,13 @@ async def halt_response(request, response): ``` ```` -.. column:: +.. 列:: ``` -Similarly, using blueprint groups, it is possible to apply middleware to an entire group of nested blueprints. +同様に、青写真グループを使用して、入れ子になった設計図のグループ全体にミドルウェアを適用することができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -330,33 +330,33 @@ app.blueprint(group) ``` ```` -## Exceptions +## 例外 -.. column:: +.. 列:: ``` -Just like other [exception handling](./exceptions.md), you can define blueprint specific handlers. +他のformat@@0(./exception handling)と同様に、ブループリント固有のハンドラを定義できます。 ``` -.. column:: +.. 列:: ```` ```python @bp.exception(NotFound) def ignore_404s(request, exception): - return text("Yep, I totally found the page: {}".format(request.url)) + return text("Yep, I find the page: {}".format(request.url)) ``` ```` -## Static files +## 静的ファイル -.. column:: +.. 列:: ``` -Blueprints can also have their own static handlers +設計図は、独自の静的ハンドラを持つこともできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -366,13 +366,13 @@ bp.static("/web/path", "/folder/to/server", name="uploads") ``` ```` -.. column:: +.. 列:: ``` -Which can then be retrieved using `url_for()`. See [routing](/guide/basics/routing.md) for more information. +これは `url_for()` を使用して取得できます。詳細は [routing](/guide/basics/routing.md) を参照してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -381,15 +381,15 @@ Which can then be retrieved using `url_for()`. See [routing](/guide/basics/routi ``` ```` -## Listeners +## リスナー -.. column:: +.. 列:: ``` -Blueprints can also implement [listeners](/guide/basics/listeners.md). +ブループリントは [listeners](/guide/basics/listeners.md) も実装できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -405,30 +405,30 @@ async def after_server_stop(app, loop): ## Versioning -As discussed in the [versioning section](/guide/advanced/versioning.md), blueprints can be used to implement different versions of a web API. +[versioning section](/guide/advanced/version.md) で説明されているように、設計図は異なるバージョンの Web API を実装するために使用できます。 -.. column:: +.. 列:: ``` -The `version` will be prepended to the routes as `/v1` or `/v2`, etc. +`version`はルートの前に`/v1`または`/v2`などとなります。 ``` -.. column:: +.. 列:: ```` ```python -auth1 = Blueprint("auth", url_prefix="/auth", version=1) -auth2 = Blueprint("auth", url_prefix="/auth", version=2) +auth1 = ブループリント("auth", url_prefix="/auth", version=1) +auth2 = ブループリント("auth", url_prefix="/auth", version=2) ``` ```` -.. column:: +.. 列:: ``` -When we register our blueprints on the app, the routes `/v1/auth` and `/v2/auth` will now point to the individual blueprints, which allows the creation of sub-sites for each API version. +アプリにブループリントを登録すると、ルート`/v1/auth`と`/v2/auth`が個々のブループリントを示すようになります。 APIバージョンごとにサブサイトを作成することができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -440,14 +440,14 @@ app.blueprint(auth2) ``` ```` -.. column:: +.. 列:: ``` -It is also possible to group the blueprints under a `BlueprintGroup` entity and version multiple of them together at the -same time. +また、 `BlueprintGroup` エンティティの下で設計図をグループ化し、それらの複数を +同時にバージョン化することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -461,19 +461,19 @@ group = Blueprint.group(auth, metrics, version="v1") ``` ```` -## Composable +## 作成可能 -A `Blueprint` may be registered to multiple groups, and each of `BlueprintGroup` itself could be registered and nested further. This creates a limitless possibility `Blueprint` composition. +`Blueprint` は複数のグループに登録することができ、`BlueprintGroup` 自体はそれぞれ登録して入れ子にすることができます。 これにより、無限の可能性をもたらす「設計図」構図が作成されます。 -_Added in v21.6_ +_V21.6_に追加されました -.. column:: +.. 列:: ``` -Take a look at this example and see how the two handlers are actually mounted as five (5) distinct routes. +この例を見て、2つのハンドラが実際に5つの(5)の異なるルートとしてどのようにマウントされているかを見てください。 ``` -.. column:: +.. 列:: ```` ```python @@ -512,9 +512,9 @@ app.blueprint(blueprint_1) ``` ```` -## Generating a URL +## URLの生成 -When generating a url with `url_for()`, the endpoint name will be in the form: +`url_for()` でURLを生成する場合、エンドポイント名は以下のようになります。 ```text {blueprint_name}.{handler_name} From 317ad82c28fa9ff57d934cea5df21257339a1aaf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:53 +0200 Subject: [PATCH 319/698] New translations blueprints.md (Chinese Simplified) --- .../zh/guide/best-practices/blueprints.md | 268 +++++++++--------- 1 file changed, 134 insertions(+), 134 deletions(-) diff --git a/guide/content/zh/guide/best-practices/blueprints.md b/guide/content/zh/guide/best-practices/blueprints.md index 7a3571058c..ea974807c8 100644 --- a/guide/content/zh/guide/best-practices/blueprints.md +++ b/guide/content/zh/guide/best-practices/blueprints.md @@ -1,42 +1,42 @@ -# Blueprints +# 蓝图 -## Overview +## 概览 -Blueprints are objects that can be used for sub-routing within an application. Instead of adding routes to the application instance, blueprints define similar methods for adding routes, which are then registered with the application in a flexible and pluggable manner. +蓝图是可以在应用程序内用于子路由的对象。 蓝图不是将路线添加到应用程序实例中，而是定义了类似的添加路线的方法， 然后以灵活和可搭配的方式在申请中登记。 -Blueprints are especially useful for larger applications, where your application logic can be broken down into several groups or areas of responsibility. +蓝图对于更大的应用程序特别有用，您的应用程序逻辑可以分成几组或几个责任领域。 -## Creating and registering +## 创建和注册 -.. column:: +.. 列: ``` -First, you must create a blueprint. It has a very similar API as the `Sanic()` app instance with many of the same decorators. +首先，您必须创建一个蓝图。它有一个非常相似的 API 与 `Sanic()` 应用实例与许多相同的装饰师相同。 ``` -.. column:: +.. 列: ```` ```python -# ./my_blueprint.py +# ./my_bluprint.py from sanic.response import json from sanic import Blueprint -bp = Blueprint("my_blueprint") +bp = Blueprint(“my_bluprint") -@bp.route("/") +@bp. oute("/") async def bp_root(request): return json({"my": "blueprint"}) ``` ```` -.. column:: +.. 列: ``` -Next, you register it with the app instance. +接下来，你在应用实例中注册它。 ``` -.. column:: +.. 列: ```` ```python @@ -48,19 +48,19 @@ app.blueprint(bp) ``` ```` -Blueprints also have the same `websocket()` decorator and `add_websocket_route` method for implementing websockets. +蓝图也有相同的`websocket()`装饰器和`add_websocket_route`方法实现websocket。 -.. column:: +.. 列: ``` -Beginning in v21.12, a Blueprint may be registered before or after adding objects to it. Previously, only objects attached to the Blueprint at the time of registration would be loaded into application instance. +从 v21.12开始，蓝图可以在添加对象之前或之后注册。 以前，只有注册时附于蓝图的对象才会被加载到应用程序实例。 ``` -.. column:: +.. 列: ```` ```python -app.blueprint(bp) +app.bluprint(bp) @bp.route("/") async def bp_root(request): @@ -68,15 +68,15 @@ async def bp_root(request): ``` ```` -## Copying +## 正在复制 -.. column:: +.. 列: ``` -Blueprints along with everything that is attached to them can be copied to new instances using the `copy()` method. The only required argument is to pass it a new `name`. However, you could also use this to override any of the values from the old blueprint. +蓝图以及附加到它们的所有内容都可以使用 `copy()` 方法复制到新的实例。 唯一需要的参数是通过一个新的 `name` 。 然而，您也可以使用这个来覆盖旧蓝图中的任何值。 ``` -.. column:: +.. 列: ```` ```python @@ -84,27 +84,27 @@ v1 = Blueprint("Version1", version=1) @v1.route("/something") def something(request): - pass + passe v2 = v1.copy("Version2", version=2) -app.blueprint(v1) -app.blueprint(v2) +app. lueprint(v1) +app.bluprint(v2) ``` ``` -Available routes: -/v1/something -/v2/something +可用路径： +/v1/some +/v2/some ``` ```` -_Added in v21.9_ +\*添加于 v21.9 \* -## Blueprint groups +## 蓝图组 -Blueprints may also be registered as part of a list or tuple, where the registrar will recursively cycle through any sub-sequences of blueprints and register them accordingly. The Blueprint.group method is provided to simplify this process, allowing a ‘mock’ backend directory structure mimicking what’s seen from the front end. Consider this (quite contrived) example: +蓝图也可以作为列表或管道的一部分注册 如果登记员将通过任何次级蓝图序列递归循环，并相应地进行登记。 提供了蓝图群组方法来简化这个过程，允许“模拟”后端目录结构模仿从前端看到的东西。 请考虑这个(相当构思) 示例： ```text api/ @@ -117,47 +117,47 @@ api/ app.py ``` -.. column:: +.. 列: ``` -#### First blueprint +#### 第一张蓝图 ``` -.. column:: +.. 列: ```` ```python # api/content/authors.py from sanic import Blueprint -authors = Blueprint("content_authors", url_prefix="/authors") +作者 = Bluprint("content_authors", url_prefix="/authors") ``` ```` -.. column:: +.. 列: ``` -#### Second blueprint +#### 第二张蓝图 ``` -.. column:: +.. 列: ```` ```python # api/content/static.py from sanic import Blueprint -static = Blueprint("content_static", url_prefix="/static") +static = Bluprint("content_static", url_prefix="/static") ``` ```` -.. column:: +.. 列: ``` -#### Blueprint group +#### 蓝图组 ``` -.. column:: +.. 列: ```` ```python @@ -170,30 +170,30 @@ content = Blueprint.group(static, authors, url_prefix="/content") ``` ```` -.. column:: +.. 列: ``` -#### Third blueprint +#### 第三张蓝图 ``` -.. column:: +.. 列: ```` ```python # api/info.py -from sanic import Blueprint +from sanic importer -info = Blueprint("info", url_prefix="/info") +info = Bluprint("info", url_prefix="/info") ``` ```` -.. column:: +.. 列: ``` -#### Another blueprint group +#### 另一个蓝图组 ``` -.. column:: +.. 列: ```` ```python @@ -206,15 +206,15 @@ api = Blueprint.group(content, info, url_prefix="/api") ``` ```` -.. column:: +.. 列: ``` -#### Main server +#### 主要服务器 -All blueprints are now registered +所有蓝图已注册 ``` -.. column:: +.. 列: ```` ```python @@ -227,193 +227,193 @@ app.blueprint(api) ``` ```` -### Blueprint group prefixes and composability +### 蓝图组前缀和可编辑性 -As shown in the code above, when you create a group of blueprints you can extend the URL prefix of all the blueprints in the group by passing the `url_prefix` argument to the `Blueprint.group` method. This is useful for creating a mock directory structure for your API. +如上面的代码所示， 当你创建一个蓝图组时，你可以通过将 `url_prefix` 参数传递到 \`Blueprint，将该组中所有蓝图的 URL 前缀扩展到该组。 路由方法 这有助于为您的 API 创建模拟目录结构。 -In addition, there is a `name_prefix` argument that can be used to make blueprints reusable and composable. The is specifically necessary when applying a single blueprint to multiple groups. By doing this, the blueprint will be registered with a unique name for each group, which allows the blueprint to be registered multiple times and have its routes each properly named with a unique identifier. +此外，还有一个“name_prefix”参数可用来使蓝图可重新使用和复制。 在对多个群组应用单一蓝图时是特别必要的。 通过这样做，蓝图将被注册为每个组的唯一名称。 它允许蓝图多次注册，并且每个路径都有一个唯一的标识符。 -.. column:: +.. 列: ``` -Consider this example. The routes built will be named as follows: -- `TestApp.group-a_bp1.route1` -- `TestApp.group-a_bp2.route2` -- `TestApp.group-b_bp1.route1` +考虑这个示例。已生成的路由将被命名如下： +- `TestAppp.group-a_bp1.route1` +- `TestAppp.group-a_bp2.route2` +- `TestAppp.group-b_bp1.route1` - `TestApp.group-b_bp2.route2` ``` -.. column:: +.. 列: ```` ```python bp1 = Blueprint("bp1", url_prefix="/bp1") bp2 = Blueprint("bp2", url_prefix="/bp2") -bp1.add_route(lambda _: ..., "/", name="route1") +bp1。 dd_route(lambda _ : ..., "/", name="route1") bp2.add_route(lambda _: ..., "/", name="route2") -group_a = Blueprint.group( +group_a = Bluprint。 roup( bp1, bp2, url_prefix="/group-a", name_prefix="group-a" ) -group_b = Blueprint.group( +group_b = 蓝图。 roup( bp1, bp2, url_prefix="/group-b", name_prefix="group-b" ) app = Sanic("TestApp") -app.blueprint(group_a) -app.blueprint(group_b) +app.bluprint(troup_a) +app.bluprint(group_b) ``` ```` -_Name prefixing added in v23.6_ +_在 v23.6_ 中添加的名称前缀 -## Middleware +## 中间件 -.. column:: +.. 列: ``` -Blueprints can also have middleware that is specifically registered for its endpoints only. +蓝图也可以有只为其端点注册的中间件. ``` -.. column:: +.. 列: ```` ```python @bp.middleware async def print_on_request(request): - print("I am a spy") + print("我是一个间谍") -@bp.middleware("request") +@bp. iddleware("request") async def halt_request(request): - return text("I halted the request") + return text("我停止请求") -@bp.middleware("response") +@bp. iddleware("响应") async def halt_response(request, response): - return text("I halted the response") + return text("我已停止响应") ``` ```` -.. column:: +.. 列: ``` -Similarly, using blueprint groups, it is possible to apply middleware to an entire group of nested blueprints. +同样，使用蓝图组可以将中间件应用到整个一组嵌套蓝图。 ``` -.. column:: +.. 列: ```` ```python bp1 = Blueprint("bp1", url_prefix="/bp1") bp2 = Blueprint("bp2", url_prefix="/bp2") -@bp1.middleware("request") +@bp1。 iddleware("request") async def bp1_only_middleware(request): - print("applied on Blueprint : bp1 Only") + print("applied on 蓝图: bp1 only") -@bp1.route("/") +@bp1。 oute("/") async def bp1_route(request): return text("bp1") -@bp2.route("/") +@bp2。 oute("/") async def bp2_route(request, param): return text(param) -group = Blueprint.group(bp1, bp2) +group = Bluprint.group(bp1, bp2) -@group.middleware("request") +@group。 iddleware("request") async def group_middleware(request): - print("common middleware applied for both bp1 and bp2") + print("common middleware applied for bp1 and bp2") -# Register Blueprint group under the app -app.blueprint(group) +# 注册应用程序 +app之下的蓝图组。 lueprint(group) ``` ```` -## Exceptions +## 例外 -.. column:: +.. 列: ``` -Just like other [exception handling](./exceptions.md), you can define blueprint specific handlers. +就像其他[异常处理](./exceptions.md)一样，您可以定义蓝图特定处理器。 ``` -.. column:: +.. 列: ```` ```python @bp.exception(NotFound) -def ignore_404s(request, exception): - return text("Yep, I totally found the page: {}".format(request.url)) +def ignorre_404s(请求, 异常): + return text("Yep, 我完全发现页面: {}".format (crequest.url)) ``` ```` -## Static files +## 静态文件 -.. column:: +.. 列: ``` -Blueprints can also have their own static handlers +蓝图也可以有自己的静态处理程序 ``` -.. column:: +.. 列: ```` ```python bp = Blueprint("bp", url_prefix="/bp") bp.static("/web/path", "/folder/to/serve") -bp.static("/web/path", "/folder/to/server", name="uploads") +bp.static("/web/path", "/folder/to/server", name="上传") ``` ```` -.. column:: +.. 列: ``` -Which can then be retrieved using `url_for()`. See [routing](/guide/basics/routing.md) for more information. +然后可以通过 `url_for()`检索。更多信息请见 [routing](/guide/basics/routing.md)。 ``` -.. column:: +.. 列: ```` ```python ->>> print(app.url_for("static", name="bp.uploads", filename="file.txt")) +>> > print(app.url_for("static", name="bp.uploads", filename="file.txt")) '/bp/web/path/file.txt' ``` ```` -## Listeners +## 监听器 -.. column:: +.. 列: ``` -Blueprints can also implement [listeners](/guide/basics/listeners.md). +蓝图也可以实现 [listeners](/guide/basics/listeners.md). ``` -.. column:: +.. 列: ```` ```python @bp.listener("before_server_start") async def before_server_start(app, loop): - ... + @bp.listener("after_server_stop") -async def after_server_stop(app, loop): +async def after _server_stop(app, loop): ... ``` ```` ## Versioning -As discussed in the [versioning section](/guide/advanced/versioning.md), blueprints can be used to implement different versions of a web API. +正如[版本部分](/guide/advanced/versioning.md)所讨论的，蓝图可以用于实现不同版本的Web API。 -.. column:: +.. 列: ``` -The `version` will be prepended to the routes as `/v1` or `/v2`, etc. +`version`将作为`/v1`或`/v2`等添加到路线上。 ``` -.. column:: +.. 列: ```` ```python @@ -422,13 +422,13 @@ auth2 = Blueprint("auth", url_prefix="/auth", version=2) ``` ```` -.. column:: +.. 列: ``` -When we register our blueprints on the app, the routes `/v1/auth` and `/v2/auth` will now point to the individual blueprints, which allows the creation of sub-sites for each API version. +当我们在应用上注册我们的蓝图时，路由`/v1/auth`和`/v2/auth`将指向个别的蓝图， 允许为每个API版本创建子站点。 ``` -.. column:: +.. 列: ```` ```python @@ -440,40 +440,40 @@ app.blueprint(auth2) ``` ```` -.. column:: +.. 列: ``` -It is also possible to group the blueprints under a `BlueprintGroup` entity and version multiple of them together at the -same time. +同时也可以将蓝图归类到 '蓝图组' 实体，并且同时将它们的多个版本一起使用 +。 ``` -.. column:: +.. 列: ```` ```python auth = Blueprint("auth", url_prefix="/auth") metrics = Blueprint("metrics", url_prefix="/metrics") -group = Blueprint.group(auth, metrics, version="v1") +group = Blueprint. roup(aut, meters, version="v1") -# This will provide APIs prefixed with the following URL path -# /v1/auth/ and /v1/metrics +# 这将为API提供以下URL路径 +# /v1/auth/ 和 /v1/metrics ``` ```` -## Composable +## 可合成的 -A `Blueprint` may be registered to multiple groups, and each of `BlueprintGroup` itself could be registered and nested further. This creates a limitless possibility `Blueprint` composition. +“蓝图”可以注册到多个组，每个“蓝图组”本身都可以注册和嵌套。 这就创造了无限的 `Blueprint` 组成。 -_Added in v21.6_ +\*添加于 v21.6 \* -.. column:: +.. 列: ``` -Take a look at this example and see how the two handlers are actually mounted as five (5) distinct routes. +看看这个示例，并看看这两个处理程序如何实际装载为五(5)条不同的路径。 ``` -.. column:: +.. 列: ```` ```python @@ -512,9 +512,9 @@ app.blueprint(blueprint_1) ``` ```` -## Generating a URL +## 正在生成 URL -When generating a url with `url_for()`, the endpoint name will be in the form: +当生成一个 url_for()\`的URL时，端点名称将是表单的： ```text {blueprint_name}.{handler_name} From 6a54f92a345009ecb46b3fe56c0df346bbf52bd8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:54 +0200 Subject: [PATCH 320/698] New translations decorators.md (Japanese) --- .../ja/guide/best-practices/decorators.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/guide/content/ja/guide/best-practices/decorators.md b/guide/content/ja/guide/best-practices/decorators.md index 3f1bfdf6c0..202ba251b6 100644 --- a/guide/content/ja/guide/best-practices/decorators.md +++ b/guide/content/ja/guide/best-practices/decorators.md @@ -1,14 +1,14 @@ -# Decorators +# デコレーター -One of the best ways to create a consistent and DRY web API is to make use of decorators to remove functionality from the handlers, and make it repeatable across your views. +一貫性のあるDRY Web APIを作成する最善の方法の1つは、デコレータを使用してハンドラから機能を削除することです。 再現できるようにするのです -.. column:: +.. 列:: ``` -Therefore, it is very common to see a Sanic view handler with several decorators on it. +したがって、その上に複数のデコレータを持つSanicビューハンドラを見ることは非常に一般的である。 ``` -.. column:: +.. 列:: ```` ```python @@ -21,11 +21,11 @@ async def get_order_details(request, params, user): ``` ```` -## Example +## 例 -Here is a starter template to help you create decorators. +ここにデコレータを作成するためのスターターテンプレートがあります。 -In this example, let’s say you want to check that a user is authorized to access a particular endpoint. You can create a decorator that wraps a handler function, checks a request if the client is authorized to access a resource, and sends the appropriate response. +この例では、ユーザーが特定のエンドポイントにアクセスする権限があることを確認しましょう。 ハンドラ関数をラップするデコレータを作成できます。 クライアントがリソースにアクセスする権限があるかどうかをリクエストをチェックし、適切なレスポンスを送信します。 ```python from functools import wraps @@ -56,35 +56,35 @@ async def test(request): return json({"status": "authorized"}) ``` -## Templates +## テンプレート -Decorators are **fundamental** to building applications with Sanic. They increase the portability and maintainablity of your code. +デコレータはSanicでアプリケーションを構築するための**基本**です。 これらはコードの移植性と保守性を高めます。 -In paraphrasing the Zen of Python: "[decorators] are one honking great idea -- let's do more of those!" +Pythonの禅を言い換えると、「[decorators] は素晴らしいアイデアです。 -To make it easier to implement them, here are three examples of copy/pastable code to get you started. +実装を容易にするために、ここでは、始めるためのコピー/貼り付け可能なコードの3つの例を紹介します。 -.. column:: +.. 列:: ``` -Don't forget to add these import statements. Although it is *not* necessary, using `@wraps` helps keep some of the metadata of your function intact. [See docs](https://docs.python.org/3/library/functools.html#functools.wraps). Also, we use the `isawaitable` pattern here to allow the route handlers to by regular or asynchronous functions. +これらのインポート文を追加することを忘れないでください。 `@wraps`を使うと、関数のメタデータをそのまま保持することができます。format@@0(https://docs) ython.org/3/library/functtools.html#functools.wraps). また、ここでは`isawaitable`パターンを使用して、通常または非同期の関数でルートハンドラを使用できます。 ``` -.. column:: +.. 列:: ```` ```python from inspect import isawaitable -from functools import wraps +from functtools import wraps ``` ```` -### With args +### 引数あり -.. column:: +.. 列:: ```` -Often, you will want a decorator that will *always* need arguments. Therefore, when it is implemented you will always be calling it. +多くの場合、*常に*引数を必要とするデコレータが必要になります。そのため、実装された場合は常にそれを呼び出すことになります。 ```python @app.get("/") @@ -94,7 +94,7 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列:: ```` ```python @@ -115,9 +115,9 @@ def foobar(arg1, arg2): ``` ```` -### Without args +### 引数なし -.. column:: +.. 列:: ```` Sometimes you want a decorator that will not take arguments. When this is the case, it is a nice convenience not to have to call it @@ -130,7 +130,7 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列:: ```` ```python @@ -151,9 +151,9 @@ def foobar(func): ``` ```` -### With or Without args +### 引数の有無にかかわらず -.. column:: +.. 列:: ```` If you want a decorator with the ability to be called or not, you can follow this pattern. Using keyword only arguments is not necessary, but might make implementation simpler. @@ -173,7 +173,7 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列:: ```` ```python From 6de94ac109b8f616190901c7a2d31794903405ab Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:55 +0200 Subject: [PATCH 321/698] New translations decorators.md (Chinese Simplified) --- .../zh/guide/best-practices/decorators.md | 86 +++++++++---------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/guide/content/zh/guide/best-practices/decorators.md b/guide/content/zh/guide/best-practices/decorators.md index 3f1bfdf6c0..af8bbdfa05 100644 --- a/guide/content/zh/guide/best-practices/decorators.md +++ b/guide/content/zh/guide/best-practices/decorators.md @@ -1,14 +1,14 @@ -# Decorators +# 装饰符 -One of the best ways to create a consistent and DRY web API is to make use of decorators to remove functionality from the handlers, and make it repeatable across your views. +创建一致的 DRY 网页API 的最佳方法之一是利用装饰器从处理器中移除功能。 并使之可以在你的意见中重复出现。 -.. column:: +.. 列: ``` -Therefore, it is very common to see a Sanic view handler with several decorators on it. +因此，非常常见的情况是看到一个带有几个装饰师的Sanic视图处理器。 ``` -.. column:: +.. 列: ```` ```python @@ -21,11 +21,11 @@ async def get_order_details(request, params, user): ``` ```` -## Example +## 示例 -Here is a starter template to help you create decorators. +这是一个帮助您创建装饰程序的启动模板。 -In this example, let’s say you want to check that a user is authorized to access a particular endpoint. You can create a decorator that wraps a handler function, checks a request if the client is authorized to access a resource, and sends the appropriate response. +在这个示例中，让我们说你想要检查用户是否被授权访问某个特定端点。 您可以创建一个装饰器，包装处理函数。 检查客户是否有权访问资源的请求，并发送适当的响应。 ```python from functools import wraps @@ -56,21 +56,21 @@ async def test(request): return json({"status": "authorized"}) ``` -## Templates +## 模板 -Decorators are **fundamental** to building applications with Sanic. They increase the portability and maintainablity of your code. +装饰器是 **基础** ，用于构建带萨尼语的应用程序。 它们提高了您的代码的可携带性和可维护性。 -In paraphrasing the Zen of Python: "[decorators] are one honking great idea -- let's do more of those!" +在解析Python的Zen时：“[decorators] 是一个很好的主意——让我们做更多的事！” -To make it easier to implement them, here are three examples of copy/pastable code to get you started. +为了使它们更容易实现，在这里是三个可复制/可粘贴代码的例子来让您开始操作。 -.. column:: +.. 列: ``` -Don't forget to add these import statements. Although it is *not* necessary, using `@wraps` helps keep some of the metadata of your function intact. [See docs](https://docs.python.org/3/library/functools.html#functools.wraps). Also, we use the `isawaitable` pattern here to allow the route handlers to by regular or asynchronous functions. +不要忘记添加这些导入语句。 虽然它是*不是*必需的，但使用 @wraws` 有助于保持您函数的某些元数据完整。[见文档](https://docs)。 ython.org/3/library/functools.html#functools.wrawals。另外，我们在这里使用 `isawaitable` 模式，允许通过常规或异步函数处理路由处理程序。 ``` -.. column:: +.. 列: ```` ```python @@ -79,81 +79,81 @@ from functools import wraps ``` ```` -### With args +### 带参数： -.. column:: +.. 列: ```` -Often, you will want a decorator that will *always* need arguments. Therefore, when it is implemented you will always be calling it. +你常常想要一个装饰器，它将*总是需要参数。因此，当它实现时，你总是会调用它。 ```python @app.get("/") @foobar(1, 2) -async def handler(request: Request): +async def 处理器(请求: 请求): return text("hi") ``` ```` -.. column:: +.. 列: ```` ```python -def foobar(arg1, arg2): - def decorator(f): - @wraps(f) - async def decorated_function(request, *args, **kwargs): +def foobar(g1, arg2: + def 装饰物(f): + @wraws(f) + async def 装饰函数(请求) *args, **kwargs): response = f(request, *args, **kwargs) - if isawaitable(response): - response = await response + if isawaitable (response): + response = requires return response return decorated_function - return decorator + return Decorator ``` ```` -### Without args +### 没有参数 -.. column:: +.. 列: ```` -Sometimes you want a decorator that will not take arguments. When this is the case, it is a nice convenience not to have to call it +有时你想要一个不需要参数的装饰器。 在这种情况下，最好不要调用 -```python -@app.get("/") +``python +@app。 et("/") @foobar -async def handler(request: Request): +async def 处理器(请求: 请求): return text("hi") ``` ```` -.. column:: +.. 列: ```` ```python -def foobar(func): +def foobar(function): def decorator(f): - @wraps(f) - async def decorated_function(request, *args, **kwargs): + @wraws(f) + async def decorated_function_request. *args, **kwargs): response = f(request, *args, **kwargs) - if isawaitable(response): - response = await response + if isawaitable (response): + response = 等待回应 return response return decorated_function - return decorator(func) + return decorator(ffunc) ``` ```` -### With or Without args +### 使用或不使用参数 -.. column:: +.. 列: ```` If you want a decorator with the ability to be called or not, you can follow this pattern. Using keyword only arguments is not necessary, but might make implementation simpler. @@ -173,7 +173,7 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列: ```` ```python From d55f53a4e65a8d240fada6645f605ff907a9ab28 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:57 +0200 Subject: [PATCH 322/698] New translations exceptions.md (Japanese) --- .../ja/guide/best-practices/exceptions.md | 202 +++++++++--------- 1 file changed, 101 insertions(+), 101 deletions(-) diff --git a/guide/content/ja/guide/best-practices/exceptions.md b/guide/content/ja/guide/best-practices/exceptions.md index 9b46c551a1..c25ddd30d2 100644 --- a/guide/content/ja/guide/best-practices/exceptions.md +++ b/guide/content/ja/guide/best-practices/exceptions.md @@ -1,25 +1,25 @@ -# Exceptions +# 例外 -## Using Sanic exceptions +## サニック例外の使用 -Sometimes you just need to tell Sanic to halt execution of a handler and send back a status code response. You can raise a `SanicException` for this and Sanic will do the rest for you. +場合によっては、ハンドラの実行を停止し、ステータスコード応答を返すようSanicに指示する必要があります。 これに対して「SanicException」を発生させることができ、Sanicはあなたのために残りを行います。 -You can pass an optional `status_code` argument. By default, a SanicException will return an internal server error 500 response. +オプションの `status_code` 引数を渡すことができます。 デフォルトでは、SanicExceptionは内部サーバーエラー500レスポンスを返します。 ```python -from sanic.exceptions import SanicException +from sanic.exception import SanicException @app.route("/youshallnotpass") async def no_no(request): - raise SanicException("Something went wrong.", status_code=501) + raise SanicException("Something went wrong .", status_code=501) ``` -Sanic provides a number of standard exceptions. They each automatically will raise the appropriate HTTP status code in your response. [Check the API reference](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) for more details. +Sanicは多くの標準的な例外を提供します。 それぞれが自動的にレスポンス内に適切なHTTPステータスコードを発生させます。 詳細については、format@@0(https\://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) を参照してください。 -.. column:: +.. 列:: ``` -The more common exceptions you _should_ implement yourself include: +より一般的な例外は、あなた自身を実装すべきである。 - `BadRequest` (400) - `Unauthorized` (401) @@ -28,7 +28,7 @@ The more common exceptions you _should_ implement yourself include: - `ServerError` (500) ``` -.. column:: +.. 列:: ```` ```python @@ -44,9 +44,9 @@ async def login(request): ``` ```` -## Exception properties +## 例外のプロパティ -All exceptions in Sanic derive from `SanicException`. That class has a few properties on it that assist the developer in consistently reporting their exceptions across an application. +Sanic のすべての例外は `SanicException` に由来します。 そのクラスには、開発者がアプリケーション全体で例外を一貫して報告するのに役立ついくつかのプロパティがあります。 - `message` - `status_code` @@ -55,17 +55,17 @@ All exceptions in Sanic derive from `SanicException`. That class has a few prope - `context` - `extra` -All of these properties can be passed to the exception when it is created, but the first three can also be used as class variables as we will see. +これらのプロパティはすべて、作成時に例外に渡すことができます。 最初の3つはクラス変数としても使えます -.. column:: +.. 列:: ``` ### `message` -The `message` property obviously controls the message that will be displayed as with any other exception in Python. What is particularly useful is that you can set the `message` property on the class definition allowing for easy standardization of language across an application +`message` プロパティは、Pythonの他の例外と同じように表示されるメッセージを明らかに制御します。 特に便利なのは、`message` プロパティをクラス定義に設定することで、アプリケーション全体で言語を簡単に標準化できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -78,15 +78,15 @@ raise CustomError("Override the default message with something else") ``` ```` -.. column:: +.. 列:: ``` ### `status_code` -This property is used to set the response code when the exception is raised. This can particularly be useful when creating custom 400 series exceptions that are usually in response to bad information coming from the client. +このプロパティは、例外が発生したときに応答コードを設定するために使用されます。 これは、通常、クライアントからの不正な情報に応答しているカスタム400シリーズの例外を作成する場合に特に便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -100,15 +100,15 @@ raise TeapotError(status_code=400) ``` ```` -.. column:: +.. 列:: ``` ### `quiet` -By default, exceptions will be output by Sanic to the `error_logger`. Sometimes this may not be desirable, especially if you are using exceptions to trigger events in exception handlers (see [the following section](./exceptions.md#handling)). You can suppress the log output using `quiet=True`. +デフォルトでは、Sanic が `error_logger` に例外を出力します。 場合によっては、これは望ましくない場合があります。特に例外を使用して例外ハンドラでイベントをトリガーする場合は (format@@0を参照してください)。 exceptions.md#handling)) `quiet=True` を使ってログ出力を抑制することができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -122,15 +122,15 @@ raise InvalidUsage("blah blah", quiet=True) ``` ```` -.. column:: +.. 列:: ``` -Sometimes while debugging you may want to globally ignore the `quiet=True` property. You can force Sanic to log out all exceptions regardless of this property using `NOISY_EXCEPTIONS` +デバッグ中に`quiet=True`プロパティをグローバルに無視したい場合があります。 `NOISY_EXCEPTIONS` -*Added in v21.12* +*バージョン21.12*に追加された、このプロパティに関係なく、Sanicにすべての例外を強制的にログアウトさせることができます ``` -.. column:: +.. 列:: ```` ```python @@ -138,15 +138,15 @@ app.config.NOISY_EXCEPTIONS = True ``` ```` -.. column:: +.. 列:: ``` ### `headers` -Using `SanicException` as a tool for creating responses is super powerful. This is in part because not only can you control the `status_code`, but you can also control reponse headers directly from the exception. +`SanicException` を使ってレスポンスを作成するのはとても強力です。 これは、 `status_code` を制御するだけでなく、 reponse ヘッダを例外から直接制御することもできるからです。 ``` -.. column:: +.. 列:: ```` ```python @@ -163,7 +163,7 @@ raise InvalidUsage("blah blah", headers={ ``` ```` -.. column:: +.. 列:: ``` ### `extra` @@ -173,7 +173,7 @@ See [contextual exceptions](./exceptions.md#contextual-exceptions) *Added in v21.12* ``` -.. column:: +.. 列:: ```` ```python @@ -181,7 +181,7 @@ raise SanicException(..., extra={"name": "Adam"}) ``` ```` -.. column:: +.. 列:: ``` ### `context` @@ -191,7 +191,7 @@ See [contextual exceptions](./exceptions.md#contextual-exceptions) *Added in v21.12* ``` -.. column:: +.. 列:: ```` ```python @@ -199,37 +199,37 @@ raise SanicException(..., context={"foo": "bar"}) ``` ```` -## Handling +## 取扱い方法 -Sanic handles exceptions automatically by rendering an error page, so in many cases you don't need to handle them yourself. However, if you would like more control on what to do when an exception is raised, you can implement a handler yourself. +Sanicはエラーページをレンダリングすることで自動的に例外を処理するため、多くの場合、自分で処理する必要はありません。 ただし、例外が発生したときに何をすべきかをもっと制御したい場合は、ハンドラを自分で実装することができます。 -Sanic provides a decorator for this, which applies to not only the Sanic standard exceptions, but **any** exception that your application might throw. +Sanicはこのためのデコレータを提供します。これはSanic標準の例外だけでなく、アプリケーションが投げるかもしれない**any**例外にも適用されます。 -.. column:: +.. 列:: ``` -The easiest method to add a handler is to use `@app.exception()` and pass it one or more exceptions. +ハンドラを追加する最も簡単な方法は、 `@app.exception()` を使用して1つ以上の例外を渡すことです。 ``` -.. column:: +.. 列:: ```` ```python -from sanic.exceptions import NotFound +from sanic.exceptionimport NotFound @app.exception(NotFound, SomeCustomException) async def ignore_404s(request, exception): - return text("Yep, I totally found the page: {}".format(request.url)) + return text("Yep, I find the page: {}".format(request.url)) ``` ```` -.. column:: +.. 列:: ``` -You can also create a catchall handler by catching `Exception`. +`Exception` をキャッチすることで、キャッチオールハンドラを作成することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -239,13 +239,13 @@ async def catch_anything(request, exception): ``` ```` -.. column:: +.. 列:: ``` -You can also use `app.error_handler.add()` to add error handlers. +`app.error_handler.add()`を使ってエラーハンドラを追加することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -256,19 +256,19 @@ app.error_handler.add(Exception, server_error_handler) ``` ```` -## Built-in error handling +## ビルトインエラー処理 -Sanic ships with three formats for exceptions: HTML, JSON, and text. You can see examples of them below in the [Fallback handler](#fallback-handler) section. +Sanic は、HTML、JSON、およびテキストの3つのフォーマットを除外して出荷します。 以下の例は format@@0(#fallback-handler) セクションにあります。 -.. column:: +.. 列:: ``` -You can control _per route_ which format to use with the `error_format` keyword argument. +`error_format` キーワード引数でどの形式を使用するかを _per route_ で制御できます。 -*Added in v21.9* +*v21.9* で追加しました ``` -.. column:: +.. 列:: ```` ```python @@ -278,9 +278,9 @@ async def handler(request): ``` ```` -## Custom error handling +## カスタムエラーの処理 -In some cases, you might want to add some more error handling functionality to what is provided by default. In that case, you can subclass Sanic's default error handler as such: +場合によっては、デフォルトで提供されるエラー処理機能を追加したい場合があります。 その場合、Sanic のデフォルトエラーハンドラを次のようにサブクラス化できます。 ```python from sanic.handlers import ErrorHandler @@ -300,15 +300,15 @@ app.error_handler = CustomErrorHandler() ## Fallback handler -Sanic comes with three fallback exception handlers: +Sanic には 3 つのフォールバック例外ハンドラが付属しています: 1. HTML -2. Text +2. テキスト 3. JSON -These handlers present differing levels of detail depending upon whether your application is in [debug mode](/guide/deployment/development.md) or not. +これらのハンドラは、アプリケーションが format@@0(/guide/deployment/development.md) かどうかによって詳細のレベルが異なります。 -By default, Sanic will be in "auto" mode, which means that it will using the incoming request and potential matching handler to choose the appropriate response format. For example, when in a browser it should always provide an HTML error page. When using curl, you might see JSON or plain text. +デフォルトでは、Sanicは「自動」モードになります。 つまり、受信リクエストと潜在的なマッチングハンドラを使用して、適切な応答形式を選択するということです。 例えば、ブラウザでは常にHTMLエラーページを提供する必要があります。 curl を使用すると、JSON またはプレーンテキストが表示されることがあります。 ### HTML @@ -316,7 +316,7 @@ By default, Sanic will be in "auto" mode, which means that it will using the inc app.config.FALLBACK_ERROR_FORMAT = "html" ``` -.. column:: +.. 列:: ```` ```python @@ -326,7 +326,7 @@ app.config.DEBUG = True ![Error](/assets/images/error-display-html-debug.png) ```` -.. column:: +.. 列:: ```` ```python @@ -336,13 +336,13 @@ app.config.DEBUG = False ![Error](/assets/images/error-display-html-prod.png) ```` -### Text +### テキスト ```python app.config.FALLBACK_ERROR_FORMAT = "text" ``` -.. column:: +.. 列:: ```` ```python @@ -375,7 +375,7 @@ Traceback of TestApp (most recent call last): ``` ```` -.. column:: +.. 列:: ```` ```python @@ -401,7 +401,7 @@ That time when that thing broke that other thing? That happened. app.config.FALLBACK_ERROR_FORMAT = "json" ``` -.. column:: +.. 列:: ```` ```python @@ -451,7 +451,7 @@ content-type: application/jso ``` ```` -.. column:: +.. 列:: ```` ```python @@ -474,17 +474,17 @@ content-type: application/json ``` ```` -### Auto +### 自動 -Sanic also provides an option for guessing which fallback option to use. +Sanicはまた、どのフォールバックオプションを使用するかを推測するためのオプションも提供します。 ```python app.config.FALLBACK_ERROR_FORMAT = "auto" ``` -## Contextual Exceptions +## 文脈の例外 -Default exception messages that simplify the ability to consistently raise exceptions throughout your application. +アプリケーション全体で例外を一貫して発生させる機能を簡素化するデフォルトの例外メッセージ。 ```python class TeapotError(SanicException): @@ -494,33 +494,33 @@ class TeapotError(SanicException): raise TeapotError ``` -But this lacks two things: +しかし、これには二つのことが欠けています: -1. A dynamic and predictable message format -2. The ability to add additional context to an error message (more on this in a moment) +1. 動的で予測可能なメッセージ形式 +2. エラーメッセージにコンテキストを追加する機能 (詳細は後で) -_Added in v21.12_ +_v21.12_ に追加されました -Using one of Sanic's exceptions, you have two options to provide additional details at runtime: +Sanicの例外のいずれかを使用すると、実行時に追加の詳細を提供する2つのオプションがあります。 ```python raise TeapotError(extra={"foo": "bar"}, context={"foo": "bar"}) ``` -What's the difference and when should you decide to use each? +違いは何であり、いつそれぞれを使用することに決めるべきか。 -- `extra` - The object itself will **never** be sent to a production client. It is meant for internal use only. What could it be used for? - - Generating (as we will see in a minute) a dynamic error message - - Providing runtime details to a logger - - Debug information (when in development mode, it is rendered) -- `context` - This object is **always** sent to production clients. It is generally meant to be used to send additional details about the context of what happened. What could it be used for? - - Providing alternative values on a `BadRequest` validation issue - - Responding with helpful details for your customers to open a support ticket - - Displaying state information like current logged in user info +- `extra` - オブジェクト自体はプロダクションクライアントに **決して**送られません\*\* 。 内部使用のみを目的としています。 それは何のために使用することができますか? + - 1分後に表示されるように、動的なエラーメッセージを生成します + - ロガーにランタイムの詳細を提供する + - デバッグ情報（開発モードの場合はレンダリングされます） +- `context` - このオブジェクトは常にプロダクションクライアントに送信されます。 これは一般的に、何が起こったのかのコンテキストについての追加の詳細を送信するために使用されます。 それは何のために使用することができますか? + - `BadRequest`検証問題に代替値を提供します + - お客様がサポートチケットを開くために役立つ詳細を記載して回答する + - 現在ログインしているユーザー情報のような状態情報を表示します -### Dynamic and predictable message using `extra` +### `extra`を使った動的で予測可能なメッセージ -Sanic exceptions can be raised using `extra` keyword arguments to provide additional information to a raised exception instance. +サニック例外は、`extra`キーワード引数を使って発生した例外インスタンスに追加情報を提供することができます。 ```python class TeapotError(SanicException): @@ -533,35 +533,35 @@ class TeapotError(SanicException): raise TeapotError(extra={"name": "Adam"}) ``` -The new feature allows the passing of `extra` meta to the exception instance, which can be particularly useful as in the above example to pass dynamic data into the message text. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. +新機能では、例外インスタンスに `extra` メタを渡すことができます。 これは、上記の例のように、動的データをメッセージテキストに渡すのに特に役立ちます。 この`extra` infoオブジェクトは `PRODUCTION` モードでは抑制されますが、 `DEVELOPMENT` モードでは表示されます。 -.. column:: +.. 列:: ``` -**DEVELOPMENT** +**開発版** ![image](~@assets/images/error-extra-debug.png) ``` -.. column:: +.. 列:: ``` -**PRODUCTION** +**製品** ![image](~@assets/images/error-extra-prod.png) ``` -### Additional `context` to an error message +### エラーメッセージに追加の `コンテキスト` -Sanic exceptions can also be raised with a `context` argument to pass intended information along to the user about what happened. This is particularly useful when creating microservices or an API intended to pass error messages in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. +サニック例外は、何が起こったかについてユーザに意図した情報を渡すための引数`context`でも発生します。 これは、マイクロサービスやエラーメッセージを JSON 形式で渡すことを意図した API を作成する場合に特に便利です。 このユースケースでは、パース可能なエラーメッセージ以外にも、クライアントに詳細を返すコンテキストを持たせたいと考えています。 ```python raise TeapotError(context={"foo": "bar"}) ``` -This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: +この情報は **私たちが常にエラーで渡したい** です(利用可能な場合)。 次のようにすべきです: -.. column:: +.. 列:: ```` **PRODUCTION** @@ -578,7 +578,7 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -.. column:: +.. 列:: ```` **DEVELOPMENT** @@ -617,20 +617,20 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -## Error reporting +## エラー報告 -Sanic has a [signal](../advanced/signals.md#built-in-signals) that allows you to hook into the exception reporting process. This is useful if you want to send exception information to a third party service like Sentry or Rollbar. This can be conveniently accomplished by attaching an error reporting handler as show below: +Sanic には [signal](../advanced/signals.md#built-in-signals) があり、例外報告プロセスにフックすることができます。 これは、Sentry や Rollbar のようなサードパーティのサービスに例外情報を送信したい場合に便利です。 これは、以下のようにエラー報告ハンドラを付けることで便利に実現できます。 ```python @app.report_exception async def catch_any_exception(app: Sanic, exception: Exception): -print("Caught exception:", exception) +print("Caught exception:) ``` .. note:: ``` -This handler will be dispatched into a background task and **IS NOT** intended for use to manipulate any response data. It is intended to be used for logging or reporting purposes only, and should not impact the ability of your application to return the error response to the client. +このハンドラはバックグラウンドタスクにディスパッチされ、任意のレスポンスデータを操作するために使用される**IS NOT** です。 ログまたはレポートの目的でのみ使用することを意図しています。 クライアントにエラー・レスポンスを返す能力には影響を与えるべきではありません ``` -_Added in v23.6_ +_V23.6_に追加されました From 90b5c562e5053a951eb03a33fbc8eb33743b31c3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:19:59 +0200 Subject: [PATCH 323/698] New translations exceptions.md (Chinese Simplified) --- .../zh/guide/best-practices/exceptions.md | 310 +++++++++--------- 1 file changed, 155 insertions(+), 155 deletions(-) diff --git a/guide/content/zh/guide/best-practices/exceptions.md b/guide/content/zh/guide/best-practices/exceptions.md index 9b46c551a1..d0c80c9c31 100644 --- a/guide/content/zh/guide/best-practices/exceptions.md +++ b/guide/content/zh/guide/best-practices/exceptions.md @@ -1,22 +1,22 @@ -# Exceptions +# 例外 -## Using Sanic exceptions +## 使用 Sanic 异常 -Sometimes you just need to tell Sanic to halt execution of a handler and send back a status code response. You can raise a `SanicException` for this and Sanic will do the rest for you. +有时，你只需要告诉Sanic停止执行处理程序并发送状态代码回复。 你可以为此举出一个 'SanicException' ，萨尼克将为你做其他事情。 -You can pass an optional `status_code` argument. By default, a SanicException will return an internal server error 500 response. +您可以通过一个可选的 `status_code` 参数。 默认情况下，一个 SanicException 将返回一个内部服务器错误500。 ```python -from sanic.exceptions import SanicException +从 sanic.exception 导入SanicException @app.route("/youshallnotpass") async def no_no(request): - raise SanicException("Something went wrong.", status_code=501) + raising SanicException("出了错", status_code=501) ``` -Sanic provides a number of standard exceptions. They each automatically will raise the appropriate HTTP status code in your response. [Check the API reference](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) for more details. +Sanic提供了一些标准例外情况。 他们将自动在您的响应中提取适当的 HTTP 状态代码。 [请参阅API参考](https://sanic.readthedocs.io/enage/sanic/api_reference.html#module-sanic.exceptions) 了解更多详情。 -.. column:: +.. 列: ``` The more common exceptions you _should_ implement yourself include: @@ -28,7 +28,7 @@ The more common exceptions you _should_ implement yourself include: - `ServerError` (500) ``` -.. column:: +.. 列: ```` ```python @@ -44,93 +44,93 @@ async def login(request): ``` ```` -## Exception properties +## 异常属性 -All exceptions in Sanic derive from `SanicException`. That class has a few properties on it that assist the developer in consistently reporting their exceptions across an application. +所有萨尼克例外情况都源于“SanicException”。 该类具有几个属性，可以帮助开发者始终如一地报告他们在应用程序中的异常情况。 - `message` - `status_code` -- `quiet` +- 安静\` - `headers` - `context` - `extra` -All of these properties can be passed to the exception when it is created, but the first three can also be used as class variables as we will see. +所有这些属性都可以在创建时传递到异常。 但前三个也可以用作我们所看到的类变量。 -.. column:: +.. 列: ``` ### `message` -The `message` property obviously controls the message that will be displayed as with any other exception in Python. What is particularly useful is that you can set the `message` property on the class definition allowing for easy standardization of language across an application +`message` 属性显然控制了将会像Python中任何其他异常一样显示的消息。 尤其有用的是，您可以在类定义中设置`message`属性，以便于所有应用程序的语言标准化 ``` -.. column:: +.. 列: ```` ```python class CustomError(SanicException): - message = "Something bad happened" + message = "出了错误" -raise CustomError -# or -raise CustomError("Override the default message with something else") +raising Custom错误 +# 或 +raw customError("用其他东西覆盖默认消息") ``` ```` -.. column:: +.. 列: ``` ### `status_code` -This property is used to set the response code when the exception is raised. This can particularly be useful when creating custom 400 series exceptions that are usually in response to bad information coming from the client. +这个属性用于设置异常时的响应代码。 这在创建习惯400系列异常时尤其有用，这些异常通常是为了对客户端提供的坏信息作出反应。 ``` -.. column:: +.. 列: ```` ```python class TeapotError(SanicException): status_code = 418 - message = "Sorry, I cannot brew coffee" + message = “对不起，” 我不能酿造咖啡” -raise TeapotError -# or -raise TeapotError(status_code=400) +提高Teapot错误 +# 或 +提高TeapotError(status_code=400) ``` ```` -.. column:: +.. 列: ``` ### `quiet` -By default, exceptions will be output by Sanic to the `error_logger`. Sometimes this may not be desirable, especially if you are using exceptions to trigger events in exception handlers (see [the following section](./exceptions.md#handling)). You can suppress the log output using `quiet=True`. +默认情况下，例外情况将由 Sanic 输出到 `error_logger` 。 有时这可能是不可取的，特别是如果你在异常处理程序中使用异常来触发事件(见以下章节) 。 异常.md#handling)。您可以使用 "quiot=True" 来抑制日志输出。 ``` -.. column:: +.. 列: ```` ```python class SilentError(SanicException): - message = "Something happened, but not shown in logs" - quiet = True + message = "发生了什么, 但未显示在日志中。 + 安静=True -raise SilentError -# or -raise InvalidUsage("blah blah", quiet=True) +引起静音错误 +# 或 +引起无效使用("blah blah", 安静=True) ``` ```` -.. column:: +.. 列: ``` -Sometimes while debugging you may want to globally ignore the `quiet=True` property. You can force Sanic to log out all exceptions regardless of this property using `NOISY_EXCEPTIONS` +有时候在调试时，你可能想要全局忽略`quiet=True`属性。 您可以使用 `NOISY_EXCEPIONS` -*Added in v21.12* +强制从 v21.12中添加的 Sanic 注销所有异常，无论这个属性如何。 ``` -.. column:: +.. 列: ```` ```python @@ -138,129 +138,129 @@ app.config.NOISY_EXCEPTIONS = True ``` ```` -.. column:: +.. 列: ``` ### `headers` -Using `SanicException` as a tool for creating responses is super powerful. This is in part because not only can you control the `status_code`, but you can also control reponse headers directly from the exception. +使用 `SanicException` 作为创建响应的工具是超强大的。 这部分是因为你不仅可以控制 `status_code`，而且你也可以直接从异常中控制回复头部。 ``` -.. column:: +.. 列: ```` ```python class MyException(SanicException): - headers = { + headers = "X-Foo": "bar" } -raise MyException -# or -raise InvalidUsage("blah blah", headers={ +raising MyException +# 或 +raising InvalidUsage("blah blah", headers=leaders= "X-Foo": "bar" }) ``` ```` -.. column:: +.. 列: ``` -### `extra` +### `extran` -See [contextual exceptions](./exceptions.md#contextual-exceptions) +查看[contextual explitions](./exceptions.md#contextual-exceptions) -*Added in v21.12* +*添加于v21.12* ``` -.. column:: +.. 列: ```` ```python -raise SanicException(..., extra={"name": "Adam"}) +raising SanicException(..., extrade={"name": "Adam"}) ``` ```` -.. column:: +.. 列: ``` ### `context` -See [contextual exceptions](./exceptions.md#contextual-exceptions) +见 [contextual explositions](./exceptions.md#contextual-异常) -*Added in v21.12* +*添加于v21.12* ``` -.. column:: +.. 列: ```` ```python -raise SanicException(..., context={"foo": "bar"}) +raising SanicException(..., context={"foo": "bar"}) ``` ```` -## Handling +## 处理 -Sanic handles exceptions automatically by rendering an error page, so in many cases you don't need to handle them yourself. However, if you would like more control on what to do when an exception is raised, you can implement a handler yourself. +通过渲染错误页自动处理异常，所以在许多情况下您不需要自己处理。 然而，如果你想要更多地控制在提出异常时做什么，你可以自己实现一个处理程序。 -Sanic provides a decorator for this, which applies to not only the Sanic standard exceptions, but **any** exception that your application might throw. +Sanic为此提供了一个装饰器，它不仅适用于Sanic标准例外情况，而且**任何**你的应用程序可能丢弃的例外情况。 -.. column:: +.. 列: ``` -The easiest method to add a handler is to use `@app.exception()` and pass it one or more exceptions. +添加处理程序的最简单方法是使用 `@app.expition()` 并传递一个或多个异常。 ``` -.. column:: +.. 列: ```` ```python from sanic.exceptions import NotFound -@app.exception(NotFound, SomeCustomException) +@app.exception(NotFound, Some CustomException) async def ignore_404s(request, exception): - return text("Yep, I totally found the page: {}".format(request.url)) + return text("Yep, 我完全发现页面: {}".format (crequest.url)) ``` ```` -.. column:: +.. 列: ``` -You can also create a catchall handler by catching `Exception`. +你也可以通过捕捉"异常"来创建一个捕获器处理器。 ``` -.. column:: +.. 列: ```` ```python @app.exception(Exception) -async def catch_anything(request, exception): +async def catch_any thing(request, exception): ... ``` ```` -.. column:: +.. 列: ``` -You can also use `app.error_handler.add()` to add error handlers. +您也可以使用 `app.error_handler.add()` 添加错误处理器。 ``` -.. column:: +.. 列: ```` ```python -async def server_error_handler(request, exception): - return text("Oops, server error", status=500) +async def server_error_handler(请求异常): + return text("Ops, server error", status=500) app.error_handler.add(Exception, server_error_handler) ``` ```` -## Built-in error handling +## 内置错误处理 -Sanic ships with three formats for exceptions: HTML, JSON, and text. You can see examples of them below in the [Fallback handler](#fallback-handler) section. +有三种异常模式的神秘船只：HTML、JSON和文本。 你可以在下面的[回退处理程序](#回退处理程序)部分看到他们的例子。 -.. column:: +.. 列: ``` You can control _per route_ which format to use with the `error_format` keyword argument. @@ -268,19 +268,19 @@ You can control _per route_ which format to use with the `error_format` keyword *Added in v21.9* ``` -.. column:: +.. 列: ```` ```python -@app.request("/", error_format="text") +@app.request("/", error_form="text") async def handler(request): ... ``` ```` -## Custom error handling +## 自定义错误处理 -In some cases, you might want to add some more error handling functionality to what is provided by default. In that case, you can subclass Sanic's default error handler as such: +在某些情况下，您可能想要将一些更多的错误处理功能添加到默认提供的功能。 在这种情况下，你可以将亚类Sanic的默认错误处理程序作为这样： ```python from sanic.handlers import ErrorHandler @@ -300,15 +300,15 @@ app.error_handler = CustomErrorHandler() ## Fallback handler -Sanic comes with three fallback exception handlers: +Sanic带有三个回退异常处理器： 1. HTML -2. Text +2. 文本 3. JSON -These handlers present differing levels of detail depending upon whether your application is in [debug mode](/guide/deployment/development.md) or not. +这些处理程序视应用程序是否处于[调试模式](/guide/deplement/development.md)而提供不同的详细程度。 -By default, Sanic will be in "auto" mode, which means that it will using the incoming request and potential matching handler to choose the appropriate response format. For example, when in a browser it should always provide an HTML error page. When using curl, you might see JSON or plain text. +默认情况下，Sanic将处于“自动”模式， 这意味着它将使用传入的请求和潜在的匹配处理程序来选择适当的响应格式。 例如，在浏览器中，它应该始终提供一个 HTML 错误页面。 当使用curl时，您可能会看到JSON或纯文本。 ### HTML @@ -316,66 +316,66 @@ By default, Sanic will be in "auto" mode, which means that it will using the inc app.config.FALLBACK_ERROR_FORMAT = "html" ``` -.. column:: +.. 列: ```` ```python app.config.DEBUG = True -``` +`` -![Error](/assets/images/error-display-html-debug.png) +！[Error](/assets/images/error-display-html-debug.png) ```` -.. column:: +.. 列: ```` ```python app.config.DEBUG = False -``` +`` -![Error](/assets/images/error-display-html-prod.png) +！[Error](/assets/images/error-disply-html-prod.png) ```` -### Text +### 文本 ```python -app.config.FALLBACK_ERROR_FORMAT = "text" +app.config.FALLBACK_ERROR_FORMAT = “文本” ``` -.. column:: +.. 列: ```` ```python app.config.DEBUG = True -``` +`` ```sh curl localhost:8000/exc -i -HTTP/1.1 500 Internal Server Error -content-length: 620 -connection: keep-alive -content-type: text/plain; charset=utf-8 +HTTP/1。 500 服务器内部错误 +内容长度：620 +连接：保持存活 +内容类型：text/plain； charset=utf-8 -⚠️ 500 — Internal Server Error -============================== -That time when that thing broke that other thing? That happened. +:警告：500-内部服务器错误 +================================= +那段时间当那个事情打破了那个其他事情吗？ 发生了这种情况。 -ServerError: That time when that thing broke that other thing? That happened. while handling path /exc -Traceback of TestApp (most recent call last): +服务器错误：那个时候那件事情打破了那个东西吗？那就发生了。 处理路径/exc +追踪TestApp (最近一次通话时间): - ServerError: That time when that thing broke that other thing? That happened. - File /path/to/sanic/app.py, line 979, in handle_request - response = await response + 服务器错误: 那个时候那个东西打破了那个其他东西？ 发生了这种情况。 + 文件 /path/to/sanic/app y, line 979, in handle_request + response = requiring response - File /path/to/server.py, line 16, in handler + file /path/to/server. y, line 16, in handler do_something(cause_error=True) - File /path/to/something.py, line 9, in do_something - raise ServerError( + files/path/to/something。 y, line 9, in do_some + raising ServerError( ``` ```` -.. column:: +.. 列: ```` ```python @@ -401,7 +401,7 @@ That time when that thing broke that other thing? That happened. app.config.FALLBACK_ERROR_FORMAT = "json" ``` -.. column:: +.. 列: ```` ```python @@ -451,7 +451,7 @@ content-type: application/jso ``` ```` -.. column:: +.. 列: ```` ```python @@ -474,53 +474,53 @@ content-type: application/json ``` ```` -### Auto +### 自动操作 -Sanic also provides an option for guessing which fallback option to use. +Sanic还提供了一种猜测的选项，这种猜测可以使用后退选项。 ```python -app.config.FALLBACK_ERROR_FORMAT = "auto" +app.config.FALLBACK_ERROR_FORMAT = "自动" ``` -## Contextual Exceptions +## 上下文异常 -Default exception messages that simplify the ability to consistently raise exceptions throughout your application. +默认异常消息简化了在整个应用程序中始终如一地提出异常的能力。 ```python class TeapotError(SanicException): status_code = 418 - message = "Sorry, I cannot brew coffee" + message = “对不起，我不能酿造咖啡” -raise TeapotError +rappot错误 ``` -But this lacks two things: +但这缺少两件事： -1. A dynamic and predictable message format -2. The ability to add additional context to an error message (more on this in a moment) +1. 动态和可预测的信息格式 +2. 添加附加上下文到错误消息的能力 (暂时更多) -_Added in v21.12_ +_添加于 v21.12_ -Using one of Sanic's exceptions, you have two options to provide additional details at runtime: +使用 Sanic的一个异常，您有两个选项在运行时提供额外细节： ```python -raise TeapotError(extra={"foo": "bar"}, context={"foo": "bar"}) +升起TeapotError(extrade={"foo": "bar"}, context={"foo": "bar"}) ``` -What's the difference and when should you decide to use each? +两者之间有什么区别，何时决定使用？ -- `extra` - The object itself will **never** be sent to a production client. It is meant for internal use only. What could it be used for? - - Generating (as we will see in a minute) a dynamic error message - - Providing runtime details to a logger - - Debug information (when in development mode, it is rendered) -- `context` - This object is **always** sent to production clients. It is generally meant to be used to send additional details about the context of what happened. What could it be used for? - - Providing alternative values on a `BadRequest` validation issue - - Responding with helpful details for your customers to open a support ticket - - Displaying state information like current logged in user info +- `extran` - 对象本身将**永远不**发送到生产客户端。 它仅供内部使用。 它可以用于什么？ + - 正在生成一个动态错误消息 (我们将在一分钟后看到) + - 为记录器提供运行时间详情 + - 调试信息(在开发模式中，它会提供) +- `context` - 此对象总是\*\*总是发送给生产客户。 一般用来提供关于所发生情况的更多细节。 它可以用于什么？ + - 在 `BadRequest` 验证问题上提供替代值 + - 回答您的客户有帮助的详细信息来打开支持工单 + - 显示当前登录用户信息等状态信息 -### Dynamic and predictable message using `extra` +### 使用 "额外" 的动态和可预测消息 -Sanic exceptions can be raised using `extra` keyword arguments to provide additional information to a raised exception instance. +可使用 `extran`关键字参数来提起无声异常，为一个引起的异常实例提供额外信息。 ```python class TeapotError(SanicException): @@ -528,14 +528,14 @@ class TeapotError(SanicException): @property def message(self): - return f"Sorry {self.extra['name']}, I cannot make you coffee" + return f"对不起{self.extr['name']}, 我不能让你咖啡” -raise TeapotError(extra={"name": "Adam"}) +raising TeapotError(extranti={"name": "Adam"}) ``` -The new feature allows the passing of `extra` meta to the exception instance, which can be particularly useful as in the above example to pass dynamic data into the message text. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. +新功能允许将 `extran`meta 传递给异常实例。 这可能与上面的例子一样对将动态数据传递到电文文本中特别有用。 这个“额外”信息对象 **将在 `PRODUCTION` 模式下被抑制** ，但将以`DevelopMENT` 模式显示。 -.. column:: +.. 列: ``` **DEVELOPMENT** @@ -543,7 +543,7 @@ The new feature allows the passing of `extra` meta to the exception instance, wh ![image](~@assets/images/error-extra-debug.png) ``` -.. column:: +.. 列: ``` **PRODUCTION** @@ -551,17 +551,17 @@ The new feature allows the passing of `extra` meta to the exception instance, wh ![image](~@assets/images/error-extra-prod.png) ``` -### Additional `context` to an error message +### 附加“context”到错误消息 -Sanic exceptions can also be raised with a `context` argument to pass intended information along to the user about what happened. This is particularly useful when creating microservices or an API intended to pass error messages in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. +还可以用`context`的参数来提出无声异常，将预定的信息传递给用户关于所发生事件的信息。 这在创建微型服务或旨在以 JSON 格式传递错误消息的 API 时特别有用。 在这种情况下，我们想要围绕例外的某些上下文，而不仅仅是一个可解析的错误信息来返回客户端。 ```python -raise TeapotError(context={"foo": "bar"}) +raised TeapotError(context={"foot": "bar"}) ``` -This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: +这是**我们想要**总是错误传递的信息(当它可用时)。 以下是它应该看起来的样子： -.. column:: +.. 列: ```` **PRODUCTION** @@ -578,7 +578,7 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -.. column:: +.. 列: ```` **DEVELOPMENT** @@ -617,20 +617,20 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -## Error reporting +## 错误报告 -Sanic has a [signal](../advanced/signals.md#built-in-signals) that allows you to hook into the exception reporting process. This is useful if you want to send exception information to a third party service like Sentry or Rollbar. This can be conveniently accomplished by attaching an error reporting handler as show below: +Sanic 有一个 [signal](../advanced/signals.md#内置信号)，允许您绑定到异常报告过程。 如果您想要向 Sentry 或 Rollbar等第三方服务发送异常信息，这是有用的。 这可以通过附加错误报告处理程序来方便地完成，如下所示： ```python @app.report_exception -async def catch_any_exception(app: Sanic, exception: Exception): -print("Caught exception:", exception) +async def catch_any_exception(app: Sanic, exception): +print("捕捉异常:", 异常) ``` -.. note:: +.. 注： ``` -This handler will be dispatched into a background task and **IS NOT** intended for use to manipulate any response data. It is intended to be used for logging or reporting purposes only, and should not impact the ability of your application to return the error response to the client. +此处理程序将被发送到一个后台任务中，**IS NOT** 将被用于操纵任何响应数据。 它仅用于伐木或报告目的。 并且不应影响您的应用程序返回错误响应客户端的能力。 ``` -_Added in v23.6_ +_添加于 v23.6_ From 0e329b8bb2ff27ff73bfcc7b29fc12e56edb382f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:00 +0200 Subject: [PATCH 324/698] New translations logging.md (Japanese) --- .../ja/guide/best-practices/logging.md | 50 +++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/guide/content/ja/guide/best-practices/logging.md b/guide/content/ja/guide/best-practices/logging.md index acc2791c88..b5880803cf 100644 --- a/guide/content/ja/guide/best-practices/logging.md +++ b/guide/content/ja/guide/best-practices/logging.md @@ -1,16 +1,16 @@ -# Logging +# ログ -Sanic allows you to do different types of logging (access log, error log) on the requests based on the [Python logging API](https://docs.python.org/3/howto/logging.html). You should have some basic knowledge on Python logging if you want to create a new configuration. +Sanicはformat@@0(https\://docs.python.org/3/howto/logging.html)に基づいてリクエストの異なるタイプのログ(アクセスログ、エラーログ)を行うことができます。 新しい設定を作成したい場合は、Pythonロギングに関する基本的な知識を持っている必要があります。 -## Quick Start +## クイックスタート -.. column:: +.. 列:: ``` -A simple example using default settings would be like this: +デフォルト設定を使用した簡単な例は次のようになります。 ``` -.. column:: +.. 列:: ```` ```python @@ -30,23 +30,23 @@ if __name__ == "__main__": ``` ```` -After the server is running, you should see logs like this. +サーバーが実行されると、このようなログが表示されます。 ```text [2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 [2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] ``` -You can send a request to server and it will print the log messages. +サーバーにリクエストを送信すると、ログメッセージが出力されます。 ```text -[2021-01-04 15:26:28 +0200] [1929659] [INFO] Here is your log -[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: GET http://localhost:8000/ 200 -1 +[2021-01-04 15:26:28 +0200] [1929659] [INFO] ログ +[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: http://localhost:8000/ 200 -1 ``` -## Changing Sanic loggers +## サイニックロガーの変更 -To use your own logging config, simply use `logging.config.dictConfig`, or pass `log_config` when you initialize Sanic app. +独自のロギング設定を使用するには、`logging.config.dictConfig` を使用するか、Sanic アプリを初期化する際に `log_config` を使用します。 ```python app = Sanic('logging_example', log_config=LOGGING_CONFIG) @@ -65,11 +65,11 @@ This is a good opportunity to place Sanic behind a proxy (like nginx) and to do For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` ``` -## Configuration +## 設定 -Sanic's default logging configuration is: `sanic.log.LOGGING_CONFIG_DEFAULTS`. +Sanic のデフォルトのロギング設定は `sanic.log.LOGGING_CONFIG_DEFAULTS` です。 -.. column:: +.. 列:: ``` There are three loggers used in sanic, and must be defined if you want to create your own logging configuration: @@ -81,20 +81,20 @@ There are three loggers used in sanic, and must be defined if you want to create | `sanic.access` | Used to log access logs. | ``` -.. column:: +.. 列:: -### Log format +### ログの形式 -In addition to default parameters provided by Python (`asctime`, `levelname`, `message`), Sanic provides additional parameters for access logger with. +Python(`asctime`, `levelname`, `message`)で提供されるデフォルトのパラメータに加えて、Sanicはアクセスロガーの追加パラメータを提供しています。 -| Log Context Parameter | Parameter Value | Datatype | -| --------------------- | ------------------------------------ | -------- | -| `host` | `request.ip` | `str` | -| `request` | `request.method + " " + request.url` | `str` | -| `status` | `response` | `int` | -| `byte` | `len(response.body)` | `int` | +| ログのコンテキストパラメータ | パラメータの値 | Datatype | +| -------------- | ------------------------------------ | -------- | +| `host` | `request.ip` | `str` | +| `request` | `request.method + " " + request.url` | `str` | +| `status` | `response` | `int` | +| `byte` | `len(response.body)` | `int` | -The default access log format is: +デフォルトのアクセスログ形式は以下の通りです: ```text %(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d From 2d40a8fb402e9d49b52c831c8e49f77294ebb43c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:02 +0200 Subject: [PATCH 325/698] New translations logging.md (Chinese Simplified) --- .../zh/guide/best-practices/logging.md | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/guide/content/zh/guide/best-practices/logging.md b/guide/content/zh/guide/best-practices/logging.md index acc2791c88..0730e2e78e 100644 --- a/guide/content/zh/guide/best-practices/logging.md +++ b/guide/content/zh/guide/best-practices/logging.md @@ -1,16 +1,16 @@ -# Logging +# 日志记录 -Sanic allows you to do different types of logging (access log, error log) on the requests based on the [Python logging API](https://docs.python.org/3/howto/logging.html). You should have some basic knowledge on Python logging if you want to create a new configuration. +Sanic 允许您根据[Python log, 错误日志](https://docs.python.org/3/howto/logging.html)对请求进行不同类型的日志(访问日志, 错误日志)。 如果您想要创建一个新的配置，您应该在 Python 日志记录中获得一些基本知识。 -## Quick Start +## 快速开始 -.. column:: +.. 列: ``` -A simple example using default settings would be like this: +一个使用默认设置的简单示例就是这样： ``` -.. column:: +.. 列: ```` ```python @@ -30,23 +30,23 @@ if __name__ == "__main__": ``` ```` -After the server is running, you should see logs like this. +在服务器运行后，你应该看到像这样的日志。 ```text [2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 [2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] ``` -You can send a request to server and it will print the log messages. +您可以向服务器发送请求，它将打印日志消息。 ```text [2021-01-04 15:26:28 +0200] [1929659] [INFO] Here is your log [2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: GET http://localhost:8000/ 200 -1 ``` -## Changing Sanic loggers +## 正在更改 Sanic logger -To use your own logging config, simply use `logging.config.dictConfig`, or pass `log_config` when you initialize Sanic app. +要使用您自己的日志配置，只需使用 `logging.config.dictConfig`，或通过 `log_config` 来初始化Sanic 应用程序。 ```python app = Sanic('logging_example', log_config=LOGGING_CONFIG) @@ -58,43 +58,43 @@ if __name__ == "__main__": .. tip:: FYI ``` -Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. +在 Python 中登录是一个相对便宜的操作。 然而，如果你正在满足大量的请求，执行情况令人关切。 所有这些时间都增加了访问日志，费用都很高。 -This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. +这是一个很好的机会，可以将 Sanic 放置在代理背后(如nginx)，并在那里进行访问日志。 您将通过禁用 `access_log` 来看到整体性能的大幅提高。 -For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +为了最佳生产性能，建议运行 Sanic，禁用了 `debug` 和 `access_log` ：`app.run(debug=False, access_log=False)` ``` -## Configuration +## 配置 -Sanic's default logging configuration is: `sanic.log.LOGGING_CONFIG_DEFAULTS`. +Sanic默认日志配置为：`sanic.log.LOGING_CONFIG_DEFAULTS`。 -.. column:: +.. 列: ``` -There are three loggers used in sanic, and must be defined if you want to create your own logging configuration: +有三名伐木者用于卫生系统。 如果您想要创建自己的日志配置，则必须定义： -| **Logger Name** | **Use Case** | -|-----------------|-------------------------------| -| `sanic.root` | Used to log internal messages. | -| `sanic.error` | Used to log error logs. | -| `sanic.access` | Used to log access logs. | +| **日志名称** | **使用案例** | +|-----------------|-----------------------| +| `sanic。 oot` | 用于记录内部消息. +| `sanic.error` | 用于日志错误日志. | +| `sanic.access` | 用于日志访问日志 ``` -.. column:: +.. 列: -### Log format +### 日志格式 -In addition to default parameters provided by Python (`asctime`, `levelname`, `message`), Sanic provides additional parameters for access logger with. +除了Python提供的默认参数外(`asctime`, `levelname`, `message`)，Sanic还提供了访问日志的额外参数。 -| Log Context Parameter | Parameter Value | Datatype | -| --------------------- | ------------------------------------ | -------- | -| `host` | `request.ip` | `str` | -| `request` | `request.method + " " + request.url` | `str` | -| `status` | `response` | `int` | -| `byte` | `len(response.body)` | `int` | +| 日志上下文参数 | 参数值 | Datatype | +| --------- | ----------------------------------- | -------- | +| `host` | `request.ip` | `str` | +| `request` | `request.methods + " + request.url` | `str` | +| `status` | `response` | `int` | +| `byte` | `len(response.body)` | `int` | -The default access log format is: +默认访问日志格式是： ```text %(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d From 1297685c5ee5cde4915e4becc440aacd190f3e77 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:03 +0200 Subject: [PATCH 326/698] New translations testing.md (Japanese) --- guide/content/ja/guide/best-practices/testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/guide/best-practices/testing.md b/guide/content/ja/guide/best-practices/testing.md index a7ac6fdaf6..fbc56f3f63 100644 --- a/guide/content/ja/guide/best-practices/testing.md +++ b/guide/content/ja/guide/best-practices/testing.md @@ -1,3 +1,3 @@ -# Testing +# テスト -See [sanic-testing](../../plugins/sanic-testing/getting-started.md) +参照: [sanic-testing](../../plugins/sanic-testing/getting-started.md) From 0ad64c76458bde2305ad1b86d205fea58bbd6c20 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:04 +0200 Subject: [PATCH 327/698] New translations testing.md (Chinese Simplified) --- guide/content/zh/guide/best-practices/testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/guide/best-practices/testing.md b/guide/content/zh/guide/best-practices/testing.md index a7ac6fdaf6..40ceda6142 100644 --- a/guide/content/zh/guide/best-practices/testing.md +++ b/guide/content/zh/guide/best-practices/testing.md @@ -1,3 +1,3 @@ -# Testing +# 测试 -See [sanic-testing](../../plugins/sanic-testing/getting-started.md) +见 [sanic-testing](../../plugins/sanic-testing/getting-started.md) From d47954e9a545ddfc38c7d8fead5f6f519eaa0c22 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:05 +0200 Subject: [PATCH 328/698] New translations caddy.md (Japanese) --- guide/content/ja/guide/deployment/caddy.md | 34 +++++++++++----------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/guide/content/ja/guide/deployment/caddy.md b/guide/content/ja/guide/deployment/caddy.md index 77d8eb39fc..326ac05a65 100644 --- a/guide/content/ja/guide/deployment/caddy.md +++ b/guide/content/ja/guide/deployment/caddy.md @@ -1,12 +1,12 @@ -# Caddy Deployment +# キャディデプロイメント -## Introduction +## はじめに -Caddy is a state-of-the-art web server and proxy that supports up to HTTP/3. Its simplicity lies in its minimalistic configuration and the inbuilt ability to automatically procure TLS certificates for your domains from Let's Encrypt. In this setup, we will configure the Sanic application to serve locally at 127.0.0.1:8001, with Caddy playing the role of the public-facing server for the domain example.com. +CaddyはHTTP/3までサポートする最先端のWebサーバーとプロキシです。 そのシンプルさは、最小限の設定と、Let's Encrypt からドメイン用の TLS 証明書を自動的に調達するための構築機能にあります。 この設定では、127.0.0でローカルで動作するようにSanicアプリケーションを設定します。 :8001, Caddy がドメインの example.com の公開サーバーの役割を果たしています。 -You may install Caddy from your favorite package menager on Windows, Linux and Mac. The package is named `caddy`. +Windows、Linux、Macでお気に入りのパッケージメニューからCaddyをインストールできます。 パッケージ名は `caddy` です。 -## Proxied Sanic app +## プロキシされたサニックアプリ ```python from sanic import Sanic @@ -23,27 +23,27 @@ def index(request): ) ``` -To run this application, save as `proxied_example.py`, and use the sanic command-line interface as follows: +このアプリケーションを実行するには、`proxied_example.py` として保存し、sanic コマンドラインインターフェイスを以下のように使用します。 ```bash SANIC_PROXIES_COUNT=1 sanic proxied_example --port 8001 ``` -Setting the SANIC_PROXIES_COUNT environment variable instructs Sanic to trust the X-Forwarded-\* headers sent by Caddy, allowing it to correctly identify the client's IP address and other information. +SANIC_PROXIES_COUNT環境変数を設定すると、SanicはCaddyから送信されたX-Forward-\*ヘッダを信頼するように命令します。 クライアントのIPアドレスやその他の情報を正しく識別できるようにします。 -## Caddy is simple +## キャディはシンプルです -If you have no other web servers running, you can simply run Caddy CLI (needs `sudo` on Linux): +他の Web サーバーが動作していない場合は、Caddy CLI を実行できます（Linux では `sudo` が必要です）。 ```bash -caddy reverse-proxy --from example.com --to :8001 +caddy リバース・プロキシ --from example.com --to :8001 ``` -This is a complete server that includes a certificate for your domain, http-to-https redirect, proxy headers, streaming and WebSockets. Your Sanic application should now be available on the domain you specified by HTTP versions 1, 2 and 3. Remember to open up UDP/443 on your firewall to enable H3 communications. +これはあなたのドメインの証明書、http-to-https リダイレクト、プロキシヘッダ、ストリーミング、WebSocketを含む完全なサーバーです。 Sanicアプリケーションは、HTTPバージョン1、2、3で指定されたドメインで利用可能になるはずです。 H3通信を有効にするには、ファイアウォールでUDP/443 を開いてください。 -All done? +すべて完了しましたか？ -Soon enough you'll be needing more than one server, or more control over details, which is where the configuration files come in. The above command is equivalent to this `Caddyfile`, serving as a good starting point for your install: +すぐに、複数のサーバーが必要になります。または、設定ファイルが入ってくる詳細を制御する必要があります。 上記のコマンドは `Caddyfile` と同等で、インストールの良い開始点として機能します。 ``` example.com { @@ -51,11 +51,11 @@ example.com { } ``` -Some Linux distributions install Caddy such that it reads configuration from `/etc/caddy/Caddyfile`, which `import /etc/caddy/conf.d/*` for each site you are running. If not, you'll need to manually run `caddy run` as a system service, pointing it at the proper config file. Alternatively, use Caddy API mode with `caddy run --resume` for persistent config changes. Note that any Caddyfile loading will replace all prior configuration and thus `caddy-api` is not configurable in this traditional manner. +Linuxディストリビューションによっては、`/etc/caddy/Caddy/Caddy/Caddyfile` から設定を読み込むようにインストールされているものもあります。これは `import /etc/caddy/conf.d/*` です。 そうでない場合は、 `caddy run` をシステムサービスとして手動で実行し、適切な設定ファイルを指す必要があります。 もしくは、永続的な設定変更には、 `caddy run --resume` を使用して Caddy API モードを使用してください。 Caddyfile の読み込みはすべての設定を置き換えるため、 `caddy-api` は従来の方法では設定できません。 -## Advanced configuration +## 高度な構成 -At times, you might need to mix static files and handlers at the site root for cleaner URLs. In Sanic, you'd use `app.static("/", "static", index="index.html")` to achieve this. However, for improved performance, you can offload serving static files to Caddy: +時には、静的なファイルとハンドラをサイトルートで混在させ、よりクリーンな URL を得る必要があるかもしれません。 Sanicでは、\`app.static("/", "static", index="index.html")を使用します。 ただし、パフォーマンスを向上させるために、静的ファイルをCaddyにオフロードすることができます。 ``` app.example.com { @@ -71,4 +71,4 @@ app.example.com { } ``` -Please refer to [Caddy documentation](https://caddyserver.com/docs/) for more options. +詳細については、format@@0(https\://caddyserver.com/docs/)を参照してください。 From e82c1b7db9e653d3c3ace8cd8eeab8198f7c286c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:07 +0200 Subject: [PATCH 329/698] New translations caddy.md (Chinese Simplified) --- guide/content/zh/guide/deployment/caddy.md | 34 +++++++++++----------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/guide/content/zh/guide/deployment/caddy.md b/guide/content/zh/guide/deployment/caddy.md index 77d8eb39fc..86deefb227 100644 --- a/guide/content/zh/guide/deployment/caddy.md +++ b/guide/content/zh/guide/deployment/caddy.md @@ -1,12 +1,12 @@ -# Caddy Deployment +# Caddy 部署 -## Introduction +## 一. 导言 -Caddy is a state-of-the-art web server and proxy that supports up to HTTP/3. Its simplicity lies in its minimalistic configuration and the inbuilt ability to automatically procure TLS certificates for your domains from Let's Encrypt. In this setup, we will configure the Sanic application to serve locally at 127.0.0.1:8001, with Caddy playing the role of the public-facing server for the domain example.com. +Caddy 是一个最先进的网络服务器和代理服务器，最多支持 HTTP/3。 它的简单性在于它的最小化配置以及从我们加密中自动获取您的域名的 TLS 证书的内置能力。 在这个设置中，我们将配置Sanic应用程序在 127.0.0.0 本地服务。 :8001, 与 Caddy 在域example.com中扮演公共对口服务器的角色。 -You may install Caddy from your favorite package menager on Windows, Linux and Mac. The package is named `caddy`. +您可以在 Windows、Linux 和 Mac 上从您最喜欢的软件包菜单中安装Caddy。 包名为`caddy`。 -## Proxied Sanic app +## Proxied Sanic 应用 ```python from sanic import Sanic @@ -23,27 +23,27 @@ def index(request): ) ``` -To run this application, save as `proxied_example.py`, and use the sanic command-line interface as follows: +要运行此应用程序，请另存为 `proxied_example.py`，并使用符合条件的命令行接口如下： ```bash -SANIC_PROXIES_COUNT=1 sanic proxied_example --port 8001 +SANIC_PROXIES_COUNT=1 sanic proxied_example --porter 8001 ``` -Setting the SANIC_PROXIES_COUNT environment variable instructs Sanic to trust the X-Forwarded-\* headers sent by Caddy, allowing it to correctly identify the client's IP address and other information. +设置SANIC_PROXIES_COUNT 环境变量指示Sanic信任Caddy发送的 X-Forwarded-\* 头部。 允许它正确识别客户端的 IP 地址和其他信息。 -## Caddy is simple +## Caddy 是简单的 -If you have no other web servers running, you can simply run Caddy CLI (needs `sudo` on Linux): +如果你没有其他网络服务器运行，你可以简单地运行 Caddy CLI (Linux需要`sudo`)： ```bash caddy reverse-proxy --from example.com --to :8001 ``` -This is a complete server that includes a certificate for your domain, http-to-https redirect, proxy headers, streaming and WebSockets. Your Sanic application should now be available on the domain you specified by HTTP versions 1, 2 and 3. Remember to open up UDP/443 on your firewall to enable H3 communications. +这是一个完整的服务器，包括您的域名、 httpto https 重定向、 代理头、 流媒体和 WebSockets的证书。 您的 Sanic 应用程序现在应该可以在 HTTP 版本 1, 2 和 3 指定的域上使用。 记住要在您的防火墙上打开 UDP/443 以启用 H3 通信。 -All done? +完成了所有任务吗？ -Soon enough you'll be needing more than one server, or more control over details, which is where the configuration files come in. The above command is equivalent to this `Caddyfile`, serving as a good starting point for your install: +很快，您将需要多个服务器，或者更多的细节控制，这是配置文件的位置。 上述命令相当于此 `Caddyfile` ，作为您安装的一个良好起点： ``` example.com { @@ -51,11 +51,11 @@ example.com { } ``` -Some Linux distributions install Caddy such that it reads configuration from `/etc/caddy/Caddyfile`, which `import /etc/caddy/conf.d/*` for each site you are running. If not, you'll need to manually run `caddy run` as a system service, pointing it at the proper config file. Alternatively, use Caddy API mode with `caddy run --resume` for persistent config changes. Note that any Caddyfile loading will replace all prior configuration and thus `caddy-api` is not configurable in this traditional manner. +一些Linux 发行版安装Caddy，它会读取`/etc/caddy/Caddyfile`的配置，它会为您正在运行的每个网站导入/etc/caddy/conf.d/\*。 如果没有，你需要手动运行 "caddy run" 作为系统服务，指向正确的配置文件。 或者，使用 caddy 运行 --resume` 来进行持续性配置更改的 Caddy API 模式。 请注意，任何Caddyfile 加载都将替换所有先前的配置，因此`caddy-api\`无法按照这种传统方式进行配置。 -## Advanced configuration +## 高级配置 -At times, you might need to mix static files and handlers at the site root for cleaner URLs. In Sanic, you'd use `app.static("/", "static", index="index.html")` to achieve this. However, for improved performance, you can offload serving static files to Caddy: +有时，您可能需要在站点根目录混合静态文件和处理程序以获取更干净的 URL。 在 Sanic, 您使用 `app.static("/", "static", index="index.html")` 来实现这一点。 然而，为了提高性能，您可以卸载静态文件到 Cadd： ``` app.example.com { @@ -71,4 +71,4 @@ app.example.com { } ``` -Please refer to [Caddy documentation](https://caddyserver.com/docs/) for more options. +更多选项请参阅[Caddy documentation](https://caddyserver.com/docs/)。 From e5ee045d5dd9c029f5f1fd41180128f6e84b8a1d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:08 +0200 Subject: [PATCH 330/698] New translations docker.md (Japanese) --- guide/content/ja/guide/deployment/docker.md | 72 ++++++++++----------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/guide/content/ja/guide/deployment/docker.md b/guide/content/ja/guide/deployment/docker.md index fe6f0dd05f..2ab66084ad 100644 --- a/guide/content/ja/guide/deployment/docker.md +++ b/guide/content/ja/guide/deployment/docker.md @@ -1,20 +1,20 @@ # Docker Deployment -## Introduction +## はじめに -For a long time, the environment has always been a difficult problem for deployment. If there are conflicting configurations in your project, you have to spend a lot of time resolving them. Fortunately, virtualization provides us with a good solution. Docker is one of them. If you don't know Docker, you can visit [Docker official website](https://www.docker.com/) to learn more. +長い間、環境はデプロイにとって困難な問題でした。 プロジェクトに矛盾する構成がある場合は、それらの解決に多くの時間を費やす必要があります。 幸いなことに、仮想化は私たちに良い解決策を提供します。 Dockerはその一つです。 Dockerを知らない場合は、format@@0(https\://www\.docker.com/)をご覧ください。 -## Build Image +## ビルド画像 -Let's start with a simple project. We will use a Sanic project as an example. Assume the project path is `/path/to/SanicDocker`. +簡単なプロジェクトから始めましょう 例として、Sanicプロジェクトを使用します。 プロジェクトのパスは `/path/to/SanicDocker` であるとします。 -.. column:: +.. 列:: ``` -The directory structure looks like this: +ディレクトリ構造は以下のようになります: ``` -.. column:: +.. 列:: ```` ```text @@ -22,17 +22,17 @@ The directory structure looks like this: SanicDocker ├── requirements.txt ├── dockerfile -└── server.py +├── server.py ``` ```` -.. column:: +.. 列:: ``` -And the `server.py` code looks like this: +`server.py`のコードは次のようになります。 ``` -.. column:: +.. 列:: ```` ```python @@ -50,10 +50,10 @@ if __name__ == '__main__': .. note:: ``` -Please note that the host cannot be 127.0.0.1 . In docker container, 127.0.0.1 is the default network interface of the container, only the container can communicate with other containers. more information please visit [Docker network](https://docs.docker.com/engine/reference/commandline/network/) +ホストは 127.0.0.1 ではありません。docker container, 127.0.0. は、コンテナのデフォルトのネットワークインターフェイスです。コンテナだけが他のコンテナと通信できます。 詳細はformat@@0(https://docs.docker.com/engine/reference/commandline/network/)をご覧ください。 ``` -Code is ready, let's write the `Dockerfile`: +コードの準備ができました。`Dockerfile`を書きましょう。 ```Dockerfile @@ -70,21 +70,21 @@ EXPOSE 8000 CMD ["python", "server.py"] ``` -Run the following command to build the image: +次のコマンドを実行してイメージをビルドします。 ```shell docker build -t my-sanic-image . ``` -## Start Container +## コンテナを起動 -.. column:: +.. 列:: ``` -After the image built, we can start the container use `my-sanic-image`: +イメージ構築後、コンテナは `my-sanic-image` を使用します。 ``` -.. column:: +.. 列:: ```` ```shell @@ -92,13 +92,13 @@ docker run --name mysanic -p 8000:8000 -d my-sanic-image ``` ```` -.. column:: +.. 列:: ``` -Now we can visit `http://localhost:8000` to see the result: +`http://localhost:8000`で結果を確認できます。 ``` -.. column:: +.. 列:: ```` ```text @@ -106,19 +106,19 @@ OK! ``` ```` -## Use docker-compose +## docker-compose を使用 -If your project consist of multiple services, you can use [docker-compose](https://docs.docker.com/compose/) to manage them. +プロジェクトが複数のサービスで構成されている場合は、 [docker-compose](https://docs.docker.com/compose/) を使用して管理できます。 -for example, we will deploy `my-sanic-image` and `nginx`, achieve through nginx access sanic server. +例えば、`my-sanic-image` と `nginx` をデプロイし、nginx アクセスの sanic サーバーを使用して実現します。 -.. column:: +.. 列:: ``` -First of all, we need prepare nginx configuration file. create a file named `mysanic.conf`: +まず、nginxの設定ファイルを準備する必要があります。`mysanic.conf`という名前のファイルを作成します。 ``` -.. column:: +.. 列:: ```` ```nginx @@ -135,13 +135,13 @@ server { ``` ```` -.. column:: +.. 列:: ``` -Then, we need to prepare `docker-compose.yml` file. The content follows: +次に、`docker-compose.yml` ファイルを準備する必要があります。内容は以下のとおりです: ``` -.. column:: +.. 列:: ```` ```yaml @@ -170,13 +170,13 @@ networks: ``` ```` -.. column:: +.. 列:: ``` -After that, we can start them: +その後、次のように開始できます。 ``` -.. column:: +.. 列:: ```` ```shell @@ -184,13 +184,13 @@ docker-compose up -d ``` ```` -.. column:: +.. 列:: ``` -Now, we can visit `http://localhost:80` to see the result: +`http://localhost:80`で結果を確認できます。 ``` -.. column:: +.. 列:: ```` ```text From a82cf4b3d641197c184aee8b0ce9470e45e40ac2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:10 +0200 Subject: [PATCH 331/698] New translations docker.md (Chinese Simplified) --- guide/content/zh/guide/deployment/docker.md | 96 ++++++++++----------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/guide/content/zh/guide/deployment/docker.md b/guide/content/zh/guide/deployment/docker.md index fe6f0dd05f..0e1a637ec6 100644 --- a/guide/content/zh/guide/deployment/docker.md +++ b/guide/content/zh/guide/deployment/docker.md @@ -1,20 +1,20 @@ -# Docker Deployment +# Docker 部署 -## Introduction +## 一. 导言 -For a long time, the environment has always been a difficult problem for deployment. If there are conflicting configurations in your project, you have to spend a lot of time resolving them. Fortunately, virtualization provides us with a good solution. Docker is one of them. If you don't know Docker, you can visit [Docker official website](https://www.docker.com/) to learn more. +长期以来，环境一直是部署的一个困难问题。 如果您的项目中存在相互冲突的配置，您必须花费大量时间解析它们。 幸运的是，虚拟化为我们提供了一个好的解决办法。 码头就是其中之一。 如果你不知道Docker，你可以访问 [Docker官方网站](https://www.docker.com/) 了解更多信息。 -## Build Image +## 构建图像 -Let's start with a simple project. We will use a Sanic project as an example. Assume the project path is `/path/to/SanicDocker`. +让我们从一个简单的项目开始。 我们将以Sanic项目为例。 假设项目路径是 `/path/to/SanicDocker` 。 -.. column:: +.. 列: ``` -The directory structure looks like this: +目录结构看起来像这样： ``` -.. column:: +.. 列: ```` ```text @@ -26,13 +26,13 @@ SanicDocker ``` ```` -.. column:: +.. 列: ``` -And the `server.py` code looks like this: +`server.py`代码看起来像这样： ``` -.. column:: +.. 列: ```` ```python @@ -47,21 +47,21 @@ if __name__ == '__main__': ``` ```` -.. note:: +.. 注： ``` -Please note that the host cannot be 127.0.0.1 . In docker container, 127.0.0.1 is the default network interface of the container, only the container can communicate with other containers. more information please visit [Docker network](https://docs.docker.com/engine/reference/commandline/network/) +请注意主机不能为127.0.0.1 。在Docker容器中，127.0.0。 是容器的默认网络接口，只有容器可以与其他容器通信。 更多信息请访问[Docker network](https://docs.docker.com/engine/reference/commandline/network/) ``` -Code is ready, let's write the `Dockerfile`: +代码已经准备好，让我们写入`Dockerfile`： ```Dockerfile -FROM sanicframework/sanic:3.8-latest +FROM sanicframework/sanic:3.8-最新 WORKDIR /sanic -COPY . . +COPY . RUN pip install -r requirements.txt @@ -70,21 +70,21 @@ EXPOSE 8000 CMD ["python", "server.py"] ``` -Run the following command to build the image: +运行以下命令来构建图像： ```shell -docker build -t my-sanic-image . +停靠构建-t my-sanic-image ``` -## Start Container +## 启动容器 -.. column:: +.. 列: ``` -After the image built, we can start the container use `my-sanic-image`: +在图像生成后，我们可以启动容器使用 "my-sanic-image" ： ``` -.. column:: +.. 列: ```` ```shell @@ -92,13 +92,13 @@ docker run --name mysanic -p 8000:8000 -d my-sanic-image ``` ```` -.. column:: +.. 列: ``` -Now we can visit `http://localhost:8000` to see the result: +现在我们可以访问 `http://localhost:8000` 来查看结果： ``` -.. column:: +.. 列: ```` ```text @@ -106,19 +106,19 @@ OK! ``` ```` -## Use docker-compose +## 使用 docker-compose -If your project consist of multiple services, you can use [docker-compose](https://docs.docker.com/compose/) to manage them. +如果您的项目包含多项服务，您可以使用 [docker-compose](https://docs.docker.com/compose/) 来管理它们。 -for example, we will deploy `my-sanic-image` and `nginx`, achieve through nginx access sanic server. +例如，我们将部署`my-sanic-image`和`nginx`，通过 nginx 访问智能服务器来实现。 -.. column:: +.. 列: ``` -First of all, we need prepare nginx configuration file. create a file named `mysanic.conf`: +首先，我们需要准备 nginx 配置文件，创建一个名为 `mysanic.conf` 的文件： ``` -.. column:: +.. 列: ```` ```nginx @@ -135,34 +135,34 @@ server { ``` ```` -.. column:: +.. 列: ``` -Then, we need to prepare `docker-compose.yml` file. The content follows: +然后，我们需要准备`docker-compose.yml`文件。 ``` -.. column:: +.. 列: ```` ```yaml -version: "3" +版本: "3" services: mysanic: image: my-sanic-image ports: - "8000:8000" - restart: always + 重启 mynginx: - image: nginx:1.13.6-alpine - ports: + image: nginx:1.13. -alpine + 端口： - "80:80" - depends_on: + 依赖于： - mysanic - volumes: - - ./mysanic.conf:/etc/nginx/conf.d/mysanic.conf - restart: always + 卷： + - . 神秘。 onf/etc/nginx/conf.d/mysanic.conf + 重启：总是 networks: default: @@ -170,13 +170,13 @@ networks: ``` ```` -.. column:: +.. 列: ``` -After that, we can start them: +然后，我们可以开始： ``` -.. column:: +.. 列: ```` ```shell @@ -184,13 +184,13 @@ docker-compose up -d ``` ```` -.. column:: +.. 列: ``` -Now, we can visit `http://localhost:80` to see the result: +现在，我们可以访问 `http://localhost:80` 查看结果： ``` -.. column:: +.. 列: ```` ```text From 7581af6b0cf4055b8d20de9c7fd3d2c15192fdc8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:13 +0200 Subject: [PATCH 332/698] New translations nginx.md (Japanese) --- guide/content/ja/guide/deployment/nginx.md | 56 +++++++++++----------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/guide/content/ja/guide/deployment/nginx.md b/guide/content/ja/guide/deployment/nginx.md index ee78d2967a..7c7b26e5ae 100644 --- a/guide/content/ja/guide/deployment/nginx.md +++ b/guide/content/ja/guide/deployment/nginx.md @@ -1,19 +1,19 @@ -# Nginx Deployment +# Nginx デプロイ -## Introduction +## はじめに -Although Sanic can be run directly on Internet, it may be useful to use a proxy -server such as Nginx in front of it. This is particularly useful for running +Sanicはインターネット上で直接実行することができますが、Nginxなどのプロキシ +サーバーをその前に使用すると便利です。 This is particularly useful for running multiple virtual hosts on the same IP, serving NodeJS or other services beside a single Sanic app, and it also allows for efficient serving of static files. -TLS and HTTP/2 are also easily implemented on such proxy. +TLS と HTTP/2 は、このようなプロキシでも容易に実装されています。 -We are setting the Sanic app to serve only locally at 127.0.0.1:8001, while the -Nginx installation is responsible for providing the service to public Internet -on domain example.com. Static files will be served by Nginx for maximal -performance. +Sanicアプリは127.0.0でローカルでのみ動作するように設定しています。 :8001, 一方、 +Nginx のインストールは、ドメインの example.com 上のパブリック インターネット +にサービスを提供する責任があります。 スタティックファイルは最大 +パフォーマンスのためにNginxによって提供されます。 -## Proxied Sanic app +## プロキシされたサニックアプリ ```python from sanic import Sanic @@ -30,34 +30,34 @@ def index(request): ) ``` -Since this is going to be a system service, save your code to -`/srv/sanicservice/proxied_example.py`. +これはシステムサービスになりますので、コードを +`/srv/sanicservice/proxied_example.py`に保存してください。 -For testing, run your app in a terminal using the `sanic` CLI in the folder where you saved the file. +テストのために、ファイルを保存したフォルダにある `sanic` CLI を使用して、アプリをターミナルで実行します。 ```bash SANIC_FORWARDED_SECRET=_hostname sanic proxied_example --port 8001 ``` -We provide Sanic config `FORWARDED_SECRET` to identify which proxy it gets -the remote addresses from. Note the `_` in front of the local hostname. +Sanic config `FORWARDED_SECRET`を用意して、リモートアドレスから +取得するプロキシを特定します。 ローカルホスト名の前にある `_` に注意してください。 This gives basic protection against users spoofing these headers and faking their IP addresses and more. -## SSL certificates +## SSL 証明書 -Install Certbot and obtain a certicate for all your domains. This will spin up its own webserver on port 80 for a moment to verify you control the given domain names. +Certbotをインストールし、すべてのドメインの証明書を取得してください。 これは、指定されたドメイン名を制御することを確認するために、しばらくの間、ポート80上で独自のWebサーバーを起動します。 ```bash certbot -d example.com -d www.example.com ``` -## Nginx configuration +## Nginx 設定 -Quite much configuration is required to allow fast transparent proxying, but -for the most part these don't need to be modified, so bear with me. +高速な透過プロキシを許可するには、非常に多くの構成が必要です しかし、ほとんどの場合、 +は修正する必要はありません。 -.. tip:: Note +.. tip:: メモ ``` Separate upstream section, rather than simply adding the IP after `proxy_pass` @@ -127,19 +127,19 @@ map $remote_addr $for_addr { } ``` -Start or restart Nginx for changes to take effect. E.g. +変更を有効にするためにNginxを起動または再起動します。 例えば、 ```bash systemctl restart nginx ``` -You should be able to connect your app on `https://example.com`. Any 404 +`https://example.com`でアプリを接続できます。 Any 404 errors and such will be handled by Sanic's error pages, and whenever a static file is present at a given path, it will be served by Nginx. -## Running as a service +## サービスとして実行中 -This part is for Linux distributions based on `systemd`. Create a unit file +この部分は `systemd` に基づいたLinuxディストリビューション用です。 Create a unit file `/etc/systemd/system/sanicexample.service` ``` @@ -157,7 +157,7 @@ Restart=always WantedBy=multi-user.target ``` -Then reload service files, start your service and enable it on boot: +次に、サービスファイルを再読み込みし、サービスを開始し、起動時に有効にします: ```bash systemctl daemon-reload @@ -165,8 +165,8 @@ systemctl start sanicexample systemctl enable sanicexample ``` -.. tip:: Note +.. tip:: メモ ``` -For brevity we skipped setting up a separate user account and a Python virtual environment or installing your app as a Python module. There are good tutorials on those topics elsewhere that easily apply to Sanic as well. The DynamicUser setting creates a strong sandbox which basically means your application cannot store its data in files, so you may consider setting `User=sanicexample` instead if you need that. +簡潔さのために、別のユーザアカウントとPython仮想環境のセットアップをスキップしたり、アプリケーションをPythonモジュールとしてインストールしたりしました。 Sanicにも簡単に適用できる他のトピックについても良いチュートリアルがあります。 DynamicUser設定は強力なサンドボックスを作成します。これは、アプリケーションがファイルにデータを保存できないことを意味します。 その代わりに、`User=sanicexample` を設定することを考えてみましょう。 ``` From 4c432ed834bf6caa0a78e7d9b6c9f5c66eca06b4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:15 +0200 Subject: [PATCH 333/698] New translations nginx.md (Chinese Simplified) --- guide/content/zh/guide/deployment/nginx.md | 94 +++++++++++----------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/guide/content/zh/guide/deployment/nginx.md b/guide/content/zh/guide/deployment/nginx.md index ee78d2967a..c7c2f8928c 100644 --- a/guide/content/zh/guide/deployment/nginx.md +++ b/guide/content/zh/guide/deployment/nginx.md @@ -1,19 +1,19 @@ -# Nginx Deployment +# Nginx 部署 -## Introduction +## 一. 导言 -Although Sanic can be run directly on Internet, it may be useful to use a proxy -server such as Nginx in front of it. This is particularly useful for running -multiple virtual hosts on the same IP, serving NodeJS or other services beside -a single Sanic app, and it also allows for efficient serving of static files. -TLS and HTTP/2 are also easily implemented on such proxy. +虽然Sanic可以直接在互联网上运行，但在互联网前使用代理 +服务器可能是有用的，例如Nginx。 这对于运行同一IP上的 +多个虚拟主机特别有用， 服务于NodeJS或除了 +单个Sanic应用之外的其他服务，并且它还允许有效地服务于静态文件。 +TLS和HTTP-2也很容易在这种代理上执行。 -We are setting the Sanic app to serve only locally at 127.0.0.1:8001, while the -Nginx installation is responsible for providing the service to public Internet -on domain example.com. Static files will be served by Nginx for maximal -performance. +我们正在设置 Sanic 应用程序仅在本地服务为127.0.0。 :8001， +Nginx 安装负责为域示例.com上的公共互联网 +提供服务。 静态文件将由Nginx提供最大 +性能。 -## Proxied Sanic app +## Proxied Sanic 应用 ```python from sanic import Sanic @@ -30,44 +30,44 @@ def index(request): ) ``` -Since this is going to be a system service, save your code to -`/srv/sanicservice/proxied_example.py`. +由于这是一个系统服务，将您的代码保存到 +`/srv/sanicservice/proxied_example.py`。 -For testing, run your app in a terminal using the `sanic` CLI in the folder where you saved the file. +为测试，使用你保存文件的文件夹中的 `sanic` CLI 在终端中运行你的应用程序。 ```bash -SANIC_FORWARDED_SECRET=_hostname sanic proxied_example --port 8001 +SANIC_FORWARDED_SECRET=_hostname sanic proxied_example --端口 8001 ``` We provide Sanic config `FORWARDED_SECRET` to identify which proxy it gets -the remote addresses from. Note the `_` in front of the local hostname. -This gives basic protection against users spoofing these headers and faking -their IP addresses and more. +the remote addresses from. 请注意本地主机名前面的`_` 。 +这提供了基本的保护，免受那些假冒头头并传真到 +他们的IP地址等用户的伤害。 -## SSL certificates +## SSL 证书 -Install Certbot and obtain a certicate for all your domains. This will spin up its own webserver on port 80 for a moment to verify you control the given domain names. +安装 Certbot 并获得您所有域的节拍。 这将会在80端口上增加它自己的web服务器，以验证您控制给定的域名。 ```bash certbot -d example.com -d www.example.com ``` -## Nginx configuration +## Nginx 配置 -Quite much configuration is required to allow fast transparent proxying, but -for the most part these don't need to be modified, so bear with me. +需要很多配置才能快速透明的代理， 但 +大部分情况下不需要修改这些内容，所以与我休戚与共。 -.. tip:: Note +.. 提示：备注 ``` -Separate upstream section, rather than simply adding the IP after `proxy_pass` -as in most tutorials, is needed for HTTP keep-alive. We also enable streaming, -WebSockets and Nginx serving static files. +HTTP keep-live需要分隔上游部分，而不是像大多数教程中那样只是在"proxy_pass" +之后添加IP。 我们还启用了串流， +WebSockets 和 Nginx 服务于静态文件。 ``` -The following config goes inside the `http` section of `nginx.conf` or if your -system uses multiple config files, `/etc/nginx/sites-available/default` or -your own files (be sure to symlink them to `sites-enabled`): +以下配置在 `nginx 的 `http` 部分内。 开启或如果您的 +系统使用多个配置文件，`/etc/nginx/sites-available/default` 或 +您自己的文件(肯定要将它们与`sites-enabled\`链接)： ```nginx # Files managed by Certbot @@ -127,46 +127,46 @@ map $remote_addr $for_addr { } ``` -Start or restart Nginx for changes to take effect. E.g. +启动或重启 Nginx 以使更改生效。 例如： ```bash -systemctl restart nginx +systemctl 重启 nginx ``` -You should be able to connect your app on `https://example.com`. Any 404 -errors and such will be handled by Sanic's error pages, and whenever a static -file is present at a given path, it will be served by Nginx. +您应该能够在 `https://example.com` 上连接您的应用程序。 任何 404 +错误将通过 Sanic's 错误页面处理， 并且当静态 +文件存在于给定路径时，它将由Nginx提供服务。 -## Running as a service +## 作为服务运行 -This part is for Linux distributions based on `systemd`. Create a unit file +本部分是基于 `systemd` 的 Linux 发行版。 创建一个单位文件 `/etc/systemd/system/sanicexample.service` ``` [Unit] -Description=Sanic Example +描述=Sanic 示例 [Service] -DynamicUser=Yes +动态用户=是 WorkingDirectory=/srv/sanicservice Environment=SANIC_PROXY_SECRET=_hostname -ExecStart=sanic proxied_example --port 8001 --fast -Restart=always +ExecStart=sanic proxied_example --porter 8001 --fast +Restart=始终 [Install] -WantedBy=multi-user.target +WantedBy=multi-user.target。 ``` -Then reload service files, start your service and enable it on boot: +然后重新加载服务文件，启动您的服务并在启动时启用它： ```bash systemctl daemon-reload systemctl start sanicexample -systemctl enable sanicexample +systemctl 启用sanicexample ``` -.. tip:: Note +.. 提示：备注 ``` -For brevity we skipped setting up a separate user account and a Python virtual environment or installing your app as a Python module. There are good tutorials on those topics elsewhere that easily apply to Sanic as well. The DynamicUser setting creates a strong sandbox which basically means your application cannot store its data in files, so you may consider setting `User=sanicexample` instead if you need that. +为简洁起见，我们跳过了设置一个单独的用户帐户和 Python 虚拟环境或将您的应用程序安装为 Python 模块。 其他地方也有很好的关于这些题目的教程，很容易应用于萨尼克。 动态用户设置创建了一个强大的沙盒，基本上意味着您的应用程序不能将其数据存储在文件中， 所以，如果您需要，您可以考虑设置 `User=sanicexplle` 。 ``` From 125da8206448ec391e43afe6b54f8166994e44a7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:16 +0200 Subject: [PATCH 334/698] New translations getting-started.md (Japanese) --- guide/content/ja/guide/getting-started.md | 64 +++++++++++------------ 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/guide/content/ja/guide/getting-started.md b/guide/content/ja/guide/getting-started.md index 67fc26f940..00189a8fc3 100644 --- a/guide/content/ja/guide/getting-started.md +++ b/guide/content/ja/guide/getting-started.md @@ -1,16 +1,16 @@ -# Getting Started +# はじめに -Before we begin, make sure you are running Python 3.8 or higher. Currently, Sanic is works with Python versions 3.8 – 3.11. +始める前に、Python 3.8 以上を実行していることを確認してください。 現在、SanicはPythonバージョン3.8 - 3.11で動作します。 -## Install +## インストール ```sh pip install sanic ``` -## Hello, world application +## こんにちは、世界のアプリケーション -.. column:: +.. 列:: ``` If you have ever used one of the many decorator based frameworks, this probably looks somewhat familiar to you. @@ -22,7 +22,7 @@ If you have ever used one of the many decorator based frameworks, this probably If you are coming from Flask or another framework, there are a few important things to point out. Remember, Sanic aims for performance, flexibility, and ease of use. These guiding principles have tangible impact on the API and how it works. ``` -.. column:: +.. 列:: ```` ```python @@ -37,21 +37,21 @@ async def hello_world(request): ``` ```` -### Important to note +### ご注意ください -- Every request handler can either be sync (`def hello_world`) or async (`async def hello_world`). Unless you have a clear reason for it, always go with `async`. -- The `request` object is always the first argument of your handler. Other frameworks pass this around in a context variable to be imported. In the `async` world, this would not work so well and it is far easier (not to mention cleaner and more performant) to be explicit about it. -- You **must** use a response type. MANY other frameworks allow you to have a return value like this: `return "Hello, world."` or this: `return {"foo": "bar"}`. But, in order to do this implicit calling, somewhere in the chain needs to spend valuable time trying to determine what you meant. So, at the expense of this ease, Sanic has decided to require an explicit call. +- 各リクエストハンドラーは、sync (`def hello_world`) または async (`async def hello_world`) のいずれかになります。 明確な理由がない限り、常に `async` を使用します。 +- `request` オブジェクトは常にハンドラの最初の引数です。 他のフレームワークは、インポートされるコンテキスト変数にこれを渡します。 `async` ワールドで うまくいかないし、明らかにするのははるかに簡単です(クリーナーやパフォーマンスの向上は言うまでもありません)。 +- 応答タイプを**使用する必要があります**。 他の多くのフレームワークでは、`return "Hello, world."` または: `return {"foo": "bar"}` のような戻り値を持つことができます。 しかしこの暗黙の呼び出しを行うためには、チェーン内のどこかで、あなたが何を意味するのかを判断するために貴重な時間を費やす必要があります。 したがって、これを犠牲にして、Sanicは明示的な呼び出しを要求することにしました。 -### Running +### 実行中 -.. column:: +.. 列:: ``` -Let's save the above file as `server.py`. And launch it. +上記のファイルを `server.py` として保存して起動しましょう。 ``` -.. column:: +.. 列:: ```` ```sh @@ -62,27 +62,27 @@ sanic server .. note:: ``` -This **another** important distinction. Other frameworks come with a built in development server and explicitly say that it is _only_ intended for development use. The opposite is true with Sanic. +この**別の**重要な区別。他のフレームワークには開発用サーバーが組み込まれており、開発用のものであることを明示的に示しています。 -**The packaged server is production ready.** +**パッケージ化されたサーバーは準備ができています。** ``` -## Sanic Extensions +## サニックエクステンション -Sanic intentionally aims for a clean and unopinionated feature list. The project does not want to require you to build your application in a certain way, and tries to avoid prescribing specific development patterns. There are a number of third-party plugins that are built and maintained by the community to add additional features that do not otherwise meet the requirements of the core repository. +Sanicは、意図的にクリーンで不要なフィーチャーリストを目指しています。 プロジェクトは、特定の方法でアプリケーションを構築する必要はありませんし、特定の開発パターンを処方しないようにしようとします。 コミュニティによって構築され、維持されているいくつかのサードパーティーのプラグインがあります, それ以外の場合、コアリポジトリの要件を満たしていない追加の機能を追加します. -However, in order **to help API developers**, the Sanic organization maintains an official plugin called [Sanic Extensions](../plugins/sanic-ext/getting-started.md) to provide all sorts of goodies, including: +しかし、**API 開発者を助けるために**ために、Sanic Organization は [Sanic Extensions](../plugins/sanic-ext/getting-started.md) と呼ばれる公式プラグインを管理し、以下を含むあらゆる種類のグッズを提供します。 -- **OpenAPI** documentation with Redoc and/or Swagger -- **CORS** protection -- **Dependency injection** into route handlers -- Request query arguments and body input **validation** -- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints -- Predefined, endpoint-specific response serializers +- **OpenAPI** Redoc や Swagger 付きドキュメント +- **CORS** 保護 +- ルートハンドラへの**依存性注入** +- クエリの引数と本文入力**バリデーション** +- `HEAD`、`OPTIONS`、および `TRACE`エンドポイントを自動的に作成します +- 事前定義されたエンドポイント固有のレスポンスシリアライザー -The preferred method to set it up is to install it along with Sanic, but you can also install the packages on their own. +設定するにはSanicと一緒にインストールする方法が推奨されますが、独自にパッケージをインストールすることもできます。 -.. column:: +.. 列:: ```` ```sh @@ -90,7 +90,7 @@ pip install sanic[ext] ``` ```` -.. column:: +.. 列:: ```` ```sh @@ -98,9 +98,9 @@ pip install sanic sanic-ext ``` ```` -Starting in v21.12, Sanic will automatically setup Sanic Extensions if it is in the same environment. You will also have access to two additional application properties: +同じ環境であれば、Sanicは自動的にSanic Extensionをv21.12から設定します。 2つの追加アプリケーションプロパティにもアクセスできます。 -- `app.extend()` - used to configure Sanic Extensions -- `app.ext` - the `Extend` instance attached to the application +- `app.extend()` - Sanic Extensionsの設定に使用 +- `app.ext` - アプリケーションに追加された `Extend` インスタンス -See [the plugin documentation](../plugins/sanic-ext/getting-started.md) for more information about how to use and work with the plugin +プラグインの使用方法と操作方法については、format@@0(../plugins/sanic-ext/getting-started.md) を参照してください。 From 8bfb17e24757c195f80351feead782a2f76ec419 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:18 +0200 Subject: [PATCH 335/698] New translations getting-started.md (Chinese Simplified) --- guide/content/zh/guide/getting-started.md | 72 +++++++++++------------ 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/guide/content/zh/guide/getting-started.md b/guide/content/zh/guide/getting-started.md index 67fc26f940..8fccd7898f 100644 --- a/guide/content/zh/guide/getting-started.md +++ b/guide/content/zh/guide/getting-started.md @@ -1,16 +1,16 @@ -# Getting Started +# 正在开始 -Before we begin, make sure you are running Python 3.8 or higher. Currently, Sanic is works with Python versions 3.8 – 3.11. +在我们开始之前，请确保您正在运行 Python 3.8或更高版本。 目前，Sanic正在与 Python 版本 3.8 - 3.11一起工作。 -## Install +## 安装 ```sh -pip install sanic +pip 安装sanic ``` -## Hello, world application +## 您好，全局应用程序 -.. column:: +.. 列: ``` If you have ever used one of the many decorator based frameworks, this probably looks somewhat familiar to you. @@ -22,36 +22,36 @@ If you have ever used one of the many decorator based frameworks, this probably If you are coming from Flask or another framework, there are a few important things to point out. Remember, Sanic aims for performance, flexibility, and ease of use. These guiding principles have tangible impact on the API and how it works. ``` -.. column:: +.. 列: ```` ```python -from sanic import Sanic +from sanic importing Sanic from sanic.response import text app = Sanic("MyHelloWorldApp") -@app.get("/") +@app. et("/") async def hello_world(request): return text("Hello, world.") ``` ```` -### Important to note +### 重要的注意事项 -- Every request handler can either be sync (`def hello_world`) or async (`async def hello_world`). Unless you have a clear reason for it, always go with `async`. -- The `request` object is always the first argument of your handler. Other frameworks pass this around in a context variable to be imported. In the `async` world, this would not work so well and it is far easier (not to mention cleaner and more performant) to be explicit about it. -- You **must** use a response type. MANY other frameworks allow you to have a return value like this: `return "Hello, world."` or this: `return {"foo": "bar"}`. But, in order to do this implicit calling, somewhere in the chain needs to spend valuable time trying to determine what you meant. So, at the expense of this ease, Sanic has decided to require an explicit call. +- 每个请求处理程序都可以同步(`def hello_world`)，也可以同步(`async def hello_world`)。 除非你有明确的理由，否则总是使用 "async"。 +- "request" 对象始终是你处理器的第一个参数。 其它框架在要导入的上下文变量中传递这一点。 在 "async" 世界中 这种情况不会很好地发挥作用，因此更容易(更干净和业绩更好)对此加以明确说明。 +- 您**必须** 使用响应类型。 其他框架允许您有一个返回值，如：`return "Hello, world."` 或者 `return {"foo": "bar"}`。 但是，为了进行这种隐性的呼叫，链中的某个地方需要花费宝贵的时间来确定你的意思。 因此，萨尼克以牺牲这个容易为代价，决定要求明确呼叫。 -### Running +### 正在运行 -.. column:: +.. 列: ``` -Let's save the above file as `server.py`. And launch it. +让我们把上面的文件保存为 `server.py`。然后启动它。 ``` -.. column:: +.. 列: ```` ```sh @@ -59,30 +59,30 @@ sanic server ``` ```` -.. note:: +.. 注： ``` -This **another** important distinction. Other frameworks come with a built in development server and explicitly say that it is _only_ intended for development use. The opposite is true with Sanic. +这**另一个**重要的区别。其它框架包含在开发服务器中，并明确表示它仅用于开发用途。 Sanic的情况正好相反。 -**The packaged server is production ready.** +**打包服务器已准备就绪。** ``` -## Sanic Extensions +## 无声扩展 -Sanic intentionally aims for a clean and unopinionated feature list. The project does not want to require you to build your application in a certain way, and tries to avoid prescribing specific development patterns. There are a number of third-party plugins that are built and maintained by the community to add additional features that do not otherwise meet the requirements of the core repository. +无知的特色清单的目的是要有一个清洁和无见解的特色清单。 该项目不想要求您以某种方式构建您的应用程序，并试图避免指定特定的开发模式。 有一些第三方插件由社区构建和维护，用于添加额外的功能，这些功能不符合核心存储库的要求。 -However, in order **to help API developers**, the Sanic organization maintains an official plugin called [Sanic Extensions](../plugins/sanic-ext/getting-started.md) to provide all sorts of goodies, including: +但是，为了帮助API开发者\*\*，Sanic 组织维持一个名为[Sanic Extensions](../plugins/sanic-ext/getting-started.md)的官方插件，提供各种各样的谷物，其中包括： -- **OpenAPI** documentation with Redoc and/or Swagger -- **CORS** protection -- **Dependency injection** into route handlers -- Request query arguments and body input **validation** -- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints -- Predefined, endpoint-specific response serializers +- **OpenAPI** 文档与 Redoc 或 Swagger +- **CORS** 保护 +- **依赖注入** 对路由处理程序 +- 请求查询参数和正文输入 **验证** +- 自动创建 `HEAD`, `OPTIONS` 和 `TRACE` 终点 +- 预定义的端点特定响应序列转换器 -The preferred method to set it up is to install it along with Sanic, but you can also install the packages on their own. +设置它的首选方法是与 Sanic 一起安装，但你也可以自己安装这个软件包。 -.. column:: +.. 列: ```` ```sh @@ -90,7 +90,7 @@ pip install sanic[ext] ``` ```` -.. column:: +.. 列: ```` ```sh @@ -98,9 +98,9 @@ pip install sanic sanic-ext ``` ```` -Starting in v21.12, Sanic will automatically setup Sanic Extensions if it is in the same environment. You will also have access to two additional application properties: +从 v21.12开始，萨尼语将在同一环境中自动设置萨尼克扩展。 您还可以访问另外两个应用程序属性： -- `app.extend()` - used to configure Sanic Extensions -- `app.ext` - the `Extend` instance attached to the application +- `app.extend()` - 用于配置 Sanic 扩展 +- `app.ext` - 附加到应用程序的`Extend`实例 -See [the plugin documentation](../plugins/sanic-ext/getting-started.md) for more information about how to use and work with the plugin +请参阅[插件文档](../plugins/sanic-ext/getting-started.md) 了解如何使用和使用插件的更多信息 From b8529acd9c2439bd82b186bd45752591c8ca434d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:20 +0200 Subject: [PATCH 336/698] New translations readme.md (Chinese Simplified) --- guide/content/zh/guide/how-to/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/README.md b/guide/content/zh/guide/how-to/README.md index 8e66fc0483..cde79793eb 100644 --- a/guide/content/zh/guide/how-to/README.md +++ b/guide/content/zh/guide/how-to/README.md @@ -1 +1 @@ -# How to ... +# 如何... From 1bcec1bcac813ae8318a1b0a439e9261f3222980 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:21 +0200 Subject: [PATCH 337/698] New translations authentication.md (Japanese) --- guide/content/ja/guide/how-to/authentication.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guide/content/ja/guide/how-to/authentication.md b/guide/content/ja/guide/how-to/authentication.md index 28e1bc29ad..c6ac86a3bd 100644 --- a/guide/content/ja/guide/how-to/authentication.md +++ b/guide/content/ja/guide/how-to/authentication.md @@ -1,8 +1,8 @@ -# Authentication +# 認証 -> How do I control authentication and authorization? +> 認証と認証を制御するにはどうすればよいですか? -This is an _extremely_ complicated subject to cram into a few snippets. But, this should provide you with an idea on ways to tackle this problem. This example uses [JWTs](https://jwt.io/), but the concepts should be equally applicable to sessions or some other scheme. +これは、いくつかのスニペットに詰め込むために_非常に複雑な対象です。 しかし、これはこの問題に取り組む方法についてのアイデアを提供する必要があります。 この例では [JWTs](https://jwt.io/)を使用しますが、この概念はセッションや他のスキームにも同様に適用されるはずです。 ## `server.py` @@ -74,7 +74,7 @@ def protected(wrapped): return decorator(wrapped) ``` -This decorator pattern is taken from the [decorators page](/en/guide/best-practices/decorators.md). +このデコレータパターンは format@@0(/ja/guide/best-practices/decorators.md) から取得されます。 *** @@ -110,7 +110,7 @@ content-type: text/plain; charset=utf-8 You are unauthorized. ``` -Also, checkout some resources from the community: +また、コミュニティからいくつかのリソースをチェックアウトします。 - Awesome Sanic - [Authorization](https://github.com/mekicha/awesome-sanic/blob/master/README.md#authentication) & [Session](https://github.com/mekicha/awesome-sanic/blob/master/README.md#session) -- [EuroPython 2020 - Overcoming access control in web APIs](https://www.youtube.com/watch?v=Uqgoj43ky6A) +- [EuroPython 2020 - Web APIでのアクセス制御の克服](https://www.youtube.com/watch?v=Uqgoj43ky6A) From 792deb3473e02311f54fcf410e76d88afb2d8eca Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:23 +0200 Subject: [PATCH 338/698] New translations authentication.md (Chinese Simplified) --- .../content/zh/guide/how-to/authentication.md | 66 +++++++++---------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/guide/content/zh/guide/how-to/authentication.md b/guide/content/zh/guide/how-to/authentication.md index 28e1bc29ad..9935a00247 100644 --- a/guide/content/zh/guide/how-to/authentication.md +++ b/guide/content/zh/guide/how-to/authentication.md @@ -1,37 +1,37 @@ -# Authentication +# 认证 -> How do I control authentication and authorization? +> 如何控制认证和授权？ -This is an _extremely_ complicated subject to cram into a few snippets. But, this should provide you with an idea on ways to tackle this problem. This example uses [JWTs](https://jwt.io/), but the concepts should be equally applicable to sessions or some other scheme. +这是一个非常复杂的 _extremy_ ，要把它变成几个代码片段。 但是，这应该为你们提供一个解决这一问题的方法的想法。 此示例使用 [JWTs](https://jwt.io/)，但概念应该同样适用于会话或其他方案。 ## `server.py` ```python -from sanic import Sanic, text +从 sanic import Sanic, text from auth import protected from login import login app = Sanic("AuthApp") -app.config.SECRET = "KEEP_IT_SECRET_KEEP_IT_SAFE" -app.blueprint(login) +app.config.SECRET = “KEEP_IT_SECRET_KEEP_IT_SAFE” +app. lueprint(login) @app.get("/secret") @protected async def secret(request): - return text("To go fast, you must be fast.") + return text("to go fast, you must be fas.") ``` ## `login.py` ```python -import jwt -from sanic import Blueprint, text +从 Sanic 导入蓝图导入jt +文本 login = Blueprint("login", url_prefix="/login") -@login.post("/") -async def do_login(request): +@login。 ost("/") +async def do_login(请求): token = jwt.encode({}, request.app.config.SECRET) return text(token) ``` @@ -74,43 +74,43 @@ def protected(wrapped): return decorator(wrapped) ``` -This decorator pattern is taken from the [decorators page](/en/guide/best-practices/decorators.md). +这种装饰模式取自[装饰品页面](/en/guide/best practices/decorators.md)。 *** ```bash -$ curl localhost:9999/secret -i -HTTP/1.1 401 Unauthorized +$ curl localhost:99999/secret -i +HTTP/1.1 401 未经授权的 content-length: 21 connection: keep-alive -content-type: text/plain; charset=utf-8 +content-type: text/pla; charset=utf-8 -You are unauthorized. +您未被授权。 -$ curl localhost:9999/login -X POST -eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE +$curl localhost:9999/log-X POST +eyJ0eXAiOiJKV1QiLCJhbGciOiJIUZI1NiJ9。 30.rjxS7ztIGt5tpirWS8BGLUqjQFca4QOetHcZTi061DE -$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.rjxS7ztIGt5tpiRWS8BGLUqjQFca4QOetHcZTi061DE" -HTTP/1.1 200 OK -content-length: 29 -connection: keep-alive -content-type: text/plain; charset=utf-8 +$ curl localhost:99999/secret -i -H "Authorization: Bearer eyJ0eXAioJKV1QiLCJhbGciOiJIUZI1NiJ9.e30.rjxS7ztIGt5tpirWS8BGLUqjQFca4QOetZTi061DE" +HTTP/1。 200 OK +内容长度：29 +连接：保持存活 +内容类型：text/pla；charset=utf-8 -To go fast, you must be fast. +要快速，您必须快速。 -$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.e30.BAD" -HTTP/1.1 401 Unauthorized -content-length: 21 -connection: keep-alive -content-type: text/plain; charset=utf-8 +$ curl localhost:9999/secret -i -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUZI1NiJ9. 30.BAD" +HTTP/1。 401 未经授权的 +内容长度：21 +连接：保持存活 +内容类型：text/plain；charset=utf-8 -You are unauthorized. +您未经授权。 ``` -Also, checkout some resources from the community: +此外，结算社区的一些资源： -- Awesome Sanic - [Authorization](https://github.com/mekicha/awesome-sanic/blob/master/README.md#authentication) & [Session](https://github.com/mekicha/awesome-sanic/blob/master/README.md#session) -- [EuroPython 2020 - Overcoming access control in web APIs](https://www.youtube.com/watch?v=Uqgoj43ky6A) +- 非常棒的 Sanic - [Authorization](https://github.com/mekicha/awesome-sanic/blob/master/README.md#认证) & [Session](https://github.com/mekicha/awesome-sanic/blob/master/README.md#session) +- [EuroPython 2020 - overcoming access control in web API](https://www.youtube.com/watch?v=Uqgoj43ky6A) From 6f3399d243c2e9b33837fa56726a3e293bfdacc2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:24 +0200 Subject: [PATCH 339/698] New translations autodiscovery.md (Japanese) --- guide/content/ja/guide/how-to/autodiscovery.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/guide/content/ja/guide/how-to/autodiscovery.md b/guide/content/ja/guide/how-to/autodiscovery.md index 90cda60083..a0929ea7d9 100644 --- a/guide/content/ja/guide/how-to/autodiscovery.md +++ b/guide/content/ja/guide/how-to/autodiscovery.md @@ -1,16 +1,16 @@ --- -title: Autodiscovery +title: 自動検出 --- -# Autodiscovery of Blueprints, Middleware, and Listeners +# 設計図、ミドルウェア、リスナーの自動発見 -> How do I autodiscover the components I am using to build my application? +> アプリケーションを構築するために使用しているコンポーネントを自動検出するにはどうすればよいですか? -One of the first problems someone faces when building an application, is _how_ to structure the project. Sanic makes heavy use of decorators to register route handlers, middleware, and listeners. And, after creating blueprints, they need to be mounted to the application. +誰かがアプリケーションを構築する際に直面する最初の問題の1つは、プロジェクトを構成する方法\*です。 Sanicはルートハンドラ、ミドルウェア、リスナーを登録するためにデコレータを活用しています。 そして、設計図を作成した後、アプリケーションにマウントする必要があります。 -A possible solution is a single file in which **everything** is imported and applied to the Sanic instance. Another is passing around the Sanic instance as a global variable. Both of these solutions have their drawbacks. +可能な解決策は、**everything** がインポートされ、Sanic インスタンスに適用される単一のファイルです。 もう一つは、グローバル変数として Sanic インスタンスを渡すことです。 これらの解決策の両方に欠点があります。 -An alternative is autodiscovery. You point your application at modules (already imported, or strings), and let it wire everything up. +代替案は自己発見である。 アプリケーションをモジュール(既にインポートされている、または文字列)に向けて、すべてのものを配線します。 ## `server.py` @@ -183,7 +183,7 @@ generate with 'find . -type d -name "__pycache__" -exec rm -rf {} +; tree' ```sh source ./.venv/bin/activate # activate the python venv which sanic is installed in -sanic sever -d # run this in the directory containing server.py +sanic sever -d # run this in the directory including server.py ``` ```text From 3bb25f49f7192f872f5b6d44efafb97195d17bd1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:26 +0200 Subject: [PATCH 340/698] New translations autodiscovery.md (Chinese Simplified) --- .../content/zh/guide/how-to/autodiscovery.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/guide/content/zh/guide/how-to/autodiscovery.md b/guide/content/zh/guide/how-to/autodiscovery.md index 90cda60083..a0e9399677 100644 --- a/guide/content/zh/guide/how-to/autodiscovery.md +++ b/guide/content/zh/guide/how-to/autodiscovery.md @@ -1,16 +1,16 @@ --- -title: Autodiscovery +title: 自动发现 --- -# Autodiscovery of Blueprints, Middleware, and Listeners +# 自动发现蓝图、中程和侦听器 -> How do I autodiscover the components I am using to build my application? +> 我如何自动发现我正在使用的组件来构建我的应用程序？ -One of the first problems someone faces when building an application, is _how_ to structure the project. Sanic makes heavy use of decorators to register route handlers, middleware, and listeners. And, after creating blueprints, they need to be mounted to the application. +某人在构建应用程序时面临的第一个问题是_如何_构建项目。 Sanic大量使用装饰器注册路由处理器、中间人和听众。 在创建蓝图后，它们需要安装到应用程序上。 -A possible solution is a single file in which **everything** is imported and applied to the Sanic instance. Another is passing around the Sanic instance as a global variable. Both of these solutions have their drawbacks. +可能的解决方案是一个 **每件事** 导入并应用到 Sanic 实例的单一文件。 另一个正在环绕着Sanic实例作为一个全球变量。 这两种解决办法都有其缺点。 -An alternative is autodiscovery. You point your application at modules (already imported, or strings), and let it wire everything up. +另一种办法是自动发现。 您将您的应用程序指向模块 (已导入，或字符串)，并让它连接一切。 ## `server.py` @@ -93,7 +93,7 @@ def autodiscover( app.blueprint(bp) ``` -## `blueprints/level1.py` +## `蓝图/level1.py` ```python from sanic import Blueprint @@ -106,7 +106,7 @@ def print_something(app, loop): logger.debug("something @ level1") ``` -## `blueprints/one/two/level3.py` +## “蓝图1e/2/level3.py” ```python from sanic import Blueprint @@ -119,7 +119,7 @@ def print_something(app, loop): logger.debug("something @ level3") ``` -## `listeners/something.py` +## `监听器/something.py` ```python from sanic import Sanic @@ -148,14 +148,14 @@ def print_something(app, loop): ## `parent/child/nested.py` ```python -from sanic import Blueprint -from sanic.log import logger +从sanic.log 导入蓝图 +从sanic.log 导入记录器 -nested = Blueprint("nested") +嵌套= Blueprint("嵌套") -@nested.after_server_start +@nested.after _server_start def print_something(app, loop): - logger.debug("something @ nested") + logger.debug("some @ 嵌套") ``` *** @@ -182,8 +182,8 @@ generate with 'find . -type d -name "__pycache__" -exec rm -rf {} +; tree' ``` ```sh -source ./.venv/bin/activate # activate the python venv which sanic is installed in -sanic sever -d # run this in the directory containing server.py +源 ./.venv/bin/激活 # 激活安装在 +sanic sever -d # 中的 python venv 在包含服务器的目录中运行它。 ``` ```text From 23ad6d7c359ff1e346e4e242d5cab458f45e6781 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:27 +0200 Subject: [PATCH 341/698] New translations cors.md (Japanese) --- guide/content/ja/guide/how-to/cors.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guide/content/ja/guide/how-to/cors.md b/guide/content/ja/guide/how-to/cors.md index 250b0aea74..8b37caf73d 100644 --- a/guide/content/ja/guide/how-to/cors.md +++ b/guide/content/ja/guide/how-to/cors.md @@ -2,16 +2,16 @@ title: CORS --- -# Cross-origin resource sharing (CORS) +# クロスオリジンリソース共有 (CORS) -> How do I configure my application for CORS? +> CORS のアプリケーションを設定するにはどうすればよいですか? .. note:: ``` -🏆 The best solution is to use [Sanic Extensions](../../plugins/sanic-ext/http/cors.md). +🏆 最善の解決策は[Sanic Extensions](../../plugins/sanic-ext/http/cors.md)を使用することです。 -However, if you would like to build your own version, you could use this limited example as a starting point. +ただし、独自のバージョンをビルドしたい場合は、この限られた例を出発点として使用することができます。 ``` ### `server.py` @@ -133,6 +133,6 @@ Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsr connection: keep-alive ``` -Also, checkout some resources from the community: +また、コミュニティからいくつかのリソースをチェックアウトします。 -- [Awesome Sanic](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) +- format@@0(https\://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) From c5d769be6e43476424fb35c7065276fb9344a566 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:29 +0200 Subject: [PATCH 342/698] New translations cors.md (Chinese Simplified) --- guide/content/zh/guide/how-to/cors.md | 42 +++++++++++++-------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/guide/content/zh/guide/how-to/cors.md b/guide/content/zh/guide/how-to/cors.md index 250b0aea74..7fc5894825 100644 --- a/guide/content/zh/guide/how-to/cors.md +++ b/guide/content/zh/guide/how-to/cors.md @@ -2,16 +2,16 @@ title: CORS --- -# Cross-origin resource sharing (CORS) +# 跨来源资源共享 -> How do I configure my application for CORS? +> 如何配置我的 CORS 应用程序？ -.. note:: +.. 注： ``` -🏆 The best solution is to use [Sanic Extensions](../../plugins/sanic-ext/http/cors.md). +🏆 最好的解决方案是使用 [Sanic Extensions](../../plugins/sanic-ext/http/cors.md). -However, if you would like to build your own version, you could use this limited example as a starting point. +然而，如果你想要建立自己的版本，你可以使用这个有限的例子作为起点。 ``` ### `server.py` @@ -38,27 +38,27 @@ app.register_middleware(add_cors_headers, "response") ## `cors.py` ```python -from typing import Iterable +从输入导入Iterable -def _add_cors_headers(response, methods: Iterable[str]) -> None: +def _add_cors_headers(响应) 方法: Iterable[str]) -> 无: allow_methods = list(set(methods)) - if "OPTIONS" not in allow_methods: - allow_methods.append("OPTIONS") - headers = { - "Access-Control-Allow-Methods": ",".join(allow_methods), - "Access-Control-Allow-Origin": "mydomain.com", + 如果"OPTIONS" 不在allow_methods: + allow_methods. pend("OPTIONS") + headers = 哇， + "Access-Control-Allow-Methods"：","。 oin(allow_methods), + "Access-Control-Allow-origin": mydomain. om, "Access-Control-Allow-Credentials": "true", - "Access-Control-Allow-Headers": ( - "origin, content-type, accept, " + “Access Control-Allow-Headers”: ( + "original, 内容类型，接受，" "authorization, x-xsrf-token, x-request-id" - ), + , } - response.headers.extend(headers) + 响应。 eaders.extend(headers) def add_cors_headers(request, response): - if request.method != "OPTIONS": - methods = [method for method in request.route.methods] - _add_cors_headers(response, methods) + if request. ethod != "OPTIONS": + methods = [方法是请求的。 退出.methods] + _add_cors_headers(响应, 方法) ``` ## `options.py` @@ -133,6 +133,6 @@ Access-Control-Allow-Headers: origin, content-type, accept, authorization, x-xsr connection: keep-alive ``` -Also, checkout some resources from the community: +此外，结算社区的一些资源： -- [Awesome Sanic](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) +- [极好的卫生](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) From dd6e53c07e18587b40d95624dff446a00ff398d0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:32 +0200 Subject: [PATCH 343/698] New translations db.md (Japanese) --- guide/content/ja/guide/how-to/db.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/db.md b/guide/content/ja/guide/how-to/db.md index 60ca822eac..476e159da3 100644 --- a/guide/content/ja/guide/how-to/db.md +++ b/guide/content/ja/guide/how-to/db.md @@ -1 +1 @@ -connecting to data sources +データソースへの接続 From aed6254df2f7a1c205067234eaa0da3f7e47c257 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:33 +0200 Subject: [PATCH 344/698] New translations db.md (Chinese Simplified) --- guide/content/zh/guide/how-to/db.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/db.md b/guide/content/zh/guide/how-to/db.md index 60ca822eac..9ccd8b17ff 100644 --- a/guide/content/zh/guide/how-to/db.md +++ b/guide/content/zh/guide/how-to/db.md @@ -1 +1 @@ -connecting to data sources +连接到数据源 From 9a042aa73870d0c13dd57528fcc9d464f691710b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:34 +0200 Subject: [PATCH 345/698] New translations decorators.md (Japanese) --- guide/content/ja/guide/how-to/decorators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/decorators.md b/guide/content/ja/guide/how-to/decorators.md index 9ef318134e..7d03dd7182 100644 --- a/guide/content/ja/guide/how-to/decorators.md +++ b/guide/content/ja/guide/how-to/decorators.md @@ -1 +1 @@ -decorators +デコレーター From 05b4a6b3cc62b7213e1bc366156b89a52baa606f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:35 +0200 Subject: [PATCH 346/698] New translations decorators.md (Chinese Simplified) --- guide/content/zh/guide/how-to/decorators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/decorators.md b/guide/content/zh/guide/how-to/decorators.md index 9ef318134e..b101957cb9 100644 --- a/guide/content/zh/guide/how-to/decorators.md +++ b/guide/content/zh/guide/how-to/decorators.md @@ -1 +1 @@ -decorators +装饰 From bc07ec474483b4034f82c268d71082c7afd06dfb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:36 +0200 Subject: [PATCH 347/698] New translations mounting.md (Japanese) --- guide/content/ja/guide/how-to/mounting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/guide/how-to/mounting.md b/guide/content/ja/guide/how-to/mounting.md index 47bf056fbb..e484b27f92 100644 --- a/guide/content/ja/guide/how-to/mounting.md +++ b/guide/content/ja/guide/how-to/mounting.md @@ -1,6 +1,6 @@ -# Application Mounting +# アプリケーションのマウント -> How do I mount my application at some path above the root? +> アプリケーションを root の上にあるパスにマウントするにはどうすればよいですか? ```python # server.py @@ -44,7 +44,7 @@ server { ```bash $ docker-compose up -d -$ sanic server.app --port=9999 --host=0.0.0.0 +$ sanic server.app --port=9999 --host=0.0.0 ``` ```bash From ff97fe797b9718fd519cc5e6fe25ce1112c1eb8b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:38 +0200 Subject: [PATCH 348/698] New translations mounting.md (Chinese Simplified) --- guide/content/zh/guide/how-to/mounting.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/guide/content/zh/guide/how-to/mounting.md b/guide/content/zh/guide/how-to/mounting.md index 47bf056fbb..765eb14720 100644 --- a/guide/content/zh/guide/how-to/mounting.md +++ b/guide/content/zh/guide/how-to/mounting.md @@ -1,6 +1,6 @@ -# Application Mounting +# 应用程序挂载 -> How do I mount my application at some path above the root? +> 如何在root上方挂载我的应用程序？ ```python # server.py @@ -17,16 +17,16 @@ def handler(request): ```yaml # docker-compose.yml -version: "3.7" -services: - app: - image: nginx:alpine - ports: +版本: "3. +服务： + app： + 图像：nginx:alpine + ports： - 80:80 - volumes: - - type: bind - source: ./conf - target: /etc/nginx/conf.d/default.conf + 卷： + - 类型：binding + 消息来源： conf + 目标：/etc/nginx/conf.d/default.conf ``` ```nginx From 5bd926fda93c3e552bb93d036b729ecff3b423ea Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:39 +0200 Subject: [PATCH 349/698] New translations orm.md (Japanese) --- guide/content/ja/guide/how-to/orm.md | 136 +++++++++++++-------------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/guide/content/ja/guide/how-to/orm.md b/guide/content/ja/guide/how-to/orm.md index 5f7f188d9a..d8217fa619 100644 --- a/guide/content/ja/guide/how-to/orm.md +++ b/guide/content/ja/guide/how-to/orm.md @@ -1,31 +1,31 @@ # ORM -> How do I use SQLAlchemy with Sanic ? +> どのように私はSanicでSQLAlchemyを使用しますか? -All ORM tools can work with Sanic, but non-async ORM tool have a impact on Sanic performance. -There are some orm packages who support +すべてのORMツールはSanicで使用できますが、非同期ORMツールはSanicパフォーマンスに影響を与えます。 +サポートする Orm パッケージがいくつかあります -At present, there are many ORMs that support Python's `async`/`await` keywords. Some possible choices include： +現在、Python の `async`/`await` キーワードをサポートするORMがたくさんあります。 いくつかの可能な選択肢には： - [Mayim](https://ahopkins.github.io/mayim/) -- [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) -- [tortoise-orm](https://github.com/tortoise/tortoise-orm) +- [SQLAlchemy 1.4](https://docs.sqlalchemy.org/ja/14/changelog/changelog_14.html) +- [tortoise-orm](https://github.com/tortoise/turtoise-orm) -Integration in to your Sanic application is fairly simple: +Sanicアプリケーションへの統合はかなり簡単です: ## Mayim -Mayim ships with [an extension for Sanic Extensions](https://ahopkins.github.io/mayim/guide/extensions.html#sanic), which makes it super simple to get started with Sanic. It is certainly possible to run Mayim with Sanic without the extension, but it is recommended because it handles all of the [lifecycle events](https://sanic.dev/en/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html). +Mayimはformat@@0(https\://ahopkins.github.io/mayim/guide/extensions.html#sanic)と一緒に出荷します。 確かに拡張機能なしで Mayim を実行することは可能ですが、すべての format@@0(https\://sanic )を処理するために推奨されています。 ev/ja/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html) -.. column:: +.. 列:: ``` -### Dependencies +### 依存関係 -First, we need to install the required dependencies. See [Mayim docs](https://ahopkins.github.io/mayim/guide/install.html#postgres) for the installation needed for your DB driver. +まず、必要な依存関係をインストールする必要があります。DBドライバに必要なインストールについては、[Mayim docs](https://ahopkins.github.io/mayim/guide/install.html#postgres)を参照してください。 ``` -.. column:: +.. 列:: ```` ```shell @@ -34,7 +34,7 @@ pip install mayim[postgres] ``` ```` -.. column:: +.. 列:: ``` ### Define ORM Model @@ -42,7 +42,7 @@ pip install mayim[postgres] Mayim allows you to use whatever you want for models. Whether it is [dataclasses](https://docs.python.org/3/library/dataclasses.html), [pydantic](https://pydantic-docs.helpmanual.io/), [attrs](https://www.attrs.org/en/stable/), or even just plain `dict` objects. Since it works very nicely [out of the box with Pydantic](https://ahopkins.github.io/mayim/guide/pydantic.html), that is what we will use here. ``` -.. column:: +.. 列:: ```` ```python @@ -64,15 +64,15 @@ class Country(BaseModel): ``` ```` -.. column:: +.. 列:: ``` -### Define SQL +### SQLを定義する -If you are unfamiliar, Mayim is different from other ORMs in that it is one-way, SQL-first. This means you define your own queries either inline, or in a separate `.sql` file, which is what we will do here. +使い慣れていない場合、Mayimは一方向のSQL-firstであるという点で他のORMとは異なります。 これは、インラインまたは別の `.sql` ファイルで独自のクエリを定義することを意味します。 ``` -.. column:: +.. 列:: ```` ```sql @@ -97,15 +97,15 @@ LIMIT $limit OFFSET $offset; ``` ```` -.. column:: +.. 列:: ``` -### Create Sanic App and Async Engine +### Sanic App と Async Engine -We need to create the app instance and attach the `SanicMayimExtension` with any executors. +アプリインスタンスを作成し、任意の実行者に `SanicMayimExtension` を追加する必要があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -132,32 +132,32 @@ Extend.register( ``` ```` -.. column:: +.. 列:: ``` -### Register Routes +### ルート登録 -Because we are using Mayim's extension for Sanic, we have the automatic `CountryExecutor` injection into the route handler. It makes for an easy, type-annotated development experience. +Sanic用のMayimの拡張機能を使っているので、ルートハンドラに自動的に`CountryExecutor`を注入しています。 これにより、タイプ注釈付きの開発が容易になります。 ``` -.. column:: +.. 列:: ```` ```python @app.get("/") -async def handler(request: Request, executor: CountryExecutor): - countries = await executor.select_all_countries() +async def handler(request, executor: CountryExecutor): + countles = await executor.select_all_countries() return json({"countries": [country.dict() for country in co ``` ```` -.. column:: +.. 列:: ``` -### Send Requests +### リクエストを送信する ``` -.. column:: +.. 列:: ```` ```sh @@ -168,17 +168,17 @@ curl 'http://127.0.0.1:8000' ## SQLAlchemy -Because [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) has added native support for `asyncio`, Sanic can finally work well with SQLAlchemy. Be aware that this functionality is still considered _beta_ by the SQLAlchemy project. +[SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) が `asyncio` のネイティブサポートを追加したため、Sanic は SQLAlchemy でうまく動作します。 この機能はまだ SQLAlchemy プロジェクトで _beta_ とみなされていることに注意してください。 -.. column:: +.. 列:: ``` -### Dependencies +### 依存関係 -First, we need to install the required dependencies. In the past, the dependencies installed were `sqlalchemy` and `pymysql`, but now `sqlalchemy` and `aiomysql` are needed. +まず、必要な依存関係をインストールする必要があります。 以前はインストールされていた依存関係は `sqlalcemy` と `pymysql` でしたが、現在は `sqlalcemy` と `aiomysql` が必要です。 ``` -.. column:: +.. 列:: ```` ```shell @@ -187,7 +187,7 @@ pip install -U aiomysql ``` ```` -.. column:: +.. 列:: ``` ### Define ORM Model @@ -195,7 +195,7 @@ pip install -U aiomysql ORM model creation remains the same. ``` -.. column:: +.. 列:: ```` ```python @@ -226,15 +226,15 @@ class Car(BaseModel): ``` ```` -.. column:: +.. 列:: ``` -### Create Sanic App and Async Engine +### Sanic AppとAsync Engine -Here we use mysql as the database, and you can also choose PostgreSQL/SQLite. Pay attention to changing the driver from `aiomysql` to `asyncpg`/`aiosqlite`. +ここではデータベースとしてmysqlを使用し、PostgreSQL/SQLiteを選択することもできます。 ドライバを`aiomysql`から`asyncpg`/`aiosqlite`に変更することに注意してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -248,7 +248,7 @@ bind = create_async_engine("mysql+aiomysql://root:root@localhost/test", echo=Tru ``` ```` -.. column:: +.. 列:: ``` ### Register Middlewares @@ -258,7 +258,7 @@ The request middleware creates an usable `AsyncSession` object and set it to `re Thread-safe variable `_base_model_session_ctx` helps you to use the session object instead of fetching it from `request.ctx`. ``` -.. column:: +.. 列:: ```` ```python @@ -285,15 +285,15 @@ async def close_session(request, response): ``` ```` -.. column:: +.. 列:: ``` ### Register Routes -According to sqlalchemy official docs, `session.query` will be legacy in 2.0, and the 2.0 way to query an ORM object is using `select`. +によると、 sqlalcemy の公式ドキュメント、 `session. uery`は2.0でレガシーとなり、ORMオブジェクトに問い合わせる2.0の方法は`select`を使用しています。 ``` -.. column:: +.. 列:: ```` ```python @@ -328,37 +328,37 @@ async def get_user(request, pk): ``` ```` -.. column:: +.. 列:: ``` -### Send Requests +### リクエストを送信する ``` -.. column:: +.. 列:: ```` ```sh curl --location --request POST 'http://127.0.0.1:8000/user' {"name":"foo","cars":[{"brand":"Tesla"}]} -``` +```sh ```sh -curl --location --request GET 'http://127.0.0.1:8000/user/1' +curl --location ---request GET 'http://127.0.0.1:8000/user/1' {"name":"foo","cars":[{"brand":"Tesla"}]} ``` ```` ## Tortoise-ORM -.. column:: +.. 列:: ``` -### Dependencies +### 依存関係 -tortoise-orm's dependency is very simple, you just need install tortoise-orm. +tortoise-ormの依存関係はとてもシンプルで、インストールするだけで済みます。 ``` -.. column:: +.. 列:: ```` ```shell @@ -366,15 +366,15 @@ pip install -U tortoise-orm ``` ```` -.. column:: +.. 列:: ``` ### Define ORM Model -If you are familiar with Django, you should find this part very familiar. +Djangoに慣れていれば、この部分はよく知っているはずです。 ``` -.. column:: +.. 列:: ```` ```python @@ -390,15 +390,15 @@ class Users(Model): ``` ```` -.. column:: +.. 列:: ``` ### Create Sanic App and Async Engine -Tortoise-orm provides a set of registration interface, which is convenient for users, and you can use it to create database connection easily. +Tortoise-ormは登録インターフェースのセットを提供しています。 利用者にとって便利で、簡単にデータベース接続を作成することができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -416,13 +416,13 @@ register_tortoise( ``` ```` -.. column:: +.. 列:: ``` -### Register Routes +### ルート登録 ``` -.. column:: +.. 列:: ```` ```python @@ -446,13 +446,13 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列:: ``` -### Send Requests +### リクエストを送信する ``` -.. column:: +.. 列:: ```` ```sh From 6018c18b72bc37b95e43a584aac9f01a3f6ff501 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:41 +0200 Subject: [PATCH 350/698] New translations orm.md (Chinese Simplified) --- guide/content/zh/guide/how-to/orm.md | 204 +++++++++++++-------------- 1 file changed, 102 insertions(+), 102 deletions(-) diff --git a/guide/content/zh/guide/how-to/orm.md b/guide/content/zh/guide/how-to/orm.md index 5f7f188d9a..dcbe64c01a 100644 --- a/guide/content/zh/guide/how-to/orm.md +++ b/guide/content/zh/guide/how-to/orm.md @@ -1,23 +1,23 @@ # ORM -> How do I use SQLAlchemy with Sanic ? +> 如何使用 SQLAlchemy 和 Sanic ？ -All ORM tools can work with Sanic, but non-async ORM tool have a impact on Sanic performance. -There are some orm packages who support +所有ORM工具都可以使用 Sanic 但非异步的 ORM 工具对Sanic 性能产生影响。 +有一些或者软件包支持 -At present, there are many ORMs that support Python's `async`/`await` keywords. Some possible choices include： +目前有许多ORM支持Python的“async`/`await\`”关键字。 一些可能的选项包括： - [Mayim](https://ahopkins.github.io/mayim/) - [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) - [tortoise-orm](https://github.com/tortoise/tortoise-orm) -Integration in to your Sanic application is fairly simple: +您的 Sanic 应用程序的集成相当简单： -## Mayim +## 马伊姆 -Mayim ships with [an extension for Sanic Extensions](https://ahopkins.github.io/mayim/guide/extensions.html#sanic), which makes it super simple to get started with Sanic. It is certainly possible to run Mayim with Sanic without the extension, but it is recommended because it handles all of the [lifecycle events](https://sanic.dev/en/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html). +Mayim船上有[Sanic Extensions的扩展](https://ahopkins.github.io/mayim/guide/extensions.html#sanic)，这使得开始萨尼克变得非常简单。 当然可以在没有扩展的情况下运行Mayim，但是建议它处理所有的[生命周期事件](https://sanic)。 ev/en/guide/basics/listeners.html)和[依赖注入](https://sanic.dev/en/plugins/sanic-ext/injection.html)。 -.. column:: +.. 列: ``` ### Dependencies @@ -25,7 +25,7 @@ Mayim ships with [an extension for Sanic Extensions](https://ahopkins.github.io/ First, we need to install the required dependencies. See [Mayim docs](https://ahopkins.github.io/mayim/guide/install.html#postgres) for the installation needed for your DB driver. ``` -.. column:: +.. 列: ```` ```shell @@ -34,7 +34,7 @@ pip install mayim[postgres] ``` ```` -.. column:: +.. 列: ``` ### Define ORM Model @@ -42,17 +42,17 @@ pip install mayim[postgres] Mayim allows you to use whatever you want for models. Whether it is [dataclasses](https://docs.python.org/3/library/dataclasses.html), [pydantic](https://pydantic-docs.helpmanual.io/), [attrs](https://www.attrs.org/en/stable/), or even just plain `dict` objects. Since it works very nicely [out of the box with Pydantic](https://ahopkins.github.io/mayim/guide/pydantic.html), that is what we will use here. ``` -.. column:: +.. 列: ```` ```python -# ./models.py -from pydantic import BaseModel +# ./models。 y +from pydanticimporting BaseModel class City(BaseModel): id: int name: str - district: str + region: str population: int class Country(BaseModel): @@ -64,15 +64,15 @@ class Country(BaseModel): ``` ```` -.. column:: +.. 列: ``` -### Define SQL +### 定义SQL -If you are unfamiliar, Mayim is different from other ORMs in that it is one-way, SQL-first. This means you define your own queries either inline, or in a separate `.sql` file, which is what we will do here. +如果您不熟悉，也许与其他ORM不同，因为它是单向的，SQL-先的。 这意味着您可以在内部或者在一个单独的`.sql`文件中定义自己的查询，这就是我们将在这里做的。 ``` -.. column:: +.. 列: ```` ```sql @@ -97,7 +97,7 @@ LIMIT $limit OFFSET $offset; ``` ```` -.. column:: +.. 列: ``` ### Create Sanic App and Async Engine @@ -105,59 +105,59 @@ LIMIT $limit OFFSET $offset; We need to create the app instance and attach the `SanicMayimExtension` with any executors. ``` -.. column:: +.. 列: ```` ```python # ./server.py from sanic import Sanic, Request, json -from sanic_ext import Extend -from mayim.executor import PostgresExecutor -from mayim.extensions import SanicMayimExtension -from models import Country +from sanic_ext import Exten +from mayim.expertor import Postgresultor +from mayim. xtenes import SanicMayimextension +from model import Country -class CountryExecutor(PostgresExecutor): +class CountryExecutor(Postgresultor): async def select_all_countries( - self, limit: int = 4, offset: int = 0 - ) -> list[Country]: - ... + self, 限制：int = 4 偏移：int = 0 + ) -> 列表[Country]: + . -app = Sanic("Test") -Extend.register( +app = Sanic("测试") +Extend。 egister( SanicMayimExtension( - executors=[CountryExecutor], - dsn="postgres://...", - ) + expertors=[CountryExecutor], + dsn="postgres://。 .", + ( ) ``` ```` -.. column:: +.. 列: ``` -### Register Routes +### 注册航线 -Because we are using Mayim's extension for Sanic, we have the automatic `CountryExecutor` injection into the route handler. It makes for an easy, type-annotated development experience. +因为我们正在使用 Mayim's 扩展 Sanic, 我们在路由处理器中自动注入了 "CountryExecutor" 。 它使人们能够轻松地获得附加类型说明的发展经验。 ``` -.. column:: +.. 列: ```` ```python @app.get("/") async def handler(request: Request, executor: CountryExecutor): - countries = await executor.select_all_countries() + countries = required executor.select_all_countries() return json({"countries": [country.dict() for country in co ``` ```` -.. column:: +.. 列: ``` -### Send Requests +### 发送请求 ``` -.. column:: +.. 列: ```` ```sh @@ -168,9 +168,9 @@ curl 'http://127.0.0.1:8000' ## SQLAlchemy -Because [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html) has added native support for `asyncio`, Sanic can finally work well with SQLAlchemy. Be aware that this functionality is still considered _beta_ by the SQLAlchemy project. +因为[SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html)添加了本机支持`asyncio`, Sanic最终可以与 SQLAlchemy 进行很好的工作。 请注意，SQLAlchemy项目仍然认为此功能是_测试版_。 -.. column:: +.. 列: ``` ### Dependencies @@ -178,7 +178,7 @@ Because [SQLAlchemy 1.4](https://docs.sqlalchemy.org/en/14/changelog/changelog_1 First, we need to install the required dependencies. In the past, the dependencies installed were `sqlalchemy` and `pymysql`, but now `sqlalchemy` and `aiomysql` are needed. ``` -.. column:: +.. 列: ```` ```shell @@ -187,15 +187,15 @@ pip install -U aiomysql ``` ```` -.. column:: +.. 列: ``` -### Define ORM Model +### 定义ORM Model -ORM model creation remains the same. +ORM model 创建保持不变。 ``` -.. column:: +.. 列: ```` ```python @@ -226,7 +226,7 @@ class Car(BaseModel): ``` ```` -.. column:: +.. 列: ``` ### Create Sanic App and Async Engine @@ -234,7 +234,7 @@ class Car(BaseModel): Here we use mysql as the database, and you can also choose PostgreSQL/SQLite. Pay attention to changing the driver from `aiomysql` to `asyncpg`/`aiosqlite`. ``` -.. column:: +.. 列: ```` ```python @@ -248,7 +248,7 @@ bind = create_async_engine("mysql+aiomysql://root:root@localhost/test", echo=Tru ``` ```` -.. column:: +.. 列: ``` ### Register Middlewares @@ -258,15 +258,15 @@ The request middleware creates an usable `AsyncSession` object and set it to `re Thread-safe variable `_base_model_session_ctx` helps you to use the session object instead of fetching it from `request.ctx`. ``` -.. column:: +.. 列: ```` ```python # ./server.py -from contextvars import ContextVar +from contextVar Import ContextVar from sqlalchemy.ext.asyncio import AsyncSession -from sqlalchemy.orm import sessionmaker +from sqlalchemy rm importing sessionmaker _sessionmaker = sessionmaker(bind, AsyncSession, expire_on_commit=False) @@ -274,18 +274,18 @@ _base_model_session_ctx = ContextVar("session") @app.middleware("request") async def inject_session(request): - request.ctx.session = _sessionmaker() + request. tx.session = _sessionmaker() request.ctx.session_ctx_token = _base_model_session_ctx.set(request.ctx.session) @app.middleware("response") async def close_session(request, response): - if hasattr(request.ctx, "session_ctx_token"): - _base_model_session_ctx.reset(request.ctx.session_ctx_token) - await request.ctx.session.close() + if havasttrac(request). tx, "session_ctx_token"): + _base_model_session_ctx.reset(crequest.ctx.session_ctx_token) + 等待request.ctx.session.close() ``` ```` -.. column:: +.. 列: ``` ### Register Routes @@ -293,54 +293,54 @@ async def close_session(request, response): According to sqlalchemy official docs, `session.query` will be legacy in 2.0, and the 2.0 way to query an ORM object is using `select`. ``` -.. column:: +.. 列: ```` ```python # ./server.py -from sqlalchemy import select +from sqlalchemy import selected from sqlalchemy.orm import selectinload -from sanic.response import json +from sanic. esponse importer json -from models import Car, Person +from models importing Car, Person @app.post("/user") async def create_user(request): - session = request.ctx.session - async with session.begin(): + session = request。 tx.session + 异步与会话。 egin(): car = Car(brand="Tesla") - person = Person(name="foo", cars=[car]) - session.add_all([person]) - return json(person.to_dict()) + person = Person(name="foo", cars=[car]() + 会话。 dd_all([person]) + return json(person). o_dict()) @app.get("/user/") async def get_user(request, pk): - session = request.ctx.session + session = request。 tx.session async with session.begin(): - stmt = select(Person).where(Person.id == pk).options(selectinload(Person.cars)) - result = await session.execute(stmt) - person = result.scalar() + stmt = select(Person).where(Person.id == pk). ptions(selectinload(Person.cars)) + results = 等待会话。 xecute(stmt) + persons = result。 calar() - if not person: + 如果不是个人，则为： return json({}) - return json(person.to_dict()) + return json(person). o_dict()) ``` ```` -.. column:: +.. 列: ``` -### Send Requests +### 发送请求 ``` -.. column:: +.. 列: ```` ```sh curl --location --request POST 'http://127.0.0.1:8000/user' -{"name":"foo","cars":[{"brand":"Tesla"}]} -``` +{"name":"foo","cars":[[{"brand":"Tesla"}]} +`` ```sh curl --location --request GET 'http://127.0.0.1:8000/user/1' @@ -350,31 +350,31 @@ curl --location --request GET 'http://127.0.0.1:8000/user/1' ## Tortoise-ORM -.. column:: +.. 列: ``` -### Dependencies +### 依赖项 -tortoise-orm's dependency is very simple, you just need install tortoise-orm. +tortoise-orm 的依赖关系非常简单，您只需要安装 tortoise-orm 。 ``` -.. column:: +.. 列: ```` ```shell -pip install -U tortoise-orm +pip安装-U tortoise-orm ``` ```` -.. column:: +.. 列: ``` -### Define ORM Model +### 定义ORM Model -If you are familiar with Django, you should find this part very familiar. +如果你熟悉Django，你应该发现这一部分非常熟悉。 ``` -.. column:: +.. 列: ```` ```python @@ -390,15 +390,15 @@ class Users(Model): ``` ```` -.. column:: +.. 列: ``` -### Create Sanic App and Async Engine +### 创建 Sanic App 和 Async 引擎 -Tortoise-orm provides a set of registration interface, which is convenient for users, and you can use it to create database connection easily. +Tortoise-orm 提供了一套注册界面。 这对用户是方便的，您可以使用它来轻松地创建数据库连接。 ``` -.. column:: +.. 列: ```` ```python @@ -416,13 +416,13 @@ register_tortoise( ``` ```` -.. column:: +.. 列: ``` -### Register Routes +### 注册路由 ``` -.. column:: +.. 列: ```` ```python @@ -446,22 +446,22 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列: ``` -### Send Requests +### 发送请求 ``` -.. column:: +.. 列: ```` ```sh curl --location --request POST 'http://127.0.0.1:8000/user' -{"users":["I am foo", "I am bar"]} -``` +{"users":["I are foo", "I are bar"]} +```\ ```sh -curl --location --request GET 'http://127.0.0.1:8000/user/1' -{"user": "I am foo"} +curl --location --request GET 'http://127。 0.0.1:8000/user/1' +{"user": "我是foot"} ``` ```` From 13cc33a37f568b17be0789d30ec18616d30ec272 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:42 +0200 Subject: [PATCH 351/698] New translations serialization.md (Japanese) --- guide/content/ja/guide/how-to/serialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/serialization.md b/guide/content/ja/guide/how-to/serialization.md index 0dfc62d35b..c4d5522a8b 100644 --- a/guide/content/ja/guide/how-to/serialization.md +++ b/guide/content/ja/guide/how-to/serialization.md @@ -1 +1 @@ -# Serialization +# シリアル化 From aad8f597e0c981791f75cdfdd6e4bc1cd83fd111 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:44 +0200 Subject: [PATCH 352/698] New translations serialization.md (Chinese Simplified) --- guide/content/zh/guide/how-to/serialization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/serialization.md b/guide/content/zh/guide/how-to/serialization.md index 0dfc62d35b..b7c18c08cb 100644 --- a/guide/content/zh/guide/how-to/serialization.md +++ b/guide/content/zh/guide/how-to/serialization.md @@ -1 +1 @@ -# Serialization +# 序列化 From 75632576c00017dcc57a29e0ab51309957ce3d2f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:47 +0200 Subject: [PATCH 353/698] New translations static-redirects.md (Japanese) --- guide/content/ja/guide/how-to/static-redirects.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/guide/how-to/static-redirects.md b/guide/content/ja/guide/how-to/static-redirects.md index 0fb99202bf..0ebb0c9ca6 100644 --- a/guide/content/ja/guide/how-to/static-redirects.md +++ b/guide/content/ja/guide/how-to/static-redirects.md @@ -1,6 +1,6 @@ -# "Static" Redirects +# 「静的」リダイレクト -> How do I configure static redirects? +> 静的リダイレクトを設定するには? ## `app.py` @@ -107,6 +107,6 @@ body { *** -Also, checkout some resources from the community: +また、コミュニティからいくつかのリソースをチェックアウトします。 - [Static Routing Example](https://github.com/Perzan/sanic-static-routing-example) From 71c6b39687806964cca4d6dbdd3d0a11135cebb6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:48 +0200 Subject: [PATCH 354/698] New translations static-redirects.md (Chinese Simplified) --- guide/content/zh/guide/how-to/static-redirects.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/zh/guide/how-to/static-redirects.md b/guide/content/zh/guide/how-to/static-redirects.md index 0fb99202bf..ad325344ec 100644 --- a/guide/content/zh/guide/how-to/static-redirects.md +++ b/guide/content/zh/guide/how-to/static-redirects.md @@ -1,6 +1,6 @@ -# "Static" Redirects +# “静态”重定向 -> How do I configure static redirects? +> 如何配置静态重定向？ ## `app.py` @@ -107,6 +107,6 @@ body { *** -Also, checkout some resources from the community: +此外，结算社区的一些资源： -- [Static Routing Example](https://github.com/Perzan/sanic-static-routing-example) +- [静态路由示例](https://github.com/Perzan/sanic-static-routing-example) From e4c9edd58ca2008c578be406001a1a9074906d33 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:49 +0200 Subject: [PATCH 355/698] New translations table-of-contents.md (Japanese) --- .../ja/guide/how-to/table-of-contents.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/guide/content/ja/guide/how-to/table-of-contents.md b/guide/content/ja/guide/how-to/table-of-contents.md index af8da93a77..40573f370a 100644 --- a/guide/content/ja/guide/how-to/table-of-contents.md +++ b/guide/content/ja/guide/how-to/table-of-contents.md @@ -1,17 +1,17 @@ --- -title: Table of Contents +title: 目次 --- -# Table of Contents +# 目次 -We have compiled fully working examples to answer common questions and user cases. For the most part, the examples are as minimal as possible, but should be complete and runnable solutions. +一般的な質問やユーザーケースに答えるための完全な作業例をまとめました。 ほとんどの部分では、例は可能な限り最小限ですが、完全で実行可能なソリューションである必要があります。 -| Page | How do I ... | -| :------------------------------------------ | :------------------------------------------------------------------ | -| [Application mounting](./mounting.md) | ... mount my application at some path above the root? | -| [Authentication](./authentication.md) | ... control authentication and authorization? | -| [Autodiscovery](./autodiscovery.md) | ... autodiscover the components I am using to build my application? | -| [CORS](./cors.md) | ... configure my application for CORS? | -| [ORM](./orm) | ... use an ORM with Sanic? | -| ["Static" Redirects](./static-redirects.md) | ... configure static redirects | -| [TLS/SSL/HTTPS](./tls.md) | ... run Sanic via HTTPS?
... redirect HTTP to HTTPS? | +| ページ | どうすればいいですか... | +| :-------------------------------------------------- | :------------------------------------------------------ | +| format@@0(./mounting.md) | ... アプリケーションをルートの上にあるパスにマウントしますか? | +| [Authentication](./authentication.md) | ... 認証と承認を制御する? | +| [Autodiscovery](./autodiscovery.md) | ... アプリケーションの構築に使用しているコンポーネントを自動的に発見しますか? | +| [CORS](./cors.md) | ... CORS のアプリケーションを設定しますか？ | +| [ORM](./orm) | ... SanicとORMを使用しますか? | +| format@@0(./static-redirects.md) | ... 静的リダイレクトの設定 | +| [TLS/SSL/HTTPS](./tls.md) | ... HTTPS経由でSanicを実行しますか？
... HTTPをHTTPSにリダイレクトしますか? | From ab3dc6e36103a0898771722732f3036f54905b71 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:51 +0200 Subject: [PATCH 356/698] New translations table-of-contents.md (Chinese Simplified) --- .../zh/guide/how-to/table-of-contents.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/guide/content/zh/guide/how-to/table-of-contents.md b/guide/content/zh/guide/how-to/table-of-contents.md index af8da93a77..a3cb53ad9a 100644 --- a/guide/content/zh/guide/how-to/table-of-contents.md +++ b/guide/content/zh/guide/how-to/table-of-contents.md @@ -1,17 +1,17 @@ --- -title: Table of Contents +title: 目录 --- -# Table of Contents +# 目录 -We have compiled fully working examples to answer common questions and user cases. For the most part, the examples are as minimal as possible, but should be complete and runnable solutions. +我们汇编了充分运作的例子，以回答共同的问题和用户案例。 在大多数情况下，这些例子尽可能少一些，但应该是完整和可运作的解决办法。 -| Page | How do I ... | -| :------------------------------------------ | :------------------------------------------------------------------ | -| [Application mounting](./mounting.md) | ... mount my application at some path above the root? | -| [Authentication](./authentication.md) | ... control authentication and authorization? | -| [Autodiscovery](./autodiscovery.md) | ... autodiscover the components I am using to build my application? | -| [CORS](./cors.md) | ... configure my application for CORS? | -| [ORM](./orm) | ... use an ORM with Sanic? | -| ["Static" Redirects](./static-redirects.md) | ... configure static redirects | -| [TLS/SSL/HTTPS](./tls.md) | ... run Sanic via HTTPS?
... redirect HTTP to HTTPS? | +| 页 | 如何做... | +| :-------------------------------- | :------------------------------------------------- | +| [应用程序挂载](./mounting.md) | ... 将我的应用程序挂载到root上方的某个路径？ | +| [Authentication](./认证.md) | ... 控制认证和授权？ | +| [Autodiscovery](./autocovery.md) | ... 自动发现我用来构建应用程序的组件？ | +| [CORS](./cors.md) | ... 配置我的 CORS 应用程序？ | +| [ORM](./orm) | ... 使用 Sanic 的 ORM 吗？ | +| ["静态" 重定向](./static-redirects.md) | ... 配置静态重定向 | +| [TLS/SSL/HTTPS](./tls.md) | ... 通过 HTTPS 运行 Sanic 吗？
... 将 HTTP 重定向到 HTTPS？ | From 1f11d6e2f42f260dc416943b8e4547bfca2b7a3c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:52 +0200 Subject: [PATCH 357/698] New translations task-queue.md (Japanese) --- guide/content/ja/guide/how-to/task-queue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/task-queue.md b/guide/content/ja/guide/how-to/task-queue.md index c5ee7c54a3..6f8d12219f 100644 --- a/guide/content/ja/guide/how-to/task-queue.md +++ b/guide/content/ja/guide/how-to/task-queue.md @@ -1 +1 @@ -task queue +タスクキュー From 4b3f2c9fbd084038a7222527308133ef6661fd8b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:54 +0200 Subject: [PATCH 358/698] New translations task-queue.md (Chinese Simplified) --- guide/content/zh/guide/how-to/task-queue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/task-queue.md b/guide/content/zh/guide/how-to/task-queue.md index c5ee7c54a3..2e59ab8dd9 100644 --- a/guide/content/zh/guide/how-to/task-queue.md +++ b/guide/content/zh/guide/how-to/task-queue.md @@ -1 +1 @@ -task queue +任务队列 From 462bff8ab4677fde8849ffe67c7777cc297b6109 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:55 +0200 Subject: [PATCH 359/698] New translations tls.md (Japanese) --- guide/content/ja/guide/how-to/tls.md | 72 ++++++++++++++-------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/guide/content/ja/guide/how-to/tls.md b/guide/content/ja/guide/how-to/tls.md index 5a4859598a..77aa5c1a5b 100644 --- a/guide/content/ja/guide/how-to/tls.md +++ b/guide/content/ja/guide/how-to/tls.md @@ -4,19 +4,19 @@ title: TLS/SSL/HTTPS # TLS/SSL/HTTPS -> How do I run Sanic via HTTPS? +> HTTPS経由でSanicを実行するにはどうすればよいですか? -If you do not have TLS certificates yet, [see the end of this page](./tls.md#get-certificates-for-your-domain-names). +まだ TLS 証明書を持っていない場合は、format@@0(./tls.md#get-certificates-for-your-domain-names) を参照してください。 -## Single domain and single certificate +## 単一ドメインと単一証明書 -.. column:: +.. 列:: ``` -Let Sanic automatically load your certificate files, which need to be named `fullchain.pem` and `privkey.pem` in the given folder: +Sanicに指定されたフォルダに`fullchain.pem`と`privkey.pem`という名前の証明書ファイルを自動的にロードさせます： ``` -.. column:: +.. 列:: ```` ```sh @@ -28,15 +28,15 @@ app.run("::", 443, ssl="/etc/letsencrypt/live/example.com/") ``` ```` -.. column:: +.. 列:: ``` -Or, you can pass cert and key filenames separately as a dictionary: +または、certとキーファイル名を辞書として個別に渡すこともできます: -Additionally, `password` may be added if the key is encrypted, all fields except for the password are passed to `request.conn_info.cert`. +キーが暗号化されている場合は、パスワードを除くすべてのフィールドが `request` に追加されます。 on_info.cert` ``` -.. column:: +.. 列:: ```` ```python @@ -49,13 +49,13 @@ app.run(host="0.0.0.0", port=8443, ssl=ssl) ``` ```` -.. column:: +.. 列:: ``` -Alternatively, [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html) may be passed, if you need full control over details such as which crypto algorithms are permitted. By default Sanic only allows secure algorithms, which may restrict access from very old devices. +代わりに、[`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html)が渡されます。どの暗号アルゴリズムが許可されているかなど、詳細を完全に制御する必要がある場合。 デフォルトでは、Sanicはセキュアなアルゴリズムのみを許可し、これは非常に古いデバイスからのアクセスを制限する可能性があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -68,17 +68,17 @@ app.run(host="0.0.0.0", port=8443, ssl=context) ``` ```` -## Multiple domains with separate certificates +## 別の証明書を持つ複数のドメイン -.. column:: +.. 列:: ``` -A list of multiple certificates may be provided, in which case Sanic chooses the one matching the hostname the user is connecting to. This occurs so early in the TLS handshake that Sanic has not sent any packets to the client yet. +複数の証明書のリストを提供することができます。その場合、Sanic はユーザーが接続しているホスト名に一致するものを選択します。 これは TLS ハンドシェイクの早い段階で発生し、Sanic はまだクライアントにパケットを送信していない。 -If the client sends no SNI (Server Name Indication), the first certificate on the list will be used even though on the client browser it will likely fail with a TLS error due to name mismatch. To prevent this fallback and to cause immediate disconnection of clients without a known hostname, add `None` as the first entry on the list. `--tls-strict-host` is the equivalent CLI option. +クライアントがSNI(サーバー名表示)を送信していない場合 リストの最初の証明書は、クライアントブラウザ上で名前が一致しないため、TLS エラーで失敗する可能性がありますが使用されます。 このフォールバックを防ぎ、既知のホスト名なしでクライアントの接続を即座に切断するには、リストの最初のエントリとして `None` を追加します。 `--tls-strict-host` はCLIオプションと同等です。 ``` -.. column:: +.. 列:: ```` ```python @@ -96,18 +96,18 @@ sanic myserver:app .. tip:: ``` -You may also use `None` in front of a single certificate if you do not wish to reveal your certificate, true hostname or site content to anyone connecting to the IP address instead of the proper DNS name. +証明書を公開したくない場合は、1つの証明書の前に `None` を使用することもできます。 適切なDNS名ではなく、IPアドレスに接続している人への真のホスト名またはサイトコンテンツ。 ``` -.. column:: +.. 列:: ``` -Dictionaries can be used on the list. This allows also specifying which domains a certificate matches to, although the names present on the certificate itself cannot be controlled from here. If names are not specified, the names from the certificate itself are used. +辞書はリストで使用できます。 これにより、証明書が一致するドメインを指定することができますが、証明書自体に存在する名前は、ここから制御することはできません。 names が指定されていない場合、証明書自体からの名前が使用されます。 -To only allow connections to the main domain **example.com** and only to subdomains of **bigcorp.test**: +メインドメイン **example.com** とサブドメインのみ **bigcorp.test** への接続を許可するには: ``` -.. column:: +.. 列:: ```` ```python @@ -123,17 +123,17 @@ app.run(host="0.0.0.0", port=8443, ssl=ssl) ``` ```` -## Accessing TLS information in handlers via `request.conn_info` fields +## `request.conn_info` フィールドを介してハンドラ内の TLS 情報にアクセスする -- `.ssl` - is the connection secure (bool) -- `.cert` - certificate info and dict fields of the currently active cert (dict) -- `.server_name` - the SNI sent by the client (str, may be empty) +- `.ssl` - 接続セキュア (bool) +- `.cert` - 現在アクティブな証明書の情報とdict フィールド (dict) +- `.server_name` - クライアントによって送信されたSNI（str、空かもしれない） -Do note that all `conn_info` fields are per connection, where there may be many requests over time. If a proxy is used in front of your server, these requests on the same pipe may even come from different users. +すべての `conn_info` フィールドは接続ごとに存在し、時間の経過とともに多くのリクエストがあることに注意してください。 プロキシがサーバの前で使用されている場合、同じパイプでのこれらのリクエストは異なるユーザからのものでもあります。 -## Redirect HTTP to HTTPS, with certificate requests still over HTTP +## HTTPをHTTPSにリダイレクトし、証明書要求は引き続きHTTP経由で行われます -In addition to your normal server(s) running HTTPS, run another server for redirection, `http_redir.py`: +HTTPS が実行されている通常のサーバーに加えて、`http_redir.py`をリダイレクトする別のサーバーを実行します。 ```python from sanic import Sanic, exceptions, response @@ -151,14 +151,14 @@ def redirect_everything_else(request, exception): return response.text("Bad Request. Please use HTTPS!", status=400) ``` -It is best to setup this as a systemd unit separate of your HTTPS servers. You may need to run HTTP while initially requesting your certificates, while you cannot run the HTTPS server yet. Start for IPv4 and IPv6: +HTTPS サーバーとは別の systemd ユニットとしてセットアップするのが最善です。 HTTPSサーバーはまだ実行できませんが、最初に証明書をリクエストする際にHTTPを実行する必要がある場合があります。 IPv4とIPv6の起動: ``` sanic http_redir:app -H 0.0.0.0 -p 80 sanic http_redir:app -H :: -p 80 ``` -Alternatively, it is possible to run the HTTP redirect application from the main application: +または、メインアプリケーションからHTTPリダイレクトアプリケーションを実行することもできます。 ```python # app == Your main application @@ -186,14 +186,14 @@ async def runner(app, app_server): app.state.is_stopping = True ``` -## Get certificates for your domain names +## ドメイン名の証明書を取得する -You can get free certificates from [Let's Encrypt](https://letsencrypt.org/). Install [certbot](https://certbot.eff.org/) via your package manager, and request a certificate: +format@@0(https\://letsencrypt.org/)から無料で証明書を取得できます。 パッケージマネージャーから [certbot](https://certbot.eff.org/) をインストールし、証明書を要求します。 ```sh sudo certbot certonly --key-type ecdsa --preferred-chain "ISRG Root X1" -d example.com -d www.example.com ``` -Multiple domain names may be added by further `-d` arguments, all stored into a single certificate which gets saved to `/etc/letsencrypt/live/example.com/` as per **the first domain** that you list here. +複数のドメイン名は `-d` 引数によって追加されることができます。すべてが `/etc/letsencrypt/live/example` に保存される単一の証明書に格納されます。 ここにリストされている**最初のドメイン**に従って、om/\`。 -The key type and preferred chain options are necessary for getting a minimal size certificate file, essential for making your server run as _fast_ as possible. The chain will still contain one RSA certificate until when Let's Encrypt gets their new EC chain trusted in all major browsers. +キータイプと優先チェーンオプションは、最小サイズの証明書ファイルを取得するために必要です。 サーバーをできるだけ速く動作させるために不可欠です。 このチェーンには、Let's Encryptがすべての主要なブラウザで新しいECチェーンを信頼するまで、1つのRSA証明書が含まれます。 From 71bce305876b34a75769e8985431f1e26fad9927 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:57 +0200 Subject: [PATCH 360/698] New translations tls.md (Chinese Simplified) --- guide/content/zh/guide/how-to/tls.md | 132 +++++++++++++-------------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/guide/content/zh/guide/how-to/tls.md b/guide/content/zh/guide/how-to/tls.md index 5a4859598a..04211e1121 100644 --- a/guide/content/zh/guide/how-to/tls.md +++ b/guide/content/zh/guide/how-to/tls.md @@ -1,61 +1,61 @@ --- -title: TLS/SSL/HTTPS +title: TLS/SL/HTTPS --- -# TLS/SSL/HTTPS +# TLS/SL/HTTPS -> How do I run Sanic via HTTPS? +> 如何通过 HTTPS 运行 Sanic ？ -If you do not have TLS certificates yet, [see the end of this page](./tls.md#get-certificates-for-your-domain-names). +如果您还没有TLS证书，[请查看此页面结尾处](./tls.md#get-certificates-for your domain-names)。 -## Single domain and single certificate +## 单域和单个证书 -.. column:: +.. 列: ``` -Let Sanic automatically load your certificate files, which need to be named `fullchain.pem` and `privkey.pem` in the given folder: +允许 Sanic 自动加载您的证书文件，这些文件需要在给定的文件夹中名为 `fullchain.pem` 和 `privkey.pem` ： ``` -.. column:: +.. 列: ```` ```sh -sudo sanic myserver:app -H :: -p 443 \ - --tls /etc/letsencrypt/live/example.com/ +sudanic myserver:app -H :: -p 443 \ + --tls /etc/letsenccrypt/live/example.com/ ``` ```python -app.run("::", 443, ssl="/etc/letsencrypt/live/example.com/") +app.run(":", 443, ssl="/etc/letsenccrypt/live/example.com/") ``` ```` -.. column:: +.. 列: ``` -Or, you can pass cert and key filenames separately as a dictionary: +或者，您可以作为字典单独传递证书和密钥文件名：此外还有 -Additionally, `password` may be added if the key is encrypted, all fields except for the password are passed to `request.conn_info.cert`. +如果密钥被加密，可以添加`密码`，除密码外，所有字段都会传递到`请求'。 onn_info.cert`. ``` -.. column:: +.. 列: ```` ```python -ssl = { +ssl = Power "cert": "/path/to/fullchain.pem", - "key": "/path/to/privkey.pem", - "password": "for encrypted privkey file", # Optional + "key": "/path/to/privkey". em", + "密码": "用于加密私钥文件", # Optional } app.run(host="0.0.0.0", port=8443, ssl=ssl) ``` ```` -.. column:: +.. 列: ``` -Alternatively, [`ssl.SSLContext`](https://docs.python.org/3/library/ssl.html) may be passed, if you need full control over details such as which crypto algorithms are permitted. By default Sanic only allows secure algorithms, which may restrict access from very old devices. +或者，[`ssl.SSLContext`](https://docs.python.org/3/library/sl.html)可以传递，如果你需要完全控制诸如允许加密算法等细节。 默认情况下，Sanic只允许使用安全算法，这可能限制使用非常旧的设备。 ``` -.. column:: +.. 列: ```` ```python @@ -68,26 +68,26 @@ app.run(host="0.0.0.0", port=8443, ssl=context) ``` ```` -## Multiple domains with separate certificates +## 具有单独证书的多个域 -.. column:: +.. 列: ``` -A list of multiple certificates may be provided, in which case Sanic chooses the one matching the hostname the user is connecting to. This occurs so early in the TLS handshake that Sanic has not sent any packets to the client yet. +可以提供多个证书列表，在这种情况下，Sanic选择与用户连接的主机名匹配的一个。 这发生在TLS 握手中，以致Sanic尚未向客户端发送任何数据包。 -If the client sends no SNI (Server Name Indication), the first certificate on the list will be used even though on the client browser it will likely fail with a TLS error due to name mismatch. To prevent this fallback and to cause immediate disconnection of clients without a known hostname, add `None` as the first entry on the list. `--tls-strict-host` is the equivalent CLI option. +如果客户端没有发送SNI (服务商名称指示), 列表上的第一个证书将被使用，即使在客户端浏览器上它可能会由于名称不匹配而导致TLS错误。 为了防止这种后退并导致客户端在没有已知主机名的情况下立即断开连接，请在列表中添加"无"作为第一项。 `--tls-strict-host` 是对应的 CLI 选项。 ``` -.. column:: +.. 列: ```` ```python ssl = ["certs/example.com/", "certs/bigcorp.test/"] -app.run(host="0.0.0.0", port=8443, ssl=ssl) +app.run(host="0.0.0 ", port=8443, ssl=ssl) ``` ```sh sanic myserver:app - --tls certs/example.com/ + --tls certs/示例。 om/ --tls certs/bigcorp.test/ --tls-strict-host ``` @@ -96,44 +96,44 @@ sanic myserver:app .. tip:: ``` -You may also use `None` in front of a single certificate if you do not wish to reveal your certificate, true hostname or site content to anyone connecting to the IP address instead of the proper DNS name. +如果您不想透露您的证书，您也可以在单一证书前使用 `None` 。 真实主机名或站点内容到连接到IP地址而不是正确的DNS名称。 ``` -.. column:: +.. 列: ``` -Dictionaries can be used on the list. This allows also specifying which domains a certificate matches to, although the names present on the certificate itself cannot be controlled from here. If names are not specified, the names from the certificate itself are used. +字典可以在列表中使用。 这也允许指定证书匹配哪个域，尽管证书本身上的名称不能从这里控制。 如果未指明姓名，则使用证书本身的名称。 -To only allow connections to the main domain **example.com** and only to subdomains of **bigcorp.test**: +只允许连接到主域**example.com** 并且只允许连接到**bigcorp.test**的子域： ``` -.. column:: +.. 列: ```` ```python ssl = [ - None, # No fallback if names do not match! - { - "cert": "certs/example.com/fullchain.pem", - "key": "certs/example.com/privkey.pem", - "names": ["example.com", "*.bigcorp.test"], + None, # 如果名称不匹配，则无回退！ + Power + "cert": "certs/example"。 om/fullchain.pem, + "key": "certs/example"。 om/privkey.pem, + "names": ["example.com", "*.bigcorp. est"], } ] app.run(host="0.0.0.0", port=8443, ssl=ssl) ``` ```` -## Accessing TLS information in handlers via `request.conn_info` fields +## 通过 `request.conn_info` 字段访问处理程序中的 TLS 信息 -- `.ssl` - is the connection secure (bool) -- `.cert` - certificate info and dict fields of the currently active cert (dict) -- `.server_name` - the SNI sent by the client (str, may be empty) +- `.ssl` - 连接安全 (布尔) +- `.cert` - 当前活动证书的 cert 信息和 dict 字段 +- `.server_name` - 客户端发送的SNI (str, 可能为空) -Do note that all `conn_info` fields are per connection, where there may be many requests over time. If a proxy is used in front of your server, these requests on the same pipe may even come from different users. +请注意，所有的`conn_info`字段都是在连接上，在连接中可能会有许多请求。 如果代理人在您的服务器面前使用，那么这些请求可能来自不同的用户。 -## Redirect HTTP to HTTPS, with certificate requests still over HTTP +## 将 HTTP 重定向到 HTTPS，证书请求仍然在 HTTP 上 -In addition to your normal server(s) running HTTPS, run another server for redirection, `http_redir.py`: +除了运行HTTPS的正常服务器之外，运行另一个服务器来重定向，`http_redir.py`： ```python from sanic import Sanic, exceptions, response @@ -151,49 +151,49 @@ def redirect_everything_else(request, exception): return response.text("Bad Request. Please use HTTPS!", status=400) ``` -It is best to setup this as a systemd unit separate of your HTTPS servers. You may need to run HTTP while initially requesting your certificates, while you cannot run the HTTPS server yet. Start for IPv4 and IPv6: +最好是将此设置为一个系统单元，从您的 HTTPS 服务器中分离出来。 您可能需要在最初请求您的证书时运行 HTTP，同时您还不能运行 HTTPS 服务器。 IPv4和IPv6开始： ``` sanic http_redir:app -H 0.0.0.0 -p 80 sanic http_redir:app -H :: -p 80 ``` -Alternatively, it is possible to run the HTTP redirect application from the main application: +或者，可以从主应用程序运行HTTP重定向应用程序： ```python -# app == Your main application -# redirect == Your http_redir application -@app.before_server_start +# 应用 == 您的主要应用程序 +# 重定向 == 您的 http_redir应用程序 +@app。 efor_server_start async def start(app, _): - app.ctx.redirect = await redirect.create_server( + app.ctx.redirect = 等待重定向. reate_server( port=80, return_asyncio_server=True ) - app.add_task(runner(redirect, app.ctx.redirect)) + app.add_task(runner(redirect, app. @app.before_server_stop async def stop(app, _): - await app.ctx.redirect.close() + 等待应用。 tx.redirect.close() async def runner(app, app_server): - app.state.is_running = True - try: - app.signalize() + app.state。 s_runing = True + 尝试： + app。 ignalize() app.finalize() - app.state.is_started = True - await app_server.serve_forever() - finally: - app.state.is_running = False - app.state.is_stopping = True + app tate.is_started = True + 等待app_server。 erve_forumver() + 最后： + app。 tate.is_runction = False + app.state.is_start = True ``` -## Get certificates for your domain names +## 获取域名证书 -You can get free certificates from [Let's Encrypt](https://letsencrypt.org/). Install [certbot](https://certbot.eff.org/) via your package manager, and request a certificate: +您可以从[我们的加密](https://letsencrypt.org/)获得免费证书。 通过您的软件包管理器安装 [certbot](https://certbot.eff.org/) 并请求证书： ```sh -sudo certbot certonly --key-type ecdsa --preferred-chain "ISRG Root X1" -d example.com -d www.example.com +sudo certbot certonly --key-type ecdsa --opeded-chain "ISRG Root X1" -d example.com -d www.example.com ``` -Multiple domain names may be added by further `-d` arguments, all stored into a single certificate which gets saved to `/etc/letsencrypt/live/example.com/` as per **the first domain** that you list here. +多个域名可以通过进一步的 "-d" 参数添加，所有的域名都存储到单个证书中，并保存到 "/etc/letsencrypt/live/example。 按照你在这里列出的首个域\*\* 的 om/\`。 -The key type and preferred chain options are necessary for getting a minimal size certificate file, essential for making your server run as _fast_ as possible. The chain will still contain one RSA certificate until when Let's Encrypt gets their new EC chain trusted in all major browsers. +关键类型和首选链选项是获取最小大小证书文件所必需的， 使您的服务器尽可能以 _快速_ 运行非常重要。 该链仍将包含一个RSA证书，直到让我们加密他们的新的EC 链在所有主要浏览器中得到信任。 From 2a727a2701eb1277567aa950e419793ea93d8981 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:57 +0200 Subject: [PATCH 361/698] New translations validation.md (Japanese) --- guide/content/ja/guide/how-to/validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/validation.md b/guide/content/ja/guide/how-to/validation.md index d45b2dea4c..ab377e8183 100644 --- a/guide/content/ja/guide/how-to/validation.md +++ b/guide/content/ja/guide/how-to/validation.md @@ -1 +1 @@ -validation +検証 From 823b15deb9f1eca725eef7427f2060fc7dea0051 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:20:59 +0200 Subject: [PATCH 362/698] New translations validation.md (Chinese Simplified) --- guide/content/zh/guide/how-to/validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/validation.md b/guide/content/zh/guide/how-to/validation.md index d45b2dea4c..f2d01dad7e 100644 --- a/guide/content/zh/guide/how-to/validation.md +++ b/guide/content/zh/guide/how-to/validation.md @@ -1 +1 @@ -validation +验证 From 8bb1f3e4bd502610e1be567fa4b5c2b1454f35c3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:00 +0200 Subject: [PATCH 363/698] New translations websocket-feed.md (Japanese) --- guide/content/ja/guide/how-to/websocket-feed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/websocket-feed.md b/guide/content/ja/guide/how-to/websocket-feed.md index ae2abc2def..8a6494a96b 100644 --- a/guide/content/ja/guide/how-to/websocket-feed.md +++ b/guide/content/ja/guide/how-to/websocket-feed.md @@ -1 +1 @@ -websocket feed +websocket フィード From a6432697acb56f4b771d23b3022a07cbc46f0fdb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:01 +0200 Subject: [PATCH 364/698] New translations websocket-feed.md (Chinese Simplified) --- guide/content/zh/guide/how-to/websocket-feed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/websocket-feed.md b/guide/content/zh/guide/how-to/websocket-feed.md index ae2abc2def..8995fc0e59 100644 --- a/guide/content/zh/guide/how-to/websocket-feed.md +++ b/guide/content/zh/guide/how-to/websocket-feed.md @@ -1 +1 @@ -websocket feed +websocket 源 From 4575ba9bee3d865e2b015c86e83f45a45fa62225 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:02 +0200 Subject: [PATCH 365/698] New translations introduction.md (Japanese) --- guide/content/ja/guide/introduction.md | 38 +++++++++++++------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/guide/content/ja/guide/introduction.md b/guide/content/ja/guide/introduction.md index 2e0b730f54..1f0282a488 100644 --- a/guide/content/ja/guide/introduction.md +++ b/guide/content/ja/guide/introduction.md @@ -1,9 +1,9 @@ -# Introduction +# はじめに -Sanic is a Python 3.8+ web server and web framework that’s written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy. +Sanic は Python 3.8+ のウェブサーバーであり、高速化のために書かれたウェブフレームワークです。 Python 3.5 で追加された async/await 構文を使用することができます。これにより、コードをノンブロッキングでスピーディーにすることができます。 .. attrs:: -:class: introduction-table +:class: 紹介テーブル ``` | | | @@ -15,21 +15,21 @@ Sanic is a Python 3.8+ web server and web framework that’s written to go fast. | Stats | [![Monthly Downloads](https://img.shields.io/pypi/dm/sanic.svg)](https://pepy.tech/project/sanic) [![Weekly Downloads](https://img.shields.io/pypi/dw/sanic.svg)](https://pepy.tech/project/sanic) [![Conda downloads](https://img.shields.io/conda/dn/conda-forge/sanic.svg)](https://anaconda.org/conda-forge/sanic) | ``` -## What is it? +## それは何ですか? -First things first, before you jump in the water, you should know that Sanic is different than other frameworks. +まず最初に、水に飛び込む前に、Sanicは他のフレームワークとは異なることを知っておくべきです。 -Right there in that first sentence there is a huge mistake because Sanic is _both_ a **framework** and a **web server**. In the deployment section we will talk a little bit more about this. +最初の文には大きな間違いがあります。なぜなら、Sanic は **framework** と **web server** の両方であるからです。 展開セクションでは、これについてもう少し詳しく説明します。 -But, remember, out of the box Sanic comes with everything you need to write, deploy, and scale a production grade web application. 🚀 +しかし、Sanicには、プロダクショングレードのWebアプリケーションを作成、デプロイ、およびスケーリングするために必要なものがすべて揃っています。 🚀 -## Goal +## 目標 -> To provide a simple way to get up and running a highly performant HTTP server that is easy to build, to expand, and ultimately to scale. +> 構築しやすい高性能な HTTP サーバーを立ち上げて実行する簡単な方法を提供します。 拡大し最終的には拡大しました -## Features +## 特徴 -.. column:: +.. 列:: ``` ### Core @@ -42,7 +42,7 @@ But, remember, out of the box Sanic comes with everything you need to write, dep - By the community, for the community ``` -.. column:: +.. 列:: ``` ### Sanic Extensions [[learn more](../plugins/sanic-ext/getting-started.md)] @@ -56,16 +56,16 @@ But, remember, out of the box Sanic comes with everything you need to write, dep - Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints ``` -## Sponsor +## スポンサー情報 -Check out [open collective](https://opencollective.com/sanic-org) to learn more about helping to fund Sanic. +format@@0(https\://opencollective.com/sanic-org) をご覧ください。 -## Join the Community +## コミュニティに参加する -The main channel for discussion is at the [community forums](https://community.sanicframework.org/). There also is a [Discord Server](https://discord.gg/FARQzAEMAA) for live discussion and chat. +ディスカッションの主なチャンネルは、format@@0(https\://community.sanicframework.org/)にあります。 ライブディスカッションやチャットのための[Discord Server](https://discord.gg/FARQzAEMAA)もあります。 -The Stackoverflow `[sanic]` tag is [actively monitored](https://stackoverflow.com/questions/tagged/sanic) by project maintainers. +Stackoverflow `[sanic]` タグはプロジェクトメンテナーによってformat@@1(https\://stackoverflow\.com/questions/tagged/sanic)です。 -## Contribution +## 貢献 -We are always happy to have new contributions. We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). Please take a look at our [Contribution guidelines](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst). +私たちは常に新しい貢献をしています。 We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). format@@0(https\://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst)をご覧ください。 From 9760d3f599ccb2611e0aa3def0993e07748f6338 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:04 +0200 Subject: [PATCH 366/698] New translations introduction.md (Chinese Simplified) --- guide/content/zh/guide/introduction.md | 36 +++++++++++++------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/guide/content/zh/guide/introduction.md b/guide/content/zh/guide/introduction.md index 2e0b730f54..74ef2300af 100644 --- a/guide/content/zh/guide/introduction.md +++ b/guide/content/zh/guide/introduction.md @@ -1,6 +1,6 @@ -# Introduction +# 一. 导言 -Sanic is a Python 3.8+ web server and web framework that’s written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy. +Sanic 是 Python 的 3.8+ 网页服务器和网页框架，它写得更快。 它允许使用 Python 3.5中添加的异步/等待语法，这使您的代码不受阻挡和快速。 .. attrs:: :class: introduction-table @@ -15,21 +15,21 @@ Sanic is a Python 3.8+ web server and web framework that’s written to go fast. | Stats | [![Monthly Downloads](https://img.shields.io/pypi/dm/sanic.svg)](https://pepy.tech/project/sanic) [![Weekly Downloads](https://img.shields.io/pypi/dw/sanic.svg)](https://pepy.tech/project/sanic) [![Conda downloads](https://img.shields.io/conda/dn/conda-forge/sanic.svg)](https://anaconda.org/conda-forge/sanic) | ``` -## What is it? +## 什么是？ -First things first, before you jump in the water, you should know that Sanic is different than other frameworks. +首先，在你跳进水面之前，你应该知道Sanic与其他框架不同。 -Right there in that first sentence there is a huge mistake because Sanic is _both_ a **framework** and a **web server**. In the deployment section we will talk a little bit more about this. +就在第一句中，因为Sanic 是 _both_a **framework** 和 **web server** 。 我们将在部署部分更多地谈论这个问题。 -But, remember, out of the box Sanic comes with everything you need to write, deploy, and scale a production grade web application. 🚀 +但请记住，Sanic 从盒子中带有你需要写、部署和缩放生产级网页应用程序的一切。 🚀 -## Goal +## 目标 -> To provide a simple way to get up and running a highly performant HTTP server that is easy to build, to expand, and ultimately to scale. +> 提供一个简单的方式来启动和运行一个易于构建的高性能的 HTTP 服务器， 扩大并最终扩大规模。 -## Features +## 功能 -.. column:: +.. 列: ``` ### Core @@ -42,7 +42,7 @@ But, remember, out of the box Sanic comes with everything you need to write, dep - By the community, for the community ``` -.. column:: +.. 列: ``` ### Sanic Extensions [[learn more](../plugins/sanic-ext/getting-started.md)] @@ -56,16 +56,16 @@ But, remember, out of the box Sanic comes with everything you need to write, dep - Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints ``` -## Sponsor +## 赞助商 -Check out [open collective](https://opencollective.com/sanic-org) to learn more about helping to fund Sanic. +查看[打开集体](https://opencollective.com/sanic-org)来了解更多关于帮助融资Sanic的信息。 -## Join the Community +## 加入社区 -The main channel for discussion is at the [community forums](https://community.sanicframework.org/). There also is a [Discord Server](https://discord.gg/FARQzAEMAA) for live discussion and chat. +讨论的主要渠道是[社区论坛](https://community.sanicframework.org/)。 还有一个 [Discord 服务器](https://discord.gg/RARQzAEMAA) 进行现场讨论和聊天。 -The Stackoverflow `[sanic]` tag is [actively monitored](https://stackoverflow.com/questions/tagged/sanic) by project maintainers. +Stackoverflow \`[sanic]' 标签由项目维护者[积极监视](https://stackoverflow.com/questions/tagged/sanic)。 -## Contribution +## 贡献 -We are always happy to have new contributions. We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). Please take a look at our [Contribution guidelines](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst). +我们总是乐于得到新的捐助。 我们有[标记的问题对任何想要开始的人来说都是好的](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner)，欢迎[questions/answers/discussion on on the forums](https://community.sanicframework.org/)。 请查看我们的[贡献指南](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst)。 From 8d89c9097e1ac3712f3efb2718e152cbefc84980 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:05 +0200 Subject: [PATCH 367/698] New translations app-loader.md (Japanese) --- guide/content/ja/guide/running/app-loader.md | 30 ++++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/ja/guide/running/app-loader.md b/guide/content/ja/guide/running/app-loader.md index 03f13e7ec7..ab5e0578fa 100644 --- a/guide/content/ja/guide/running/app-loader.md +++ b/guide/content/ja/guide/running/app-loader.md @@ -1,18 +1,18 @@ --- -title: Dynamic Applications +title: 動的アプリケーション --- -# Dynamic Applications +# 動的アプリケーション -Running Sanic has been optimized to work with the CLI. If you have not read it yet, you should read [Running Sanic](./running.md#sanic-server) to become familiar with the options. +SanicはCLIで動作するように最適化されています。 まだ読んでいない場合は、format@@0(./running.md#sanic-server)を読んで、オプションに慣れるようにしてください。 -.. column:: +.. 列:: ``` -This includes running it as a global scope object... +これにはグローバルスコープオブジェクトとして実行することが含まれます... ``` -.. column:: +.. 列:: ```` ```sh @@ -28,13 +28,13 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列:: ``` -...or, a factory function that creates the `Sanic` application object. +...または、`Sanic`アプリケーションオブジェクトを作成するファクトリ関数。 ``` -.. column:: +.. 列:: ```` ```sh @@ -53,17 +53,17 @@ def create_app(): ``` ```` -**Sometimes, this is not enough ... 🤔** +**時々、これは十分ではありません... 🤔** -Introduced in [v22.9](../release-notes/v22.9.md), Sanic has an `AppLoader` object that is responsible for creating an application in the various [worker processes](./manager.md#how-sanic-server-starts-processes). You can take advantage of this if you need to create a more dynamic startup experience for your application. +[v22.9](../release-notes/v22.9.md) で導入されたSanicは、さまざまな[worker processes](./manager.md#how-sanic-server-starts-processes)でアプリケーションを作成する `AppLoader` オブジェクトを持っています。 アプリケーションでより動的なスタートアップ体験を作成する必要がある場合は、これを利用できます。 -.. column:: +.. 列:: ``` -An `AppLoader` can be passed a callable that returns a `Sanic` instance. That `AppLoader` could be used with the low-level application running API. +`AppLoader`は、`Sanic`インスタンスを返す呼び出し可能なものを渡すことができます。その`AppLoader`は、APIを実行する低レベルのアプリケーションで使用できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -95,4 +95,4 @@ python path/to/server.py MyTestAppName ``` ```` -In the above example, the `AppLoader` is created with a `factory` that can be used to create copies of the same application across processes. When doing this, you should explicitly use the `Sanic.serve` pattern shown above so that the `AppLoader` that you create is not replaced. +上記の例では、 `AppLoader` は `factory` で作成され、プロセス間で同じアプリケーションのコピーを作成できます。 これを行う場合は、上記の`Sanic.serve`パターンを使用して、作成した`AppLoader`が置き換えられないようにしてください。 From 2698700854a89f07b42aecbd86c31b062d486b70 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:07 +0200 Subject: [PATCH 368/698] New translations app-loader.md (Chinese Simplified) --- guide/content/zh/guide/running/app-loader.md | 30 ++++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/zh/guide/running/app-loader.md b/guide/content/zh/guide/running/app-loader.md index 03f13e7ec7..11eb6ecdec 100644 --- a/guide/content/zh/guide/running/app-loader.md +++ b/guide/content/zh/guide/running/app-loader.md @@ -1,18 +1,18 @@ --- -title: Dynamic Applications +title: 动态应用程序 --- -# Dynamic Applications +# 动态应用程序 -Running Sanic has been optimized to work with the CLI. If you have not read it yet, you should read [Running Sanic](./running.md#sanic-server) to become familiar with the options. +正在运行的Sanic已被优化，以配合CLI。 如果你还没有阅读它，你应该阅读 [Running Sanic](./running.md#sanic-server) 来熟悉这些选项。 -.. column:: +.. 列: ``` -This includes running it as a global scope object... +这包括将其作为全局范围对象运行... ``` -.. column:: +.. 列: ```` ```sh @@ -28,13 +28,13 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列: ``` -...or, a factory function that creates the `Sanic` application object. +...或者创建一个 `Sanic` 应用程序对象的工厂函数。 ``` -.. column:: +.. 列: ```` ```sh @@ -53,17 +53,17 @@ def create_app(): ``` ```` -**Sometimes, this is not enough ... 🤔** +**有时候，这还不够... 🤔** -Introduced in [v22.9](../release-notes/v22.9.md), Sanic has an `AppLoader` object that is responsible for creating an application in the various [worker processes](./manager.md#how-sanic-server-starts-processes). You can take advantage of this if you need to create a more dynamic startup experience for your application. +引入于 [v22.9](../release-notes/v22.9.md)，萨尼克有一个`AppLoader` 对象，负责在各种[工人进程](./manager.md#how-sanic-server-starts-process)中创建一个应用程序。 如果你需要为你的应用程序创建一个更动态的启动体验，你可以利用这个机会。 -.. column:: +.. 列: ``` -An `AppLoader` can be passed a callable that returns a `Sanic` instance. That `AppLoader` could be used with the low-level application running API. +一个 `AppLoader` 可以传递一个传唤函数返回一个 `Sanic` 实例。这个`AppLoader` 可以与运行 API 的低级别应用程序一起使用。 ``` -.. column:: +.. 列: ```` ```python @@ -95,4 +95,4 @@ python path/to/server.py MyTestAppName ``` ```` -In the above example, the `AppLoader` is created with a `factory` that can be used to create copies of the same application across processes. When doing this, you should explicitly use the `Sanic.serve` pattern shown above so that the `AppLoader` that you create is not replaced. +在上面的例子中，`AppLoader` 是用`factory`创建的，它可以用来在整个过程中创建同一应用程序的副本。 在这样做时，您应该明确使用上面显示的 `Sanic.serve` 模式，以便您创建的 `AppLoader` 不会被替换。 From f129c16ef6fa79dd42961096fafd7f855185e0c7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:08 +0200 Subject: [PATCH 369/698] New translations configuration.md (Japanese) --- .../content/ja/guide/running/configuration.md | 230 +++++++++--------- 1 file changed, 115 insertions(+), 115 deletions(-) diff --git a/guide/content/ja/guide/running/configuration.md b/guide/content/ja/guide/running/configuration.md index 89dacd7f7a..6258f2361b 100644 --- a/guide/content/ja/guide/running/configuration.md +++ b/guide/content/ja/guide/running/configuration.md @@ -1,14 +1,14 @@ -# Configuration +# 設定 -## Basics +## 基本 -.. column:: +.. 列:: ``` -Sanic holds the configuration in the config attribute of the application object. The configuration object is merely an object that can be modified either using dot-notation or like a dictionary. +Sanic はアプリケーションオブジェクトの config 属性に設定を保持します。 構成オブジェクトは、ドット表記または辞書のように変更できるオブジェクトにすぎません。 ``` -.. column:: +.. 列:: ```` ```python @@ -18,13 +18,13 @@ app.config["DB_USER"] = "appuser" ``` ```` -.. column:: +.. 列:: ``` -You can also use the `update()` method like on regular dictionaries. +`update()`メソッドは、通常の辞書と同様に使用することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -40,20 +40,20 @@ app.config.update(db_settings) .. note:: ``` -It is standard practice in Sanic to name your config values in **uppercase letters**. Indeed, you may experience weird behaviors if you start mixing uppercase and lowercase names. +Sanicでは標準的な方法で、設定値を**大文字**で指定します。 確かに、大文字と小文字の名前を混ぜ始めると、奇妙な動作が発生することがあります。 ``` -## Loading +## 読み込み中 -### Environment variables +### 環境変数 -.. column:: +.. 列:: ``` -Any environment variables defined with the `SANIC_` prefix will be applied to the Sanic config. For example, setting `SANIC_REQUEST_TIMEOUT` will be loaded by the application automatically and fed into the `REQUEST_TIMEOUT` config variable. +SANIC_`プレフィックスで定義された環境変数は、Sanicの設定に適用されます。 例えば、`SANIC_REQUEST_TIMEOUT` を設定すると、アプリケーションが自動的にロードされ、 `REQUEST_TIMEOUT` 設定変数に与えられます。 ``` -.. column:: +.. 列:: ```` ```bash @@ -65,13 +65,13 @@ $ export SANIC_REQUEST_TIMEOUT=10 ``` ```` -.. column:: +.. 列:: ``` -You can change the prefix that Sanic is expecting at startup. +Sanicが起動時に期待しているプレフィックスを変更できます。 ``` -.. column:: +.. 列:: ```` ```bash @@ -84,13 +84,13 @@ $ export MYAPP_REQUEST_TIMEOUT=10 ``` ```` -.. column:: +.. 列:: ``` -You can also disable environment variable loading completely. +環境変数の読み込みを完全に無効にすることもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -98,19 +98,19 @@ app = Sanic(__name__, load_env=False) ``` ```` -### Using Sanic.update_config +### Sanic.update_config の使用 -The `Sanic` instance has a _very_ versatile method for loading config: `app.update_config`. You can feed it a path to a file, a dictionary, a class, or just about any other sort of object. +`Sanic`インスタンスは、config: `app.update_config`をロードするための_very_汎用的なメソッドを持っています。 ファイル、辞書、クラス、またはその他のあらゆる種類のオブジェクトにパスを与えることができます。 -#### From a file +#### ファイルから -.. column:: +.. 列:: ``` -Let's say you have `my_config.py` file that looks like this. +たとえば、次のような `my_config.py` ファイルがあるとします。 ``` -.. column:: +.. 列:: ```` ```python @@ -120,13 +120,13 @@ B = 2 ``` ```` -.. column:: +.. 列:: ``` -You can load this as config values by passing its path to `app.update_config`. +`app.update_config`にパスを渡すことで、これを設定値としてロードできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -136,13 +136,13 @@ You can load this as config values by passing its path to `app.update_config`. ``` ```` -.. column:: +.. 列:: ``` -This path also accepts bash style environment variables. +このパスは、bash スタイルの環境変数も受け付けます。 ``` -.. column:: +.. 列:: ```` ```bash @@ -156,18 +156,18 @@ app.update_config("${my_path}/my_config.py") .. note:: ``` -Just remember that you have to provide environment variables in the format `${environment_variable}` and that `$environment_variable` is not expanded (is treated as "plain" text). +ただ、`${environment_variable}`形式で環境変数を指定する必要があり、`$environment_variable`は展開されていないことを覚えておいてください（「プレーン」テキストとして扱われます）。 ``` -#### From a dict +#### 辞書から -.. column:: +.. 列:: ``` -The `app.update_config` method also works on plain dictionaries. +`app.update_config` メソッドはプレーン辞書でも動作します。 ``` -.. column:: +.. 列:: ```` ```python @@ -175,15 +175,15 @@ app.update_config({"A": 1, "B": 2}) ``` ```` -#### From a class or object +#### クラスまたはオブジェクトから -.. column:: +.. 列:: ``` -You can define your own config class, and pass it to `app.update_config` +独自の設定クラスを定義し、`app.update_config`に渡すことができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -195,13 +195,13 @@ app.update_config(MyConfig) ``` ```` -.. column:: +.. 列:: ``` -It even could be instantiated. +インスタンス化することもできます ``` -.. column:: +.. 列:: ```` ```python @@ -209,30 +209,30 @@ app.update_config(MyConfig()) ``` ```` -### Type casting +### 鋳造タイプ -When loading from environment variables, Sanic will attempt to cast the values to expected Python types. This particularly applies to: +環境変数から読み込むとき、Sanicは期待されるPython型に値をキャストしようとします。 これは特に以下に該当します： - `int` - `float` - `bool` -In regards to `bool`, the following _case insensitive_ values are allowed: +`bool`に関しては、以下の_大文字小文字を区別しません。 -- **`True`**: `y`, `yes`, `yep`, `yup`, `t`, `true`, `on`, `enable`, `enabled`, `1` -- **`False`**: `n`, `no`, `f`, `false`, `off`, `disable`, `disabled`, `0` +- **`True`**: `y`, `yes`, `yep`, `yep`, `yup`, `true`, `on`, `enable`, `enabled`, `1` +- **`False`**: `n`, `no`, `f`, `false`, `off`, `disabled`, `0` -If a value cannot be cast, it will default to a `str`. +値をキャストできない場合、デフォルトは `str` になります。 -.. column:: +.. 列:: ``` -Additionally, Sanic can be configured to cast additional types using additional type converters. This should be any callable that returns the value or raises a `ValueError`. +さらに、Sanicは追加の型コンバータを使用して追加の型をキャストするように設定できます。 値を返したり、`ValueError` を発生させたりする任意の呼び出し可能である必要があります。 -*Added in v21.12* +*v21.12* に追加されました ``` -.. column:: +.. 列:: ```` ```python @@ -240,42 +240,42 @@ app = Sanic(..., config=Config(converters=[UUID])) ``` ```` -## Builtin values - -| **Variable** | **Default** | **Description** | -| -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| ACCESS_LOG | True | Disable or enable access log | -| AUTO_EXTEND | True | Control whether [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) will load if it is in the existing virtual environment | -| AUTO_RELOAD | True | Control whether the application will automatically reload when a file changes | -| EVENT_AUTOREGISTER | True | When `True` using the `app.event()` method on a non-existing signal will automatically create it and not raise an exception | -| FALLBACK_ERROR_FORMAT | html | Format of error response if an exception is not caught and handled | -| FORWARDED_FOR_HEADER | X-Forwarded-For | The name of "X-Forwarded-For" HTTP header that contains client and proxy ip | -| FORWARDED_SECRET | None | Used to securely identify a specific proxy server (see below) | -| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | How long to wait to force close non-idle connection (sec) | -| INSPECTOR | False | Whether to enable the Inspector | -| INSPECTOR_HOST | localhost | The host for the Inspector | -| INSPECTOR_PORT | 6457 | The port for the Inspector | -| INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | -| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | -| INSPECTOR_API_KEY | - | The API key for the Inspector | -| KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | -| KEEP_ALIVE | True | Disables keep-alive when False | -| MOTD | True | Whether to display the MOTD (message of the day) at startup | -| MOTD_DISPLAY | {} | Key/value pairs to display additional, arbitrary data in the MOTD | -| NOISY_EXCEPTIONS | False | Force all `quiet` exceptions to be logged | -| PROXIES_COUNT | None | The number of proxy servers in front of the app (e.g. nginx; see below) | -| REAL_IP_HEADER | None | The name of "X-Real-IP" HTTP header that contains real client ip | -| REGISTER | True | Whether the app registry should be enabled | -| REQUEST_BUFFER_SIZE | 65536 | Request buffer size before request is paused, default is 64 Kib | -| REQUEST_ID_HEADER | X-Request-ID | The name of "X-Request-ID" HTTP header that contains request/correlation ID | -| REQUEST_MAX_SIZE | 100000000 | How big a request may be (bytes), default is 100 megabytes | -| REQUEST_MAX_HEADER_SIZE | 8192 | How big a request header may be (bytes), default is 8192 bytes | -| REQUEST_TIMEOUT | 60 | How long a request can take to arrive (sec) | -| RESPONSE_TIMEOUT | 60 | How long a response can take to process (sec) | -| USE_UVLOOP | True | Whether to override the loop policy to use `uvloop`. Supported only with `app.run`. | -| WEBSOCKET_MAX_SIZE | 2^20 | Maximum size for incoming messages (bytes) | -| WEBSOCKET_PING_INTERVAL | 20 | A Ping frame is sent every ping_interval seconds. | -| WEBSOCKET_PING_TIMEOUT | 20 | Connection is closed when Pong is not received after ping_timeout seconds | +## 組み込み値 + +| **変数** | **デフォルト** | **説明** | +| ------------------------------------------------------------ | --------------- | -------------------------------------------------------------------------------------------- | +| ACCESS_LOG | True | アクセスログを無効または有効にする | +| 拡張されました。 | True | [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) が既存の仮想環境にある場合にロードされるかどうかを制御する | +| AUTO_RELOAD | True | ファイルが変更されたときにアプリケーションが自動的にリロードされるかどうかを制御します | +| number@@0 自動登録 | True | 存在しない信号で `app.event()` メソッドを使用して `True` を使用すると自動的に作成され、例外は発生しません。 | +| FORMAT | html | 例外がキャッチされて処理されていない場合のエラー応答のフォーマット | +| 前に進みました。 | X-Forwarded-For | クライアントとプロキシIPを含むHTTPヘッダー「X-Forwarded-For」の名前 | +| FORWARDED_SECRET | なし | 特定のプロキシ サーバーを安全に識別するために使用します (下記参照) | +| タイムアウト | 15.0 | アイドル状態でない接続を強制終了するまで待機する時間 (秒) | +| 検査 | False | インスペクタを有効にするかどうか | +| INSPECTOR_HOST | localhost | インスペクタのホスト | +| インポートします。 | 6457 | インスペクターのポート | +| キー | - | インスペクタの TLS キー | +| INSPECTOR_TLS_CERT | * | インスペクタの TLS 証明書 | +| INSPECTOR_API_KEY | - | インスペクタの API キー | +| ALIVE_TIMEOUT | 120 | TCPコネクションを保持する期間 (秒) | +| 保持します。 | True | Falseのときは生き残りを無効にします | +| MOTD | True | 起動時にMOTD (メッセージ) を表示するかどうか | +| MOTD_表示 | {} | MOTD に追加の任意のデータを表示するキー/値のペア | +| NOISY_EXCEPTIONS | False | すべての `quiet` 例外をログに記録する | +| PROXIES_COUNT | なし | アプリの前にあるプロキシサーバーの数（例：nginx、下記参照） | +| REAL_IP_HEADER | なし | 実際のクライアントIPを含むHTTPヘッダーの名前 | +| 登録 | True | アプリレジストリを有効にするかどうか | +| リクエストのBUFF_サイズ | 65536 | リクエストを一時停止する前のリクエストバッファサイズ。デフォルトは64KBです。 | +| リクエストID | X-リクエストID | リクエスト/相関IDを含む "X-Request-ID" HTTP ヘッダーの名前 | +| 最大サイズ | 100000000 | リクエストの大きさ（バイト）は100メガバイトです | +| 要求される最大ヘッダのサイズ | 8192 | リクエストヘッダがどれくらい大きいか(バイト)、デフォルトは8192バイト | +| 要求時間 | 60 | リクエスト到着までにかかる時間 (秒) | +| タイムアウト | 60 | 応答の処理にかかる時間 (秒) | +| UVLoopを使用します。 | True | `uvloop` を使用するループポリシーをオーバーライドします。 `app.run`でのみサポートされています。 | +| 最大サイズ | 2^20 | 受信メッセージの最大サイズ (バイト) | +| Ping_INTERVAL | 20 | Pingフレームは、ping_interval 秒ごとに送信されます。 | +| ping_timeout | 20 | ping_timeout 秒後に Pong が受信されなかった場合、接続は切断されます | .. tip:: FYI @@ -287,42 +287,42 @@ app = Sanic(..., config=Config(converters=[UUID])) - v22.12 added: `INSPECTOR_HOST`, `INSPECTOR_PORT`, `INSPECTOR_TLS_KEY`, `INSPECTOR_TLS_CERT`, `INSPECTOR_API_KEY` ``` -## Timeouts +## タイムアウト -### REQUEST_TIMEOUT +### 要求時間 -A request timeout measures the duration of time between the instant when a new open TCP connection is passed to the -Sanic backend server, and the instant when the whole HTTP request is received. If the time taken exceeds the +リクエストタイムアウトは、新しいオープンTCP接続が +Sanicバックエンドサーバに渡された瞬間の時間を測定します。 そして全体の HTTP リクエストが受信された瞬間です。 If the time taken exceeds the `REQUEST_TIMEOUT` value (in seconds), this is considered a Client Error so Sanic generates an `HTTP 408` response -and sends that to the client. Set this parameter's value higher if your clients routinely pass very large request payloads -or upload requests very slowly. +and sends that to the client. クライアントが非常に大きなリクエストペイロード +を日常的に渡したり、リクエストを非常にゆっくりアップロードした場合、このパラメータの値を高く設定します。 -### RESPONSE_TIMEOUT +### タイムアウト -A response timeout measures the duration of time between the instant the Sanic server passes the HTTP request to the Sanic App, and the instant a HTTP response is sent to the client. If the time taken exceeds the `RESPONSE_TIMEOUT` value (in seconds), this is considered a Server Error so Sanic generates an `HTTP 503` response and sends that to the client. Set this parameter's value higher if your application is likely to have long-running process that delay the -generation of a response. +応答タイムアウトは、Sanic サーバーが HTTP リクエストを Sanic App に渡す瞬間の時間を測定します。 クライアントにHTTPレスポンスが送信されます。 経過時間が `RESPONSE_TIMEOUT` 値を超えた場合 (秒数) これはサーバーエラーと見なされるため、Sanic は `HTTP 503` レスポンスを生成してクライアントに送信します。 アプリケーションが、応答の +生成を遅らせる長時間のプロセスを持つ可能性がある場合、このパラメータの値を大きく設定します。 -### KEEP_ALIVE_TIMEOUT +### ALIVE_TIMEOUT -#### What is Keep Alive? And what does the Keep Alive Timeout value do? +#### Keep Aliveとは何ですか? そして、Keep Alive Timeoutの価値は何ですか? -`Keep-Alive` is a HTTP feature introduced in `HTTP 1.1`. When sending a HTTP request, the client (usually a web browser application) can set a `Keep-Alive` header to indicate the http server (Sanic) to not close the TCP connection after it has send the response. This allows the client to reuse the existing TCP connection to send subsequent HTTP requests, and ensures more efficient network traffic for both the client and the server. +`Keep-Alive`は、`HTTP 1.1`で導入されたHTTP機能です。 HTTP リクエストを送信するとき クライアント(通常はウェブブラウザアプリケーション)は、レスポンスを送信した後にTCPコネクションを閉じないように、httpサーバー(SANC)を示す「Keep-Alive」ヘッダを設定できます。 これにより、クライアントは既存の TCP コネクションを再利用して、後続の HTTP リクエストを送信することができます。 クライアントとサーバーの両方で、より効率的なネットワークトラフィックを確保します。 -The `KEEP_ALIVE` config variable is set to `True` in Sanic by default. If you don't need this feature in your application, set it to `False` to cause all client connections to close immediately after a response is sent, regardless of the `Keep-Alive` header on the request. +デフォルトでは、`KEEP_ALIVE`設定変数は、Sanicでは`True`に設定されています。 アプリケーションでこの機能を必要としない場合 応答が送信された直後にすべてのクライアント接続が閉じられるようにするには、 `False` に設定します。 リクエストの `Keep-Alive` ヘッダーに関係なく。 -The amount of time the server holds the TCP connection open is decided by the server itself. In Sanic, that value is configured using the `KEEP_ALIVE_TIMEOUT` value. By default, **it is set to 120 seconds**. This means that if the client sends a `Keep-Alive` header, the server will hold the TCP connection open for 120 seconds after sending the response, and the client can reuse the connection to send another HTTP request within that time. +サーバーがTCP接続を開いている時間は、サーバー自身によって決まります。 Sanic では、その値は `KEEP_ALIVE_TIMEOUT` 値を使用して設定されます。 デフォルトでは、**120秒**に設定されています。 これは、クライアントが `Keep-Alive` ヘッダーを送信した場合、サーバーは応答を送信した後 120 秒間、TCP コネクションを保持します。 クライアントはその時間内に別の HTTP リクエストを送信するために接続を再利用できます。 -For reference: +参考: -- Apache httpd server default keepalive timeout = 5 seconds -- Nginx server default keepalive timeout = 75 seconds -- Nginx performance tuning guidelines uses keepalive = 15 seconds -- Caddy server default keepalive timeout = 120 seconds -- IE (5-9) client hard keepalive limit = 60 seconds -- Firefox client hard keepalive limit = 115 seconds -- Opera 11 client hard keepalive limit = 120 seconds -- Chrome 13+ client keepalive limit > 300+ seconds +- Apache サーバのデフォルトの keepalving timeout = 5 秒 +- Nginx サーバーのデフォルトの keepalving タイムアウト = 75 秒 +- Nginx パフォーマンスチューニングガイドラインでは、keepliving = 15 seconds +- キャディサーバーのデフォルトキープサバイバルタイムアウト = 120 秒 +- IE (5-9) クライアントハードキープアライブ制限 = 60秒 +- Firefox クライアントのハードキープサバイバル制限 = 115 秒 +- Opera 11 クライアントのハードキープサバイバル制限 = 120 秒 +- Chrome 13+クライアントキープサバイバル制限 > 300秒以上 -## Proxy configuration +## プロキシ設定 -See [proxy configuration section](/guide/advanced/proxy-headers.md) +format@@0(/guide/advanced/proxy-headers.md) を参照してください。 From fe3605ee73a0e1397999fe1d9069b9844db01d0e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:11 +0200 Subject: [PATCH 370/698] New translations configuration.md (Chinese Simplified) --- .../content/zh/guide/running/configuration.md | 232 +++++++++--------- 1 file changed, 116 insertions(+), 116 deletions(-) diff --git a/guide/content/zh/guide/running/configuration.md b/guide/content/zh/guide/running/configuration.md index 89dacd7f7a..3a2ab1c3cf 100644 --- a/guide/content/zh/guide/running/configuration.md +++ b/guide/content/zh/guide/running/configuration.md @@ -1,14 +1,14 @@ -# Configuration +# 配置 -## Basics +## 基础知识 -.. column:: +.. 列: ``` -Sanic holds the configuration in the config attribute of the application object. The configuration object is merely an object that can be modified either using dot-notation or like a dictionary. +Sanic持有应用程序对象配置属性中的配置。 配置对象只是一个可以使用点符号或像字典修改的对象。 ``` -.. column:: +.. 列: ```` ```python @@ -18,17 +18,17 @@ app.config["DB_USER"] = "appuser" ``` ```` -.. column:: +.. 列: ``` -You can also use the `update()` method like on regular dictionaries. +您也可以使用 `update()` 方法，例如在常规字典上。 ``` -.. column:: +.. 列: ```` ```python -db_settings = { +db_settings= { 'DB_HOST': 'localhost', 'DB_NAME': 'appdb', 'DB_USER': 'appuser' @@ -37,41 +37,41 @@ app.config.update(db_settings) ``` ```` -.. note:: +.. 注： ``` -It is standard practice in Sanic to name your config values in **uppercase letters**. Indeed, you may experience weird behaviors if you start mixing uppercase and lowercase names. +萨尼克的标准练习是在 **大写字母** 中命名您的配置值。 确实，如果你开始混合大写和小写地名，你可能会遇到奇怪的行为。 ``` -## Loading +## 正在加载 -### Environment variables +### 环境变量 -.. column:: +.. 列: ``` -Any environment variables defined with the `SANIC_` prefix will be applied to the Sanic config. For example, setting `SANIC_REQUEST_TIMEOUT` will be loaded by the application automatically and fed into the `REQUEST_TIMEOUT` config variable. +任何通过 `SANIC_` 前缀定义的环境变量都将被应用到 Sanic 配置。 例如，设置 `SANIC_REQUEST_TIMEOUT` 将被自动加载，并输入`REQUEST_TIMEOUT` 配置变量。 ``` -.. column:: +.. 列: ```` ```bash $ export SANIC_REQUEST_TIMEOUT=10 ``` ```python ->>> print(app.config.REQUEST_TIMEOUT) +>> > print(app.config.REQUEST_TIMEOUT) 10 ``` ```` -.. column:: +.. 列: ``` -You can change the prefix that Sanic is expecting at startup. +您可以更改Sanic 在启动时预期的前缀。 ``` -.. column:: +.. 列: ```` ```bash @@ -84,13 +84,13 @@ $ export MYAPP_REQUEST_TIMEOUT=10 ``` ```` -.. column:: +.. 列: ``` -You can also disable environment variable loading completely. +您也可以完全禁用环境变量。 ``` -.. column:: +.. 列: ```` ```python @@ -98,19 +98,19 @@ app = Sanic(__name__, load_env=False) ``` ```` -### Using Sanic.update_config +### 正在使用 Sanic.update_config -The `Sanic` instance has a _very_ versatile method for loading config: `app.update_config`. You can feed it a path to a file, a dictionary, a class, or just about any other sort of object. +`Sanic` 实例有一个用于加载配置的所有_多功能方法：`app.update_config`。 你可以为它提供到文件的路径、字典、类或任何其他类型的对象。 -#### From a file +#### 从文件 -.. column:: +.. 列: ``` -Let's say you have `my_config.py` file that looks like this. +让我们说你有看起来像这样的 `my_config.py` 文件。 ``` -.. column:: +.. 列: ```` ```python @@ -120,13 +120,13 @@ B = 2 ``` ```` -.. column:: +.. 列: ``` -You can load this as config values by passing its path to `app.update_config`. +您可以通过将其路径传递给`app.update_config`来加载它作为配置值。 ``` -.. column:: +.. 列: ```` ```python @@ -136,13 +136,13 @@ You can load this as config values by passing its path to `app.update_config`. ``` ```` -.. column:: +.. 列: ``` -This path also accepts bash style environment variables. +此路径也接受基础风格环境变量。 ``` -.. column:: +.. 列: ```` ```bash @@ -153,21 +153,21 @@ app.update_config("${my_path}/my_config.py") ``` ```` -.. note:: +.. 注： ``` Just remember that you have to provide environment variables in the format `${environment_variable}` and that `$environment_variable` is not expanded (is treated as "plain" text). ``` -#### From a dict +#### 从一个词典 -.. column:: +.. 列: ``` -The `app.update_config` method also works on plain dictionaries. +`app.update_config` 方法也适用于普通字典。 ``` -.. column:: +.. 列: ```` ```python @@ -175,15 +175,15 @@ app.update_config({"A": 1, "B": 2}) ``` ```` -#### From a class or object +#### 来自类或对象 -.. column:: +.. 列: ``` -You can define your own config class, and pass it to `app.update_config` +您可以定义自己的配置类，然后传递到 `app.update_config` ``` -.. column:: +.. 列: ```` ```python @@ -195,13 +195,13 @@ app.update_config(MyConfig) ``` ```` -.. column:: +.. 列: ``` -It even could be instantiated. +它甚至可以实例化。 ``` -.. column:: +.. 列: ```` ```python @@ -209,30 +209,30 @@ app.update_config(MyConfig()) ``` ```` -### Type casting +### 铸造类型 -When loading from environment variables, Sanic will attempt to cast the values to expected Python types. This particularly applies to: +当从环境变量加载时，Sanic会试图将这些值投射到预期的 Python 类型。 这尤其适用于： - `int` - `float` - `bool` -In regards to `bool`, the following _case insensitive_ values are allowed: +关于“布尔值”，允许以下_case insensitive_value： - **`True`**: `y`, `yes`, `yep`, `yup`, `t`, `true`, `on`, `enable`, `enabled`, `1` -- **`False`**: `n`, `no`, `f`, `false`, `off`, `disable`, `disabled`, `0` +- **`False`**: `n`, `no`, `false`, `off`, `disabled`, `0` -If a value cannot be cast, it will default to a `str`. +如果一个值不能投递，它将默认投递到一个 `str`。 -.. column:: +.. 列: ``` -Additionally, Sanic can be configured to cast additional types using additional type converters. This should be any callable that returns the value or raises a `ValueError`. +此外，Sanic可以配置为使用其他类型转换器投射额外类型。 这应该是返回值或提升`ValueError`的任何可调用。 -*Added in v21.12* +*添加于v21.12* ``` -.. column:: +.. 列: ```` ```python @@ -240,42 +240,42 @@ app = Sanic(..., config=Config(converters=[UUID])) ``` ```` -## Builtin values - -| **Variable** | **Default** | **Description** | -| -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| ACCESS_LOG | True | Disable or enable access log | -| AUTO_EXTEND | True | Control whether [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) will load if it is in the existing virtual environment | -| AUTO_RELOAD | True | Control whether the application will automatically reload when a file changes | -| EVENT_AUTOREGISTER | True | When `True` using the `app.event()` method on a non-existing signal will automatically create it and not raise an exception | -| FALLBACK_ERROR_FORMAT | html | Format of error response if an exception is not caught and handled | -| FORWARDED_FOR_HEADER | X-Forwarded-For | The name of "X-Forwarded-For" HTTP header that contains client and proxy ip | -| FORWARDED_SECRET | None | Used to securely identify a specific proxy server (see below) | -| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | How long to wait to force close non-idle connection (sec) | -| INSPECTOR | False | Whether to enable the Inspector | -| INSPECTOR_HOST | localhost | The host for the Inspector | -| INSPECTOR_PORT | 6457 | The port for the Inspector | -| INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | -| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | -| INSPECTOR_API_KEY | - | The API key for the Inspector | -| KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | -| KEEP_ALIVE | True | Disables keep-alive when False | -| MOTD | True | Whether to display the MOTD (message of the day) at startup | -| MOTD_DISPLAY | {} | Key/value pairs to display additional, arbitrary data in the MOTD | -| NOISY_EXCEPTIONS | False | Force all `quiet` exceptions to be logged | -| PROXIES_COUNT | None | The number of proxy servers in front of the app (e.g. nginx; see below) | -| REAL_IP_HEADER | None | The name of "X-Real-IP" HTTP header that contains real client ip | -| REGISTER | True | Whether the app registry should be enabled | -| REQUEST_BUFFER_SIZE | 65536 | Request buffer size before request is paused, default is 64 Kib | -| REQUEST_ID_HEADER | X-Request-ID | The name of "X-Request-ID" HTTP header that contains request/correlation ID | -| REQUEST_MAX_SIZE | 100000000 | How big a request may be (bytes), default is 100 megabytes | -| REQUEST_MAX_HEADER_SIZE | 8192 | How big a request header may be (bytes), default is 8192 bytes | -| REQUEST_TIMEOUT | 60 | How long a request can take to arrive (sec) | -| RESPONSE_TIMEOUT | 60 | How long a response can take to process (sec) | -| USE_UVLOOP | True | Whether to override the loop policy to use `uvloop`. Supported only with `app.run`. | -| WEBSOCKET_MAX_SIZE | 2^20 | Maximum size for incoming messages (bytes) | -| WEBSOCKET_PING_INTERVAL | 20 | A Ping frame is sent every ping_interval seconds. | -| WEBSOCKET_PING_TIMEOUT | 20 | Connection is closed when Pong is not received after ping_timeout seconds | +## 内置值 + +| **变量** | **默认** | **描述** | +| -------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- | +| ACCESS_LOG | 真的 | 禁用或启用访问日志 | +| AUTO_EXTEND | 真的 | 控制 [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) 是否会在现有虚拟环境中加载 | +| AUTO_RELOAD | 真的 | 控制文件更改时应用程序是否会自动重新加载 | +| EVENT_AUTOREGISTER | 真的 | 当`True`使用`app.event()`方法在不存在的信号上将自动创建它，而不会引起异常 | +| FALLBACK_ERROR_FORMAT | .html | 未捕获和处理异常时的错误响应格式 | +| FORWARDED_FOR_HEADER | X-转发-输入 | 包含客户端和代理IP的 "X-Forwarded-for" HTTP 头名称 | +| FORWARDED_SECRET | 无 | 用于安全识别特定代理服务器(见下文) | +| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | 强制关闭非空闲连接等待多长时间 (秒) | +| INSPECTO | 错误 | 是否启用检查器 | +| INSPECTOR_HOST | 本地主机 | 检查专员的主机 | +| INSPECTOR_PORT | 6457 | 检查员的端口 | +| INSPECTOR_TLS_TITLE | - | 检查员的TLS密钥 | +| INSPECTOR_TLS_CERT | * | 检查员的TLS证书 | +| INSPECTOR_API_KEY | - | 检查员的 API 密钥 | +| KEEP_ALIVEUT | 120 | 保持TCP连接打开多长时间(秒) | +| KEEP_ALIVE | 真的 | False 时禁用保持生命值 | +| MOTD | 真的 | 启动时是否显示 MOTD (当天消息) | +| MOTD_DISPLAY | {} | Key/value 对应显示额外的任意数据 | +| NOISY_EXCEPTIONS | 错误 | 强制所有“安静”异常被记录 | +| PROXIES _COUNT | 无 | 在应用程序前面的代理服务器数量 (例如，nginx；见下方) | +| VIP_HEADER | 无 | 包含真实客户端IP的 "X-Real-IP" HTTP 头名称 | +| 注册 | 真的 | 是否启用应用注册 | +| REQUEST_BUFFER_SIZE | 65536 | 请求暂停前请求缓冲区大小，默认是 64 Kib | +| REQUEST_HEADER | X-请求-ID | 包含请求/关联ID的 "X-Request-ID" HTTP 头名称 | +| REQUEST_MAX_SIZE | 100000000 | 请求的大小可能是 (bytes), 默认是 100 megabytes | +| REQUEST_MAX_HEADER_SIZE | 8192 | 请求头可能有多大(字节)，默认值为8192字节 | +| REQUEST_TIMEOUT | 60 | 到达请求可能需要多长时间(秒) | +| 重置_TIMEOUT | 60 | 处理过程可能需要多长时间(秒) | +| USE_UVLOOP | 真的 | 是否覆盖循环策略使用 `uvloop` 。 只支持 `app.run` 。 | +| WEBSOCKET_MAX_SIZE | 2^20 | 收到消息的最大大小(字节) | +| WEBSOCKET_INTERVAL | 20 | 每个ping_interval 秒都会发送一个Ping 帧。 | +| WEBSOCKET_PING_TIMEOUT | 20 | 当Pong在ping_timeout秒后未收到时，连接将被关闭 | .. tip:: FYI @@ -287,42 +287,42 @@ app = Sanic(..., config=Config(converters=[UUID])) - v22.12 added: `INSPECTOR_HOST`, `INSPECTOR_PORT`, `INSPECTOR_TLS_KEY`, `INSPECTOR_TLS_CERT`, `INSPECTOR_API_KEY` ``` -## Timeouts +## 超时 ### REQUEST_TIMEOUT -A request timeout measures the duration of time between the instant when a new open TCP connection is passed to the -Sanic backend server, and the instant when the whole HTTP request is received. If the time taken exceeds the -`REQUEST_TIMEOUT` value (in seconds), this is considered a Client Error so Sanic generates an `HTTP 408` response -and sends that to the client. Set this parameter's value higher if your clients routinely pass very large request payloads +请求超时测量当一个新打开的 TCP 连接传递到 +Sanic 后端服务器时本机之间的时间长度。 和收到整个HTTP请求时的即时通讯。 如果所需时间超过 +`REQUEST_TIMEOUT` (秒), 这被视为客户端错误，所以Sanic生成一个 `HTTP 408` 响应 +并将其发送到客户端。 Set this parameter's value higher if your clients routinely pass very large request payloads or upload requests very slowly. -### RESPONSE_TIMEOUT +### 重置_TIMEOUT -A response timeout measures the duration of time between the instant the Sanic server passes the HTTP request to the Sanic App, and the instant a HTTP response is sent to the client. If the time taken exceeds the `RESPONSE_TIMEOUT` value (in seconds), this is considered a Server Error so Sanic generates an `HTTP 503` response and sends that to the client. Set this parameter's value higher if your application is likely to have long-running process that delay the -generation of a response. +响应超时量度介于 Sanic 服务器通过 HTTP 请求到 Sanic App之间的时间。 即时HTTP响应发送到客户端。 如果时间超过`RESPONSE_TIMEOUT` (秒), 这被视为服务器错误，所以Sanic生成一个 `HTTP 503` 响应，并将其发送到客户端。 如果您的应用程序可能有长期运行的过程会延迟 +生成响应，则设置此参数的值更高。 -### KEEP_ALIVE_TIMEOUT +### KEEP_ALIVEUT -#### What is Keep Alive? And what does the Keep Alive Timeout value do? +#### 什么是继续存活？ 保持活的超时值是什么？ -`Keep-Alive` is a HTTP feature introduced in `HTTP 1.1`. When sending a HTTP request, the client (usually a web browser application) can set a `Keep-Alive` header to indicate the http server (Sanic) to not close the TCP connection after it has send the response. This allows the client to reuse the existing TCP connection to send subsequent HTTP requests, and ensures more efficient network traffic for both the client and the server. +`Keep-Alive`是`HTTP 1.1`中引入的HTTP功能。 发送 HTTP 请求时 客户端(通常是一个网页浏览器应用程序)可以设置一个 `Keep-Alive` 头来指示http服务器(Sanic)在发送响应后不关闭TCP连接。 这允许客户端重新使用现有的 TCP 连接来发送其后的 HTTP 请求。 并确保客户端和服务器更有效的网络通信。 -The `KEEP_ALIVE` config variable is set to `True` in Sanic by default. If you don't need this feature in your application, set it to `False` to cause all client connections to close immediately after a response is sent, regardless of the `Keep-Alive` header on the request. +默认情况下，`KEEP_ALIVE`配置变量设置为 `True`。 如果您在应用程序中不需要此功能， 设置为 `False` 以使所有客户端连接在响应发出后立即关闭。 无论请求时是否有“Keep-Alive”标题。 -The amount of time the server holds the TCP connection open is decided by the server itself. In Sanic, that value is configured using the `KEEP_ALIVE_TIMEOUT` value. By default, **it is set to 120 seconds**. This means that if the client sends a `Keep-Alive` header, the server will hold the TCP connection open for 120 seconds after sending the response, and the client can reuse the connection to send another HTTP request within that time. +服务器保持TCP连接打开的时间长度由服务器自己决定。 在Sanic中，该值使用`KEEP_ALIVE_TIMEOUT` 来配置它。 默认情况下，**它被设置为 120 秒**。 这意味着，如果客户端发送一个 `Keep-Alive` 头，在发送响应后，服务器将保持TCP 连接打开120秒。 并且客户端可以在此时间内重新使用连接发送另一个 HTTP 请求。 -For reference: +供参考： -- Apache httpd server default keepalive timeout = 5 seconds -- Nginx server default keepalive timeout = 75 seconds -- Nginx performance tuning guidelines uses keepalive = 15 seconds -- Caddy server default keepalive timeout = 120 seconds -- IE (5-9) client hard keepalive limit = 60 seconds -- Firefox client hard keepalive limit = 115 seconds -- Opera 11 client hard keepalive limit = 120 seconds -- Chrome 13+ client keepalive limit > 300+ seconds +- Apache httpd 服务器默认保留生命超时 = 5 秒 +- Nginx 服务器默认保留存活超时 = 75 秒 +- Nginx 性能调节准则使用了保持生命=15秒 +- Caddy 服务器默认保留存活超时 = 120秒 +- IE (5-9) 客户硬保留生命限制 = 60 秒 +- Firefox 客户硬存活限制 = 115秒 +- Opera 11 客户端硬存活限制 = 120 秒 +- Chrome 13+ 客户端保持生命限制 > 300+ 秒 -## Proxy configuration +## 代理配置 -See [proxy configuration section](/guide/advanced/proxy-headers.md) +请参阅[代理配置部分](/guide/advanced/proxy-headers.md) From 3d121cbdd498a2464d1c276e09f6eebc0c99fc19 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:12 +0200 Subject: [PATCH 371/698] New translations development.md (Japanese) --- guide/content/ja/guide/running/development.md | 168 +++++++++--------- 1 file changed, 84 insertions(+), 84 deletions(-) diff --git a/guide/content/ja/guide/running/development.md b/guide/content/ja/guide/running/development.md index 03f7c5b47d..6080a1d55a 100644 --- a/guide/content/ja/guide/running/development.md +++ b/guide/content/ja/guide/running/development.md @@ -1,12 +1,12 @@ -# Development +# 開発 -The first thing that should be mentioned is that the webserver that is integrated into Sanic is **not** just a development server. +最初に言及すべきことは、Sanicに統合されているWebサーバーは開発サーバーだけではないということです。 -It is production ready out-of-the-box, _unless you enable in debug mode_. +_デバッグモード_で有効にしない限り、プロダクションはすぐにすぐに準備ができています。 -## Debug mode +## デバッグモード -By setting the debug mode, Sanic will be more verbose in its output and will disable several run-time optimizations. +デバッグモードを設定すると、Sanicは出力をより冗長にし、複数のランタイム最適化を無効にします。 ```python # server.py @@ -21,48 +21,48 @@ async def hello_world(request): ``` ```sh -sanic server:app --host=0.0.0.0 --port=1234 --debug +sanic server:app --host=0.0.0 --port=1234 --debug ``` -.. danger:: +.. 危険:: ``` -Sanic's debug mode will slow down the server's performance, and is **NOT** intended for production environments. +Sanicのデバッグモードはサーバーのパフォーマンスを低下させ、本番環境向けではありません。 -**DO NOT** enable debug mode in production. +**本番環境でデバッグモードを有効にしないでください** 。 ``` -## Automatic Reloader +## 自動リローダー -.. column:: +.. 列:: ``` -Sanic offers a way to enable or disable the Automatic Reloader. The easiest way to enable it is using the CLI's `--reload` argument to activate the Automatic Reloader. Every time a Python file is changed, the reloader will restart your application automatically. This is very convenient while developing. +Sanicは自動リロードを有効または無効にする方法を提供します。 それを有効にする最も簡単な方法は、CLIの`--reload`引数を使用して自動リロードを有効にすることです。 Pythonファイルが変更されるたびに、リローダーはアプリケーションを自動的に再起動します。 これは開発中に非常に便利です。 -.. note:: +.. Note:: - The reloader is only available when using Sanic's [worker manager](./manager.md). If you have disabled it using `--single-process` then the reloader will not be available to you. + このリローダーはSanicの[worker manager]()を使用している場合にのみ利用できます。 `--single-process` を使用して無効にした場合、再ローダーは利用できません。 ``` -.. column:: +.. 列:: ```` ```sh sanic path.to:app --reload ``` -You can also use the shorthand property +簡体字プロパティ ```sh sanic path.to:app -r ``` ```` -.. column:: +.. 列:: ``` -If you have additional directories that you would like to automatically reload on file save (for example, a directory of HTML templates), you can add that using `--reload-dir`. +ファイル保存時に自動的にリロードしたい追加のディレクトリがある場合(例: HTML テンプレートのディレクトリ) `--reload-dir` を使用して追加できます。 ``` -.. column:: +.. 列:: ```` ```sh @@ -74,21 +74,21 @@ sanic path.to:app -r -R /path/to/one -R /path/to/two ``` ```` -## Development REPL +## 開発REPL .. new:: v23.12 ``` -The Sanic CLI comes with a REPL (aka "read-eval-print loop") that can be used to interact with your application. This is useful for debugging and testing. A REPL is the interactive shell that you get when you run `python` without any arguments. +Sanic CLI には、アプリケーションとやり取りするために使用できる REPL (別名「read-eval-print loop」)が付属しています。 これはデバッグとテストに役立ちます。REPL は引数なしで `python` を実行するときに得られる対話型シェルです。 ``` -.. column:: +.. 列:: ``` -You can start the REPL by passing the `--repl` argument to the Sanic CLI. +Sanic CLI に `--repl` 引数を渡すことで、REPL を開始できます。 ``` -.. column:: +.. 列:: ```` ```sh @@ -96,13 +96,13 @@ sanic path.to.server:app --repl ``` ```` -.. column:: +.. 列:: ``` -Or, perhaps more conveniently, when you run `--dev`, Sanic will automatically start the REPL for you. However, in this case you might be prompted to hit the "ENTER" key before actually starting the REPL. +もしくは、 `--dev`を実行すると、Sanicは自動的にREPLを開始します。 ただし、この場合、REPLを実際に開始する前に「ENTER」キーを押すように求められる場合があります。 ``` -.. column:: +.. 列:: ```` ```sh @@ -112,22 +112,22 @@ sanic path.to.server:app --dev ![](/assets/images/repl.png) -As seen in the screenshot above, the REPL will automatically add a few variables to the global namespace. These are: +上のスクリーンショットで見られるように、REPL は自動的にいくつかの変数をグローバル名前空間に追加します。 これらは次のとおりです。 -- `app` - The Sanic application instance. This is the same instance that is passed to the `sanic` CLI. -- `sanic` - The `sanic` module. This is the same module that is imported when you run `import sanic`. -- `do` - A function that will create a mock `Request` object and pass it to your application. This is useful for testing your application from the REPL. -- `client` - An instance of `httpx.Client` that is configured to make requests to your application. This is useful for testing your application from the REPL. **Note:** This is only available if `httpx` is installed in your environment. +- `app` - Sanic applicationインスタンス。 これは、`sanic` CLI に渡されるのと同じインスタンスです。 +- `sanic` - `sanic`モジュール。 `import sanic` を実行したときにインポートされたモジュールと同じです。 +- `do` - モック`Request`オブジェクトを作成し、アプリケーションに渡す関数。 これは、REPLからアプリケーションをテストする場合に便利です。 +- `client` - アプリケーションへのリクエストを行うように設定された `httpx.Client` のインスタンス。 これは、REPLからアプリケーションをテストする場合に便利です。 **注意:** これはあなたの環境で `httpx` がインストールされている場合にのみ利用できます。 -### Async/Await support +### Async/Await サポート -.. column:: +.. 列:: ``` -The REPL supports `async`/`await` syntax. This means that you can use `await` in the REPL to wait for asynchronous operations to complete. This is useful for testing asynchronous code. +REPL は `async`/`await` 構文をサポートしています。つまり、REPL で `await` を使用して非同期操作が完了するまで待つことができます。 これは非同期コードのテストに便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -136,23 +136,23 @@ The REPL supports `async`/`await` syntax. This means that you can use `await` in ``` ```` -### The `app` variable +### 変数 `app` -You need to keep in mind that the `app` variable is your app instance as it existed when the REPL was started. It is the instance that is loaded when running the CLI command. This means that any changes that are made to your source code and subsequently reloaded in the workers will not be reflected in the `app` variable. If you want to interact with the reloaded app instance, you will need to restart the REPL. +`app` 変数は、REPL が起動されたときに存在するため、アプリのインスタンスであることに注意してください。 これは、CLI コマンドを実行するときにロードされるインスタンスです。 つまり、ソースコードに加えられ、ワーカーにリロードされた変更は、 `app` 変数には反映されません。 リロードされたアプリケーション・インスタンスとやり取りしたい場合は、REPLを再起動する必要があります。 -However, it is also very useful to have access to the original app instance in the REPL for adhoc testing and debugging. +しかし、アドホックのテストとデバッグのためにREPLの元のアプリケーション・インスタンスにアクセスできることも非常に便利です。 -### The `client` variable +### `client` 変数 -When [httpx](https://www.python-httpx.org/) is installed in your environment, the `client` variable will be available in the REPL. This is an instance of `httpx.Client` that is configured to make requests to your running application. +[httpx](https://www.python-httpx.org/) があなたの環境にインストールされている場合、`client` 変数はREPLで利用可能になります。 これは実行中のアプリケーションへのリクエストを行うように設定された `httpx.Client` のインスタンスです。 -.. column:: +.. 列:: ``` -To use it, simply call one of the HTTP methods on the client. See the [httpx documentation](https://www.python-httpx.org/api/#client) for more information. +これを使用するには、クライアントの HTTP メソッドのいずれかを呼び出してください。詳細については、[httpx documentation](https://www.python-httpx.org/api/#client) を参照してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -161,50 +161,50 @@ To use it, simply call one of the HTTP methods on the client. See the [httpx doc ``` ```` -### The `do` function +### `do` 関数 -As discussed above, the `app` instance exists as it did at the time the REPL was started, and as was modified inside the REPL. Any changes to the instance that cause a server to be reloaded will not be reflected in the `app` variable. This is where the `do` function comes in. +上で説明したように、REPLが開始された時と同様に、`app` インスタンスが存在し、REPL内で変更されました。 サーバーを再ロードさせるインスタンスへの変更は、 `app` 変数には反映されません。 `do`関数が入ってくるところです。 -Let's say that you have modified your application inside the REPL to add a new route: +新しいルートを追加するために REPL 内のアプリケーションを変更したとします。 ```python >>> @app.get("/new-route") ... async def new_route(request): -... return sanic.json({"hello": "world"}) +... return sanic.json({"hello": "world"}) ... ->>> + >>format@@4 ``` -You can use the `do` function to mock out a request, and pass it to the application as if it were a real HTTP request. This will allow you to test your new route without having to restart the REPL. +`do` 関数を使ってリクエストをモックし、アプリケーションに実際の HTTP リクエストのように渡すことができます。 これにより、REPLを再起動せずに新しいルートをテストすることができます。 ```python >>> await do("/new-route") Result(request=, response=) ``` -The `do` function returns a `Result` object that contains the `Request` and `Response` objects that were returned by your application. It is a `NamedTuple`, so you can access the values by name: +`do` 関数は、アプリケーションから返された `Request` と `Response` オブジェクトを含む `Result` オブジェクトを返します。 `NamedTuple`ですので、名前で値にアクセスできます: ```python >>> result = await do("/new-route") >>> result.request ->>> result.response +>>response ``` -Or, by destructuring the tuple: +または、タプルを分割することによって: ```python ->>> request, response = await do("/new-route") ->>> request +>>> リクエスト、応答 = await do("//new-route") +>>> リクエスト ->>> response +>>応答 ``` -### When to use `do` vs `client`? +### `do` vs `client` はいつ使えばいいですか？ -.. column:: +.. 列:: ``` **Use `do` when ...** @@ -214,7 +214,7 @@ Or, by destructuring the tuple: - You make a change to your application inside the REPL ``` -.. column:: +.. 列:: ``` **Use `client` when ...** @@ -224,45 +224,45 @@ Or, by destructuring the tuple: - You want to send an actual HTTP request to your application ``` -_Added in v23.12_ +_v23.12_ に追加されました -## Complete development mode +## 開発モードを完了 -.. column:: +.. 列:: ``` -If you would like to be in debug mode **and** have the Automatic Reloader running, you can pass `dev=True`. This is equivalent to **debug + auto reload**. +デバッグモードにしたい場合は、自動リロードを実行している**と**、`dev=True`を渡すことができます。 これは**debug + auto reload**と同等です。 -*Added in v22.3* +*v22.3*に追加されました ``` -.. column:: +.. 列:: ```` ```sh sanic path.to:app --dev ``` -You can also use the shorthand property +簡体字プロパティ ```sh sanic path.to:app -d -``` + ``` も使用できます。 ```` .. new:: v23.12 ``` -Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Development REPL](./development.md#development-repl) section for more information. +`--dev` フラグに v23.12 を追加すると、REPLを開始することができます。format@@0()を参照してください。 詳細は development.md#development-repl) セクションを参照してください。 -As of v23.12, the `--dev` flag is roughly equivalent to `--debug --reload --repl`. Using `--dev` will require you to expressly begin the REPL by hitting "ENTER", while passing the `--repl` flag explicitly starts it. +V23 の時点。 2, `--dev` フラグは `--debug --reload --repl` とほぼ同じです。 `--dev` を使用すると、明示的に `--repl` フラグを渡すと、REPL を開始する必要があります。 ``` -.. column:: +.. 列:: ``` -If you would like to disable the REPL while using the `--dev` flag, you can pass `--no-repl`. +`--dev`フラグを使用してREPLを無効にしたい場合は、`--no-repl`を渡すことができます。 ``` -.. column:: +.. 列:: ```` ```sh @@ -270,19 +270,19 @@ sanic path.to:app --dev --no-repl ``` ```` -## Automatic TLS certificate +## 自動 TLS 証明書 -When running in `DEBUG` mode, you can ask Sanic to handle setting up localhost temporary TLS certificates. This is helpful if you want to access your local development environment with `https://`. +`DEBUG`モードで実行している場合、Sanicに、localhostの一時的なTLS証明書の設定を処理するよう依頼できます。 これは、`https://`でローカル開発環境にアクセスしたい場合に役立ちます。 -This functionality is provided by either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). Both are good choices, but there are some differences. `trustme` is a Python library and can be installed into your environment with `pip`. This makes for easy envrionment handling, but it is not compatible when running a HTTP/3 server. `mkcert` might be a more involved installation process, but can install a local CA and make it easier to use. +この機能は [mkcert](https://github.com/FiloSottile/mkcert) または [trustme](https://github.com/python-trio/trustme) のいずれかで提供されています。 どちらも良い選択ですが、いくつかの違いがあります。 `trustme`はPythonライブラリで、`pip`を使って環境にインストールできます。 これにより、envrionment の処理が簡単になりますが、HTTP/3 サーバーの実行時は互換性がありません。 `mkcert` はインストールプロセスにより複雑なものかもしれませんが、ローカルの CA をインストールして使いやすくすることができます。 -.. column:: +.. 列:: ``` -You can choose which platform to use by setting `config.LOCAL_CERT_CREATOR`. When set to `"auto"`, it will select either option, preferring `mkcert` if possible. +`config.LOCAL_CERT_CREATOR` を設定することで、使用するプラットフォームを選択できます。`"auto"`に設定すると、可能な場合は `mkcert` を優先して、どちらかのオプションを選択します。 ``` -.. column:: +.. 列:: ```` ```python @@ -292,13 +292,13 @@ app.config.LOCAL_CERT_CREATOR = "trustme" ``` ```` -.. column:: +.. 列:: ``` -Automatic TLS can be enabled at Sanic server run time: +Sanic サーバーの実行時間で自動的な TLS を有効にできます。 ``` -.. column:: +.. 列:: ```` ```sh @@ -306,10 +306,10 @@ sanic path.to.server:app --auto-tls --debug ``` ```` -.. warning:: +.. 警告:: ``` -Localhost TLS certificates (like those generated by both `mkcert` and `trustme`) are **NOT** suitable for production environments. If you are not familiar with how to obtain a *real* TLS certificate, checkout the [How to...](../how-to/tls.md) section. +ローカルホストの TLS 証明書 (`mkcert` と `trustme` の両方によって生成された証明書) は、本番環境には適していません。 *real* TLS 証明書の取得方法がわからない場合は、[How to...](../how-to/tls.md) セクションをチェックしてください。 ``` -_Added in v22.6_ +_v22.6_に追加されました From f7a16f3e4596a7946962cfac2a4c51ec1430b266 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:14 +0200 Subject: [PATCH 372/698] New translations development.md (Chinese Simplified) --- guide/content/zh/guide/running/development.md | 180 +++++++++--------- 1 file changed, 90 insertions(+), 90 deletions(-) diff --git a/guide/content/zh/guide/running/development.md b/guide/content/zh/guide/running/development.md index 03f7c5b47d..8ec2420aea 100644 --- a/guide/content/zh/guide/running/development.md +++ b/guide/content/zh/guide/running/development.md @@ -1,12 +1,12 @@ -# Development +# 贸易和发展会议 -The first thing that should be mentioned is that the webserver that is integrated into Sanic is **not** just a development server. +应该提到的第一件事是，集成到 Sanic 的 web 服务器是 **不是** 开发服务器。 -It is production ready out-of-the-box, _unless you enable in debug mode_. +它已准备就绪，除非您在调试模式下启用\*。 -## Debug mode +## 调试模式 -By setting the debug mode, Sanic will be more verbose in its output and will disable several run-time optimizations. +通过设置调试模式，Sanic将会在其输出中更详细，并将禁用几个运行时的优化。 ```python # server.py @@ -24,7 +24,7 @@ async def hello_world(request): sanic server:app --host=0.0.0.0 --port=1234 --debug ``` -.. danger:: +.. 危险：: ``` Sanic's debug mode will slow down the server's performance, and is **NOT** intended for production environments. @@ -32,37 +32,37 @@ Sanic's debug mode will slow down the server's performance, and is **NOT** inten **DO NOT** enable debug mode in production. ``` -## Automatic Reloader +## 自动重新加载 -.. column:: +.. 列: ``` -Sanic offers a way to enable or disable the Automatic Reloader. The easiest way to enable it is using the CLI's `--reload` argument to activate the Automatic Reloader. Every time a Python file is changed, the reloader will restart your application automatically. This is very convenient while developing. +Sanic 提供了一种启用或禁用自动重新加载器的方式。 启用它的最简单方式是使用 CLI 的 `--reload` 参数来激活自动重新加载。 每次更改 Python 文件，读取器将自动重启您的应用程序。 正在开发时这非常方便。 -.. note:: +... 注意： - The reloader is only available when using Sanic's [worker manager](./manager.md). If you have disabled it using `--single-process` then the reloader will not be available to you. + 读取器仅在使用 Sanic's 的[工人经理](.) 时才可用。 manager.md. 如果您已禁用它使用 "--lin-process" ，则读取器将不会对您开放。 ``` -.. column:: +.. 列: ```` ```sh sanic path.to:app --reload -``` -You can also use the shorthand property +`` +你也可以使用短暂属性 ```sh sanic path.to:app -r ``` ```` -.. column:: +.. 列: ``` -If you have additional directories that you would like to automatically reload on file save (for example, a directory of HTML templates), you can add that using `--reload-dir`. +如果你有额外的目录，你想要在文件保存时自动重新加载 (例如) 一个 HTML 模板的目录，您可以使用 "--reload-dir" 添加。 ``` -.. column:: +.. 列: ```` ```sh @@ -76,19 +76,19 @@ sanic path.to:app -r -R /path/to/one -R /path/to/two ## Development REPL -.. new:: v23.12 +.. 新：v23.12 ``` -The Sanic CLI comes with a REPL (aka "read-eval-print loop") that can be used to interact with your application. This is useful for debugging and testing. A REPL is the interactive shell that you get when you run `python` without any arguments. +Sanic CLI 带有一个 REPL (又名“读-写循环”)，可用来与您的应用程序进行交互。 这对调试和测试非常有用。REPL是你在没有任何参数的情况下运行python时得到的交互式外壳。 ``` -.. column:: +.. 列: ``` -You can start the REPL by passing the `--repl` argument to the Sanic CLI. +你可以将 "--repli" 参数传递到 Sanic CLI 来启动 REPL ``` -.. column:: +.. 列: ```` ```sh @@ -96,13 +96,13 @@ sanic path.to.server:app --repl ``` ```` -.. column:: +.. 列: ``` -Or, perhaps more conveniently, when you run `--dev`, Sanic will automatically start the REPL for you. However, in this case you might be prompted to hit the "ENTER" key before actually starting the REPL. +也许更方便的是，当你运行`--dev`时，萨尼克会自动为你启动REPL。 然而，在这种情况下，你可能会在实际启动REPL之前被提示按“ENTER”键。 ``` -.. column:: +.. 列: ```` ```sh @@ -110,49 +110,49 @@ sanic path.to.server:app --dev ``` ```` -![](/assets/images/repl.png) +![](/assets/images/repli.png) -As seen in the screenshot above, the REPL will automatically add a few variables to the global namespace. These are: +如上文截图所示，REPL将自动为全局命名空间添加几个变量。 它们是： -- `app` - The Sanic application instance. This is the same instance that is passed to the `sanic` CLI. -- `sanic` - The `sanic` module. This is the same module that is imported when you run `import sanic`. -- `do` - A function that will create a mock `Request` object and pass it to your application. This is useful for testing your application from the REPL. -- `client` - An instance of `httpx.Client` that is configured to make requests to your application. This is useful for testing your application from the REPL. **Note:** This is only available if `httpx` is installed in your environment. +- `app` - Sanic 应用程序实例。 这是传递到 `sanic` CLI 的相同实例。 +- `sanic` - `sanic` 模块。 这是在您运行 "import sanic" 时导入的同一个模块。 +- `do` - 一个将创建模拟`Request`对象并将其传递给您的应用程序的函数。 这对测试你来自REPL的申请非常有用。 +- `client` - 一个`httpx.glient`的实例被配置为向您的应用程序提出请求。 这对测试你来自REPL的申请非常有用。 **注意：** 只有在你的环境中安装了 `httpx` 时，这才是可用的。 -### Async/Await support +### Async/Awaw 支持 -.. column:: +.. 列: ``` -The REPL supports `async`/`await` syntax. This means that you can use `await` in the REPL to wait for asynchronous operations to complete. This is useful for testing asynchronous code. +REPL 支持 `async`/`await` 语法。这意味着你可以使用 `await` 来等待异步操作完成。 这有助于测试异步代码。 ``` -.. column:: +.. 列: ```` ```python ->>> await app.ctx.db.fetchval("SELECT 1") +>>> > 等待 app.ctx.db.fetchval("SELECT 1") 1 ``` ```` -### The `app` variable +### `app`变量 -You need to keep in mind that the `app` variable is your app instance as it existed when the REPL was started. It is the instance that is loaded when running the CLI command. This means that any changes that are made to your source code and subsequently reloaded in the workers will not be reflected in the `app` variable. If you want to interact with the reloaded app instance, you will need to restart the REPL. +你需要记住，`app`变量是你的应用程序实例，因为它是在REPL启动时存在的。 它是运行CLI 命令时加载的实例。 这意味着对你的源代码的任何更改，然后在工人中重新加载，都不会反映在`app`变量中。 如果你想要与重新加载的应用进行交互，你需要重新启动REPL。 -However, it is also very useful to have access to the original app instance in the REPL for adhoc testing and debugging. +然而，访问REPL中的原始应用程序以进行临时测试和调试也非常有用。 -### The `client` variable +### "客户端" 变量 -When [httpx](https://www.python-httpx.org/) is installed in your environment, the `client` variable will be available in the REPL. This is an instance of `httpx.Client` that is configured to make requests to your running application. +当 [httpx](https://www.python-httpx.org/) 安装在您的环境中时，"client" 变量将可在REPL中找到。 这是一个 `httpxClient` 的实例，它被配置为向您正在运行的应用程序提出请求。 -.. column:: +.. 列: ``` -To use it, simply call one of the HTTP methods on the client. See the [httpx documentation](https://www.python-httpx.org/api/#client) for more information. +若要使用它，只需调用客户端上的 HTTP 方法之一。请参阅[httpx documentation](https://www.python-httpx.org/api/#client)获取更多信息。 ``` -.. column:: +.. 列: ```` ```python @@ -161,50 +161,50 @@ To use it, simply call one of the HTTP methods on the client. See the [httpx doc ``` ```` -### The `do` function +### `do`函数 -As discussed above, the `app` instance exists as it did at the time the REPL was started, and as was modified inside the REPL. Any changes to the instance that cause a server to be reloaded will not be reflected in the `app` variable. This is where the `do` function comes in. +正如上文所讨论的那样，“app”实例就像启动REPL时那样存在，并且在REPL内部进行了修改。 导致服务器重新加载的实例的任何更改都不会反映在`app`变量中。 这是`do`函数的位置。 -Let's say that you have modified your application inside the REPL to add a new route: +让我们说你已经修改了你在REPL中的应用程序以添加一条新的路由： ```python >>> @app.get("/new-route") ... async def new_route(request): -... return sanic.json({"hello": "world"}) +... return sanic.json({"hello": "world"}) ... ->>> +>> ``` -You can use the `do` function to mock out a request, and pass it to the application as if it were a real HTTP request. This will allow you to test your new route without having to restart the REPL. +您可以使用 `do` 函数模拟请求，并将其传递到应用程序中，仿佛它是一个真正的 HTTP 请求。 这将允许您测试您的新路线，而不必重新启动REPL。 ```python ->>> await do("/new-route") -Result(request=, response=) +>>>>正在等待 do("/new-route") +结果(request=, response=) ``` -The `do` function returns a `Result` object that contains the `Request` and `Response` objects that were returned by your application. It is a `NamedTuple`, so you can access the values by name: +`do`函数返回一个包含 `Request` 和 `Response` 对象的 `Result` 对象。 这是一个 `NamedTuple` ，因此您可以按名称访问值： ```python ->>> result = await do("/new-route") ->>> result.request +>>>> 结果 = 等待完成("/new-route") +>>>> result.request ->>> result.response +>>> result.reply ``` -Or, by destructuring the tuple: +或者，通过摧毁管： ```python ->>> request, response = await do("/new-route") ->>> request +>>>>请求, 应答 = 等待完成("/new-route") +>>>>>>>>请求 ->>> response +>>>>>>>> 应答 ``` -### When to use `do` vs `client`? +### 什么时候使用 `do` 和 `client`? -.. column:: +.. 列: ``` **Use `do` when ...** @@ -214,7 +214,7 @@ Or, by destructuring the tuple: - You make a change to your application inside the REPL ``` -.. column:: +.. 列: ``` **Use `client` when ...** @@ -224,31 +224,31 @@ Or, by destructuring the tuple: - You want to send an actual HTTP request to your application ``` -_Added in v23.12_ +_添加于 v23.12_ -## Complete development mode +## 完成开发模式 -.. column:: +.. 列: ``` -If you would like to be in debug mode **and** have the Automatic Reloader running, you can pass `dev=True`. This is equivalent to **debug + auto reload**. +如果你想要处于调试模式**和** 运行自动重新加载器，你可以通过 `dev=True`。 这相当于**调试+自动重新加载**。 -*Added in v22.3* +*添加于v22.3* ``` -.. column:: +.. 列: ```` ```sh sanic path.to:app --dev -``` -You can also use the shorthand property +`` +你也可以使用短暂属性 ```sh sanic path.to:app -d ``` ```` -.. new:: v23.12 +.. 新：v23.12 ``` Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Development REPL](./development.md#development-repl) section for more information. @@ -256,13 +256,13 @@ Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Dev As of v23.12, the `--dev` flag is roughly equivalent to `--debug --reload --repl`. Using `--dev` will require you to expressly begin the REPL by hitting "ENTER", while passing the `--repl` flag explicitly starts it. ``` -.. column:: +.. 列: ``` -If you would like to disable the REPL while using the `--dev` flag, you can pass `--no-repl`. +如果你想要在使用 --dev' 标志时禁用REPL，你可以通过 "--no-reply "。 ``` -.. column:: +.. 列: ```` ```sh @@ -270,35 +270,35 @@ sanic path.to:app --dev --no-repl ``` ```` -## Automatic TLS certificate +## 自动TLS证书 -When running in `DEBUG` mode, you can ask Sanic to handle setting up localhost temporary TLS certificates. This is helpful if you want to access your local development environment with `https://`. +当在 `DEBUG` 模式下运行时，您可以要求Sanic 处理本地主机临时TLS 证书的设置。 如果您想要访问 'https\://' 本地发展环境，这将是很有帮助的。 -This functionality is provided by either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). Both are good choices, but there are some differences. `trustme` is a Python library and can be installed into your environment with `pip`. This makes for easy envrionment handling, but it is not compatible when running a HTTP/3 server. `mkcert` might be a more involved installation process, but can install a local CA and make it easier to use. +此功能由 [mkcert](https://github.com/FiloSottile/mkcert) 或 [trustme](https://github.com/python-trio/trustme) 提供。 两者都是好的选择，但也有一些差异。 `Trustme` 是一个 Python 库，可以安装在 `pip` 里的环境。 这使得可以轻松地处理Envrionment，但在运行 HTTP/3 服务器时是不兼容的。 `mkcert`可能是一个更多的安装过程，但可以安装本地CA并使其更容易使用。 -.. column:: +.. 列: ``` -You can choose which platform to use by setting `config.LOCAL_CERT_CREATOR`. When set to `"auto"`, it will select either option, preferring `mkcert` if possible. +您可以通过设置 `config.LOCAL_CERT_CREATOR` 选择哪个平台。当设置为 `auto`时，它将选择任何一个选项，如果可能则选择`mkcert`。 ``` -.. column:: +.. 列: ```` ```python -app.config.LOCAL_CERT_CREATOR = "auto" -app.config.LOCAL_CERT_CREATOR = "mkcert" -app.config.LOCAL_CERT_CREATOR = "trustme" +app.config.LOCAL_CERT_CREATOR= "auto" +app.config.LOCAL_CERT_CREATOR= "mkcert" +app.config.LOCAL_CERT_CREATOR= "trustme" ``` ```` -.. column:: +.. 列: ``` -Automatic TLS can be enabled at Sanic server run time: +Sanic 服务器运行时间可以启用自动TLS： ``` -.. column:: +.. 列: ```` ```sh @@ -306,10 +306,10 @@ sanic path.to.server:app --auto-tls --debug ``` ```` -.. warning:: +.. 警告：: ``` -Localhost TLS certificates (like those generated by both `mkcert` and `trustme`) are **NOT** suitable for production environments. If you are not familiar with how to obtain a *real* TLS certificate, checkout the [How to...](../how-to/tls.md) section. +本地的 TLS 证书（就像`mkcert` 和 `trustme` 生成的证书一样）**不适用于生产环境。 如果您不熟悉如何获得*真实*TLS证书，请签出[如何...](../how-to/tls.md)。 ``` -_Added in v22.6_ +_添加于 v22.6_ From c6436bba3da8dcc17e65ec6362d2b976a24e46f5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:15 +0200 Subject: [PATCH 373/698] New translations inspector.md (Japanese) --- guide/content/ja/guide/running/inspector.md | 128 ++++++++++---------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/guide/content/ja/guide/running/inspector.md b/guide/content/ja/guide/running/inspector.md index c8310877d9..a7e383b479 100644 --- a/guide/content/ja/guide/running/inspector.md +++ b/guide/content/ja/guide/running/inspector.md @@ -1,26 +1,26 @@ # Inspector -The Sanic Inspector is a feature of Sanic Server. It is _only_ available when running Sanic with the built-in [worker manager](./manager.md). +Sanic Inspector は、Sanic Server の機能です。 Sanic を組み込みの format@@0(./manager.md) で実行している場合は _のみ_ 利用できます。 -It is an HTTP application that _optionally_ runs in the background of your application to allow you to interact with the running instance of your application. +これは、アプリケーションの実行中のインスタンスと対話できるように、アプリケーションのバックグラウンドで_オプション_で動作するHTTPアプリケーションです。 .. tip:: INFO ``` -The Inspector was introduced in limited capacity in v22.9, but the documentation on this page assumes you are using v22.12 or higher. +インスペクターは v22.9 で限定的な容量で導入されましたが、このページのドキュメントでは、v22.12 以上を使用していることを前提としています。 ``` -## Getting Started +## はじめに -The inspector is disabled by default. To enable it, you have two options. +インスペクターはデフォルトで無効になっています。 それを有効にするには、2つのオプションがあります。 -.. column:: +.. 列:: ``` -Set a flag when creating your application instance. +アプリケーションインスタンスを作成するときにフラグを設定します。 ``` -.. column:: +.. 列:: ```` ```python @@ -28,13 +28,13 @@ app = Sanic("TestApp", inspector=True) ``` ```` -.. column:: +.. 列:: ``` -Or, set a configuration value. +または、設定値を設定します。 ``` -.. column:: +.. 列:: ```` ```python @@ -43,26 +43,26 @@ app.config.INSPECTOR = True ``` ```` -.. warning:: +.. 警告:: ``` -If you are using the configuration value, it *must* be done early and before the main worker process starts. This means that it should either be an environment variable, or it should be set shortly after creating the application instance as shown above. +設定値を使用している場合は、メインワーカープロセスが開始される前に *必ず* 設定を行わなければなりません。 これは、環境変数であるか、上記のようにアプリケーションインスタンスを作成した直後に設定する必要があることを意味します。 ``` -## Using the Inspector +## インスペクターの使用 -Once the inspector is running, you will have access to it via the CLI or by directly accessing its web API via HTTP. +インスペクターが実行されると、CLI 経由または直接 Web API に HTTP 経由でアクセスできるようになります。 -.. column:: +.. 列:: ```` -**Via CLI** +**CLI** ```sh sanic inspect ``` ```` -.. column:: +.. 列:: ```` **Via HTTP** @@ -74,31 +74,31 @@ curl http://localhost:6457 .. note:: ``` -Remember, the Inspector is not running on your Sanic application. It is a seperate process, with a seperate application, and exposed on a seperate socket. +覚えておいてください、インスペクターはSanicアプリケーション上で実行されていません。それは分離されたアプリケーションであり、分離されたソケット上で公開されています。 ``` -## Built-in Commands +## 内蔵コマンド -The Inspector comes with the following built-in commands. +インスペクターには、次の組み込みコマンドが付属しています。 -| CLI Command | HTTP Action | Description | -| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ | -| `inspect` | `GET /` | Display basic details about the running application. | -| `inspect reload` | `POST /reload` | Trigger a reload of all server workers. | -| `inspect shutdown` | `POST /shutdown` | Trigger a shutdown of all processes. | -| `inspect scale N` | `POST /scale`
`{"replicas": N}` | Scale the number of workers. Where `N` is the target number of replicas. | +| CLIコマンド | HTTP アクション | 説明 | +| ------------------ | ------------------------------ | ----------------------------- | +| `inspect` | `GET /` | 実行中のアプリケーションに関する基本的な詳細を表示します。 | +| `inspect reload` | `POST /reload` | すべてのサーバワーカーのリロードをトリガーします。 | +| `inspect shutdown` | `POST /shutdown` | すべてのプロセスをシャットダウンします。 | +| `inspect scale N` | `POST /scale`
`{"レプリカ": N}` | ワーカーの数を調整します。 `N`がレプリカの対象数です。 | -## Custom Commands +## カスタムコマンド -The Inspector is easily extendable to add custom commands (and endpoints). +インスペクターは簡単に拡張でき、カスタムコマンド(およびエンドポイント)を追加できます。 -.. column:: +.. 列:: ``` -Subclass the `Inspector` class and create arbitrary methods. As long as the method name is not preceded by an underscore (`_`), then the name of the method will be a new subcommand on the inspector. +`Inspector` クラスをサブクラス化し、任意のメソッドを作成します。 メソッド名の前にアンダースコア(`_`)がない限り、 そして、このメソッドの名前は、インスペクタの新しいサブコマンドになります。 ``` -.. column:: +.. 列:: ```` ```python @@ -114,23 +114,23 @@ app = Sanic("TestApp", inspector_class=MyInspector, inspector=True) ``` ```` -This will expose custom methods in the general pattern: +これは一般的なパターンでカスタムメソッドを公開します。 -- CLI: `sanic inspect ` +- CLI: `健全な検査 ` - HTTP: `POST /` -It is important to note that the arguments that the new method accepts are derived from how you intend to use the command. For example, the above `something` method accepts all positional and keyword based parameters. +新しいメソッドが受け取る引数は、コマンドの使用方法に基づいていることに注意することが重要です。 例えば、上記の `something` メソッドは、すべての位置とキーワードベースのパラメータを受け取ります。 -.. column:: +.. 列:: ``` -In the CLI, the positional and keyword parameters are passed as either positional or keyword arguments to your method. All values will be a `str` with the following exceptions: +CLIでは、位置パラメータとキーワードパラメータが、メソッドに位置引数またはキーワード引数として渡されます。 すべての値は次の例外を持つ`str`になります: -- A keyword parameter with no assigned value will be: `True` -- Unless the parameter is prefixed with `no-`, then it will be: `False` +- 代入されていないキーワードパラメータは次のようになります: `True` +- パラメータが`no`で始まる場合を除きます。 次のようになります: `False` ``` -.. column:: +.. 列:: ```` ```sh @@ -143,13 +143,13 @@ In your application log console, you will see: ``` ```` -.. column:: +.. 列:: ``` -The same can be achieved by hitting the API directly. You can pass arguments to the method by exposing them in a JSON payload. The only thing to note is that the positional arguments should be exposed as `{"args": [...]}`. +APIを直接押すことでも同様です。JSONペイロードで公開することでメソッドに引数を渡すことができます。 唯一の注意点は、位置引数は `{"args": [...] }` として公開されるべきであるということです。 ``` -.. column:: +.. 列:: ```` ```sh @@ -163,25 +163,25 @@ In your application log console, you will see: ``` ```` -## Using in production +## プロダクションでの使用 -.. danger:: +.. 危険:: ``` -Before exposing the Inspector on a product, please consider all of the options in this section carefully. +製品のインスペクターを公開する前に、このセクションのすべてのオプションを注意深く検討してください。 ``` -When running Inspector on a remote production instance, you can protect the endpoints by requiring TLS encryption, and requiring API key authentication. +リモート本番インスタンスでインスペクターを実行する場合、TLS 暗号化を要求し、API キー認証を必要とすることでエンドポイントを保護できます。 -### TLS encryption +### TLS 暗号化 -.. column:: +.. 列:: ``` -To the Inspector HTTP instance over TLS, pass the paths to your certificate and key. +TLS を介してインスペクタの HTTP インスタンスには、証明書と鍵へのパスを渡します。 ``` -.. column:: +.. 列:: ```` ```python @@ -190,13 +190,13 @@ app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" ``` ```` -.. column:: +.. 列:: ``` -This will require use of the `--secure` flag, or `https://`. +`--secure` フラグまたは `https://` を使用する必要があります。 ``` -.. column:: +.. 列:: ```` ```sh @@ -207,15 +207,15 @@ curl https://:6457 ``` ```` -### API Key Authentication +### API キー認証 -.. column:: +.. 列:: ``` -You can secure the API with bearer token authentication. +Bearer token authenticationでAPIをセキュリティ保護できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -223,23 +223,23 @@ app.config.INSPECTOR_API_KEY = "Super-Secret-200" ``` ```` -.. column:: +.. 列:: ``` -This will require the `--api-key` parameter, or bearer token authorization header. +これには`--api-key` パラメータまたはベアラートトークン認証ヘッダが必要です。 ``` -.. column:: +.. 列:: ```` ```sh sanic inspect --api-key=Super-Secret-200 ``` ```sh -curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" ``` ```` -## Configuration +## 設定 -See [configuration](./configuration.md) +[configuration](./configuration.md) を参照してください。 From 15c32e6641a3a23da594a3a9a86560048e71b3d5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:17 +0200 Subject: [PATCH 374/698] New translations inspector.md (Chinese Simplified) --- guide/content/zh/guide/running/inspector.md | 158 ++++++++++---------- 1 file changed, 79 insertions(+), 79 deletions(-) diff --git a/guide/content/zh/guide/running/inspector.md b/guide/content/zh/guide/running/inspector.md index c8310877d9..b8da974281 100644 --- a/guide/content/zh/guide/running/inspector.md +++ b/guide/content/zh/guide/running/inspector.md @@ -1,26 +1,26 @@ -# Inspector +# 检查员 -The Sanic Inspector is a feature of Sanic Server. It is _only_ available when running Sanic with the built-in [worker manager](./manager.md). +Sanic 检查员是Sanic Server的一个特征。 在使用内置的 [工人经理] (./manager.md) 运行 Sanic 时，它是唯一可用的。 -It is an HTTP application that _optionally_ runs in the background of your application to allow you to interact with the running instance of your application. +这是一个 HTTP 应用程序_可选_在您的应用程序后台运行，允许您与运行中的应用程序的实例进行交互。 .. tip:: INFO ``` -The Inspector was introduced in limited capacity in v22.9, but the documentation on this page assumes you are using v22.12 or higher. +在v22.9中，检查员的能力有限，但本页上的文件假定您正在使用v22.12或更多。 ``` -## Getting Started +## 正在开始 -The inspector is disabled by default. To enable it, you have two options. +检查员默认是禁用的。 要启用它，您有两个选项。 -.. column:: +.. 列: ``` -Set a flag when creating your application instance. +在创建应用程序实例时设置一个标记。 ``` -.. column:: +.. 列: ```` ```python @@ -28,128 +28,128 @@ app = Sanic("TestApp", inspector=True) ``` ```` -.. column:: +.. 列: ``` -Or, set a configuration value. +或者设置一个配置值。 ``` -.. column:: +.. 列: ```` ```python -app = Sanic("TestApp") +app = Sanic("测试应用") app.config.INSPECTOR = True ``` ```` -.. warning:: +.. 警告：: ``` -If you are using the configuration value, it *must* be done early and before the main worker process starts. This means that it should either be an environment variable, or it should be set shortly after creating the application instance as shown above. +如果您正在使用配置值，它*必须在主工作流程开始之前尽早完成。 这意味着它要么应该是一个环境变量，要么应该在创建上文所示的应用程序实例之后马上设定。 ``` -## Using the Inspector +## 使用检查器 -Once the inspector is running, you will have access to it via the CLI or by directly accessing its web API via HTTP. +一旦检查员运行，您将可以通过 CLI 或通过 HTTP 直接访问 Web API 访问它。 -.. column:: +.. 列: ```` **Via CLI** ```sh -sanic inspect +sanic inspection ``` ```` -.. column:: +.. 列: ```` -**Via HTTP** +**通过 HTTP** ```sh curl http://localhost:6457 ``` ```` -.. note:: +.. 注： ``` -Remember, the Inspector is not running on your Sanic application. It is a seperate process, with a seperate application, and exposed on a seperate socket. +请记住，检查员没有在您的 Sanic 应用程序上运行。它是一个分隔过程，具有一个分隔的应用程序，并且在一个隔绝的套接字上暴露。 ``` -## Built-in Commands +## 内置命令 -The Inspector comes with the following built-in commands. +检查员带着以下内置命令。 -| CLI Command | HTTP Action | Description | -| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ | -| `inspect` | `GET /` | Display basic details about the running application. | -| `inspect reload` | `POST /reload` | Trigger a reload of all server workers. | -| `inspect shutdown` | `POST /shutdown` | Trigger a shutdown of all processes. | -| `inspect scale N` | `POST /scale`
`{"replicas": N}` | Scale the number of workers. Where `N` is the target number of replicas. | +| CLI 命令 | HTTP 操作 | 描述 | +| -------- | ---------------------------------- | ------------------- | +| `检查` | `GET /` | 显示正在运行的应用程序的基本细节。 | +| `检查重新加载` | `POST /重新加载` | 触发所有服务器员工的重新加载。 | +| \`检查关机' | `POST /shutdown` | 触发所有进程的关闭。 | +| `检查比例N` | `POST /scale`
`{"replicas": N}` | 缩放工人数量。 `N`是复制的目标数。 | -## Custom Commands +## 自定义命令 -The Inspector is easily extendable to add custom commands (and endpoints). +检查员很容易添加自定义命令(和终点)。 -.. column:: +.. 列: ``` -Subclass the `Inspector` class and create arbitrary methods. As long as the method name is not preceded by an underscore (`_`), then the name of the method will be a new subcommand on the inspector. +将`Inspector`类子类并创建任意方法。 只要方法名称前面没有下划线(`_`)， 然后方法的名称将是视察员上的一个新的子命令。 ``` -.. column:: +.. 列: ```` ```python -from sanic import json -from sanic.worker.inspector import Inspector +从Sanic.worker导入json +n旁观导入检查员 class MyInspector(Inspector): - async def something(self, *args, **kwargs): + async def something(self, *args, **kwargs： print(args) print(kwargs) -app = Sanic("TestApp", inspector_class=MyInspector, inspector=True) +app = Sanic("测试应用", spector_class=MyInspector, spector=True) ``` ```` -This will expose custom methods in the general pattern: +这将会显示常规模式中的自定义方法： -- CLI: `sanic inspect ` +- CLI: `sanic inspection ` - HTTP: `POST /` -It is important to note that the arguments that the new method accepts are derived from how you intend to use the command. For example, the above `something` method accepts all positional and keyword based parameters. +必须指出，新方法接受的参数来自你打算如何使用命令。 例如，上面的“something”方法接受所有基于位置和关键字的参数。 -.. column:: +.. 列: ``` -In the CLI, the positional and keyword parameters are passed as either positional or keyword arguments to your method. All values will be a `str` with the following exceptions: +在 CLI 中，位置和关键字参数作为您方法的定位或关键词参数传递。 所有值都将是一个 `str` 但有以下例外情况: -- A keyword parameter with no assigned value will be: `True` -- Unless the parameter is prefixed with `no-`, then it will be: `False` +- 一个没有分配值的关键字参数将是: `True` +- 除非参数前缀为 `no `, 然后它将是：`False` ``` -.. column:: +.. 列: ```` ```sh -sanic inspect something one two three --four --no-five --six=6 +sanic 检查了两个--four --no-five --six=6 +`` +在您的应用程序日志控制台中， 你会看到： ``` -In your application log console, you will see: -``` -('one', 'two', 'three') +('one', 'tw', 'three') {'four': True, 'five': False, 'six': '6'} ``` ```` -.. column:: +.. 列: ``` -The same can be achieved by hitting the API directly. You can pass arguments to the method by exposing them in a JSON payload. The only thing to note is that the positional arguments should be exposed as `{"args": [...]}`. +直接点击 API 可以实现同样的目标。您可以在 JSON 有效载荷中将参数传递到方法中。 唯一需要注意的是，位置参数应该以`{"args": [...] }`的形式暴露。 ``` -.. column:: +.. 列: ```` ```sh @@ -163,25 +163,25 @@ In your application log console, you will see: ``` ```` -## Using in production +## 在生产中使用 -.. danger:: +.. 危险：: ``` -Before exposing the Inspector on a product, please consider all of the options in this section carefully. +在向检查员展示产品之前，请仔细考虑本节中的所有选项。 ``` -When running Inspector on a remote production instance, you can protect the endpoints by requiring TLS encryption, and requiring API key authentication. +当在远程生产实例中运行检查员时，您可以通过需要 TLS 加密和需要 API 密钥认证来保护端点。 -### TLS encryption +### TLS 加密 -.. column:: +.. 列: ``` -To the Inspector HTTP instance over TLS, pass the paths to your certificate and key. +通过 TLS 向检查员HTTP 实例将路径传递到您的证书和密钥。 ``` -.. column:: +.. 列: ```` ```python @@ -190,32 +190,32 @@ app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" ``` ```` -.. column:: +.. 列: ``` -This will require use of the `--secure` flag, or `https://`. +这将需要使用 "--secure" 标志或 "https://"。 ``` -.. column:: +.. 列: -```` +````` ```sh -sanic inspect --secure --host= -``` +sanic inspection --secure --host= +```` ```sh -curl https://:6457 +curl https:////:6457 ``` -```` +````` -### API Key Authentication +### API 密钥认证 -.. column:: +.. 列: ``` -You can secure the API with bearer token authentication. +您可以通过持单人令牌身份验证来保护 API。 ``` -.. column:: +.. 列: ```` ```python @@ -223,13 +223,13 @@ app.config.INSPECTOR_API_KEY = "Super-Secret-200" ``` ```` -.. column:: +.. 列: ``` -This will require the `--api-key` parameter, or bearer token authorization header. +这将需要 "--api-key" 参数，或无记者令牌授权标题。 ``` -.. column:: +.. 列: ```` ```sh @@ -240,6 +240,6 @@ curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" ``` ```` -## Configuration +## 配置 See [configuration](./configuration.md) From cb4f085a7688902e4becdf121acf944a09092af0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:18 +0200 Subject: [PATCH 375/698] New translations manager.md (Japanese) --- guide/content/ja/guide/running/manager.md | 328 +++++++++++----------- 1 file changed, 164 insertions(+), 164 deletions(-) diff --git a/guide/content/ja/guide/running/manager.md b/guide/content/ja/guide/running/manager.md index b71685420e..3b284c4f73 100644 --- a/guide/content/ja/guide/running/manager.md +++ b/guide/content/ja/guide/running/manager.md @@ -1,36 +1,36 @@ --- -title: Worker Manager +title: ワーカーマネージャー --- -# Worker Manager +# ワーカーマネージャー -The worker manager and its functionality was introduced in version 22.9. +Worker マネージャーとその機能はバージョン 22.9 で導入されました。 -_The details of this section are intended for more advanced usages and **not** necessary to get started._ +_このセクションの詳細は、より高度な使用を目的としています。開始するのに必要なものではありません。_ -The purpose of the manager is to create consistency and flexibility between development and production environments. Whether you intend to run a single worker, or multiple workers, whether with, or without auto-reload: the experience will be the same. +マネージャーの目的は、開発環境と生産環境の間の一貫性と柔軟性を創造することです。 単一のワーカーを実行するか、複数のワーカーを実行するかに関わらず、自動再ロードの有無に関わらず、経験は同じになります。 -In general it looks like this: +一般的には以下のようになります: -![](https://user-images.githubusercontent.com/166269/178677618-3b4089c3-6c6a-4ecc-8d7a-7eba2a7f29b0.png) +![](https://user-images.githubusercontent.com/166269/17677618-3b4089c3-6c6a-4ecc-8d7a-7eba2a7f29b0.png) -When you run Sanic, the main process instantiates a `WorkerManager`. That manager is in charge of running one or more `WorkerProcess`. There generally are two kinds of processes: +Sanic を実行すると、メインプロセスは `WorkerManager` をインスタンス化します。 そのマネージャーは1つ以上の `WorkerProcess` の実行を担当しています。 一般的には2種類のプロセスがあります。 -- server processes, and -- non-server processes. +- サーバープロセスと +- 非サーバー プロセス -For the sake of ease, the User Guide generally will use the term "worker" or "worker process" to mean a server process, and "Manager" to mean the single worker manager running in your main process. +ユーザーガイドでは、一般的にサーバープロセスを意味する「ワーカー」または「ワーカープロセス」という用語を使用します。 「マネージャー」とは、メインプロセスで実行されている単一のワーカーマネージャーを意味します。 -## How Sanic Server starts processes +## Sanic Server がプロセスを開始する方法 -Sanic will start processes using the [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) start method. This means that for every process/worker, the global scope of your application will be run on its own thread. The practical impact of this that _if_ you do not run Sanic with the CLI, you will need to nest the execution code inside a block to make sure it only runs on `__main__`. +Sanic は [spawn](https://docs.python.org/3/library/multiprocessing.html#context-and-start-methods) を使用してプロセスを開始します。 つまり、プロセス/ワーカーごとに、アプリケーションのグローバルスコープが独自のスレッドで実行されます。 あなたがCLIを使ってSanicを実行しない場合\*この実際的な影響。 `__main__`でのみ実行されるように、ブロックの中に実行コードを入れ子にする必要があります。 ```python if __name__ == "__main__": app.run() ``` -If you do not, you are likely to see an error message like this: +しない場合は、次のようなエラーメッセージが表示される可能性があります。 ``` sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. @@ -40,39 +40,39 @@ This may have happened if you are running Sanic in the global scope and not insi See more information: https://sanic.dev/en/guide/deployment/manager.html#how-sanic-server-starts-processes ``` -The likely fix for this problem is nesting your Sanic run call inside of the `__name__ == "__main__"` block. If you continue to receive this message after nesting, or if you see this while using the CLI, then it means the port you are trying to use is not available on your machine and you must select another port. +この問題を解決するには、`__name__ == "__main__"`ブロックの中に Sanic runを入れ子にする必要があります。 ネストの後にこのメッセージを受信し続ける場合、または CLI の使用中にこのメッセージが表示される場合。 使おうとしているポートはマシン上では利用できない 別のポートを選択しなければならない -### Starting a worker +### ワーカーを開始 -All worker processes _must_ send an acknowledgement when starting. This happens under the hood, and you as a developer do not need to do anything. However, the Manager will exit with a status code `1` if one or more workers do not send that `ack` message, or a worker process throws an exception while trying to start. If no exceptions are encountered, the Manager will wait for up to thirty (30) seconds for the acknowledgement. +すべてのワーカープロセスは開始時に確認を送信する必要があります。 これはボンネットの下で起こり、開発者としてあなたは何もする必要はありません。 ただし、1人以上のワーカーがメッセージを送信しない場合、マネージャーはステータスコード`1`で終了します。 またはワーカープロセスは、起動中に例外をスローします。 例外が発生しない場合、マネージャーは承認のために最大30秒間待機します。 -.. column:: +.. 列:: ``` -In the situation when you know that you will need more time to start, you can monkeypatch the Manager. The threshold does not include anything inside of a listener, and is limited to the execution time of everything in the global scope of your application. +あなたが開始するために多くの時間が必要になることを知っている状況では、マネージャーをmonkeypatch ことができます。 しきい値はリスナーの中には含まれません。 アプリケーションのグローバルな範囲内のすべての実行時間に制限されます。 -If you run into this issue, it may indicate a need to look deeper into what is causing the slow startup. +この問題に遭遇した場合、起動が遅い原因について詳しく調べる必要がある可能性があります。 ``` -.. column:: +.. 列:: ```` ```python from sanic.worker.manager import WorkerManager -WorkerManager.THRESHOLD = 100 # Value is in 0.1s +WorkerManager.THRESHOLD = 100 # Value is in 0.1s ``` ```` -See [worker ack](#worker-ack) for more information. +詳細は format@@0(#worker-ack) を参照してください。 -.. column:: +.. 列:: ``` -As stated above, Sanic will use [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to start worker processes. If you would like to change this behavior and are aware of the implications of using different start methods, you can modify as shown here. +上記のように、Sanic は [spawn](https://docs.python.org/3/library/multiprocessing.html#context-and-start-methods) を使用してワーカープロセスを開始します。 この動作を変更し、異なるstart メソッドを使用することの影響を認識したい場合は、ここに示すように変更できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -84,19 +84,19 @@ Sanic.start_method = "fork" ### Worker ack -When all of your workers are running in a subprocess a potential problem is created: deadlock. This can occur when the child processes cease to function, but the main process is unaware that this happened. Therefore, Sanic servers will automatically send an `ack` message (short for acknowledge) to the main process after startup. +すべてのワーカーがサブプロセスで実行されている場合、潜在的な問題が生じます:デッドロック。 これは子プロセスが機能を停止した場合に発生することがありますが、メインプロセスはこれが起こったことを認識していません。 したがって、Sanicサーバーは起動後にメインプロセスに自動的に`ack`メッセージ（確認のための略）を送信します。 -In version 22.9, the `ack` timeout was short and limited to `5s`. In version 22.12, the timeout was lengthened to `30s`. If your application is shutting down after thirty seconds then it might be necessary to manually increase this threshhold. +バージョン22.9では、`ack`のタイムアウトは短く、`5s`に制限されていました。 バージョン 22.12 では、タイムアウトは `30s` に延長されました。 アプリケーションが30秒後にシャットダウンする場合、このしきい値を手動で増やす必要があるかもしれません。 -.. column:: +.. 列:: ``` -The value of `WorkerManager.THRESHOLD` is in `0.1s` increments. Therefore, to set it to one minute, you should set the value to `600`. +`WorkerManager.THRESHOLD` の値は `0.1s` 単位です。したがって1分に設定するには、値を `600` に設定してください。 -This value should be set as early as possible in your application, and should ideally happen in the global scope. Setting it after the main process has started will not work. +この値は、アプリケーションで可能な限り早期に設定する必要があり、理想的にはグローバルスコープで設定する必要があります。 メインプロセスが開始された後に設定することはできません。 ``` -.. column:: +.. 列:: ```` ```python @@ -106,19 +106,19 @@ WorkerManager.THRESHOLD = 600 ``` ```` -### Zero downtime restarts +### ゼロダウンタイムの再起動 -By default, when restarting workers, Sanic will teardown the existing process first before starting a new one. +デフォルトでは、ワーカーを再起動すると、Sanicは新しいプロセスを開始する前に既存のプロセスを最初に分解します。 -If you are intending to use the restart functionality in production then you may be interested in having zero-downtime reloading. This can be accomplished by forcing the reloader to change the order to start a new process, wait for it to [ack](#worker-ack), and then teardown the old process. +本番環境で再起動機能を使用しようとしている場合は、ゼロダウンタイムのリロードに興味があるかもしれません。 これは、新しいプロセスを開始するために、再ローダーを強制的に変更することによって達成することができます。 [ack](#worker-ack) まで待ってから、古いプロセスを分解します。 -.. column:: +.. 列:: ``` -From the multiplexer, use the `zero_downtime` argument +マルチプレクサから`zero_downtime`引数を使います。 ``` -.. column:: +.. 列:: ```` ```python @@ -126,32 +126,32 @@ app.m.restart(zero_downtime=True) ``` ```` -_Added in v22.12_ +_v22.12_ に追加されました -## Using shared context between worker processes +## ワーカープロセス間で共有コンテキストを使用する -Python provides a few methods for [exchanging objects](https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes), [synchronizing](https://docs.python.org/3/library/multiprocessing.html#synchronization-between-processes), and [sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-between-processes) between processes. This usually involves objects from the `multiprocessing` and `ctypes` modules. +Python provides a few methods for [exchanging objects](https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes), [synchronizing](https://docs.python.org/3/library/multiprocessing.html#synchronization-between-processes), and [sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-between-processes) between processes. これには通常、 `multiprocessing` と `ctypes` モジュールのオブジェクトが含まれます。 -If you are familiar with these objects and how to work with them, you will be happy to know that Sanic provides an API for sharing these objects between your worker processes. If you are not familiar, you are encouraged to read through the Python documentation linked above and try some of the examples before proceeding with implementing shared context. +あなたがこれらのオブジェクトとそれらの操作方法に精通しているなら Sanicはこれらのオブジェクトをワーカープロセス間で共有するためのAPIを提供しています。 慣れていない場合は、 上記のリンク先の Python ドキュメントを読んで、共有コンテキストの実装を進める前にいくつかの例を試してみることをお勧めします。 -Similar to how [application context](../basics/app.md#application-context) allows an applicaiton to share state across the lifetime of the application with `app.ctx`, shared context provides the same for the special objects mentioned above. This context is available as `app.shared_ctx` and should **ONLY** be used to share objects intended for this purpose. +format@@0(../basics/app.md#application-context) と同様に、アプリケーションの寿命にわたってアプリケーションが `app と状態を共有することができます。 tx`は、上記の特別なオブジェクトに対して共有コンテキストを提供します。 このコンテキストは `app.shared_ctx` として利用できます。この目的のためにオブジェクトを共有するために **ONLY** を使用します。 -The `shared_ctx` will: +`shared_ctx` は次のようになります: -- _NOT_ share regular objects like `int`, `dict`, or `list` -- _NOT_ share state between Sanic instances running on different machines -- _NOT_ share state to non-worker processes -- **only** share state between server workers managed by the same Manager +- _NOT_ `int` や `dict` や `list` などの通常のオブジェクトを共有していません +- _違う_マシン上で実行されているSanicインスタンス間での状態の共有 +- _NOT_ 状態をワーカー以外のプロセスと共有 +- **のみ** 同じマネージャーによって管理されたサーバーワーカー間の状態を共有 -Attaching an inappropriate object to `shared_ctx` will likely result in a warning, and not an error. You should be careful to not accidentally add an unsafe object to `shared_ctx` as it may not work as expected. If you are directed here because of one of those warnings, you might have accidentally used an unsafe object in `shared_ctx`. +`shared_ctx` に不適切なオブジェクトを追加すると警告になり、エラーにならない可能性があります。 `shared_ctx` に誤って安全でないオブジェクトを追加しないように注意してください。 これらの警告が原因でここに指示された場合、`shared_ctx` で安全でないオブジェクトを誤って使用した可能性があります。 -.. column:: +.. 列:: ``` -In order to create a shared object you **must** create it in the main process and attach it inside of the `main_process_start` listener. +共有オブジェクトを作成するには、メインプロセスで作成し、 `main_process_start` リスナーの中に添付する必要があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -163,38 +163,38 @@ async def main_process_start(app): ``` ```` -Trying to attach to the `shared_ctx` object outside of this listener may result in a `RuntimeError`. +このリスナーの外で `shared_ctx` オブジェクトにアタッチしようとすると、 `RuntimeError` になります。 -.. column:: +.. 列:: ``` -After creating the objects in the `main_process_start` listener and attaching to the `shared_ctx`, they will be available in your workers wherever the application instance is available (example: listeners, middleware, request handlers). +`main_process_start` リスナーでオブジェクトを作成し、`shared_ctx` にアタッチした後 アプリケーションインスタンスが利用可能な場所(例:リスナー、ミドルウェア、リクエストハンドラ)は、ワーカー内で利用可能になります。 ``` -.. column:: +.. 列:: ```` ```python from multiprocessing import Queue -@app.get("") +@app.get(char@@2) async def handler(request): request.app.shared_ctx.queue.put(1) ... ``` ```` -## Access to the multiplexer +## マルチプレクサへのアクセス -The application instance has access to an object that provides access to interacting with the Manager and other worker processes. The object is attached as the `app.multiplexer` property, but it is more easily accessed by its alias: `app.m`. +アプリケーションインスタンスは、Manager や他のワーカープロセスとの相互作用へのアクセスを提供するオブジェクトへのアクセス権を持っています。 オブジェクトは `app.multiple` プロパティとしてアタッチされますが、`app.m` は別名でアクセスしやすくなります。 -.. column:: +.. 列:: ``` -For example, you can get access to the current worker state. +たとえば、現在のワーカーの状態にアクセスできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -211,13 +211,13 @@ Sanic-Server-0-0 ``` ```` -.. column:: +.. 列:: ``` -The `multiplexer` also has access to terminate the Manager, or restart worker processes +`multiplace`は、マネージャーを終了するか、ワーカープロセスを再起動するためのアクセス権を持っています ``` -.. column:: +.. 列:: ```` ```python @@ -235,15 +235,15 @@ app.m.name.restart(all_workers=True) # Available v22.12+ ``` ```` -## Worker state +## ワーカーの状態 -.. column:: +.. 列:: ``` -As shown above, the `multiplexer` has access to report upon the state of the current running worker. However, it also contains the state for ALL processes running. +上に示すように、`multiplace` は現在の実行中のワーカーの状態を報告するためにアクセスできます。 しかし、それはまた、実行されているすべてのプロセスのための状態を含みます。 ``` -.. column:: +.. 列:: ```` ```python @@ -273,39 +273,39 @@ async def print_state(request: Request): ``` ```` -The possible states are: +可能な状態は次のとおりです。 -- `NONE` - The worker has been created, but there is no process yet -- `IDLE` - The process has been created, but is not running yet -- `STARTING` - The process is starting -- `STARTED` - The process has started -- `ACKED` - The process has started and sent an acknowledgement (usually only for server processes) -- `JOINED` - The process has exited and joined the main process -- `TERMINATED` - The process has exited and terminated -- `RESTARTING` - The process is restarting -- `FAILED` - The process encountered an exception and is no longer running -- `COMPLETED` - The process has completed its work and exited successfully +- `NONE` - 作業者が作成されましたが、プロセスはまだありません。 +- `IDLE` - プロセスは作成されましたが、まだ実行されていません +- `STARTING` - プロセスが開始されています +- `STARTED` - プロセスが開始されました +- `ACKED` - プロセスが開始され、承認を送信しました (通常はサーバーのプロセスのみ) +- `JOINED` - プロセスが終了し、メインプロセスに参加しました +- `TERMINATED` - プロセスが終了し、終了しました +- `RESTARTING` - プロセスが再起動しています +- `FAILED` - プロセスが例外に遭遇し、実行されなくなりました +- `COMPLETED` - プロセスが完了し、終了しました -## Built-in non-server processes +## 組み込みの非サーバー プロセス -As mentioned, the Manager also has the ability to run non-server processes. Sanic comes with two built-in types of non-server processes, and allows for [creating custom processes](#running-custom-processes). +前述のように、マネージャーは非サーバプロセスを実行することもできます。 Sanicには2種類の非サーバープロセスが組み込まれており、format@@0(#running-custom-processes) を使用できます。 -The two built-in processes are +二つの組み込みプロセスは -- the [auto-reloader](./development.md#automatic-reloader), optionally enabled to watch the file system for changes and trigger a restart -- [inspector](#inspector), optionally enabled to provide external access to the state of the running instance +- [auto-reloader](./development.md#automatic-reloader) は、ファイルシステムの変更を監視し、再起動をトリガーするために必要に応じて有効になります +- [inspector](#inspector) オプションで実行中のインスタンスの状態への外部アクセスを提供することができます ## Inspector -Sanic has the ability to expose the state and the functionality of the `multiplexer` to the CLI. Currently, this requires the CLI command to be run on the same machine as the running Sanic instance. By default the inspector is disabled. +Sanicは、CLIに「multiplane」の状態と機能を公開する能力を持っています。 現在、実行中のSanicインスタンスと同じマシン上でCLIコマンドを実行する必要があります。 デフォルトではインスペクターは無効になっています。 -.. column:: +.. 列:: ``` -To enable it, set the config value to `True`. +有効にするには、設定値を `True` に設定します。 ``` -.. column:: +.. 列:: ```` ```python @@ -313,51 +313,51 @@ app.config.INSPECTOR = True ``` ```` -You will now have access to execute any of these CLI commands: +これで、これらの CLI コマンドのいずれかを実行することができます。 ``` -sanic inspect reload Trigger a reload of the server workers -sanic inspect shutdown Shutdown the application and all processes -sanic inspect scale N Scale the number of workers to N -sanic inspect Run a custom command +健全な検査 reload サーバワーカーのリロードをトリガーする +sanic inspect shutdown the application and all processes +sanic inspect scale N ワーカー数を N +sanic inspect カスタムコマンドを実行 ``` ![](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) -.. column:: +.. 列:: ``` -This works by exposing a small HTTP service on your machine. You can control the location using configuration values: +これは、マシン上の小さなHTTPサービスを公開することで動作します。設定値を使用して場所を制御できます。 ``` -.. column:: +.. 列:: ```` ```python -app.config.INSPECTOR_HOST = "localhost" -app.config.INSPECTOR_PORT = 6457 +app.config.INSPECTOR_HOST = "localhost" +app.config.INSPECTOR_PORT = 6457 ``` ```` -[Learn more](./inspector.md) to find out what is possible with the Inspector. +format@@0(./inspector.md) は、インスペクターで何が可能かを知ることができます。 -## Running custom processes +## カスタムプロセスの実行 -To run a managed custom process on Sanic, you must create a callable. If that process is meant to be long-running, then it should handle a shutdown call by a `SIGINT` or `SIGTERM` signal. +Sanicで管理されたカスタムプロセスを実行するには、呼び出し可能ファイルを作成する必要があります。 そのプロセスが長時間実行されることを意図している場合は、`SIGINT`または`SIGTERM`信号によるシャットダウンコールを処理する必要があります。 -.. column:: +.. 列:: ``` -The simplest method for doing that in Python will be to just wrap your loop in `KeyboardInterrupt`. +Pythonでそれを行う最も簡単な方法は、`KeyboardInterrupt`でループをラップすることです。 -If you intend to run another application, like a bot, then it is likely that it already has capability to handle this signal and you likely do not need to do anything. +ボットのような別のアプリケーションを実行する場合。 この信号を処理する能力を持っている可能性があります おそらく何もする必要はありません ``` -.. column:: +.. 列:: ```` ```python -from time import sleep +from time import slep def my_process(foo): try: @@ -368,13 +368,13 @@ def my_process(foo): ``` ```` -.. column:: +.. 列:: ``` -That callable must be registered in the `main_process_ready` listener. It is important to note that is is **NOT** the same location that you should register [shared context](#using-shared-context-between-worker-processes) objects. +その呼び出し可能ファイルは `main_process_ready` リスナーに登録する必要があります。 重要なのは、format@@0(#using-shared-context-between-worker-processes) オブジェクトを登録するのと同じ場所ではないことです。 ``` -.. column:: +.. 列:: ```` ```python @@ -385,17 +385,17 @@ async def ready(app: Sanic, _): ``` ```` -### Transient v. durable processes +### Transient v.耐久性のあるプロセス -.. column:: +.. 列:: ``` -When you manage a process with the `manage` method, you have the option to make it transient or durable. A transient process will be restarted by the auto-reloader, and a durable process will not. +`manage` メソッドでプロセスを管理する場合は、プロセスをトランジェントまたは耐久性にするオプションがあります。 一時的なプロセスは、オートリローダーによって再起動され、耐久性のあるプロセスは実行されません。 -By default, all processes are durable. +デフォルトでは、すべてのプロセスは耐久性があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -405,12 +405,12 @@ async def ready(app: Sanic, _): "MyProcess", my_process, {"foo": "bar"}, - transient=True, + transitent=True, ) ``` ```` -### Tracked v. untracked processes +### 追跡されていないプロセス .. new:: v23.12 @@ -422,13 +422,13 @@ See [worker state](./manager#worker-state) for more information. Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. ``` -.. column:: +.. 列:: ``` -When you are running a non-long-running process, you can opt out of tracking it by setting `tracked=False` in the `manage` method. This means that upon completion of the process it will be removed from the list of tracked processes. You will only be able to check the state of the process while it is running. +長時間実行されていないプロセスを実行している場合は、`manage`メソッドに`tracked=False`を設定することでトラッキングを解除できます。 これは、プロセスが完了すると、追跡されたプロセスのリストから削除されることを意味します。 実行中のプロセスの状態のみを確認できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -443,23 +443,23 @@ async def ready(app: Sanic, _): ``` ```` -_Added in v23.12_ +_v23.12_ に追加されました -### Restartable custom processes +### 再起動可能なカスタムプロセス .. new:: v23.12 ``` -A custom process that is transient will **always** be restartable. That means the auto-restart will work as expected. However, what if you want to be able to *manually* restart a process, but not have it be restarted by the auto-reloader? +トランジェントであるカスタムプロセスは**常に起動可能**になります。つまり、自動再起動は想定どおりに動作します。 ただし、プロセスを手動で再起動できますが、オートリローダーで再起動できない場合はどうなりますか? ``` -.. column:: +.. 列:: ``` -In this scenario, you can set `restartable=True` in the `manage` method. This will allow you to manually restart the process, but it will not be restarted by the auto-reloader. +このシナリオでは、`manage`メソッドで`restartable=True`を設定できます。 これにより、手動でプロセスを再起動することができますが、自動再起動では再起動しません。 ``` -.. column:: +.. 列:: ```` ```python @@ -474,13 +474,13 @@ async def ready(app: Sanic, _): ``` ```` -.. column:: +.. 列:: ``` -You could now manually restart that process from the multiplexer. +マルチプレクサから手動でそのプロセスを再起動できるようになりました。 ``` -.. column:: +.. 列:: ```` ```python @@ -491,23 +491,23 @@ async def restart_handler(request: Request): ``` ```` -_Added in v23.12_ +_v23.12_ に追加されました -### On the fly process management +### オンザフライプロセス管理 .. new:: v23.12 ``` -Custom processes are usually added in the `main_process_ready` listener. However, there may be times when you want to add a process after the application has started. For example, you may want to add a process from a request handler. The multiplexer provides a method for doing this. +カスタムプロセスは通常 `main_process_ready` リスナーに追加されます。 ただし、アプリケーションの開始後にプロセスを追加したい場合があります。 例えば、リクエストハンドラからプロセスを追加することができます。multiplexer はこれを行うためのメソッドを提供します。 ``` -.. column:: +.. 列:: ``` -Once you have a reference to the multiplexer, you can call `manage` to add a process. It works the same as the `manage` method on the Manager. +マルチプレクサへの参照ができたら、プロセスを追加するために `manage` を呼び出すことができます。 マネージャーの `manage` メソッドと同じ動作をします。 ``` -.. column:: +.. 列:: ```` ```python @@ -523,17 +523,17 @@ async def start_handler(request: Request): ``` ```` -_Added in v23.12_ +_v23.12_ に追加されました -## Single process mode +## シングルプロセスモード -.. column:: +.. 列:: ``` -If you would like to opt out of running multiple processes, you can run Sanic in a single process only. In this case, the Manager will not run. You will also not have access to any features that require processes (auto-reload, the inspector, etc). +複数のプロセスの実行をオプトアウトしたい場合は、1つのプロセスでのみSanicを実行できます。 この場合、マネージャーは実行されません。 また、プロセスを必要とする機能(自動リロード、インスペクタなど)にもアクセスできません。 ``` -.. column:: +.. 列:: ```` ```sh @@ -552,31 +552,31 @@ if __name__ == "__main__": ## Sanic and multiprocessing -Sanic makes heavy use of the [`multiprocessing` module](https://docs.python.org/3/library/multiprocessing.html) to manage the worker processes. You should generally avoid lower level usage of this module (like setting the start method) as it may interfere with the functionality of Sanic. +Sanic は [`multiprocessing` module](https://docs.python.org/3/library/multiprocessing.html) を使用してワーカープロセスを管理します。 通常、Sanic の機能を妨げる可能性があるため、このモジュールの低レベル使用(start メソッドの設定など)は避けるべきです。 -### Start methods in Python +### Pythonでメソッドを開始 -Before explaining what Sanic tries to do, it is important to understand what the `start_method` is and why it is important. Python generally allows for three different methods of starting a process: +Sanicが何をしようとしているのかを説明する前に、`start_method`とは何か、なぜそれが重要なのかを理解することが重要です。 Python では一般的に、プロセスを開始するための 3 つの異なるメソッドが使用できます。 - `fork` - `spawn` - `forkserver` -The `fork` and `forkserver` methods are only available on Unix systems, and `spawn` is the only method available on Windows. On Unix systems where you have a choice, `fork` is generally the default system method. +`fork` と `forkserver` メソッドは Unix システムでのみ使用でき、`spawn` は Windows で利用できる唯一のメソッドです。 選択肢がある Unix システムでは、`fork` は一般的にデフォルトのシステムメソッドです。 -You are encouraged to read the [Python documentation](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to learn more about the differences between these methods. However, the important thing to know is that `fork` basically copies the entire memory of the parent process into the child process, whereas `spawn` will create a new process and then load the application into that process. This is the reason why you need to nest your Sanic `run` call inside of the `__name__ == "__main__"` block if you are not using the CLI. +これらのメソッドの違いについては、format@@0(https\://docs.python.org/3/library/multiprocessing.html#context-and-start-methods)を参照してください。 ただし、重要なことは、基本的に親プロセスのメモリ全体を子プロセスにコピーすることです。 `spawn` は新しいプロセスを作成し、そのプロセスにアプリケーションをロードします。 CLIを使っていない場合は、`__name__ == "__main__"`ブロックの中に、Sanic `run` を入れ子にする必要があります。 -### Sanic and start methods +### サニックメソッドと開始方法 -By default, Sanic will try and use `spawn` as the start method. This is because it is the only method available on Windows, and it is the safest method on Unix systems. +デフォルトでは、Sanicはstartメソッドとして`spawn`を使用します。 これは、Windows で利用可能な唯一の方法であり、Unix システムで最も安全な方法であるためです。 -.. column:: +.. 列:: ``` -However, if you are running Sanic on a Unix system and you would like to use `fork` instead, you can do so by setting the `start_method` on the `Sanic` class. You will want to do this as early as possible in your application, and ideally in the global scope before you import any other modules. +もしあなたが Unix システムで Sanic を実行していて、代わりに `fork` を使用したい場合。 `Sanic`クラスに`start_method`を設定することで可能です。 他のモジュールをインポートする前に、アプリケーションで可能な限り早期にこれを行い、グローバルスコープで理想的にこれを行う必要があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -586,23 +586,23 @@ Sanic.start_method = "fork" ``` ```` -### Overcoming a `RuntimeError` +### `RuntimeError`をクリアする -You might have received a `RuntimeError` that looks like this: +次のような `RuntimeError` を受け取ったかもしれません。 ``` -RuntimeError: Start method 'spawn' was requested, but 'fork' was already set. +RuntimeError: Startメソッド'spawn'が要求されましたが、'fork'は既に設定されていました。 ``` -If so, that means somewhere in your application you are trying to set the start method that conflicts with what Sanic is trying to do. You have a few options to resolve this: +そうであれば、アプリケーションのどこかでSanicがやろうとしていることと競合するstartメソッドを設定しようとしていることを意味します。 これを解決するにはいくつかのオプションがあります。 -.. column:: +.. 列:: ``` -**OPTION 1:** You can tell Sanic that the start method has been set and to not try and set it again. +**OPTION 1:** Sanicに、startメソッドが設定されており、再度設定しないようにすることができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -612,13 +612,13 @@ Sanic.START_METHOD_SET = True ``` ```` -.. column:: +.. 列:: ``` -**OPTION 2:** You could tell Sanic that you intend to use `fork` and to not try and set it to `spawn`. +**OPTION 2:** Sanicに、 `fork` を使うつもりで、 `spawn` を使わないように伝えることができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -628,13 +628,13 @@ Sanic.start_method = "fork" ``` ```` -.. column:: +.. 列:: ``` -**OPTION 3:** You can tell Python to use `spawn` instead of `fork` by setting the `multiprocessing` start method. +**OPTION 3:** `multiprocessing` start メソッドを設定することで、`fork` の代わりに `spawn` を使用するようにPythonに指示できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -644,7 +644,7 @@ multiprocessing.set_start_method("spawn") ``` ```` -In any of these options, you should run this code as early as possible in your application. Depending upon exactly what your specific scenario is, you may need to combine some of the options. +これらのいずれかのオプションでは、アプリケーションでできるだけ早くこのコードを実行する必要があります。 具体的なシナリオによっては、いくつかのオプションを組み合わせる必要がある場合があります。 .. note:: From 12d9cd8d08f5945a2a526b74b97351773cc9d5b9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:20 +0200 Subject: [PATCH 376/698] New translations manager.md (Chinese Simplified) --- guide/content/zh/guide/running/manager.md | 372 +++++++++++----------- 1 file changed, 186 insertions(+), 186 deletions(-) diff --git a/guide/content/zh/guide/running/manager.md b/guide/content/zh/guide/running/manager.md index b71685420e..b10abc05de 100644 --- a/guide/content/zh/guide/running/manager.md +++ b/guide/content/zh/guide/running/manager.md @@ -1,36 +1,36 @@ --- -title: Worker Manager +title: 工人管理器 --- -# Worker Manager +# 工人管理器 -The worker manager and its functionality was introduced in version 22.9. +22.9版引入了工人经理及其功能。 -_The details of this section are intended for more advanced usages and **not** necessary to get started._ +_本节的详细信息是为了更高级的用法，**无需** 开始。_ -The purpose of the manager is to create consistency and flexibility between development and production environments. Whether you intend to run a single worker, or multiple workers, whether with, or without auto-reload: the experience will be the same. +管理人员的目的是在开发和生产环境之间建立连贯性和灵活性。 您是否打算运行单个工人或多个工人，无论是否使用自动重新加载： 体验是一样的。 -In general it looks like this: +一般而言，它看起来像这样： -![](https://user-images.githubusercontent.com/166269/178677618-3b4089c3-6c6a-4ecc-8d7a-7eba2a7f29b0.png) +![](https://user-images.githubusercontent.com/1662669/178677618-3b4089c3-6c6a-4ecc-8d7a-7eba2a7f29b0.png) -When you run Sanic, the main process instantiates a `WorkerManager`. That manager is in charge of running one or more `WorkerProcess`. There generally are two kinds of processes: +当你运行 Sanic 时，主要进程会实例化一个 `WorkerManager` 。 该经理负责运行一个或多个`WorkerProcess`。 通常有两种程序： -- server processes, and -- non-server processes. +- 服务器进程和 +- 非服务器流程。 -For the sake of ease, the User Guide generally will use the term "worker" or "worker process" to mean a server process, and "Manager" to mean the single worker manager running in your main process. +为了方便起见，用户指南通常使用“工人”或“工人处理”这个术语来表示服务器过程。 和“经理”指在您的主要进程中运行的单个工人管理员。 -## How Sanic Server starts processes +## Sanic 服务器如何启动进程 -Sanic will start processes using the [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) start method. This means that for every process/worker, the global scope of your application will be run on its own thread. The practical impact of this that _if_ you do not run Sanic with the CLI, you will need to nest the execution code inside a block to make sure it only runs on `__main__`. +Sanic 将使用 [spawn](https://docs.python.org/3/library/multiprocessing.html#contextsand-start-methods) 启动进程。 这意味着对于每个进程/工作者，您的应用程序的全局范围将在自己的线程上运行。 The practical impact of this that _if_ you do not run Sanic with the CLI, you will need to nest the execution code inside a block to make sure it only runs on `__main__`. ```python if __name__ == "__main__": app.run() ``` -If you do not, you are likely to see an error message like this: +如果您没有，您可能会看到像这样的错误消息： ``` sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. @@ -40,39 +40,39 @@ This may have happened if you are running Sanic in the global scope and not insi See more information: https://sanic.dev/en/guide/deployment/manager.html#how-sanic-server-starts-processes ``` -The likely fix for this problem is nesting your Sanic run call inside of the `__name__ == "__main__"` block. If you continue to receive this message after nesting, or if you see this while using the CLI, then it means the port you are trying to use is not available on your machine and you must select another port. +The likely fix for this problem is nesting your Sanic run call inside of the `__name__ == "__main__"` block. 如果您在嵌套后继续收到此消息，或者如果您在使用CLI时看到此消息， 然后，这意味着您正在尝试使用的端口在您的机器上不可用，您必须选择另一个端口。 -### Starting a worker +### 开始工作者 -All worker processes _must_ send an acknowledgement when starting. This happens under the hood, and you as a developer do not need to do anything. However, the Manager will exit with a status code `1` if one or more workers do not send that `ack` message, or a worker process throws an exception while trying to start. If no exceptions are encountered, the Manager will wait for up to thirty (30) seconds for the acknowledgement. +所有工序_必须_在启动时发送确认信息。 这种情况发生在最严重的情况下，你作为开发者不需要做任何事情。 然而，如果一个或多个工人不发送`ack`消息，管理员将用状态码`1`退出， 或者工人进程在试图启动时抛出异常。 如果没有遇到例外情况，管理员将等待至多三十(30)秒的确认时间。 -.. column:: +.. 列: ``` -In the situation when you know that you will need more time to start, you can monkeypatch the Manager. The threshold does not include anything inside of a listener, and is limited to the execution time of everything in the global scope of your application. +在你知道你需要更多时间来开始的情况下，你可以把管理员混为一谈。 阈值不包括侦听器内的任何内容， 并且限制在您的应用程序的全局范围内的执行时间。 -If you run into this issue, it may indicate a need to look deeper into what is causing the slow startup. +如果你遇到这个问题，它可能会表明需要更深入地了解导致启动速度缓慢的原因。 ``` -.. column:: +.. 列: ```` ```python -from sanic.worker.manager import WorkerManager +from sanic.worker.many import WorkerManager -WorkerManager.THRESHOLD = 100 # Value is in 0.1s +WorkerManager.THRESHOLD = 100 # 值在 0.1s ``` ```` -See [worker ack](#worker-ack) for more information. +欲了解更多信息，请查看[工人的链接](#worker-ack)。 -.. column:: +.. 列: ``` -As stated above, Sanic will use [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to start worker processes. If you would like to change this behavior and are aware of the implications of using different start methods, you can modify as shown here. +如上所述，Sanic将使用 [spawn](https://docs.python.org/3/library/multiprocessing.html#contextsand-start-methods) 启动工人进程。 如果你想改变这种行为并且知道使用不同的起始方法会产生什么影响，你可以在这里进行修改。 ``` -.. column:: +.. 列: ```` ```python @@ -82,21 +82,21 @@ Sanic.start_method = "fork" ``` ```` -### Worker ack +### 工人套装 -When all of your workers are running in a subprocess a potential problem is created: deadlock. This can occur when the child processes cease to function, but the main process is unaware that this happened. Therefore, Sanic servers will automatically send an `ack` message (short for acknowledge) to the main process after startup. +当您所有的工人在子进程中运行时，可能出现的问题会被创建：僵局。 当儿童进程停止运作时，就可能出现这种情况，但主要进程并不知道发生了这种情况。 因此，Sanic 服务器将在启动后自动向主进程发送一个 'ack' 消息 (以便确认)。 -In version 22.9, the `ack` timeout was short and limited to `5s`. In version 22.12, the timeout was lengthened to `30s`. If your application is shutting down after thirty seconds then it might be necessary to manually increase this threshhold. +在22.9版本中，`ack`超时短暂，仅限`5s`。 在第22.12版中，超时时间延长到\`30秒'。 如果您的应用程序在30秒后关闭，可能需要手动增加此阈值。 -.. column:: +.. 列: ``` -The value of `WorkerManager.THRESHOLD` is in `0.1s` increments. Therefore, to set it to one minute, you should set the value to `600`. +`WorkerManager.THRESHOLD`的值是 `0.1s`。因此，要将它设置为 1分钟，您应该将值设置为 `600'。 -This value should be set as early as possible in your application, and should ideally happen in the global scope. Setting it after the main process has started will not work. +此值应尽早在您的应用程序中设置，并且最好在全局范围内出现。 在主要进程开始后设置它将是行不通的。 ``` -.. column:: +.. 列: ```` ```python @@ -106,56 +106,56 @@ WorkerManager.THRESHOLD = 600 ``` ```` -### Zero downtime restarts +### 零下限重启时间 -By default, when restarting workers, Sanic will teardown the existing process first before starting a new one. +默认情况下，当重启工人时，萨尼克会先拆除现有的进程，然后再开始一个新进程。 -If you are intending to use the restart functionality in production then you may be interested in having zero-downtime reloading. This can be accomplished by forcing the reloader to change the order to start a new process, wait for it to [ack](#worker-ack), and then teardown the old process. +如果您打算在生产中使用重启功能，那么您可能会有兴趣进行零下机刷新。 可以通过强迫读取器改变订单来实现这一点。 等待它到 [ack](#worker-ack), 然后拆除旧的进程。 -.. column:: +.. 列: ``` -From the multiplexer, use the `zero_downtime` argument +从多路程序中，使用 `zero_downtime` 参数 ``` -.. column:: +.. 列: ```` ```python -app.m.restart(zero_downtime=True) +app.m.restt(zero_downtime=True) ``` ```` -_Added in v22.12_ +_在 v22.12中添加_ -## Using shared context between worker processes +## 使用工人流程之间的共享环境 -Python provides a few methods for [exchanging objects](https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between-processes), [synchronizing](https://docs.python.org/3/library/multiprocessing.html#synchronization-between-processes), and [sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-between-processes) between processes. This usually involves objects from the `multiprocessing` and `ctypes` modules. +Python 提供了几种方法用于[交换对象](https\://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between en-processes)、 [synchronizing](https\://docs.python.org/3/library/multiprocessing.html#synization-between process)和[sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-honen-processes) 之间的流程。 这通常涉及来自`multiprocessing` 和 `ctypes` 模块的对象。 -If you are familiar with these objects and how to work with them, you will be happy to know that Sanic provides an API for sharing these objects between your worker processes. If you are not familiar, you are encouraged to read through the Python documentation linked above and try some of the examples before proceeding with implementing shared context. +如果你熟悉这些对象以及如何与它们合作， 你会很乐意知道， Sanic 提供了一个 API 用于在你的工序之间分享这些物体。 如果你不熟悉， 鼓励您阅读以上链接的 Python 文档，然后尝试一些示例，然后执行共享环境。 -Similar to how [application context](../basics/app.md#application-context) allows an applicaiton to share state across the lifetime of the application with `app.ctx`, shared context provides the same for the special objects mentioned above. This context is available as `app.shared_ctx` and should **ONLY** be used to share objects intended for this purpose. +类似于[应用程序上下文](../basics/app.md#application-context)允许应用程序在应用程序整个生命周期内与 `app 共享状态。 tx`, 共享上下文为上述特殊对象提供了相同的内容。 此上下文可用于 `app.shared_ctx` 并且应该**ONLY** 用于共享用于此目的的物体。 -The `shared_ctx` will: +`shared_ctx`将： -- _NOT_ share regular objects like `int`, `dict`, or `list` -- _NOT_ share state between Sanic instances running on different machines -- _NOT_ share state to non-worker processes -- **only** share state between server workers managed by the same Manager +- _NOT_ 共享常规对象，如`int`、`dict`或`list` +- _NOT_ 在不同机器上运行的 Sanic 实例之间共享状态 +- _NOT_ 共享状态到非工序中 +- **仅** 服务器工人之间由同一管理器管理的共享状态 -Attaching an inappropriate object to `shared_ctx` will likely result in a warning, and not an error. You should be careful to not accidentally add an unsafe object to `shared_ctx` as it may not work as expected. If you are directed here because of one of those warnings, you might have accidentally used an unsafe object in `shared_ctx`. +将不恰当对象附加到 "shared_ctx" 可能会导致警告，而不是错误。 您应该小心不要意外添加一个不安全的对象到 "shared_ctx" ，因为它可能无法正常工作。 如果你因为其中一个警告而在这里被指向，你可能会意外地在 "shared_ctx" 中使用不安全的物体。 -.. column:: +.. 列: ``` -In order to create a shared object you **must** create it in the main process and attach it inside of the `main_process_start` listener. +为了创建一个共享对象，你**必须** 在主流程中创建它，并将它附加在`main_process_start`监听器中。 ``` -.. column:: +.. 列: ```` ```python -from multiprocessing import Queue +来自多处理导入队列 @app.main_process_start async def main_process_start(app): @@ -163,38 +163,38 @@ async def main_process_start(app): ``` ```` -Trying to attach to the `shared_ctx` object outside of this listener may result in a `RuntimeError`. +尝试附加到监听器外面的`shared_ctx`对象可能会导致一个 `RuntimeError` 。 -.. column:: +.. 列: ``` -After creating the objects in the `main_process_start` listener and attaching to the `shared_ctx`, they will be available in your workers wherever the application instance is available (example: listeners, middleware, request handlers). +在 `main_process_start` 监听器中创建对象并附加到 `shared_ctx` 之后， 只要有应用程序实例就可以在您的工作人员中使用(例如：监听器、中间器、请求处理器)。 ``` -.. column:: +.. 列: ```` ```python -from multiprocessing import Queue +来自多处理导入队列 @app.get("") -async def handler(request): +async def 处理器(请求): request.app.shared_ctx.queue.put(1) ... ``` ```` -## Access to the multiplexer +## 访问多声道器 -The application instance has access to an object that provides access to interacting with the Manager and other worker processes. The object is attached as the `app.multiplexer` property, but it is more easily accessed by its alias: `app.m`. +应用程序实例可以访问一个对象，它能够提供与经理和其他工人进程互动的权限。 此对象被附加为 `app.multiplexer` 属性，但它更容易被其别名访问：`app.m`。 -.. column:: +.. 列: ``` -For example, you can get access to the current worker state. +例如，您可以访问当前的工人状态。 ``` -.. column:: +.. 列: ```` ```python @@ -211,13 +211,13 @@ Sanic-Server-0-0 ``` ```` -.. column:: +.. 列: ``` -The `multiplexer` also has access to terminate the Manager, or restart worker processes +`multiplexer` 也可以终止管理器或重启工作人员进程 ``` -.. column:: +.. 列: ```` ```python @@ -235,15 +235,15 @@ app.m.name.restart(all_workers=True) # Available v22.12+ ``` ```` -## Worker state +## 工人状态 -.. column:: +.. 列: ``` -As shown above, the `multiplexer` has access to report upon the state of the current running worker. However, it also contains the state for ALL processes running. +如上文所示，`multiplexer`可以报告当前运行的工人的状态。 然而，它也包含所有正在运行的进程的状态。 ``` -.. column:: +.. 列: ```` ```python @@ -273,39 +273,39 @@ async def print_state(request: Request): ``` ```` -The possible states are: +可能的州有： -- `NONE` - The worker has been created, but there is no process yet -- `IDLE` - The process has been created, but is not running yet -- `STARTING` - The process is starting -- `STARTED` - The process has started -- `ACKED` - The process has started and sent an acknowledgement (usually only for server processes) -- `JOINED` - The process has exited and joined the main process -- `TERMINATED` - The process has exited and terminated -- `RESTARTING` - The process is restarting -- `FAILED` - The process encountered an exception and is no longer running -- `COMPLETED` - The process has completed its work and exited successfully +- `NONE` - 工人已被创建，但还没有进程 +- `IDLE` - 进程已创建，但尚未运行 +- `STARTING` - 进程正在开始 +- `STARTED` - 进程已经开始 +- `ACKED` - 进程已经启动并发送了一条确认信息(通常只适用于服务器进程) +- `JOINED` - 该进程已经退出并加入了主要进程 +- `TERNATED` - 该进程已经退出并终止 +- `RESTARTING` - 进程正在重启 +- `FAILED` - 进程遇到异常，已不再运行 +- `COMPLETED` - 该进程已经完成并成功退出 -## Built-in non-server processes +## 内置非服务器进程 -As mentioned, the Manager also has the ability to run non-server processes. Sanic comes with two built-in types of non-server processes, and allows for [creating custom processes](#running-custom-processes). +如上所述，管理员也有能力运行非服务器程序。 Sanic 带有两种内置类型的非服务器进程，并允许[创建自定义进程](#running-custom-processes)。 -The two built-in processes are +两个内置进程是 -- the [auto-reloader](./development.md#automatic-reloader), optionally enabled to watch the file system for changes and trigger a restart -- [inspector](#inspector), optionally enabled to provide external access to the state of the running instance +- [auto-reloader](./development.md#automatic-reloader) 可选地启用监视文件系统进行更改并触发重启 +- [inspector](#spector), 可选地启用提供外部访问的运行实例状态 -## Inspector +## 检查员 -Sanic has the ability to expose the state and the functionality of the `multiplexer` to the CLI. Currently, this requires the CLI command to be run on the same machine as the running Sanic instance. By default the inspector is disabled. +Sanic 有能力在 CLI 中暴露`multiplexer` 的状态和功能。 目前，这需要在 CLI 命令上运行与运行中的 Sanic 实例相同的机器。 默认情况下，检查员被禁用。 -.. column:: +.. 列: ``` -To enable it, set the config value to `True`. +要启用它，请将配置值设置为“True”。 ``` -.. column:: +.. 列: ```` ```python @@ -313,47 +313,47 @@ app.config.INSPECTOR = True ``` ```` -You will now have access to execute any of these CLI commands: +您现在可以访问这些CLI命令： ``` -sanic inspect reload Trigger a reload of the server workers -sanic inspect shutdown Shutdown the application and all processes -sanic inspect scale N Scale the number of workers to N -sanic inspect Run a custom command +净化检查重新加载服务器工作人员的一次重新加载 +净化检查关闭应用程序和所有进程 +净化检查员将工人人数缩放到N +净化检查 运行一个自定义命令 ``` ![](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) -.. column:: +.. 列: ``` -This works by exposing a small HTTP service on your machine. You can control the location using configuration values: +通过在您的机器上显示一个小的 HTTP 服务来实现这一点。您可以使用配置值控制位置： ``` -.. column:: +.. 列: ```` ```python -app.config.INSPECTOR_HOST = "localhost" -app.config.INSPECTOR_PORT = 6457 +app.config.INSPECTOR_HOST = "localhost" +app.config.INSPECTOR_PORT = 6457 ``` ```` -[Learn more](./inspector.md) to find out what is possible with the Inspector. +[了解更多](./检查员.md)来了解与检查员可能做些什么。 -## Running custom processes +## 运行自定义进程 -To run a managed custom process on Sanic, you must create a callable. If that process is meant to be long-running, then it should handle a shutdown call by a `SIGINT` or `SIGTERM` signal. +若要在 Sanic 上运行一个管理下的自定义进程，您必须创建一个可调用。 如果这个进程是打算长期运行的，那么它就应该用一个`SIGINT`或`SIGTERM`的信号来处理一个关机呼叫。 -.. column:: +.. 列: ``` -The simplest method for doing that in Python will be to just wrap your loop in `KeyboardInterrupt`. +Python最简单的方法是把你的循环换成`KeyboardInterrupt'。 -If you intend to run another application, like a bot, then it is likely that it already has capability to handle this signal and you likely do not need to do anything. +如果您打算运行另一个应用程序，像机器人那样， 然后，它很可能已经有能力处理这个信号，而且你可能不需要做任何事情。 ``` -.. column:: +.. 列: ```` ```python @@ -368,26 +368,26 @@ def my_process(foo): ``` ```` -.. column:: +.. 列: ``` -That callable must be registered in the `main_process_ready` listener. It is important to note that is is **NOT** the same location that you should register [shared context](#using-shared-context-between-worker-processes) objects. +此可调用必须在 `main_process_ready` 监听器中注册。 必须注意的是，**不** 是你应该注册[共享上下文](#使用共享上下文-工人之间的过程)对象的同一地点。 ``` -.. column:: +.. 列: ```` ```python @app.main_process_ready async def ready(app: Sanic, _): -# app.manager.manage(, , ) - app.manager.manage("MyProcess", my_process, {"foo": "bar"}) +# app.manager.manager.manag(, , ) + app.manager.manager.management("MyProcess", my_proces", {"foo": "bar"}) ``` ```` -### Transient v. durable processes +### B. 过渡时期与持久进程 -.. column:: +.. 列: ``` When you manage a process with the `manage` method, you have the option to make it transient or durable. A transient process will be restarted by the auto-reloader, and a durable process will not. @@ -395,24 +395,24 @@ When you manage a process with the `manage` method, you have the option to make By default, all processes are durable. ``` -.. column:: +.. 列: ```` ```python @app.main_process_ready async def ready(app: Sanic, _): - app.manager.manage( + app.manager.manager.management( "MyProcess", my_process, {"foo": "bar"}, - transient=True, + transitent=True, ) ``` ```` -### Tracked v. untracked processes +### 跟踪或未跟踪的进程 -.. new:: v23.12 +.. 新：v23.12 ``` Out of the box, Sanic will track the state of all processes. This means that you can access the state of the process from the [multiplexer](./manager#access-to-the-multiplexer) object, or from the [Inspector](./manager#inspector). @@ -422,20 +422,20 @@ See [worker state](./manager#worker-state) for more information. Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. ``` -.. column:: +.. 列: ``` -When you are running a non-long-running process, you can opt out of tracking it by setting `tracked=False` in the `manage` method. This means that upon completion of the process it will be removed from the list of tracked processes. You will only be able to check the state of the process while it is running. +当你正在运行一个非长期运行的过程时，你可以在"管理"方法中设置 "tracked=False" 来选择不跟踪它。 这意味着一旦完成这一进程，它将从跟踪的进程清单中删除。 您只能在进程运行时检查进程状态。 ``` -.. column:: +.. 列: ```` ```python @app.main_process_ready async def ready(app: Sanic, _): - app.manager.manage( - "OneAndDone", + app.manager.manager.manage( + "One AndDone", do_once, {}, tracked=False, @@ -443,97 +443,97 @@ async def ready(app: Sanic, _): ``` ```` -_Added in v23.12_ +_添加于 v23.12_ -### Restartable custom processes +### 可重新启动自定义进程 -.. new:: v23.12 +.. 新：v23.12 ``` -A custom process that is transient will **always** be restartable. That means the auto-restart will work as expected. However, what if you want to be able to *manually* restart a process, but not have it be restarted by the auto-reloader? +临时性的自定义进程将**总是可以重启。这意味着自动重启将会如预期的那样正常工作。 然而，如果你想要能够*手动*重新启动一个过程，但它不会被自动重新加载器重新启动？ ``` -.. column:: +.. 列: ``` -In this scenario, you can set `restartable=True` in the `manage` method. This will allow you to manually restart the process, but it will not be restarted by the auto-reloader. +在这个场景中，你可以在“管理”方法中设置 `rehartable=True`。 这将允许您手动重启进程，但它不会被自动重新加载器重启。 ``` -.. column:: +.. 列: ```` ```python @app.main_process_ready async def ready(app: Sanic, _): - app.manager.manage( + app.manager.manager.management( "MyProcess", my_process, {"foo": "bar"}, - restartable=True, + restable=True, ) ``` ```` -.. column:: +.. 列: ``` -You could now manually restart that process from the multiplexer. +您现在可以从多路程序手动重启此进程。 ``` -.. column:: +.. 列: ```` ```python @app.get("/restart") -async def restart_handler(request: Request): - request.app.m.restart("Sanic-MyProcess-0") +async def restest_handler(request: acquest): + request.app.m.restt("Sanic-MyProcess-0") return json({"foo": request.app.m.name}) ``` ```` -_Added in v23.12_ +_添加于 v23.12_ -### On the fly process management +### 飞行过程管理 -.. new:: v23.12 +.. 新：v23.12 ``` -Custom processes are usually added in the `main_process_ready` listener. However, there may be times when you want to add a process after the application has started. For example, you may want to add a process from a request handler. The multiplexer provides a method for doing this. +自定义进程通常在 `main_process_ready` 监听器中添加。 然而，有时候您想要在应用程序启动后添加一个过程。 例如，您可能想要从请求处理器中添加一个进程。多路程序提供了这样做的方法。 ``` -.. column:: +.. 列: ``` -Once you have a reference to the multiplexer, you can call `manage` to add a process. It works the same as the `manage` method on the Manager. +一旦你有一个多路由器的引用，你可以调用 `manage` 来添加一个过程。 它与经理上的 `manag` 方法相同。 ``` -.. column:: +.. 列: ```` ```python @app.post("/start") -async def start_handler(request: Request): - request.app.m.manage( - "MyProcess", +async def start_handler(request): + request.app.m. anage( + "我的过程", my_process, {"foo": "bar"}, workers=2, - ) - return json({"foo": request.app.m.name}) + + return json({"foo": request. pweb name}) ``` ```` -_Added in v23.12_ +_添加于 v23.12_ -## Single process mode +## 单进程模式 -.. column:: +.. 列: ``` -If you would like to opt out of running multiple processes, you can run Sanic in a single process only. In this case, the Manager will not run. You will also not have access to any features that require processes (auto-reload, the inspector, etc). +如果你想要退出运行多个进程，你只能在一个进程中运行 Sanic。 在这种情况下，管理员不会运行。 您也无法访问任何需要处理的功能 (自动重新加载、检查员等)。 ``` -.. column:: +.. 列: ```` ```sh @@ -550,33 +550,33 @@ if __name__ == "__main__": ``` ```` -## Sanic and multiprocessing +## 声学和多处理器 -Sanic makes heavy use of the [`multiprocessing` module](https://docs.python.org/3/library/multiprocessing.html) to manage the worker processes. You should generally avoid lower level usage of this module (like setting the start method) as it may interfere with the functionality of Sanic. +Sanic大量使用 [`multiprocessing` 模块](https://docs.python.org/3/library/multiprocessing.html) 来管理工人过程。 您通常应该避免低级别使用此模块(例如设置起始方法)，因为它可能会干扰Sanic的功能。 -### Start methods in Python +### 在 Python 中启动方法 -Before explaining what Sanic tries to do, it is important to understand what the `start_method` is and why it is important. Python generally allows for three different methods of starting a process: +在解释萨尼克试图做什么之前，必须了解`start_method`是什么以及为什么它是重要的。 Python通常允许三种不同的方法启动进程： - `fork` - `spawn` - `forkserver` -The `fork` and `forkserver` methods are only available on Unix systems, and `spawn` is the only method available on Windows. On Unix systems where you have a choice, `fork` is generally the default system method. +"fork" 和 "forkserver" 方法仅在 Unix 系统上可用，而"spawn" 是Windows上唯一可用的方法。 在您可以选择的 Unix 系统中，`fork` 通常是默认系统方法。 -You are encouraged to read the [Python documentation](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) to learn more about the differences between these methods. However, the important thing to know is that `fork` basically copies the entire memory of the parent process into the child process, whereas `spawn` will create a new process and then load the application into that process. This is the reason why you need to nest your Sanic `run` call inside of the `__name__ == "__main__"` block if you are not using the CLI. +鼓励您阅读[Python文档](https://docs.python.org/3/library/multiprocessing.html#contextsand-start-methods)，了解更多关于这些方法之间差异的信息。 然而，重要的是`fork`基本上将父过程的整个记忆复制到子过程中。 而`spawn`会创建一个新的流程，然后将应用程序加载到该流程中。 This is the reason why you need to nest your Sanic `run` call inside of the `__name__ == "__main__"` block if you are not using the CLI. -### Sanic and start methods +### 智能和启动方法 -By default, Sanic will try and use `spawn` as the start method. This is because it is the only method available on Windows, and it is the safest method on Unix systems. +默认情况下，Sanic会尝试使用 `spawn` 作为起始方法。 这是因为它是Windows上唯一可用的方法，它是Unix系统上最安全的方法。 -.. column:: +.. 列: ``` -However, if you are running Sanic on a Unix system and you would like to use `fork` instead, you can do so by setting the `start_method` on the `Sanic` class. You will want to do this as early as possible in your application, and ideally in the global scope before you import any other modules. +然而，如果你在 Unix 系统上运行 Sanic 而你想使用 `fork` 你可以通过设置 `Sanic` 类的 `start_method` 来做到这一点。 您将尽早在您的应用程序中，并且最好是在全局范围内，然后再导入任何其他模块。 ``` -.. column:: +.. 列: ```` ```python @@ -586,23 +586,23 @@ Sanic.start_method = "fork" ``` ```` -### Overcoming a `RuntimeError` +### 覆盖一个 `RuntimeError` -You might have received a `RuntimeError` that looks like this: +您可能已经收到了一个看起来像这样的 `RuntimeError` ： ``` -RuntimeError: Start method 'spawn' was requested, but 'fork' was already set. +运行时错误：请求了开始方法“spawn”，但“fork”已经设置。 ``` -If so, that means somewhere in your application you are trying to set the start method that conflicts with what Sanic is trying to do. You have a few options to resolve this: +如果是，这意味着你在应用程序中的某个地方试图设置与萨尼克试图做什么相冲突的起始方法。 您有几个选项来解决这个问题： -.. column:: +.. 列: ``` -**OPTION 1:** You can tell Sanic that the start method has been set and to not try and set it again. +**选项1:** 你可以告诉Sanic, 开始方法已经设置, 不要再尝试. ``` -.. column:: +.. 列: ```` ```python @@ -612,13 +612,13 @@ Sanic.START_METHOD_SET = True ``` ```` -.. column:: +.. 列: ``` -**OPTION 2:** You could tell Sanic that you intend to use `fork` and to not try and set it to `spawn`. +**选项2：** 你可以告诉Sanic你打算使用 `fork` 而不尝试设置为 `spawn` 。 ``` -.. column:: +.. 列: ```` ```python @@ -628,13 +628,13 @@ Sanic.start_method = "fork" ``` ```` -.. column:: +.. 列: ``` -**OPTION 3:** You can tell Python to use `spawn` instead of `fork` by setting the `multiprocessing` start method. +**选项3：** 您可以通过设置 `multiprocessing` 开始方法，告诉Python 使用 `spawn` 而不是 `fork` 。 ``` -.. column:: +.. 列: ```` ```python @@ -644,9 +644,9 @@ multiprocessing.set_start_method("spawn") ``` ```` -In any of these options, you should run this code as early as possible in your application. Depending upon exactly what your specific scenario is, you may need to combine some of the options. +在这些选项中，您应该尽早在应用程序中运行此代码。 根据具体的场景，您可能需要合并一些选项。 -.. note:: +.. 注： ```` The potential issues that arise from this problem are usually easily solved by just allowing Sanic to be in charge of multiprocessing. This usually means making use of the `main_process_start` and `main_process_ready` listeners to deal with multiprocessing issues. For example, you should move instantiating multiprocessing primitives that do a lot of work under the hood from the global scope and into a listener. From 294e15901bd75c69928b88aba728c44f3dbcf3cb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:22 +0200 Subject: [PATCH 377/698] New translations running.md (Japanese) --- guide/content/ja/guide/running/running.md | 246 +++++++++++----------- 1 file changed, 123 insertions(+), 123 deletions(-) diff --git a/guide/content/ja/guide/running/running.md b/guide/content/ja/guide/running/running.md index 4be2300da5..6f8a923b6f 100644 --- a/guide/content/ja/guide/running/running.md +++ b/guide/content/ja/guide/running/running.md @@ -1,20 +1,20 @@ --- -title: Running Sanic +title: 実行中のサニック --- -# Running Sanic +# 実行中のサニック -Sanic ships with its own internal web server. Under most circumstances, this is the preferred method for deployment. In addition, you can also deploy Sanic as an ASGI app bundled with an ASGI-able web server. +Sanicは独自の内部Webサーバーを搭載しています。 ほとんどの状況では、これはデプロイに最適な方法です。 また、SanicをASGI対応のWebサーバーにバンドルされたASGIアプリとしてデプロイすることもできます。 ## Sanic Server -The main way to run Sanic is to use the included [CLI](#sanic-cli). +Sanicを走る主な方法は、付属の [CLI](#sanic-cli)を使うことです。 ```sh sanic path.to.server:app ``` -In this example, Sanic is instructed to look for a python module called `path.to.server`. Inside of that module, it will look for a global variable called `app`, which should be an instance of `Sanic(...)`. +この例では、Sanicは`path.to.server`というPythonモジュールを探すように指示されています。 このモジュールの中では、`app`という名前のグローバル変数を探します。これは、`Sanic(...)`のインスタンスでなければなりません。 ```python # ./path/to/server.py @@ -27,37 +27,37 @@ async def handler(request: Request): return json({"foo": "bar"}) ``` -You may also dropdown to the [lower level API](#low-level-apprun) to call `app.run` as a script. However, if you choose this option you should be more comfortable handling issues that may arise with `multiprocessing`. +`app.run` をスクリプトとして呼び出すには、format@@0(#low-level-apprun) にドロップダウンすることもできます。 ただし、このオプションを選択した場合は、 `multiprocessing` で発生する可能性のある問題をより快適に処理する必要があります。 -### Workers +### Worker -.. column:: +.. 列:: ``` -By default, Sanic runs a main process and a single worker process (see [worker manager](./manager.md) for more details). +デフォルトでは、Sanicはメインプロセスと単一のワーカープロセスを実行します([worker manager](./manager)を参照してください)。 d) 詳細については)。 -To crank up the juice, just specify the number of workers in the run arguments. +ジュースをクランクアップするには、実行引数に含まれるワーカーの数を指定します。 ``` -.. column:: +.. 列:: ```` ```sh -sanic server:app --host=0.0.0.0 --port=1337 --workers=4 +sanic server:app --host=0.0.0.0 --port=1337 --works=4 ``` ```` -Sanic will automatically spin up multiple processes and route traffic between them. We recommend as many workers as you have available processors. +Sanicは自動的に複数のプロセスとそれらの間のルートトラフィックを回します。 利用可能なプロセッサを持っている数だけの労働者をお勧めします。 -.. column:: +.. 列:: ``` -The easiest way to get the maximum CPU performance is to use the `--fast` option. This will automatically run the maximum number of workers given the system constraints. +最大CPUパフォーマンスを得る最も簡単な方法は、 `--fast` オプションを使用することです。 これは自動的にシステム制約を与えられたワーカーの最大数を実行します。 -*Added in v21.12* +*v21.12* に追加されました ``` -.. column:: +.. 列:: ```` ```sh @@ -65,17 +65,17 @@ sanic server:app --host=0.0.0.0 --port=1337 --fast ``` ```` -In version 22.9, Sanic introduced a new worker manager to provide more consistency and flexibility between development and production servers. Read [about the manager](./manager.md) for more details about workers. +バージョン22.9では、Sanicは開発サーバーと本番サーバーの間でより一貫性と柔軟性を提供する新しいワーカーマネージャを導入しました。 format@@0(./manager.md) を読んで、worker の詳細を確認してください。 -.. column:: +.. 列:: ``` -If you only want to run Sanic with a single process, specify `single_process` in the run arguments. This means that auto-reload, and the worker manager will be unavailable. +Sanicを単一のプロセスでのみ実行したい場合は、run引数に`single_process`を指定します。 これは自動再読み込みを行い、ワーカーマネージャーが利用できなくなることを意味します。 -*Added in v22.9* +*v22.9* に追加されました ``` -.. column:: +.. 列:: ```` ```sh @@ -83,11 +83,11 @@ sanic server:app --host=0.0.0.0 --port=1337 --single-process ``` ```` -### Running via command +### コマンドで実行 #### Sanic CLI -Use `sanic --help` to see all the options. +すべてのオプションを見るには `sanic --help` を使います。 .. attrs:: :title: Sanic CLI help output @@ -189,33 +189,33 @@ Optional ``` ```` -#### As a module +#### モジュールとして -.. column:: +.. 列:: ``` -Sanic applications can also be called directly as a module. +Sanic アプリケーションはモジュールとして直接呼び出すこともできます。 ``` -.. column:: +.. 列:: ```` ```bash -python -m sanic server.app --host=0.0.0.0 --port=1337 --workers=4 +python -m sanic server.app --host=0.0.0.0 --port=1337 --works=4 ``` ```` -#### Using a factory +#### 工場の利用 -A very common solution is to develop your application _not_ as a global variable, but instead using the factory pattern. In this context, "factory" means a function that returns an instance of `Sanic(...)`. +非常に一般的な解決策は、アプリケーションをグローバル変数としてではなく\*開発することですが、代わりにファクトリパターンを使用することです。 この文脈で、"factory"とは、`Sanic(...)`のインスタンスを返す関数を意味します。 -.. column:: +.. 列:: ``` -Suppose that you have this in your `server.py` +`server.py`にこれがあるとします。 ``` -.. column:: +.. 列:: ```` ```python @@ -228,13 +228,13 @@ def create_app() -> Sanic: ``` ```` -.. column:: +.. 列:: ``` -You can run this application now by referencing it in the CLI explicitly as a factory: +このアプリケーションは、CLIで明示的にファクトリとして参照することで実行できます。 ``` -.. column:: +.. 列:: ```` ```sh @@ -252,17 +252,17 @@ sanic server:create_app *Implicit command added in v23.3* ```` -### Low level `app.run` +### 低レベル `app.run` -When using `app.run` you will just call your Python file like any other script. +`app.run`を使用する場合は、他のスクリプトと同様にPythonファイルを呼び出します。 -.. column:: +.. 列:: ``` -`app.run` must be properly nested inside of a name-main block. +`app.run` は name-main ブロックの中に正しく入れ子にする必要があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -274,7 +274,7 @@ if __name__ == "__main__": ``` ```` -.. danger:: +.. 危険:: ```` Be *careful* when using this pattern. A very common mistake is to put too much logic inside of the `if __name__ == "__main__":` block. @@ -309,39 +309,39 @@ elif __name__ == "__main__": ``` ```` -To use the low-level `run` API, after defining an instance of `sanic.Sanic`, we can call the run method with the following keyword arguments: +低レベルの`run` APIを使用するには、`sanic.Sanic`のインスタンスを定義した後、以下のキーワード引数を使用してrunメソッドを呼び出すことができます。 -| Parameter | Default | Description | -| :---------------------------------------: | :--------------: | :---------------------------------------------------------------------------------------- | -| **host** | `"127.0.0.1"` | Address to host the server on. | -| **port** | `8000` | Port to host the server on. | -| **unix** | `None` | Unix socket name to host the server on (instead of TCP). | -| **dev** | `False` | Equivalent to `debug=True` and `auto_reload=True`. | -| **debug** | `False` | Enables debug output (slows server). | -| **ssl** | `None` | SSLContext for SSL encryption of worker(s). | -| **sock** | `None` | Socket for the server to accept connections from. | -| **workers** | `1` | Number of worker processes to spawn. Cannot be used with fast. | -| **loop** | `None` | An asyncio-compatible event loop. If none is specified, Sanic creates its own event loop. | -| **protocol** | `HttpProtocol` | Subclass of asyncio.protocol. | -| **version** | `HTTP.VERSION_1` | The HTTP version to use (`HTTP.VERSION_1` or `HTTP.VERSION_3`). | -| **access_log** | `True` | Enables log on handling requests (significantly slows server). | -| **auto_reload** | `None` | Enables auto-reload on the source directory. | -| **reload_dir** | `None` | A path or list of paths to directories the auto-reloader should watch. | -| **noisy_exceptions** | `None` | Whether to set noisy exceptions globally. None means leave as default. | -| **motd** | `True` | Whether to display the startup message. | -| **motd_display** | `None` | A dict with extra key/value information to display in the startup message | -| **fast** | `False` | Whether to maximize worker processes. Cannot be used with workers. | -| **verbosity** | `0` | Level of logging detail. Max is 2. | -| **auto_tls** | `False` | Whether to auto-create a TLS certificate for local development. Not for production. | -| **single_process** | `False` | Whether to run Sanic in a single process. | +| パラメータ | デフォルト | 説明 | +| :---------------------------------------: | :--------------: | :--------------------------------------------------------------------------- | +| **ホスト** | `"127.0.0.1"` | サーバーをホストするためのアドレス。 | +| **ポート** | `8000` | サーバーをホストするためのポート。 | +| **unix** | `なし` | (TCP の代わりに) サーバーをホストする Unix ソケット名。 | +| **dev** | `False` | `debug=True`と`auto_reload=True`と同じです。 | +| **debug** | `False` | デバッグ出力を有効にします(サーバーを遅くします)。 | +| **ssl** | `なし` | ワーカーの SSL 暗号化の SSLContext です。 | +| **sock** | `なし` | サーバーが接続を受け入れるソケット。 | +| **works** | `1` | spawn するワーカープロセスの数。 高速では使用できません。 | +| **ループ** | `なし` | 非同期互換イベントループ。 何も指定されていない場合、Sanic は独自のイベントループを作成します。 | +| **protocol** | `HttpProtocol` | asyncio.protocolのサブクラス。 | +| **バージョン** | `HTTP.VERSION_1` | 使用する HTTP バージョン (`HTTP.VERSION_1` または `HTTP.VERSION_3` )。 | +| **access_log** | `True` | リクエスト処理時にログを有効にします（サーバーが大幅に遅くなります）。 | +| **auto_reload** | `なし` | ソースディレクトリの自動リロードを有効にします。 | +| **reload_dir** | `なし` | 自動リローダーが監視すべきディレクトリへのパスまたはリスト。 | +| **noisy_exceptions** | `なし` | 騒々しい例外をグローバルに設定するかどうか。 はいずれもデフォルトのままにします。 | +| **motd** | `True` | 起動時のメッセージを表示するかどうかを設定します。 | +| **motd_display** | `なし` | スタートアップメッセージに表示する追加のキー/値情報を持つディクト | +| **fast** | `False` | ワーカープロセスを最大化するかどうか。 ワーカーでは使用できません。 | +| **verbosity** | `0` | ログの詳細レベル。 最大は 2 です。 | +| **auto_tls** | `False` | ローカル開発用の TLS 証明書を自動作成するかどうか。 生産のためではありません。 | +| **single_process** | `False` | 単一のプロセスでSanicを実行するかどうか。 | -.. column:: +.. 列:: ``` -For example, we can turn off the access log in order to increase performance, and bind to a custom host and port. +たとえば、パフォーマンスを向上させるためにアクセスログをオフにし、カスタムホストとポートにバインドすることができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -353,13 +353,13 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列:: ``` -Now, just execute the python script that has `app.run(...)` +`app.run(...)`を持つPythonスクリプトを実行してください。 ``` -.. column:: +.. 列:: ```` ```sh @@ -367,15 +367,15 @@ python server.py ``` ```` -For a slightly more advanced implementation, it is good to know that `app.run` will call `app.prepare` and `Sanic.serve` under the hood. +もう少し高度な実装では、 `app.run` は `app.prepare` と `Sanic.serve` をフードの下で呼び出すことを知っておくと良いでしょう。 -.. column:: +.. 列:: ``` -Therefore, these are equivalent: +したがって、これらは等価です: ``` -.. column:: +.. 列:: ```` ```python @@ -389,33 +389,33 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列:: ``` -This can be useful if you need to bind your appliction(s) to multiple ports. +アプリケーションを複数のポートにバインドする必要がある場合に便利です。 ``` -.. column:: +.. 列:: ```` ```python if __name__ == "__main__": app1.prepare(host='0.0.0.0', port=9990) app1.prepare(host='0.0.0.0', port=9991) - app2.prepare(host='0.0.0.0', port=5555) + app2.prepare(host='0.0.0.0', port=555555) Sanic.serve() ``` ```` ### Sanic Simple Server -.. column:: +.. 列:: ``` -Sometimes you just have a directory of static files that need to be served. This especially can be handy for quickly standing up a localhost server. Sanic ships with a Simple Server, where you only need to point it at a directory. +場合によっては、提供する必要がある静的ファイルのディレクトリがあります。 特に、localhostサーバーを素早く立ち上げるのに便利です。 Sanic shipにはシンプルなサーバーがあり、ディレクトリにそれを指すだけで済みます。 ``` -.. column:: +.. 列:: ```` ```sh @@ -423,25 +423,25 @@ sanic ./path/to/dir --simple ``` ```` -.. column:: +.. 列:: ``` -This could also be paired with auto-reloading. +これは自動リロードと組み合わせることもできます。 ``` -.. column:: +.. 列:: ```` ```sh -sanic ./path/to/dir --simple --reload --reload-dir=./path/to/dir +sanic ./path/to/dir --simple -reload -reload-dir=./path/to/dir ``` ```` -_Added in v21.6_ +_V21.6_に追加されました ### HTTP/3 -Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed to use HTTP/3: +Sanic server provides HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). HTTP/3を使用するには**インストールする必要があります** ```sh pip install sanic aioquic @@ -451,9 +451,9 @@ pip install sanic aioquic pip install sanic[http3] ``` -To start HTTP/3, you must explicitly request it when running your application. +HTTP/3 を開始するには、アプリケーションの実行時に明示的にリクエストする必要があります。 -.. column:: +.. 列:: ```` ```sh @@ -465,7 +465,7 @@ sanic path.to.server:app -3 ``` ```` -.. column:: +.. 列:: ```` ```python @@ -473,13 +473,13 @@ app.run(version=3) ``` ```` -To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](../release-notes/v22.3.html#application-multi-serve) introduced in v22.3. This will automatically add an [Alt-Svc](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc) header to your HTTP/1.1 requests to let the client know that it is also available as HTTP/3. +HTTP/3 と HTTP/1.1 の両方のサーバーを同時に実行するには、v22.3 で導入された [application multi-serve] (../release-notes/v22.3.html#application-multi-serve) を使用します。 これにより自動的に [Alt-Svc](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc) ヘッダーがHTTP/1.1 リクエストに追加され、クライアントにHTTP/3 としても利用可能であることを知らせます。 -.. column:: +.. 列:: ```` ```sh -sanic path.to.server:app --http=3 --http=1 +sanic path.to.server:app --http=3 -http=1 ``` ```sh @@ -487,7 +487,7 @@ sanic path.to.server:app -3 -1 ``` ```` -.. column:: +.. 列:: ```` ```python @@ -497,21 +497,21 @@ Sanic.serve() ``` ```` -Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. See [development](./development.md) for more details. +HTTP/3 は TLS を必要とするため、TLS 証明書なしでは HTTP/3 サーバーを起動できません。 `DEBUG`モードの場合は、format@@0(../how-to/tls.html) または `mkcert` を使用してください。 現在、HTTP/3 に対する自動的な TLS 設定は `trustme` と互換性がありません。 詳細は [development](./development.md) を参照してください。 -_Added in v22.6_ +_v22.6_に追加されました ## ASGI -Sanic is also ASGI-compliant. This means you can use your preferred ASGI webserver to run Sanic. The three main implementations of ASGI are [Daphne](http://github.com/django/daphne), [Uvicorn](https://www.uvicorn.org/), and [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html). +SanicもASGIに準拠しています。 つまり、ご希望のASGIウェブサーバーを使用してSanicを実行することができます。 ASGI の 3 つの主な実装は [Daphne](http://github.com/django/daphne), [Uvicorn](https://www.uvicorn.org/), および [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html) です。 -.. warning:: +.. 警告:: ``` -Daphne does not support the ASGI `lifespan` protocol, and therefore cannot be used to run Sanic. See [Issue #264](https://github.com/django/daphne/issues/264) for more details. +DaphneはASGIの`lifespan`プロトコルをサポートしていないため、Sanicを実行するために使用することはできません。詳細は[課題 264](https://github.com/django/daphne/issues/264)を参照してください。 ``` -Follow their documentation for the proper way to run them, but it should look something like: +適切な実行方法については、ドキュメントに従ってください。しかし、次のようになります。 ```sh uvicorn myapp:app @@ -521,46 +521,46 @@ uvicorn myapp:app hypercorn myapp:app ``` -A couple things to note when using ASGI: +ASGIを使用する場合、いくつか注意すべきことがあります: -1. When using the Sanic webserver, websockets will run using the `websockets` package. In ASGI mode, there is no need for this package since websockets are managed in the ASGI server. -2. The ASGI lifespan protocol https\://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. +1. Sanic ウェブサーバを使用する場合、websocketsは`websockets`パッケージを使用して実行されます。 ASGI モードでは、ウェブソケットは ASGI サーバで管理されるため、このパッケージは必要ありません。 +2. ASGIの寿命プロトコル https\://asgi.readthedocs.io/en/latest/specs/lifespan.htmlは、起動とシャットダウンの2つのサーバーイベントのみをサポートしています。 Sanicは、起動前、起動後、シャットダウン前、シャットダウン後の4つを持っています。 したがって、ASGIモードで 起動イベントとシャットダウンイベントは連続して実行され、実際にはサーバープロセスの開始と終了の周りには実行されません(それ以降はASGIサーバーによって制御されます)。 ですから、`after_server_start` と `before_server_stop` を使うのがベストです。 -### Trio +### トリオ -Sanic has experimental support for running on Trio with: +SanicはTrioでの実行を実験的にサポートしています。 ```sh hypercorn -k trio myapp:app ``` -## Gunicorn +## グニコーン -[Gunicorn](http://gunicorn.org/) ("Green Unicorn") is a WSGI HTTP Server for UNIX based operating systems. It is a pre-fork worker model ported from Ruby’s Unicorn project. +[Gunicorn](http://gunicorn.org/) ("Green Unicorn") は UNIX ベースのオペレーティングシステム用の WSGI HTTP Server です。 これは、RubyのUnicornプロジェクトから移植されたpre-forkワーカーモデルです。 -In order to run Sanic application with Gunicorn, you need to use it with the adapter from [uvicorn](https://www.uvicorn.org/). Make sure uvicorn is installed and run it with `uvicorn.workers.UvicornWorker` for Gunicorn worker-class argument: +SanicalアプリケーションをGunicornで実行するには、 [uvicorn](https://www.uvicorn.org/)のアダプターで使用する必要があります。 uvicornがインストールされていることを確認し、Gunicorn.worker.UvicornWorker\`でGunicornワーカークラスの引数を実行します: ```sh -gunicorn myapp:app --bind 0.0.0.0:1337 --worker-class uvicorn.workers.UvicornWorker +gunicorn myapp:app --bind 0.0.0.0.0:1337 --worker-class uvicorn.worker.UvicornWorker ``` -See the [Gunicorn Docs](http://docs.gunicorn.org/en/latest/settings.html#max-requests) for more information. +詳細は [Gunicorn Docs](http://docs.gunicorn.org/en/latest/settings.html#max-requests) を参照してください。 -.. warning:: +.. 警告:: ``` -It is generally advised to not use `gunicorn` unless you need it. The Sanic Server is primed for running Sanic in production. Weigh your considerations carefully before making this choice. Gunicorn does provide a lot of configuration options, but it is not the best choice for getting Sanic to run at its fastest. +一般的には、必要な場合以外は `gunicorn` を使用しないことをお勧めします。 Sanic Serverは、本番環境でSanicを実行するためにプライミングされています。この選択を行う前に、慎重に考慮事項を検討してください。 Gunicornは多くの設定オプションを提供しますが、Sanicを最速で走らせるための最良の選択ではありません。 ``` -## Performance considerations +## パフォーマンスに関する考慮事項 -.. column:: +.. 列:: ``` -When running in production, make sure you turn off `debug`. +本番環境で実行する場合は、`debug` をオフにしてください。 ``` -.. column:: +.. 列:: ```` ```sh @@ -568,15 +568,15 @@ sanic path.to.server:app ``` ```` -.. column:: +.. 列:: ``` -Sanic will also perform fastest if you turn off `access_log`. +`access_log` をオフにすると、Sanicも最速に動作します。 -If you still require access logs, but want to enjoy this performance boost, consider using [Nginx as a proxy](./nginx.md), and letting that handle your access logging. It will be much faster than anything Python can handle. +まだアクセスログが必要で、このパフォーマンスを向上させたい場合は、[Nginx をプロキシとして使用することを検討してください](。 nginx.md)、そしてアクセスログを処理させます。Pythonが扱えるどんなものよりもずっと速くなります。 ``` -.. column:: +.. 列:: ```` ```sh From bc38d409b00302c946a82a9cf8969b3afbfcaf45 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:24 +0200 Subject: [PATCH 378/698] New translations running.md (Chinese Simplified) --- guide/content/zh/guide/running/running.md | 258 +++++++++++----------- 1 file changed, 129 insertions(+), 129 deletions(-) diff --git a/guide/content/zh/guide/running/running.md b/guide/content/zh/guide/running/running.md index 4be2300da5..86f2f029f9 100644 --- a/guide/content/zh/guide/running/running.md +++ b/guide/content/zh/guide/running/running.md @@ -1,37 +1,37 @@ --- -title: Running Sanic +title: 正在运行 Sanic --- -# Running Sanic +# 正在运行 Sanic -Sanic ships with its own internal web server. Under most circumstances, this is the preferred method for deployment. In addition, you can also deploy Sanic as an ASGI app bundled with an ASGI-able web server. +Sanic船上有自己的网络服务器。 在大多数情况下，这是最好的部署方法。 此外，您还可以将 Sanic 部署为 ASGI 应用，并且将其绑定到 ASGI-able Web 服务器。 -## Sanic Server +## Sanic 服务器 -The main way to run Sanic is to use the included [CLI](#sanic-cli). +运行Sanic的主要方式是使用包含 [CLI](#sanic-clik). ```sh sanic path.to.server:app ``` -In this example, Sanic is instructed to look for a python module called `path.to.server`. Inside of that module, it will look for a global variable called `app`, which should be an instance of `Sanic(...)`. +在这个示例中，已指示Sanic寻找一个名为 `path.to.server` 的 python 模块。 在该模块中，它将寻找一个叫做`app`的全球变量，它应该是`Sanic(...)`的实例。 ```python # ./path/to/server.py -from sanic import Sanic, Request, json +来自Sanic import Sanic, Request, json app = Sanic("TestApp") @app.get("/") -async def handler(request: Request): +async def handler(request): return json({"foo": "bar"}) ``` -You may also dropdown to the [lower level API](#low-level-apprun) to call `app.run` as a script. However, if you choose this option you should be more comfortable handling issues that may arise with `multiprocessing`. +你也可以下拉到[较低级别的 API](#low-level-apprun)来调用 `app.run` 作为脚本。 然而，如果您选择此选项，您应该比较舒适地处理可能因“多处理”而产生的问题。 -### Workers +### A. 工 人 -.. column:: +.. 列: ``` By default, Sanic runs a main process and a single worker process (see [worker manager](./manager.md) for more details). @@ -39,7 +39,7 @@ By default, Sanic runs a main process and a single worker process (see [worker m To crank up the juice, just specify the number of workers in the run arguments. ``` -.. column:: +.. 列: ```` ```sh @@ -47,17 +47,17 @@ sanic server:app --host=0.0.0.0 --port=1337 --workers=4 ``` ```` -Sanic will automatically spin up multiple processes and route traffic between them. We recommend as many workers as you have available processors. +Sanic将自动旋转多个进程和它们之间的路由流量。 我们推荐像您现有的处理器一样多的工人。 -.. column:: +.. 列: ``` -The easiest way to get the maximum CPU performance is to use the `--fast` option. This will automatically run the maximum number of workers given the system constraints. +获取最大CPU性能的最简单方法是使用“--fast”选项。 由于系统限制，此操作将自动运行最大数量的员工。 -*Added in v21.12* +*在 v21.12* 中添加。 ``` -.. column:: +.. 列: ```` ```sh @@ -65,9 +65,9 @@ sanic server:app --host=0.0.0.0 --port=1337 --fast ``` ```` -In version 22.9, Sanic introduced a new worker manager to provide more consistency and flexibility between development and production servers. Read [about the manager](./manager.md) for more details about workers. +在第22.9版中，Sanic引入了一个新的工人经理，以便在开发服务机和生产服务机之间提供更大的一致性和灵活性。 阅读[关于经理](./manager.md)了解更多有关工人的详情。 -.. column:: +.. 列: ``` If you only want to run Sanic with a single process, specify `single_process` in the run arguments. This means that auto-reload, and the worker manager will be unavailable. @@ -75,19 +75,19 @@ If you only want to run Sanic with a single process, specify `single_process` in *Added in v22.9* ``` -.. column:: +.. 列: ```` ```sh -sanic server:app --host=0.0.0.0 --port=1337 --single-process +sanic server:app --host=0.0.0.0 --port=1337 --sin-process ``` ```` -### Running via command +### 通过命令运行 #### Sanic CLI -Use `sanic --help` to see all the options. +使用 'sanic --help' 查看所有选项。 .. attrs:: :title: Sanic CLI help output @@ -189,15 +189,15 @@ Optional ``` ```` -#### As a module +#### 作为一个模块 -.. column:: +.. 列: ``` -Sanic applications can also be called directly as a module. +Sanic 应用程序也可以直接调用为模块。 ``` -.. column:: +.. 列: ```` ```bash @@ -205,17 +205,17 @@ python -m sanic server.app --host=0.0.0.0 --port=1337 --workers=4 ``` ```` -#### Using a factory +#### 使用一个工厂。 -A very common solution is to develop your application _not_ as a global variable, but instead using the factory pattern. In this context, "factory" means a function that returns an instance of `Sanic(...)`. +一个非常常见的解决办法是开发你的应用程序_不是_作为一个全局变量，而是使用出厂模式。 在这个上下文中，"factory" 是指返回一个 `Sanic(...)` 实例的函数。 -.. column:: +.. 列: ``` -Suppose that you have this in your `server.py` +假定你在 `server.py` 里有这个内容 ``` -.. column:: +.. 列: ```` ```python @@ -228,41 +228,41 @@ def create_app() -> Sanic: ``` ```` -.. column:: +.. 列: ``` -You can run this application now by referencing it in the CLI explicitly as a factory: +您现在可以在 CLI 中明确地将其作为一个工厂来运行此应用程序： ``` -.. column:: +.. 列: ```` ```sh -sanic server:create_app --factory +sanic server:create_app --frant ``` -Or, explicitly like this: +Or, 明示类似于: ```sh sanic "server:create_app()" ``` -Or, implicitly like this: +Or, 默示类似于： ```sh sanic server:create_app ``` -*Implicit command added in v23.3* +*默示命令添加于v23.3* ```` -### Low level `app.run` +### 低级别 `app.run` -When using `app.run` you will just call your Python file like any other script. +当使用 `app.run` 时，你会像其他脚本一样调用 Python 文件。 -.. column:: +.. 列: ``` -`app.run` must be properly nested inside of a name-main block. +`app.run`必须正确嵌套在一个名称的主块内。 ``` -.. column:: +.. 列: ```` ```python @@ -274,7 +274,7 @@ if __name__ == "__main__": ``` ```` -.. danger:: +.. 危险：: ```` Be *careful* when using this pattern. A very common mistake is to put too much logic inside of the `if __name__ == "__main__":` block. @@ -309,39 +309,39 @@ elif __name__ == "__main__": ``` ```` -To use the low-level `run` API, after defining an instance of `sanic.Sanic`, we can call the run method with the following keyword arguments: +要使用低级别的 `run` API，在定义一个 `sanic.Sanic` 实例后，我们可以使用以下关键词参数来调用运行方法： -| Parameter | Default | Description | -| :---------------------------------------: | :--------------: | :---------------------------------------------------------------------------------------- | -| **host** | `"127.0.0.1"` | Address to host the server on. | -| **port** | `8000` | Port to host the server on. | -| **unix** | `None` | Unix socket name to host the server on (instead of TCP). | -| **dev** | `False` | Equivalent to `debug=True` and `auto_reload=True`. | -| **debug** | `False` | Enables debug output (slows server). | -| **ssl** | `None` | SSLContext for SSL encryption of worker(s). | -| **sock** | `None` | Socket for the server to accept connections from. | -| **workers** | `1` | Number of worker processes to spawn. Cannot be used with fast. | -| **loop** | `None` | An asyncio-compatible event loop. If none is specified, Sanic creates its own event loop. | -| **protocol** | `HttpProtocol` | Subclass of asyncio.protocol. | -| **version** | `HTTP.VERSION_1` | The HTTP version to use (`HTTP.VERSION_1` or `HTTP.VERSION_3`). | -| **access_log** | `True` | Enables log on handling requests (significantly slows server). | -| **auto_reload** | `None` | Enables auto-reload on the source directory. | -| **reload_dir** | `None` | A path or list of paths to directories the auto-reloader should watch. | -| **noisy_exceptions** | `None` | Whether to set noisy exceptions globally. None means leave as default. | -| **motd** | `True` | Whether to display the startup message. | -| **motd_display** | `None` | A dict with extra key/value information to display in the startup message | -| **fast** | `False` | Whether to maximize worker processes. Cannot be used with workers. | -| **verbosity** | `0` | Level of logging detail. Max is 2. | -| **auto_tls** | `False` | Whether to auto-create a TLS certificate for local development. Not for production. | -| **single_process** | `False` | Whether to run Sanic in a single process. | +| 参数 | 默认设置 | 描述 | +| :---------------------------------------: | :-------------: | :--------------------------------------------------------------------- | +| **主机** | `"127.0.0.1"` | 服务器主机地址已开启。 | +| **端口** | `8000` | 服务器端口已开启。 | +| **unix** | `无` | 服务器主机的 Unix 套接字名称 (而不是TCP)。 | +| **dev** | `False` | 等于`debug=True`和`auto_reload=True`。 | +| **debug** | `False` | 启用调试输出 (慢速服务器)。 | +| **ssl** | `无` | SSLContext for SSL 加密 (s)。 | +| **sock** | `无` | Socket 让服务器接受连接。 | +| **Workers** | `1` | 要生成的工序数量。 无法快速使用。 | +| **循环** | `无` | 一个异步兼容的事件循环。 如果没有具体说明，Sanic将创建自己的事件循环。 | +| **protocol** | `HttpProtocol` | asyncio.protocol的子类。 | +| **版本** | `HTTPVERSION_1` | 要使用的 HTTP 版本 (`HTTP.VERSION_1` 或 `HTTP.VERSION_3`). | +| **access_log** | `True` | 启用处理请求的日志 (大大减慢服务器)。 | +| **auto_reload** | `无` | 启用源目录自动重新加载。 | +| **reload_dir** | `无` | 自动读取加载器应该监视的目录路径或路径列表。 | +| **noisy_exceptions** | `无` | 是否设置全局噪音异常。 没有表示离开为默认值。 | +| **motd** | `True` | 是否显示启动消息。 | +| **motd_display** | `无` | 在启动消息中显示额外的密钥/值信息 | +| **fast** | `False` | 是否最大化工人工序。 无法与工人一起使用。 | +| **详细化** | `0` | 日志的详细级别。 最大值为 2。 | +| **自动_tls** | `False` | 是否为本地开发自动创建TLS证书。 不是生产的。 | +| **单独处理** | `False` | 是否在一个过程中运行 Sanic。 | -.. column:: +.. 列: ``` -For example, we can turn off the access log in order to increase performance, and bind to a custom host and port. +例如，我们可以关闭访问日志以提高性能并绑定到自定义主机和端口。 ``` -.. column:: +.. 列: ```` ```python @@ -353,13 +353,13 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列: ``` -Now, just execute the python script that has `app.run(...)` +现在，只需执行 'app.run(...)' 的 python 脚本 ``` -.. column:: +.. 列: ```` ```sh @@ -367,15 +367,15 @@ python server.py ``` ```` -For a slightly more advanced implementation, it is good to know that `app.run` will call `app.prepare` and `Sanic.serve` under the hood. +对于稍微高级的实现来说，我们很高兴知道`app.run`会调用`app.preparre`和`Sanic.serve`。 -.. column:: +.. 列: ``` -Therefore, these are equivalent: +因此，这些标准等同于： ``` -.. column:: +.. 列: ```` ```python @@ -389,13 +389,13 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列: ``` -This can be useful if you need to bind your appliction(s) to multiple ports. +如果您需要将应用程序绑定到多个端口，这将是有用的。 ``` -.. column:: +.. 列: ```` ```python @@ -407,29 +407,29 @@ if __name__ == "__main__": ``` ```` -### Sanic Simple Server +### Sanic 简单服务器 -.. column:: +.. 列: ``` -Sometimes you just have a directory of static files that need to be served. This especially can be handy for quickly standing up a localhost server. Sanic ships with a Simple Server, where you only need to point it at a directory. +有时，你只是一个需要服务的静态文件目录。 这尤其可以方便快速站立本地主机服务器。 一个简单的服务器的神秘船，你只需要在一个目录上指明。 ``` -.. column:: +.. 列: ```` ```sh -sanic ./path/to/dir --simple +sanic ./path/to/dir --imple ``` ```` -.. column:: +.. 列: ``` -This could also be paired with auto-reloading. +这也可以与自动重新加载配对。 ``` -.. column:: +.. 列: ```` ```sh @@ -437,11 +437,11 @@ sanic ./path/to/dir --simple --reload --reload-dir=./path/to/dir ``` ```` -_Added in v21.6_ +\*添加于 v21.6 \* ### HTTP/3 -Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed to use HTTP/3: +Sanic 服务器使用 [aioquic](https://github.com/aiortc/aioquic) 提供 HTTP/3 支持。 此 \*\*must \*\* 安装后才能使用 HTTP/3： ```sh pip install sanic aioquic @@ -451,9 +451,9 @@ pip install sanic aioquic pip install sanic[http3] ``` -To start HTTP/3, you must explicitly request it when running your application. +要启动 HTTP/3，您必须在运行应用程序时明确请求它。 -.. column:: +.. 列: ```` ```sh @@ -465,7 +465,7 @@ sanic path.to.server:app -3 ``` ```` -.. column:: +.. 列: ```` ```python @@ -473,9 +473,9 @@ app.run(version=3) ``` ```` -To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](../release-notes/v22.3.html#application-multi-serve) introduced in v22.3. This will automatically add an [Alt-Svc](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Alt-Svc) header to your HTTP/1.1 requests to let the client know that it is also available as HTTP/3. +要同时运行一个 HTTP/3 和 HTTP/1.1 服务器，您可以使用 v22.3 引入的 [application multi-servve](../release-notes/v22.3.html#application-multi-servve)。 这将自动添加一个 [Alt-Svc](https\://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ Alt-Svc) 头到您的 HTTP/1.1 请求让客户端知道它也是可用的 HTTP/3。 -.. column:: +.. 列: ```` ```sh @@ -487,80 +487,80 @@ sanic path.to.server:app -3 -1 ``` ```` -.. column:: +.. 列: ```` ```python -app.prepare(version=3) -app.prepare(version=1) +app.preparre(version=3) +app.preparre(version=1) Sanic.serve() ``` ```` -Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. See [development](./development.md) for more details. +因为HTTP 3 需要 TLS，您不能在没有TLS 证书的情况下启动 HTTP/3 服务器。 你应该[自己设置它](../how-to/tls.html)，或者在 `DEBUG` 模式下使用 `mkcert` 。 目前，HTTP/3 的自动TLS设置与 `trustme` 不兼容。 更多详细信息请访问 [development](./development.md)。 -_Added in v22.6_ +_添加于 v22.6_ ## ASGI -Sanic is also ASGI-compliant. This means you can use your preferred ASGI webserver to run Sanic. The three main implementations of ASGI are [Daphne](http://github.com/django/daphne), [Uvicorn](https://www.uvicorn.org/), and [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html). +Sanic也是ASGI合规者。 这意味着您可以使用您喜欢的 ASGI web服务器来运行 Sanic。 ASGI的三个主要实施方式是： [Daphne](http://github.com/django/daphne)、 [Uvicorn](https://www.uvicorn.org/)和 [Hypercorn](https://pgjones.gitlab.io/hypercorn/index.html)。 -.. warning:: +.. 警告：: ``` -Daphne does not support the ASGI `lifespan` protocol, and therefore cannot be used to run Sanic. See [Issue #264](https://github.com/django/daphne/issues/264) for more details. +Daphne不支持ASGI `lifespan` 协议，因此不能用于运行 Sanic。详情请参阅[Issue #264](https://github.com/django/daphne/issues/264)。 ``` -Follow their documentation for the proper way to run them, but it should look something like: +按照他们的文档来运行他们，但它应该看起来像这样： ```sh uvicorn myapp:app ``` ```sh -hypercorn myapp:app +超彩应用:app ``` -A couple things to note when using ASGI: +使用ASGI时要注意的几件事： -1. When using the Sanic webserver, websockets will run using the `websockets` package. In ASGI mode, there is no need for this package since websockets are managed in the ASGI server. -2. The ASGI lifespan protocol https\://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. +1. 当使用 Sanic 网络服务器时，websockets 将使用 `websockets` 软件包运行。 在 ASGI 模式下，没有必要使用这个软件包，因为websockets 是在 ASGI 服务器上管理的。 +2. ASGI 生命周期协议 https\://asgi.readthedocs.io/en/latest/specs/lifespan.html，只支持两个服务器事件：启动和关机。 萨里语有四个：启动前、启动后、关闭前和关机。 因此，以ASGI模式， 启动和关闭事件将连续运行，而不是围绕服务器进程开始和结束(因为现在是由 ASGI 服务器控制的)。 因此，最好使用 `after _server_start` 和 `previ_server_stop` 。 -### Trio +### 特里奥文 -Sanic has experimental support for running on Trio with: +Sanic在Trio上运行时有实验支持： ```sh -hypercorn -k trio myapp:app +超精彩-k 三次应用：应用 ``` -## Gunicorn +## 古尼科恩州 -[Gunicorn](http://gunicorn.org/) ("Green Unicorn") is a WSGI HTTP Server for UNIX based operating systems. It is a pre-fork worker model ported from Ruby’s Unicorn project. +[Gunicorn](http://gunicorn.org/) ("Green Unicorn") 是一个基于UNIX的操作系统的 WSGI HTTP 服务器。 这是一个基于 Ruby Unicorn项目的前叉工人模型。 -In order to run Sanic application with Gunicorn, you need to use it with the adapter from [uvicorn](https://www.uvicorn.org/). Make sure uvicorn is installed and run it with `uvicorn.workers.UvicornWorker` for Gunicorn worker-class argument: +若要与 Gunicorn一起运行 Sanic 应用程序，您需要使用 [uvicorn]的适配器(https\://www\.uvicorn.org/)。 确保uvicorn已经安装并运行它与 `uvicorn.workers.UvicornWorker` for Gunicorn worker-class参数： ```sh -gunicorn myapp:app --bind 0.0.0.0:1337 --worker-class uvicorn.workers.UvicornWorker +gunicorn myapp:app --binding 0.0.0:1337 --worker-classuvicorn.workers.UvicornWorker ``` -See the [Gunicorn Docs](http://docs.gunicorn.org/en/latest/settings.html#max-requests) for more information. +详见[Gunicorn Docs](http://docs.gunicorn.org/enarage/settings.html#max-requests)。 -.. warning:: +.. 警告：: ``` -It is generally advised to not use `gunicorn` unless you need it. The Sanic Server is primed for running Sanic in production. Weigh your considerations carefully before making this choice. Gunicorn does provide a lot of configuration options, but it is not the best choice for getting Sanic to run at its fastest. +通常建议不要使用“gunicorn”，除非你需要它。 Sanic 服务器已经准备好在生产中运行 Sanic。在作出这一选择之前仔细加大您的考虑。 Gunicorn确实提供了许多配置选项，但它不是让Sanic以最快的速度运行的最佳选择。 ``` -## Performance considerations +## 业绩考虑 -.. column:: +.. 列: ``` -When running in production, make sure you turn off `debug`. +在生产中运行时，请确保您关闭“debug”。 ``` -.. column:: +.. 列: ```` ```sh @@ -568,18 +568,18 @@ sanic path.to.server:app ``` ```` -.. column:: +.. 列: ``` -Sanic will also perform fastest if you turn off `access_log`. +如果您关闭了 "access_log" ，Sanic 也会执行最快的操作。 -If you still require access logs, but want to enjoy this performance boost, consider using [Nginx as a proxy](./nginx.md), and letting that handle your access logging. It will be much faster than anything Python can handle. +如果您仍然需要访问日志，但是想要享受此性能增强，请考虑使用 [Nginx 作为代理](。)。 nginx.md, 并让它处理您的访问记录。它将比任何Python能够处理的更快一些。 ``` -.. column:: +.. 列: ```` ```sh -sanic path.to.server:app --no-access-logs +sanic path.to.server:app --no-access-log ``` ```` From f0357ff7d7561c08130f69808fc50795afda4fb6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:25 +0200 Subject: [PATCH 379/698] New translations help.md (Japanese) --- guide/content/ja/help.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/ja/help.md b/guide/content/ja/help.md index f84355e054..e0df6041f1 100644 --- a/guide/content/ja/help.md +++ b/guide/content/ja/help.md @@ -1,13 +1,13 @@ --- -title: Need some help? -layout: main +title: ヘルプが必要ですか？ +layout: メイン --- -# Need some help? +# ヘルプが必要ですか？ -As an active community of developers, we try to support each other. If you need some help, try one of the following: +開発者の積極的なコミュニティとして、私たちはお互いをサポートしようとしています。 ヘルプが必要な場合は、以下のいずれかをお試しください。 -.. column:: +.. 列:: ``` ### Discord 💬 @@ -17,16 +17,16 @@ Best place to turn for quick answers and live chat `#sanic-support` channel on the [Discord server](https://discord.gg/FARQzAEMAA) ``` -.. column:: +.. 列:: ``` -### Community Forums 👥 +### Community Forums :busts_in_sシルエット: + -Good for sharing snippets of code and longer support queries `Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) ``` *** -We also actively monitor the `[sanic]` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic). +[Stack Overflow](https://stackoverflow.com/questions/tagged/sanic)の`[sanic]`タグも積極的に監視しています。 From 52080f1f852edef1bb35afeb158f53ab5df52806 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:27 +0200 Subject: [PATCH 380/698] New translations help.md (Chinese Simplified) --- guide/content/zh/help.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/guide/content/zh/help.md b/guide/content/zh/help.md index f84355e054..d07461ed22 100644 --- a/guide/content/zh/help.md +++ b/guide/content/zh/help.md @@ -1,32 +1,32 @@ --- -title: Need some help? -layout: main +title: 需要一些帮助吗？ +layout: 主要的 --- -# Need some help? +# 需要一些帮助吗？ -As an active community of developers, we try to support each other. If you need some help, try one of the following: +作为一个活跃的开发者社区，我们努力相互支持。 如果您需要一些帮助，请尝试以下一种： -.. column:: +.. 列: ``` -### Discord 💬 +### Discord :speech_cloon: -Best place to turn for quick answers and live chat +最好在[Discord服务器]上开启快速答案和在线聊天 -`#sanic-support` channel on the [Discord server](https://discord.gg/FARQzAEMAA) +`#sanic-support` 频道(https://discord.gg/FARQzAEMAA) ``` -.. column:: +.. 列: ``` -### Community Forums 👥 +### 社区论坛 👥 -Good for sharing snippets of code and longer support queries +最好分享代码片段和更长时间的支持查询 -`Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) +"Questions and Help" categories on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) ``` *** -We also actively monitor the `[sanic]` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic). +我们还积极监视[堆栈溢出](https://stackoverflow.com/questions/tagged/sanic)上的\`[sanic]'标签。 From 9836e7fa390ccadfad0af32a571ccf00573fcb61 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:28 +0200 Subject: [PATCH 381/698] New translations index.md (Japanese) --- guide/content/ja/index.md | 42 +++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/guide/content/ja/index.md b/guide/content/ja/index.md index 3c09f07788..c2b0245bdf 100644 --- a/guide/content/ja/index.md +++ b/guide/content/ja/index.md @@ -1,25 +1,25 @@ --- -title: The lightning-fast asynchronous Python web framework -layout: home +title: 超高速非同期のPythonウェブフレームワーク +layout: ホーム features: - - title: Simple and lightweight - details: Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. - - title: Unopinionated and flexible - details: Build the way you want to build without letting your tooling constrain you. - - title: Performant and scalable - details: Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. - - title: Production ready - details: Out of the box, it comes bundled with a web server ready to power your web applications. - - title: Trusted by millions - details: Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework - - title: Community driven - details: The project is maintained and run by the community for the community. + - title: シンプルで軽量な + details: スマートなデフォルトを持つ直感的なAPIと肥満がないと、アプリの構築を直進できます。 + - title: 不要で柔軟性があります + details: ツールを使うことで制約がなくても構築方法を構築できます。 + - title: パフォーマンスとスケーラブルな + details: 主な関心事として速度とスケーラビリティをゼロから構築しました。 大小のWebアプリケーションに電力を供給する準備ができています。 + - title: 生産準備完了 + details: ボックスの外には、Webアプリケーションに電力を供給するためのWebサーバーが付属しています。 + - title: 何百万人に信頼されています + details: Sanic は PyPI 上で最も人気のあるフレームワークの一つであり、非同期対応フレームワーク + - title: コミュニティ主導型の + details: このプロジェクトはコミュニティによって運営されています。 --- -### ⚡ The lightning-fast asynchronous Python web framework +### ⚡ 超高速非同期Pythonウェブフレームワーク .. attrs:: -:class: columns is-multiline mt-6 +:class: 列は mt-6 ``` .. attrs:: @@ -69,14 +69,14 @@ features: :class: is-size-3 mt-6 ``` -**With the features and tools you'd expect.** +**機能とツールを使って。** ``` .. attrs:: :class: is-size-3 ml-6 ``` -**And some {span:has-text-primary:you wouldn't believe}.** +**そしていくつかの {span:has-text-primary:you wouldn't believe}.** ``` .. tab:: Production-grade @@ -110,7 +110,7 @@ sanic path.to.server:app ``` ```` -.. tab:: TLS server +.. tab:: TLS サーバ ```` Running Sanic with TLS enabled is as simple as passing it the file paths... @@ -145,7 +145,7 @@ async def feed(request: Request, ws: Websocket): ``` ```` -.. tab:: Static files +.. tab:: 静的ファイル ```` Serving static files is of course intuitive and easy. Just name an endpoint and either a file or directory that should be served. @@ -223,7 +223,7 @@ await app.dispatch("something.happened.ohmy") ``` ```` -.. tab:: Smart error handling +.. tab:: スマートエラー処理 ```` Raising errors will intuitively result in proper HTTP errors: From 8b35a70d28574b9a0481dbb6265317f427438f19 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:30 +0200 Subject: [PATCH 382/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 106 +++++++++++++++++++------------------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index 3c09f07788..bc0f1f67c5 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -1,22 +1,22 @@ --- -title: The lightning-fast asynchronous Python web framework -layout: home +title: 闪电快异步的 Python web 框架 +layout: 首页 features: - - title: Simple and lightweight - details: Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. - - title: Unopinionated and flexible - details: Build the way you want to build without letting your tooling constrain you. - - title: Performant and scalable - details: Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. - - title: Production ready - details: Out of the box, it comes bundled with a web server ready to power your web applications. - - title: Trusted by millions - details: Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework - - title: Community driven - details: The project is maintained and run by the community for the community. + - title: 简单和轻量度 + details: 智能默认和没有博客的直观API允许您直接建立您的应用程序。 + - title: 无意见和灵活的 + details: 构建你想要构建的方式而不让你的工具约束你。 + - title: 性能和可缩放 + details: 以速度和可伸缩性作为主要关切事项。 它已经准备好为无论大小的网络应用程序供电。 + - title: 生产已准备好 + details: 在盒子中，它被捆绑在一个网络服务器上，可以为您的网络应用程序提供电力。 + - title: 受数以百万计的信任的 + details: Sanic 是 PyPI 最受欢迎的框架之一，是启用异步的顶部框架 + - title: 社区驱动的 + details: 该项目由社区为社区维护和管理。 --- -### ⚡ The lightning-fast asynchronous Python web framework +### :hig_voltag: lightning-fast asynchronous Python web Framework .. attrs:: :class: columns is-multiline mt-6 @@ -69,17 +69,17 @@ features: :class: is-size-3 mt-6 ``` -**With the features and tools you'd expect.** +**使用您所期望的功能和工具。** ``` .. attrs:: :class: is-size-3 ml-6 ``` -**And some {span:has-text-primary:you wouldn't believe}.** +**和一些 {span:has-text-primary:you wouldn't believe}.** ``` -.. tab:: Production-grade +.. 标签：生产等级 ```` After installing, Sanic has all the tools you need for a scalable, production-grade server—out of the box! @@ -110,28 +110,28 @@ sanic path.to.server:app ``` ```` -.. tab:: TLS server +.. 标签：TLS服务器 ```` -Running Sanic with TLS enabled is as simple as passing it the file paths... +启用 TLS 来运行Sanic与传递文件路径一样简单... ```sh -sanic path.to.server:app --cert=/path/to/bundle.crt --key=/path/to/privkey.pem -``` +sanic path.to.server:app --cert=/path/to/bundle。 rt --key=/path/to/privkey.pem +`` -... or the a directory containing `fullchain.pem` and `privkey.pem` +... 或包含`fullchain.pem` 和 `privkey.pem` ```sh -sanic path.to.server:app --tls=/path/to/certs +sanic path.to. erver:app --tls=/path/to/certs ``` -**Even better**, while you are developing, let Sanic handle setting up local TLS certificates so you can access your site over TLS at [https://localhost:8443](https://localhost:8443) +**甚至更好地**，正在开发中。 让Sanic处理设置本地TLS证书，以便您可以通过 TLS 访问 [https://localhost:8443](https://localhost:8443) ```sh -sanic path.to.server:app --dev --auto-tls +sanic 路径。 o.server:app --dev --auto-tls ``` ```` -.. tab:: Websockets +.. 标签：Websockets ```` Up and running with websockets in no time using the [websockets](https://websockets.readthedocs.io) package. @@ -145,35 +145,35 @@ async def feed(request: Request, ws: Websocket): ``` ```` -.. tab:: Static files +.. 标签：静态文件 ```` -Serving static files is of course intuitive and easy. Just name an endpoint and either a file or directory that should be served. +服务静态文件当然是直观和容易的。只需命名一个端点和一个应该服务的文件或目录。 ```python app.static("/", "/path/to/index.html") -app.static("/uploads/", "/path/to/uploads/") +应用。 tatic("/uploads/", "/path/to/uploads/") ``` -Moreover, serving a directory has two additional features: automatically serving an index, and automatically serving a file browser. +此外，服务目录还有两个额外功能：自动服务索引，自动服务于文件浏览器。 -Sanic can automatically serve `index.html` (or any other named file) as an index page in a directory or its subdirectories. +Sanic 可以自动将 `index.html` (或任何其他命名文件) 作为目录或其子目录中的索引页。 ```python app.static( "/uploads/", "/path/to/uploads/", - index="index.html" -) + index="索引。 +() ``` -And/or, setup Sanic to display a file browser. +And/or 设置Sanic 以显示文件浏览器。 -![image](/assets/images/directory-view.png) +！[image](/assets/images/directory-view.png) ```python -app.static( +app tatic( "/uploads/", "/path/to/uploads/", directory_view=True @@ -181,7 +181,7 @@ app.static( ``` ```` -.. tab:: Lifecycle +.. tab：生命周期： ```` Beginning or ending a route with functionality is as simple as adding a decorator. @@ -223,35 +223,35 @@ await app.dispatch("something.happened.ohmy") ``` ```` -.. tab:: Smart error handling +.. 标签：智能错误处理 ```` -Raising errors will intuitively result in proper HTTP errors: +提升错误会直观地导致正确的 HTTP 错误： -```python -raise sanic.exceptions.NotFound # Automatically responds with HTTP 404 -``` +``python +raising sanic.exception。 ootFound # 自动响应HTTP 404 +`` -Or, make your own: +或是你自己： ```python -from sanic.exceptions import SanicException +xceptions import SanicException class TeapotError(SanicException): status_code = 418 - message = "Sorry, I cannot brew coffee" + message = “对不起，” 我不能酿造咖啡” -raise TeapotError +提高Teapot错误 ``` -And, when an error does happen, Sanic's beautiful DEV mode error page will help you drill down to the bug quickly. +当发生错误时， Sanic美丽的 DEV 模式错误页面将帮助您快速钻到漏洞。 -![image](../assets/images/error-div-by-zero.png) +！[image](../assets/images/error-div-zero.png) -Regardless, Sanic comes with an algorithm that attempts to respond with HTML, JSON, or text-based errors as appropriate. Don't worry, it is super easy to setup and customize your error handling to your exact needs. +不管怎样，Sanic带有一个算法，尝试使用HTML，JSON或文本错误作为相应答复。 别担心，设置和自定义您的错误处理符合您的具体需要是非常简单的。 ```` -.. tab:: App Inspector +.. 选项卡：应用查看器 ```` Check in on your live, running applications (whether local or remote). @@ -303,7 +303,7 @@ sanic inspect migrations ``` ```` -.. tab:: Extendable +.. 标签：可扩展 ``` In addition to the tools that Sanic comes with, the officially supported [Sanic Extensions](./plugins/sanic-ext/getting-started.md) provides lots of extra goodies to make development easier. @@ -318,7 +318,7 @@ In addition to the tools that Sanic comes with, the officially supported [Sanic - Live **health monitor** ``` -.. tab:: Developer Experience +.. 标签：开发者体验 ``` Sanic is **built for building**. From 74a0dadbdf3e15c618d3b90a2fe3766163be0a36 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:31 +0200 Subject: [PATCH 383/698] New translations code-of-conduct.md (Japanese) --- .../ja/organization/code-of-conduct.md | 71 +++++++++---------- 1 file changed, 34 insertions(+), 37 deletions(-) diff --git a/guide/content/ja/organization/code-of-conduct.md b/guide/content/ja/organization/code-of-conduct.md index 84f0f12d5f..fdd48a1b88 100644 --- a/guide/content/ja/organization/code-of-conduct.md +++ b/guide/content/ja/organization/code-of-conduct.md @@ -1,6 +1,6 @@ -# Contributor Covenant Code of Conduct +# 貢献者の契約行動コード -## Our Pledge +## 私たちの誓い In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and @@ -9,33 +9,31 @@ size, disability, ethnicity, gender identity and expression, level of experience nationality, personal appearance, race, religion, or sexual identity and orientation. -## Our Standards +## 私たちの基準 -Examples of behavior that contributes to creating a positive environment -include: +正の環境を作り出すことに貢献する行動の例は以下のとおりです。 -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members +- 歓迎と包括的な言語の使用 +- 異なる視点や経験を尊重する +- 建設的な批判を優雅に受け入れます +- コミュニティにとって何が最善なのかに焦点を当てます +- 他のコミュニティメンバーへの共感を表示 -Examples of unacceptable behavior by participants include: +参加者が受け入れられない行動の例としては、次のようなものがあります。 -- The use of sexualized language or imagery and unwelcome sexual attention or - advances -- Trolling, insulting/derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or electronic - address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting +- 性的言語または画像の使用と歓迎されない性的注意または + の進歩。 +- トロール、侮辱的/軽蔑的なコメント、個人的または政治的な攻撃 +- 公的または私的な嫌がらせについて +- 物理的または電子的な + アドレスなど、他人の個人情報を明示的な許可なしに公開する +- プロの設定で合理的に不適切とみなされる他の行為 -## Our Responsibilities +## 私たちの責任 -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +プロジェクト管理者は、許容される +行動の基準を明確にする責任があり、受け入れられない行動のあらゆるインスタンスに対して、 +応答において適切かつ公正な是正措置をとることが期待されます。 Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions @@ -43,10 +41,10 @@ that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. -## Scope +## スコープ -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of +この行動規範は、個人がプロジェクトまたはコミュニティを代表している場合、プロジェクトスペースと公共スペース +の両方に適用されます。 Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be @@ -54,21 +52,20 @@ further defined and clarified by project maintainers. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at adam\@sanicframework.org. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is +adam\@sanicframework.org のプロジェクト チームに連絡することで、虐待、嫌がらせ、またはその他の受け入れられない行動のインスタンスが +報告される可能性があります。 +のすべての苦情は審査され調査され、 +が状況に対して必要かつ適切であると判断される対応となります。 The project team is obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. +具体的な執行ポリシーの詳細については、別途掲載することがあります。 -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. +信仰に基づいて行動規範を遵守しない、または強制しないプロジェクトのメンテナーは、プロジェクトのリーダーシップの他の +メンバーによって決定されるように、一時的または恒久的な影響に直面する可能性があります。 -## Attribution +## 表示 -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +この行動規範は、[http://contributor-covenant.org/version/1/4][homepage] +で利用できる [Contributor Covenant][version] から適用されます。 [homepage]: http://contributor-covenant.org From c52dbf996d4ab9bb9f58a28c75ff6dc4dce1dff8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:33 +0200 Subject: [PATCH 384/698] New translations code-of-conduct.md (Chinese Simplified) --- .../zh/organization/code-of-conduct.md | 76 +++++++++---------- 1 file changed, 37 insertions(+), 39 deletions(-) diff --git a/guide/content/zh/organization/code-of-conduct.md b/guide/content/zh/organization/code-of-conduct.md index 84f0f12d5f..2704a63246 100644 --- a/guide/content/zh/organization/code-of-conduct.md +++ b/guide/content/zh/organization/code-of-conduct.md @@ -1,6 +1,6 @@ -# Contributor Covenant Code of Conduct +# 贡献者盟约行为守则 -## Our Pledge +## 我们的保证 In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and @@ -9,33 +9,32 @@ size, disability, ethnicity, gender identity and expression, level of experience nationality, personal appearance, race, religion, or sexual identity and orientation. -## Our Standards +## 我们的标准 -Examples of behavior that contributes to creating a positive environment -include: +有助于创造积极环境的行为 +的例子包括： -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Gracefully accepting constructive criticism -- Focusing on what is best for the community -- Showing empathy towards other community members +- 使用欢迎和包容的语言 +- 尊重不同的观点和经验 +- 优雅地接受建设性的评论 +- 侧重于最适合社区的内容 +- 对其他社区成员表示同情。 -Examples of unacceptable behavior by participants include: +参与者不可接受的行为实例包括： -- The use of sexualized language or imagery and unwelcome sexual attention or - advances -- Trolling, insulting/derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or electronic - address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting +- 性化语言或图像的使用以及不受欢迎的性关注或 + 的进展情况 +- 挑选、侮辱/贬损性评论以及个人或政治攻击 +- 公开或私下骚扰行为 +- 未经明确许可，发布他人的私人信息，例如物理或电子 + 地址 +- 职业环境中可以合理地认为不合适的其他行为 -## Our Responsibilities +## 我们的责任 -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +项目维护者负责澄清可接受的 +行为的标准，并且预期将在 +反应中采取适当和公平的纠正行动，应对任何不可接受的行为。 Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions @@ -43,33 +42,32 @@ that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. -## Scope +## 范围 This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be +when an individual is representing the project or its community. +代表一个项目或社区的例子包括使用官方项目电子邮件 +地址 在网上或离线活动中，通过官方社交媒体帐户发布信息，或担任指定的 +代表。 Representation of a project may be further defined and clarified by project maintainers. -## Enforcement +## 执行 -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at adam\@sanicframework.org. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. +可能是通过联系项目团队Adam\@sanicframework.org报告的滥用、骚扰或其他令人无法接受的行为。 所有 +申诉都将得到审查和调查，结果将产生 +被认为是必要和适合当时情况的答复。 项目组负责 +对事件报告者保密。 +具体执法政策的进一步细节可另行公布。 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. -## Attribution +## 属性 -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +本行为守则摘自[贡献者公约][homepage]第1.4版， +[http://contributor-covenant.org/version/1/4][version] -[homepage]: http://contributor-covenant.org +[homepage]: http://contributor-Covenant.org [version]: http://contributor-covenant.org/version/1/4/ From 3cd88d35f3fbe442f5b1658f8e8aa86fa58ac5bc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:35 +0200 Subject: [PATCH 385/698] New translations contributing.md (Japanese) --- guide/content/ja/organization/contributing.md | 144 +++++++++--------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/guide/content/ja/organization/contributing.md b/guide/content/ja/organization/contributing.md index fc38154f48..089082832c 100644 --- a/guide/content/ja/organization/contributing.md +++ b/guide/content/ja/organization/contributing.md @@ -1,48 +1,48 @@ -# Contributing +# コントリビューション -Thank you for your interest! Sanic is always looking for contributors. If you don't feel comfortable contributing code, adding docstrings to the source files, or helping with the [Sanic User Guide](https://github.com/sanic-org/sanic-guide) by providing documentation or implementation examples would be appreciated! +ご興味をお持ちいただきありがとうございます! Sanicは常に貢献者を探しています。 貢献するコードが不快であれば、ソース・ファイルにdocstringを追加したり、[Sanic User Guide](https://github) を手伝ってください。 om/sanic-org/sanic-guide: ドキュメントまたは実装例を提供することにより、当然のことです! -We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Our [code of conduct](https://github.com/sanic-org/sanic/blob/master/CONDUCT.md) sets the standards for behavior. +我々は,性別,性的指向,障害,民族性,宗教その他の個人的特性にかかわらず,すべての人に友好的で安全で歓迎的な環境を提供することにコミットしている。 format@@0(https\://github.com/sanic-org/sanic/blob/master/CONDUCT.md) は行動の標準を設定します。 -## Installation +## インストール -To develop on Sanic (and mainly to just run the tests) it is highly recommend to install from sources. +Sanicで開発する(主にテストを実行する)には、ソースからインストールすることを強くお勧めします。 -So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run: +そのため、既にリポジトリをクローンし、すでに設定されている仮想環境が作業ディレクトリにあると仮定してから、以下を実行します。 ```sh -pip install -e ".[dev]" +pip install -e " .[dev]" ``` -## Dependency Changes +## 依存関係の変更 -`Sanic` doesn't use `requirements*.txt` files to manage any kind of dependencies related to it in order to simplify the effort required in managing the dependencies. Please make sure you have read and understood the following section of the document that explains the way `sanic` manages dependencies inside the `setup.py` file. +`Sanic` は `requirements*.txt` ファイルを使用して、依存関係の管理に必要な作業を簡素化するために、依存関係に関連するあらゆる種類の依存関係を管理しません。 `setup.py`ファイル内で`sanic`が依存関係を管理する方法を説明する以下のセクションを読んで理解していることを確認してください。 -| Dependency Type | Usage | Installation | -| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------- | -| requirements | Bare minimum dependencies required for sanic to function | `pip3 install -e .` | -| tests_require / extras_require['test'] | Dependencies required to run the Unit Tests for `sanic` | `pip3 install -e '.[test]'` | -| extras_require['dev'] | Additional Development requirements to add contributing | `pip3 install -e '.[dev]'` | -| extras_require['docs'] | Dependencies required to enable building and enhancing sanic documentation | `pip3 install -e '.[docs]'` | +| 依存関係の種類 | 使用法 | インストール | +| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | --------------------------- | +| 要件 | sanic が機能するために必要な最小の依存関係を事前に確認する | `pip3 install -e .` | +| tests_require / extras_require['test'] | `sanic`のユニットテストを実行するために必要な依存関係 | `pip3 install -e '.[test]'` | +| extras_require['dev'] | 貢献を追加するための追加開発要件 | `pip3 install -e '.[dev]'` | +| extras_require['docs'] | サニック文書の構築と強化に必要な依存関係 | `pip3 install -e '.[docs]'` | -## Running all tests +## すべてのテストを実行中 -To run the tests for Sanic it is recommended to use tox like so: +Sanicのテストを実行するには、以下のようにtoxを使用することをお勧めします。 ```sh tox ``` -See it's that simple! +それは簡単です参照してください! -`tox.ini` contains different environments. Running `tox` without any arguments will +`tox.ini` には異なる環境が含まれています。 Running `tox` without any arguments will run all unittests, perform lint and other checks. -## Run unittests +## Unittestsを実行 -`tox` environment -> `[testenv]` +`tox` 環境 -> `[testenv]` -To execute only unittests, run `tox` with environment like so: +unittestsのみを実行するには、次のような環境で`tox`を実行します。 ```sh @@ -51,116 +51,116 @@ tox -e py37 -v -- tests/test_config.py tox -e py310 -v -- tests/test_config.py ``` -## Run lint checks +## lint のチェックを実行 -`tox` environment -> `[testenv:lint]` +`tox` 環境 -> `[testenv:lint]` -Permform `flake8`\ , `black` and `isort` checks. +`flake8`\ , `black` と `isort` のチェックを実行します。 ```sh tox -e lint ``` -## Run type annotation checks +## 型アノテーションチェックを実行 -`tox` environment -> `[testenv:type-checking]` +`tox` 環境 -> `[testenv:type-checking]` -Permform `mypy` checks. +`mypy`チェックを実行します。 ```sh -tox -e type-checking +tox -e タイプチェック ``` -## Run other checks +## 他のチェックを実行 -`tox` environment -> `[testenv:check]` +`tox` 環境 -> `[testenv:check]` -Perform other checks. +他のチェックを実行します。 ```sh tox -e check ``` -## Run Static Analysis +## 静的解析を実行 -`tox` environment -> `[testenv:security]` +`tox` 環境 -> `[testenv:security]` -Perform static analysis security scan +静的解析セキュリティスキャンを実行 ```sh -tox -e security +tox -e セキュリティ ``` -## Run Documentation sanity check +## ドキュメントの健全性チェックを実行 -`tox` environment -> `[testenv:docs]` +`tox` 環境 -> `[testenv:docs]` -Perform sanity check on documentation +ドキュメント上で健全性チェックを行う ```sh -tox -e docs +tox -e ドキュメント ``` -## Code Style +## コードスタイル -To maintain the code consistency, Sanic uses the following tools: +Sanicはコードの一貫性を維持するために、以下のツールを使用します。 -1. [isort](https://github.com/timothycrosley/isort) +1. [isort](https://github.com/timothycrossley/isort) 2. [black](https://github.com/python/black) 3. [flake8](https://github.com/PyCQA/flake8) 4. [slotscheck](https://github.com/ariebovenberg/slotscheck) ### isort -`isort` sorts Python imports. It divides imports into three categories sorted each in alphabetical order: +`isort` は Python インポートをソートします。 これは、インポートをアルファベット順にソートされた3つのカテゴリに分割します。 -1. built-in -2. third-party -3. project-specific +1. ビルトイン +2. サードパーティーの +3. プロジェクト固有の -### black +### ブラック -`black` is a Python code formatter. +`black` はPythonのコードフォーマッタです。 ### flake8 -`flake8` is a Python style guide that wraps the following tools into one: +`flake8` は次のツールを一つにまとめるPythonスタイルガイドです。 1. PyFlakes 2. pycodestyle -3. Ned Batchelder's McCabe script +3. Ned BatchelderのMcCabeスクリプト ### slotscheck -`slotscheck` ensures that there are no problems with `__slots__` (e.g., overlaps, or missing slots in base classes). +`slotscheck` は、`__slots__` に問題がないことを保証します (基本クラスの重複や欠落など)。 -`isort`, `black`, `flake8`, and `slotscheck` checks are performed during `tox` lint checks. +`isort` 、 `black` 、 `flake8` 、 `slotscheck` のチェックは `tox` lintチェック中に行われます。 -The **easiest** way to make your code conform is to run the following before committing: +**最も簡単**な方法は、コミットする前に以下を実行することです。 ```bash -make pretty +きれいにする ``` -Refer to [tox documentation](https://tox.readthedocs.io/en/latest/index.html) for more details. +詳細については、format@@0(https\://tox.readthedocs.io/en/latest/index.html)を参照してください。 -## Pull requests +## プルリクエスト -So the pull request approval rules are pretty simple: +したがって、プルリクエストの承認ルールは非常に簡単です。 -1. All pull requests must pass unit tests. -2. All pull requests must be reviewed and approved by at least one current member of the Core Developer team. -3. All pull requests must pass flake8 checks. -4. All pull requests must match `isort` and `black` requirements. -5. All pull requests must be **PROPERLY** type annotated, unless exemption is given. -6. All pull requests must be consistent with the existing code. -7. If you decide to remove/change anything from any common interface a deprecation message should accompany it in accordance with our [deprecation policy](https://sanicframework.org/en/guide/project/policies.html#deprecation). -8. If you implement a new feature you should have at least one unit test to accompany it. -9. An example must be one of the following: - - Example of how to use Sanic - - Example of how to use Sanic extensions - - Example of how to use Sanic and asynchronous library +1. すべてのプルリクエストは単体テストに合格しなければなりません。 +2. すべてのプルリクエストは、コア開発チームの少なくとも1人の現在のメンバーによって審査および承認されなければなりません。 +3. すべてのプルリクエストは flake8 チェックを渡す必要があります。 +4. すべてのプルリクエストは `isort` と `black` 要件に一致する必要があります。 +5. 免除が与えられない限り、全てのプルリクエストは **PROPERLY** 型に注釈を付ける必要があります。 +6. すべてのプルリクエストは、既存のコードと一致している必要があります。 +7. 任意の一般的なインターフェイスから何かを削除/変更することにした場合、非推奨メッセージは format@@0(https\://sanicframework.org/ja/guide/project/polices.html#deprecation )に従って同行する必要があります。 +8. 新しい機能を実装する場合は、少なくとも1つの単位テストが必要です。 +9. 例は次のいずれかでなければなりません: + - Sanicの使い方の例 + - Sanic extensions の使用例 + - Sanicライブラリと非同期ライブラリの使用例 -## Documentation +## ドキュメント -_Check back. We are reworking our documentation so this will change._ +戻って確認(_C) 変更されるようにドキュメントを再作業しています。_ From 239bad02955ae36176a0d2503eb1fc653c501085 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:36 +0200 Subject: [PATCH 386/698] New translations contributing.md (Chinese Simplified) --- guide/content/zh/organization/contributing.md | 144 +++++++++--------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/guide/content/zh/organization/contributing.md b/guide/content/zh/organization/contributing.md index fc38154f48..5193f4c598 100644 --- a/guide/content/zh/organization/contributing.md +++ b/guide/content/zh/organization/contributing.md @@ -1,109 +1,109 @@ -# Contributing +# 贡献中 -Thank you for your interest! Sanic is always looking for contributors. If you don't feel comfortable contributing code, adding docstrings to the source files, or helping with the [Sanic User Guide](https://github.com/sanic-org/sanic-guide) by providing documentation or implementation examples would be appreciated! +感谢您的兴趣！ Sanic总是在寻找贡献者。 如果你觉得不舒服的贡献代码，请将文档添加到源文件中，或帮助[Sanic User Guide](https://github)。 请提供文件或执行实例，以此表示欢迎！ -We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic. Our [code of conduct](https://github.com/sanic-org/sanic/blob/master/CONDUCT.md) sets the standards for behavior. +我们致力于为所有人提供一个友好、安全和受欢迎的环境，不论其性别、性取向、残疾、族裔、宗教或类似的个人特征。 我们的[行为守则](https://github.com/sanic-org/sanic/blob/master/CONDUCT.md)规定了行为标准。 -## Installation +## 安装 -To develop on Sanic (and mainly to just run the tests) it is highly recommend to install from sources. +要在 Sanic 上开发(主要是运行测试)，强烈建议从源头安装。 -So assume you have already cloned the repo and are in the working directory with a virtual environment already set up, then run: +所以假定你已经克隆了仓库，并且在工作目录中已经设置了虚拟环境，然后运行： ```sh pip install -e ".[dev]" ``` -## Dependency Changes +## 依赖关系变化 -`Sanic` doesn't use `requirements*.txt` files to manage any kind of dependencies related to it in order to simplify the effort required in managing the dependencies. Please make sure you have read and understood the following section of the document that explains the way `sanic` manages dependencies inside the `setup.py` file. +`Sanic` 不使用 `requirements*.txt` 文件来管理与此相关的任何依赖关系，以简化管理依赖关系所需的努力。 请确保您已经阅读并理解文档的下面一节，其中解释了`sanic` 如何管理`setup.py`文件中的依赖关系。 -| Dependency Type | Usage | Installation | -| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------- | -| requirements | Bare minimum dependencies required for sanic to function | `pip3 install -e .` | -| tests_require / extras_require['test'] | Dependencies required to run the Unit Tests for `sanic` | `pip3 install -e '.[test]'` | -| extras_require['dev'] | Additional Development requirements to add contributing | `pip3 install -e '.[dev]'` | -| extras_require['docs'] | Dependencies required to enable building and enhancing sanic documentation | `pip3 install -e '.[docs]'` | +| 依赖类型 | 用法 | 安装 | +| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------- | +| 所需经费 | 智能正常运行所需的最低依赖关系 | `pip3 install -e .` | +| tests_request / extras_require['test'] | 运行 `sanic` 设备测试所需的依赖关系 | \`pip3 install -e '.[test]' | +| extras_require['dev'] | 增加捐款的额外发展要求 | \`pip3 install -e '.[dev]' | +| extras_require['docs'] | 建立和加强卫生文档所需的依赖关系 | \`pip3 install -e '.[docs]' | -## Running all tests +## 正在运行所有测试 -To run the tests for Sanic it is recommended to use tox like so: +要运行 Sanic 测试，建议像这样使用tox： ```sh tox ``` -See it's that simple! +看看这么简单！ -`tox.ini` contains different environments. Running `tox` without any arguments will +`tox.ini`含有不同的环境。 Running `tox` without any arguments will run all unittests, perform lint and other checks. -## Run unittests +## 不需要时运行 -`tox` environment -> `[testenv]` +`tox` 环境 -> `[testenv]` -To execute only unittests, run `tox` with environment like so: +只能执行空闲的玩家就能运行类似于环境的\`毒性'： ```sh tox -e py37 -v -- tests/test_config.py -# or +# 或 tox -e py310 -v -- tests/test_config.py ``` -## Run lint checks +## 运行行检查 -`tox` environment -> `[testenv:lint]` +`tox` 环境 -> `[testenv:lin]` -Permform `flake8`\ , `black` and `isort` checks. +执行 `flake8` 、 `black` 和 `isort` 检查。 ```sh tox -e lint ``` -## Run type annotation checks +## 运行类型批注检查 -`tox` environment -> `[testenv:type-checking]` +`tox` 环境 -> `[testenv:type-checking]` -Permform `mypy` checks. +执行`mypy`检查。 ```sh -tox -e type-checking +tox -e 类型检查 ``` -## Run other checks +## 运行其他检查 -`tox` environment -> `[testenv:check]` +`tox` 环境 -> `[testenv:check]` -Perform other checks. +执行其他检查。 ```sh -tox -e check +tox -e 检查 ``` -## Run Static Analysis +## 运行静态分析 -`tox` environment -> `[testenv:security]` +`tox` 环境 -> `[testenv:security]` -Perform static analysis security scan +执行静态分析安全扫描 ```sh -tox -e security +tox -e 安全 ``` -## Run Documentation sanity check +## 运行文档智能检查 -`tox` environment -> `[testenv:docs]` +`tox` 环境 -> `[testenv:docs]` -Perform sanity check on documentation +对文档进行智能检查 ```sh -tox -e docs +tox -e 文档 ``` -## Code Style +## 代码样式 -To maintain the code consistency, Sanic uses the following tools: +为了保持代码的一致性，Sanic使用以下工具： 1. [isort](https://github.com/timothycrosley/isort) 2. [black](https://github.com/python/black) @@ -112,55 +112,55 @@ To maintain the code consistency, Sanic uses the following tools: ### isort -`isort` sorts Python imports. It divides imports into three categories sorted each in alphabetical order: +`isort` 排序的 Python 导入。 它将进口分为三类，按字母顺序排列： -1. built-in -2. third-party -3. project-specific +1. 内置的 +2. 第三方 +3. 特定项目 -### black +### 黑色 -`black` is a Python code formatter. +`black` 是一个 Python 代码格式。 -### flake8 +### 火焰8 -`flake8` is a Python style guide that wraps the following tools into one: +`flake8` 是一个 Python 风格指南，将以下工具包装成一个工具： 1. PyFlakes 2. pycodestyle -3. Ned Batchelder's McCabe script +3. Ned Batchid's McCabe 脚本 ### slotscheck `slotscheck` ensures that there are no problems with `__slots__` (e.g., overlaps, or missing slots in base classes). -`isort`, `black`, `flake8`, and `slotscheck` checks are performed during `tox` lint checks. +`isort`, `black`, `flake8`, `slotscheck` 检查是在 `tox` 链接检查期间进行的。 -The **easiest** way to make your code conform is to run the following before committing: +**最简单** 使您的代码符合要求的方法是在提交之前运行以下内容： ```bash -make pretty +做得很好 ``` -Refer to [tox documentation](https://tox.readthedocs.io/en/latest/index.html) for more details. +欲了解更多详情，请参阅[tox documentation](https\://tox.readthedocs.io/en/ index.html)。 -## Pull requests +## 拉取请求 -So the pull request approval rules are pretty simple: +所以拉取请求批准规则非常简单： -1. All pull requests must pass unit tests. -2. All pull requests must be reviewed and approved by at least one current member of the Core Developer team. -3. All pull requests must pass flake8 checks. -4. All pull requests must match `isort` and `black` requirements. -5. All pull requests must be **PROPERLY** type annotated, unless exemption is given. -6. All pull requests must be consistent with the existing code. -7. If you decide to remove/change anything from any common interface a deprecation message should accompany it in accordance with our [deprecation policy](https://sanicframework.org/en/guide/project/policies.html#deprecation). -8. If you implement a new feature you should have at least one unit test to accompany it. -9. An example must be one of the following: - - Example of how to use Sanic - - Example of how to use Sanic extensions - - Example of how to use Sanic and asynchronous library +1. 所有合并请求必须通过单元测试。 +2. 所有合并请求必须经过核心开发团队中至少一个当前成员的审查和批准。 +3. 所有合并请求都必须通过 flake8 检查。 +4. 所有合并请求必须匹配 `isort` 和 `black` 要求。 +5. 所有合并请求必须为 **PROPERLY** 类型，除非给予豁免。 +6. 所有合并请求必须与现有代码一致。 +7. 如果您决定从任何通用接口中移除/更改任何内容，则应根据我们的[废弃政策](https://sanicframework.org/en/guide/project/policies.html#disposition)随附一个废弃的消息。 +8. 如果你实现了一个新功能，你应该至少有一个单元测试来伴随它。 +9. 一个例子必须是： + - 如何使用 Sanic 的例子 + - 如何使用 Sanic 扩展 + - 如何使用 Sanic 和异步库的例子 -## Documentation +## 文件 -_Check back. We are reworking our documentation so this will change._ +回车. 我们正在重新编写我们的文件，以便改变这种情况。 From 25ea0ddd7134c619e2a123dd56466edd47754808 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:38 +0200 Subject: [PATCH 387/698] New translations policies.md (Japanese) --- guide/content/ja/organization/policies.md | 108 +++++++++++----------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/guide/content/ja/organization/policies.md b/guide/content/ja/organization/policies.md index 5870095910..1c6d3283c4 100644 --- a/guide/content/ja/organization/policies.md +++ b/guide/content/ja/organization/policies.md @@ -1,78 +1,78 @@ -# Policies +# ポリシー ## Versioning -Sanic uses [calendar versioning](https://calver.org/), aka "calver". To be more specific, the pattern follows: +Sanic は format@@0(https\://calver.org/), "calver" を使用しています。 具体的には、パターンは次のとおりです。 ``` YY.MM.MICRO ``` -Generally, versions are referred to in their `YY.MM` form. The `MICRO` number indicates an incremental patch version, starting at `0`. +一般的に、バージョンは `YY.MM` 形式で参照されます。 `MICRO` は、`0`から始まる増分パッチのバージョンを示します。 -## Reporting a Vulnerability +## 脆弱性の報告 -If you discover a security vulnerability, we ask that you **do not** create an issue on GitHub. Instead, please [send a message to the core-devs](https://community.sanicframework.org/g/core-devs) on the community forums. Once logged in, you can send a message to the core-devs by clicking the message button. +セキュリティ上の脆弱性が発見された場合は、GitHub で問題を **作成しない** ようお願いします。 代わりに、コミュニティフォーラムで format@@0(https\://community.sanicframework.org/g/core-devs) を参照してください。 ログインすると、メッセージボタンをクリックしてコア開発者にメッセージを送信できます。 -Alternatively, you can send a private message to Adam Hopkins on Discord. Find him on the [Sanic discord server](https://discord.gg/FARQzAEMAA). +あるいは、Adam Hopkins の Discordにプライベートメッセージを送信することもできます。 format@@0(https\://discord.gg/FARQzAEMAA) で彼を見つけてください。 -This will help to not publicize the issue until the team can address it and resolve it. +これは、チームが問題に対処して解決するまで問題を公表しないようにするのに役立ちます。 -## Release Schedule +## リリーススケジュール -There are four (4) scheduled releases per year: March, June, September, and December. Therefore, there are four (4) released versions per year: `YY.3`, `YY.6`, `YY.9`, and `YY.12`. +4 つあります (4) 年間スケジュールリリース: 3月, 6月, 9月, 12月. そのため、`YY.3`、`YY.6`、`YY.9`、`YY.12`の4つのリリースバージョンがあります。 -This release schedule provides: +このリリーススケジュールは以下のとおりです。 -- a predictable release cadence, -- relatively short development windows allowing features to be regularly released, -- controlled [deprecations](#deprecation), and -- consistent stability with a yearly LTS. +- 予測可能なリリースケイデンスが +- 比較的短い開発ウィンドウにより、定期的に機能がリリースされます。 +- [deprecations](#deprecation) を制御しました +- 年間のLTSと安定しています -We also use the yearly release cycle in conjunction with our governance model, covered by the [S.C.O.P.E.](./scope.md) +[S.C.O.P.E.](./scope.md) でカバーされるガバナンスモデルと併せて、年次リリースサイクルも使用します。 -### Long term support v Interim releases +### 長期サポート v 中間リリース -Sanic releases a long term support release (aka "LTS") once a year in December. The LTS releases receive bug fixes and security updates for **24 months**. Interim releases throughout the year occur every three months, and are supported until the subsequent release. +Sanicは12月に年に一度長期サポートリリース(別名「LTS」)をリリースしています。 LTSリリースでは、**24ヶ月**のバグ修正とセキュリティアップデートを受け取ります。 年間を通じた中間リリースは3ヶ月ごとに行われ、その後のリリースまでサポートされています。 -| Version | Release | LTS | Supported | -| ------- | ---------- | ------------- | --------- | -| 23.12 | 2023-12-31 | until 2025-12 | ✅ | -| 23.6 | 2023-07-25 | | ⚪ | -| 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | -| 22.9 | 2022-09-29 | | ⚪ | -| 22.6 | 2022-06-30 | | ⚪ | -| 22.3 | 2022-03-31 | | ⚪ | -| 21.12 | 2021-12-26 | | ⚪ | -| 21.9 | 2021-09-30 | | ⚪ | -| 21.6 | 2021-06-27 | | ⚪ | -| 21.3 | 2021-03-21 | | ⚪ | -| 20.12 | 2020-12-29 | | ⚪ | -| 20.9 | 2020-09-30 | | ⚪ | -| 20.6 | 2020-06-28 | | ⚪ | -| 20.3 | 2020-05-14 | | ⚪ | -| 19.12 | 2019-12-27 | | ⚪ | -| 19.9 | 2019-10-12 | | ⚪ | -| 19.6 | 2019-06-21 | | ⚪ | -| 19.3 | 2019-03-23 | | ⚪ | -| 18.12 | 2018-12-27 | | ⚪ | -| 0.8.3 | 2018-09-13 | | ⚪ | -| 0.7.0 | 2017-12-06 | | ⚪ | -| 0.6.0 | 2017-08-03 | | ⚪ | -| 0.5.4 | 2017-05-09 | | ⚪ | -| 0.4.1 | 2017-02-28 | | ⚪ | -| 0.3.1 | 2017-02-09 | | ⚪ | -| 0.2.0 | 2017-01-14 | | ⚪ | -| 0.1.9 | 2016-12-25 | | ⚪ | -| 0.1.0 | 2016-10-16 | | ⚪ | +| バージョン | リリース | LTS | サポート | +| ----- | ---------- | ------------ | ---- | +| 23.12 | 2023-12-31 | 2025年から12年まで | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | 2024年～12年まで | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | +| 0.8.3 | 2018-09-13 | | ⚪ | +| 0.7.0 | 2017-12-06 | | ⚪ | +| 0.6.0 | 2017-08-03 | | ⚪ | +| 0.5.4 | 2017-05-09 | | ⚪ | +| 0.4.1 | 2017-02-28 | | ⚪ | +| 0.3.1 | 2017-02-09 | | ⚪ | +| 0.2.0 | 2017-01-14 | | ⚪ | +| 0.1.9 | 2016-12-25 | | ⚪ | +| 0.1.0 | 2016-10-16 | | ⚪ | -☑️ = security fixes\ -✅ = full support\ -⚪ = no support +☑️ = セキュリティ修正\ +✅ = フルサポート\ +⚪ = サポートなし -## Deprecation +## 廃止予定 -Before a feature is deprecated, or breaking changes are introduced into the API, it shall be publicized and shall appear with deprecation warnings through two release cycles. No deprecations shall be made in an LTS release. +機能が廃止される前、またはAPIに互換性のない変更が導入されます。 それは公表され非推奨の警告とともに2つのリリースサイクルを通じて表示されるものとします。 非推奨はLTSリリースで行われることはありません。 -Breaking changes or feature removal may happen outside of these guidelines when absolutely warranted. These circumstances should be rare. For example, it might happen when no alternative is available to curtail a major security issue. +絶対的に保証された場合、変更または機能の削除はこれらのガイドラインの外で行われることがあります。 これらの状況はまれであるべきである。 たとえば、主要なセキュリティ問題を削減する代替手段がない場合に発生する可能性があります。 From ba4e6d5d374f5eed30964051867fb1a6f7c54172 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:40 +0200 Subject: [PATCH 388/698] New translations policies.md (Chinese Simplified) --- guide/content/zh/organization/policies.md | 132 +++++++++++----------- 1 file changed, 66 insertions(+), 66 deletions(-) diff --git a/guide/content/zh/organization/policies.md b/guide/content/zh/organization/policies.md index 5870095910..24e8b68553 100644 --- a/guide/content/zh/organization/policies.md +++ b/guide/content/zh/organization/policies.md @@ -1,78 +1,78 @@ -# Policies +# 政策 ## Versioning -Sanic uses [calendar versioning](https://calver.org/), aka "calver". To be more specific, the pattern follows: +Sanic 使用 [日历版本](https://calver.org/), 别名“calver”。 为了更具体地说明以下模式： ``` -YY.MM.MICRO +YY.MMM.MMRO ``` -Generally, versions are referred to in their `YY.MM` form. The `MICRO` number indicates an incremental patch version, starting at `0`. - -## Reporting a Vulnerability - -If you discover a security vulnerability, we ask that you **do not** create an issue on GitHub. Instead, please [send a message to the core-devs](https://community.sanicframework.org/g/core-devs) on the community forums. Once logged in, you can send a message to the core-devs by clicking the message button. - -Alternatively, you can send a private message to Adam Hopkins on Discord. Find him on the [Sanic discord server](https://discord.gg/FARQzAEMAA). - -This will help to not publicize the issue until the team can address it and resolve it. - -## Release Schedule - -There are four (4) scheduled releases per year: March, June, September, and December. Therefore, there are four (4) released versions per year: `YY.3`, `YY.6`, `YY.9`, and `YY.12`. - -This release schedule provides: - -- a predictable release cadence, -- relatively short development windows allowing features to be regularly released, -- controlled [deprecations](#deprecation), and -- consistent stability with a yearly LTS. - -We also use the yearly release cycle in conjunction with our governance model, covered by the [S.C.O.P.E.](./scope.md) - -### Long term support v Interim releases - -Sanic releases a long term support release (aka "LTS") once a year in December. The LTS releases receive bug fixes and security updates for **24 months**. Interim releases throughout the year occur every three months, and are supported until the subsequent release. - -| Version | Release | LTS | Supported | -| ------- | ---------- | ------------- | --------- | -| 23.12 | 2023-12-31 | until 2025-12 | ✅ | -| 23.6 | 2023-07-25 | | ⚪ | -| 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | -| 22.9 | 2022-09-29 | | ⚪ | -| 22.6 | 2022-06-30 | | ⚪ | -| 22.3 | 2022-03-31 | | ⚪ | -| 21.12 | 2021-12-26 | | ⚪ | -| 21.9 | 2021-09-30 | | ⚪ | -| 21.6 | 2021-06-27 | | ⚪ | -| 21.3 | 2021-03-21 | | ⚪ | -| 20.12 | 2020-12-29 | | ⚪ | -| 20.9 | 2020-09-30 | | ⚪ | -| 20.6 | 2020-06-28 | | ⚪ | -| 20.3 | 2020-05-14 | | ⚪ | -| 19.12 | 2019-12-27 | | ⚪ | -| 19.9 | 2019-10-12 | | ⚪ | -| 19.6 | 2019-06-21 | | ⚪ | -| 19.3 | 2019-03-23 | | ⚪ | -| 18.12 | 2018-12-27 | | ⚪ | -| 0.8.3 | 2018-09-13 | | ⚪ | -| 0.7.0 | 2017-12-06 | | ⚪ | -| 0.6.0 | 2017-08-03 | | ⚪ | -| 0.5.4 | 2017-05-09 | | ⚪ | -| 0.4.1 | 2017-02-28 | | ⚪ | -| 0.3.1 | 2017-02-09 | | ⚪ | -| 0.2.0 | 2017-01-14 | | ⚪ | -| 0.1.9 | 2016-12-25 | | ⚪ | -| 0.1.0 | 2016-10-16 | | ⚪ | +一般情况下，版本在他们的 `YY.MM` 表格中被引用。 `MICRO`数字表示一个递增补补版，从`0`开始。 + +## 报告脆弱性 + +如果你发现安全脆弱性，我们请你**不**在GitHub 上创建一个问题。 相反，请在社区论坛上[发送消息给core-devs](https://community.sanicframework.org/g/core-devs)。 登录后，您可以通过单击消息按钮向核心开发人员发送消息。 + +或者，您可以在 Discord 上向Adam Hopkins发送私信。 在 [Sanic Discord 服务器](https://discord.gg/RARQzAEMA) 查找他。 + +这将有助于在小组能够处理和解决问题之前不予公布。 + +## 发布计划 + +计划每年释放四(4)人：3月、6月、9月和12月。 因此，每年发布4种版本：`YY.3`、`YY.6`、`YY.9`和`YY.12`。 + +此发布时间表规定： + +- 一种可预见的释放方式， +- 相对较短的开发窗口，允许定期发布功能， +- 控制 [deprecations](#废弃)，及 +- 与一年一度的LTS保持稳定性。 + +我们还使用年度发行周期，同时使用 [S.C.O.P.E.](./ scope.md) + +### 长期支助诉临时释放案 + +12月，Sanic每年发布一次长期支持释放（又名“LTS”）。 LTS 版本在 **24 个月**中获得错误修复和安全更新。 全年的临时释放每三个月进行一次，并在随后的释放之前得到支持。 + +| 版本 | 发布 | LTS | 支持的 | +| ----- | ---------- | ------- | --- | +| 23.12 | 2023-12-31 | 2025-12 | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | 2024-12 | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | +| 0.8.3 | 2018-09-13 | | ⚪ | +| 0.7.0 | 2017-12-06 | | ⚪ | +| 0.6.0 | 2017-08-03 | | ⚪ | +| 0.5.4 | 2017-05-09 | | ⚪ | +| 0.4.1 | 2017-02-28 | | ⚪ | +| 0.3.1 | 2017-02-09 | | ⚪ | +| 0.2.0 | 2017-01-14 | | ⚪ | +| 0.1.9 | 2016-12-25 | | ⚪ | +| 0.1.0 | 2016-10-16 | | ⚪ | ☑️ = security fixes\ -✅ = full support\ -⚪ = no support +:check_mark_buton: = 完全支持\ +⚪ = 不支持 -## Deprecation +## 废弃的 -Before a feature is deprecated, or breaking changes are introduced into the API, it shall be publicized and shall appear with deprecation warnings through two release cycles. No deprecations shall be made in an LTS release. +在某个功能被废弃之前，或者对API引入破解的更改。 它应予公布，并应在两个释放周期内以过时警告出现。 LTS 版本中不应放弃使用。 -Breaking changes or feature removal may happen outside of these guidelines when absolutely warranted. These circumstances should be rare. For example, it might happen when no alternative is available to curtail a major security issue. +在绝对必要的情况下，有可能在这些准则之外发生打破变化或取消特征的情况。 这种情况应该是少见的。 例如，如果没有其他办法来减少一个重大的安全问题，就可能出现这种情况。 From 414d67402733bddf209cfe95d033e0cc2caf84cf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:41 +0200 Subject: [PATCH 389/698] New translations scope.md (Japanese) --- guide/content/ja/organization/scope.md | 280 ++++++++++++------------- 1 file changed, 140 insertions(+), 140 deletions(-) diff --git a/guide/content/ja/organization/scope.md b/guide/content/ja/organization/scope.md index 47a1c4f085..078f5d0358 100644 --- a/guide/content/ja/organization/scope.md +++ b/guide/content/ja/organization/scope.md @@ -1,257 +1,257 @@ -# Sanic Community Organization Policy E-manual (SCOPE) +# Sanic Community Organization ポリシー E-manual (SCOPE) .. attrs:: -:class: is-size-7 +:class: is size-7 ``` -_December 2019, version 1_ +_2019年12月バージョン1_ ``` -## Goals +## 目標 -To create a sustainable, community-driven organization around the Sanic projects that promote: (1) stability and predictability, (2) quick iteration and enhancement cycles, (3) engagement from outside contributors, (4) overall reliable software, and (5) a safe, rewarding environment for the community members. +Sanicプロジェクトで促進される持続可能でコミュニティ主導の組織を作るために、(1)安定性と予測可能性、(2)反復性とエンハンスメントサイクルを促進する。 (3)外部からの関与、(4)全体的な信頼性の高いソフトウェア、(5)コミュニティメンバーにとって安全でやりがいのある環境。 -## Overview +## 概要 -This Policy is the governance model for the Sanic Community Organization (“SCO”). The SCO is a meritocratic, consensus-based community organization responsible for all projects adopted by it. Anyone with an interest in one of the projects can join the community, contribute to the community or projects, and participate in the decision making process. This document describes how that participation takes place and how to set about earning merit within the project community. +本ポリシーは、Sanic Community Organization (以下「SCO」)のガバナンスモデルです。 SCOは、それによって採択されたすべてのプロジェクトに対して責任を負う、合意に基づくメリットがあるコミュニティ組織です。 プロジェクトのいずれかに興味がある人は誰でもコミュニティに参加できます。 コミュニティやプロジェクトに貢献し、意思決定プロセスに参加する。 このドキュメントでは、その参加がどのように行われ、プロジェクトコミュニティ内でどのようにメリットを得るかについて説明します。 -## Structure +## 構成 -The SCO has multiple **projects**. Each project is represented by a single GitHub repository under the Sanic community umbrella. These projects are used by **users**, developed by **contributors**, governed by **core developers**, released by **release managers**, and ultimately overseen by a **steering council**. If this sounds similar to the Python project and PEP 8016 that is because it is intentionally designed that way. +SCOには複数の**プロジェクト**があります。 各プロジェクトは、Sanic community の傘下にある GitHub リポジトリによって表されます。 これらのプロジェクトは**ユーザー**によって開発された**貢献者**によって**解放マネージャー**によってリリースされ、**ステアリング評議会**によって最終的に監督される**コア開発者**によって管理されています。 これが Python プロジェクトや PEP 8016 に似ている場合は、意図的にそのように設計されているためです。 -## Roles and responsibilities +## 役割と責任 -### Users +### ユーザー -Users are community members who have a need for the projects. They are the developers and personnel that download and install the packages. Users are the **most important** members of the community and without them the projects would have no purpose. Anyone can be a user and the licenses adopted by the projects shall be appropriate open source licenses. +ユーザーはプロジェクトを必要とするコミュニティメンバーです。 彼らは、パッケージをダウンロードしてインストールする開発者や人員です。 ユーザーはコミュニティの**最も重要な**メンバーであり、それがなければプロジェクトは何の目的もありません。 誰でも利用者であり、プロジェクトによって採用されたライセンスは、適切なオープンソースライセンスでなければなりません。 -_The SCO asks its users to participate in the project and community as much as possible._ +_SCOはできるだけ多くのプロジェクトとコミュニティに参加するようユーザーに要求します。_ -User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to): +ユーザー貢献により、プロジェクトチームはそれらのユーザーのニーズを確実に満たすことができます。 一般的なユーザーの貢献には以下のものが含まれます(これらに限定されません)。 -- evangelizing about the project (e.g. a link on a website and word-of-mouth awareness raising) -- informing developers of strengths and weaknesses from a new user perspective -- providing moral support (a ‘thank you’ goes a long way) -- providing financial support (the software is open source, but its developers need to eat) +- プロジェクトについての伝道（例：ウェブサイトのリンクや口コミ啓発など） +- 新しいユーザーの視点から強みと弱みを開発者に伝えることです +- 道徳的サポートを提供する（「ありがとう」は長い道のりを行く） +- 資金援助を提供する(ソフトウェアはオープンソースですが、開発者は食べる必要があります) -Users who continue to engage with the SCO, its projects, and its community will often become more and more involved. Such users may find themselves becoming contributors, as described in the next section. +SCO、そのプロジェクト、およびそのコミュニティに引き続き関与し続けるユーザーは、多くの場合、ますます関与するようになります。 次のセクションで説明されているように、そのようなユーザーは自分自身が貢献者になる可能性があります。 -### Contributors +### 貢献者 -Contributors are community members who contribute in concrete ways to one or more of the projects. Anyone can become a contributor and contributions can take many forms. Contributions and requirements are governed by each project separately by a contribution policy. +貢献者は、プロジェクトの1つ以上の方法で具体的に貢献するコミュニティメンバーです。 誰でも貢献者になることができ、貢献は多くの形式をとることができます。 貢献と要件は、それぞれのプロジェクトで個別に貢献ポリシーによって管理されます。 -There is **no expectation** of commitment to the project, **no specific skill requirements** and **no selection process**. +**プロジェクトへのコミットメントの期待はありません**特定のスキル要件はありません**と**選択プロセスはありません\*\*。 -In addition to their actions as users, contributors may also find themselves doing one or more of the following: +ユーザーとしての行動に加えて、貢献者は自分自身が次のいずれかまたは複数を実行していることがあります: -- supporting new users (existing users are often the best people to support new users) -- reporting bugs -- identifying requirements -- providing graphics and web design -- Programming -- example use cases -- assisting with project infrastructure -- writing documentation -- fixing bugs -- adding features -- providing constructive opinions and engaging in community discourse +- 新規ユーザーのサポート (既存のユーザーは新規ユーザーをサポートするのに最適なユーザーです) +- バグの報告 +- 要件を特定する +- グラフィックやウェブデザインを提供し +- プログラミング +- ユースケースの例 +- プロジェクトのインフラ整備の支援 +- ドキュメントの書き込み +- バグの修正 +- 機能の追加 +- 建設的な意見を述べコミュニティの議論に従事し -Contributors engage with the projects through GitHub and the Community Forums. They submit changes to the projects itself via pull requests, which will be considered for inclusion in the project by the community at large. The Community Forums are the most appropriate place to ask for help when making that first contribution. +貢献者はGitHubとコミュニティフォーラムを通じてプロジェクトに取り組んでいます。 彼らはプルリクエストを介してプロジェクト自体に変更を提出します。これは、一般的にコミュニティによってプロジェクトに含められると考えられます。 コミュニティフォーラムは、最初の貢献をする際に助けを求めるのに最適な場所です。 -Indeed one of the most important roles of a contributor may be to **simply engage in the community conversation**. Most decisions about the direction of a project are made by consensus. This is discussed in more detail below. In general, however, it is helpful for the health and direction of the projects for the contributors to **speak freely** (within the confines of the code of conduct) and **express their opinions and experiences** to help drive the consensus building. +実際、貢献者の最も重要な役割の一つは、**単にコミュニティの会話に参加する**ことです。 プロジェクトの方向性に関するほとんどの決定は、コンセンサスによって行われます。 これについては、後述します。 しかし、一般的には、 貢献者が**自由に話す**(行動規範の範囲内で)プロジェクトの健康と方向性に役立ち、**意見や経験を表明**してコンセンサスの構築を促進します。 -As contributors gain experience and familiarity with a project, their profile within, and commitment to, the community will increase. At some stage, they may find themselves being nominated for a core developer team. +貢献者がプロジェクトの経験と慣れ親しみを得るにつれて、彼らの内側のプロファイルとコミュニティへのコミットメントが増加します。 ある段階では、コア開発チームにノミネートされることがあります。 -### Core Developer +### コア開発者 -Each project under the SCO umbrella has its own team of core developers. They are the people in charge of that project. +SCO傘下の各プロジェクトには、コア開発者のチームがあります。 彼らはそのプロジェクトを担当している人々です。 -_What is a core developer?_ +_コア開発者とは何ですか？_ -Core developers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Being a core developer allows contributors to more easily carry on with their project related activities by giving them direct access to the project’s resources. They can make changes directly to the project repository without having to submit changes via pull requests from a fork. +コア開発者は、コミュニティとの継続的な関わりを通じてプロジェクトの継続的な開発に取り組んでいることを示したコミュニティメンバーです。 コア開発者であることは、プロジェクトのリソースに直接アクセスできるようにすることで、貢献者がプロジェクト関連のアクティビティをより簡単に継続できるようにします。 フォークからのプルリクエストを介して変更を送信することなく、プロジェクトリポジトリに直接変更を加えることができます。 -This does not mean that a core developer is free to do what they want. In fact, core developers have no more direct authority over the final release of a package than do contributors. While this honor does indicate a valued member of the community who has demonstrated a healthy respect for the project’s aims and objectives, their work continues to be reviewed by the community before acceptance in an official release. +これは、コア開発者が自分の望むことを自由に行うことを意味するものではありません。 実際、コア開発者はパッケージの最終リリースに対して、貢献者より直接的な権限を持っていません。 この名誉は、プロジェクトの目的と目的に対して健全な敬意を示しているコミュニティの重要なメンバーを示しています。 彼らの仕事は公表前にコミュニティによって見直され続けています -_What can a core developer do on a project?_ +_コア開発者はプロジェクトで何ができますか？_ -Each project might define this role slightly differently. However, the general usage of this designation is that an individual has risen to a level of trust within the community such that they now are given some control. This comes in the form of push rights to non-protected branches, and the ability to have a voice in the approval of pull requests. +各プロジェクトは、この役割を若干異なって定義することができます。 ただし、 一般的に使用されているのは、個人がコミュニティ内で信頼されるようになったということです 彼らは今何らかの制御を与えられるようになったのです これは、保護されていないブランチに対するプッシュ権限、およびプルリクエストの承認で声を持つ能力の形で来ます。 -The projects employ various communication mechanisms to ensure that all contributions are reviewed by the community as a whole. This includes tools provided by GitHub, as well as the Community Forums. By the time a contributor is invited to become a core developer, they should be familiar with the various tools and workflows as a user and then as a contributor. +プロジェクトは様々なコミュニケーションメカニズムを採用し、すべての貢献がコミュニティ全体によって見直されるようにしています。 これには、コミュニティフォーラムだけでなく、GitHubが提供するツールも含まれます。 貢献者がコア開発者になるために招待されるまでに。 ユーザーとしてそして貢献者として 様々なツールやワークフローに精通しているべきです -_How to become a core developer?_ +_コア開発者になるには？_ -Anyone can become a core developer; there are no special requirements, other than to have shown a willingness and ability to positively participate in the project as a team player. +誰でもコア開発者になることができます。 特別な要件はありませんチームプレーヤーとして プロジェクトに積極的に参加する意欲と能力を示す以外は -Typically, a potential core developer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time. However, there is **no technical or other skill** requirement for eligibility. +通常、潜在的なコア開発者は、プロジェクト、その目的、およびその戦略について理解していることを示す必要があります。 彼らはまた、期間の間にプロジェクトに貴重な貢献を提供します。 ただし、資格については、**技術的またはその他のスキル**の要件はありません。 -New core developers can be **nominated by any existing core developer** at any time. At least twice a year (April and October) there will be a ballot process run by the Steering Council. Voting should be done by secret ballot. Each existing core developer for that project receives a number of votes equivalent to the number of nominees on the ballot. For example, if there are four nominees, then each existing core developer has four votes. The core developer may cast those votes however they choose, but may not vote for a single nominee more than once. A nominee must receive two-thirds approval from the number of cast ballots (not the number of eligible ballots). Once accepted by the core developers, it is the responsibility of the Steering Council to approve and finalize the nomination. The Steering Council does not have the right to determine whether a nominee is meritorious enough to receive the core developer title. However, they do retain the right to override a vote in cases where the health of the community would so require. +新しいコア開発者はいつでも**既存のコア開発者**にノミネートされることができます。 少なくとも年に2回(4月と10月)は、運営協議会によって実施される投票プロセスがあります。 投票は秘密の投票によって行われるべきです。 そのプロジェクトの各コア開発者は、投票で候補者の数に相当する数の票を受け取ります。 例えば、4人のノミネート者がいる場合、各既存のコア開発者には4つの投票があります。 コア開発者は、しかし、それらの投票をキャストすることができますが、複数回のノミネートに投票することはできません。 候補者は、キャスト投票数(適格投票数ではない)から3分の2の承認を得なければなりません。 コア開発者によって受け入れられると、それは指名を承認し、最終的に決定するためのステアリング評議会の責任です。 The Steering Council は、ノミネート者がコア開発者のタイトルを受け取るのに十分な功績があるかどうかを判断する権利を持っていません。 しかしながら、コミュニティの健全性が必要とされる場合には、投票を無効にする権利は保持されます。 -Once the vote has been held, the aggregated voting results are published on the Community Forums. The nominee is entitled to request an explanation of any override against them. A nominee that fails to be admitted as a core developer may be nominated again in the future. +投票が行われると、集計された投票結果がコミュニティフォーラムに掲載されます。 ノミネート候補者は、それらに対するオーバーライドの説明を要求する権利があります。 コア開発者として認められていない候補者は、今後再度ノミネートされる可能性があります。 -It is important to recognize that being a core developer is a privilege, not a right. That privilege must be earned and once earned it can be removed by the Steering Council (see next section) in extreme circumstances. However, under normal circumstances the core developer title exists for as long as the individual wishes to continue engaging with the project and community. +コア開発者であることは、権利ではなく特権であることを認識することが重要です。 その特権は獲得されなければならず、一度獲得されると極端な状況で運営評議会(次のセクションを参照)によって削除することができます。 しかし、通常の状況では、個々の人がプロジェクトやコミュニティと引き続き関わりたいと思っている限り、開発者のタイトルは存在します。 -A committer who shows an above-average level of contribution to the project, particularly with respect to its strategic direction and long-term health, may be nominated to become a member of the Steering Council, or a Release Manager. This role is described below. +プロジェクトへの平均以上の貢献度を示すコミッター, 特にその戦略的な方向性と長期的な健康に関して. ステアリング評議会またはリリースマネージャのメンバーになるために指名することができます。 この役割については、以下で説明します。 -_What are the rights and responsibilities of core developers?_ +_コア開発者の権利と責任は何ですか？_ -As discussed, the majority of decisions to be made are by consensus building. In certain circumstances where an issue has become more contentious, or a major decision needs to be made, the Release Manager or Steering Council may decide (or be required) to implement the RFC process, which is outlined in more detail below. +議論されたように、すべき決定の大部分はコンセンサスの構築によって行われる。 問題がより論争的になった、または主要な決定がなされる必要がある特定の状況で。 Release Manager または Steering Council は、下記より詳細に概説されている RFC プロセスを実装するために決定(または要求される)することができます。 -It is also incumbent upon core developers to have a voice in the governance of the community. All core developers for all of the projects have the ability to be nominated to be on the Steering Council and vote in their elections. +また、コミュニティのガバナンスにおいて発言権を持つことは、コア開発者にも課せられています。 すべてのプロジェクトのコア開発者は、運営評議会に推薦され、選挙に投票する能力を持っています。 -This Policy (the “SCOPE”) may only be changed under the authority of two-thirds of active core developers, except that in the first six (6) months after adoption, the core developers reserve the right to make changes under the authority of a simple majority of active core developers. +このポリシー（以下「SCOPE」）は、アクティブなコア開発者の3分の2の権限の下でのみ変更することができます。 養子縁組終了後最初の6ヶ月で コア開発者は単なる大多数のアクティブ開発者の権限の下で 変更を加える権利を保有しています -_What if a core developer becomes inactive?_ +_コア開発者が非アクティブになったらどうしますか？_ -It is hoped that all core developers participate and remain active on a regular basis in their projects. However, it is also understood that such commitments may not be realistic or possible from time to time. +すべてのコア開発者がプロジェクトに参加し、定期的に活動を続けることが期待されています。 しかし、そのようなコミットメントは時々現実的ではないかもしれない、あるいは可能ではないかもしれないことも理解されています。 -Therefore, the Steering Council has the duty to encourage participation and the responsibility to place core developers into an inactive status if they are no longer willing or capable to participate. The main purpose of this is **not to punish** a person for behavior, but to help the development process to continue for those that do remain active. +そのため、 運営評議会は、参加を奨励する義務があり、コア開発者がもはや参加する意思がない、または参加できる能力がない場合は、非アクティブな状態に置く責任があります。 この主な目的は、**行動のために人を罰しない**ことです。 開発プロセスが続けられるようにするためです -To this end, a core developer that becomes “inactive” shall not have commit rights to a repository, and shall not participate in any votes. To be eligible to vote in an election, a core developer **must have been active** at the time of the previous scheduled project release. +この目的のために、「非アクティブ」になるコア開発者は、リポジトリに対する権利をコミットせず、いかなる投票にも参加してはなりません。 選挙に投票する資格を得るためには、前の予定されたプロジェクトリリース時にコア開発者**がアクティブでなければなりません**。 -Inactive members may ask the Steering Council to reinstate their status at any time, and upon such request the Steering Council shall make the core developer active again. +活動していないメンバーは、運営評議会にいつでも地位を復活させるよう要請することができます。 そして、そのような要請に応じて、運営評議会は、コア開発者を再び活性化させるものとする。 -Individuals that know they will be unable to maintain their active status for a period are asked to be in communication with the Steering Council and declare themselves inactive if necessary. +一定期間アクティブな地位を維持することができないことを知っている個人は、運営評議会と連絡を取り、必要に応じて非アクティブであると宣言するよう求められます。 -An “active” core developer is an individual that has participated in a meaningful way during the previous six months. Any further definition is within the discretion of the Steering Council. +「アクティブ」なコア開発者は、過去6ヶ月間に有意義な方法で参加した個人です。 これ以上の定義は、運営協議会の裁量の範囲内にあります。 -### Release Manager +### リリースマネージャー -Core developers shall have access only to make commits and merges on non-protected branches. The “master” branch and other protected branches are controlled by the release management team for that project. Release managers shall be elected from the core development team by the core development team, and shall serve for a full release cycle. +コア開発者は、保護されていないブランチに対してコミットとマージを行うためにのみアクセスできるものとします。 「master」ブランチと他の保護されたブランチは、そのプロジェクトのリリース管理チームによって管理されます。 リリースマネージャーは、コア開発チームによってコア開発チームから選出され、完全なリリースサイクルのために役立つものとします。 -Each core developer team may decide how many release managers to have for each release cycle. It is highly encouraged that there be at least two release managers for a release cycle to help divide the responsibilities and not force too much effort upon a single person. However, there also should not be so many managers that their efforts are impeded. +各コア開発チームは、各リリースサイクルに必要なリリースマネージャーの数を決定できます。 少なくとも2人のリリースマネージャーがリリースサイクルで責任を分担し、一人の人にあまり努力を強いられないようにすることを強くお勧めします。 しかし、彼らの努力が妨げられるほど多くの管理者がいるべきではありません。 -The main responsibilities of the release management team include: +リリース管理チームの主な責任は次のとおりです。 -- push the development cycle forward by monitoring and facilitating technical discussions -- establish a release calendar and perform actions required to release packages -- approve pull requests to the master branch and other protected branches -- merge pull requests to the master branch and other protected branches +- 技術的な議論を監視し促進することで開発サイクルを前進させ +- リリースカレンダーを確立し、パッケージをリリースするために必要なアクションを実行します +- マスターブランチや他の保護されたブランチへのプルリクエストを承認する +- マスターブランチと他の保護されたブランチにプルリクエストをマージする -The release managers **do not have the authority to veto or withhold a merge** of a pull request that otherwise meets contribution criteria and has been accepted by the community. It is not their responsibility to decide what should be developed, but rather that the decisions of the community are carried out and that the project is being moved forward. +リリースマネージャーは、プルリクエストのマージを拒否または保留する権限がありません。これらは、コントリビューション基準を満たしており、コミュニティによって受け入れられています。 何を開発すべきかを決めるのは彼らの責任ではありません。 共同体の決定が下されプロジェクトが進められているのです -From time to time, a decision may need to be made that cannot be achieved through consensus. In that case, the release managers have the authority to call upon the removal of the decision to the RFC process. This should not occur regularly (unless required as discussed below), and its use should be discouraged in favor of the more communal consensus building strategy. +時折、合意によっては達成できない決定が必要な場合があります。 その場合、リリース マネージャは、RFC プロセスへの決定の削除を要求する権限を持っています。 これは定期的に発生するべきではありません(以下で説明するように必要な場合を除きます)。そして、その使用は、より共同的なコンセンサスの構築戦略に賛成することをお勧めしません。 -Since not all projects have the same requirements, the specifics governing release managers on a project shall be set forth in an Appendix to this Policy, or in the project’s contribution guidelines. +すべてのプロジェクトが同じ要件を持っているわけではないので、 プロジェクトのリリースマネージャーに関する詳細は、本ポリシーの付録またはプロジェクトのコントリビューションガイドラインに記載されています。 -If necessary, the Steering Council has the right to remove a release manager that is derelict in their duties, or for other good cause. +必要に応じて、ステアリング評議会には、職務を放棄する、または他の正当な理由のために、リリースマネージャーを削除する権利があります。 -### Steering Council +### 運営評議会format@@0 -The Steering Council is the governing body consisting of those individuals identified as the “project owner” and having control of the resources and assets of the SCO. Their ultimate goal is to ensure the smooth operation of the projects by removing impediments, and assisting the members as needed. It is expected that they will be regular voices in the community. +運営協議会は、「プロジェクト所有者」として特定され、SCOのリソースと資産を管理する個人からなる統治機関です。 彼らの最終的な目標は、障害を取り除き、必要に応じてメンバーを支援することにより、プロジェクトの円滑な運営を確保することです。 彼らはコミュニティの定期的な声になることが期待されています。 -_What can the Steering Council do?_ +_運営評議会に何ができるか？_ -The members of the Steering Council **do not individually have any more authority than any other core developer**, and shall not have any additional rights to make decisions, commits, merges, or the like on a project. +運営評議会のメンバーは、**他のどのコア開発者よりも権限を持っていません**。 プロジェクトの決定、約束、合併などを行う追加の権利は一切ありません -However, as a body, the Steering Council has the following capacity: +ただし、本体として、運営審議会には以下のような能力があります。 -- accept, remand, and reject all RFCs -- enforce the community code of conduct -- administer community assets such as repositories, servers, forums, integration services, and the like (or, to delegate such authority to someone else) -- place core developers into inactive status where appropriate take any other enforcement measures afforded to it in this Policy, including, in extreme cases, removing core developers -- adopt or remove projects from the community umbrella +- すべての RFC を受け入れ、再配布、および拒否する +- コミュニティの行動規範を施行し +- リポジトリ、サーバー、フォーラム、統合サービスなどのコミュニティ・アセットを管理する (または、そのような権限を他の誰かに委任する) +- コア開発者を非アクティブな状態に配置します。このポリシーで与えられたその他の執行措置を適切に取ります。 極端な場合にはコア開発者を排除し +- コミュニティの傘下からプロジェクトを採用したり削除したりします -It is highly encouraged that the Steering Council delegate its authority as much as possible, and where appropriate, to other willing community members. +運営評議会は、可能な限りその権限を、適切な場合には他の意欲的なコミュニティメンバーに委任することが強く奨励される。 -The Steering Council **does not have the authority** to change this Policy. +運営評議会は、このポリシーを変更する権限を持っていません\*\*。 -_How many members are on the Steering Council?_ +_運営協議会のメンバーは何人いますか？_ -Four. +4 -While it seems like a committee with four votes may potentially end in a deadlock with no way to break a majority vote, the Steering Council is discouraged from voting as much as possible. Instead, it should try to work by consensus, and requires three consenting votes when it is necessary to vote on a matter. +4票の委員会のように思われますが、多数決を破る方法がなく、潜在的に行き詰まり状態に終わる可能性があります。 運営評議会は、できるだけ多くの投票から落胆しています。 代わりにコンセンサスによって動作しようとする必要があります, それは問題に投票する必要がある場合は、3つの同意票を必要とします. -_How long do members serve on the Steering Council?_ +_運営協議会のメンバーはどれくらいですか？_ -A single term shall be for two calendar years starting in January. Terms shall be staggered so that each year there are two members continuing from the previous year’s council. +単期は1月から2暦年間とする。 利用規約は、毎年、前年の評議会から継続している2人のメンバーがあるようにずれるものとします。 -Therefore, the inaugural vote shall have two positions available for a two year term, and two positions available for a one year term. +そのため、就任票は2年の任期に2つの役職と1年の任期に2つの役職を設けなければならない。 -There are no limits to the number of terms that can be served, and it is possible for an individual to serve consecutive terms. +提供できる用語の数に制限はなく、個人が連続した用語を提供することができます。 -_Who runs the Steering Council?_ +_ステアリング評議会を運営するのは誰ですか？_ -After the Steering Council is elected, the group shall collectively decide upon one person to act as the Chair. The Chair does not have any additional rights or authority over any other member of the Steering Council. +運営評議会が選出された後、グループは、議長として行動する一人を共同で決定しなければならない。 議長は、運営協議会の他のメンバーよりも任意の追加の権利や権限を持っていません。 -The role of the Chair is merely as a coordinator and facilitator. The Chair is expected to ensure that all governance processes are adhered to. The position is more administrative and clerical, and is expected that the Chair sets agendas and coordinates discussion of the group. +議長の役割は、単にコーディネーターであり、ファシリテーターとしての役割です。 議長は、すべてのガバナンスプロセスが遵守されることを確実にすることが期待されます。 位置は、より行政的で明白であり、議題を設定し、グループの議論を調整することが期待されています。 -_How are council members elected?_ +_諮問委員はどうやって選ばれますか？_ -Once a year, **all eligible core developers** for each of the projects shall have the right to elect members to the Steering Council. +年に一度、プロジェクトごとに**すべての適格なコア開発者**は、Steering Councilのメンバーを選出する権利を有します。 -Nominations shall be open from September 1 and shall close on September 30. After that, voting shall begin on October 1 and shall close on October 31. Every core developer active on the date of the June release of the Sanic Framework for that year shall be eligible to receive one vote per vacant seat on the Steering Council. For the sake of clarity, to be eligible to vote, a core developer **does not** need to be a core developer on Sanic Framework, but rather just have been active within their respective project on that date. +推薦は9月1日から開始し、9月30日に終了するものとします。 その後、10月1日に投票を開始し、10月31日に終了します。 その年のサニック・フレームワークの6月リリースの日にアクティブなすべてのコア開発者は、ステアリング・カウンシルの空席あたり1票を受け取る資格があります。 明確にするために、投票の資格を得るために、コア開発者はSanic Frameworkのコア開発者である必要はありません\*\*。 それぞれのプロジェクトの中で活動しているのです -The top recipients of votes shall be declared the winners. If there is any tie, it is highly encouraged that the tied nominees themselves resolve the dispute before a decision is made at random. +投票の上位者は、勝者として宣言されるものとします。 提携がある場合は、結ばれた候補者自身が決定がランダムにされる前に紛争を解決することが強く奨励されます。 -In regards to the inaugural vote of the Steering Council, the top two vote-recipients shall serve for two years, and the next two vote-recipients shall assume the one-year seats. +運営評議会の議決については、上位2名が2年間務める。 次の2人の有権者が1年議席に就くことになります -To be an eligible candidate for the Steering Council, the individual must have been a core developer in active status on at least one project for the previous twelve months. +運営評議会の適格な候補者になるには 個人は過去12ヶ月間少なくとも1つのプロジェクトの現役の 中心的な開発者である必要があります -_What if there is a vacancy?_ +_空きがある場合はどうしますか_ -If a vacancy on the Steering Council exists during a term, then the next highest vote-recipient in the previous election shall be offered to complete the remainder of the term. If one cannot be found this way, the Steering Council may decide the most appropriate course of action to fill the seat (whether by appointment, vote, or other means). +運営審議会に欠員がある場合。 次の最高の投票受領者は任期の残りを完了するために提出されなければならない この方法で見つけることができない場合 運営評議会は、議席を埋めるための最も適切な行動の方法を決定することができます(任命、投票、または他の意味によってかどうか)。 -If a member of the Steering Council becomes inactive, then that individual shall be removed from the Steering Council immediately and the seat shall become vacant. +運営協議会のメンバーが非アクティブになった場合 その後、その個人は直ちに運営委員会から解任され、議席は空席となります。 -In extreme cases, the body of all core developers has the right to bring a vote to remove a member of the Steering Council for cause by a two-thirds majority of all eligible voting core developers. +極端な場合 すべてのコア開発者の本体は、適格な投票コア開発者の3分の2が運営評議会のメンバーを削除する投票権を持っています。 -_How shall the Steering Council conduct its business?_ +_運営評議会はどのように事業を行うか？_ -As much as possible, the Steering Council shall conduct its business and discussions in the open. Any member of the community should be allowed to enter the conversation with them. However, at times it may be necessary or appropriate for discussions to be held privately. Selecting the proper venue for conversations is part of the administrative duties of the Chair. +可能な限り、運営評議会は、事業と議論を公然と行う。 コミュニティのメンバーは、彼らとの会話に参加することを許可する必要があります。 ただし、個人的に議論を行う場合には、必要または適切な場合があります。 会話のための適切な会場を選択することは議長の行政業務の一部です。 -While the specifics of how to operate are beyond the scope of the Policy, it is encouraged that the Steering Council attempt to meet at least one time per quarter in a “real-time” discussion. This could be achieved via video conferencing, live chatting, or other appropriate means. +操作方法の詳細はポリシーの範囲を超えています。 運営評議会は、「リアルタイム」の議論で四半期に少なくとも1回は会うことを奨励されます。 これは、ビデオ会議、ライブチャット、または他の適切な手段によって達成することができます。 -## Support +## サポート -All participants in the community are encouraged to provide support for users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a community member. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal. +コミュニティのすべての参加者は、プロジェクト管理インフラストラクチャ内のユーザーにサポートを提供することをお勧めします。 このサポートは、コミュニティを成長させる方法として提供されています。 支援を求める人は、プロジェクト内のすべての支援活動が自発的であることを認識し、したがって、時間が許す限り提供されます。 したがって、保証された回答時間または結果を必要とするユーザーは、コミュニティメンバーからサポート契約を購入するよう求める必要があります。 しかし、それ自身の条件でプロジェクトに取り組むことをいとわない人のために。 他のユーザーを支援してくれるのは理想的です -## Decision making process +## 意思決定プロセス -Decisions about the future of the projects are made through discussion with all members of the community, from the newest user to the most experienced member. Everyone has a voice. +プロジェクトの将来についての決定は、コミュニティのすべてのメンバーとの議論を通じて行われます。 最新のユーザーから最も経験豊富なメンバーまで 誰もが声を持っている。 -All non-sensitive project management discussion takes place on the community forums, or other designated channels. Occasionally, sensitive discussions may occur in private. +機密性のないプロジェクト管理に関する議論は、コミュニティフォーラムやその他の指定されたチャンネルで行われます。 時折、機密性の高い議論がプライベートに行われることがあります。 -In order to ensure that the project is not bogged down by endless discussion and continual voting, the project operates a policy of **lazy consensus**. This allows the majority of decisions to be made without resorting to a formal vote. For any **major decision** (as defined below), there is a separate Request for Comment (RFC) process. +プロジェクトが終わりのない議論と継続的な投票によって妨げられないようにするために、プロジェクトは**怠惰な合意**のポリシーを運営しています。 これにより、正式な投票に頼らずに大多数の決定を行うことができます。 **大きな判断** (以下に定義します) については、別途コメントリクエスト(RFC) プロセスがあります。 -### Technical decisions +### 技術的な決定 -Pull requests and technical decisions should generally fall into the following categories. +プルリクエストと技術的な決定は、通常、以下のカテゴリーに分類されます。 -- **Routine**: Documentation fixes, code changes that are for cleanup or additional testing. No functionality changes. -- **Minor**: Changes to the code base that either fix a bug, or introduce a trivial feature. No breaking changes. -- **Major**: Any change to the code base that breaks or deprecates existing API, alters operation in a non-trivial manner, or adds a significant feature. +- **ルーチン**: ドキュメント修正、クリーンアップや追加テストのためのコード変更。 機能の変更はありません。 +- **Minor**: バグを修正したり、些細な機能を導入したりするコードベースへの変更。 改行の変更はありません。 +- **Major**: 既存のAPIを壊したり廃止したりするコードベースに変更を加えたり、些細な方法で操作を変更したり、重要な機能を追加したりします。 -It is generally the responsibility of the release managers to make sure that changes to the repositories receive the proper authorization before merge. +リポジトリへの変更がマージの前に適切な承認を受け取ることを確認するのは、通常、リリースマネージャの責任です。 -The release managers retain the authority to individually review and accept routine decisions that meet standards for code quality without additional input. +リリースマネージャーは、追加の入力なしにコード品質の基準を満たすルーチンの決定を個別にレビューし、受け入れる権限を保持します。 -### Lazy consensus +### 怠惰な -Decision making (whether by the community or Steering Council) typically involves the following steps: +意思決定(コミュニティまたは運営評議会によって)には通常、次のステップが含まれます。 -- proposal -- discussion -- vote (if consensus is not reached through discussion) -- decision +- 提案 +- ディスカッション +- 投票（議論を通じて合意に達していない場合） +- 決定 -Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should post a message on the appropriate channel on the Community forums, or submit a pull request implementing the idea on GitHub. This will prompt a review and, if necessary, a discussion of the idea. +コミュニティメンバーは誰でも、コミュニティによる検討のための提案をすることができます。 新しいアイデアについてのディスカッションを開始するには、コミュニティフォーラムに適切なチャネルにメッセージを投稿する必要があります。 または、GitHub でアイデアを実装するプルリクエストを送信します。 これは、レビューを促し、必要に応じて、アイデアの議論を促します。 -The goal of this review and discussion is to gain approval for the contribution. Since most people in the project community have a shared vision, there is often little need for discussion in order to reach consensus. +このレビューと議論の目的は、貢献の承認を得ることです。 プロジェクトコミュニティのほとんどの人々がビジョンを共有しているので、コンセンサスを得るためには議論の必要性がほとんどないことが多い。 -In general, as long as nobody explicitly opposes a proposal or patch, it is recognized as having the support of the community. This is called lazy consensus; that is, those who have not stated their opinion explicitly have implicitly agreed to the implementation of the proposal. +一般に、提案やパッチに明示的に反対する人がいない限り、それはコミュニティの支援を受けていると認識されています。 これは怠惰な合意と呼ばれます; すなわち, 彼らの意見を述べていない人々は、暗黙のうちに提案の実施に合意しました. -Lazy consensus is a very important concept within the SCO. It is this process that allows a large group of people to efficiently reach consensus, as someone with no objections to a proposal need not spend time stating their position, and others need not spend time reading such messages. +怠惰なコンセンサスはSCOの中で非常に重要な概念です。 大勢の人々が効率的にコンセンサスに達することを可能にするのはこのプロセスです。 提案に異議なしに自分の立場を述べるのに時間を費やす必要はない 他の人はそのようなメッセージを読む時間を費やす必要はない -For lazy consensus to be effective, it is necessary to allow an appropriate amount of time before assuming that there are no objections to the proposal. This is somewhat dependent upon the circumstances, but it is generally assumed that 72 hours is reasonable. This requirement ensures that everyone is given enough time to read, digest and respond to the proposal. This time period is chosen so as to be as inclusive as possible of all participants, regardless of their location and time commitments. The facilitators of discussion (whether it be the Chair or the Release Managers, where applicable) shall be charged with determining the proper length of time for such consensus to be reached. +怠惰なコンセンサスのために有効であること。 提案に異議はないと仮定する前に適切な時間が必要です これは状況によりますが、一般的には72時間が合理的であると想定されています。 この要件により、誰もが提案を読み、ダイジェスト、および回答するのに十分な時間を与えられることが保証されます。 この期間は、その場所と時間の約束に関係なく、すべての参加者の可能な限り包括的であるように選択されます。 議論のファシリテーター(議長であろうとリリースマネージャーであろうと)。 (該当する場合) このようなコンセンサスに到達するまでの適切な時間の長さを決定することが義務付けられます。 -As discussed above regarding so-called routine decisions, the release managers have the right to make decisions within a shorter period of time. In such cases, lazy consensus shall be implied. +いわゆるルーチン決定に関する上記のように、リリース管理者は短期間で決定を行う権利を有します。 このような場合には、怠惰なコンセンサスが暗示されなければならない。 -### Request for Comment (RFC) +### コメントのリクエスト (RFC) -The Steering Council shall be in charge of overseeing the RFC process. It shall be a process that remains open to debate to all members of the community, and shall allow for ample time to consider a proposal and for members to respond and engage in meaningful discussion. +運営評議会は、RFC プロセスの監督を担当します。 それはコミュニティのすべてのメンバーに議論を開いているプロセスである。 提案を検討し、メンバーが有意義な議論を行うための十分な時間を確保しなければならない。 -The final decision is vested with the Steering Council. However, it is strongly discouraged that the Steering Council adopt a decision that is contrary to any consensus that may exist in the community. From time to time this may happen if there is a conflict between consensus and the overall project and community goals. +最終的な決定は、ステアリング評議会によって与えられます。 しかし、運営審議会が、コミュニティ内に存在する可能性のあるコンセンサスに反する決定を採用することは強く落胆しています。 時折、コンセンサスとプロジェクト全体とコミュニティの目標の間に矛盾がある場合、これは起こるかもしれません。 -An RFC shall be initiated by submission to the Steering Council in the public manner as set forth by the Steering Council. Debate shall continue and be facilitated by the Steering Council in general, and the Chair specifically. +RFC は、運営評議会によって規定されているような公的な方法で運営評議会への提出によって開始されるものとします。 議論は、継続し、一般的に運営委員会によって促進されるものとします, そして、具体的に議長. -In circumstances that the Steering Council feels it is appropriate, the RFC process may be waived in favor of lazy consensus. +運営評議会が適切だと感じる場合には、RFC プロセスは怠惰な合意に賛成して放棄される可能性があります。 From e4e852750b6e4a397d92d45d766eb151f6415d82 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:43 +0200 Subject: [PATCH 390/698] New translations scope.md (Chinese Simplified) --- guide/content/zh/organization/scope.md | 278 ++++++++++++------------- 1 file changed, 139 insertions(+), 139 deletions(-) diff --git a/guide/content/zh/organization/scope.md b/guide/content/zh/organization/scope.md index 47a1c4f085..680c5c7a40 100644 --- a/guide/content/zh/organization/scope.md +++ b/guide/content/zh/organization/scope.md @@ -1,257 +1,257 @@ -# Sanic Community Organization Policy E-manual (SCOPE) +# 社区组织政策电子手册 .. attrs:: :class: is-size-7 ``` -_December 2019, version 1_ +_2019年12月，版本 1_ ``` -## Goals +## 目标 -To create a sustainable, community-driven organization around the Sanic projects that promote: (1) stability and predictability, (2) quick iteration and enhancement cycles, (3) engagement from outside contributors, (4) overall reliable software, and (5) a safe, rewarding environment for the community members. +围绕萨尼语项目建立一个可持续的、由社区推动的组织，促进：(1) 稳定和可预测性，(2) 快速迭代和增强周期， (3) 外部贡献者的参与，(4) 通盘可靠的软件，和(5) 社区成员的安全有益环境。 -## Overview +## 概览 -This Policy is the governance model for the Sanic Community Organization (“SCO”). The SCO is a meritocratic, consensus-based community organization responsible for all projects adopted by it. Anyone with an interest in one of the projects can join the community, contribute to the community or projects, and participate in the decision making process. This document describes how that participation takes place and how to set about earning merit within the project community. +这项政策是萨尼语社区组织的管理模式。 上海合作组织是一个优秀的社区组织，负责该组织通过的所有项目。 任何对其中一个项目感兴趣的人都可以加入社区。 为社区或项目作出贡献，并参与决策进程。 本文件介绍了如何进行这种参与以及如何在项目界内确定赚取收入的长处。 -## Structure +## 结构 -The SCO has multiple **projects**. Each project is represented by a single GitHub repository under the Sanic community umbrella. These projects are used by **users**, developed by **contributors**, governed by **core developers**, released by **release managers**, and ultimately overseen by a **steering council**. If this sounds similar to the Python project and PEP 8016 that is because it is intentionally designed that way. +上海合作组织有多个**项目**。 每个项目都有一个单一的GitHub 仓库，位于Sanic社区保护伞下。 这些项目由 **users**、由 **contributors**开发，由 **core 开发者**、由**发行经理**发布，最终由**指导理事会**监督。 如果这听起来类似于Python项目和 PEP 8016 ，因为它是故意设计的。 -## Roles and responsibilities +## 作用和责任 -### Users +### 用户 -Users are community members who have a need for the projects. They are the developers and personnel that download and install the packages. Users are the **most important** members of the community and without them the projects would have no purpose. Anyone can be a user and the licenses adopted by the projects shall be appropriate open source licenses. +用户是需要项目的社区成员。 他们是下载和安装软件包的开发者和人员。 用户是社区中**最重要的**成员\*\*，没有他们，项目就毫无用处。 任何人都可以是用户，项目通过的许可证应该是适当的开源许可证。 -_The SCO asks its users to participate in the project and community as much as possible._ +_上海合作组织请其用户尽可能多地参与该项目和社区。 -User contributions enable the project team to ensure that they are satisfying the needs of those users. Common user contributions include (but are not limited to): +用户贡献使项目小组能够确保满足这些用户的需要。 共同用户贡献包括(但不限于)： -- evangelizing about the project (e.g. a link on a website and word-of-mouth awareness raising) -- informing developers of strengths and weaknesses from a new user perspective -- providing moral support (a ‘thank you’ goes a long way) -- providing financial support (the software is open source, but its developers need to eat) +- 宣传项目(如网站上的链接和提高对口文字的认识) +- 从新用户角度向开发者通报优点和弱点。 +- 提供道德支持 (“谢谢”很长时间) +- 提供财政支持 (软件是开放源码，但其开发者需要吃) -Users who continue to engage with the SCO, its projects, and its community will often become more and more involved. Such users may find themselves becoming contributors, as described in the next section. +继续与上海合作组织、其项目和社区接触的用户往往越来越多地参与进来。 如下一节所述，这些用户可能会成为贡献者。 -### Contributors +### 贡献者 -Contributors are community members who contribute in concrete ways to one or more of the projects. Anyone can become a contributor and contributions can take many forms. Contributions and requirements are governed by each project separately by a contribution policy. +捐助方是社区成员，他们以具体方式为一个或多个项目作出贡献。 任何人都可以成为捐助者，捐助可以采取多种形式。 捐款和需求由每个项目根据捐款政策分别管理。 -There is **no expectation** of commitment to the project, **no specific skill requirements** and **no selection process**. +**没有对项目的承诺**，**没有具体的技能要求**，**没有选择过程**。 -In addition to their actions as users, contributors may also find themselves doing one or more of the following: +除了作为用户采取的行动外，捐款者还可能会发现自己做以下一项或多项工作： -- supporting new users (existing users are often the best people to support new users) -- reporting bugs -- identifying requirements -- providing graphics and web design -- Programming -- example use cases -- assisting with project infrastructure -- writing documentation -- fixing bugs -- adding features -- providing constructive opinions and engaging in community discourse +- 支持新用户(现有用户往往是支持新用户的最佳用户) +- 报告错误 +- 鉴别要求 +- 提供图形和网页设计 +- 编程中 +- 示例使用 +- 协助项目基础设施 +- 撰写文档 +- 修复错误 +- 添加功能 +- 提供建设性意见和参与社区对话 -Contributors engage with the projects through GitHub and the Community Forums. They submit changes to the projects itself via pull requests, which will be considered for inclusion in the project by the community at large. The Community Forums are the most appropriate place to ask for help when making that first contribution. +参与者通过GitHub 和社区论坛参与这些项目。 他们通过拉动请求提交对项目本身的更改，一般社区将考虑将其纳入项目。 社区论坛是在作出首次贡献时寻求帮助的最适当场所。 -Indeed one of the most important roles of a contributor may be to **simply engage in the community conversation**. Most decisions about the direction of a project are made by consensus. This is discussed in more detail below. In general, however, it is helpful for the health and direction of the projects for the contributors to **speak freely** (within the confines of the code of conduct) and **express their opinions and experiences** to help drive the consensus building. +的确，贡献者最重要的作用之一可能是**只是参与社区对话**。 关于项目方向的大多数决定都是以协商一致方式作出的。 下文将更详细地讨论这一问题。 然而，一般而言，这种情况都是如此。 这有助于项目的健康和方向，使参与者能够（在行为守则范围内）**自由地说** 和**表达他们的意见和经验** 以帮助推动建立共识。 -As contributors gain experience and familiarity with a project, their profile within, and commitment to, the community will increase. At some stage, they may find themselves being nominated for a core developer team. +随着捐助方获得经验和熟悉一个项目，他们在社区内的形象和对社区的承诺将增加。 在某个阶段，他们可能会被提名为核心开发者团队。 -### Core Developer +### 核心开发者 -Each project under the SCO umbrella has its own team of core developers. They are the people in charge of that project. +上海合作组织下属的每个项目都有自己的核心开发人员。 他们是该项目的负责人。 -_What is a core developer?_ +_什么是核心开发者？_ -Core developers are community members who have shown that they are committed to the continued development of the project through ongoing engagement with the community. Being a core developer allows contributors to more easily carry on with their project related activities by giving them direct access to the project’s resources. They can make changes directly to the project repository without having to submit changes via pull requests from a fork. +核心开发者是社区成员，他们已经表明，他们致力于通过与社区的持续接触继续发展项目。 作为一个核心开发者，捐助方能够更容易地开展与项目有关的活动，让他们直接获得项目的资源。 他们可以直接对项目仓库进行更改，而不必通过分叉的合并请求提交更改。 -This does not mean that a core developer is free to do what they want. In fact, core developers have no more direct authority over the final release of a package than do contributors. While this honor does indicate a valued member of the community who has demonstrated a healthy respect for the project’s aims and objectives, their work continues to be reviewed by the community before acceptance in an official release. +这并不意味着核心开发者可以自由地做他们想要做的事情。 事实上，核心开发者对最终发布一揽子计划没有比贡献者更直接的权力。 虽然这一荣誉确实表明社区中表现出对项目宗旨和目标的健康尊重的有价值的成员。 她们的工作继续由社区审查，然后才被正式释放。 -_What can a core developer do on a project?_ +_核心开发者在项目上可以做什么？_ -Each project might define this role slightly differently. However, the general usage of this designation is that an individual has risen to a level of trust within the community such that they now are given some control. This comes in the form of push rights to non-protected branches, and the ability to have a voice in the approval of pull requests. +每个项目对这一角色的定义可能略有不同。 然而，仍然存在着这种情况。 这种指定的一般用法是，个人在社区内已经发展到一定程度的信任程度，从而使他们现在能够得到某种程度的控制。 其形式是向无保护的分支推送权利以及在批准拉取请求时有发言权的能力。 -The projects employ various communication mechanisms to ensure that all contributions are reviewed by the community as a whole. This includes tools provided by GitHub, as well as the Community Forums. By the time a contributor is invited to become a core developer, they should be familiar with the various tools and workflows as a user and then as a contributor. +这些项目采用各种交流机制，以确保所有捐款都得到整个社区的审查。 这包括GitHub 以及社区论坛提供的工具。 当邀请贡献者成为核心开发者时。 他们应该熟悉各种工具和工作流程，作为用户，然后作为贡献者。 -_How to become a core developer?_ +_如何成为核心开发者？_ -Anyone can become a core developer; there are no special requirements, other than to have shown a willingness and ability to positively participate in the project as a team player. +任何人都可以成为核心开发者； 除了表现出作为团队成员积极参加项目的意愿和能力之外，没有其他特殊要求。 -Typically, a potential core developer will need to show that they have an understanding of the project, its objectives and its strategy. They will also have provided valuable contributions to the project over a period of time. However, there is **no technical or other skill** requirement for eligibility. +通常，潜在的核心开发商需要表明他们了解项目、其目标和战略。 他们还将在一段时间内为该项目作出宝贵贡献。 然而，在资格方面没有**技术或其他技能**要求。 -New core developers can be **nominated by any existing core developer** at any time. At least twice a year (April and October) there will be a ballot process run by the Steering Council. Voting should be done by secret ballot. Each existing core developer for that project receives a number of votes equivalent to the number of nominees on the ballot. For example, if there are four nominees, then each existing core developer has four votes. The core developer may cast those votes however they choose, but may not vote for a single nominee more than once. A nominee must receive two-thirds approval from the number of cast ballots (not the number of eligible ballots). Once accepted by the core developers, it is the responsibility of the Steering Council to approve and finalize the nomination. The Steering Council does not have the right to determine whether a nominee is meritorious enough to receive the core developer title. However, they do retain the right to override a vote in cases where the health of the community would so require. +新的核心开发者可以在任何时候被任何现有的核心开发者\*\*提名。 指导委员会将每年至少举行两次投票（4月和10月）。 投票应以无记名投票方式进行。 该项目的每个现有核心开发者获得的票数相当于选票上被提名者的人数。 例如，如果有四个被提名者，那么现有的每个核心开发者都有四票。 核心开发者可以按自己选择的方式投票，但不能投票一次以上的被提名者。 被提名人必须得到选票数（而不是合格选票数）三分之二的批准。 一旦得到核心开发者的接受，指导委员会就有责任批准和最后确定提名。 指导委员会无权确定被提名人是否有足够的价值来获得核心开发者头衔。 但是，如果社区的健康有此需要，他们确实保留否决投票的权利。 -Once the vote has been held, the aggregated voting results are published on the Community Forums. The nominee is entitled to request an explanation of any override against them. A nominee that fails to be admitted as a core developer may be nominated again in the future. +一旦进行了投票，将在社区论坛上公布汇总投票结果。 被提名人有权要求对反对他们的任何否决作出解释。 不被接纳为核心开发者的被提名人将来可能再次被提名。 -It is important to recognize that being a core developer is a privilege, not a right. That privilege must be earned and once earned it can be removed by the Steering Council (see next section) in extreme circumstances. However, under normal circumstances the core developer title exists for as long as the individual wishes to continue engaging with the project and community. +必须认识到，作为核心开发者是一种特权，而不是一种权利。 必须获得这项特权，一旦获得这项特权，指导委员会就可以在极端情况下取消（见下一节）。 然而，在正常情况下，只要个人愿意继续与项目和社区接触，核心开发商的所有权就存在。 -A committer who shows an above-average level of contribution to the project, particularly with respect to its strategic direction and long-term health, may be nominated to become a member of the Steering Council, or a Release Manager. This role is described below. +项目委员会的成员显示对项目的贡献超过平均水平，特别是在其战略方向和长期健康方面， 可被提名为指导委员会成员或发布管理员。 下文介绍了这一作用。 -_What are the rights and responsibilities of core developers?_ +_核心开发者的权利和责任是什么？ _ -As discussed, the majority of decisions to be made are by consensus building. In certain circumstances where an issue has become more contentious, or a major decision needs to be made, the Release Manager or Steering Council may decide (or be required) to implement the RFC process, which is outlined in more detail below. +正如所讨论的那样，将要作出的大多数决定都是通过建立共识作出的。 在某些情况下，某一问题变得更具争议性或需要作出重大决定。 发布主管或指导委员会可决定（或需要）实施成果文件进程，下文将更详细地概述。 -It is also incumbent upon core developers to have a voice in the governance of the community. All core developers for all of the projects have the ability to be nominated to be on the Steering Council and vote in their elections. +核心开发者也有责任在社区治理中发表意见。 所有项目的所有核心开发者都有能力被提名参加指导委员会并在其选举中投票。 -This Policy (the “SCOPE”) may only be changed under the authority of two-thirds of active core developers, except that in the first six (6) months after adoption, the core developers reserve the right to make changes under the authority of a simple majority of active core developers. +本政策(“SCOPE”)只能在三分之二活跃核心开发商的授权下修改。 但在收养后的头六(6)个月内， 核心开发者保留在简单多数活跃的核心开发者授权下进行更改的权利。 -_What if a core developer becomes inactive?_ +_核心开发者不活跃时怎么办？_ -It is hoped that all core developers participate and remain active on a regular basis in their projects. However, it is also understood that such commitments may not be realistic or possible from time to time. +希望所有核心开发商都能定期参与并继续积极参加其项目。 然而，人们也认识到，这种承诺可能不现实或不时不可能。 -Therefore, the Steering Council has the duty to encourage participation and the responsibility to place core developers into an inactive status if they are no longer willing or capable to participate. The main purpose of this is **not to punish** a person for behavior, but to help the development process to continue for those that do remain active. +因此， 指导委员会有责任鼓励参与，如果核心开发者不再愿意或不再有能力参与，则有责任使他们处于不活跃状态。 其主要目的是\*\*不是为了惩罚一个人的行为， 但有助于发展进程继续为那些仍然活跃的国家服务。 -To this end, a core developer that becomes “inactive” shall not have commit rights to a repository, and shall not participate in any votes. To be eligible to vote in an election, a core developer **must have been active** at the time of the previous scheduled project release. +为此目的，“不活跃”的核心开发者不应拥有对储存库的权利，也不应参与任何投票。 要有资格在选举中投票，核心开发人员在上次计划的项目发布时必须已经活跃\*\*。 -Inactive members may ask the Steering Council to reinstate their status at any time, and upon such request the Steering Council shall make the core developer active again. +不活跃的成员可随时要求指导委员会恢复其地位。 在提出这种要求后，指导委员会应使核心开发商再次活跃。 -Individuals that know they will be unable to maintain their active status for a period are asked to be in communication with the Steering Council and declare themselves inactive if necessary. +如果个人知道他们在一段时间内无法维持其现役地位，则请他们与指导委员会联系，并在必要时宣布不再活动。 -An “active” core developer is an individual that has participated in a meaningful way during the previous six months. Any further definition is within the discretion of the Steering Council. +“积极的”核心开发者是在过去六个月中以有意义的方式参与的个人。 任何进一步的定义都属于指导委员会的酌处权。 -### Release Manager +### 发布管理器 -Core developers shall have access only to make commits and merges on non-protected branches. The “master” branch and other protected branches are controlled by the release management team for that project. Release managers shall be elected from the core development team by the core development team, and shall serve for a full release cycle. +核心开发者只能在无保护的分支上做出承诺和合并。 “主人”分支和其他受保护分支由该项目的释放管理小组控制。 单元管理人员应由核心开发小组从核心开发小组中选出，并应有一个完整的发放周期。 -Each core developer team may decide how many release managers to have for each release cycle. It is highly encouraged that there be at least two release managers for a release cycle to help divide the responsibilities and not force too much effort upon a single person. However, there also should not be so many managers that their efforts are impeded. +每个核心开发者团队可以决定每个发行周期有多少发行管理员。 人们深受鼓舞的是，至少有两名释放管理人员负责一个释放周期，以帮助分清责任，而不要把太多的精力强加给一个人。 然而，也不应有太多的管理人员，以至于他们的努力受到阻碍。 -The main responsibilities of the release management team include: +发布管理小组的主要职责包括： -- push the development cycle forward by monitoring and facilitating technical discussions -- establish a release calendar and perform actions required to release packages -- approve pull requests to the master branch and other protected branches -- merge pull requests to the master branch and other protected branches +- 通过监测和促进技术讨论推进发展周期 +- 建立发布日历并执行发布包所需的操作 +- 批准对主分支和其他受保护分支的合并请求 +- 合并合并请求到主分支和其他受保护分支 -The release managers **do not have the authority to veto or withhold a merge** of a pull request that otherwise meets contribution criteria and has been accepted by the community. It is not their responsibility to decide what should be developed, but rather that the decisions of the community are carried out and that the project is being moved forward. +释放管理员**无权否决或拒绝合并**在其他情况下符合贡献标准且已被社区接受的合并请求。 他们没有责任决定应该制定什么措施。 而是社区的决定正在执行，项目正在向前推进。 -From time to time, a decision may need to be made that cannot be achieved through consensus. In that case, the release managers have the authority to call upon the removal of the decision to the RFC process. This should not occur regularly (unless required as discussed below), and its use should be discouraged in favor of the more communal consensus building strategy. +可能需要时常作出无法通过协商一致做出的决定。 在这种情况下，释放管理人员有权要求将决定移送《索取资料书》进程。 这种做法不应定期发生（除非如下文所述的要求），应鼓励使用这种做法，以利于采取更多的社区建立共识战略。 -Since not all projects have the same requirements, the specifics governing release managers on a project shall be set forth in an Appendix to this Policy, or in the project’s contribution guidelines. +因为并非所有项目都有相同的要求， 关于某一项目的排放管理人员的具体规定应在本政策的附录或项目的贡献准则中加以规定。 -If necessary, the Steering Council has the right to remove a release manager that is derelict in their duties, or for other good cause. +如有必要，指导委员会有权撤换一名因其职责或其他正当理由而失职的释放管理员。 -### Steering Council +### 指导理事会 -The Steering Council is the governing body consisting of those individuals identified as the “project owner” and having control of the resources and assets of the SCO. Their ultimate goal is to ensure the smooth operation of the projects by removing impediments, and assisting the members as needed. It is expected that they will be regular voices in the community. +指导委员会是由那些被确定为“项目所有人”并控制上海合作组织资源和资产的个人组成的管理机构。 其最终目标是通过消除障碍和在需要时协助成员确保项目的顺利运作。 预计他们将在社区中经常发出声音。 -_What can the Steering Council do?_ +_指导委员会能做些什么？_ -The members of the Steering Council **do not individually have any more authority than any other core developer**, and shall not have any additional rights to make decisions, commits, merges, or the like on a project. +指导委员会成员**个别拥有比任何其他核心开发者更多的权限**， 而且对某一项目无任何额外的决定、承诺、合并或类似权利。 -However, as a body, the Steering Council has the following capacity: +然而，作为一个机构，指导委员会具有以下能力： -- accept, remand, and reject all RFCs -- enforce the community code of conduct -- administer community assets such as repositories, servers, forums, integration services, and the like (or, to delegate such authority to someone else) -- place core developers into inactive status where appropriate take any other enforcement measures afforded to it in this Policy, including, in extreme cases, removing core developers -- adopt or remove projects from the community umbrella +- 接受、汇款和拒绝所有RFCs +- 强制执行社区行为守则 +- 管理社区资产，如仓库、服务器、论坛、集成服务等等(或将这种权力授予其他人) +- 酌情采取本政策给予核心开发商的任何其他强制执行措施，使核心开发商处于非活动状态， 包括在极端情况下移除核心开发者 +- 通过或从社区伞式组织中删除项目 -It is highly encouraged that the Steering Council delegate its authority as much as possible, and where appropriate, to other willing community members. +人们高度鼓励指导委员会尽可能并酌情将其权力下放给其他愿意的社区成员。 -The Steering Council **does not have the authority** to change this Policy. +指导委员会**没有权力**改变这项政策。 -_How many members are on the Steering Council?_ +_有多少成员在指导委员会？ -Four. +四、结论和建议 -While it seems like a committee with four votes may potentially end in a deadlock with no way to break a majority vote, the Steering Council is discouraged from voting as much as possible. Instead, it should try to work by consensus, and requires three consenting votes when it is necessary to vote on a matter. +虽然它似乎像一个四票的委员会，但有可能陷入僵局，无法打破多数票。 指导委员会不鼓励尽可能多地进行表决。 相反，它应该努力以协商一致方式开展工作，并在需要就某一事项进行表决时需要三次同意的表决。 -_How long do members serve on the Steering Council?_ +_成员在指导委员会任职多长时间?_ -A single term shall be for two calendar years starting in January. Terms shall be staggered so that each year there are two members continuing from the previous year’s council. +从1月开始，任期为两个历年。 任期将错开，以便每年有两名成员从前一年的理事会继续任职。 -Therefore, the inaugural vote shall have two positions available for a two year term, and two positions available for a one year term. +因此，就职投票应有两个任期两年的职位和两个任期一年的职位。 -There are no limits to the number of terms that can be served, and it is possible for an individual to serve consecutive terms. +可以使用的任期不受限制，个人可以连续任职。 -_Who runs the Steering Council?_ +_谁来管理指导理事会？_ -After the Steering Council is elected, the group shall collectively decide upon one person to act as the Chair. The Chair does not have any additional rights or authority over any other member of the Steering Council. +指导委员会选出后，该小组应集体决定由一人担任主席。 主席对指导委员会的任何其他成员没有任何其他权利或权力。 -The role of the Chair is merely as a coordinator and facilitator. The Chair is expected to ensure that all governance processes are adhered to. The position is more administrative and clerical, and is expected that the Chair sets agendas and coordinates discussion of the group. +主席的作用仅仅是协调人和调解人。 预期主席将确保所有治理进程都得到遵守。 这一职位更具行政性和文秘性，预计主席将制定小组的议程并协调小组的讨论。 -_How are council members elected?_ +_理事会成员是如何选举的？_ -Once a year, **all eligible core developers** for each of the projects shall have the right to elect members to the Steering Council. +每个项目每年一次，**所有合格的核心开发者** 应有权选举指导委员会成员。 -Nominations shall be open from September 1 and shall close on September 30. After that, voting shall begin on October 1 and shall close on October 31. Every core developer active on the date of the June release of the Sanic Framework for that year shall be eligible to receive one vote per vacant seat on the Steering Council. For the sake of clarity, to be eligible to vote, a core developer **does not** need to be a core developer on Sanic Framework, but rather just have been active within their respective project on that date. +提名应从9月1日起开放，并于9月30日结束。 此后，表决应于10月1日开始，10月31日结束。 在该年度6月份发布《Sanic框架》之日活跃的每个核心开发商都有资格获得指导委员会每个空缺席位的一票。 为了明确起见，要有投票资格，核心开发者**不需要**就必须是Sanic Framework的核心开发者。 但实际上当时只是在其各自的项目范围内积极开展工作。 -The top recipients of votes shall be declared the winners. If there is any tie, it is highly encouraged that the tied nominees themselves resolve the dispute before a decision is made at random. +最高得票者将被宣布为获胜者。 如果有任何矛盾之处，受牵连的被提名人自己在随意作出决定之前解决争端，就会受到极大鼓舞。 -In regards to the inaugural vote of the Steering Council, the top two vote-recipients shall serve for two years, and the next two vote-recipients shall assume the one-year seats. +关于指导委员会的首次投票，两名选票最多者任期两年。 接下来的两个选票接受国应占一年的席位。 -To be an eligible candidate for the Steering Council, the individual must have been a core developer in active status on at least one project for the previous twelve months. +成为指导委员会的合格候选人； 该个人必须是在过去12个月中至少一个项目上处于活跃状态的核心开发者。 -_What if there is a vacancy?_ +_如果有空缺怎么办？_ -If a vacancy on the Steering Council exists during a term, then the next highest vote-recipient in the previous election shall be offered to complete the remainder of the term. If one cannot be found this way, the Steering Council may decide the most appropriate course of action to fill the seat (whether by appointment, vote, or other means). +如果指导委员会在任期内存在空缺， 然后应向上次选举中获得最高票数的人提供完成剩余任期的机会。 如果找不到这种方法， 指导委员会可决定填补该席位的最适当行动方针（通过任命、表决或其他方式）。 -If a member of the Steering Council becomes inactive, then that individual shall be removed from the Steering Council immediately and the seat shall become vacant. +如果指导委员会的一名成员不活跃， 然后应立即将此人从指导委员会除名，该职位应出缺。 -In extreme cases, the body of all core developers has the right to bring a vote to remove a member of the Steering Council for cause by a two-thirds majority of all eligible voting core developers. +在极端情况下， 所有核心开发者的机构都有权以所有有资格投票的核心开发者的三分之二多数表决取消指导委员会的一名成员。 -_How shall the Steering Council conduct its business?_ +_指导委员会应如何开展工作?_ -As much as possible, the Steering Council shall conduct its business and discussions in the open. Any member of the community should be allowed to enter the conversation with them. However, at times it may be necessary or appropriate for discussions to be held privately. Selecting the proper venue for conversations is part of the administrative duties of the Chair. +指导委员会应尽可能公开开展工作和讨论。 应允许社区的任何成员参加与他们的对话。 然而，有时可能有必要或适合私下进行讨论。 选择适当的会话地点是主席行政职责的一部分。 -While the specifics of how to operate are beyond the scope of the Policy, it is encouraged that the Steering Council attempt to meet at least one time per quarter in a “real-time” discussion. This could be achieved via video conferencing, live chatting, or other appropriate means. +虽然如何运作的具体规定不属于该政策的范围， 令人感到鼓舞的是，指导委员会试图每季度至少举行一次“实时”讨论。 这可以通过电视会议、实况聊天或其他适当手段来实现。 -## Support +## 支持 -All participants in the community are encouraged to provide support for users within the project management infrastructure. This support is provided as a way of growing the community. Those seeking support should recognize that all support activity within the project is voluntary and is therefore provided as and when time allows. A user requiring guaranteed response times or results should therefore seek to purchase a support contract from a community member. However, for those willing to engage with the project on its own terms, and willing to help support other users, the community support channels are ideal. +鼓励社区所有参与者在项目管理基础设施内向用户提供支助。 提供这种支助是促进社区发展的一种方式。 寻求支助者应认识到，项目内的所有支助活动都是自愿性的，因此在时间允许的情况下提供。 因此，要求有保证的反应时间或结果的用户应设法从社区成员那里购买支持合同。 然而，对于那些愿意按照自己的条件参与项目的人来说，则是如此。 社区支助渠道是最理想的，愿意帮助其他用户。 -## Decision making process +## 决策过程 -Decisions about the future of the projects are made through discussion with all members of the community, from the newest user to the most experienced member. Everyone has a voice. +有关项目未来的决定是通过与社区所有成员讨论作出的。 从最新用户到经验最丰富的会员。 每个人都有发言权。 -All non-sensitive project management discussion takes place on the community forums, or other designated channels. Occasionally, sensitive discussions may occur in private. +所有非敏感项目管理讨论都在社区论坛或其他指定渠道进行。 偶尔还会私下进行敏感的讨论。 -In order to ensure that the project is not bogged down by endless discussion and continual voting, the project operates a policy of **lazy consensus**. This allows the majority of decisions to be made without resorting to a formal vote. For any **major decision** (as defined below), there is a separate Request for Comment (RFC) process. +为了确保该项目不会因无休止的讨论和持续表决而陷入僵局，该项目实行了**迟迟不能达成共识**的政策。 这使得大多数决定不必经过正式表决就能作出。 对于任何**重大决定** (下面界定)，都有一个单独的征求意见程序。 -### Technical decisions +### 技术决定 -Pull requests and technical decisions should generally fall into the following categories. +合并请求和技术决定一般应分为以下几类。 -- **Routine**: Documentation fixes, code changes that are for cleanup or additional testing. No functionality changes. -- **Minor**: Changes to the code base that either fix a bug, or introduce a trivial feature. No breaking changes. -- **Major**: Any change to the code base that breaks or deprecates existing API, alters operation in a non-trivial manner, or adds a significant feature. +- **Routine**: 文档修复，用于清理或额外测试的代码更改。 功能没有变化。 +- **Minor**: 更改代码基础以修复一个bug或引入一个微不足道的功能。 没有中断的更改。 +- **Major**: 对代码基础的任何更改都会破坏或废弃现有的API, 以非微不足道的方式更改操作, 或添加一个重要的功能。 -It is generally the responsibility of the release managers to make sure that changes to the repositories receive the proper authorization before merge. +通常，发布管理员有责任确保在合并之前对储存库的更改得到适当的授权。 -The release managers retain the authority to individually review and accept routine decisions that meet standards for code quality without additional input. +释放管理人员保留个别审查和接受符合编码质量标准的例行决定的权力，而无需额外投入。 -### Lazy consensus +### 延迟的协议 -Decision making (whether by the community or Steering Council) typically involves the following steps: +决策（无论是由社区还是指导委员会）通常涉及下列步骤： -- proposal -- discussion -- vote (if consensus is not reached through discussion) -- decision +- 建 议 +- 讨论情况 +- 投票(如果不能通过讨论达成协商一致意见) +- 决 定 -Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should post a message on the appropriate channel on the Community forums, or submit a pull request implementing the idea on GitHub. This will prompt a review and, if necessary, a discussion of the idea. +任何社区成员都可以提出建议，供社区考虑。 为了发起关于新想法的讨论，他们应在共同体论坛的适当渠道上发表信息， 或者在GitHub上提交一个实现想法的拉取请求。 这将促使人们进行审查，并在必要时讨论这一想法。 -The goal of this review and discussion is to gain approval for the contribution. Since most people in the project community have a shared vision, there is often little need for discussion in order to reach consensus. +这次审查和讨论的目的是获得对捐款的批准。 由于项目界的大多数人都有共同的愿景，达成共识往往没有必要进行讨论。 -In general, as long as nobody explicitly opposes a proposal or patch, it is recognized as having the support of the community. This is called lazy consensus; that is, those who have not stated their opinion explicitly have implicitly agreed to the implementation of the proposal. +一般来说，只要无人明确反对某项建议或修补，就会被认为得到了社区的支持。 这就是说，那些没有明确表示其意见的人默示同意执行该建议。 -Lazy consensus is a very important concept within the SCO. It is this process that allows a large group of people to efficiently reach consensus, as someone with no objections to a proposal need not spend time stating their position, and others need not spend time reading such messages. +迟迟不达成共识是上海合作组织内一个非常重要的概念。 正是这一进程使大批人能够有效地达成共识。 因为对某项建议没有异议的人不需要花时间说明其立场，其他人不需要花时间阅读这些信息。 -For lazy consensus to be effective, it is necessary to allow an appropriate amount of time before assuming that there are no objections to the proposal. This is somewhat dependent upon the circumstances, but it is generally assumed that 72 hours is reasonable. This requirement ensures that everyone is given enough time to read, digest and respond to the proposal. This time period is chosen so as to be as inclusive as possible of all participants, regardless of their location and time commitments. The facilitators of discussion (whether it be the Chair or the Release Managers, where applicable) shall be charged with determining the proper length of time for such consensus to be reached. +为了使迟迟不达成的协商一致意见行之有效， 有必要在假定对该提案没有异议之前留出适当的时间。 这在某种程度上取决于情况，但一般认为72小时是合理的。 这项要求确保每个人都有足够的时间阅读、消化和回应这项建议。 选择这一时限是为了尽可能包容所有参与者，无论其地点和时间如何。 讨论主持人(不论是主席还是发布经理) 应负责确定达成这种协商一致意见的适当时间。 -As discussed above regarding so-called routine decisions, the release managers have the right to make decisions within a shorter period of time. In such cases, lazy consensus shall be implied. +如上所述，关于所谓的例行决定，释放管理人员有权在较短的时间内作出决定。 在这种情况下，将会暗示迟迟不能达成共识。 -### Request for Comment (RFC) +### 请求评论 (RFC) -The Steering Council shall be in charge of overseeing the RFC process. It shall be a process that remains open to debate to all members of the community, and shall allow for ample time to consider a proposal and for members to respond and engage in meaningful discussion. +指导委员会负责监督改革成果框架进程。 这一进程仍然可以向社区所有成员进行辩论。 并应留出充分时间审议某项提案，并使成员能够答复和进行有意义的讨论。 -The final decision is vested with the Steering Council. However, it is strongly discouraged that the Steering Council adopt a decision that is contrary to any consensus that may exist in the community. From time to time this may happen if there is a conflict between consensus and the overall project and community goals. +最后决定由指导委员会作出。 然而，指导委员会通过的决定与社区可能存在的任何共识背道而驰，令人强烈沮丧。 如果共识与总体项目和社区目标之间不时发生冲突，就可能发生这种情况。 -An RFC shall be initiated by submission to the Steering Council in the public manner as set forth by the Steering Council. Debate shall continue and be facilitated by the Steering Council in general, and the Chair specifically. +将按照指导委员会的规定，以公开方式向指导委员会提交一份征求意见。 辩论应继续进行，并由指导委员会和具体由主席主持。 -In circumstances that the Steering Council feels it is appropriate, the RFC process may be waived in favor of lazy consensus. +在指导委员会认为适当的情况下，区域渔业委员会的程序可能被放弃，转而赞成迟迟不达成共识。 From 80962d211aa664a30a7f10f4fa2f8635290c94cb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:45 +0200 Subject: [PATCH 391/698] New translations configuration.md (Japanese) --- .../ja/plugins/sanic-ext/configuration.md | 234 +++++++++--------- 1 file changed, 117 insertions(+), 117 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/configuration.md b/guide/content/ja/plugins/sanic-ext/configuration.md index 1443cfc6e9..41891c6bc8 100644 --- a/guide/content/ja/plugins/sanic-ext/configuration.md +++ b/guide/content/ja/plugins/sanic-ext/configuration.md @@ -1,27 +1,27 @@ --- -title: Sanic Extensions - Configuration +title: Sanic Extensions - 設定 --- -# Configuration +# 設定 -Sanic Extensions can be configured in all of the same ways that [you can configure Sanic](../../guide/deployment/configuration.md). That makes configuring Sanic Extensions very easy. +Sanic Extensionsは、format@@0(../../guide/deployment/configuration.md)と同じ方法で設定できます。 これにより、Sanic Extensionsを非常に簡単に構成できます。 ```python app = Sanic("MyApp") app.config.OAS_URL_PREFIX = "/apidocs" ``` -However, there are a few more configuration options that should be considered. +しかし、検討すべき設定オプションはいくつかあります。 -## Manual `extend` +## 手動の`extend` -.. column:: +.. 列:: ``` -Even though Sanic Extensions will automatically attach to your application, you can manually choose `extend`. When you do that, you can pass all of the configuration values as a keyword arguments (lowercase). +Sanic Extensionsはアプリケーションに自動的にアタッチされますが、手動で`extend`を選択することができます。 これを行うと、すべての設定値をキーワード引数(小文字)として渡すことができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -30,13 +30,13 @@ app.extend(oas_url_prefix="/apidocs") ``` ```` -.. column:: +.. 列:: ``` -Or, alternatively they could be passed all at once as a single `dict`. +あるいは、一度に 1 つの `dict` として渡すこともできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -45,13 +45,13 @@ app.extend(config={"oas_url_prefix": "/apidocs"}) ``` ```` -.. column:: +.. 列:: ``` -Both of these solutions suffers from the fact that the names of the configuration settings are not discoverable by an IDE. Therefore, there is also a type annotated object that you can use. This should help the development experience. +これらのソリューションはどちらも、IDEによって構成設定の名前が検出できないという事実に苦しんでいます。 したがって、使用できる型注釈付きオブジェクトもあります。これは開発に役立つはずです。 ``` -.. column:: +.. 列:: ```` ```python @@ -62,14 +62,14 @@ app.extend(config=Config(oas_url_prefix="/apidocs")) ``` ```` -## Settings +## 設定 .. note:: ```` -Often, the easiest way to change these for an application (since they likely are not going to change dependent upon an environment), is to set them directly on the `app.config` object. +多くの場合、アプリケーションのためにこれらを変更する最も簡単な方法 (環境に依存して変更しない可能性が高いので) `appに直接設定することです。 onfig` オブジェクト -Simply use the capitalized version of the configuration key as shown here: +ここで示すように、設定キーの大文字のバージョンを使用します。 ```python app = Sanic("MyApp") @@ -79,210 +79,210 @@ app.config.OAS_URL_PREFIX = "/apidocs" ### `cors` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable CORS protection +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: CORS 保護を有効にするかどうか ### `cors_allow_headers` -- **Type**: `str` -- **Default**: `"*"` -- **Description**: Value of the header: `access-control-allow-headers` +- **タイプ**: `str` +- **デフォルト**: `"*"` +- **説明**: ヘッダの値: `access-control-allow-headers` ### `cors_always_send` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to always send the header: `access-control-allow-origin` +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: ヘッダを常に送信するかどうか: `access-control-allow-origin` ### `cors_automatic_options` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to automatically generate `OPTIONS` endpoints for routes that do _not_ already have one defined +- **タイプ**: `bool` +- **デフォルト**: `True` +- **Description**: _ない_ルートの「OPTIONS」エンドポイントを自動的に生成するかどうか ### `cors_expose_headers` -- **Type**: `str` -- **Default**: `""` -- **Description**: Value of the header: `access-control-expose-headers` +- **タイプ**: `str` +- **デフォルト**: `""` +- **説明**: ヘッダの値: `access-control-expose-headers` ### `cors_max_age` -- **Type**: `int` -- **Default**: `5` -- **Description**: Value of the header: `access-control-max-age` +- **タイプ**: `int` +- **デフォルト**: `5` +- **説明**: ヘッダの値: `access-control-max-age` ### `cors_methods` -- **Type**: `str` -- **Default**: `""` -- **Description**: Value of the header: `access-control-access-control-allow-methods` +- **タイプ**: `str` +- **デフォルト**: `""` +- **説明**: ヘッダの値: `access-control-access-control-allow-methods` ### `cors_origins` -- **Type**: `str` -- **Default**: `""` -- **Description**: Value of the header: `access-control-allow-origin` +- **タイプ**: `str` +- **デフォルト**: `""` +- **説明**: ヘッダの値: `access-control-allow-origin` -.. warning:: +.. 警告:: ``` -Be very careful if you place `*` here. Do not do this unless you know what you are doing as it can be a security issue. +`*`をここに置くときは注意してください。 セキュリティの問題である可能性があるため、何をしているかを知っていない限り、これをしないでください。 ``` ### `cors_send_wildcard` -- **Type**: `bool` -- **Default**: `False` -- **Description**: Whether to send a wildcard origin instead of the incoming request origin +- **タイプ**: `bool` +- **デフォルト**: `False` +- **Description**: リクエストオリジンの代わりにワイルドカードを送信するかどうか ### `cors_supports_credentials` -- **Type**: `bool` -- **Default**: `False` -- **Description**: Value of the header: `access-control-allow-credentials` +- **タイプ**: `bool` +- **デフォルト**: `False` +- **説明**: ヘッダの値: `access-control-allow-credentials` ### `cors_vary_header` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to add the `vary` header +- **タイプ**: `bool` +- **デフォルト**: `True` +- **Description**: `vary`ヘッダーを追加するかどうか ### `http_all_methods` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Adds the HTTP `CONNECT` and `TRACE` methods as allowable +- **タイプ**: `bool` +- **デフォルト**: `True` +- **Description**: 許可されている HTTP の `CONNECT` と `TRACE` メソッドを追加します ### `http_auto_head` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Automatically adds `HEAD` handlers to any `GET` routes +- **タイプ**: `bool` +- **デフォルト**: `True` +- **Description**: 自動的に `HEAD` ハンドラを `GET` ルートに追加します。 ### `http_auto_options` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Automatically adds `OPTIONS` handlers to any routes without +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: 自動的に `OPTIONS` ハンドラをルートなしで追加します ### `http_auto_trace` -- **Type**: `bool` -- **Default**: `False` -- **Description**: Automatically adds `TRACE` handlers to any routes without +- **タイプ**: `bool` +- **デフォルト**: `False` +- **説明**: 自動的に `TRACE` ハンドラをルートなしで追加します ### `oas` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable OpenAPI specification generation +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: OpenAPI仕様の生成を有効にするかどうか ### `oas_autodoc` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to automatically extract OpenAPI details from the docstring of a route function +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: ルート関数のdocstringからOpenAPIの詳細を自動的に抽出するかどうか ### `oas_ignore_head` -- **Type**: `bool` -- **Default**: `True` -- **Description**: WHen `True`, it will not add `HEAD` endpoints into the OpenAPI specification +- **タイプ**: `bool` +- **デフォルト**: `True` +- **Description**: When `True`, `HEAD`エンドポイントをOpenAPI仕様に追加しません ### `oas_ignore_options` -- **Type**: `bool` -- **Default**: `True` -- **Description**: WHen `True`, it will not add `OPTIONS` endpoints into the OpenAPI specification +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: When `True` はOpenAPI仕様に`OPTIONS`エンドポイントを追加しません ### `oas_path_to_redoc_html` -- **Type**: `Optional[str]` -- **Default**: `None` -- **Description**: Path to HTML file to override the existing Redoc HTML +- **タイプ**: `Optional[str]` +- **デフォルト**: `None` +- **Description**: 既存のやり直しHTMLをオーバーライドするHTMLファイルへのパス ### `oas_path_to_swagger_html` -- **Type**: `Optional[str]` -- **Default**: `None` -- **Description**: Path to HTML file to override the existing Swagger HTML +- **タイプ**: `Optional[str]` +- **デフォルト**: `None` +- **説明**: 既存の Swagger HTML をオーバーライドする HTML ファイルへのパス ### `oas_ui_default` -- **Type**: `Optional[str]` -- **Default**: `"redoc"` -- **Description**: Which OAS documentation to serve on the bare `oas_url_prefix` endpoint; when `None` there will be no documentation at that location +- **タイプ**: `Optional[str]` +- **デフォルト**: `"redoc"` +- **説明**: どのOASドキュメントを `oas_url_prefix` エンドポイントで提供します。`None` の場所にドキュメントがありません。 ### `oas_ui_redoc` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable the Redoc UI +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: やり直しのUIを有効にするかどうか ### `oas_ui_swagger` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable the Swagger UI +- **タイプ**: `bool` +- **デフォルト**: `True` +- **説明**: Swagger UI を有効にするかどうか ### `oas_ui_swagger_version` -- **Type**: `str` -- **Default**: `"4.1.0"` -- **Description**: Which Swagger version to use +- **タイプ**: `str` +- **デフォルト**: `"4.1.0"` +- **説明**: どのSwaggerバージョンを使用するか ### `oas_uri_to_config` -- **Type**: `str` +- **タイプ**: `str` - **Default**: `"/swagger-config"` -- **Description**: Path to serve the Swagger configurtaion +- **説明**: Swagger configurtaion を提供するパス ### `oas_uri_to_json` -- **Type**: `str` +- **タイプ**: `str` - **Default**: `"/openapi.json"` -- **Description**: Path to serve the OpenAPI JSON +- **説明**: OpenAPI JSON を提供するためのパス ### `oas_uri_to_redoc` -- **Type**: `str` -- **Default**: `"/redoc"` -- **Description**: Path to Redoc +- **タイプ**: `str` +- **デフォルト**: `"/redoc"` +- **説明**: やり直しへのパス ### `oas_uri_to_swagger` -- **Type**: `str` +- **タイプ**: `str` - **Default**: `"/swagger"` -- **Description**: Path to Swagger +- **説明**: Swagger へのパス ### `oas_url_prefix` -- **Type**: `str` +- **タイプ**: `str` - **Default**: `"/docs"` -- **Description**: URL prefix for the Blueprint that all of the OAS documentation witll attach to +- **説明**: OASドキュメントのすべてのwitllが添付するブループリントのURLプレフィックス。 ### `swagger_ui_configuration` -- **Type**: `Dict[str, Any]` -- **Default**: `{"apisSorter": "alpha", "operationsSorter": "alpha", "docExpansion": "full"}` -- **Description**: The Swagger documentation to be served to the frontend +- **タイプ**: `Dict[str, Any]` +- **デフォルト**: `{"apisSorter": "alpha", "operationsSorter": "alpha", "docExpansion": "full"}` +- **説明**: フロントエンドに提供される Swagger ドキュメント ### `templating_enable_async` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to set `enable_async` on the Jinja `Environment` +- **タイプ**: `bool` +- **デフォルト**: `True` +- **Description**: 神社`Environment` に `enable_async` を設定するかどうか ### `templating_path_to_templates` -- **Type**: `Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]] ` -- **Default**: `templates` -- **Description**: A single path, or multiple paths to where your template files are located +- **タイプ**: `Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]] ` +- **デフォルト**: `templates` +- **説明**: テンプレートファイルがどこにあるか、単一のパス、または複数のパスです。 ### `trace_excluded_headers` -- **Type**: `Sequence[str]` -- **Default**: `("authorization", "cookie")` -- **Description**: Which headers should be suppresed from responses to `TRACE` requests +- **タイプ**: `Sequence[str]` +- **デフォルト**: `("authorization", "cookie")` +- **Description**: `TRACE`リクエストへのレスポンスから抑制されるヘッダーを指定します。 From 6b824fa570ca5aec4c884239a7253b2e17d88ab4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:47 +0200 Subject: [PATCH 392/698] New translations configuration.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/configuration.md | 238 +++++++++--------- 1 file changed, 119 insertions(+), 119 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/configuration.md b/guide/content/zh/plugins/sanic-ext/configuration.md index 1443cfc6e9..c9594e290a 100644 --- a/guide/content/zh/plugins/sanic-ext/configuration.md +++ b/guide/content/zh/plugins/sanic-ext/configuration.md @@ -1,27 +1,27 @@ --- -title: Sanic Extensions - Configuration +title: Sanic 扩展 - 配置 --- -# Configuration +# 配置 -Sanic Extensions can be configured in all of the same ways that [you can configure Sanic](../../guide/deployment/configuration.md). That makes configuring Sanic Extensions very easy. +可使用[你可以配置Sanic](../../guide/deplment/configuration.md)的所有相同方式配置Sanic 扩展。 这使得配置Sanic扩展变得非常容易。 ```python app = Sanic("MyApp") app.config.OAS_URL_PREFIX = "/apidocs" ``` -However, there are a few more configuration options that should be considered. +然而，还有一些其他配置方案应加以考虑。 -## Manual `extend` +## 手动`extend` -.. column:: +.. 列: ``` -Even though Sanic Extensions will automatically attach to your application, you can manually choose `extend`. When you do that, you can pass all of the configuration values as a keyword arguments (lowercase). +尽管Sanic 扩展会自动附加到您的应用程序，但您可以手动选择 `extend`。 当你这样做时，你可以传递所有的配置值作为关键字参数(小写)。 ``` -.. column:: +.. 列: ```` ```python @@ -30,13 +30,13 @@ app.extend(oas_url_prefix="/apidocs") ``` ```` -.. column:: +.. 列: ``` -Or, alternatively they could be passed all at once as a single `dict`. +或者，也可以同时将其作为一个单一的词语。 ``` -.. column:: +.. 列: ```` ```python @@ -45,31 +45,31 @@ app.extend(config={"oas_url_prefix": "/apidocs"}) ``` ```` -.. column:: +.. 列: ``` -Both of these solutions suffers from the fact that the names of the configuration settings are not discoverable by an IDE. Therefore, there is also a type annotated object that you can use. This should help the development experience. +由于配置设置的名称无法被IDE发现，这两种解决办法都受到影响。 因此，您也可以使用一个类型注释的对象。这将有助于开发体验。 ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import Config +来自sanic_ext import Config app = Sanic("MyApp") app.extend(config=Config(oas_url_prefix="/apidocs")) ``` ```` -## Settings +## 设置 -.. note:: +.. 注： ```` -Often, the easiest way to change these for an application (since they likely are not going to change dependent upon an environment), is to set them directly on the `app.config` object. +通常最容易改变申请的方式(因为它们可能不会因环境而改变)， 将它们直接设置在“应用”上。 onfig`对象。 -Simply use the capitalized version of the configuration key as shown here: +只需使用这里显示的配置密钥的大写版本： ```python app = Sanic("MyApp") @@ -79,210 +79,210 @@ app.config.OAS_URL_PREFIX = "/apidocs" ### `cors` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable CORS protection +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否启用 CORS 保护 ### `cors_allow_headers` -- **Type**: `str` -- **Default**: `"*"` -- **Description**: Value of the header: `access-control-allow-headers` +- **类型**: `str` +- **默认**: `"*"` +- **描述**: 标题值: `access-control-allow-headers` ### `cors_always_send` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to always send the header: `access-control-allow-origin` +- **类型**: `bool` +- **默认**: `True` +- **描述**: 是否总是发送头部: `access-control-allow-origin` ### `cors_automatic_options` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to automatically generate `OPTIONS` endpoints for routes that do _not_ already have one defined +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否为那些没有\*定义过一个的路由自动生成 "OPTIONS" 端点 ### `cors_expose_headers` -- **Type**: `str` -- **Default**: `""` -- **Description**: Value of the header: `access-control-expose-headers` +- **类型**: `str` +- **默认**: `""` +- **描述**: 标题值: `access-control-expose-headers` ### `cors_max_age` -- **Type**: `int` -- **Default**: `5` -- **Description**: Value of the header: `access-control-max-age` +- **类型**: `int` +- **默认**: `5` +- **描述**: 标题值: `access-control-max-age` ### `cors_methods` -- **Type**: `str` -- **Default**: `""` -- **Description**: Value of the header: `access-control-access-control-allow-methods` +- **类型**: `str` +- **默认**: `""` +- **描述**: 标题值: `access-control-access-allow-methods` ### `cors_origins` -- **Type**: `str` -- **Default**: `""` -- **Description**: Value of the header: `access-control-allow-origin` +- **类型**: `str` +- **默认**: `""` +- **描述**: 标题值: `access-control-allow-origin` -.. warning:: +.. 警告：: ``` -Be very careful if you place `*` here. Do not do this unless you know what you are doing as it can be a security issue. +如果你把`*`放在这里，请非常小心。 不要这样做，除非你知道你正在做什么，因为它可能是一个安全问题。 ``` ### `cors_send_wildcard` -- **Type**: `bool` -- **Default**: `False` -- **Description**: Whether to send a wildcard origin instead of the incoming request origin +- **类型**: `bool` +- **默认**: `False` +- **描述**：是否发送通配符来源而不是传入请求来源 ### `cors_supports_credentials` -- **Type**: `bool` -- **Default**: `False` -- **Description**: Value of the header: `access-control-allow-credentials` +- **类型**: `bool` +- **默认**: `False` +- **描述**: 标题值: `access-control-allow-credentials` ### `cors_vary_header` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to add the `vary` header +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否添加 `vary` 标题 ### `http_all_methods` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Adds the HTTP `CONNECT` and `TRACE` methods as allowable +- **类型**: `bool` +- **默认**: `True` +- **描述**: 添加 HTTP `CONNECT` 和 `TRACE` 方法为允许方法 ### `http_auto_head` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Automatically adds `HEAD` handlers to any `GET` routes +- **类型**: `bool` +- **默认**: `True` +- **描述**：自动将 `HEAD` 处理程序添加到任何 `GET` 路由 ### `http_auto_options` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Automatically adds `OPTIONS` handlers to any routes without +- **类型**: `bool` +- **默认**: `True` +- **描述**：自动将 `OpTIONS` 处理程序添加到任何路由中，无需此说明 ### `http_auto_trace` -- **Type**: `bool` -- **Default**: `False` -- **Description**: Automatically adds `TRACE` handlers to any routes without +- **类型**: `bool` +- **默认**: `False` +- **描述**：自动将 `TRACE` 处理程序添加到任何路由中无需添加。 ### `oas` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable OpenAPI specification generation +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否启用 OpenAPI 规范生成 ### `oas_autodoc` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to automatically extract OpenAPI details from the docstring of a route function +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否从路由函数的 docstring 自动提取OpenAPI 详细信息 ### `oas_ignore_head` -- **Type**: `bool` -- **Default**: `True` -- **Description**: WHen `True`, it will not add `HEAD` endpoints into the OpenAPI specification +- **类型**: `bool` +- **默认**: `True` +- **描述**: WHen `True`, 它将不会在 OpenAPI 规范中添加 `HEAD` 端点 ### `oas_ignore_options` -- **Type**: `bool` -- **Default**: `True` -- **Description**: WHen `True`, it will not add `OPTIONS` endpoints into the OpenAPI specification +- **类型**: `bool` +- **默认**: `True` +- **描述**: WHen `True`, 它不会在 OpenAPI 规范中添加 `OPTIONS` 端点 ### `oas_path_to_redoc_html` -- **Type**: `Optional[str]` -- **Default**: `None` -- **Description**: Path to HTML file to override the existing Redoc HTML +- **类型**: `可选的[str]` +- **默认**: `None` +- **描述**：HTML文件路径以覆盖现有的 Redoc HTML ### `oas_path_to_swagger_html` -- **Type**: `Optional[str]` -- **Default**: `None` -- **Description**: Path to HTML file to override the existing Swagger HTML +- **类型**: `可选的[str]` +- **默认**: `None` +- **描述**：要覆盖现有的 Swagger HTML 文件的路径 ### `oas_ui_default` -- **Type**: `Optional[str]` -- **Default**: `"redoc"` -- **Description**: Which OAS documentation to serve on the bare `oas_url_prefix` endpoint; when `None` there will be no documentation at that location +- **类型**: `可选的[str]` +- **默认**: \`"redoc"" +- **描述**：哪些OAS 文档将用于bare `oas_url_prefix`端点；当`None`时，该位置将没有文档。 ### `oas_ui_redoc` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable the Redoc UI +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否启用 Redoc 界面 ### `oas_ui_swagger` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to enable the Swagger UI +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否启用 Swagger 界面 ### `oas_ui_swagger_version` -- **Type**: `str` -- **Default**: `"4.1.0"` -- **Description**: Which Swagger version to use +- **类型**: `str` +- **默认**: `"4.1.0"` +- **描述**：要使用哪个Swagger版本 ### `oas_uri_to_config` -- **Type**: `str` +- **类型**: `str` - **Default**: `"/swagger-config"` -- **Description**: Path to serve the Swagger configurtaion +- **描述**：服务的 Swagger 配置路径 ### `oas_uri_to_json` -- **Type**: `str` +- **类型**: `str` - **Default**: `"/openapi.json"` -- **Description**: Path to serve the OpenAPI JSON +- **描述**：提供 OpenAPI JSON 的路径 ### `oas_uri_to_redoc` -- **Type**: `str` -- **Default**: `"/redoc"` -- **Description**: Path to Redoc +- **类型**: `str` +- **默认**: \`"/redoc"" +- **描述**：Redoc 路径 ### `oas_uri_to_swagger` -- **Type**: `str` +- **类型**: `str` - **Default**: `"/swagger"` -- **Description**: Path to Swagger +- **描述**：到 Swagger 的路径 ### `oas_url_prefix` -- **Type**: `str` +- **类型**: `str` - **Default**: `"/docs"` -- **Description**: URL prefix for the Blueprint that all of the OAS documentation witll attach to +- **描述**：所有OA文档都有意附加的蓝图的 URL 前缀 ### `swagger_ui_configuration` - **Type**: `Dict[str, Any]` -- **Default**: `{"apisSorter": "alpha", "operationsSorter": "alpha", "docExpansion": "full"}` -- **Description**: The Swagger documentation to be served to the frontend +- **默认**: "{"apisSorter": "alph", "operationsSorter": "alpha", "docExpassion": "full"}" +- **描述**: 即将服务到前端的 Swagger 文档 ### `templating_enable_async` -- **Type**: `bool` -- **Default**: `True` -- **Description**: Whether to set `enable_async` on the Jinja `Environment` +- **类型**: `bool` +- **默认**: `True` +- **描述**：是否在 Jinja `Environment` 中设置 `enable_async` ### `templating_path_to_templates` -- **Type**: `Union[str, os.PathLike, Sequence[Union[str, os.PathLike]]] ` -- **Default**: `templates` -- **Description**: A single path, or multiple paths to where your template files are located +- **Type**: \`Union[str, os.PathLike, Sequence[Union[str, os.PathLie]]] +- **默认**: `templates` +- **描述**：单一路径，或多个路径到您的模板文件所在位置 -### `trace_excluded_headers` +### `Trace_excluded_headers` -- **Type**: `Sequence[str]` -- **Default**: `("authorization", "cookie")` -- **Description**: Which headers should be suppresed from responses to `TRACE` requests +- **Type**: `序列[str]` +- **默认**: `("authorization", "cookie")` +- **描述**：哪个头应该从对 `TRACE` 请求的响应中停止 From 028384c81e430bf56cf1b6e612a81fd1b97159ac Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:48 +0200 Subject: [PATCH 393/698] New translations convenience.md (Japanese) --- .../ja/plugins/sanic-ext/convenience.md | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/convenience.md b/guide/content/ja/plugins/sanic-ext/convenience.md index 7aaef2aa75..8cb677a4b0 100644 --- a/guide/content/ja/plugins/sanic-ext/convenience.md +++ b/guide/content/ja/plugins/sanic-ext/convenience.md @@ -1,18 +1,18 @@ --- -title: Sanic Extensions - Convenience +title: サニックエクステンション - Convenience --- -# Convenience +# 便利さ -## Fixed serializer +## 固定シリアライザー -.. column:: +.. 列:: ``` -Often when developing an application, there will be certain routes that always return the same sort of response. When this is the case, you can predefine the return serializer and on the endpoint, and then all that needs to be returned is the content. +多くの場合、アプリケーションを開発する場合、常に同じ種類のレスポンスを返す特定のルートがあります。 この場合、返品シリアライザとエンドポイントを事前に定義できます。 返されるべきものは内容だけです ``` -.. column:: +.. 列:: ```` ```python @@ -27,13 +27,13 @@ async def hello_world(request, name: str): ``` ```` -.. column:: +.. 列:: ``` -The `serializer` decorator also can add status codes. +`serializer`デコレータはステータスコードを追加することもできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -46,15 +46,15 @@ async def create_something(request): ``` ```` -## Custom serializer +## カスタムシリアライザー -.. column:: +.. 列:: ``` -Using the `@serializer` decorator, you can also pass your own custom functions as long as they also return a valid type (`HTTPResonse`). +`@serializer`デコレータを使用して、有効な型(`HTTPResonse`)を返す限り、独自のカスタム関数を渡すこともできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -75,19 +75,19 @@ async def do_action(request, action: str): ``` ```` -.. column:: +.. 列:: ``` -Now, returning just a string should return a nice serialized output. +今度は、文字列だけを返すと、素敵なシリアル化された出力が返されます。 ``` -.. column:: +.. 列:: ```` ```python $ curl localhost:8000/eat_cookies -X POST { - "request_id": "ef81c45b-235c-46dd-9dbd-b550f8fa77f9", + "request_id": "ef81c45b-235c-46d-9dbd-b550f8fa77f9", "action": "eat_cookies", "message": "This is a message" } @@ -95,31 +95,31 @@ $ curl localhost:8000/eat_cookies -X POST ``` ```` -## Request counter +## カウンターを要求する -.. column:: +.. 列:: ``` -Sanic Extensions comes with a subclass of `Request` that can be setup to automatically keep track of the number of requests processed per worker process. To enable this, you should pass the `CountedRequest` class to your application contructor. +Sanic Extensionsには`Request`のサブクラスが付属しており、ワーカープロセスごとに処理されたリクエストの数を自動的に追跡できるように設定できます。 これを有効にするには、アプリケーションコントラクターに `CounttedRequest` クラスを渡す必要があります。 ``` -.. column:: +.. 列:: ```` ```python from sanic_ext import CountedRequest -app = Sanic(..., request_class=CountedRequest) +app = Sanic(..., request_class=CounttedRequest) ``` ```` -.. column:: +.. 列:: ``` -You will now have access to the number of requests served during the lifetime of the worker process. +ワーカープロセスの生涯中に提供されるリクエスト数にアクセスできるようになります。 ``` -.. column:: +.. 列:: ```` ```python @@ -129,6 +129,6 @@ async def handler(request: CountedRequest): ``` ```` -If possible, the request count will also be added to the [worker state](../../guide/deployment/manager.md#worker-state). +可能であれば、リクエスト数は [worker state](../../guide/deployment/manager.md#worker-state) にも追加されます。 ![](https://user-images.githubusercontent.com/166269/190922460-43bd2cfc-f81a-443b-b84f-07b6ce475cbf.png) From c188cd3ebd1de1a789a71f2f3bbf736edd4a948e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:50 +0200 Subject: [PATCH 394/698] New translations convenience.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/convenience.md | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/convenience.md b/guide/content/zh/plugins/sanic-ext/convenience.md index 7aaef2aa75..a498b4249e 100644 --- a/guide/content/zh/plugins/sanic-ext/convenience.md +++ b/guide/content/zh/plugins/sanic-ext/convenience.md @@ -1,18 +1,18 @@ --- -title: Sanic Extensions - Convenience +title: 无声扩展 - 便捷性 --- -# Convenience +# 便捷性 -## Fixed serializer +## 固定序列转换器 -.. column:: +.. 列: ``` -Often when developing an application, there will be certain routes that always return the same sort of response. When this is the case, you can predefine the return serializer and on the endpoint, and then all that needs to be returned is the content. +在开发应用程序时，往往会有某些路径总是返回同样的响应。 如果情况如此，您可以预定义返回序列转换器和端点。 然后所有需要返回的都是内容。 ``` -.. column:: +.. 列: ```` ```python @@ -27,13 +27,13 @@ async def hello_world(request, name: str): ``` ```` -.. column:: +.. 列: ``` -The `serializer` decorator also can add status codes. +`序列化器`装饰器也可以添加状态码。 ``` -.. column:: +.. 列: ```` ```python @@ -46,15 +46,15 @@ async def create_something(request): ``` ```` -## Custom serializer +## 自定义序列转换器 -.. column:: +.. 列: ``` -Using the `@serializer` decorator, you can also pass your own custom functions as long as they also return a valid type (`HTTPResonse`). +使用 `@serializer` 装饰器，您也可以传递您自己的自定义函数只要他们返回一个有效的类型(`HTTPResonse`)。 ``` -.. column:: +.. 列: ```` ```python @@ -75,51 +75,51 @@ async def do_action(request, action: str): ``` ```` -.. column:: +.. 列: ``` -Now, returning just a string should return a nice serialized output. +现在，返回一个字符串应该返回一个很好的序列化输出。 ``` -.. column:: +.. 列: ```` ```python $ curl localhost:8000/eat_cookies -X POST -{ - "request_id": "ef81c45b-235c-46dd-9dbd-b550f8fa77f9", +own + "request_id": "ef81c45b-235c-46ddd-b50f8fa77f9", "action": "eat_cookies", - "message": "This is a message" + "message": "这是一个消息" } ``` ```` -## Request counter +## 请求计数器 -.. column:: +.. 列: ``` -Sanic Extensions comes with a subclass of `Request` that can be setup to automatically keep track of the number of requests processed per worker process. To enable this, you should pass the `CountedRequest` class to your application contructor. +Sanic 扩展有一个子类的 `Request` ，可以设置来自动跟踪每个工人进程处理的请求数量。 为了启用此功能，您应该将 ' CountedRequest` 类传递给您的应用程序contrator。 ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import CountedRequest +来自sanic_ext import CountedRequest -app = Sanic(..., request_class=CountedRequest) +app = Sanic(...request_class=CountedRequest) ``` ```` -.. column:: +.. 列: ``` -You will now have access to the number of requests served during the lifetime of the worker process. +您现在将能够访问在工人整个过程中服务的请求数量。 ``` -.. column:: +.. 列: ```` ```python @@ -129,6 +129,6 @@ async def handler(request: CountedRequest): ``` ```` -If possible, the request count will also be added to the [worker state](../../guide/deployment/manager.md#worker-state). +如果可能，请求计数也将添加到[工人状态](../../guide/deplement/manager.md#worker-state)。 ![](https://user-images.githubusercontent.com/166269/190922460-43bd2cfc-f81a-443b-b84f-07b6ce475cbf.png) From 740febd576858461856d46b14e3fa1a8a279390b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:51 +0200 Subject: [PATCH 395/698] New translations custom.md (Japanese) --- guide/content/ja/plugins/sanic-ext/custom.md | 36 ++++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/custom.md b/guide/content/ja/plugins/sanic-ext/custom.md index 6facab3f66..50e6984433 100644 --- a/guide/content/ja/plugins/sanic-ext/custom.md +++ b/guide/content/ja/plugins/sanic-ext/custom.md @@ -1,28 +1,28 @@ --- -title: Sanic Extensions - Custom +title: サニックエクステンション - Custom --- -# Custom extensions +# カスタムの拡張機能 -It is possible to create your own custom extensions. +独自の拡張機能を作成することは可能です。 -Version 22.9 added the `Extend.register` [method](#extension-preregistration). This makes it extremely easy to add custom expensions to an application. +バージョン 22.9 は `Extend.register` [method](#extension-preregistration) を追加しました。 これにより、アプリケーションにカスタムの拡張機能を追加することが非常に簡単になります。 -## Anatomy of an extension +## 拡張機能の解剖学 -All extensions must subclass `Extension`. +すべてのエクステンションは `Extension` のサブクラスでなければなりません。 -### Required +### 必須 -- `name`: By convention, the name is an all-lowercase string -- `startup`: A method that runs when the extension is added +- `name`: 規約により、名前は全て小文字の文字列です +- `startup`: 拡張機能が追加されたときに実行されるメソッド -### Optional +### 省略可能 -- `label`: A method that returns additional information about the extension in the MOTD -- `included`: A method that returns a boolean whether the extension should be enabled or not (could be used for example to check config state) +- `label`: MOTD の拡張機能に関する追加情報を返すメソッド +- `included`: 拡張機能を有効にするかどうかを真偽値を返すメソッド (設定状態を確認するために例えば使用できます) -### Example +### 例 ```python from sanic import Request, Sanic, json @@ -68,15 +68,15 @@ async def handler(request: Request): return json({"foo": "bar"}) ``` -## Extension preregistration +## エクステンションの事前登録 -.. column:: +.. 列:: ``` -`Extend.register` simplifies the addition of custom extensions. +`Extend.register` はカスタムエクステンションの追加を簡単にします。 ``` -.. column:: +.. 列:: ```` ```python @@ -89,4 +89,4 @@ Extend.register(MyCustomExtension()) ``` ```` -_Added in v22.9_ +_v22.9_に追加されました From b70353801370df0d59f028752c2c9438e09e2911 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:52 +0200 Subject: [PATCH 396/698] New translations custom.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/custom.md | 42 ++++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/custom.md b/guide/content/zh/plugins/sanic-ext/custom.md index 6facab3f66..19b15fc171 100644 --- a/guide/content/zh/plugins/sanic-ext/custom.md +++ b/guide/content/zh/plugins/sanic-ext/custom.md @@ -1,28 +1,28 @@ --- -title: Sanic Extensions - Custom +title: Sanic 扩展 - 自定义 --- -# Custom extensions +# 自定义扩展 -It is possible to create your own custom extensions. +可以创建您自己的自定义扩展。 -Version 22.9 added the `Extend.register` [method](#extension-preregistration). This makes it extremely easy to add custom expensions to an application. +22.9版本添加了 `Extend.register` [method](#extension-preregistration)。 这使得在应用程序中添加自定义支出变得极为容易。 -## Anatomy of an extension +## 扩展的解析度 -All extensions must subclass `Extension`. +所有扩展必须是子类“扩展”。 -### Required +### 必填 -- `name`: By convention, the name is an all-lowercase string -- `startup`: A method that runs when the extension is added +- `name`: 按惯例, 名称是一个小写字符串 +- `启动`: 添加扩展时运行的方法 -### Optional +### 可选的 -- `label`: A method that returns additional information about the extension in the MOTD -- `included`: A method that returns a boolean whether the extension should be enabled or not (could be used for example to check config state) +- `label`：返回MOTD中有关扩展的额外信息的方法 +- `included`：返回是否启用扩展名布尔值的方法 (可以用来检查配置状态) -### Example +### 示例 ```python from sanic import Request, Sanic, json @@ -68,25 +68,25 @@ async def handler(request: Request): return json({"foo": "bar"}) ``` -## Extension preregistration +## 扩展预注册 -.. column:: +.. 列: ``` -`Extend.register` simplifies the addition of custom extensions. +`Extend.register` 简化了自定义扩展的添加。 ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import Extend, Extension +from sanic_ext import Extend, extension class MyCustomExtension(Extension): - ... -Extend.register(MyCustomExtension()) + +Extend.register(MyCustomExtencion()) ``` ```` -_Added in v22.9_ +_添加于 v22.9_ From bce07d0b80f93509f4c99a2df6b1ac4dc82f60ed Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:53 +0200 Subject: [PATCH 397/698] New translations getting-started.md (Japanese) --- .../ja/plugins/sanic-ext/getting-started.md | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/getting-started.md b/guide/content/ja/plugins/sanic-ext/getting-started.md index bf49796ec7..2c7c6e1e82 100644 --- a/guide/content/ja/plugins/sanic-ext/getting-started.md +++ b/guide/content/ja/plugins/sanic-ext/getting-started.md @@ -1,53 +1,53 @@ --- -title: Sanic Extensions - Getting Started +title: サニックエクステンション - はじめに --- -# Getting Started +# はじめに -Sanic Extensions is an _officially supported_ plugin developed, and maintained by the SCO. The primary goal of this project is to add additional features to help Web API and Web application development easier. +Sanic Extensionsは、SCOによって開発され、維持されている_公式にサポートされている_プラグインです。 このプロジェクトの主な目的は、Web API および Web アプリケーション開発を容易にする追加機能を追加することです。 -## Features +## 特徴 -- CORS protection -- Template rendering with Jinja -- Dependency injection into route handlers -- OpenAPI documentation with Redoc and/or Swagger -- Predefined, endpoint-specific response serializers -- Request query arguments and body input validation -- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- CORS保護 +- 神社でテンプレートをレンダリングする +- ルートハンドラへの依存性インジェクション +- やり直しや Swagger を使用した OpenAPI ドキュメント +- 事前定義されたエンドポイント固有のレスポンスシリアライザー +- クエリクエストの引数と本文入力のバリデーションをリクエスト +- `HEAD`、`OPTIONS`、および `TRACE`エンドポイントを自動的に作成します -## Minimum requirements +## 最低要件 - **Python**: 3.8+ - **Sanic**: 21.9+ -## Install +## インストール -The best method is to just install Sanic Extensions along with Sanic itself: +最良の方法は、Sanic自体と一緒にSanic Extensionsをインストールすることです: ```bash pip install sanic[ext] ``` -You can of course also just install it by itself. +もちろん、単独でインストールすることもできます。 ```bash pip install sanic-ext ``` -## Extend your application +## アプリケーションを拡張 -Out of the box, Sanic Extensions will enable a bunch of features for you. +Sanic Extensionsは、すぐにたくさんの機能を利用できるようになります。 -.. column:: +.. 列:: ``` -To setup Sanic Extensions (v21.12+), you need to do: **nothing**. If it is installed in the environment, it is setup and ready to go. +Sanic Extensions(v21.12+)をセットアップするには、次の手順を実行する必要があります。**何もありません**。環境内にインストールされている場合は、セットアップして準備が整います。 -This code is the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md) _without any changes_, but using Sanic Extensions with `sanic-ext` installed in the background. +このコードは、[Sanic Getting Started page](../../guide/getting-started)のHello, world appです。 d) _何も変更せずに `sanic-ext` がバックグラウンドにインストールされた Sanic 拡張機能を使用します。 ``` -.. column:: +.. 列:: ```` ```python @@ -62,7 +62,7 @@ async def hello_world(request): ``` ```` -.. column:: +.. 列:: ``` **_OLD DEPRECATED SETUP_** @@ -72,7 +72,7 @@ In v21.9, the easiest way to get started is to instantiate it with `Extend`. If you look back at the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md), you will see the only additions here are the two highlighted lines. ``` -.. column:: +.. 列:: ```` ```python @@ -89,4 +89,4 @@ async def hello_world(request): ``` ```` -Regardless of how it is setup, you should now be able to view the OpenAPI documentation and see some of the functionality in action: [http://localhost:8000/docs](http://localhost:8000/docs). +どのように設定されているかに関わらず、OpenAPI ドキュメントを表示し、動作中のいくつかの機能を確認できるようになりました: [http://localhost:8000/docs](http://localhost:8000/docs)。 From bd86f795bddc300ad3e0a4fefbf62d0d43020e6a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:55 +0200 Subject: [PATCH 398/698] New translations getting-started.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/getting-started.md | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/getting-started.md b/guide/content/zh/plugins/sanic-ext/getting-started.md index bf49796ec7..e5afa6da06 100644 --- a/guide/content/zh/plugins/sanic-ext/getting-started.md +++ b/guide/content/zh/plugins/sanic-ext/getting-started.md @@ -1,78 +1,78 @@ --- -title: Sanic Extensions - Getting Started +title: Sanic 扩展 - 开始使用 --- -# Getting Started +# 正在开始 -Sanic Extensions is an _officially supported_ plugin developed, and maintained by the SCO. The primary goal of this project is to add additional features to help Web API and Web application development easier. +Sanic 扩展是由 SCO开发和维护的 _官方支持_ 插件。 这个项目的主要目标是增加额外的功能，帮助Web API 和Web 应用程序开发更容易。 -## Features +## 功能 -- CORS protection -- Template rendering with Jinja -- Dependency injection into route handlers -- OpenAPI documentation with Redoc and/or Swagger -- Predefined, endpoint-specific response serializers -- Request query arguments and body input validation -- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +- CORS 保护 +- 使用 Jinja 渲染模板 +- 依赖注入路由处理 +- 与 Redoc 或 Swagger 的 OpenAPI 文档 +- 预定义的端点特定响应序列转换器 +- 请求查询参数和实体输入验证 +- 自动创建 `HEAD`, `OPTIONS` 和 `TRACE` 终点 -## Minimum requirements +## 最低要求 - **Python**: 3.8+ - **Sanic**: 21.9+ -## Install +## 安装 -The best method is to just install Sanic Extensions along with Sanic itself: +最好的方法是立即安装 Sanic 扩展以及Sanic 本身： ```bash pip install sanic[ext] ``` -You can of course also just install it by itself. +当然你也可以自己安装它。 ```bash -pip install sanic-ext +pip 安装 sanic-ext ``` -## Extend your application +## 扩展您的应用程序 -Out of the box, Sanic Extensions will enable a bunch of features for you. +Sanic 扩展将从箱子中为您启用一堆功能。 -.. column:: +.. 列: ``` -To setup Sanic Extensions (v21.12+), you need to do: **nothing**. If it is installed in the environment, it is setup and ready to go. +若要设置 Sanic 扩展 (v21.12+), 您需要做: **nithing** 。如果它是在环境中安装的，它将被设置并准备就绪。 -This code is the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md) _without any changes_, but using Sanic Extensions with `sanic-ext` installed in the background. +此代码是Hello, 世界应用在 [Sanic Getting Started page](../../guide/getting-started). d) _没有任何更改_, 但使用 Sanic Extensions 使用 `sanic-ext` 在后台安装。 ``` -.. column:: +.. 列: ```` ```python -from sanic import Sanic +from sanic importing Sanic from sanic.response import text app = Sanic("MyHelloWorldApp") -@app.get("/") +@app. et("/") async def hello_world(request): return text("Hello, world.") ``` ```` -.. column:: +.. 列: ``` **_OLD DEPRECATED SETUP_** -In v21.9, the easiest way to get started is to instantiate it with `Extend`. +在 v21.9中，最容易启动的方法是使用 `Extend` 实例化它。 -If you look back at the Hello, world app in the [Sanic Getting Started page](../../guide/getting-started.md), you will see the only additions here are the two highlighted lines. +如果你回到你好，世界应用在 [Sanic Getting Started页面](../) 向导/getting-started.md, 您将看到这里唯一的添加是两行高亮显示。 ``` -.. column:: +.. 列: ```` ```python @@ -89,4 +89,4 @@ async def hello_world(request): ``` ```` -Regardless of how it is setup, you should now be able to view the OpenAPI documentation and see some of the functionality in action: [http://localhost:8000/docs](http://localhost:8000/docs). +无论如何设置，您现在都应该能够查看 OpenAPI 文档，并查看一些功能：[[http://localhost:8000/docs](http://localhost:8000/docs](http://localhost:8000/docs)。 From 977eecb037862aae853afd733a1a6204be2b1b5a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:56 +0200 Subject: [PATCH 399/698] New translations health-monitor.md (Japanese) --- .../ja/plugins/sanic-ext/health-monitor.md | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/health-monitor.md b/guide/content/ja/plugins/sanic-ext/health-monitor.md index 82b8271f95..b3051a49fa 100644 --- a/guide/content/ja/plugins/sanic-ext/health-monitor.md +++ b/guide/content/ja/plugins/sanic-ext/health-monitor.md @@ -1,22 +1,22 @@ --- -title: Sanic Extensions - Health Monitor +title: サニックエクステンション - ヘルスモニター --- -# Health monitor +# ヘルスモニター -The health monitor requires both `sanic>=22.9` and `sanic-ext>=22.9`. +ヘルスモニターには、`sanic>=22.9` と `sanic-ext>=22.9` の両方が必要です。 -You can setup Sanic Extensions to monitor the health of your worker processes. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). +Sanic Extensionsを設定して、作業工程の健全性を監視できます。 format@@0(../../guide/deployment/manager.md#single-process-mode) ではないことが必要です。 -## Setup +## セットアップ -.. column:: +.. 列:: ``` -Out of the box, the health monitor is disabled. You will need to opt-in if you would like to use it. +ヘルスモニターは無効になっています。使用したい場合はオプトインする必要があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -24,23 +24,23 @@ app.config.HEALTH = True ``` ```` -## How does it work +## どのように機能します -The monitor sets up a new background process that will periodically receive acknowledgements of liveliness from each worker process. If a worker process misses a report too many times, then the monitor will restart that one worker. +モニターは新しいバックグラウンドプロセスを設定し、それぞれのワーカープロセスから定期的に活気を認識します。 ワーカープロセスがレポートを何度も見逃した場合、モニターはそのワーカーを再起動します。 -## Diagnostics endpoint +## 診断エンドポイント -.. column:: +.. 列:: ``` -The health monitor will also enable a diagnostics endpoint that outputs the [worker state](../../guide/deployment/manager.md#worker-state). By default is id disabled. +ヘルスモニターは、[worker state](../../guide/deployment/manager)を出力する診断エンドポイントも有効にします。 d#worker-state). デフォルトではIDが無効になっています。 .. danger:: - The diagnostics endpoint is not secured. If you are deploying it in a production environment, you should take steps to protect it with a proxy server if you are using one. If not, you may want to consider disabling this feature in production since it will leak details about your server state. + 診断エンドポイントはセキュリティ保護されていません。 本番環境でデプロイする場合は、プロキシサーバーを使用して保護する手順を実行する必要があります。 そうでない場合は、サーバーの状態に関する詳細が漏れるため、本番環境でこの機能を無効にすることを検討することをお勧めします。 ``` -.. column:: +.. 列:: ```` ``` @@ -66,15 +66,15 @@ $ curl http://localhost:8000/__health__ ``` ```` -## Configuration - -| Key | Type | Default | Description | -| --------------------------------------------------------------------------------- | ------ | --------------- | --------------------------------------------------------------------------- | -| HEALTH | `bool` | `False` | Whether to enable this extension. | -| HEALTH_ENDPOINT | `bool` | `False` | Whether to enable the diagnostics endpoint. | -| HEALTH_MAX_MISSES | `int` | `3` | The number of consecutive misses before a worker process is restarted. | -| HEALTH_MISSED_THRESHHOLD | `int` | `10` | The number of seconds the monitor checks for worker process health. | -| HEALTH_MONITOR | `bool` | `True` | Whether to enable the health monitor. | -| HEALTH_REPORT_INTERVAL | `int` | `5` | The number of seconds between reporting each acknowledgement of liveliness. | -| HEALTH_URI_TO_INFO | `str` | `""` | The URI path of the diagnostics endpoint. | -| HEALTH_URL_PREFIX | `str` | `"/__health__"` | The URI prefix of the diagnostics blueprint. | +## 設定 + +| キー | タイプ | デフォルト | 説明 | +| ------------------------------------ | ------ | --------------- | --------------------------- | +| 健康 | `bool` | `False` | この拡張機能を有効にするかどうか。 | +| HEALTH_ENDPOINT | `bool` | `False` | 診断のエンドポイントを有効にするかどうか。 | +| 最大値が足りません | `int` | `3` | ワーカープロセスが再起動される前に連続したミスの数。 | +| 健康状態がありません。 | `int` | `10` | モニターがワーカープロセスの健全性をチェックする秒数。 | +| ヘルスモニター | `bool` | `True` | かどうかのヘルスモニターを有効にします。 | +| 内部レポート | `int` | `5` | 活気のあるそれぞれの確認を報告するまでの秒数。 | +| CHALLENGE_LABEL | `str` | `""` | 診断エンドポイントの URI パス。 | +| PREFIX | `str` | `"/__health__"` | 診断のブループリントの URI プレフィックス。 | From 645169f09ab52f52f856e13be9946964ea84447b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:58 +0200 Subject: [PATCH 400/698] New translations health-monitor.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/health-monitor.md | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/health-monitor.md b/guide/content/zh/plugins/sanic-ext/health-monitor.md index 82b8271f95..ae016637d3 100644 --- a/guide/content/zh/plugins/sanic-ext/health-monitor.md +++ b/guide/content/zh/plugins/sanic-ext/health-monitor.md @@ -1,22 +1,22 @@ --- -title: Sanic Extensions - Health Monitor +title: 神经扩展-健康监测 --- -# Health monitor +# 健康监测 -The health monitor requires both `sanic>=22.9` and `sanic-ext>=22.9`. +健康监视器需要`sanic>=22.9`和`sanic-ext>=22.9`。 -You can setup Sanic Extensions to monitor the health of your worker processes. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). +您可以设置 Sanic 扩展来监测您的工作流程的健康状况。 这要求您不要处于[单一进程模式](../../guide/deplement/manager.md#单一进程模式)。 -## Setup +## 设置 -.. column:: +.. 列: ``` -Out of the box, the health monitor is disabled. You will need to opt-in if you would like to use it. +在方框中，健康监视器被禁用。如果您想要使用它，您需要选择进入它。 ``` -.. column:: +.. 列: ```` ```python @@ -24,23 +24,23 @@ app.config.HEALTH = True ``` ```` -## How does it work +## 如何工作 -The monitor sets up a new background process that will periodically receive acknowledgements of liveliness from each worker process. If a worker process misses a report too many times, then the monitor will restart that one worker. +监测员建立了一个新的背景程序，将定期从每个工人过程中收到直观的确认书。 如果某个工人进程错过多次报告，则监视器会重新启动该工人。 -## Diagnostics endpoint +## 诊断终点 -.. column:: +.. 列: ``` -The health monitor will also enable a diagnostics endpoint that outputs the [worker state](../../guide/deployment/manager.md#worker-state). By default is id disabled. +健康监视器还将启用一个诊断端点，输出[工人状态](../../guide/deplement/manager)。 d#worker-state)。默认情况下ID已禁用。 -.. danger:: +。危险： - The diagnostics endpoint is not secured. If you are deploying it in a production environment, you should take steps to protect it with a proxy server if you are using one. If not, you may want to consider disabling this feature in production since it will leak details about your server state. + 诊断端点不安全。 如果你在生产环境中部署它，你应该采取步骤来保护它，如果你在使用代理服务器的话。 如果没有，您可能想要考虑在生产中禁用此功能，因为它会泄露您服务器状态的详细信息。 ``` -.. column:: +.. 列: ```` ``` @@ -66,15 +66,15 @@ $ curl http://localhost:8000/__health__ ``` ```` -## Configuration - -| Key | Type | Default | Description | -| --------------------------------------------------------------------------------- | ------ | --------------- | --------------------------------------------------------------------------- | -| HEALTH | `bool` | `False` | Whether to enable this extension. | -| HEALTH_ENDPOINT | `bool` | `False` | Whether to enable the diagnostics endpoint. | -| HEALTH_MAX_MISSES | `int` | `3` | The number of consecutive misses before a worker process is restarted. | -| HEALTH_MISSED_THRESHHOLD | `int` | `10` | The number of seconds the monitor checks for worker process health. | -| HEALTH_MONITOR | `bool` | `True` | Whether to enable the health monitor. | -| HEALTH_REPORT_INTERVAL | `int` | `5` | The number of seconds between reporting each acknowledgement of liveliness. | -| HEALTH_URI_TO_INFO | `str` | `""` | The URI path of the diagnostics endpoint. | -| HEALTH_URL_PREFIX | `str` | `"/__health__"` | The URI prefix of the diagnostics blueprint. | +## 配置 + +| 关键字 | 类型 | 默认设置 | 描述 | +| --------------------------------------------------------------------------------- | ------ | --------------- | ---------------- | +| 生命值 | `bool` | `False` | 是否启用此扩展。 | +| HEALTH_ENDPOINT | `bool` | `False` | 是否启用诊断端点。 | +| HEALTH_MEX_MISSES | `int` | `3` | 工作流程重新启动前连续缺失次数。 | +| HEALTH_MISSED_TITLE | `int` | `10` | 检查工人流程健康的秒数。 | +| HEALTH_MONITOR | `bool` | `True` | 是否启用健康监视器。 | +| HEALTH_REPORT_INTERVAL | `int` | `5` | 每次确认活动之间的秒数。 | +| HEALTH_URI_TO_INFO | `str` | `""` | 诊断端点的 URI 路径。 | +| HEALTH_URL_PREFIX | `str` | `"/__health__"` | 诊断蓝图的 URI 前缀。 | From f13d5579b59d60fbd07b4c1801bf64c7a4904def Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:21:59 +0200 Subject: [PATCH 401/698] New translations cors.md (Japanese) --- .../content/ja/plugins/sanic-ext/http/cors.md | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/http/cors.md b/guide/content/ja/plugins/sanic-ext/http/cors.md index d5e4f2ba4e..2726a56bd7 100644 --- a/guide/content/ja/plugins/sanic-ext/http/cors.md +++ b/guide/content/ja/plugins/sanic-ext/http/cors.md @@ -1,26 +1,26 @@ --- -title: Sanic Extensions - CORS protection +title: Sanic Extensions - CORS保護 --- -# CORS protection +# CORS保護 -Cross-Origin Resource Sharing (aka CORS) is a _huge_ topic by itself. The documentation here cannot go into enough detail about _what_ it is. You are highly encouraged to do some research on your own to understand the security problem presented by it, and the theory behind the solutions. [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are a great first step. +クロスオリジンリソース共有(CORS)は、単独で_巨大_トピックです。 ここのドキュメントでは、_何_についての詳細を説明することはできません。 あなたは非常にそれによって提示されたセキュリティの問題を理解するために、独自にいくつかの研究を行うことを奨励されています, そして、ソリューションの背後にある理論. [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) は素晴らしい第一歩です。 -In super brief terms, CORS protection is a framework that browsers use to facilitate how and when a web page can access information from another domain. It is extremely relevant to anyone building a single-page application. Often times your frontend might be on a domain like `https://portal.myapp.com`, but it needs to access the backend from `https://api.myapp.com`. +超簡単な言葉で CORS保護は、ウェブページが別のドメインから情報にアクセスできる方法と時間を容易にするためにブラウザが使用するフレームワークです。 これは、シングルページアプリケーションを構築するすべての人にとって非常に重要です。 フロントエンドは `https://portal.myapp.com` のようなドメインであることがよくありますが、 `https://api.myapp.com` からバックエンドにアクセスする必要があります。 -The implementation here is heavily inspired by [`sanic-cors`](https://github.com/ashleysommer/sanic-cors), which is in turn based upon [`flask-cors`](https://github.com/corydolphin/flask-cors). It is therefore very likely that you can achieve a near drop-in replacement of `sanic-cors` with `sanic-ext`. +ここでの実装は[`sanic-cors`](https://github.com/ashleysommer/sanic-cors)に大きくインスパイアされており、順番には [`flask-cors`](https://github.com/corydolphin/flask-cors) に基づいています。 したがって、ほぼ`sanic-cors`を`sanic-ext`に置き換えることができます。 -## Basic implementation +## 基本的な実装 -.. column:: +.. 列:: ``` -As shown in the example in the [auto-endpoints example](methods.md#options), Sanic Extensions will automatically enable CORS protection without further action. But, it does not offer too much out of the box. +format@@0(method) の例に示すように。 d#options), Sanic Extensionsは自動的にCORS保護を有効にします。しかし、あまり使いすぎることはありません。 -At a *bare minimum*, it is **highly** recommended that you set `config.CORS_ORIGINS` to the intended origin(s) that will be accessing the application. +*裸の最小値*では、アプリケーションにアクセスする目的の起点に`config.CORS_ORIGINS`を設定することを**高度に** 推奨します。 ``` -.. column:: +.. 列:: ```` ```python @@ -45,33 +45,33 @@ connection: keep-alive ``` ```` -## Configuration +## 設定 -The true power of CORS protection, however, comes into play once you start configuring it. Here is a table of all of the options. +ただし、CORSの設定を開始すると、CORSの保護の真の機能が実現します。 ここにすべてのオプションの表があります。 -| Key | Type | Default | Description | -| --------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `CORS_ALLOW_HEADERS` | `str` or `List[str]` | `"*"` | The list of headers that will appear in `access-control-allow-headers`. | -| `CORS_ALWAYS_SEND` | `bool` | `True` | When `True`, will always set a value for `access-control-allow-origin`. When `False`, will only set it if there is an `Origin` header. | -| `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | When the incoming preflight request is received, whether to automatically set values for `access-control-allow-headers`, `access-control-max-age`, and `access-control-allow-methods` headers. If `False` these values will only be set on routes that are decorated with the `@cors` decorator. | -| `CORS_EXPOSE_HEADERS` | `str` or `List[str]` | `""` | Specific list of headers to be set in `access-control-expose-headers` header. | -| `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | The maximum number of seconds the preflight response may be cached using the `access-control-max-age` header. A falsey value will cause the header to not be set. | -| `CORS_METHODS` | `str` or `List[str]` | `""` | The HTTP methods that the allowed origins can access, as set on the `access-control-allow-methods` header. | -| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | The origins that are allowed to access the resource, as set on the `access-control-allow-origin` header. | -| `CORS_SEND_WILDCARD` | `bool` | `False` | If `True`, will send the wildcard `*` origin instead of the `origin` request header. | -| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | Whether to set the `access-control-allow-credentials` header. | -| `CORS_VARY_HEADER` | `bool` | `True` | Whether to add `vary` header, when appropriate. | +| キー | タイプ | デフォルト | 説明 | +| -------------------------- | -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `CORS_ALLOW_HEADERS` | `str` または `List[str]` | `"*"` | `access-control-allow-headers` に表示されるヘッダーの一覧です。 | +| `CORS_ALWAYS_SEND` | `bool` | `True` | `True` の場合、 `access-control-allow-origin` の値は常に設定されます。 `False` の場合、`Origin` ヘッダーがある場合にのみ設定されます。 | +| `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | 入力されるプリフライトリクエストが受信されると、`access-control-allow-headers` 、 `access-control-max-age` 、 `access-control-allow-methods` ヘッダの値を自動的に設定するかどうか。 `False`の場合、これらの値は`@cors`デコレータで装飾されたルートにのみ設定されます。 | +| `CORS_EXPOSE_HEADERS` | `str` または `List[str]` | `""` | `access-control-expose-headers` ヘッダに設定されるヘッダの特定のリスト。 | +| `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | プリフライト応答の最大秒数は `access-control-max-age` ヘッダーを使用してキャッシュできます。 偽の値を指定すると、ヘッダーは設定されません。 | +| `CORS_METHODS` | `str` または `List[str]` | `""` | `access-control-allow-methods` ヘッダーに設定されているように、許可されたオリジンがアクセスできるHTTPメソッドです。 | +| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | `access-control-allow-origin` ヘッダーに設定されているように、リソースにアクセスできるオリジンです。 | +| `CORS_SEND_WILD` | `bool` | `False` | `True`の場合、`origin`リクエストヘッダの代わりにワイルドカード`*`オリジンを送信します。 | +| `CORS_SUPPORT_CREDENTIALS` | `bool` | `False` | `access-control-allow-credentials` ヘッダーを設定します。 | +| `CORS_VARY_HEADER` | `bool` | `True` | `vary`ヘッダを追加するかどうか。 | -_For the sake of brevity, where the above says `List[str]` any instance of a `list`, `set`, `frozenset`, or `tuple` will be acceptable. Alternatively, if the value is a `str`, it can be a comma delimited list._ +_上記の「リスト[str]」と書かれている簡潔さのために、`リスト`、`set`、`frozenset`、または`tuple`のいずれかのインスタンスは受け入れられます。 あるいは、値が `str` の場合、カンマ区切りのリストにすることもできます。_ -## Route level overrides +## ルートレベルの上書き -.. column:: +.. 列:: ``` -It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. +特定のルートのアプリ全体の設定を上書きする必要がある場合もあります。 これを可能にするには、 `@sanic_ext.cors()` デコレータを使用して、ルート固有の値を設定します。 -The values that can be overridden with this decorator are: +このデコレータで上書きできる値は次のとおりです。 - `origins` - `expose_headers` @@ -81,16 +81,16 @@ The values that can be overridden with this decorator are: - `max_age` ``` -.. column:: +.. 列:: ```` ```python from sanic_ext import cors -app.config.CORS_ORIGINS = "https://foo.com" +app.config.CORS_ORIGinS = "https://foo.com" @app.get("/", host="bar.com") -@cors(origins="https://bar.com") +@cors(origs="https://bar.com") async def hello_world(request): return text("Hello, world.") ``` From becb6c366f77bf863e5b1061286e21270f4ddf15 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:01 +0200 Subject: [PATCH 402/698] New translations cors.md (Chinese Simplified) --- .../content/zh/plugins/sanic-ext/http/cors.md | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/http/cors.md b/guide/content/zh/plugins/sanic-ext/http/cors.md index d5e4f2ba4e..51dabb91f6 100644 --- a/guide/content/zh/plugins/sanic-ext/http/cors.md +++ b/guide/content/zh/plugins/sanic-ext/http/cors.md @@ -1,26 +1,26 @@ --- -title: Sanic Extensions - CORS protection +title: Sanic Extensions - CORS 保护 --- -# CORS protection +# CORS 保护 -Cross-Origin Resource Sharing (aka CORS) is a _huge_ topic by itself. The documentation here cannot go into enough detail about _what_ it is. You are highly encouraged to do some research on your own to understand the security problem presented by it, and the theory behind the solutions. [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) are a great first step. +跨源资源共享（又称核心资源共享）本身就是一个_大量_的主题。 这里的文档无法详细了解_它是什么_。 我们非常鼓励你自己进行一些研究，以了解它所提出的安全问题以及解决办法背后的理论。 [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)是很好的第一步。 -In super brief terms, CORS protection is a framework that browsers use to facilitate how and when a web page can access information from another domain. It is extremely relevant to anyone building a single-page application. Often times your frontend might be on a domain like `https://portal.myapp.com`, but it needs to access the backend from `https://api.myapp.com`. +以超简短的措辞， CORS 保护是一个浏览器用来方便网页如何和何时可以从另一个域访问信息的框架。 这与任何人建立单页应用程序都是极其相关的。 您的前端常常可能位于一个域名上，例如`https://portal.myapp.com`，但它需要访问`https://api.myapp.com`的后端。 -The implementation here is heavily inspired by [`sanic-cors`](https://github.com/ashleysommer/sanic-cors), which is in turn based upon [`flask-cors`](https://github.com/corydolphin/flask-cors). It is therefore very likely that you can achieve a near drop-in replacement of `sanic-cors` with `sanic-ext`. +此处的执行受到[`sanic-cors`](https://github.com/ashleysommer/sanic-cors)的大力启发，而这又是基于[`flask-cors`](https://github.com/corydolphin/flask-cors)。 因此，你很可能会用`sanic-ext`来取代\`sanic-cors'。 -## Basic implementation +## 基本执行 -.. column:: +.. 列: ``` -As shown in the example in the [auto-endpoints example](methods.md#options), Sanic Extensions will automatically enable CORS protection without further action. But, it does not offer too much out of the box. +如[自动端点示例](方法)中的示例所示。 d#options), Sanic Extensions 会自动使CORS 保护无需采取进一步行动, 但它不会提供太多的箱子. -At a *bare minimum*, it is **highly** recommended that you set `config.CORS_ORIGINS` to the intended origin(s) that will be accessing the application. +在 *bare minimum * 上，**强烈** 建议您将 `config.CORS_ORIGINS` 设置为将访问应用程序的原始(s)。 ``` -.. column:: +.. 列: ```` ```python @@ -45,43 +45,43 @@ connection: keep-alive ``` ```` -## Configuration +## 配置 -The true power of CORS protection, however, comes into play once you start configuring it. Here is a table of all of the options. +然而，一旦你开始配置CORS 保护的真正功效。 这是所有选项的一个表。 -| Key | Type | Default | Description | -| --------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `CORS_ALLOW_HEADERS` | `str` or `List[str]` | `"*"` | The list of headers that will appear in `access-control-allow-headers`. | -| `CORS_ALWAYS_SEND` | `bool` | `True` | When `True`, will always set a value for `access-control-allow-origin`. When `False`, will only set it if there is an `Origin` header. | -| `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | When the incoming preflight request is received, whether to automatically set values for `access-control-allow-headers`, `access-control-max-age`, and `access-control-allow-methods` headers. If `False` these values will only be set on routes that are decorated with the `@cors` decorator. | -| `CORS_EXPOSE_HEADERS` | `str` or `List[str]` | `""` | Specific list of headers to be set in `access-control-expose-headers` header. | -| `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | The maximum number of seconds the preflight response may be cached using the `access-control-max-age` header. A falsey value will cause the header to not be set. | -| `CORS_METHODS` | `str` or `List[str]` | `""` | The HTTP methods that the allowed origins can access, as set on the `access-control-allow-methods` header. | -| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | The origins that are allowed to access the resource, as set on the `access-control-allow-origin` header. | -| `CORS_SEND_WILDCARD` | `bool` | `False` | If `True`, will send the wildcard `*` origin instead of the `origin` request header. | -| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | Whether to set the `access-control-allow-credentials` header. | -| `CORS_VARY_HEADER` | `bool` | `True` | Whether to add `vary` header, when appropriate. | +| 关键字 | 类型 | 默认设置 | 描述 | +| --------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `CORS_ALLOW_HEADERS` | `str` 或 `list[str]` | `"*"` | 显示在"访问控制-允许-headers"中的标题列表。 | +| `CORS_ALWAYS_SEND` | `bool` | `True` | 当`True`时，总是会设置`access-control-allow-origin`的值。 当`False`时，只有在存在`原始`标题时才会设置它。 | +| `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | 当收到传入的飞行前请求时，是否为`access-controll-allow-headers`、`access-control-max-age`和`access-control-allow-methods`设置自动设置值。 如果`False`，则这些值将只设在使用 `@cors` 装饰器装饰的路径上。 | +| `CORS_EXPOSE_HEADERS` | `str` 或 `list[str]` | `""` | 要在 `access-controll-expose-headers` 标题中设置的特殊标题列表。 | +| `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | 飞行前响应的最大秒数可以使用 'access-control-max-age' 头缓存。 falsey 值将导致页眉不被设置。 | +| `CORS_METHODS` | `str` 或 `list[str]` | `""` | 允许的源代码访问的 HTTP 方法，设置在 `access-control-allow-methods` 标题上。 | +| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | 允许访问资源的来源，如在 `access-control-allow-origin` 标题上设定。 | +| `CORS_SEND_WILDCARD` | `bool` | `False` | 如果`True`，将发送通配符`*`而不是\`orig'请求标题。 | +| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | 是否设置 `access-control-allow-credentials` 标题。 | +| `CORS_VARY_HEADER` | `bool` | `True` | 是否在适当时添加 `vary` 标题。 | -_For the sake of brevity, where the above says `List[str]` any instance of a `list`, `set`, `frozenset`, or `tuple` will be acceptable. Alternatively, if the value is a `str`, it can be a comma delimited list._ +_For the sake of brevity, where the above says `List[str]` any instance of a `list`, `set`, `frozenset`, or `tuple` will be acceptable. 或者，如果值是 `str`，它可以是逗号分隔的列表。_ -## Route level overrides +## 路由级别覆盖 -.. column:: +.. 列: ``` -It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. +有时可能需要覆盖特定路由的应用程序设置。 为了允许这一点，您可以使用 `@sanic_ext.cors()` 装饰符来设置不同的路径特定值。 -The values that can be overridden with this decorator are: +此装饰符可以覆盖的值是： - `origins` -- `expose_headers` +- `expose_headers' - `allow_headers` - `allow_methods` - `supports_credentials` - `max_age` ``` -.. column:: +.. 列: ```` ```python From c878651a4b350256b445b140de075164b22d92e2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:02 +0200 Subject: [PATCH 403/698] New translations methods.md (Japanese) --- .../ja/plugins/sanic-ext/http/methods.md | 58 +++++++++---------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/http/methods.md b/guide/content/ja/plugins/sanic-ext/http/methods.md index 34e841d723..2a0c72957c 100644 --- a/guide/content/ja/plugins/sanic-ext/http/methods.md +++ b/guide/content/ja/plugins/sanic-ext/http/methods.md @@ -1,18 +1,18 @@ --- -title: Sanic Extensions - HTTP Methods +title: サニックエクステンション - HTTPメソッド --- -# HTTP Methods +# HTTPメソッド -## Auto-endpoints +## 自動エンドポイント -The default behavior is to automatically generate `HEAD` endpoints for all `GET` routes, and `OPTIONS` endpoints for all -routes. Additionally, there is the option to automatically generate `TRACE` endpoints. However, these are not enabled by -default. +デフォルトの動作は、すべての `GET` ルートの `HEAD` エンドポイントと、すべての +ルートの `OPTIONS` エンドポイントを自動的に生成することです。 さらに、 `TRACE` エンドポイントを自動生成するオプションもあります。 ただし、これらは +デフォルトでは有効になっていません。 -### HEAD +### 頭 -.. column:: +.. 列:: ``` - **Configuration**: `AUTO_HEAD` (default `True`) @@ -22,7 +22,7 @@ A `HEAD` request provides the headers and an otherwise identical response to wha However, it does not actually return the body. ``` -.. column:: +.. 列:: ```` ```python @@ -43,9 +43,9 @@ content-type: text/plain; charset=utf-8 ``` ```` -### OPTIONS +### オプション -.. column:: +.. 列:: ``` - **Configuration**: `AUTO_OPTIONS` (default `True`) @@ -55,7 +55,7 @@ content-type: text/plain; charset=utf-8 endpoint. ``` -.. column:: +.. 列:: ```` ```python @@ -81,12 +81,12 @@ connection: keep-alive .. tip:: ``` -Even though Sanic Extensions will setup these routes for you automatically, if you decide to manually create an `@app.options` route, it will *not* be overridden. +Sanic Extensionsは自動的にこれらのルートを設定しますが、`@app.options`ルートを手動で作成する場合、上書きされることはありません。 ``` -### TRACE +### トレースする -.. column:: +.. 列:: ``` - **Configuration**: `AUTO_TRACE` (default `False`) @@ -96,7 +96,7 @@ By default, `TRACE` endpoints will **not** be automatically created. However, Sa create them if you wanted. This is something that is not allowed in vanilla Sanic. ``` -.. column:: +.. 列:: ```` ```python @@ -127,24 +127,24 @@ Accept: */* .. tip:: ``` -Setting up `AUTO_TRACE` can be super helpful, especially when your application is deployed behind a proxy since it will help you determine how the proxy is behaving. +`AUTO_TRACE` のセットアップはとても役に立ちます。 アプリケーションがプロキシの背後に展開されている場合は特にプロキシがどのように動作するかを判断するのに役立ちます ``` -## Additional method support +## 追加メソッドのサポート -Vanilla Sanic allows you to build endpoints with the following HTTP methods: +Vanilla Sanicは以下のHTTPメソッドでエンドポイントを構築できます。 -- [GET](/en/guide/basics/routing.html#get) -- [POST](/en/guide/basics/routing.html#post) -- [PUT](/en/guide/basics/routing.html#put) -- [HEAD](/en/guide/basics/routing.html#head) -- [OPTIONS](/en/guide/basics/routing.html#options) -- [PATCH](/en/guide/basics/routing.html#patch) -- [DELETE](/en/guide/basics/routing.html#delete) +- [GET](/ja/guide/basics/routing.html#get) +- [POST](/ja/guide/basics/routing.html#post) +- [PUT](/ja/guide/basics/routing.html#put) +- [HEAD](/ja/guide/basics/routing.html#head) +- [OPTIONS](/ja/guide/basics/routing.html#options) +- [PATCH](/ja/guide/basics/routing.html#patch) +- [DELETE](/ja/guide/basics/routing.html#delete) -See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more. +詳細は [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) を参照してください。 -.. column:: +.. 列:: ``` There are, however, two more "standard" HTTP methods: `TRACE` and `CONNECT`. Sanic Extensions will allow you to build @@ -154,7 +154,7 @@ It is worth pointing out that this will *NOT* enable convenience methods: `@app. use `@app.route` as shown in the example here. ``` -.. column:: +.. 列:: ```` ```python From be65be8daaf1ffc3f135f9cee0b8c97c8ea41e02 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:04 +0200 Subject: [PATCH 404/698] New translations methods.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/http/methods.md | 102 +++++++++--------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/http/methods.md b/guide/content/zh/plugins/sanic-ext/http/methods.md index 34e841d723..ab95d82701 100644 --- a/guide/content/zh/plugins/sanic-ext/http/methods.md +++ b/guide/content/zh/plugins/sanic-ext/http/methods.md @@ -1,61 +1,61 @@ --- -title: Sanic Extensions - HTTP Methods +title: Sanic 扩展 - HTTP 方法 --- -# HTTP Methods +# HTTP 方法 -## Auto-endpoints +## 自动终点 -The default behavior is to automatically generate `HEAD` endpoints for all `GET` routes, and `OPTIONS` endpoints for all -routes. Additionally, there is the option to automatically generate `TRACE` endpoints. However, these are not enabled by -default. +默认行为是自动生成所有的 `GET` 路径的 `HEAD` 端点，以及所有 +路径的 `OPTIONS` 端点。 此外，还有自动生成 `TRACE` 端点的选项。 然而， +默认情况下没有启用这些功能。 -### HEAD +### 黑色 -.. column:: +.. 列: ``` -- **Configuration**: `AUTO_HEAD` (default `True`) -- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) +- **配置**: `AUTO_HEAD` (默认 `True`) +- **MDN**: [阅读更多](https://developer.mozilla). rg/en-US/docs/Web/HTTPMethods/HEAD -A `HEAD` request provides the headers and an otherwise identical response to what a `GET` request would provide. -However, it does not actually return the body. +A `HEAD` 请求提供了标题和对一个 `GET` 请求提供的相同的响应。 +然而，实际上并没有归还尸体。 ``` -.. column:: +.. 列: ```` ```python @app.get("/") async def hello_world(request): - return text("Hello, world.") -``` + return text("Hello, world" +`` -Given the above route definition, Sanic Extensions will enable `HEAD` responses, as seen here. +鉴于上述路由定义，Sanic Extensions 将能使`HEAD` 反应，如上所示。 ``` $ curl localhost:8000 --head -HTTP/1.1 200 OK -access-control-allow-origin: * +HTTP/1。 200 OK +access-allow-origin: * content-length: 13 connection: keep-alive content-type: text/plain; charset=utf-8 ``` ```` -### OPTIONS +### 选项 -.. column:: +.. 列: ``` -- **Configuration**: `AUTO_OPTIONS` (default `True`) -- **MDN**: [Read more](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) +- **配置**: `AUTO_OPTIONS` (默认 `True`) +- **MDN**: [阅读更多] (https://developer.mozilla). rg/en-US/docs/Web/HTTP/Methods/OPTIONS -`OPTIONS` requests provide the recipient with details about how the client is allowed to communicate with a given -endpoint. +"OPTIONS" 请求向收件人详细介绍了如何允许客户端与指定 +端口进行通信。 ``` -.. column:: +.. 列: ```` ```python @@ -81,12 +81,12 @@ connection: keep-alive .. tip:: ``` -Even though Sanic Extensions will setup these routes for you automatically, if you decide to manually create an `@app.options` route, it will *not* be overridden. +即使Sanic 扩展会自动为您设置这些路径，如果您决定手动创建一个 `@app.options` 路径，它将*不*被覆盖。 ``` -### TRACE +### 追踪器 -.. column:: +.. 列: ``` - **Configuration**: `AUTO_TRACE` (default `False`) @@ -96,69 +96,69 @@ By default, `TRACE` endpoints will **not** be automatically created. However, Sa create them if you wanted. This is something that is not allowed in vanilla Sanic. ``` -.. column:: +.. 列: ```` ```python -@app.route("/", methods=["trace"]) -async def handler(request): - ... +@app.route("/", methods=["追踪"]) +async def 处理器(请求): + ``` -To enable auto-creation of these endpoints, you must first enable them when extending Sanic. +要启用这些端点的自动创建，您必须先启用它们才能扩展 Sanic。 ```python from sanic_ext import Extend, Config -app.extend(config=Config(http_auto_trace=True)) +app. xtend(config=Config(http_auto_trace=True)) ``` -Now, assuming you have some endpoints setup, you can trace them as shown here: +现在，假定您有一些端点设置， 你可以在这里追踪它们： ``` $ curl localhost:8000 -X TRACE -TRACE / HTTP/1.1 -Host: localhost:9999 -User-Agent: curl/7.76.1 -Accept: */* +TRACE / HTTP/1。 +主机：localhost:9999 +User-Agent：curl/7.76.1 +接受：*/* ``` ```` .. tip:: ``` -Setting up `AUTO_TRACE` can be super helpful, especially when your application is deployed behind a proxy since it will help you determine how the proxy is behaving. +设置 `AUTO_TRACE` 可以提供超级帮助， 尤其是当您的应用程序被部署在代理后面，因为它将帮助您确定代理人的行为方式。 ``` -## Additional method support +## 额外方法支持 -Vanilla Sanic allows you to build endpoints with the following HTTP methods: +Vanilla Sanic允许您使用 HTTP 方法构建终点： - [GET](/en/guide/basics/routing.html#get) - [POST](/en/guide/basics/routing.html#post) - [PUT](/en/guide/basics/routing.html#put) - [HEAD](/en/guide/basics/routing.html#head) -- [OPTIONS](/en/guide/basics/routing.html#options) +- [OPTIONS](/en/guide/basics/routing.html#选项) - [PATCH](/en/guide/basics/routing.html#patch) - [DELETE](/en/guide/basics/routing.html#delete) -See [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more. +详见[MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) -.. column:: +.. 列: ``` -There are, however, two more "standard" HTTP methods: `TRACE` and `CONNECT`. Sanic Extensions will allow you to build -endpoints using these methods, which would otherwise not be allowed. +然而，还有两种"标准"HTTP方法：`TRACE`和`CONNECT`。 Sanic 扩展将允许您使用这些方法构建 +端点，否则这些方法是不允许的。 -It is worth pointing out that this will *NOT* enable convenience methods: `@app.trace` or `@app.connect`. You need to -use `@app.route` as shown in the example here. +值得指出的是，这将*无* 启用方便方法：`@app。 竞技`或`@app.connect`。您需要 +使用示例`@app.route`。 ``` -.. column:: +.. 列: ```` ```python -@app.route("/", methods=["trace", "connect"]) +@app.route("/", methods=["追踪", "connect"]) async def handler(_): return empty() ``` From f5b50851f3dfa97bf15cd7dcfe167b673bf682c3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:05 +0200 Subject: [PATCH 405/698] New translations injection.md (Japanese) --- .../content/ja/plugins/sanic-ext/injection.md | 134 +++++++++--------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/injection.md b/guide/content/ja/plugins/sanic-ext/injection.md index 7e9711d749..6387f575fb 100644 --- a/guide/content/ja/plugins/sanic-ext/injection.md +++ b/guide/content/ja/plugins/sanic-ext/injection.md @@ -1,47 +1,47 @@ --- -title: Sanic Extensions - Dependency Injection +title: Sanic Extensions - 依存性インジェクション --- -# Dependency Injection +# 依存性インジェクション -Dependency injection is a method to add arguments to a route handler based upon the defined function signature. Specifically, it looks at the **type annotations** of the arguments in the handler. This can be useful in a number of cases like: +依存性インジェクションは、定義された関数署名に基づいてルートハンドラに引数を追加するメソッドです。 具体的には、ハンドラの引数の**型注釈**を見てみます。 これは以下のような場合に便利です。 -- Fetching an object based upon request headers (like the current session user) -- Recasting certain objects into a specific type -- Using the request object to prefetch data -- Auto inject services +- (現在のセッションユーザのような) リクエストヘッダに基づいてオブジェクトを取得しています +- 特定のオブジェクトを特定の型に再作成する +- リクエストオブジェクトを使用してデータを先読みする +- 自動注入サービス -The `Extend` instance has two basic methods on it used for dependency injection: a lower level `add_dependency`, and a higher level `dependency`. +`Extend` インスタンスには、依存注入に使用される2つの基本的なメソッドがあります。下位レベルの `add_dependency` と上位レベルの `dependency` です。 -**Lower level**: `app.ext.add_dependency(...)` +**低レベル**: `app.ext.add_dependency(...)` -- `type: Type,`: some unique class that will be the type of the object -- `constructor: Optional[Callable[..., Any]],` (OPTIONAL): a function that will return that type +- `type: Type,`: オブジェクトの型になるいくつかの一意のクラス。 +- `constructor: Optional[Callable[..., Any]],` (OPTIONAL): その型を返す関数。 -**Higher level**: `app.ext.dependency(...)` +**より高いレベル**: `app.ext.dependency(...)` -- `obj: Any`: any object that you would like injected -- `name: Optional[str]`: some name that could alternately be used as a reference +- `obj: Any`: 注入したいすべてのオブジェクト +- `name: Optional[str]`: 参照として交互に使用できるいくつかの名前 -Let's explore some use cases here. +ここでいくつかのユースケースを見てみましょう。 -.. warning:: +.. 警告:: ``` -If you used dependency injection prior to v21.12, the lower level API method was called `injection`. It has since been renamed to `add_dependency` and starting in v21.12 `injection` is an alias for `add_dependency`. The `injection` method has been deprecated for removal in v22.6. +v21.12 より前に依存性インジェクションを使用した場合、下位レベルの API メソッドは `injection` と呼ばれました。 それ以降、`add_dependency`に名前が変更され、v21で始まります。 2 `injection`は`add_dependency`のエイリアスです。`injection`メソッドはv22.6の削除のために非推奨となりました。 ``` -## Basic implementation +## 基本的な実装 -The simplest use case would be simply to recast a value. +最も単純なユースケースは、単に値を再キャストすることです。 -.. column:: +.. 列:: ``` -This could be useful if you have a model that you want to generate based upon the matched path parameters. +これは、マッチしたパスパラメータに基づいて生成するモデルがある場合に便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -65,13 +65,13 @@ You chose Chocolate (Yum!) ``` ```` -.. column:: +.. 列:: ``` -This works by passing a keyword argument to the constructor of the `type` argument. The previous example is equivalent to this. +これは、`type`引数のコンストラクタにキーワード引数を渡すことで動作します。前の例はこれと同じです。 ``` -.. column:: +.. 列:: ```` ```python @@ -79,17 +79,17 @@ flavor = IceCream(flavor="chocolate") ``` ```` -## Additional constructors +## 追加のコンストラクター -.. column:: +.. 列:: ``` -Sometimes you may need to also pass a constructor. This could be a function, or perhaps even a classmethod that acts as a constructor. In this example, we are creating an injection that will call `Person.create` first. +コンストラクタを渡す必要がある場合もあります。これは関数や、コンストラクタとして動作するclassメソッドであってもよいでしょう。 この例では、`Person を呼び出す注入を作成しています。 最初に「やり直す」。 -Also important to note on this example, we are actually injecting **two (2)** objects! It of course does not need to be this way, but we will inject objects based upon the function signature. +この例でも重要なことは、実際に **two (2)** オブジェクトを注入していることです! もちろん、このようにする必要はありませんが、関数署名に基づいてオブジェクトを注入します。 ``` -.. column:: +.. 列:: ```` ```python @@ -125,23 +125,23 @@ Person(person_id=PersonID(person_id=123), name='noname', age=111) ``` ```` -When a `constructor` is passed to `ext.add_dependency` (like in this example) that will be called. If not, then the object will be created by calling the `type`. A couple of important things to note about passing a `constructor`: +`constructor` が ext.add_dependency`(この例のように) に渡されたときに呼び出されます。 そうでない場合は、`type`を呼び出してオブジェクトを作成します。`constructor\`を渡すことについて、いくつかの重要なことに注意してください。 -1. A positional `request: Request` argument is _usually_ expected. See the `Person.create` method above as an example using a `request` and [arbitrary constructors](#arbitrary-constructors) for how to use a callable that does not require a `request`. -2. All matched path parameters are injected as keyword arguments. -3. Dependencies can be chained and nested. Notice how in the previous example the `Person` dataclass has a `PersonID`? That means that `PersonID` will be called first, and that value is added to the keyword arguments when calling `Person.create`. +1. 位置`request: Request`引数は通常、期待されています。 `Person を見なさい。 上記の reate` メソッドは、`request` と format@@0(#arbitrary-constructors) を使用して、`request` を必要としない呼び出し元を使用する方法を例としています。 +2. マッチしたパスパラメータはすべてキーワード引数として注入されます。 +3. 依存関係はチェーンとネストが可能です。 前の例では、 `Person` dataclass が `PersonID` になっていることに注意してください。 つまり、 `PersonID` が最初に呼び出され、 `Person.create` を呼び出すときにその値がキーワード引数に追加されます。 -## Arbitrary constructors +## 任意のコンストラクター -.. column:: +.. 列:: ``` -Sometimes you may want to construct your injectable _without_ the `Request` object. This is useful if you have arbitrary classes or functions that create your objects. If the callable does have any required arguments, then they should themselves be injectable objects. +時々、注入可能な _without_ を `Request` オブジェクトにしたいと思うかもしれません。 これは、オブジェクトを作成する任意のクラスや関数がある場合に便利です。 callable が必要な引数を持っている場合は、それ自体が注入可能なオブジェクトである必要があります。 -This is very useful if you have services or other types of objects that should only exist for the lifetime of a single request. For example, you might use this pattern to pull a single connection from your database pool. +これは、単一のリクエストの寿命のためにのみ存在すべきサービスやその他のタイプのオブジェクトがある場合に非常に便利です。 たとえば、このパターンを使用して、データベース プールから単一の接続をプルすることができます。 ``` -.. column:: +.. 列:: ```` ```python @@ -161,11 +161,11 @@ async def handler(request: Request, beta: Beta): ``` ```` -_Added in v22.9_ +_v22.9_に追加されました -## Objects from the `Request` +## `Request`からのオブジェクト -.. column:: +.. 列:: ```` Sometimes you may want to extract details from the request and preprocess them. You could, for example, cast the request JSON to a Python object, and then add some additional logic based upon DB queries. @@ -187,7 +187,7 @@ Sometimes you may want to extract details from the request and preprocess them. In this example, we are using the `Request` object in the `compile_profile` constructor to run a fake DB query to generate and return a `UserProfile` object. ```` -.. column:: +.. 列:: ```` ```python @@ -243,19 +243,19 @@ $ curl localhost:8000/profile -X PATCH -d '{"name": "Alice", "birthday": "2000-0 ``` ```` -## Injecting services +## 注入サービス -It is a common pattern to create things like database connection pools and store them on the `app.ctx` object. This makes them available throughout your application, which is certainly a convenience. One downside, however, is that you no longer have a typed object to work with. You can use dependency injections to fix this. First we will show the concept using the lower level `add_dependency` like we have been using in the previous examples. But, there is a better way using the higher level `dependency` method. +データベース接続プールのようなものを作成し、 `app.ctx` オブジェクトに保存するのは一般的なパターンです。 これにより、アプリケーション全体で利用可能になります。これは確かに便利です。 しかし欠点の一つは、もはや一緒に作業する型付けされたオブジェクトを持っていないことです。 依存性注入を使用してこれを修正できます。 最初に、先ほどの例で使ったように、下位レベルの `add_dependency` を使ってコンセプトを示します。 しかし、より高いレベルの `dependency` メソッドを使うより良い方法があります。 -### The lower level API using `add_dependency` +### `add_dependency`を使用する下位レベルのAPI。 -.. column:: +.. 列:: ``` -This works very similar to the [last example](#objects-from-the-request) where the goal is the extract something from the `Request` object. In this example, a database object was created on the `app.ctx` instance, and is being returned in the dependency injection constructor. +これは format@@0(#objects-from-the-request) に非常によく似ています。目的は `Request` オブジェクトから何かを抽出することです。 この例では、データベースオブジェクトが `app.ctx` インスタンス上に作成され、依存性インジェクションコンストラクタで返されます。 ``` -.. column:: +.. 列:: ```` ```python @@ -284,17 +284,17 @@ result ``` ```` -### The higher level API using `dependency` +### `dependency`を使用するより高いレベルのAPI。 -.. column:: +.. 列:: ``` -Since we have an actual *object* that is available when adding the dependency injection, we can use the higher level `dependency` method. This will make the pattern much easier to write. +依存性注入を追加するときに利用できる実際の *object* があるので、より高いレベルの `dependency` メソッドを使用できます。 これにより、パターンが書けるようになります。 -This method should always be used when you want to inject something that exists throughout the lifetime of the application instance and is not request specific. It is very useful for services, third party clients, and connection pools since they are not request specific. +アプリケーションインスタンスの寿命を通じて存在し、特定の要求ではない何かを注入する場合は、このメソッドを常に使用する必要があります。 特定の要求ではないため、サービス、サードパーティクライアント、および接続プールに非常に便利です。 ``` -.. column:: +.. 列:: ```` ```python @@ -318,17 +318,17 @@ result ``` ```` -## Generic types +## 一般的なタイプ -Be carefule when using a [generic type](https://docs.python.org/3/library/typing.html#typing.Generic). The way that Sanic's dependency injection works is by matching the entire type definition. Therefore, `Foo` is not the same as `Foo[str]`. This can be particularly tricky when trying to use the [higher-level `dependency` method](#the-higher-level-api-using-dependency) since the type is inferred. +format@@0(https\://docs.python.org/3/library/typing.html#typing.Generic)を使用するときは、気をつけてください。 Sanicの依存性注入が機能する方法は、型の定義全体に一致することです。 したがって、`Foo` は `Foo[str] ` と同じではありません。 型が推測されるので、format@@0(#the-higher-level-api-using-dependency) を使用しようとすると、これは特に難しいことがあります。 -.. column:: +.. 列:: ``` -For example, this will **NOT** work as expected since there is no definition for `Test[str]`. +例えば、`Test[str] `の定義がないため、これは **期待通りに動作しません** 。 ``` -.. column:: +.. 列:: ```` ```python @@ -349,13 +349,13 @@ def test(request, test: Test[str]): ``` ```` -.. column:: +.. 列:: ``` -To get this example to work, you will need to add an explicit definition for the type you intend to be injected. +この例を動作させるには、注入するタイプの明示的な定義を追加する必要があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -377,15 +377,15 @@ def test(request, test: Test[str]): ``` ```` -## Configuration +## 設定 -.. column:: +.. 列:: ``` -By default, dependencies will be injected after the `http.routing.after` [signal](../../guide/advanced/signals.md#built-in-signals). Starting in v22.9, you can change this to the `http.handler.before` signal. +デフォルトでは、依存関係は `http.routing.after` [signal](../../guide/advanced/signals.md#built-in-signals) の後に注入されます。v22.9 以降は、`http.handler.before` 信号に変更できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -393,4 +393,4 @@ app.config.INJECTION_SIGNAL = "http.handler.before" ``` ```` -_Added in v22.9_ +_v22.9_に追加されました From ba0412bdd8e544073402e388318986ebdc16baea Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:07 +0200 Subject: [PATCH 406/698] New translations injection.md (Chinese Simplified) --- .../content/zh/plugins/sanic-ext/injection.md | 166 +++++++++--------- 1 file changed, 83 insertions(+), 83 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/injection.md b/guide/content/zh/plugins/sanic-ext/injection.md index 7e9711d749..53e6dfc45b 100644 --- a/guide/content/zh/plugins/sanic-ext/injection.md +++ b/guide/content/zh/plugins/sanic-ext/injection.md @@ -1,47 +1,47 @@ --- -title: Sanic Extensions - Dependency Injection +title: 神经扩展 - 依赖注入量 --- -# Dependency Injection +# 依赖注入次数 -Dependency injection is a method to add arguments to a route handler based upon the defined function signature. Specifically, it looks at the **type annotations** of the arguments in the handler. This can be useful in a number of cases like: +依赖注入是基于定义函数签名向路由处理程序添加参数的方法。 具体而言，它看了处理器中参数的 **类型注释** 。 这在一些情况下可能是有用的，例如： -- Fetching an object based upon request headers (like the current session user) -- Recasting certain objects into a specific type -- Using the request object to prefetch data -- Auto inject services +- 正在获取基于请求头的对象 (像当前会话用户) +- 将某些对象重置为特定类型 +- 使用请求对象预获取数据 +- 自动注入服务 -The `Extend` instance has two basic methods on it used for dependency injection: a lower level `add_dependency`, and a higher level `dependency`. +`Extend`实例有两种基本方法用于依赖注入：较低级别的 `add_dependency`和较高级别的 `dependency`。 -**Lower level**: `app.ext.add_dependency(...)` +**较低级别**: `app.ext.add_dependency(...)` -- `type: Type,`: some unique class that will be the type of the object -- `constructor: Optional[Callable[..., Any]],` (OPTIONAL): a function that will return that type +- `type,`: 某些独特的类将是对象的类型 +- `constructor: Optional[Callable[..., Any],` (OPTIONAL): 一个返回这种类型的函数 -**Higher level**: `app.ext.dependency(...)` +**更高级别**: `app.ext.dependency(...)` -- `obj: Any`: any object that you would like injected -- `name: Optional[str]`: some name that could alternately be used as a reference +- `obj: Any`: 任何你想要注入的对象 +- `name: 可选的[str]`: 可以交替用作参考的一些名称 -Let's explore some use cases here. +让我们在这里探索一些案例。 -.. warning:: +.. 警告：: ``` -If you used dependency injection prior to v21.12, the lower level API method was called `injection`. It has since been renamed to `add_dependency` and starting in v21.12 `injection` is an alias for `add_dependency`. The `injection` method has been deprecated for removal in v22.6. +如果您在 v21.12之前使用依赖注入，较低级别的 API 方法被称为“注入”。 其后更名为`add_dependency`，并从v21开始。 2 `injection` 是一个 `add_dependency` 的别名。`injection` 方法已经不推荐在 v22.6 中移除。 ``` -## Basic implementation +## 基本执行 -The simplest use case would be simply to recast a value. +最简单的情况是只是重定一个数值。 -.. column:: +.. 列: ``` -This could be useful if you have a model that you want to generate based upon the matched path parameters. +如果你有一个模型，你想要根据匹配的路径参数生成，这可能是有用的。 ``` -.. column:: +.. 列: ```` ```python @@ -65,31 +65,31 @@ You chose Chocolate (Yum!) ``` ```` -.. column:: +.. 列: ``` -This works by passing a keyword argument to the constructor of the `type` argument. The previous example is equivalent to this. +将关键字参数传递给`type`参数的构造函数。前一个例子就是这个例子。 ``` -.. column:: +.. 列: ```` ```python -flavor = IceCream(flavor="chocolate") +flavor = IceCream(flavor="巧克力") ``` ```` -## Additional constructors +## 附加构造器 -.. column:: +.. 列: ``` -Sometimes you may need to also pass a constructor. This could be a function, or perhaps even a classmethod that acts as a constructor. In this example, we are creating an injection that will call `Person.create` first. +有时你可能也需要传递构造函数。这可能是一个函数，甚至可能是一个作为构造函数的类方法。 在这个例子中，我们正在创建一种叫做“人”的注射。 先得到`。 -Also important to note on this example, we are actually injecting **two (2)** objects! It of course does not need to be this way, but we will inject objects based upon the function signature. +同样重要的是注意到这个示例。我们实际上正在注入**两个(2)** 对象！ 当然不需要这样做，但我们将根据函数签名注入物体。 ``` -.. column:: +.. 列: ```` ```python @@ -125,23 +125,23 @@ Person(person_id=PersonID(person_id=123), name='noname', age=111) ``` ```` -When a `constructor` is passed to `ext.add_dependency` (like in this example) that will be called. If not, then the object will be created by calling the `type`. A couple of important things to note about passing a `constructor`: +当一个 `constructor` 传递到 `ext.add_dependency` (就像在这个例子中那样)时，它将被调用。 如果没有，则将通过调用 `type` 来创建对象。 有几件重要的事情要注意到一个\`构造器'： -1. A positional `request: Request` argument is _usually_ expected. See the `Person.create` method above as an example using a `request` and [arbitrary constructors](#arbitrary-constructors) for how to use a callable that does not require a `request`. -2. All matched path parameters are injected as keyword arguments. -3. Dependencies can be chained and nested. Notice how in the previous example the `Person` dataclass has a `PersonID`? That means that `PersonID` will be called first, and that value is added to the keyword arguments when calling `Person.create`. +1. 一个位置的 `request: Request' 参数是 *通常的*。 请参阅“人员”。 获取上面的方法作为示例使用 `request`和 [arbitrary-constructors](#arbitry-constructors) 来使用不需要`request\` 的电报。 +2. 所有匹配的路径参数都作为关键字参数注入。 +3. 依赖关系可以被链和嵌套。 请注意在前一个示例中，`Person` 数据集如何有一个 `PersonID` ？ 这意味着`PersonID`将首先被调用，并且在调用 `Person.create` 时将该值添加到关键字参数中。 -## Arbitrary constructors +## 任意构造器 -.. column:: +.. 列: ``` -Sometimes you may want to construct your injectable _without_ the `Request` object. This is useful if you have arbitrary classes or functions that create your objects. If the callable does have any required arguments, then they should themselves be injectable objects. +有时您可能想要构建您注入的 _with_the `Request` 对象。 如果您有任意的类或函数创建您的对象，这是有用的。 如果传唤书中确实有任何必要的参数，那么传唤书本身应当是可以注射的物体。 -This is very useful if you have services or other types of objects that should only exist for the lifetime of a single request. For example, you might use this pattern to pull a single connection from your database pool. +如果您有服务或其他类型的对象只能在单个请求的一生中存在，这是非常有用的。 例如，您可以使用此模式从数据库池中拉取单个连接。 ``` -.. column:: +.. 列: ```` ```python @@ -161,33 +161,33 @@ async def handler(request: Request, beta: Beta): ``` ```` -_Added in v22.9_ +_添加于 v22.9_ -## Objects from the `Request` +## 来自 `Request` 的对象 -.. column:: +.. 列: ```` -Sometimes you may want to extract details from the request and preprocess them. You could, for example, cast the request JSON to a Python object, and then add some additional logic based upon DB queries. +有时您可能想要从请求中提取详细信息并预先处理。 例如，您可以将 JSON 投射到一个 Python 对象，然后添加一些基于数据库查询的附加逻辑。 -.. warning:: +... 警告：: - If you plan to use this method, you should note that the injection actually happens *before* Sanic has had a chance to read the request body. The headers should already have been consumed. So, if you do want access to the body, you will need to manually consume as seen in this example. + 如果您计划使用此方法，， 您应该注意到注射实际上发生在*先于*圣诞老人有机会阅读请求身体之前。 头应该已经消耗。 所以，如果你想要访问身体，你需要手动消耗在这个例子中看到。 - ```python - await request.receive_body() + ``python + 正在等待请求。 eceive_body() ``` - This could be used in cases where you otherwise might: + 这可以用于否则你可能: - - use middleware to preprocess and add something to the `request.ctx` - - use decorators to preprocess and inject arguments into the request handler + - 使用中间件预处理并添加某些内容到 "请求"。 tx` + - 使用装饰器预处理并注入参数到请求处理程序 - In this example, we are using the `Request` object in the `compile_profile` constructor to run a fake DB query to generate and return a `UserProfile` object. + 在此示例 我们正在使用 `compile_profile` 构造函数中的 `Request` 对象来运行一个假DB 查询来生成并返回一个 `UserProfile` 对象。 ```` -.. column:: +.. 列: ```` ```python @@ -243,19 +243,19 @@ $ curl localhost:8000/profile -X PATCH -d '{"name": "Alice", "birthday": "2000-0 ``` ```` -## Injecting services +## 注射服务 -It is a common pattern to create things like database connection pools and store them on the `app.ctx` object. This makes them available throughout your application, which is certainly a convenience. One downside, however, is that you no longer have a typed object to work with. You can use dependency injections to fix this. First we will show the concept using the lower level `add_dependency` like we have been using in the previous examples. But, there is a better way using the higher level `dependency` method. +创建数据库连接池并将其存储在`app.ctx`对象上是常见的模式。 这将使它们能够在您的整个应用程序中使用，这肯定是一种方便。 然而，一个缺点是你不再有一个要处理的打字对象。 您可以使用依赖注入来解决这个问题。 首先，我们将使用下级`add_dependency`来显示这个概念，就像我们在前面的例子中所使用的那样。 但是，可以更好地使用更高级别的 \`依赖' 方法。 -### The lower level API using `add_dependency` +### 使用 `add_dependency` 的较低级别 API -.. column:: +.. 列: ``` -This works very similar to the [last example](#objects-from-the-request) where the goal is the extract something from the `Request` object. In this example, a database object was created on the `app.ctx` instance, and is being returned in the dependency injection constructor. +这个操作非常类似于[最后一个例子](#objects-frow-the-request) 的目标是从 `Request` 对象中提取某些东西。 在这个示例中，在 `app.ctx` 实例上创建了一个数据库对象，正在返回依赖注入构造器。 ``` -.. column:: +.. 列: ```` ```python @@ -284,17 +284,17 @@ result ``` ```` -### The higher level API using `dependency` +### 较高级别的 API 使用 `dependency` -.. column:: +.. 列: ``` -Since we have an actual *object* that is available when adding the dependency injection, we can use the higher level `dependency` method. This will make the pattern much easier to write. +由于我们在添加依赖注入时有一个可用的实际的 *对象*，我们可以使用更高级别的 "依赖" 方法。 这将使写入模式变得更容易。 -This method should always be used when you want to inject something that exists throughout the lifetime of the application instance and is not request specific. It is very useful for services, third party clients, and connection pools since they are not request specific. +当您想要注入在应用程序实例整个生命周期中存在而不是请求具体的东西时，这个方法应该始终使用。 它对服务、第三方客户和连接池非常有用，因为它们没有具体要求。 ``` -.. column:: +.. 列: ```` ```python @@ -318,17 +318,17 @@ result ``` ```` -## Generic types +## 通用类型 -Be carefule when using a [generic type](https://docs.python.org/3/library/typing.html#typing.Generic). The way that Sanic's dependency injection works is by matching the entire type definition. Therefore, `Foo` is not the same as `Foo[str]`. This can be particularly tricky when trying to use the [higher-level `dependency` method](#the-higher-level-api-using-dependency) since the type is inferred. +使用[通用类型](https://docs.python.org/3/library/typing.html#typing.Generic)时小心谨慎。 Sanic依赖注入的方式是匹配整个类型的定义。 因此，`Foo`与`Foo[str] `不同。 当尝试使用 [更高级别的 '依赖' 方法](#the-high-level-api-using-dependency)时，这可能特别棘手，因为这种类型被推断。 -.. column:: +.. 列: ``` -For example, this will **NOT** work as expected since there is no definition for `Test[str]`. +例如，由于没有`测试[str] `的定义，**不** 会正常工作。 ``` -.. column:: +.. 列: ```` ```python @@ -349,48 +349,48 @@ def test(request, test: Test[str]): ``` ```` -.. column:: +.. 列: ``` -To get this example to work, you will need to add an explicit definition for the type you intend to be injected. +要使这个示例发挥作用，您需要为您打算注入的类型添加一个明确的定义。 ``` -.. column:: +.. 列: ```` ```python -import typing +import from sanic import Sanic, text T = typing.TypeVar("T") -class Test(typing.Generic[T]): +class Test(键入)。 enric[T]: test: T -app = Sanic("testapp") -_singleton = Test() -app.ext.add_dependency(Test[str], lambda: _singleton) +app = Sanic("taspp") +_sinleton = Test() +app. xt.add_dependency(Test[str], lambda: _sinleton) @app.get("/") -def test(request, test: Test[str]): +def 测试 (请求, test: 测试[str]): ... ``` ```` -## Configuration +## 配置 -.. column:: +.. 列: ``` By default, dependencies will be injected after the `http.routing.after` [signal](../../guide/advanced/signals.md#built-in-signals). Starting in v22.9, you can change this to the `http.handler.before` signal. ``` -.. column:: +.. 列: ```` ```python -app.config.INJECTION_SIGNAL = "http.handler.before" +app.config.INJECTION_SIGAL = "http.handler.before" ``` ```` -_Added in v22.9_ +_添加于 v22.9_ From 942c2449e7bd3ca9f53c3779af9cc57ed4d42ebe Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:08 +0200 Subject: [PATCH 407/698] New translations logger.md (Japanese) --- guide/content/ja/plugins/sanic-ext/logger.md | 32 ++++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/logger.md b/guide/content/ja/plugins/sanic-ext/logger.md index 0ea5f309b8..4294fd6f38 100644 --- a/guide/content/ja/plugins/sanic-ext/logger.md +++ b/guide/content/ja/plugins/sanic-ext/logger.md @@ -1,24 +1,24 @@ --- -title: Sanic Extensions - Background logger +title: Sanic Extensions - バックグラウンドロガー --- -# Background logger +# バックグラウンドログ -The background logger requires both `sanic>=22.9` and `sanic-ext>=22.9`. +バックグラウンドロガーには `sanic>=22.9` と `sanic-ext>=22.9` が必要です。 -You can setup Sanic Extensions to log all of your messages from a background process. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). +Sanic Extensionsを設定すると、バックグラウンドプロセスからすべてのメッセージをログに記録できます。 format@@0(../../guide/deployment/manager.md#single-process-mode) ではないことが必要です。 -Logging can sometimes be an expensive operation. By pushing all logging off to a background process, you can potentially gain some performance benefits. +ロギングは高価な操作になることがあります。 すべてのログをバックグラウンドプロセスにプッシュすることで、パフォーマンスのメリットが得られる可能性があります。 -## Setup +## セットアップ -.. column:: +.. 列:: ``` -Out of the box, the background logger is disabled. You will need to opt-in if you would like to use it. +バックグラウンドロガーが無効になっています。使用する場合はオプトインする必要があります。 ``` -.. column:: +.. 列:: ```` ```python @@ -26,13 +26,13 @@ app.config.LOGGING = True ``` ```` -## How does it work +## どのように機能します -When enabled, the extension will create a `multoprocessing.Queue`. It will remove all handlers on the [default Sanic loggers](../../guide/best-practices/logging.md) and replace them with a [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler). When a message is logged, it will be pushed into the queue by the handler, and read by the background process to the log handlers that were originally in place. This means you can still configure logging as normal and it should "just work." +有効にすると、拡張機能は `multoprocessing.Queue` を作成します。 format@@0(../../guide/best-practices/logging.md) 上のすべてのハンドラを削除し、[`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler) に置き換えます。 メッセージがログされると、ハンドラによってキューにプッシュされます。 バックグラウンドプロセスで元々あったログハンドラを読み取ることができます つまり、通常どおりにロギングを設定することができ、「ただ動作する」ことができます。 -## Configuration +## 設定 -| Key | Type | Default | Description | -| ------------------------------------------------------------------------------------- | ------ | ------- | ------------------------------------------------------- | -| LOGGING | `bool` | `False` | Whether to enable this extension. | -| LOGGING_QUEUE_MAX_SIZE | `int` | `4096` | The max size of the queue before messages are rejected. | +| キー | タイプ | デフォルト | 説明 | +| ------------------------------------------------------------- | ------ | ------- | ----------------------- | +| ログイン | `bool` | `False` | この拡張機能を有効にするかどうか。 | +| LOGGING_QUEUE_最大サイズ | `int` | `4096` | メッセージが拒否される前のキューの最大サイズ。 | From dbebf43309d5153db1142e84910e9f26e05d4cb4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:10 +0200 Subject: [PATCH 408/698] New translations logger.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/logger.md | 34 ++++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/logger.md b/guide/content/zh/plugins/sanic-ext/logger.md index 0ea5f309b8..55bd921d4f 100644 --- a/guide/content/zh/plugins/sanic-ext/logger.md +++ b/guide/content/zh/plugins/sanic-ext/logger.md @@ -1,38 +1,38 @@ --- -title: Sanic Extensions - Background logger +title: Sanic 扩展-背景记录器 --- -# Background logger +# 背景记录器 -The background logger requires both `sanic>=22.9` and `sanic-ext>=22.9`. +背景记录器需要 `sanic>=22.9` 和 `sanic-ext>=22.9`。 -You can setup Sanic Extensions to log all of your messages from a background process. This requires that you not be in [single process mode](../../guide/deployment/manager.md#single-process-mode). +您可以设置 Sanic 扩展来从后台进程中记录您所有的消息。 这要求您不要处于[单一进程模式](../../guide/deplement/manager.md#单一进程模式)。 -Logging can sometimes be an expensive operation. By pushing all logging off to a background process, you can potentially gain some performance benefits. +日志记录有时可能是一个昂贵的操作。 通过将所有登录推出到后台流程，您可以获得一些性能效益。 -## Setup +## 设置 -.. column:: +.. 列: ``` -Out of the box, the background logger is disabled. You will need to opt-in if you would like to use it. +在方框之外，后台记录器已禁用。如果您想要使用它，您将需要选入它。 ``` -.. column:: +.. 列: ```` ```python -app.config.LOGGING = True +app.config.LOGING = True ``` ```` -## How does it work +## 如何工作 -When enabled, the extension will create a `multoprocessing.Queue`. It will remove all handlers on the [default Sanic loggers](../../guide/best-practices/logging.md) and replace them with a [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler). When a message is logged, it will be pushed into the queue by the handler, and read by the background process to the log handlers that were originally in place. This means you can still configure logging as normal and it should "just work." +启用时，扩展将创建 `multoprocessing.Queue` 。 它将移除[默认 Sanic loggers](../../guide/best practices/logging.md) 上的所有处理程序，并将其替换为 [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler)。 当消息被记录时，它将被处理器推送到队列。 并通过后台进程读取原有的日志处理程序。 这意味着您仍然可以将日志配置为正常，它应该“只能工作”。 -## Configuration +## 配置 -| Key | Type | Default | Description | -| ------------------------------------------------------------------------------------- | ------ | ------- | ------------------------------------------------------- | -| LOGGING | `bool` | `False` | Whether to enable this extension. | -| LOGGING_QUEUE_MAX_SIZE | `int` | `4096` | The max size of the queue before messages are rejected. | +| 关键字 | 类型 | 默认设置 | 描述 | +| ------------------------------------------------------------------------------------ | ------ | ------- | -------------- | +| 正在登录 | `bool` | `False` | 是否启用此扩展。 | +| LOGING_QUEUE_MAX_SIZE | `int` | `4096` | 拒绝消息之前队列的最大尺寸。 | From 22bba1419d3ee3fc8392a86f9edbc04c4518039e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:11 +0200 Subject: [PATCH 409/698] New translations openapi.md (Japanese) --- guide/content/ja/plugins/sanic-ext/openapi.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi.md b/guide/content/ja/plugins/sanic-ext/openapi.md index acf33139b1..ae66d6e105 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi.md +++ b/guide/content/ja/plugins/sanic-ext/openapi.md @@ -1,11 +1,11 @@ --- -title: Sanic Extensions - OAS +title: サニックエクステンション - OAS --- # Openapi -- Adding documentation with decorators -- Documenting CBV -- Using autodoc -- Rendering docs with redoc/swagger -- Validation +- デコレータでドキュメントを追加する +- CBV のドキュメント +- autoconの使用 +- Redoc/swaggerによるドキュメントのレンダリング +- 検証 From 6fb84ba299bf138284da2fb7b09f06ea06b337d5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:12 +0200 Subject: [PATCH 410/698] New translations openapi.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/openapi.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi.md b/guide/content/zh/plugins/sanic-ext/openapi.md index acf33139b1..ad8490dca6 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi.md +++ b/guide/content/zh/plugins/sanic-ext/openapi.md @@ -1,11 +1,11 @@ --- -title: Sanic Extensions - OAS +title: 无声扩展 - OAS --- # Openapi -- Adding documentation with decorators -- Documenting CBV -- Using autodoc -- Rendering docs with redoc/swagger -- Validation +- 添加文档到装饰 +- 正在文档CBV +- 使用 autodoc +- 使用redoc/swagger渲染docs +- 验证 From d642da6679b9449cd77aaf0dc51ca61e6122e01d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:13 +0200 Subject: [PATCH 411/698] New translations advanced.md (Japanese) --- guide/content/ja/plugins/sanic-ext/openapi/advanced.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi/advanced.md b/guide/content/ja/plugins/sanic-ext/openapi/advanced.md index b83b905741..75589a9bcc 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi/advanced.md +++ b/guide/content/ja/plugins/sanic-ext/openapi/advanced.md @@ -1,13 +1,13 @@ --- -title: Sanic Extensions - Advanced OAS +title: サニックエクステンション - Advanced OAS --- -# Advanced +# 高度な設定 _Documentation in progress_ ## CBV -## Blueprints +## 建設計画 -## Components +## コンポーネント From 12e5a6965feb51c66faaf88dc9a6ffaaf91ddcb1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:15 +0200 Subject: [PATCH 412/698] New translations advanced.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/openapi/advanced.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/advanced.md b/guide/content/zh/plugins/sanic-ext/openapi/advanced.md index b83b905741..83c86956b8 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/advanced.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/advanced.md @@ -1,13 +1,13 @@ --- -title: Sanic Extensions - Advanced OAS +title: 无声扩展 - 高级OAS --- -# Advanced +# 高级版 -_Documentation in progress_ +正在编写文档_ ## CBV -## Blueprints +## 蓝图 -## Components +## 组件 From 53fc53ce249bda9f1daf2520a5cfc47f5c6476f8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:16 +0200 Subject: [PATCH 413/698] New translations autodoc.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/autodoc.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi/autodoc.md b/guide/content/ja/plugins/sanic-ext/openapi/autodoc.md index e5c962aced..4c3d7389ec 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi/autodoc.md +++ b/guide/content/ja/plugins/sanic-ext/openapi/autodoc.md @@ -1,20 +1,20 @@ --- -title: Sanic Extensions - Auto-documentation +title: サニックエクステンション - 自動ドキュメント --- -# Auto-documentation +# 自動ドキュメント -To make documenting endpoints easier, Sanic Extensions will use a function's docstring to populate your documentation. +エンドポイントの文書化を容易にするために、Sanic Extensionsはdocstringを使ってドキュメントを作成します。 -## Summary and description +## 概要と説明 -.. column:: +.. 列:: ``` -A function's docstring will be used to create the summary and description. As you can see from this example here, the docstring has been parsed to use the first line as the summary, and the remainder of the string as the description. +要約と説明を作成するために、関数の docstring が使用されます。 この例からわかるように、docstringは最初の行を要約として使用するようにパースされています。 文字列の説明として残りの部分を指定します。 ``` -.. column:: +.. 列:: ```` ```python @@ -48,17 +48,17 @@ async def handler(request, something: str): ``` ```` -## Operation level YAML +## 操作レベルYAML -.. column:: +.. 列:: ``` -You can expand upon this by adding valid OpenAPI YAML to the docstring. Simply add a line that contains `openapi:`, followed by your YAML. +これを展開するには、有効なOpenAPI YAML を docstring に追加します。単純に `openapi:` を含む行を追加し、その後に YAML を追加します。 -The `---` shown in the example is *not* necessary. It is just there to help visually identify the YAML as a distinct section of the docstring. +例に示す`---`は*不要*です。 YAML をドキュメント文字列の明確なセクションとして視覚的に識別するために、そこにあるだけです。 ``` -.. column:: +.. 列:: ```` ```python @@ -125,12 +125,12 @@ async def handler(request, something: str): .. note:: ``` -When both YAML documentation and decorators are used, it is the content from the decorators that will take priority when generating the documentation. +YAML ドキュメントとデコレータの両方が使用される場合、ドキュメントを生成する際に優先されるデコレータのコンテンツです。 ``` -## Excluding docstrings +## docstringsを除外 -.. column:: +.. 列:: ``` Sometimes a function may contain a docstring that is not meant to be consumed inside the documentation. @@ -140,7 +140,7 @@ Sometimes a function may contain a docstring that is not meant to be consumed in **Option 2**: Disable it for the single handler with the `@openapi.no_autodoc` decorator ``` -.. column:: +.. 列:: ```` ```python From 2d7447dece77551818d9bcd7f20ceeb7471d7c4c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:17 +0200 Subject: [PATCH 414/698] New translations autodoc.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/autodoc.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md index e5c962aced..f4e82d0f0e 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md @@ -1,20 +1,20 @@ --- -title: Sanic Extensions - Auto-documentation +title: Sanic 扩展 - 自动文档 --- -# Auto-documentation +# 自动文档 -To make documenting endpoints easier, Sanic Extensions will use a function's docstring to populate your documentation. +要使文档端点变得更容易，Sanic 扩展将使用函数的 docstring 来填充您的文档。 -## Summary and description +## 摘要和说明 -.. column:: +.. 列: ``` -A function's docstring will be used to create the summary and description. As you can see from this example here, the docstring has been parsed to use the first line as the summary, and the remainder of the string as the description. +函数的 docstring 将用于创建摘要和描述。 从这里的例子中你可以看到， docstring 已被解析成第一行作为总结。 和字符串的其余部分作为描述。 ``` -.. column:: +.. 列: ```` ```python @@ -48,17 +48,17 @@ async def handler(request, something: str): ``` ```` -## Operation level YAML +## 操作级别 YAML -.. column:: +.. 列: ``` -You can expand upon this by adding valid OpenAPI YAML to the docstring. Simply add a line that contains `openapi:`, followed by your YAML. +你可以通过将有效的 OpenAPI YAML 添加到文档字符串来扩展这个。只需添加一行包含 `openapi:`, 然后是你的 YAML。 -The `---` shown in the example is *not* necessary. It is just there to help visually identify the YAML as a distinct section of the docstring. +示例中显示的 "---" 是*不需要*。 只是为了帮助视觉辨认YAML是文档的一个独特部分。 ``` -.. column:: +.. 列: ```` ```python @@ -122,25 +122,25 @@ async def handler(request, something: str): ``` ```` -.. note:: +.. 注： ``` -When both YAML documentation and decorators are used, it is the content from the decorators that will take priority when generating the documentation. +当使用YAML文档和装饰器时，在生成文档时优先考虑的是装饰器的内容。 ``` -## Excluding docstrings +## 不包括文档字符串 -.. column:: +.. 列: ``` -Sometimes a function may contain a docstring that is not meant to be consumed inside the documentation. +有时候函数可能包含一个文档字符串，该字符串不打算在文档内消耗。 -**Option 1**: Globally turn off auto-documentation `app.config.OAS_AUTODOC = False` +**选项1**：全局关闭自动文档“应用”。 onfig.OAS_AUTODOC = False` -**Option 2**: Disable it for the single handler with the `@openapi.no_autodoc` decorator +**选项2**：使用 `@openapi.no_autodoc` 装饰器禁用单个处理程序 ``` -.. column:: +.. 列: ```` ```python From 7968b2a825046f426baffee7a4265eded5c0327b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:18 +0200 Subject: [PATCH 415/698] New translations basics.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/basics.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi/basics.md b/guide/content/ja/plugins/sanic-ext/openapi/basics.md index e461fa2c49..3eec956e06 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi/basics.md +++ b/guide/content/ja/plugins/sanic-ext/openapi/basics.md @@ -1,22 +1,22 @@ --- -title: Sanic Extensions - Basic OAS +title: サニックエクステンション - Basic OAS --- -# Basics +# 基本 .. note:: ``` -The OpenAPI implementation in Sanic Extensions is based upon the OAS3 implementation from [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi). In fact, Sanic Extensions is in a large way the successor to that project, which entered maintenance mode upon the release of Sanic Extensions. If you were previously using OAS3 with `sanic-openapi` you should have an easy path to upgrading to Sanic Extensions. Unfortunately, this project does *NOT* support the OAS2 specification. +Sanic ExtensionsのOpenAPI実装は、[`sanic-openapi`](https://github.com/sanic-org/sanic-openapi)のOAS3実装に基づいています。 実際、Sanic Extensionsは、Sanic Extensionsのリリース時にメンテナンスモードになったプロジェクトの後継者として大きな意味を持っています。 以前に `sanic-openapi` を使用していた場合は、Sanic Extensionsへのアップグレードの簡単なパスが必要です。 残念ながら、このプロジェクトは OAS2 仕様をサポートしていません。 ``` -.. column:: +.. 列:: ``` -Out of the box, Sanic Extensions provides automatically generated API documentation using the [v3.0 OpenAPI specification](https://swagger.io/specification/). There is nothing special that you need to do +Sanic Extensionsは、[v3.0 OpenAPI仕様](https://swagger.io/specification/)を使用して自動的に生成されたAPIドキュメントを提供しています。特別なことはありません。 ``` -.. column:: +.. 列:: ```` ```python @@ -28,15 +28,15 @@ app = Sanic("MyApp") ``` ```` -After doing this, you will now have beautiful documentation already generated for you based upon your existing application: +これを行うと、既存のアプリケーションに基づいてすでに生成された美しいドキュメントが表示されます。 - [http://localhost:8000/docs](http://localhost:8000/docs) - [http://localhost:8000/docs/redoc](http://localhost:8000/docs/redoc) - [http://localhost:8000/docs/swagger](http://localhost:8000/docs/swagger) -Checkout the [section on configuration](../configuration.md) to learn about changing the routes for the docs. You can also turn off one of the two UIs, and customize which UI will be available on the `/docs` route. +ドキュメントのルート変更について学ぶには、[section on configuration](../configuration.md) をチェックしてください。 2 つの UI のいずれかをオフにして、`/docs` ルートでどのUIが利用できるかをカスタマイズすることもできます。 -.. column:: +.. 列:: ``` Using [Redoc](https://github.com/Redocly/redoc) @@ -44,7 +44,7 @@ Using [Redoc](https://github.com/Redocly/redoc) ![Redoc](/assets/images/sanic-ext-redoc.png) ``` -.. column:: +.. 列:: ``` or [Swagger UI](https://github.com/swagger-api/swagger-ui) @@ -52,17 +52,17 @@ or [Swagger UI](https://github.com/swagger-api/swagger-ui) ![Swagger UI](/assets/images/sanic-ext-swagger.png) ``` -## Changing specification metadata +## 仕様メタデータの変更 -.. column:: +.. 列:: ``` -If you want to change any of the metada, you should use the `describe` method. +メタデータを変更したい場合は、 `describe` メソッドを使用してください。 -In this example `dedent` is being used with the `description` argument to make multi-line strings a little cleaner. This is not necessary, you can pass any string value here. +`dedent` の例では、複数行の文字列を少しクリーナーにするために `description` 引数を使用しています。 これは必要ありません。任意の文字列値を渡すことができます。 ``` -.. column:: +.. 列:: ```` ```python From 56d341d7b2895be5fda36006c29d3d7fbe4a50ac Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:20 +0200 Subject: [PATCH 416/698] New translations basics.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/basics.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/basics.md b/guide/content/zh/plugins/sanic-ext/openapi/basics.md index e461fa2c49..962e4361e7 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/basics.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/basics.md @@ -1,22 +1,22 @@ --- -title: Sanic Extensions - Basic OAS +title: 无声扩展 - 基本OAS --- -# Basics +# 基础知识 -.. note:: +.. 注： ``` -The OpenAPI implementation in Sanic Extensions is based upon the OAS3 implementation from [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi). In fact, Sanic Extensions is in a large way the successor to that project, which entered maintenance mode upon the release of Sanic Extensions. If you were previously using OAS3 with `sanic-openapi` you should have an easy path to upgrading to Sanic Extensions. Unfortunately, this project does *NOT* support the OAS2 specification. +在 Sanic 扩展中实现OpenAPI 是基于从 [`sanic-openapi` ](https://github.com/sanic-org/sanic-openapi )实现的 OAS3 实现。 事实上，Sanic扩展在很大程度上是该项目的继承者，该项目在释放Sanic扩展后进入了维护模式。 如果你先前使用 `sanic-openapi` 的 OAS3 ，你应该有一个简单的路径升级到 Sanic Extensions. 不幸的是，该项目支持 OAS2 的规格。 ``` -.. column:: +.. 列: ``` -Out of the box, Sanic Extensions provides automatically generated API documentation using the [v3.0 OpenAPI specification](https://swagger.io/specification/). There is nothing special that you need to do +在方框中，Sanic 扩展使用[v3.0 OpenAPI 规范](https://swagger.io/specification/)自动生成的 API 文档。您不需要做任何特殊操作 ``` -.. column:: +.. 列: ```` ```python @@ -24,45 +24,45 @@ from sanic import Sanic app = Sanic("MyApp") -# Add all of your views +# 添加您所有的观点 ``` ```` -After doing this, you will now have beautiful documentation already generated for you based upon your existing application: +在这么做之后，您现在将根据您现有的应用程序为您生成美丽的文档： - [http://localhost:8000/docs](http://localhost:8000/docs) - [http://localhost:8000/docs/redoc](http://localhost:8000/docs/redoc) - [http://localhost:8000/docs/swagger](http://localhost:8000/docs/swagger) -Checkout the [section on configuration](../configuration.md) to learn about changing the routes for the docs. You can also turn off one of the two UIs, and customize which UI will be available on the `/docs` route. +签出[配置部分](../configuration.md) 以了解如何更改文档的路由。 您也可以关闭两个界面中的一个，并自定义界面，在`/docs`路由上可用。 -.. column:: +.. 列: ``` -Using [Redoc](https://github.com/Redocly/redoc) +使用 [Redoc](https://github.com/Redocly/Redoc) -![Redoc](/assets/images/sanic-ext-redoc.png) +！[Redoc](/assets/images/sanic-ext-redoc.png) ``` -.. column:: +.. 列: ``` -or [Swagger UI](https://github.com/swagger-api/swagger-ui) +或 [Swagger UI](https://github.com/swagger-api/swagger-ui) ![Swagger UI](/assets/images/sanic-ext-swagger.png) ``` -## Changing specification metadata +## 更改规范元数据 -.. column:: +.. 列: ``` -If you want to change any of the metada, you should use the `describe` method. +如果你想要更改任何元数据, 你应该使用 "描述" 方法。 -In this example `dedent` is being used with the `description` argument to make multi-line strings a little cleaner. This is not necessary, you can pass any string value here. +在这个示例中使用 `edent` 和 `description` 参数来使多行字符串变得更加清洁。 这是不必要的，您可以在此传递任何字符串值。 ``` -.. column:: +.. 列: ```` ```python From 0b6e8b7559269c712c46f299f54efc4a2381ad76 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:22 +0200 Subject: [PATCH 417/698] New translations decorators.md (Japanese) --- .../plugins/sanic-ext/openapi/decorators.md | 210 +++++++++--------- 1 file changed, 105 insertions(+), 105 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi/decorators.md b/guide/content/ja/plugins/sanic-ext/openapi/decorators.md index 63af9849ef..9d7d893619 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi/decorators.md +++ b/guide/content/ja/plugins/sanic-ext/openapi/decorators.md @@ -2,13 +2,13 @@ title: Sanic Extensions - OAS Decorators --- -# Decorators +# デコレーター -The primary mechanism for adding content to your schema is by decorating your endpoints. If you have -used `sanic-openapi` in the past, this should be familiar to you. The decorators and their arguments match closely +スキーマにコンテンツを追加する主なメカニズムは、エンドポイントを飾ることです。 過去に +が`sanic-openapi`を使ったことがあるなら、これはよく知っているはずです。 The decorators and their arguments match closely the [OAS v3.0 specification](https://swagger.io/specification/). -.. column:: +.. 列:: ``` All of the examples show will wrap around a route definition. When you are creating these, you should make sure that @@ -16,7 +16,7 @@ your Sanic route decorator (`@app.route`, `@app.get`, etc) is the outermost deco put that first and then one or more of the below decorators after. ``` -.. column:: +.. 列:: ```` ```python @@ -30,7 +30,7 @@ async def handler(request, something: str): ``` ```` -.. column:: +.. 列:: ``` You will also see a lot of the below examples reference a model object. For the sake of simplicity, the examples will @@ -38,7 +38,7 @@ use `UserProfile` that will look like this. The point is that it can be any well this being a `dataclass` or some other kind of model object. ``` -.. column:: +.. 列:: ```` ```python @@ -49,19 +49,19 @@ class UserProfile: ``` ```` -## Definition decorator +## 定義デコレーター ### `@openapi.definition` -The `@openapi.definition` decorator allows you to define all parts of an operations on a path at once. It is an omnibums -decorator in that it has the same capabilities to create operation definitions as the rest of the decorators. Using -multiple field-specific decorators or a single decorator is a style choice for you the developer. +`@openapi.definition` デコレータを使用すると、一度にパス上の操作のすべての部分を定義できます。 それは装飾者の残りの部分と同じ操作定義を作成する能力を持っているという点でオムニバス +デコレータです。 +複数のフィールド固有のデコレータまたは単一のデコレータを使用することは、開発者にとってスタイルの選択です。 -The fields are purposely permissive in accepting multiple types to make it easiest for you to define your operation. +フィールドは意図的に複数の型を受け入れることで、操作を定義するのが最も簡単になります。 -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `body` | **dict, RequestBody, _YourModel_** | | `deprecated` | **bool** | @@ -69,15 +69,15 @@ The fields are purposely permissive in accepting multiple types to make it easie | `document` | **str, ExternalDocumentation** | | `exclude` | **bool** | | `operation` | **str** | -| `parameter` | **str, dict, Parameter, [str], [dict], [Parameter]** | +| `パラメータ` | **str, dict, Parameter, [str], [dict], [Parameter]** | | `response` | **dict, Response, _YourModel_, [dict], [Response]** | | `summary` | **str** | | `tag` | **str, Tag, [str], [Tag]** | | `secured` | **Dict[str, Any]** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -85,31 +85,31 @@ The fields are purposely permissive in accepting multiple types to make it easie body=RequestBody(UserProfile, required=True), summary="User profile update", tag="one", - response=[Success, Response(Failure, status=400)], + response=[Success, Response, status=400)], ) ``` ```` -.. column:: +.. 列:: -_See below examples for more examples. Any of the values for the below decorators can be used in the corresponding -keyword argument._ +_より多くの例については以下を参照してください。 以下のデコレータのいずれかの値は、対応する +キーワード引数で使用できます。_ -## Field-specific decorators +## フィールド固有の装飾 -All the following decorators are based on `@openapi` +以下のデコレータは `@openapi` に基づいています。 ### body -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ----------- | ---------------------------------- | | **content** | **_YourModel_, dict, RequestBody** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -125,7 +125,7 @@ All the following decorators are based on `@openapi` ``` ```` -.. column:: +.. 列:: ```` ```python @@ -141,15 +141,15 @@ All the following decorators are based on `@openapi` ``` ```` -### deprecated +### 非推奨です -**Arguments** +**引数** -_None_ +_なし_ -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -157,7 +157,7 @@ _None_ ``` ```` -.. column:: +.. 列:: ```` ```python @@ -165,17 +165,17 @@ _None_ ``` ```` -### description +### 説明 -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ------ | ------- | | `text` | **str** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -192,20 +192,20 @@ _None_ ``` ```` -.. column:: +.. 列:: -### document +### ドキュメント -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ------------- | ------- | | `url` | **str** | | `description` | **str** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -213,7 +213,7 @@ _None_ ``` ```` -.. column:: +.. 列:: ```` ```python @@ -221,20 +221,20 @@ _None_ ``` ```` -### exclude +### 除外する -Can be used on route definitions like all of the other decorators, or can be called on a Blueprint +他のデコレータと同様にルート定義に使用したり、ブループリントで呼び出したりできます。 -**Arguments** +**引数** -| Field | Type | Default | -| ------ | ------------- | -------- | -| `flag` | **bool** | **True** | -| `bp` | **Blueprint** | | +| フィールド | タイプ | デフォルト | +| ------ | -------- | -------- | +| `flag` | **bool** | **True** | +| `bp` | **設計図** | | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -242,7 +242,7 @@ Can be used on route definitions like all of the other decorators, or can be cal ``` ```` -.. column:: +.. 列:: ```` ```python @@ -250,19 +250,19 @@ openapi.exclude(bp=some_blueprint) ``` ```` -### operation +### 操作 -Sets the operation ID. +操作 ID を設定します。 -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ------ | ------- | | `name` | **str** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -270,19 +270,19 @@ Sets the operation ID. ``` ```` -.. column:: +.. 列:: -**Arguments** +**引数** -| Field | Type | Default | +| フィールド | タイプ | デフォルト | | ---------- | ----------------------------------------- | ----------- | | `name` | **str** | | | `schema` | _**type**_ | **str** | | `location` | **"query", "header", "path" or "cookie"** | **"query"** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -294,7 +294,7 @@ Sets the operation ID. ``` ```` -.. column:: +.. 列:: ```` ```python @@ -306,22 +306,22 @@ Sets the operation ID. ``` ```` -### response +### 応答 -**Arguments** +**引数** -If using a `Response` object, you should not pass any other arguments. +`Response` オブジェクトを使用する場合は、他の引数を渡すべきではありません。 -| Field | Type | +| フィールド | タイプ | | ------------- | ----------------------------- | | `status` | **int** | | `content` | **_type_, _YourModel_, dict** | | `description` | **str** | -| `response` | **Response** | +| `response` | **応答** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -349,7 +349,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列:: ```` ```python @@ -369,15 +369,15 @@ If using a `Response` object, you should not pass any other arguments. ### summary -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ------ | ------- | | `text` | **str** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -385,19 +385,19 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列:: -### tag +### タグ -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ------- | ------------ | | `*args` | **str, Tag** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -405,7 +405,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列:: ```` ```python @@ -413,17 +413,17 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -### secured +### 保護されている -**Arguments** +**引数** -| Field | Type | +| フィールド | タイプ | | ----------------- | --------------------------------------------------------------------------- | | `*args, **kwargs` | **str, Dict[str, Any]** | -**Examples** +**例** -.. column:: +.. 列:: ```` ```python @@ -431,9 +431,9 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列:: -.. column:: +.. 列:: ```` ```python @@ -441,7 +441,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列:: ```` ```python @@ -449,7 +449,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列:: ```` ```python @@ -457,7 +457,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列:: ```` ```python @@ -465,20 +465,20 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -Do not forget to use `add_security_scheme`. See [security](./security.md) for more details. +`add_security_scheme` を使用することを忘れないでください。 詳細は [security](./security.md) を参照してください。 \`\` -## Integration with Pydantic +## Pydanticとの統合 -Pydantic models have the ability to [generate OpenAPI schema](https://pydantic-docs.helpmanual.io/usage/schema/). +Pydanticモデルはformat@@0(https\://pydantic-docs.helpmanual.io/usage/schema/)を生成する機能を持っています。 -.. column:: +.. 列:: ``` -To take advantage of Pydantic model schema generation, pass the output in place of the schema. +Pydanticモデルスキーマ生成を利用するには、スキーマの代わりに出力を渡してください。 ``` -.. column:: +.. 列:: ```` ```python @@ -514,7 +514,7 @@ async def get(request): .. note:: ``` -It is important to set that `ref_template`. By default Pydantic will select a template that is not standard OAS. This will cause the schema to not be found when generating the final document. +`ref_template`を設定することが重要です。デフォルトではPydanticは標準のOASではないテンプレートを選択します。 これにより、最終的なドキュメントを生成する際にスキーマが見つかりません。 ``` -_Added in v22.9_ +_v22.9_に追加されました From 3c932c5ec04acd6beaced2d91e72d4bb135ee1eb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:24 +0200 Subject: [PATCH 418/698] New translations decorators.md (Chinese Simplified) --- .../plugins/sanic-ext/openapi/decorators.md | 316 +++++++++--------- 1 file changed, 158 insertions(+), 158 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/decorators.md b/guide/content/zh/plugins/sanic-ext/openapi/decorators.md index 63af9849ef..8506c6651a 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/decorators.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/decorators.md @@ -1,14 +1,14 @@ --- -title: Sanic Extensions - OAS Decorators +title: 无声扩展 - 美洲组织装饰师 --- -# Decorators +# 装饰符 -The primary mechanism for adding content to your schema is by decorating your endpoints. If you have -used `sanic-openapi` in the past, this should be familiar to you. The decorators and their arguments match closely -the [OAS v3.0 specification](https://swagger.io/specification/). +将内容添加到您的方案的主要机制是通过装饰您的终点。 If you have +used `sanic-openapi` in the past, this should be familiar to you. 装饰者及其参数与[OAS v3.0 规格](https://swagger.io/specialization/)密切匹配 +。 -.. column:: +.. 列: ``` All of the examples show will wrap around a route definition. When you are creating these, you should make sure that @@ -16,29 +16,29 @@ your Sanic route decorator (`@app.route`, `@app.get`, etc) is the outermost deco put that first and then one or more of the below decorators after. ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import openapi +来自sanic_ext importing openapi @app.get("/path/to/") -@openapi.summary("This is a summary") -@openapi.description("This is a description") -async def handler(request, something: str): +@openapi.summary("这是一个摘要") +@openapi。 escription("这是一个描述") +async def 处理器(请求, 内容: str): ... ``` ```` -.. column:: +.. 列: ``` -You will also see a lot of the below examples reference a model object. For the sake of simplicity, the examples will -use `UserProfile` that will look like this. The point is that it can be any well-typed class. You could easily imagine -this being a `dataclass` or some other kind of model object. +您还将看到许多下面的示例引用模型对象。 为了简洁起见，示例将为 +使用 'UserProfile` 。 问题是，它可以是任何类型良好的类。 您可以轻松地想象一下 +这是一个 `dataclass` 或某种其他类型的模型对象。 ``` -.. column:: +.. 列: ```` ```python @@ -49,74 +49,74 @@ class UserProfile: ``` ```` -## Definition decorator +## 定义装饰符 ### `@openapi.definition` -The `@openapi.definition` decorator allows you to define all parts of an operations on a path at once. It is an omnibums -decorator in that it has the same capabilities to create operation definitions as the rest of the decorators. Using -multiple field-specific decorators or a single decorator is a style choice for you the developer. +`@openapi.definition`装饰器允许您同时在路径上定义操作的所有部分。 它是一个 +装饰器，它具有与其他装饰者相同的创建操作定义的能力。 使用 +多个特定字段的装饰符或单个装饰符是你开发者的样式选择。 -The fields are purposely permissive in accepting multiple types to make it easiest for you to define your operation. +字段有意允许接受多种类型，使您最容易定义您的操作。 -**Arguments** +**参数** -| Field | Type | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `body` | **dict, RequestBody, _YourModel_** | -| `deprecated` | **bool** | -| `description` | **str** | -| `document` | **str, ExternalDocumentation** | -| `exclude` | **bool** | -| `operation` | **str** | -| `parameter` | **str, dict, Parameter, [str], [dict], [Parameter]** | -| `response` | **dict, Response, _YourModel_, [dict], [Response]** | -| `summary` | **str** | -| `tag` | **str, Tag, [str], [Tag]** | -| `secured` | **Dict[str, Any]** | +| 字段 | 类型 | +| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `body` | **dict, RequestBody, _YourModel_** | +| `已弃用` | **布尔** | +| `描述` | **str** | +| `文档` | **str, ExternalDocumentation** | +| `exclude` | **布尔** | +| `operation` | **str** | +| `参数` | **str, dict, 参数, [str], [dict], [Parameter]** | +| `response` | **dict, Response, _YourModel_, [dict], [Response]** | +| `summary` | **str** | +| `tag` | **str, Tag, [str], [Tag]** | +| `securd` | **Dict[str, Any]** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @openapi.definition( body=RequestBody(UserProfile, required=True), - summary="User profile update", + summary="User profile", tag="one", - response=[Success, Response(Failure, status=400)], + response=[Success, ResponseFailure, status=400)], ) ``` ```` -.. column:: +.. 列: -_See below examples for more examples. Any of the values for the below decorators can be used in the corresponding -keyword argument._ +- 更多例子见下文。 以下装饰符的任何值都可以在对应的 + 关键字参数中使用。\* -## Field-specific decorators +## 场地特定装饰 -All the following decorators are based on `@openapi` +以下所有装饰符都基于 `@openapi` -### body +### 正文内容 -**Arguments** +**参数** -| Field | Type | -| ----------- | ---------------------------------- | -| **content** | **_YourModel_, dict, RequestBody** | +| 字段 | 类型 | +| ------ | ---------------------------------- | +| **内容** | **_YourModel_, dict, RequestBody** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @openapi.body(UserProfile) ``` -```python +``python @openapi.body({"application/json": UserProfile}) ``` @@ -125,7 +125,7 @@ All the following decorators are based on `@openapi` ``` ```` -.. column:: +.. 列: ```` ```python @@ -141,71 +141,71 @@ All the following decorators are based on `@openapi` ``` ```` -### deprecated +### 已弃用 -**Arguments** +**参数** -_None_ +_无_ -**Examples** +**示例** -.. column:: +.. 列: ```` ```python -@openapi.deprecated() +@openapi.过时() ``` ```` -.. column:: +.. 列: ```` ```python -@openapi.deprecated +@openapi.废弃的 ``` ```` -### description +### 描述 -**Arguments** +**参数** -| Field | Type | +| 字段 | 类型 | | ------ | ------- | | `text` | **str** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @openapi.description( - """This is a **description**. + """这是一个**描述** 。 -## You can use `markdown` +## 你可以使用 "markdown" -- And +- 和 - make -- lists. +- 列表。 """ ) ``` ```` -.. column:: +.. 列: -### document +### 文档 -**Arguments** +**参数** -| Field | Type | -| ------------- | ------- | -| `url` | **str** | -| `description` | **str** | +| 字段 | 类型 | +| ----- | ------- | +| `url` | **str** | +| `描述` | **str** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @@ -213,7 +213,7 @@ _None_ ``` ```` -.. column:: +.. 列: ```` ```python @@ -221,20 +221,20 @@ _None_ ``` ```` -### exclude +### 不包含 -Can be used on route definitions like all of the other decorators, or can be called on a Blueprint +可以像所有其他装饰器一样用于路由定义，或者可以在蓝图上调用 -**Arguments** +**参数** -| Field | Type | Default | -| ------ | ------------- | -------- | -| `flag` | **bool** | **True** | -| `bp` | **Blueprint** | | +| 字段 | 类型 | 默认设置 | +| ------ | ------ | -------- | +| `flag` | **布尔** | **True** | +| `bp` | **蓝图** | | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @@ -242,27 +242,27 @@ Can be used on route definitions like all of the other decorators, or can be cal ``` ```` -.. column:: +.. 列: ```` ```python -openapi.exclude(bp=some_blueprint) +openapi.exclude(bp=some_bluprint) ``` ```` -### operation +### 操作 -Sets the operation ID. +设置操作 ID。 -**Arguments** +**参数** -| Field | Type | +| 字段 | 类型 | | ------ | ------- | | `name` | **str** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @@ -270,58 +270,58 @@ Sets the operation ID. ``` ```` -.. column:: +.. 列: -**Arguments** +**参数** -| Field | Type | Default | -| ---------- | ----------------------------------------- | ----------- | -| `name` | **str** | | -| `schema` | _**type**_ | **str** | -| `location` | **"query", "header", "path" or "cookie"** | **"query"** | +| 字段 | 类型 | 默认设置 | +| ---------- | ------------------------------------- | -------- | +| `name` | **str** | | +| `schema` | _**type**_ | **str** | +| `location` | **"查询", "header", "path" 或 "cookie"** | **"查询"** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @openapi.parameter("thing") ``` -```python -@openapi.parameter(parameter=Parameter("foobar", deprecated=True)) +``python +@openapi.parameter(parameter=Parameter("foobar", 过时=True)) ``` ```` -.. column:: +.. 列: ```` ```python @openapi.parameter("Authorization", str, "header") ``` -```python +``python @openapi.parameter("thing", required=True, allowEmptyValue=False) ``` ```` -### response +### 应答 -**Arguments** +**参数** -If using a `Response` object, you should not pass any other arguments. +如果使用 "Response" 对象，您不应传递任何其他参数。 -| Field | Type | -| ------------- | ----------------------------- | -| `status` | **int** | -| `content` | **_type_, _YourModel_, dict** | -| `description` | **str** | -| `response` | **Response** | +| 字段 | 类型 | +| ---------- | --------------------------- | +| `status` | **int** | +| `content` | **_类型_, _YourModel_, dict** | +| `描述` | **str** | +| `response` | **答复** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @@ -349,55 +349,55 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列: ```` ```python -@openapi.response(200, UserProfile, "...") +@openapi.response200, UserProfile, "...") ``` ```python -@openapi.response( +@openapi。 esponse( 200, - { + 然后才能 "application/json": UserProfile, }, - "Description...", + "描述. .", ) ``` ```` ### summary -**Arguments** +**参数** -| Field | Type | +| 字段 | 类型 | | ------ | ------- | | `text` | **str** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python -@openapi.summary("This is an endpoint") -``` +@openapi.summary("这是一个终点") + ```` -.. column:: +.. 列: -### tag +### 标签 -**Arguments** +**参数** -| Field | Type | +| 字段 | 类型 | | ------- | ------------ | | `*args` | **str, Tag** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @@ -405,7 +405,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列: ```` ```python @@ -413,17 +413,17 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -### secured +### 安全的 -**Arguments** +**参数** -| Field | Type | +| 字段 | 类型 | | ----------------- | --------------------------------------------------------------------------- | | `*args, **kwargs` | **str, Dict[str, Any]** | -**Examples** +**示例** -.. column:: +.. 列: ```` ```python @@ -431,9 +431,9 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列: -.. column:: +.. 列: ```` ```python @@ -441,7 +441,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列: ```` ```python @@ -449,7 +449,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列: ```` ```python @@ -457,7 +457,7 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -.. column:: +.. 列: ```` ```python @@ -465,20 +465,20 @@ If using a `Response` object, you should not pass any other arguments. ``` ```` -Do not forget to use `add_security_scheme`. See [security](./security.md) for more details. +不要忘记使用 add_security_scheme\` 。 更多详细信息请访问 [security](./security.md)。 \`\` -## Integration with Pydantic +## 与 Pydantic集成 -Pydantic models have the ability to [generate OpenAPI schema](https://pydantic-docs.helpmanual.io/usage/schema/). +Pydantic模型有能力[生成 OpenAPI 方案](https://pydantic-docs.helpmanual.io/usage/schema/)。 -.. column:: +.. 列: ``` -To take advantage of Pydantic model schema generation, pass the output in place of the schema. +为了利用Pydantic模型架构生成，将输出转换为架构。 ``` -.. column:: +.. 列: ```` ```python @@ -511,10 +511,10 @@ async def get(request): ``` ```` -.. note:: +.. 注： ``` -It is important to set that `ref_template`. By default Pydantic will select a template that is not standard OAS. This will cause the schema to not be found when generating the final document. +设置`ref_template`非常重要。默认情况下，Pydantic将选择一个非标准的 OAS模板。 这将导致在生成最后文档时找不到样式。 ``` -_Added in v22.9_ +_添加于 v22.9_ From e98073dade98975f839f0dafc8621b9ed364b62b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:25 +0200 Subject: [PATCH 419/698] New translations security.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/security.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi/security.md b/guide/content/ja/plugins/sanic-ext/openapi/security.md index 416e794bf5..d9b90d0d7e 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi/security.md +++ b/guide/content/ja/plugins/sanic-ext/openapi/security.md @@ -1,16 +1,16 @@ --- -title: Sanic Extensions - OAS Security Schemes +title: サニックエクステンション - OASセキュリティスキーム --- -# Security Schemes +# セキュリティスキーム -To document authentication schemes, there are two steps. +認証スキームを文書化するには、2つのステップがあります。 -_Security is only available starting in v21.12.2_ +_Security は v21.12.2_ からのみ利用できます。 -## Document the scheme +## スキームをドキュメント -.. column:: +.. 列:: ```` The first thing that you need to do is define one or more security schemes. The basic pattern will be to define it as: @@ -24,7 +24,7 @@ The `type` should correspond to one of the allowed security schemes: `"apiKey"`, You should consult the [OpenAPI Specification](https://swagger.io/specification/) for details on what values are appropriate. ```` -.. column:: +.. 列:: ```` ```python @@ -58,15 +58,15 @@ app.ext.openapi.add_security_scheme( ``` ```` -## Document the endpoints +## エンドポイントをドキュメント -.. column:: +.. 列:: ``` -There are two options, document _all_ endpoints. +2つのオプションがあります。文書には_all_エンドポイントがあります。 ``` -.. column:: +.. 列:: ```` ```python @@ -75,13 +75,13 @@ app.ext.openapi.secured("token") ``` ```` -.. column:: +.. 列:: ``` -Or, document only specific routes. +または、特定のルートのみをドキュメントします。 ``` -.. column:: +.. 列:: ```` ```python From 8901bfc1ef8c9dbeb1cfc23c4774801349aa825b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:27 +0200 Subject: [PATCH 420/698] New translations security.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/security.md | 76 +++++++++---------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/security.md b/guide/content/zh/plugins/sanic-ext/openapi/security.md index 416e794bf5..7ad5b195fa 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/security.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/security.md @@ -1,56 +1,56 @@ --- -title: Sanic Extensions - OAS Security Schemes +title: 无声扩展——美洲国家组织的安全计划 --- -# Security Schemes +# 安全方案 -To document authentication schemes, there are two steps. +要记载认证计划，有两个步骤。 -_Security is only available starting in v21.12.2_ +_Security 仅在 v21.12.2_ 开始 -## Document the scheme +## 记录方案 -.. column:: +.. 列: ```` -The first thing that you need to do is define one or more security schemes. The basic pattern will be to define it as: +您需要做的第一件事是定义一个或多个安全方案。 基本模式将定义为： -```python +``python add_security_scheme("", "") ``` -The `type` should correspond to one of the allowed security schemes: `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. You can then pass appropriate keyword arguments as allowed by the specification. +`type` 应该对应于允许的安全方案之一：`"apiKey", `"http", `oauth2", `"openIdConnect"。 然后您可以通过指定允许的适当关键字参数。 -You should consult the [OpenAPI Specification](https://swagger.io/specification/) for details on what values are appropriate. +您应该咨询[OpenAPI Specification](https://swagger.io/specification/) 了解什么值是合适的。 ```` -.. column:: +.. 列: ```` ```python app.ext.openapi.add_security_scheme("api_key", "apiKey") -app.ext.openapi.add_security_scheme( +app.ext.openapi。 dd_security_scheme( "token", "http", scheme="bearer", - bearer_format="JWT", + bearer_form="JWT", ) -app.ext.openapi.add_security_scheme("token2", "http") -app.ext.openapi.add_security_scheme( - "oldschool", +应用。 xt.openapi.add_security_scheme("token2", "http") +app.ext.openapi。 dd_security_scheme( + "老学校", "http", scheme="basic", ) -app.ext.openapi.add_security_scheme( +app.ext.openapi。 dd_security_scheme( "oa2", "oauth2", - flows={ - "implicit": { - "authorizationUrl": "http://example.com/auth", - "scopes": { + flows=own + "implicit": 哇， + "authorizationUrl": "http://example"。 om/auth”， + "scopes": Power "on:two": "something", - "three:four": "something else", - "threefour": "something else...", + "the:four ": "some other", + "三": "其他东西. .", }, } }, @@ -58,15 +58,15 @@ app.ext.openapi.add_security_scheme( ``` ```` -## Document the endpoints +## 记录终点 -.. column:: +.. 列: ``` -There are two options, document _all_ endpoints. +有两个选项，文件 _all_endpoint。 ``` -.. column:: +.. 列: ```` ```python @@ -75,34 +75,34 @@ app.ext.openapi.secured("token") ``` ```` -.. column:: +.. 列: ``` -Or, document only specific routes. +或者只文档特定的路由。 ``` -.. column:: +.. 列: ```` ```python -@app.route("/one") +@app。 oute("/one") async def handler1(request): """ openapi: - --- + - security: - foo: [] - """ + ""” -@app.route("/two") +@app. oute("/tw") @openapi.secured("foo") -@openapi.secured({"bar": []}) +@openapi。 普遍({"bar"：[]}) @openapi.secured(baz=[]) -async def handler2(request): +async def 处理器2(请求)： ... -@app.route("/three") -@openapi.definition(secured="foo") +@app.route("/the") +@openapi。 finition(secured="foo") @openapi.definition(secured={"bar": []}) async def handler3(request): ... From f702eb53d763ffc390e519741377d7a343e8e422 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:28 +0200 Subject: [PATCH 421/698] New translations ui.md (Japanese) --- .../ja/plugins/sanic-ext/openapi/ui.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi/ui.md b/guide/content/ja/plugins/sanic-ext/openapi/ui.md index fd1f4182e6..7c9bcd7cf6 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi/ui.md +++ b/guide/content/ja/plugins/sanic-ext/openapi/ui.md @@ -1,10 +1,10 @@ --- -title: Sanic Extensions - OAS UI +title: サニックエクステンション - OAS UI --- # UI -Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice to use one, or both of them. Out of the box, the following endpoints are setup for you, with the bare `/docs` displaying Redoc. +Sanic Extensionsには、RedocとSwaggerの両方のインターフェースが付属しています。 あなたはそれらのいずれかまたは両方を使用する選択があります。 以下の端点があなたのためにセットアップされています。元の `/docs` にはRedocが表示されています。 - `/docs` - `/docs/openapi.json` @@ -12,19 +12,19 @@ Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice - `/docs/swagger` - `/docs/openapi-config` -## Config options +## 設定オプション -| **Key** | **Type** | **Default** | **Desctiption** | -| -------------------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `OAS_IGNORE_HEAD` | `bool` | `True` | Whether to display `HEAD` endpoints. | -| `OAS_IGNORE_OPTIONS` | `bool` | `True` | Whether to display `OPTIONS` endpoints. | -| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Redoc HTML | -| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Swagger HTML | -| `OAS_UI_DEFAULT` | `Optional[str]` | `"redoc"` | Can be set to `redoc` or `swagger`. Controls which UI to display on the base route. If set to `None`, then the base route will not be setup. | -| `OAS_UI_REDOC` | `bool` | `True` | Whether to enable Redoc UI. | -| `OAS_UI_SWAGGER` | `bool` | `True` | Whether to enable Swagger UI. | -| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | URI path to the OpenAPI config used by Swagger | -| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | URI path to the JSON document. | -| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | URI path to Redoc. | -| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI path to Swagger. | -| `OAS_URL_PREFIX` | `str` | `"/docs"` | URL prefix to use for the Blueprint for OpenAPI docs. | +| **キー** | **Type** | **デフォルト** | **降順** | +| -------------------------- | --------------- | ------------------- | ---------------------------------------------------------------------------------------- | +| `OAS_IGNORE_HEAD` | `bool` | `True` | 「HEAD」エンドポイントを表示するかどうかを設定します。 | +| `OAS_IGNORE_Options` | `bool` | `True` | 「OPTIONS」エンドポイントを表示するかどうかを設定します。 | +| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `なし` | デフォルトのやり直しのHTMLをオーバーライドするHTMLへのパス | +| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `なし` | デフォルトの Swagger HTML を上書きするための HTML へのパス | +| `OAS_UI_DEFAULT` | `Optional[str]` | `"redoc"` | `redoc` または `swagger` に設定できます。 ベースルート上に表示する UI を制御します。 `None` に設定されている場合、ベースルートは設定されません。 | +| `OAS_UI_REDOC` | `bool` | `True` | Redoc UI を有効にするかどうか。 | +| `OAS_UI_SWAGGER` | `bool` | `True` | Swagger UI を有効にするかどうか。 | +| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | Swagger が使用する OpenAPI 設定への URI パス | +| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | JSON ドキュメントへの URI パスです。 | +| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | 再ドックへのURIパス | +| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | Swagger への URI パスです。 | +| `OAS_URL_PREFIX` | `str` | `"/docs"` | OpenAPIドキュメントのブループリントに使用するURLプレフィックス。 | From 0e72ce425e5e9dc0b25e42d0d021201a1a16968e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:30 +0200 Subject: [PATCH 422/698] New translations ui.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/openapi/ui.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/ui.md b/guide/content/zh/plugins/sanic-ext/openapi/ui.md index fd1f4182e6..f929bffdb5 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/ui.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/ui.md @@ -1,10 +1,10 @@ --- -title: Sanic Extensions - OAS UI +title: Sanic 扩展 - OAS UI --- # UI -Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice to use one, or both of them. Out of the box, the following endpoints are setup for you, with the bare `/docs` displaying Redoc. +Sanic 扩展使用Redoc和Swagger两种接口。 你可以选择使用一个，或两个。 下面的终点是为您设置的，下面的 bare `/docs` 显示重启。 - `/docs` - `/docs/openapi.json` @@ -12,19 +12,19 @@ Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice - `/docs/swagger` - `/docs/openapi-config` -## Config options +## 配置选项 -| **Key** | **Type** | **Default** | **Desctiption** | -| -------------------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `OAS_IGNORE_HEAD` | `bool` | `True` | Whether to display `HEAD` endpoints. | -| `OAS_IGNORE_OPTIONS` | `bool` | `True` | Whether to display `OPTIONS` endpoints. | -| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Redoc HTML | -| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Swagger HTML | -| `OAS_UI_DEFAULT` | `Optional[str]` | `"redoc"` | Can be set to `redoc` or `swagger`. Controls which UI to display on the base route. If set to `None`, then the base route will not be setup. | -| `OAS_UI_REDOC` | `bool` | `True` | Whether to enable Redoc UI. | -| `OAS_UI_SWAGGER` | `bool` | `True` | Whether to enable Swagger UI. | -| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | URI path to the OpenAPI config used by Swagger | -| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | URI path to the JSON document. | -| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | URI path to Redoc. | -| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI path to Swagger. | -| `OAS_URL_PREFIX` | `str` | `"/docs"` | URL prefix to use for the Blueprint for OpenAPI docs. | +| **密钥** | **Type** | **默认** | **去除提示** | +| -------------------------- | ---------- | ------------------- | ----------------------------------------------------------- | +| `OAS_IGNORE_HEAD` | `bool` | `True` | 是否显示 `HEAD` 终点。 | +| `OAS_IGNORE_OPTIONS` | `bool` | `True` | 是否显示 "OPTIONS" 端点。 | +| `OAS_PATH_TO_REDOC_HTML` | `可选的[str]` | `无` | 覆盖默认的 Redoc HTML 路径 | +| `OAS_PATH_TO_SWAGGER_HTML` | `可选的[str]` | `无` | 覆盖默认的 Swagger HTML 路径 | +| `OAS_UI_DEFAULT` | `可选的[str]` | `"redoc"` | 可以设置为 `redoc` 或 `swagger` 。 控制基线路上显示的界面。 如果设置为“无”，基线路将不会设置。 | +| `OAS_UI_REDOC` | `bool` | `True` | 是否启用 Redoc UI | +| `OAS_UI_SWAGGER` | `bool` | `True` | 是否启用 Swagger UI | +| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | Swagger 使用的 OpenAPI 配置的 URI 路径 | +| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | JSON文档的 URI 路径。 | +| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | 重新编码的 URI 路径。 | +| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI 到 Swagger 的路径。 | +| `OAS_URL_PREFIX` | `str` | `"/docs"` | 用于OpenAPI 文档蓝图的 URL 前缀。 | From bb7fdc970973326ae6ac87f7f411e876bbbdcfc0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:31 +0200 Subject: [PATCH 423/698] New translations html5tagger.md (Japanese) --- guide/content/ja/plugins/sanic-ext/templating/html5tagger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md b/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md index ab2c64ccdb..baba439d0b 100644 --- a/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md +++ b/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md @@ -2,6 +2,6 @@ title: Sanic Extensions - html5tagger --- -# Coming soon +# 近日公開 See [GitHub])(https\://github.com/sanic-org/html5tagger/) From 70eb075de7604a3bf31320bae9f1d0b756407c1c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:32 +0200 Subject: [PATCH 424/698] New translations html5tagger.md (Chinese Simplified) --- .../content/zh/plugins/sanic-ext/templating/html5tagger.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md b/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md index ab2c64ccdb..aac8d92735 100644 --- a/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md +++ b/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md @@ -1,7 +1,7 @@ --- -title: Sanic Extensions - html5tagger +title: Sanic 扩展 - html5tagger --- -# Coming soon +# 即将开始 -See [GitHub])(https\://github.com/sanic-org/html5tagger/) +See [GitHub](https://github.com/sanic-org/html5tagger/) From c8532be58d99fbddf1ca8ce3469dd0390b2bb9d7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:33 +0200 Subject: [PATCH 425/698] New translations jinja.md (Japanese) --- .../ja/plugins/sanic-ext/templating/jinja.md | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/templating/jinja.md b/guide/content/ja/plugins/sanic-ext/templating/jinja.md index 1f3cefbb22..a02c38b884 100644 --- a/guide/content/ja/plugins/sanic-ext/templating/jinja.md +++ b/guide/content/ja/plugins/sanic-ext/templating/jinja.md @@ -2,31 +2,31 @@ title: Sanic Extensions - Jinja --- -# Templating +# テンプレート設定 -Sanic Extensions can easily help you integrate templates into your route handlers. +Sanic Extensions は、テンプレートをルートハンドラに簡単に統合するのに役立ちます。 -## Dependencies +## 依存関係 -**Currently, we only support [Jinja](https://github.com/pallets/jinja/).** +**現在、 [Jinja](https://github.com/pallets/jinja/)のみサポートしています。** -[Read the Jinja docs first](https://jinja.palletsprojects.com/en/3.1.x/) if you are unfamiliar with how to create templates. +format@@0(https\://jinja.palletsprojects.com/en/3.1.x/) テンプレートを作成する方法に慣れていない場合は、format@@1を参照してください。 -Sanic Extensions will automatically setup and load Jinja for you if it is installed in your environment. Therefore, the only setup that you need to do is install Jinja: +Sanic Extensionsは、環境にインストールされている場合、自動的にJinjaをセットアップしてロードします。 したがって、必要なセットアップはJinjaのインストールだけです。 ``` pip install Jinja2 ``` -## Rendering a template from a file +## ファイルからテンプレートをレンダリングする -There are three (3) ways for you: +あなたには3つの方法があります: -1. Using a decorator to pre-load the template file -2. Returning a rendered `HTTPResponse` object -3. Hybrid pattern that creates a `LazyResponse` +1. テンプレートファイルを事前にロードするデコレータを使用する +2. レンダリングされた `HTTPResponse` オブジェクトを返す +3. `LazyResponse`を作るハイブリッドパターン。 -Let's imagine you have a file called `./templates/foo.html`: +`./templates/foo.html`というファイルがあるとしましょう。 ```html @@ -48,17 +48,17 @@ Let's imagine you have a file called `./templates/foo.html`: ``` -Let's see how you could render it with Sanic + Jinja. +Sanic + Jinjaでどのようにレンダリングできるか見てみましょう。 ### Option 1 - as a decorator -.. column:: +.. 列:: ``` -The benefit of this approach is that the templates can be predefined at startup time. This will mean that less fetching needs to happen in the handler, and should therefore be the fastest option. +このアプローチの利点は、起動時にテンプレートをあらかじめ定義できることです。 これは、より少ないフェッチがハンドラで起こる必要があることを意味し、したがって最速のオプションであるべきです。 ``` -.. column:: +.. 列:: ```` ```python @@ -69,15 +69,15 @@ async def handler(request: Request): ``` ```` -### Option 2 - as a return object +### Option 2 - 戻り値オブジェクトとして -.. column:: +.. 列:: ``` -This is meant to mimic the `text`, `json`, `html`, `file`, etc pattern of core Sanic. It will allow the most customization to the response object since it has direct control of it. Just like in other `HTTPResponse` objects, you can control headers, cookies, etc. +これはSanicの`text`、`json`、`html`、`file`などのパターンを模倣するものです。 それはそれを直接制御しているので、レスポンスオブジェクトにほとんどのカスタマイズを可能にする。 他の `HTTPResponse` オブジェクトと同様に、ヘッダー、クッキーなどを制御できます。 ``` -.. column:: +.. 列:: ```` ```python @@ -93,13 +93,13 @@ async def handler(request: Request): ### Option 3 - hybrid/lazy -.. column:: +.. 列:: ``` -In this approach, the template is defined up front and not inside the handler (for performance). Then, the `render` function returns a `LazyResponse` that can be used to build a proper `HTTPResponse` inside the decorator. +このアプローチでは、テンプレートはハンドラ内ではなく前面で定義されます(パフォーマンスのため)。 次に、`render` 関数はデコレータ内で適切な `HTTPResponse` を構築するために使用できる `LazyResponse` を返します。 ``` -.. column:: +.. 列:: ```` ```python @@ -112,15 +112,15 @@ async def handler(request: Request): ``` ```` -## Rendering a template from a string +## 文字列からテンプレートをレンダリング -.. column:: +.. 列:: ``` -Sometimes you may want to write (or generate) your template inside of Python code and _not_ read it from an HTML file. In this case, you can still use the `render` function we saw above. Just use `template_source`. +Pythonコードの中でテンプレートを書く(または生成する)ことを望むことがあり、HTMLファイルから_not_読み込みを望むことがあります。 この場合でも、上記で見た「render」関数を使うことができます。`template_source` を使うだけです。 ``` -.. column:: +.. 列:: ```` ```python @@ -159,13 +159,13 @@ async def handler(request): .. note:: ``` -In this example, we use `textwrap.dedent` to remove the whitespace in the beginning of each line of the multi-line string. It is not necessary, but just a nice touch to keep both the code and the generated source clean. +この例では、複数行の文字列の先頭にある空白を削除するために `textwrap.dedent` を使用します。 それは必要ありませんが、コードと生成されたソースの両方をきれいに保つためにちょうどいいタッチです。 ``` -## Development and auto-reload +## 開発と自動再読み込み -If auto-reload is turned on, then changes to your template files should trigger a reload of the server. +自動再読み込みがオンになっている場合、テンプレートファイルへの変更によりサーバーの再読み込みが実行されます。 -## Configuration +## 設定 -See `templating_enable_async` and `templating_path_to_templates` in [settings](./configuration.md#settings). +[settings](./configuration.md#settings) の `templating_enable_async` と `templating_path_to_templates` を参照してください。 From 9f7b138ae67e28a2e8897e969b68f82ca0d0ce94 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:35 +0200 Subject: [PATCH 426/698] New translations jinja.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/templating/jinja.md | 84 +++++++++---------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/templating/jinja.md b/guide/content/zh/plugins/sanic-ext/templating/jinja.md index 1f3cefbb22..e55ced9a99 100644 --- a/guide/content/zh/plugins/sanic-ext/templating/jinja.md +++ b/guide/content/zh/plugins/sanic-ext/templating/jinja.md @@ -2,31 +2,31 @@ title: Sanic Extensions - Jinja --- -# Templating +# 模板 -Sanic Extensions can easily help you integrate templates into your route handlers. +Sanic 扩展可以轻松地帮助您将模板整合到您的路由处理器中。 -## Dependencies +## 依赖关系 -**Currently, we only support [Jinja](https://github.com/pallets/jinja/).** +**目前，我们只支持 [Jinja](https://github.com/pallets/jinja/)。** -[Read the Jinja docs first](https://jinja.palletsprojects.com/en/3.1.x/) if you are unfamiliar with how to create templates. +[如果你不熟悉如何创建模板，请先阅读Jinja 文档](https://jinja.palletsprojects.com/en/3.1.x/)。 -Sanic Extensions will automatically setup and load Jinja for you if it is installed in your environment. Therefore, the only setup that you need to do is install Jinja: +Sanic 扩展如果安装在您的环境中，它将自动为您设置并加载Jinja。 因此，您需要做的唯一设置是安装 Jinja： ``` pip install Jinja2 ``` -## Rendering a template from a file +## 从文件渲染模板 -There are three (3) ways for you: +您有三(3)种方式： -1. Using a decorator to pre-load the template file -2. Returning a rendered `HTTPResponse` object -3. Hybrid pattern that creates a `LazyResponse` +1. 使用装饰器预加载模板文件 +2. 返回渲染`HTTPResponse`对象 +3. 混合模式创建一个 `LazyResponse` -Let's imagine you have a file called `./templates/foo.html`: +让我们想象你有一个叫做`./templates/foo.html`的文件： ```html @@ -48,17 +48,17 @@ Let's imagine you have a file called `./templates/foo.html`: ``` -Let's see how you could render it with Sanic + Jinja. +让我们看看你如何用 Sanic + Jinja来渲染它。 -### Option 1 - as a decorator +### 备选案文1 - 装饰符 -.. column:: +.. 列: ``` -The benefit of this approach is that the templates can be predefined at startup time. This will mean that less fetching needs to happen in the handler, and should therefore be the fastest option. +这种方法的好处是，可以在启动时预定义模板。 这将意味着较少需要在处理器中进行获取，因此应该是最快的选择。 ``` -.. column:: +.. 列: ```` ```python @@ -69,58 +69,58 @@ async def handler(request: Request): ``` ```` -### Option 2 - as a return object +### 备选案文2 - 作为退货对象 -.. column:: +.. 列: ``` -This is meant to mimic the `text`, `json`, `html`, `file`, etc pattern of core Sanic. It will allow the most customization to the response object since it has direct control of it. Just like in other `HTTPResponse` objects, you can control headers, cookies, etc. +这意在模仿核心Sanic的“文本”、“json”、“html”、“file”等模式。 它将允许对响应对象进行最直接的自定义，因为它可以直接控制它。 就像在其他 `HTTPResponse` 对象一样，你可以控制头、 cookie 等。 ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import render +来自sanic_ext import render + +@app。 et("/alt") +异步处理器(请求: 请求): + 正在等待渲染( + "foo". tml, context={"seq": ["the", "four"]}, status=400 -@app.get("/alt") -async def handler(request: Request): - return await render( - "foo.html", context={"seq": ["three", "four"]}, status=400 - ) ``` ```` -### Option 3 - hybrid/lazy +### 备选案文3 - 混合的 lazy -.. column:: +.. 列: ``` -In this approach, the template is defined up front and not inside the handler (for performance). Then, the `render` function returns a `LazyResponse` that can be used to build a proper `HTTPResponse` inside the decorator. +在这个方法中，模板是先定义的，而不是在处理程序内(用于性能)。 然后，`render` 函数返回一个 `LazyResponse` ，该函数可以用于在装配器内构建一个 `HTTPResponse` 。 ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import render +from sanic_ext importing render @app.get("/") @app.ext.template("foo.html") async def handler(request: Request): - return await render(context={"seq": ["five", "six"]}, status=400) + returning render(context={"seq": ["fir", "six"]}, status=400) ``` ```` -## Rendering a template from a string +## 从字符串渲染模板 -.. column:: +.. 列: ``` -Sometimes you may want to write (or generate) your template inside of Python code and _not_ read it from an HTML file. In this case, you can still use the `render` function we saw above. Just use `template_source`. +有时，您可能想要在 Python 代码中写入(或生成) 您的模板和 _not_ 从 HTML 文件中读取。 在这种情况下，你仍然可以使用 `render` 函数。只需使用 `template_source` 。 ``` -.. column:: +.. 列: ```` ```python @@ -156,16 +156,16 @@ async def handler(request): ``` ```` -.. note:: +.. 注： ``` -In this example, we use `textwrap.dedent` to remove the whitespace in the beginning of each line of the multi-line string. It is not necessary, but just a nice touch to keep both the code and the generated source clean. +在这个示例中，我们使用 `texttwrap.dedent` 来删除多行字符串开始处的空格。 它是不必要的，而只是一个很好的触摸来保持代码和生成的源代码的清理。 ``` -## Development and auto-reload +## 开发和自动重载 -If auto-reload is turned on, then changes to your template files should trigger a reload of the server. +如果启用自动重新加载，则更改您的模板文件会触发服务器的重新加载。 -## Configuration +## 配置 See `templating_enable_async` and `templating_path_to_templates` in [settings](./configuration.md#settings). From d80981bc213103cd0c99c429d3716a29545c9050 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:36 +0200 Subject: [PATCH 427/698] New translations validation.md (Japanese) --- .../ja/plugins/sanic-ext/validation.md | 86 +++++++++---------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/validation.md b/guide/content/ja/plugins/sanic-ext/validation.md index 504c931a88..87cb2e2a50 100644 --- a/guide/content/ja/plugins/sanic-ext/validation.md +++ b/guide/content/ja/plugins/sanic-ext/validation.md @@ -1,24 +1,24 @@ --- -title: Sanic Extensions - Validation +title: サニックエクステンション - 検証 --- -# Validation +# 検証 -One of the most commonly implemented features of a web application is user-input validation. For obvious reasons, this is not only a security issue, but also just plain good practice. You want to make sure your data conforms to expectations, and throw a `400` response when it does not. +Webアプリケーションの最も一般的に実装されている機能の1つは、ユーザー入力検証です。 明らかな理由から、これはセキュリティの問題だけでなく、単に明白な良い実践です。 データが期待値に合致していることを確認し、そうでない場合は `400` レスポンスを投げます。 -## Implementation +## 実装 -### Validation with Dataclasses +### Dataclassの検証 -With the introduction of [Data Classes](https://docs.python.org/3/library/dataclasses.html), Python made it super simple to create objects that meet a defined schema. However, the standard library only supports type checking validation, **not** runtime validation. Sanic Extensions adds the ability to do runtime validations on incoming requests using `dataclasses` out of the box. If you also have either `pydantic` or `attrs` installed, you can alternatively use one of those libraries. +format@@0(https\://docs.python.org/3/library/dataclasses.html)の導入により、Pythonは定義されたスキーマを満たすオブジェクトを簡単に作成できました。 しかし、標準ライブラリは型チェック検証のみをサポートしており、実行時の検証ではありません。 Sanic Extensionsは、 `dataclasses`を使って受信するリクエストに対して実行時の検証を行う機能を追加します。 `pydantic`または`attrs`のいずれかがインストールされている場合は、それらのライブラリのいずれかを使用することもできます。 -.. column:: +.. 列:: ``` -First, define a model. +まず、モデルを定義します。 ``` -.. column:: +.. 列:: ```` ```python @@ -28,13 +28,13 @@ class SearchParams: ``` ```` -.. column:: +.. 列:: ``` -Then, attach it to your route +次に、ルートに添付してください ``` -.. column:: +.. 列:: ```` ```python @@ -42,18 +42,18 @@ from sanic_ext import validate @app.route("/search") @validate(query=SearchParams) -async def handler(request, query: SearchParams): +async def handler(request, query: SearchParams: return json(asdict(query)) ``` ```` -.. column:: +.. 列:: ``` -You should now have validation on the incoming request. +これで、受信リクエストのバリデーションが完了するはずです。 ``` -.. column:: +.. 列:: ```` ``` @@ -68,17 +68,17 @@ $ curl localhost:8000/search\?q=python ``` ```` -### Validation with Pydantic +### Pydanticによる検証 -You can use Pydantic models also. +Pydanticモデルも使用できます。 -.. column:: +.. 列:: ``` -First, define a model. +まず、モデルを定義します。 ``` -.. column:: +.. 列:: ```` ```python @@ -88,13 +88,13 @@ class Person(BaseModel): ``` ```` -.. column:: +.. 列:: ``` -Then, attach it to your route +次に、ルートに添付してください ``` -.. column:: +.. 列:: ```` ```python @@ -107,13 +107,13 @@ async def handler(request, body: Person): ``` ```` -.. column:: +.. 列:: ``` -You should now have validation on the incoming request. +これで、受信リクエストのバリデーションが完了するはずです。 ``` -.. column:: +.. 列:: ```` ``` @@ -122,17 +122,17 @@ $ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST ``` ```` -### Validation with Attrs +### Attrsによる検証 -You can use Attrs also. +Attrsも使用できます。 -.. column:: +.. 列:: ``` -First, define a model. +まず、モデルを定義します。 ``` -.. column:: +.. 列:: ```` ```python @@ -144,13 +144,13 @@ class Person: ``` ```` -.. column:: +.. 列:: ``` -Then, attach it to your route +次に、ルートに添付してください ``` -.. column:: +.. 列:: ```` ```python @@ -163,13 +163,13 @@ async def handler(request, body: Person): ``` ```` -.. column:: +.. 列:: ``` -You should now have validation on the incoming request. +これで、受信リクエストのバリデーションが完了するはずです。 ``` -.. column:: +.. 列:: ```` ``` @@ -178,17 +178,17 @@ $ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST ``` ```` -## What can be validated? +## 何を検証できますか？ -The `validate` decorator can be used to validate incoming user data from three places: JSON body data (`request.json`), form body data (`request.form`), and query parameters (`request.args`). +`validate` デコレータは、3つの場所から受信したユーザーデータを検証するために使用できます: JSON body data (`request. son`), form body data (`request.form`), and query parameters (`request.args`). -.. column:: +.. 列:: ``` -As you might expect, you can attach your model using the keyword arguments of the decorator. +予想通り、デコレータのキーワード引数を使用してモデルをアタッチすることができます。 ``` -.. column:: +.. 列:: ```` ```python From 9bef4f532f4df612294b2e5d08fde9e806e31ba0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:38 +0200 Subject: [PATCH 428/698] New translations validation.md (Chinese Simplified) --- .../zh/plugins/sanic-ext/validation.md | 110 +++++++++--------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/validation.md b/guide/content/zh/plugins/sanic-ext/validation.md index 504c931a88..923e96c10a 100644 --- a/guide/content/zh/plugins/sanic-ext/validation.md +++ b/guide/content/zh/plugins/sanic-ext/validation.md @@ -1,24 +1,24 @@ --- -title: Sanic Extensions - Validation +title: Sanic 扩展 - 验证 --- -# Validation +# 验证 -One of the most commonly implemented features of a web application is user-input validation. For obvious reasons, this is not only a security issue, but also just plain good practice. You want to make sure your data conforms to expectations, and throw a `400` response when it does not. +网络应用程序最常用的功能之一是用户输入验证。 由于明显的原因，这不仅是一个安全问题，而且也是一个明显的良好做法。 你想要确保你的数据符合预期，并且在没有响应时扔出一个 \`400'。 -## Implementation +## 二． 执行情况 -### Validation with Dataclasses +### 与 Dataclasses 验证 -With the introduction of [Data Classes](https://docs.python.org/3/library/dataclasses.html), Python made it super simple to create objects that meet a defined schema. However, the standard library only supports type checking validation, **not** runtime validation. Sanic Extensions adds the ability to do runtime validations on incoming requests using `dataclasses` out of the box. If you also have either `pydantic` or `attrs` installed, you can alternatively use one of those libraries. +随着[Data Classes](https://docs.python.org/3/library/dataclasses.html)的引入，Python使得创建符合定义模式的对象变得非常简单。 但是，标准库只支持类型检查验证， **不** 运行时间验证。 Sanic 扩展增加了使用`dataclasses`从方框中下载的请求进行运行时验证的能力。 如果你也安装了"pydantic"或"景点"，你也可以使用这些库中的一个。 -.. column:: +.. 列: ``` -First, define a model. +首先，定义一个模型。 ``` -.. column:: +.. 列: ```` ```python @@ -28,13 +28,13 @@ class SearchParams: ``` ```` -.. column:: +.. 列: ``` -Then, attach it to your route +然后将其附加到您的路由 ``` -.. column:: +.. 列: ```` ```python @@ -47,38 +47,38 @@ async def handler(request, query: SearchParams): ``` ```` -.. column:: +.. 列: ``` -You should now have validation on the incoming request. +您现在应该对传入请求进行验证。 ``` -.. column:: +.. 列: ```` -``` +`` $ curl localhost:8000/search -⚠️ 400 — Bad Request -==================== -Invalid request body: SearchParams. Error: missing a required argument: 'q' +⚠️ 400 - Bad Request +============== +无效的请求正文: 搜索参数 错误：缺少一个必需的参数：'q' ``` ``` -$ curl localhost:8000/search\?q=python +$ curl localhost:8000/search\? =python {"q":"python"} ``` ```` -### Validation with Pydantic +### 使用 Pydantic验证 -You can use Pydantic models also. +您也可以使用 Pydantic模型。 -.. column:: +.. 列: ``` -First, define a model. +首先，定义一个模型。 ``` -.. column:: +.. 列: ```` ```python @@ -88,107 +88,107 @@ class Person(BaseModel): ``` ```` -.. column:: +.. 列: ``` -Then, attach it to your route +然后将其附加到您的路由 ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import validate +from sanic_ext import valides @app.post("/person") @validate(json=Person) async def handler(request, body: Person): - return json(body.dict()) + return json(Body.dict()) ``` ```` -.. column:: +.. 列: ``` -You should now have validation on the incoming request. +您现在应该对传入请求进行验证。 ``` -.. column:: +.. 列: ```` ``` -$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +$ curl localhost:8000/personn -d '{"name": "Alice", "age": 21}" -X POST {"name":"Alice","age":21} ``` ```` -### Validation with Attrs +### 使用Attrs进行验证 -You can use Attrs also. +您也可以使用Attrso。 -.. column:: +.. 列: ``` -First, define a model. +首先，定义一个模型。 ``` -.. column:: +.. 列: ```` ```python -@attrs.define -class Person: +@trans.define +class person: name: str age: int ``` ```` -.. column:: +.. 列: ``` -Then, attach it to your route +然后将其附加到您的路由 ``` -.. column:: +.. 列: ```` ```python -from sanic_ext import validate +from sanic_ext import valides @app.post("/person") @validate(json=Person) async def handler(request, body: Person): - return json(attrs.asdict(body)) + return json(Body)) ``` ```` -.. column:: +.. 列: ``` -You should now have validation on the incoming request. +您现在应该对传入请求进行验证。 ``` -.. column:: +.. 列: ```` ``` -$ curl localhost:8000/person -d '{"name": "Alice", "age": 21}' -X POST +$ curl localhost:8000/personn -d '{"name": "Alice", "age": 21}" -X POST {"name":"Alice","age":21} ``` ```` -## What can be validated? +## 什么可以验证？ -The `validate` decorator can be used to validate incoming user data from three places: JSON body data (`request.json`), form body data (`request.form`), and query parameters (`request.args`). +`validate`装饰符可以用来验证来自三个地方的用户数据：JSON body data (\`request ). 这种情况可能会影响到国家的经济和社会经济利益。 -.. column:: +.. 列: ``` -As you might expect, you can attach your model using the keyword arguments of the decorator. +正如您可能期望的那样，您可以使用装饰器的关键字参数附上您的模型。 ``` -.. column:: +.. 列: ```` ```python From 38f861fc5c2420799d11f016596730368d1c71f3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:39 +0200 Subject: [PATCH 429/698] New translations clients.md (Japanese) --- .../ja/plugins/sanic-testing/clients.md | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/guide/content/ja/plugins/sanic-testing/clients.md b/guide/content/ja/plugins/sanic-testing/clients.md index 7dfa3ea8c7..f81a88e58e 100644 --- a/guide/content/ja/plugins/sanic-testing/clients.md +++ b/guide/content/ja/plugins/sanic-testing/clients.md @@ -1,24 +1,24 @@ --- -title: Sanic Testing - Test Clients +title: サニックテスト - テストクライアント --- -# Test Clients +# クライアントのテスト -There are three different test clients available to you, each of them presents different capabilities. +3つの異なるテストクライアントが用意されており、それぞれが異なる機能を提供します。 -## Regular sync client: `SanicTestClient` +## 定期的な同期クライアント: `SanicTestClient` -The `SanicTestClient` runs an actual version of the Sanic Server on your local network to run its tests. Each time it calls an endpoint it will spin up a version of the application and bind it to a socket on the host OS. Then, it will use `httpx` to make calls directly to that application. +`SanicTestClient` はローカルネットワーク上で実際のバージョンの Sanic Server を実行し、テストを実行します。 エンドポイントを呼び出すたびに、アプリケーションのバージョンを起動し、ホスト OS 上のソケットにバインドします。 次に、そのアプリケーションへ直接呼び出しを行うために `httpx` を使用します。 -This is the typical way that Sanic applications are tested. +これは、Sanicアプリケーションがテストされる典型的な方法です。 -.. column:: +.. 列:: ``` -Once installing Sanic Testing, the regular `SanicTestClient` can be used without further setup. This is because Sanic does the leg work for you under the hood. +Sanic Testing をインストールすると、通常の `SanicTestClient` をセットアップせずに使用できます。 これは、サニックがフードの下であなたのために脚を動作させるからです。 ``` -.. column:: +.. 列:: ```` ```python @@ -26,13 +26,13 @@ app.test_client.get("/path/to/endpoint") ``` ```` -.. column:: +.. 列:: ``` -However, you may find it desirable to instantiate the client yourself. +しかし、クライアントを自分でインスタンス化することが望ましいと思うかもしれません。 ``` -.. column:: +.. 列:: ```` ```python @@ -43,13 +43,13 @@ test_client.get("/path/to/endpoint") ``` ```` -.. column:: +.. 列:: ``` -A third option for starting the test client is to use the `TestManager`. This is a convenience object that sets up both the `SanicTestClient` and the `SanicASGITestClient`. +テストクライアントを開始するための3つ目のオプションは、`TestManager` を使用することです。 これは、`SanicTestClient` と `SanicASGITestClient` の両方を設定する便利なオブジェクトです。 ``` -.. column:: +.. 列:: ```` ```python @@ -62,7 +62,7 @@ mgr.test_client.get("/path/to/endpoint") ``` ```` -You can make a request by using one of the following methods +以下のいずれかの方法でリクエストを行うことができます。 - `SanicTestClient.get` - `SanicTestClient.post` @@ -74,7 +74,7 @@ You can make a request by using one of the following methods - `SanicTestClient.websocket` - `SanicTestClient.request` -You can use these methods _almost_ identically as you would when using `httpx`. Any argument that you would pass to `httpx` will be accepted, **with one caveat**: If you are using `test_client.request` and want to manually specify the HTTP method, you should use: `http_method`: +これらのメソッドは `httpx` を使用するときとほぼ同じように使うことができます。 `httpx`に渡す引数は、**ひとつの注意を払って**以下のように受け入れられます: `test_clientを使用している場合。 equest`とHTTPメソッドを手動で指定したい場合は、`http_method`を使用してください。 ```python test_client.request("/path/to/endpoint", http_method="get") @@ -82,15 +82,15 @@ test_client.request("/path/to/endpoint", http_method="get") ## ASGI async client: `SanicASGITestClient` -Unlike the `SanicTestClient` that spins up a server on every request, the `SanicASGITestClient` does not. Instead it makes use of the `httpx` library to execute Sanic as an ASGI application to reach inside and execute the route handlers. +リクエストごとにサーバーをスピンアップする `SanicTestClient` とは異なり、`SanicASGITestClient` はありません。 代わりに、`httpx`ライブラリを使用して、SanicをASGIアプリケーションとして実行し、ルートハンドラにアクセスして実行します。 -.. column:: +.. 列:: ``` -This test client provides all of the same methods and generally works as the `SanicTestClient`. The only difference is that you will need to add an `await` to each call: +このテストクライアントは全ての同じメソッドを提供し、一般的には `SanicTestClient` として動作します。 唯一の違いは、呼び出しごとに`await`を追加する必要があることです。 ``` -.. column:: +.. 列:: ```` ```python @@ -98,27 +98,27 @@ await app.test_client.get("/path/to/endpoint") ``` ```` -The `SanicASGITestClient` can be used in the exact same three ways as the `SanicTestClient`. +`SanicASGITestClient` は `SanicTestClient` と全く同じ3つの方法で使用できます。 .. note:: ``` -The `SanicASGITestClient` does not need to only be used with ASGI applications. The same way that the `SanicTestClient` does not need to only test sync endpoints. Both of these clients are capable of testing *any* Sanic application. +`SanicASGITestClient` は ASGI アプリケーションでのみ使用する必要はありません。 `SanicTestClient` は同期エンドポイントのみをテストする必要がないのと同じ方法です。どちらのクライアントも、*任意*のSanicアプリケーションをテストすることができます。 ``` -## Persistent service client: `ReusableClient` +## 永続的なサービスクライアント: `ReusableClient` -This client works under a similar premise as the `SanicTestClient` in that it stands up an instance of your application and makes real HTTP requests to it. However, unlike the `SanicTestClient`, when using the `ReusableClient` you control the lifecycle of the application. +このクライアントは `SanicTestClient` と同様の前提で動作し、アプリケーションのインスタンスを立ち上げ、実際の HTTP リクエストを行います。 しかし、`SanicTestClient` とは異なり、`ReusableClient` を使用する場合は、アプリケーションのライフサイクルを制御します。 -That means that every request **does not** start a new web server. Instead you will start the server and stop it as needed and can make multiple requests to the same running instance. +つまり、リクエストごとに**新しいWebサーバーを起動しません**。 代わりに、サーバーを起動し、必要に応じて停止し、同じ実行中のインスタンスに複数のリクエストを行うことができます。 -.. column:: +.. 列:: ``` -Unlike the other two clients, you **must** instantiate this client for use: +他の2つのクライアントとは異なり、このクライアントを**インスタンス化**して使用する必要があります： ``` -.. column:: +.. 列:: ```` ```python @@ -128,13 +128,13 @@ client = ReusableClient(app) ``` ```` -.. column:: +.. 列:: ``` -Once created, you will use the client inside of a context manager. Once outside of the scope of the manager, the server will shutdown. +作成されると、コンテキストマネージャーの内部のクライアントを使用します。マネージャーの範囲外の場合、サーバーはシャットダウンします。 ``` -.. column:: +.. 列:: ```` ```python From a35fad4848bb6a8225c5dbe4b561d183b16fd2ff Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:41 +0200 Subject: [PATCH 430/698] New translations clients.md (Chinese Simplified) --- .../zh/plugins/sanic-testing/clients.md | 94 +++++++++---------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/guide/content/zh/plugins/sanic-testing/clients.md b/guide/content/zh/plugins/sanic-testing/clients.md index 7dfa3ea8c7..7465218a85 100644 --- a/guide/content/zh/plugins/sanic-testing/clients.md +++ b/guide/content/zh/plugins/sanic-testing/clients.md @@ -1,68 +1,68 @@ --- -title: Sanic Testing - Test Clients +title: Sanic 测试-测试客户端 --- -# Test Clients +# 测试客户端 -There are three different test clients available to you, each of them presents different capabilities. +您有三个不同的测试客户端，每个客户端具有不同的能力。 -## Regular sync client: `SanicTestClient` +## 常规同步客户端： `SanicTestClient` -The `SanicTestClient` runs an actual version of the Sanic Server on your local network to run its tests. Each time it calls an endpoint it will spin up a version of the application and bind it to a socket on the host OS. Then, it will use `httpx` to make calls directly to that application. +`SanicTestClient` 在您的本地网络上运行一个实际版本的 Sanic Server 来运行测试程序。 每次调用端点时，它会旋转应用程序的版本，并将它绑定到主机OS上的套接字。 然后，它将使用 `httpx` 直接拨打该应用程序。 -This is the typical way that Sanic applications are tested. +这是测试Sanic应用的典型方式。 -.. column:: +.. 列: ``` -Once installing Sanic Testing, the regular `SanicTestClient` can be used without further setup. This is because Sanic does the leg work for you under the hood. +安装 Sanic 测试后，普通的 `SanicTestClient` 可以在不需要进一步设置的情况下使用。 这是因为Sanic在树枝下为你工作。 ``` -.. column:: +.. 列: ```` ```python app.test_client.get("/path/to/endpoint") -``` + ```` -.. column:: +.. 列: ``` -However, you may find it desirable to instantiate the client yourself. +然而，您可能会发现自己需要实例化客户端。 ``` -.. column:: +.. 列: ```` ```python -from sanic_testing.testing import SanicTestClient +from sanic_testing.testimate importing SanicTestClient test_client = SanicTestClient(app) test_client.get("/path/to/endpoint") ``` ```` -.. column:: +.. 列: ``` -A third option for starting the test client is to use the `TestManager`. This is a convenience object that sets up both the `SanicTestClient` and the `SanicASGITestClient`. +开始测试客户端的第三个选项是使用 `TestManager` 。 这个方便对象同时设置 `SanicTestClient` 和 `SanicASGITestClient` 。 ``` -.. column:: +.. 列: ```` ```python -from sanic_testing import TestManager +来自sanic_testination TestManager mgr = TestManager(app) app.test_client.get("/path/to/endpoint") -# or +# 或 mgr.test_client.get("/path/to/endpoint") ``` ```` -You can make a request by using one of the following methods +您可以通过以下方法之一提出请求 - `SanicTestClient.get` - `SanicTestClient.post` @@ -74,7 +74,7 @@ You can make a request by using one of the following methods - `SanicTestClient.websocket` - `SanicTestClient.request` -You can use these methods _almost_ identically as you would when using `httpx`. Any argument that you would pass to `httpx` will be accepted, **with one caveat**: If you are using `test_client.request` and want to manually specify the HTTP method, you should use: `http_method`: +您可以使用这些方法 _almost_ 和您使用 `httpx`时的相同方法。 你传递到`httpx`的任何参数都将被接受，**有一个警告**：如果你在使用`test_client。 赤道`并想手动指定 HTTP 方法，你应该使用: `http_method`: ```python test_client.request("/path/to/endpoint", http_method="get") @@ -82,71 +82,71 @@ test_client.request("/path/to/endpoint", http_method="get") ## ASGI async client: `SanicASGITestClient` -Unlike the `SanicTestClient` that spins up a server on every request, the `SanicASGITestClient` does not. Instead it makes use of the `httpx` library to execute Sanic as an ASGI application to reach inside and execute the route handlers. +不同于“SanicTestClient”在每个请求上旋转服务器，`SanicASGITestClient`不是。 相反，它使用`httpx`库来执行 Sanic 作为ASGI 应用程序来到内部并执行路由处理器。 -.. column:: +.. 列: ``` -This test client provides all of the same methods and generally works as the `SanicTestClient`. The only difference is that you will need to add an `await` to each call: +此测试客户端提供了所有相同的方法，通常与“SanicTestClient”相同。 唯一的区别是您需要在每次通话中添加一个 "等待" ： ``` -.. column:: +.. 列: ```` ```python -await app.test_client.get("/path/to/endpoint") -``` +等待app.test_client.get("/path/to/endpoint") + ```` -The `SanicASGITestClient` can be used in the exact same three ways as the `SanicTestClient`. +`SanicASGITestClient`可以用与`SanicTestClient`完全相同的三种方式使用。 -.. note:: +.. 注： ``` -The `SanicASGITestClient` does not need to only be used with ASGI applications. The same way that the `SanicTestClient` does not need to only test sync endpoints. Both of these clients are capable of testing *any* Sanic application. +`SanicASGITestClient` 不需要只能用于ASGI 应用程序。 类似于“SanicTestClient”不需要只测试同步端点。这两个客户端都能测试*任何*无声应用程序。 ``` -## Persistent service client: `ReusableClient` +## 持久服务客户端: `ReusableClient` -This client works under a similar premise as the `SanicTestClient` in that it stands up an instance of your application and makes real HTTP requests to it. However, unlike the `SanicTestClient`, when using the `ReusableClient` you control the lifecycle of the application. +此客户端在类似于`SanicTestClient`的前提下工作，因为它代表了您应用程序的实例，并且向它提出了真正的 HTTP 请求。 然而，与`SanicTestClient`不同的是，当使用 `ReusableClient` 时，你会控制应用程序的生命周期。 -That means that every request **does not** start a new web server. Instead you will start the server and stop it as needed and can make multiple requests to the same running instance. +这意味着每个请求 **不** 启动一个新的 web 服务器。 相反，您将根据需要启动并停止服务器，并且可以向同一个运行中的实例多次提出请求。 -.. column:: +.. 列: ``` -Unlike the other two clients, you **must** instantiate this client for use: +不同于其他两个客户端，您**必须** 实例化此客户端： ``` -.. column:: +.. 列: ```` ```python -from sanic_testing.reusable import ReusableClient +来自sanic_testing.reusableClient client = ReusableClient(app) ``` ```` -.. column:: +.. 列: ``` -Once created, you will use the client inside of a context manager. Once outside of the scope of the manager, the server will shutdown. +一旦创建，您将在上下文管理器中使用客户端。一旦管理器超出范围，服务器将关闭。 ``` -.. column:: +.. 列: ```` ```python -from sanic_testing.reusable import ReusableClient +来自sanic_testing。 可用于导入可重复使用的客户端 def test_multiple_endpoints_on_same_server(app): - client = ReusableClient(app) - with client: - _, response = client.get("/path/to/1") - assert response.status == 200 + 客户端= ReusableClient(app) + 带客户端: + _, 响应 = 客户端。 et("/path/to/1") + 要求响应。 tatus == 200 - _, response = client.get("/path/to/2") - assert response.status == 200 + _, 响应 = 客户。 et("/path/to/2") + claim response.status == 200 ``` ```` From fd6fbbaf197e1e5a9e0a0423a3632899c411fd6f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:42 +0200 Subject: [PATCH 431/698] New translations getting-started.md (Japanese) --- .../plugins/sanic-testing/getting-started.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/guide/content/ja/plugins/sanic-testing/getting-started.md b/guide/content/ja/plugins/sanic-testing/getting-started.md index 5dcdb0e38f..d305e9b1b1 100644 --- a/guide/content/ja/plugins/sanic-testing/getting-started.md +++ b/guide/content/ja/plugins/sanic-testing/getting-started.md @@ -1,33 +1,33 @@ --- -title: Sanic Testing - Getting Started +title: サニックテスト - はじめに --- -# Getting Started +# はじめに -Sanic Testing is the _official_ testing client for Sanic. Its primary use is to power the tests of the Sanic project itself. However, it is also meant as an easy-to-use client for getting your API tests up and running quickly. +Sanic Testingは、Sanicの_公式_テストクライアントです。 その主な使用は、Sanicプロジェクト自体のテストに電力を供給することです。 ただし、APIテストをすばやく実行するための使いやすいクライアントとしても意味されます。 -## Minimum requirements +## 最低要件 - **Python**: 3.7+ - **Sanic**: 21.3+ -Versions of Sanic older than 21.3 have this module integrated into Sanic itself as `sanic.testing`. +21.3より古いSanicのバージョンは、このモジュールをSanic自体に`sanic.testing`として統合しています。 -## Install +## インストール -Sanic Testing can be installed from PyPI: +PyPI からテストをインストールすることができます。 ``` pip install sanic-testing ``` -## Basic Usage +## 基本的な使用法 -As long as the `sanic-testing` package is in the environment, there is nothing you need to do to start using it. +`sanic-testing`パッケージが環境の中にある限り、使い始める必要はありません。 -### Writing a sync test +### 同期テストを書く -In order to use the test client, you just need to access the property `test_client` on your application instance: +テストクライアントを使用するには、アプリケーションインスタンスの `test_client` プロパティにアクセスするだけです。 ```python import pytest @@ -51,15 +51,15 @@ def test_basic_test_client(app): assert response.status == 200 ``` -### Writing an async test +### 非同期テストを書く -In order to use the async test client in `pytest`, you should install the `pytest-asyncio` plugin. +`pytest`でasyncテストクライアントを使用するには、`pytest-asyncio`プラグインをインストールしてください。 ``` pip install pytest-asyncio ``` -You can then create an async test and use the ASGI client: +非同期テストを作成し、ASGI クライアントを使用できます。 ```python import pytest From e780a2a355a3510a600231252c67b829974f3aa5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:44 +0200 Subject: [PATCH 432/698] New translations getting-started.md (Chinese Simplified) --- .../plugins/sanic-testing/getting-started.md | 50 +++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/guide/content/zh/plugins/sanic-testing/getting-started.md b/guide/content/zh/plugins/sanic-testing/getting-started.md index 5dcdb0e38f..81a177f57c 100644 --- a/guide/content/zh/plugins/sanic-testing/getting-started.md +++ b/guide/content/zh/plugins/sanic-testing/getting-started.md @@ -1,65 +1,65 @@ --- -title: Sanic Testing - Getting Started +title: Sanic 测试-入门开始 --- -# Getting Started +# 正在开始 -Sanic Testing is the _official_ testing client for Sanic. Its primary use is to power the tests of the Sanic project itself. However, it is also meant as an easy-to-use client for getting your API tests up and running quickly. +Sanic Testing 是 _official_ 测试Sanic 客户。 它的主要用途是为萨尼克项目本身的测试提供动力。 然而，它也是一个易于使用的客户端，可以让您的 API 测试升级并快速运行。 -## Minimum requirements +## 最低要求 - **Python**: 3.7+ - **Sanic**: 21.3+ -Versions of Sanic older than 21.3 have this module integrated into Sanic itself as `sanic.testing`. +年龄在21岁以上的Sanic版本将此模块并入Sanic本身，作为“sanic.testing”。 -## Install +## 安装 -Sanic Testing can be installed from PyPI: +可从 PyPI 安装Sanic 测试： ``` -pip install sanic-testing +pip 安装卫生测试 ``` -## Basic Usage +## 基本用法 -As long as the `sanic-testing` package is in the environment, there is nothing you need to do to start using it. +只要`sanic-testing`软件包处于环境中，你就不需要开始使用它。 -### Writing a sync test +### 写入同步测试 -In order to use the test client, you just need to access the property `test_client` on your application instance: +为了使用测试客户端，您只需要在您的应用程序实例中访问属性 'test_client' ： ```python -import pytest -from sanic import Sanic, response +从 sanic import Sanic, 导入 pytest +，响应 -@pytest.fixture +@pytest。 ixture def app(): sanic_app = Sanic("TestSanic") - @sanic_app.get("/") + @sanic_app. et("/") def basic(request): - return response.text("foo") + return response. ext("foo") return sanic_app def test_basic_test_client(app): - request, response = app.test_client.get("/") + request, response = app.test_client. et("/") - assert request.method.lower() == "get" - assert response.body == b"foo" - assert response.status == 200 + passage request.method.lower() == "get" + signing response。 did == b"foo" + passage response.status == 200 ``` -### Writing an async test +### 写入异步测试 -In order to use the async test client in `pytest`, you should install the `pytest-asyncio` plugin. +为了使用 pytest`中的 async 测试客户端，您应该安装`pytest-asyncio\` 插件。 ``` -pip install pytest-asyncio +pip install pest-asyncio ``` -You can then create an async test and use the ASGI client: +然后您可以创建异步测试并使用 ASGI 客户端： ```python import pytest From 353b01e9e50c179aec95fa7a3b2822d01eb12456 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:45 +0200 Subject: [PATCH 433/698] New translations v21.12.md (Japanese) --- guide/content/ja/release-notes/2021/v21.12.md | 214 +++++++++--------- 1 file changed, 107 insertions(+), 107 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.12.md b/guide/content/ja/release-notes/2021/v21.12.md index 2b80536a32..829e05b5a0 100644 --- a/guide/content/ja/release-notes/2021/v21.12.md +++ b/guide/content/ja/release-notes/2021/v21.12.md @@ -1,51 +1,51 @@ --- -title: Version 21.12 (LTS) +title: バージョン 21.12 (LTS) --- -# Version 21.12 (LTS) +# バージョン 21.12 (LTS) -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the final release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will now enter long-term support and will be supported for two years until December 2023. +これはバージョン21のformat@@0(../../org/polices.md#release-schedule)の最終リリースです。 バージョン21は現在、長期サポートに入り、2023年12月までの2年間サポートされます。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Strict application and blueprint names +### アプリケーション名とブループリント名 -In [v21.6](./v21.6.md#stricter-application-and-blueprint-names-and-deprecation) application and blueprint names were required to conform to a new set of restrictions. That change is now being enforced at startup time. +[v21.6](./v21.6.md#stricter-application-and-blueprint-names-deprecation) では、新しい制約のセットに準拠するためにアプリケーションと設計図名が必要でした。 この変更は現在起動時に適用されています。 -Names **must**: +名前**必須**： -1. Only use alphanumeric characters (`a-zA-Z0-9`) -2. May contain a hyphen (`-`) or an underscore (`_`) -3. Must begin with a letter or underscore (`a-zA-Z_`) +1. 英数字のみを使用 (`a-zA-Z0-9`) +2. ハイフン(`-`)またはアンダースコア(`_`)を含めることができます +3. 文字またはアンダースコアで始まる必要があります (`a-zA-Z_`) -### Strict application and blueprint properties +### アプリケーションとブループリントの厳密なプロパティ -The old leniency to allow directly setting properties of a `Sanic` or `Blueprint` object was deprecated and no longer allowed. You must use the `ctx` object. +`Sanic`または`Blueprint`オブジェクトのプロパティを直接設定することを許可する古い寛大さは廃止されました。 `ctx` オブジェクトを使用してください。 ```python app = Sanic("MyApp") app.ctx.db = Database() ``` -### Removals +### 削除 -The following deprecated features no longer exist: +次の非推奨機能は存在しません。 - `sanic.exceptions.abort` - `sanic.views.CompositionView` - `sanic.response.StreamingHTTPResponse` -### Upgrade your streaming responses (if not already) +### ストリーミング応答をアップグレードする (まだない場合) -The `sanic.response.stream` response method has been **deprecated** and will be removed in v22.6. If you are sill using an old school streaming response, please upgrade it. +`sanic.response.stream` レスポンスメソッドは **廃止予定** で、v22.6 で削除されます。 古い学校のストリーミング応答を使用している場合は、アップグレードしてください。 -**OLD - Deprecated** +**OLD - 非推奨** ```python async def sample_streaming_fn(response): @@ -54,10 +54,10 @@ async def sample_streaming_fn(response): @app.route("/") async def test(request: Request): - return stream(sample_streaming_fn, content_type="text/csv") + return stream(sample_streaming_fn, content_type="csv") ``` -**Current** +**現在** ```python async def sample_streaming_fn(response): @@ -71,9 +71,9 @@ async def test(request: Request): await response.send("bar") ``` -### CLI overhaul and MOTD (Message of the Day) +### CLIのオーバーホールとMOTD (メッセージ・オブ・ザ・デイ) -The Sanic CLI has received a fairly extensive upgrade. It adds a bunch of new features to make it on par with `app.run()`. It also includes a new MOTD display to provide quick, at-a-glance highlights about your running environment. The MOTD is TTY-aware, and therefore will be less verbose in server logs. It is mainly intended as a convenience during application development. +Sanic CLIはかなり広範なアップグレードを受けています。 `app.run()`と同等の新機能を追加します。 また、新しいMOTD ディスプレイが含まれており、実行環境に関する迅速かつ一目のハイライトを提供します。 MOTD は TTY を認識しているため、サーバログでは冗長性が低くなります。 主にアプリケーション開発の利便性を目的としています。 ``` $ sanic --help @@ -153,13 +153,13 @@ Optional --no-noisy-exceptions No output stack traces for all exceptions ``` -### Server running modes and changes coming to `debug` +### サーバーの動作モードと変更は `debug` にあります -There are now two running modes: `DEV` and `PRODUCTION`. By default, Sanic server will run under `PRODUCTION` mode. This is intended for deployments. +`DEV`と`PRODUCTION`の2つの実行モードがあります。 デフォルトでは、Sanic サーバーは `PRODUCTION` モードで実行されます。 これは展開を目的としています。 -Currently, `DEV` mode will operate very similarly to how `debug=True` does in older Sanic versions. However, in v22.3. `debug=True` will **no longer** enable auto-reload. If you would like to have debugging and auto-reload, you should enable `DEV` mode. +現在、`DEV`モードは、古いSanicバージョンでは`debug=True`がどのように動作するかと非常によく似ています。 ただし、v22.3では。 `debug=True` は自動リロードを**もう有効にしません** 。 デバッグと自動再ロードを行いたい場合は、`DEV`モードを有効にしてください。 -**DEVELOPMENT** +**開発** ``` $ sanic server:app --dev @@ -169,7 +169,7 @@ $ sanic server:app --dev app.run(debug=True, auto_reload=True) ``` -**PRODUCTION** +**製品** ``` $ sanic server:app @@ -179,24 +179,24 @@ $ sanic server:app app.run() ``` -Beginning in v22.3, `PRODUCTION` mode will no longer enable access logs by default. +v22.3 以降、`PRODUCTION` モードはデフォルトでアクセスログを有効にしなくなりました。 -A summary of the changes are as follows: +変更の概要は以下のとおりです。 -| Flag | Mode | Tracebacks | Logging | Access logs | Reload | Max workers | -| ------- | ----- | ---------- | ------- | ----------- | ------ | ----------- | -| --debug | DEBUG | yes | DEBUG | yes | ^1 | | -| | PROD | no | INFO ^2 | ^3 | | | -| --dev | DEBUG | yes | DEBUG | yes | yes | | -| --fast | | | | | | yes | +| フラグ | モード | トレースバック | ログ | アクセスログ | Reload | 最大ワーカー数 | +| ------- | ----- | ------- | ------ | ------ | ------ | ------- | +| --debug | DEBUG | はい | DEBUG | はい | ^1 | | +| | PROD | いいえ | INFO^2 | ^3 | | | +| --dev | DEBUG | はい | DEBUG | はい | はい | | +| --fast | | | | | | はい | -- ^1 `--debug` to deprecate auto-reloading and remove in 22.3 -- ^2 After 22.3 this moves to WARNING -- ^3 After 22.3: no +- ^1 `--debug` で自動リロードと削除を非推奨にする 22.3 +- ^2 22.3の後、これはWARNINGに移動します +- ^3 後に 22.3: いいえ -### Max allowed workers +### 許可された最大ワーカー数 -You can easily spin up the maximum number of allowed workers using `--fast`. +`--fast` を使用すると、許容されるワーカーの最大数を簡単に呼び出すことができます。 ``` $ sanic server:app --fast @@ -206,20 +206,20 @@ $ sanic server:app --fast app.run(fast=True) ``` -### First-class Sanic Extensions support +### ファーストクラスのサニックエクステンションのサポート -[Sanic Extensions](../../plugins/sanic-ext/getting-started.md) provides a number of additional features specifically intended for API developers. You can now easily implement all of the functionality it has to offer without additional setup as long as the package is in the environment. These features include: +[Sanic Extensions](../../plugins/sanic-ext/getting-started.md) は、API開発者向けに特化した多数の追加機能を提供します。 パッケージが環境内にある限り、追加のセットアップなしで提供するすべての機能を簡単に実装できるようになりました。 これらの機能は次のとおりです。 -- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints -- CORS protection -- Predefined, endpoint-specific response serializers -- Dependency injection into route handlers -- OpenAPI documentation with Redoc and/or Swagger -- Request query arguments and body input validation +- `HEAD`、`OPTIONS`、および `TRACE`エンドポイントを自動的に作成します +- CORS保護 +- 事前定義されたエンドポイント固有のレスポンスシリアライザー +- ルートハンドラへの依存性インジェクション +- やり直しや Swagger を使用した OpenAPI ドキュメント +- クエリクエストの引数と本文入力のバリデーションをリクエスト -The preferred method is to install it along with Sanic, but you can also install the packages on their own. +推奨される方法は、Sanic と一緒にインストールすることですが、独自にパッケージをインストールすることもできます。 -.. column:: +.. 列:: ```` ``` @@ -227,7 +227,7 @@ $ pip install sanic[ext] ``` ```` -.. column:: +.. 列:: ```` ``` @@ -235,11 +235,11 @@ $ pip install sanic sanic-ext ``` ```` -After that, no additional configuration is required. Sanic Extensions will be attached to your application and provide all of the additional functionality with **no further configuration**. +その後、追加の設定は必要ありません。 Sanic Extensionsはアプリケーションに接続され、**これ以上の設定はありません**ですべての機能を提供します。 -If you want to change how it works, or provide additional configuration, you can change Sanic extensions using `app.extend`. The following examples are equivalent. The `Config` object is to provide helpful type annotations for IDE development. +動作を変更したり、追加の設定をしたい場合は、 `app.extend` を使ってSanic拡張機能を変更することができます。 以下の例は等価です。 `Config` オブジェクトは、IDE開発に役立つ型注釈を提供することです。 -.. column:: +.. 列:: ```` ```python @@ -249,7 +249,7 @@ app.extend(config={"oas_url_prefix": "/apidocs"}) ``` ```` -.. column:: +.. 列:: ```` ```python @@ -259,7 +259,7 @@ app.config.OAS_URL_PREFIX = "/apidocs" ``` ```` -.. column:: +.. 列:: ```` ```python @@ -271,11 +271,11 @@ app.extend(config=Config(oas_url_prefix="/apidocs")) ``` ```` -.. column:: +.. 列:: -### Contextual exceptions +### 文脈依存の例外 -In [v21.9](./v21.9.md#default-exception-messages) we added default messages to exceptions that simplify the ability to consistently raise exceptions throughout your application. +[v21.9](./v21.9.md#default-exception-messages) では、アプリケーション全体で例外を一貫して発生させる機能を簡素化する例外にデフォルトのメッセージを追加しました。 ```python class TeapotError(SanicException): @@ -285,12 +285,12 @@ class TeapotError(SanicException): raise TeapotError ``` -But this lacked two things: +しかし、これには二つのことが欠けていました。 -1. A dynamic and predictable message format -2. The ability to add additional context to an error message (more on this in a moment) +1. 動的で予測可能なメッセージ形式 +2. エラーメッセージにコンテキストを追加する機能 (詳細は後で) -The current release allows any Sanic exception to have additional information to when raised to provide context when writing an error message: +現在のリリースでは、Sanic の例外はエラーメッセージを書くときにコンテキストを提供するための追加情報を持つことができます。 ```python class TeapotError(SanicException): @@ -303,35 +303,35 @@ class TeapotError(SanicException): raise TeapotError(extra={"name": "Adam"}) ``` -The new feature allows the passing of `extra` meta to the exception instance. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. +新機能では、例外インスタンスに `extra` メタを渡すことができます。 この`extra` infoオブジェクトは `PRODUCTION` モードでは抑制されますが、 `DEVELOPMENT` モードでは表示されます。 -.. column:: +.. 列:: ``` -**PRODUCTION** +**製品** ![image](https://user-images.githubusercontent.com/166269/139014161-cda67cd1-843f-4ad2-9fa1-acb94a59fc4d.png) ``` -.. column:: +.. 列:: ``` -**DEVELOPMENT** +**開発版** ![image](https://user-images.githubusercontent.com/166269/139014121-0596b084-b3c5-4adb-994e-31ba6eba6dad.png) ``` -Getting back to item 2 from above: _The ability to add additional context to an error message_ +上からアイテム2に戻る: _エラーメッセージにコンテキストを追加する機能_ -This is particularly useful when creating microservices or an API that you intend to pass error messages back in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. +これは、エラーメッセージをJSON形式で渡すことを意図しているマイクロサービスやAPIを作成する場合に特に便利です。 このユースケースでは、パース可能なエラーメッセージ以外にも、クライアントに詳細を返すコンテキストを持たせたいと考えています。 ```python raise TeapotError(context={"foo": "bar"}) ``` -This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: +この情報は **私たちが常にエラーで渡したい** です(利用可能な場合)。 次のようにすべきです: -.. column:: +.. 列:: ```` **PRODUCTION** @@ -348,7 +348,7 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -.. column:: +.. 列:: ```` **DEVELOPMENT** @@ -394,9 +394,9 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -### Background task management +### バックグラウンドタスク管理 -When using the `app.add_task` method to create a background task, there now is the option to pass an optional `name` keyword argument that allows it to be fetched, or cancelled. +`app を使用する場合。 バックグラウンドタスクを作成するためのdd_task` メソッド これで、オプションの `name` キーワード引数を渡すことができ、取得またはキャンセルすることができます。 ```python app.add_task(dummy, name="dummy_task") @@ -405,9 +405,9 @@ task = app.get_task("dummy_task") app.cancel_task("dummy_task") ``` -### Route context kwargs in definitions +### 定義内のコンテキストのkwargsをルーティングします -When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. +route (ルート)が定義された場合、任意の数のキーワード引数を `ctx_` プレフィックスで追加できます。 これらの値はルート `ctx` オブジェクトに注入されます。 ```python @app.get("/1", ctx_label="something") @@ -428,55 +428,55 @@ async def do_something(request): ... ``` -### Blueprints can be registered at any time +### ブループリントはいつでも登録できます -In previous versions of Sanic, there was a strict ordering of when a Blueprint could be attached to an application. If you ran `app.blueprint(bp)` _before_ attaching all objects to the Blueprint instance, they would be missed. +Sanicの以前のバージョンでは、アプリケーションにブループリントを付けることができるときに厳しい順序がありました。 `app.blueprint(bp)` を全てのオブジェクトをブループリントのインスタンスに追加する前に\*実行した場合、それらは見逃されます。 -Now, you can attach a Blueprint at anytime and everything attached to it will be included at startup. +今では、いつでもブループリントを添付することができ、それに添付されているすべてが起動時に含まれます。 -### Noisy exceptions (force all exceptions to logs) +### ノイズ例外（ログにすべての例外を強制） -There is a new `NOISY_EXCEPTIONS` config value. When it is `False` (which is the default), Sanic will respect the `quiet` property of any `SanicException`. This means that an exception with `quiet=True` will not be displayed to the log output. +新しい `NOISY_EXCEPTIONS` 設定値があります。 `False`（デフォルト）の場合、Sanicは任意の`SanicException`の`quiet`プロパティを尊重します。 つまり、 `quiet=True` を持つ例外はログ出力に表示されません。 -However, when setting `NOISY_EXCEPTIONS=True`, all exceptions will be logged regardless of the `quiet` value. +しかし、`NOISY_EXCEPTIONS=True`を設定した場合、`quiet`値に関係なくすべての例外が記録されます。 -This can be helpful when debugging. +これはデバッグ時に役立ちます。 ```python app.config.NOISY_EXCEPTIONS = True ``` -### Signal events as `Enum` +### シグナルイベント を `Enum` として表示 -There is an `Enum` with all of the built-in signal values for convenience. +便宜上、すべての信号値が組み込まれている `Enum` があります。 ```python from sanic.signals import Event @app.signal(Event.HTTP_LIFECYCLE_BEGIN) async def connection_opened(conn_info): - ... +... ``` -### Custom type casting of environment variables +### 環境変数のカスタム型キャスト -By default, Sanic will convert an `int`, `float`, or a `bool` value when applying environment variables to the `config` instance. You can extend this with your own converter: +デフォルトでは、Sanicは環境変数を`config`インスタンスに適用するときに`int`、`float`、または`bool`値を変換します。 独自のコンバーターで拡張できます： ```python app = Sanic(..., config=Config(converters=[UUID])) ``` -### Disable `uvloop` by configuration value +### 設定値により `uvloop` を無効にする -The usage of `uvloop` can be controlled by configuration value: +`uvloop` の使用は、設定値で制御できます。 ```python app.config.USE_UVLOOP = False ``` -### Run Sanic server with multiple TLS certificates +### 複数の TLS 証明書でSanic サーバーを実行する -Sanic can be run with multiple TLS certificates: +Sanic は、複数の TLS 証明書で実行できます。 ```python app.run( @@ -487,25 +487,25 @@ app.run( ) ``` -## News +## ニュース -### Coming Soon: Python Web Development with Sanic +### 近日公開予定：Sanicを使ったPythonウェブ開発 -A book about Sanic is coming soon by one of the core developers, [@ahopkins](https://github.com/ahopkins). +Sanicについての本は、コア開発者の一人[@ahopkins](https://github.com/ahopkins)によってまもなく公開されます。 -Learn more at [sanicbook.com](https://sanicbook.com). +詳細は [sanicbook.com](https://sanicbook.com) でご覧ください。 -> Get equipped with the practical knowledge of working with Sanic to increase the performance and scalability of your web applications. While doing that, we will level-up your development skills as you learn to customize your application to meet the changing business needs without having to significantly over-engineer the app. +> Webアプリケーションのパフォーマンスとスケーラビリティを向上させるために、Sanicとの作業の実用的な知識を備えてください。 それを実行しながら。 変化するビジネスニーズに応えるためにアプリケーションをカスタマイズすることを学ぶにつれて、開発スキルをレベルアップします。アプリを大幅にオーバーエンジニアリングすることなく。 -A portion of book proceeds goes into the Sanic Community Organization to help fund the development and operation of Sanic. So, buying the book is another way you can support Sanic. +本の収益の一部はSanic Community Organizationに入って、Sanicの開発と運営に資金を提供します。 だから、本を購入することはあなたがサニックをサポートすることができる別の方法です。 -### Dark mode for the docs +### ドキュメントのダークモード -If you have not already noticed, this Sanic website is now available in a native dark mode. You can toggle the theme at the top right of the page. +まだ気づいていない場合は、このSanicウェブサイトをネイティブダークモードで利用できるようになりました。 ページ右上のテーマを切り替えることができます。 -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@adarsharegmi](https://github.com/adarsharegmi) [@ahopkins](https://github.com/ahopkins) @@ -524,8 +524,8 @@ Thank you to everyone that participated in this release: :clap: [@vltr](https://github.com/vltr) [@whos4n3](https://github.com/whos4n3) -And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. +そして、[@miss85246](https://github.com/miss85246)と[@ZinkLu](https://github.com/ZinkLu)に感謝します。 *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From e910b84ae139031f07b6eb327ac30e465b3347cf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:48 +0200 Subject: [PATCH 434/698] New translations v21.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.12.md | 312 +++++++++--------- 1 file changed, 156 insertions(+), 156 deletions(-) diff --git a/guide/content/zh/release-notes/2021/v21.12.md b/guide/content/zh/release-notes/2021/v21.12.md index 2b80536a32..46225b4c7f 100644 --- a/guide/content/zh/release-notes/2021/v21.12.md +++ b/guide/content/zh/release-notes/2021/v21.12.md @@ -1,79 +1,79 @@ --- -title: Version 21.12 (LTS) +title: 第21.12版 (LTS) --- -# Version 21.12 (LTS) +# 第21.12版 (LTS) .. toc:: -## Introduction +## 一. 导言 -This is the final release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will now enter long-term support and will be supported for two years until December 2023. +这是版本21的最后版本[发行周期](../../org/policies.md#release-schedule)。 第21版现在将提供长期支助，为期两年，直至2023年12月。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### Strict application and blueprint names +### 严格的应用和蓝图名称 -In [v21.6](./v21.6.md#stricter-application-and-blueprint-names-and-deprecation) application and blueprint names were required to conform to a new set of restrictions. That change is now being enforced at startup time. +在 [v21.6](./v21.6.md#严格应用与蓝图名称-废弃)应用和蓝图名称必须符合一套新的限制。 这种改变现在正在启动时执行。 -Names **must**: +名称 **必须** ： -1. Only use alphanumeric characters (`a-zA-Z0-9`) -2. May contain a hyphen (`-`) or an underscore (`_`) -3. Must begin with a letter or underscore (`a-zA-Z_`) +1. 仅使用字母数字字符(`a-zA-Z0-9`) +2. 可能包含连线(`-`) 或下划线(`_`) +3. 必须以字母或下划线开头(`a-zA-Z_`) -### Strict application and blueprint properties +### 严格的应用和蓝图属性 -The old leniency to allow directly setting properties of a `Sanic` or `Blueprint` object was deprecated and no longer allowed. You must use the `ctx` object. +旧的宽大处理允许直接设置一个 `Sanic` 或 `Blueprint` 对象的属性已被废弃，不再允许。 您必须使用 `ctx` 对象。 ```python app = Sanic("MyApp") app.ctx.db = Database() ``` -### Removals +### 移除 -The following deprecated features no longer exist: +以下已废弃的功能不再存在： -- `sanic.exceptions.abort` -- `sanic.views.CompositionView` +- `sanic.exceptions.abot` +- `sanic.views.compositionView` - `sanic.response.StreamingHTTPResponse` -### Upgrade your streaming responses (if not already) +### 升级您的流媒体响应(如果尚未完成) -The `sanic.response.stream` response method has been **deprecated** and will be removed in v22.6. If you are sill using an old school streaming response, please upgrade it. +`sanic.response.stream`响应方法已被**废弃** 并将在 v22.6中删除。 如果您使用旧的学校流媒体响应，请升级它。 -**OLD - Deprecated** +**OLD - 过时** ```python -async def sample_streaming_fn(response): - await response.write("foo,") - await response.write("bar") +async def sample_streaming_fn(响应): + 等待响应.write("foo, ") + 等待响应.write("bar") @app.route("/") -async def test(request: Request): - return stream(sample_streaming_fn, content_type="text/csv") +async def 测试(请求: 请求): + return (Sample_streing_fn, content_type="text/csv") ``` -**Current** +**当前** ```python -async def sample_streaming_fn(response): - await response.write("foo,") - await response.write("bar") +async def sample_streaming_fn(响应): + 等待响应.write("foo, ") + 等待响应.write("bar") -@app.route("/") -async def test(request: Request): - response = await request.respond(content_type="text/csv") - await response.send("foo,") - await response.send("bar") +@app. oute("/") +异步测试(请求: 请求): + response = 等待请求。 espond(content_type="text/csv") + 等待响应.send("foo,") + 等待响应.send("bar") ``` -### CLI overhaul and MOTD (Message of the Day) +### CLI 全面检查和MOTD (白天) -The Sanic CLI has received a fairly extensive upgrade. It adds a bunch of new features to make it on par with `app.run()`. It also includes a new MOTD display to provide quick, at-a-glance highlights about your running environment. The MOTD is TTY-aware, and therefore will be less verbose in server logs. It is mainly intended as a convenience during application development. +Sanic CLI得到了相当广泛的升级。 它添加了一系列新功能，使它与`app.run()`相同。 它还包括一个新的 MOTD 显示，以提供快速、简洁的关于您运行环境的高亮。 贸易和发展中心知道TTY-knowledge，因此服务器日志中的详细信息将会减少。 它主要是为了方便开发应用程序。 ``` $ sanic --help @@ -153,73 +153,73 @@ Optional --no-noisy-exceptions No output stack traces for all exceptions ``` -### Server running modes and changes coming to `debug` +### 服务器运行模式和将调试变换到 `debug` -There are now two running modes: `DEV` and `PRODUCTION`. By default, Sanic server will run under `PRODUCTION` mode. This is intended for deployments. +现在有两个运行模式：`DEV`和\`PRODUCTION'。 默认情况下，Sanic 服务器将在 "PRODUCTION" 模式下运行。 这是用于部署的。 -Currently, `DEV` mode will operate very similarly to how `debug=True` does in older Sanic versions. However, in v22.3. `debug=True` will **no longer** enable auto-reload. If you would like to have debugging and auto-reload, you should enable `DEV` mode. +目前，`DEV`模式将非常类似于`debug=True`在旧版本的 Sanic 中所做的操作。 然而，在第v22.3段中。 `debug=True` 将\*\*不再启用自动重新加载。 如果你想要调试和自动重新加载，你应该启用 `DEV` 模式。 -**DEVELOPMENT** +**最新情况** ``` $ sanic server:app --dev ``` ```python -app.run(debug=True, auto_reload=True) +运行(调试=True, auto_reload=True) ``` -**PRODUCTION** +**产品** ``` $ sanic server:app ``` ```python -app.run() +run() ``` -Beginning in v22.3, `PRODUCTION` mode will no longer enable access logs by default. +从 v22.3 开始，`PRODUCTION` 模式将不再启用访问日志。 -A summary of the changes are as follows: +这些变动概述如下： -| Flag | Mode | Tracebacks | Logging | Access logs | Reload | Max workers | -| ------- | ----- | ---------- | ------- | ----------- | ------ | ----------- | -| --debug | DEBUG | yes | DEBUG | yes | ^1 | | -| | PROD | no | INFO ^2 | ^3 | | | -| --dev | DEBUG | yes | DEBUG | yes | yes | | -| --fast | | | | | | yes | +| 标志 | 模式 | 后退 | 日志记录 | 访问日志 | Reload | 最大员工人数 | +| ------- | ----- | -- | ------- | ---- | ------ | ------ | +| --debug | DEBUG | 是的 | DEBUG | 是的 | ^1 | | +| | PROD | 否 | INFO ^2 | ^3 | | | +| --dev | DEBUG | 是的 | DEBUG | 是的 | 是的 | | +| --fast | | | | | | 是的 | -- ^1 `--debug` to deprecate auto-reloading and remove in 22.3 -- ^2 After 22.3 this moves to WARNING -- ^3 After 22.3: no +- ^1 `--debug` 不推荐自动重新加载并在 22.3 中删除 +- ^2 22.3 之后移动到警告 +- ^3 22.3之后：无 -### Max allowed workers +### 最大允许的工人 -You can easily spin up the maximum number of allowed workers using `--fast`. +您可以轻松地使用"--fast"来增加允许的工人的最大数量。 ``` $ sanic server:app --fast ``` ```python -app.run(fast=True) +运行 (ast=True) ``` -### First-class Sanic Extensions support +### 一等神经扩展支持 -[Sanic Extensions](../../plugins/sanic-ext/getting-started.md) provides a number of additional features specifically intended for API developers. You can now easily implement all of the functionality it has to offer without additional setup as long as the package is in the environment. These features include: +[Sanic Extensions](../../plugins/sanic-ext/getting-started.md) 提供了一些专门用于 API 开发者的额外功能。 只要包处于环境中，您现在可以轻松地实现它必须提供的所有功能，而无需附加设置。 这些特点包括： -- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints -- CORS protection -- Predefined, endpoint-specific response serializers -- Dependency injection into route handlers -- OpenAPI documentation with Redoc and/or Swagger -- Request query arguments and body input validation +- 自动创建 `HEAD`, `OPTIONS` 和 `TRACE` 终点 +- CORS 保护 +- 预定义的端点特定响应序列转换器 +- 依赖注入路由处理 +- 与 Redoc 或 Swagger 的 OpenAPI 文档 +- 请求查询参数和实体输入验证 -The preferred method is to install it along with Sanic, but you can also install the packages on their own. +首选方法是与 Sanic 一起安装，但您也可以自己安装软件包。 -.. column:: +.. 列: ```` ``` @@ -227,39 +227,39 @@ $ pip install sanic[ext] ``` ```` -.. column:: +.. 列: ```` ``` -$ pip install sanic sanic-ext +$ pip install sanic-ext ``` ```` -After that, no additional configuration is required. Sanic Extensions will be attached to your application and provide all of the additional functionality with **no further configuration**. +此后，不需要额外的配置。 Sanic 扩展将附加到您的应用程序，并提供所有附加功能，**不再配置**。 -If you want to change how it works, or provide additional configuration, you can change Sanic extensions using `app.extend`. The following examples are equivalent. The `Config` object is to provide helpful type annotations for IDE development. +如果您想要更改它的工作方式，或提供额外的配置，您可以使用 `app.extend` 更改Sanic 扩展。 下面的例子是相同的。 `Config`对象是为IDE开发提供有用的类型注释。 -.. column:: +.. 列: ```` ```python -# This is optional, not required +# 这是可选的，不需要 app = Sanic("MyApp") app.extend(config={"oas_url_prefix": "/apidocs"}) ``` ```` -.. column:: +.. 列: ```` ```python -# This is optional, not required +# 这是可选的，不需要 app = Sanic("MyApp") app.config.OAS_URL_PREFIX = "/apidocs" ``` ```` -.. column:: +.. 列: ```` ```python @@ -271,26 +271,26 @@ app.extend(config=Config(oas_url_prefix="/apidocs")) ``` ```` -.. column:: +.. 列: -### Contextual exceptions +### 上下文异常 -In [v21.9](./v21.9.md#default-exception-messages) we added default messages to exceptions that simplify the ability to consistently raise exceptions throughout your application. +在 [v21.9](./v21.9.md#default-exception-messages) 中，我们添加了默认消息到异常，简化了在您的整个应用程序中始终如一地提出异常的能力。 ```python class TeapotError(SanicException): status_code = 418 - message = "Sorry, I cannot brew coffee" + message = “对不起，我不能酿造咖啡” -raise TeapotError +rappot错误 ``` -But this lacked two things: +但缺少两件事： -1. A dynamic and predictable message format -2. The ability to add additional context to an error message (more on this in a moment) +1. 动态和可预测的信息格式 +2. 添加附加上下文到错误消息的能力 (暂时更多) -The current release allows any Sanic exception to have additional information to when raised to provide context when writing an error message: +当前版本允许任何Sanic异常在写错误消息时提供背景信息： ```python class TeapotError(SanicException): @@ -298,14 +298,14 @@ class TeapotError(SanicException): @property def message(self): - return f"Sorry {self.extra['name']}, I cannot make you coffee" + return f"对不起{self.extr['name']}, 我不能让你咖啡” -raise TeapotError(extra={"name": "Adam"}) +raising TeapotError(extranti={"name": "Adam"}) ``` -The new feature allows the passing of `extra` meta to the exception instance. This `extra` info object **will be suppressed** when in `PRODUCTION` mode, but displayed in `DEVELOPMENT` mode. +新功能允许将 `extra` 元传递给异常实例。 这个“额外”信息对象 **将在 `PRODUCTION` 模式下被抑制** ，但将以`DevelopMENT` 模式显示。 -.. column:: +.. 列: ``` **PRODUCTION** @@ -313,25 +313,25 @@ The new feature allows the passing of `extra` meta to the exception instance. Th ![image](https://user-images.githubusercontent.com/166269/139014161-cda67cd1-843f-4ad2-9fa1-acb94a59fc4d.png) ``` -.. column:: +.. 列: ``` -**DEVELOPMENT** +**developMENT** -![image](https://user-images.githubusercontent.com/166269/139014121-0596b084-b3c5-4adb-994e-31ba6eba6dad.png) +！[image](https://user-images.githubusercontent.com/1662669/139014121-0596b084-b3c5-4adb-994e-31ba6eba6dad.png) ``` -Getting back to item 2 from above: _The ability to add additional context to an error message_ +从以上获取到项目2：_添加附加上下文到错误消息的能力 -This is particularly useful when creating microservices or an API that you intend to pass error messages back in JSON format. In this use case, we want to have some context around the exception beyond just a parseable error message to return details to the client. +这在创建微型服务或您打算以 JSON 格式传递错误消息的API时特别有用。 在这种情况下，我们想要围绕例外的某些上下文，而不仅仅是一个可解析的错误信息来返回客户端。 ```python -raise TeapotError(context={"foo": "bar"}) +raised TeapotError(context={"foot": "bar"}) ``` -This is information **that we want** to always be passed in the error (when it is available). Here is what it should look like: +这是**我们想要**总是错误传递的信息(当它可用时)。 以下是它应该看起来的样子： -.. column:: +.. 列: ```` **PRODUCTION** @@ -348,44 +348,44 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -.. column:: +.. 列: ```` -**DEVELOPMENT** +**developMENT** ```json -{ - "description": "I'm a teapot", +Paper + "description": "我是个茶", "status": 418, - "message": "Sorry Adam, I cannot make you coffee", - "context": { + "消息": "对不起, 我不能让你咖啡", + "context": Power "foo": "bar" }, - "extra": { + "extran": Power "name": "Adam", - "more": "lines", - "complex": { + "more ": "lines", + "复合": Power "one": "two" } }, - "path": "/", + "路径": "/", "args": {}, "exceptions": [ - { + len "type": "TeapotError", - "exception": "Sorry Adam, I cannot make you coffee", + "异常": "对不起，Adam, 我不能让你喝咖啡”， "frames": [ - { + Power "file": "handle_request", "line": 83, "name": "handle_request", "src": "" }, - { - "file": "/tmp/p.py", + Power + "file": "/tmp/p. y", "line": 17, "name": "handler", - "src": "raise TeapotError(" + "src": "raising TeapotError(" } ] } @@ -394,9 +394,9 @@ This is information **that we want** to always be passed in the error (when it i ``` ```` -### Background task management +### 背景任务管理 -When using the `app.add_task` method to create a background task, there now is the option to pass an optional `name` keyword argument that allows it to be fetched, or cancelled. +使用 `app 时. dd_task` 方法来创建背景任务。 现在可以通过一个可选的 `name` 关键字参数来获取或取消它。 ```python app.add_task(dummy, name="dummy_task") @@ -405,105 +405,105 @@ task = app.get_task("dummy_task") app.cancel_task("dummy_task") ``` -### Route context kwargs in definitions +### 定义中路由上下文kwargs -When a route is defined, you can add any number of keyword arguments with a `ctx_` prefix. These values will be injected into the route `ctx` object. +当路由被定义时，您可以添加任何数量的关键字参数与 `ctx_` 前缀。 这些值将被注入到路由 `ctx` 对象中。 ```python @app.get("/1", ctx_label="something") async def handler1(request): ... -@app.get("/2", ctx_label="something") +@appp. et("/2", ctx_label="something") async def handler2(request): ... -@app.get("/99") +@app. et("/99") async def handler99(request): ... -@app.on_request +@app. n_request async def do_something(request): if request.route.ctx.label == "something": - ... +... ``` -### Blueprints can be registered at any time +### 蓝图可以随时注册 -In previous versions of Sanic, there was a strict ordering of when a Blueprint could be attached to an application. If you ran `app.blueprint(bp)` _before_ attaching all objects to the Blueprint instance, they would be missed. +在先前版本的Sanic中，严格规定蓝图何时可以附加到申请中。 如果你在 `app.blueprint(bp)` \*之前将所有对象附加到蓝图实例中，他们就会被错过。 -Now, you can attach a Blueprint at anytime and everything attached to it will be included at startup. +现在，您可以随时附加蓝图，附加到它的所有内容都将在启动时包含。 -### Noisy exceptions (force all exceptions to logs) +### 噪音异常(强制所有异常日志) -There is a new `NOISY_EXCEPTIONS` config value. When it is `False` (which is the default), Sanic will respect the `quiet` property of any `SanicException`. This means that an exception with `quiet=True` will not be displayed to the log output. +有一个新的 `NOISY_EXCEPTIONS` 配置值。 当它是 `False` (默认值) 时，萨尼克会尊重任何`SanicException`的安静\` 属性。 这意味着"安静=True"的异常将不会显示到日志输出。 -However, when setting `NOISY_EXCEPTIONS=True`, all exceptions will be logged regardless of the `quiet` value. +然而，当设置 `NOISY_EXCEPTIONS=True` 时，所有异常都将被记录，而不论安静的值如何。 -This can be helpful when debugging. +在调试时这可能是有帮助的。 ```python -app.config.NOISY_EXCEPTIONS = True +应用程序.config.NOISY_EXCEPTIS = True ``` -### Signal events as `Enum` +### 信号事件为 `Enum` -There is an `Enum` with all of the built-in signal values for convenience. +有一个 `Enum` 包含所有内置的信号值以方便。 ```python -from sanic.signals import Event +从sanic.signatures @app.signal(Event.HTTP_LIFECYCLE_BEGIN) async def connection_opened(conn_info): - ... + ``` -### Custom type casting of environment variables +### 自定义环境变量的投影类型 -By default, Sanic will convert an `int`, `float`, or a `bool` value when applying environment variables to the `config` instance. You can extend this with your own converter: +默认情况下，当将环境变量应用到 `config` 实例时，Sanic 会将`int`、`float`、`bool`等值转换为`config`。 您可以通过自己的转换器来扩展此功能： ```python -app = Sanic(..., config=Config(converters=[UUID])) +应用 = Sanic(..., config=Config(converters=[UUID])) ``` -### Disable `uvloop` by configuration value +### 按配置值禁用 `uvloop` -The usage of `uvloop` can be controlled by configuration value: +`uvloop`的用法可以由配置值控制： ```python -app.config.USE_UVLOOP = False +应用程序config.USE_UVLOOP = 错误 ``` -### Run Sanic server with multiple TLS certificates +### 用 TLS 证书运行 Sanic 服务器 -Sanic can be run with multiple TLS certificates: +Sanic 可以使用多个TLS证书运行： ```python -app.run( +运行( ssl=[ - "/etc/letsencrypt/live/example.com/", - "/etc/letsencrypt/live/mysite.example/", + "/etc/letsent/crypt/live/example.com/", + "/etcrypt/live/mysite.example/", ] ) ``` -## News +## 新闻 -### Coming Soon: Python Web Development with Sanic +### 即将到来：Python Web Development with Sanic -A book about Sanic is coming soon by one of the core developers, [@ahopkins](https://github.com/ahopkins). +一本关于Sanic的书即将由一个核心开发者编写，[@ahopkins](https://github.com/ahopkins)。 -Learn more at [sanicbook.com](https://sanicbook.com). +在 [sanicbook.com](https://sanicbook.com)上了解更多信息。 -> Get equipped with the practical knowledge of working with Sanic to increase the performance and scalability of your web applications. While doing that, we will level-up your development skills as you learn to customize your application to meet the changing business needs without having to significantly over-engineer the app. +> 装备了与Sanic合作的实用知识，以提高您的网络应用程序的性能和可扩展性。 在这样做的时候， 我们将提升您的开发技能，因为您正在学会自定义您的应用程序，以满足不断变化的业务需要，而不必过度设计应用程序。 -A portion of book proceeds goes into the Sanic Community Organization to help fund the development and operation of Sanic. So, buying the book is another way you can support Sanic. +部分账单收入转入萨尼语社区组织，以帮助资助萨尼语的发展和运作。 因此，购买该书是你可以支持Sanic的另一种方式。 -### Dark mode for the docs +### 文档的暗色模式 -If you have not already noticed, this Sanic website is now available in a native dark mode. You can toggle the theme at the top right of the page. +如果你还没有注意到，这个Sanic网站现在可以在本机黑暗模式下使用。 您可以切换页面右上角的主题。 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -524,8 +524,8 @@ Thank you to everyone that participated in this release: :clap: [@vltr](https://github.com/vltr) [@whos4n3](https://github.com/whos4n3) -And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. +并且，特别感谢你[@miss85246](https://github.com/miss85246)和[@ZinkLu](https://github.com/ZinkLu)做了大量工作，使文档同步并翻译成中文。 *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 43ef0d3a7564e5118ce1552d867f797efe37af71 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:49 +0200 Subject: [PATCH 435/698] New translations v21.3.md (Japanese) --- guide/content/ja/release-notes/2021/v21.3.md | 172 +++++++++---------- 1 file changed, 86 insertions(+), 86 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.3.md b/guide/content/ja/release-notes/2021/v21.3.md index 2539e750b2..5a41716a33 100644 --- a/guide/content/ja/release-notes/2021/v21.3.md +++ b/guide/content/ja/release-notes/2021/v21.3.md @@ -1,16 +1,16 @@ --- -title: Version 21.3 +title: バージョン 21.3 --- -# Version 21.3 +# バージョン 21.3 -.. toc:: +.. TOC:: -## Introduction +## はじめに -Sanic is now faster. +サニックは今より速くなりました。 -Well, it already was fast. But with the first iteration of the v21 release, we incorporated a few major milestones that have made some tangible improvements. These encompass some ideas that have been in the works for years, and have finally made it into the released version. +まあ、それはすでに速かったです。 しかし、v21リリースの最初の反復で、いくつかの具体的な改善を行った主要なマイルストーンをいくつか取り入れました。 これらは、長年の作品にされてきたいくつかのアイデアを包含し、最終的にリリースされたバージョンにそれを作りました。 .. warning:: Breaking changes @@ -25,53 +25,53 @@ pip freeze > requirements.txt For most typical installations, you should be able to upgrade without a problem. ```` -## What to know +## 知っておくべきこと -Notable new or breaking features, and what to upgrade... +注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Python 3.7+ Only +### Python 3.7+ のみ -This version drops Python 3.6 support. Version 20.12LTS will continue to support Python 3.6 until its EOL in December, 2022, and version 19.12LTS will support it until its EOL in December, 2021. +このバージョンは Python 3.6 のサポートを削除します。 バージョン 20.12LTS は Python 3.6 を 2022 年12 月、バージョン 19 までサポートします。 2LTSは2021年12月にEOLまでサポートします。 -Read more about our [LTS policy](../project/policies.md#long-term-support-v-interim-releases). +format@@0(../project/policy.md#long-term-support-v-interim-releases) についてもっと読んでください。 -### Streaming as first class citizen +### ファーストクラスの市民としてストリーミング中 -The biggest speed improvement came from unifying the request/response cycle into a single flow. Previously, there was a difference between regular cycles, and streaming cycles. This has been simplified under the hood, even though the API is staying the same right now for compatibility. The net benefit is that **all** requests now should see a new benefit. +最大の速度向上は、リクエスト/レスポンスサイクルを単一のフローに統合することでした。 以前は、定期的なサイクルとストリーミングサイクルに違いがありました。 APIは互換性のために現在同じままでいるにもかかわらず、これは実際には簡素化されています。 利点は、 **すべての** のリクエストに新しい利点が表示されるようになりました。 -Read more about [streaming changes](../advanced/streaming.md#response-streaming). +format@@0(../advanced/streaming.md#response-streaming) についてもっと読んでください。 -### Router overhaul +### ルーターのオーバーホール -The old Sanic router was based upon regular expressions. In addition it suffered from a number of quirks that made it hard to modify at run time, and resulted in some performance issues. This change has been years in the making and now [converts the router to a compiled tree at startup](https://community.sanicframework.org/t/a-fast-new-router/649/41). Look for additional improvements throughout the year. +古いSanicルータは正規表現に基づいていました。 また、実行時に変更が困難になった癖も多数あり、パフォーマンス上の問題も生じた。 この変更は長年にわたって行われており、format@@0(https\://community.sanicframework.org/t/a-fast-new-router/649/41) でルーターをコンパイルしました。 年間を通して追加の改善を探してください。 -The outward facing API has kept backwards compatibility. However, if you were accessing anything inside the router specifically, you many notice some changes. For example: +外向きのAPIは後方互換性を保っています。 ただし、ルーター内の何かにアクセスしている場合は、いくつかの変更に気づくことがあります。 例: -1. `Router.get()` has a new return value -2. `Route` is now a proper class object and not a `namedtuple` -3. If building the router manually, you will need to call `Router.finalize()` before it is usable -4. There is a new `` pattern that can be matched in your routes -5. You cannot startup an application without at least one route defined +1. `Router.get()`に新しい戻り値があります +2. `Route`は適切なクラスオブジェクトで、`namedtuple`ではありません。 +3. ルーターを手動で構築する場合は、使用する前に `Router.finalize()` を呼び出す必要があります。 +4. ルートにマッチする新しい``パターンがあります +5. 少なくとも 1 つのルートが定義されていないアプリケーションを起動することはできません。 -The router is now located in its own repository: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-routing/). +ルーターは以下のリポジトリにあります: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router)。format@@0(https\://pypi.org/project/sanic-routing/) ### Signals API ⭐️ -_BETA Feature: API to be finalized in v21.6_ +_BETA 機能: v21.6_ で確定する API -A side benefit of the new router is that it can do double duty also powering the [new signals API](https://github.com/sanic-org/sanic/issues/1630). This feature is being released for public usage now, and likely the public API will not change in its final form. +新しいルータの利点として、format@@0(https\://github.com/sanic-org/sanic/issues/1630)にも電力を供給できることが挙げられます。 この機能は現在一般向けにリリースされており、パブリックAPIは最終的な形で変更されない可能性があります。 -The core ideas of this feature are: +この機能の中核的なアイデアは次のとおりです。 -1. to allow the developer greater control and access to plugging into the server and request lifecycles, -2. to provide new tools to synchronize and send messages through your application, and -3. to ultimately further increase performance. +1. サーバーへのプラグインやライフサイクルのリクエストを行うことができます +2. アプリケーションを通じてメッセージを同期および送信する新しいツールを提供します。 +3. 最終的にはさらにパフォーマンスを向上させることができます -The API introduces three new methods: +APIは3つの新しいメソッドを導入しました。 -- `@app.signal(...)` - For defining a signal handler. It looks and operates very much like a route. Whenever that signal is dispatched, this handler will be executed. -- `app.event(...)` - An awaitable that can be used anywhere in your application to pause execution until the event is triggered. -- `app.dispatch(...)` - Trigger an event and cause the signal handlers to execute. +- `@app.signal(...)` - シグナルハンドラを定義するため。 見た目とルートのように動作します。 そのシグナルがディスパッチされるたびに、このハンドラが実行されます。 +- `app.event(...)` - イベントがトリガーされるまで実行を一時停止するアプリケーションのどこでも使用できる待ち時間。 +- `app.dispatch(...)` - イベントをトリガーしてシグナルハンドラを実行します。 ```python @app.signal("foo.bar.") @@ -94,37 +94,37 @@ async def trigger(request): return response.text("Done.") ``` -### Route naming +### ルート名 -Routes used to be referenced by both `route.name` and `route.endpoint`. While similar, they were slightly different. Now, all routes will be **consistently** namespaced and referenced. +以前は `route.name` と `route.endpoint` の両方で参照されていたルート。 似ていますが、少し違っていました。 これで、すべてのルートは**一貫して** 名前空間と参照されます。 ```text -.[optional:.] +.[optional:] ``` -This new "name" is assigned to the property `route.name`. We are deprecating `route.endpoint`, and will remove that property in v21.9. Until then, it will be an alias for `route.name`. +この新しい "name" はプロパティ `route.name` に割り当てられています。 `route.endpoint` は非推奨となっており、v21.9 でそのプロパティを削除します。 それまでは、`route.name` のエイリアスになります。 -In addition, naming prefixes that had been in use for things like static, websocket, and blueprint routes have been removed. +また、静的、websocket、blueprint ルートなどで使用されていたプレフィックスを削除しました。 -### New decorators +### 新しいデコレーター -Several new convenience decorators to help IDEs with autocomplete. +autocompleteでIDEを支援するいくつかの新しいコンビニエンスデコレータ。 ```python -# Alias to @app.listener("...") +# @app.listener("...") @app.before_server_start -@app.after_server_stop +@app.after_server_start @app.before_server_start @app.after_server_stop -# Alias to @app.middleware("...") +# @app.middleware("...") @app.on_request @app.on_response ``` ### Unquote in route -If you have a route that uses non-ascii characters, Sanic will no longer `unquote` the text for you. You will need to specifically tell the route definition that it should do so. +ASCII以外の文字を使用するルートがある場合、Sanicはテキストを`unquote`ではなくなります。 ルート定義を具体的に伝える必要があります。 ```python @app.route("/overload/", methods=["GET"], unquote=True) @@ -135,11 +135,11 @@ request, response = app.test_client.get("/overload/您好") assert response.text == "OK2 您好" ``` -If you forget to do so, your text will remain encoded. +忘れた場合、テキストはエンコードされたままになります。 -### Alter `Request.match_info` +### `Request.match_info`を変更します -The `match_info` has always provided the data for the matched path parameters. You now have access to modify that, for example in middleware. +`match_info` は常にマッチしたパスパラメータのデータを提供しています。 これで、ミドルウェアなどで変更できるようになりました。 ```python @app.on_request @@ -147,9 +147,9 @@ def convert_to_snake_case(request): request.match_info = to_snake(request.match_info) ``` -### Version types in routes +### バージョンの種類がルートにあります -The `version` argument in routes can now be: +ルート内の `version` 引数は以下のようになります。 - `str` - `int` @@ -161,42 +161,42 @@ The `version` argument in routes can now be: @app.route("/foo", version=2.1) ``` -### Safe method handling with body +### ボディで安全な取り扱い方法 -Route handlers for `GET`, `HEAD`, `OPTIONS` and `DELETE` will not decode any HTTP body passed to it. You can override this: +`GET`、`HEAD`、`OPTIONS`および`DELETE`のルートハンドラは、渡されたHTTPボディをデコードしません。 上書きすることができます： ```python @app.delete(..., ignore_body=False) ``` -### Application, Blueprint and Blueprint Group parity +### アプリケーション、ブループリント、ブループリントグループパリティ -The `Sanic` and `Blueprint` classes share a common base. Previously they duplicated a lot of functionality, that lead to slightly different implementations between them. Now that they both inherit the same base class, developers and plugins should have a more consistent API to work with. +`Sanic`と`Blueprint`クラスは共通のベースを持っています。 以前は、多くの機能を複製しており、それによって実装が若干異なりました。 両方とも同じベースクラスを継承するようになったので、開発者とプラグインにはより一貫性のある API が必要になりました。 -Also, Blueprint Groups now also support common URL extensions like the `version` and `strict_slashes` keyword arguments. +また、ブループリントグループは `version` や `strict_slashes` キーワード引数のような一般的な URL 拡張もサポートするようになりました。 -### Dropped `httpx` from dependencies +### 依存関係から `httpx` をドロップしました -There is no longer a dependency on `httpx`. +`httpx` に依存関係はありません。 -### Removed `testing` library +### `testing`ライブラリを削除しました -Sanic internal testing client has been removed. It is now located in its own repository: [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-testing/). +Sanic 社内テスト クライアントは削除されました。 これは [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) と、それ自身のformat@@0(https\://pypi.org/project/sanic-testing/)にあります。 -If you have `sanic-testing` installed, it will be available and usable on your `Sanic()` application instances as before. So, the **only** change you will need to make is to add `sanic-testing` to your test suite requirements. +`sanic-testing`がインストールされている場合は、以前のように`Sanic()`アプリケーション・インスタンスで利用可能になります。 ですから、**のみ**変更する必要があるのは、テストスイートの要件に`sanic-testing`を追加することです。 -### Application and connection level context (`ctx`) objects +### アプリケーションと接続レベルのコンテキスト (`ctx`) オブジェクト -Version 19.9 [added ](https://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API. This helpful construct easily allows for attaching properties and data to a request object (for example, in middleware), and reusing the information elsewhere int he application. +Version 19.9 format@@0(https\://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API この便利な構文により、リクエストオブジェクトにプロパティやデータを簡単にアタッチすることができます(例えば、 ミドルウェアで)、他の場所でアプリケーション情報を再利用します。 -Similarly, this concept is being extended in two places: +同様に、この概念は2つの場所で拡張されています: -1. the application instance, and -2. a transport connection. +1. アプリケーション・インスタンスと +2. 交通機関の接続だ -#### Application context +#### アプリケーションのコンテキスト -A common use case is to attach properties to the app instance. For the sake of consistency, and to avoid the issue of name collision with Sanic properties, the `ctx` object now exists on `Sanic` instances. +一般的な使用例は、アプリケーションインスタンスにプロパティをアタッチすることです。 整合性のために、Sanic プロパティとの名前の衝突を避けるために、`ctx` オブジェクトは `Sanic` インスタンス上に存在します。 ```python @app.before_server_startup @@ -208,9 +208,9 @@ async def startup_db(app, _): app.ctx.db = await connect_to_db() ``` -#### Connection context +#### 接続の内容 -When a client sends a keep alive header, Sanic will attempt to keep the transport socket [open for a period of time](../deployment/configuration.md#keep-alive-timeout). That transport object now has a `ctx` object available on it. This effectively means that multiple requests from a single client (where the transport layer is being reused) may share state. +クライアントがキープライブヘッダーを送信すると、Sanicはトランスポートソケットをformat@@0(../deployment/configuration.md#keep-alive-timeout) に保持しようとします。 そのトランスポートオブジェクトには`ctx`オブジェクトが用意されています。 これは、(トランスポート層が再利用されている)単一のクライアントからの複数のリクエストが共有されることを意味します。 ```python @app.on_request @@ -225,48 +225,48 @@ async def count_foo(request): ``` ```bash -$ curl localhost:8000 localhost:8000 localhost:8000 +$ curl localhost:8000 localhost:8000 request.conn_info.ctx.foo=1 request.conn_info.ctx.foo=2 request.conn_info.ctx.foo=3 ``` -.. warning:: +.. 警告:: ``` -Connection level context is an experimental feature, and should be finalized in v21.6. +接続レベルのコンテキストは実験的な機能であり、v21.6 で確定する必要があります。 ``` -## News +## ニュース -### A NEW frontpage 🎉 +### 新しいフロントページ 🎉 -We have split the documentation into two. The docstrings inside the codebase will still continue to build sphinx docs to ReadTheDocs. However, it will be limited to API documentation. The new frontpage will house the "Sanic User Guide". +ドキュメントを二つに分割しました。 コードベース内の docstring は ReadTheDocs への sphinx ドキュメントのビルドを継続します。 ただし、API ドキュメントに限定されます。 新しいフロントページには、「サニック・ユーザー・ガイド」が含まれます。 -The new site runs on Vuepress. Contributions are welcome. We also invite help in translating the documents. +新しいサイトはVuepressで動作します。 貢献は歓迎します。 ドキュメントの翻訳にもご協力いただきます。 -As a part of this, we also freshened up the RTD documentation and changed it to API docs only. +その一環として、RTDドキュメントを刷新し、APIドキュメントのみに変更しました。 -### Chat has moved to Discord +### チャットはDiscordに移動しました -The Gitter chatroom has taken one step closer to being phased out. In its place we opened a [Discord server](https://discord.gg/FARQzAEMAA). +Gitterのチャットルームは段階的に廃止されることに一歩近づいた。 その場所でformat@@0(https\://discord.gg/FARQzAEMAA)を開きました。 ### Open Collective -The Sanic Community Organization has [opened a page on Open Collective](https://opencollective.com/sanic-org) to enable anyone that would like to financially support the development of Sanic. +Sanic Community Organization は format@@0(https\://opencollective.com/sanic-org) を開き、Sanic の開発を経済的にサポートしたい人を対象にしています。 -### 2021 Release Managers +### 2021 Release Manager -Thank you to @sjsadowski and @yunstanford for acting as release managers for both 2019 and 2020. This year's release managers are @ahopkins and @vltr. +@sjsadowskiと@yunstanfordに、2019年と2020年のリリースマネージャーを務めていただきありがとうございます。 今年のリリースマネージャーは @ahopkins と @vltr。 -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: -[@ahopkins](https://github.com/ahopkins) [@akshgpt7](https://github.com/akshgpt7) [@artcg](https://github.com/artcg) [@ashleysommer](https://github.com/ashleysommer) [@elis-k](https://github.com/elis-k) [@harshanarayana](https://github.com/harshanarayana) [@sjsadowski](https://github.com/sjsadowski) [@tronic](https://github.com/tronic) [@vltr](https://github.com/vltr), +[@ahopkins](https://github.com/ahopkins) [@akshgpt7](https://github.com/akshgpt7) [@artcg](https://github.com/ashleysommer)[@ashleysommer](https://github.com/ashleysommer) [@elis-k](https://github.com/elisamarayana)[@harshanararayana](https://github.com/harshanarayana)[@sadowski) [@sjsadowski](https://github.com/sjsadowski) -To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for translating our documents into Chinese, +To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) を中国語に翻訳する *** -Make sure to checkout the changelog to get links to all the PRs, etc. +すべてのPRへのリンクなどを取得するには、チェンジログをチェックしてください。 From 0fb94596866faebea2b5f2e741b77b915e5a61d2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:51 +0200 Subject: [PATCH 436/698] New translations v21.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.3.md | 208 +++++++++---------- 1 file changed, 104 insertions(+), 104 deletions(-) diff --git a/guide/content/zh/release-notes/2021/v21.3.md b/guide/content/zh/release-notes/2021/v21.3.md index 2539e750b2..2e343a1ae2 100644 --- a/guide/content/zh/release-notes/2021/v21.3.md +++ b/guide/content/zh/release-notes/2021/v21.3.md @@ -1,18 +1,18 @@ --- -title: Version 21.3 +title: 版本21.3 --- -# Version 21.3 +# 版本21.3 .. toc:: -## Introduction +## 一. 导言 -Sanic is now faster. +现在沙漠化速度更快。 -Well, it already was fast. But with the first iteration of the v21 release, we incorporated a few major milestones that have made some tangible improvements. These encompass some ideas that have been in the works for years, and have finally made it into the released version. +好吧，它已经很快了。 但是，随着二十一世纪会议的第一次复会，我们纳入了几个重大里程碑，这些里程碑已经取得了一些具体的改进。 这些建议包含了多年来一直在工作中的一些想法，并最终将其变成了已经发表的版本。 -.. warning:: Breaking changes +.. 警告：打破更改 ```` Version 21.3 introduces a lot of new features. But, it also includes some breaking changes. This is why these changes were introduced after the last LTS. If you rely upon something that has been removed, you should continue to use v20.12LTS until you are able to upgrade. @@ -25,121 +25,121 @@ pip freeze > requirements.txt For most typical installations, you should be able to upgrade without a problem. ```` -## What to know +## 了解什么 -Notable new or breaking features, and what to upgrade... +显著的新功能或破损功能以及升级内容... -### Python 3.7+ Only +### 仅限Python 3.7+ -This version drops Python 3.6 support. Version 20.12LTS will continue to support Python 3.6 until its EOL in December, 2022, and version 19.12LTS will support it until its EOL in December, 2021. +此版本丢弃了 Python 3.6 支持。 20.12LTS版本将继续支持Python 3.6，直至2022年12月EOL和19版。 2LTS将支持它至2021年12月的EOL。 -Read more about our [LTS policy](../project/policies.md#long-term-support-v-interim-releases). +阅读更多关于我们的 [LTS 政策] (../project/policies.md#long-term support-v-interim-releases). -### Streaming as first class citizen +### 作为一等公民串流 -The biggest speed improvement came from unifying the request/response cycle into a single flow. Previously, there was a difference between regular cycles, and streaming cycles. This has been simplified under the hood, even though the API is staying the same right now for compatibility. The net benefit is that **all** requests now should see a new benefit. +最大的速度提高是将请求/响应周期统一为单一的流程。 以前，正常周期与流周期之间存在着差异。 这已经简化到了它的位置，尽管API 现在保持相同，因为兼容性。 净养恤金是**所有**请求现在都应看到新的养恤金。 -Read more about [streaming changes](../advanced/streaming.md#response-streaming). +阅读更多关于 [串流变化](../advanced/streading.md#response-streaming)。 -### Router overhaul +### 路由器全面检查 -The old Sanic router was based upon regular expressions. In addition it suffered from a number of quirks that made it hard to modify at run time, and resulted in some performance issues. This change has been years in the making and now [converts the router to a compiled tree at startup](https://community.sanicframework.org/t/a-fast-new-router/649/41). Look for additional improvements throughout the year. +旧的Sanic路由器是以正则表达方式为基础的。 此外，它还遇到了一些使得很难在运行时加以修改的问题，并造成了一些业绩问题。 这种变化已经是多年了，现在[在启动时将路由器转换为编译的树](https://community.sanicframework.org/t/a-快速-new-routter/649/41)。 寻求全年的进一步改进。 -The outward facing API has kept backwards compatibility. However, if you were accessing anything inside the router specifically, you many notice some changes. For example: +外置的 API 保持了后向兼容性。 但是，如果你特别访问路由器内的任何东西，你就会注意到一些变化。 例如： -1. `Router.get()` has a new return value -2. `Route` is now a proper class object and not a `namedtuple` -3. If building the router manually, you will need to call `Router.finalize()` before it is usable -4. There is a new `` pattern that can be matched in your routes -5. You cannot startup an application without at least one route defined +1. `Router.get()` 有一个新的返回值 +2. `Route` 现在是一个合适的类对象，而不是一个`namedtuple` +3. 如果手动构建路由器，你需要调用 `Router.finalize()` 方法才能使用 +4. 有一个新的 `` 模式可以匹配到您的路由 +5. 您不能在没有定义至少一个路由的情况下启动应用程序 -The router is now located in its own repository: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-routing/). +路由器现在位于自己的仓库中：[sanic-org/sanic-router](https://github.com/sanic-org/sanic-router)，也是自己的[PyPI上的独立包件](https://pypi.org/project/sanic-routing/)。 ### Signals API ⭐️ -_BETA Feature: API to be finalized in v21.6_ +_BETA 特性：API将在 v21.6_ 中完成 -A side benefit of the new router is that it can do double duty also powering the [new signals API](https://github.com/sanic-org/sanic/issues/1630). This feature is being released for public usage now, and likely the public API will not change in its final form. +新路由器的一个附带好处是，它也可以为[新信号API](https://github.com/sanic-org/sanic/issues/1630)提供双重动力。 此功能正在发布，供公共使用，很可能公共API将不会改变其最终形式。 -The core ideas of this feature are: +这个特点的核心思想是： -1. to allow the developer greater control and access to plugging into the server and request lifecycles, -2. to provide new tools to synchronize and send messages through your application, and -3. to ultimately further increase performance. +1. 允许开发者更多地控制和访问插件到服务器和请求生命周期， +2. 提供新的工具，通过您的应用程序同步和发送消息；以及 +3. 最终进一步提高性能。 -The API introduces three new methods: +API 引入了三种新方法： -- `@app.signal(...)` - For defining a signal handler. It looks and operates very much like a route. Whenever that signal is dispatched, this handler will be executed. -- `app.event(...)` - An awaitable that can be used anywhere in your application to pause execution until the event is triggered. -- `app.dispatch(...)` - Trigger an event and cause the signal handlers to execute. +- `@app.signal(...)` - 定义信号处理器。 它看起来很像一条路线。 每当发出此信号时，此处理程序将被执行。 +- `app.event(...)` - 一个可在应用程序中随时随地用于暂停执行直到事件触发的可待办事宜。 +- `app.signatch(...)` - 触发一个事件并导致信号处理程序被执行。 ```python @app.signal("foo.bar.") -async def signal_handler(thing, **kwargs): - print(f"[signal_handler] {thing=}", kwargs) +async def signal_handler(notes, **kwargs): + print(f)[signal_handler] {thing=}", kwargs) async def wait_for_event(app): while True: - print("> waiting") - await app.event("foo.bar.*") + print("> 等待") + 等待应用。 vent("foo.bar. ") print("> event found\n") -@app.after_server_start -async def after_server_start(app, loop): - app.add_task(wait_for_event(app)) +@app. fter_server_start +async def after _server_start(app, rol): + app. dd_task(wait_for_event(app)) @app.get("/") -async def trigger(request): - await app.dispatch("foo.bar.baz") - return response.text("Done.") +async def 触发器(request): + 等待app.appailch("foo.bar.baz") + return response.text("完成") ``` -### Route naming +### 路由名称 -Routes used to be referenced by both `route.name` and `route.endpoint`. While similar, they were slightly different. Now, all routes will be **consistently** namespaced and referenced. +路由被`route.name`和`route.endpoint`引用. 虽然类似，但它们略有不同。 现在，所有航线都将**前后一致** 命名空间并被引用。 ```text -.[optional:.] +。[可选：。] ``` -This new "name" is assigned to the property `route.name`. We are deprecating `route.endpoint`, and will remove that property in v21.9. Until then, it will be an alias for `route.name`. +这个新的“名称”已分配给属性 "route.name"。 我们正在废弃`route.endpoint`, 并将在 v21.9 中移除该属性。 在此之前，它将是`route.name`的一个别名。 -In addition, naming prefixes that had been in use for things like static, websocket, and blueprint routes have been removed. +此外，为静态、websocket和蓝图路线等事项使用的命名前缀已被删除。 -### New decorators +### 新装饰符 -Several new convenience decorators to help IDEs with autocomplete. +好几个新的方便装饰师帮助IDE自动完成。 ```python -# Alias to @app.listener("...") -@app.before_server_start -@app.after_server_stop -@app.before_server_start +# 别名 @app.listener("...") +@app.befor_server_start @app.after_server_stop +@app.prev_server_stop +@app.after _server_stop -# Alias to @app.middleware("...") +# 别名 @app.midlewarer("...") @app.on_request @app.on_response ``` -### Unquote in route +### 在航线中取消引用 -If you have a route that uses non-ascii characters, Sanic will no longer `unquote` the text for you. You will need to specifically tell the route definition that it should do so. +如果你有一条使用非ascii字符的路由，萨尼克将不再能够为你\`取消引用'。 您需要具体告诉路线定义它应该这样做。 ```python @app.route("/overload/", methods=["GET"], unquote=True) async def handler2(request, param): return text("OK2 " + param) -request, response = app.test_client.get("/overload/您好") -assert response.text == "OK2 您好" +request, response = app. est_client.get("/overload/potsertifle") +power response.text == "OK2 etail" ``` -If you forget to do so, your text will remain encoded. +如果你忘记了这一点，你的文本将保持编码。 -### Alter `Request.match_info` +### 更改 `Request.match_info` -The `match_info` has always provided the data for the matched path parameters. You now have access to modify that, for example in middleware. +`match_info` 始终提供匹配路径参数的数据。 您现在有权修改这一点，例如在中间行程中。 ```python @app.on_request @@ -147,9 +147,9 @@ def convert_to_snake_case(request): request.match_info = to_snake(request.match_info) ``` -### Version types in routes +### 路径中的版本类型 -The `version` argument in routes can now be: +现在路上的 `version` 参数可以是： - `str` - `int` @@ -161,56 +161,56 @@ The `version` argument in routes can now be: @app.route("/foo", version=2.1) ``` -### Safe method handling with body +### 与身体一起安全处理方法 -Route handlers for `GET`, `HEAD`, `OPTIONS` and `DELETE` will not decode any HTTP body passed to it. You can override this: +`GET`、`HEAD`、`OPTIONS`和`DELETE`的路由处理程序将不会解码传递给它的任何HTTP体。 您可以覆盖： ```python @app.delete(..., ignore_body=False) ``` -### Application, Blueprint and Blueprint Group parity +### 应用程序、 蓝图和蓝图组均等性 -The `Sanic` and `Blueprint` classes share a common base. Previously they duplicated a lot of functionality, that lead to slightly different implementations between them. Now that they both inherit the same base class, developers and plugins should have a more consistent API to work with. +`Sanic` 和 `Blueprint` 两个类有一个共同的基础。 以前，它们重复了许多功能，导致它们之间的执行略有不同。 既然他们都继承了相同的基础类，开发者和插件应该有一个更加一致的API。 -Also, Blueprint Groups now also support common URL extensions like the `version` and `strict_slashes` keyword arguments. +另外，蓝图组现在也支持常见的 URL 扩展，例如`version` 和 `strict_slashes` 关键字参数。 -### Dropped `httpx` from dependencies +### 从依赖中丢弃`httpx` -There is no longer a dependency on `httpx`. +不再依赖`httpx`。 -### Removed `testing` library +### 已删除 `testing` 库 -Sanic internal testing client has been removed. It is now located in its own repository: [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) and is also its own [standalone package on PyPI](https://pypi.org/project/sanic-testing/). +Sanic 内部测试客户端已被移除。 它现在位于自己的仓库：[sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing)并且也是自己的[PyPI上独立的软件包](https://pypi.org/project/sanic-testing/)。 -If you have `sanic-testing` installed, it will be available and usable on your `Sanic()` application instances as before. So, the **only** change you will need to make is to add `sanic-testing` to your test suite requirements. +如果您已经安装了 `sanic-testing` ，它将和以前一样在你的 `Sanic()` 应用程序上可用和使用。 因此，您需要做的**仅**更改是将`sanic-testing`添加到您的测试套装要求中。 -### Application and connection level context (`ctx`) objects +### 应用程序和连接级别环境(`ctx`) 对象 -Version 19.9 [added ](https://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API. This helpful construct easily allows for attaching properties and data to a request object (for example, in middleware), and reusing the information elsewhere int he application. +版本19.9 [添加](https://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API。 这个有用的构建可以轻松地将属性和数据附加到请求对象 (例如) 在中间, 并在别处重新使用他所申请的信息。 -Similarly, this concept is being extended in two places: +同样，这一概念正在两个地方扩大： -1. the application instance, and -2. a transport connection. +1. 申请实例和 +2. a 运输连接。 -#### Application context +#### 应用程序上下文： -A common use case is to attach properties to the app instance. For the sake of consistency, and to avoid the issue of name collision with Sanic properties, the `ctx` object now exists on `Sanic` instances. +一个常见的用例是将属性附加到应用实例。 为了一致性并避免名称与 Sanic 属性碰撞的问题，`ctx` 对象现在存在于 `Sanic` 实例中。 ```python @app.before_server_startup async def startup_db(app, _): # WRONG - app.db = await connect_to_db() + app.db = 等待connect_to_db() # CORRECT - app.ctx.db = await connect_to_db() + app.ctx.db = 等待connect_to_db() ``` -#### Connection context +#### 连接环境 -When a client sends a keep alive header, Sanic will attempt to keep the transport socket [open for a period of time](../deployment/configuration.md#keep-alive-timeout). That transport object now has a `ctx` object available on it. This effectively means that multiple requests from a single client (where the transport layer is being reused) may share state. +当客户端发送一个保持生命的头部时，Sanic 会尝试保持传送套接字[打开一段时间](../deplement/configuration.md#keep-live-timeout)。 这个传输对象现在有一个 `ctx` 对象可供使用。 这实际上意味着单个客户端的多次请求（在运输层被重新使用的情况下）可能会共享状态。 ```python @app.on_request @@ -225,48 +225,48 @@ async def count_foo(request): ``` ```bash -$ curl localhost:8000 localhost:8000 localhost:8000 +$ curl localhost:8000 localhost:8000 localhost:8000 localhost:8000 request.conn_info.ctx.foo=1 request.conn_info.ctx.foo=2 -request.conn_info.ctx.foo=3 +request.conn_info.ctx.fo=3 ``` -.. warning:: +.. 警告：: ``` -Connection level context is an experimental feature, and should be finalized in v21.6. +连接级别环境是一个实验功能，应在 v21.6 中最后确定。 ``` -## News +## 新闻 -### A NEW frontpage 🎉 +### 新的首页 🎉 -We have split the documentation into two. The docstrings inside the codebase will still continue to build sphinx docs to ReadTheDocs. However, it will be limited to API documentation. The new frontpage will house the "Sanic User Guide". +我们将文件分成两部分。 代码库内的码头仍将继续构建到 ReadTheDocs 的 Sphinx 文档。 然而，它将仅限于API文档。 新的首页将存放“Sanic 用户指南”。 -The new site runs on Vuepress. Contributions are welcome. We also invite help in translating the documents. +新站点运行于Vuepress。 欢迎提供捐助。 我们还请各方帮助翻译这些文件。 -As a part of this, we also freshened up the RTD documentation and changed it to API docs only. +作为其中的一部分，我们还刷新了RTD文档并将其更改为仅API文档。 -### Chat has moved to Discord +### 聊天已移动到Discord -The Gitter chatroom has taken one step closer to being phased out. In its place we opened a [Discord server](https://discord.gg/FARQzAEMAA). +Gitter chatroom已经朝着逐步淘汰的方向迈出了一步。 在它的位置，我们打开了一个[Discord服务器](https://discord.gg/RARQzAEMAA)。 -### Open Collective +### 开放集团 -The Sanic Community Organization has [opened a page on Open Collective](https://opencollective.com/sanic-org) to enable anyone that would like to financially support the development of Sanic. +萨尼克社区组织[打开了一个开放的集体页面](https://opencollective.com/sanic-org)，以使任何想要资助萨尼克发展的人都能够这样做。 -### 2021 Release Managers +### 2021 发布管理器 -Thank you to @sjsadowski and @yunstanford for acting as release managers for both 2019 and 2020. This year's release managers are @ahopkins and @vltr. +感谢您的 @sjsadowski 和 @yunstanford 担任2019和2020年的释放管理员。 今年的发行经理是 @ahopkins 和 @vltr。 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: -[@ahopkins](https://github.com/ahopkins) [@akshgpt7](https://github.com/akshgpt7) [@artcg](https://github.com/artcg) [@ashleysommer](https://github.com/ashleysommer) [@elis-k](https://github.com/elis-k) [@harshanarayana](https://github.com/harshanarayana) [@sjsadowski](https://github.com/sjsadowski) [@tronic](https://github.com/tronic) [@vltr](https://github.com/vltr), +[@ahopkins](https://github.com/ahopkins) [@akshgpt7](https://github.com/akshgpt7) [@artcg](https://github.com/artcg) [@ashleysommer](https://github.com/ashleysommer)[@elis-k](https://github.com/elis-k) [@harshanarayana](https://github.com/harshanarayana) [@sjsadowski](https://github.com/sjsadowski) [@tronic](https://github.com/tranic) [@vltr](https://github.com/vltr), -To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for translating our documents into Chinese, +[@ConnorZhang](https://github.com/miss85246)和[@ZinkLu](https://github.com/ZinkLu)将我们的文件翻译成中文。 *** -Make sure to checkout the changelog to get links to all the PRs, etc. +确保检查更新日志以获取所有PR等链接。 From a11e860104de7b415ae5423b14c98a6ec0918ce5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:52 +0200 Subject: [PATCH 437/698] New translations v21.6.md (Japanese) --- guide/content/ja/release-notes/2021/v21.6.md | 190 +++++++++---------- 1 file changed, 95 insertions(+), 95 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.6.md b/guide/content/ja/release-notes/2021/v21.6.md index 98453a86f4..fa31c59f6d 100644 --- a/guide/content/ja/release-notes/2021/v21.6.md +++ b/guide/content/ja/release-notes/2021/v21.6.md @@ -1,48 +1,48 @@ --- -title: Version 21.6 +title: バージョン21.6 --- -# Version 21.6 +# バージョン21.6 -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the second release of the version 21 [release cycle](../project/policies.md#release-schedule). There will be one more release in September before version 21 is "finalized" in the December long-term support version. One thing users may have noticed starting in 21.3, the router was moved to its own package: [`sanic-routing`](https://pypi.org/project/sanic-routing). This change is likely to stay for now. Starting with this release, the minimum required version is 0.7.0. +これはバージョン21のformat@@0(../project/polices.md#release-schedule)の2番目のリリースです。 12月の長期サポートバージョンでは、バージョン21が「確定」される前の9月にもう1つのリリースが予定されています。 ユーザーが気づいたことがありますが、21.3からルーターは独自のパッケージに移動されました: [`sanic-routing`](https://pypi.org/project/sanic-routing) この変化は、今のところ続く可能性が高い。 このリリース以降、最低限必要なバージョンは 0.7.0 です。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Deprecation of `StreamingHTTPResponse` +### `StreamingHTTPResponse` の廃止予定 -The use of `StreamingHTTPResponse` has been deprecated and will be removed in the 21.12 release. This impacts both `sanic.response.stream` and `sanic.response.file_stream`, which both under the hood instantiate `StreamingHTTPResponse`. +`StreamingHTTPResponse` の使用は非推奨となり、21.12 リリースで削除されます。 これは、 `Streaming.response.stream` と `sanic.response.file_stream` の両方に影響を与えます。 -Although the exact migration path has yet to be determined, `sanic.response.stream` and `sanic.response.file_stream` will continue to exist in v21.12 in some form as convenience operators. Look for more details throughout this Summer as we hope to have this finalized by the September release. +正確な移行パスはまだ決まっていませんが、`sanic.response.stream` と `sanic.response.file_stream` は、何らかの形でコンビニエンス演算子としてv21.12 に存在し続けます。 9月リリースまでに最終決定を迎えることを望んでいるので、この夏を通じて詳細をご覧ください。 -### Deprecation of `CompositionView` +### `CompositionView` の廃止予定 -Usage of `CompositionView` has been deprecated and will be removed in 21.12. +`CompositionView` の使用は非推奨となり、21.12 で削除されます。 -### Deprecation of path parameter types: `string` and `number` +### パスパラメータ型の非推奨: `string` と `number` -Going forward, you should use `str` and `float` for path param types instead of `string` and `number`. +先に進むには、`string` と `number` の代わりに、パスパラメータの型に `str` と `float` を使用します。 ```python @app.get("//") async def handler(request, foo: str, bar: float): - ... +... ``` -Existing `string` and `number` types are aliased and will continue to work, but will be removed in v21.12. +既存の `string` と `number` 型はエイリアスされ、引き続き動作しますが、v21.12 で削除されます。 -### Version 0.7 router upgrades +### バージョン0.7ルーターのアップグレード -This includes a number of bug fixes and more gracefully handles a wider array of edge cases than v0.6. If you experience any patterns that are not supported, [please report them](https://github.com/sanic-org/sanic-routing/issues). You can see some of the issues resolved on the `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases). +これには数多くのバグ修正が含まれており、v0.6 よりも広範囲のエッジケースをより優雅に処理します。 サポートされていないパターンがあれば、format@@0(https\://github.com/sanic-org/sanic-routing/issues) を報告してください。 `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases) で解決されたいくつかの問題を見ることができます。 -### Inline streaming with `eof()` +### `eof()`でインラインストリーミング -Version 21.3 included [big changes in how streaming is handled](https://sanic.dev/en/guide/release-notes/v21.3.html#what-to-know). The pattern introduced will become the default (see below). As a convenience, a new `response.eof()` method has been included. It should be called once the final data has been pushed to the client: +バージョン21.3にはformat@@0(https\://sanic.dev/ja/guide/release-notes/v21.3.html#what-to-know)が含まれています。 導入されたパターンがデフォルトになります (下記参照)。 便宜上、新しい `response.eof()` メソッドが含まれています。 最終的なデータがクライアントにプッシュされると呼び出されます。 ```python @app.route("/") @@ -54,17 +54,17 @@ async def test(request): return response ``` -### New path parameter type: `slug` +### 新しいパスパラメータタイプ: `slug` -You can now specify a dynamic path segment as a `slug` with appropriate matching: +次のように、適切な一致を持つ`スラグ`として動的パスセグメントを指定できます。 ```python @app.get("/articles/") async def article(request, article_slug: str): - ... +... ``` -Slugs must consist of lowercase letters or digits. They may contain a hyphen (`-`), but it cannot be the first character. +スラッグは小文字または数字で構成されている必要があります。 ハイフン(`-`)を含むことができますが、最初の文字にすることはできません。 ``` this-is-a-slug @@ -74,31 +74,31 @@ NOT-a-slug -NOT-a-slug ``` -### Stricter application and blueprint names, and deprecation +### より厳密なアプリケーションとブループリント名、および廃止予定 -Your application and `Blueprint` instances must conform to a stricter set of requirements: +アプリケーションと `Blueprint` インスタンスは、より厳しい要件セットに準拠する必要があります。 -1. Only consisting of alphanumeric characters -2. May contain a hyphen (`-`) or an underscore (`_`) -3. Must begin with a letter (uppercase or lowercase) +1. 英数字のみで構成されます +2. ハイフン(`-`)またはアンダースコア(`_`)を含めることができます +3. 文字（大文字または小文字）で始まる必要があります -The naming convention is similar to Python variable naming conventions, with the addition of allowing hyphens (`-`). +命名規則は Python の変数命名規則に似ており、ハイフン(`-`)を追加しました。 -The looser standard has been deprecatated. Beginning in 21.12, non-conformance will be a startup time error. +より緩い標準は廃止されました。 21.12 以降、非準拠は起動時エラーとなります。 -### A new access on `Route` object: `route.uri` +### `Route` オブジェクトへの新しいアクセス: `route.uri` -The `Route` object in v21.3 no longer had a `uri` attribute. Instead, the closes you could get was `route.path`. However, because of how `sanic-routing` works, the `path` property does _not_ have a leading `/`. This has been corrected so that now there is a `route.uri` with a leading slash: +v21.3 の `Route` オブジェクトには `uri` 属性がなくなりました。 代わりに、`route.path` がクローズされました。 しかし、`sanic-routing`の仕組みにより、`path`プロパティは先頭の`/`を_持っていません_。 これを修正しました。先頭のスラッシュを持つ `route.uri` があります。 ```python route.uri == f"/{route.path}" ``` -### A new accessor on `Request` object impacting IPs +### IPに影響を与える`Request`オブジェクトの新しいアクセサー -To access the IP address of the incoming request, Sanic has had a convenience accessor on the request object: `request.ip`. That is not new, and comes from an underlying object that provides details about the open HTTP connection: `request.conn_info`. +受け取ったリクエストのIPアドレスにアクセスするために、Sanicはリクエストオブジェクト`request.ip`に利便性の高いアクセサーを持っています。 これは新しいものではなく、オープンな HTTP 接続の詳細を提供する `request.conn_info` から生成されます。 -The current version adds a new `client_ip` accessor to that `conn_info` object. For IPv4, you will not notice a difference. However, for IPv6 applications, the new accessor will provide an "unwrapped" version of the address. Consider the following example: +現在のバージョンは `conn_info` オブジェクトに新しい `client_ip` アクセサーを追加します。 IPv4では違いに気付かないでしょう。 しかし、IPv6アプリケーションの場合、新しいaccessorはアドレスの「未ラップ」バージョンを提供します。 次の例を考えてみましょう: ```python @app.get("/") @@ -124,9 +124,9 @@ $ curl http://\[::1\]:8000 ``` -### Alternate `Config` and `Sanic.ctx` objects +### 代替の `Config` と `Sanic.ctx` オブジェクト -You can now pass your own config and context objects to your Sanic applications. A custom configuration _should_ be a subclass of `sanic.config.Config`. The context object can be anything you want, with no restrictions whatsoever. +Sanic アプリケーションに独自の設定とコンテキストオブジェクトを渡せるようになりました。 カスタム設定\*は、`sanic.config.Config` のサブクラスでなければなりません。 コンテキストオブジェクトは何でも自由に使用でき、制限は一切ありません。 ```python class CustomConfig(Config): @@ -137,7 +137,7 @@ app = Sanic("custom", config=config) assert isinstance(app.config, CustomConfig) ``` -And... +そして... ```python class CustomContext: @@ -148,17 +148,17 @@ app = Sanic("custom", ctx=ctx) assert isinstance(app.ctx, CustomContext) ``` -### Sanic CLI improvements +### Sanic CLI の改善 -1. New flag for existing feature: `--auto-reload` -2. Some new shorthand flags for existing arguments -3. New feature: `--factory` -4. New feature: `--simple` -5. New feature: `--reload-dir` +1. 既存の機能の新しいフラグ: `--auto-reload` +2. 既存の引数の新しい短縮形フラグ +3. 新機能: `--factory` +4. 新機能: `--simple` +5. 新機能: `--reload-dir` -#### Factory applications +#### ファクトリーアプリケーション -For applications that follow the factory pattern (a function that returns a `sanic.Sanic` instance), you can now launch your application from the Sanic CLI using the `--factory` flag. +ファクトリパターンに従ったアプリケーション（`sanic を返す関数）。 anic`インスタンス)、`--factory`フラグを使用して、Sanic CLIからアプリケーションを起動できるようになりました。 ```python from sanic import Blueprint, Sanic, text @@ -175,7 +175,7 @@ def create_app() -> Sanic: return app ``` -You can now run it: +実行できるようになりました： ```bash $ sanic path.to:create_app --factory @@ -183,59 +183,59 @@ $ sanic path.to:create_app --factory #### Sanic Simple Server -Sanic CLI now includes a simple pattern to serve a directory as a web server. It will look for an `index.html` at the directory root. +Sanic CLI には、ディレクトリを Web サーバーとして提供するシンプルなパターンが含まれています。 ディレクトリのルートで `index.html` を探します。 ```bash $ sanic ./path/to/dir --simple ``` -.. warning:: +.. 警告:: ``` -This feature is still in early *beta* mode. It is likely to change in scope. +この機能はまだ初期の *beta* モードです。スコープ内で変更される可能性があります。 ``` -#### Additional reload directories +#### 追加のリロードディレクトリ -When using either `debug` or `auto-reload`, you can include additional directories for Sanic to watch for new files. +`debug` または `auto-reload` を使用する場合、Sanicに新しいファイルを監視するディレクトリを追加することができます。 ```bash -sanic ... --reload-dir=/path/to/foo --reload-dir=/path/to/bar +sanic ... --reload-dir=/path/to/foo -reload-dir=/path/to/bar ``` .. tip:: ``` -You do *NOT* need to include this on your application directory. Sanic will automatically reload when any Python file in your application changes. You should use the `reload-dir` argument when you want to listen and update your application when static files are updated. +アプリケーションディレクトリにこれを含める必要はありません。Sanicはアプリケーション内のPythonファイルが変更されると自動的にリロードされます。 静的ファイルが更新されたときにアプリケーションをリッスンして更新したいときは、 `reload-dir` 引数を使う必要があります。 ``` -### Version prefix +### バージョン接頭辞： -When adding `version`, your route is prefixed with `/v`. This will always be at the beginning of the path. This is not new. +`version` を追加すると、ルートには `/v ` がプレフィックス付きです。 これは常にパスの先頭にあります。 これは、新しいことではありません。 ```python # /v1/my/path app.route("/my/path", version=1) ``` -Now, you can alter the prefix (and therefore add path segments _before_ the version). +これでプレフィックスを変更することができます(したがって、バージョンより前にパスセグメントを追加することができます)。 ```python # /api/v1/my/path app.route("/my/path", version=1, version_prefix="/api/v") ``` -The `version_prefix` argument is can be defined in: +引数 `version_prefix` は以下のように定義できます: -- `app.route` and `bp.route` decorators (and all the convenience decorators also) -- `Blueprint` instantiation -- `Blueprint.group` constructor -- `BlueprintGroup` instantiation -- `app.blueprint` registration +- `app.route` と `bp.route` デコレーター （そしてすべてのコンビニエンスデコレーターも） +- `Blueprint` インスタンス +- `Blueprint.group` コンストラクター +- `BlueprintGroup` インスタンス +- `app.blueprint` 登録 -### Signal event auto-registration +### シグナルイベントの自動登録 -Setting `config.EVENT_AUTOREGISTER` to `True` will allow you to await any signal event even if it has not previously been defined with a signal handler. +`config.EVENT_AUTOREGISTER` を `True` に設定すると、以前にシグナルハンドラで定義されていなくても、シグナルイベントを待つことができます。 ```python @app.signal("do.something.start") @@ -243,29 +243,29 @@ async def signal_handler(): await do_something() await app.dispatch("do.something.complete") -# somethere else in your app: +# あなたのアプリの他の何か: await app.event("do.something.complete") ``` -### Infinitely reusable and nestable `Blueprint` and `BlueprintGroup` +### 無限に再利用可能で安定した `ブループリント` と `ブループリントグループ` -A single `Blueprint` may not be assigned and reused to multiple groups. The groups themselves can also by infinitely nested into one or more other groups. This allows for an unlimited range of composition. +単一の `Blueprint` は割り当てられず、複数のグループに再利用できません。 グループ自体は無限に一つ以上のグループに入れ子にすることもできます。 これにより、無限の範囲のコンポジションが可能になります。 -### HTTP methods as `Enum` +### HTTPメソッド -Sanic now has `sanic.HTTPMethod`, which is an `Enum`. It can be used interchangeably with strings: +Sanic には `sanic.HTTPMethod` があり、これは `Enum` です。 文字列と相互に使用できます: ```python from sanic import Sanic, HTTPMethod @app.route("/", methods=["post", "PUT", HTTPMethod.PATCH]) async def handler(...): - ... +... ``` -### Expansion of `HTTPMethodView` +### `HTTPMethodView` の拡張 -Class based views may be attached now in one of three ways: +クラスベースのビューは、次のいずれかの方法のいずれかで添付できます。 **Option 1 - Existing** @@ -289,47 +289,47 @@ DummyView.attach(app, "/") ```python class DummyView(HTTPMethodView, attach=app, uri="/"): - ... +... ``` -Options 2 and 3 are useful if your CBV is located in another file: +オプション2と3は、CBVが別のファイルにある場合に便利です: ```python from sanic import Sanic, HTTPMethodView class DummyView(HTTPMethodView, attach=Sanic.get_app(), uri="/"): - ... +... ``` -## News +## ニュース -### Discord and support forums +### Discordとサポートフォーラム -If you have not already joined our community, you can become a part by joining the [Discord server](https://discord.gg/FARQzAEMAA) and the [Community Forums](https://community.sanicframework.org/). Also, follow [@sanicframework](https://twitter.com/sanicframework) on Twitter. +まだコミュニティに参加していない場合は、[Discord server](https://discord.gg/FARQzAEMAA)とformat@@0(https\://community.sanicframework.org/)に参加してください。 また、Twitterで[@sanicframework](https://twitter.com/sanicframework)をフォローしてください。 -### SCO 2022 elections +### SCO2022の投票 -The Summer 🏝/Winter ❄️ (choose your Hemisphere) is upon us. That means we will be holding elections for the SCO. This year, we will have the following positions to fill: +Summer :dart_island:/Winter ❄️ (あなたの半球を選んでください) が私たちの前にあります。 つまり、私たちはSCOの選挙を行うことになります。 今年は以下のようなポジションを埋めることができます: -- Steering Council Member (2 year term) -- Steering Council Member (2 year term) -- Steering Council Member (1 year term) -- Release Manager v22 -- Release Manager v22 +- 運営審議会メンバー（2年間） +- 運営審議会メンバー（2年間） +- 運営評議会メンバー（1年） +- リリース マネージャー v22 +- リリース マネージャー v22 -[@vltr](https://github.com/vltr) will be staying on to complete his second year on the Steering Council. +[@vltr](https://github.com/vltr)はステアリング評議会で2年目を迎えます。 -If you are interested in learning more, you can read about the SCO [roles and responsibilities](../project/scope.md#roles-and-responsibilities), or Adam Hopkins on Discord. +詳細を知りたい方は、SCOformat@@0(../project/scope.md#roles-and-responsibities)、またはAdam Hopkins on Discordを読んでください。 -Nominations will begin September 1. More details will be available on the Forums as we get closer. +推薦は9月1日から開始します。 詳細については、フォーラムでご覧いただけます。 -### New project underway +### 新しいプロジェクトが進行中です -We have added a new project to the SCO umbrella: [`sanic-ext`](https://github.com/sanic-org/sanic-ext). It is not yet released, and in heavy active development. The goal for the project will ultimately be to replace [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi) with something that provides more features for web application developers, including input validation, CORS handling, and HTTP auto-method handlers. If you are interested in helping out, let us know on Discord. Look for an initial release of this project sometime (hopefully) before the September release. +SCO傘に新しいプロジェクトを追加しました: [`sanic-ext`](https://github.com/sanic-org/sanic-ext) それはまだリリースされておらず、積極的に開発されています。 プロジェクトのゴールは最終的に[`sanic-openapi`](https://github) を置き換えることです。 om/sanic-org/sanic-openapi) は、入力検証、CORSハンドリング、HTTP自動メソッドハンドラなど、ウェブアプリケーション開発者のためのより多くの機能を提供します。 あなたが助けに興味があるなら、Discordでお知らせください。 9月リリースの前に(うまくいけば)このプロジェクトの最初のリリースを探してください。 -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@aaugustin](https://github.com/aaugustin) [@ahopkins](https://github.com/ahopkins) @@ -349,4 +349,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From d95e987d3f72d73a28b94a3fdb2f19b13ee8f902 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:55 +0200 Subject: [PATCH 438/698] New translations v21.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.6.md | 242 +++++++++---------- 1 file changed, 121 insertions(+), 121 deletions(-) diff --git a/guide/content/zh/release-notes/2021/v21.6.md b/guide/content/zh/release-notes/2021/v21.6.md index 98453a86f4..a9c1fd07e9 100644 --- a/guide/content/zh/release-notes/2021/v21.6.md +++ b/guide/content/zh/release-notes/2021/v21.6.md @@ -1,32 +1,32 @@ --- -title: Version 21.6 +title: 版本21.6 --- -# Version 21.6 +# 版本21.6 .. toc:: -## Introduction +## 一. 导言 -This is the second release of the version 21 [release cycle](../project/policies.md#release-schedule). There will be one more release in September before version 21 is "finalized" in the December long-term support version. One thing users may have noticed starting in 21.3, the router was moved to its own package: [`sanic-routing`](https://pypi.org/project/sanic-routing). This change is likely to stay for now. Starting with this release, the minimum required version is 0.7.0. +这是第二次版本的 21 [发行周期] (../project/policies.md#release-schedule)。 9月份还会有一个版本，然后再在12月份的长期支持版本中“定稿”。 有一件用户可能从21.3开始注意到，路由器被移动到自己的包裹上：[`sanic-routing`](https://pypi.org/project/sanic-routing)。 这种变化现在可能会持续下去。 从发布开始，最低要求版本为 0.7.0。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### Deprecation of `StreamingHTTPResponse` +### 弃用 `StreamingHTTPResponse` -The use of `StreamingHTTPResponse` has been deprecated and will be removed in the 21.12 release. This impacts both `sanic.response.stream` and `sanic.response.file_stream`, which both under the hood instantiate `StreamingHTTPResponse`. +`StreamingHTTPResponse`的使用已被废弃，并将在21.12版本中删除。 这影响到`sanic.response.stream` 和 `sanic.response.file_stream`, 这两者都是在hood instantiate `StreamingHTTPResponse`下发生的。 -Although the exact migration path has yet to be determined, `sanic.response.stream` and `sanic.response.file_stream` will continue to exist in v21.12 in some form as convenience operators. Look for more details throughout this Summer as we hope to have this finalized by the September release. +虽然确切的迁移路径尚待确定，但`sanic.response.stream`和`sanic.response.file_stream`将以某种形式作为方便操作者继续存在。 在今年夏天全天寻找更多细节，因为我们希望在9月份公布之前完成这项工作。 -### Deprecation of `CompositionView` +### 弃用 `ComppositionView` -Usage of `CompositionView` has been deprecated and will be removed in 21.12. +`CompositionView`的用法已被废弃，将在 21.12中删除。 -### Deprecation of path parameter types: `string` and `number` +### 废弃路径参数类型：`string` 和 `number` -Going forward, you should use `str` and `float` for path param types instead of `string` and `number`. +今后你应该使用 `str` 和 `float` 作为路径参数类型，而不是 `string` 和 `number` 。 ```python @app.get("//") @@ -34,71 +34,71 @@ async def handler(request, foo: str, bar: float): ... ``` -Existing `string` and `number` types are aliased and will continue to work, but will be removed in v21.12. +现有的 `string` 和 `num` 类型都是别名并将继续工作，但将在 v21.12中移除。 -### Version 0.7 router upgrades +### 版本0.7路由器升级 -This includes a number of bug fixes and more gracefully handles a wider array of edge cases than v0.6. If you experience any patterns that are not supported, [please report them](https://github.com/sanic-org/sanic-routing/issues). You can see some of the issues resolved on the `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases). +这包括一些错误修复，并且比v0.6更宽松地处理更多的边缘案例。 如果您遇到任何不被支持的模式，[请报告它们](https://github.com/sanic-org/sanic-routing/issues)。 您可以在 `sanic-routing` [发行笔记](https://github.com/sanic-org/sanic-routing/releases)上看到一些问题已经解决。 -### Inline streaming with `eof()` +### 内联 `eof()` -Version 21.3 included [big changes in how streaming is handled](https://sanic.dev/en/guide/release-notes/v21.3.html#what-to-know). The pattern introduced will become the default (see below). As a convenience, a new `response.eof()` method has been included. It should be called once the final data has been pushed to the client: +第21.3版包括[如何处理流媒体的重大变化](https\://sanic.dev/en/guide/release-notes/v21.3.html#what to-know)。 采用的模式将成为缺省模式（见下文）。 为方便起见，列入了一个新的`response.eof()`方法。 一旦最终数据被推送到客户端，它应被调用： ```python @app.route("/") async def test(request): - response = await request.respond(content_type="text/csv") - await response.send("foo,") - await response.send("bar") - await response.eof() - return response + response = request.reply (content_type="text/csv") + 等待应答.send("foo") + 等待应答.send("bar") + 等待应答.eof() + 返回 ``` -### New path parameter type: `slug` +### 新路径参数类型：`slug` -You can now specify a dynamic path segment as a `slug` with appropriate matching: +您现在可以指定一个动态路径段为 `slug` ，并且匹配： ```python @app.get("/articles/") -async def article(request, article_slug: str): - ... +异步文章(请求, article_slug: str): +... ``` -Slugs must consist of lowercase letters or digits. They may contain a hyphen (`-`), but it cannot be the first character. +Slugs必须由小写字母或数字组成。 它们可能含有连字符(`-`)，但不能是第一个字符。 ``` -this-is-a-slug -with-123-is-also-a-slug -111-at-start-is-a-slug +This-a-slug +与 123-is-also a slug +111-at-is-a-slug NOT-a-slug -NOT-a-slug ``` -### Stricter application and blueprint names, and deprecation +### 更严格的应用程序和蓝图名称以及弃用 -Your application and `Blueprint` instances must conform to a stricter set of requirements: +您的应用程序和“蓝图”实例必须符合一套更严格的要求： -1. Only consisting of alphanumeric characters -2. May contain a hyphen (`-`) or an underscore (`_`) -3. Must begin with a letter (uppercase or lowercase) +1. 只包含字母数字字符 +2. 可能包含连线(`-`) 或下划线(`_`) +3. 必须以字母开头(大写或小写) -The naming convention is similar to Python variable naming conventions, with the addition of allowing hyphens (`-`). +命名协议类似于Python变量命名协议，并增加了允许连字符串（`-`）。 -The looser standard has been deprecatated. Beginning in 21.12, non-conformance will be a startup time error. +放松标准已经被拆除。 从21.12开始，不符合同将是启动时间错误。 -### A new access on `Route` object: `route.uri` +### `Route`对象上的新访问权: `route.uri` -The `Route` object in v21.3 no longer had a `uri` attribute. Instead, the closes you could get was `route.path`. However, because of how `sanic-routing` works, the `path` property does _not_ have a leading `/`. This has been corrected so that now there is a `route.uri` with a leading slash: +v21.3中的`路由`对象不再具有`uri`属性。 相反，你可以得到的关卡是“route.path”。 然而，由于`sanic-routing`是如何工作的，因此`path`财产没有`/`的领先地位。 这个问题已经纠正，现在有一个 `route.uri` 带有一个顶部斜线： ```python route.uri == f"/{route.path}" ``` -### A new accessor on `Request` object impacting IPs +### 在 `Request` 对象上的一个新存取器影响IPs -To access the IP address of the incoming request, Sanic has had a convenience accessor on the request object: `request.ip`. That is not new, and comes from an underlying object that provides details about the open HTTP connection: `request.conn_info`. +要访问传入请求的 IP 地址，Sanic 在请求对象上有一个便捷访问器：`request.ip`。 这不是新的，来自一个提供开启HTTP连接详细信息的底层对象：\`request.conn_info'。 -The current version adds a new `client_ip` accessor to that `conn_info` object. For IPv4, you will not notice a difference. However, for IPv6 applications, the new accessor will provide an "unwrapped" version of the address. Consider the following example: +当前版本为`conn_info`对象添加了一个新的`client_ip`访问器。 对于IPv4，您不会发现差异。 然而，对于IPv6应用，新的访问器将提供地址的“卸载”版本。 请考虑以下示例： ```python @app.get("/") @@ -115,29 +115,29 @@ app.run(sock=my_ipv6_sock) ``` ```bash -$ curl http://\[::1\]:8000 -{ - "request.ip": "::1", +$ curl http://\[:1\]:8000 +v. + "request.ip": ":1", "request.conn_info.client": "[::1]", - "request.conn_info.client_ip": "::1" + "request.conn_info.client_ip": ":1" } ``` -### Alternate `Config` and `Sanic.ctx` objects +### 备用的 `Config` 和 `Sanic.ctx` 对象 -You can now pass your own config and context objects to your Sanic applications. A custom configuration _should_ be a subclass of `sanic.config.Config`. The context object can be anything you want, with no restrictions whatsoever. +您现在可以将自己的配置和上下文对象传递到您的 Sanic 应用程序。 自定义配置文件 _应该_ 为子类 `sanic.config.Config` 。 上下文对象可以是你想要的任何东西，没有任何限制。 ```python class CustomConfig(Config): ... -config = CustomConfig() +config= CustomConfig() app = Sanic("custom", config=config) -assert isinstance(app.config, CustomConfig) +configinstance(app.config, CustomConfig) ``` -And... +是... ```python class CustomContext: @@ -145,20 +145,20 @@ class CustomContext: ctx = CustomContext() app = Sanic("custom", ctx=ctx) -assert isinstance(app.ctx, CustomContext) +significance(app.ctx, CustomContext) ``` -### Sanic CLI improvements +### Sanic CLI 改进 -1. New flag for existing feature: `--auto-reload` -2. Some new shorthand flags for existing arguments -3. New feature: `--factory` -4. New feature: `--simple` -5. New feature: `--reload-dir` +1. 现有功能的新标志：`--auto-reload` +2. 现有参数的一些新的简写标记 +3. 新功能：`--factory` +4. 新功能：`--simple` +5. 新功能：`--reload-dir` -#### Factory applications +#### 工厂应用 -For applications that follow the factory pattern (a function that returns a `sanic.Sanic` instance), you can now launch your application from the Sanic CLI using the `--factory` flag. +对于遵循出厂模式的应用程序(函数返回“卫生”函数)。 您现在可以使用 "--factory" 标志从 Sanic CLI 启动您的应用程序。 ```python from sanic import Blueprint, Sanic, text @@ -175,29 +175,29 @@ def create_app() -> Sanic: return app ``` -You can now run it: +您现在可以运行它： ```bash -$ sanic path.to:create_app --factory +$ sanic path.to:create_app --facture ``` -#### Sanic Simple Server +#### Sanic 简单服务器 -Sanic CLI now includes a simple pattern to serve a directory as a web server. It will look for an `index.html` at the directory root. +Sanic CLI 现在包含一个简单的模式，作为一个网络服务器的目录。 它将在目录根目录寻找一个 `index.html` 。 ```bash -$ sanic ./path/to/dir --simple +$ sanic ./path/to/dir --imple ``` -.. warning:: +.. 警告：: ``` -This feature is still in early *beta* mode. It is likely to change in scope. +此功能仍处于早期的 *beta* 模式。它的范围可能会改变。 ``` -#### Additional reload directories +#### 附加重新加载目录 -When using either `debug` or `auto-reload`, you can include additional directories for Sanic to watch for new files. +当使用 `debug` 或 `auto-reload` 时，您可以为Sanic 添加额外的目录以监视新文件。 ```bash sanic ... --reload-dir=/path/to/foo --reload-dir=/path/to/bar @@ -206,68 +206,68 @@ sanic ... --reload-dir=/path/to/foo --reload-dir=/path/to/bar .. tip:: ``` -You do *NOT* need to include this on your application directory. Sanic will automatically reload when any Python file in your application changes. You should use the `reload-dir` argument when you want to listen and update your application when static files are updated. +您的确*不*需要将此内容包含在您的应用程序目录中。当您的应用程序中任何Python文件更改时，Sanic会自动重新加载。 当静态文件更新时，您应该使用 "reload-dir" 参数来监听和更新您的应用程序。 ``` -### Version prefix +### 版本前缀 -When adding `version`, your route is prefixed with `/v`. This will always be at the beginning of the path. This is not new. +当添加 `version` 时，您的路由前缀为 `/v`。 这将永远处于道路的开始。 这并不是新鲜事。 ```python # /v1/my/path app.route("/my/path", version=1) ``` -Now, you can alter the prefix (and therefore add path segments _before_ the version). +现在，您可以更改前缀(因此在\*版本之前添加路径段)。 ```python # /api/v1/my/path app.route("/my/path", version=1, version_prefix="/api/v") ``` -The `version_prefix` argument is can be defined in: +`version_prefix`参数可以定义于： -- `app.route` and `bp.route` decorators (and all the convenience decorators also) -- `Blueprint` instantiation -- `Blueprint.group` constructor -- `BlueprintGroup` instantiation -- `app.blueprint` registration +- `app.route` 和 `bp.route` 装饰符 (也包括所有方便装饰师) +- `Blueprint` 实例 +- `Blueprint.group` 构造函数 +- `BlueprintGroup` 实例 +- `app.bluprint` 注册 -### Signal event auto-registration +### 信号事件自动注册 -Setting `config.EVENT_AUTOREGISTER` to `True` will allow you to await any signal event even if it has not previously been defined with a signal handler. +设置`config.EVENT_AUTOREGISTER`为`True`，将允许您等待任何信号事件，即使它以前没有一个信号处理器来定义。 ```python @app.signal("do.something.start") async def signal_handler(): - await do_something() - await app.dispatch("do.something.complete") + 等待do_something() + 等待app.appailch("do.something.complete") -# somethere else in your app: -await app.event("do.something.complete") +# 在您的应用中其他一些: +等待app.event("do.something.complete") ``` -### Infinitely reusable and nestable `Blueprint` and `BlueprintGroup` +### 无限可复用和可嵌套的 `Blueprint` 和 `BlueprintGroup` -A single `Blueprint` may not be assigned and reused to multiple groups. The groups themselves can also by infinitely nested into one or more other groups. This allows for an unlimited range of composition. +单个的 `Blueprint` 不能分配给多个组。 这些团体本身也可以通过无限期地嵌入一个或多个其他团体。 这允许无限的组合。 -### HTTP methods as `Enum` +### HTTP 方法作为 `Enum` -Sanic now has `sanic.HTTPMethod`, which is an `Enum`. It can be used interchangeably with strings: +Sanic 现在有 `sanic.HTTPMethod`, 它是 `Enum`。 它可以与字符串互换使用： ```python -from sanic import Sanic, HTTPMethod +从 sanic import Sanic, HTTPMethow -@app.route("/", methods=["post", "PUT", HTTPMethod.PATCH]) +@app.route("/", methods=["post", "PUT", HTTPMethod.pATCH]) async def handler(...): - ... +... ``` -### Expansion of `HTTPMethodView` +### 扩展`HTTPMethodView` -Class based views may be attached now in one of three ways: +基于班级的视图现在可以通过以下三种方式之一： -**Option 1 - Existing** +**选项1 - 退出** ```python class DummyView(HTTPMethodView): @@ -276,10 +276,10 @@ class DummyView(HTTPMethodView): app.add_route(DummyView.as_view(), "/dummy") ``` -**Option 2 - From `attach` method** +**选项2 - 从 `attach` 方法** ```python -class DummyView(HTTPMethodView): +DummyView(HTTPMethodView): ... DummyView.attach(app, "/") @@ -288,46 +288,46 @@ DummyView.attach(app, "/") **Option 3 - From class definition at `__init_subclass__`** ```python -class DummyView(HTTPMethodView, attach=app, uri="/"): - ... +DummyView(HTTPMethodView, attach=app, uri="/"): +... ``` -Options 2 and 3 are useful if your CBV is located in another file: +如果您的CBV位于另一个文件中，选项2和3是有用的： ```python -from sanic import Sanic, HTTPMethodView +从 Sanic 导入 Sanic, HTTPMethodView + +类DummyView(HTTPMethodView, attach=Sanic.get_app(), uri="/"): -class DummyView(HTTPMethodView, attach=Sanic.get_app(), uri="/"): - ... ``` -## News +## 新闻 -### Discord and support forums +### Discord 和支持论坛 -If you have not already joined our community, you can become a part by joining the [Discord server](https://discord.gg/FARQzAEMAA) and the [Community Forums](https://community.sanicframework.org/). Also, follow [@sanicframework](https://twitter.com/sanicframework) on Twitter. +如果你还没有加入我们的社区，你可以通过加入 [Discord 服务器] (https\://discord.gg/RARQzAEMAA) 和 [Community Forums](https://community.sanicframework.org/) 来成为一个组成部分。 另外，在Twitter上关注[@sanicframework](https://twitter.com/sanicframework)。 -### SCO 2022 elections +### 上海合作组织2022年选举 -The Summer 🏝/Winter ❄️ (choose your Hemisphere) is upon us. That means we will be holding elections for the SCO. This year, we will have the following positions to fill: +夏季的 🏝️/Winter ❄️ (选择你的Hemisphere) 已经到达我们了。 这意味着我们将举行上海合作组织的选举。 今年，我们将有以下职位要填补： -- Steering Council Member (2 year term) -- Steering Council Member (2 year term) -- Steering Council Member (1 year term) -- Release Manager v22 -- Release Manager v22 +- 指导委员会成员(任期两年) +- 指导委员会成员(任期两年) +- 指导委员会成员（任期一年） +- 发行管理器 v22 +- 发行管理器 v22 -[@vltr](https://github.com/vltr) will be staying on to complete his second year on the Steering Council. +[@vltr](https://github.com/vltr)将继续在指导委员会完成他的第二年。 -If you are interested in learning more, you can read about the SCO [roles and responsibilities](../project/scope.md#roles-and-responsibilities), or Adam Hopkins on Discord. +如果您有兴趣了解更多信息，您可以阅读上海合作组织[角色和责任](../project/scope.md#roles-and-responsibilities)，或Adam Hopkins on Discord。 -Nominations will begin September 1. More details will be available on the Forums as we get closer. +提名将于9月1日开始。 更多详细信息将在论坛上我们更加接近时提供。 -### New project underway +### 新项目正在进行中 -We have added a new project to the SCO umbrella: [`sanic-ext`](https://github.com/sanic-org/sanic-ext). It is not yet released, and in heavy active development. The goal for the project will ultimately be to replace [`sanic-openapi`](https://github.com/sanic-org/sanic-openapi) with something that provides more features for web application developers, including input validation, CORS handling, and HTTP auto-method handlers. If you are interested in helping out, let us know on Discord. Look for an initial release of this project sometime (hopefully) before the September release. +我们在上海合作组织总括中增加了一个新项目：[`sanic-ext`](https://github.com/sanic-org/sanic-ext)。 它尚未释放，正在积极发展。 该项目的目标最终将是替换[`sanic-openapi`](https://github)。 提供更多功能的 web 应用程序开发者的 om/sanic-org/sanic-openapi ，包括输入验证、CORS 处理和HTTP 自动方法处理器。 如果您有兴趣帮助您，请在Discord上告诉我们。 在九月份发布之前的某个时候(希望是)寻找这个项目的初步版本。 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -349,4 +349,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够，[财务贡献](https://opencollective.com/sanic-org/)。 From 84a56208449faaf9aec1ba1f983f7874fadaff8f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:56 +0200 Subject: [PATCH 439/698] New translations v21.9.md (Japanese) --- guide/content/ja/release-notes/2021/v21.9.md | 164 +++++++++---------- 1 file changed, 82 insertions(+), 82 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.9.md b/guide/content/ja/release-notes/2021/v21.9.md index 8b3b8149de..37a6161764 100644 --- a/guide/content/ja/release-notes/2021/v21.9.md +++ b/guide/content/ja/release-notes/2021/v21.9.md @@ -1,77 +1,77 @@ --- -title: Version 21.9 +title: バージョン21.9 --- -# Version 21.9 +# バージョン21.9 -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the third release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will be "finalized" in the December long-term support version release. +これはバージョン21のformat@@0(../../org/policies.md#release-schedule)の3番目のリリースです。 バージョン21は、12月の長期サポートバージョンリリースで「確定」されます。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Removal of config values: `WEBSOCKET_READ_LIMIT`, `WEBSOCKET_WRITE_LIMIT` and `WEBSOCKET_MAX_QUEUE` +### 設定値の削除: `WEBSOCKET_READ_LIMIT`, `WEBSOCKET_WRITE_LIMIT` と `WEBSOCKET_MAX_QUEUE` -With the complete overhaul of the websocket implementation, these configuration values were removed. There currently is not a plan to replace them. +websocket 実装の完全なオーバーホールにより、これらの設定値は削除されました。 現在、それらを交換する計画はありません。 -### Deprecation of default value of `FALLBACK_ERROR_FORMAT` +### `FALLBACK_ERROR_FORMAT` のデフォルト値の非推奨。 -When no error handler is attached, Sanic has used `html` as the fallback format-type. This has been deprecated and will change to `text` starting in v22.3. While the value of this has changed to `auto`, it will still continue to use HTML as the last resort thru v21.12LTS before changing. +エラーハンドラがアタッチされていない場合、Sanicはフォールバックフォーマットタイプに`html`を使用しました。 これは非推奨となり、v22.3 から始まる「text」に変更されます。 この値は `auto` に変更されましたが、変更前の最後の手段として HTML を引き続き使用します。 -### `ErrorHandler.lookup` signature deprecation +### `ErrorHandler.lookup` シグネチャは非推奨です -The `ErrorHandler.lookup` now **requires** two positional arguments: +`ErrorHandler.lookup` は2つの位置引数を\*\*必要とします。 ```python def lookup(self, exception, route_name: Optional[str]): ``` -A non-conforming method will cause Blueprint-specific exception handlers to not properly attach. +準拠していないメソッドを使用すると、ブループリント固有の例外ハンドラが適切にアタッチされなくなります。 -### Reminder of upcoming removals +### 今後の削除の通知 -As a reminder, the following items have already been deprecated, and will be removed in version 21.12LTS +リマインダーとして、以下の項目は既に非推奨となり、バージョン 21.12LTS で削除されます。 - `CompositionView` -- `load_env` (use `env_prefix` instead) -- Sanic objects (application instances, blueprints, and routes) must by alphanumeric conforming to: `^[a-zA-Z][a-zA-Z0-9_\-]*$` -- Arbitrary assignment of objects to application and blueprint instances (use `ctx` instead; removal of this has been bumped from 21.9 to 21.12) +- `load_env` (代わりに `env_prefix` を使用) +- サニック・オブジェクト (アプリケーションのインスタンス、設計図、ルート) は以下の英数字でなければなりません: `^[a-zA-Z][a-zA-Z0-9_\-]*$` +- アプリケーションおよびブループリントインスタンスへのオブジェクトの任意の割り当て（代わりに`ctx`を使用してください。これの削除は21.9から21.12に行われました） -### Overhaul of websockets +### ウェブソケットのオーバーホール -There has been a huge overhaul to the handling of websocket connections. Thanks to [@aaugustin](https://github.com/aaugustin) the [`websockets`](https://websockets.readthedocs.io/en/stable/index.html) now has a new implementation that allows Sanic to handle the I/O of websocket connections on its own. Therefore, Sanic has bumped the minimum version to `websockets>=10.0`. +WebSocket接続の処理には大きなオーバーホールがありました。 [@aaughustin](https://github.com/aaughustin) [`websockets`](https://websockets.readthedocs.io/en/stable/index.html) のおかげで、Sanicがウェブソケット接続のI/Oを独自に処理できるようにする新しい実装が追加されました。 したがって、Sanicは最小のバージョンを`websockets>=10.0`にバンプしました。 -The change should mostly be unnoticeable to developers, except that some of the oddities around websocket handlers in Sanic have been corrected. For example, you now should be able to catch the `CancellError` yourself when someone disconnects: +SanicのWebSocketハンドラに関する奇妙な変更が修正されたことを除いて、ほとんどの変更は開発者にとって目立たないはずです。 たとえば、誰かが切断したときに `CancellError` を自分でキャッチできるようになりました。 ```python @app.websocket("/") -async def handler(request, ws): +async def handler(request, ws: try: while True: await asyncio.sleep(0.25) - except asyncio.CancelledError: + except asyncio.CanceledError: print("User closed connection") ``` -### Built-in signals +### ビルトイン信号 -Version [21.3](./v21.3.md) introduced [signals](../advanced/signals.md). Now, Sanic dispatches signal events **from within the codebase** itself. This means that developers now have the ability to hook into the request/response cycle at a much closer level than before. +バージョン [21.3](./v21.3.md) で [signals](../advanced/signals.md) が導入されました。 Sanicはコードベース内からシグナルイベントを**送信**します。 これにより、開発者は以前よりもずっと近いレベルでリクエスト/レスポンスサイクルをフックすることができます。 -Previously, if you wanted to inject some logic you were limited to middleware. Think of integrated signals as _super_-middleware. The events that are dispatched now include: +以前は、ロジックを注入する場合は、ミドルウェアに限定されていました。 統合された信号を_super_-middlewareと考えてください。 派遣されるイベントは次のとおりです。 -- `http.lifecycle.begin` -- `http.lifecycle.complete` -- `http.lifecycle.exception` -- `http.lifecycle.handle` -- `http.lifecycle.read_body` -- `http.lifecycle.read_head` -- `http.lifecycle.request` -- `http.lifecycle.response` -- `http.lifecycle.send` +- `http.lifycle.begin` +- `http.lifycle.complete` +- `http.lifycle.exception` +- `http.lifycle.handle` +- `http.lifycle.read_body` +- `http.lifycle.read_head` +- `http.lifycle.request` +- `http.lifycle.response` +- `http.lifycle.send` - `http.middleware.after` - `http.middleware.before` - `http.routing.after` @@ -84,14 +84,14 @@ Previously, if you wanted to inject some logic you were limited to middleware. T .. note:: ``` -The `server` signals are the same as the four (4) main server listener events. In fact, those listeners themselves are now just convenience wrappers to signal implementations. +`server` は、4 つの (4) のメインサーバリスナーイベントと同じです。 実際、これらのリスナー自身が実装を知らせるための便利なラッパーになっています。 ``` -### Smarter `auto` exception formatting +### よりスマートな `auto` 例外フォーマット -Sanic will now try to respond with an appropriate exception format based upon the endpoint and the client. For example, if your endpoint always returns a `sanic.response.json` object, then any exceptions will automatically be formatted in JSON. The same is true for `text` and `html` responses. +Sanicはエンドポイントとクライアントに基づいて適切な例外形式で応答しようとします。 たとえば、エンドポイントが `sanic.response.json` オブジェクトを常に返す場合、例外は自動的に JSON でフォーマットされます。 `text`と`html`レスポンスでも同じです。 -Furthermore, you now can _explicitly_ control which formatter to use on a route-by-route basis using the route definition: +さらに、ルート定義を使用してルートごとにどのフォーマッタを使用するかを明示的に制御できるようになりました。 ```python @app.route("/", error_format="json") @@ -99,12 +99,12 @@ async def handler(request): pass ``` -### Blueprint copying +### 建設計画のコピー -Blueprints can be copied to new instances. This will carry forward everything attached to it, like routes, middleware, etc. +設計図は新しいインスタンスにコピーできます。 これにより、ルート、ミドルウェアなど、接続されているすべてのものが転送されます。 ```python -v1 = Blueprint("Version1", version=1) +v1 = 青写真("Version1", version=1) @v1.route("/something") def something(request): @@ -121,34 +121,34 @@ app.blueprint(v2) /v2/something ``` -### Blueprint group convenience methods +### 建設計画グループの便利な方法 -Blueprint groups should now have all of the same methods available to them as regular Blueprints. With this, along with Blueprint copying, Blueprints should now be very composable and flexible. +設計図グループは、通常の設計図と同じ方法をすべて使用できるようになりました。 これにより、ブループリントのコピーとともに、ブループリントは非常に構成可能で柔軟性があります。 -### Accept header parsing +### ヘッダーの解析を承認する -Sanic `Request` objects can parse an `Accept` header to provide an ordered list of the client's content-type preference. You can simply access it as an accessor: +Sanic `Request` オブジェクトは、 `Accept` ヘッダを解析して、クライアントのコンテンツタイプ設定の順序リストを提供することができます。 アクセサリーとしてアクセスできます: ```python print(request.accept) # ["*/*"] ``` -It also is capable of handling wildcard matching. For example, assuming the incoming request included: +また、ワイルドカードマッチングを処理することもできます。 たとえば、受信リクエストが含まれていると仮定します。 ``` -Accept: */* +承認: */* ``` -Then, the following is `True`: +次に、`True`を指定します。 ```python -"text/plain" in request.accept +request.accept の "text/plain" ``` -### Default exception messages +### デフォルトの例外メッセージ -Any exception that derives from `SanicException` can now define a default exception message. This makes it more convenient and maintainable to reuse the same exception in multiple places without running into DRY issues with the message that the exception provides. +`SanicException`に由来する例外は、デフォルトの例外メッセージを定義できるようになりました。 これにより、同じ例外を複数の場所で再利用することがより便利で、例外が提供するメッセージを伴うDRYの問題に巻き込まれることなく、メンテナンス可能になります。 ```python class TeaError(SanicException): @@ -157,68 +157,68 @@ class TeaError(SanicException): raise TeaError ``` -### Type annotation conveniences +### 型注釈の便利さ -It is now possible to control the path parameter types using Python's type annotations. Instead of doing this: +Pythonの型アノテーションを使ってパスパラメータ型を制御できるようになりました。 以下を行う代わりに: ```python @app.route("///") def handler(request: Request, one: int, two: float, three: UUID): - ... +... ``` -You can now simply do this: +これで簡単に行うことができます。 ```python @app.route("///") def handler(request: Request, one: int, two: float, three: UUID): - ... +... ``` -Both of these examples will result in the same routing principles to be applied. +どちらの例でも、同じルーティング原則が適用されます。 -### Explicit static resource type +### 明示的な静的リソースタイプ -You can now explicitly tell a `static` endpoint whether it is supposed to treat the resource as a file or a directory: +リソースをファイルとして扱うかディレクトリとして扱うかどうかを明示的に指定できるようになりました。 ```python static("/", "/path/to/some/file", resource_type="file")) ``` -## News +## ニュース -### Release of `sanic-ext` and deprecation of `sanic-openapi` +### `sanic-ext` のリリースと非推奨の `sanic-openapi` -One of the core principles of Sanic is that it is meant to be a tool, not a dictator. As the frontpage of this website states: +Sanicの主要な原則の一つは、独裁者ではなく、道具であることを意味するということです。 このウェブサイトのフロントページは以下のとおりです。 -> Build the way you want to build without letting your tooling constrain you. +> ツールを使うことで制約がなくても構築方法を構築できます。 -This means that a lot of common features used (specifically by Web API developers) do not exist in the `sanic` repository. This is for good reason. Being unopinionated provides the developer freedom and flexibility. +これは、(特に Web API 開発者によって) 使用される多くの一般的な機能が `sanic` リポジトリに存在しないことを意味します。 これは正当な理由がある。 無関心であることは、開発者の自由と柔軟性を提供します。 -But, sometimes you do not want to have to build and rebuild the same things. Sanic has until now really relied upon the awesome support of the community to fill in the gaps with plugins. +しかし、時々あなたは同じものを構築し、再構築する必要はありません。 Sanicはこれまで、プラグインでギャップを埋めるためにコミュニティの素晴らしいサポートを本当に頼ってきました。 -From the early days, there has been an official `sanic-openapi` package that offered the ability to create OpenAPI documentation based upon your application. But, that project has been plagued over the years and has not been given as much priority as the main project. +初期から公式の `sanic-openapi` パッケージがあり、アプリケーションに基づいて OpenAPI ドキュメントを作成することができました。 しかし、そのプロジェクトは長年にわたって悩まされており、主要プロジェクトほど優先されていません。 -Starting with the release of v21.9, the SCO is deprecating the `sanic-openapi` package and moving it to maintenance mode. This means that it will continue to get updates as needed to maintain it for the current future, but it will not receive any new feature enhancements. +v21.9のリリースから、SCOは`sanic-openapi`パッケージを非推奨にし、メンテナンスモードに移行します。 これは、現在の将来のためにそれを維持するために必要に応じて更新を引き続き取得することを意味します。 しかし、新機能拡張は一切受け付けません。 -A new project called `sanic-ext` is taking its place. This package provides not only the ability to build OAS3 documentation, but fills in many of the gaps that API developers may want in their applications. For example, out of the box it will setup CORS, and auto enable `HEAD` and `OPTIONS` responses where needed. It also has the ability validate incoming data using either standard library Dataclasses or Pydantic models. +`sanic-ext`という新しいプロジェクトが始まっています。 このパッケージは、OAS3ドキュメントを構築する機能だけでなく、 しかし、API 開発者がアプリケーションに求める多くのギャップを埋めます。 例えば、CORSをセットアップし、必要に応じて`HEAD`と`OPTIONS`応答を自動的に有効にします。 また、標準ライブラリDataclassまたはPydanticモデルのいずれかを使用して受信データを検証することもできます。 -The list of goodies includes: +グッズのリストには以下が含まれます: -- CORS protection -- incoming request validation +- CORS保護 +- 受信リクエストの検証 - auto OAS3 documentation using Redoc and/or Swagger UI -- auto `HEAD`, `OPTIONS`, and `TRACE` responses -- dependency injection -- response serialization +- auto `HEAD` 、 `OPTIONS` 、 `TRACE` 応答 +- 依存性インジェクション +- レスポンスシリアライゼーション -This project is still in `alpha` mode for now and is subject to change. While it is considered to be production capable, there may be some need to change the API as we continue to add features. +このプロジェクトは `alpha` モードになっており、変更される可能性があります。 本番環境では対応可能であると考えられていますが、引き続き機能を追加するためにAPIを変更する必要があるかもしれません。 -Checkout the [documentation](../../plugins/sanic-ext/getting-started.md) for more details. +詳細については、 [documentation](../../plugins/sanic-ext/getting-started.md) をチェックアウトしてください。 -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@aaugustin](https://github.com/aaugustin) [@ahopkins](https://github.com/ahopkins) @@ -233,8 +233,8 @@ Thank you to everyone that participated in this release: :clap: [@Tronic](https://github.com/tronic) [@vltr](https://github.com/vltr) -And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. +そして、[@miss85246](https://github.com/miss85246)と[@ZinkLu](https://github.com/ZinkLu)に感謝します。 *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From 03e75e94d4c599c135ef6b12ed6009e9f19f0c8c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:58 +0200 Subject: [PATCH 440/698] New translations v21.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.9.md | 174 +++++++++---------- 1 file changed, 87 insertions(+), 87 deletions(-) diff --git a/guide/content/zh/release-notes/2021/v21.9.md b/guide/content/zh/release-notes/2021/v21.9.md index 8b3b8149de..763e6949f8 100644 --- a/guide/content/zh/release-notes/2021/v21.9.md +++ b/guide/content/zh/release-notes/2021/v21.9.md @@ -1,97 +1,97 @@ --- -title: Version 21.9 +title: 版本21.9 --- -# Version 21.9 +# 版本21.9 .. toc:: -## Introduction +## 一. 导言 -This is the third release of the version 21 [release cycle](../../org/policies.md#release-schedule). Version 21 will be "finalized" in the December long-term support version release. +这是版本21的第三次版本[发行周期](../../org/policies.md#release-schedule)。 版本21将在12月份长期支持版本发布时“最后完成”。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### Removal of config values: `WEBSOCKET_READ_LIMIT`, `WEBSOCKET_WRITE_LIMIT` and `WEBSOCKET_MAX_QUEUE` +### 移除配置值：`WEBSOCKET_READ_LIMIT`、`WEBSOCKET_WRITE_LIMITED `和`WEBSOCKET_MAX_QUEUE` -With the complete overhaul of the websocket implementation, these configuration values were removed. There currently is not a plan to replace them. +随着Web套接字实现的全面整修，这些配置值已被删除。 目前没有计划替换它们。 -### Deprecation of default value of `FALLBACK_ERROR_FORMAT` +### 废弃`FALLBACK_ERROR_FORMAT` 的默认值 -When no error handler is attached, Sanic has used `html` as the fallback format-type. This has been deprecated and will change to `text` starting in v22.3. While the value of this has changed to `auto`, it will still continue to use HTML as the last resort thru v21.12LTS before changing. +当没有错误处理程序被附加时，Sanic使用了“html”作为备用格式类型。 这已被弃用，并将从 v22.3 开始变为`text`。 虽然这个值已经更改为 `auto`，但它仍将继续使用 HTML 作为最后的推力v21.12LTS 才能改变。 -### `ErrorHandler.lookup` signature deprecation +### `ErrorHandler.lookup`签名已弃用 -The `ErrorHandler.lookup` now **requires** two positional arguments: +`ErrorHandler.lookup`现在**需要** 两个位置参数： ```python -def lookup(self, exception, route_name: Optional[str]): +def 查找(自己，例外情况，route_name: 可选[str])： ``` -A non-conforming method will cause Blueprint-specific exception handlers to not properly attach. +不符合同的方法会导致蓝图特定的异常处理程序无法正确附加。 -### Reminder of upcoming removals +### 即将清除的提醒 -As a reminder, the following items have already been deprecated, and will be removed in version 21.12LTS +作为提醒，下列项目已经被废弃，并将在21.12LTS版本中删除 - `CompositionView` -- `load_env` (use `env_prefix` instead) -- Sanic objects (application instances, blueprints, and routes) must by alphanumeric conforming to: `^[a-zA-Z][a-zA-Z0-9_\-]*$` -- Arbitrary assignment of objects to application and blueprint instances (use `ctx` instead; removal of this has been bumped from 21.9 to 21.12) +- `load_env` (使用 `env_prefix` 代替) +- Sanic objects (application instance, blueprints, and routes) must by alphamumeric conforming to `^[a-zA-Z][a-zA-Z0-9_\-]*$` +- 任意将对象分配到应用程序和蓝图实例(代之以使用 `ctx` ；将其移除已从21.9移至21.12) -### Overhaul of websockets +### 重写网上套接字 -There has been a huge overhaul to the handling of websocket connections. Thanks to [@aaugustin](https://github.com/aaugustin) the [`websockets`](https://websockets.readthedocs.io/en/stable/index.html) now has a new implementation that allows Sanic to handle the I/O of websocket connections on its own. Therefore, Sanic has bumped the minimum version to `websockets>=10.0`. +对网络套接字连接的处理进行了大修。 多亏了[@aaugustin](https://github.com/aaaugustin)[websockets`](https://websockets.readthedocs.io/en/stable/index.html)现在有了一个新的安装程序，允许Sanic自行处理Websocket连接的 I/O 。 因此，Sanic已将最小版本变成`websockets>=10.0\` 。 -The change should mostly be unnoticeable to developers, except that some of the oddities around websocket handlers in Sanic have been corrected. For example, you now should be able to catch the `CancellError` yourself when someone disconnects: +这种变化对开发者来说基本上是不明显的，只是一些环绕Sanic网络套接字处理器的困难已经得到纠正。 例如，当有人断开连接时，您现在应该能够抓到自己的 "取消错误"： ```python @app.websocket("/") -async def handler(request, ws): - try: +async def 处理器(请求, w): + 尝试: while True: - await asyncio.sleep(0.25) - except asyncio.CancelledError: - print("User closed connection") + 等待asyncio.sleep(0.25) + 但asyncio.cancelled错误除外: + print("用户闭合连接") ``` -### Built-in signals +### 内置信号 -Version [21.3](./v21.3.md) introduced [signals](../advanced/signals.md). Now, Sanic dispatches signal events **from within the codebase** itself. This means that developers now have the ability to hook into the request/response cycle at a much closer level than before. +Version [21.3](./v21.3.md) introduced [signals](../advanced/signals.md). 现在，Sanic 调度事件**来自codebase** 本身。 这意味着开发人员现在有能力将请求/响应周期绑定到比以往更接近的水平。 -Previously, if you wanted to inject some logic you were limited to middleware. Think of integrated signals as _super_-middleware. The events that are dispatched now include: +之前, 如果你想要注入一些逻辑, 你被限制在中间。 把集成信号看作是_super_-middleware。 现在发出的事件包括： - `http.lifecycle.begin` - `http.lifecycle.complete` -- `http.lifecycle.exception` +- `http.lifecycle.excition` - `http.lifecycle.handle` - `http.lifecycle.read_body` - `http.lifecycle.read_head` - `http.lifecycle.request` - `http.lifecycle.response` - `http.lifecycle.send` -- `http.middleware.after` -- `http.middleware.before` -- `http.routing.after` +- `http.midleware.after ` +- `http.midleware.before` +- `http.routing.after ` - `http.routing.before` -- `server.init.after` +- `server.init.after ` - `server.init.before` -- `server.shutdown.after` +- `server.shutdown.after ` - `server.shutdown.before` -.. note:: +.. 注： ``` -The `server` signals are the same as the four (4) main server listener events. In fact, those listeners themselves are now just convenience wrappers to signal implementations. +服务器信号与四(4)服务器监听器事件相同。 事实上，这些听众本身现在只是表示执行情况的方便。 ``` -### Smarter `auto` exception formatting +### Smarter `auto`异常格式 -Sanic will now try to respond with an appropriate exception format based upon the endpoint and the client. For example, if your endpoint always returns a `sanic.response.json` object, then any exceptions will automatically be formatted in JSON. The same is true for `text` and `html` responses. +Sanic现在将试图根据端点和客户端以适当的例外格式进行回应。 例如，如果您的端点总是返回 `sanic.response.json` 对象，那么任何异常都会自动在 JSON 格式化。 `text`和`html`响应也是如此。 -Furthermore, you now can _explicitly_ control which formatter to use on a route-by-route basis using the route definition: +此外，您现在可以使用 _explicitly_ 控制哪个格式化器在路由基础上使用路由定义： ```python @app.route("/", error_format="json") @@ -99,67 +99,67 @@ async def handler(request): pass ``` -### Blueprint copying +### 蓝图复制 -Blueprints can be copied to new instances. This will carry forward everything attached to it, like routes, middleware, etc. +蓝图可以复制到新的实例。 这将传送附加到它的所有东西，如路线、中间距等。 ```python v1 = Blueprint("Version1", version=1) @v1.route("/something") def something(request): - pass + passe v2 = v1.copy("Version2", version=2) -app.blueprint(v1) -app.blueprint(v2) +app.bluprint(v1) +app.luprint(v2) ``` ``` -/v1/something -/v2/something +/v1/some +/v2/some ``` -### Blueprint group convenience methods +### 蓝图组方便方法 -Blueprint groups should now have all of the same methods available to them as regular Blueprints. With this, along with Blueprint copying, Blueprints should now be very composable and flexible. +蓝图组现在应该拥有与普通蓝图相同的方法。 这样，蓝图连同蓝图复制，现在应该是非常合成和灵活的。 -### Accept header parsing +### 接受页眉解析 -Sanic `Request` objects can parse an `Accept` header to provide an ordered list of the client's content-type preference. You can simply access it as an accessor: +Sanic `Request` 对象可以解析 `Acept` 标题，提供客户端内容类型首选项的顺序列表。 您可以作为配件访问它： ```python -print(request.accept) +打印(request.accept) # ["*/*"] ``` -It also is capable of handling wildcard matching. For example, assuming the incoming request included: +它还能够处理通配符。 例如，假定收到的请求包括： ``` -Accept: */* +接受：*/* ``` -Then, the following is `True`: +然后，以下是`True`： ```python -"text/plain" in request.accept +在请求中接受“文本/平原” ``` -### Default exception messages +### 默认异常消息 -Any exception that derives from `SanicException` can now define a default exception message. This makes it more convenient and maintainable to reuse the same exception in multiple places without running into DRY issues with the message that the exception provides. +来自`SanicExcution`的任何异常现在都可以定义默认异常消息。 这使得在多个地方重新使用相同的异常更方便和更容易操作，而不会在异常所提供的消息中进入DRY问题。 ```python class TeaError(SanicException): message = "Tempest in a teapot" -raise TeaError +raw TeaErrors ``` -### Type annotation conveniences +### 输入批注便利 -It is now possible to control the path parameter types using Python's type annotations. Instead of doing this: +现在可以使用 Python 类型注释来控制路径参数类型。 而不是这样做： ```python @app.route("///") @@ -167,7 +167,7 @@ def handler(request: Request, one: int, two: float, three: UUID): ... ``` -You can now simply do this: +您现在可以简单地这样做： ```python @app.route("///") @@ -175,48 +175,48 @@ def handler(request: Request, one: int, two: float, three: UUID): ... ``` -Both of these examples will result in the same routing principles to be applied. +这两个例子都将导致适用相同的路由原则。 -### Explicit static resource type +### 明确静态资源类型 -You can now explicitly tell a `static` endpoint whether it is supposed to treat the resource as a file or a directory: +您现在可以明确告诉一个 `static` 端点，它是否应该将资源视为一个文件或一个目录： ```python static("/", "/path/to/some/file", resource_type="file")) ``` -## News +## 新闻 -### Release of `sanic-ext` and deprecation of `sanic-openapi` +### 释放`sanic-ext`和废弃`sanic-openapi` -One of the core principles of Sanic is that it is meant to be a tool, not a dictator. As the frontpage of this website states: +萨尼克的核心原则之一是，它是一种工具，而不是独裁者。 该网站的首页称： -> Build the way you want to build without letting your tooling constrain you. +> 构建你想要构建的方式而不让你的工具约束你。 -This means that a lot of common features used (specifically by Web API developers) do not exist in the `sanic` repository. This is for good reason. Being unopinionated provides the developer freedom and flexibility. +这意味着在`sanic` 仓库中不存在很多使用的常见功能(具体来说是由 Web API 开发者使用)。 这是有充分理由的。 不作决定就提供了开发者的自由和灵活性。 -But, sometimes you do not want to have to build and rebuild the same things. Sanic has until now really relied upon the awesome support of the community to fill in the gaps with plugins. +但是，有时你们不想要建造和重建同样的东西。 迄今为止，Sanic确实依靠社区的大力支持来弥补插件的缺口。 -From the early days, there has been an official `sanic-openapi` package that offered the ability to create OpenAPI documentation based upon your application. But, that project has been plagued over the years and has not been given as much priority as the main project. +从最初几天起，就有一个官方的`sanic-openapi`软件包，能够根据您的应用程序创建 OpenAPI 文档。 但是，这个项目多年来一直受到困扰，没有像主要项目那样受到高度重视。 -Starting with the release of v21.9, the SCO is deprecating the `sanic-openapi` package and moving it to maintenance mode. This means that it will continue to get updates as needed to maintain it for the current future, but it will not receive any new feature enhancements. +从发布v21.9开始，上海合作组织正在废弃`sanic-openapi`软件包，并将其移动到维护模式。 这意味着它将继续得到必要的更新，以便为当前的未来保持这种状态。 但它将不会收到任何新的功能强化。 -A new project called `sanic-ext` is taking its place. This package provides not only the ability to build OAS3 documentation, but fills in many of the gaps that API developers may want in their applications. For example, out of the box it will setup CORS, and auto enable `HEAD` and `OPTIONS` responses where needed. It also has the ability validate incoming data using either standard library Dataclasses or Pydantic models. +一个叫做`sanic-ext`的新项目正在取代它。 这个包不仅提供了构建OAS3文档的能力。 但可以填补API开发者在他们的应用程序中可能需要的许多空白。 例如，它将从方框中设置CORS, 并在需要时自动启用 `HEAD` 和 `OPTIONS` 。 它还能够使用标准库基准数或Pydantic模型验证收到的数据。 -The list of goodies includes: +山羊清单包括： -- CORS protection -- incoming request validation -- auto OAS3 documentation using Redoc and/or Swagger UI -- auto `HEAD`, `OPTIONS`, and `TRACE` responses -- dependency injection -- response serialization +- CORS 保护 +- 传入请求验证 +- 使用 Redoc 或 Swagger UI 自动使用 OAS3 文档 +- auto `HEAD`、`OPTIONS`和`TRACE`的回应 +- 依赖输入 +- 响应序列化 -This project is still in `alpha` mode for now and is subject to change. While it is considered to be production capable, there may be some need to change the API as we continue to add features. +此项目现在仍然处于"alpha" 模式，并且可能会被更改。 虽然它被认为是生产能力，但在我们继续添加特性时，可能需要更改API。 -Checkout the [documentation](../../plugins/sanic-ext/getting-started.md) for more details. +签出 [documentation](../../plugins/sanic-ext/getting-started.md) 以了解更多详情。 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -233,8 +233,8 @@ Thank you to everyone that participated in this release: :clap: [@Tronic](https://github.com/tronic) [@vltr](https://github.com/vltr) -And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. +并且，特别感谢你[@miss85246](https://github.com/miss85246)和[@ZinkLu](https://github.com/ZinkLu)做了大量工作，使文档同步并翻译成中文。 *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够，[财务贡献](https://opencollective.com/sanic-org/)。 From 4ce7c0af10b0874d8feff8c9c40f8c7548ee508e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:22:59 +0200 Subject: [PATCH 441/698] New translations v22.12.md (Japanese) --- guide/content/ja/release-notes/2022/v22.12.md | 96 +++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.12.md b/guide/content/ja/release-notes/2022/v22.12.md index 0134d40494..b66e49a84e 100644 --- a/guide/content/ja/release-notes/2022/v22.12.md +++ b/guide/content/ja/release-notes/2022/v22.12.md @@ -1,24 +1,24 @@ --- -title: Version 22.12 (LTS) +title: バージョン 22.12 (LTS) --- -# Version 22.12 (LTS) +# バージョン 22.12 (LTS) -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the final release of the version 22 [release cycle](../../org/policies.md#release-schedule). As such it is a **long-term support** release, and will be supported as stated in the [policies](../../org/policies.md#long-term-support-v-interim-releases). +これはバージョン22format@@0(../../org/polices.md#release-schedule)の最終リリースです。 このようなものは **長期サポート** リリースであり、 [policies](../../org/polices.md#long-term-support-v-interim-releases) で述べられているようにサポートされます。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... ### 🚨 _BREAKING CHANGE_ - Sanic Inspector is now an HTTP server -Sanic v22.9 introduced the [Inspector](./v22.9.md#inspector) to allow live inspection of a running Sanic instance. This feature relied upon opening a TCP socket and communicating over a custom protocol. That basic TCP protocol has been dropped in favor of running a full HTTP service in its place. [Learn more about the Inspector](../deployment/inspector.md). +Sanic v22.9 は、実行中の Sanic インスタンスの実況検査を可能にする [Inspector](./v22.9.md#inspector) を導入しました。 この機能は、TCP ソケットを開き、カスタムプロトコル上で通信する際に依存していました。 その基本的なTCPプロトコルは、その場所で完全なHTTPサービスを実行することを支持しています。 format@@0(../deployment/inspector.md) -The current release introduces a new HTTP server and a refreshed CLI experience. This enables several new features highlighted here. Perhaps the most significant change, however, is to move all of the Inspector's commands to a subparser on the CLI instance. +今回のリリースでは、新しい HTTP サーバーと更新された CLI エクスペリエンスが導入されました。 これにより、ここでハイライトされたいくつかの新機能が有効になります。 しかし、最も重要な変更点は、インスペクターのすべてのコマンドを CLI インスタンスのサブパーサーに移動することです。 ``` $ sanic inspect --help @@ -51,99 +51,99 @@ Optional Run a custom command ``` -#### CLI remote access now available +#### CLIリモートアクセスが利用可能になりました -The `host` and `port` of the Inspector are now explicitly exposed on the CLI as shown above. Previously in v22.9, they were inferred by reference to the application instance. Because of this change, it will be more possible to expose the Inspector on live production instances and access from a remote installation of the CLI. +インスペクタの `host` と `port` は、上記のようにCLIに明示的に公開されます。 以前は v22.9 ではアプリケーションインスタンスを参照して推論されていました。 この変更により、 インスペクターを本番環境のインスタンスに公開し、CLI のリモートインストールからアクセスできるようになります。 -For example, you can check your running production deployment from your local development machine. +たとえば、ローカルの開発マシンから実行中の本番環境を確認できます。 ``` $ sanic inspect --host=1.2.3.4 ``` -.. warning:: +.. 警告:: ``` -For **production** instances, make sure you are _using TLS and authentication_ described below. +**本番環境** の場合は、_TLS と authentication_ が使用されていることを確認してください。 ``` -#### TLS encryption now available +#### TLS 暗号化が利用可能になりました -You can secure your remote Inspector access by providing a TLS certificate to encrypt the web traffic. +Web トラフィックを暗号化する TLS 証明書を提供することで、リモートインスペクターのアクセスを保護できます。 ```python app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" ``` -To access an encrypted installation via the CLI, use the `--secure` flag. +CLI 経由で暗号化されたインストールにアクセスするには、`--secure` フラグを使用します。 ``` $ sanic inspect --secure ``` -#### Authentication now available +#### 認証が利用可能になりました -To control access to the remote Inspector, you can protect the endpoints using an API key. +リモートインスペクターへのアクセスを制御するには、API キーを使用してエンドポイントを保護できます。 ```python app.config.INSPECTOR_API_KEY = "Super-Secret-200" ``` -To access a protected installation via the CLI, use the `--api-key` flag. +CLI 経由で保護されたインストールにアクセスするには、`--api-key` フラグを使用します。 ``` $ sanic inspect --api-key=Super-Secret-200 ``` -This is equivalent to the header: `Authorization: Bearer `. +これは `Authorization: Bearer ` と同じです。 ``` -$ curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +$ curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" ``` -### Scale number of running server workers +### 実行中のサーバーワーカーの数を調整 -The Inspector is now capable of scaling the number of worker processes. For example, to scale to 3 replicas, use the following command: +インスペクターは、ワーカープロセスの数を調整できるようになりました。 例えば、3 つのレプリカにスケーリングするには、次のコマンドを使用します。 ``` $ sanic inspect scale 3 ``` -### Extend Inspector with custom commands +### インスペクタをカスタムコマンドで拡張 -The Inspector is now fully extendable to allow for adding custom commands to the CLI. For more information see [Custom Commands](../deployment/inspector.md#custom-commands). +インスペクターは CLI にカスタムコマンドを追加できるようになりました。 詳細については、[カスタムコマンド](../deployment/inspector.md#custom-commands)を参照してください。 ``` $ sanic inspect foo --bar ``` -### Early worker exit on failure +### 失敗時に早期ワーカー終了 -The process manager shipped with v22.9 had a very short startup timeout. This was to protect against deadlock. This was increased to 30s, and a new mechanism has been added to fail early if there is a crash in a worker process on startup. +v22.9 に同梱されているプロセスマネージャーは、非常に短いスタートアップタイムアウトがありました。 これはデッドロックから守るためだった。 これは30秒に増加しました。 新しいメカニズムが追加されました起動時にワーカープロセスにクラッシュが発生した場合です -### Introduce `JSONResponse` with convenience methods to update a JSON response body +### JSON レスポンスボディを更新するための便利なメソッドを使用して `JSONResponse` を導入する -The `sanic.response.json` convenience method now returns a new subclass of `HTTPResponse` appropriately named: `JSONResponse`. This new type has some convenient methods for handling changes to a response body after its creation. +`sanic.response.json`便利メソッドは、`JSONResponse`という名前の新しいサブクラスを返すようになりました。 この新しいタイプには、レスポンスボディへの変更を作成後に処理するための便利な方法がいくつかあります。 ```python resp = json({"foo": "bar"}) resp.update({"another": "value"}) ``` -See [Returning JSON Data](../basics/response.md#returning-json-data) for more information. +詳細については、[../basics/response.md#returning-json-data] を参照してください。 -### Updates to downstream requirements: `uvloop` and `websockets` +### 下流の要件の更新: `uvloop` と `websockets` -Minimum `uvloop` was set to `0.15.0`. Changes were added to make Sanic compliant with `websockets` version `11.0`. +最小値の `uvloop` を `0.15.0` に設定しました。 Sanic が `websockets` バージョン `11.0` に準拠するように変更を加えました。 -### Force exit on 2nd `ctrl+c` +### `ctrl+c`を強制終了する -On supporting operating systems, the existing behavior is for Sanic server to try to perform a graceful shutdown when hitting `ctrl+c`. This new release will perform an immediate shutdown on subsequent `ctrl+c` after the initial shutdown has begun. +オペレーティングシステムをサポートする場合には、Sanic サーバが `ctrl+c` を押した時に優雅なシャットダウンを試みることが既存の動作です。 この新しいリリースでは、最初のシャットダウンが開始された後に続く「ctrl+c」に対して即座にシャットダウンを実行します。 -### Deprecations and Removals +### 非推奨と削除 -1. _DEPRECATED_ - The `--inspect*` commands introduced in v22.9 have been replaced with a new subcommand parser available as `inspect`. The flag versions will continue to operate until v23.3. You are encouraged to use the replacements. While this short deprecation period is a deviation from the standard two-cycles, we hope this change will be minimally disruptive. +1. _DEPRECATED_ - v22.9 で導入された `--inspect*` コマンドは、`inspect` として利用可能な新しいサブコマンドパーサに置き換えられました。 フラグのバージョンは v23.3 まで動作します。 交換を使用することをお勧めします。 この短い非推奨期間は標準的な2サイクルからの偏差ですが、この変更が最小限に抑えられることを願っています。 ``` OLD sanic ... --inspect NEW sanic ... inspect @@ -158,22 +158,22 @@ On supporting operating systems, the existing behavior is for Sanic server to tr NEW sanic ... inspect shutdown ``` -## News +## ニュース -The Sanic Community Organization will be headed by a new Steering Council for 2023. There are two returning and two new members. +Sanic Community Organizationは2023年の新しい運営会議を率いています。 帰還者は二人、新会員は二人いる。 -[@ahopkins](https://github.com/ahopkins) _returning_ \ -[@prryplatypus](https://github.com/prryplatypus) _returning_ \ -[@sjsadowski](https://github.com/sjsadowski) _NEW_ \ -[@Tronic](https://github.com/Tronic) _NEW_ +[@ahopkins](https://github.com/ahopkins) _returning_ \ +[@prryplatypus](https://github.com/prryplatypus) _returning_ \ +[@sjsadowski](https://github.com/sjsadowski) _NEW_ \ +[@Tronic](https://github.com/Tronic) _NEW_ -The 2023 release managers are [@ahopkins](https://github.com/ahopkins) and [@sjsadowski](https://github.com/sjsadowski). +2023年のリリースマネージャーは[@ahopkins](https://github.com/ahopkins)と[@sjsadowski](https://github.com/sjsadowski)です。 -If you are interested in getting more involved with Sanic, contact us on the [Discord server](https://discord.gg/FARQzAEMAA). +Sanicにもっと関心がある場合は、[Discordサーバー](https://discord.gg/FARQzAEMAA)でご連絡ください。 -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@aaugustin](https://github.com/aaugustin) [@ahopkins](https://github.com/ahopkins) @@ -187,4 +187,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From 566d409b06841653f60d4119d6a9e066541aa093 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:01 +0200 Subject: [PATCH 442/698] New translations v22.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.12.md | 128 +++++++++--------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/guide/content/zh/release-notes/2022/v22.12.md b/guide/content/zh/release-notes/2022/v22.12.md index 0134d40494..5a5b5d0c71 100644 --- a/guide/content/zh/release-notes/2022/v22.12.md +++ b/guide/content/zh/release-notes/2022/v22.12.md @@ -1,24 +1,24 @@ --- -title: Version 22.12 (LTS) +title: 第22.12版 (LTS) --- -# Version 22.12 (LTS) +# 第22.12版 (LTS) .. toc:: -## Introduction +## 一. 导言 -This is the final release of the version 22 [release cycle](../../org/policies.md#release-schedule). As such it is a **long-term support** release, and will be supported as stated in the [policies](../../org/policies.md#long-term-support-v-interim-releases). +这是版本22 的最后版本[发行周期](../../org/policies.md#release-schedule)。 因此，这是一个 **长期支持** 发布，并将按照 [policies]的说明提供支持(../../org/policies.md#long-term support-v-interim-releases)。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### 🚨 _BREAKING CHANGE_ - Sanic Inspector is now an HTTP server +### 🚨 _BREAKING CHANGE_ - Sanic Inspector 现在是一个 HTTP 服务器 -Sanic v22.9 introduced the [Inspector](./v22.9.md#inspector) to allow live inspection of a running Sanic instance. This feature relied upon opening a TCP socket and communicating over a custom protocol. That basic TCP protocol has been dropped in favor of running a full HTTP service in its place. [Learn more about the Inspector](../deployment/inspector.md). +Sanic v22.9 引入了 [Inspector](./v22.9.md#视察员)，以便对运行中的Sanic 实例进行实时检查。 此功能依赖于打开 TCP 套接字和通过自定义协议进行通信。 这个基本TCP协议已被丢弃，转而在它的位置上运行一个完整的HTTP服务。 [了解更多关于检查员的信息](../deplement/spector.md)。 -The current release introduces a new HTTP server and a refreshed CLI experience. This enables several new features highlighted here. Perhaps the most significant change, however, is to move all of the Inspector's commands to a subparser on the CLI instance. +当前版本介绍了一个新的 HTTP 服务器和刷新的 CLI 体验。 这将使这里突出显示的几个新功能。 然而，最重要的变化也许是将检查员的所有命令转移到CLI实例的子解析器。 ``` $ sanic inspect --help @@ -51,140 +51,140 @@ Optional Run a custom command ``` -#### CLI remote access now available +#### CLI 远程访问现在可用 -The `host` and `port` of the Inspector are now explicitly exposed on the CLI as shown above. Previously in v22.9, they were inferred by reference to the application instance. Because of this change, it will be more possible to expose the Inspector on live production instances and access from a remote installation of the CLI. +如上文所示，检查员的`主机`和港口\`现在已经在CLI上明确暴露。 此前在v22.9中，根据申请实例推定。 由于这一变化， 更可能的做法是让检查专员了解现场生产实例和远程安装CLI的访问。 -For example, you can check your running production deployment from your local development machine. +例如，您可以从本地开发机器检查您正在运行的生产部署。 ``` -$ sanic inspect --host=1.2.3.4 +$ sanic inspection --host=1.2.3.4 ``` -.. warning:: +.. 警告：: ``` -For **production** instances, make sure you are _using TLS and authentication_ described below. +在 **production** 实例中，请确保您正在使用 _using TLS and authentification_ 描述如下。 ``` -#### TLS encryption now available +#### TLS 加密现在可用 -You can secure your remote Inspector access by providing a TLS certificate to encrypt the web traffic. +您可以通过提供 TLS 证书来加密网络流量来保护您的远程检查员访问权限。 ```python app.config.INSPECTOR_TLS_CERT = "/path/to/cert.pem" app.config.INSPECTOR_TLS_KEY = "/path/to/key.pem" ``` -To access an encrypted installation via the CLI, use the `--secure` flag. +要通过 CLI 访问加密安装，请使用 "--secure" 标记。 ``` -$ sanic inspect --secure +$ sanic inspection --secure ``` -#### Authentication now available +#### 身份验证现在可用 -To control access to the remote Inspector, you can protect the endpoints using an API key. +要控制远程检查器的访问权限，您可以使用 API 密钥保护终点。 ```python -app.config.INSPECTOR_API_KEY = "Super-Secret-200" +app.config.INSPECTOR_API_KEY = "超级秘书200" ``` -To access a protected installation via the CLI, use the `--api-key` flag. +要通过 CLI 访问受保护的安装，请使用 "--api-key" 标记。 ``` -$ sanic inspect --api-key=Super-Secret-200 +$ sanic inspection --api-key=Super-Secret-200 ``` This is equivalent to the header: `Authorization: Bearer `. ``` -$ curl http://localhost:6457 -H "Authorization: Bearer Super-Secret-200" +$ curl http://localhost:6457-H "Authorization: Morer Super-Secret-200" ``` -### Scale number of running server workers +### 缩放运行服务器员数 -The Inspector is now capable of scaling the number of worker processes. For example, to scale to 3 replicas, use the following command: +检查专员现在能够缩减工人工序的数量。 例如，若要缩放到三个仿真品，请使用以下命令： ``` -$ sanic inspect scale 3 +美元桑色体检查比例 3 ``` -### Extend Inspector with custom commands +### 使用自定义命令扩展检查器 -The Inspector is now fully extendable to allow for adding custom commands to the CLI. For more information see [Custom Commands](../deployment/inspector.md#custom-commands). +检查员现在可以充分扩展，可以将自定义命令添加到CLI。 欲了解更多信息，请查看[自定义命令](../deplement/检查员.md#custom-commands)。 ``` -$ sanic inspect foo --bar +$ sanic inspection foo --bar ``` -### Early worker exit on failure +### 工人在失败时提早退出 -The process manager shipped with v22.9 had a very short startup timeout. This was to protect against deadlock. This was increased to 30s, and a new mechanism has been added to fail early if there is a crash in a worker process on startup. +带有v22.9的流程经理的启动时间非常短。 这是为了防止僵局。 增加到30秒， 而且，如果工人进程启动时发生崩溃，新机制已经增加到早期失败。 -### Introduce `JSONResponse` with convenience methods to update a JSON response body +### 引入`JSONResponse` 并方便更新JSON响应机构 -The `sanic.response.json` convenience method now returns a new subclass of `HTTPResponse` appropriately named: `JSONResponse`. This new type has some convenient methods for handling changes to a response body after its creation. +`sanic.response.json`方便方法现在返回一个新的子类的 `HTTPResponse`：`JSONResponse`。 这种新类型有一些方便的方法来处理一个响应机构创建后的更改。 ```python -resp = json({"foo": "bar"}) +resp = json({"foot": "bar"}) resp.update({"another": "value"}) ``` -See [Returning JSON Data](../basics/response.md#returning-json-data) for more information. +[return JSON Data](../basics/response.md#returning-json-data) 获取更多信息。 -### Updates to downstream requirements: `uvloop` and `websockets` +### 下游需求更新：`uvloop` 和 `websockets` -Minimum `uvloop` was set to `0.15.0`. Changes were added to make Sanic compliant with `websockets` version `11.0`. +最小的 `uvloop` 设置为 `0.15.0` 。 已添加更改，使Sanic 兼容`websockets`11.0\`版本。 -### Force exit on 2nd `ctrl+c` +### 强制退出 2nd `ctrl+c` -On supporting operating systems, the existing behavior is for Sanic server to try to perform a graceful shutdown when hitting `ctrl+c`. This new release will perform an immediate shutdown on subsequent `ctrl+c` after the initial shutdown has begun. +在支持操作系统时，现有的行为是 Sanic 服务器试图在点击 `ctrl+c` 时执行宽松的关机。 这个新版本将在最初关闭后立即关闭 ctrl+c。 -### Deprecations and Removals +### 废弃和移除 -1. _DEPRECATED_ - The `--inspect*` commands introduced in v22.9 have been replaced with a new subcommand parser available as `inspect`. The flag versions will continue to operate until v23.3. You are encouraged to use the replacements. While this short deprecation period is a deviation from the standard two-cycles, we hope this change will be minimally disruptive. +1. _DEPRECATED_ - 在 v22.9 中引入的 `--checkt*` 命令已被一个新的子命令解析器替换为 `expect` 。 旗帜版本将继续运行到 v23.3。 鼓励您使用替换。 虽然这一短暂的废弃期偏离了标准的两周期，但我们希望这种变化能够尽量减少干扰。 ``` - OLD sanic ... --inspect - NEW sanic ... inspect + OLD sanic ... --inspect + new sanic ... Inspection - OLD sanic ... --inspect-raw - NEW sanic ... inspect --raw + OLD sanic . .. --inspect-raw + New sanic ... inspection --raw - OLD sanic ... --inspect-reload - NEW sanic ... inspect reload + OLD sanic . .. --inspect-reload + 新的sanic... 检查重新加载 - OLD sanic ... --inspect-shutdown - NEW sanic ... inspect shutdown + OLD sanic... --inspect-shutdown + 新的sanic... 检查关机 ``` -## News +## 新闻 -The Sanic Community Organization will be headed by a new Steering Council for 2023. There are two returning and two new members. +萨尼克社区组织将由一个新的指导委员会领导，任期为2023年。 有两名返回的成员和两名新成员。 -[@ahopkins](https://github.com/ahopkins) _returning_ \ -[@prryplatypus](https://github.com/prryplatypus) _returning_ \ -[@sjsadowski](https://github.com/sjsadowski) _NEW_ \ -[@Tronic](https://github.com/Tronic) _NEW_ +[@ahopkins](https://github.com/ahopkins) _returning_ +[@prryplatypus](https://github.com/prryplatypus) _returning_ \ +[@sjsadowski](https://github.com/sjsadowski) _NEW_ +[@Tronic](https://github.com/Tronic) _NEW_ -The 2023 release managers are [@ahopkins](https://github.com/ahopkins) and [@sjsadowski](https://github.com/sjsadowski). +2023年版本管理员是：[@ahopkins](https://github.com/ahopkins)和[@sjsadowski](https://github.com/sjsadowski)。 -If you are interested in getting more involved with Sanic, contact us on the [Discord server](https://discord.gg/FARQzAEMAA). +如果您有兴趣更多地参与Sanic，请在[Discord服务器](https://discord.gg/RARQzAEMAA)联系我们。 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: -[@aaugustin](https://github.com/aaugustin) +[@aaugustin](https://github.com/aaaugustin) [@ahopkins](https://github.com/ahopkins) [@ChihweiLHBird](https://github.com/ChihweiLHBird) [@kijk2869](https://github.com/kijk2869) [@LiraNuna](https://github.com/LiraNuna) -[@prryplatypus](https://github.com/prryplatypus) +[@prplatryypus](https://github.com/prryplatypus) [@sjsadowski](https://github.com/sjsadowski) [@todddialpad](https://github.com/todddialpad) -[@Tronic](https://github.com/Tronic) +[@ *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 6df397af585ff4f9bc0a7f5a2df7e8de53953fb0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:02 +0200 Subject: [PATCH 443/698] New translations v22.3.md (Japanese) --- guide/content/ja/release-notes/2022/v22.3.md | 128 +++++++++---------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.3.md b/guide/content/ja/release-notes/2022/v22.3.md index 90efaa047d..b692ee53ba 100644 --- a/guide/content/ja/release-notes/2022/v22.3.md +++ b/guide/content/ja/release-notes/2022/v22.3.md @@ -1,67 +1,67 @@ --- -title: Version 22.3 +title: バージョン22.3 --- -# Version 22.3 +# バージョン22.3 -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the first release of the version 22 [release cycle](../../org/policies.md#release-schedule). All of the standard SCO libraries are now entering the same release cycle and will follow the same versioning pattern. Those packages are: +これはバージョン22format@@0(../../org/polices.md#release-schedule)の最初のリリースです。 すべての標準SCOライブラリが同じリリースサイクルに入り、同じバージョンのパターンに従います。 これらのパッケージは以下のとおりです: - [`sanic-routing`](https://github.com/sanic-org/sanic-routing) - [`sanic-testing`](https://github.com/sanic-org/sanic-testing) - [`sanic-ext`](https://github.com/sanic-org/sanic-ext) -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Application multi-serve +### アプリケーションのマルチ サービス -The Sanic server now has an API to allow you to run multiple applications side-by-side in the same process. This is done by calling `app.prepare(...)` on one or more application instances, one or many times. Each time it should be bound to a unique host/port combination. Then, you begin serving the applications by calling `Sanic.serve()`. +Sanicサーバーには、同じプロセスで複数のアプリケーションを並行して実行できるAPIが追加されました。 これは、1つまたは複数のアプリケーションインスタンスに対して`app.prepare(...)`を呼び出すことによって行われます。 毎回ユニークなホスト/ポートの組み合わせにバインドする必要があります。 次に、`Sanic.serve()`を呼び出してアプリケーションのサービスを開始します。 ```python app = Sanic("One") app2 = Sanic("Two") -app.prepare(port=9999) +app.prepare(port=999999) app.prepare(port=9998) app.prepare(port=9997) -app2.prepare(port=8888) +app2.prepare(port=888888) app2.prepare(port=8887) Sanic.serve() ``` -In the above snippet, there are two applications that will be run concurrently and bound to multiple ports. This feature is _not_ supported in the CLI. +上記のスニペットには、同時に実行され、複数のポートにバインドされる2つのアプリケーションがあります。 この機能は CLI ではサポートされていません。 -This pattern is meant to be an alternative to running `app.run(...)`. It should be noted that `app.run` is now just a shorthand for the above pattern and is still fully supported. +このパターンは、 `app.run(...)` の代わりに使用されます。 `app.run` は上記のパターンの省略形に過ぎず、まだ完全にサポートされていることに注意してください。 -### 👶 _BETA FEATURE_ - New path parameter type: file extensions +### 👶 _BETA FEATURE_ - 新しいパスパラメータタイプ: ファイル拡張子 -A very common pattern is to create a route that dynamically generates a file. The endpoint is meant to match on a file with an extension. There is a new path parameter to match files: ``. +非常に一般的なパターンは、動的にファイルを生成するルートを作成することです。 エンドポイントは、拡張子のあるファイル上で一致するように意図されています。 ファイルに一致する新しいパスパラメータがあります: ``。 ```python @app.get("/path/to/") async def handler(request, filename, ext): - ... +... ``` -This will catch any pattern that ends with a file extension. You may, however want to expand this by specifying which extensions, and also by using other path parameter types for the file name. +これはファイル拡張子で終わるパターンをキャッチします。 ただし、拡張子を指定し、ファイル名に他のパスパラメータ型を使用することで、これを展開することができます。 -For example, if you want to catch a `.jpg` file that is only numbers: +例えば、数字のみの`.jpg`ファイルをキャッチしたい場合: ```python @app.get("/path/to/") async def handler(request, filename, ext): - ... +... ``` -Some potential examples: +いくつかの潜在的な例: -| definition | example | filename | extension | +| 定義 | 例 | ファイル名 | 拡張 | | ---------------------------------- | ----------- | -------- | ---------- | | \ | page.txt | `"page"` | `"txt"` | | \ | cat.jpg | `"cat"` | `"jpg"` | @@ -70,59 +70,59 @@ Some potential examples: | \ | 123.svg | `123` | `"svg"` | | \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | -### 🚨 _BREAKING CHANGE_ - Path parameter matching of non-empty strings +### 🚨 _BREAKING CHANGE_ - パスパラメータの空でない文字列の一致 -A dynamic path parameter will only match on a non-empty string. +動的パスパラメータは空でない文字列にのみマッチします。 -Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now only match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. +以前は、動的な文字列パラメータ (`/` または `/`) を持つルートは、空の文字列を含む任意の文字列にマッチします。 空でない文字列にのみマッチします。 古い動作を保持するには、新しいパラメータ `/ ` を使用します。 ```python @app.get("/path/to/") async def handler(request, foo) - ... +... ``` -### 🚨 _BREAKING CHANGE_ - `sanic.worker.GunicornWorker` has been removed +### 🚨 _BREAKING CHANGE_ - `sanic.worker.GunicornWorker` が削除されました -Departing from our normal deprecation policy, the `GunicornWorker` was removed as a part of the process of upgrading the Sanic server to include multi-serve. This decision was made largely in part because even while it existed it was not an optimal strategy for deploying Sanic. +通常の非推奨ポリシーから離れて、Sanic サーバーをマルチサーブにアップグレードするプロセスの一部として `GunicornWorker` が削除されました。 この決定は、存在している間にも、Sanicを展開するための最適な戦略ではなかったため、主に部分的に行われました。 -If you want to deploy Sanic using `gunicorn`, then you are advised to do it using [the strategy implemented by `uvicorn`](https://www.uvicorn.org/#running-with-gunicorn). This will effectively run Sanic as an ASGI application through `uvicorn`. You can upgrade to this pattern by installing `uvicorn`: +`gunicorn`を使用してSanicをデプロイしたい場合は、format@@0(https\://www\.uvicorn.org/#running-with-gunicorn)を使用して実行することをお勧めします。 これにより、SanicはASGIアプリケーションとして`uvicorn`を通じて効果的に実行されます。 `uvicorn`をインストールすると、このパターンにアップグレードできます。 ``` pip install uvicorn ``` -Then, you should be able to run it with a pattern like this: +次に、次のようなパターンで実行できるはずです。 ``` -gunicorn path.to.sanic:app -k uvicorn.workers.UvicornWorker +gunicorn path.to.sanic:app -k uvicorn.worker.UvicornWorker ``` ### Authorization header parsing -The `Authorization` header has been partially parseable for some time now. You have been able to use `request.token` to gain access to a header that was in one of the following two forms: +The `Authorization` header has been partly parseable for some time. `request.token`を使って、以下の2つの形式のいずれかにあるヘッダーにアクセスできます。 ``` Authorization: Token Authorization: Bearer ``` -Sanic can now parse more credential types like `BASIC`: +Sanic は `BASIC` のようなより多くの資格情報型を解析できるようになりました。 ``` -Authorization: Basic Z2lsLWJhdGVzOnBhc3N3b3JkMTIz +Authorization: Basic Z2lsLWJhdGVzOnBhc3N3b3JkMTiz ``` -This can be accessed now as `request.credentials`: +これは `request.credentials` としてアクセスできるようになりました。 ```python print(request.credentials) -# Credentials(auth_type='Basic', token='Z2lsLWJhdGVzOnBhc3N3b3JkMTIz', _username='gil-bates', _password='password123') +# 資格情報(auth_type='Basic', token='Z2lsLWJhdGVzOnBhc3N3b3JkMTIz', _username='gil-bates', _password='password123') ``` -### CLI arguments optionally injected into application factory +### CLI引数はオプションでアプリケーションファクトリに注入されます -Sanic will now attempt to inject the parsed CLI arguments into your factory if you are using one. +Sanicは、解析されたCLI引数を使用している場合、工場に注入しようとします。 ```python def create_app(args): @@ -133,38 +133,38 @@ def create_app(args): ``` $sanic p:create_app --factory -Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False) +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tlshost=False, works=1, fast=False, access_log=False, debug=False, aut_reload=False, path=Path=False, motd=True, verboss=None, y_exceptions=False) ``` -If you are running the CLI with `--factory`, you also have the option of passing arbitrary arguments to the command, which will be injected into the argument `Namespace`. +`--factory`でCLIを実行している場合は、コマンドに任意の引数を渡すこともできます。 引数`Namespace`に注入されます。 ``` -sanic p:create_app --factory --foo=bar -Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False, foo='bar') +sanic p:create_app --factory -foo=bar +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0. ', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, worker=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noise, noisy_exceptions=False, foo='bar') ``` -### New reloader process listener events +### 新しいリローダープロセスリスナーイベント -When running Sanic server with auto-reload, there are two new events that trigger a listener _only_ on the reloader process: +Sanic サーバーを自動リロードして実行する場合、リローダープロセスで _only_ リスナーをトリガーする 2 つの新しいイベントがあります。 - `reload_process_start` - `reload_process_stop` -These are only triggered if the reloader is running. +これらは、リローダーが実行されている場合にのみトリガーされます。 ```python @app.reload_process_start async def reload_start(*_): - print(">>>>>> reload_start <<<<<<") + print(">>>>>>>> reload_start <<<<<") @app.reload_process_stop -async def reload_stop(*_): - print(">>>>>> reload_stop <<<<<<") +async def reload_stop (*_): + print(">>>>>>>>reload_stop <<<<") ``` -### The event loop is no longer a required argument of a listener +### イベントループはもはやリスナーの必須引数ではありません -You can leave out the `loop` argument of a listener. Both of these examples work as expected: +リスナーの引数 `loop` は省略できます。 これらの例はどちらも期待通りに動作します: ```python @app.before_server_start @@ -173,40 +173,40 @@ async def without(app): @app.before_server_start async def with(app, loop): - ... +... ``` -### Removal - Debug mode does not automatically start the reloader +### 削除 - デバッグモードが自動的にリローダーを開始しません -When running with `--debug` or `debug=True`, the Sanic server will not automatically start the auto-reloader. This feature of doing both on debug was deprecated in v21 and removed in this release. If you would like to have _both_ debug mode and auto-reload, you can use `--dev` or `dev=True`. +`--debug` または `debug=True` で実行している場合、Sanic サーバは自動的にリローダーを起動しません。 このデバッグで両方を行う機能は v21 で非推奨となり、このリリースで削除されました。 \*debug mode と auto-reload の両方を使用したい場合は、 `--dev` または `dev=True` を使用できます。 -**dev = debug mode + auto reloader** +**dev = デバッグモード + auto reloader** -### Deprecation - Loading of lower case environment variables +### Deprecation - 小文字環境変数の読み込み -Sanic loads prefixed environment variables as configuration values. It has not distinguished between uppercase and lowercase as long as the prefix matches. However, it has always been the convention that the keys should be uppercase. This is deprecated and you will receive a warning if the value is not uppercase. In v22.9 only uppercase and prefixed keys will be loaded. +Sanicは接頭辞付きの環境変数を設定値として読み込みます。 プレフィックスが一致している限り、大文字と小文字は区別されません。 ただし、キーは大文字にすべきという慣習は常にありました。 これは非推奨であり、値が大文字でない場合は警告が表示されます。 v22.9では、大文字と接頭辞付きキーのみがロードされます。 -## News +## ニュース -### Packt publishes new book on Sanic web development +### Packt は Sanic Web 開発に関する新しい本を公開 -.. column:: +.. 列:: ``` -There is a new book on **Python Web Development with Sanic** by [@ahopkins](https://github.com/ahopkins). The book is endorsed by the SCO and part of the proceeds of all sales go directly to the SCO for further development of Sanic. +[@ahopkins](https://github.com/ahopkins)による**Python Web Development の新しい本があります。 本書はSCOによって承認されており、すべての売り上げの一部は、Sanicのさらなる発展のためにSCOに直接行きます。 -You can learn more at [sanicbook.com](https://sanicbook.com/) + [sanicbook.com](https://sanicbook.com/) で詳細を学ぶことができます。 ``` -.. column:: +.. 列:: ``` ![Python Web Development with Sanic](https://sanicbook.com/images/SanicCoverFinal.png) ``` -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@aericson](https://github.com/aericson) [@ahankinson](https://github.com/ahankinson) @@ -227,4 +227,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From 72ac8c1cc661af45e543463e6e350cdad14f76d3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:04 +0200 Subject: [PATCH 444/698] New translations v22.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.3.md | 146 +++++++++---------- 1 file changed, 73 insertions(+), 73 deletions(-) diff --git a/guide/content/zh/release-notes/2022/v22.3.md b/guide/content/zh/release-notes/2022/v22.3.md index 90efaa047d..e7d3fd7eea 100644 --- a/guide/content/zh/release-notes/2022/v22.3.md +++ b/guide/content/zh/release-notes/2022/v22.3.md @@ -1,128 +1,128 @@ --- -title: Version 22.3 +title: 22.3 版本 --- -# Version 22.3 +# 22.3 版本 .. toc:: -## Introduction +## 一. 导言 -This is the first release of the version 22 [release cycle](../../org/policies.md#release-schedule). All of the standard SCO libraries are now entering the same release cycle and will follow the same versioning pattern. Those packages are: +这是版本22 [发行周期](../../org/policies.md#release-schedule)的第一次版本。 所有标准的上海合作组织图书馆现在都进入了相同的发布周期，并且将遵循相同的版本模式。 这些一揽子计划是： - [`sanic-routing`](https://github.com/sanic-org/sanic-routing) - [`sanic-testing`](https://github.com/sanic-org/sanic-testing) - [`sanic-ext`](https://github.com/sanic-org/sanic-ext) -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### Application multi-serve +### 应用程序多服务 -The Sanic server now has an API to allow you to run multiple applications side-by-side in the same process. This is done by calling `app.prepare(...)` on one or more application instances, one or many times. Each time it should be bound to a unique host/port combination. Then, you begin serving the applications by calling `Sanic.serve()`. +Sanic 服务器现在有一个 API ，允许您在同一过程中并肩运行多个应用程序。 这是通过在一个或多个应用程序实例上调用 `app.preparere(...)` 做到的，一次或多次。 每次它都应受独特的东道国/港口组合的约束。 然后，你开始使用`Sanic.serve()`来为应用程序服务。 ```python -app = Sanic("One") +App = Sanic("One") app2 = Sanic("Two") -app.prepare(port=9999) -app.prepare(port=9998) -app.prepare(port=9997) -app2.prepare(port=8888) -app2.prepare(port=8887) +app.preparre(port=99999) +app.preparre(port=9998) +app.preparre(port=9997) +app2.preparre(port=888888) +app2.preparre(port=8887) Sanic.serve() ``` -In the above snippet, there are two applications that will be run concurrently and bound to multiple ports. This feature is _not_ supported in the CLI. +在上面的代码片段，有两个应用程序将同时运行并绑定到多个端口。 此功能在 CLI 中_不支持_。 -This pattern is meant to be an alternative to running `app.run(...)`. It should be noted that `app.run` is now just a shorthand for the above pattern and is still fully supported. +这个模式是要替代运行 `app.run(...)` 。 应该注意到，`app.run`现在只是上述模式的一个短语，仍然得到完全支持。 -### 👶 _BETA FEATURE_ - New path parameter type: file extensions +### 👶 _BETA FEATURE_ - 新路径参数类型: 文件扩展 -A very common pattern is to create a route that dynamically generates a file. The endpoint is meant to match on a file with an extension. There is a new path parameter to match files: ``. +一个非常常见的模式是创建一个动态生成文件的路由。 端点是指在文件上与扩展名匹配。 有一个匹配文件的新路径参数：``。 ```python @app.get("/path/to/") -async def handler(request, filename, ext): - ... +async def 处理(请求, 文件名, ext): +... ``` -This will catch any pattern that ends with a file extension. You may, however want to expand this by specifying which extensions, and also by using other path parameter types for the file name. +这将捕获任何以文件扩展名结尾的模式。 然而，您可能想要通过指定哪个扩展名以及使用文件名称的其他路径参数类型来展开这个扩展。 -For example, if you want to catch a `.jpg` file that is only numbers: +例如，如果你想要抓取一个只是数字的 `.jpg` 文件： ```python @app.get("/path/to/") -async def handler(request, filename, ext): - ... +async def 处理(请求, 文件名, ext): +... ``` -Some potential examples: +一些潜在的例子： -| definition | example | filename | extension | -| ---------------------------------- | ----------- | -------- | ---------- | -| \ | page.txt | `"page"` | `"txt"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| 定义 | 示例 | 文件名 | 扩展 | +| ---------------------------------- | ----------- | -------- | ----------- | +| \ | 页次 | `"page"` | `"txt"` | +| \ | jpg | `"cat"` | \`"jpg"" | +| \ | jpg | `"cat"` | \`"jpg"" | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | -### 🚨 _BREAKING CHANGE_ - Path parameter matching of non-empty strings +### 🚨 _Breaking变换_ - 非空字符串路径参数 -A dynamic path parameter will only match on a non-empty string. +动态路径参数只匹配非空字符串。 -Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now only match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. +之前一个带有动态字符串参数的路由(`/` 或 `/`) 将匹配任何字符串，包括空字符串。 现在只匹配一个非空字符串。 要保留旧的行为，您应该使用新的参数类型：`/`。 ```python @app.get("/path/to/") -async def handler(request, foo) - ... +async def 处理器(请求，foo) +... ``` -### 🚨 _BREAKING CHANGE_ - `sanic.worker.GunicornWorker` has been removed +### 🚨 _Breaking变换_ - `sanic.worker.GunicornWorker` 已删除 -Departing from our normal deprecation policy, the `GunicornWorker` was removed as a part of the process of upgrading the Sanic server to include multi-serve. This decision was made largely in part because even while it existed it was not an optimal strategy for deploying Sanic. +“GunicornWorker”背离了我们通常的废弃政策，被移除，作为升级Sanic服务器以包括多服务的过程的一部分。 作出这一决定的部分原因是，即使存在这种决定，也不是部署萨尼克的最佳战略。 -If you want to deploy Sanic using `gunicorn`, then you are advised to do it using [the strategy implemented by `uvicorn`](https://www.uvicorn.org/#running-with-gunicorn). This will effectively run Sanic as an ASGI application through `uvicorn`. You can upgrade to this pattern by installing `uvicorn`: +如果你想使用“gunicorn”来部署Sanic，那么你应该使用[uvicorn`执行的策略](https://www.uvicorn.org/#running-with-gunicorn)来部署Sanic。 这将通过`uvicorn'来有效运行 Sanic。 您可以通过安装 `uvicorn` 来升级到此模式： ``` pip install uvicorn ``` -Then, you should be able to run it with a pattern like this: +然后，你应该能够以这样的模式运行它： ``` gunicorn path.to.sanic:app -k uvicorn.workers.UvicornWorker ``` -### Authorization header parsing +### 授权头正在解析 -The `Authorization` header has been partially parseable for some time now. You have been able to use `request.token` to gain access to a header that was in one of the following two forms: +`Authorization`标题已经部分解析了一段时间。 您可以使用 `request.token` 来获取以下两种形式之一的标题： ``` Authorization: Token Authorization: Bearer ``` -Sanic can now parse more credential types like `BASIC`: +Sanic 现在可以解析更多的凭据类型，如`BASIC`： ``` -Authorization: Basic Z2lsLWJhdGVzOnBhc3N3b3JkMTIz +授权： 基本Z2lsLWJhdGVzOnBhc3N3b3JkMTIz ``` -This can be accessed now as `request.credentials`: +现在可以以 `request.credentials` 的形式访问： ```python print(request.credentials) # Credentials(auth_type='Basic', token='Z2lsLWJhdGVzOnBhc3N3b3JkMTIz', _username='gil-bates', _password='password123') ``` -### CLI arguments optionally injected into application factory +### CLI 参数可选注入到应用程序出厂中 -Sanic will now attempt to inject the parsed CLI arguments into your factory if you are using one. +如果你正在使用解析的 CLI 参数，Sanic 现在会尝试将解析的 CLI 参数注入到工厂。 ```python def create_app(args): @@ -136,35 +136,35 @@ $sanic p:create_app --factory Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False) ``` -If you are running the CLI with `--factory`, you also have the option of passing arbitrary arguments to the command, which will be injected into the argument `Namespace`. +如果你使用 `--factory` 来运行CLI ，你也可以选择将任意参数传递给命令。 它将被注入到参数 `namespace` 。 ``` -sanic p:create_app --factory --foo=bar -Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.1', port=8000, unix='', cert=None, key=None, tls=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False, foo='bar') +sanic p:create_app --factor --foo=bar +Namespace(module='p:create_app', factory=True, simple=False, host='127.0.0.0 ', port=8000, unix='', cert=None, key=None, tlshost=False, workers=1, fast=False, access_log=False, debug=False, auto_reload=False, path=None, dev=False, motd=True, verbosity=None, noisy_exceptions=False, foo='bar') ``` -### New reloader process listener events +### 新的阅读器进程监听器事件 -When running Sanic server with auto-reload, there are two new events that trigger a listener _only_ on the reloader process: +当运行带有自动重新加载的Sanic服务器时，有两个新事件会触发读取器\*仅在读取器过程中触发： - `reload_process_start` - `reload_process_stop` -These are only triggered if the reloader is running. +只有当读取器正在运行时才触发这些。 ```python @app.reload_process_start async def reload_start(*_): - print(">>>>>> reload_start <<<<<<") + print(">>>>>>>>> reload_start <<<<<<<<") @app.reload_process_stop async def reload_stop(*_): - print(">>>>>> reload_stop <<<<<<") + print(">>>>>>>>> reload_stop <<<<<") ``` -### The event loop is no longer a required argument of a listener +### 事件循环不再是监听器的必填参数 -You can leave out the `loop` argument of a listener. Both of these examples work as expected: +你可以忽略监听器的 "循环" 参数。 这两个例子都按预期那样起作用： ```python @app.before_server_start @@ -173,38 +173,38 @@ async def without(app): @app.before_server_start async def with(app, loop): - ... +... ``` -### Removal - Debug mode does not automatically start the reloader +### 删除 - 调试模式不会自动启动读取器 -When running with `--debug` or `debug=True`, the Sanic server will not automatically start the auto-reloader. This feature of doing both on debug was deprecated in v21 and removed in this release. If you would like to have _both_ debug mode and auto-reload, you can use `--dev` or `dev=True`. +当与 `--debug` 或 `debug=True`运行时，Sanic 服务器将不会自动启动自动重新加载器。 这个在调试时同时执行的功能在 v21 中被废弃，并且在这个版本中被删除。 如果你想要_同时_调试模式和自动重新加载，你可以使用 "--dev" 或 "dev=True" 。 -**dev = debug mode + auto reloader** +**dev = 调试模式 + 自动重新加载器** -### Deprecation - Loading of lower case environment variables +### 废弃-加载小写环境变量 -Sanic loads prefixed environment variables as configuration values. It has not distinguished between uppercase and lowercase as long as the prefix matches. However, it has always been the convention that the keys should be uppercase. This is deprecated and you will receive a warning if the value is not uppercase. In v22.9 only uppercase and prefixed keys will be loaded. +Sanic 负载预固定环境变量作为配置值。 只要前缀匹配，它就没有区分大写和小写。 然而，钥匙应当居于首位的始终是公约。 这已被弃用，如果值不是大写，您将收到警告。 在 v22.9 中，只能加载大写和预定的密钥。 -## News +## 新闻 -### Packt publishes new book on Sanic web development +### Packt 出版关于Sanic web 开发的新书 -.. column:: +.. 列: ``` -There is a new book on **Python Web Development with Sanic** by [@ahopkins](https://github.com/ahopkins). The book is endorsed by the SCO and part of the proceeds of all sales go directly to the SCO for further development of Sanic. +在**Python Web Development 与 Sanic** 上有一本由[@ahopkins](https://github.com/ahopkins)编写的新书。 该书得到上海合作组织的认可，所有销售收入的一部分直接送到上海合作组织，以进一步发展萨尼克。 -You can learn more at [sanicbook.com](https://sanicbook.com/) +您可以在 [sanicbook.com](https://sanicbook.com/) 学习更多 ``` -.. column:: +.. 列: ``` ![Python Web Development with Sanic](https://sanicbook.com/images/SanicCoverFinal.png) ``` -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -227,4 +227,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From b73ead640d7aef4683d2c564735a1c9703cffbe4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:05 +0200 Subject: [PATCH 445/698] New translations v22.6.md (Japanese) --- guide/content/ja/release-notes/2022/v22.6.md | 88 ++++++++++---------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.6.md b/guide/content/ja/release-notes/2022/v22.6.md index 73b893c498..a5e418f394 100644 --- a/guide/content/ja/release-notes/2022/v22.6.md +++ b/guide/content/ja/release-notes/2022/v22.6.md @@ -1,24 +1,24 @@ --- -title: Version 22.6 +title: バージョン22.6 --- -# Version 22.6 +# バージョン22.6 -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the second release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. +これはバージョン22のformat@@0(../../org/policies.md#release-schedule)の2番目のリリースです。 バージョン22は、12月の長期サポートバージョンリリースで「確定」されます。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Automatic TLS setup in `DEBUG` mode +### `DEBUG`モードでの自動TLSセットアップ -The Sanic server can automatically setup a TLS certificate using either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). This certificate will enable `https://localhost` (or another local address) for local development environments. You must install either `mkcert` or `trustme` on your own for this to work. +Sanic サーバーは、 [mkcert](https://github.com/FiloSottile/mkcert) または [trustme](https://github.com/python-trio/trustme) を使用して TLS 証明書を自動的にセットアップできます。 この証明書はローカル開発環境で `https://localhost` (または別のローカルアドレス) を有効にします。 これを行うには、 `mkcert` または `trustme` のいずれかを自分でインストールする必要があります。 -.. column:: +.. 列:: ```` ``` @@ -26,7 +26,7 @@ $ sanic path.to.server:app --auto-tls --debug ``` ```` -.. column:: +.. 列:: ```` ```python @@ -34,13 +34,13 @@ app.run(debug=True, auto_tls=True) ``` ```` -This feature is not available when running in `ASGI` mode, or in `PRODUCTION` mode. When running Sanic in production, you should be using a real TLS certificate either purchased through a legitimate vendor, or using [Let's Encrypt](https://letsencrypt.org/). +この機能は `ASGI` モードまたは `PRODUCTION` モードで実行している場合は使用できません。 Sanic を本番環境で実行する場合、正規のベンダー経由で購入した実際の TLS 証明書を使用するか、format@@0(https\://letsencrypt.org/) を使用する必要があります。 ### HTTP/3 Server 🚀 -In June 2022, the IETF finalized and published [RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html), the specification for HTTP/3. In short, HTTP/3 is a **very** different protocol than HTTP/1.1 and HTTP/2 because it implements HTTP over UDP instead of TCP. The new HTTP protocol promises faster webpage load times and solving some of the problems of the older standards. You are encouraged to [read more about](https://http3-explained.haxx.se/) this new web technology. You likely will need to install a [capable client](https://curl.se/docs/http3.html) as traditional tooling will not work. +2022 年6 月に、IETF は、HTTP/3 の仕様である [RFC 9114](https://www.rfc-editor.org/rfc/rfc91114.html) を最終決定し公開しました。 要するに、HTTP/3 は HTTP/1.1 や HTTP/2 とは異なるプロトコルです。なぜなら、TCPの代わりにUDP経由でHTTPを実装するからです。 新しいHTTPプロトコルは、Webページの読み込み時間を短縮し、古い標準のいくつかの問題を解決します。 format@@0(https\://http3-explained.haxx.se/) の新しいウェブテクノロジーを使うことをお勧めします。 従来のツールは動作しないため、format@@0(https\://curl.se/docs/http3.html)をインストールする必要があります。 -Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed: +Sanic server provides HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). **インストールする必要があります** ``` pip install sanic aioquic @@ -50,9 +50,9 @@ pip install sanic aioquic pip install sanic[http3] ``` -To start HTTP/3, you must explicitly request it when running your application. +HTTP/3 を開始するには、アプリケーションの実行時に明示的にリクエストする必要があります。 -.. column:: +.. 列:: ```` ``` @@ -64,7 +64,7 @@ $ sanic path.to.server:app -3 ``` ```` -.. column:: +.. 列:: ```` ```python @@ -72,13 +72,13 @@ app.run(version=3) ``` ```` -To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](./v22.3.html#application-multi-serve) introduced in v22.3. +HTTP/3 と HTTP/1.1 の両方のサーバーを同時に実行するには、v22.3 で導入された [application multi-serve](./v22.3.html#application-multi-serve) を使用します。 -.. column:: +.. 列:: ```` ``` -$ sanic path.to.server:app --http=3 --http=1 +$ sanic path.to.server:app --http=3 -http=1 ``` ``` @@ -86,33 +86,33 @@ $ sanic path.to.server:app -3 -1 ``` ```` -.. column:: +.. 列:: ```` ```python -app.prepre(version=3) +app.preprepre(version=3) app.prepre(version=1) Sanic.serve() ``` ```` -Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. +HTTP/3 は TLS を必要とするため、TLS 証明書なしでは HTTP/3 サーバーを起動できません。 `DEBUG`モードの場合は、format@@0(../how-to/tls.html) または `mkcert` を使用してください。 現在、HTTP/3 に対する自動的な TLS 設定は `trustme` と互換性がありません。 -**👶 This feature is being released as an _EARLY RELEASE FEATURE_.** It is **not** yet fully compliant with the HTTP/3 specification, lacking some features like [websockets](https://websockets.spec.whatwg.org/), [webtransport](https://w3c.github.io/webtransport/), and [push responses](https://http3-explained.haxx.se/en/h3/h3-push). Instead the intent of this release is to bring the existing HTTP request/response cycle towards feature parity with HTTP/3. Over the next several releases, more HTTP/3 features will be added and the API for it finalized. +**👶 This feature is being released as an _EARLY RELEASE FEATURE_.** It is **not** yet fully compliant with the HTTP/3 specification, lacking some features like [websockets](https://websockets.spec.whatwg.org/), [webtransport](https://w3c.github.io/webtransport/), and [push responses](https://http3-explained.haxx.se/en/h3/h3-push). このリリースの意図は、既存の HTTP リクエスト/レスポンスサイクルを HTTP/3 と同等の機能にすることです。 次のいくつかのリリースでは、より多くの HTTP/3 の機能が追加され、そのための API が確定されます。 -### Consistent exception naming +### 一貫性のある例外命名です -Some of the Sanic exceptions have been renamed to be more compliant with standard HTTP response names. +Sanic 例外の一部は、標準の HTTP レスポンス名に準拠するように改名されました。 - `InvalidUsage` >> `BadRequest` - `MethodNotSupported` >> `MethodNotAllowed` - `ContentRangeError` >> `RangeNotSatisfiable` -All old names have been aliased and will remain backwards compatible. +すべての古い名前はエイリアスされており、後方互換性があります。 -### Current request getter +### 現在のリクエスト取得 -Similar to the API to access an application (`Sanic.get_app()`), there is a new method for retrieving the current request when outside of a request handler. +アプリケーション(`Sanic.get_app()`)にアクセスするためのAPIと同様に、リクエストハンドラの外部から現在のリクエストを取得するための新しいメソッドがあります。 ```python from sanic import Request @@ -120,9 +120,9 @@ from sanic import Request Request.get_current() ``` -### Improved API support for setting cache control headers +### キャッシュコントロールヘッダーの設定の API サポートの改善 -The `file` response helper has some added parameters to make it easier to handle setting of the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header. +`file` レスポンスヘルパーには、 [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) ヘッダーの設定を容易にするためのいくつかのパラメータが追加されています。 ```python file( @@ -133,28 +133,28 @@ file( ) ``` -### Custom `loads` function +### カスタムの `loads` 関数 -Just like Sanic supports globally setting a custom `dumps`, you can now set a global custom `loads`. +Sanicがカスタムの`dumps`をグローバルに設定するのと同様に、グローバルにカスタムの`loads`を設定できるようになりました。 ```python -from orjson import loads +from orjson import load app = Sanic("Test", loads=loads) ``` -### Deprecations and Removals +### 非推奨と削除 -1. _REMOVED_ - Applications may no longer opt-out of the application registry -2. _REMOVED_ - Custom exception handlers will no longer run after some part of an exception has been sent -3. _REMOVED_ - Fallback error formats cannot be set on the `ErrorHandler` and must **only** be set in the `Config` -4. _REMOVED_ - Setting a custom `LOGO` for startup is no longer allowed -5. _REMOVED_ - The old `stream` response convenience method has been removed -6. _REMOVED_ - `AsyncServer.init` is removed and no longer an alias of `AsyncServer.app.state.is_started` +1. _削除_ - アプリケーションはもはやアプリケーションレジストリからオプトアウトされない可能性があります +2. _REMOVED_ - 一部の例外が送信された後、カスタム例外ハンドラは実行されなくなります +3. _削除_ - フォールバックエラーフォーマットは `ErrorHandler` には設定できません。`Config` で**のみ**設定する必要があります +4. _削除_ - スタートアップ用のカスタム `LOGO` の設定はもう許可されていません +5. _REMOVED_ - 古い`stream`レスポンスの利便性メソッドが削除されました +6. _REMOVED_ - `AsyncServer.init` は削除され、`AsyncServer.app.state.is_started` のエイリアスは削除されました。 -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@ahopkins](https://github.com/ahopkins) [@amitay87](https://github.com/amitay87) @@ -170,4 +170,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From e0e51847f23d7b5e84f5831c58ae91e17d723e3b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:07 +0200 Subject: [PATCH 446/698] New translations v22.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.6.md | 102 +++++++++---------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/guide/content/zh/release-notes/2022/v22.6.md b/guide/content/zh/release-notes/2022/v22.6.md index 73b893c498..d20a5349db 100644 --- a/guide/content/zh/release-notes/2022/v22.6.md +++ b/guide/content/zh/release-notes/2022/v22.6.md @@ -1,24 +1,24 @@ --- -title: Version 22.6 +title: 22.6 版本 --- -# Version 22.6 +# 22.6 版本 .. toc:: -## Introduction +## 一. 导言 -This is the second release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. +这是第二次版本的 22 [发行周期] (../../org/policies.md#release-schedule)。 版本22将在12月份的长期支持版本发布时“最后完成”。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### Automatic TLS setup in `DEBUG` mode +### `DEBUG`模式下自动设置TLS -The Sanic server can automatically setup a TLS certificate using either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). This certificate will enable `https://localhost` (or another local address) for local development environments. You must install either `mkcert` or `trustme` on your own for this to work. +Sanic 服务器可以使用 [mkcert](https://github.com/FiloSottile/mkcert) 或 [trustme](https://github.com/python-trio/trustme) 自动设置一个 TLS 证书。 此证书将启用本地开发环境的`https://localhost`(或另一个本地地址)。 您必须自己安装 `mkcert` 或 `trustme` 才能正常工作。 -.. column:: +.. 列: ```` ``` @@ -26,21 +26,21 @@ $ sanic path.to.server:app --auto-tls --debug ``` ```` -.. column:: +.. 列: ```` ```python app.run(debug=True, auto_tls=True) -``` + ```` -This feature is not available when running in `ASGI` mode, or in `PRODUCTION` mode. When running Sanic in production, you should be using a real TLS certificate either purchased through a legitimate vendor, or using [Let's Encrypt](https://letsencrypt.org/). +在`ASGI`模式或`PRODUCTION`模式下运行时，此功能不可用。 当在生产中运行 Sanic时，您应该使用真正的TLS 证书，要么通过合法的供应商购买，要么使用[我们的加密](https://letsenccrypt.org/)。 -### HTTP/3 Server 🚀 +### HTTP/3 Server :ro火箭： -In June 2022, the IETF finalized and published [RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html), the specification for HTTP/3. In short, HTTP/3 is a **very** different protocol than HTTP/1.1 and HTTP/2 because it implements HTTP over UDP instead of TCP. The new HTTP protocol promises faster webpage load times and solving some of the problems of the older standards. You are encouraged to [read more about](https://http3-explained.haxx.se/) this new web technology. You likely will need to install a [capable client](https://curl.se/docs/http3.html) as traditional tooling will not work. +2022年6月，国际电子交易日志最后确定并出版了HTTP/3规格[RFC 9114](https://www.rfc-editor.org/rfc/rfc9114.html)。 简而言之，HTTP/3 是一个**所有**不同于HTTP/1.1和HTTP-2的协议，因为它使用 UDP而不是TCP 新的 HTTP 协议保证更快的网页加载时间和解决旧标准的一些问题。 你被鼓励[阅读更多关于](https://http3-explanined.haxx.se/)这个新的网页技术。 您可能需要安装一个[能够的客户端](https://curl.se/docs/http3.html)，因为传统的工具将无法工作。 -Sanic server offers HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). This **must** be installed: +Sanic 服务器使用 [aioquic](https://github.com/aiortc/aioquic) 提供 HTTP/3 支持。 此 \*\*must \*\* 已安装： ``` pip install sanic aioquic @@ -50,12 +50,12 @@ pip install sanic aioquic pip install sanic[http3] ``` -To start HTTP/3, you must explicitly request it when running your application. +要启动 HTTP/3，您必须在运行应用程序时明确请求它。 -.. column:: +.. 列: ```` -``` +`` $ sanic path.to.server:app --http=3 ``` @@ -64,7 +64,7 @@ $ sanic path.to.server:app -3 ``` ```` -.. column:: +.. 列: ```` ```python @@ -72,12 +72,12 @@ app.run(version=3) ``` ```` -To run both an HTTP/3 and HTTP/1.1 server simultaneously, you can use [application multi-serve](./v22.3.html#application-multi-serve) introduced in v22.3. +要同时运行一个 HTTP/3 和 HTTP/1.1 服务器，您可以使用 v22.3 引入的 [application multiserve](./v22.3.html#application-multi-servve)。 -.. column:: +.. 列: ```` -``` +`` $ sanic path.to.server:app --http=3 --http=1 ``` @@ -86,73 +86,73 @@ $ sanic path.to.server:app -3 -1 ``` ```` -.. column:: +.. 列: ```` ```python app.prepre(version=3) -app.prepre(version=1) +app.pres(version=1) Sanic.serve() ``` ```` -Because HTTP/3 requires TLS, you cannot start a HTTP/3 server without a TLS certificate. You should [set it up yourself](../how-to/tls.html) or use `mkcert` if in `DEBUG` mode. Currently, automatic TLS setup for HTTP/3 is not compatible with `trustme`. +因为HTTP 3 需要 TLS，您不能在没有TLS 证书的情况下启动 HTTP/3 服务器。 你应该[自己设置它](../how-to/tls.html)，或者在 `DEBUG` 模式下使用 `mkcert` 。 目前，HTTP/3 的自动TLS设置与 `trustme` 不兼容。 -**👶 This feature is being released as an _EARLY RELEASE FEATURE_.** It is **not** yet fully compliant with the HTTP/3 specification, lacking some features like [websockets](https://websockets.spec.whatwg.org/), [webtransport](https://w3c.github.io/webtransport/), and [push responses](https://http3-explained.haxx.se/en/h3/h3-push). Instead the intent of this release is to bring the existing HTTP request/response cycle towards feature parity with HTTP/3. Over the next several releases, more HTTP/3 features will be added and the API for it finalized. +\*\*👶 此功能正在发布为 _EARLY RELEASE FEATURE_. \* 它是 **没有** 完全符合HTTP/3 规格，缺少一些功能，如 [websockets](https://websockets)。 pet.whatwg.org/, [webtransport](https://w3c.github.io/webtransport/), 和 [推送回复](https://http3-explanined.haxx.se/en/h3/h3-pub). 相反，此版本的意图是使现有的 HTTP 请求/响应周期与HTTP/3实现地物对等。 在以后的几个版本中，将会添加更多的 HTTP/3 功能，并且它的 API 已经完成。 -### Consistent exception naming +### 前后一致的异常名称 -Some of the Sanic exceptions have been renamed to be more compliant with standard HTTP response names. +有些Sanic异常已更名为更符合标准HTTP响应名称。 - `InvalidUsage` >> `BadRequest` -- `MethodNotSupported` >> `MethodNotAllowed` +- `MethodNotSupped` >> `MethodNotalled` - `ContentRangeError` >> `RangeNotSatisfiable` -All old names have been aliased and will remain backwards compatible. +所有旧名字都已被别名，并将保持向后兼容。 -### Current request getter +### 当前请求获取 -Similar to the API to access an application (`Sanic.get_app()`), there is a new method for retrieving the current request when outside of a request handler. +类似于访问应用程序的 API (`Sanic.get_app()`)，在请求处理程序之外有一个新方法来检索当前请求。 ```python -from sanic import Request +从 sanic 导入请求 Request.get_current() ``` -### Improved API support for setting cache control headers +### 改进了 API 支持设置缓存控制头部 -The `file` response helper has some added parameters to make it easier to handle setting of the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header. +`file`响应助手有一些额外的参数，使它更容易处理设置 [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header。 ```python -file( +文件( ..., last_modified=..., - max_age=..., - no_store=..., + max_age=...., + no_store=...., ) ``` -### Custom `loads` function +### 自定义 `loads` 函数 -Just like Sanic supports globally setting a custom `dumps`, you can now set a global custom `loads`. +就像Sanic支持全局设置一个自定义 `dumps`，您现在可以设置一个全局自定义 \`loads'。 ```python -from orjson import loads +从 orjson 导入负载 -app = Sanic("Test", loads=loads) +应用 = Sanic("测试", loads=loads) ``` -### Deprecations and Removals +### 废弃和移除 -1. _REMOVED_ - Applications may no longer opt-out of the application registry -2. _REMOVED_ - Custom exception handlers will no longer run after some part of an exception has been sent -3. _REMOVED_ - Fallback error formats cannot be set on the `ErrorHandler` and must **only** be set in the `Config` -4. _REMOVED_ - Setting a custom `LOGO` for startup is no longer allowed -5. _REMOVED_ - The old `stream` response convenience method has been removed -6. _REMOVED_ - `AsyncServer.init` is removed and no longer an alias of `AsyncServer.app.state.is_started` +1. _REMOVED_——申请者不得再选择退出申请登记册 +2. _REMOVED_ - 自定义异常处理程序在发送部分异常后将不再运行 +3. _REMOVED_ - Fallback 错误格式不能设置在 `ErrorHandler` 上，并且必须**仅** 在 `Config` 中设置 +4. _REMOVED_ - 不再允许为启动设置自定义 `LOGO` +5. _REMOVED_ - 旧的 `stream` 响应方便方法已被删除 +6. _REMOVED_ - `AsyncServer.init` 已被删除，不再是 `AsyncServer.app.state.is_started` 的别名 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -170,4 +170,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 3969e2889cf9a10cab38af1407f001596ea8650a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:09 +0200 Subject: [PATCH 447/698] New translations v22.9.md (Japanese) --- guide/content/ja/release-notes/2022/v22.9.md | 222 +++++++++---------- 1 file changed, 111 insertions(+), 111 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.9.md b/guide/content/ja/release-notes/2022/v22.9.md index b1ea8bf5d1..e6497e051c 100644 --- a/guide/content/ja/release-notes/2022/v22.9.md +++ b/guide/content/ja/release-notes/2022/v22.9.md @@ -1,50 +1,50 @@ --- -title: Version 22.9 +title: バージョン 22.9 --- -# Version 22.9 +# バージョン 22.9 -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the third release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. +これはバージョン22のformat@@0(../../org/policies.md#release-schedule)の3番目のリリースです。 バージョン22は、12月の長期サポートバージョンリリースで「確定」されます。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### ⚠ _IMPORTANT_ - New worker manager 🚀 +### ⚠️ _重要_ - 新しいワーカーマネージャー🚀 -Sanic server has been overhauled to provide more consistency and flexbility in how it operates. More details about the motivations are outlined in [PR #2499](https://github.com/sanic-org/sanic/pull/2499) and discussed in a live stream [discussion held on YouTube](https://youtu.be/m8HCO8NK7HE). +Sanic サーバーは、どのように動作するかにより一貫性と柔軟性を提供するためにオーバーホールされています。 動機の詳細については、[PR #2499](https://github.com/sanic-org/sanic/pull/2499)を参照してください。ライブストリーム [discussion hold on YouTube](https://youtu.be/m8HCO8NK7HE) で議論されています。 -This **does NOT apply** to Sanic in ASGI mode +これはASGIモードでSanicには適用されません -#### Overview of the changes +#### 変更の概要 -- The worker servers will **always** run in a child process. - - Previously this could change depending upon one versus many workers, and the usage or not of the reloader. This should lead to much more predictable development environments that more closely match their production counterparts. -- Multi-workers is **now supported on Windows**. - - This was impossible because Sanic relied upon the `multiprocessing` module using `fork`, which is not available on Windows. - - Now, Sanic will always use `spawn`. This does have some noticeable differences, particularly if you are running Sanic in the global scope with `app.run` (see below re: upgrade issues). -- The application instance now has a new `multiplexer` object that can be used to restart one or many workers. This could, for example, be triggered by a request. -- There is a new Inspector that can provide details on the state of your server. -- Sanic worker manager can run arbitrary processes. - - This allows developers to add any process they want from within Sanic. - - Possible use cases: - - Health monitor, see Sanic Extensions - - Logging queue, see Sanic Extensions - - Background worker queue in a seperate process - - Running another application, like a bot -- There is a new listener called: `main_process_ready`. It really should only be used for adding arbitrary processes to Sanic. -- Passing shared objects between workers. - - Python does allow some types of objects to share state between processes, whether through shared memory, pipes, etc. - - Sanic will now allow these types of object to be shared on the `app.shared_ctx` object. - - Since this feature relies upon Pythons `multiprocessing` library, it obviously will only work to share state between Sanic worker instances that are instantiated from the same execution. This is _not_ meant to provide an API for horizontal scaling across multiple machines for example. +- ワーカーサーバーは子プロセスで**常時**実行されます。 + - 以前は、これは1対多のワーカー、およびリローダーの使用または使用によって変更される可能性がありました。 これにより、より密接に生産相手と一致する、より予測可能な開発環境につながるはずです。 +- マルチワーカーは \*_Windows_ でサポートされるようになりました。 + - SanicはWindowsでは利用できない`fork`を使って`multiprocessing`モジュールを使用していたので、これは不可能でした。 + - Sanicは常に `spawn` を使用します。 これはいくつかの顕著な違いがあります。特に `app.run` を使用してグローバルスコープで Sanic を実行している場合(下記参照: upgrade issues)。 +- アプリケーション・インスタンスは、1つまたは複数のワーカーを再起動するために使用できる新しい`multiplace`オブジェクトを持っています。 これは、例えば、リクエストによってトリガーされる可能性があります。 +- 新しいインスペクターがあり、サーバーの状態について詳細を提供できます。 +- Sanic Worker マネージャは任意のプロセスを実行できます。 + - これにより、開発者はSanic内で必要なプロセスを追加できます。 + - 利用可能なユースケース: + - ヘルスモニター、Sanic Extensions を参照してください。 + - ログキュー, 参照Sanic Extensions + - 分離プロセスのバックグラウンドワーカーキュー + - ボットのように別のアプリケーションを実行しています +- `main_process_ready`という新しいリスナーがあります。 Sanicに任意のプロセスを追加するためにのみ使用する必要があります。 +- Worker 間で共有されたオブジェクトを渡す。 + - Python では、共有メモリやパイプなどを介してプロセス間で状態を共有するオブジェクトがあります。 + - Sanicはこれらのタイプのオブジェクトを`app.shared_ctx`オブジェクトで共有できるようになりました。 + - この機能は Python の `multiprocessing` ライブラリに依存しています。 明らかに、同じ実行からインスタンス化されたSanicワーカーインスタンス間での状態の共有にのみ有効です。 これは、たとえば複数のマシンで水平スケーリングを行うための API を提供することを意味していません。 -#### Adding a shared context object +#### 共有コンテキストオブジェクトの追加 -To share an object between worker processes, it _MUST_ be assigned inside of the `main_process_start` listener. +ワーカープロセス間でオブジェクトを共有するには、 `main_process_start` リスナーの中で _MUST_ が割り当てられます。 ```python from multiprocessing import Queue @@ -54,7 +54,7 @@ async def main_process_start(app): app.shared_ctx.queue = Queue() ``` -All objects on `shared_ctx` will be available now within each worker process. +`shared_ctx` 上のすべてのオブジェクトは、各ワーカプロセス内で使用できるようになります。 ```python @app.before_server_starts @@ -70,24 +70,24 @@ async def handler(request): assert isinstance(request.app.shared_ctx.queue, Queue) ``` -_NOTE: Sanic will not stop you from registering an unsafe object, but may warn you. Be careful not to just add a regular list object, for example, and expect it to work. You should have an understanding of how to share state between processes._ +\*注意: Sanicは安全でないオブジェクトを登録することを止めることはありませんが、警告することがあります。 例えば、通常のリストオブジェクトを追加しないように注意してください。 プロセス間でどのように状態を共有するかを理解しておく必要があります。 -#### Running arbitrary processes +#### 任意のプロセスを実行中 -Sanic can run any arbitrary process for you. It should be capable of being stopped by a `SIGINT` or `SIGTERM` OS signal. +Sanicは任意のプロセスを実行することができます。 `SIGINT` または `SIGTERM` OS 信号で停止することができます。 -These processes should be registered inside of the `main_process_ready` listener. +これらのプロセスは `main_process_ready` リスナーの中に登録する必要があります。 ```python @app.main_process_ready async def ready(app: Sanic, _): - app.manager.manage("MyProcess", my_process, {"foo": "bar"}) -# app.manager.manage(, , ) + app.manager.manager.manage("MyProcess", my_process, {"foo": "bar"}) +# app.manager.manage(, , ) ``` #### Inspector -Sanic ships with an optional Inspector, which is a special process that allows for the CLI to inspect the running state of an application and issue commands. It currently will only work if the CLI is being run on the same machine as the Sanic instance. +Sanic ships with an optional Inspector, これは、CLI がアプリケーションの実行状態と問題コマンドを検査できるようにする特別なプロセスです。 現在、CLI が Sanic インスタンスと同じマシン上で実行されている場合にのみ動作します。 ``` sanic path.to:app --inspect @@ -95,7 +95,7 @@ sanic path.to:app --inspect ![Sanic inspector](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) -The new CLI commands are: +新しい CLI コマンドは次のとおりです。 ``` --inspect Inspect the state of a running instance, human readable @@ -104,19 +104,19 @@ The new CLI commands are: --trigger-shutdown Trigger all processes to shutdown ``` -This is not enabled by default. In order to have it available, you must opt in: +これはデフォルトでは有効になっていません。 利用できるようにするには、以下を選択する必要があります： ```python app.config.INSPECTOR = True ``` -\*Note: Sanic Extensions provides a [custom request](../basics/app.md#custom-requests) class that will add a request counter to the server state. +\*注意: Sanic Extensionsはサーバの状態にリクエストカウンタを追加するformat@@0(../basics/app.md#custom-requests)クラスを提供します。 -#### Application multiplexer +#### アプリケーションマルチプレクサ -Many of the same information and functionality is available on the application instance itself. There is a new `multiplexer` object on the application instance that has the ability to restart one or more workers, and fetch information about the current state. +同じ情報と機能の多くは、アプリケーションインスタンス自体で利用できます。 アプリケーション・インスタンスには、1つ以上のワーカーを再起動できる新しい「multiplace」オブジェクトがあります。 をクリックし、現在の状態に関する情報を取得します。 -You can access it as `app.multiplexer`, or more likely by its short alias `app.m`. +`app.multipplaze`としてアクセスすることも、短いエイリアスの`app.m`でアクセスすることもできます。 ```python @app.on_request @@ -124,35 +124,35 @@ async def print_state(request: Request): print(request.app.m.state) ``` -#### Potential upgrade issues +#### 潜在的なアップグレードの問題 -Because of the switch from `fork` to `spawn`, if you try running the server in the global scope you will receive an error. If you see something like this: +`fork`から`spawn`への切り替えのため、サーバーをグローバルスコープで実行しようとするとエラーが発生します。 次のようなものが表示された場合: ``` sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. -This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. +グローバルスコープで Sanic を実行していて、`if __name__ == "__main__"` ブロックの中ではない場合に発生した可能性があります。 ``` -... then the change is simple. Make sure `app.run` is inside a block. +... 変更は簡単だ `app.run`がブロックの中にあることを確認してください。 ```python if __name__ == "__main__": - app.run(port=9999, dev=True) + app.run(port=999999, dev=True) ``` -#### Opting out of the new functionality +#### 新しい機能を無効にする -If you would like to run Sanic without the new process manager, you may easily use the legacy runners. Please note that support for them **will be removed** in the future. A date has not yet been set, but will likely be sometime in 2023. +新しいプロセスマネージャーなしでSanicを実行したい場合は、レガシーランナーを簡単に使用できます。 これらのサポートは **今後削除されます**。 日付は、まだ設定されていませんが、2023年のいつかになるでしょう。 -To opt out of the new server and use the legacy, choose the appropriate method depending upon how you run Sanic: +新しいサーバーをオプトアウトしてレガシーを使用するには、Sanicの実行方法に応じて適切な方法を選択してください。 -.. column:: +.. 列:: ``` -If you use the CLI... +CLIを使用している場合... ``` -.. column:: +.. 列:: ```` ``` @@ -160,13 +160,13 @@ sanic path.to:app --legacy ``` ```` -.. column:: +.. 列:: ``` -If you use `app.run`... +`app.run`を使用する場合... ``` -.. column:: +.. 列:: ```` ``` @@ -174,13 +174,13 @@ app.run(..., legacy=True) ``` ```` -.. column:: +.. 列:: ``` -If you `app.prepare`... +`app.prepare` の場合... ``` -.. column:: +.. 列:: ```` ``` @@ -189,15 +189,15 @@ Sanic.serve_legacy() ``` ```` -Similarly, you can force Sanic to run in a single process. This however means there will not be any access to the auto-reloader. +同様に、Sanicを単一のプロセスで実行させることができます。 しかし、これは自動リローダーへのアクセスがないことを意味します。 -.. column:: +.. 列:: ``` -If you use the CLI... +CLIを使用している場合... ``` -.. column:: +.. 列:: ```` ``` @@ -205,13 +205,13 @@ sanic path.to:app --single-process ``` ```` -.. column:: +.. 列:: ``` -If you use `app.run`... +`app.run`を使用する場合... ``` -.. column:: +.. 列:: ```` ``` @@ -219,13 +219,13 @@ app.run(..., single_process=True) ``` ```` -.. column:: +.. 列:: ``` -If you `app.prepare`... +`app.prepare` の場合... ``` -.. column:: +.. 列:: ```` ``` @@ -234,11 +234,11 @@ Sanic.serve_single() ``` ```` -### Middleware priority +### ミドルウェアの優先度 -Middleware is executed in an order based upon when it was defined. Request middleware are executed in sequence and response middleware in reverse. This could have an unfortunate impact if your ordering is strictly based upon import ordering with global variables for example. +ミドルウェアは、定義されたタイミングに基づいて順番に実行されます。 リクエストミドルウェアは順番に実行され、レスポンスミドルウェアは逆に実行されます。 これは、例えばグローバル変数のインポート順序に厳密に基づいている場合に、不幸な影響を与える可能性があります。 -A new addition is to break-out of the strict construct and allow a priority to be assigned to a middleware. The higher the number for a middleware definition, the earlier in the sequence it will be executed. This applies to **both** request and response middleware. +新たに追加されたのは、strict 構文のブレークアウトであり、ミドルウェアに優先度を割り当てることです。 ミドルウェア定義の数値が高いほど、シーケンスの前に実行されます。 これは**両方**リクエストとレスポンスミドルウェアに適用されます。 ```python @app.on_request @@ -247,49 +247,49 @@ async def low_priority(_): @app.on_request(priority=10) async def high_priority(_): - ... +... ``` -In the above example, even though `low_priority` is defined first, `high_priority` will run first. +上記の例では、 `low_priority` が先に定義されていても、 `high_priority` が先に実行されます。 -### Custom `loads` function +### カスタムの `loads` 関数 -Sanic has supported the ability to add a [custom `dumps` function](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic) when instantiating an app. The same functionality has been extended to `loads`, which will be used when deserializing. +Sanicはアプリのインスタンス化時にformat@@0(https\://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic)を追加する機能をサポートしています。 同じ機能が `loads` に拡張され、デシリアライズ時に使用されます。 ```python -from json import loads +from json import load Sanic("Test", loads=loads) ``` -### Websocket objects are now iterable +### Websocket オブジェクトがイテレーション可能になりました -Rather than calling `recv` in a loop on a `Websocket` object, you can iterate on it in a `for` loop. +`Websocket` オブジェクトのループで `recv` を呼び出すのではなく、`for` ループで繰り返すことができます。 ```python from sanic import Request, Websocket @app.websocket("/ws") async def ws_echo_handler(request: Request, ws: Websocket): - async for msg in ws: + async msg in ws: await ws.send(msg) ``` -### Appropriately respond with 304 on static files +### 静的ファイルに対しては304で適切に対応します -When serving a static file, the Sanic server can respond appropriately to a request with `If-Modified-Since` using a `304` response instead of resending a file. +静的ファイルを提供する場合、Sanic サーバーはファイルを再送する代わりに、`304` レスポンスを使用して `If-Modified-Since` を使用してリクエストに適切に対応できます。 -### Two new signals to wrap handler execution +### ハンドラの実行をラップするための2つの新しい信号 -Two new [signals](../advanced/signals.md) have been added that wrap the execution of a request handler. +リクエストハンドラの実行をラップする2つの新しい [signals](../advanced/signals.md) が追加されました。 -- `http.handler.before` - runs after request middleware but before the route handler -- `http.handler.after` - runs after the route handler - - In _most_ circumstances, this also means that it will run before response middleware. However, if you call `request.respond` from inside of a route handler, then your middleware will come first +- `http.handler.before` - リクエストミドルウェアの後、ルートハンドラの前に実行されます +- `http.handler.after` - ルートハンドラの後に実行されます + - _ほとんど_ 状況では、これはレスポンスミドルウェアの前に動作することを意味します。 しかし、ルートハンドラの中から`request.respond`を呼び出した場合、ミドルウェアが先に来ます。 -### New Request properties for HTTP method information +### HTTPメソッド情報の新しいリクエストプロパティ -The HTTP specification defines which HTTP methods are: safe, idempotent, and cacheable. New properties have been added that will respond with a boolean flag to help identify the request property based upon the method. +HTTP 仕様では、安全、idempotent、およびキャッシュ可能の HTTP メソッドが定義されています。 メソッドに基づいてリクエストプロパティを特定するのに役立つブーリアンフラグで応答する新しいプロパティが追加されました。 ```python request.is_safe @@ -297,40 +297,40 @@ request.is_idempotent request.is_cacheable ``` -### 🚨 _BREAKING CHANGE_ - Improved cancel request exception +### 🚨 _BREAKING 変更_ - キャンセル要求例外の改善 -In prior version of Sanic, if a `CancelledError` was caught it could bubble up and cause the server to respond with a `503`. This is not always the desired outcome, and it prevented the usage of that error in other circumstances. As a result, Sanic will now use a subclass of `CancelledError` called: `RequestCancelled` for this functionality. It likely should have little impact unless you were explicitly relying upon the old behavior. +Sanicの以前のバージョンでは、`CancelledError` がキャッチされた場合、バブルが解除され、サーバーが`503`で応答する可能性があります。 これは常に望ましい結果ではなく、他の状況ではそのエラーの使用を妨げています。 結果として、Sanicはこの機能に`CancelledError`というサブクラスを使用するようになりました。 明示的に古い動作に頼らない限り、影響はほとんどないはずです。 -For more details on the specifics of these properties, checkout the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). +これらのプロパティの詳細については、[MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) を参照してください。 -### New deprecation warning filter +### 新しい非推奨警告フィルター -You can control the level of deprecation warnings from Sanic using [standard library warning filter values](https://docs.python.org/3/library/warnings.html#the-warnings-filter). Default is `"once"`. +Sanicからの非推奨警告のレベルは、[standard library warning filter values](https://docs.python.org/3/library/warnings.html#the-warnings-filter) を使用して制御できます。 デフォルトは `"once"` です。 ```python -app.config.DEPRECATION_FILTER = "ignore" +app.config.DEPRECEATION_FILTER = "ignore" ``` -### Deprecations and Removals +### 非推奨と削除 -1. _DEPRECATED_ - Duplicate route names have been deprecated and will be removed in v23.3 -2. _DEPRECATED_ - Registering duplicate exception handlers has been deprecated and will be removed in v23.3 -3. _REMOVED_ - `route.ctx` not set by Sanic, and is a blank object for users, therefore ... +1. _DEPRECATED_ - ルート名の重複は非推奨となり、v23.3で削除されます +2. _DEPRECATED_ - 重複した例外ハンドラの登録は廃止予定となり、v23.3で削除されます。 +3. _REMOVED_ - `route.ctx`はSanicが設定したものではなく、ユーザーのための空白のオブジェクトなので... - `route.ctx.ignore_body` >> `route.extra.ignore_body` - `route.ctx.stream` >> `route.extra.stream` - `route.ctx.hosts` >> `route.extra.hosts` - `route.ctx.static` >> `route.extra.static` - `route.ctx.error_format` >> `route.extra.error_format` - `route.ctx.websocket` >> `route.extra.websocket` -4. _REMOVED_ - `app.debug` is READ-ONLY -5. _REMOVED_ - `app.is_running` removed -6. _REMOVED_ - `app.is_stopping` removed -7. _REMOVED_ - `Sanic._uvloop_setting` removed -8. _REMOVED_ - Prefixed environment variables will be ignored if not uppercase +4. _削除_ - `app.debug`はREAD-ONLY +5. _削除_ - `app.is_running`が削除されました +6. _削除_ - `app.is_stopping` が削除されました +7. _削除_ - `Sanic._uvloop_setting` が削除されました +8. _REMOVED_ - プリフィックスされた環境変数は大文字でなければ無視されます -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@ahopkins](https://github.com/ahopkins) [@azimovMichael](https://github.com/azimovMichael) @@ -346,4 +346,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From e5096fb2c03dd37bad6e9db5915c8f35952f6c9d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:11 +0200 Subject: [PATCH 448/698] New translations v22.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.9.md | 258 +++++++++---------- 1 file changed, 129 insertions(+), 129 deletions(-) diff --git a/guide/content/zh/release-notes/2022/v22.9.md b/guide/content/zh/release-notes/2022/v22.9.md index b1ea8bf5d1..7e8afc0a58 100644 --- a/guide/content/zh/release-notes/2022/v22.9.md +++ b/guide/content/zh/release-notes/2022/v22.9.md @@ -1,60 +1,60 @@ --- -title: Version 22.9 +title: 22.9 版本 --- -# Version 22.9 +# 22.9 版本 .. toc:: -## Introduction +## 一. 导言 -This is the third release of the version 22 [release cycle](../../org/policies.md#release-schedule). Version 22 will be "finalized" in the December long-term support version release. +这是版本22 的第三次版本[发行周期](../../org/policies.md#release-schedule)。 版本22将在12月份的长期支持版本发布时“最后完成”。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### ⚠ _IMPORTANT_ - New worker manager 🚀 +### ⚠️ _IMPORTANT_ - 新的工人管理器 :ro火箭： -Sanic server has been overhauled to provide more consistency and flexbility in how it operates. More details about the motivations are outlined in [PR #2499](https://github.com/sanic-org/sanic/pull/2499) and discussed in a live stream [discussion held on YouTube](https://youtu.be/m8HCO8NK7HE). +对Sanic服务器进行了全面检查，以便使其运作方式更加一致和灵活。 更多关于动机的详细信息载于[PR #2499](https://github.com/sanic-org/sanic/pull/2499)，并在直播中讨论[YouTube上的讨论](https://youtu.be/m8HCO8NK7HE)。 -This **does NOT apply** to Sanic in ASGI mode +这个**不适用于ASGI 模式的 Sanic** -#### Overview of the changes +#### 变化概述 -- The worker servers will **always** run in a child process. - - Previously this could change depending upon one versus many workers, and the usage or not of the reloader. This should lead to much more predictable development environments that more closely match their production counterparts. -- Multi-workers is **now supported on Windows**. - - This was impossible because Sanic relied upon the `multiprocessing` module using `fork`, which is not available on Windows. - - Now, Sanic will always use `spawn`. This does have some noticeable differences, particularly if you are running Sanic in the global scope with `app.run` (see below re: upgrade issues). -- The application instance now has a new `multiplexer` object that can be used to restart one or many workers. This could, for example, be triggered by a request. -- There is a new Inspector that can provide details on the state of your server. -- Sanic worker manager can run arbitrary processes. - - This allows developers to add any process they want from within Sanic. - - Possible use cases: - - Health monitor, see Sanic Extensions - - Logging queue, see Sanic Extensions - - Background worker queue in a seperate process - - Running another application, like a bot -- There is a new listener called: `main_process_ready`. It really should only be used for adding arbitrary processes to Sanic. -- Passing shared objects between workers. - - Python does allow some types of objects to share state between processes, whether through shared memory, pipes, etc. - - Sanic will now allow these types of object to be shared on the `app.shared_ctx` object. - - Since this feature relies upon Pythons `multiprocessing` library, it obviously will only work to share state between Sanic worker instances that are instantiated from the same execution. This is _not_ meant to provide an API for horizontal scaling across multiple machines for example. +- 工人服务器将**总是**在子进程中运行。 + - 以前，这种情况可能会根据一个工人相对于许多工人的情况以及重新装载器的使用情况而改变。 这应导致更加可预测的发展环境，使其与生产对应方更加吻合。 +- Windows\*\*现在支持多个工作者。 + - 这是不可能的，因为Sanic依靠使用 "fork" 的 "multiprocessing" 模块，而这个模块在Windows上不可用。 + - 现在，Sanic将总是使用 `spawn` 。 这确实有一些明显的差异，特别是如果你正在全球范围内用 \`app.run' 运行 Sanic (见下面：升级问题)。 +- 应用程序实例现在有一个新的 `multiplexer` 对象，可以用来重启一个或多个工人。 例如，这可能是请求所触发的。 +- 有一个新的检查员可以提供关于您服务器状态的详细信息。 +- 卫生工作者管理人员可以任意进行工作。 + - 这允许开发者添加他们想要的 Sanic 内部的任何进程。 + - 可能的使用案例： + - 健康监视器，见Sanic Extensions + - 日志队列，见Sanic Extensions + - 分隔进程中的背景工作者队列 + - 正在运行另一个应用程序，就像一个bot +- 有一个新的监听器叫做`main_process_ready`。 确实只能用它来为萨尼克增加武断的过程。 +- 在员工之间传递共享对象。 + - Python 确实允许某些类型的对象在进程之间分享状态，不管是通过共享内存、管道等。 + - Sanic 现在允许在`app.shared_ctx`对象上共享这些类型的对象。 + - 因为此功能依靠Pythons `multiprocessing`库， 它显然只能在同一执行实例中的萨尼克工人之间分享状态。 这不是 \* 提供一个 API 用于多台机器之间的水平缩放。 -#### Adding a shared context object +#### 添加共享上下文对象 -To share an object between worker processes, it _MUST_ be assigned inside of the `main_process_start` listener. +要在工作流程之间共享一个对象，它_MUST_将被分配到 `main_process_start` 监听器。 ```python -from multiprocessing import Queue +从多处理导入队列 @app.main_process_start async def main_process_start(app): app.shared_ctx.queue = Queue() ``` -All objects on `shared_ctx` will be available now within each worker process. +"shared_ctx" 上的所有对象现在都可以在每个工作流程中使用。 ```python @app.before_server_starts @@ -70,53 +70,53 @@ async def handler(request): assert isinstance(request.app.shared_ctx.queue, Queue) ``` -_NOTE: Sanic will not stop you from registering an unsafe object, but may warn you. Be careful not to just add a regular list object, for example, and expect it to work. You should have an understanding of how to share state between processes._ +_注意：Sanic不会阻止您注册一个不安全的物品，但可能会警告您。 请注意不要仅仅添加一个普通列表对象，并期望它能起作用。 您应该了解如何分享进程之间的状态。_ -#### Running arbitrary processes +#### 正在运行任意进程 -Sanic can run any arbitrary process for you. It should be capable of being stopped by a `SIGINT` or `SIGTERM` OS signal. +Sanic可以为你任意运行任何过程。 它应该能够被 `SIGINT` 或 `SIGTERM` OS 信号拦截。 -These processes should be registered inside of the `main_process_ready` listener. +这些进程应该在 "main_process_ready" 监听器中注册。 ```python @app.main_process_ready async def ready(app: Sanic, _): - app.manager.manage("MyProcess", my_process, {"foo": "bar"}) -# app.manager.manage(, , ) + app.manager.manager.management("MyProcess", my_process, {"foo": "bar"}) +# app.manager.manager.management(, , ) ``` -#### Inspector +#### 检查员 -Sanic ships with an optional Inspector, which is a special process that allows for the CLI to inspect the running state of an application and issue commands. It currently will only work if the CLI is being run on the same machine as the Sanic instance. +具有可选检查员的Sanic船。 这是一个特殊过程，允许CLI检查应用程序的运行状态和发布命令。 它目前只有当CLI运行于与Sanic实例相同的机器时才会起作用。 ``` -sanic path.to:app --inspect +sanic path.to:app --inspection ``` -![Sanic inspector](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) +![Sanic 查看器](https://user-images.githubusercontent.com/166269/190099384-2f2f3fae-22d5-4529-b279-8446f6b5f9bd.png) -The new CLI commands are: +新的 CLI 命令是： ``` - --inspect Inspect the state of a running instance, human readable - --inspect-raw Inspect the state of a running instance, JSON output - --trigger-reload Trigger worker processes to reload - --trigger-shutdown Trigger all processes to shutdown + --inspect 检查运行实例的状态 人类可读的 + --查看运行实例的状态 JSON 输出 + --触发器重新加载触发器进程以重新加载 + --触发器关闭所有进程 ``` -This is not enabled by default. In order to have it available, you must opt in: +默认情况下未启用此功能。 要有它，您必须选择： ```python app.config.INSPECTOR = True ``` -\*Note: Sanic Extensions provides a [custom request](../basics/app.md#custom-requests) class that will add a request counter to the server state. +\*注意：Sanic Extensions 提供了一个 [自定义请求](../basics/app.md#custom-requests) 类，它将添加一个请求对应到服务器状态。 -#### Application multiplexer +#### 应用程序多路程序器 -Many of the same information and functionality is available on the application instance itself. There is a new `multiplexer` object on the application instance that has the ability to restart one or more workers, and fetch information about the current state. +许多相同的信息和功能都可以在应用程序实例本身上获得。 应用程序实例上有一个新的 `multiplexer` 对象，它能够重启一个或多个工人。 并获取当前状态的信息。 -You can access it as `app.multiplexer`, or more likely by its short alias `app.m`. +您可以以 `app.multiplexer` 的身份访问它，或更可能通过它的短别名`app.m`访问它。 ```python @app.on_request @@ -124,35 +124,35 @@ async def print_state(request: Request): print(request.app.m.state) ``` -#### Potential upgrade issues +#### 可能的升级问题 -Because of the switch from `fork` to `spawn`, if you try running the server in the global scope you will receive an error. If you see something like this: +因为“fork”切换到“spawn”。如果您尝试在全局范围内运行服务器，您将收到一个错误。 如果你看到这样的东西： ``` sanic.exceptions.ServerError: Sanic server could not start: [Errno 98] Address already in use. This may have happened if you are running Sanic in the global scope and not inside of a `if __name__ == "__main__"` block. ``` -... then the change is simple. Make sure `app.run` is inside a block. +... 然后变化就很简单了。 请确认 `app.run` 是在方块内。 ```python if __name__ == "__main__": app.run(port=9999, dev=True) ``` -#### Opting out of the new functionality +#### 选择退出新功能 -If you would like to run Sanic without the new process manager, you may easily use the legacy runners. Please note that support for them **will be removed** in the future. A date has not yet been set, but will likely be sometime in 2023. +如果你想要在没有新的进程管理器的情况下运行 Sanic，你可以轻松地使用旧版的运行器。 请注意支持他们**将来会被删除** 日期尚未确定，但有可能在2023年某个时候确定。 -To opt out of the new server and use the legacy, choose the appropriate method depending upon how you run Sanic: +若要退出新服务器并使用遗产，根据您如何运行 Sanic，选择适当的方法： -.. column:: +.. 列: ``` -If you use the CLI... +如果您使用CLI... ``` -.. column:: +.. 列: ```` ``` @@ -160,44 +160,44 @@ sanic path.to:app --legacy ``` ```` -.. column:: +.. 列: ``` -If you use `app.run`... +如果您使用 `app.run`... ``` -.. column:: +.. 列: ```` -``` +`` app.run(..., legacy=True) ``` ```` -.. column:: +.. 列: ``` -If you `app.prepare`... +如果您`app.prepare`... ``` -.. column:: +.. 列: ```` -``` -app.prepare(...) +`` +app.preparre(...) Sanic.serve_legacy() ``` ```` -Similarly, you can force Sanic to run in a single process. This however means there will not be any access to the auto-reloader. +同样，你可以强制Sanic在一个过程中运行。 然而，这意味着将无法访问自动重新加载器。 -.. column:: +.. 列: ``` -If you use the CLI... +如果您使用CLI... ``` -.. column:: +.. 列: ```` ``` @@ -205,40 +205,40 @@ sanic path.to:app --single-process ``` ```` -.. column:: +.. 列: ``` -If you use `app.run`... +如果您使用 `app.run`... ``` -.. column:: +.. 列: ```` -``` -app.run(..., single_process=True) +`` +app.run(..., sinle_process=True) ``` ```` -.. column:: +.. 列: ``` -If you `app.prepare`... +如果您`app.prepare`... ``` -.. column:: +.. 列: ```` -``` -app.prepare(...) +`` +app.preparre(...) Sanic.serve_single() ``` ```` -### Middleware priority +### 中间件优先级 -Middleware is executed in an order based upon when it was defined. Request middleware are executed in sequence and response middleware in reverse. This could have an unfortunate impact if your ordering is strictly based upon import ordering with global variables for example. +中间件是根据定义时的顺序执行的。 请求中间件按顺序执行，而中间件则对应。 如果您的订单严格基于导入订单，比如全局变量，这可能会产生不幸的影响。 -A new addition is to break-out of the strict construct and allow a priority to be assigned to a middleware. The higher the number for a middleware definition, the earlier in the sequence it will be executed. This applies to **both** request and response middleware. +增加的一个新内容是打破严格的结构，并允许将优先权分配给一个中间体。 中间件定义的数字越高，执行顺序就越早。 这适用于**既有**请求也有中途响应。 ```python @app.on_request @@ -246,89 +246,89 @@ async def low_priority(_): ... @app.on_request(priority=10) -async def high_priority(_): - ... +async def hig_priority(_): +... ``` -In the above example, even though `low_priority` is defined first, `high_priority` will run first. +在上面的例子中，即使首先定义了 `low_priority` ，但是`high_priority` 将先运行。 -### Custom `loads` function +### 自定义 `loads` 函数 -Sanic has supported the ability to add a [custom `dumps` function](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic) when instantiating an app. The same functionality has been extended to `loads`, which will be used when deserializing. +Sanic 支持在实例化应用程序时添加 [自定义 `dumps` 函数] (https\://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic)。 同一功能已扩展到 `loads`, 当反序列化时将使用它。 ```python -from json import loads +从 json 导入负载 -Sanic("Test", loads=loads) +Sanic("测试", loads=loads) ``` -### Websocket objects are now iterable +### Websocket 对象现在是可以迭代的 -Rather than calling `recv` in a loop on a `Websocket` object, you can iterate on it in a `for` loop. +你不能在 Websocket`对象上调用`recv`方法，而是可以在`for\` 循环中迭代。 ```python -from sanic import Request, Websocket +从 sanic 导入请求, Websocket @app.websocket("/ws") -async def ws_echo_handler(request: Request, ws: Websocket): - async for msg in ws: - await ws.send(msg) +async def ws_echo_handler(request: request, ws: Websocket): + async for msg in w: + request ws.send(msg) ``` -### Appropriately respond with 304 on static files +### 以304个静态文件作出适当响应 -When serving a static file, the Sanic server can respond appropriately to a request with `If-Modified-Since` using a `304` response instead of resending a file. +当服务于静态文件时，Sanic 服务器可以使用 `If-Modified-Since` 响应而不是重置一个文件。 -### Two new signals to wrap handler execution +### 两个新的信号来包装处理器执行 -Two new [signals](../advanced/signals.md) have been added that wrap the execution of a request handler. +添加了两个新的 [signals](../advanced/signals.md)，将执行请求处理器。 -- `http.handler.before` - runs after request middleware but before the route handler -- `http.handler.after` - runs after the route handler - - In _most_ circumstances, this also means that it will run before response middleware. However, if you call `request.respond` from inside of a route handler, then your middleware will come first +- `http.handler.befor` - 在请求中间件后但在路由处理程序之前运行 +- `http.handler.after ` - 在路由处理程序后运行 + - 在_大多数_情况下，这也意味着它将在中间反应之前运行。 然而，如果你从路由处理器内部调用 `request.respond` ，那么你的中间件将会先来到去。 -### New Request properties for HTTP method information +### HTTP 方法信息的新请求属性 -The HTTP specification defines which HTTP methods are: safe, idempotent, and cacheable. New properties have been added that will respond with a boolean flag to help identify the request property based upon the method. +HTTP规格界定了哪种HTTP方法：安全、易感染性和可缓存。 添加了新的属性，以响应布尔标识来帮助根据方法识别请求属性。 ```python -request.is_safe +is_safe request.is_idempotent request.is_cacheable ``` -### 🚨 _BREAKING CHANGE_ - Improved cancel request exception +### 🚨 _Breaking变换_ - 改进的取消请求异常 -In prior version of Sanic, if a `CancelledError` was caught it could bubble up and cause the server to respond with a `503`. This is not always the desired outcome, and it prevented the usage of that error in other circumstances. As a result, Sanic will now use a subclass of `CancelledError` called: `RequestCancelled` for this functionality. It likely should have little impact unless you were explicitly relying upon the old behavior. +在先前版本的 Sanic 中，如果抓到一个 `取消的错误` ，它可能会泡沫化并导致服务器以 `503` 响应. 这并不总是期望的结果，它防止了在其他情况下使用这一错误。 因此，Sanic现在将使用一个子类的 `CancelledError` ，叫做`RequestCancelled`。 除非你明确依赖旧的行为，否则它可能不会产生什么影响。 -For more details on the specifics of these properties, checkout the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). +欲了解这些属性的细节详情，请签出[MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods)。 -### New deprecation warning filter +### 新的废弃警告过滤器 -You can control the level of deprecation warnings from Sanic using [standard library warning filter values](https://docs.python.org/3/library/warnings.html#the-warnings-filter). Default is `"once"`. +您可以使用[标准库警告过滤值](https://docs.python.org/3/library/warnings.html#the-warnings-filter)控制来自Sanic的废弃警告的级别。 默认为“一次”\`。 ```python -app.config.DEPRECATION_FILTER = "ignore" +app.config.DEPRECATION_FILTER = "忽略" ``` -### Deprecations and Removals +### 废弃和移除 -1. _DEPRECATED_ - Duplicate route names have been deprecated and will be removed in v23.3 -2. _DEPRECATED_ - Registering duplicate exception handlers has been deprecated and will be removed in v23.3 -3. _REMOVED_ - `route.ctx` not set by Sanic, and is a blank object for users, therefore ... +1. _删除_ - 重复的路由名称已被弃用，并将在 v23.3 中删除。 +2. _DEPRECATED_-注册重复的异常处理程序已被弃用，并将在 v23.3 中删除。 +3. _REMOVED_ - `route.ctx` 没有由 Sanic 设置，因此是用户的空白对象... - `route.ctx.ignore_body` >> `route.extra.ignore_body` - `route.ctx.stream` >> `route.extra.stream` - `route.ctx.hosts` >> `route.extra.hosts` - `route.ctx.static` >> `route.extra.static` - - `route.ctx.error_format` >> `route.extra.error_format` + - `route.ctx.error_格式` >> `route.extra.error_格式` - `route.ctx.websocket` >> `route.extra.websocket` -4. _REMOVED_ - `app.debug` is READ-ONLY -5. _REMOVED_ - `app.is_running` removed -6. _REMOVED_ - `app.is_stopping` removed -7. _REMOVED_ - `Sanic._uvloop_setting` removed -8. _REMOVED_ - Prefixed environment variables will be ignored if not uppercase +4. _REMOVED_ - 只有`app.debug` 是 READ-唯一的 +5. _REMOVED_ - `app.is_running` 已移除 +6. _REMOVED_ - `app.is_stopping` 已删除 +7. _REMOVED_ - `Sanic._uvloop_setting` 已删除 +8. _REMOVED_ - 如果不是大写，预固定环境变量将被忽略 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -346,4 +346,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 36a269303e90f180e94ba923256b0bea91252727 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:12 +0200 Subject: [PATCH 449/698] New translations v23.12.md (Japanese) --- guide/content/ja/release-notes/2023/v23.12.md | 98 +++++++++---------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/guide/content/ja/release-notes/2023/v23.12.md b/guide/content/ja/release-notes/2023/v23.12.md index 6694a10d2e..7a08b57a0d 100644 --- a/guide/content/ja/release-notes/2023/v23.12.md +++ b/guide/content/ja/release-notes/2023/v23.12.md @@ -1,55 +1,55 @@ --- -title: Version 23.12 +title: バージョン 23.12 --- -# Version 23.12 (LTS) +# バージョン 23.12 (LTS) -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the final release of the version 23 [release cycle](../../organization/policies.md#release-schedule). It is designated as a **long-term support ("LTS") release**, which means it will receive support for two years as stated in the support policy. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose.) +これはバージョン23format@@0(../../organization/policyes.md#release-schedule)の最終リリースです。 これは**長期サポート(LTS)リリース**として指定されています。これはサポートポリシーに記載されている2年間のサポートを受けることを意味します。 何か問題が発生した場合は、 [GitHub](https://github.com/sanic-org/sanic/issues/new/choose) にご注意ください。 -## What to know +## 知っておくべきこと -More details in the [Changelog](../changelog.html). Notable new or breaking features, and what to upgrade: +[Changelog](../changelog.html) の詳細。 注目すべき新機能や破損した機能、アップグレードする機能: -### 🎉 Documentation now using {span:has-text-primary:Sanic} +### 🎉 {span:has-text-primary:Sanic} を使用してドキュメントを作成 ![](http://127.0.0.1:8000/assets/images/sanic-framework-logo-circle-128x128.png) -You can read [all about how](/en/built-with-sanic.html), but we converted this documentation site to using the SHH 🤫 stack. +format@@0(/ja/built-with-sanic.html) を読むことができますが、このドキュメントサイトは SHH 🤫 スタックを使用しています。 - [Sanic](https://sanic.dev) - [html5tagger](https://github.com/sanic-org/html5tagger) - [HTMX](https://htmx.org/) -### 👶 _BETA_ Welcome to the Sanic interactive console +### 👶 _BETA_ Sanic インタラクティブコンソールへようこそ -That's right, Sanic now ships with a REPL! +そうです、Sanicは今REPLを発送しています! ![](/assets/images/repl.png) -When using the Sanic CLI, you can pass the `--repl` argument to automatically run an interactive console along side your application. This is extremely helpful while developing, and allows you access to the application instance, as well as a built-in client enabled to send HTTP requests to the running instance. +Sanic CLI を使用する場合は、`--repl` 引数を渡すことで、アプリケーション側でインタラクティブなコンソールを自動的に実行できます。 これは開発中に非常に役立ち、アプリケーションインスタンスにアクセスすることができます。 実行中のインスタンスに HTTP リクエストを送信するために有効になっている組み込みクライアントだけでなく。 -If you use the `--dev` flag, this feature is quasi-enabled by default. While it will not outright run the REPL, it will start the process and allow you to enter the REPL at anytime by hitting `` on your keyboard. +`--dev` フラグを使用している場合、この機能はデフォルトで準対応です。 REPLは完全に実行されませんが、 それはプロセスを開始し、キーボードの``を押すことによっていつでもREPLを入力することができます。 -_This is still in BETA mode. We would appreciate you letting us know about any any enhancement requests or issues._ +\*これはまだベータモードです。 私たちは、任意の機能強化の要求や問題について私たちに知らせていただきありがとうございます。 \* -### Python 3.12 support +### Python 3.12 のサポート -We have added Python 3.12 to the supported versions. +サポートされているバージョンに Python 3.12 を追加しました。 -### Start and restart arbitrary processes +### 任意のプロセスを起動して再起動します -Using the [multiplexer](../../guide/running/manager.md#access-to-the-multiplexer), you can now start and restart arbitrary or pre-existing processes. This enabled the following new features in the way the multiplexer and worker manager operate: +[multiplexer](../../guide/running/manager.md#access-to-the-multiplexer) を使用すると、任意または既存のプロセスを開始して再起動できるようになりました。 これにより、マルチプレクサとワーカーマネージャが動作する方法で、次の新機能が有効になりました。 -1. `multiplexer.restart("")` will now restart a targeted single process -2. `multiplexer.manage(...)` is a new method that works exactly like `manager.manage(...)` -3. The `manage` methods now have additional keyword arguments: - - `tracked` - whether the state of the process is tracked after the process completes - - `restartable` - whether the process should be allowed to be restarted - - `auto_start` - whether the process should be started immediately after it is created +1. `multiplexer.restart("")`は目標とされた単一のプロセスを再起動します +2. `multiplexer.manage(...)` は、 `manager.manage(...)` とまったく同じように動作する新しいメソッドです。 +3. `manage` メソッドにキーワード引数が追加されました。 + - `tracked` - プロセスが完了した後にプロセスの状態が追跡されるかどうか + - `restartable` - プロセスを再起動させるかどうか + - `auto_start` - 作成後すぐにプロセスを開始するかどうか ```python def task(n: int = 10, **kwargs): @@ -74,27 +74,27 @@ def start_process(app: Sanic): app.manager.manage("TEST", task, kwargs={"n": 3}, restartable=True) ``` -### Prioritized listeners and signals +### 優先順位付けされたリスナーと信号 -In [v22.9](../2022/v22.9.md) Sanic added prioritization to middleware to allow arbitrary ordering of middleware. This same concept has now been extended to listeners and signals. This will allow a priority number to be assigned at creation time that will override its default position in the execution timeline. +[v22.9](../2022/v22.9.md) Sanicはミドルウェアの任意の順序を可能にするためにミドルウェアに優先順位付けを追加しました。 この同じ概念は、リスナーとシグナルにも拡張されています。 これにより、作成時に優先度番号が割り当てられ、実行タイムライン内のデフォルトの位置が上書きされます。 ```python @app.before_server_start(priority=3) async def sample(app): - ... +... ``` -The higher the number, the higher priority it will receive. Overall the rules for deciding the order of execution are as follows: +数が多いほど、優先度が高くなります。 全体的に実行の順序を決定するためのルールは次のとおりです。 -1. Priority in descending order -2. Application listeners before Blueprint listeners -3. Registration order +1. 降順の優先度 +2. Blueprint リスナーより前のアプリのリスナー +3. 登録注文 -_Remember, some listeners are executed in reverse order_ +_リスナが逆順に実行されることを覚えておいてください_ -### Websocket signals +### Websocket シグナル -We have added three new signals for websockets: +websocketに新しい3つのシグナルを追加しました。 1. `websocket.handler.before` 2. `websocket.handler.after` @@ -116,11 +116,11 @@ async def ws_exception( ... ``` -![](https://camo.githubusercontent.com/ea2894c88bedf37a4f12f129569e8fd14bfceaa36d4452c7b7a1869d2f1cdb18/68747470733a2f2f7a692e66692f77732d7369676e616c732e706e67) +![](https://camo.githubusercontent.com/ea2894c88bedf37a4f12f1295696e8fd14bfceaa36d4452c7b7a1869d2f1cdb18/68747470733a2f2f7a692e66692f77732d7369676e616c732e706e676e67) -### Simplified signals +### シンプルな信号 -Sanic has always enforced a three part naming convention for signals: `one.two.three`. However, now you can create simpler names that are only a single part. +Sanic は常に `one.two.three` の3つの命名規則を強制しています。 ただし、単一の部分だけである単純な名前を作成できるようになりました。 ```python @app.signal("foo") @@ -128,7 +128,7 @@ async def foo(): ... ``` -You can make that part dynamic just like with regular signals and routes: +通常の信号やルートと同じように、その部分を動的にすることができます。 ```python @app.signal("") @@ -143,19 +143,19 @@ async def test(request: Request): return json({"hello": "world"}) ``` -If you need to have multiple dynamic signals, then you should use the longer three-part format. +複数の動的信号を使用する必要がある場合は、長い3つの部品形式を使用する必要があります。 -### The `event` method has been updated +### `event`メソッドが更新されました -A number of changes have been made to both `app.event()` and `blueprint.event()`. +`app.event()` と `blueprint.event()` の両方に変更が加えられました。 -- `condition` and `exclusive` are keywords to control matching conditions (similar to the `signal()` methods) -- You can pass either a `str` or an `Enum` (just like `signal()`) -- returns a copy of the context that was passed to the `dispatch()` method +- `condition` と `exclusive` はマッチ条件を制御するためのキーワードです（`signal()`メソッドと同様） +- `signal()`のように、`str`か`Enum`を渡すことができます。 +- は、`dispatch()` メソッドに渡されたコンテキストのコピーを返します。 -### Reload trigger gets changed files +### リロードトリガーが変更されたファイルを取得します -The files changed by the reloader are now injected into the listener. This will allow the trigger to do something with knowledge of what those changed files were. +リローダーによって変更されたファイルは現在リスナーに注入されます。 これにより、トリガーはそれらの変更されたファイルが何であったかの知識を持って何かを行うことができます。 ```python @app.after_reload_trigger @@ -163,9 +163,9 @@ async def after_reload_trigger(_, changed): print(changed) ``` -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@ahopkins](https://github.com/ahopkins) [@ChihweiLHBird](https://github.com/ChihweiLHBird) @@ -182,4 +182,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From 300224c87d4608e3db048de7b3ae84a8ad191c6a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:14 +0200 Subject: [PATCH 450/698] New translations v23.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.12.md | 128 +++++++++--------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/guide/content/zh/release-notes/2023/v23.12.md b/guide/content/zh/release-notes/2023/v23.12.md index 6694a10d2e..f8ec203ad9 100644 --- a/guide/content/zh/release-notes/2023/v23.12.md +++ b/guide/content/zh/release-notes/2023/v23.12.md @@ -1,55 +1,55 @@ --- -title: Version 23.12 +title: 第23.12版 --- -# Version 23.12 (LTS) +# 第23.12版 (LTS) .. toc:: -## Introduction +## 一. 导言 -This is the final release of the version 23 [release cycle](../../organization/policies.md#release-schedule). It is designated as a **long-term support ("LTS") release**, which means it will receive support for two years as stated in the support policy. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose.) +这是第23版的最后版本[发行周期](../../organization/policies.md#release-schedule)。 它被指定为**长期支持("LTS") release**, 这意味着它将按照支持政策的规定得到两年的支持。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/seloe.) -## What to know +## 了解什么 -More details in the [Changelog](../changelog.html). Notable new or breaking features, and what to upgrade: +更多详细信息在 [Changelog](../changelog.html)。 显著的新功能或破损功能以及升级内容： -### 🎉 Documentation now using {span:has-text-primary:Sanic} +### :party_poper: 文档现在使用 {span:has-text-primary:Sanic} ![](http://127.0.0.1:8000/assets/images/sanic-framework-logo-circle-128x128.png) -You can read [all about how](/en/built-with-sanic.html), but we converted this documentation site to using the SHH 🤫 stack. +您可以阅读[所有关于如何](/en/build-with-sanic.html)，但我们将此文档网站转换为使用 SHH 🤫 stack。 - [Sanic](https://sanic.dev) - [html5tagger](https://github.com/sanic-org/html5tagger) - [HTMX](https://htmx.org/) -### 👶 _BETA_ Welcome to the Sanic interactive console +### 👶 _BETA_ 欢迎使用 Sanic 交互式控制台 -That's right, Sanic now ships with a REPL! +这是正确的，现在萨尼克带着REPL！ -![](/assets/images/repl.png) +![](/assets/images/repli.png) -When using the Sanic CLI, you can pass the `--repl` argument to automatically run an interactive console along side your application. This is extremely helpful while developing, and allows you access to the application instance, as well as a built-in client enabled to send HTTP requests to the running instance. +当使用 Sanic CLI 时，你可以通过 "--repli" 参数来自动运行一个交互式控制台。 这在开发时非常有用，允许您访问应用程序实例。 还有一个内置客户端已启用，可以将 HTTP 请求发送到运行实例。 -If you use the `--dev` flag, this feature is quasi-enabled by default. While it will not outright run the REPL, it will start the process and allow you to enter the REPL at anytime by hitting `` on your keyboard. +如果您使用 "--dev" 标志，此功能默认是准启用的。 它将不会彻底运行REPL， 它将启动进程，并允许您随时在键盘上点击\`'。 -_This is still in BETA mode. We would appreciate you letting us know about any any enhancement requests or issues._ +_这仍然处于BETA模式。 我们希望你让我们了解任何升级请求或问题。_ -### Python 3.12 support +### Python 3.12 支持 -We have added Python 3.12 to the supported versions. +我们已经将 Python 3.12 添加到支持的版本。 -### Start and restart arbitrary processes +### 启动并重启任意进程 -Using the [multiplexer](../../guide/running/manager.md#access-to-the-multiplexer), you can now start and restart arbitrary or pre-existing processes. This enabled the following new features in the way the multiplexer and worker manager operate: +使用 [multiplexer](../../guide/running/manager.md#access-to-the-multiplexer)，您现在可以开始并重启任意或原有的过程。 这使得多路程序和工人管理员的运作方式具有以下新功能： -1. `multiplexer.restart("")` will now restart a targeted single process -2. `multiplexer.manage(...)` is a new method that works exactly like `manager.manage(...)` -3. The `manage` methods now have additional keyword arguments: - - `tracked` - whether the state of the process is tracked after the process completes - - `restartable` - whether the process should be allowed to be restarted - - `auto_start` - whether the process should be started immediately after it is created +1. `multiplexer.restt("")` 现在将重新启动一个目标的单一进程 +2. `multiplexer.manag(...)` 是一种完全类似于`manager.management(...)` 的新方法 +3. `manag` 方法现在有额外的关键字参数： + - `tracked` - 进程完成后是否跟踪进程状态 + - `restable` - 是否允许重启进程 + - `auto_start` - 是否在创建后立即启动此进程 ```python def task(n: int = 10, **kwargs): @@ -74,53 +74,53 @@ def start_process(app: Sanic): app.manager.manage("TEST", task, kwargs={"n": 3}, restartable=True) ``` -### Prioritized listeners and signals +### 已排序的听众和信号 -In [v22.9](../2022/v22.9.md) Sanic added prioritization to middleware to allow arbitrary ordering of middleware. This same concept has now been extended to listeners and signals. This will allow a priority number to be assigned at creation time that will override its default position in the execution timeline. +在 [v22.9](../2022/v22.9.md) 中，Sanic 增加了中间件的优先顺序，以允许任意排序中间件。 这一概念现已扩大到听众和信号。 这将允许在创建时指定一个优先级编号，这将覆盖其在执行时间段中的默认位置。 ```python @app.before_server_start(priority=3) -async def sample(app): - ... +异步采样(app): +... ``` -The higher the number, the higher priority it will receive. Overall the rules for deciding the order of execution are as follows: +数字越高，它将获得越高的优先级。 总体上，决定执行顺序的规则如下： -1. Priority in descending order -2. Application listeners before Blueprint listeners -3. Registration order +1. 按降序排序 +2. 蓝图监听器之前的应用程序监听器 +3. 注册订单 -_Remember, some listeners are executed in reverse order_ +_记住，一些监听器被反向执行_ -### Websocket signals +### Websocket 信号 -We have added three new signals for websockets: +我们为websocket添加了三个新信号： 1. `websocket.handler.before` -2. `websocket.handler.after` +2. `websocket.handler.after ` 3. `websocket.handler.exception` ```python @app.signal("websocket.handler.before") async def ws_before(request: Request, websocket: Websocket): - ... -@app.signal("websocket.handler.after") -async def ws_after(request: Request, websocket: Websocket): - ... + +@app.signal("websocket.handler.after ") +async def ws_after (request: Request, websocket: Websocket): + . -@app.signal("websocket.handler.exception") +@app.signal("websocket.handler. xception") async def ws_exception( request: Request, websocket: Websocket, exception: Exception ): - ... +... ``` -![](https://camo.githubusercontent.com/ea2894c88bedf37a4f12f129569e8fd14bfceaa36d4452c7b7a1869d2f1cdb18/68747470733a2f2f7a692e66692f77732d7369676e616c732e706e67) +![](https://camo.githubusercontent.com/ea2894c88bedf37a4f12f1296569e8fd14bfceaa36d4452c7b7a1869d2f1cdb18/687477733a2f2f7a692f77732d73696e616c732e706e67) -### Simplified signals +### 简化信号 -Sanic has always enforced a three part naming convention for signals: `one.two.three`. However, now you can create simpler names that are only a single part. +“Sanic”总是强制执行三部分命名标记协议：`one e.tw.three`。 然而，现在你可以创建更简单的名字，这只是一个部件。 ```python @app.signal("foo") @@ -128,42 +128,42 @@ async def foo(): ... ``` -You can make that part dynamic just like with regular signals and routes: +你可以让这个部件与正常信号和路由一样动态： ```python @app.signal("") -async def handler(**kwargs): - print("foobar signal received") +async def 处理器(**kwargs): + print("收到foobar 信号") print(kwargs) -@app.route("/") -async def test(request: Request): - await request.app.dispatch("foobar") +@app. oute("/") +异步测试(请求: 请求): + 等待request.appailch("foobar") return json({"hello": "world"}) ``` -If you need to have multiple dynamic signals, then you should use the longer three-part format. +如果您需要有多个动态信号，那么您应该使用较长的三部分格式。 -### The `event` method has been updated +### `event` 方法已被更新 -A number of changes have been made to both `app.event()` and `blueprint.event()`. +对 `app.event()` 和 `bluprint.event()`都做了一些修改。 -- `condition` and `exclusive` are keywords to control matching conditions (similar to the `signal()` methods) -- You can pass either a `str` or an `Enum` (just like `signal()`) -- returns a copy of the context that was passed to the `dispatch()` method +- `condition` 和 `exclusive` 是控制匹配条件的关键字 (类似于“signal()\` 方法) +- 您可以通过 `str` 或 `Enum` (就像`signal()`) +- 返回传递到调度()方法的上下文副本 -### Reload trigger gets changed files +### 重新加载触发器文件已更改 -The files changed by the reloader are now injected into the listener. This will allow the trigger to do something with knowledge of what those changed files were. +由读取器更改的文件现在被注入到侦听器。 这将允许触发器在知道那些更改过的文件的情况下做一些事情。 ```python -@app.after_reload_trigger -async def after_reload_trigger(_, changed): - print(changed) +@app.after_reload_tend +async def after _reload_trigger(_, 更改): + 打印(更改) ``` -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -182,4 +182,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 7b98e6fd6ed1c3420b0b7fc27b286bffd227b7d8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:15 +0200 Subject: [PATCH 451/698] New translations v23.3.md (Japanese) --- guide/content/ja/release-notes/2023/v23.3.md | 226 +++++++++---------- 1 file changed, 113 insertions(+), 113 deletions(-) diff --git a/guide/content/ja/release-notes/2023/v23.3.md b/guide/content/ja/release-notes/2023/v23.3.md index 70dc746698..b0e65eefeb 100644 --- a/guide/content/ja/release-notes/2023/v23.3.md +++ b/guide/content/ja/release-notes/2023/v23.3.md @@ -1,46 +1,46 @@ --- -title: Version 23.3 +title: バージョン 23.3 --- -# Version 23.3 +# バージョン 23.3 -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the first release of the version 23 [release cycle](../../org/policies.md#release-schedule). As such contains some deprecations and hopefully some _small_ breaking changes. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). +これはバージョン23format@@0(../../org/polices.md#release-schedule)の最初のリリースです。 このように、いくつかの廃止予定が含まれており、うまくいけばいくつかの_小規模な_破壊的な変更があります。 何か問題が発生した場合は、 [GitHub](https://github.com/sanic-org/sanic/issues/new/choose) にご注意ください。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Nicer traceback formatting +### より優れたトレースバックのフォーマット -The SCO adopted two projects into the Sanic namespace on GitHub: [tracerite](https://github.com/sanic-org/tracerite) and [html5tagger](https://github.com/sanic-org/html5tagger). These projects team up to provide and incredible new error page with more details to help the debugging process. +SCOは2つのプロジェクトをGitHub上のSanic名前空間に採用しました: [tracerite](https://github.com/sanic-org/tracerite) と [html5tagger](https://github.com/sanic-org/html5tagger) これらのプロジェクトは、デバッグプロセスに役立つ詳細を提供し、信じられないほどの新しいエラーページを提供するためにチームを編成します。 -This is provided out of the box, and will adjust to display only relevant information whether in DEBUG more or PROD mode. +これは、DEBUGモードまたはPRODモードにかかわらず、関連する情報のみを表示するように調整されます。 -.. column:: +.. 列:: ``` -**Using PROD mode** +**PRODモードを使用** ![image](/assets/images/error-html-no-debug.png) ``` -.. column:: +.. 列:: ``` -**Using DEBUG mode** +**DEBUGモードを使う** ![image](/assets/images/error-html-debug.png) ``` -Light and dark mode HTML pages are available and will be used implicitly. +ライトモードとダークモード HTMLページは利用可能で、暗黙的に使用されます。 -### Basic file browser on directories +### ディレクトリの基本的なファイルブラウザー -When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. +静的ハンドラからディレクトリを提供する場合、Sanic は `directory_view=True` を使用して基本的なファイルブラウザーを表示するように設定することができます。 -.. column:: +.. 列:: ```` ```python @@ -48,19 +48,19 @@ app.static("/uploads/", "/path/to/dir/", directory_view=True) ``` ```` -.. column:: +.. 列:: ``` ![image](/assets/images/directory-view.png) ``` -Light and dark mode HTML pages are available and will be used implicitly. +ライトモードとダークモード HTMLページは利用可能で、暗黙的に使用されます。 -### HTML templating with Python +### PythonでHTMLテンプレートを作成 -Because Sanic is using [html5tagger](https://github.com/sanic-org/html5tagger) under the hood to render the [new error pages](#nicer-traceback-formatting), you now have the package available to you to easily generate HTML pages in Python code: +Sanic は [html5tagger](https://github) を使用しているためです。 om/sanic-org/html5tagger) format@@0(#nicer-traceback-formatting) をボンネットの下にレンダリングします。 Pythonコードで簡単にHTMLページを生成できるようになりました。 -.. column:: +.. 列:: ```` ```python @@ -82,7 +82,7 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列:: ```` ```html @@ -105,84 +105,84 @@ async def handler(request: Request): ``` ```` -### Auto-index serving is available on static handlers +### 自動インデックス提供は静的ハンドラで利用できます -Sanic can now be configured to serve an index file when serving a static directory. +Sanicは、静的ディレクトリを提供するときにインデックスファイルを提供するように設定できるようになりました。 ```python app.static("/assets/", "/path/to/some/dir", index="index.html") ``` -When using the above, requests to `http://example.com/assets/` will automatically serve the `index.html` file located in that directory. +上記を使用する場合、`http://example.com/assets/`へのリクエストは、そのディレクトリにある`index.html`ファイルを自動的に提供します。 -### Simpler CLI targets +### シンプルな CLI ターゲット -It is common practice for Sanic applications to use the variable `app` as the application instance. Because of this, the CLI application target (the second value of the `sanic` CLI command) now tries to infer the application instance based upon what the target is. If the target is a module that contains an `app` variable, it will use that. +Sanicアプリケーションでは、変数`app`をアプリケーションインスタンスとして使用するのが一般的です。 このためです CLI アプリケーションのターゲット (`sanic` コマンドの 2 番目の値) は、ターゲットに基づいてアプリケーションのインスタンスを推定しようとします。 ターゲットが `app` 変数を含むモジュールの場合は、それを使用します。 -There are now four possible ways to launch a Sanic application from the CLI. +現在、CLI から Sanic アプリケーションを起動する方法は 4 つあります。 -#### 1. Application instance +#### 1. アプリケーションインスタンス -As normal, providing a path to a module and an application instance will work as expected. +通常と同様に、モジュールとアプリケーションインスタンスへのパスを提供することは期待どおりに動作します。 ```sh -sanic path.to.module:app # global app instance +sanic path.to.module:app # グローバルアプリ インスタンス ``` -#### 2. Application factory +#### 2. 申請工場 -Previously, to serve the factory pattern, you would need to use the `--factory` flag. This can be omitted now. +以前は、ファクトリパターンを提供するには、 `--factory` フラグを使用する必要がありました。 これは現在省略できます。 ```sh -sanic path.to.module:create_app # factory pattern +sanic path.to.module:create_app # ファクトリパターン ``` -#### 3. Path to launch Sanic Simple Server +#### 3. Sanic Simple Server を起動するパス -Similarly, to launch the Sanic simple server (serve static directory), you previously needed to use the `--simple` flag. This can be omitted now, and instead simply provide the path to the directory. +同様に、Sanic シンプルなサーバー (静的ディレクトリを提供する) を起動するには、以前は `--simple` フラグを使用する必要がありました。 これを省略することができ、代わりにディレクトリへのパスを単純に提供します。 ```sh -sanic ./path/to/directory/ # simple serve +sanic ./path/to/directory/ # simple serve ``` -#### 4. Python module containing an `app` variable +#### 4. 変数`app`を含むPythonモジュール -As stated above, if the target is a module that contains an `app` variable, it will use that (assuming that `app` variable is a `Sanic` instance). +前述のように、ターゲットが `app` 変数を含むモジュールの場合。 これを使用します (変数`app`が`Sanic`インスタンスであると仮定します)。 ```sh -sanic path.to.module # module with app instance +appインスタンスを持つsanic path.to.module # モジュール ``` -### More convenient methods for setting and deleting cookies +### Cookieの設定と削除のためのより便利な方法 -The old cookie pattern was awkward and clunky. It didn't look like regular Python because of the "magic" going on under the hood. +古いクッキーのパターンはぎこちなくて不器用でした。 普通のPythonのようには見えませんでした。なぜなら、"魔法"がオンになっているからです。 -.. column:: +.. 列:: ``` -😱 This is not intuitive and is confusing for newcomers. +😱 これは直感的ではなく、新規参入者にとって混乱しています。 ``` -.. column:: +.. 列:: ```` ```python -response = text("There's a cookie up in this response") +response = text("このレスポンスにはクッキーがあります") response.cookies["test"] = "It worked!" -response.cookies["test"]["domain"] = ".yummy-yummy-cookie.com" +response. ookies["test"]["domain"] = ".yummy-yummy-cookie.com" response.cookies["test"]["httponly"] = True ``` ```` -There are now new methods (and completely overhauled `Cookie` and `CookieJar` objects) to make this process more convenient. +このプロセスをより便利にするために、新しいメソッド(完全に`Cookie`と`CookieJar`オブジェクト)が追加されました。 -.. column:: +.. 列:: ``` -😌 Ahh... Much nicer. +:releaseed_face: ああ...もっといい。 ``` -.. column:: +.. 列:: ```` ```python @@ -196,80 +196,80 @@ response.add_cookie( ``` ```` -### Better cookie compatibility +### より良いクッキーの互換性 -Sanic has added support for [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes), making it seemless and easy to read and write cookies with the values. +Sanic は [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookie#cookie_prefixes) のサポートを追加しました。これにより、値を持つ Cookie を読み書きしやすくなりました。 -While setting the cookie... +Cookieの設定中... ```py response.cookies.add_cookie("foo", "bar", host_prefix=True) ``` -This will create the prefixed cookie: `__Host-foo`. However, when accessing the cookie on an incoming request, you can do so without knowing about the existence of the header. +`__Host-foo`というプレフィックス付きのクッキーが作成されます。 ただし、リクエストでクッキーにアクセスする場合は、ヘッダーの存在を知らなくてもアクセスできます。 ```py request.cookies.get("foo") ``` -It should also be noted, cookies can be accessed as properties just like [headers](#access-any-header-as-a-property). +なお、クッキーは [headers](#access-any-header-as-a-property) と同様のプロパティとしてアクセスすることもできます。 ```python request.cookies.foo ``` -And, cookies are similar to the `request.args` and `request.form` objects in that multiple values can be retrieved using `getlist`. +クッキーは `request.args` と `request.form` オブジェクトに似ており、複数の値を取得するには `getlist` を使用します。 ```py request.cookies.getlist("foo") ``` -Also added is support for creating [partitioned cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie). +format@@0(https\://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie)の作成もサポートされています。 ```py response.cookies.add_cookie(..., partitioned=True) ``` -### 🚨 _BREAKING CHANGE_ - More consistent and powerful `SanicException` +### 🚨 _BREAKING CHANGE_ - より強力な `SanicException` -Sanic has for a while included the `SanicException` as a base class exception. This could be extended to add `status_code`, etc. [See more details](http://localhost:8080/en/guide/best-practices/exceptions.html). +Sanicは基本クラスの例外として`SanicException`をしばらく含んでいます。 これは `status_code` などを追加するために拡張できます。format@@0(http\://localhost:8080/ja/guide/best-practics/exceptions.html) -**NOW**, using all of the various exceptions has become easier. The commonly used exceptions can be imported directly from the root level module. +**今です**、様々な例外をすべて使うのが簡単になりました。 一般的に使用される例外は、ルートレベルモジュールから直接インポートできます。 ```python from sanic import NotFound, Unauthorized, BadRequest, ServerError ``` -In addition, all of these arguments are available as keyword arguments on every exception type: +さらに、これらの引数はすべて例外型ごとにキーワード引数として使用できます。 -| argument | type | description | -| --------- | ------ | ----------------------------------------------------------- | -| `quiet` | `bool` | Suppress the traceback from the logs | -| `context` | `dict` | Additional information shown in error pages _always_ | -| `extra` | `dict` | Additional information shown in error pages in _DEBUG_ mode | -| `headers` | `dict` | Additional headers sent in the response | +| 引数 | タイプ | 説明 | +| --------- | ------ | ---------------------------- | +| `quiet` | `bool` | ログからのトレースバックを抑制する | +| `context` | `dict` | エラーページに表示される追加情報 _常時_ | +| `extra` | `dict` | _DEBUG_ モードでエラーページに表示される追加情報 | +| `headers` | `dict` | 返信に送信される追加ヘッダー | -None of these are themselves new features. However, they are more consistent in how you can use them, thus creating a powerful way to control error responses directly. +これらのどれもそれ自体の新機能ではありません。 しかし、それらの使用方法により一貫性が高いため、エラー応答を直接制御する強力な方法が作成されます。 ```py raise ServerError(headers={"foo": "bar"}) ``` -The part of this that is a breaking change is that some formerly positional arguments are now keyword only. +これの部分は、以前は位置引数がキーワードのみであるということです。 -You are encouraged to look at the specific implementations for each error in the [API documents](https://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions). +format@@0(https\://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions)にある各エラーの実装を確認することをお勧めします。 -### 🚨 _BREAKING CHANGE_ - Refresh `Request.accept` functionality to be more performant and spec-compliant +### 🚨 _BREAKING 変更_ - `Request.accept` 機能をよりパフォーマンスと仕様準拠に更新します。 -Parsing od the `Accept` headers into the `Request.accept` accessor has been improved. If you were using this property and relying upon its equality operation, this has changed. You should probably transition to using the `request.accept.match()` method. +`Accessor に `Accept`ヘッダを解析する機能が改善されました。 このプロパティを使用していて、その等価性操作に頼っていた場合、これは変更されました。 おそらく、`request.accept.match()\` メソッドを使用する必要があります。 -### Access any header as a property +### プロパティとして任意のヘッダーにアクセス -To simplify access to headers, you can access a raw (unparsed) version of the header as a property. The name of the header is the name of the property in all lowercase letters, and switching any hyphens (`-`) to underscores (`_`). +ヘッダーへのアクセスを簡単にするために、ヘッダーの未処理バージョンにプロパティとしてアクセスできます。 ヘッダーの名前は、すべての小文字のプロパティの名前で、ハイフン(`-`)をアンダースコア(`_`)に切り替えます。 -For example: +例: -.. column:: +.. 列:: ```` ``` @@ -280,7 +280,7 @@ X-Request-ID: 123ABC ``` ```` -.. column:: +.. 列:: ```` ```py @@ -290,13 +290,13 @@ request.headers.x_request_id ``` ```` -### Consume `DELETE` body by default +### デフォルトで `DELETE` ボディを消費する -By default, the body of a `DELETE` request will now be consumed and read onto the `Request` object. This will make `body` available like on `POST`, `PUT`, and `PATCH` requests without any further action. +デフォルトでは、 `DELETE` リクエストの本文が使用され、 `Request` オブジェクトに読み込まれるようになりました。 `POST`、`PUT`、`PATCH`リクエストのように、 `body`を利用できるようにします。 -### Custom `CertLoader` for direct control of creating `SSLContext` +### `SSLContext`を作成することを直接制御するためのカスタム`CertLoader` -Sometimes you may want to create your own `SSLContext` object. To do this, you can create your own subclass of `CertLoader` that will generate your desired context object. +独自の `SSLContext` オブジェクトを作成したい場合もあります。 これを行うには、目的のコンテキストオブジェクトを生成する `CertLoader` のサブクラスを作成できます。 ```python from sanic.worker.loader import CertLoader @@ -308,28 +308,28 @@ class MyCertLoader(CertLoader): app = Sanic(..., certloader_class=MyCertLoader) ``` -### Deprecations and Removals +### 非推奨と削除 -1. _DEPRECATED_ - Dict-style cookie setting -2. _DEPRECATED_ - Using existence of JSON data on the request for one factor in using JSON error formatter -3. _REMOVED_ - Remove deprecated `__blueprintname__` property -4. _REMOVED_ - duplicate route names -5. _REMOVED_ - duplicate exception handler definitions -6. _REMOVED_ - inspector CLI with flags -7. _REMOVED_ - legacy server (including `sanic.server.serve_single` and `sanic.server.serve_multiple`) -8. _REMOVED_ - serving directory with bytes string -9. _REMOVED_ - `Request.request_middleware_started` -10. _REMOVED_ - `Websocket.connection` +1. _DEPRECATED_ - Dict-style cookieの設定 +2. _DEPRECATED_ - JSON エラーフォーマッタを使用する場合、1つの要因に対するリクエストに JSON データの存在を使用する +3. _削除_ - 非推奨の`__blueprintname__` プロパティ +4. _削除_ - ルート名の重複 +5. _削除_ - 重複した例外ハンドラーの定義 +6. _削除_ - 旗付きインスペクタCLI +7. _削除_ - レガシーサーバー (`sanic.server.serve_single` と `sanic.server.serve_multiple` を含む) +8. _REMOVED_ - バイト文字列付きのディレクトリを提供します +9. _削除_ - `Request.request_middleware_started` +10. _削除_ - `Websocket.connection` -#### Duplicated route names are no longer allowed +#### ルート名が重複している場合はもう許可されていません -In version 22.9, Sanic announced that v23.3 would deprecate allowing routes to be registered with duplicate names. If you see the following error, it is because of that change: +バージョン22.9では、Sanicはv23.3がルートを重複した名前で登録できるようにすることを発表しました。 次のエラーが表示された場合は、その変更によるものです。 -> sanic.exceptions.ServerError: Duplicate route names detected: SomeApp.some_handler. You should rename one or more of them explicitly by using the `name` param, or changing the implicit name derived from the class and function name. For more details, please see https\://sanic.dev/en/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed +> sanic.exceptions.ServerError: ルート名が重複しています: SomeApp.some_handler。 `name` パラメータを使用することで、名前を変更する必要があります。 クラスと関数名から派生した暗黙的な名前を変更することもできます。 詳細は https\://sanic.dev/ja/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed を参照してください。 -If you are seeing this, you should opt-in to using explicit names for your routes. +これを見ている場合は、ルートに明示的な名前を使用することをオプトインする必要があります。 -.. column:: +.. 列:: ```` **BAD** @@ -342,7 +342,7 @@ async def handler(request: Request): ``` ```` -.. column:: +.. 列:: ```` **GOOD** @@ -355,11 +355,11 @@ async def handler(request: Request): ``` ```` -#### Response cookies +#### レスポンスクッキー -Response cookies act as a `dict` for compatibility purposes only. In version 24.3, all `dict` methods will be removed and response cookies will be objects only. +レスポンスCookieは互換性の目的でのみ「dict」として機能します。 バージョン 24.3 では、すべての `dict` メソッドは削除され、レスポンクッキーはオブジェクトのみになります。 -Therefore, if you are using this pattern to set cookie properties, you will need to upgrade it before version 24.3. +したがって、クッキーのプロパティを設定するためにこのパターンを使用している場合は、バージョン24.3以前にアップグレードする必要があります。 ```python resp = HTTPResponse() @@ -367,31 +367,31 @@ resp.cookies["foo"] = "bar" resp.cookies["foo"]["httponly"] = True ``` -Instead, you should be using the `add_cookie` method: +代わりに、`add_cookie`メソッドを使用する必要があります。 ```python resp = HTTPResponse() resp.add_cookie("foo", "bar", httponly=True) ``` -#### Request cookies +#### Cookie をリクエスト -Sanic has added support for reading duplicated cookie keys to be more in compliance with RFC specifications. To retain backwards compatibility, accessing a cookie value using `__getitem__` will continue to work to fetch the first value sent. Therefore, in version 23.3 and prior versions this will be `True`. +Sanicは、RFC 仕様に準拠するために重複した Cookie キーを読み取るサポートを追加しました。 後方互換性を維持するために、`__getitem__`を使用してクッキーの値にアクセスすると、送信された最初の値を取得するために動作します。 したがって、バージョン23.3以前のバージョンでは、これは `True` になります。 ```python assert request.cookies["foo"] == "bar" assert request.cookies.get("foo") == "bar" ``` -Version 23.3 added `getlist` +バージョン 23.3 が `getlist` を追加しました ```python assert request.cookies.getlist("foo") == ["bar"] ``` -As stated above, the `get` and `getlist` methods are available similar to how they exist on other request properties (`request.args`, `request.form`, etc). Starting in v24.3, the `__getitem__` method for cookies will work exactly like those properties. This means that `__getitem__` will return a list of values. +上記のように、他のリクエストプロパティ(`request.args`、`request.form`など)にあるように、`get`と`getlist`メソッドが利用できます。 v24.3 以降、クッキーの `__getitem__` メソッドはこれらのプロパティとまったく同じように動作します。 これは、`__getitem__`が値のリストを返すことを意味します。 -Therefore, if you are relying upon this functionality to return only one value, you should upgrade to the following pattern before v24.3. +したがって、この機能を使用して1つの値だけを返す場合は、v24.3の前に以下のパターンにアップグレードしてください。 ```python assert request.cookies["foo"] == ["bar"] @@ -399,9 +399,9 @@ assert request.cookies.get("foo") == "bar" assert request.cookies.getlist("foo") == ["bar"] ``` -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@ahopkins](https://github.com/ahopkins) [@ChihweiLHBird](https://github.com/ChihweiLHBird) @@ -418,4 +418,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From eb8999b02184d072327864f85cc1e15b02c26931 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:18 +0200 Subject: [PATCH 452/698] New translations v23.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.3.md | 296 +++++++++---------- 1 file changed, 148 insertions(+), 148 deletions(-) diff --git a/guide/content/zh/release-notes/2023/v23.3.md b/guide/content/zh/release-notes/2023/v23.3.md index 70dc746698..3f6a2a4ce0 100644 --- a/guide/content/zh/release-notes/2023/v23.3.md +++ b/guide/content/zh/release-notes/2023/v23.3.md @@ -1,46 +1,46 @@ --- -title: Version 23.3 +title: 23.3 版本 --- -# Version 23.3 +# 23.3 版本 .. toc:: -## Introduction +## 一. 导言 -This is the first release of the version 23 [release cycle](../../org/policies.md#release-schedule). As such contains some deprecations and hopefully some _small_ breaking changes. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). +这是第23版的第一次版本[发行周期](../../org/policies.md#release-schedule)。 因此含有一些废弃的偏见，希望有些_小_断裂的修改。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出一个问题。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### Nicer traceback formatting +### 较好的追踪格式 -The SCO adopted two projects into the Sanic namespace on GitHub: [tracerite](https://github.com/sanic-org/tracerite) and [html5tagger](https://github.com/sanic-org/html5tagger). These projects team up to provide and incredible new error page with more details to help the debugging process. +上合组织在GitHub上通过了两个项目，将其纳入Sanic命名空间： [tracerite](https://github.com/sanic-org/tracerite) 和 [html5tagger](https://github.com/sanic-org/html5tagger)。 这些项目团队可以提供和令人难以置信的新错误页面，并提供更多详细信息来帮助调试过程。 -This is provided out of the box, and will adjust to display only relevant information whether in DEBUG more or PROD mode. +这是由方框提供的，并将调整以只显示相关信息，不管是在DEBUG 更多还是PROD 模式。 -.. column:: +.. 列: ``` **Using PROD mode** ![image](/assets/images/error-html-no-debug.png) ``` -.. column:: +.. 列: ``` **Using DEBUG mode** ![image](/assets/images/error-html-debug.png) ``` -Light and dark mode HTML pages are available and will be used implicitly. +浅暗模式的 HTML 页面可用，将被隐含使用。 -### Basic file browser on directories +### 目录上的基本文件浏览器 -When serving a directory from a static handler, Sanic can be configured to show a basic file browser instead using `directory_view=True`. +当使用静态处理器的目录时，Sanic可以被配置为显示基本文件浏览器，而不是使用 `directory_view=True`。 -.. column:: +.. 列: ```` ```python @@ -48,48 +48,48 @@ app.static("/uploads/", "/path/to/dir/", directory_view=True) ``` ```` -.. column:: +.. 列: ``` ![image](/assets/images/directory-view.png) ``` -Light and dark mode HTML pages are available and will be used implicitly. +浅暗模式的 HTML 页面可用，将被隐含使用。 -### HTML templating with Python +### 使用 Python 的 HTML 模板 -Because Sanic is using [html5tagger](https://github.com/sanic-org/html5tagger) under the hood to render the [new error pages](#nicer-traceback-formatting), you now have the package available to you to easily generate HTML pages in Python code: +因为Sanic正在使用 [html5tagger](https://github)。 om/sanic-org/html5tagger，用于渲染[新的错误页面](#nicer-traceback-forming), 您现在有可用的软件包可以轻松生成Python代码的 HTML 页面： -.. column:: +.. 列: ```` ```python from html5tagger import Document from sanic import Request, Sanic, html -app = Sanic("TestApp") +app = Sanic("测试应用") -@app.get("/") -async def handler(request: Request): - doc = Document("My Website") - doc.h1("Hello, world.") - with doc.table(id="data"): - doc.tr.th("First").th("Second").th("Third") +@app. et("/") +async def 处理器(请求: 请求): + doc = Document("我的网站") + doc. 1 ("你好，世界。") + 与doc. able(id="data "): + doc.tr.th("First").th("Second"). h("Third") doc.tr.td(1).td(2).td(3) - doc.p(class_="text")("A paragraph with ") - doc.a(href="/files")("a link")(" and ").em("formatting") + doc. (tclass_="text")("A paragraph with ") + doc.ahhref="/files")("a link")(" and ").em("格式化") return html(doc) ``` ```` -.. column:: +.. 列: ```` ```html -My Website -

Hello, world.

+我的网站 +

Hello, world。

First @@ -101,186 +101,186 @@ async def handler(request: Request): 3

- A paragraph with a link and formatting + A paragraph with a link and forming ``` ```` -### Auto-index serving is available on static handlers +### 自动索引服务在静态处理程序上可用 -Sanic can now be configured to serve an index file when serving a static directory. +Sanic 现在可以配置为静态目录时的索引文件。 ```python app.static("/assets/", "/path/to/some/dir", index="index.html") ``` -When using the above, requests to `http://example.com/assets/` will automatically serve the `index.html` file located in that directory. +当使用上述内容时，`http://example.com/assets/`将自动为位于该目录的`index.html`文件服务。 -### Simpler CLI targets +### 简单的 CLI 目标 -It is common practice for Sanic applications to use the variable `app` as the application instance. Because of this, the CLI application target (the second value of the `sanic` CLI command) now tries to infer the application instance based upon what the target is. If the target is a module that contains an `app` variable, it will use that. +Sanic 应用程序通常使用变量`app`作为应用程序实例。 由于这个原因， CLI 应用程序目标 (`sanic` CLI 命令的第二值) 现在试图根据目标推断应用程序实例。 如果目标是包含一个`app`变量的模块，它将使用它。 -There are now four possible ways to launch a Sanic application from the CLI. +现在有四种可能的方式从地方倡议启动一个Sanic应用程序。 -#### 1. Application instance +#### 1. 应用程序实例 -As normal, providing a path to a module and an application instance will work as expected. +正常情况下，为模块和应用程序实例提供路径将按预期工作。 ```sh -sanic path.to.module:app # global app instance +sanic path.to.module:app # 全局应用实例 ``` -#### 2. Application factory +#### 2. 应用工厂： -Previously, to serve the factory pattern, you would need to use the `--factory` flag. This can be omitted now. +以前，为了服务出厂模式，你需要使用 "--factory" 旗帜。 现在可以省略。 ```sh -sanic path.to.module:create_app # factory pattern +sanic path.to.module:create_app # 出厂模式 ``` -#### 3. Path to launch Sanic Simple Server +#### 3. 启动Sanic 简单服务器路径 -Similarly, to launch the Sanic simple server (serve static directory), you previously needed to use the `--simple` flag. This can be omitted now, and instead simply provide the path to the directory. +同样，要启动 Sanic 简单服务器 (服务静态目录)，您以前需要使用 "--simple" 旗帜。 现在这可以省略，而只是提供到目录的路径。 ```sh -sanic ./path/to/directory/ # simple serve +sanic ./path/to/directory/ # 简单服务 ``` -#### 4. Python module containing an `app` variable +#### 4. 包含一个`app`变量的 Python 模块 -As stated above, if the target is a module that contains an `app` variable, it will use that (assuming that `app` variable is a `Sanic` instance). +如上所述，如果目标是包含一个`app`变量的模块， 它将使用那个(假设`app`变量是一个 `Sanic` 实例)。 ```sh -sanic path.to.module # module with app instance +带有应用程序实例的 sanic path.to.module # 模块 ``` -### More convenient methods for setting and deleting cookies +### 更方便的 cookie 设置和删除 -The old cookie pattern was awkward and clunky. It didn't look like regular Python because of the "magic" going on under the hood. +旧的 cookie 模式非常糟糕，很难找。 它看起来不像普通的 Python ，因为那个尺寸下“魔法”。 -.. column:: +.. 列: ``` -😱 This is not intuitive and is confusing for newcomers. +:fac_screaming_in_fear: 这不是直观的，对新来者来说是混淆不清的。 ``` -.. column:: +.. 列: ```` ```python -response = text("There's a cookie up in this response") -response.cookies["test"] = "It worked!" -response.cookies["test"]["domain"] = ".yummy-yummy-cookie.com" -response.cookies["test"]["httponly"] = True +response = text("在这个响应中有一个 cookie ") +response.cookies["test"] = "它正常工作！" +响应。 ookies["test"]["domain"] = ".yummy-yummy-cookie.com" +response.cookies["test"]["httuponly"] = True ``` ```` -There are now new methods (and completely overhauled `Cookie` and `CookieJar` objects) to make this process more convenient. +现在已经有了新的方法（以及完全全面的`Cookie`和CookieJar\`对象）来使这个过程更加方便。 -.. column:: +.. 列: ``` -😌 Ahh... Much nicer. +😌 Ahh... 非常好。 ``` -.. column:: +.. 列: ```` ```python -response = text("There's a cookie up in this response") -response.add_cookie( +response = text("在这个响应中有cookie") +response。 dd_cookie( "test", - "It worked!", - domain=".yummy-yummy-cookie.com", + "it 工作!", + domain=". ummy-yummy-cookie.com", httponly=True ) ``` ```` -### Better cookie compatibility +### 更好的 cookie 兼容性 -Sanic has added support for [cookie prefixes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes), making it seemless and easy to read and write cookies with the values. +Sanic 增加了对 [cookie 前缀](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes)的支持，使读取和写下这些值看起来变得越来越简单。 -While setting the cookie... +设置cookie时... ```py -response.cookies.add_cookie("foo", "bar", host_prefix=True) +响应.cookies.add_cookie("foo", "bar", host_prefix=True) ``` -This will create the prefixed cookie: `__Host-foo`. However, when accessing the cookie on an incoming request, you can do so without knowing about the existence of the header. +这将创建预设的 cookie: `__Host-foo`。 然而，当访问传入请求时您可以在不知道头部存在的情况下访问cookie。 ```py -request.cookies.get("foo") +cookie.get("foo") ``` -It should also be noted, cookies can be accessed as properties just like [headers](#access-any-header-as-a-property). +还应该注意到，cookie可以作为属性访问，如 [headers](#access-any-header-as a property)。 ```python -request.cookies.foo +Cookie.foo ``` -And, cookies are similar to the `request.args` and `request.form` objects in that multiple values can be retrieved using `getlist`. +而且，cookie类似于“request.args”和“request.form”对象，因为可以使用 `getlist` 获取多个值。 ```py -request.cookies.getlist("foo") +cookie.getlist("foo") ``` -Also added is support for creating [partitioned cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie). +还添加了支持创建 [分区的 cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie)。 ```py -response.cookies.add_cookie(..., partitioned=True) +响应.cookies.add_cookie(...，分区=True) ``` -### 🚨 _BREAKING CHANGE_ - More consistent and powerful `SanicException` +### 🚨 _Breaking变换_ - 更加一致和强大的 `SanicException` -Sanic has for a while included the `SanicException` as a base class exception. This could be extended to add `status_code`, etc. [See more details](http://localhost:8080/en/guide/best-practices/exceptions.html). +Sanic已经有一段时间将`SanicException`作为基本类别的例外。 可将其扩展到添加`status_code`等（详见http\://localhost:8080/en/guide/best practices/exceptions.html）。 -**NOW**, using all of the various exceptions has become easier. The commonly used exceptions can be imported directly from the root level module. +**NOW**，使用所有不同的例外已变得更加容易。 通常使用的异常可以直接从 root 级模块导入。 ```python -from sanic import NotFound, Unauthorized, BadRequest, ServerError +从 NotFound, 未经授权, BadRequest, ServerError ``` -In addition, all of these arguments are available as keyword arguments on every exception type: +此外，所有这些参数都可以作为关键词参数用于每个异常类型： -| argument | type | description | -| --------- | ------ | ----------------------------------------------------------- | -| `quiet` | `bool` | Suppress the traceback from the logs | -| `context` | `dict` | Additional information shown in error pages _always_ | -| `extra` | `dict` | Additional information shown in error pages in _DEBUG_ mode | -| `headers` | `dict` | Additional headers sent in the response | +| 参数 | 类型 | 描述 | +| --------- | ------ | -------------------------- | +| 安静\` | `bool` | 从日志中取消跟踪 | +| `context` | `dict` | 错误页面_总是显示额外信息_ | +| `extra` | `dict` | 在 \*DEBUG 模式下的错误页面中显示的额外信息 | +| `headers` | `dict` | 响应中发送的更多信头 | -None of these are themselves new features. However, they are more consistent in how you can use them, thus creating a powerful way to control error responses directly. +所有这些本身都不是新的特征。 然而，它们在如何使用它们方面更加一致，从而创造了一种直接控制错误响应的强大方式。 ```py -raise ServerError(headers={"foo": "bar"}) +升起服务器错误(headers={"foo": "bar"}) ``` -The part of this that is a breaking change is that some formerly positional arguments are now keyword only. +这种变化的一个重要部分是，有些原先的立场论点现在只是关键词。 -You are encouraged to look at the specific implementations for each error in the [API documents](https://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions). +鼓励您查看[API 文档](https://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions)中每个错误的具体实现。 -### 🚨 _BREAKING CHANGE_ - Refresh `Request.accept` functionality to be more performant and spec-compliant +### 🚨 _Breaking变换_ - 刷新`Request.accept` 功能以提高性能和投影兼容性 -Parsing od the `Accept` headers into the `Request.accept` accessor has been improved. If you were using this property and relying upon its equality operation, this has changed. You should probably transition to using the `request.accept.match()` method. +解析`接受`标题'到 `Request.accept` 访问器已经改进。 如果你正在使用这个财产并依靠它的平等操作，这种情况已经改变。 您可能应该转换为 `request.accept.match()` 方法。 -### Access any header as a property +### 以属性访问任何页眉内容 -To simplify access to headers, you can access a raw (unparsed) version of the header as a property. The name of the header is the name of the property in all lowercase letters, and switching any hyphens (`-`) to underscores (`_`). +为了简化对页眉的访问权限，您可以访问原始(未解析的)页眉版本作为属性。 标题的名称是所有小写字母中的属性的名称, 并切换任何连字符(`-`) 到下划线 (`_`). -For example: +例如： -.. column:: +.. 列: ```` ``` -GET /foo/bar HTTP/1.1 -Host: localhost +GET /foot/bar HTTP/1.1 +主机：localhost User-Agent: curl/7.88.1 X-Request-ID: 123ABC ``` ```` -.. column:: +.. 列: ```` ```py @@ -290,76 +290,76 @@ request.headers.x_request_id ``` ```` -### Consume `DELETE` body by default +### 默认消耗`DELETE` 体 -By default, the body of a `DELETE` request will now be consumed and read onto the `Request` object. This will make `body` available like on `POST`, `PUT`, and `PATCH` requests without any further action. +默认情况下，一个 `DELETE` 请求的正文将会被消耗并读取到 `Request` 对象。 这将使`body`像`POST`、`PUT`和`PATCH`请求一样无需采取任何进一步行动。 -### Custom `CertLoader` for direct control of creating `SSLContext` +### 自定义 `CertLoader` 用于直接控制创建 `SSLContext` -Sometimes you may want to create your own `SSLContext` object. To do this, you can create your own subclass of `CertLoader` that will generate your desired context object. +有时，您可能想要创建自己的 `SSLContext` 对象。 要做到这一点，你可以创建你自己的 `CertLoader` 子类，生成你所需的上下文对象。 ```python -from sanic.worker.loader import CertLoader +从 sanic.worker.loader 导入 CertLoader -class MyCertLoader(CertLoader): +类 MyCertLoader(CertLoader): def load(self, app: Sanic) -> SSLContext: ... -app = Sanic(..., certloader_class=MyCertLoader) +app = Sanic(...certloader_class=MyCertLoader) ``` -### Deprecations and Removals +### 废弃和移除 -1. _DEPRECATED_ - Dict-style cookie setting -2. _DEPRECATED_ - Using existence of JSON data on the request for one factor in using JSON error formatter +1. _DEECATED_-Dict-样式 cookie 设置 +2. _DEECATED_ - 使用 JSON 数据请求使用JSON 错误格式化一个因素时使用 JSON 数据 3. _REMOVED_ - Remove deprecated `__blueprintname__` property -4. _REMOVED_ - duplicate route names -5. _REMOVED_ - duplicate exception handler definitions -6. _REMOVED_ - inspector CLI with flags -7. _REMOVED_ - legacy server (including `sanic.server.serve_single` and `sanic.server.serve_multiple`) -8. _REMOVED_ - serving directory with bytes string -9. _REMOVED_ - `Request.request_middleware_started` -10. _REMOVED_ - `Websocket.connection` +4. _删除_ - 重复路由名称 +5. _REMOVED_ - 重复异常处理器定义 +6. _REMOVED_ - 带着旗帜的检查器 CLI +7. _REMOVED_ - 旧服务器(包括`sanic.server.serve_single` 和 `sanic.server.serve_multiple`) +8. _REMOVED_ - 使用字节字符串的目录 +9. _REMOVED_ - `Request.request_middleware_started` +10. _REMOVED_ - `Websocket.connection` -#### Duplicated route names are no longer allowed +#### 不再允许重复的路由名称 -In version 22.9, Sanic announced that v23.3 would deprecate allowing routes to be registered with duplicate names. If you see the following error, it is because of that change: +在第22.9版中，Sanic宣布说，V23.3不允许使用重复名称注册路线。 如果你看到以下错误，它是因为这种改变： -> sanic.exceptions.ServerError: Duplicate route names detected: SomeApp.some_handler. You should rename one or more of them explicitly by using the `name` param, or changing the implicit name derived from the class and function name. For more details, please see https\://sanic.dev/en/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed +> 异常。服务器错误：检测到重复的路由名称：有人App.some_handler。 您应该使用 "name" 参数来明确重命名其中一个或多个， 或更改来自类和函数名称的隐含名称。 欲了解更多详情，请访问https\://sanic.dev/en/guide/release-notes/v23.3.html#carbated-route-names-are-no longer-allowed -If you are seeing this, you should opt-in to using explicit names for your routes. +如果你看到这一点，你应该选择为你的路线使用明确的名称。 -.. column:: +.. 列: ```` **BAD** ```python -app = Sanic("SomeApp") +app = Sanic("有人应用") @app.get("/") @app.get("/foo") -async def handler(request: Request): +async def handler(请求): ``` ```` -.. column:: +.. 列: ```` **GOOD** ```python -app = Sanic("SomeApp") +app = Sanic("有人应用") @app.get("/", name="root") @app.get("/foo", name="foo") -async def handler(request: Request): +async def handler(请求): ``` ```` -#### Response cookies +#### 响应 cookie -Response cookies act as a `dict` for compatibility purposes only. In version 24.3, all `dict` methods will be removed and response cookies will be objects only. +响应 cookie 仅为了兼容起作用的 `dict` 。 在版本24.3中，所有的`dict`方法将被删除，应答的 cookie 将仅为对象。 -Therefore, if you are using this pattern to set cookie properties, you will need to upgrade it before version 24.3. +因此，如果您使用此模式来设置 cookie 属性，您需要在版本 24.3 之前升级它。 ```python resp = HTTPResponse() @@ -367,39 +367,39 @@ resp.cookies["foo"] = "bar" resp.cookies["foo"]["httponly"] = True ``` -Instead, you should be using the `add_cookie` method: +相反，您应该使用 "add_cookie" 方法： ```python resp = HTTPResponse() resp.add_cookie("foo", "bar", httponly=True) ``` -#### Request cookies +#### 请求 cookie -Sanic has added support for reading duplicated cookie keys to be more in compliance with RFC specifications. To retain backwards compatibility, accessing a cookie value using `__getitem__` will continue to work to fetch the first value sent. Therefore, in version 23.3 and prior versions this will be `True`. +Sanic增加了对阅读重复的 cookie 密钥的支持，以便更加符合RFC 规格。 To retain backwards compatibility, accessing a cookie value using `__getitem__` will continue to work to fetch the first value sent. 因此，在第23.3版和以前的版本中，这将是“True”。 ```python -assert request.cookies["foo"] == "bar" -assert request.cookies.get("foo") == "bar" +cookie["foo"] == "bar" +坚持request.cookies.get("foo") == "bar" ``` -Version 23.3 added `getlist` +版本23.3添加了 `getlist` ```python -assert request.cookies.getlist("foo") == ["bar"] +cookies.getlist("foo") == ["bar"] ``` -As stated above, the `get` and `getlist` methods are available similar to how they exist on other request properties (`request.args`, `request.form`, etc). Starting in v24.3, the `__getitem__` method for cookies will work exactly like those properties. This means that `__getitem__` will return a list of values. +如上文所述，`get` 和 `getlist` 两个方法都是可用的，类似于它们在其他请求属性上的存在方式(`request.args`, `request.form`, 等等)。 Starting in v24.3, the `__getitem__` method for cookies will work exactly like those properties. This means that `__getitem__` will return a list of values. -Therefore, if you are relying upon this functionality to return only one value, you should upgrade to the following pattern before v24.3. +因此，如果你只能依靠此功能返回一个值，你应该在v24.3之前升级到以下模式。 ```python -assert request.cookies["foo"] == ["bar"] -assert request.cookies.get("foo") == "bar" -assert request.cookies.getlist("foo") == ["bar"] +cookies["foo"] == ["bar"] +坚持request.cookies.get("fo") == "bar" +signing request.cookies.getlist("foo") == ["bar"] ``` -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -418,4 +418,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 69e6df10caaf299c100083f830b833c74641ca84 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:19 +0200 Subject: [PATCH 453/698] New translations v23.6.md (Japanese) --- guide/content/ja/release-notes/2023/v23.6.md | 106 +++++++++---------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/guide/content/ja/release-notes/2023/v23.6.md b/guide/content/ja/release-notes/2023/v23.6.md index 74a3260c2b..f32744f8e1 100644 --- a/guide/content/ja/release-notes/2023/v23.6.md +++ b/guide/content/ja/release-notes/2023/v23.6.md @@ -1,50 +1,50 @@ --- -title: Version 23.6 +title: バージョン23.6 --- -# Version 23.6 +# バージョン23.6 -.. toc:: +.. TOC:: -## Introduction +## はじめに -This is the second release of the version 23 [release cycle](../../org/policies.md#release-schedule). If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). +これはバージョン23のformat@@0(../../org/policies.md#release-schedule)の2番目のリリースです。 何か問題が発生した場合は、 [GitHub](https://github.com/sanic-org/sanic/issues/new/choose) にご注意ください。 -## What to know +## 知っておくべきこと -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +詳細は [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html) をご覧ください。 注目すべき新機能や破損した機能、そしてアップグレードする機能... -### Remove Python 3.7 support +### Python 3.7 のサポートを削除 -Python 3.7 is due to reach its scheduled upstream end-of-life on 2023-06-27. Sanic is now dropping support for Python 3.7, and requires Python 3.8 or newer. +Python 3.7 は 2023-06-27 に予定されている上流の終了点に到達する予定です。 Sanic は Python 3.7 のサポートを廃止しており、Python 3.8 以降が必要です。 -See [#2777](https://github.com/sanic-org/sanic/pull/2777). +[#2777](https://github.com/sanic-org/sanic/pull/2777)を参照してください。 -### Resolve pypy compatibility issues +### Pypy 互換性の問題を解決する -A small patch was added to the `os` module to once again allow for Sanic to run with PyPy. This workaround replaces the missing `readlink` function (missing in PyPy `os` module) with the function `os.path.realpath`, which serves to the same purpose. +`os`モジュールにもう一度、SanicがPyPyPyで動くようにするための小さなパッチが追加されました。 この回避策は、欠けている `readlink` 関数 (PyPy `os` モジュールに欠けている) を `os.path.realpath` 関数と置き換えます。 -See [#2782](https://github.com/sanic-org/sanic/pull/2782). +[#2782](https://github.com/sanic-org/sanic/pull/2782)を参照してください。 -### Add custom typing to config and ctx objects +### 設定とctxオブジェクトにカスタム入力を追加する -The `sanic.Sanic` and `sanic.Request` object have become generic types that will make it more convenient to have fully typed `config` and `ctx` objects. +`sanic.Sanic`と`sanic.Request`オブジェクトは、`config`と`ctx`オブジェクトを完全に入力するのに便利な一般的な型になりました。 -In the most simple form, the `Sanic` object is typed as: +最もシンプルな形式では、 `Sanic` オブジェクトは次のように入力されます。 ```python from sanic import Sanic app = Sanic("test") -reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]" +learm_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]" ``` -.. tip:: Note +.. tip:: メモ ``` -It should be noted, there is *no* requirement to use the generic types. The default types are `sanic.config.Config` and `types.SimpleNamespace`. This new feature is just an option for those that want to use it and existing types of `app: Sanic` and `request: Request` should work just fine. +注意してください。一般的な型を使用するための *no* 要件がありません。デフォルトの型は `sanic.config.Config` と `types.SimpleNamespace` です。 この新機能は、既存の`app: Sanic`と`request: Request`を使いたい人のためのオプションにすぎません。 ``` -Now it is possible to have a fully-type `app.config`, `app.ctx`, and `request.ctx` objects though generics. This allows for better integration with auto completion tools in IDEs improving the developer experience. +これで、ジェネリクスではありますが、完全に `app.config`、`app.ctx`、および `request.ctx`オブジェクトを持つことができます。 これにより、IDEの自動補完ツールとの統合が改善され、開発者エクスペリエンスが向上します。 ```python from sanic import Request, Sanic @@ -75,19 +75,19 @@ async def handler(request: CustomRequest): ... ``` -As a side effect, now `request.ctx` is lazy initialized, which should reduce some overhead when the `request.ctx` is unused. +副作用として、`request.tx`は遅延初期化されています。`request.tx`が使用されていない場合のオーバーヘッドを減らす必要があります。 -One further change you may have noticed in the above snippet is the `make_context` method. This new method can be used by custom `Request` types to inject an object different from a `SimpleNamespace` similar to how Sanic has allowed custom application context objects for a while. +上記のスニペットでもう一つの変更点は、 `make_context` メソッドです。 この新しいメソッドは、カスタム `Request` 型で、Sanic がしばらくの間カスタムアプリケーションコンテキストオブジェクトを許可しているのと同様に、 `SimpleNamespace` とは異なるオブジェクトを注入するために使用できます。 -For a more thorough discussion, see [custom typed application](../basics/app.md#custom-typed-application) and [custom typed request](../basics/app.md#custom-typed-request). +詳細については、[custom typed application](../basics/app.md#custom-typed-application) および [custom typed request](../basics/app.md#custom-typed-request) を参照してください。 -See [#2785](https://github.com/sanic-org/sanic/pull/2785). +[#2785](https://github.com/sanic-org/sanic/pull/2785)を参照してください。 -### Universal exception signal +### 普遍的な例外信号 -A new exception signal added for **ALL** exceptions raised while the server is running: `"server.exception.reporting"`. This is a universal signal that will be emitted for any exception raised, and dispatched as its own task. This means that it will _not_ block the request handler, and will _not_ be affected by any middleware. +`"server.exception.reporting"`というサーバーの実行中に発生した**すべての**例外に新しい例外シグナルが追加されました。 これは、任意の例外が発生し、独自のタスクとして発信される普遍的な信号です。 つまり、リクエストハンドラは_ブロックせず_、ミドルウェアは_影響を受けません_。 -This is useful for catching exceptions that may occur outside of the request handler (for example in signals, or in a background task), and it intended for use to create a consistent error handling experience for the user. +これはリクエストハンドラの外で発生する可能性のある例外をキャッチする場合に便利です (シグナルなど)。 またはバックグラウンドタスクで)、一貫性のあるエラー処理エクスペリエンスをユーザーに作成するために使用することを目的としています。 ```python from sanic.signals import Event @@ -97,25 +97,25 @@ async def catch_any_exception(app: Sanic, exception: Exception): app.ctx.my_error_reporter_utility.error(exception) ``` -This pattern can be simplified with a new decorator `@app.report_exception`: +このパターンは、新しいデコレーター `@app.report_exception` で簡略化できます。 ```python @app.report_exception async def catch_any_exception(app: Sanic, exception: Exception): - print("Caught exception:", exception) + print("Caught exception:) ``` -It should be pointed out that this happens in a background task and is **NOT** for manipulation of an error response. It is only for reporting, logging, or other purposes that should be triggered when an application error occurs. +これはバックグラウンドタスクで発生し、エラー応答の操作は**しない**と指摘する必要があります。 これは、アプリケーションエラーが発生したときにトリガーされるレポート、ログ、またはその他の目的のためのものです。 -See [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792). +[#2724](https://github.com/sanic-org/sanic/pull/2724)と[#2792](https://github.com/sanic-org/sanic/pull/2792)を参照してください。 -### Add name prefixing to BP groups +### BPグループの前に名前を追加 -Sanic had been raising a warning on duplicate route names for a while, and started to enforce route name uniqueness in [v23.3](https://sanic.dev/en/guide/release-notes/v23.3.html#deprecations-and-removals). This created a complication for blueprint composition. +Sanicはしばらくの間、ルート名の重複に関する警告を表示しており、 [v23.3](https://sanic.dev/ja/guide/release-notes/v23.3.html#deprecations-and-removals)でルート名の一意性を強制するようになりました。 これによりブループリントの組成が複雑になりました。 -New name prefixing parameter for blueprints groups has been added to alleviate this issue. It allows nesting of blueprints and groups to make them composable. +ブループリントグループの新しい名前プレフィックスパラメータが追加されました。 設計図やグループの入れ子を作ることで、それらを構成可能にします。 -The addition is the new `name_prefix` parameter as shown in this snippet. +このスニペットに示すように、新しいパラメータ`name_prefix`が追加されました。 ```python bp1 = Blueprint("bp1", url_prefix="/bp1") @@ -136,37 +136,37 @@ app.blueprint(group_a) app.blueprint(group_b) ``` -The routes built will be named as follows: +構築されるルートは以下のようになります。 - `TestApp.group-a_bp1.route1` - `TestApp.group-a_bp2.route2` - `TestApp.group-b_bp1.route1` - `TestApp.group-b_bp2.route2` -See [#2727](https://github.com/sanic-org/sanic/pull/2727). +[#2727](https://github.com/sanic-org/sanic/pull/272727)をご覧ください。 -### Add `request.client_ip` +### `request.client_ip`を追加 -Sanic has introduced `request.client_ip`, a new accessor that provides client's IP address from both local and proxy data. It allows running the application directly on Internet or behind a proxy. This is equivalent to `request.remote_addr or request.ip`, providing the client IP regardless of how the application is deployed. +Sanicはローカルとプロキシの両方のデータからクライアントのIPアドレスを提供する新しいaccessorである`request.client_ip`を導入しました。 インターネット上またはプロキシの背後で直接アプリケーションを実行できます。 これは `request.remote_addr や request.ip` と同じで、アプリケーションのデプロイ方法に関係なくクライアントの IP を提供します。 -See [#2790](https://github.com/sanic-org/sanic/pull/2790). +[#2790](https://github.com/sanic-org/sanic/pull/2790)を参照してください。 -### Increase of `KEEP_ALIVE_TIMEOUT` default to 120 seconds +### デフォルトの `KEEP_ALIVE_TIMEOUT` を 120 秒に増やします。 -The default `KEEP_ALIVE_TIMEOUT` value changed from 5 seconds to 120 seconds. It is of course still configurable, but this change should improve performance on long latency connections, where reconnecting is expensive, and better fits typical user flow browsing pages with longer-than-5-second intervals. +デフォルトの `KEEP_ALIVE_TIMEOUT` 値が 5 秒から 120 秒に変更されました。 もちろんまだ設定可能ですが、この変更により、長いレイテンシ接続のパフォーマンスが向上するはずです。 再接続は高価で、一般的なユーザーフロー閲覧ページに5秒間隔以上適合します。 -Sanic has historically used 5 second timeouts to quickly close idle connections. The chosen value of **120 seconds** is indeed larger than Nginx default of 75, and is the same value that Caddy server has by default. +Sanicは、アイドル接続を迅速に閉じるために歴史的に5秒のタイムアウトを使用しています。 選択した値の**120秒**は確かにNginxのデフォルト値75より大きく、Caddyサーバーがデフォルトで持っている値と同じです。 -Related to [#2531](https://github.com/sanic-org/sanic/issues/2531) and -[#2681](https://github.com/sanic-org/sanic/issues/2681). +[#2531](https://github.com/sanic-org/sanic/issues/2531)と +[#2681](https://github.com/sanic-org/sanic/issues/2681)に関連しています。 -See [#2670](https://github.com/sanic-org/sanic/pull/2670). +[#2670](https://github.com/sanic-org/sanic/pull/2670)を参照してください。 -### Set multiprocessing start method early +### マルチプロセッシング開始メソッドを早期に設定 -Due to how Python handles `multiprocessing`, it may be confusing to some users how to properly create synchronization primitives. This is due to how Sanic creates the `multiprocessing` context. This change sets the start method early so that any primitives created will properly attach to the correct context. +Python が `multiprocessing` をどのように扱うかによって、 同期プリミティブを適切に作成する方法を一部のユーザが混乱させるかもしれません。 これは、Sanic が `multiprocessing` コンテキストを作成する方法によるものです。 この変更は、作成された任意のプリミティブが正しいコンテキストに適切にアタッチされるように、start メソッドを早期に設定します。 -For most users, this should not be noticeable or impactful. But, it should make creation of something like this easier and work as expected. +ほとんどのユーザーにとって、これは顕著であり、影響を与えるべきではありません。 しかし、このようなものを作りやすく、期待どおりに動作させるべきです。 ```python from multiprocessing import Queue @@ -176,11 +176,11 @@ async def main_process_start(app): app.shared_ctx.queue = Queue() ``` -See [#2776](https://github.com/sanic-org/sanic/pull/2776). +[#2776](https://github.com/sanic-org/sanic/pull/2776)を参照してください。 -## Thank you +## ありがとうございます -Thank you to everyone that participated in this release: :clap: +このリリースに参加いただき、ありがとうございます： :clap: [@ahopkins](https://github.com/ahopkins) [@ChihweiLHBird](https://github.com/ChihweiLHBird) @@ -196,4 +196,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) From e4107b5324a896a67de15eb9f87850668d5ba9f6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:21 +0200 Subject: [PATCH 454/698] New translations v23.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.6.md | 134 +++++++++---------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/guide/content/zh/release-notes/2023/v23.6.md b/guide/content/zh/release-notes/2023/v23.6.md index 74a3260c2b..f45729cc33 100644 --- a/guide/content/zh/release-notes/2023/v23.6.md +++ b/guide/content/zh/release-notes/2023/v23.6.md @@ -1,36 +1,36 @@ --- -title: Version 23.6 +title: 第23.6版 --- -# Version 23.6 +# 第23.6版 .. toc:: -## Introduction +## 一. 导言 -This is the second release of the version 23 [release cycle](../../org/policies.md#release-schedule). If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). +这是第二次版本的 23 [发行周期] (../../org/policies.md#release-schedule)。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出一个问题。 -## What to know +## 了解什么 -More details in the [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html). Notable new or breaking features, and what to upgrade... +更多详细信息在 [Changelog](https://sanic.readthedocs.io/en/stable/sanic/changelog.html)。 显著的新功能或破损功能以及升级内容... -### Remove Python 3.7 support +### 移除 Python 3.7 支持 -Python 3.7 is due to reach its scheduled upstream end-of-life on 2023-06-27. Sanic is now dropping support for Python 3.7, and requires Python 3.8 or newer. +Python 3.7将于2023-06-27年到达预定的上游报废。 Sanic 正在放弃对 Python 3.7的支持，需要 Python 3.8或更高版本。 -See [#2777](https://github.com/sanic-org/sanic/pull/2777). +见[No. 27777](https://github.com/sanic-org/sanic/pull/2777)。 -### Resolve pypy compatibility issues +### 解决pypy 兼容性问题 -A small patch was added to the `os` module to once again allow for Sanic to run with PyPy. This workaround replaces the missing `readlink` function (missing in PyPy `os` module) with the function `os.path.realpath`, which serves to the same purpose. +在 `os` 模块中添加了一个小补丁，让Sanic 再次与 PyPy 一起运行。 此操作将缺失的 `readlink` 函数(PyPy `os` 模块中缺失) 替换为 `os.path.realpath` 函数，这个函数具有相同的目的。 -See [#2782](https://github.com/sanic-org/sanic/pull/2782). +见[No. 2782](https://github.com/sanic-org/sanic/pull/2782)。 -### Add custom typing to config and ctx objects +### 添加自定义输入到配置和 ctx 对象 -The `sanic.Sanic` and `sanic.Request` object have become generic types that will make it more convenient to have fully typed `config` and `ctx` objects. +`sanic.Sanic`和`sanic.Request`的对象已经成为通用类型，使完全输入`config`和`ctx`对象更方便。 -In the most simple form, the `Sanic` object is typed as: +在最简单的形式中，`Sanic`对象被输入为： ```python from sanic import Sanic @@ -38,17 +38,17 @@ app = Sanic("test") reveal_type(app) # N: Revealed type is "sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace]" ``` -.. tip:: Note +.. 提示：备注 ``` -It should be noted, there is *no* requirement to use the generic types. The default types are `sanic.config.Config` and `types.SimpleNamespace`. This new feature is just an option for those that want to use it and existing types of `app: Sanic` and `request: Request` should work just fine. +应该注意到，有*否*要求使用通用类型。默认类型是 `sanic.config.Config` 和 `types.SimpleNamespace` 。 这个新功能只是那些想要使用它的人的一个选项，并且“应用：Sanic”和“request：Request”应该正常工作。 ``` -Now it is possible to have a fully-type `app.config`, `app.ctx`, and `request.ctx` objects though generics. This allows for better integration with auto completion tools in IDEs improving the developer experience. +现在可以有一个全型的 `app.config`, `app.ctx`, 和 `request.ctx` 对象，尽管它们是普通的。 这样可以更好地结合开发者体验的自动完成工具。 ```python -from sanic import Request, Sanic -from sanic.config import Config +从 Sanic 导入请求， Sanic +来自Sanic。 onfig importing config class CustomConfig(Config): pass @@ -60,125 +60,125 @@ class RequestContext: foo: Foo class CustomRequest(Request[Sanic[CustomConfig, Foo], RequestContext]): - @staticmethod + @static方法 def make_context() -> RequestContext: ctx = RequestContext() - ctx.foo = Foo() + ctx. oo = Foo() return ctx app = Sanic( "test", config=CustomConfig(), ctx=Foo(), request_class=CustomRequest ) -@app.get("/") -async def handler(request: CustomRequest): - ... +@app. et("/") +async def 处理器(请求：自定义请求)： +... ``` -As a side effect, now `request.ctx` is lazy initialized, which should reduce some overhead when the `request.ctx` is unused. +作为一个附带效果，现在`request.ctx`已经启动，这会在未使用 `request.ctx`时减少一些间接费用。 -One further change you may have noticed in the above snippet is the `make_context` method. This new method can be used by custom `Request` types to inject an object different from a `SimpleNamespace` similar to how Sanic has allowed custom application context objects for a while. +您在上述片段中可能注意到的另一个变化是 `make_context` 方法。 这个新方法可以用于自定义 `Request` 类型来注入不同于 `SimpleNamespace` 的对象，类似于Sanic 允许自定义应用程序上下文对象一段时间。 -For a more thorough discussion, see [custom typed application](../basics/app.md#custom-typed-application) and [custom typed request](../basics/app.md#custom-typed-request). +关于更详细的讨论，见[自定义的应用程序](../basics/app.md#custom-typed应用程序)和[自定义的请求](../basics/app.md#custom-typedrequest)。 -See [#2785](https://github.com/sanic-org/sanic/pull/2785). +见[第2785号](https://github.com/sanic-org/sanic/pull/2785)。 -### Universal exception signal +### 通用异常信号 -A new exception signal added for **ALL** exceptions raised while the server is running: `"server.exception.reporting"`. This is a universal signal that will be emitted for any exception raised, and dispatched as its own task. This means that it will _not_ block the request handler, and will _not_ be affected by any middleware. +在服务器运行时为 **ALL** 添加了一个新的异常信号：`server.exception.reporting`。 这是一个普遍的信号，将因提出的任何例外而发出，并作为其自身的任务予以发出。 这意味着它将_不_阻止请求处理器，并且将_不_受到任何中间件的影响。 -This is useful for catching exceptions that may occur outside of the request handler (for example in signals, or in a background task), and it intended for use to create a consistent error handling experience for the user. +这对于捕捉请求处理程序之外可能出现的异常（例如信号中的异常）非常有用， 它旨在为用户创建一个一致的错误处理体验。 ```python -from sanic.signals import Event +从sanic.signatures @app.signal(Event.SERVER_LIFECYCLE_EXCEPTION) -async def catch_any_exception(app: Sanic, exception: Exception): - app.ctx.my_error_reporter_utility.error(exception) +async def catch_any_exception(app: Sanic, exception: + app.ctx.my_error_reporter_utility.error(异常) ``` -This pattern can be simplified with a new decorator `@app.report_exception`: +这种模式可以通过新的装饰符`@app.report_exception`来简化： ```python @app.report_exception -async def catch_any_exception(app: Sanic, exception: Exception): - print("Caught exception:", exception) +async def catch_any_exception(app: Sanic, exception): + print("捕捉异常:", 异常) ``` -It should be pointed out that this happens in a background task and is **NOT** for manipulation of an error response. It is only for reporting, logging, or other purposes that should be triggered when an application error occurs. +应该指出的是，这种情况是在一个后台任务中发生的，并且因为错误响应被操纵而**无**。 仅用于报告、记录或其他应用发生错误时应触发的目的。 -See [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792). +见[第2724](https://github.com/sanic-org/sanic/pull/2724)和[第2792](https://github.com/sanic-org/sanic/pull/2792)。 -### Add name prefixing to BP groups +### 将名称前缀添加到 BP 组 -Sanic had been raising a warning on duplicate route names for a while, and started to enforce route name uniqueness in [v23.3](https://sanic.dev/en/guide/release-notes/v23.3.html#deprecations-and-removals). This created a complication for blueprint composition. +Sanic对重复的路线名称提出警告已有一段时间，并开始在 [v23.3](https://sanic.dev/en/guide/release-notes/v23.3.html#disposations-and-removals)强制执行路线名称唯一性。 这使蓝图组成复杂化。 -New name prefixing parameter for blueprints groups has been added to alleviate this issue. It allows nesting of blueprints and groups to make them composable. +为了缓解这个问题，添加了蓝图组的新名称前缀参数。 它允许嵌套蓝图和组使它们可以合成的。 -The addition is the new `name_prefix` parameter as shown in this snippet. +添加是这个代码段中显示的新的 `name_prefix` 参数。 ```python -bp1 = Blueprint("bp1", url_prefix="/bp1") -bp2 = Blueprint("bp2", url_prefix="/bp2") +bp1 = Bluprint("bp1", url_prefix="/bp1") +bp2 = Bluprint("bp2", url_prefix="/bp2") -bp1.add_route(lambda _: ..., "/", name="route1") -bp2.add_route(lambda _: ..., "/", name="route2") +bp1.add_route(lambda _..., "/"name="route1") +bp2.add_route(Lambda _..., "/", name="route2") -group_a = Blueprint.group( +group_a = 蓝图。 roup( bp1, bp2, url_prefix="/group-a", name_prefix="group-a" ) -group_b = Blueprint.group( +group_b = 蓝图。 roup( bp1, bp2, url_prefix="/group-b", name_prefix="group-b" ) app = Sanic("TestApp") app.blueprint(group_a) -app.blueprint(group_b) +app.bluprint(group_b) ``` -The routes built will be named as follows: +建造的路线将命名如下： - `TestApp.group-a_bp1.route1` - `TestApp.group-a_bp2.route2` - `TestApp.group-b_bp1.route1` - `TestApp.group-b_bp2.route2` -See [#2727](https://github.com/sanic-org/sanic/pull/2727). +见[第2727号](https://github.com/sanic-org/sanic/pull/2727)。 -### Add `request.client_ip` +### 添加 `request.client_ip` -Sanic has introduced `request.client_ip`, a new accessor that provides client's IP address from both local and proxy data. It allows running the application directly on Internet or behind a proxy. This is equivalent to `request.remote_addr or request.ip`, providing the client IP regardless of how the application is deployed. +Sanic 已经引入了 `request.client_ip` ，这是一个新的访问器，从本地和代理数据中提供客户端的 IP 地址。 它允许直接在互联网上或代理后面运行该应用程序。 这相当于`request.remote_addr 或 request.ip`, 提供客户端IP, 无论应用程序是如何部署的。 -See [#2790](https://github.com/sanic-org/sanic/pull/2790). +见[第2790号](https://github.com/sanic-org/sanic/pull/2790)。 -### Increase of `KEEP_ALIVE_TIMEOUT` default to 120 seconds +### 将 `KEEP_ALIVE_TIMEOUT` 默认值增加到120秒 -The default `KEEP_ALIVE_TIMEOUT` value changed from 5 seconds to 120 seconds. It is of course still configurable, but this change should improve performance on long latency connections, where reconnecting is expensive, and better fits typical user flow browsing pages with longer-than-5-second intervals. +默认的`KEEP_ALIVE_TIMEOUT`值从5秒变为120秒。 它当然仍然是可配置的，但这种变化将提高长期延迟连接的性能， 在重新连接费用较高的地方，更适合用户流浏览页面长度超过5秒。 -Sanic has historically used 5 second timeouts to quickly close idle connections. The chosen value of **120 seconds** is indeed larger than Nginx default of 75, and is the same value that Caddy server has by default. +Sanic历来使用5次超时来迅速关闭闲置连接。 选择的 **120 秒** 的值确实大于 Nginx 默认值75，且与 Caddy 服务器默认值相同。 Related to [#2531](https://github.com/sanic-org/sanic/issues/2531) and [#2681](https://github.com/sanic-org/sanic/issues/2681). -See [#2670](https://github.com/sanic-org/sanic/pull/2670). +见[No. 2670](https://github.com/sanic-org/sanic/pull/2670)。 -### Set multiprocessing start method early +### 尽早设置多处理开始方法 -Due to how Python handles `multiprocessing`, it may be confusing to some users how to properly create synchronization primitives. This is due to how Sanic creates the `multiprocessing` context. This change sets the start method early so that any primitives created will properly attach to the correct context. +由于Python如何处理 `multiprocessing` ，它可能会使一些用户混淆如何正确创建同步的初级读物。 这是因为Sanic是如何创建多处理环境的。 此更改及早设置起始方法，以使创建的任何原始都能正确地附加到正确的上下文中。 -For most users, this should not be noticeable or impactful. But, it should make creation of something like this easier and work as expected. +对大多数用户来说，这不应明显或具有影响。 但是，它应该使这种创造变得更加容易，并且能够如预期的那样发挥作用。 ```python -from multiprocessing import Queue +从多处理导入队列 @app.main_process_start async def main_process_start(app): app.shared_ctx.queue = Queue() ``` -See [#2776](https://github.com/sanic-org/sanic/pull/2776). +见[No. 2776](https://github.com/sanic-org/sanic/pull/2776)。 -## Thank you +## 谢谢你 Thank you to everyone that participated in this release: :clap: @@ -196,4 +196,4 @@ Thank you to everyone that participated in this release: :clap: *** -If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 41d77f0d79383fb175f38ccb690b11cf0bbac3af Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:22 +0200 Subject: [PATCH 455/698] New translations v23.9.md (Japanese) --- guide/content/ja/release-notes/2023/v23.9.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/release-notes/2023/v23.9.md b/guide/content/ja/release-notes/2023/v23.9.md index 630da3625b..c4cdc12904 100644 --- a/guide/content/ja/release-notes/2023/v23.9.md +++ b/guide/content/ja/release-notes/2023/v23.9.md @@ -1,7 +1,7 @@ --- -title: Version 23.9 +title: バージョン 23.9 --- -# Version 23.9 +# バージョン 23.9 -_Due to circumstances at the time, v.23.9 was skipped._ +_当時の状況により、v.23.9はスキップされました。 _ From 02a4f526ed76eb599fbe02a1dd3fdc00ddbd126c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:23 +0200 Subject: [PATCH 456/698] New translations v23.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.9.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/zh/release-notes/2023/v23.9.md b/guide/content/zh/release-notes/2023/v23.9.md index 630da3625b..51b8622cd9 100644 --- a/guide/content/zh/release-notes/2023/v23.9.md +++ b/guide/content/zh/release-notes/2023/v23.9.md @@ -1,7 +1,7 @@ --- -title: Version 23.9 +title: 第23.9版 --- -# Version 23.9 +# 第23.9版 -_Due to circumstances at the time, v.23.9 was skipped._ +_由于当时的情况，v.23.9已经跳过。 From 992a6ab27b816f88d306bf148eb3f0ffdd2fcd44 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:29 +0200 Subject: [PATCH 457/698] New translations changelog.md (Japanese) --- guide/content/ja/release-notes/changelog.md | 1863 ++++++++++--------- 1 file changed, 932 insertions(+), 931 deletions(-) diff --git a/guide/content/ja/release-notes/changelog.md b/guide/content/ja/release-notes/changelog.md index b98df20c9e..bde23a6d5a 100644 --- a/guide/content/ja/release-notes/changelog.md +++ b/guide/content/ja/release-notes/changelog.md @@ -1,127 +1,127 @@ --- -content_class: changelog +content_class: 更新履歴 --- -# Changelog +# 更新履歴 -🔶 Current release\ -🔷 In support LTS release +🔶 現在のリリース\ +🔷 LTS リリース -## Version 23.12.0 🔶🔷 +## バージョン23.12.0 🔶🔷 -_Current version_ +_現在のバージョン_ -### Features +### 特徴 -- [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes -- [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown -- [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket -- [#2822](https://github.com/sanic-org/sanic/pull/2822) Listener and signal prioritization -- [#2831](https://github.com/sanic-org/sanic/pull/2831) Reduce memory consumption -- [#2837](https://github.com/sanic-org/sanic/pull/2837) Accept bare cookies -- [#2841](https://github.com/sanic-org/sanic/pull/2841) Add `websocket.handler.` signals -- [#2805](https://github.com/sanic-org/sanic/pull/2805) Add changed files to reload trigger listeners -- [#2813](https://github.com/sanic-org/sanic/pull/2813) Allow for simple signals -- [#2827](https://github.com/sanic-org/sanic/pull/2827) Improve functionality and consistency of `Sanic.event()` -- [#2851](https://github.com/sanic-org/sanic/pull/2851) Allow range requests for a single byte -- [#2854](https://github.com/sanic-org/sanic/pull/2854) Better `Request.scheme` for websocket requests -- [#2858](https://github.com/sanic-org/sanic/pull/2858) Convert Sanic `Request` to a Websockets `Request` for handshake -- [#2859](https://github.com/sanic-org/sanic/pull/2859) Add a REPL to the `sanic` CLI -- [#2870](https://github.com/sanic-org/sanic/pull/2870) Add Python 3.12 support -- [#2875](https://github.com/sanic-org/sanic/pull/2875) Better exception on multiprocessing context conflicts +- [#2775](https://github.com/sanic-org/sanic/pull/2775) 任意のプロセスを開始して再起動する +- [#2811](https://github.com/sanic-org/sanic/pull/2811) シャットダウン時のクリーナープロセス管理 +- [#2812](https://github.com/sanic-org/sanic/pull/2812) オープンなウェブソケットでタスクのトレースバックを抑制する +- [#2822](https://github.com/sanic-org/sanic/pull/2822) リスナーとシグナルの優先順位付け +- [#2831](https://github.com/sanic-org/sanic/pull/2831) メモリ消費量を削減 +- [#2837](https://github.com/sanic-org/sanic/pull/2837) ベアクッキーを受け入れます +- [#2841](https://github.com/sanic-org/sanic/pull/2841) `websocket.handler.` signers を追加する +- [#2805](https://github.com/sanic-org/sanic/pull/2805) 変更されたファイルを追加してトリガーリスナーをリロードする +- [#2813](https://github.com/sanic-org/sanic/pull/2813) シンプルなシグナルを許可する +- [#2827](https://github.com/sanic-org/sanic/pull/2827) `Sanic.event()`の機能性と一貫性を向上させます +- [#2851](https://github.com/sanic-org/sanic/pull/2851) 1 バイトの範囲リクエストを許可する +- [#2854](https://github.com/sanic-org/sanic/pull/2854) ウェブソケットリクエストに適した`Request.scheme` を改善 +- [#2858](https://github.com/sanic-org/sanic/pull/2858) Sanic `Request`をWebsockets `Request`にハンドシェイク変換する +- [#2859](https://github.com/sanic-org/sanic/pull/2859) `sanic` CLI に REPL を追加します +- [#2870](https://github.com/sanic-org/sanic/pull/2870) Python 3.12 サポートを追加 +- [#2875](https://github.com/sanic-org/sanic/pull/2875) マルチプロセッシングコンテキストの競合時の例外の改善 -### Bugfixes +### バグ修正 -- [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data +- [#2803](https://github.com/sanic-org/sanic/pull/2803) MOTD の追加データ表示を修正する -### Deprecations and Removals +### 非推奨と削除 -### Developer infrastructure +### 開発者のインフラストラクチャ -- [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases -- [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU -- [#2807](https://github.com/sanic-org/sanic/pull/2807) Add constraint for autodocsum (lint issue in old package version) -- [#2808](https://github.com/sanic-org/sanic/pull/2808) Refactor GitHub Actions -- [#2814](https://github.com/sanic-org/sanic/pull/2814) Run CI pipeline on git push -- [#2846](https://github.com/sanic-org/sanic/pull/2846) Drop old performance tests/benchmarks +- [#2796](https://github.com/sanic-org/sanic/pull/2796) ユニットテストケースをリファクタリングする +- [#2801](https://github.com/sanic-org/sanic/pull/2801) CPUが1つだけの場合、`test_fast`を修正する +- [#2807](https://github.com/sanic-org/sanic/pull/2807) autocsum の制約を追加する (lint issum in old package version) +- [#2808](https://github.com/sanic-org/sanic/pull/2808) GitHubアクションをリファクタリングする +- [#2814](https://github.com/sanic-org/sanic/pull/2814) git push で CI パイプラインを実行 +- [#2846](https://github.com/sanic-org/sanic/pull/2846) 古いパフォーマンステスト/ベンチマーク - [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile cleanup - [#2865](https://github.com/sanic-org/sanic/pull/2865) [#2869](https://github.com/sanic-org/sanic/pull/2869) [#2872](https://github.com/sanic-org/sanic/pull/2872) [#2879](https://github.com/sanic-org/sanic/pull/2879) - Add ruff to toolchain -- [#2866](https://github.com/sanic-org/sanic/pull/2866) Fix the alt svc test to run locally with explicit buffer nbytes -- [#2877](https://github.com/sanic-org/sanic/pull/2877) Use Python's trusted publisher in deployments -- [#2882](https://github.com/sanic-org/sanic/pull/2882) Introduce dynamic port fixture in targeted locations in the test suite + ツールチェーンにラフを追加 +- [#2866](https://github.com/sanic-org/sanic/pull/2866) alt svc テストが明示的なバッファnbytes でローカルで実行されるように修正する +- [#2877](https://github.com/sanic-org/sanic/pull/2877) Pythonの信頼できるパブリッシャーをデプロイに使用する +- [#2882](https://github.com/sanic-org/sanic/pull/2882) テストスイート内の対象となる場所に動的ポートフィクスチャーを導入する -### Improved Documentation +### ドキュメントの改善 - [#2781](https://github.com/sanic-org/sanic/pull/2781) [#2821](https://github.com/sanic-org/sanic/pull/2821) - [#2861](https://github.com/sanic-org/sanic/pull/2861) - [#2863](https://github.com/sanic-org/sanic/pull/2863) - Conversion of User Guide to the SHH (Sanic, html5tagger, HTMX) stack -- [#2810](https://github.com/sanic-org/sanic/pull/2810) Update README -- [#2855](https://github.com/sanic-org/sanic/pull/2855) Edit Discord badge -- [#2864](https://github.com/sanic-org/sanic/pull/2864) Adjust documentation for using state properties within http/https redirection document + [#2861](https://github.com/sanic-org/sanic/pull/2863) + [#2863](https://github.com/sanic-org/sanic-pull/pull/2781) + User Guide to SHH (Sanic, html5tagger, HTMX) stack +- [#2810](https://github.com/sanic-org/sanic/pull/2810) README を更新 +- [#2855](https://github.com/sanic-org/sanic/pull/2855) Discordバッジを編集する +- [#2864](https://github.com/sanic-org/sanic/pull/2864) http/https リダイレクションドキュメント内で state プロパティを使用するためのドキュメントを調整する -## Version 23.9.0 +## バージョン 23.9.0 -_Due to circumstances at the time, v.23.9 was skipped._ +_当時の状況により、v.23.9はスキップされました。 _ -## Version 23.6.0 +## バージョン 23.6.0 -### Features +### 特徴 -- [#2670](https://github.com/sanic-org/sanic/pull/2670) Increase `KEEP_ALIVE_TIMEOUT` default to 120 seconds -- [#2716](https://github.com/sanic-org/sanic/pull/2716) Adding allow route overwrite option in blueprint -- [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792) Add a new exception signal for ALL exceptions raised anywhere in application -- [#2727](https://github.com/sanic-org/sanic/pull/2727) Add name prefixing to BP groups -- [#2754](https://github.com/sanic-org/sanic/pull/2754) Update request type on middleware types -- [#2770](https://github.com/sanic-org/sanic/pull/2770) Better exception message on startup time application induced import error -- [#2776](https://github.com/sanic-org/sanic/pull/2776) Set multiprocessing start method early -- [#2785](https://github.com/sanic-org/sanic/pull/2785) Add custom typing to config and ctx objects -- [#2790](https://github.com/sanic-org/sanic/pull/2790) Add `request.client_ip` +- [#2670](https://github.com/sanic-org/sanic/pull/2670) `KEEP_ALIVE_TIMEOUT`のデフォルトを120秒に増やします +- [#2716](https://github.com/sanic-org/sanic/pull/2716) ブループリントにルート上書きオプションを追加する +- [#2724](https://github.com/sanic-org/sanic/pull/2724) および [#2792](https://github.com/sanic-org/sanic/pull/2792) アプリケーションのどこでも発生するすべての例外に新しい例外信号を追加します。 +- [#2727](https://github.com/sanic-org/sanic/pull/2727) BPグループの前に名前を追加 +- [#2754](https://github.com/sanic-org/sanic/pull/2754) ミドルウェアタイプのリクエストタイプを更新 +- [#2770](https://github.com/sanic-org/sanic/pull/2770) 起動時にエラーが発生した場合の例外メッセージの改善 +- [#2776](https://github.com/sanic-org/sanic/pull/2776) マルチプロセッシングスタートメソッドを早期に設定する +- [#2785](https://github.com/sanic-org/sanic/pull/2785) 設定とctxオブジェクトにカスタム入力を追加 +- [#2790](https://github.com/sanic-org/sanic/pull/2790) `request.client_ip` を追加する -### Bugfixes +### バグ修正 -- [#2728](https://github.com/sanic-org/sanic/pull/2728) Fix traversals for intended results -- [#2729](https://github.com/sanic-org/sanic/pull/2729) Handle case when headers argument of ResponseStream constructor is None -- [#2737](https://github.com/sanic-org/sanic/pull/2737) Fix type annotation for `JSONREsponse` default content type -- [#2740](https://github.com/sanic-org/sanic/pull/2740) Use Sanic's serializer for JSON responses in the Inspector -- [#2760](https://github.com/sanic-org/sanic/pull/2760) Support for `Request.get_current` in ASGI mode -- [#2773](https://github.com/sanic-org/sanic/pull/2773) Alow Blueprint routes to explicitly define error_format -- [#2774](https://github.com/sanic-org/sanic/pull/2774) Resolve headers on different renderers -- [#2782](https://github.com/sanic-org/sanic/pull/2782) Resolve pypy compatibility issues +- [#2728](https://github.com/sanic-org/sanic/pull/2728) 意図した結果のトラバーサルを修正 +- [#2729](https://github.com/sanic-org/sanic/pull/2729) ResponseStream コンストラクターの引数が None の場合に処理する +- [#2737](https://github.com/sanic-org/sanic/pull/2737) デフォルトのコンテンツ型の型アノテーションを修正 +- [#2740](https://github.com/sanic-org/sanic/pull/2740) SanicのシリアライザをインスペクターでJSONレスポンスに使用する +- [#2760](https://github.com/sanic-org/sanic/pull/2760) ASGI モードでの `Request.get_current` のサポート +- [#2773](https://github.com/sanic-org/sanic/pull/2773) 明示的にerror_format を定義するためのブループリントルートを無視する +- [#2774](https://github.com/sanic-org/sanic/pull/2774) さまざまなレンダラーでヘッダーを解決する +- [#2782](https://github.com/sanic-org/sanic/pull/2782) pypy の互換性の問題を解決する -### Deprecations and Removals +### 非推奨と削除 -- [#2777](https://github.com/sanic-org/sanic/pull/2777) Remove Python 3.7 support +- [#2777](https://github.com/sanic-org/sanic/pull/2777) Python 3.7 サポートを削除 -### Developer infrastructure +### 開発者のインフラストラクチャ - [#2766](https://github.com/sanic-org/sanic/pull/2766) Unpin setuptools version -- [#2779](https://github.com/sanic-org/sanic/pull/2779) Run keep alive tests in loop to get available port +- [#2779](https://github.com/sanic-org/sanic/pull/2779) 有効なポートを取得するために、ループ内のテストを実行してください -### Improved Documentation +### ドキュメントの改善 - [#2741](https://github.com/sanic-org/sanic/pull/2741) Better documentation examples about running Sanic From that list, the items to highlight in the release notes: -## Version 23.3.0 +## バージョン 23.3.0 -### Features +### 特徴 -- [#2545](https://github.com/sanic-org/sanic/pull/2545) Standardize init of exceptions for more consistent control of HTTP responses using exceptions -- [#2606](https://github.com/sanic-org/sanic/pull/2606) Decode headers as UTF-8 also in ASGI -- [#2646](https://github.com/sanic-org/sanic/pull/2646) Separate ASGI request and lifespan callables -- [#2659](https://github.com/sanic-org/sanic/pull/2659) Use `FALLBACK_ERROR_FORMAT` for handlers that return `empty()` -- [#2662](https://github.com/sanic-org/sanic/pull/2662) Add basic file browser (HTML page) and auto-index serving -- [#2667](https://github.com/sanic-org/sanic/pull/2667) Nicer traceback formatting (HTML page) -- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter error page rendering format selection; more reliant upon header and "common sense" defaults -- [#2680](https://github.com/sanic-org/sanic/pull/2680) Check the status of socket before shutting down with `SHUT_RDWR` -- [#2687](https://github.com/sanic-org/sanic/pull/2687) Refresh `Request.accept` functionality to be more performant and spec-compliant -- [#2696](https://github.com/sanic-org/sanic/pull/2696) Add header accessors as properties +- [#2545](https://github.com/sanic-org/sanic/pull/2545) 例外の init を標準化して、例外を使用してHTTPレスポンスの一貫性を高めます。 +- [#2606](https://github.com/sanic-org/sanic/pull/2606) ASGIでもUTF-8としてデコードヘッダーを解読する +- [#2646](https://github.com/sanic-org/sanic/pull/2646) ASGIリクエストと寿命の呼び出しを分離する +- [#2659](https://github.com/sanic-org/sanic/pull/2659) `empty()` を返すハンドラには `FALLBACK_ERROR_FORMAT` を使用してください。 +- [#2662](https://github.com/sanic-org/sanic/pull/2662) 基本的なファイルブラウザー (HTMLページ) と自動インデックスサービス +- [#2667](https://github.com/sanic-org/sanic/pull/2667) Nice traceback formatting (HTML page) +- [#2668](https://github.com/sanic-org/sanic/pull/2668) よりスマートなエラーページレンダリングフォーマットの選択。ヘッダーと「常識」のデフォルトに依存する +- [#2680](https://github.com/sanic-org/sanic/pull/2680) `SHUT_RDWR` でシャットダウンする前にソケットの状態を確認してください。 +- [#2687](https://github.com/sanic-org/sanic/pull/2687) `Request.accept` 機能をよりパフォーマンスと仕様に準拠するように更新します。 +- [#2696](https://github.com/sanic-org/sanic/pull/2696) ヘッダーアクセサをプロパティとして追加 ``` Example-Field: Foo, Bar Example-Field: Baz @@ -129,459 +129,459 @@ _Due to circumstances at the time, v.23.9 was skipped._ ```python request.headers.example_field == "Foo, Bar,Baz" ``` -- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simpler CLI targets +- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simpler CLI target ```sh - $ sanic path.to.module:app # global app instance - $ sanic path.to.module:create_app # factory pattern - $ sanic ./path/to/directory/ # simple serve + $ sanic path.to.module:app # global app instance + $ sanic path.to.module:create_app # factory pattern + $ sanic ./path/to/directory/ # simple serve ``` -- [#2701](https://github.com/sanic-org/sanic/pull/2701) API to define a number of workers in managed processes -- [#2704](https://github.com/sanic-org/sanic/pull/2704) Add convenience for dynamic changes to routing -- [#2706](https://github.com/sanic-org/sanic/pull/2706) Add convenience methods for cookie creation and deletion +- [#2701](https://github.com/sanic-org/sanic/pull/2701) 管理されたプロセスの多くのワーカーを定義する API +- [#2704](https://github.com/sanic-org/sanic/pull/2704) ルーティングの動的変更に便利な機能を追加 +- [#2706](https://github.com/sanic-org/sanic/pull/2706) クッキーの作成と削除に便利なメソッドを追加する ```python response = text("...") response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com") ``` -- [#2707](https://github.com/sanic-org/sanic/pull/2707) Simplified `parse_content_header` escaping to be RFC-compliant and remove outdated FF hack -- [#2710](https://github.com/sanic-org/sanic/pull/2710) Stricter charset handling and escaping of request URLs -- [#2711](https://github.com/sanic-org/sanic/pull/2711) Consume body on `DELETE` by default -- [#2719](https://github.com/sanic-org/sanic/pull/2719) Allow `password` to be passed to TLS context -- [#2720](https://github.com/sanic-org/sanic/pull/2720) Skip middleware on `RequestCancelled` -- [#2721](https://github.com/sanic-org/sanic/pull/2721) Change access logging format to `%s` -- [#2722](https://github.com/sanic-org/sanic/pull/2722) Add `CertLoader` as application option for directly controlling `SSLContext` objects -- [#2725](https://github.com/sanic-org/sanic/pull/2725) Worker sync state tolerance on race condition +- [#2707](https://github.com/sanic-org/sanic/pull/2707) `parse_content_header` エスケープを簡素化し、RFCに準拠し、古いFFハックを削除する +- [#2710](https://github.com/sanic-org/sanic/pull/2710) リクエストURLの厳密な文字セットの扱いとescaping +- [#2711](https://github.com/sanic-org/sanic/pull/2711) デフォルトでは `DELETE` の本文を消費します +- [#2719](https://github.com/sanic-org/sanic/pull/2719) `password` を TLS コンテキストに渡すことを許可する +- [#2720](https://github.com/sanic-org/sanic/pull/2720) `RequestCancelled` でミドルウェアをスキップする +- [#2721](https://github.com/sanic-org/sanic/pull/2721) アクセスログのフォーマットを \`%s\`\` に変更する +- [#2722](https://github.com/sanic-org/sanic/pull/2722) `SSLContext` オブジェクトを直接制御するためのアプリケーションオプションとして `CertLoader` を追加します +- [#2725](https://github.com/sanic-org/sanic/pull/2725) レース状態におけるワーカー同期状態 -### Bugfixes +### バグ修正 -- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket to pass thru bytes as is -- [#2697](https://github.com/sanic-org/sanic/pull/2697) Fix comparison between datetime aware and naive in `file` when using `If-Modified-Since` +- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI のウェブソケットをそのままバイトを渡します +- [#2697](https://github.com/sanic-org/sanic/pull/2697) `If-Modified-Since` を使用した場合、datetime aware と naive の比較を`file` で修正しました -### Deprecations and Removals +### 非推奨と削除 -- [#2666](https://github.com/sanic-org/sanic/pull/2666) Remove deprecated `__blueprintname__` property +- [#2666](https://github.com/sanic-org/sanic/pull/2666) 非推奨の「**blueprintname**」プロパティを削除します -### Improved Documentation +### ドキュメントの改善 -- [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect +- [#2712](https://github.com/sanic-org/sanic/pull/2712) リダイレクトを作成するために `'https'` を使用した例を改善しました -## Version 22.12.0 🔷 +## バージョン22.12.0 🔷 -_Current LTS version_ +現在のLTSバージョン_ -### Features +### 特徴 -- [#2569](https://github.com/sanic-org/sanic/pull/2569) Add `JSONResponse` class with some convenient methods when updating a response object -- [#2598](https://github.com/sanic-org/sanic/pull/2598) Change `uvloop` requirement to `>=0.15.0` -- [#2609](https://github.com/sanic-org/sanic/pull/2609) Add compatibility with `websockets` v11.0 -- [#2610](https://github.com/sanic-org/sanic/pull/2610) Kill server early on worker error - - Raise deadlock timeout to 30s -- [#2617](https://github.com/sanic-org/sanic/pull/2617) Scale number of running server workers -- [#2621](https://github.com/sanic-org/sanic/pull/2621) [#2634](https://github.com/sanic-org/sanic/pull/2634) Send `SIGKILL` on subsequent `ctrl+c` to force worker exit -- [#2622](https://github.com/sanic-org/sanic/pull/2622) Add API to restart all workers from the multiplexer -- [#2624](https://github.com/sanic-org/sanic/pull/2624) Default to `spawn` for all subprocesses unless specifically set: +- [#2569](https://github.com/sanic-org/sanic/pull/2569) レスポンスオブジェクトを更新する際に便利なメソッドで `JSONResponse` クラスを追加する +- [#2598](https://github.com/sanic-org/sanic/pull/2598) `uvloop`の要件を`>=0.15.0`に変更します +- [#2609](https://github.com/sanic-org/sanic/pull/2609) `websockets` v11.0 との互換性を追加 +- [#2610](https://github.com/sanic-org/sanic/pull/2610) ワーカーエラー時にサーバーを早期にキルする + - デッドロックのタイムアウトを30秒に上げる +- [#2617](https://github.com/sanic-org/sanic/pull/2617) 実行中のサーバーワーカーの数 +- [#2621](https://github.com/sanic-org/sanic/pull/2621) [#2634](https://github.com/sanic-org/sanic/pull/2634) 次の`ctrl+c`に`SIGKILL`を送信してワーカーの出口を強制する +- [#2622](https://github.com/sanic-org/sanic/pull/2622) APIを追加してマルチプレクサからすべてのワーカーを再起動する +- [#2624](https://github.com/sanic-org/sanic/pull/2624) 特別に設定しない限り、全てのサブプロセスの `spawn` をデフォルトに設定します。 ```python from sanic import Sanic Sanic.start_method = "fork" ``` -- [#2625](https://github.com/sanic-org/sanic/pull/2625) Filename normalisation of form-data/multipart file uploads -- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector: - - Remote access to inspect running Sanic instances - - TLS support for encrypted calls to Inspector - - Authentication to Inspector with API key - - Ability to extend Inspector with custom commands -- [#2632](https://github.com/sanic-org/sanic/pull/2632) Control order of restart operations -- [#2633](https://github.com/sanic-org/sanic/pull/2633) Move reload interval to class variable -- [#2636](https://github.com/sanic-org/sanic/pull/2636) Add `priority` to `register_middleware` method -- [#2639](https://github.com/sanic-org/sanic/pull/2639) Add `unquote` to `add_route` method +- [#2625](https://github.com/sanic-org/sanic/pull/2625) フォームデータ/マルチパートファイルアップロードの正規化 +- [#2626](https://github.com/sanic-org/sanic/pull/2626) HTTP インスペクタに移動: + - 実行中の Sanic インスタンスを検査するリモートアクセス + - TLSはインスペクターへの暗号化コールに対応しています + - API キーを使用したインスペクタの認証 + - カスタムコマンドでインスペクターを拡張できる機能 +- [#2632](https://github.com/sanic-org/sanic/pull/2632) 再起動操作の順序を制御する +- [#2633](https://github.com/sanic-org/sanic/pull/2633) リロード間隔をクラス変数に移動する +- [#2636](https://github.com/sanic-org/sanic/pull/2636) `register_middleware`メソッドに`priority`を追加します +- [#2639](https://github.com/sanic-org/sanic/pull/2639) `add_route`メソッドに`unquote`を追加します - [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets to receive `text` or `bytes` -### Bugfixes +### バグ修正 -- [#2607](https://github.com/sanic-org/sanic/pull/2607) Force socket shutdown before close to allow rebinding -- [#2590](https://github.com/sanic-org/sanic/pull/2590) Use actual `StrEnum` in Python 3.11+ -- [#2615](https://github.com/sanic-org/sanic/pull/2615) Ensure middleware executes only once per request timeout -- [#2627](https://github.com/sanic-org/sanic/pull/2627) Crash ASGI application on lifespan failure -- [#2635](https://github.com/sanic-org/sanic/pull/2635) Resolve error with low-level server creation on Windows +- [#2607](https://github.com/sanic-org/sanic/pull/2607) ソケットの再結合を許可する前に強制的にシャットダウンする +- [#2590](https://github.com/sanic-org/sanic/pull/2590) Python 3.11以降では実際の`StrEnum`を使用してください +- [#2615](https://github.com/sanic-org/sanic/pull/2615) ミドルウェアがリクエストタイムアウトごとに1回だけ実行されることを確認する +- [#2627](https://github.com/sanic-org/sanic/pull/2627) 寿命エラーに関するクラッシュASGIアプリケーション +- [#2635](https://github.com/sanic-org/sanic/pull/2635) Windowsで低レベルのサーバー作成でエラーを解決する -### Deprecations and Removals +### 非推奨と削除 -- [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) Signal conditions and triggers saved on `signal.extra` -- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector - - 🚨 _BREAKING CHANGE_: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol - - _DEPRECATE_: The `--inspect*` commands have been deprecated in favor of `inspect ...` commands -- [#2628](https://github.com/sanic-org/sanic/pull/2628) Replace deprecated `distutils.strtobool` +- [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) シグナル条件とトリガーは `signal.extra` に保存されます。 +- [#2626](https://github.com/sanic-org/sanic/pull/2626) HTTPインスペクタに移動 + - 🚨 _BREAKING CHANGE_: インスペクターをカスタムプロトコルを持つシンプルなTCPソケットからSanicアプリに移動します。 + - _DEPRECATE_: `--inspect*` コマンドは非推奨になりました。 +- [#2628](https://github.com/sanic-org/sanic/pull/2628) 非推奨の `distutils.strtobool` を置き換え -### Developer infrastructure +### 開発者のインフラストラクチャ -- [#2612](https://github.com/sanic-org/sanic/pull/2612) Add CI testing for Python 3.11 +- [#2612](https://github.com/sanic-org/sanic/pull/2612) CI testing for Python 3.11 -## Version 22.9.1 +## バージョン 22.9.1 -### Features +### 特徴 -- [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered +- [#2585](https://github.com/sanic-org/sanic/pull/2585) アプリケーションが登録されていない場合のエラーメッセージを改善しました -### Bugfixes +### バグ修正 -- [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation -- [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility -- [#2592](https://github.com/sanic-org/sanic/pull/2592) Fix properties in nested blueprint groups -- [#2595](https://github.com/sanic-org/sanic/pull/2595) Introduce sleep interval on new worker reloader +- [#2578](https://github.com/sanic-org/sanic/pull/2578) プロセス証明書作成に証明書ローダーを追加する +- [#2591](https://github.com/sanic-org/sanic/pull/2591) `spawn`互換性のためにsentinel identityを使用しないでください +- [#2592](https://github.com/sanic-org/sanic/pull/2592) 入れ子になったブループリントグループのプロパティを修正 +- [#2595](https://github.com/sanic-org/sanic/pull/2595) 新しいワーカーの再ローダーで睡眠間隔を導入する -### Deprecations and Removals +### 非推奨と削除 -### Developer infrastructure +### 開発者のインフラストラクチャ -- [#2588](https://github.com/sanic-org/sanic/pull/2588) Markdown templates on issue forms +- [#2588](https://github.com/sanic-org/sanic/pull/2588) Issue フォームの Markdown テンプレート -### Improved Documentation +### ドキュメントの改善 - [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 documentation -- [#2582](https://github.com/sanic-org/sanic/pull/2582) Cleanup documentation on Windows support +- [#2582](https://github.com/sanic-org/sanic/pull/2582) Windows 対応のドキュメントをクリーンアップする -## Version 22.9.0 +## バージョン 22.9.0 -### Features +### 特徴 -- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom loads function -- [#2490](https://github.com/sanic-org/sanic/pull/2490) Make `WebsocketImplProtocol` async iterable -- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refactor -- [#2506](https://github.com/sanic-org/sanic/pull/2506) Use `pathlib` for path resolution (for static file serving) -- [#2508](https://github.com/sanic-org/sanic/pull/2508) Use `path.parts` instead of `match` (for static file serving) -- [#2513](https://github.com/sanic-org/sanic/pull/2513) Better request cancel handling -- [#2516](https://github.com/sanic-org/sanic/pull/2516) Add request properties for HTTP method info: +- [#2445](https://github.com/sanic-org/sanic/pull/2445) カスタムロード関数を追加 +- [#2490](https://github.com/sanic-org/sanic/pull/2490) `WebsocketImpletocol` async iterable +- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager のリファクタリング機能 +- [#2506](https://github.com/sanic-org/sanic/pull/2506) パス解像度には`pathlib`を使用してください (静的なファイルを提供する場合) +- [#2508](https://github.com/sanic-org/sanic/pull/2508) `match` の代わりに `path.parts` を使ってください (静的なファイルを提供する場合) +- [#2513](https://github.com/sanic-org/sanic/pull/2513) リクエスト処理をキャンセルする +- [#2516](https://github.com/sanic-org/sanic/pull/2516) HTTP メソッドのリクエストプロパティを追加: - `request.is_safe` - `request.is_idempotent` - `request.is_cacheable` - - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _for more information about when these apply_ -- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI -- [#2526](https://github.com/sanic-org/sanic/pull/2526) Cache control support for static files for returning 304 when appropriate -- [#2533](https://github.com/sanic-org/sanic/pull/2533) Refactor `_static_request_handler` -- [#2540](https://github.com/sanic-org/sanic/pull/2540) Add signals before and after handler execution + - _参照_ format@@0(https\://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _これらが適用される時の詳細_ +- [#2522](https://github.com/sanic-org/sanic/pull/2522) ASGIに常にサーバーの場所を表示する +- [#2526](https://github.com/sanic-org/sanic/pull/2526) 適切な場合に304を返すための静的ファイルのキャッシュ管理のサポート +- [#2533](https://github.com/sanic-org/sanic/pull/2533) リファクタリング`_static_request_handler` +- [#2540](https://github.com/sanic-org/sanic/pull/2540) ハンドラ実行の前後に信号を追加する - `http.handler.before` - `http.handler.after` -- [#2542](https://github.com/sanic-org/sanic/pull/2542) Add _[redacted]_ to CLI :) -- [#2546](https://github.com/sanic-org/sanic/pull/2546) Add deprecation warning filter -- [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware priority and performance enhancements +- [#2542](https://github.com/sanic-org/sanic/pull/2542) _[redacted]_ to CLI :) +- [#2546](https://github.com/sanic-org/sanic/pull/2546) 非推奨警告フィルタを追加する +- [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware の優先度とパフォーマンスの強化 -### Bugfixes +### バグ修正 -- [#2495](https://github.com/sanic-org/sanic/pull/2495) Prevent directory traversion with static files -- [#2515](https://github.com/sanic-org/sanic/pull/2515) Do not apply double slash to paths in certain static dirs in Blueprints +- [#2495](https://github.com/sanic-org/sanic/pull/2495) 静的なファイルでディレクトリのtraversionを防止する +- [#2515](https://github.com/sanic-org/sanic/pull/2515) ブループリントの特定の静的dirsに二重スラッシュを適用しないでください -### Deprecations and Removals +### 非推奨と削除 -- [#2525](https://github.com/sanic-org/sanic/pull/2525) Warn on duplicate route names, will be prevented outright in v23.3 -- [#2537](https://github.com/sanic-org/sanic/pull/2537) Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3 +- [#2525](https://github.com/sanic-org/sanic/pull/2525) 重複したルート名の警告はv23.3で完全に防止されます +- [#2537](https://github.com/sanic-org/sanic/pull/2537) 重複した例外に対する警告と非推奨通知はv23.3で完全に防止されます。 -### Developer infrastructure +### 開発者のインフラストラクチャ - [#2504](https://github.com/sanic-org/sanic/pull/2504) Cleanup test suite -- [#2505](https://github.com/sanic-org/sanic/pull/2505) Replace Unsupported Python Version Number from the Contributing Doc -- [#2530](https://github.com/sanic-org/sanic/pull/2530) Do not include tests folder in installed package resolver +- [#2505](https://github.com/sanic-org/sanic/pull/2505) コントリビューションドキュメントからサポートされていないPythonバージョン番号を置き換え +- [#2530](https://github.com/sanic-org/sanic/pull/2530) インストールされたパッケージリゾルバーにtestsフォルダを含めないでください -### Improved Documentation +### ドキュメントの改善 -- [#2502](https://github.com/sanic-org/sanic/pull/2502) Fix a few typos -- [#2517](https://github.com/sanic-org/sanic/pull/2517) [#2536](https://github.com/sanic-org/sanic/pull/2536) Add some type hints +- [#2502](https://github.com/sanic-org/sanic/pull/2502) いくつかのタイプミスを修正 +- [#2517](https://github.com/sanic-org/sanic/pull/2517) [#2536](https://github.com/sanic-org/sanic/pull/2536) いくつかのタイプヒントを追加する -## Version 22.6.2 +## バージョン 22.6.2 -### Bugfixes +### バグ修正 -- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI +- [#2522](https://github.com/sanic-org/sanic/pull/2522) ASGIに常にサーバーの場所を表示する -## Version 22.6.1 +## バージョン 22.6.1 -### Bugfixes +### バグ修正 -- [#2477](https://github.com/sanic-org/sanic/pull/2477) Sanic static directory fails when folder name ends with ".." +- [#2477](https://github.com/sanic-org/sanic/pull/2477) フォルダ名が ".." で終わると、Sanic static ディレクトリに失敗します。 -## Version 22.6.0 +## バージョン 22.6.0 -### Features +### 特徴 -- [#2378](https://github.com/sanic-org/sanic/pull/2378) Introduce HTTP/3 and autogeneration of TLS certificates in `DEBUG` mode - - 👶 _EARLY RELEASE FEATURE_: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented. - - 📦 _EXTRA REQUIREMENT_: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a [HTTP/3 capable client](https://curl.se/docs/http3.html). - - 📦 _EXTRA REQUIREMENT_: In order to use TLS autogeneration, you must install either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). -- [#2416](https://github.com/sanic-org/sanic/pull/2416) Add message to `task.cancel` -- [#2420](https://github.com/sanic-org/sanic/pull/2420) Add exception aliases for more consistent naming with standard HTTP response types (`BadRequest`, `MethodNotAllowed`, `RangeNotSatisfiable`) -- [#2432](https://github.com/sanic-org/sanic/pull/2432) Expose ASGI `scope` as a property on the `Request` object -- [#2438](https://github.com/sanic-org/sanic/pull/2438) Easier access to websocket class for annotation: `from sanic import Websocket` -- [#2439](https://github.com/sanic-org/sanic/pull/2439) New API for reading form values with options: `Request.get_form` -- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom `loads` function -- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) Improved API to support setting cache control headers -- [#2453](https://github.com/sanic-org/sanic/pull/2453) Move verbosity filtering to logger -- [#2475](https://github.com/sanic-org/sanic/pull/2475) Expose getter for current request using `Request.get_current()` +- [#2378](https://github.com/sanic-org/sanic/pull/2378) `DEBUG`モードでHTTP/3とTLS証明書の自動生成を導入する + - 👶 _早期にリリースされる機能_: HTTP/3 を超えてサニックにサービスを提供することは早期リリース機能です。 まだHTTP/3 の仕様を完全にカバーしているわけではありませんが、代わりに、Sanic の既存の HTTP/1.1 サーバーとの機能準拠を目指しています。 Websocket、WebTransport、プッシュ応答は、まだ実装されていないいくつかの機能の例です。 + - 📦 _EXTRA要求_: すべてのHTTPクライアントがHTTP/3サーバーとインターフェースできるわけではありません。 [HTTP/3 対応クライアント](https://curl.se/docs/http3.html) をインストールする必要があります。 + - 📦 _EXTRA REQUIREMENT_: TLS の自己生成を使用するには、 [mkcert](https://github.com/FiloSottile/mkcert) または [trustme](https://github.com/python-trio/trustme)のいずれかをインストールする必要があります。 +- [#2416](https://github.com/sanic-org/sanic/pull/2416) `task.cancel`にメッセージを追加する +- [#2420](https://github.com/sanic-org/sanic/pull/2420) 標準のHTTPレスポンスタイプ(`BadRequest`, `MethodNotAllowed`, `RangeNotSatisfiable`)でより一貫した命名をするための例外エイリアスを追加します。 +- [#2432](https://github.com/sanic-org/sanic/pull/2432) `Request`オブジェクトのプロパティとしてASGI `scope`を公開します +- [#2438](https://github.com/sanic-org/sanic/pull/2438) 注釈のWebSocketクラスへの簡単なアクセス: `from sanic import Websocket` +- [#2439](https://github.com/sanic-org/sanic/pull/2439) フォームの値を読み取るための新しいAPI: `Request.get_form` +- [#2445](https://github.com/sanic-org/sanic/pull/2445) カスタムの `loads` 関数を追加する +- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) キャッシュコントロールヘッダーの設定をサポートする API を改善しました。 +- [#2453](https://github.com/sanic-org/sanic/pull/2453) 詳細フィルタリングをロガーに移動する +- [#2475](https://github.com/sanic-org/sanic/pull/2475) `Request.get_current()` を使って現在のリクエストの取得を行います。 -### Bugfixes +### バグ修正 -- [#2448](https://github.com/sanic-org/sanic/pull/2448) Fix to allow running with `pythonw.exe` or places where there is no `sys.stdout` -- [#2451](https://github.com/sanic-org/sanic/pull/2451) Trigger `http.lifecycle.request` signal in ASGI mode -- [#2455](https://github.com/sanic-org/sanic/pull/2455) Resolve typing of stacked route definitions -- [#2463](https://github.com/sanic-org/sanic/pull/2463) Properly catch websocket CancelledError in websocket handler in Python 3.7 +- [#2448](https://github.com/sanic-org/sanic/pull/2448) `pythonw.exe`または`sys.stdout`がない場所で実行できるように修正しました +- [#2451](https://github.com/sanic-org/sanic/pull/2451) ASGI モードで `http.lifycle.request` シグナルをトリガーします +- [#2455](https://github.com/sanic-org/sanic/pull/2455) 積み上げられたルート定義のタイピングを解決する +- [#2463](https://github.com/sanic-org/sanic/pull/2463) Python 3.7 の websocket ハンドラーの CancelledError を適切にキャッチします。 -### Deprecations and Removals +### 非推奨と削除 -- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 deprecations and changes - 1. Optional application registry - 2. Execution of custom handlers after some part of response was sent - 3. Configuring fallback handlers on the `ErrorHandler` - 4. Custom `LOGO` setting +- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6の非推奨と変更 + 1. オプションのアプリケーションレジストリ + 2. 応答の一部が送信された後のカスタムハンドラの実行 + 3. `ErrorHandler`でフォールバックハンドラを設定する + 4. カスタム `LOGO` 設定 5. `sanic.response.stream` 6. `AsyncioServer.init` -### Developer infrastructure +### 開発者のインフラストラクチャ -- [#2449](https://github.com/sanic-org/sanic/pull/2449) Clean up `black` and `isort` config -- [#2479](https://github.com/sanic-org/sanic/pull/2479) Fix some flappy tests +- [#2449](https://github.com/sanic-org/sanic/pull/2449) `black`と`isort`の設定をクリーンアップする +- [#2479](https://github.com/sanic-org/sanic/pull/2479) フラッピーテストを修正する -### Improved Documentation +### ドキュメントの改善 -- [#2461](https://github.com/sanic-org/sanic/pull/2461) Update example to match current application naming standards -- [#2466](https://github.com/sanic-org/sanic/pull/2466) Better type annotation for `Extend` -- [#2485](https://github.com/sanic-org/sanic/pull/2485) Improved help messages in CLI +- [#2461](https://github.com/sanic-org/sanic/pull/2461) アプリケーションの命名規格に合わせてサンプルを更新する +- [#2466](https://github.com/sanic-org/sanic/pull/2466) `Extend` の型注釈を改善しました +- [#2485](https://github.com/sanic-org/sanic/pull/2485) CLI のヘルプメッセージを改善 -## Version 22.3.0 +## バージョン 22.3.0 -### Features +### 特徴 -- [#2347](https://github.com/sanic-org/sanic/pull/2347) API for multi-application server - - 🚨 _BREAKING CHANGE_: The old `sanic.worker.GunicornWorker` has been **removed**. To run Sanic with `gunicorn`, you should use it thru `uvicorn` [as described in their docs](https://www.uvicorn.org/#running-with-gunicorn). - - 🧁 _SIDE EFFECT_: Named background tasks are now supported, even in Python 3.7 -- [#2357](https://github.com/sanic-org/sanic/pull/2357) Parse `Authorization` header as `Request.credentials` -- [#2361](https://github.com/sanic-org/sanic/pull/2361) Add config option to skip `Touchup` step in application startup -- [#2372](https://github.com/sanic-org/sanic/pull/2372) Updates to CLI help messaging -- [#2382](https://github.com/sanic-org/sanic/pull/2382) Downgrade warnings to backwater debug messages -- [#2396](https://github.com/sanic-org/sanic/pull/2396) Allow for `multidict` v0.6 -- [#2401](https://github.com/sanic-org/sanic/pull/2401) Upgrade CLI catching for alternative application run types -- [#2402](https://github.com/sanic-org/sanic/pull/2402) Conditionally inject CLI arguments into factory -- [#2413](https://github.com/sanic-org/sanic/pull/2413) Add new start and stop event listeners to reloader process -- [#2414](https://github.com/sanic-org/sanic/pull/2414) Remove loop as required listener arg -- [#2415](https://github.com/sanic-org/sanic/pull/2415) Better exception for bad URL parsing +- [#2347](https://github.com/sanic-org/sanic/pull/2347) マルチアプリケーション・サーバー用 API + - 🚨 _BREAKING CHANGE_: 古い `sanic.worker.GunicornWorker` が \*\*削除されました。 Sanic を `gunicorn` で実行するには、`uvicorn` format@@0(https\://www\.uvicorn.org/#running-with-gunicorn) で実行する必要があります。 + - 🧁 _SIDE EFFECT_: 名前付きバックグラウンドタスクがPython 3.7 でもサポートされるようになりました +- [#2357](https://github.com/sanic-org/sanic/pull/2357) `Request.credentials` として `Authorization` ヘッダーを解析 +- [#2361](https://github.com/sanic-org/sanic/pull/2361) 設定オプションを追加して、アプリケーションの起動時に`Touchup`ステップをスキップします +- [#2372](https://github.com/sanic-org/sanic/pull/2372) CLIヘルプメッセージングへのアップデート +- [#2382](https://github.com/sanic-org/sanic/pull/2382) バックウォーターデバッグメッセージに警告をダウングレードする +- [#2396](https://github.com/sanic-org/sanic/pull/2396) `multidict` v0.6を許可する +- [#2401](https://github.com/sanic-org/sanic/pull/2401) アプリケーションの実行タイプに応じてCLIをアップグレード +- [#2402](https://github.com/sanic-org/sanic/pull/2402) CLI引数を工場に条件付きで注入する +- [#2413](https://github.com/sanic-org/sanic/pull/2413) 新しい開始と停止のイベントリスナを再ローダープロセスに追加します +- [#2414](https://github.com/sanic-org/sanic/pull/2414) 必要に応じてループを削除 +- [#2415](https://github.com/sanic-org/sanic/pull/2415) 不正なURL解析に対する例外の改善 - [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) Add a new extention parameter type: ``, ``, ``, ``, ``, `` - - 👶 _BETA FEATURE_: This feature will not work with `path` type matching, and is being released as a beta feature only. -- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) Change `register_pattern` to accept a `str` or `Pattern` -- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) Default matching on non-empty strings only, and new `strorempty` pattern type - - 🚨 _BREAKING CHANGE_: Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now **only** match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. + - 👶 _ベータ機能_: この機能は `path` タイプのマッチングでは動作せず、ベータ機能としてのみリリースされています。 +- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) `register_pattern`を`str`または`Pattern`に変更します。 +- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) 空でない文字列のみのデフォルトのマッチングと、新しい `strorempty` パターンタイプ + - 🚨 _BREAKING CHANGE_: 以前は動的な文字列パラメータ (`/` または `/`) を持つルートが任意の文字列にマッチします。 空の文字列も含めてね 空でない文字列と**のみ**が一致します。 古い動作を保持するには、新しいパラメータ `/ ` を使用します。 -### Bugfixes +### バグ修正 -- [#2373](https://github.com/sanic-org/sanic/pull/2373) Remove `error_logger` on websockets -- [#2381](https://github.com/sanic-org/sanic/pull/2381) Fix newly assigned `None` in task registry -- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) Add type casting to regex route matching -- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) Add requirements check on regex routes (this resolves, for example, multiple static directories with differing `host` values) +- [#2373](https://github.com/sanic-org/sanic/pull/2373) websockets の `error_logger` を削除する +- [#2381](https://github.com/sanic-org/sanic/pull/2381) 新たに割り当てられた `None` をタスクレジストリに修正する +- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) regex route matchに型キャストを追加 +- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) regex route (ホスト値が異なる複数の静的ディレクトリなど)の要件を追加します。 -### Deprecations and Removals +### 非推奨と削除 -- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 Deprecations and changes - 1. `debug=True` and `--debug` do _NOT_ automatically run `auto_reload` - 2. Default error render is with plain text (browsers still get HTML by default because `auto` looks at headers) - 3. `config` is required for `ErrorHandler.finalize` - 4. `ErrorHandler.lookup` requires two positional args - 5. Unused websocket protocol args removed -- [#2344](https://github.com/sanic-org/sanic/pull/2344) Deprecate loading of lowercase environment variables +- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 廃止と変更 + 1. `debug=True` と `--debug` do _NOT_ は自動的に `auto_reload` を実行します + 2. デフォルトのエラーレンダリングはプレーンテキストで行われます（ブラウザーは `auto` がヘッダを参照するため、HTML をデフォルトで取得します） + 3. `ErrorHandler.finalize`には`config`が必要です + 4. `ErrorHandler.lookup` には2つの位置引数が必要です + 5. 未使用の websocket プロトコル引数を削除しました +- [#2344](https://github.com/sanic-org/sanic/pull/2344) 小文字の環境変数のロードを非推奨にする -### Developer infrastructure +### 開発者のインフラストラクチャ -- [#2363](https://github.com/sanic-org/sanic/pull/2363) Revert code coverage back to Codecov -- [#2405](https://github.com/sanic-org/sanic/pull/2405) Upgrade tests for `sanic-routing` changes +- [#2363](https://github.com/sanic-org/sanic/pull/2363) コードカバレッジをCodecovに戻す +- [#2405](https://github.com/sanic-org/sanic/pull/2405) `sanic-routing`の変更のためのテストのアップグレード - [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) Allow for httpx v0.22 -### Improved Documentation - -- [#2350](https://github.com/sanic-org/sanic/pull/2350) Fix link in README for ASGI -- [#2398](https://github.com/sanic-org/sanic/pull/2398) Document middleware on_request and on_response -- [#2409](https://github.com/sanic-org/sanic/pull/2409) Add missing documentation for `Request.respond` - -### Miscellaneous - -- [#2376](https://github.com/sanic-org/sanic/pull/2376) Fix typing for `ListenerMixin.listener` -- [#2383](https://github.com/sanic-org/sanic/pull/2383) Clear deprecation warning in `asyncio.wait` -- [#2387](https://github.com/sanic-org/sanic/pull/2387) Cleanup `__slots__` implementations -- [#2390](https://github.com/sanic-org/sanic/pull/2390) Clear deprecation warning in `asyncio.get_event_loop` - -## Version 21.12.1 - -- [#2349](https://github.com/sanic-org/sanic/pull/2349) Only display MOTD on startup -- [#2354](https://github.com/sanic-org/sanic/pull/2354) Ignore name argument in Python 3.7 -- [#2355](https://github.com/sanic-org/sanic/pull/2355) Add config.update support for all config values - -## Version 21.12.0 - -### Features - -- [#2260](https://github.com/sanic-org/sanic/pull/2260) Allow early Blueprint registrations to still apply later added objects -- [#2262](https://github.com/sanic-org/sanic/pull/2262) Noisy exceptions - force logging of all exceptions -- [#2264](https://github.com/sanic-org/sanic/pull/2264) Optional `uvloop` by configuration -- [#2270](https://github.com/sanic-org/sanic/pull/2270) Vhost support using multiple TLS certificates -- [#2277](https://github.com/sanic-org/sanic/pull/2277) Change signal routing for increased consistency - - _BREAKING CHANGE_: If you were manually routing signals there is a breaking change. The signal router's `get` is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using `app.dispatch` or `bp.dispatch`, there is no change. -- [#2290](https://github.com/sanic-org/sanic/pull/2290) Add contextual exceptions -- [#2291](https://github.com/sanic-org/sanic/pull/2291) Increase join concat performance -- [#2295](https://github.com/sanic-org/sanic/pull/2295), [#2316](https://github.com/sanic-org/sanic/pull/2316), [#2331](https://github.com/sanic-org/sanic/pull/2331) Restructure of CLI and application state with new displays and more command parity with `app.run` -- [#2302](https://github.com/sanic-org/sanic/pull/2302) Add route context at definition time -- [#2304](https://github.com/sanic-org/sanic/pull/2304) Named tasks and new API for managing background tasks -- [#2307](https://github.com/sanic-org/sanic/pull/2307) On app auto-reload, provide insight of changed files -- [#2308](https://github.com/sanic-org/sanic/pull/2308) Auto extend application with [Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) if it is installed, and provide first class support for accessing the extensions -- [#2309](https://github.com/sanic-org/sanic/pull/2309) Builtin signals changed to `Enum` -- [#2313](https://github.com/sanic-org/sanic/pull/2313) Support additional config implementation use case -- [#2321](https://github.com/sanic-org/sanic/pull/2321) Refactor environment variable hydration logic -- [#2327](https://github.com/sanic-org/sanic/pull/2327) Prevent sending multiple or mixed responses on a single request -- [#2330](https://github.com/sanic-org/sanic/pull/2330) Custom type casting on environment variables -- [#2332](https://github.com/sanic-org/sanic/pull/2332) Make all deprecation notices consistent -- [#2335](https://github.com/sanic-org/sanic/pull/2335) Allow underscore to start instance names - -### Bugfixes - -- [#2273](https://github.com/sanic-org/sanic/pull/2273) Replace assignation by typing for `websocket_handshake` -- [#2285](https://github.com/sanic-org/sanic/pull/2285) Fix IPv6 display in startup logs -- [#2299](https://github.com/sanic-org/sanic/pull/2299) Dispatch `http.lifecyle.response` from exception handler - -### Deprecations and Removals - -- [#2306](https://github.com/sanic-org/sanic/pull/2306) Removal of deprecated items - - `Sanic` and `Blueprint` may no longer have arbitrary properties attached to them - - `Sanic` and `Blueprint` forced to have compliant names +### ドキュメントの改善 + +- [#2350](https://github.com/sanic-org/sanic/pull/2350) READMEのリンクを修正する +- [#2398](https://github.com/sanic-org/sanic/pull/2398) ドキュメントミドルウェアon_requestとon_response +- [#2409](https://github.com/sanic-org/sanic/pull/2409) `Request.respond`に不足しているドキュメントを追加する + +### その他 + +- [#2376](https://github.com/sanic-org/sanic/pull/2376) `ListenerMixin.listener` の入力を修正 +- [#2383](https://github.com/sanic-org/sanic/pull/2383) `asyncio.wait` で非推奨の警告をクリアする +- [#2387](https://github.com/sanic-org/sanic/pull/2387) Cleanup `__slots__` 実装 +- [#2390](https://github.com/sanic-org/sanic/pull/2390) `asyncio.get_event_loop`で非推奨の警告をクリアする + +## バージョン21.12.1 + +- [#2349](https://github.com/sanic-org/sanic/pull/2349) スタートアップ時にMOTD のみ表示する +- [#2354](https://github.com/sanic-org/sanic/pull/2354) Python 3.7 の名前引数を無視する +- [#2355](https://github.com/sanic-org/sanic/pull/2355) config.update サポートをすべての設定値に追加しました。 + +## バージョン 21.12.0 + +### 特徴 + +- [#2260](https://github.com/sanic-org/sanic/pull/2260) 初期のブループリント登録を許可して、後で追加されたオブジェクトを適用する +- [#2262](https://github.com/sanic-org/sanic/pull/2262) ノイズ例外 - すべての例外を強制的にログ収集する +- [#2264](https://github.com/sanic-org/sanic/pull/2264) オプションの `uvloop` 設定で +- [#2270](https://github.com/sanic-org/sanic/pull/2270) 複数の TLS 証明書を使用した Vhost サポート +- [#2277](https://github.com/sanic-org/sanic/pull/2277) シグナルルーティングを変更して一貫性を高めます。 + - _BREAKING CHANGE_:手動でルーティングしていた場合は、改ざんの変更があります。 シグナルルーターの「get」は100%決定的なものではなくなりました。 返される信号をループさせて、要件を適切にマッチングするための追加のステップが追加されました。 `app.dispatch` や `bp.dispatch` を使ってシグナルがディスパッチされている場合、変更はありません。 +- [#2290](https://github.com/sanic-org/sanic/pull/2290) 文脈例外を追加する +- [#2291](https://github.com/sanic-org/sanic/pull/2291) 参加コンキャットのパフォーマンスを向上させる +- [#2295](https://github.com/sanic-org/sanic/pull/2295), [#2316](https://github.com/sanic-org/sanic/pull/2331), [#2331](https://github.com/sanic-org/sanic/pull/2331) CLIとアプリケーションの状態を再構築し、`app.run`を使用するとコマンドパリティを強化します。 +- [#2302](https://github.com/sanic-org/sanic/pull/2302) 定義時にルートコンテキストを追加 +- [#2304](https://github.com/sanic-org/sanic/pull/2304) バックグラウンドタスクを管理するための名前付きタスクと新しい API +- [#2307](https://github.com/sanic-org/sanic/pull/2307) アプリの自動再読み込みで、変更されたファイルの洞察を提供する +- [#2308](https://github.com/sanic-org/sanic/pull/2308) インストールされている場合は[Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html)でアプリケーションを自動的に拡張し、拡張機能にアクセスするためのファーストクラスをサポートします。 +- [#2309](https://github.com/sanic-org/sanic/pull/2309) 組み込み信号が`Enum`に変更されました +- [#2313](https://github.com/sanic-org/sanic/pull/2313) 追加の設定実装ユースケースに対応 +- [#2321](https://github.com/sanic-org/sanic/pull/2321) 環境変数水和ロジックをリファクタリングする +- [#2327](https://github.com/sanic-org/sanic/pull/2327) 単一のリクエストで複数の反応や混合反応を防ぎます +- [#2330](https://github.com/sanic-org/sanic/pull/2330) 環境変数のカスタム型キャスト。 +- [#2332](https://github.com/sanic-org/sanic/pull/2332) すべての非推奨通知を一貫性のあるものにする +- [#2335](https://github.com/sanic-org/sanic/pull/2335) アンダースコアのインスタンス名の開始を許可する + +### バグ修正 + +- [#2273](https://github.com/sanic-org/sanic/pull/2273) `websocket_handshake`を入力して割り当てを変更する +- [#2285](https://github.com/sanic-org/sanic/pull/2285) スタートアップログのIPv6表示を修正 +- [#2299](https://github.com/sanic-org/sanic/pull/2299) 例外ハンドラから `http.lifyle.response` を送信する + +### 非推奨と削除 + +- [#2306](https://github.com/sanic-org/sanic/pull/2306) 非推奨アイテムの削除 + - `Sanic` と `Blueprint` に任意のプロパティが付いていない可能性があります + - `Sanic` と `Blueprint` に準拠した名前が強制されました - alphanumeric + `_` + `-` - - must start with letter or `_` - - `load_env` keyword argument of `Sanic` + - は文字または`_`で始まる必要があります + - `Sanic`の`load_env`キーワード引数 - `sanic.exceptions.abort` - `sanic.views.CompositionView` - `sanic.response.StreamingHTTPResponse` - - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming -- [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting + - _注意:_ `stream()` レスポンスメソッド (呼び出し可能なストリーミング関数を渡す) は廃止され、v22.6 で削除されます。 新しいスタイルのすべてのストリーミング応答をアップグレードする必要があります: https\://sanicframework.org/ja/guide/advanced/streaming.html#response-stream +- [#2320](https://github.com/sanic-org/sanic/pull/2320) Configからエラーハンドラ設定用アプリインスタンスを削除します -### Developer infrastructure +### 開発者のインフラストラクチャ -- [#2251](https://github.com/sanic-org/sanic/pull/2251) Change dev install command -- [#2286](https://github.com/sanic-org/sanic/pull/2286) Change codeclimate complexity threshold from 5 to 10 -- [#2287](https://github.com/sanic-org/sanic/pull/2287) Update host test function names so they are not overwritten -- [#2292](https://github.com/sanic-org/sanic/pull/2292) Fail CI on error -- [#2311](https://github.com/sanic-org/sanic/pull/2311), [#2324](https://github.com/sanic-org/sanic/pull/2324) Do not run tests for draft PRs -- [#2336](https://github.com/sanic-org/sanic/pull/2336) Remove paths from coverage checks -- [#2338](https://github.com/sanic-org/sanic/pull/2338) Cleanup ports on tests +- [#2251](https://github.com/sanic-org/sanic/pull/2251) dev install コマンドを変更する +- [#2286](https://github.com/sanic-org/sanic/pull/2286) コード化のしきい値を5から10に変更する +- [#2287](https://github.com/sanic-org/sanic/pull/2287) ホストテスト関数名を上書きしないように更新する +- [#2292](https://github.com/sanic-org/sanic/pull/2292) エラー時に失敗する CI +- [#2311](https://github.com/sanic-org/sanic/pull/2311), [#2324](https://github.com/sanic-org/sanic/pull/2324) PRsのドラフトテストを実行しないでください +- [#2336](https://github.com/sanic-org/sanic/pull/2336) カバレッジチェックからパスを削除 +- [#2338](https://github.com/sanic-org/sanic/pull/2338) テストのポートをクリーンアップする -### Improved Documentation +### ドキュメントの改善 -- [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2329), [#2333](https://github.com/sanic-org/sanic/pull/2333) Cleanup typos and fix language +- [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2333) 型のクリーンアップと言語の修正 -### Miscellaneous +### その他 -- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) Add Python 3.10 support -- [#2279](https://github.com/sanic-org/sanic/pull/2279), [#2317](https://github.com/sanic-org/sanic/pull/2317), [#2322](https://github.com/sanic-org/sanic/pull/2322) Add/correct missing type annotations -- [#2305](https://github.com/sanic-org/sanic/pull/2305) Fix examples to use modern implementations +- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/22941) [#2341](https://github.com/sanic-org/sanic/pull/2341) Python 3.10 サポートを追加 +- [#2279](https://github.com/sanic-org/sanic/pull/2279), [#2317](https://github.com/sanic-org/sanic/pull/2322) 不足している型の注釈を追加/修正する +- [#2305](https://github.com/sanic-org/sanic/pull/2305) モダンな実装を使用する例を修正しました。 -## Version 21.9.3 +## バージョン 21.9.3 -_Rerelease of v21.9.2 with some cleanup_ +_クリーンアップされた v21.9.2 の再リリース_ -## Version 21.9.2 +## バージョン 21.9.2 -- [#2268](https://github.com/sanic-org/sanic/pull/2268) Make HTTP connections start in IDLE stage, avoiding delays and error messages -- [#2310](https://github.com/sanic-org/sanic/pull/2310) More consistent config setting with post-FALLBACK_ERROR_FORMAT apply +- [#2268](https://github.com/sanic-org/sanic/pull/2268) HTTP接続をIDLEステージで開始し、遅延やエラーメッセージを回避する +- [#2310](https://github.com/sanic-org/sanic/pull/2310) Post-FALLBACK_ERROR_FORMAT が適用されます。 -## Version 21.9.1 +## バージョン21.9.1 -- [#2259](https://github.com/sanic-org/sanic/pull/2259) Allow non-conforming ErrorHandlers +- [#2259](https://github.com/sanic-org/sanic/pull/2259) 非準拠ErrorHandlers を許可する -## Version 21.9.0 +## バージョン 21.9.0 -### Features +### 特徴 -- [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) Complete overhaul of I/O to websockets -- [#2160](https://github.com/sanic-org/sanic/pull/2160) Add new 17 signals into server and request lifecycles -- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto` fallback formatting upon exception -- [#2184](https://github.com/sanic-org/sanic/pull/2184) Introduce implementation for copying a Blueprint -- [#2200](https://github.com/sanic-org/sanic/pull/2200) Accept header parsing -- [#2207](https://github.com/sanic-org/sanic/pull/2207) Log remote address if available -- [#2209](https://github.com/sanic-org/sanic/pull/2209) Add convenience methods to BP groups -- [#2216](https://github.com/sanic-org/sanic/pull/2216) Add default messages to SanicExceptions -- [#2225](https://github.com/sanic-org/sanic/pull/2225) Type annotation convenience for annotated handlers with path parameters -- [#2236](https://github.com/sanic-org/sanic/pull/2236) Allow Falsey (but not-None) responses from route handlers -- [#2238](https://github.com/sanic-org/sanic/pull/2238) Add `exception` decorator to Blueprint Groups -- [#2244](https://github.com/sanic-org/sanic/pull/2244) Explicit static directive for serving file or dir (ex: `static(..., resource_type="file")`) -- [#2245](https://github.com/sanic-org/sanic/pull/2245) Close HTTP loop when connection task cancelled +- [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) I/Oをwebsocketに完全にオーバーホールする +- [#2160](https://github.com/sanic-org/sanic/pull/2160) サーバーに17の新しい信号を追加し、ライフサイクルをリクエストする +- [#2162](https://github.com/sanic-org/sanic/pull/2162) 例外が発生した場合、よりスマートな `auto` フォールバックの書式設定 +- [#2184](https://github.com/sanic-org/sanic/pull/2184) ブループリントをコピーするための実装を導入する +- [#2200](https://github.com/sanic-org/sanic/pull/2200) ヘッダーの解析を許可 +- [#2207](https://github.com/sanic-org/sanic/pull/2207) 利用可能な場合はリモートアドレスを記録する +- [#2209](https://github.com/sanic-org/sanic/pull/2209) BPグループに便利な方法を追加 +- [#2216](https://github.com/sanic-org/sanic/pull/2216) SanicExceptionsにデフォルトのメッセージを追加する +- [#2225](https://github.com/sanic-org/sanic/pull/2225) パスパラメータを持つアノテーションハンドラのタイプアノテーションの利便性。 +- [#2236](https://github.com/sanic-org/sanic/pull/2236) ルートハンドラーからのFalsey(ただしNoneではない)応答を許可する +- [#2238](https://github.com/sanic-org/sanic/pull/2238) ブループリントグループに`exception`デコレータを追加する +- [#2244](https://github.com/sanic-org/sanic/pull/2244) ファイルまたはdir (例: `static(..., resource_type="file")`) +- [#2245](https://github.com/sanic-org/sanic/pull/2245) 接続タスクがキャンセルされたらHTTPループを閉じます。 -### Bugfixes +### バグ修正 -- [#2188](https://github.com/sanic-org/sanic/pull/2188) Fix the handling of the end of a chunked request -- [#2195](https://github.com/sanic-org/sanic/pull/2195) Resolve unexpected error handling on static requests -- [#2208](https://github.com/sanic-org/sanic/pull/2208) Make blueprint-based exceptions attach and trigger in a more intuitive manner -- [#2211](https://github.com/sanic-org/sanic/pull/2211) Fixed for handling exceptions of asgi app call -- [#2213](https://github.com/sanic-org/sanic/pull/2213) Fix bug where ws exceptions not being logged -- [#2231](https://github.com/sanic-org/sanic/pull/2231) Cleaner closing of tasks by using `abort()` in strategic places to avoid dangling sockets -- [#2247](https://github.com/sanic-org/sanic/pull/2247) Fix logging of auto-reload status in debug mode -- [#2246](https://github.com/sanic-org/sanic/pull/2246) Account for BP with exception handler but no routes +- [#2188](https://github.com/sanic-org/sanic/pull/2188) チャンクされたリクエストの終了を修正する +- [#2195](https://github.com/sanic-org/sanic/pull/2195) 静的リクエスト時の予期しないエラー処理を解決する +- [#2208](https://github.com/sanic-org/sanic/pull/2208) ブループリントベースの例外をより直感的にアタッチしてトリガーさせる。 +- [#2211](https://github.com/sanic-org/sanic/pull/2211) asgi アプリ呼び出しの例外処理を修正。 +- [#2213](https://github.com/sanic-org/sanic/pull/2213) 例外が記録されないバグを修正しました。 +- [#2231](https://github.com/sanic-org/sanic/pull/2231) 戦略的な場所で `abort()` を使用してタスクを終了させ、ダングルソケットを避けます。 +- [#2247](https://github.com/sanic-org/sanic/pull/2247) デバッグモードでの自動リロード状態のロギングを修正する +- [#2246](https://github.com/sanic-org/sanic/pull/2246) BPアカウントの例外ハンドラーですがルートはありません -### Developer infrastructure +### 開発者のインフラストラクチャ -- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP unit tests with raw client -- [#2199](https://github.com/sanic-org/sanic/pull/2199) Switch to codeclimate -- [#2214](https://github.com/sanic-org/sanic/pull/2214) Try Reopening Windows Tests -- [#2229](https://github.com/sanic-org/sanic/pull/2229) Refactor `HttpProtocol` into a base class -- [#2230](https://github.com/sanic-org/sanic/pull/2230) Refactor `server.py` into multi-file module +- [#2194](https://github.com/sanic-org/sanic/pull/2194) 生クライアントのHTTPユニットテスト +- [#2199](https://github.com/sanic-org/sanic/pull/2199) codeclimate に切り替える +- [#2214](https://github.com/sanic-org/sanic/pull/2214) Windows テストを再開してみてください +- [#2229](https://github.com/sanic-org/sanic/pull/2229) `HttpProtocol`をベースクラスにリファクタリングします +- [#2230](https://github.com/sanic-org/sanic/pull/2230) `server.py`をマルチファイルモジュールにリファクタリングします。 -### Miscellaneous +### その他 -- [#2173](https://github.com/sanic-org/sanic/pull/2173) Remove Duplicated Dependencies and PEP 517 Support -- [#2193](https://github.com/sanic-org/sanic/pull/2193), [#2196](https://github.com/sanic-org/sanic/pull/2196), [#2217](https://github.com/sanic-org/sanic/pull/2217) Type annotation changes +- [#2173](https://github.com/sanic-org/sanic/pull/2173) 重複した依存関係とPEP 517のサポート +- [#2193](https://github.com/sanic-org/sanic/pull/2193), [#2196](https://github.com/sanic-org/sanic/pull/2196), [#2217](https://github.com/sanic-org/sanic/pull/2217) 型注釈の変更 -## Version 21.6.1 +## バージョン 21.6.1 -**Bugfixes** +**バグ修正** - [#2178](https://github.com/sanic-org/sanic/pull/2178) Update sanic-routing to allow for better splitting of complex URI templates -- [#2183](https://github.com/sanic-org/sanic/pull/2183) Proper - handling of chunked request bodies to resolve phantom 503 in logs -- [#2181](https://github.com/sanic-org/sanic/pull/2181) Resolve - regression in exception logging -- [#2201](https://github.com/sanic-org/sanic/pull/2201) Cleanup - request info in pipelined requests +- [#2183](https://github.com/sanic-org/sanic/pull/2183) ブロックされたリクエストボディの適切な + 処理でログ内のファントム503を解決する +- [#2181](https://github.com/sanic-org/sanic/pull/2181) 例外ロギングで + 回帰を解決する +- [#2201](https://github.com/sanic-org/sanic/pull/2201) パイプライン化リクエストの + リクエスト情報 -## Version 21.6.0 +## バージョン 21.6.0 -**Features** +**機能** -- [#2094](https://github.com/sanic-org/sanic/pull/2094) Add - `response.eof()` method for closing a stream in a handler +- [#2094](https://github.com/sanic-org/sanic/pull/2094) ハンドラ内でストリームを閉じるために + `response.eof()` メソッドを追加する -- [#2097](https://github.com/sanic-org/sanic/pull/2097) Allow - case-insensitive HTTP Upgrade header +- [#2097](https://github.com/sanic-org/sanic/pull/2097) + 大文字小文字を区別しない HTTP アップグレードヘッダー -- [#2104](https://github.com/sanic-org/sanic/pull/2104) Explicit - usage of CIMultiDict getters +- [#2104](https://github.com/sanic-org/sanic/pull/2104) 明示 + CIMultDictゲッターの使用 -- [#2109](https://github.com/sanic-org/sanic/pull/2109) Consistent - use of error loggers +- [#2109](https://github.com/sanic-org/sanic/pull/2109) 一貫性のある + エラーロガーの使用 -- [#2114](https://github.com/sanic-org/sanic/pull/2114) New - `client_ip` access of connection info instance +- [#21114](https://github.com/sanic-org/sanic/pull/2114) 新しい + `client_ip` 接続情報インスタンスへのアクセス -- [#2119](https://github.com/sanic-org/sanic/pull/2119) Alternatate - classes on instantiation for `Config` and `Sanic.ctx` +- [#2119](https://github.com/sanic-org/sanic/pull/2119) `Config` と `Sanic.ctx` のインスタンス化時の代替 + クラス - [#2133](https://github.com/sanic-org/sanic/pull/2133) Implement new version of AST router - - Proper differentiation between `alpha` and `string` param - types - - Adds a `slug` param type, example: `` - - Deprecates `` in favor of `` - - Deprecates `` in favor of `` + - `alpha` と `string` param + 型を適切に区別します + - `slug` param typeを追加します。例: `` + - 非推奨の``は`` + - 非推奨の``は`` - Adds a `route.uri` accessor - [#2136](https://github.com/sanic-org/sanic/pull/2136) CLI - improvements with new optional params + の改善と新しいオプションのパラメータ -- [#2137](https://github.com/sanic-org/sanic/pull/2137) Add - `version_prefix` to URL builders +- [#2137](https://github.com/sanic-org/sanic/pull/2137) URLビルダーに + `version_prefix` を追加する - [#2140](https://github.com/sanic-org/sanic/pull/2140) Event autoregistration with `EVENT_AUTOREGISTER` @@ -591,195 +591,194 @@ _Rerelease of v21.9.2 with some cleanup_ stricter names on `Sanic()` and `Blueprint()` - [#2150](https://github.com/sanic-org/sanic/pull/2150) Infinitely - reusable and nestable `Blueprint` and `BlueprintGroup` + reuseable and nestable `Blueprint` and `BlueprintGroup` -- [#2154](https://github.com/sanic-org/sanic/pull/2154) Upgrade - `websockets` dependency to min version +- [#2154](https://github.com/sanic-org/sanic/pull/2154) + `websockets` の依存関係をminバージョンにアップグレード -- [#2155](https://github.com/sanic-org/sanic/pull/2155) Allow for - maximum header sizes to be increased: `REQUEST_MAX_HEADER_SIZE` +- [#2155](https://github.com/sanic-org/sanic/pull/2155) + の最大ヘッダーサイズを増加させる: `REQUEST_MAX_HEADER_SIZE` -- [#2157](https://github.com/sanic-org/sanic/pull/2157) Allow app - factory pattern in CLI +- [#2157](https://github.com/sanic-org/sanic/pull/2157) CLI でアプリ + ファクトリパターンを許可する -- [#2165](https://github.com/sanic-org/sanic/pull/2165) Change HTTP - methods to enums +- [#2165](https://github.com/sanic-org/sanic/pull/2165) HTTP + メソッドを列挙に変更する -- [#2167](https://github.com/sanic-org/sanic/pull/2167) Allow - auto-reloading on additional directories +- [#2167](https://github.com/sanic-org/sanic/pull/2167) + 追加ディレクトリの自動再読み込みを許可する -- [#2168](https://github.com/sanic-org/sanic/pull/2168) Add simple - HTTP server to CLI +- [#2168](https://github.com/sanic-org/sanic/pull/2168) シンプルな + HTTPサーバーをCLIに追加 -- [#2170](https://github.com/sanic-org/sanic/pull/2170) Additional - methods for attaching `HTTPMethodView` +- [#2170](https://github.com/sanic-org/sanic/pull/2170) 追加の + メソッドで `HTTPMethodView` をアタッチする -**Bugfixes** +**バグ修正** - [#2091](https://github.com/sanic-org/sanic/pull/2091) Fix `UserWarning` in ASGI mode for missing `__slots__` -- [#2099](https://github.com/sanic-org/sanic/pull/2099) Fix static - request handler logging exception on 404 -- [#2110](https://github.com/sanic-org/sanic/pull/2110) Fix - request.args.pop removes parameters inconsistently +- [#2099](https://github.com/sanic-org/sanic/pull/2099) スタティック + リクエストハンドラーのログ例外を404で修正 +- [#2110](https://github.com/sanic-org/sanic/pull/2110) + request.args.pop パラメータを不整合に削除する - [#2107](https://github.com/sanic-org/sanic/pull/2107) Fix type hinting for load_env -- [#2127](https://github.com/sanic-org/sanic/pull/2127) Make sure - ASGI ws subprotocols is a list -- [#2128](https://github.com/sanic-org/sanic/pull/2128) Fix issue - where Blueprint exception handlers do not consistently route to - proper handler +- [#2127](https://github.com/sanic-org/sanic/pull/2127) + ASGI ws サブプロトコルがリストであることを確認してください +- [#2128](https://github.com/sanic-org/sanic/pull/2128) 問題 + ブループリントの例外ハンドラーが一貫して + 適切なハンドラーにルートされない問題を修正 -**Deprecations and Removals** +**非推奨と削除** -- [#2156](https://github.com/sanic-org/sanic/pull/2156) Remove - config value `REQUEST_BUFFER_QUEUE_SIZE` +- [#2156](https://github.com/sanic-org/sanic/pull/2156) + 設定値 `REQUE_SIZE` を削除する - [#2170](https://github.com/sanic-org/sanic/pull/2170) - `CompositionView` deprecated and marked for removal in 21.12 -- [#2172](https://github.com/sanic-org/sanic/pull/2170) Deprecate + `CompositionView` は非推奨となり、21.12 で削除されるようになりました。 +- [#2172](https://github.com/sanic-org/sanic/pull/2170) StreamingHTTPResponse -**Developer infrastructure** +**開発者のインフラストラクチャ** -- [#2149](https://github.com/sanic-org/sanic/pull/2149) Remove - Travis CI in favor of GitHub Actions +- [#2149](https://github.com/sanic-org/sanic/pull/2149) GitHub Actions を支持する + Travis CI を削除する -**Improved Documentation** +**ドキュメントの改善** -- [#2164](https://github.com/sanic-org/sanic/pull/2164) Fix typo in - documentation -- [#2100](https://github.com/sanic-org/sanic/pull/2100) Remove - documentation for non-existent arguments +- [#2164](https://github.com/sanic-org/sanic/pull/2164) + ドキュメントのtypoを修正 +- [#2100](https://github.com/sanic-org/sanic/pull/2100) 存在しない引数の + ドキュメントを削除する -## Version 21.3.2 +## バージョン 21.3.2 -**Bugfixes** +**バグ修正** -- [#2081](https://github.com/sanic-org/sanic/pull/2081) Disable - response timeout on websocket connections +- [#2081](https://github.com/sanic-org/sanic/pull/2081) WebSocket接続で + 応答タイムアウトを無効にする - [#2085](https://github.com/sanic-org/sanic/pull/2085) Make sure that blueprints with no slash is maintained when applied -## Version 21.3.1 +## バージョン 21.3.1 -**Bugfixes** +**バグ修正** -- [#2076](https://github.com/sanic-org/sanic/pull/2076) Static files - inside subfolders are not accessible (404) +- [#2076](https://github.com/sanic-org/sanic/pull/2076) サブフォルダー内の静的ファイル + にアクセスできません (404) -## Version 21.3.0 +## バージョン 21.3.0 Release Notes -**Features** +**機能** - [#1876](https://github.com/sanic-org/sanic/pull/1876) Unified - streaming server -- [#2005](https://github.com/sanic-org/sanic/pull/2005) New - `Request.id` property -- [#2008](https://github.com/sanic-org/sanic/pull/2008) Allow - Pathlib Path objects to be passed to `app.static()` helper + ストリーミングサーバー +- [#2005](https://github.com/sanic-org/sanic/pull/2005) 新しい + `Request.id` プロパティ +- [#2008](https://github.com/sanic-org/sanic/pull/2008) + Pathlib Path オブジェクトを `app.static()` helper に渡すことを許可する - [#2010](https://github.com/sanic-org/sanic/pull/2010), [#2031](https://github.com/sanic-org/sanic/pull/2031) New startup-optimized router - [#2018](https://github.com/sanic-org/sanic/pull/2018) - [#2064](https://github.com/sanic-org/sanic/pull/2064) Listeners - for main server process -- [#2032](https://github.com/sanic-org/sanic/pull/2032) Add raw - header info to request object + [#2064](https://github.com/sanic-org/sanic/pull/2064) メインサーバープロセスのリスナー +- [#2032](https://github.com/sanic-org/sanic/pull/2032) オブジェクトをリクエストするために生の + ヘッダー情報を追加する - [#2042](https://github.com/sanic-org/sanic/pull/2042) [#2060](https://github.com/sanic-org/sanic/pull/2060) - [#2061](https://github.com/sanic-org/sanic/pull/2061) Introduce + [#2061](https://github.com/sanic-org/sanic/pull/2061) Signals API -- [#2043](https://github.com/sanic-org/sanic/pull/2043) Add - `__str__` and `__repr__` to Sanic and Blueprint -- [#2047](https://github.com/sanic-org/sanic/pull/2047) Enable - versioning and strict slash on BlueprintGroup -- [#2053](https://github.com/sanic-org/sanic/pull/2053) Make - `get_app` name argument optional -- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON encoder - change via app -- [#2063](https://github.com/sanic-org/sanic/pull/2063) App and - connection level context objects - -**Bugfixes** - -- Resolve [#1420](https://github.com/sanic-org/sanic/pull/1420) - `url_for` where `strict_slashes` are on for a path ending in `/` -- Resolve [#1525](https://github.com/sanic-org/sanic/pull/1525) - Routing is incorrect with some special characters +- [#2043](https://github.com/sanic-org/sanic/pull/2043) SanicとBlueprintに + `__str__` と \`__repr__を追加する +- [#2047](https://github.com/sanic-org/sanic/pull/2047) ブループリントグループで + バージョン管理と厳密なスラッシュを有効にする +- [#2053](https://github.com/sanic-org/sanic/pull/2053) + `get_app` name 引数は省略可能にする +- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSONエンコーダー + をアプリ経由で変更 +- [#2063](https://github.com/sanic-org/sanic/pull/2063) App と + コネクションレベルのコンテキストオブジェクト + +**バグ修正** + +- 解決する [#1420](https://github.com/sanic-org/sanic/pull/1420) + `url_for` ここで `strict_slashes` は`/`で終わるパスに対して有効です +- 解決[#1525](https://github.com/sanic-org/sanic/pull/1525) + ルーティングは特殊文字で正しくありません - Resolve [#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI - headers in body -- Resolve [#1722](https://github.com/sanic-org/sanic/pull/1722) - Using curl in chunk mode -- Resolve [#1730](https://github.com/sanic-org/sanic/pull/1730) - Extra content in ASGI streaming response -- Resolve [#1749](https://github.com/sanic-org/sanic/pull/1749) - Restore broken middleware edge cases -- Resolve [#1785](https://github.com/sanic-org/sanic/pull/1785) + headers +- 解決する [#1722](https://github.com/sanic-org/sanic/pull/1722) + チャンクモードで curl を使う +- 解決[#1730](https://github.com/sanic-org/sanic/pull/1730) + ASGIストリーミング応答の追加コンテンツ +- 解決[#1749](https://github.com/sanic-org/sanic/pull/1749) + 壊れたミドルウェアのエッジケースを復元する +- 解決[#1785](https://github.com/sanic-org/sanic/pull/1785) [#1804](https://github.com/sanic-org/sanic/pull/1804) Synchronous - error handlers -- Resolve [#1790](https://github.com/sanic-org/sanic/pull/1790) - Protocol errors did not support async error handlers #1790 -- Resolve [#1824](https://github.com/sanic-org/sanic/pull/1824) - Timeout on specific methods -- Resolve [#1875](https://github.com/sanic-org/sanic/pull/1875) - Response timeout error from all routes after returning several - timeouts from a specific route -- Resolve [#1988](https://github.com/sanic-org/sanic/pull/1988) - Handling of safe methods with body -- [#2001](https://github.com/sanic-org/sanic/pull/2001) Raise - ValueError when cookie max-age is not an integer - -**Deprecations and Removals** + error handler +- 解決 [#1790](https://github.com/sanic-org/sanic/pull/1790) + プロトコルエラーは非同期エラーハンドラをサポートしていません #1790 +- 解決[#1824](https://github.com/sanic-org/sanic/pull/1824) + 特定のメソッドのタイムアウト +- 解決[#1875](https://github.com/sanic-org/sanic/pull/1875) + 特定のルートから複数の + タイムアウトを返した後のすべてのルートからの応答タイムアウトエラー。 +- 解決する [#1988](https://github.com/sanic-org/sanic/pull/1988) + ボディで安全なメソッドを処理する +- [#2001](https://github.com/sanic-org/sanic/pull/2001) Cookie max-age が整数でない場合の + ValueError + +**非推奨と削除** - [#2007](https://github.com/sanic-org/sanic/pull/2007) \* Config - using `from_envvar` \* Config using `from_pyfile` \* Config using - `from_object` -- [#2009](https://github.com/sanic-org/sanic/pull/2009) Remove Sanic - test client to its own package + `from_envar` \* 設定で + `from_object` を使用する +- [#2009](https://github.com/sanic-org/sanic/pull/2009) Sanic + テストクライアントを独自のパッケージに削除 - [#2036](https://github.com/sanic-org/sanic/pull/2036), - [#2037](https://github.com/sanic-org/sanic/pull/2037) Drop Python - 3.6 support -- `Request.endpoint` deprecated in favor of `Request.name` -- handler type name prefixes removed (static, websocket, etc) + [#2037](https://github.com/sanic-org/sanic/pull/2037) Python + 3.6 のサポート +- `Request.endpoint` は `Request.name` を支持しています。 +- handler 型名プレフィックスが削除されました (静的、websocketなど) -**Developer infrastructure** +**開発者のインフラストラクチャ** -- [#1995](https://github.com/sanic-org/sanic/pull/1995) Create - FUNDING.yml -- [#2013](https://github.com/sanic-org/sanic/pull/2013) Add codeql - to CI pipeline +- [#1995](https://github.com/sanic-org/sanic/pull/1995) + FUNDING.yml を作成 +- [#2013](https://github.com/sanic-org/sanic/pull/2013) CIパイプラインにcodeql + を追加 - [#2038](https://github.com/sanic-org/sanic/pull/2038) Codecov - configuration updates -- [#2049](https://github.com/sanic-org/sanic/pull/2049) Updated - setup.py to use `find_packages` + 設定の更新 +- [#2049](https://github.com/sanic-org/sanic/pull/2049) `find_packages`を使用するように + setup.pyを更新しました -**Improved Documentation** +**ドキュメントの改善** - [#1218](https://github.com/sanic-org/sanic/pull/1218) - Documentation for sanic.log.\* is missing + sanic.log.\* のドキュメントがありません - [#1608](https://github.com/sanic-org/sanic/pull/1608) Add documentation on calver and LTS - [#1731](https://github.com/sanic-org/sanic/pull/1731) Support mounting application elsewhere than at root path -- [#2006](https://github.com/sanic-org/sanic/pull/2006) Upgraded - type annotations and improved docstrings and API documentation -- [#2052](https://github.com/sanic-org/sanic/pull/2052) Fix some - examples and docs +- [#2006](https://github.com/sanic-org/sanic/pull/2006) + 型の注釈とdocstrings と API ドキュメンテーションの改善 +- [#2052](https://github.com/sanic-org/sanic/pull/2052) いくつかの + 例とドキュメントを修正する -**Miscellaneous** +**その他** -- `Request.route` property -- Better websocket subprotocols support +- `Request.route` プロパティ +- より優れた websocket サブプロトコルのサポート - Resolve bug with middleware in Blueprint Group when passed callable -- Moves common logic between Blueprint and Sanic into mixins -- Route naming changed to be more consistent - - request endpoint is the route name +- ブループリントとサニックの間で共通のロジックをミックスインに移動します。 +- ルート名をより一貫性のあるものに変更しました + - 要求エンドポイントはルート名です - route names are fully namespaced -- Some new convenience decorators: +- いくつかの新しいコンビニエンスデコレータ: - `@app.main_process_start` - `@app.main_process_stop` - `@app.before_server_start` @@ -788,268 +787,269 @@ Notes - `@app.after_server_stop` - `@app.on_request` - `@app.on_response` -- Fixes `Allow` header that did not include `HEAD` -- Using "name" keyword in `url_for` for a "static" route where - name does not exist -- Cannot have multiple `app.static()` without using the named param -- Using "filename" keyword in `url_for` on a file route -- `unquote` in route def (not automatic) -- `routes_all` is tuples -- Handler arguments are kwarg only -- `request.match_info` is now a cached (and not computed) property -- Unknown static file mimetype is sent as `application/octet-stream` -- `_host` keyword in `url_for` -- Add charset default to `utf-8` for text and js content types if - not specified -- Version for a route can be str, float, or int -- Route has ctx property -- App has `routes_static`, `routes_dynamic`, `routes_regex` -- [#2044](https://github.com/sanic-org/sanic/pull/2044) Code cleanup - and refactoring +- `HEAD`を含まない`Allow`ヘッダーを修正しました。 +- ``` + 名が存在しない\"静的\"ルートに`url_for`で\"name\" キーワードを使用する + ``` +- 名前付きの param を使用せずに複数の `app.static()` を持つことはできません +- ファイルルート上で`url_for`の"filename" キーワードを使用する +- ルートデフの`unquote` (自動ではありません) +- `routes_all`はタプルです +- ハンドラの引数はkwargのみです +- `request.match_info` はキャッシュされた(計算されていない)プロパティになりました +- 不明な静的ファイル mimetype が `application/octet-stream` として送信されます。 +- `url_for`の`_host` キーワード +- ``` + が指定されていない場合はテキストとjsコンテンツタイプのデフォルトの文字セットを`utf-8`に追加します + ``` +- ルートのバージョンはstr、float、int にすることができます。 +- ルートは ctx プロパティを持ちます +- アプリには`routes_static`、`routes_dynamic`、`routes_regex`があります +- [#2044](https://github.com/sanic-org/sanic/pull/2044) コードクリーンアップ + とリファクタリングを行う - [#2072](https://github.com/sanic-org/sanic/pull/2072) Remove `BaseSanic` metaclass -- [#2074](https://github.com/sanic-org/sanic/pull/2074) Performance - adjustments in `handle_request_` +- [#2074](https://github.com/sanic-org/sanic/pull/2074) パフォーマンス + `handle_request_` の調整 -## Version 20.12.3 +## バージョン 20.12.3 -**Bugfixes** +**バグ修正** -- [#2021](https://github.com/sanic-org/sanic/pull/2021) Remove - prefix from websocket handler name +- [#2021](https://github.com/sanic-org/sanic/pull/2021) ウェブソケットハンドラ名から + プレフィックスを削除 -## Version 20.12.2 +## バージョン 20.12.2 -**Dependencies** +**依存** -- [#2026](https://github.com/sanic-org/sanic/pull/2026) Fix uvloop - to 0.14 because 0.15 drops Python 3.6 support -- [#2029](https://github.com/sanic-org/sanic/pull/2029) Remove old - chardet requirement, add in hard multidict requirement +- [#2026](https://github.com/sanic-org/sanic/pull/2026) uvloop + を0.15 は Python 3.6 のサポートをドロップするため0.14 に修正しました。 +- [#2029](https://github.com/sanic-org/sanic/pull/2029) 古い + チャード要件を削除し、ハードマルチディクト要件を追加 -## Version 19.12.5 +## バージョン 19.12.5 -**Dependencies** +**依存** -- [#2025](https://github.com/sanic-org/sanic/pull/2025) Fix uvloop - to 0.14 because 0.15 drops Python 3.6 support -- [#2027](https://github.com/sanic-org/sanic/pull/2027) Remove old - chardet requirement, add in hard multidict requirement +- [#2025](https://github.com/sanic-org/sanic/pull/2025) uvloop + を0.15 は Python 3.6 のサポートをドロップするため0.14 に修正 +- [#2027](https://github.com/sanic-org/sanic/pull/2027) 古い + チャード要件を削除し、ハードマルチディクト要件を追加 -## Version 20.12.0 +## バージョン 20.12.0 -**Features** +**機能** -- [#1993](https://github.com/sanic-org/sanic/pull/1993) Add disable - app registry -- [#1945](https://github.com/sanic-org/sanic/pull/1945) Static route - more verbose if file not found -- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static - routes registration on a blueprint -- [#1961](https://github.com/sanic-org/sanic/pull/1961) Add Python - 3.9 support +- [#1993](https://github.com/sanic-org/sanic/pull/1993) + アプリレジストリを無効にする +- [#1945](https://github.com/sanic-org/sanic/pull/1945) 静的ルート + より詳細なファイルが見つからない場合 +- [#1954](https://github.com/sanic-org/sanic/pull/1954)静的 + ルートのブループリントへの登録を修正する +- [#1961](https://github.com/sanic-org/sanic/pull/1961) Python + 3.9 のサポート - [#1962](https://github.com/sanic-org/sanic/pull/1962) Sanic CLI upgrade - [#1967](https://github.com/sanic-org/sanic/pull/1967) Update aiofile version requirements -- [#1969](https://github.com/sanic-org/sanic/pull/1969) Update - multidict version requirements -- [#1970](https://github.com/sanic-org/sanic/pull/1970) Add py.typed - file +- [#1969](https://github.com/sanic-org/sanic/pull/1969) + のバージョン要件 +- [#1970](https://github.com/sanic-org/sanic/pull/1970) py.typed + ファイルを追加 - [#1972](https://github.com/sanic-org/sanic/pull/1972) Speed optimization in request handler -- [#1979](https://github.com/sanic-org/sanic/pull/1979) Add app - registry and Sanic class level app retrieval +- [#1979](https://github.com/sanic-org/sanic/pull/1979) アプリ + レジストリとサニッククラスレベルのアプリ検索を追加 -**Bugfixes** +**バグ修正** -- [#1965](https://github.com/sanic-org/sanic/pull/1965) Fix Chunked - Transport-Encoding in ASGI streaming response +- [#1965](https://github.com/sanic-org/sanic/pull/1965) ASGIストリーミング応答でチャンクされた + トランスポートエンコード -**Deprecations and Removals** +**非推奨と削除** - [#1981](https://github.com/sanic-org/sanic/pull/1981) Cleanup and remove deprecated code -**Developer infrastructure** +**開発者のインフラストラクチャ** -- [#1956](https://github.com/sanic-org/sanic/pull/1956) Fix load - module test -- [#1973](https://github.com/sanic-org/sanic/pull/1973) Transition - Travis from .org to .com +- [#1956](https://github.com/sanic-org/sanic/pull/1956) load + モジュールテストを修正 +- [#1973](https://github.com/sanic-org/sanic/pull/1973) トランジション + Travisを.orgから.comへ。 - [#1986](https://github.com/sanic-org/sanic/pull/1986) Update tox requirements -**Improved Documentation** +**ドキュメントの改善** - [#1951](https://github.com/sanic-org/sanic/pull/1951) - Documentation improvements -- [#1983](https://github.com/sanic-org/sanic/pull/1983) Remove - duplicate contents in testing.rst -- [#1984](https://github.com/sanic-org/sanic/pull/1984) Fix typo in - routing.rst + ドキュメントの改善 +- [#1983](https://github.com/sanic-org/sanic/pull/1983) testing.rst で内容が重複する + を削除 +- [#1984](https://github.com/sanic-org/sanic/pull/1984) + routing.rst のtypoを修正 -## Version 20.9.1 +## バージョン 20.9.1 -**Bugfixes** +**バグ修正** -- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static - route registration on blueprints -- [#1957](https://github.com/sanic-org/sanic/pull/1957) Removes - duplicate headers in ASGI streaming body +- [#1954](https://github.com/sanic-org/sanic/pull/1954) 青写真の静的 + ルート登録を修正 +- [#1957](https://github.com/sanic-org/sanic/pull/1957) ASGI ストリーミングボディの + 重複ヘッダーを削除 -## Version 19.12.3 +## バージョン 19.12.3 -**Bugfixes** +**バグ修正** -- [#1959](https://github.com/sanic-org/sanic/pull/1959) Removes - duplicate headers in ASGI streaming body +- [#1959](https://github.com/sanic-org/sanic/pull/1959) ASGI ストリーミングボディの + 重複ヘッダーを削除 -## Version 20.9.0 +## バージョン 20.9.0 -**Features** +**機能** -- [#1887](https://github.com/sanic-org/sanic/pull/1887) Pass - subprotocols in websockets (both sanic server and ASGI) +- [#1887](https://github.com/sanic-org/sanic/pull/1887) WebSocketsの + サブプロトコルを渡します (両方のsanic serverとASGI)。 - [#1894](https://github.com/sanic-org/sanic/pull/1894) - Automatically set `test_mode` flag on app instance -- [#1903](https://github.com/sanic-org/sanic/pull/1903) Add new - unified method for updating app values + アプリインスタンスに `test_mode` フラグを自動的に設定 +- [#1903](https://github.com/sanic-org/sanic/pull/1903) アプリの値を更新するための新しい + ユニファイドメソッドを追加する - [#1906](https://github.com/sanic-org/sanic/pull/1906), - [#1909](https://github.com/sanic-org/sanic/pull/1909) Adds - WEBSOCKET_PING_TIMEOUT and WEBSOCKET_PING_INTERVAL configuration - values + [#1909](https://github.com/sanic-org/sanic/pull/1909) + WEBSOCKET_PING_TIMEOUTとWEBSOCKET_PING_INTERVAL 設定 + 値 - [#1935](https://github.com/sanic-org/sanic/pull/1935) httpx - version dependency updated, it is slated for removal as a - dependency in v20.12 -- [#1937](https://github.com/sanic-org/sanic/pull/1937) Added auto, - text, and json fallback error handlers (in v21.3, the default will - change form html to auto) + バージョンの依存関係が更新されました。v20.12 で + 依存関係が削除される予定です。 +- [#1937](https://github.com/sanic-org/sanic/pull/1937) auto、 + text、json fallback エラーハンドラを追加しました (v21.3では、デフォルトは + フォームの html を autoに変更します) -**Bugfixes** +**バグ修正** - [#1897](https://github.com/sanic-org/sanic/pull/1897) Resolves exception from unread bytes in stream -**Deprecations and Removals** +**非推奨と削除** - [#1903](https://github.com/sanic-org/sanic/pull/1903) - config.from_envar, config.from_pyfile, and config.from_object are - deprecated and set to be removed in v21.3 + config.from_envar, config.from_pyfile, config.from_object は + 非推奨であり、v21.3 で削除されるように設定されています。 -**Developer infrastructure** +**開発者のインフラストラクチャ** - [#1890](https://github.com/sanic-org/sanic/pull/1890), - [#1891](https://github.com/sanic-org/sanic/pull/1891) Update isort - calls to be compatible with new API -- [#1893](https://github.com/sanic-org/sanic/pull/1893) Remove - version section from setup.cfg -- [#1924](https://github.com/sanic-org/sanic/pull/1924) Adding - \--strict-markers for pytest + [#1891](https://github.com/sanic-org/sanic/pull/1891) isort + 呼び出しを新しいAPIと互換性があるように更新する +- [#1893](https://github.com/sanic-org/sanic/pull/1893) setup.cfg から + バージョンセクションを削除 +- [#1924](https://github.com/sanic-org/sanic/pull/1924) + \--strict-marker を pytest に追加する -**Improved Documentation** +**ドキュメントの改善** -- [#1922](https://github.com/sanic-org/sanic/pull/1922) Add explicit - ASGI compliance to the README +- [#1922](https://github.com/sanic-org/sanic/pull/1922) 明示的な + ASGI準拠をREADMEに追加する -## Version 20.6.3 +## バージョン 20.6.3 -**Bugfixes** +**バグ修正** - [#1884](https://github.com/sanic-org/sanic/pull/1884) Revert change to multiprocessing mode -## Version 20.6.2 +## バージョン 20.6.2 -**Features** +**機能** -- [#1641](https://github.com/sanic-org/sanic/pull/1641) Socket - binding implemented properly for IPv6 and UNIX sockets +- [#1641](https://github.com/sanic-org/sanic/pull/1641) IPv6 および UNIX ソケットに適切に実装された Socket + バインディング。 -## Version 20.6.1 +## バージョン 20.6.1 -**Features** +**機能** -- [#1760](https://github.com/sanic-org/sanic/pull/1760) Add version - parameter to websocket routes -- [#1866](https://github.com/sanic-org/sanic/pull/1866) Add `sanic` - as an entry point command -- [#1880](https://github.com/sanic-org/sanic/pull/1880) Add handler - names for websockets for url_for usage +- [#1760](https://github.com/sanic-org/sanic/pull/1760) ウェブソケットルートにバージョン + パラメータを追加する +- [#1866](https://github.com/sanic-org/sanic/pull/1866) エントリポイントコマンドとして `sanic` + を追加する +- [#1880](https://github.com/sanic-org/sanic/pull/1880) url_for usage 用ウェブソケットのハンドラ + 名を追加する -**Bugfixes** +**バグ修正** -- [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for - host parameter issue with lists +- [#1776](https://github.com/sanic-org/sanic/pull/1776) + ホストパラメータのリストに関するバグ修正 - [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static _handler pickling error -- [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader - on OSX py38 and Windows +- [#1827](https://github.com/sanic-org/sanic/pull/1827) OSX py38 と Windows のリローダー + を修正 - [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse named_response_middlware execution order, to match normal response middleware execution order -- [#1853](https://github.com/sanic-org/sanic/pull/1853) Fix pickle - error when attempting to pickle an application which contains - websocket routes +- [#1853](https://github.com/sanic-org/sanic/pull/1853) Pickle + エラーを修正 + websocket routes を含むアプリケーションをpickle しようとするとエラーが発生します -**Deprecations and Removals** +**非推奨と削除** -- [#1739](https://github.com/sanic-org/sanic/pull/1739) Deprecate - body_bytes to merge into body +- [#1739](https://github.com/sanic-org/sanic/pull/1739) + body_bytes を本体にマージする -**Developer infrastructure** +**開発者のインフラストラクチャ** -- [#1852](https://github.com/sanic-org/sanic/pull/1852) Fix naming - of CI test env on Python nightlies +- [#1852](https://github.com/sanic-org/sanic/pull/1852) PythonナイトリーのCI test envの + 命名を修正 - [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust websockets version to setup.py - [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap - run()'s "protocol" type annotation in Optional[] + run()の"protocol" 型アノテーションオプション[] -**Improved Documentation** +**ドキュメントの改善** -- [#1846](https://github.com/sanic-org/sanic/pull/1846) Update docs - to clarify response middleware execution order -- [#1865](https://github.com/sanic-org/sanic/pull/1865) Fixing rst - format issue that was hiding documentation +- [#1846](https://github.com/sanic-org/sanic/pull/1846) docs + を更新してミドルウェアの実行順序を明確にする +- [#1865](https://github.com/sanic-org/sanic/pull/1865) 文書を隠していたrst + フォーマットの問題を修正しました -## Version 20.6.0 +## バージョン 20.6.0 -_Released, but unintentionally omitting PR #1880, so was replaced by -20.6.1_ +_リリースされましたが、意図せずPR #1880を省略したため、 +20.6.1_ に置き換えられました -## Version 20.3.0 +## バージョン 20.3.0 -**Features** +**機能** -- [#1762](https://github.com/sanic-org/sanic/pull/1762) Add - `srv.start_serving()` and `srv.serve_forever()` to `AsyncioServer` -- [#1767](https://github.com/sanic-org/sanic/pull/1767) Make Sanic - usable on `hypercorn -k trio myweb.app` +- [#1762](https://github.com/sanic-org/sanic/pull/1762) + `srv.start_serving()` と `srv.serve_forever()` を `AsyncioServer` に追加します +- [#1767](https://github.com/sanic-org/sanic/pull/1767) `hypercorn -k trio myweb.app` で Sanic + を使えるようにする - [#1768](https://github.com/sanic-org/sanic/pull/1768) No tracebacks on normal errors and prettier error pages -- [#1769](https://github.com/sanic-org/sanic/pull/1769) Code cleanup - in file responses +- [#1769](https://github.com/sanic-org/sanic/pull/1769) ファイル応答のコードクリーンアップ - [#1793](https://github.com/sanic-org/sanic/pull/1793) and [#1819](https://github.com/sanic-org/sanic/pull/1819) Upgrade `str.format()` to f-strings -- [#1798](https://github.com/sanic-org/sanic/pull/1798) Allow - multiple workers on MacOS with Python 3.8 -- [#1820](https://github.com/sanic-org/sanic/pull/1820) Do not set - content-type and content-length headers in exceptions +- [#1798](https://github.com/sanic-org/sanic/pull/1798) + Python 3.8 を搭載した MacOS の複数のワーカーを許可する +- [#1820](https://github.com/sanic-org/sanic/pull/1820) + content-type と content-length ヘッダーを例外で設定しないでください。 -**Bugfixes** +**バグ修正** -- [#1748](https://github.com/sanic-org/sanic/pull/1748) Remove loop - argument in `asyncio.Event` in Python 3.8 -- [#1764](https://github.com/sanic-org/sanic/pull/1764) Allow route - decorators to stack up again +- [#1748](https://github.com/sanic-org/sanic/pull/1748) Python 3.8 の `asyncio.Event` の loop + 引数を削除します +- [#1764](https://github.com/sanic-org/sanic/pull/1764) ルート + デコレータが再びスタックできるようにする - [#1789](https://github.com/sanic-org/sanic/pull/1789) Fix tests using hosts yielding incorrect `url_for` -- [#1808](https://github.com/sanic-org/sanic/pull/1808) Fix Ctrl+C - and tests on Windows +- [#1808](https://github.com/sanic-org/sanic/pull/1808) Ctrl+C + とWindowsでのテスト -**Deprecations and Removals** +**非推奨と削除** - [#1800](https://github.com/sanic-org/sanic/pull/1800) Begin deprecation in way of first-class streaming, removal of @@ -1058,60 +1058,60 @@ _Released, but unintentionally omitting PR #1880, so was replaced by deprecation from [#1666](https://github.com/sanic-org/sanic/pull/1666) of dictionary context on `request` objects. -- [#1807](https://github.com/sanic-org/sanic/pull/1807) Remove - server config args that can be read directly from app +- [#1807](https://github.com/sanic-org/sanic/pull/1807) アプリから直接読み込むことのできる + サーバー設定の引数を削除する - [#1818](https://github.com/sanic-org/sanic/pull/1818) Complete deprecation of `app.remove_route` and `request.raw_args` -**Dependencies** +**依存** -- [#1794](https://github.com/sanic-org/sanic/pull/1794) Bump `httpx` - to 0.11.1 +- [#1794](https://github.com/sanic-org/sanic/pull/1794) `httpx` + を0.11.1 - [#1806](https://github.com/sanic-org/sanic/pull/1806) Import `ASGIDispatch` from top-level `httpx` (from third-party deprecation) -**Developer infrastructure** +**開発者のインフラストラクチャ** -- [#1833](https://github.com/sanic-org/sanic/pull/1833) Resolve - broken documentation builds +- [#1833](https://github.com/sanic-org/sanic/pull/1833) + 壊れたドキュメントのビルドを解決する -**Improved Documentation** +**ドキュメントの改善** -- [#1755](https://github.com/sanic-org/sanic/pull/1755) Usage of - `response.empty()` +- [#1755](https://github.com/sanic-org/sanic/pull/1755) + `response.empty()` の使用法 - [#1778](https://github.com/sanic-org/sanic/pull/1778) Update README - [#1783](https://github.com/sanic-org/sanic/pull/1783) Fix typo - [#1784](https://github.com/sanic-org/sanic/pull/1784) Corrected changelog for docs move of MD to RST ([#1691](https://github.com/sanic-org/sanic/pull/1691)) -- [#1803](https://github.com/sanic-org/sanic/pull/1803) Update - config docs to match DEFAULT_CONFIG -- [#1814](https://github.com/sanic-org/sanic/pull/1814) Update +- [#1803](https://github.com/sanic-org/sanic/pull/1803) + 設定ドキュメントをDEFAULT_CONFIGに一致させるように更新する +- [#1814](https://github.com/sanic-org/sanic/pull/1814) 更新 getting_started.rst - [#1821](https://github.com/sanic-org/sanic/pull/1821) Update to deployment -- [#1822](https://github.com/sanic-org/sanic/pull/1822) Update docs - with changes done in 20.3 -- [#1834](https://github.com/sanic-org/sanic/pull/1834) Order of - listeners +- [#1822](https://github.com/sanic-org/sanic/pull/1822) ドキュメント + を20.3で変更を加えて更新する +- [#1834](https://github.com/sanic-org/sanic/pull/1834) + リスナーの順序 -## Version 19.12.0 +## バージョン 19.12.0 -**Bugfixes** +**バグ修正** -- Fix blueprint middleware application +- ブループリントミドルウェアアプリケーションを修正 Currently, any blueprint middleware registered, irrespective of which blueprint was used to do so, was being applied to all of the routes created by the `@app` and `@blueprint` alike. - As part of this change, the blueprint based middleware application - is enforced based on where they are registered. + この変更の一環として、ブループリントベースのミドルウェアアプリケーション + は登録場所に基づいて施行されます。 - - If you register a middleware via `@blueprint.middleware` then it - will apply only to the routes defined by the blueprint. + - `@blueprint.middleware`を介してミドルウェアを登録する場合、 + はblueprintで定義されたルートにのみ適用されます。 - If you register a middleware via `@blueprint_group.middleware` then it will apply to all blueprint based routes that are part of the group. @@ -1119,7 +1119,7 @@ _Released, but unintentionally omitting PR #1880, so was replaced by applied on all available routes ([#37](https://github.com/sanic-org/sanic/issues/37)) -- Fix [url_for]{.title-ref} behavior with missing SERVER_NAME +- SERVER_NAME がない場合の [url_for]{.title-ref} の動作を修正 If the [SERVER_NAME]{.title-ref} was missing in the [app.config]{.title-ref} entity, the [url_for]{.title-ref} on the @@ -1129,79 +1129,80 @@ _Released, but unintentionally omitting PR #1880, so was replaced by optional behavior. ([#1707](https://github.com/sanic-org/sanic/issues/1707)) -**Improved Documentation** +**ドキュメントの改善** -- Move docs from MD to RST +- MDからRSTへドキュメントを移動 Moved all docs from markdown to restructured text like the rest of the docs to unify the scheme and make it easier in the future to update documentation. ([#1691](https://github.com/sanic-org/sanic/issues/1691)) -- Fix documentation for [get]{.title-ref} and [getlist]{.title-ref} of - the [request.args]{.title-ref} +- [get]{.title-ref} と [getlist]{.title-ref} の + [request.args]{.title-ref} のドキュメントを修正 - Add additional example for showing the usage of - [getlist]{.title-ref} and fix the documentation string for - [request.args]{.title-ref} behavior - ([#1704](https://github.com/sanic-org/sanic/issues/1704)) + ``` + [getlist]{.title-ref} の使用例を追加し、 + [request.args]{.title-ref} ビヘイビア + ([#1704](https://github.com/sanic-org/sanic/issues/1704)) のドキュメント文字列を修正します。 + ``` -## Version 19.6.3 +## バージョン 19.6.3 -**Features** +**機能** -- Enable Towncrier Support +- タウンクリエのサポートを有効にする - As part of this feature, [towncrier]{.title-ref} is being introduced - as a mechanism to partially automate the process of generating and - managing change logs as part of each of pull requests. + この機能の一環として、 [towncrier]{.title-ref} は、各プルリクエストの一部として、変更ログを生成するプロセスと + 管理するメカニズムとして、 + が導入されています。 ([#1631](https://github.com/sanic-org/sanic/issues/1631)) -**Improved Documentation** +**ドキュメントの改善** -- Documentation infrastructure changes +- ドキュメンテーションインフラストラクチャの変更 - Enable having a single common [CHANGELOG]{.title-ref} file for both GitHub page and documentation - - Fix Sphinix deprecation warnings - - Fix documentation warnings due to invalid [rst]{.title-ref} - indentation + - Sphinix非推奨の警告を修正 + - 無効な [rst]{.title-ref} + インデントによるドキュメント警告の修正 - Enable common contribution guidelines file across GitHub and documentation via [CONTRIBUTING.rst]{.title-ref} ([#1631](https://github.com/sanic-org/sanic/issues/1631)) -## Version 19.6.2 +## バージョン 19.6.2 -**Features** +**機能** - [#1562](https://github.com/sanic-org/sanic/pull/1562) Remove `aiohttp` dependency and create new `SanicTestClient` based upon [requests-async](https://github.com/encode/requests-async) -- [#1475](https://github.com/sanic-org/sanic/pull/1475) Added ASGI - support (Beta) +- [#1475](https://github.com/sanic-org/sanic/pull/1475) ASGI + サポートを追加しました (ベータ) - [#1436](https://github.com/sanic-org/sanic/pull/1436) Add Configure support from object string -**Bugfixes** +**バグ修正** -- [#1587](https://github.com/sanic-org/sanic/pull/1587) Add missing - handle for Expect header. +- [#1587](https://github.com/sanic-org/sanic/pull/1587) Expect ヘッダーの + ハンドルを追加します。 - [#1560](https://github.com/sanic-org/sanic/pull/1560) Allow to disable Transfer-Encoding: chunked. -- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix graceful - shutdown. +- [#1558](https://github.com/sanic-org/sanic/pull/1558) 優雅な + シャットダウンを修正。 - [#1594](https://github.com/sanic-org/sanic/pull/1594) Strict - Slashes behavior fix + スラッシュ動作修正 -**Deprecations and Removals** +**非推奨と削除** - [#1544](https://github.com/sanic-org/sanic/pull/1544) Drop dependency on distutil -- [#1562](https://github.com/sanic-org/sanic/pull/1562) Drop support - for Python 3.5 -- [#1568](https://github.com/sanic-org/sanic/pull/1568) Deprecate - route removal. +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Python 3.5 の + サポートを終了する +- [#1568](https://github.com/sanic-org/sanic/pull/1568) + のルート削除が非推奨です。 -.. warning:: Warning +.. 警告:: ``` Sanic will not support Python 3.5 from version 19.6 and forward. @@ -1210,83 +1211,83 @@ December 2020, and therefore passing Python\'s official support version 3.5, which is set to expire in September 2020. ``` -## Version 19.3 +## バージョン 19.3 -**Features** +**機能** - [#1497](https://github.com/sanic-org/sanic/pull/1497) Add support for zero-length and RFC 5987 encoded filename for multipart/form-data requests. -- [#1484](https://github.com/sanic-org/sanic/pull/1484) The type of - `expires` attribute of `sanic.cookies.Cookie` is now enforced to - be of type `datetime`. +- [#1484](https://github.com/sanic-org/sanic/pull/1484) `sanic.cookies.Cookie` の + `expires` 属性の型は `datetime` 型の + に適用されます。 - [#1482](https://github.com/sanic-org/sanic/pull/1482) Add support for the `stream` parameter of `sanic.Sanic.add_route()` available to `sanic.Blueprint.add_route()`. -- [#1481](https://github.com/sanic-org/sanic/pull/1481) Accept - negative values for route parameters with type `int` or `number`. +- [#1481](https://github.com/sanic-org/sanic/pull/1481) `int`または`number`型のルートパラメータの + 負の値を受け入れます。 - [#1476](https://github.com/sanic-org/sanic/pull/1476) Deprecated the use of `sanic.request.Request.raw_args` - it has a fundamental - flaw in which is drops repeated query string parameters. Added - `sanic.request.Request.query_args` as a replacement for the - original use-case. + flaw in which is drops repeated query string parameters. + `sanic.request.Request.query_args` が + 元のユースケースの置き換えとして追加されました。 -- [#1472](https://github.com/sanic-org/sanic/pull/1472) Remove an - unwanted `None` check in Request class `repr` implementation. This - changes the default `repr` of a Request from `` to - `` +- [#1472](https://github.com/sanic-org/sanic/pull/1472) Request class `repr` 実装の + 不要な `None` チェックを削除します。 この + は、``からリクエストのデフォルトの`repr`を + ``に変更します。 -- [#1470](https://github.com/sanic-org/sanic/pull/1470) Added 2 new - parameters to `sanic.app.Sanic.create_server`: +- [#1470](https://github.com/sanic-org/sanic/pull/1470) `sanic.app.create_server`に2つの新しい + パラメータを追加: - - `return_asyncio_server` - whether to return an - asyncio.Server. - - `asyncio_server_kwargs` - kwargs to pass to - `loop.create_server` for the event loop that sanic is using. + - `return_asyncio_server` - + asyncio.Serverを返すかどうか。 + - `asyncio_server_kwargs` - kwargs は、sanic が使用しているイベントループの + `loop.create_server` に渡します。 > - This is a breaking change. + これは、破損した変化です。 -- [#1499](https://github.com/sanic-org/sanic/pull/1499) Added a set - of test cases that test and benchmark route resolution. +- [#1499](https://github.com/sanic-org/sanic/pull/1499) ルート解像度をテストとベンチマークするテストケースのセット + を追加しました。 -- [#1457](https://github.com/sanic-org/sanic/pull/1457) The type of - the `"max-age"` value in a `sanic.cookies.Cookie` is now enforced - to be an integer. Non-integer values are replaced with `0`. +- [#1457](https://github.com/sanic-org/sanic/pull/1457) `sanic.cookies.Cookie` 内の `"max-age"`値の + 型が整数になるようになりました。 + 整数でない値は `0` に置き換えられます。 - [#1445](https://github.com/sanic-org/sanic/pull/1445) Added the `endpoint` attribute to an incoming `request`, containing the name of the handler function. -- [#1423](https://github.com/sanic-org/sanic/pull/1423) Improved - request streaming. `request.stream` is now a bounded-size buffer - instead of an unbounded queue. Callers must now call - `await request.stream.read()` instead of - `await request.stream.get()` to read each portion of the body. +- [#1423](https://github.com/sanic-org/sanic/pull/1423) + リクエストストリーミングを改善しました。 `request.stream` はバインドされていないキューの代わりに、バインドされたサイズのバッファ + になりました。 呼び出し側は + `await request.stream.get()` の代わりに + `await request.stream.read()` を呼び出し、本文の各部分を読み取る必要があります。 - This is a breaking change. + これは、破損した変化です。 -**Bugfixes** +**バグ修正** -- [#1502](https://github.com/sanic-org/sanic/pull/1502) Sanic was - prefetching `time.time()` and updating it once per second to avoid - excessive `time.time()` calls. The implementation was observed to - cause memory leaks in some cases. The benefit of the prefetch - appeared to negligible, so this has been removed. Fixes +- [#1502](https://github.com/sanic-org/sanic/pull/1502) Sanicは、 + `time.time()`の先頭に追加し、毎秒1回更新して、 + 過剰な`time.time()`の呼び出しを回避します。 実装が + に観察され、メモリリークが発生する場合がありました。 プリフェッチ + の利点は無視できるように見えたため、これが削除されました。 Fixes [#1500](https://github.com/sanic-org/sanic/pull/1500) - [#1501](https://github.com/sanic-org/sanic/pull/1501) Fix a bug in the auto-reloader when the process was launched as a module i.e. `python -m init0.mod1` where the sanic server is started in `init0/mod1.py` with `debug` enabled and imports another module in `init0`. -- [#1376](https://github.com/sanic-org/sanic/pull/1376) Allow sanic - test client to bind to a random port by specifying `port=None` - when constructing a `SanicTestClient` +- [#1376](https://github.com/sanic-org/sanic/pull/1376) `SanicTestClient` を構築する際に `port=None` + を指定することで、sanic + テストクライアントがランダムなポートにバインドできるようにします。 - [#1399](https://github.com/sanic-org/sanic/pull/1399) Added the ability to specify middleware on a blueprint group, so that all routes produced from the blueprints in the group have the @@ -1297,97 +1298,97 @@ December 2020, and therefore passing Python\'s official support version `app.run()`. This allows the access log to be disabled for example when running via gunicorn. -**Developer infrastructure** +**開発者のインフラストラクチャ** - [#1529](https://github.com/sanic-org/sanic/pull/1529) Update project PyPI credentials -- [#1515](https://github.com/sanic-org/sanic/pull/1515) fix linter - issue causing travis build failures (fix #1514) -- [#1490](https://github.com/sanic-org/sanic/pull/1490) Fix python - version in doc build -- [#1478](https://github.com/sanic-org/sanic/pull/1478) Upgrade - setuptools version and use native docutils in doc build -- [#1464](https://github.com/sanic-org/sanic/pull/1464) Upgrade - pytest, and fix caplog unit tests +- [#1515](https://github.com/sanic-org/sanic/pull/1515) linter + の問題を修正する (#1514を修正) +- [#1490](https://github.com/sanic-org/sanic/pull/1490) doc build で python + のバージョンを修正 +- [#1478](https://github.com/sanic-org/sanic/pull/1478) + setuptools のバージョンをアップグレードし、doc ビルドでネイティブの docutils を使用する +- [#1464](https://github.com/sanic-org/sanic/pull/1464) + pytestをアップグレードし、caplog 単体テストを修正する -**Improved Documentation** +**ドキュメントの改善** - [#1516](https://github.com/sanic-org/sanic/pull/1516) Fix typo at the exception documentation - [#1510](https://github.com/sanic-org/sanic/pull/1510) fix typo in Asyncio example - [#1486](https://github.com/sanic-org/sanic/pull/1486) - Documentation typo -- [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar - in README.md + ドキュメント typo +- [#1477](https://github.com/sanic-org/sanic/pull/1477) README.md で文法 + を修正 - [#1489](https://github.com/sanic-org/sanic/pull/1489) Added "databases" to the extensions list -- [#1483](https://github.com/sanic-org/sanic/pull/1483) Add - sanic-zipkin to extensions list -- [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link - to deleted repo, Sanic-OAuth, from the extensions list +- [#1483](https://github.com/sanic-org/sanic/pull/1483) 拡張リストに + sanic-zipkinを追加する +- [#1487](https://github.com/sanic-org/sanic/pull/1487) + リンクを削除しました。拡張機能リストからリポジトリ、Sanic-OAuthを削除しました。 - [#1460](https://github.com/sanic-org/sanic/pull/1460) 18.12 changelog -- [#1449](https://github.com/sanic-org/sanic/pull/1449) Add example - of amending request object +- [#1449](https://github.com/sanic-org/sanic/pull/1449) リクエストオブジェクトを修正する例 + を追加 - [#1446](https://github.com/sanic-org/sanic/pull/1446) Update README - [#1444](https://github.com/sanic-org/sanic/pull/1444) Update README -- [#1443](https://github.com/sanic-org/sanic/pull/1443) Update - README, including new logo -- [#1440](https://github.com/sanic-org/sanic/pull/1440) fix minor - type and pip install instruction mismatch +- [#1443](https://github.com/sanic-org/sanic/pull/1443) 新しいロゴを含む + READMEを更新 +- [#1440](https://github.com/sanic-org/sanic/pull/1440) マイナー + 型とpipインストール命令の不一致を修正 - [#1424](https://github.com/sanic-org/sanic/pull/1424) - Documentation Enhancements + ドキュメントの拡張 -Note: 19.3.0 was skipped for packagement purposes and not released on -PyPI +注: 19.3.0 はパッケージ化目的でスキップされ、 +PyPI ではリリースされません。 -## Version 18.12 +## バージョン 18.12 ### 18.12.0 -- Changes: +- 変更点: - - Improved codebase test coverage from 81% to 91%. + - コードベースのテストカバレッジが81named@@0に向上しました。 - Added stream_large_files and host examples in static_file document - Added methods to append and finish body content on Request (#1379) - - Integrated with .appveyor.yml for windows ci support - - Added documentation for AF_INET6 and AF_UNIX socket usage - - Adopt black/isort for codestyle - - Cancel task when connection_lost - - Simplify request ip and port retrieval logic - - Handle config error in load config file. - - Integrate with codecov for CI - - Add missed documentation for config section. - - Deprecate Handler.log - - Pinned httptools requirement to version 0.0.10+ - -- Fixes: - - - Fix `remove_entity_headers` helper function (#1415) + - windows ci サポート用 .appveyor.yml と統合されました + - AF_INET6 と AF_UNIX ソケットの使用に関するドキュメントを追加しました + - コードスタイルに黒/isortを採用 + - 接続失敗時にタスクをキャンセルする + - リクエストIPとポート取得ロジックを簡素化する + - load設定ファイルのconfigエラーを処理します。 + - CI用のcodecovと統合 + - 設定セクションに不足しているドキュメントを追加します。 + - Handler.log を非推奨にする + - バージョン 0.0.0.10 + の httptools 要件をピン留めしました + +- 修正: + + - `remove_entity_headers` ヘルパー関数を修正 (#1415) - Fix TypeError when use Blueprint.group() to group blueprint with default url_prefix, Use os.path.normpath to avoid invalid url_prefix like api//v1 f8a6af1 Rename the `http` module to `helpers` to prevent conflicts with the built-in Python http library (fixes #1323) - - Fix unittests on windows - - Fix Namespacing of sanic logger - - Fix missing quotes in decorator example - - Fix redirect with quoted param - - Fix doc for latest blueprint code - - Fix build of latex documentation relating to markdown lists - - Fix loop exception handling in app.py - - Fix content length mismatch in windows and other platform - - Fix Range header handling for static files (#1402) - - Fix the logger and make it work (#1397) - - Fix type pikcle->pickle in multiprocessing test - - Fix pickling blueprints Change the string passed in the - "name" section of the namedtuples in Blueprint to match the - name of the Blueprint module attribute name. This allows + - WindowsのUnittestsを修正 + - 健全なロガーの名前空間を修正 + - デコレータの例で不足している引用符を修正 + - 引用符で囲まれたパラメータでリダイレクトを修正 + - 最新の建設計画コードのドキュメントを修正します。 + - マークダウンリストに関するラテックス文書の構築を修正 + - app.pyでループ例外処理を修正 + - Windowsや他のプラットフォームでコンテンツの長さが一致しない問題を修正 + - 固定ファイルの範囲ヘッダーの処理を修正 (#1402) + - ロガーを修正して動作させます(#1397) + - マルチプロセッシングテストでpikcle->pickle型を修正 + - ブループリント内の名前付きタプルの + "name" セクションで渡された文字列をブループリントモジュール属性名の + 名に合わせて変更します。 This allows blueprints to be pickled and unpickled, without errors, which is a requirement of running Sanic in multiprocessing mode in Windows. Added a test for pickling and unpickling blueprints @@ -1395,137 +1396,137 @@ PyPI test for enabling multiprocessing on an app with a blueprint (only useful to catch this bug if the tests are run on Windows). - - Fix document for logging + - ログのドキュメントを修正 -## Version 0.8 +## バージョン 0.8 **0.8.3** -- Changes: - - Ownership changed to org 'sanic-org' +- 変更点: + - 所有権を組織に変更しました 'sanic-org' **0.8.0** -- Changes: - - Add Server-Sent Events extension (Innokenty Lebedev) - - Graceful handling of request_handler_task cancellation (Ashley +- 変更点: + - サーバー送信済みイベント拡張を追加 (Innokenty Lebedev) + - request_handler_task キャンセルの優美な処理 (Ashley Sommer) - - Sanitize URL before redirection (aveao) - - Add url_bytes to request (johndoe46) - - py37 support for travisci (yunstanford) - - Auto reloader support for OSX (garyo) - - Add UUID route support (Volodymyr Maksymiv) - - Add pausable response streams (Ashley Sommer) - - Add weakref to request slots (vopankov) - - remove ubuntu 12.04 from test fixture due to deprecation - (yunstanford) - - Allow streaming handlers in add_route (kinware) - - use travis_retry for tox (Raphael Deem) - - update aiohttp version for test client (yunstanford) - - add redirect import for clarity (yingshaoxo) - - Update HTTP Entity headers (Arnulfo Solís) - - Add register_listener method (Stephan Fitzpatrick) - - Remove uvloop/ujson dependencies for Windows (abuckenheimer) - - Content-length header on 204/304 responses (Arnulfo Solís) - - Extend WebSocketProtocol arguments and add docs (Bob Olde + - リダイレクト前の URL をサニタイズします（保存） + - リクエストに url_bytes を追加 (johndoe46) + - py37 は travisci (ユンスタンフォード) のサポート + - OSX (garyo) への自動リローダーのサポート + - UUID ルートサポートを追加 (Volodymyr Maksymiv) + - 一時停止可能な応答ストリームを追加 (Ashley Sommer) + - スロットを要求するために弱点を追加する (vopankov) + - 廃止予定の + (yunstanford) のためにテストフィクスチャーから ubuntu 12.04 を削除します + - add_route (kinware) でストリーミングハンドラを許可する + - tox(Raphael Deem)にtravis_retryを使う + - テストクライアント用の aiohttp バージョンの更新 (yunstanford) + - 明瞭度のためのリダイレクトインポートを追加 (yingshaoxo) + - HTTP エンティティヘッダーを更新 (Arnulfo Soli's) + - register_listenerメソッドを追加 (Stephan Fitzpatrick) + - Windows用のuvloop/ujson依存関係の削除 (abuckenheimer) + - Content-length header on 204/304 responses (Arnulfo Soli's) + - WebSocketProtocol引数の拡張とドキュメントの追加 (Bob Olde Hampsink, yunstanford) - - Update development status from pre-alpha to beta (Maksim + - アルファ前からベータ版への開発状況を更新 (Maksim Anisenkov) - - KeepAlive Timeout log level changed to debug (Arnulfo Solís) - - Pin pytest to 3.3.2 because of pytest-dev/pytest#3170 (Maksim - Aniskenov) - - Install Python 3.5 and 3.6 on docker container for tests (Shahin + - KeepAlive タイムアウトのログレベルがデバッグに変更されました (Arnulfo Soli's) + - pytest-dev/pytest#3170 (Maksim + Aniskenov) により pytest を3.3.2 にピンします + - テスト用のdocker container に Python 3.5 と 3.6 をインストールします (Shahin Azad) - - Add support for blueprint groups and nesting (Elias Tarhini) - - Remove uvloop for windows setup (Aleksandr Kurlov) + - 建設計画グループとネスト（Alias Tarhini）のサポートを追加する + - Windows用のuvloopを削除します(Aleksandr Kurlov) - Auto Reload (Yaser Amari) - - Documentation updates/fixups (multiple contributors) -- Fixes: - - Fix: auto_reload in Linux (Ashley Sommer) - - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) - - Fix: disable auto_reload by default on windows (abuckenheimer) - - Fix (1143): Turn off access log with gunicorn (hqy) - - Fix (1268): Support status code for file response (Cosmo Borsky) - - Fix (1266): Add content_type flag to Sanic.static (Cosmo Borsky) - - Fix: subprotocols parameter missing from add_websocket_route - (ciscorn) - - Fix (1242): Responses for CI header (yunstanford) - - Fix (1237): add version constraint for websockets (yunstanford) - - Fix (1231): memory leak - always release resource (Phillip Xu) - - Fix (1221): make request truthy if transport exists (Raphael + - ドキュメントの更新/修正 (複数の投稿者) +- 修正: + - 修正: Linux で auto_reload (Ashley Sommer) + - 修正:aiohttp >= 3.3.0 (Ashley Sommer) + - 修正: windows ではデフォルトで auto_reload を無効にする (abuckenheimer) + - 修正 (1143): gunicorn (hqy) でアクセスログをオフにする + - Fix (1268): ファイル応答のステータスコードをサポート (Cosmo Borsky) + - Fix (1266): Sanic.static (Cosmo Borsky) にcontent_type フラグを追加 + - 修正: add_websocket_route + (ciscorn) からサブプロトコルパラメータがありません + - Fix (1242): CI ヘッダーのレスポンス (yunstanford) + - Fix (1237): websockets (yunstanford) のバージョン制約を追加 + - 修正 (1231): メモリリーク - 常にリソースをリリース (フィリップXu) + - Fix (1221): トランスポートが存在する場合はリクエストを真にする (Raphael Deem) - - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) - - Fix try_everything examples (PyManiacGR, kot83) - - Fix (1158): default to auto_reload in debug mode (Raphael Deem) - - Fix (1136): ErrorHandler.response handler call too restrictive + - aiohttp>=3.1.0（Ashley Sommer）のテストに失敗する問題を修正 + - try_everything の例を修正 (PyManiacGR, kot83) + - Fix (1158): デバッグモードで auto_reload がデフォルト(Raphel Deem) + - Fix (11136): ErrorHandler.response ハンドラの呼び出しが制限されています (Julien Castiaux) - - Fix: raw requires bytes-like object (cloudship) + - 修正: raw requires bytes-like object (cloudship) - Fix (1120): passing a list in to a route decorator's host arg (Timothy Ebiuwhe) - - Fix: Bug in multipart/form-data parser (DirkGuijt) + - 修正: マルチパート/フォームデータパーサのバグ(DirkGuijt) - Fix: Exception for missing parameter when value is null (NyanKiyoshi) - - Fix: Parameter check (Howie Hu) - - Fix (1089): Routing issue with named parameters and different - methods (yunstanford) - - Fix (1085): Signal handling in multi-worker mode (yunstanford) - - Fix: single quote in readme.rst (Cosven) - - Fix: method typos (Dmitry Dygalo) - - Fix: log_response correct output for ip and port (Wibowo + - 修正:パラメータチェック(Howie Hu) + - Fix (1089): 名前付きパラメータと異なる + メソッドでルーティングの問題 (yunstanford) + - Fix (1085): マルチワーカーモードでの信号処理 (yunstanford) + - 修正: readme.rst (Cosven) のシングルクォート + - 修正: メソッドの誤植(Dmitry Dygalo) + - Fix: ipとポートのlog_response正しい出力 (Wiboo Arindrarto) - - Fix (1042): Exception Handling (Raphael Deem) - - Fix: Chinese URIs (Howie Hu) - - Fix (1079): timeout bug when self.transport is None (Raphael - Deem) - - Fix (1074): fix strict_slashes when route has slash (Raphael + - 修正 (1042): 例外処理 (Raphael Deem) + - 修正:中国語URI (Howie Hu) + - Fix (1079): self.transportが None の場合のタイムアウトバグ (Raphael Deem) - - Fix (1050): add samesite cookie to cookie keys (Raphael Deem) - - Fix (1065): allow add_task after server starts (Raphael Deem) - - Fix (1061): double quotes in unauthorized exception (Raphael + - Fix (1074): route has slash (Raphael + Deem) がスラッシュの場合の strict_slash の修正 + - Fix (1050): Cookie キーに samesite Cookie を追加する (Raphel Deem) + - 修正 (1065): サーバ起動後に add_task を許可する (Raphael Deem) + - 修正 (1061): 許可されていない例外のダブルクォート (Raphael Deem) - - Fix (1062): inject the app in add_task method (Raphael Deem) + - 修正 (1062): add_task メソッドに アプリを注入する (Raphael Deem) - Fix: update environment.yml for readthedocs (Eli Uriegas) - Fix: Cancel request task when response timeout is triggered (Jeong YunWon) - Fix (1052): Method not allowed response for RFC7231 compliance (Raphael Deem) - - Fix: IPv6 Address and Socket Data Format (Dan Palmer) + - 修正:IPv6 アドレスとソケットデータフォーマット(ダン・パーマー) -Note: Changelog was unmaintained between 0.1 and 0.7 +注: 更新履歴は0.1から0.7の間は維持されませんでした -## Version 0.1 +## バージョン 0.1 **0.1.7** -- Reversed static url and directory arguments to meet spec +- 仕様を満たすために静的URLとディレクトリ引数を逆にしました **0.1.6** -- Static files -- Lazy Cookie Loading +- 静的ファイル +- 遅延クッキーの読み込み中 **0.1.5** -- Cookies -- Blueprint listeners and ordering -- Faster Router -- Fix: Incomplete file reads on medium+ sized post requests +- Cookie +- 設計図のリスナーと注文 +- より速いルータを使用する +- 修正:不完全なファイルは、中程度の大きさのポストリクエストで読み込まれます - Breaking: after_start and before_stop now pass sanic as their first argument **0.1.4** -- Multiprocessing +- マルチ処理 **0.1.3** -- Blueprint support -- Faster Response processing +- ブループリントのサポート +- 迅速な応答処理 **0.1.1 - 0.1.2** -- Struggling to update pypi via CI +- CI経由でピピを更新するのに苦労しています **0.1.0** -- Released to public +- 公開 From a681c96ebfac2dabb0b0ea646e3ffcbaf7c7321b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 10:23:40 +0200 Subject: [PATCH 458/698] New translations changelog.md (Chinese Simplified) --- guide/content/zh/release-notes/changelog.md | 2025 +++++++++---------- 1 file changed, 1010 insertions(+), 1015 deletions(-) diff --git a/guide/content/zh/release-notes/changelog.md b/guide/content/zh/release-notes/changelog.md index b98df20c9e..99d70b726c 100644 --- a/guide/content/zh/release-notes/changelog.md +++ b/guide/content/zh/release-notes/changelog.md @@ -1,559 +1,559 @@ --- -content_class: changelog +content_class: 更新日志 --- -# Changelog +# 更新日志 -🔶 Current release\ -🔷 In support LTS release +:larg_orange_diamond: Current release\ +:larg_blu_diamond: In support LTS release -## Version 23.12.0 🔶🔷 +## 版本23.12.0 :larg_orange_diamond::larg_blu_diamond: -_Current version_ +_当前版本_ -### Features +### 功能 -- [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes -- [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown -- [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket -- [#2822](https://github.com/sanic-org/sanic/pull/2822) Listener and signal prioritization -- [#2831](https://github.com/sanic-org/sanic/pull/2831) Reduce memory consumption -- [#2837](https://github.com/sanic-org/sanic/pull/2837) Accept bare cookies -- [#2841](https://github.com/sanic-org/sanic/pull/2841) Add `websocket.handler.` signals -- [#2805](https://github.com/sanic-org/sanic/pull/2805) Add changed files to reload trigger listeners -- [#2813](https://github.com/sanic-org/sanic/pull/2813) Allow for simple signals -- [#2827](https://github.com/sanic-org/sanic/pull/2827) Improve functionality and consistency of `Sanic.event()` -- [#2851](https://github.com/sanic-org/sanic/pull/2851) Allow range requests for a single byte -- [#2854](https://github.com/sanic-org/sanic/pull/2854) Better `Request.scheme` for websocket requests -- [#2858](https://github.com/sanic-org/sanic/pull/2858) Convert Sanic `Request` to a Websockets `Request` for handshake -- [#2859](https://github.com/sanic-org/sanic/pull/2859) Add a REPL to the `sanic` CLI -- [#2870](https://github.com/sanic-org/sanic/pull/2870) Add Python 3.12 support -- [#2875](https://github.com/sanic-org/sanic/pull/2875) Better exception on multiprocessing context conflicts +- [#2775](https://github.com/sanic-org/sanic/pull/2775) 开始并重启任意进程 +- [#2811](https://github.com/sanic-org/sanic/pull/2811) +- [#2812](https://github.com/sanic-org/sanic/pull/2812) 禁止任务在打开websocket上取消跟踪 +- [#2822](https://github.com/sanic-org/sanic/pull/2822) 侦听器和信号优先级 +- [#2831](https://github.com/sanic-org/sanic/pull/2831) 减少内存消耗量 +- [#2837](https://github.com/sanic-org/sanic/pull/2837) 接受最佳cookies +- [#2841](https://github.com/sanic-org/sanic/pull/2841) 添加 \`websocket.handler.\" 信号 +- [#2805](https://github.com/sanic-org/sanic/pull/2805) 添加更改的文件以重新载入触发监听器 +- [#2813](https://github.com/sanic-org/sanic/pull/2813) 允许提供简单的信号 +- [#2827](https://github.com/sanic-org/sanic/pull/2827) 改进`Sanic.event()`的功能和一致性 +- [#2851](https://github.com/sanic-org/sanic/pull/2851) 允许范围请求单个字节 +- [#2854](https://github.com/sanic-org/sanic/pull/2854) 为web套接字请求更好地`Request.scheme` +- [#2858](https://github.com/sanic-org/sanic/pull/2858) 将Sanic `Request` 转换为Websockets `Request` 来握手 +- [#2859](https://github.com/sanic-org/sanic/pull/2859) 在 `sanic` CLI 中添加一个 REPL +- [#2870](https://github.com/sanic-org/sanic/pull/2870) 添加 Python 3.12 支持 +- [#2875](https://github.com/sanic-org/sanic/pull/2875) 在多处理环境冲突中更好的例外 -### Bugfixes +### 错误修正 -- [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data +- [#2803](https://github.com/sanic-org/sanic/pull/2803) 修复MOTD显示额外数据 -### Deprecations and Removals +### 废弃和移除 -### Developer infrastructure +### 开发者基础设施 -- [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases -- [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU -- [#2807](https://github.com/sanic-org/sanic/pull/2807) Add constraint for autodocsum (lint issue in old package version) -- [#2808](https://github.com/sanic-org/sanic/pull/2808) Refactor GitHub Actions -- [#2814](https://github.com/sanic-org/sanic/pull/2814) Run CI pipeline on git push -- [#2846](https://github.com/sanic-org/sanic/pull/2846) Drop old performance tests/benchmarks -- [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile cleanup +- [#2796](https://github.com/sanic-org/sanic/pull/2796) 重新计算单位测试案件 +- [#2801](https://github.com/sanic-org/sanic/pull/2801) 在只有一个 CPU 时修复`test_fast` +- [#2807](https://github.com/sanic-org/sanic/pull/2807) 添加自动文档的约束 (旧软件包版本中的行号) +- [#2808](https://github.com/sanic-org/sanic/pull/2808) Reface GitHub Actions +- [#2814](https://github.com/sanic-org/sanic/pull/2814) 在 git 推送时运行CI 管道上 +- [#2846](https://github.com/sanic-org/sanic/pull/2846) 删除旧的性能测试/基准 +- [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile 清理 - [#2865](https://github.com/sanic-org/sanic/pull/2865) [#2869](https://github.com/sanic-org/sanic/pull/2869) [#2872](https://github.com/sanic-org/sanic/pull/2872) [#2879](https://github.com/sanic-org/sanic/pull/2879) - Add ruff to toolchain -- [#2866](https://github.com/sanic-org/sanic/pull/2866) Fix the alt svc test to run locally with explicit buffer nbytes -- [#2877](https://github.com/sanic-org/sanic/pull/2877) Use Python's trusted publisher in deployments -- [#2882](https://github.com/sanic-org/sanic/pull/2882) Introduce dynamic port fixture in targeted locations in the test suite + 添加ruff到工具链中 +- [#2866](https://github.com/sanic-org/sanic/pull/2866) 修复alt svc 测试以便在本地使用显式缓存nbytes +- [#2877](https://github.com/sanic-org/sanic/pull/2877) 在部署中使用Python可信的出版商 +- [#2882](https://github.com/sanic-org/sanic/pull/2882) 在测试套装中引入目标位置的动态端口灯具 -### Improved Documentation +### 改进文档 - [#2781](https://github.com/sanic-org/sanic/pull/2781) [#2821](https://github.com/sanic-org/sanic/pull/2821) [#2861](https://github.com/sanic-org/sanic/pull/2861) [#2863](https://github.com/sanic-org/sanic/pull/2863) - Conversion of User Guide to the SHH (Sanic, html5tagger, HTMX) stack -- [#2810](https://github.com/sanic-org/sanic/pull/2810) Update README -- [#2855](https://github.com/sanic-org/sanic/pull/2855) Edit Discord badge -- [#2864](https://github.com/sanic-org/sanic/pull/2864) Adjust documentation for using state properties within http/https redirection document + 用户指南转换为 SHH (Sanic, html5tagger, HTMX) +- [#2810](https://github.com/sanic-org/sanic/pull/2810) 更新README +- [#2855](https://github.com/sanic-org/sanic/pull/2855) 编辑Discord 徽章 +- [#2864](https://github.com/sanic-org/sanic/pull/2864) 调整文档使用状态属性在 http/https 重定向文档 -## Version 23.9.0 +## 版本23.9.0 -_Due to circumstances at the time, v.23.9 was skipped._ +_由于当时的情况，v.23.9已经跳过。 -## Version 23.6.0 +## 版本 23.6.0 -### Features +### 功能 -- [#2670](https://github.com/sanic-org/sanic/pull/2670) Increase `KEEP_ALIVE_TIMEOUT` default to 120 seconds -- [#2716](https://github.com/sanic-org/sanic/pull/2716) Adding allow route overwrite option in blueprint -- [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792) Add a new exception signal for ALL exceptions raised anywhere in application -- [#2727](https://github.com/sanic-org/sanic/pull/2727) Add name prefixing to BP groups -- [#2754](https://github.com/sanic-org/sanic/pull/2754) Update request type on middleware types -- [#2770](https://github.com/sanic-org/sanic/pull/2770) Better exception message on startup time application induced import error -- [#2776](https://github.com/sanic-org/sanic/pull/2776) Set multiprocessing start method early -- [#2785](https://github.com/sanic-org/sanic/pull/2785) Add custom typing to config and ctx objects -- [#2790](https://github.com/sanic-org/sanic/pull/2790) Add `request.client_ip` +- [#2670](https://github.com/sanic-org/sanic/pull/2670) 增加`KEEP_ALIVE_TIMEOUT` 默认为120秒 +- [#2716](https://github.com/sanic-org/sanic/pull/2716) 在蓝图中添加允许路由覆盖选项 +- [#2724](https://github.com/sanic-org/sanic/pull/2724)和[#2792](https://github.com/sanic-org/sanic/pull/2792) 为应用中任何地方提出的所有例外添加一个新的异常信号。 +- [#2727](https://github.com/sanic-org/sanic/pull/2727) 为BP组添加名称前缀 +- [#2754](https://github.com/sanic-org/sanic/pull/2754) 更新中间件类型的请求类型 +- [#2770](https://github.com/sanic-org/sanic/pull/2770) 启动时间应用程序引发导入错误时更好的异常消息 +- [#2776](https://github.com/sanic-org/sanic/pull/2776) 设置多处理开始方法 +- [#2785](https://github.com/sanic-org/sanic/pull/2785) 添加自定义键入配置和 ctx 对象 +- [#2790](https://github.com/sanic-org/sanic/pull/2790) 添加`request.client_ip` -### Bugfixes +### 错误修正 -- [#2728](https://github.com/sanic-org/sanic/pull/2728) Fix traversals for intended results -- [#2729](https://github.com/sanic-org/sanic/pull/2729) Handle case when headers argument of ResponseStream constructor is None -- [#2737](https://github.com/sanic-org/sanic/pull/2737) Fix type annotation for `JSONREsponse` default content type -- [#2740](https://github.com/sanic-org/sanic/pull/2740) Use Sanic's serializer for JSON responses in the Inspector -- [#2760](https://github.com/sanic-org/sanic/pull/2760) Support for `Request.get_current` in ASGI mode -- [#2773](https://github.com/sanic-org/sanic/pull/2773) Alow Blueprint routes to explicitly define error_format -- [#2774](https://github.com/sanic-org/sanic/pull/2774) Resolve headers on different renderers -- [#2782](https://github.com/sanic-org/sanic/pull/2782) Resolve pypy compatibility issues +- [#2728](https://github.com/sanic-org/sanic/pull/2728) 修复预定结果 +- [#2729](https://github.com/sanic-org/sanic/pull/2729) +- [#2737](https://github.com/sanic-org/sanic/pull/2737) 修复`JSONREspone`默认内容类型的注解 +- [#2740](https://github.com/sanic-org/sanic/pull/2740) 在检查员中使用 Sanic的序列化器为 JSON 响应 +- [#2760](https://github.com/sanic-org/sanic/pull/2760) 在 ASGI 模式中支持 `Request.get_current` +- [#2773](https://github.com/sanic-org/sanic/pull/2773) 蓝图路由，明确定义错误格式 +- [#2774](https://github.com/sanic-org/sanic/pull/2774) 解析不同渲染器的标题 +- [#2782](https://github.com/sanic-org/sanic/pull/2782) 解决pypy 兼容性问题 -### Deprecations and Removals +### 废弃和移除 -- [#2777](https://github.com/sanic-org/sanic/pull/2777) Remove Python 3.7 support +- [#2777](https://github.com/sanic-org/sanic/pull/2777) 移除 Python 3.7 支持 -### Developer infrastructure +### 开发者基础设施 -- [#2766](https://github.com/sanic-org/sanic/pull/2766) Unpin setuptools version -- [#2779](https://github.com/sanic-org/sanic/pull/2779) Run keep alive tests in loop to get available port +- [#2766](https://github.com/sanic-org/sanic/pull/2766) 解压设置工具版本 +- [#2779](https://github.com/sanic-org/sanic/pull/2779) 运行在循环中进行活化测试以获取端口。 -### Improved Documentation +### 改进文档 -- [#2741](https://github.com/sanic-org/sanic/pull/2741) Better documentation examples about running Sanic - From that list, the items to highlight in the release notes: +- [#2741](https://github.com/sanic-org/sanic/pull/2741) 更好的文档实例来运行 Sanic + 从该列表中，要在发行说明中高亮显示的内容： -## Version 23.3.0 +## 版本23.3.0 -### Features +### 功能 -- [#2545](https://github.com/sanic-org/sanic/pull/2545) Standardize init of exceptions for more consistent control of HTTP responses using exceptions -- [#2606](https://github.com/sanic-org/sanic/pull/2606) Decode headers as UTF-8 also in ASGI -- [#2646](https://github.com/sanic-org/sanic/pull/2646) Separate ASGI request and lifespan callables -- [#2659](https://github.com/sanic-org/sanic/pull/2659) Use `FALLBACK_ERROR_FORMAT` for handlers that return `empty()` -- [#2662](https://github.com/sanic-org/sanic/pull/2662) Add basic file browser (HTML page) and auto-index serving -- [#2667](https://github.com/sanic-org/sanic/pull/2667) Nicer traceback formatting (HTML page) -- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter error page rendering format selection; more reliant upon header and "common sense" defaults -- [#2680](https://github.com/sanic-org/sanic/pull/2680) Check the status of socket before shutting down with `SHUT_RDWR` -- [#2687](https://github.com/sanic-org/sanic/pull/2687) Refresh `Request.accept` functionality to be more performant and spec-compliant -- [#2696](https://github.com/sanic-org/sanic/pull/2696) Add header accessors as properties +- [#2545](https://github.com/sanic-org/sanic/pull/2545) +- [#2606](https://github.com/sanic-org/sanic/pull/2606) 也在 ASGI 中解码头为 UTF-8 +- [#2646](https://github.com/sanic-org/sanic/pull/2646) 单独的 ASGI 请求和有效期彩信 +- [#2659](https://github.com/sanic-org/sanic/pull/2659) 使用 `FALLBACK_ERROR_FORMAT` 返回的 `empty()` +- [#2662](https://github.com/sanic-org/sanic/pull/262) 添加基本文件浏览器 (HTML页面) 和自动索引服务 +- [#2667](https://github.com/sanic-org/sanic/pull/2667) 较强的追踪格式化(HTML页面) +- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter 错误页面渲染格式选择；更多依赖于头部和“常识”默认值 +- [#2680](https://github.com/sanic-org/sanic/pull/2680) 在使用 `SHUT_RDWR` 关闭之前检查套接字的状态 +- [#2687](https://github.com/sanic-org/sanic/pull/267) 刷新`Request.accept` 功能，使其更加性能和符合观光。 +- [#2696](https://github.com/sanic-org/sanic/pull/2696) 添加标题访问器作为属性 ``` - Example-Field: Foo, Bar - Example-Field: Baz + 示例字段: Foo, Bar + 示例字段: Baz ``` ```python - request.headers.example_field == "Foo, Bar,Baz" + headers.example_field ="Foo, Bar,Baz" ``` -- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simpler CLI targets +- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simple CLI 目标 ```sh - $ sanic path.to.module:app # global app instance - $ sanic path.to.module:create_app # factory pattern - $ sanic ./path/to/directory/ # simple serve + $ sanic path.to.module:app # 全局应用实例 + $ sanic path.to.module:create_app # 出厂模式 + sanic ./path/to/directory/ # 简单服务 ``` -- [#2701](https://github.com/sanic-org/sanic/pull/2701) API to define a number of workers in managed processes -- [#2704](https://github.com/sanic-org/sanic/pull/2704) Add convenience for dynamic changes to routing -- [#2706](https://github.com/sanic-org/sanic/pull/2706) Add convenience methods for cookie creation and deletion +- [#2701](https://github.com/sanic-org/sanic/pull/2701) API 来定义管理过程中的一些工人 +- [#2704](https://github.com/sanic-org/sanic/pull/2704) 添加动态更改路由的便利。 +- [#2706](https://github.com/sanic-org/sanic/pull/2706) 为cookie的创建和删除添加便利方法 ```python response = text("...") - response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com") + response.add_cookie("test", "it work!", domain=".yummy-yummy-cookie.com") ``` -- [#2707](https://github.com/sanic-org/sanic/pull/2707) Simplified `parse_content_header` escaping to be RFC-compliant and remove outdated FF hack -- [#2710](https://github.com/sanic-org/sanic/pull/2710) Stricter charset handling and escaping of request URLs -- [#2711](https://github.com/sanic-org/sanic/pull/2711) Consume body on `DELETE` by default -- [#2719](https://github.com/sanic-org/sanic/pull/2719) Allow `password` to be passed to TLS context -- [#2720](https://github.com/sanic-org/sanic/pull/2720) Skip middleware on `RequestCancelled` -- [#2721](https://github.com/sanic-org/sanic/pull/2721) Change access logging format to `%s` -- [#2722](https://github.com/sanic-org/sanic/pull/2722) Add `CertLoader` as application option for directly controlling `SSLContext` objects -- [#2725](https://github.com/sanic-org/sanic/pull/2725) Worker sync state tolerance on race condition +- [#2707](https://github.com/sanic-org/sanic/pull/2707) 简化的 `parse_content_header` 逃避与 RFC 兼容并移除过时的 FF 哈克 +- [#2710](https://github.com/sanic-org/sanic/pull/2710) +- [#2711](https://github.com/sanic-org/sanic/pull/2711) 默认使用 `DELETE` 上 +- [#2719](https://github.com/sanic-org/sanic/pull/2719) 允许 `password` 传入TLS 环境 +- [#2720](https://github.com/sanic-org/sanic/pull/2720) 在 `RequestCancelled` 上跳过中间件 +- [#2721](https://github.com/sanic-org/sanic/pull/2721) 将访问日志格式更改为`%s` +- [#2722](https://github.com/sanic-org/sanic/pull/2722) 添加 `CertLoader` 作为直接控制 `SSLContext` 对象的应用程序选项 +- [#2725](https://github.com/sanic-org/sanic/pull/2725) 工人在种族条件下同步状态容忍度 -### Bugfixes +### 错误修正 -- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket to pass thru bytes as is -- [#2697](https://github.com/sanic-org/sanic/pull/2697) Fix comparison between datetime aware and naive in `file` when using `If-Modified-Since` +- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket 来传递节点像是 +- [#2697](https://github.com/sanic-org/sanic/pull/2697) 使用 `If-Modified-Since` 时修复日期时间和天真之间的比较 -### Deprecations and Removals +### 废弃和移除 - [#2666](https://github.com/sanic-org/sanic/pull/2666) Remove deprecated `__blueprintname__` property -### Improved Documentation +### 改进文档 -- [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect +- [#2712](https://github.com/sanic-org/sanic/pull/2712) 通过使用 \`\`'https\://github.com/sanic/pull/2712改进的示例来创建重定向 -## Version 22.12.0 🔷 +## 版本22.12.0 :larg_blu_diamond: -_Current LTS version_ +_当前LTS版本_ -### Features +### 功能 -- [#2569](https://github.com/sanic-org/sanic/pull/2569) Add `JSONResponse` class with some convenient methods when updating a response object -- [#2598](https://github.com/sanic-org/sanic/pull/2598) Change `uvloop` requirement to `>=0.15.0` -- [#2609](https://github.com/sanic-org/sanic/pull/2609) Add compatibility with `websockets` v11.0 -- [#2610](https://github.com/sanic-org/sanic/pull/2610) Kill server early on worker error - - Raise deadlock timeout to 30s -- [#2617](https://github.com/sanic-org/sanic/pull/2617) Scale number of running server workers -- [#2621](https://github.com/sanic-org/sanic/pull/2621) [#2634](https://github.com/sanic-org/sanic/pull/2634) Send `SIGKILL` on subsequent `ctrl+c` to force worker exit -- [#2622](https://github.com/sanic-org/sanic/pull/2622) Add API to restart all workers from the multiplexer -- [#2624](https://github.com/sanic-org/sanic/pull/2624) Default to `spawn` for all subprocesses unless specifically set: +- [#2569](https://github.com/sanic-org/sanic/pull/2569) 在更新响应对象时添加 `JSONResponse` 类，并有一些方便的方法 +- [#2598](https://github.com/sanic-org/sanic/pull/2598) 将 `uvloop` 要求更改为 `>=0.15.0` +- [#2609](https://github.com/sanic-org/sanic/pull/2609) 添加与 `websockets` v11.0 +- [#2610](https://github.com/sanic-org/sanic/pull/2610) 在工人错误的早期杀死服务器 + - 将僵局提升到30秒 +- [#2617](https://github.com/sanic-org/sanic/pull/261) +- [#2621](https://github.com/sanic-org/sanic/pull/2621)[#2634](https://github.com/sanic-org/sanic/pull/2634) 在随后的`ctrl+c`上发送`SIGKILL`，迫使工人退出 +- [#2622](https://github.com/sanic-org/sanic/pull/2622) 添加 API 以重新启动多路程序的所有工人。 +- [#2624](https://github.com/sanic-org/sanic/pull/2624) 默认为所有子进程的`spawn`，除非具体设置： ```python - from sanic import Sanic + 从Sanic 导入 Sanic - Sanic.start_method = "fork" + Sanic.start_methods = "fork" ``` -- [#2625](https://github.com/sanic-org/sanic/pull/2625) Filename normalisation of form-data/multipart file uploads -- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector: - - Remote access to inspect running Sanic instances - - TLS support for encrypted calls to Inspector - - Authentication to Inspector with API key - - Ability to extend Inspector with custom commands -- [#2632](https://github.com/sanic-org/sanic/pull/2632) Control order of restart operations -- [#2633](https://github.com/sanic-org/sanic/pull/2633) Move reload interval to class variable -- [#2636](https://github.com/sanic-org/sanic/pull/2636) Add `priority` to `register_middleware` method -- [#2639](https://github.com/sanic-org/sanic/pull/2639) Add `unquote` to `add_route` method -- [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets to receive `text` or `bytes` +- [#2625](https://github.com/sanic-org/sanic/pull/2625) 格式数据/多部分文件上传文件名正常化 +- [#2626](https://github.com/sanic-org/sanic/pull/2626) 移动到HTTP检查器： + - 远程访问以检查正在运行的 Sanic 实例 + - TLS 支持给检查员的加密通话 + - 使用 API 密钥验证检查员 + - 使用自定义命令扩展检查员的能力 +- [#2632](https://github.com/sanic-org/sanic/pull/2632) 重新启动操作的控制顺序 +- [#2633](https://github.com/sanic-org/sanic/pull/2633) 将重新加载间隔移至类变量 +- [#2636](https://github.com/sanic-org/sanic/pull/2636) 在 `register_middleware` 方法中添加 `priority` +- [#2639](https://github.com/sanic-org/sanic/pull/2639) 在 `add_route` 方法中加上“unquote\` +- [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets 接收`text` 或 `bytes` -### Bugfixes +### 错误修正 -- [#2607](https://github.com/sanic-org/sanic/pull/2607) Force socket shutdown before close to allow rebinding -- [#2590](https://github.com/sanic-org/sanic/pull/2590) Use actual `StrEnum` in Python 3.11+ -- [#2615](https://github.com/sanic-org/sanic/pull/2615) Ensure middleware executes only once per request timeout -- [#2627](https://github.com/sanic-org/sanic/pull/2627) Crash ASGI application on lifespan failure -- [#2635](https://github.com/sanic-org/sanic/pull/2635) Resolve error with low-level server creation on Windows +- [#2607](https://github.com/sanic-org/sanic/pull/2607) 强制套接字关闭之前允许重新绑定 +- [#2590](https://github.com/sanic-org/sanic/pull/2590) 在Python 3.11+中使用实际的`StrEnum` +- [#2615](https://github.com/sanic-org/sanic/pull/2615) 确保每个请求超时只执行一次中间件执行 +- [#2627](https://github.com/sanic-org/sanic/pull/2627) 在生命周期失败时崩溃ASGI应用程序 +- [#2635](https://github.com/sanic-org/sanic/pull/2635) 解决Windows 上低级服务器创建错误 -### Deprecations and Removals +### 废弃和移除 -- [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) Signal conditions and triggers saved on `signal.extra` -- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector - - 🚨 _BREAKING CHANGE_: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol - - _DEPRECATE_: The `--inspect*` commands have been deprecated in favor of `inspect ...` commands -- [#2628](https://github.com/sanic-org/sanic/pull/2628) Replace deprecated `distutils.strtobool` +- [#2608](https://github.com/sanic-org/sanic/pull/2608)[#2630](https://github.com/sanic-org/sanic/pull/2630) 信号条件和在`signal.extr` 上保存的触发器 +- [#2626](https://github.com/sanic-org/sanic/pull/2626) 移动到 HTTP 检查 + - 🚨 _Breaking更改_: 将检查员从一个带有自定义协议的 TCP 套接字移动到一个Sanic 应用程序 + - _DEPRECATE_: "--inspect\*" 命令已被弃用而改用 "inspect..." 命令 +- [#2628](https://github.com/sanic-org/sanic/pull/2628) 替换已废弃的`dutils.strtobool` -### Developer infrastructure +### 开发者基础设施 -- [#2612](https://github.com/sanic-org/sanic/pull/2612) Add CI testing for Python 3.11 +- [#2612](https://github.com/sanic-org/sanic/pull/2612) 添加CI 测试Python 3.11 -## Version 22.9.1 +## 第22.9.1 版 -### Features +### 功能 -- [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered +- [#2585](https://github.com/sanic-org/sanic/pull/2585) 没有注册应用程序时改进错误消息 -### Bugfixes +### 错误修正 -- [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation -- [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility -- [#2592](https://github.com/sanic-org/sanic/pull/2592) Fix properties in nested blueprint groups -- [#2595](https://github.com/sanic-org/sanic/pull/2595) Introduce sleep interval on new worker reloader +- [#2578](https://github.com/sanic-org/sanic/pull/2578) +- [#2591](https://github.com/sanic-org/sanic/pull/2591) 不使用 sentinel identity 来实现`spawn` 兼容性 +- [#2592](https://github.com/sanic-org/sanic/pull/2592) 修复嵌套蓝图组中的属性 +- [#2595](https://github.com/sanic-org/sanic/pull/2595) 在新的工人读取器上设置睡眠间隔 -### Deprecations and Removals +### 废弃和移除 -### Developer infrastructure +### 开发者基础设施 - [#2588](https://github.com/sanic-org/sanic/pull/2588) Markdown templates on issue forms -### Improved Documentation +### 改进文档 -- [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 documentation -- [#2582](https://github.com/sanic-org/sanic/pull/2582) Cleanup documentation on Windows support +- [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 文档 +- [#2582](https://github.com/sanic-org/sanic/pull/2582) 清除Windows支持 -## Version 22.9.0 +## 版本 22.9.0 -### Features +### 功能 -- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom loads function -- [#2490](https://github.com/sanic-org/sanic/pull/2490) Make `WebsocketImplProtocol` async iterable -- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refactor -- [#2506](https://github.com/sanic-org/sanic/pull/2506) Use `pathlib` for path resolution (for static file serving) -- [#2508](https://github.com/sanic-org/sanic/pull/2508) Use `path.parts` instead of `match` (for static file serving) -- [#2513](https://github.com/sanic-org/sanic/pull/2513) Better request cancel handling -- [#2516](https://github.com/sanic-org/sanic/pull/2516) Add request properties for HTTP method info: +- [#2445](https://github.com/sanic-org/sanic/pull/2445) 添加自定义负载函数 +- [#2490](https://github.com/sanic-org/sanic/pull/2490) 使`WebsocketImplication` async +- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refacture +- [#2506](https://github.com/sanic-org/sanic/pull/2506) 使用 `pathlib` 作为路径分辨率(用于静态文件服务) +- [#2508](https://github.com/sanic-org/sanic/pull/2508) 使用 `path.parts` 而不是 `match` (用于静态文件服务) +- [#2513](https://github.com/sanic-org/sanic/pull/2513) 更好地请求取消处理 +- [#2516](https://github.com/sanic-org/sanic/pull/2516) 添加HTTP方法信息的请求属性： - `request.is_safe` - - `request.is_idempotent` - - `request.is_cacheable` - - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _for more information about when these apply_ -- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI -- [#2526](https://github.com/sanic-org/sanic/pull/2526) Cache control support for static files for returning 304 when appropriate -- [#2533](https://github.com/sanic-org/sanic/pull/2533) Refactor `_static_request_handler` -- [#2540](https://github.com/sanic-org/sanic/pull/2540) Add signals before and after handler execution - - `http.handler.before` - - `http.handler.after` -- [#2542](https://github.com/sanic-org/sanic/pull/2542) Add _[redacted]_ to CLI :) -- [#2546](https://github.com/sanic-org/sanic/pull/2546) Add deprecation warning filter -- [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware priority and performance enhancements + - `request.is_identient` + - `request.is_cache` + - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _获取更多关于何时应用的信息_ +- [#2522](https://github.com/sanic-org/sanic/pull/252) 始终在ASGI 中显示服务器位置 +- [#2526](https://github.com/sanic-org/sanic/pull/2526) 缓存控制支持静态文件在适当时返回 304 +- [#2533](https://github.com/sanic-org/sanic/pull/2533) 重新因素`_static_request_handler` +- [#2540](https://github.com/sanic-org/sanic/pull/2540) + - `http.handler.befor` + - `http.handler.after ` +- [#2542](https://github.com/sanic-org/sanic/pull/2542) 添加 \*[redacted]到 CLI :) +- [#2546](https://github.com/sanic-org/sanic/pull/2546) 添加废弃警告过滤器 +- [#2550](https://github.com/sanic-org/sanic/pull/250) 中间件优先级和性能提高 -### Bugfixes +### 错误修正 -- [#2495](https://github.com/sanic-org/sanic/pull/2495) Prevent directory traversion with static files -- [#2515](https://github.com/sanic-org/sanic/pull/2515) Do not apply double slash to paths in certain static dirs in Blueprints +- [#2495](https://github.com/sanic-org/sanic/pull/2495) 防止目录陷阱与静态文件 +- [#2515](https://github.com/sanic-org/sanic/pull/2515) 不要在蓝图中的某些静态目录中对路径使用双斜线 -### Deprecations and Removals +### 废弃和移除 -- [#2525](https://github.com/sanic-org/sanic/pull/2525) Warn on duplicate route names, will be prevented outright in v23.3 -- [#2537](https://github.com/sanic-org/sanic/pull/2537) Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3 +- [#2525](https://github.com/sanic-org/sanic/pull/225) 在重复的路线名称上发出警告，将在 v23.3 中彻底防止发出警告。 +- [#2537](https://github.com/sanic-org/sanic/pull/2537) 对于重复的例外情况发出警告和弃置通知，将在v23.3中彻底防止。 -### Developer infrastructure +### 开发者基础设施 -- [#2504](https://github.com/sanic-org/sanic/pull/2504) Cleanup test suite -- [#2505](https://github.com/sanic-org/sanic/pull/2505) Replace Unsupported Python Version Number from the Contributing Doc -- [#2530](https://github.com/sanic-org/sanic/pull/2530) Do not include tests folder in installed package resolver +- [#2504](https://github.com/sanic-org/sanic/pull/2504) 清理测试套件 +- [#2505](https://github.com/sanic-org/sanic/pull/2505) 从贡献工具箱中替换不支持的 Python 版本 +- [#2530](https://github.com/sanic-org/sanic/pull/2530) -### Improved Documentation +### 改进文档 -- [#2502](https://github.com/sanic-org/sanic/pull/2502) Fix a few typos -- [#2517](https://github.com/sanic-org/sanic/pull/2517) [#2536](https://github.com/sanic-org/sanic/pull/2536) Add some type hints +- [#2502](https://github.com/sanic-org/sanic/pull/2502) 修复几个typos +- [#2517](https://github.com/sanic-org/sanic/pull/2517)[#2536](https://github.com/sanic-org/sanic/pull/2536) 添加一些类型的提示 -## Version 22.6.2 +## 22.6.2 版本 -### Bugfixes +### 错误修正 -- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI +- [#2522](https://github.com/sanic-org/sanic/pull/252) 始终在ASGI 中显示服务器位置 -## Version 22.6.1 +## 22.6.1 版本 -### Bugfixes +### 错误修正 -- [#2477](https://github.com/sanic-org/sanic/pull/2477) Sanic static directory fails when folder name ends with ".." +- [#2477](https://github.com/sanic-org/sanic/pull/2477) 当文件夹名称以“...”结尾时，无声静态目录失败 -## Version 22.6.0 +## 版本 22.6.0 -### Features +### 功能 -- [#2378](https://github.com/sanic-org/sanic/pull/2378) Introduce HTTP/3 and autogeneration of TLS certificates in `DEBUG` mode - - 👶 _EARLY RELEASE FEATURE_: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented. - - 📦 _EXTRA REQUIREMENT_: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a [HTTP/3 capable client](https://curl.se/docs/http3.html). - - 📦 _EXTRA REQUIREMENT_: In order to use TLS autogeneration, you must install either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). -- [#2416](https://github.com/sanic-org/sanic/pull/2416) Add message to `task.cancel` -- [#2420](https://github.com/sanic-org/sanic/pull/2420) Add exception aliases for more consistent naming with standard HTTP response types (`BadRequest`, `MethodNotAllowed`, `RangeNotSatisfiable`) -- [#2432](https://github.com/sanic-org/sanic/pull/2432) Expose ASGI `scope` as a property on the `Request` object -- [#2438](https://github.com/sanic-org/sanic/pull/2438) Easier access to websocket class for annotation: `from sanic import Websocket` -- [#2439](https://github.com/sanic-org/sanic/pull/2439) New API for reading form values with options: `Request.get_form` -- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom `loads` function -- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) Improved API to support setting cache control headers -- [#2453](https://github.com/sanic-org/sanic/pull/2453) Move verbosity filtering to logger -- [#2475](https://github.com/sanic-org/sanic/pull/2475) Expose getter for current request using `Request.get_current()` +- [#2378](https://github.com/sanic-org/sanic/pull/2378) 在 `DEBUG` 模式中引入HTTP/3 和 TLS 证书的自动生成 + - 👶 _EARLY RELEASE FEATURE_: 通过 HTTP/3 提供Sanic 是一种提早发布功能。 它尚未完全涵盖HTTP/3 单项，而是旨在与现有的 HTTP/1.1 服务器实现功能对等。 Websockets, WebTransport, 推送响应是一些尚未实现的功能的例子。 + - 📦 _EXTRA REQUIREMENT_: 并非所有HTTP客户端都能够与 HTTP/3 服务器接口。 您可能需要安装 [HTTP 3 能够安装的客户端](https://curl.se/docs/http3.html)。 + - 📦 _EXTRA REQUIREMENT_: 若要使用 TLS 自动生成，您必须安装 [mkcert](https://github.com/FiloSottile/mkcert) 或 [trustme](https://github.com/python-trio/trustme)。 +- [#2416](https://github.com/sanic-org/sanic/pull/2416) 将消息添加到 `task.cancel` +- [#2420](https://github.com/sanic-org/sanic/pull/2420) 添加异常别名以更一致地命名与标准HTTP响应类型(`BadRequest`, `MethodNotalled`, `RangeNotSatisfiable`) +- [#2432](https://github.com/sanic-org/sanic/pull/2432) 将ASGI `scope` 作为一个 `Request` 对象的属性 +- [#2438](https://github.com/sanic-org/sanic/pull/2438) 更容易访问Websocket类别以获取批注: `from sanic import Websocket` +- [#2439](https://github.com/sanic-org/sanic/pull/2439) 新API用于阅读带有选项的表格值：`Request.get_form` +- [#2445](https://github.com/sanic-org/sanic/pull/2445) 添加自定义 `loads` 函数 +- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) 改进API以支持设置缓存控制头部 +- [#2453](https://github.com/sanic-org/sanic/pull/2453) 移动动词过滤器到记录器 +- [#2475](https://github.com/sanic-org/sanic/pull/2475) 使用 `Request.get_current()` 方法显示当前请求的获取器 -### Bugfixes +### 错误修正 -- [#2448](https://github.com/sanic-org/sanic/pull/2448) Fix to allow running with `pythonw.exe` or places where there is no `sys.stdout` -- [#2451](https://github.com/sanic-org/sanic/pull/2451) Trigger `http.lifecycle.request` signal in ASGI mode -- [#2455](https://github.com/sanic-org/sanic/pull/2455) Resolve typing of stacked route definitions -- [#2463](https://github.com/sanic-org/sanic/pull/2463) Properly catch websocket CancelledError in websocket handler in Python 3.7 +- [#2448](https://github.com/sanic-org/sanic/pull/2448) 修正允许使用 pythonw\.exe\` 或没有 'sys.stdout' 的地方运行 +- [#2451](https://github.com/sanic-org/sanic/pull/2451)在 ASGI 模式中触发`http.lifecycle.request` 信号 +- [#2455](https://github.com/sanic-org/sanic/pull/2455) 解决堆叠路线定义的打字问题 +- [#2463](https://github.com/sanic-org/sanic/pull/2463) Python 3.7 Websocket 处理程序中正确捕获websocket 取消错误 -### Deprecations and Removals +### 废弃和移除 -- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 deprecations and changes - 1. Optional application registry - 2. Execution of custom handlers after some part of response was sent - 3. Configuring fallback handlers on the `ErrorHandler` - 4. Custom `LOGO` setting +- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 废弃和更改 + 1. 可选的应用程序注册 + 2. 发送部分响应后执行自定义处理程序 + 3. 在 `ErrorHandler` 上配置回退处理 + 4. 自定义 `LOGO` 设置 5. `sanic.response.stream` 6. `AsyncioServer.init` -### Developer infrastructure +### 开发者基础设施 -- [#2449](https://github.com/sanic-org/sanic/pull/2449) Clean up `black` and `isort` config -- [#2479](https://github.com/sanic-org/sanic/pull/2479) Fix some flappy tests +- [#2449](https://github.com/sanic-org/sanic/pull/2449) 清理`black`和`isort`配置 +- [#2479](https://github.com/sanic-org/sanic/pull/2479) 修复一些简易测试 -### Improved Documentation +### 改进文档 -- [#2461](https://github.com/sanic-org/sanic/pull/2461) Update example to match current application naming standards -- [#2466](https://github.com/sanic-org/sanic/pull/2466) Better type annotation for `Extend` -- [#2485](https://github.com/sanic-org/sanic/pull/2485) Improved help messages in CLI +- [#2461](https://github.com/sanic-org/sanic/pull/2461) 更新示例以匹配当前应用程序命名标准 +- [#2466](https://github.com/sanic-org/sanic/pull/2466) 更好类型`Extend` +- [#2485](https://github.com/sanic-org/sanic/pull/2485) 改进CLI 中的帮助信息 -## Version 22.3.0 +## 版本22.3.0 -### Features +### 功能 -- [#2347](https://github.com/sanic-org/sanic/pull/2347) API for multi-application server - - 🚨 _BREAKING CHANGE_: The old `sanic.worker.GunicornWorker` has been **removed**. To run Sanic with `gunicorn`, you should use it thru `uvicorn` [as described in their docs](https://www.uvicorn.org/#running-with-gunicorn). - - 🧁 _SIDE EFFECT_: Named background tasks are now supported, even in Python 3.7 +- [#2347](https://github.com/sanic-org/sanic/pull/2347) 多应用程序服务器的 API + - 🚨 _Breaking CHANGE_: 旧的 `sanic.worker.GunicornWorker` 已被删除 \*\*。 若要用 `gunicorn` 来运行Sanic，你应该使用它`uvicorn` [如他们的文件中所述](https://www.uvicorn.org/#running-with-gunicorn)。 + - 🧁 _SIDE EFFECT_: 命名后台任务现在得到支持, 甚至是 Python 3.7 - [#2357](https://github.com/sanic-org/sanic/pull/2357) Parse `Authorization` header as `Request.credentials` -- [#2361](https://github.com/sanic-org/sanic/pull/2361) Add config option to skip `Touchup` step in application startup -- [#2372](https://github.com/sanic-org/sanic/pull/2372) Updates to CLI help messaging -- [#2382](https://github.com/sanic-org/sanic/pull/2382) Downgrade warnings to backwater debug messages -- [#2396](https://github.com/sanic-org/sanic/pull/2396) Allow for `multidict` v0.6 -- [#2401](https://github.com/sanic-org/sanic/pull/2401) Upgrade CLI catching for alternative application run types -- [#2402](https://github.com/sanic-org/sanic/pull/2402) Conditionally inject CLI arguments into factory -- [#2413](https://github.com/sanic-org/sanic/pull/2413) Add new start and stop event listeners to reloader process -- [#2414](https://github.com/sanic-org/sanic/pull/2414) Remove loop as required listener arg -- [#2415](https://github.com/sanic-org/sanic/pull/2415) Better exception for bad URL parsing -- [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) Add a new extention parameter type: ``, ``, ``, ``, ``, `` - - 👶 _BETA FEATURE_: This feature will not work with `path` type matching, and is being released as a beta feature only. -- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) Change `register_pattern` to accept a `str` or `Pattern` -- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) Default matching on non-empty strings only, and new `strorempty` pattern type - - 🚨 _BREAKING CHANGE_: Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now **only** match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. - -### Bugfixes - -- [#2373](https://github.com/sanic-org/sanic/pull/2373) Remove `error_logger` on websockets -- [#2381](https://github.com/sanic-org/sanic/pull/2381) Fix newly assigned `None` in task registry -- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) Add type casting to regex route matching -- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) Add requirements check on regex routes (this resolves, for example, multiple static directories with differing `host` values) - -### Deprecations and Removals - -- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 Deprecations and changes - 1. `debug=True` and `--debug` do _NOT_ automatically run `auto_reload` - 2. Default error render is with plain text (browsers still get HTML by default because `auto` looks at headers) - 3. `config` is required for `ErrorHandler.finalize` - 4. `ErrorHandler.lookup` requires two positional args - 5. Unused websocket protocol args removed -- [#2344](https://github.com/sanic-org/sanic/pull/2344) Deprecate loading of lowercase environment variables - -### Developer infrastructure - -- [#2363](https://github.com/sanic-org/sanic/pull/2363) Revert code coverage back to Codecov -- [#2405](https://github.com/sanic-org/sanic/pull/2405) Upgrade tests for `sanic-routing` changes -- [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) Allow for httpx v0.22 - -### Improved Documentation - -- [#2350](https://github.com/sanic-org/sanic/pull/2350) Fix link in README for ASGI -- [#2398](https://github.com/sanic-org/sanic/pull/2398) Document middleware on_request and on_response -- [#2409](https://github.com/sanic-org/sanic/pull/2409) Add missing documentation for `Request.respond` - -### Miscellaneous - -- [#2376](https://github.com/sanic-org/sanic/pull/2376) Fix typing for `ListenerMixin.listener` -- [#2383](https://github.com/sanic-org/sanic/pull/2383) Clear deprecation warning in `asyncio.wait` +- [#2361](https://github.com/sanic-org/sanic/pull/2361) 在应用程序启动时添加配置选项以跳过`Touchup` 步骤 +- [#2372](https://github.com/sanic-org/sanic/pull/2372) 更新到 CLI 帮助发送消息 +- [#2382](https://github.com/sanic-org/sanic/pull/2382) 降级警告到背水调试消息 +- [#2396](https://github.com/sanic-org/sanic/pull/2396) 允许使用 `multidict` v0.6 +- [#2401](https://github.com/sanic-org/sanic/pull/2401) 升级 CLI 捕获替代应用程序运行类型 +- [#2402](https://github.com/sanic-org/sanic/pull/2402) 有条件将CLI 参数注入工厂中 +- [#2413](https://github.com/sanic-org/sanic/pull/2413) 添加新的开始和停止事件监听器到阅读器进程 +- [#2414](https://github.com/sanic-org/sanic/pull/2414) 移除循环作为必要的听众arg +- [#2415](https://github.com/sanic-org/sanic/pull/245) +- [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) 添加一个新的退出参数类型：``, ``, ``, ` `, ``, ``, `` + - 👶 _BETA FEATURE_: 此功能将无法与 `path` 类型匹配, 并且仅作为测试版发布. +- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) 更改`register_pattern` 以接受一个 `str` 或 `Pattern` +- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) 仅在非空字符串上默认匹配，以及新的 `strempty` 模式类型 + - 🚨 _Breaking变异_: 之前带有动态字符串参数的路由(`/` 或 `/`) 将在任何字符串上匹配, 包含空字符串。 现在**仅** 匹配一个非空字符串。 要保留旧的行为，您应该使用新的参数类型：`/`。 + +### 错误修正 + +- [#2373](https://github.com/sanic-org/sanic/pull/2373) 在websockets上删除 `error_logger` +- [#2381](https://github.com/sanic-org/sanic/pull/2381) 修复任务注册表中新分配的`None` +- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) 添加类型铸造到regex route 匹配 +- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) 在regex routing上添加要求检查(这个解析方法是多个静态目录，具有不同的`host`值) + +### 废弃和移除 + +- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 废弃和更改 + 1. `debug=True` 和 `--debug` 做_NOT_ 自动运行 `auto_reload` + 2. 默认错误渲染为纯文本(默认仍然获取 HTML ，因为`auto` 看着头部) + 3. `config` 是需要 `ErrorHandler.finalize` + 4. `ErrorHandler.lookup` 需要两个位置参数 + 5. 未使用的 websocket 协议参数已删除 +- [#2344](https://github.com/sanic-org/sanic/pull/2344) 废弃加载小写环境变量 + +### 开发者基础设施 + +- [#2363](https://github.com/sanic-org/sanic/pull/2363) 将代码覆盖范围还原到 Codecov +- [#2405](https://github.com/sanic-org/sanic/pull/2405) 升级`sanic-routing`更改测试 +- [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) 允许 httpx v0.22 + +### 改进文档 + +- [#2350](https://github.com/sanic-org/sanic/pull/2350) README中的 ASGI 修复链接 +- [#2398](https://github.com/sanic-org/sanic/pull/2398) 文档中间件on_request 和 on_response +- [#2409](https://github.com/sanic-org/sanic/pull/2409) 添加缺失的`Request.respond `文档 + +### 其他事项 + +- [#2376](https://github.com/sanic-org/sanic/pull/2376) 修复`ListenerMixin.listener` +- [#2383](https://github.com/sanic-org/sanic/pull/2383) 在 `asyncio.wait` 中清除废弃警告。 - [#2387](https://github.com/sanic-org/sanic/pull/2387) Cleanup `__slots__` implementations -- [#2390](https://github.com/sanic-org/sanic/pull/2390) Clear deprecation warning in `asyncio.get_event_loop` - -## Version 21.12.1 - -- [#2349](https://github.com/sanic-org/sanic/pull/2349) Only display MOTD on startup -- [#2354](https://github.com/sanic-org/sanic/pull/2354) Ignore name argument in Python 3.7 -- [#2355](https://github.com/sanic-org/sanic/pull/2355) Add config.update support for all config values - -## Version 21.12.0 - -### Features - -- [#2260](https://github.com/sanic-org/sanic/pull/2260) Allow early Blueprint registrations to still apply later added objects -- [#2262](https://github.com/sanic-org/sanic/pull/2262) Noisy exceptions - force logging of all exceptions -- [#2264](https://github.com/sanic-org/sanic/pull/2264) Optional `uvloop` by configuration -- [#2270](https://github.com/sanic-org/sanic/pull/2270) Vhost support using multiple TLS certificates -- [#2277](https://github.com/sanic-org/sanic/pull/2277) Change signal routing for increased consistency - - _BREAKING CHANGE_: If you were manually routing signals there is a breaking change. The signal router's `get` is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using `app.dispatch` or `bp.dispatch`, there is no change. -- [#2290](https://github.com/sanic-org/sanic/pull/2290) Add contextual exceptions -- [#2291](https://github.com/sanic-org/sanic/pull/2291) Increase join concat performance -- [#2295](https://github.com/sanic-org/sanic/pull/2295), [#2316](https://github.com/sanic-org/sanic/pull/2316), [#2331](https://github.com/sanic-org/sanic/pull/2331) Restructure of CLI and application state with new displays and more command parity with `app.run` -- [#2302](https://github.com/sanic-org/sanic/pull/2302) Add route context at definition time -- [#2304](https://github.com/sanic-org/sanic/pull/2304) Named tasks and new API for managing background tasks -- [#2307](https://github.com/sanic-org/sanic/pull/2307) On app auto-reload, provide insight of changed files -- [#2308](https://github.com/sanic-org/sanic/pull/2308) Auto extend application with [Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) if it is installed, and provide first class support for accessing the extensions -- [#2309](https://github.com/sanic-org/sanic/pull/2309) Builtin signals changed to `Enum` -- [#2313](https://github.com/sanic-org/sanic/pull/2313) Support additional config implementation use case -- [#2321](https://github.com/sanic-org/sanic/pull/2321) Refactor environment variable hydration logic -- [#2327](https://github.com/sanic-org/sanic/pull/2327) Prevent sending multiple or mixed responses on a single request -- [#2330](https://github.com/sanic-org/sanic/pull/2330) Custom type casting on environment variables -- [#2332](https://github.com/sanic-org/sanic/pull/2332) Make all deprecation notices consistent -- [#2335](https://github.com/sanic-org/sanic/pull/2335) Allow underscore to start instance names - -### Bugfixes - -- [#2273](https://github.com/sanic-org/sanic/pull/2273) Replace assignation by typing for `websocket_handshake` -- [#2285](https://github.com/sanic-org/sanic/pull/2285) Fix IPv6 display in startup logs -- [#2299](https://github.com/sanic-org/sanic/pull/2299) Dispatch `http.lifecyle.response` from exception handler - -### Deprecations and Removals - -- [#2306](https://github.com/sanic-org/sanic/pull/2306) Removal of deprecated items - - `Sanic` and `Blueprint` may no longer have arbitrary properties attached to them - - `Sanic` and `Blueprint` forced to have compliant names +- [#2390](https://github.com/sanic-org/sanic/pull/2390) 在 `asyncio.get_event_loop` 中清除废弃警告 + +## 版本21.12.1 + +- [#2349](https://github.com/sanic-org/sanic/pull/2349) 仅在启动时显示MOTD +- [#2354](https://github.com/sanic-org/sanic/pull/2354) 忽略Python 3.7 中的名称参数 +- [#2355](https://github.com/sanic-org/sanic/pull/2355) 添加config.update 支持所有配置 + +## 版本21.12.0 + +### 功能 + +- [#2260](https://github.com/sanic-org/sanic/pull/2260) 允许早期蓝图注册仍然应用以后添加的对象 +- [No. 2262](https://github.com/sanic-org/sanic/pull/2262) 噪音异常——强制记录所有异常 +- [#2264](https://github.com/sanic-org/sanic/pull/2264) 可选的`uvloop` +- [#2270](https://github.com/sanic-org/sanic/pull/2270) 使用多个TLS证书支持虚拟主机 +- [#2277](https://github.com/sanic-org/sanic/pull/2277) 为提高一致性而改变信号路由 + - _购买更改_：如果你是手动路由信号，有一个破碎的变化。 信号路由器的 `get` 不再是 100% 的决定因素。 现在有一个额外的步骤来循环回来的信号，以便在要求上进行适当的匹配。 如果正在使用`app.rapoch`或`bp.poidch`发出信号'发出信号的话，则没有变化。 +- [#2290](https://github.com/sanic-org/sanic/pull/2290) 添加上下文异常 +- [#2291](https://github.com/sanic-org/sanic/pull/2291) +- [#2295](https://github.com/sanic-org/sanic/pull/2295)，[#2316](https://github.com/sanic-org/sanic/pull/2316)，[#2331](https://github.com/sanic-org/sanic/pull/23331) 重新调整CLI和应用程序状态，使用新的显示和更多的命令对等性 +- [#2302](https://github.com/sanic-org/sanic/pull/2302) 在定义时间添加路由环境 +- [#2304](https://github.com/sanic-org/sanic/pull/2304) 命名任务和新的 API 用于管理背景任务 +- [#2307](https://github.com/sanic-org/sanic/pull/2307) 在应用自动重新加载时，提供已更改文件的见解。 +- [#2308](https://github.com/sanic-org/sanic/pull/2308) 安装后自动扩展应用程序[Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) 并提供第一类支持访问扩展。 +- [#2309](https://github.com/sanic-org/sanic/pull/2309) +- [#2313](https://github.com/sanic-org/sanic/pull/2313) 支持额外配置实现使用 +- [#2321](https://github.com/sanic-org/sanic/pull/2321) +- [#2327](https://github.com/sanic-org/sanic/pull/2327) 防止对单个请求发送多个或混合的答复 +- [#2330](https://github.com/sanic-org/sanic/pull/2330) 环境变量定制类型投射器 +- [#2332](https://github.com/sanic-org/sanic/pull/2332) 使所有废弃通知保持一致 +- [#2335](https://github.com/sanic-org/sanic/pull/2335) 允许下划线开始实例名称 + +### 错误修正 + +- [#2273](https://github.com/sanic-org/sanic/pull/2273) 替换分配给`websocket_handshake` +- [#2285](https://github.com/sanic-org/sanic/pull/2285) 修复启动日志中的IPv6 显示 +- [#2299](https://github.com/sanic-org/sanic/pull/2299) 从异常处理器调度`http.lifecyle.response` + +### 废弃和移除 + +- [#2306](https://github.com/sanic-org/sanic/pull/2306) 移除弃用的项目 + - `Sanic` 和 `Blueprint` 可能不再具有附加于它们的任意属性 + - `Sanic` 和 `Blueprint` 被迫有符合要求的名称 - alphanumeric + `_` + `-` - - must start with letter or `_` - - `load_env` keyword argument of `Sanic` - - `sanic.exceptions.abort` - - `sanic.views.CompositionView` + - 必须以字母或`_`开头。 + - `load_env`关键词参数 `Sanic` + - `sanic.exceptions.abot` + - `sanic.views.compositionView` - `sanic.response.StreamingHTTPResponse` - - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming -- [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting + - _注意:_ `stream()`响应方法(如果你通过了一个可调用的流媒体函数)已被弃用,将在 v22.6 中删除。 您应该将所有流媒体响应升级到新风格：https\://sanicframework.org/en/guide/advanced/streaming.html#response-串流 +- [#2320](https://github.com/sanic-org/sanic/pull/2320) 从配置中删除应用实例以进行错误处理设置 -### Developer infrastructure +### 开发者基础设施 -- [#2251](https://github.com/sanic-org/sanic/pull/2251) Change dev install command -- [#2286](https://github.com/sanic-org/sanic/pull/2286) Change codeclimate complexity threshold from 5 to 10 -- [#2287](https://github.com/sanic-org/sanic/pull/2287) Update host test function names so they are not overwritten -- [#2292](https://github.com/sanic-org/sanic/pull/2292) Fail CI on error -- [#2311](https://github.com/sanic-org/sanic/pull/2311), [#2324](https://github.com/sanic-org/sanic/pull/2324) Do not run tests for draft PRs -- [#2336](https://github.com/sanic-org/sanic/pull/2336) Remove paths from coverage checks -- [#2338](https://github.com/sanic-org/sanic/pull/2338) Cleanup ports on tests +- [#2251](https://github.com/sanic-org/sanic/pull/2251) 更改安装命令 +- [#2286](https://github.com/sanic-org/sanic/pull/2286) 更改编解码复杂性阈值从 5 到 10 +- [#2287](https://github.com/sanic-org/sanic/pull/2287) 更新主机测试函数名以免被覆盖 +- [#2292](https://github.com/sanic-org/sanic/pull/2292) 错误故障CI +- [#2311](https://github.com/sanic-org/sanic/pull/2311) [#2324](https://github.com/sanic-org/sanic/pull/224) 不对PR草案进行测试 +- [#2336](https://github.com/sanic-org/sanic/pull/2336) 从覆盖面检查中删除路径 +- [#2338](https://github.com/sanic-org/sanic/pull/2338) 测试端口清理 -### Improved Documentation +### 改进文档 -- [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2329), [#2333](https://github.com/sanic-org/sanic/pull/2333) Cleanup typos and fix language +- [#2269](https://github.com/sanic-org/sanic/pull/2269)，[#2329](https://github.com/sanic-org/sanic/pull/2329)，[#2333](https://github.com/sanic-org/sanic/pull/233) 清理typos和修复语言 -### Miscellaneous +### 其他事项 -- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) Add Python 3.10 support -- [#2279](https://github.com/sanic-org/sanic/pull/2279), [#2317](https://github.com/sanic-org/sanic/pull/2317), [#2322](https://github.com/sanic-org/sanic/pull/2322) Add/correct missing type annotations -- [#2305](https://github.com/sanic-org/sanic/pull/2305) Fix examples to use modern implementations +- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) 添加 Python 3.10 支持 +- [#2279](https://github.com/sanic-org/sanic/pull/2279)，[#2317](https://github.com/sanic-org/sanic/pull/2317)，[#2322](https://github.com/sanic-org/sanic/pull/232) 添加/正确缺失的类型注释 +- [#2305](https://github.com/sanic-org/sanic/pull/2305) 修复使用现代实现的例子 -## Version 21.9.3 +## 21.9.3 版本 -_Rerelease of v21.9.2 with some cleanup_ +- 通过清理恢复v21.9.2 \* -## Version 21.9.2 +## 第21.9.2 版 -- [#2268](https://github.com/sanic-org/sanic/pull/2268) Make HTTP connections start in IDLE stage, avoiding delays and error messages -- [#2310](https://github.com/sanic-org/sanic/pull/2310) More consistent config setting with post-FALLBACK_ERROR_FORMAT apply +- [#2268](https://github.com/sanic-org/sanic/pull/2268) +- [#2310](https://github.com/sanic-org/sanic/pull/2310) -## Version 21.9.1 +## 21.9.1 版本 -- [#2259](https://github.com/sanic-org/sanic/pull/2259) Allow non-conforming ErrorHandlers +- [#2259](https://github.com/sanic-org/sanic/pull/2259) 允许不符合要求的错误处理 -## Version 21.9.0 +## 版本21.9.0 -### Features +### 功能 -- [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) Complete overhaul of I/O to websockets -- [#2160](https://github.com/sanic-org/sanic/pull/2160) Add new 17 signals into server and request lifecycles -- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto` fallback formatting upon exception -- [#2184](https://github.com/sanic-org/sanic/pull/2184) Introduce implementation for copying a Blueprint -- [#2200](https://github.com/sanic-org/sanic/pull/2200) Accept header parsing -- [#2207](https://github.com/sanic-org/sanic/pull/2207) Log remote address if available -- [#2209](https://github.com/sanic-org/sanic/pull/2209) Add convenience methods to BP groups -- [#2216](https://github.com/sanic-org/sanic/pull/2216) Add default messages to SanicExceptions -- [#2225](https://github.com/sanic-org/sanic/pull/2225) Type annotation convenience for annotated handlers with path parameters -- [#2236](https://github.com/sanic-org/sanic/pull/2236) Allow Falsey (but not-None) responses from route handlers -- [#2238](https://github.com/sanic-org/sanic/pull/2238) Add `exception` decorator to Blueprint Groups -- [#2244](https://github.com/sanic-org/sanic/pull/2244) Explicit static directive for serving file or dir (ex: `static(..., resource_type="file")`) -- [#2245](https://github.com/sanic-org/sanic/pull/2245) Close HTTP loop when connection task cancelled +- [#2158](https://github.com/sanic-org/sanic/pull/2158)，[#2248](https://github.com/sanic-org/sanic/pull/2248) 全面整修I/O至websockets +- [#2160](https://github.com/sanic-org/sanic/pull/2160) 将新的17个信号添加到服务器并请求生命周期 +- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto`退回格式化异常) +- [#2184](https://github.com/sanic-org/sanic/pull/2184) +- [#2200](https://github.com/sanic-org/sanic/pull/2200) 接受标题解析 +- [#2207](https://github.com/sanic-org/sanic/pull/2207) 日志远程地址如果可用 +- [#2209](https://github.com/sanic-org/sanic/pull/2209) 向BP组添加方便方法 +- [#2216](https://github.com/sanic-org/sanic/pull/2216) 将默认消息添加到 SanicExceptions +- [#2225](https://github.com/sanic-org/sanic/pull/2225) +- [#2236](https://github.com/sanic-org/sanic/pull/2236) 允许Falsey(但不是)从路由处理器中回复 +- [#2238](https://github.com/sanic-org/sanic/pull/2238) 在蓝图组中加上“异常”装饰符 +- [#2244](https://github.com/sanic-org/sanic/pull/2244) 对服务文件或目录的静态明确指令(例如: `static(..., resource_type="file")` +- [#2245](https://github.com/sanic-org/sanic/pull/2245) 在连接任务取消时关闭HTTP循环 -### Bugfixes +### 错误修正 -- [#2188](https://github.com/sanic-org/sanic/pull/2188) Fix the handling of the end of a chunked request -- [#2195](https://github.com/sanic-org/sanic/pull/2195) Resolve unexpected error handling on static requests -- [#2208](https://github.com/sanic-org/sanic/pull/2208) Make blueprint-based exceptions attach and trigger in a more intuitive manner -- [#2211](https://github.com/sanic-org/sanic/pull/2211) Fixed for handling exceptions of asgi app call -- [#2213](https://github.com/sanic-org/sanic/pull/2213) Fix bug where ws exceptions not being logged -- [#2231](https://github.com/sanic-org/sanic/pull/2231) Cleaner closing of tasks by using `abort()` in strategic places to avoid dangling sockets -- [#2247](https://github.com/sanic-org/sanic/pull/2247) Fix logging of auto-reload status in debug mode -- [#2246](https://github.com/sanic-org/sanic/pull/2246) Account for BP with exception handler but no routes +- [#2188](https://github.com/sanic-org/sanic/pull/2188) 修复对块请求结束的处理 +- [#2195](https://github.com/sanic-org/sanic/pull/2195) 解决静态请求处理意外错误 +- [#2208](https://github.com/sanic-org/sanic/pull/2208) +- [#2211](https://github.com/sanic-org/sanic/pull/2211) 固定用于处理异常的 asgi 应用程序调用 +- [#2213](https://github.com/sanic-org/sanic/pull/2213) 修复错误，在这个错误中，没有记录除数 +- [#2231](https://github.com/sanic-org/sanic/pull/2231) 清理结束任务，在战略地点使用“abort()”以避免染色套接字 +- [#2247](https://github.com/sanic-org/sanic/pull/2247) 修复调试模式下自动重新加载状态记录 +- [#2246](https://github.com/sanic-org/sanic/pull/2246) 为BP账户，但没有路由 -### Developer infrastructure +### 开发者基础设施 -- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP unit tests with raw client -- [#2199](https://github.com/sanic-org/sanic/pull/2199) Switch to codeclimate -- [#2214](https://github.com/sanic-org/sanic/pull/2214) Try Reopening Windows Tests -- [#2229](https://github.com/sanic-org/sanic/pull/2229) Refactor `HttpProtocol` into a base class -- [#2230](https://github.com/sanic-org/sanic/pull/2230) Refactor `server.py` into multi-file module +- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP Unit tests with raw 客户端 +- [#2199](https://github.com/sanic-org/sanic/pull/2199) 切换到解码器 +- [#2214](https://github.com/sanic-org/sanic/pull/2214) 尝试重启Windows 测试 +- [#2229](https://github.com/sanic-org/sanic/pull/2229) 将`HttpProtocol`重新因素变成一个基准类 +- [#2230](https://github.com/sanic-org/sanic/pull/2230) 重新因素`server.py`到多文件模块 -### Miscellaneous +### 其他事项 -- [#2173](https://github.com/sanic-org/sanic/pull/2173) Remove Duplicated Dependencies and PEP 517 Support -- [#2193](https://github.com/sanic-org/sanic/pull/2193), [#2196](https://github.com/sanic-org/sanic/pull/2196), [#2217](https://github.com/sanic-org/sanic/pull/2217) Type annotation changes +- [#2173](https://github.com/sanic-org/sanic/pull/2173) 删除重复的依赖关系和 PEP 517 支持 +- [#2193](https://github.com/sanic-org/sanic/pull/2193)，[#2196](https://github.com/sanic-org/sanic/pull/2196)，[#2217](https://github.com/sanic-org/sanic/pull/2217) -## Version 21.6.1 +## 版本21.6.1 -**Bugfixes** +**错误修复** - [#2178](https://github.com/sanic-org/sanic/pull/2178) Update sanic-routing to allow for better splitting of complex URI templates - [#2183](https://github.com/sanic-org/sanic/pull/2183) Proper - handling of chunked request bodies to resolve phantom 503 in logs -- [#2181](https://github.com/sanic-org/sanic/pull/2181) Resolve - regression in exception logging -- [#2201](https://github.com/sanic-org/sanic/pull/2201) Cleanup - request info in pipelined requests + 处理块请求机构以解析日志中的幽灵503 +- [#2181](https://github.com/sanic-org/sanic/pull/2181) 解决异常日志中的 + 回归问题 +- [#2201](https://github.com/sanic-org/sanic/pull/2201) 清理管道请求中的 + 请求 -## Version 21.6.0 +## 版本21.6.0 -**Features** +**特征** - [#2094](https://github.com/sanic-org/sanic/pull/2094) Add `response.eof()` method for closing a stream in a handler -- [#2097](https://github.com/sanic-org/sanic/pull/2097) Allow - case-insensitive HTTP Upgrade header +- [#2097](https://github.com/sanic-org/sanic/pull/2097) 允许 + 不区分大小写的 HTTP 升级标题 - [#2104](https://github.com/sanic-org/sanic/pull/2104) Explicit usage of CIMultiDict getters @@ -561,30 +561,30 @@ _Rerelease of v21.9.2 with some cleanup_ - [#2109](https://github.com/sanic-org/sanic/pull/2109) Consistent use of error loggers -- [#2114](https://github.com/sanic-org/sanic/pull/2114) New - `client_ip` access of connection info instance +- [#2114](https://github.com/sanic-org/sanic/pull/2114) 新的 + `client_ip` 访问连接信息实例 - [#2119](https://github.com/sanic-org/sanic/pull/2119) Alternatate - classes on instantiation for `Config` and `Sanic.ctx` + 类实例化的`Config` 和 `Sanic.ctx` -- [#2133](https://github.com/sanic-org/sanic/pull/2133) Implement - new version of AST router +- [#2133](https://github.com/sanic-org/sanic/pull/2133) 实现 + 新版本的 AST 路由器 - - Proper differentiation between `alpha` and `string` param - types - - Adds a `slug` param type, example: `` - - Deprecates `` in favor of `` - - Deprecates `` in favor of `` + - `alpha` 和 `string`param + 类型之间的适当区别 + - 添加一个 `slug` 参数类型，例如：`` + - 废弃foo:string`而改成`。 + - 废弃foo:number`而改成`。 - Adds a `route.uri` accessor - [#2136](https://github.com/sanic-org/sanic/pull/2136) CLI - improvements with new optional params + 改进使用新的可选参数 -- [#2137](https://github.com/sanic-org/sanic/pull/2137) Add - `version_prefix` to URL builders +- [#2137](https://github.com/sanic-org/sanic/pull/2137) 在 URL 生成器中添加 + `version_prefix` -- [#2140](https://github.com/sanic-org/sanic/pull/2140) Event - autoregistration with `EVENT_AUTOREGISTER` +- [#2140](https://github.com/sanic-org/sanic/pull/2140) 事件 + 自动注册 with `EVENT_AUTORGISTER` - [#2146](https://github.com/sanic-org/sanic/pull/2146), [#2147](https://github.com/sanic-org/sanic/pull/2147) Require @@ -593,477 +593,472 @@ _Rerelease of v21.9.2 with some cleanup_ - [#2150](https://github.com/sanic-org/sanic/pull/2150) Infinitely reusable and nestable `Blueprint` and `BlueprintGroup` -- [#2154](https://github.com/sanic-org/sanic/pull/2154) Upgrade - `websockets` dependency to min version +- [#2154](https://github.com/sanic-org/sanic/pull/2154) 将 + `websockets` 依赖关系升级为最小版本 -- [#2155](https://github.com/sanic-org/sanic/pull/2155) Allow for - maximum header sizes to be increased: `REQUEST_MAX_HEADER_SIZE` +- [#2155](https://github.com/sanic-org/sanic/pull/2155) 允许 + 增加最大标题尺寸：`REQUEST_MAX_HEADER_SIZE` -- [#2157](https://github.com/sanic-org/sanic/pull/2157) Allow app - factory pattern in CLI +- [#2157](https://github.com/sanic-org/sanic/pull/2157) 允许应用 + 出厂模式在 CLI -- [#2165](https://github.com/sanic-org/sanic/pull/2165) Change HTTP - methods to enums +- [#2165](https://github.com/sanic-org/sanic/pull/2165) 将 HTTP + 方法更改为enums -- [#2167](https://github.com/sanic-org/sanic/pull/2167) Allow - auto-reloading on additional directories +- [#2167](https://github.com/sanic-org/sanic/pull/2167) 允许 + 自动重新加载附加目录 -- [#2168](https://github.com/sanic-org/sanic/pull/2168) Add simple - HTTP server to CLI +- [#2168](https://github.com/sanic-org/sanic/pull/2168) 添加简单的 + HTTP 服务器到 CLI -- [#2170](https://github.com/sanic-org/sanic/pull/2170) Additional - methods for attaching `HTTPMethodView` +- [#2170](https://github.com/sanic-org/sanic/pull/2170) 附加的 + 方法附加`HTTPMethodView` -**Bugfixes** +**错误修复** - [#2091](https://github.com/sanic-org/sanic/pull/2091) Fix `UserWarning` in ASGI mode for missing `__slots__` -- [#2099](https://github.com/sanic-org/sanic/pull/2099) Fix static - request handler logging exception on 404 -- [#2110](https://github.com/sanic-org/sanic/pull/2110) Fix - request.args.pop removes parameters inconsistently -- [#2107](https://github.com/sanic-org/sanic/pull/2107) Fix type - hinting for load_env -- [#2127](https://github.com/sanic-org/sanic/pull/2127) Make sure - ASGI ws subprotocols is a list -- [#2128](https://github.com/sanic-org/sanic/pull/2128) Fix issue - where Blueprint exception handlers do not consistently route to - proper handler - -**Deprecations and Removals** +- [#2099](https://github.com/sanic-org/sanic/pull/2099) 修复静态 + 请求处理记录异常于404 +- [#2110](https://github.com/sanic-org/sanic/pull/2110) 修复 + request.args.pop 去除不一致的参数 +- [#2107](https://github.com/sanic-org/sanic/pull/2107) 修理 + 引导load_env +- [#2127](https://github.com/sanic-org/sanic/pull/2127) 请确认 + ASGI ws 子协议是一个列表 +- [#2128](https://github.com/sanic-org/sanic/pull/2128) 修复问题 + 蓝图异常处理程序没有始终如一地路由到 + 适当处理程序 + +**废弃和删除** - [#2156](https://github.com/sanic-org/sanic/pull/2156) Remove config value `REQUEST_BUFFER_QUEUE_SIZE` - [#2170](https://github.com/sanic-org/sanic/pull/2170) - `CompositionView` deprecated and marked for removal in 21.12 -- [#2172](https://github.com/sanic-org/sanic/pull/2170) Deprecate + `CompositionView` 已废弃，并在21.12中标记为移除。 +- [#2172](https://github.com/sanic-org/sanic/pull/2170) 废弃 StreamingHTTPResponse -**Developer infrastructure** +**开发者基础设施** -- [#2149](https://github.com/sanic-org/sanic/pull/2149) Remove - Travis CI in favor of GitHub Actions +- [#2149](https://github.com/sanic-org/sanic/pull/2149) 删除 + Travis CI 支持GitHub 操作 -**Improved Documentation** +**改进文档** -- [#2164](https://github.com/sanic-org/sanic/pull/2164) Fix typo in - documentation -- [#2100](https://github.com/sanic-org/sanic/pull/2100) Remove - documentation for non-existent arguments +- [#2164](https://github.com/sanic-org/sanic/pull/2164) 修复 + 文档中的类型 +- [#2100](https://github.com/sanic-org/sanic/pull/2100) 移除不存在的参数的 + 文档 -## Version 21.3.2 +## 21.3.2 版本 -**Bugfixes** +**错误修复** -- [#2081](https://github.com/sanic-org/sanic/pull/2081) Disable - response timeout on websocket connections +- [#2081](https://github.com/sanic-org/sanic/pull/2081) 在 websocket 连接上禁用 + 响应超时 - [#2085](https://github.com/sanic-org/sanic/pull/2085) Make sure that blueprints with no slash is maintained when applied -## Version 21.3.1 +## 版本21.3.1 -**Bugfixes** +**错误修复** -- [#2076](https://github.com/sanic-org/sanic/pull/2076) Static files - inside subfolders are not accessible (404) +- [#2076](https://github.com/sanic-org/sanic/pull/2076) 子文件夹内的静态文件 + 不可访问 (404) -## Version 21.3.0 +## 版本21.3.0 -Release -Notes +发布 +笔记 -**Features** +**特征** - [#1876](https://github.com/sanic-org/sanic/pull/1876) Unified - streaming server + 串流服务器 - [#2005](https://github.com/sanic-org/sanic/pull/2005) New - `Request.id` property -- [#2008](https://github.com/sanic-org/sanic/pull/2008) Allow - Pathlib Path objects to be passed to `app.static()` helper + `Request.id` 属性 +- [#2008](https://github.com/sanic-org/sanic/pull/2008) 允许 + Pathlib 路径对象传递给`app.static()` - [#2010](https://github.com/sanic-org/sanic/pull/2010), [#2031](https://github.com/sanic-org/sanic/pull/2031) New - startup-optimized router + 启动-优化路由器 - [#2018](https://github.com/sanic-org/sanic/pull/2018) - [#2064](https://github.com/sanic-org/sanic/pull/2064) Listeners - for main server process -- [#2032](https://github.com/sanic-org/sanic/pull/2032) Add raw - header info to request object + [#2064](https://github.com/sanic-org/sanic/pull/2064) 主服务器进程的侦听器 +- [#2032](https://github.com/sanic-org/sanic/pull/2032) 添加原始的 + 头信息以请求对象 - [#2042](https://github.com/sanic-org/sanic/pull/2042) [#2060](https://github.com/sanic-org/sanic/pull/2060) [#2061](https://github.com/sanic-org/sanic/pull/2061) Introduce Signals API - [#2043](https://github.com/sanic-org/sanic/pull/2043) Add `__str__` and `__repr__` to Sanic and Blueprint -- [#2047](https://github.com/sanic-org/sanic/pull/2047) Enable - versioning and strict slash on BlueprintGroup +- [#2047](https://github.com/sanic-org/sanic/pull/2047) 启用 + 版本并在蓝图组上严格闪光灯 - [#2053](https://github.com/sanic-org/sanic/pull/2053) Make - `get_app` name argument optional -- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON encoder - change via app -- [#2063](https://github.com/sanic-org/sanic/pull/2063) App and - connection level context objects - -**Bugfixes** - -- Resolve [#1420](https://github.com/sanic-org/sanic/pull/1420) - `url_for` where `strict_slashes` are on for a path ending in `/` -- Resolve [#1525](https://github.com/sanic-org/sanic/pull/1525) - Routing is incorrect with some special characters -- Resolve [#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI - headers in body -- Resolve [#1722](https://github.com/sanic-org/sanic/pull/1722) - Using curl in chunk mode -- Resolve [#1730](https://github.com/sanic-org/sanic/pull/1730) - Extra content in ASGI streaming response -- Resolve [#1749](https://github.com/sanic-org/sanic/pull/1749) - Restore broken middleware edge cases + `get_app` name 参数是可选的 +- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON编码器 + 通过应用程序更改 +- [#2063](https://github.com/sanic-org/sanic/pull/2063) App 和 + 连接级别环境对象 + +**错误修复** + +- 解析[#1420](https://github.com/sanic-org/sanic/pull/1420) + `url_for` ，其中`strict_slashes` 正在开启路径，结束于 `/` +- 解析[#1525](https://github.com/sanic-org/sanic/pull/1525) + 路由不正确，有一些特殊字符 +- 解析[#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI + 物体头 +- 解析[#1722](https://github.com/sanic-org/sanic/pull/1722) + 在区块模式中使用curl +- 解析[#1730](https://github.com/sanic-org/sanic/pull/1730) + ASGI 串流响应额外内容 +- 解析[#1749](https://github.com/sanic-org/sanic/pull/1749) + 还原破损的中间件边缘案件 - Resolve [#1785](https://github.com/sanic-org/sanic/pull/1785) [#1804](https://github.com/sanic-org/sanic/pull/1804) Synchronous error handlers -- Resolve [#1790](https://github.com/sanic-org/sanic/pull/1790) - Protocol errors did not support async error handlers #1790 -- Resolve [#1824](https://github.com/sanic-org/sanic/pull/1824) - Timeout on specific methods +- 解析[#1790](https://github.com/sanic-org/sanic/pull/1790) + 协议错误不支持 async 错误处理程序 #1790 +- 解析[#1824](https://github.com/sanic-org/sanic/pull/1824) + 超时特定方法 - Resolve [#1875](https://github.com/sanic-org/sanic/pull/1875) Response timeout error from all routes after returning several timeouts from a specific route -- Resolve [#1988](https://github.com/sanic-org/sanic/pull/1988) - Handling of safe methods with body -- [#2001](https://github.com/sanic-org/sanic/pull/2001) Raise - ValueError when cookie max-age is not an integer +- 解析[#1988](https://github.com/sanic-org/sanic/pull/1988) + 用身体处理安全方法 +- [#2001](https://github.com/sanic-org/sanic/pull/2001) 提升 + 值错误，因为cookie max-age 不是整数 -**Deprecations and Removals** +**废弃和删除** -- [#2007](https://github.com/sanic-org/sanic/pull/2007) \* Config - using `from_envvar` \* Config using `from_pyfile` \* Config using +- [#2007](https://github.com/sanic-org/sanic/pull/2007)\* 配置 + 使用 `from_envvar` \* 配置使用 `from_pyfile` \* 配置使用 `from_object` -- [#2009](https://github.com/sanic-org/sanic/pull/2009) Remove Sanic - test client to its own package +- [#2009](https://github.com/sanic-org/sanic/pull/2009) 删除Sanic + 测试客户端到自己的包 - [#2036](https://github.com/sanic-org/sanic/pull/2036), [#2037](https://github.com/sanic-org/sanic/pull/2037) Drop Python - 3.6 support -- `Request.endpoint` deprecated in favor of `Request.name` -- handler type name prefixes removed (static, websocket, etc) + 3.6 +- `Request.endpoint` 已不推荐使用 `Request.name` +- 处理器类型名称前缀已删除 (静态、websocket 等) -**Developer infrastructure** +**开发者基础设施** - [#1995](https://github.com/sanic-org/sanic/pull/1995) Create FUNDING.yml -- [#2013](https://github.com/sanic-org/sanic/pull/2013) Add codeql - to CI pipeline -- [#2038](https://github.com/sanic-org/sanic/pull/2038) Codecov - configuration updates -- [#2049](https://github.com/sanic-org/sanic/pull/2049) Updated - setup.py to use `find_packages` +- [#2013](https://github.com/sanic-org/sanic/pull/2013) 将codeql + 添加到CI 管道中 +- [#2038](https://github.com/sanic-org/pull/2038) Codecov + 配置更新 +- [#2049](https://github.com/sanic-org/sanic/pull/2049) 更新 + 设置，使用 `find_packes` -**Improved Documentation** +**改进文档** - [#1218](https://github.com/sanic-org/sanic/pull/1218) - Documentation for sanic.log.\* is missing -- [#1608](https://github.com/sanic-org/sanic/pull/1608) Add - documentation on calver and LTS + 文件缺失。\* +- [#1608](https://github.com/sanic-org/sanic/pull/1608) 添加 + 卡车文档和 LTS - [#1731](https://github.com/sanic-org/sanic/pull/1731) Support mounting application elsewhere than at root path -- [#2006](https://github.com/sanic-org/sanic/pull/2006) Upgraded - type annotations and improved docstrings and API documentation -- [#2052](https://github.com/sanic-org/sanic/pull/2052) Fix some - examples and docs - -**Miscellaneous** - -- `Request.route` property -- Better websocket subprotocols support -- Resolve bug with middleware in Blueprint Group when passed - callable -- Moves common logic between Blueprint and Sanic into mixins -- Route naming changed to be more consistent - - request endpoint is the route name - - route names are fully namespaced -- Some new convenience decorators: +- [#2006](https://github.com/sanic-org/sanic/pull/2006) 升级 + 类型注释并改进文档字符串和 API 文档 +- [#2052](https://github.com/sanic-org/sanic/pull/2052) 修复一些 + 示例和文档 + +**杂项** + +- `Request.route` 属性 +- 更好的Websocket 子协议支持 +- 传递了 + 时用蓝图组中的中间件解决bug +- 将蓝图和Sanic之间的通用逻辑移动到混合物 +- 路由命名更改为更加一致 + - 请求端点是路由名称 + - 路由名称已完全空格 +- 一些新的便利装饰符： - `@app.main_process_start` - `@app.main_process_stop` - - `@app.before_server_start` - - `@app.after_server_start` - - `@app.before_server_stop` - - `@app.after_server_stop` + - `@app.befor_server_start` + - `@app.after _server_start` + - `@app.befor_server_stop` + - `@app.after _server_stop` - `@app.on_request` - `@app.on_response` -- Fixes `Allow` header that did not include `HEAD` -- Using "name" keyword in `url_for` for a "static" route where - name does not exist -- Cannot have multiple `app.static()` without using the named param -- Using "filename" keyword in `url_for` on a file route -- `unquote` in route def (not automatic) -- `routes_all` is tuples -- Handler arguments are kwarg only -- `request.match_info` is now a cached (and not computed) property -- Unknown static file mimetype is sent as `application/octet-stream` -- `_host` keyword in `url_for` -- Add charset default to `utf-8` for text and js content types if - not specified -- Version for a route can be str, float, or int -- Route has ctx property -- App has `routes_static`, `routes_dynamic`, `routes_regex` -- [#2044](https://github.com/sanic-org/sanic/pull/2044) Code cleanup - and refactoring -- [#2072](https://github.com/sanic-org/sanic/pull/2072) Remove +- 修复不包含 `HEAD` 的 `Alle` 标题 +- 在 `url_for` 中使用 "name" 关键字用于"static"路由，在那里不存在 + 名称 +- 不使用命名参数，无法拥有多个`app.static()` +- 在文件路径上使用 "filename" 关键字在 `url_for` +- `取消引号`而不是自动' +- `routes_all` 是导线 +- 处理器参数只是 kwarg +- `request.match_info` 现在是缓存的(而不是计算的)属性 +- 未知的静态文件 mimetype 以 `application/octet-stream` 格式发送 +- `url_for`中的`_host`关键字 +- 如果没有指定 + ，为文本和 js 内容类型添加字符集默认值到 `utf-8` +- 路由的版本可以是字符串、浮点型变量或整数 +- 路由有 ctx 属性 +- 应用程序有`routes_static`, `routes_dynamic`, `routes_regex` +- [#2044](https://github.com/sanic-org/sanic/pull/2044) 代码清理 + 并重新排料中 +- [#2072](https://github.com/sanic-org/sanic/pull/2072) 删除 `BaseSanic` metaclass -- [#2074](https://github.com/sanic-org/sanic/pull/2074) Performance - adjustments in `handle_request_` +- [#2074](https://github.com/sanic-org/sanic/pull/2074) 性能 + 调整 `handle_request_` -## Version 20.12.3 +## 第20.12.3 版 -**Bugfixes** +**错误修复** -- [#2021](https://github.com/sanic-org/sanic/pull/2021) Remove - prefix from websocket handler name +- [#2021](https://github.com/sanic-org/sanic/pull/2021) 从websocket 处理器名称中删除 + 前缀 -## Version 20.12.2 +## 第20.12.2版 -**Dependencies** +**依赖** -- [#2026](https://github.com/sanic-org/sanic/pull/2026) Fix uvloop - to 0.14 because 0.15 drops Python 3.6 support -- [#2029](https://github.com/sanic-org/sanic/pull/2029) Remove old - chardet requirement, add in hard multidict requirement +- [#2026](https://github.com/sanic-org/sanic/pull/2026) 修复uvloop + 至 0.14 因为0.15 drops Python 3.6 支持 +- [#2029](https://github.com/sanic-org/sanic/pull/2029) 删除旧的 + 字符要求，在硬的多词要求中添加 -## Version 19.12.5 +## 第19.12.5版 -**Dependencies** +**依赖** - [#2025](https://github.com/sanic-org/sanic/pull/2025) Fix uvloop - to 0.14 because 0.15 drops Python 3.6 support -- [#2027](https://github.com/sanic-org/sanic/pull/2027) Remove old - chardet requirement, add in hard multidict requirement - -## Version 20.12.0 - -**Features** - -- [#1993](https://github.com/sanic-org/sanic/pull/1993) Add disable - app registry -- [#1945](https://github.com/sanic-org/sanic/pull/1945) Static route - more verbose if file not found -- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static - routes registration on a blueprint -- [#1961](https://github.com/sanic-org/sanic/pull/1961) Add Python - 3.9 support + 到 0.14 因为0.15 drops Python 3.6 支持 +- [#2027](https://github.com/sanic-org/sanic/pull/2027) 删除旧的 + chardet 要求，在硬的多词要求中添加 + +## 版本20.12.0 + +**特征** + +- [#1993](https://github.com/sanic-org/sanic/pull/1993) 添加禁用 + 应用注册 +- [#1945](https://github.com/sanic-org/sanic/pull/1945) 静态路由 + 更详细，如果找不到文件 +- [#1954](https://github.com/sanic-org/sanic/pull/1954) 修复静态 + 路由注册在蓝图上 +- [#1961](https://github.com/sanic-org/sanic/pull/1961) 添加 Python + 3.9 支持 - [#1962](https://github.com/sanic-org/sanic/pull/1962) Sanic CLI - upgrade + 升级 - [#1967](https://github.com/sanic-org/sanic/pull/1967) Update - aiofile version requirements + aiofile 版本要求 - [#1969](https://github.com/sanic-org/sanic/pull/1969) Update - multidict version requirements -- [#1970](https://github.com/sanic-org/sanic/pull/1970) Add py.typed - file + multidict requirements +- [#1970](https://github.com/sanic-org/sanic/pull/1970) 添加py.typed + 文件 - [#1972](https://github.com/sanic-org/sanic/pull/1972) Speed optimization in request handler -- [#1979](https://github.com/sanic-org/sanic/pull/1979) Add app - registry and Sanic class level app retrieval +- [#1979](https://github.com/sanic-org/sanic/pull/1979) 添加应用 + 注册表和 Sanic 类级应用程序检索器 -**Bugfixes** +**错误修复** -- [#1965](https://github.com/sanic-org/sanic/pull/1965) Fix Chunked - Transport-Encoding in ASGI streaming response +- [#1965](https://github.com/sanic-org/sanic/pull/1965) 修正Chunked + 传输-编码在 ASGI 串流响应中 -**Deprecations and Removals** +**废弃和删除** -- [#1981](https://github.com/sanic-org/sanic/pull/1981) Cleanup and - remove deprecated code +- [#1981](https://github.com/sanic-org/sanic/pull/1981) 清理和 + 删除已废弃的代码 -**Developer infrastructure** +**开发者基础设施** -- [#1956](https://github.com/sanic-org/sanic/pull/1956) Fix load - module test +- [#1956](https://github.com/sanic-org/sanic/pull/1956) 修正负载 + 模块测试 - [#1973](https://github.com/sanic-org/sanic/pull/1973) Transition - Travis from .org to .com + Travis从.org 到 .com - [#1986](https://github.com/sanic-org/sanic/pull/1986) Update tox - requirements + 要求 -**Improved Documentation** +**改进文档** - [#1951](https://github.com/sanic-org/sanic/pull/1951) - Documentation improvements -- [#1983](https://github.com/sanic-org/sanic/pull/1983) Remove - duplicate contents in testing.rst -- [#1984](https://github.com/sanic-org/sanic/pull/1984) Fix typo in - routing.rst + 文档改进 +- [#1983](https://github.com/sanic-org/sanic/pull/1983) 移除测试.rst 中的 + 重复内容 +- [#1984](https://github.com/sanic-org/sanic/pull/1984) 修复 + 路由.rst -## Version 20.9.1 +## 20.9.1 版本 -**Bugfixes** +**错误修复** -- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static - route registration on blueprints -- [#1957](https://github.com/sanic-org/sanic/pull/1957) Removes - duplicate headers in ASGI streaming body +- [#1954](https://github.com/sanic-org/sanic/pull/1954) 修复静态 + 路由注册在蓝图上 +- [#1957](https://github.com/sanic-org/sanic/pull/1957) 删除ASGI流体中的 + 重复标题 -## Version 19.12.3 +## 第19.12.3 版 -**Bugfixes** +**错误修复** -- [#1959](https://github.com/sanic-org/sanic/pull/1959) Removes - duplicate headers in ASGI streaming body +- [#1959](https://github.com/sanic-org/sanic/pull/1959) 删除ASGI流体中的 + 重复的头部 -## Version 20.9.0 +## 版本20.9.0 -**Features** +**特征** -- [#1887](https://github.com/sanic-org/sanic/pull/1887) Pass - subprotocols in websockets (both sanic server and ASGI) +- [#1887](https://github.com/sanic-org/sanic/pull/1887) 在 websockets (均为sanic server and ASGI) 传递 + 子协议 - [#1894](https://github.com/sanic-org/sanic/pull/1894) - Automatically set `test_mode` flag on app instance -- [#1903](https://github.com/sanic-org/sanic/pull/1903) Add new - unified method for updating app values + 在应用实例上自动设置 `test_mode` 标志 +- [#1903](https://github.com/sanic-org/sanic/pull/1903) 添加新的 + 统一方法来更新应用值 - [#1906](https://github.com/sanic-org/sanic/pull/1906), [#1909](https://github.com/sanic-org/sanic/pull/1909) Adds - WEBSOCKET_PING_TIMEOUT and WEBSOCKET_PING_INTERVAL configuration - values + WEBSOCKET_PING_TIMEOUT和WEBSOCKET_PING_ING_INTERVAL configuration + 值 - [#1935](https://github.com/sanic-org/sanic/pull/1935) httpx - version dependency updated, it is slated for removal as a - dependency in v20.12 -- [#1937](https://github.com/sanic-org/sanic/pull/1937) Added auto, - text, and json fallback error handlers (in v21.3, the default will - change form html to auto) + 版本依赖关系更新，它预定在 v20.12 中被移除为 + 依赖关系。 +- [#1937](https://github.com/sanic-org/sanic/pull/1937) 已添加自动、 + 文本和 json 回退错误处理程序(v21.3, 默认为 + 更改表格为 auto) -**Bugfixes** +**错误修复** -- [#1897](https://github.com/sanic-org/sanic/pull/1897) Resolves - exception from unread bytes in stream +- [#1897](https://github.com/sanic-org/sanic/pull/1897) 解析流中未读字节的 + 异常 -**Deprecations and Removals** +**废弃和删除** - [#1903](https://github.com/sanic-org/sanic/pull/1903) - config.from_envar, config.from_pyfile, and config.from_object are - deprecated and set to be removed in v21.3 + config.from_envar, config.from_pyfile, 和 config.from_object 是 + 废弃并设置为 v21.3 -**Developer infrastructure** +**开发者基础设施** - [#1890](https://github.com/sanic-org/sanic/pull/1890), - [#1891](https://github.com/sanic-org/sanic/pull/1891) Update isort - calls to be compatible with new API -- [#1893](https://github.com/sanic-org/sanic/pull/1893) Remove - version section from setup.cfg -- [#1924](https://github.com/sanic-org/sanic/pull/1924) Adding + [#1891](https://github.com/sanic-org/sanic/pull/1891) 更新isort + 调用以兼容新的 API +- [#1893](https://github.com/sanic-org/sanic/pull/1893) 从setup.cfg 中删除 + 版本 +- [#1924](https://github.com/sanic-org/sanic/pull/1924) 添加 \--strict-markers for pytest -**Improved Documentation** +**改进文档** -- [#1922](https://github.com/sanic-org/sanic/pull/1922) Add explicit - ASGI compliance to the README +- [#1922](https://github.com/sanic-org/sanic/pull/1922) 在README 中添加明确的 + ASGI 遵守情况 -## Version 20.6.3 +## 20.6.3 版本 -**Bugfixes** +**错误修复** -- [#1884](https://github.com/sanic-org/sanic/pull/1884) Revert - change to multiprocessing mode +- [#1884](https://github.com/sanic-org/sanic/pull/1884) 还原 + 更改为多处理模式 -## Version 20.6.2 +## 20.6.2 版本 -**Features** +**特征** - [#1641](https://github.com/sanic-org/sanic/pull/1641) Socket - binding implemented properly for IPv6 and UNIX sockets + 绑定适合IPv6和UNIX套接字 -## Version 20.6.1 +## 20.6.1 版本 -**Features** +**特征** -- [#1760](https://github.com/sanic-org/sanic/pull/1760) Add version - parameter to websocket routes -- [#1866](https://github.com/sanic-org/sanic/pull/1866) Add `sanic` - as an entry point command +- [#1760](https://github.com/sanic-org/sanic/pull/1760) 在 websocket 路由中添加版本 + 参数 +- [#1866](https://github.com/sanic-org/sanic/pull/1866) 添加`sanic` + 作为入口点命令 - [#1880](https://github.com/sanic-org/sanic/pull/1880) Add handler names for websockets for url_for usage -**Bugfixes** - -- [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for - host parameter issue with lists -- [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static - _handler pickling error -- [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader - on OSX py38 and Windows -- [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse - named_response_middlware execution order, to match normal response - middleware execution order +**错误修复** + +- [#1776](https://github.com/sanic-org/sanic/pull/1776) + 主机参数问题的 Bug 修复 +- [#1842](https://github.com/sanic-org/sanic/pull/1842) 修复静态 + _处理程序拾取错误 +- [#1827](https://github.com/sanic-org/sanic/pull/1827) 在 OSX py38 和 Windows 上修复读取器 +- [#1848](https://github.com/sanic-org/sanic/pull/1848) 反向 + named_response_midlware execution order，以匹配正常的响应Order + 中间件执行顺序 - [#1853](https://github.com/sanic-org/sanic/pull/1853) Fix pickle error when attempting to pickle an application which contains websocket routes -**Deprecations and Removals** +**废弃和删除** -- [#1739](https://github.com/sanic-org/sanic/pull/1739) Deprecate - body_bytes to merge into body +- [#1739](https://github.com/sanic-org/sanic/pull/1739) 废弃 + body_bytes并入体 -**Developer infrastructure** +**开发者基础设施** -- [#1852](https://github.com/sanic-org/sanic/pull/1852) Fix naming - of CI test env on Python nightlies +- [#1852](https://github.com/sanic-org/sanic/pull/1852) 修复CI test env Python nightlies 上的 - [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust - websockets version to setup.py -- [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap - run()'s "protocol" type annotation in Optional[] + websockets 版本以设置py +- [#1869](https://github.com/sanic-org/sanic/pull/1869) 包装 + run()'s "protocol" 类型注释在选项[] -**Improved Documentation** +**改进文档** -- [#1846](https://github.com/sanic-org/sanic/pull/1846) Update docs - to clarify response middleware execution order -- [#1865](https://github.com/sanic-org/sanic/pull/1865) Fixing rst - format issue that was hiding documentation +- [#1846](https://github.com/sanic-org/sanic/pull/1846) 更新文档 + 以澄清响应中间件执行顺序 +- [#1865](https://github.com/sanic-org/sanic/pull/1865) 修复正在隐藏文档的 rst + 格式问题 -## Version 20.6.0 +## 版本20.6.0 -_Released, but unintentionally omitting PR #1880, so was replaced by -20.6.1_ +_释放但无意省略的 PR #1880，所以被 +20.6.1_ 取代。 -## Version 20.3.0 +## 版本20.3.0 -**Features** +**特征** - [#1762](https://github.com/sanic-org/sanic/pull/1762) Add `srv.start_serving()` and `srv.serve_forever()` to `AsyncioServer` - [#1767](https://github.com/sanic-org/sanic/pull/1767) Make Sanic - usable on `hypercorn -k trio myweb.app` -- [#1768](https://github.com/sanic-org/sanic/pull/1768) No - tracebacks on normal errors and prettier error pages -- [#1769](https://github.com/sanic-org/sanic/pull/1769) Code cleanup - in file responses -- [#1793](https://github.com/sanic-org/sanic/pull/1793) and - [#1819](https://github.com/sanic-org/sanic/pull/1819) Upgrade - `str.format()` to f-strings -- [#1798](https://github.com/sanic-org/sanic/pull/1798) Allow - multiple workers on MacOS with Python 3.8 -- [#1820](https://github.com/sanic-org/sanic/pull/1820) Do not set - content-type and content-length headers in exceptions - -**Bugfixes** - -- [#1748](https://github.com/sanic-org/sanic/pull/1748) Remove loop - argument in `asyncio.Event` in Python 3.8 + 可在 `hypercorn -k trio myweb.app` 上使用 +- [#1768](https://github.com/sanic-org/sanic/pull/1768) 没有 + 对正常错误和预审错误页面的跟踪 +- [#1769](https://github.com/sanic-org/sanic/pull/1769) 代码清理文件回复中的 +- [#1793](https://github.com/sanic-org/sanic/pull/1793)和 + [#1819](https://github.com/sanic-org/sanic/pull/1819) 将 + `str.form()` 升级为f-字符串。 +- [#1798](https://github.com/sanic-org/sanic/pull/1798) 允许 + MacOS 上与Python 3.8的多个工作者。 +- [#1820](https://github.com/sanic-org/sanic/pull/1820) 不在异常中设置 + 内容类型和内容长度标题 + +**错误修复** + +- [#1748](https://github.com/sanic-org/sanic/pull/1748) 移除在 Python 3.8 的`asyncio.Event` 中的 + 循环 - [#1764](https://github.com/sanic-org/sanic/pull/1764) Allow route decorators to stack up again -- [#1789](https://github.com/sanic-org/sanic/pull/1789) Fix tests - using hosts yielding incorrect `url_for` -- [#1808](https://github.com/sanic-org/sanic/pull/1808) Fix Ctrl+C - and tests on Windows +- [#1789](https://github.com/sanic-org/sanic/pull/1789) 使用产生错误的\`url_for'的主机修复 +- [#1808](https://github.com/sanic-org/sanic/pull/1808) 修正Ctrl+C + 和Windows 测试 -**Deprecations and Removals** +**废弃和删除** -- [#1800](https://github.com/sanic-org/sanic/pull/1800) Begin - deprecation in way of first-class streaming, removal of - `body_init`, `body_push`, and `body_finish` +- [#1800](https://github.com/sanic-org/sanic/pull/1800) 以一流的方式开始 + 弃置，移除 + `body_init`, `body_pub`和`body_finish` - [#1801](https://github.com/sanic-org/sanic/pull/1801) Complete deprecation from [#1666](https://github.com/sanic-org/sanic/pull/1666) of dictionary context on `request` objects. -- [#1807](https://github.com/sanic-org/sanic/pull/1807) Remove - server config args that can be read directly from app +- [#1807](https://github.com/sanic-org/sanic/pull/1807) 删除可直接从应用程序读取的 + 服务器配置 args - [#1818](https://github.com/sanic-org/sanic/pull/1818) Complete deprecation of `app.remove_route` and `request.raw_args` -**Dependencies** +**依赖** - [#1794](https://github.com/sanic-org/sanic/pull/1794) Bump `httpx` to 0.11.1 @@ -1071,50 +1066,50 @@ _Released, but unintentionally omitting PR #1880, so was replaced by `ASGIDispatch` from top-level `httpx` (from third-party deprecation) -**Developer infrastructure** +**开发者基础设施** -- [#1833](https://github.com/sanic-org/sanic/pull/1833) Resolve - broken documentation builds +- [#1833](https://github.com/sanic-org/sanic/pull/1833) 解决了 + 损坏的文档版本 -**Improved Documentation** +**改进文档** -- [#1755](https://github.com/sanic-org/sanic/pull/1755) Usage of +- [#1755](https://github.com/sanic-org/sanic/pull/1755) `response.empty()` - [#1778](https://github.com/sanic-org/sanic/pull/1778) Update README -- [#1783](https://github.com/sanic-org/sanic/pull/1783) Fix typo -- [#1784](https://github.com/sanic-org/sanic/pull/1784) Corrected - changelog for docs move of MD to RST +- [#1783](https://github.com/sanic-org/sanic/pull/1783) 修复类型 +- [#1784](https://github.com/sanic-org/sanic/pull/1784) 更正了 + 更改了 MD 移动到 RST ([#1691](https://github.com/sanic-org/sanic/pull/1691)) -- [#1803](https://github.com/sanic-org/sanic/pull/1803) Update - config docs to match DEFAULT_CONFIG -- [#1814](https://github.com/sanic-org/sanic/pull/1814) Update +- [#1803](https://github.com/sanic-org/sanic/pull/1803) 更新 + 配置文件以匹配DEFAULT_CONFIG +- [#1814](https://github.com/sanic-org/sanic/pull/1814) 更新 getting_started.rst -- [#1821](https://github.com/sanic-org/sanic/pull/1821) Update to - deployment -- [#1822](https://github.com/sanic-org/sanic/pull/1822) Update docs - with changes done in 20.3 -- [#1834](https://github.com/sanic-org/sanic/pull/1834) Order of - listeners +- [#1821](https://github.com/sanic-org/sanic/pull/1821) 更新到 + 部署 +- [#1822](https://github.com/sanic-org/sanic/pull/1822) 更新文档 + 并修改于 20.3 +- [#1834](https://github.com/sanic-org/sanic/pull/1834) + 侦听器顺序 -## Version 19.12.0 +## 版本19.12.0 -**Bugfixes** +**错误修复** -- Fix blueprint middleware application +- 修复蓝图中间件应用 - Currently, any blueprint middleware registered, irrespective of - which blueprint was used to do so, was being applied to all of the - routes created by the `@app` and `@blueprint` alike. + 目前，任何蓝图中间件都已注册，而不论 + 是用哪个蓝图来注册的。 正在应用于所有由 `@app` 和 `@bluprint` 创建的 + 路由。 - As part of this change, the blueprint based middleware application - is enforced based on where they are registered. + 作为此更改的一部分，基于蓝图的中间件应用程序 + 是根据它们的注册地点强制执行的。 - If you register a middleware via `@blueprint.middleware` then it will apply only to the routes defined by the blueprint. - - If you register a middleware via `@blueprint_group.middleware` - then it will apply to all blueprint based routes that are part - of the group. + - 如果您通过 `@bluprint_group.middleware` + 注册了一个中间软件，它将适用于所有基于蓝图的路由，这些路由属于群组的 + 部分。 - If you define a middleware via `@app.middleware` then it will be applied on all available routes ([#37](https://github.com/sanic-org/sanic/issues/37)) @@ -1127,15 +1122,15 @@ _Released, but unintentionally omitting PR #1880, so was replaced by [AttributeError]{.title-ref}. This fix makes the availability of [SERVER_NAME]{.title-ref} on our [app.config]{.title-ref} an optional behavior. - ([#1707](https://github.com/sanic-org/sanic/issues/1707)) + ([No. 1707](https://github.com/sanic-org/sanic/issues/1707)) -**Improved Documentation** +**改进文档** -- Move docs from MD to RST +- 将文档从MD移动到RST - Moved all docs from markdown to restructured text like the rest of - the docs to unify the scheme and make it easier in the future to - update documentation. + 将所有文档从Markdown移动到调整后的文本，如 + 的其他文档，统一方案并使它在未来更容易地更新到 + 更新文档。 ([#1691](https://github.com/sanic-org/sanic/issues/1691)) - Fix documentation for [get]{.title-ref} and [getlist]{.title-ref} of @@ -1146,386 +1141,386 @@ _Released, but unintentionally omitting PR #1880, so was replaced by [request.args]{.title-ref} behavior ([#1704](https://github.com/sanic-org/sanic/issues/1704)) -## Version 19.6.3 +## 版本19.6.3 -**Features** +**特征** -- Enable Towncrier Support +- 启用 Towncrier 支持 As part of this feature, [towncrier]{.title-ref} is being introduced as a mechanism to partially automate the process of generating and managing change logs as part of each of pull requests. - ([#1631](https://github.com/sanic-org/sanic/issues/1631)) + ([No. 1631](https://github.com/sanic-org/sanic/issues/1631)) -**Improved Documentation** +**改进文档** -- Documentation infrastructure changes +- 文件基础设施变化 - Enable having a single common [CHANGELOG]{.title-ref} file for both GitHub page and documentation - - Fix Sphinix deprecation warnings + - 修复 Sphinix 废弃警告 - Fix documentation warnings due to invalid [rst]{.title-ref} indentation - Enable common contribution guidelines file across GitHub and documentation via [CONTRIBUTING.rst]{.title-ref} ([#1631](https://github.com/sanic-org/sanic/issues/1631)) -## Version 19.6.2 +## 版本19.6.2 -**Features** +**特征** -- [#1562](https://github.com/sanic-org/sanic/pull/1562) Remove - `aiohttp` dependency and create new `SanicTestClient` based upon - [requests-async](https://github.com/encode/requests-async) -- [#1475](https://github.com/sanic-org/sanic/pull/1475) Added ASGI - support (Beta) +- [#1562](https://github.com/sanic-org/sanic/pull/1562) 去除 + `aiohttp` 依赖关系，并根据 + [requests-async](https://github.com/encode/requests-async) 创建新的`SanicTestClient` +- [#1475](https://github.com/sanic-org/sanic/pull/1475) 添加了ASGI + 支持(Beta) - [#1436](https://github.com/sanic-org/sanic/pull/1436) Add Configure support from object string -**Bugfixes** +**错误修复** -- [#1587](https://github.com/sanic-org/sanic/pull/1587) Add missing - handle for Expect header. +- [#1587](https://github.com/sanic-org/sanic/pull/1587) 添加缺失的 + 句柄给预期头部。 - [#1560](https://github.com/sanic-org/sanic/pull/1560) Allow to disable Transfer-Encoding: chunked. -- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix graceful - shutdown. +- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix 宽松的 + 关机。 - [#1594](https://github.com/sanic-org/sanic/pull/1594) Strict - Slashes behavior fix + 斜线行为修复 -**Deprecations and Removals** +**废弃和删除** - [#1544](https://github.com/sanic-org/sanic/pull/1544) Drop - dependency on distutil + 依附于打分上 - [#1562](https://github.com/sanic-org/sanic/pull/1562) Drop support for Python 3.5 -- [#1568](https://github.com/sanic-org/sanic/pull/1568) Deprecate - route removal. +- [#1568](https://github.com/sanic-org/sanic/pull/1568) 废弃 + 路由移动。 -.. warning:: Warning +.. 警告：：警告 ``` -Sanic will not support Python 3.5 from version 19.6 and forward. -However, version 18.12LTS will have its support period extended thru -December 2020, and therefore passing Python\'s official support version -3.5, which is set to expire in September 2020. +Sanic 将不支持 Python 3.5 版本的 19.6 和前进。 +然而，版本 18。 2LTS 将有其支持期延长期延时 +2020年12月，因此通过 Python\'s 官方支持版本 +3。 ，定于2020年9月到期。 ``` -## Version 19.3 +## 版本19.3 -**Features** +**特征** - [#1497](https://github.com/sanic-org/sanic/pull/1497) Add support for zero-length and RFC 5987 encoded filename for multipart/form-data requests. -- [#1484](https://github.com/sanic-org/sanic/pull/1484) The type of - `expires` attribute of `sanic.cookies.Cookie` is now enforced to - be of type `datetime`. +- [#1484](https://github.com/sanic-org/sanic/pull/1484) `sanic.cookies.cookie`的 + `expires`属性的类型现在被强制执行到 + 的类型是`datetime`。 -- [#1482](https://github.com/sanic-org/sanic/pull/1482) Add support - for the `stream` parameter of `sanic.Sanic.add_route()` available - to `sanic.Blueprint.add_route()`. +- [#1482](https://github.com/sanic-org/sanic/pull/1482) 添加支持 + 的`sanic.Sanic.add_route()` 的 + 至`sanic.Blueprint.add_route()` 。 -- [#1481](https://github.com/sanic-org/sanic/pull/1481) Accept - negative values for route parameters with type `int` or `number`. +- [#1481](https://github.com/sanic-org/sanic/pull/1481) 接受路径参数的 + 负值，类型为 `int` 或 `num` 。 -- [#1476](https://github.com/sanic-org/sanic/pull/1476) Deprecated - the use of `sanic.request.Request.raw_args` - it has a fundamental - flaw in which is drops repeated query string parameters. Added - `sanic.request.Request.query_args` as a replacement for the - original use-case. +- [#1476](https://github.com/sanic-org/sanic/pull/1476) 废弃了 + 的使用 `sanic.request.Request.raw_args` - 它有一个基本的 + 缺陷，它会丢弃重复查询字符串参数。 添加 + `sanic.request.Requery_args` 作为原始的 + use-case。 -- [#1472](https://github.com/sanic-org/sanic/pull/1472) Remove an - unwanted `None` check in Request class `repr` implementation. This - changes the default `repr` of a Request from `` to - `` +- [#1472](https://github.com/sanic-org/sanic/pull/1472) 移除请求类`repr`实现中的 + 意外的`None` 检查。 此 + 将请求的默认`repr` 从 ``改为 + \\` -- [#1470](https://github.com/sanic-org/sanic/pull/1470) Added 2 new - parameters to `sanic.app.Sanic.create_server`: +- [#1470](https://github.com/sanic-org/sanic/pull/1470) 添加2个新的 + 参数到 `sanic.app.Sanic.create_server` - - `return_asyncio_server` - whether to return an - asyncio.Server. + - `return_asyncio_server` - 是否返回 + asyncio.Server。 - `asyncio_server_kwargs` - kwargs to pass to `loop.create_server` for the event loop that sanic is using. > - This is a breaking change. + 这是一个突破性的变化。 -- [#1499](https://github.com/sanic-org/sanic/pull/1499) Added a set - of test cases that test and benchmark route resolution. +- [#1499](https://github.com/sanic-org/sanic/pull/1499) 添加了测试和基准路由分辨率为 + 的测试案例。 -- [#1457](https://github.com/sanic-org/sanic/pull/1457) The type of - the `"max-age"` value in a `sanic.cookies.Cookie` is now enforced - to be an integer. Non-integer values are replaced with `0`. +- [#1457](https://github.com/sanic-org/sanic/pull/1457) + 的类型在 `sanic.cookies.cookie` 中的 `max-age` 值现在是强制执行 + 为整数。 非整数值替换为 \`0'。 -- [#1445](https://github.com/sanic-org/sanic/pull/1445) Added the - `endpoint` attribute to an incoming `request`, containing the name - of the handler function. +- [#1445](https://github.com/sanic-org/sanic/pull/1445) 将 + `endpoint` 属性添加到传入的 `request` 中，包含处理器函数的 + 名称。 -- [#1423](https://github.com/sanic-org/sanic/pull/1423) Improved - request streaming. `request.stream` is now a bounded-size buffer - instead of an unbounded queue. Callers must now call - `await request.stream.read()` instead of - `await request.stream.get()` to read each portion of the body. +- [#1423](https://github.com/sanic-org/sanic/pull/1423) 改进了 + 请求流。 `request.stream` 现在是一个已退回的大小 + 而不是一个无限制的队列。 现在呼叫者必须调用 + `request.stream.read()` 而不是一个 + `required request.stream.get()` 以阅读身体的每一部分。 - This is a breaking change. + 这是一个突破性的变化。 -**Bugfixes** +**错误修复** - [#1502](https://github.com/sanic-org/sanic/pull/1502) Sanic was prefetching `time.time()` and updating it once per second to avoid - excessive `time.time()` calls. The implementation was observed to - cause memory leaks in some cases. The benefit of the prefetch - appeared to negligible, so this has been removed. Fixes + excessive `time.time()` calls. 观察到 + 在一些情况下造成内存泄漏。 预获取 + 的好处似乎微不足道，因此这个好处已被删除。 修复 [#1500](https://github.com/sanic-org/sanic/pull/1500) -- [#1501](https://github.com/sanic-org/sanic/pull/1501) Fix a bug in - the auto-reloader when the process was launched as a module i.e. - `python -m init0.mod1` where the sanic server is started in - `init0/mod1.py` with `debug` enabled and imports another module in - `init0`. -- [#1376](https://github.com/sanic-org/sanic/pull/1376) Allow sanic - test client to bind to a random port by specifying `port=None` - when constructing a `SanicTestClient` -- [#1399](https://github.com/sanic-org/sanic/pull/1399) Added the - ability to specify middleware on a blueprint group, so that all - routes produced from the blueprints in the group have the - middleware applied. -- [#1442](https://github.com/sanic-org/sanic/pull/1442) Allow the - the use the `SANIC_ACCESS_LOG` environment variable to - enable/disable the access log when not explicitly passed to - `app.run()`. This allows the access log to be disabled for example - when running via gunicorn. - -**Developer infrastructure** - -- [#1529](https://github.com/sanic-org/sanic/pull/1529) Update - project PyPI credentials -- [#1515](https://github.com/sanic-org/sanic/pull/1515) fix linter - issue causing travis build failures (fix #1514) -- [#1490](https://github.com/sanic-org/sanic/pull/1490) Fix python - version in doc build -- [#1478](https://github.com/sanic-org/sanic/pull/1478) Upgrade - setuptools version and use native docutils in doc build -- [#1464](https://github.com/sanic-org/sanic/pull/1464) Upgrade - pytest, and fix caplog unit tests - -**Improved Documentation** +- [#1501](https://github.com/sanic-org/sanic/pull/1501)修复了 + 自动读取加载器中的一个错误，当过程作为模块启动时， + "python -m init0.mod1", 在这种情况下, sanic server 开始于 + `init0/mod1.py` , 启用了 `debug` , 并在 + `init0` 中导入另一个模块. +- [#1376](https://github.com/sanic-org/sanic/pull/1376) 允许sanic + 测试客户端在构建一个 `port=None` + 时绑定到随机端口 +- [#1399](https://github)。 om/sanic-org/sanic/pull/1399)增加了 + 在蓝图组中指定中间件的能力。 所以从组中的蓝图中生成的所有 + 路径都应用了 + 中间件. +- [#1442](https://github.com/sanic-org/sanic/pull/1442) 允许 + 使用 `SANIC_ACCESS_LOG` 环境变量到 + 启用/禁用访问日志时未明确传递到 + `app.run()` 。 这将允许在使用枪炮运行时禁用访问日志，例如 + 。 + +**开发者基础设施** + +- [#1529](https://github.com/sanic-org/sanic/pull/1529) 更新 + 项目 PyPI 凭据 +- [#1515](https://github.com/sanic-org/sanic/pull/1515) fixed linter + issue causing travis building succession(fix #1514) +- [#1490](https://github.com/sanic-org/sanic/pull/1490) 修复python + 版本在编译中 +- [#1478](https://github.com/sanic-org/sanic/pull/1478) 升级 + 设置工具版本并在构建过程中使用本机文档 +- [#1464](https://github.com/sanic-org/sanic/pull/14644) 升级 + pytest 并修复capg 单元测试 + +**改进文档** - [#1516](https://github.com/sanic-org/sanic/pull/1516) Fix typo at - the exception documentation -- [#1510](https://github.com/sanic-org/sanic/pull/1510) fix typo in + 是例外文档 +- [#1510](https://github.com/sanic-org/sanic/pull/1510) fixe typo in Asyncio example - [#1486](https://github.com/sanic-org/sanic/pull/1486) - Documentation typo -- [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar + 文档类型 +- [#1477](https://github.com/sanic-org/sanic/pull/1477) 修理文法 in README.md -- [#1489](https://github.com/sanic-org/sanic/pull/1489) Added - "databases" to the extensions list -- [#1483](https://github.com/sanic-org/sanic/pull/1483) Add - sanic-zipkin to extensions list -- [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link - to deleted repo, Sanic-OAuth, from the extensions list +- [#1489](https://github.com/sanic-org/sanic/pull/1489) 添加 + "databases" 到扩展列表 +- [#1483](https://github.com/sanic-org/sanic/pull/1483) 在扩展列表中添加 + sanic-zipkin +- [#1487](https://github.com/sanic-org/sanic/pull/1487) 删除了链接 + 从扩展列表中删除 Sanic-OAuth, - [#1460](https://github.com/sanic-org/sanic/pull/1460) 18.12 changelog - [#1449](https://github.com/sanic-org/sanic/pull/1449) Add example of amending request object -- [#1446](https://github.com/sanic-org/sanic/pull/1446) Update +- [#1446](https://github.com/sanic-org/sanic/pull/1446) 更新 README -- [#1444](https://github.com/sanic-org/sanic/pull/1444) Update +- [#1444](https://github.com/sanic-org/sanic/pull/14444) 更新 README -- [#1443](https://github.com/sanic-org/sanic/pull/1443) Update - README, including new logo -- [#1440](https://github.com/sanic-org/sanic/pull/1440) fix minor - type and pip install instruction mismatch +- [#1443](https://github.com/sanic-org/sanic/pull/1443) 更新 + README，包括新的徽标 +- [#1440](https://github.com/sanic-org/sanic/pull/1440) 修复小的 + 类型和 pip安装指令不匹配 - [#1424](https://github.com/sanic-org/sanic/pull/1424) - Documentation Enhancements + 文档改进 -Note: 19.3.0 was skipped for packagement purposes and not released on -PyPI +注： 19.3.0 被跳过用于封装目的，没有在 +PyPI 上发布 -## Version 18.12 +## 18.12 版本 ### 18.12.0 -- Changes: +- 变更： - - Improved codebase test coverage from 81% to 91%. - - Added stream_large_files and host examples in static_file - document - - Added methods to append and finish body content on Request + - 代码片测试覆盖率从81%提高到91%。 + - 在static_file + 文档中添加串流大量文件和主机示例 + - 添加方法以在请求 (#1379) - - Integrated with .appveyor.yml for windows ci support - - Added documentation for AF_INET6 and AF_UNIX socket usage - - Adopt black/isort for codestyle - - Cancel task when connection_lost - - Simplify request ip and port retrieval logic - - Handle config error in load config file. - - Integrate with codecov for CI - - Add missed documentation for config section. - - Deprecate Handler.log - - Pinned httptools requirement to version 0.0.10+ - -- Fixes: - - - Fix `remove_entity_headers` helper function (#1415) - - Fix TypeError when use Blueprint.group() to group blueprint - with default url_prefix, Use os.path.normpath to avoid invalid - url_prefix like api//v1 f8a6af1 Rename the `http` module to - `helpers` to prevent conflicts with the built-in Python http - library (fixes #1323) - - Fix unittests on windows - - Fix Namespacing of sanic logger - - Fix missing quotes in decorator example - - Fix redirect with quoted param - - Fix doc for latest blueprint code - - Fix build of latex documentation relating to markdown lists - - Fix loop exception handling in app.py - - Fix content length mismatch in windows and other platform - - Fix Range header handling for static files (#1402) - - Fix the logger and make it work (#1397) - - Fix type pikcle->pickle in multiprocessing test - - Fix pickling blueprints Change the string passed in the - "name" section of the namedtuples in Blueprint to match the - name of the Blueprint module attribute name. This allows - blueprints to be pickled and unpickled, without errors, which - is a requirement of running Sanic in multiprocessing mode in - Windows. Added a test for pickling and unpickling blueprints + - Windows ci 支持与 .appveyor.yml 集成 + - 为 AF_INET6 和 AF_UNIX 套接字使用添加文档 + - 采用黑色/isort来换代币 + - 连接丢失时取消任务 + - 简化请求 ip 和端口检索逻辑。 + - 处理负载配置文件中的配置错误。 + - CI 与 codecov 集成 + - 为配置部分添加未接文档。 + - 已弃用 Handler.log + - 固定的 httptools 要求到版本 0.0.10 + + +- 修复： + + - 修复 `remove_entity_headers` 函数(#1415) + - 修复蓝图 + 蓝图使用默认的 url_prefix时，使用 os.path。 避免无效的 + url_prefix 像api//v1 f8a6af1 那样将`http` 模块重命名为 + `helpers` 以防止与内置的 Python HTp + 库 (fixes #1323) 发生冲突 + - 修复窗口上的无功者 + - 修复清理记录器命名空间 + - 修复装饰器示例中缺少的引用 + - 使用引用参数修复重定向 + - 修复最新蓝图代码 + - 修复与 Markdown 列表相关的 latex 文档构建。 + - 修复app.py 中的循环异常处理 + - 修复窗口和其他平台中的内容长度不匹配 + - 修复静态文件的范围头处理 (#1402) + - 修复记录器并使其工作 (#1397) + - 修复多处理测试中的 pikcle->选取的类型 + - 修复选取蓝图更改蓝图在蓝图中的 + "name" 部分中传递的字符串，以便匹配蓝图模块属性名称的 + 名称。 这使得 + 蓝图能够在没有错误的情况下被选取和卸载， + 是在 + Windows中以多处理模式运行Sanic的要求。 Added a test for pickling and unpickling blueprints Added a test for pickling and unpickling sanic itself Added a test for enabling multiprocessing on an app with a blueprint (only useful to catch this bug if the tests are run on Windows). - - Fix document for logging + - 修复日志文档 -## Version 0.8 +## 版本 0.8 **0.8.3** -- Changes: - - Ownership changed to org 'sanic-org' +- 变更： + - 所有权更改为 org 'sanic-org' **0.8.0** -- Changes: - - Add Server-Sent Events extension (Innokenty Lebedev) - - Graceful handling of request_handler_task cancellation (Ashley +- 变更： + - 添加服务器发送事件扩展 (Innokty Lebedev) + - 优化处理 request_handler_task 取消 (Ashley Sommer) - - Sanitize URL before redirection (aveao) - - Add url_bytes to request (johndoe46) - - py37 support for travisci (yunstanford) - - Auto reloader support for OSX (garyo) - - Add UUID route support (Volodymyr Maksymiv) - - Add pausable response streams (Ashley Sommer) - - Add weakref to request slots (vopankov) - - remove ubuntu 12.04 from test fixture due to deprecation - (yunstanford) - - Allow streaming handlers in add_route (kinware) - - use travis_retry for tox (Raphael Deem) - - update aiohttp version for test client (yunstanford) - - add redirect import for clarity (yingshaoxo) - - Update HTTP Entity headers (Arnulfo Solís) - - Add register_listener method (Stephan Fitzpatrick) - - Remove uvloop/ujson dependencies for Windows (abuckenheimer) - - Content-length header on 204/304 responses (Arnulfo Solís) - - Extend WebSocketProtocol arguments and add docs (Bob Olde + - 在重定向前Sanize URL (aveao) + - 添加url_bytes到请求 (johndoe46) + - py37 支持travisci(yunstanford) + - 自动装入器支持 OSX (garyo) + - 添加 UUID 路由支持 (Volodymyr Maksymiv) + - 添加可用响应流 (Ashley Sommer) + - 添加弱项到请求时段(vopankov) + - 由于废弃 + (yunstanford) 从测试灯具中移除 ubuntu 12.04 + - 允许在add_route (kinware) 中流媒体处理程序 + - 使用 travis_retry for tox (Raphael Deem) + - 更新测试客户端的 aiothttp 版本 (yunstanford) + - 添加重定向导导入以提高清晰度(yingshaoxo) + - 更新 HTTP 实体标题 (Arnulfo Solis) + - 添加注册监听方法 (Stephan Fitzpatrick) + - 删除 Windows 的 uvloop/ujson 依赖项 (abuckenheimer) + - 204/304答复的内容长度标题(Arnulfo Soli) + - 扩展 WebSocketProtocol 参数并添加文档 (Bob Olde Hampsink, yunstanford) - - Update development status from pre-alpha to beta (Maksim + - 更新开发状态从 alpha 到beta (Maksim Anisenkov) - - KeepAlive Timeout log level changed to debug (Arnulfo Solís) - - Pin pytest to 3.3.2 because of pytest-dev/pytest#3170 (Maksim + - KeepAlive 超时日志级别更改为调试(Arnulfo Soli) + - 因为pest-dev/pytest#3170 (Maksim Aniskenov) - - Install Python 3.5 and 3.6 on docker container for tests (Shahin + - 安装 Python 3.5 和 3.6 到码头容器进行测试 (Shahin Azad) - - Add support for blueprint groups and nesting (Elias Tarhini) - - Remove uvloop for windows setup (Aleksandr Kurlov) + - 添加支持蓝图组和嵌套(Elias Tarhini) + - 移除窗口设置的 uvloop(Aleksandr Kurlov) - Auto Reload (Yaser Amari) - - Documentation updates/fixups (multiple contributors) -- Fixes: - - Fix: auto_reload in Linux (Ashley Sommer) - - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) - - Fix: disable auto_reload by default on windows (abuckenheimer) - - Fix (1143): Turn off access log with gunicorn (hqy) - - Fix (1268): Support status code for file response (Cosmo Borsky) - - Fix (1266): Add content_type flag to Sanic.static (Cosmo Borsky) - - Fix: subprotocols parameter missing from add_websocket_route - (ciscorn) - - Fix (1242): Responses for CI header (yunstanford) - - Fix (1237): add version constraint for websockets (yunstanford) - - Fix (1231): memory leak - always release resource (Phillip Xu) - - Fix (1221): make request truthy if transport exists (Raphael + - 文档更新/修复(多个贡献者) +- 修复： + - 修复：Linux自动重新加载(Ashley Sommer) + - 修复：aiothttp >= 3.3.0 (Ashley Sommer) + - 修复：在窗口上默认禁用自动重新加载 (abuckenheimer) + - 修复 (1143)：用枪炮关闭访问日志 (hqy) + - 修复 (1268)：文件响应的支持状态代码 (Cosmo Borsky) + - 修复 (1266)：将 content_type 标志添加到 Sanic.statil (Cosmo Borsky) + - 修复：从add_websocket_route + 中缺少子协议参数(ciscorn) + - 修复 (1242)：CI 头的响应 (yunstanford) + - 修复 (1237): 添加 websockets 的版本约束 (yunstanford) + - 修复 (1231): 内存泄漏- 总是释放资源 (Phillip Xu) + - 修复 (1221)：如果存在传输，请提出truthy (Raphael Deem) - - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) - - Fix try_everything examples (PyManiacGR, kot83) - - Fix (1158): default to auto_reload in debug mode (Raphael Deem) - - Fix (1136): ErrorHandler.response handler call too restrictive + - 修复aiohttp>=3.1.0 (Ashley Sommer) + - 修复所有示例(PyManiacGR, kot83) + - 修复 (1158)：默认在调试模式下自动重新加载 (Raphael Deem) + - 修复 (1136): ErrorHandler.response 处理器调用限制性过强的 (Julien Castiaux) - - Fix: raw requires bytes-like object (cloudship) - - Fix (1120): passing a list in to a route decorator's host arg - (Timothy Ebiuwhe) - - Fix: Bug in multipart/form-data parser (DirkGuijt) - - Fix: Exception for missing parameter when value is null - (NyanKiyoshi) - - Fix: Parameter check (Howie Hu) - - Fix (1089): Routing issue with named parameters and different - methods (yunstanford) - - Fix (1085): Signal handling in multi-worker mode (yunstanford) - - Fix: single quote in readme.rst (Cosven) - - Fix: method typos (Dmitry Dygalo) - - Fix: log_response correct output for ip and port (Wibowo + - 修复：原始需要类似字节的对象 (云) + - 修复 (1120): 将列表传递到路由装饰器's host arg + (Timothy Ebiuwe) + - 修复：多部分/形式数据解析器中的错误(DirkGuijt) + - 修复：值为 null + 时缺少参数的异常(NyanKiyoshi) + - 修复：参数检查 (Howie Hu) + - 修复 (1089): 带有命名参数和不同的 + 方法的路由问题 (yunstanford) + - 修复(1085)：以多工模式处理信号(yunstanford) + - 修复：readme.rst中的单引号(成本) + - 修复：方法类型 (Dmitry Dygalo) + - 修复：Log_response 正确的IP和端口输出(Wibowo Arindrarto) - - Fix (1042): Exception Handling (Raphael Deem) - - Fix: Chinese URIs (Howie Hu) - - Fix (1079): timeout bug when self.transport is None (Raphael + - 修复(1042)：异常处理(Raphael Deem) + - 修正：中文 URI (Howie Hu) + - 修复 (1079)：当自己的传送无时超时 (Raphael Deem) - - Fix (1074): fix strict_slashes when route has slash (Raphael + - 修复 (1074)：在路由有斜线时修复 strit_slash(Raphael Deem) - - Fix (1050): add samesite cookie to cookie keys (Raphael Deem) - - Fix (1065): allow add_task after server starts (Raphael Deem) - - Fix (1061): double quotes in unauthorized exception (Raphael + - 修复 (1050): 将 samesite cookie 添加到 cookie keys (Raphael Deem) + - 修复 (1065)：允许在服务器启动后添加任务 (Raphael Deem) + - 修复 (1061)：在未经授权的异常中双引号 (Raphael Deem) - - Fix (1062): inject the app in add_task method (Raphael Deem) - - Fix: update environment.yml for readthedocs (Eli Uriegas) + - 修复 (1062)：将应用程序注入到 add_task 方法 (Raphael Deem) + - 修正: 更新 environment.yml for readthedocs (Eli Uriegas) - Fix: Cancel request task when response timeout is triggered (Jeong YunWon) - Fix (1052): Method not allowed response for RFC7231 compliance (Raphael Deem) - - Fix: IPv6 Address and Socket Data Format (Dan Palmer) + - 修复：IPv6 地址和 Socket 数据格式 (Dan Palmer) -Note: Changelog was unmaintained between 0.1 and 0.7 +注：更新日志保持在 0.1 和 0.7之间 -## Version 0.1 +## 版本 0.1 **0.1.7** -- Reversed static url and directory arguments to meet spec +- 反转静态URL和目录参数以适应spec **0.1.6** -- Static files -- Lazy Cookie Loading +- 静态文件 +- Lazy Cookie 加载 **0.1.5** -- Cookies -- Blueprint listeners and ordering -- Faster Router -- Fix: Incomplete file reads on medium+ sized post requests -- Breaking: after_start and before_stop now pass sanic as their - first argument +- Cookie +- 蓝图监听器和顺序 +- 快速路由器 +- 修复：在中等以上大小的帖子请求中读取不完整的文件 +- 断开︰ 事后开始和之前停止现在作为他们的 + 第一个参数 **0.1.4** -- Multiprocessing +- 多处理 **0.1.3** -- Blueprint support -- Faster Response processing +- 蓝图支持 +- 快速响应处理 **0.1.1 - 0.1.2** -- Struggling to update pypi via CI +- 通过 CI 更新 pypi 的字符串 **0.1.0** -- Released to public +- 向公众发布 From 5849c5ced192646f2fa91ceda0846e389c3bf042 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 11:20:16 +0200 Subject: [PATCH 459/698] New translations streaming.md (Japanese) --- guide/content/ja/guide/advanced/streaming.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/ja/guide/advanced/streaming.md b/guide/content/ja/guide/advanced/streaming.md index 71fb38b808..6382f6f9c2 100644 --- a/guide/content/ja/guide/advanced/streaming.md +++ b/guide/content/ja/guide/advanced/streaming.md @@ -109,21 +109,21 @@ async def index(request): await response.send(record[0]) ``` -`await response.eof()` を呼び出すことで、ストリームを明示的に終了させることができます。 これは `await response.send("", True)` を置き換える便利なメソッドです。 ハンドラがクライアントに送り返すものが何も残っていないと判断した _後に_ **1度だけ** 呼び出されるべきです。 Sanic サーバーで使用するのは_任意_ですが、Sanic を ASGI モードで実行している場合は、ストリームを明示的に終了させる必要があります。 +`await response.eof()` を呼び出すことで、ストリームを明示的に終了させることができます。 これは `await response.send("", True)` を置き換える便利なメソッドです。 ハンドラがクライアントに送り返すものが何も残っていないと判断した _後に_ **1度だけ** 呼び出されるべきです。 Sanic サーバーで使用するのは_任意_ですが、SanicをASGIモードで動作させている場合は、**必ず**明示的にストリームを終了させなければなりません。 -_v21.6_で`eof`を呼び出すことがオプションになりました +_v21.6で`eof`の呼び出しが任意になりました_ ## ファイルストリーミング -.. 列:: +.. column:: ``` -Sanic は `sanic.response.file_stream` 関数を提供しており、大きなファイルを送信したいときに便利です。 `StreamingHTTPResponse` オブジェクトを返し、デフォルトではチャンクされた転送エンコーディングを使用します。このため、Sanicはレスポンスに`Content-Length` HTTPヘッダーを追加しません。 +Sanicは、大きなファイルを送信する場合に便利な `sanic.response.file_stream` 関数を提供します。`StreamingHTTPResponse`オブジェクトを返し、デフォルトではチャンク転送エンコーディングを使用します。このため、Sanicはレスポンスに`Content-Length` HTTPヘッダーを追加しません。 -典型的なユースケースは、ビデオファイルをストリーミングすることでしょう。 +典型的な使用例は、ビデオファイルをストリーミングしている場合です。 ``` -.. 列:: +.. column:: ```` ```python @@ -141,13 +141,13 @@ async def handler_file_stream(request): ``` ```` -.. 列:: +.. column:: ``` -`Content-Length` ヘッダーを使用したい場合は、チャンク付き転送エンコーディングを無効にし、`Content-Length` ヘッダーを追加するだけで手動で追加できます。 +`Content-Length`ヘッダーを使用したい場合は、チャンク転送エンコーディングを無効にし、`Content-Length`ヘッダーを手動で追加するだけです。 ``` -.. 列:: +.. column:: ```` ```python From 76e9a4b6b7043b884c7a3edd1a74393a0de18af9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Jan 2024 11:20:17 +0200 Subject: [PATCH 460/698] New translations versioning.md (Japanese) --- guide/content/ja/guide/advanced/versioning.md | 72 +++++++++---------- 1 file changed, 34 insertions(+), 38 deletions(-) diff --git a/guide/content/ja/guide/advanced/versioning.md b/guide/content/ja/guide/advanced/versioning.md index 42120439fe..e630c6ede6 100644 --- a/guide/content/ja/guide/advanced/versioning.md +++ b/guide/content/ja/guide/advanced/versioning.md @@ -1,24 +1,24 @@ -# Versioning +# バージョン進行 -エンドポイントにバージョンを追加するためのAPI構築の標準的な方法です。 これにより、互換性のないエンドポイントを簡単に区別することができます。 +API構築では、エンドポイントにバージョンを追加するのが標準的な方法です。 これにより、互換性のないエンドポイントを簡単に区別することができます。 バージョンを追加すると、`/v{version}`のURLプレフィックスがエンドポイントに追加されます。 -バージョンは `int` 、`float` 、または `str` です。 許容可能な値: +バージョンは `int` 、`float` 、または `str` にすることができます。 許容値: - `1`, `2`, `3` - `1.1`, `2.25`, `3.0` - `"1"`、`"v1"`、`"v1.1"` -## ルートごと +## ルートごとのバージョン -.. 列:: +.. column:: ``` バージョン番号をルートに直接渡すことができます。 ``` -.. 列:: +.. column:: ```` ```python @@ -34,15 +34,15 @@ def handle_request(request): ``` ```` -## 設計図ごと +## Blueprintごとのバージョン -.. 列:: +.. column:: ``` -また、バージョン番号を blueprint に渡すこともできます。blueprint 内のすべてのルートに適用されます。 +Blueprintにバージョン番号を渡すこともできます。 これは、そのBlueprint内のすべてのルートに適用されます。 ``` -.. 列:: +.. column:: ```` ```python @@ -55,27 +55,23 @@ def handle_request(request): ``` ```` -## ブループリントグループごと +## Blueprintグループごとのバージョン -.. 列:: +.. column:: ``` -In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint -group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the -same information with a value specified while creating a blueprint instance. +バージョン化されたBlueprintの管理を簡素化するために、グループにバージョン番号を提供できます。Blueprintインスタンスを作成する際に指定された値で同じ情報を上書きしない場合、 その下方でグループ化されたすべてのBlueprintにも同じ情報が継承されます。 -When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to -the routes being registered. +バージョン管理にblueprintグループを使用する場合、ルートの登録中に以下の順序でバージョンプレフィックスが適用されます。 -1. Route Level configuration -2. Blueprint level configuration -3. Blueprint Group level configuration +1. ルートレベルの設定 +2. Blueprintレベルの設定 +3. Blueprintグループレベルの設定 -If we find a more pointed versioning specification, we will pick that over the more generic versioning specification -provided under the Blueprint or Blueprint Group +もし、より小さな単位でのバージョン管理仕様が見つかれば、BlueprintやBlueprintグループの下で提供される一般的なバージョン管理仕様よりも、そちらを選ぶことになります。 ``` -.. 列:: +.. column:: ```` ```python @@ -115,29 +111,29 @@ async def handle_endpoint_2_bp2(request): ``` ```` -## バージョン接頭辞： +## バージョンプレフィックス -上記のように、ルートに適用される`version`は、生成されたURIパスの最初のセグメントである**常に**です。 したがって、バージョンの前にパスセグメントを追加するために、 `version` 引数が渡されるすべての場所を渡すことができます。`version_prefix` も渡すことができます。 +上で見たように、ルートに適用される`version`は、**常に**生成されたURIパスの最初のセグメントになります。 したがって、バージョンの前にパスセグメントを追加できるように、`version`引数が渡されるすべての場所で、`version_prefix`を渡すこともできます。 -引数 `version_prefix` は以下のように定義できます： +引数 `version_prefix` は以下の場所で定義できます： -- `app.route` と `bp.route` デコレーター （そしてすべてのコンビニエンスデコレーターも） -- `Blueprint` インスタンス -- `Blueprint.group` コンストラクター -- `BlueprintGroup` インスタンス -- `app.blueprint` 登録 +- `app.route` と `bp.route` デコレーター (そして、すべての便利なデコレータ) +- `Blueprint`のインスタンス化 +- `Blueprint.group` コンストラクタ +- `BlueprintGroup`のインスタンス化 +- `app.blueprint` の登録 -複数の場所に定義がある場合、より具体的な定義はより一般的に優先されます。 このリストはその階層を提供します。 +複数の場所に定義がある場合、より具体的な定義はより一般的な定義を上書きします。 上のリストはそのヒエラルキーと対応しています。 `version_prefix` のデフォルト値は `/v` です。 -.. 列:: +.. column:: ``` -`/api` にバージョン管理されたルートをマウントできる機能がよくあります。これは `version_prefix` で簡単に実現できます。 +バージョン管理されたルートを `/api` にマウントしたいという状況がよくあります。これは`version_prefix`で簡単に実現できます。 ``` -.. 列:: +.. column:: ```` ```python @@ -146,13 +142,13 @@ app.route("/my/path", version=1, version_prefix="/api/v") ``` ```` -.. 列:: +.. column:: ``` -おそらく、`/api` ルートを単一の `BlueprintGroup` にロードすることでしょう。 +おそらく、より説得力のある使用法は、すべての`/api`ルートを単一の`BlueprintGroup`にロードすることです。 ``` -.. 列:: +.. column:: ```` ```python From 87de82f639438a31f8df63a57f320bde6fa11639 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 24 Jan 2024 12:50:23 +0200 Subject: [PATCH 461/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index bc0f1f67c5..3f0963004e 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -1,8 +1,8 @@ --- -title: 闪电快异步的 Python web 框架 +title: 闪电般快速的异步 Python 网络框架 layout: 首页 features: - - title: 简单和轻量度 + - title: 简单轻便 details: 智能默认和没有博客的直观API允许您直接建立您的应用程序。 - title: 无意见和灵活的 details: 构建你想要构建的方式而不让你的工具约束你。 From d6fa164288353ab698b54428c75356fb91311fb5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 24 Jan 2024 14:04:44 +0200 Subject: [PATCH 462/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 165 +++++++++++++++++++------------------- 1 file changed, 83 insertions(+), 82 deletions(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index 3f0963004e..624413675c 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -1,22 +1,22 @@ --- -title: 闪电般快速的异步 Python 网络框架 +title: 闪电般快速的异步 Python Web 框架 layout: 首页 features: - title: 简单轻便 - details: 智能默认和没有博客的直观API允许您直接建立您的应用程序。 - - title: 无意见和灵活的 - details: 构建你想要构建的方式而不让你的工具约束你。 - - title: 性能和可缩放 - details: 以速度和可伸缩性作为主要关切事项。 它已经准备好为无论大小的网络应用程序供电。 - - title: 生产已准备好 - details: 在盒子中，它被捆绑在一个网络服务器上，可以为您的网络应用程序提供电力。 - - title: 受数以百万计的信任的 - details: Sanic 是 PyPI 最受欢迎的框架之一，是启用异步的顶部框架 - - title: 社区驱动的 - details: 该项目由社区为社区维护和管理。 + details: 开箱即用，直观无臃肿且具有智能默认设置的框架 API 可以使您直接构建应用程序 + - title: 灵巧无束 + details: 按照您的意愿进行自由创建，不会对您造成任何约束 + - title: 易于拓展 + details: 关注应用的速度和可伸缩性 随时为大大小小的网络应用程序提供支持 + - title: 生产环境预备 + details: Sanic 不仅是一个框架，也是一个服务器，它可以随时为您编写的 Web 应用程序提供部署服务 + - title: 备受信赖 + details: Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步 Web 框架 + - title: 社区驱动 + details: 从社区来，到社区去，拥有大量的活跃贡献者 --- -### :hig_voltag: lightning-fast asynchronous Python web Framework +### :hig_voltag: 闪电般快速的异步 Python Web 框架 .. attrs:: :class: columns is-multiline mt-6 @@ -25,44 +25,44 @@ features: .. attrs:: :class: column is-4 - #### Simple and lightweight + #### 简单轻便 - Intuitive API with smart defaults and no bloat allows you to get straight to work building your app. + 开箱即用，直观无臃肿且具有智能默认设置的框架 API 可以使您直接构建应用程序 .. attrs:: :class: column is-4 - #### Unopinionated and flexible + #### 灵巧无束 - Build the way you want to build without letting your tooling constrain you. + 按照您的意愿进行自由创建，不会对您造成任何约束 .. attrs:: :class: column is-4 - #### Performant and scalable + #### 易于拓展 - Built from the ground up with speed and scalability as a main concern. It is ready to power web applications big and small. + 关注应用的速度和可伸缩性，可随时为大大小小的网络应用程序提供支持 .. attrs:: :class: column is-4 - #### Production ready + #### 生产环境预备 - Out of the box, it comes bundled with a web server ready to power your web applications. + Sanic 不仅是一个框架，也是一个服务器，它可以随时为您编写的 Web 应用程序提供部署服务 .. attrs:: :class: column is-4 - #### Trusted by millions + #### 备受信赖 - Sanic is one of the overall most popular frameworks on PyPI, and the top async enabled framework + Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步 Web 框架 .. attrs:: :class: column is-4 - #### Community driven + #### 社区驱动 - The project is maintained and run by the community for the community. + 从社区来，到社区去，拥有大量的活跃贡献者 ``` .. attrs:: @@ -79,12 +79,12 @@ features: **和一些 {span:has-text-primary:you wouldn't believe}.** ``` -.. 标签：生产等级 +.. tab:: 生产级别（Production-grade） ```` -After installing, Sanic has all the tools you need for a scalable, production-grade server—out of the box! +在安装后，Sanic 将为您提供开箱即用的可扩展生产级服务器所需的所有工具！ -Including [full TLS support](/en/guide/how-to/tls). +甚至包括[完整的 TLS 支持](/zh/guide/how-to/tls)。 ```python from sanic import Sanic @@ -110,7 +110,7 @@ sanic path.to.server:app ``` ```` -.. 标签：TLS服务器 +.. tab:: TLS 服务器（TLS server） ```` 启用 TLS 来运行Sanic与传递文件路径一样简单... @@ -131,10 +131,11 @@ sanic 路径。 o.server:app --dev --auto-tls ``` ```` -.. 标签：Websockets +.. tab:: Websockets ```` -Up and running with websockets in no time using the [websockets](https://websockets.readthedocs.io) package. +通过 [websockets](https://websockets.readthedocs.io) 库，可以马上实现的 WebSockets。 + ```python from sanic import Request, Websocket @@ -145,17 +146,17 @@ async def feed(request: Request, ws: Websocket): ``` ```` -.. 标签：静态文件 +.. tab:: 静态文件（Static files） ```` -服务静态文件当然是直观和容易的。只需命名一个端点和一个应该服务的文件或目录。 +建立静态文件服务当然是既直观又容易。只需要给一个端点以及一个需要被服务的文件或目录命名即可。 ```python app.static("/", "/path/to/index.html") -应用。 tatic("/uploads/", "/path/to/uploads/") +app.static("/uploads/", "/path/to/uploads/") ``` -此外，服务目录还有两个额外功能：自动服务索引，自动服务于文件浏览器。 +此外，为目录提供服务还有两个附加功能：自动提供索引和自动提供文件浏览器。 Sanic 可以自动将 `index.html` (或任何其他命名文件) 作为目录或其子目录中的索引页。 @@ -163,17 +164,17 @@ Sanic 可以自动将 `index.html` (或任何其他命名文件) 作为目录或 app.static( "/uploads/", "/path/to/uploads/", - index="索引。 -() + index="index.html" +) ``` -And/or 设置Sanic 以显示文件浏览器。 +之后，设置 Sanic 以显示文件浏览器。 -！[image](/assets/images/directory-view.png) +![image](/assets/images/directory-view.png) ```python -app tatic( +app.static( "/uploads/", "/path/to/uploads/", directory_view=True @@ -181,10 +182,10 @@ app tatic( ``` ```` -.. tab：生命周期： +.. tab:: 生命周期（Lifecycle） ```` -Beginning or ending a route with functionality is as simple as adding a decorator. +添加一个装饰器，就能够应用一个在请求开始或是响应结束时的功能性的路由。 ```python @app.on_request @@ -196,7 +197,7 @@ async def custom_banner(request, response): response.headers["X-Foo"] = request.ctx.foo ``` -Same with server events. +服务器事件（server events）也是一样的。 ```python @app.before_server_start @@ -208,14 +209,14 @@ async def setup_db(app): await app.ctx.db_pool.shutdown() ``` -But, Sanic also allows you to tie into a bunch of built-in events (called signals), or create and dispatch your own. +除此之外，Sanic 还允许您绑定一系列内置事件（称为信号），或创建和调度自己的事件。 ```python -@app.signal("http.lifecycle.complete") # built-in +@app.signal("http.lifecycle.complete") # 内建 async def my_signal_handler(conn_info): print("Connection has been closed") -@app.signal("something.happened.ohmy") # custom +@app.signal("something.happened.ohmy") # 定制 async def my_signal_handler(): print("something happened") @@ -223,38 +224,38 @@ await app.dispatch("something.happened.ohmy") ``` ```` -.. 标签：智能错误处理 +.. tab:: 智能错误处理（Smart error handling） ```` -提升错误会直观地导致正确的 HTTP 错误： +出错后，会出现直观且准确的 HTTP 错误： -``python -raising sanic.exception。 ootFound # 自动响应HTTP 404 -`` +```python +raise sanic.exceptions.NotFound # 自动响应 HTTP 404 +``` -或是你自己： +或是实现您自己的： ```python -xceptions import SanicException +from sanic.exceptions import SanicException class TeapotError(SanicException): status_code = 418 - message = “对不起，” 我不能酿造咖啡” + message = "抱歉，我不能煮咖啡Orz" -提高Teapot错误 +raise TeapotError ``` -当发生错误时， Sanic美丽的 DEV 模式错误页面将帮助您快速钻到漏洞。 +如果出现错误，Sanic 美观的开发模式错误页面将帮助您快速定位到错误所在。 -！[image](../assets/images/error-div-zero.png) +![image](../assets/images/error-div-by-zero.png) -不管怎样，Sanic带有一个算法，尝试使用HTML，JSON或文本错误作为相应答复。 别担心，设置和自定义您的错误处理符合您的具体需要是非常简单的。 +无论如何，Sanic 自带的算法都会根据情况尝试响应 HTML、JSON 或基于文本的错误。不要担心，根据您的具体需求设置和自定义错误处理非常简单。 ```` -.. 选项卡：应用查看器 +.. tab:: 应用查看器（App Inspector） ```` -Check in on your live, running applications (whether local or remote). +不管是在本地还是在远程，Sanic 都可以检查你正在运行的应用。 ```sh sanic inspect @@ -290,45 +291,45 @@ Sanic-Inspector-0 starts: 1 ``` -And, issue commands like `reload`, `shutdown`, `scale`... +并且可以使用像是 `reload`, `shutdown`, `scale` 的命令... ```sh sanic inspect scale 4 ``` -... or even create your own! +... 甚至是创建你自己的！ ```sh sanic inspect migrations ``` ```` -.. 标签：可扩展 +.. tab:: 可扩展（Extendable） ``` -In addition to the tools that Sanic comes with, the officially supported [Sanic Extensions](./plugins/sanic-ext/getting-started.md) provides lots of extra goodies to make development easier. - -- **CORS** protection -- Template rendering with **Jinja** -- **Dependency injection** into route handlers -- OpenAPI documentation with **Redoc** and/or **Swagger** -- Predefined, endpoint-specific response **serializers** -- Request query arguments and body input **validation** -- **Auto create** HEAD, OPTIONS, and TRACE endpoints -- Live **health monitor** +除了 Sanic 自带的工具外，官方支持的 [Sanic 扩展](./plugins/sanic-ext/getting-started.md) 还提供了许多额外的好东西，使您的开发更加轻松。 + +- **CORS** 保护 +- 使用 **Jinja** 进行模板渲染 +- 将其他对象通过 **Dependency injection** （依赖注入）到路由处理程序中 +- 使用 **Redoc** 和/或 **Swagger** 编写 OpenAPI 文档 +- 预定义的特定端点响应**序列化器**（serializers） +- 请求查询参数和正文输入的**验证器**（validation） +- **自动创建** HEAD、OPTIONS 和 TRACE 端点（auto create） +- 实时**健康监控**（health monitor） ``` -.. 标签：开发者体验 +.. tab:: 开发体验（Developer Experience） ``` -Sanic is **built for building**. +Sanic **为构建而生**。 -From the moment it is installed, Sanic includes helpful tools to help the developer get their job done. +从安装的那一刻起，Sanic 就包含帮助开发人员完成工作的有用工具。 -- **One server** - Develop locally in DEV mode on the same server that will run your PRODUCTION application -- **Auto reload** - Reload running applications every time you save a Python file, but also auto-reload **on any arbitrary directory** like HTML template directories -- **Debugging tools** - Super helpful (and beautiful) [error pages](/en/guide/best-practices/exceptions) that help you traverse the trace stack easily -- **Auto TLS** - Running a localhost website with `https` can be difficult, [Sanic makes it easy](/en/guide/how-to/tls) -- **Streamlined testing** - Built-in testing capabilities, making it easier for developers to create and run tests, ensuring the quality and reliability of their services -- **Modern Python** - Thoughtful use of type hints to help the developer IDE experience +- **单个服务器** - 在将运行生产应用程序的同一服务器上以开发模式进行本地开发 +- **自动重载** - 每次保存 Python 文件时重载正在运行的应用程序，也可在**任意目录**下自动重载，如 HTML 模板目录。 +- **调试工具** - 超级有用（而且漂亮）的[错误页面](/zh/guide/best-practices/exceptions)，帮助你轻松遍历跟踪堆栈 +- **自动 TLS** - 使用 "https" 运行本地主机网站可能很困难，但是 [Sanic 让它变得简单](/zh/guide/how-to/tls) +- **简化测试** - 内置测试功能，使开发人员更容易创建和运行测试，确保服务的质量和可靠性 +- **现代 Python**- 体贴地使用类型提示，帮助开发人员获得集成开发环境体验 ``` From 2edbb156661415d52c7d9c170fb99264e19e2a03 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 24 Jan 2024 14:04:45 +0200 Subject: [PATCH 463/698] New translations help.md (Chinese Simplified) --- guide/content/zh/help.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/guide/content/zh/help.md b/guide/content/zh/help.md index d07461ed22..59b95936f5 100644 --- a/guide/content/zh/help.md +++ b/guide/content/zh/help.md @@ -1,32 +1,32 @@ --- -title: 需要一些帮助吗？ -layout: 主要的 +title: 需要帮助吗？ +layout: 主界面 --- -# 需要一些帮助吗？ +# 需要帮助吗？ -作为一个活跃的开发者社区，我们努力相互支持。 如果您需要一些帮助，请尝试以下一种： +作为活跃的开发者社区，我们尽力相互支持。 如果您需要帮助，请尝试以下中的一种： -.. 列: +.. column:: ``` ### Discord :speech_cloon: -最好在[Discord服务器]上开启快速答案和在线聊天 +快速答案与在线聊天的最好出处 -`#sanic-support` 频道(https://discord.gg/FARQzAEMAA) +[Discord 服务器]的 `#sanic-support` 频道(https://discord.gg/FARQzAEMAA) ``` -.. 列: +.. column:: ``` ### 社区论坛 👥 -最好分享代码片段和更长时间的支持查询 +分享代码片段或是请求更长时间的支持最好在这里 -"Questions and Help" categories on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) +[论坛](https://community.sanicframework.org/c/questions-and-help/6)上的「问题与帮助」（Questions and Help） ``` *** -我们还积极监视[堆栈溢出](https://stackoverflow.com/questions/tagged/sanic)上的\`[sanic]'标签。 +我们还积极监视 [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic) 上的\`[sanic]'标签。 From 2eaf3258dc12731691346adfaab5d34a437d075a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 24 Jan 2024 15:40:59 +0200 Subject: [PATCH 464/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index 624413675c..bbf2cd1510 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -76,7 +76,7 @@ features: :class: is-size-3 ml-6 ``` -**和一些 {span:has-text-primary:you wouldn't believe}.** +**还有一些{span:has-text-primary:您甚至不敢相信的}。** ``` .. tab:: 生产级别（Production-grade） From 74dfddb2b957e5c1d99c0ad8285397566a8978d7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 24 Jan 2024 15:41:00 +0200 Subject: [PATCH 465/698] New translations built-with-sanic.md (Chinese Simplified) --- guide/content/zh/built-with-sanic.md | 56 ++++++++++++++-------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/guide/content/zh/built-with-sanic.md b/guide/content/zh/built-with-sanic.md index 72b8f3445d..ed2b9b4a10 100644 --- a/guide/content/zh/built-with-sanic.md +++ b/guide/content/zh/built-with-sanic.md @@ -1,67 +1,67 @@ --- -title: 全速前进-我们如何用Sanic 构建这个站点 -layout: 主要的 +title: 全速向前——我们如何通过 Sanic 构建这个站点 +layout: 主界面 --- .. attrs:: :class: title ``` -前方全速： +全速向前： ``` .. attrs:: :class: subtitle ``` -我们如何用Sanic构建这个站点 +我们如何通过 Sanic 构建这个站点 ``` -欢迎来到我们的互联网的小角落，我们自豪地说，“是的，我们用Sanic建造了这个！” 这不仅仅是一个网站；它是我们的游戏场、我们的测试实验室、我们的战场以及我们的家中。 +欢迎来到这个互联网中我们可以自豪地说，「是的，我们用 Sanic 建造了这个！」的小角落。 这里不仅仅是一个网站，也是我们的游戏场、测试实验室、战场以及家里。 ![](/assets/images/build-sanic.png) -### 故事：“我们喝我们自己的冠军” +### 故事：「我们饮下自酿的香槟」 -我们非常相信萨尼克语，我们决定对它进行最终测试——运行我们自己的网站。 它就像在他们自己的餐馆吃奶酪，只有在食物中毒的风险较低的情况下才能吃饭。 +我们非常相信 Sanic，因此我们决定对它进行最终测试——运行我们自己的网站。 就像在自家的餐馆里的厨师，只有在食物中毒的风险很低很低的情况下才敢畅怀开吃。 -为什么？ 因为建立网站或网页应用程序是硬性的。 现在有无数令人感动的部分，挑战太多，始终需要速度和可靠性。 我们只想向你展示你的很多方法之一。 +那么为什么？ 因为建立网站或网络应用程序是困难的。 这里有数不清的活动部件、大量的挑战，以及对速度和可靠性无时不在的需求。 我们只想向您展示你_可以_ 实现的很多方法之一。 -在这个高风险的数字厨房中，萨尼克是我们的秘密成分。 通过在Sanic上部署我们自己的网站，我们不只是展示自己的能力；我们正在现实世界中对它们进行压力测试。 这是我们走路的机会，证明萨尼克在纸面上不是好事——这是一种强有力的， 从最小的博客到最繁忙的电子商务站点都能够处理所有的问题，这种框架可以是高性能的框架。 +在这个高风险的数字厨房中， Sanic 是我们的秘方。 通过 Sanic 部署我们自己的网站，我们不只是展示自己的能力，我们正让现实世界对 Sanic 进行压力测试。 这是我们大显身手的机会，证明 Sanic 不只是纸上谈兵，它还是一个强大稳健的高性能框架，可以处理所有场景，从最简单的博客到最繁忙的电子商务网站。 -因此，我们在这里打着我们自己的旗手，相信我们知道如果萨尼克能够管理我们的场地，它也能够为你提供电力。 喜欢按思考的速度编程！ 🥂 +因此，我们在这里啜饮着自己酿造的香槟，自信满满，如果 Sanic 能够运行我们的网站，它也能为您的网站提供动力。 向可以按照灵感迸发的速度编码干杯！ 🥂 -### 设置：数字大洋，奥霍！ +### 安装：数字的汪洋大海，啊哈！ -我们启动了我们在数字大洋应用平台上的网站，因为我们喜欢高性能的云端航行。 认为它在云端有一个Ferrari-快速、睡觉，但更容易处理。 +我们启动了我们在 DigitalOcean App Platform 上的网站，因为我们喜爱高性能的云端航行。 这就好比在云上拥有一辆法拉利跑车——快速、美观，而且易于操作。 -为什么要简化？ 有了一个精干的团队，没有德沃普斯大家，我们需要一种不引信、直截了当的解决办法。 数字海洋为我们提供了顺利航行平台作为服务的经验。 它对满足我们的需要是完美的：轻松设置、自动部署以及让你睡觉的可靠性。 +为何求简？ 有简单的团队而没有开发运维专家，我们需要一种不大费周章、直截了当的解决办法。 DigitalOcean 为我们提供了顺利航行的平台既服务（PaaS）的经验。 它完美地满足我们的需要：轻松设置、自动部署以及让你可以安稳睡觉的可靠性。 -我们的选择反映了我们的精神：注重你的优势，让平台进行繁重的提升。 对我们来说，这意味着用萨尼克创造惊人的网络经验，辅之以一个简单但强有力的部署解决办法。 ⛵ +我们的选择反映了我们的理念：专注于自己的优势，而让平台负责繁重的工作。 对我们来讲，这意味着通过 Sanic 创造惊人的网络经验，并由简单而强大的部署解决方案提供支持。 ⛵ -### 代码: GitHub的位置 +### 代码：GitHub 就是它的位置 -我们的所有代码都在开放式中，将公众审查的光荣放在GitHub 上。 为什么隐藏魔法？ 它正好在这里，全文看到[我们的GitHub 仓库](https://github.com/sanic-org/sanic/tree/main/guide)。 继续前进，拿起宠物，派生它，用它玩游戏，打断它(然后修复它)。 +我们的所有代码都是开放的，并在 GitHub 上接受公众的监督。 为何遮掩魔法？ 它在[我们的 GitHub 仓库](https://github.com/sanic-org/sanic/tree/main/guide)中。 来吧，看一看， fork 一 fork ，玩一玩，弄坏它（最好再好心地修好它）。 -开放源码不仅仅是我们的蜂窝；这是我们的灵魂。 这是为了共同建立比我们更大的东西。 我们的守则证明了合作创新，是发展的游乐场，也是实际行动中的“圣经”的例子。 +对我们来说，「开源」不仅仅是浮于表现的流行语，还是我们的理念与灵魂。 是为了我们，可以共同创建比我们还要大的东西。 我们的代码是协作创新的见证，是开发的乐园，也是 Sanic 在行动中的真实案例。 -每一行代码，每项承诺都反映出我们用Sanic的旅程，展示我们如何利用其速度和可扩展性。 您的贡献，不管是修复bug，建议一个功能，还是改进文档，都是推动这个项目前进的因素。 +每一行代码每一次提交，都反映出我们与 Sanic 的旅程，展示我们如何利用其速度和可扩展性。 您的贡献，不管是修复 bug 、建议一个功能，或是改进文档，都是推动这个项目前进的因素。 -所以，潜入，贡献你的基因，让我们继续以萨尼语塑造网络发展的未来。 我们一起不仅仅是编码——我们正在创建一个社区驱动的电台。 🚀 +所以，来吧，贡献你的想法你的解决方案，让我们继续通过 Sanic 创建网络发展的未来。 我们不仅仅是编写代码——我们正在创建一个由社区驱动的发电站。 🚀 -### 邀请：写入，代码，Break，Fix！ +### 邀请：写，码，破，立！ -- **Documentarians**：喜欢制作复杂的物品很容易？ 我们的文档是你的画布。 用文字涂掉！ 🎨 +- **记录者**： 喜欢把复杂的东西说得简单明了？ 我们的文档是你的画布。 键盘当画笔的那种！ 🎨 -- **Code Ninjas**: 查找bug? Squash 'em. 有主意？ Code 'em. 让拉取请求降雨！ 🥷 +- **代码忍者**：找到了 bug ? 打得他们落花流水！ 有想法？ 码出来！ 让拉取请求降雨！ 🥷 -- **Bug Hunters**：如果你发现了缺陷，不只是污点。 让我们知道吧。 我们很喜欢寻找一个很好的漏洞。 🐛 +- **Bug 猎人**：如果你发现了 bug ，不要光盯着。 告诉我们吧。 我们很喜欢好的 bug 猎人。 🐛 -### 底线 +### 写在最后 -我们用萨尼克建造这个网站来显示它可以做些什么。 它很快，很有趣，是我们使用的。 因此，如果事物迅速负荷，就把我们推倒在后面。 如果他们不是，好吧... 我们指责宇宙射线吗？ +我们用 Sanic 建造这个网站来展示给大家它可以做些什么。 它很快，很有趣，也是我们正在使用的。 嗯，如果真的加载得很快的话，那就呱唧呱唧。 如果不是这样，嗯... 我们就怪... 宇宙射线？ -加入我们不仅是好的，而且是好的！ +加入我们，让 Sanic 不仅好，还好到让人叫妈妈！ -欢呼， -Sanic 团队(有时戴帽子) +干杯🍻， +（偶尔也穿斗篷的） Sanic 团队敬上 From dc8d6e82b7a45b612e57830c191b4a73def59b5b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 24 Jan 2024 15:41:01 +0200 Subject: [PATCH 466/698] New translations app-loader.md (Chinese Simplified) --- guide/content/zh/guide/running/app-loader.md | 30 ++++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/zh/guide/running/app-loader.md b/guide/content/zh/guide/running/app-loader.md index 11eb6ecdec..3872b97fcb 100644 --- a/guide/content/zh/guide/running/app-loader.md +++ b/guide/content/zh/guide/running/app-loader.md @@ -1,18 +1,18 @@ --- -title: 动态应用程序 +title: 动态应用 --- -# 动态应用程序 +# 动态应用（Dynamic Applications） -正在运行的Sanic已被优化，以配合CLI。 如果你还没有阅读它，你应该阅读 [Running Sanic](./running.md#sanic-server) 来熟悉这些选项。 +我们优化了通过命令行来运行 Sanic 应用的过程。 如果您还不了解的话，最好在读这篇文章前去看一下 [运行 Sanic](./running.md#sanic-server) 以获取一些详细的信息。 -.. 列: +.. column:: ``` -这包括将其作为全局范围对象运行... +既可以指定全局变量来启动应用： ``` -.. 列: +.. column:: ```` ```sh @@ -28,13 +28,13 @@ async def handler(request: Request): ``` ```` -.. 列: +.. column:: ``` -...或者创建一个 `Sanic` 应用程序对象的工厂函数。 +也可以指定某创建 Sanic 对象的工厂函数来启动： ``` -.. 列: +.. column:: ```` ```sh @@ -53,17 +53,17 @@ def create_app(): ``` ```` -**有时候，这还不够... 🤔** +**但有些时候，这还不够... 🤔** -引入于 [v22.9](../release-notes/v22.9.md)，萨尼克有一个`AppLoader` 对象，负责在各种[工人进程](./manager.md#how-sanic-server-starts-process)中创建一个应用程序。 如果你需要为你的应用程序创建一个更动态的启动体验，你可以利用这个机会。 +在 [v22.9](../release-notes/v22.9.md) 的版本中，Sanic 添加了负责在各个[工作进程](./manager.md#how-sanic-server-starts-process)中创建一个应用程序的 `AppLoader` 。 如果你需要更加「动态」的运行体验，那可以用一下它。 -.. 列: +.. column:: ``` -一个 `AppLoader` 可以传递一个传唤函数返回一个 `Sanic` 实例。这个`AppLoader` 可以与运行 API 的低级别应用程序一起使用。 +我们可以将一个能够返回 `Sanic` 实例的工厂函数给 `AppLoader` 。`AppLoader` 可以和更底层的运行应用的 API 一起使用。 ``` -.. 列: +.. column:: ```` ```python @@ -95,4 +95,4 @@ python path/to/server.py MyTestAppName ``` ```` -在上面的例子中，`AppLoader` 是用`factory`创建的，它可以用来在整个过程中创建同一应用程序的副本。 在这样做时，您应该明确使用上面显示的 `Sanic.serve` 模式，以便您创建的 `AppLoader` 不会被替换。 +在这个例子中，`AppLoader` 与 `factory` 传入的可用于在不同进程中创建同一应用的拷贝的函数一起被创建。 然后您需要显式地使用 `Sanic.serve` ，这样您的 `AppLoader` 就不会被自动生成的应用替换。 From b91b1810b7cb5f91852f723a93b07345f48d32f4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 30 Jan 2024 17:35:00 +0200 Subject: [PATCH 467/698] New translations class-based-views.md (Chinese Simplified) --- .../zh/guide/advanced/class-based-views.md | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/guide/content/zh/guide/advanced/class-based-views.md b/guide/content/zh/guide/advanced/class-based-views.md index 94d5c9dd94..59241cd4af 100644 --- a/guide/content/zh/guide/advanced/class-based-views.md +++ b/guide/content/zh/guide/advanced/class-based-views.md @@ -5,11 +5,11 @@ .. 列: ``` -### 问题 +### 问题所在 -设计一个 API 时常见的模式是在依赖HTTP 方法的同一个端点上具有多个功能。 +设计 API 时的常见思路是在根据 HTTP 请求方法的不同而产生不同响应的同一端点上实现多种功能。 -虽然这两种选项都起作用，但它们并不是良好的设计做法，随着你的项目的发展，可能很难长期维持。 +虽然这两种选项都可以，但它们并不是良好的设计思维，随着你的项目的发展，可能很难长期维护。 ``` .. 列: @@ -44,9 +44,9 @@ async def bar(request): .. 列: ``` -### 解析器 +### 解决方案 -基于类的视图只是实现回应行为的类类。 它们为在同一端点将不同HTTP请求类型的处理分割开来提供了一条途径。 +基于类的视图只是实现请求响应行为的类。 它们提供了一种在同一端点划分不同 HTTP 请求类型的处理方法。 ``` .. 列: @@ -69,24 +69,24 @@ app.add_route(FooBar.as_view(), "/foobar") ``` ```` -## 定义视图(Defining a view) +## 定义一个视图 -A class-based view should subclass :class:`sanic.views.HTTPMethodView`. 然后您可以执行具有相应的 HTTP 方法名称的类方法。 如果收到一个没有定义方法的请求，将生成一个 \`405: 方法不允许' 响应。 +基于类的视图应当继承 :class:`sanic.views.HTTPMethodView`。 然后，您可以使用相应 HTTP 方法的名称来实现类方法。 如果收到一个没有定义方法的请求，将生成一个 \`405: Method not allowed' 响应。 .. 列: ``` -要在端点注册一个基于类的视图，将使用 `app.add_route` 方法。 第一个参数应该是使用`as_view`方法的定义类，第二个参数应该是URL终点。 +要在一个 URL 端点注册一个基于类的视图，需要使用 `app.add_route` 方法。 第一个参数应该是实现了`as_view`方法的定义类，第二个参数应该是 URL 端点。 可用的方法是： - get -- 发表 -- 放置 -- 补丁 -- 删除 -- 首长 -- 选项 +- post +- put +- patch +- delete +- head +- options ``` .. 列: @@ -101,7 +101,7 @@ class SimpleView(HTTPMethodView): def get(self, request): return text("I am get method") - # You can also use async syntax + # 也支持 async 语法 async def post(self, request): return text("I am post method") @@ -123,7 +123,7 @@ app.add_route(SimpleView.as_view(), "/") .. 列: ``` -您可以使用路径参数就像[路由部分](/guide/basics/routing.md)中讨论过的路径参数。 +您可以完全按照[路由部分](/guide/basics/routing.md)中讨论的方式使用路径参数。 ``` .. 列: @@ -139,11 +139,11 @@ app.add_route(NameView.asp.as_view(), "/") ``` ```` -## 装饰符 +## 装饰器 -正如在[装饰物部分](/guide/best practices/decorators.md)中所讨论的那样，您常常需要在终点中添加使用装饰物的功能。 您与 CBV 有两个选项： +正如[装饰器部分](/guide/best-practices/decorators.md)中所讨论的，您通常需要使用装饰器向端点添加功能。 您与 CBV 有两个选项： -1. 应用于视图中的 _all_ HTTP 方法 +1. 应用于视图中的 _全部_ HTTP 方法 2. 单独应用于视图中的 HTTP 方法 让我们看看这些选项是什么样子： From 48b2edb73a245f1fc2e4bb066dc24735781d6720 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 2 Feb 2024 16:11:29 +0200 Subject: [PATCH 468/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index bbf2cd1510..7ea7611c0e 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -3,17 +3,17 @@ title: 闪电般快速的异步 Python Web 框架 layout: 首页 features: - title: 简单轻便 - details: 开箱即用，直观无臃肿且具有智能默认设置的框架 API 可以使您直接构建应用程序 + details: 直观的 API 具有智能默认设置且无臃肿，让您可以直接开始构建应用程序。 - title: 灵巧无束 - details: 按照您的意愿进行自由创建，不会对您造成任何约束 + details: 按照您的意愿进行自由开发，而不是让工具约束你 - title: 易于拓展 details: 关注应用的速度和可伸缩性 随时为大大小小的网络应用程序提供支持 - - title: 生产环境预备 - details: Sanic 不仅是一个框架，也是一个服务器，它可以随时为您编写的 Web 应用程序提供部署服务 + - title: 生产就绪 + details: 开箱即用，Sanic 配有一个 Web 服务器组件，并随时准备驱动您的 Web 应用 - title: 备受信赖 - details: Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步 Web 框架 + details: Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步兼容 Web 框架 - title: 社区驱动 - details: 从社区来，到社区去，拥有大量的活跃贡献者 + details: 从社区来，到社区去。Sanic 由社区维护和管理 --- ### :hig_voltag: 闪电般快速的异步 Python Web 框架 @@ -113,21 +113,21 @@ sanic path.to.server:app .. tab:: TLS 服务器（TLS server） ```` -启用 TLS 来运行Sanic与传递文件路径一样简单... +在启用 TLS 的情况下运行 Sanic 就像向其传递文件路径一样简单...... ```sh sanic path.to.server:app --cert=/path/to/bundle。 rt --key=/path/to/privkey.pem `` -... 或包含`fullchain.pem` 和 `privkey.pem` +... 或是包含`fullchain.pem` 和 `privkey.pem`的目录 ```sh sanic path.to. erver:app --tls=/path/to/certs ``` -**甚至更好地**，正在开发中。 让Sanic处理设置本地TLS证书，以便您可以通过 TLS 访问 [https://localhost:8443](https://localhost:8443) +**甚至更好地**，在开发中，让Sanic处理设置本地TLS证书，以便您可以通过 TLS 访问 [https://localhost:8443](https://localhost:8443) ```sh -sanic 路径。 o.server:app --dev --auto-tls +sanic path.to.server:app --dev --auto-tls ``` ```` From bd20f643747526e9cbe0761dfa2b2bcc7daa4678 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 2 Feb 2024 16:11:30 +0200 Subject: [PATCH 469/698] New translations static-redirects.md (Chinese Simplified) --- .../zh/guide/how-to/static-redirects.md | 34 ++++++++----------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/guide/content/zh/guide/how-to/static-redirects.md b/guide/content/zh/guide/how-to/static-redirects.md index ad325344ec..15aa850291 100644 --- a/guide/content/zh/guide/how-to/static-redirects.md +++ b/guide/content/zh/guide/how-to/static-redirects.md @@ -5,47 +5,41 @@ ## `app.py` ```python -### SETUP ### +### 设置 ### import typing import sanic, sanic.response -# Create the Sanic app +# 创建 Sanic app app = sanic.Sanic(__name__) -# This dictionary represents your "static" -# redirects. For example, these values -# could be pulled from a configuration file. +# 该目录代表你的 "static" 目录重定向。 +# 举个例子，这些值可以从配置文件中提取。 REDIRECTS = { - '/':'/hello_world', # Redirect '/' to '/hello_world' - '/hello_world':'/hello_world.html' # Redirect '/hello_world' to 'hello_world.html' + '/':'/hello_world', # 重定向 '/' 到 '/hello_world' + '/hello_world':'/hello_world.html' #重定向 '/hello_world' 到 'hello_world.html' } -# This function will return another function -# that will return the configured value -# regardless of the arguments passed to it. +# 这个函数会返回另一个（已配置值）的函数，而且不受已传参数的限制。 def get_static_function(value:typing.Any) -> typing.Callable[..., typing.Any]: return lambda *_, **__: value -### ROUTING ### -# Iterate through the redirects +### 路由 ### +# 遍历重定向 for src, dest in REDIRECTS.items(): - # Create the redirect response object + # 创建重定向响应对象 response:sanic.HTTPResponse = sanic.response.redirect(dest) - # Create the handler function. Typically, - # only a sanic.Request object is passed - # to the function. This object will be - # ignored. + # 创建处理函数，通常，仅将 sanic.Request 对象传递给该函数。 该对象将被忽略。 handler = get_static_function(response) - # Route the src path to the handler + # 路由src到处理函数 app.route(src)(handler) -# Route some file and client resources +# 随便路由一些文件和client资源 app.static('/files/', 'files') app.static('/', 'client') -### RUN ### +### 运行 ### if __name__ == '__main__': app.run( '127.0.0.1', From dbe6249fb7e888fb3cc4bfc59ffad41a1a4a0532 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 2 Feb 2024 16:11:36 +0200 Subject: [PATCH 470/698] New translations changelog.md (Chinese Simplified) --- guide/content/zh/release-notes/changelog.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/guide/content/zh/release-notes/changelog.md b/guide/content/zh/release-notes/changelog.md index 99d70b726c..79c3331a9a 100644 --- a/guide/content/zh/release-notes/changelog.md +++ b/guide/content/zh/release-notes/changelog.md @@ -973,8 +973,7 @@ _当前LTS版本_ 参数 - [#1866](https://github.com/sanic-org/sanic/pull/1866) 添加`sanic` 作为入口点命令 -- [#1880](https://github.com/sanic-org/sanic/pull/1880) Add handler - names for websockets for url_for usage +- [#1880](https://github.com/sanic-org/sanic/pull/1880) 为url_for用途的websockets添加处理函数名 **错误修复** @@ -983,9 +982,8 @@ _当前LTS版本_ - [#1842](https://github.com/sanic-org/sanic/pull/1842) 修复静态 _处理程序拾取错误 - [#1827](https://github.com/sanic-org/sanic/pull/1827) 在 OSX py38 和 Windows 上修复读取器 -- [#1848](https://github.com/sanic-org/sanic/pull/1848) 反向 - named_response_midlware execution order，以匹配正常的响应Order - 中间件执行顺序 +- [#1848](https://github.com/sanic-org/sanic/pull/1848) 反转 + named_response_midlware 的执行顺序，以匹配正常的响应中间件执行顺序 - [#1853](https://github.com/sanic-org/sanic/pull/1853) Fix pickle error when attempting to pickle an application which contains websocket routes From c2c3063786de3f55a658e7b176754f1e91d78d9f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 04:35:52 +0200 Subject: [PATCH 471/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 50 +++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index 7ea7611c0e..8c7c04184c 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -5,13 +5,13 @@ features: - title: 简单轻便 details: 直观的 API 具有智能默认设置且无臃肿，让您可以直接开始构建应用程序。 - title: 灵巧无束 - details: 按照您的意愿进行自由开发，而不是让工具约束你 + details: 按照您的意愿进行自由创建，不会对您造成任何约束 - title: 易于拓展 details: 关注应用的速度和可伸缩性 随时为大大小小的网络应用程序提供支持 - title: 生产就绪 - details: 开箱即用，Sanic 配有一个 Web 服务器组件，并随时准备驱动您的 Web 应用 + details: 开箱即用，Sanic 不仅是一个框架，也是一个服务器，并随时准备驱动您的 Web 应用 - title: 备受信赖 - details: Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步兼容 Web 框架 + details: Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步 Web 框架 - title: 社区驱动 details: 从社区来，到社区去。Sanic 由社区维护和管理 --- @@ -27,7 +27,7 @@ features: #### 简单轻便 - 开箱即用，直观无臃肿且具有智能默认设置的框架 API 可以使您直接构建应用程序 + 直观的 API 具有智能默认设置且无臃肿，让您可以直接开始构建应用程序。 .. attrs:: :class: column is-4 @@ -46,9 +46,9 @@ features: .. attrs:: :class: column is-4 - #### 生产环境预备 + #### 生产就绪 - Sanic 不仅是一个框架，也是一个服务器，它可以随时为您编写的 Web 应用程序提供部署服务 + 开箱即用，Sanic 不仅是一个框架，也是一个服务器，并随时准备驱动您的 Web 应用 .. attrs:: :class: column is-4 @@ -62,21 +62,21 @@ features: #### 社区驱动 - 从社区来，到社区去，拥有大量的活跃贡献者 + 从社区来，到社区去。Sanic 由社区维护和管理 ``` .. attrs:: :class: is-size-3 mt-6 ``` -**使用您所期望的功能和工具。** +**有你所期待的功能和工具。** ``` .. attrs:: :class: is-size-3 ml-6 ``` -**还有一些{span:has-text-primary:您甚至不敢相信的}。** +**还有一些{span:has-text-primary:意料之外的惊喜}。** ``` .. tab:: 生产级别（Production-grade） @@ -113,18 +113,18 @@ sanic path.to.server:app .. tab:: TLS 服务器（TLS server） ```` -在启用 TLS 的情况下运行 Sanic 就像向其传递文件路径一样简单...... +使用 带 TLS 的 Sanic 就像向其设置文件路径一样简单...... ```sh sanic path.to.server:app --cert=/path/to/bundle。 rt --key=/path/to/privkey.pem `` -... 或是包含`fullchain.pem` 和 `privkey.pem`的目录 +... 或是包含`fullchain.pem` 和 `privkey.pem`的目录文件夹 ```sh sanic path.to. erver:app --tls=/path/to/certs ``` -**甚至更好地**，在开发中，让Sanic处理设置本地TLS证书，以便您可以通过 TLS 访问 [https://localhost:8443](https://localhost:8443) +**除此之外**，在开发中，让Sanic处理设置本地TLS证书，以便您可以通过 TLS 访问 [https://localhost:8443](https://localhost:8443) ```sh sanic path.to.server:app --dev --auto-tls @@ -134,7 +134,7 @@ sanic path.to.server:app --dev --auto-tls .. tab:: Websockets ```` -通过 [websockets](https://websockets.readthedocs.io) 库，可以马上实现的 WebSockets。 +得益于 [websockets](https://websockets.readthedocs.io) 库，可以无缝实现的 WebSockets。 ```python from sanic import Request, Websocket @@ -149,7 +149,7 @@ async def feed(request: Request, ws: Websocket): .. tab:: 静态文件（Static files） ```` -建立静态文件服务当然是既直观又容易。只需要给一个端点以及一个需要被服务的文件或目录命名即可。 +建立静态文件服务当然是既直观又容易。只需配置一个入口并且指定一个文件或一个目录文件夹即可。 ```python app.static("/", "/path/to/index.html") @@ -185,7 +185,7 @@ app.static( .. tab:: 生命周期（Lifecycle） ```` -添加一个装饰器，就能够应用一个在请求开始或是响应结束时的功能性的路由。 +添加一个装饰器，就能在应用生命周期开始或结束时插入自定义的处理函数 ```python @app.on_request @@ -209,14 +209,14 @@ async def setup_db(app): await app.ctx.db_pool.shutdown() ``` -除此之外，Sanic 还允许您绑定一系列内置事件（称为信号），或创建和调度自己的事件。 +除此之外，Sanic 还允许您绑定一系列官方内置事件（称为信号），或创建和调度自己的事件。 ```python -@app.signal("http.lifecycle.complete") # 内建 +@app.signal("http.lifecycle.complete") # built-in (官方内置的) async def my_signal_handler(conn_info): print("Connection has been closed") -@app.signal("something.happened.ohmy") # 定制 +@app.signal("something.happened.ohmy") # custom (自定义的) async def my_signal_handler(): print("something happened") @@ -227,20 +227,20 @@ await app.dispatch("something.happened.ohmy") .. tab:: 智能错误处理（Smart error handling） ```` -出错后，会出现直观且准确的 HTTP 错误： +出错后，会出现直观且合适的 HTTP 错误： ```python -raise sanic.exceptions.NotFound # 自动响应 HTTP 404 +raise sanic.exceptions.NotFound # Automatically responds with HTTP 404 ``` -或是实现您自己的： +或是实现您自己的错误处理方法： ```python from sanic.exceptions import SanicException class TeapotError(SanicException): status_code = 418 - message = "抱歉，我不能煮咖啡Orz" + message = "Sorry, I cannot brew coffee" raise TeapotError ``` @@ -249,7 +249,7 @@ raise TeapotError ![image](../assets/images/error-div-by-zero.png) -无论如何，Sanic 自带的算法都会根据情况尝试响应 HTML、JSON 或基于文本的错误。不要担心，根据您的具体需求设置和自定义错误处理非常简单。 +无论如何，Sanic 自带的算法都会根据情况尝试响应 HTML、JSON 或 text-based 的错误。不要担心，您可以根据您的具体需求，非常简单的设置和自定义错误处理的方法。 ```` .. tab:: 应用查看器（App Inspector） @@ -313,9 +313,9 @@ sanic inspect migrations - 使用 **Jinja** 进行模板渲染 - 将其他对象通过 **Dependency injection** （依赖注入）到路由处理程序中 - 使用 **Redoc** 和/或 **Swagger** 编写 OpenAPI 文档 -- 预定义的特定端点响应**序列化器**（serializers） +- 预先定义好的**序列化函数**(eg `json` `text`)、作用于不同的路由入口（serializers） - 请求查询参数和正文输入的**验证器**（validation） -- **自动创建** HEAD、OPTIONS 和 TRACE 端点（auto create） +- **自动创建** HEAD、OPTIONS 和 TRACE 入口（auto create） - 实时**健康监控**（health monitor） ``` From 71dac3655ef78b5f2f5881ca15d0ae167ede7596 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 05:57:09 +0200 Subject: [PATCH 472/698] New translations help.md (Chinese Simplified) --- guide/content/zh/help.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/help.md b/guide/content/zh/help.md index 59b95936f5..11052a6e66 100644 --- a/guide/content/zh/help.md +++ b/guide/content/zh/help.md @@ -22,7 +22,7 @@ layout: 主界面 ``` ### 社区论坛 👥 -分享代码片段或是请求更长时间的支持最好在这里 +分享代码片段 或者 想要持久的咨询支持 建议发布在这里 [论坛](https://community.sanicframework.org/c/questions-and-help/6)上的「问题与帮助」（Questions and Help） ``` From fb8a6b98c044ff5cd31b4b81d52c89c83d2821fb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 05:57:13 +0200 Subject: [PATCH 473/698] New translations v23.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.9.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/zh/release-notes/2023/v23.9.md b/guide/content/zh/release-notes/2023/v23.9.md index 51b8622cd9..630da3625b 100644 --- a/guide/content/zh/release-notes/2023/v23.9.md +++ b/guide/content/zh/release-notes/2023/v23.9.md @@ -1,7 +1,7 @@ --- -title: 第23.9版 +title: Version 23.9 --- -# 第23.9版 +# Version 23.9 -_由于当时的情况，v.23.9已经跳过。 +_Due to circumstances at the time, v.23.9 was skipped._ From d914d8d5cbc8d5c6f3431d1142d4480f258fe950 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 05:57:18 +0200 Subject: [PATCH 474/698] New translations changelog.md (Chinese Simplified) --- guide/content/zh/release-notes/changelog.md | 1990 ++++++++++--------- 1 file changed, 998 insertions(+), 992 deletions(-) diff --git a/guide/content/zh/release-notes/changelog.md b/guide/content/zh/release-notes/changelog.md index 79c3331a9a..c4bbf8da4a 100644 --- a/guide/content/zh/release-notes/changelog.md +++ b/guide/content/zh/release-notes/changelog.md @@ -4,556 +4,556 @@ content_class: 更新日志 # 更新日志 -:larg_orange_diamond: Current release\ +:larg_orange_diamond: Current release :larg_blu_diamond: In support LTS release -## 版本23.12.0 :larg_orange_diamond::larg_blu_diamond: +## Version 23.12.0 🔶🔷 _当前版本_ -### 功能 - -- [#2775](https://github.com/sanic-org/sanic/pull/2775) 开始并重启任意进程 -- [#2811](https://github.com/sanic-org/sanic/pull/2811) -- [#2812](https://github.com/sanic-org/sanic/pull/2812) 禁止任务在打开websocket上取消跟踪 -- [#2822](https://github.com/sanic-org/sanic/pull/2822) 侦听器和信号优先级 -- [#2831](https://github.com/sanic-org/sanic/pull/2831) 减少内存消耗量 -- [#2837](https://github.com/sanic-org/sanic/pull/2837) 接受最佳cookies -- [#2841](https://github.com/sanic-org/sanic/pull/2841) 添加 \`websocket.handler.\" 信号 -- [#2805](https://github.com/sanic-org/sanic/pull/2805) 添加更改的文件以重新载入触发监听器 -- [#2813](https://github.com/sanic-org/sanic/pull/2813) 允许提供简单的信号 -- [#2827](https://github.com/sanic-org/sanic/pull/2827) 改进`Sanic.event()`的功能和一致性 -- [#2851](https://github.com/sanic-org/sanic/pull/2851) 允许范围请求单个字节 -- [#2854](https://github.com/sanic-org/sanic/pull/2854) 为web套接字请求更好地`Request.scheme` -- [#2858](https://github.com/sanic-org/sanic/pull/2858) 将Sanic `Request` 转换为Websockets `Request` 来握手 -- [#2859](https://github.com/sanic-org/sanic/pull/2859) 在 `sanic` CLI 中添加一个 REPL -- [#2870](https://github.com/sanic-org/sanic/pull/2870) 添加 Python 3.12 支持 -- [#2875](https://github.com/sanic-org/sanic/pull/2875) 在多处理环境冲突中更好的例外 - -### 错误修正 - -- [#2803](https://github.com/sanic-org/sanic/pull/2803) 修复MOTD显示额外数据 - -### 废弃和移除 - -### 开发者基础设施 - -- [#2796](https://github.com/sanic-org/sanic/pull/2796) 重新计算单位测试案件 -- [#2801](https://github.com/sanic-org/sanic/pull/2801) 在只有一个 CPU 时修复`test_fast` -- [#2807](https://github.com/sanic-org/sanic/pull/2807) 添加自动文档的约束 (旧软件包版本中的行号) -- [#2808](https://github.com/sanic-org/sanic/pull/2808) Reface GitHub Actions -- [#2814](https://github.com/sanic-org/sanic/pull/2814) 在 git 推送时运行CI 管道上 -- [#2846](https://github.com/sanic-org/sanic/pull/2846) 删除旧的性能测试/基准 -- [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile 清理 +### Features + +- [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes +- [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown +- [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket +- [#2822](https://github.com/sanic-org/sanic/pull/2822) Listener and signal prioritization +- [#2831](https://github.com/sanic-org/sanic/pull/2831) Reduce memory consumption +- [#2837](https://github.com/sanic-org/sanic/pull/2837) Accept bare cookies +- [#2841](https://github.com/sanic-org/sanic/pull/2841) Add `websocket.handler.` signals +- [#2805](https://github.com/sanic-org/sanic/pull/2805) Add changed files to reload trigger listeners +- [#2813](https://github.com/sanic-org/sanic/pull/2813) Allow for simple signals +- [#2827](https://github.com/sanic-org/sanic/pull/2827) Improve functionality and consistency of `Sanic.event()` +- [#2851](https://github.com/sanic-org/sanic/pull/2851) Allow range requests for a single byte +- [#2854](https://github.com/sanic-org/sanic/pull/2854) Better `Request.scheme` for websocket requests +- [#2858](https://github.com/sanic-org/sanic/pull/2858) Convert Sanic `Request` to a Websockets `Request` for handshake +- [#2859](https://github.com/sanic-org/sanic/pull/2859) Add a REPL to the `sanic` CLI +- [#2870](https://github.com/sanic-org/sanic/pull/2870) Add Python 3.12 support +- [#2875](https://github.com/sanic-org/sanic/pull/2875) Better exception on multiprocessing context conflicts + +### Bugfixes + +- [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data + +### Deprecations and Removals + +### Developer infrastructure + +- [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases +- [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU +- [#2807](https://github.com/sanic-org/sanic/pull/2807) Add constraint for autodocsum (lint issue in old package version) +- [#2808](https://github.com/sanic-org/sanic/pull/2808) Refactor GitHub Actions +- [#2814](https://github.com/sanic-org/sanic/pull/2814) Run CI pipeline on git push +- [#2846](https://github.com/sanic-org/sanic/pull/2846) Drop old performance tests/benchmarks +- [#2848](https://github.com/sanic-org/sanic/pull/2848) Makefile cleanup - [#2865](https://github.com/sanic-org/sanic/pull/2865) [#2869](https://github.com/sanic-org/sanic/pull/2869) [#2872](https://github.com/sanic-org/sanic/pull/2872) [#2879](https://github.com/sanic-org/sanic/pull/2879) - 添加ruff到工具链中 -- [#2866](https://github.com/sanic-org/sanic/pull/2866) 修复alt svc 测试以便在本地使用显式缓存nbytes -- [#2877](https://github.com/sanic-org/sanic/pull/2877) 在部署中使用Python可信的出版商 -- [#2882](https://github.com/sanic-org/sanic/pull/2882) 在测试套装中引入目标位置的动态端口灯具 + Add ruff to toolchain +- [#2866](https://github.com/sanic-org/sanic/pull/2866) Fix the alt svc test to run locally with explicit buffer nbytes +- [#2877](https://github.com/sanic-org/sanic/pull/2877) Use Python's trusted publisher in deployments +- [#2882](https://github.com/sanic-org/sanic/pull/2882) Introduce dynamic port fixture in targeted locations in the test suite -### 改进文档 +### Improved Documentation - [#2781](https://github.com/sanic-org/sanic/pull/2781) [#2821](https://github.com/sanic-org/sanic/pull/2821) [#2861](https://github.com/sanic-org/sanic/pull/2861) [#2863](https://github.com/sanic-org/sanic/pull/2863) - 用户指南转换为 SHH (Sanic, html5tagger, HTMX) -- [#2810](https://github.com/sanic-org/sanic/pull/2810) 更新README -- [#2855](https://github.com/sanic-org/sanic/pull/2855) 编辑Discord 徽章 -- [#2864](https://github.com/sanic-org/sanic/pull/2864) 调整文档使用状态属性在 http/https 重定向文档 + Conversion of User Guide to the SHH (Sanic, html5tagger, HTMX) stack +- [#2810](https://github.com/sanic-org/sanic/pull/2810) Update README +- [#2855](https://github.com/sanic-org/sanic/pull/2855) Edit Discord badge +- [#2864](https://github.com/sanic-org/sanic/pull/2864) Adjust documentation for using state properties within http/https redirection document -## 版本23.9.0 +## Version 23.9.0 -_由于当时的情况，v.23.9已经跳过。 +_Due to circumstances at the time, v.23.9 was skipped._ -## 版本 23.6.0 +## Version 23.6.0 -### 功能 +### Features -- [#2670](https://github.com/sanic-org/sanic/pull/2670) 增加`KEEP_ALIVE_TIMEOUT` 默认为120秒 -- [#2716](https://github.com/sanic-org/sanic/pull/2716) 在蓝图中添加允许路由覆盖选项 -- [#2724](https://github.com/sanic-org/sanic/pull/2724)和[#2792](https://github.com/sanic-org/sanic/pull/2792) 为应用中任何地方提出的所有例外添加一个新的异常信号。 -- [#2727](https://github.com/sanic-org/sanic/pull/2727) 为BP组添加名称前缀 -- [#2754](https://github.com/sanic-org/sanic/pull/2754) 更新中间件类型的请求类型 -- [#2770](https://github.com/sanic-org/sanic/pull/2770) 启动时间应用程序引发导入错误时更好的异常消息 -- [#2776](https://github.com/sanic-org/sanic/pull/2776) 设置多处理开始方法 -- [#2785](https://github.com/sanic-org/sanic/pull/2785) 添加自定义键入配置和 ctx 对象 -- [#2790](https://github.com/sanic-org/sanic/pull/2790) 添加`request.client_ip` +- [#2670](https://github.com/sanic-org/sanic/pull/2670) Increase `KEEP_ALIVE_TIMEOUT` default to 120 +- [#2716](https://github.com/sanic-org/sanic/pull/2716) Adding allow route overwrite option in blueprint +- [#2724](https://github.com/sanic-org/sanic/pull/2724) and [#2792](https://github.com/sanic-org/sanic/pull/2792) Add a new exception signal for ALL exceptions raised anywhere in application +- [#2727](https://github.com/sanic-org/sanic/pull/2727) Add name prefixing to BP groups +- [#2754](https://github.com/sanic-org/sanic/pull/2754) Update request type on middleware types +- [#2770](https://github.com/sanic-org/sanic/pull/2770) Better exception message on startup time application induced import error +- [#2776](https://github.com/sanic-org/sanic/pull/2776) Set multiprocessing start method early +- [#2785](https://github.com/sanic-org/sanic/pull/2785) Add custom typing to config and ctx objects +- [#2790](https://github.com/sanic-org/sanic/pull/2790) Add `request.client_ip` -### 错误修正 +### Bugfixes -- [#2728](https://github.com/sanic-org/sanic/pull/2728) 修复预定结果 -- [#2729](https://github.com/sanic-org/sanic/pull/2729) -- [#2737](https://github.com/sanic-org/sanic/pull/2737) 修复`JSONREspone`默认内容类型的注解 -- [#2740](https://github.com/sanic-org/sanic/pull/2740) 在检查员中使用 Sanic的序列化器为 JSON 响应 -- [#2760](https://github.com/sanic-org/sanic/pull/2760) 在 ASGI 模式中支持 `Request.get_current` -- [#2773](https://github.com/sanic-org/sanic/pull/2773) 蓝图路由，明确定义错误格式 -- [#2774](https://github.com/sanic-org/sanic/pull/2774) 解析不同渲染器的标题 -- [#2782](https://github.com/sanic-org/sanic/pull/2782) 解决pypy 兼容性问题 +- [#2728](https://github.com/sanic-org/sanic/pull/2728) Fix traversals for intended results +- [#2729](https://github.com/sanic-org/sanic/pull/2729) Handle case when headers argument of ResponseStream constructor is None +- [#2737](https://github.com/sanic-org/sanic/pull/2737) Fix type annotation for `JSONREsponse` default content type +- [#2740](https://github.com/sanic-org/sanic/pull/2740) Use Sanic's serializer for JSON responses in the Inspector +- [#2760](https://github.com/sanic-org/sanic/pull/2760) Support for `Request.get_current` in ASGI mode +- [#2773](https://github.com/sanic-org/sanic/pull/2773) Alow Blueprint routes to explicitly define error_format +- [#2774](https://github.com/sanic-org/sanic/pull/2774) Resolve headers on different renderers +- [#2782](https://github.com/sanic-org/sanic/pull/2782) Resolve pypy compatibility issues ### 废弃和移除 -- [#2777](https://github.com/sanic-org/sanic/pull/2777) 移除 Python 3.7 支持 +- [#2777](https://github.com/sanic-org/sanic/pull/2777) Remove Python 3.7 support ### 开发者基础设施 -- [#2766](https://github.com/sanic-org/sanic/pull/2766) 解压设置工具版本 -- [#2779](https://github.com/sanic-org/sanic/pull/2779) 运行在循环中进行活化测试以获取端口。 +- [#2766](https://github.com/sanic-org/sanic/pull/2766) Unpin setuptools version +- [#2779](https://github.com/sanic-org/sanic/pull/2779) Run keep alive tests in loop to get available port -### 改进文档 +### Improved Documentation -- [#2741](https://github.com/sanic-org/sanic/pull/2741) 更好的文档实例来运行 Sanic - 从该列表中，要在发行说明中高亮显示的内容： +- [#2741](https://github.com/sanic-org/sanic/pull/2741) Better documentation examples about running Sanic + From that list, the items to highlight in the release notes: -## 版本23.3.0 +## Version 23.3.0 -### 功能 +### Features -- [#2545](https://github.com/sanic-org/sanic/pull/2545) -- [#2606](https://github.com/sanic-org/sanic/pull/2606) 也在 ASGI 中解码头为 UTF-8 -- [#2646](https://github.com/sanic-org/sanic/pull/2646) 单独的 ASGI 请求和有效期彩信 -- [#2659](https://github.com/sanic-org/sanic/pull/2659) 使用 `FALLBACK_ERROR_FORMAT` 返回的 `empty()` -- [#2662](https://github.com/sanic-org/sanic/pull/262) 添加基本文件浏览器 (HTML页面) 和自动索引服务 -- [#2667](https://github.com/sanic-org/sanic/pull/2667) 较强的追踪格式化(HTML页面) -- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter 错误页面渲染格式选择；更多依赖于头部和“常识”默认值 -- [#2680](https://github.com/sanic-org/sanic/pull/2680) 在使用 `SHUT_RDWR` 关闭之前检查套接字的状态 -- [#2687](https://github.com/sanic-org/sanic/pull/267) 刷新`Request.accept` 功能，使其更加性能和符合观光。 -- [#2696](https://github.com/sanic-org/sanic/pull/2696) 添加标题访问器作为属性 +- [#2545](https://github.com/sanic-org/sanic/pull/2545) Standardize init of exceptions for more consistent control of HTTP responses using exceptions +- [#2606](https://github.com/sanic-org/sanic/pull/2606) Decode headers as UTF-8 also in ASGI +- [#2646](https://github.com/sanic-org/sanic/pull/2646) Separate ASGI request and lifespan callables +- [#2659](https://github.com/sanic-org/sanic/pull/2659) Use `FALLBACK_ERROR_FORMAT` for handlers that return `empty()` +- [#2662](https://github.com/sanic-org/sanic/pull/2662) Add basic file browser (HTML page) and auto-index serving +- [#2667](https://github.com/sanic-org/sanic/pull/2667) Nicer traceback formatting (HTML page) +- [#2668](https://github.com/sanic-org/sanic/pull/2668) Smarter error page rendering format selection; more reliant upon header and "common sense" defaults +- [#2680](https://github.com/sanic-org/sanic/pull/2680) Check the status of socket before shutting down with `SHUT_RDWR` +- [#2687](https://github.com/sanic-org/sanic/pull/2687) Refresh `Request.accept` functionality to be more performant and spec-compliant +- [#2696](https://github.com/sanic-org/sanic/pull/2696) Add header accessors as properties ``` - 示例字段: Foo, Bar - 示例字段: Baz + Example-Field: Foo, Bar + Example-Field: Baz ``` ```python - headers.example_field ="Foo, Bar,Baz" + request.headers.example_field == "Foo, Bar,Baz" ``` -- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simple CLI 目标 +- [#2700](https://github.com/sanic-org/sanic/pull/2700) Simpler CLI targets ```sh - $ sanic path.to.module:app # 全局应用实例 - $ sanic path.to.module:create_app # 出厂模式 - sanic ./path/to/directory/ # 简单服务 + $ sanic path.to.module:app # global app instance + $ sanic path.to.module:create_app # factory pattern + $ sanic ./path/to/directory/ # simple serve ``` -- [#2701](https://github.com/sanic-org/sanic/pull/2701) API 来定义管理过程中的一些工人 -- [#2704](https://github.com/sanic-org/sanic/pull/2704) 添加动态更改路由的便利。 -- [#2706](https://github.com/sanic-org/sanic/pull/2706) 为cookie的创建和删除添加便利方法 +- [#2701](https://github.com/sanic-org/sanic/pull/2701) API to define a number of workers in managed processes +- [#2704](https://github.com/sanic-org/sanic/pull/2704) Add convenience for dynamic changes to routing +- [#2706](https://github.com/sanic-org/sanic/pull/2706) Add convenience methods for cookie creation and deletion ```python response = text("...") - response.add_cookie("test", "it work!", domain=".yummy-yummy-cookie.com") + response.add_cookie("test", "It worked!", domain=".yummy-yummy-cookie.com") ``` -- [#2707](https://github.com/sanic-org/sanic/pull/2707) 简化的 `parse_content_header` 逃避与 RFC 兼容并移除过时的 FF 哈克 -- [#2710](https://github.com/sanic-org/sanic/pull/2710) -- [#2711](https://github.com/sanic-org/sanic/pull/2711) 默认使用 `DELETE` 上 -- [#2719](https://github.com/sanic-org/sanic/pull/2719) 允许 `password` 传入TLS 环境 -- [#2720](https://github.com/sanic-org/sanic/pull/2720) 在 `RequestCancelled` 上跳过中间件 -- [#2721](https://github.com/sanic-org/sanic/pull/2721) 将访问日志格式更改为`%s` -- [#2722](https://github.com/sanic-org/sanic/pull/2722) 添加 `CertLoader` 作为直接控制 `SSLContext` 对象的应用程序选项 -- [#2725](https://github.com/sanic-org/sanic/pull/2725) 工人在种族条件下同步状态容忍度 +- [#2707](https://github.com/sanic-org/sanic/pull/2707) Simplified `parse_content_header` escaping to be RFC-compliant and remove outdated FF hack +- [#2710](https://github.com/sanic-org/sanic/pull/2710) Stricter charset handling and escaping of request URLs +- [#2711](https://github.com/sanic-org/sanic/pull/2711) Consume body on `DELETE` by default +- [#2719](https://github.com/sanic-org/sanic/pull/2719) Allow `password` to be passed to TLS context +- [#2720](https://github.com/sanic-org/sanic/pull/2720) Skip middleware on `RequestCancelled` +- [#2721](https://github.com/sanic-org/sanic/pull/2721) Change access logging format to `%s` +- [#2722](https://github.com/sanic-org/sanic/pull/2722) Add `CertLoader` as application option for directly controlling `SSLContext` objects +- [#2725](https://github.com/sanic-org/sanic/pull/2725) Worker sync state tolerance on race condition -### 错误修正 +### Bugfixes -- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket 来传递节点像是 -- [#2697](https://github.com/sanic-org/sanic/pull/2697) 使用 `If-Modified-Since` 时修复日期时间和天真之间的比较 +- [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket to pass thru bytes as is +- [#2697](https://github.com/sanic-org/sanic/pull/2697) Fix comparison between datetime aware and naive in `file` when using `If-Modified-Since` ### 废弃和移除 - [#2666](https://github.com/sanic-org/sanic/pull/2666) Remove deprecated `__blueprintname__` property -### 改进文档 +### Improved Documentation -- [#2712](https://github.com/sanic-org/sanic/pull/2712) 通过使用 \`\`'https\://github.com/sanic/pull/2712改进的示例来创建重定向 +- [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect -## 版本22.12.0 :larg_blu_diamond: +## Version 22.12.0 🔷 _当前LTS版本_ -### 功能 - -- [#2569](https://github.com/sanic-org/sanic/pull/2569) 在更新响应对象时添加 `JSONResponse` 类，并有一些方便的方法 -- [#2598](https://github.com/sanic-org/sanic/pull/2598) 将 `uvloop` 要求更改为 `>=0.15.0` -- [#2609](https://github.com/sanic-org/sanic/pull/2609) 添加与 `websockets` v11.0 -- [#2610](https://github.com/sanic-org/sanic/pull/2610) 在工人错误的早期杀死服务器 - - 将僵局提升到30秒 -- [#2617](https://github.com/sanic-org/sanic/pull/261) -- [#2621](https://github.com/sanic-org/sanic/pull/2621)[#2634](https://github.com/sanic-org/sanic/pull/2634) 在随后的`ctrl+c`上发送`SIGKILL`，迫使工人退出 -- [#2622](https://github.com/sanic-org/sanic/pull/2622) 添加 API 以重新启动多路程序的所有工人。 -- [#2624](https://github.com/sanic-org/sanic/pull/2624) 默认为所有子进程的`spawn`，除非具体设置： +### Features + +- [#2569](https://github.com/sanic-org/sanic/pull/2569) Add `JSONResponse` class with some convenient methods when updating a response object +- [#2598](https://github.com/sanic-org/sanic/pull/2598) Change `uvloop` requirement to `>=0.15.0` +- [#2609](https://github.com/sanic-org/sanic/pull/2609) Add compatibility with `websockets` v11.0 +- [#2610](https://github.com/sanic-org/sanic/pull/2610) Kill server early on worker error + - Raise deadlock timeout to 30s +- [#2617](https://github.com/sanic-org/sanic/pull/2617) Scale number of running server workers +- [#2621](https://github.com/sanic-org/sanic/pull/2621) [#2634](https://github.com/sanic-org/sanic/pull/2634) Send `SIGKILL` on subsequent `ctrl+c` to force worker exit +- [#2622](https://github.com/sanic-org/sanic/pull/2622) Add API to restart all workers from the multiplexer +- [#2624](https://github.com/sanic-org/sanic/pull/2624) Default to `spawn` for all subprocesses unless specifically set: ```python - 从Sanic 导入 Sanic + from sanic import Sanic - Sanic.start_methods = "fork" + Sanic.start_method = "fork" ``` -- [#2625](https://github.com/sanic-org/sanic/pull/2625) 格式数据/多部分文件上传文件名正常化 -- [#2626](https://github.com/sanic-org/sanic/pull/2626) 移动到HTTP检查器： - - 远程访问以检查正在运行的 Sanic 实例 - - TLS 支持给检查员的加密通话 - - 使用 API 密钥验证检查员 - - 使用自定义命令扩展检查员的能力 -- [#2632](https://github.com/sanic-org/sanic/pull/2632) 重新启动操作的控制顺序 -- [#2633](https://github.com/sanic-org/sanic/pull/2633) 将重新加载间隔移至类变量 -- [#2636](https://github.com/sanic-org/sanic/pull/2636) 在 `register_middleware` 方法中添加 `priority` -- [#2639](https://github.com/sanic-org/sanic/pull/2639) 在 `add_route` 方法中加上“unquote\` -- [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets 接收`text` 或 `bytes` +- [#2625](https://github.com/sanic-org/sanic/pull/2625) Filename normalisation of form-data/multipart file uploads +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector: + - Remote access to inspect running Sanic instances + - TLS support for encrypted calls to Inspector + - Authentication to Inspector with API key + - Ability to extend Inspector with custom commands +- [#2632](https://github.com/sanic-org/sanic/pull/2632) Control order of restart operations +- [#2633](https://github.com/sanic-org/sanic/pull/2633) Move reload interval to class variable +- [#2636](https://github.com/sanic-org/sanic/pull/2636) Add `priority` to `register_middleware` method +- [#2639](https://github.com/sanic-org/sanic/pull/2639) Add `unquote` to `add_route` method +- [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets to receive `text` or `bytes` -### 错误修正 +### Bugfixes -- [#2607](https://github.com/sanic-org/sanic/pull/2607) 强制套接字关闭之前允许重新绑定 -- [#2590](https://github.com/sanic-org/sanic/pull/2590) 在Python 3.11+中使用实际的`StrEnum` -- [#2615](https://github.com/sanic-org/sanic/pull/2615) 确保每个请求超时只执行一次中间件执行 -- [#2627](https://github.com/sanic-org/sanic/pull/2627) 在生命周期失败时崩溃ASGI应用程序 -- [#2635](https://github.com/sanic-org/sanic/pull/2635) 解决Windows 上低级服务器创建错误 +- [#2607](https://github.com/sanic-org/sanic/pull/2607) Force socket shutdown before close to allow rebinding +- [#2590](https://github.com/sanic-org/sanic/pull/2590) Use actual `StrEnum` in Python 3.11+ +- [#2615](https://github.com/sanic-org/sanic/pull/2615) Ensure middleware executes only once per request timeout +- [#2627](https://github.com/sanic-org/sanic/pull/2627) Crash ASGI application on lifespan failure +- [#2635](https://github.com/sanic-org/sanic/pull/2635) Resolve error with low-level server creation on Windows -### 废弃和移除 +### Deprecations and Removals -- [#2608](https://github.com/sanic-org/sanic/pull/2608)[#2630](https://github.com/sanic-org/sanic/pull/2630) 信号条件和在`signal.extr` 上保存的触发器 -- [#2626](https://github.com/sanic-org/sanic/pull/2626) 移动到 HTTP 检查 - - 🚨 _Breaking更改_: 将检查员从一个带有自定义协议的 TCP 套接字移动到一个Sanic 应用程序 - - _DEPRECATE_: "--inspect\*" 命令已被弃用而改用 "inspect..." 命令 -- [#2628](https://github.com/sanic-org/sanic/pull/2628) 替换已废弃的`dutils.strtobool` +- [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) Signal conditions and triggers saved on `signal.extra` +- [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector + - 🚨 _BREAKING CHANGE_: Moves the Inspector to a Sanic app from a simple TCP socket with a custom protocol + - _DEPRECATE_: The `--inspect*` commands have been deprecated in favor of `inspect ...` commands +- [#2628](https://github.com/sanic-org/sanic/pull/2628) Replace deprecated `distutils.strtobool` -### 开发者基础设施 +### Developer infrastructure -- [#2612](https://github.com/sanic-org/sanic/pull/2612) 添加CI 测试Python 3.11 +- [#2612](https://github.com/sanic-org/sanic/pull/2612) Add CI testing for Python 3.11 -## 第22.9.1 版 +## Version 22.9.1 -### 功能 +### Features -- [#2585](https://github.com/sanic-org/sanic/pull/2585) 没有注册应用程序时改进错误消息 +- [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered -### 错误修正 +### Bugfixes -- [#2578](https://github.com/sanic-org/sanic/pull/2578) -- [#2591](https://github.com/sanic-org/sanic/pull/2591) 不使用 sentinel identity 来实现`spawn` 兼容性 -- [#2592](https://github.com/sanic-org/sanic/pull/2592) 修复嵌套蓝图组中的属性 -- [#2595](https://github.com/sanic-org/sanic/pull/2595) 在新的工人读取器上设置睡眠间隔 +- [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation +- [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility +- [#2592](https://github.com/sanic-org/sanic/pull/2592) Fix properties in nested blueprint groups +- [#2595](https://github.com/sanic-org/sanic/pull/2595) Introduce sleep interval on new worker reloader -### 废弃和移除 +### Deprecations and Removals -### 开发者基础设施 +### Developer infrastructure - [#2588](https://github.com/sanic-org/sanic/pull/2588) Markdown templates on issue forms -### 改进文档 +### Improved Documentation -- [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 文档 -- [#2582](https://github.com/sanic-org/sanic/pull/2582) 清除Windows支持 +- [#2556](https://github.com/sanic-org/sanic/pull/2556) v22.9 documentation +- [#2582](https://github.com/sanic-org/sanic/pull/2582) Cleanup documentation on Windows support -## 版本 22.9.0 +## Version 22.9.0 -### 功能 +### Features -- [#2445](https://github.com/sanic-org/sanic/pull/2445) 添加自定义负载函数 -- [#2490](https://github.com/sanic-org/sanic/pull/2490) 使`WebsocketImplication` async -- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refacture -- [#2506](https://github.com/sanic-org/sanic/pull/2506) 使用 `pathlib` 作为路径分辨率(用于静态文件服务) -- [#2508](https://github.com/sanic-org/sanic/pull/2508) 使用 `path.parts` 而不是 `match` (用于静态文件服务) -- [#2513](https://github.com/sanic-org/sanic/pull/2513) 更好地请求取消处理 -- [#2516](https://github.com/sanic-org/sanic/pull/2516) 添加HTTP方法信息的请求属性： +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom loads function +- [#2490](https://github.com/sanic-org/sanic/pull/2490) Make `WebsocketImplProtocol` async iterable +- [#2499](https://github.com/sanic-org/sanic/pull/2499) Sanic Server WorkerManager refactor +- [#2506](https://github.com/sanic-org/sanic/pull/2506) Use `pathlib` for path resolution (for static file serving) +- [#2508](https://github.com/sanic-org/sanic/pull/2508) Use `path.parts` instead of `match` (for static file serving) +- [#2513](https://github.com/sanic-org/sanic/pull/2513) Better request cancel handling +- [#2516](https://github.com/sanic-org/sanic/pull/2516) Add request properties for HTTP method info: - `request.is_safe` - `request.is_identient` - `request.is_cache` - - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _获取更多关于何时应用的信息_ -- [#2522](https://github.com/sanic-org/sanic/pull/252) 始终在ASGI 中显示服务器位置 -- [#2526](https://github.com/sanic-org/sanic/pull/2526) 缓存控制支持静态文件在适当时返回 304 -- [#2533](https://github.com/sanic-org/sanic/pull/2533) 重新因素`_static_request_handler` -- [#2540](https://github.com/sanic-org/sanic/pull/2540) + - _See_ [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _for more information about when these apply_ +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI +- [#2526](https://github.com/sanic-org/sanic/pull/2526) Cache control support for static files for returning 304 when appropriate +- [#2533](https://github.com/sanic-org/sanic/pull/2533) Refactor `_static_request_handler` +- [#2540](https://github.com/sanic-org/sanic/pull/2540) Add signals before and after handler execution - `http.handler.befor` - `http.handler.after ` -- [#2542](https://github.com/sanic-org/sanic/pull/2542) 添加 \*[redacted]到 CLI :) -- [#2546](https://github.com/sanic-org/sanic/pull/2546) 添加废弃警告过滤器 -- [#2550](https://github.com/sanic-org/sanic/pull/250) 中间件优先级和性能提高 +- [#2542](https://github.com/sanic-org/sanic/pull/2542) Add _[redacted]_ to CLI :) +- [#2546](https://github.com/sanic-org/sanic/pull/2546) Add deprecation warning filter +- [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware priority and performance enhancements ### 错误修正 -- [#2495](https://github.com/sanic-org/sanic/pull/2495) 防止目录陷阱与静态文件 -- [#2515](https://github.com/sanic-org/sanic/pull/2515) 不要在蓝图中的某些静态目录中对路径使用双斜线 +- [#2495](https://github.com/sanic-org/sanic/pull/2495) Prevent directory traversion with static files +- [#2515](https://github.com/sanic-org/sanic/pull/2515) Do not apply double slash to paths in certain static dirs in Blueprints -### 废弃和移除 +### Deprecations and Removals -- [#2525](https://github.com/sanic-org/sanic/pull/225) 在重复的路线名称上发出警告，将在 v23.3 中彻底防止发出警告。 -- [#2537](https://github.com/sanic-org/sanic/pull/2537) 对于重复的例外情况发出警告和弃置通知，将在v23.3中彻底防止。 +- [#2525](https://github.com/sanic-org/sanic/pull/2525) Warn on duplicate route names, will be prevented outright in v23.3 +- [#2537](https://github.com/sanic-org/sanic/pull/2537) Raise warning and deprecation notice on duplicate exceptions, will be prevented outright in v23.3 -### 开发者基础设施 +### Developer infrastructure -- [#2504](https://github.com/sanic-org/sanic/pull/2504) 清理测试套件 -- [#2505](https://github.com/sanic-org/sanic/pull/2505) 从贡献工具箱中替换不支持的 Python 版本 -- [#2530](https://github.com/sanic-org/sanic/pull/2530) +- [#2504](https://github.com/sanic-org/sanic/pull/2504) Cleanup test suite +- [#2505](https://github.com/sanic-org/sanic/pull/2505) Replace Unsupported Python Version Number from the Contributing Doc +- [#2530](https://github.com/sanic-org/sanic/pull/2530) Do not include tests folder in installed package resolver -### 改进文档 +### Improved Documentation -- [#2502](https://github.com/sanic-org/sanic/pull/2502) 修复几个typos -- [#2517](https://github.com/sanic-org/sanic/pull/2517)[#2536](https://github.com/sanic-org/sanic/pull/2536) 添加一些类型的提示 +- [#2502](https://github.com/sanic-org/sanic/pull/2502) Fix a few typos +- [#2517](https://github.com/sanic-org/sanic/pull/2517) [#2536](https://github.com/sanic-org/sanic/pull/2536) Add some type hints -## 22.6.2 版本 +## Version 22.6.2 -### 错误修正 +### Bugfixes -- [#2522](https://github.com/sanic-org/sanic/pull/252) 始终在ASGI 中显示服务器位置 +- [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI -## 22.6.1 版本 +## Version 22.6.1 -### 错误修正 +### Bugfixes -- [#2477](https://github.com/sanic-org/sanic/pull/2477) 当文件夹名称以“...”结尾时，无声静态目录失败 +- [#2477](https://github.com/sanic-org/sanic/pull/2477) Sanic static directory fails when folder name ends with ".." -## 版本 22.6.0 +## Version 22.6.0 -### 功能 +### Features -- [#2378](https://github.com/sanic-org/sanic/pull/2378) 在 `DEBUG` 模式中引入HTTP/3 和 TLS 证书的自动生成 - - 👶 _EARLY RELEASE FEATURE_: 通过 HTTP/3 提供Sanic 是一种提早发布功能。 它尚未完全涵盖HTTP/3 单项，而是旨在与现有的 HTTP/1.1 服务器实现功能对等。 Websockets, WebTransport, 推送响应是一些尚未实现的功能的例子。 - - 📦 _EXTRA REQUIREMENT_: 并非所有HTTP客户端都能够与 HTTP/3 服务器接口。 您可能需要安装 [HTTP 3 能够安装的客户端](https://curl.se/docs/http3.html)。 - - 📦 _EXTRA REQUIREMENT_: 若要使用 TLS 自动生成，您必须安装 [mkcert](https://github.com/FiloSottile/mkcert) 或 [trustme](https://github.com/python-trio/trustme)。 -- [#2416](https://github.com/sanic-org/sanic/pull/2416) 将消息添加到 `task.cancel` -- [#2420](https://github.com/sanic-org/sanic/pull/2420) 添加异常别名以更一致地命名与标准HTTP响应类型(`BadRequest`, `MethodNotalled`, `RangeNotSatisfiable`) -- [#2432](https://github.com/sanic-org/sanic/pull/2432) 将ASGI `scope` 作为一个 `Request` 对象的属性 -- [#2438](https://github.com/sanic-org/sanic/pull/2438) 更容易访问Websocket类别以获取批注: `from sanic import Websocket` -- [#2439](https://github.com/sanic-org/sanic/pull/2439) 新API用于阅读带有选项的表格值：`Request.get_form` -- [#2445](https://github.com/sanic-org/sanic/pull/2445) 添加自定义 `loads` 函数 -- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) 改进API以支持设置缓存控制头部 -- [#2453](https://github.com/sanic-org/sanic/pull/2453) 移动动词过滤器到记录器 -- [#2475](https://github.com/sanic-org/sanic/pull/2475) 使用 `Request.get_current()` 方法显示当前请求的获取器 +- [#2378](https://github.com/sanic-org/sanic/pull/2378) Introduce HTTP/3 and autogeneration of TLS certificates in `DEBUG` mode + - 👶 _EARLY RELEASE FEATURE_: Serving Sanic over HTTP/3 is an early release feature. It does not yet fully cover the HTTP/3 spec, but instead aims for feature parity with Sanic's existing HTTP/1.1 server. Websockets, WebTransport, push responses are examples of some features not yet implemented. + - 📦 _EXTRA REQUIREMENT_: Not all HTTP clients are capable of interfacing with HTTP/3 servers. You may need to install a [HTTP/3 capable client](https://curl.se/docs/http3.html). + - 📦 _EXTRA REQUIREMENT_: In order to use TLS autogeneration, you must install either [mkcert](https://github.com/FiloSottile/mkcert) or [trustme](https://github.com/python-trio/trustme). +- [#2416](https://github.com/sanic-org/sanic/pull/2416) Add message to `task.cancel` +- [#2420](https://github.com/sanic-org/sanic/pull/2420) Add exception aliases for more consistent naming with standard HTTP response types (`BadRequest`, `MethodNotAllowed`, `RangeNotSatisfiable`) +- [#2432](https://github.com/sanic-org/sanic/pull/2432) Expose ASGI `scope` as a property on the `Request` object +- [#2438](https://github.com/sanic-org/sanic/pull/2438) Easier access to websocket class for annotation: `from sanic import Websocket` +- [#2439](https://github.com/sanic-org/sanic/pull/2439) New API for reading form values with options: `Request.get_form` +- [#2445](https://github.com/sanic-org/sanic/pull/2445) Add custom `loads` function +- [#2447](https://github.com/sanic-org/sanic/pull/2447), [#2486](https://github.com/sanic-org/sanic/pull/2486) Improved API to support setting cache control headers +- [#2453](https://github.com/sanic-org/sanic/pull/2453) Move verbosity filtering to logger +- [#2475](https://github.com/sanic-org/sanic/pull/2475) Expose getter for current request using `Request.get_current()` ### 错误修正 -- [#2448](https://github.com/sanic-org/sanic/pull/2448) 修正允许使用 pythonw\.exe\` 或没有 'sys.stdout' 的地方运行 -- [#2451](https://github.com/sanic-org/sanic/pull/2451)在 ASGI 模式中触发`http.lifecycle.request` 信号 -- [#2455](https://github.com/sanic-org/sanic/pull/2455) 解决堆叠路线定义的打字问题 -- [#2463](https://github.com/sanic-org/sanic/pull/2463) Python 3.7 Websocket 处理程序中正确捕获websocket 取消错误 +- [#2448](https://github.com/sanic-org/sanic/pull/2448) Fix to allow running with `pythonw.exe` or places where there is no `sys.stdout` +- [#2451](https://github.com/sanic-org/sanic/pull/2451) Trigger `http.lifecycle.request` signal in ASGI mode +- [#2455](https://github.com/sanic-org/sanic/pull/2455) Resolve typing of stacked route definitions +- [#2463](https://github.com/sanic-org/sanic/pull/2463) Properly catch websocket CancelledError in websocket handler in Python 3.7 -### 废弃和移除 +### Deprecations and Removals -- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 废弃和更改 - 1. 可选的应用程序注册 - 2. 发送部分响应后执行自定义处理程序 - 3. 在 `ErrorHandler` 上配置回退处理 - 4. 自定义 `LOGO` 设置 +- [#2487](https://github.com/sanic-org/sanic/pull/2487) v22.6 deprecations and changes + 1. Optional application registry + 2. Execution of custom handlers after some part of response was sent + 3. Configuring fallback handlers on the `ErrorHandler` + 4. Custom `LOGO` setting 5. `sanic.response.stream` 6. `AsyncioServer.init` -### 开发者基础设施 +### Developer infrastructure -- [#2449](https://github.com/sanic-org/sanic/pull/2449) 清理`black`和`isort`配置 -- [#2479](https://github.com/sanic-org/sanic/pull/2479) 修复一些简易测试 +- [#2449](https://github.com/sanic-org/sanic/pull/2449) Clean up `black` and `isort` config +- [#2479](https://github.com/sanic-org/sanic/pull/2479) Fix some flappy tests -### 改进文档 +### Improved Documentation -- [#2461](https://github.com/sanic-org/sanic/pull/2461) 更新示例以匹配当前应用程序命名标准 -- [#2466](https://github.com/sanic-org/sanic/pull/2466) 更好类型`Extend` -- [#2485](https://github.com/sanic-org/sanic/pull/2485) 改进CLI 中的帮助信息 +- [#2461](https://github.com/sanic-org/sanic/pull/2461) Update example to match current application naming standards +- [#2466](https://github.com/sanic-org/sanic/pull/2466) Better type annotation for `Extend` +- [#2485](https://github.com/sanic-org/sanic/pull/2485) Improved help messages in CLI -## 版本22.3.0 +## Version 22.3.0 -### 功能 +### Features -- [#2347](https://github.com/sanic-org/sanic/pull/2347) 多应用程序服务器的 API - - 🚨 _Breaking CHANGE_: 旧的 `sanic.worker.GunicornWorker` 已被删除 \*\*。 若要用 `gunicorn` 来运行Sanic，你应该使用它`uvicorn` [如他们的文件中所述](https://www.uvicorn.org/#running-with-gunicorn)。 - - 🧁 _SIDE EFFECT_: 命名后台任务现在得到支持, 甚至是 Python 3.7 +- [#2347](https://github.com/sanic-org/sanic/pull/2347) API for multi-application server + - 🚨 _BREAKING CHANGE_: The old `sanic.worker.GunicornWorker` has been **removed**. To run Sanic with `gunicorn`, you should use it thru `uvicorn` [as described in their docs](https://www.uvicorn.org/#running-with-gunicorn). + - 🧁 _SIDE EFFECT_: Named background tasks are now supported, even in Python 3.7 - [#2357](https://github.com/sanic-org/sanic/pull/2357) Parse `Authorization` header as `Request.credentials` -- [#2361](https://github.com/sanic-org/sanic/pull/2361) 在应用程序启动时添加配置选项以跳过`Touchup` 步骤 -- [#2372](https://github.com/sanic-org/sanic/pull/2372) 更新到 CLI 帮助发送消息 -- [#2382](https://github.com/sanic-org/sanic/pull/2382) 降级警告到背水调试消息 -- [#2396](https://github.com/sanic-org/sanic/pull/2396) 允许使用 `multidict` v0.6 -- [#2401](https://github.com/sanic-org/sanic/pull/2401) 升级 CLI 捕获替代应用程序运行类型 -- [#2402](https://github.com/sanic-org/sanic/pull/2402) 有条件将CLI 参数注入工厂中 -- [#2413](https://github.com/sanic-org/sanic/pull/2413) 添加新的开始和停止事件监听器到阅读器进程 -- [#2414](https://github.com/sanic-org/sanic/pull/2414) 移除循环作为必要的听众arg -- [#2415](https://github.com/sanic-org/sanic/pull/245) -- [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) 添加一个新的退出参数类型：``, ``, ``, ` `, ``, ``, `` - - 👶 _BETA FEATURE_: 此功能将无法与 `path` 类型匹配, 并且仅作为测试版发布. -- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) 更改`register_pattern` 以接受一个 `str` 或 `Pattern` -- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) 仅在非空字符串上默认匹配，以及新的 `strempty` 模式类型 - - 🚨 _Breaking变异_: 之前带有动态字符串参数的路由(`/` 或 `/`) 将在任何字符串上匹配, 包含空字符串。 现在**仅** 匹配一个非空字符串。 要保留旧的行为，您应该使用新的参数类型：`/`。 +- [#2361](https://github.com/sanic-org/sanic/pull/2361) Add config option to skip `Touchup` step in application startup +- [#2372](https://github.com/sanic-org/sanic/pull/2372) Updates to CLI help messaging +- [#2382](https://github.com/sanic-org/sanic/pull/2382) Downgrade warnings to backwater debug messages +- [#2396](https://github.com/sanic-org/sanic/pull/2396) Allow for `multidict` v0.6 +- [#2401](https://github.com/sanic-org/sanic/pull/2401) Upgrade CLI catching for alternative application run types +- [#2402](https://github.com/sanic-org/sanic/pull/2402) Conditionally inject CLI arguments into factory +- [#2413](https://github.com/sanic-org/sanic/pull/2413) Add new start and stop event listeners to reloader process +- [#2414](https://github.com/sanic-org/sanic/pull/2414) Remove loop as required listener arg +- [#2415](https://github.com/sanic-org/sanic/pull/2415) Better exception for bad URL parsing +- [sanic-routing#47](https://github.com/sanic-org/sanic-routing/pull/47) Add a new extention parameter type: ``, ``, ``, ``, ``, `` + - 👶 _BETA FEATURE_: This feature will not work with `path` type matching, and is being released as a beta feature only. +- [sanic-routing#57](https://github.com/sanic-org/sanic-routing/pull/57) Change `register_pattern` to accept a `str` or `Pattern` +- [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) Default matching on non-empty strings only, and new `strorempty` pattern type + - 🚨 _BREAKING CHANGE_: Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now **only** match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. ### 错误修正 -- [#2373](https://github.com/sanic-org/sanic/pull/2373) 在websockets上删除 `error_logger` -- [#2381](https://github.com/sanic-org/sanic/pull/2381) 修复任务注册表中新分配的`None` -- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) 添加类型铸造到regex route 匹配 -- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) 在regex routing上添加要求检查(这个解析方法是多个静态目录，具有不同的`host`值) +- [#2373](https://github.com/sanic-org/sanic/pull/2373) Remove `error_logger` on websockets +- [#2381](https://github.com/sanic-org/sanic/pull/2381) Fix newly assigned `None` in task registry +- [sanic-routing#52](https://github.com/sanic-org/sanic-routing/pull/52) Add type casting to regex route matching +- [sanic-routing#60](https://github.com/sanic-org/sanic-routing/pull/60) Add requirements check on regex routes (this resolves, for example, multiple static directories with differing `host` values) -### 废弃和移除 +### Deprecations and Removals -- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 废弃和更改 - 1. `debug=True` 和 `--debug` 做_NOT_ 自动运行 `auto_reload` - 2. 默认错误渲染为纯文本(默认仍然获取 HTML ，因为`auto` 看着头部) - 3. `config` 是需要 `ErrorHandler.finalize` - 4. `ErrorHandler.lookup` 需要两个位置参数 - 5. 未使用的 websocket 协议参数已删除 -- [#2344](https://github.com/sanic-org/sanic/pull/2344) 废弃加载小写环境变量 +- [#2362](https://github.com/sanic-org/sanic/pull/2362) 22.3 Deprecations and changes + 1. `debug=True` and `--debug` do _NOT_ automatically run `auto_reload` + 2. Default error render is with plain text (browsers still get HTML by default because `auto` looks at headers) + 3. `config` is required for `ErrorHandler.finalize` + 4. `ErrorHandler.lookup` requires two positional args + 5. Unused websocket protocol args removed +- [#2344](https://github.com/sanic-org/sanic/pull/2344) Deprecate loading of lowercase environment variables -### 开发者基础设施 +### Developer infrastructure -- [#2363](https://github.com/sanic-org/sanic/pull/2363) 将代码覆盖范围还原到 Codecov -- [#2405](https://github.com/sanic-org/sanic/pull/2405) 升级`sanic-routing`更改测试 -- [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) 允许 httpx v0.22 +- [#2363](https://github.com/sanic-org/sanic/pull/2363) Revert code coverage back to Codecov +- [#2405](https://github.com/sanic-org/sanic/pull/2405) Upgrade tests for `sanic-routing` changes +- [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) Allow for httpx v0.22 -### 改进文档 +### Improved Documentation -- [#2350](https://github.com/sanic-org/sanic/pull/2350) README中的 ASGI 修复链接 -- [#2398](https://github.com/sanic-org/sanic/pull/2398) 文档中间件on_request 和 on_response -- [#2409](https://github.com/sanic-org/sanic/pull/2409) 添加缺失的`Request.respond `文档 +- [#2350](https://github.com/sanic-org/sanic/pull/2350) Fix link in README for ASGI +- [#2398](https://github.com/sanic-org/sanic/pull/2398) Document middleware on_request and on_response +- [#2409](https://github.com/sanic-org/sanic/pull/2409) Add missing documentation for `Request.respond` -### 其他事项 +### Miscellaneous -- [#2376](https://github.com/sanic-org/sanic/pull/2376) 修复`ListenerMixin.listener` -- [#2383](https://github.com/sanic-org/sanic/pull/2383) 在 `asyncio.wait` 中清除废弃警告。 +- [#2376](https://github.com/sanic-org/sanic/pull/2376) Fix typing for `ListenerMixin.listener` +- [#2383](https://github.com/sanic-org/sanic/pull/2383) Clear deprecation warning in `asyncio.wait` - [#2387](https://github.com/sanic-org/sanic/pull/2387) Cleanup `__slots__` implementations -- [#2390](https://github.com/sanic-org/sanic/pull/2390) 在 `asyncio.get_event_loop` 中清除废弃警告 - -## 版本21.12.1 - -- [#2349](https://github.com/sanic-org/sanic/pull/2349) 仅在启动时显示MOTD -- [#2354](https://github.com/sanic-org/sanic/pull/2354) 忽略Python 3.7 中的名称参数 -- [#2355](https://github.com/sanic-org/sanic/pull/2355) 添加config.update 支持所有配置 - -## 版本21.12.0 - -### 功能 - -- [#2260](https://github.com/sanic-org/sanic/pull/2260) 允许早期蓝图注册仍然应用以后添加的对象 -- [No. 2262](https://github.com/sanic-org/sanic/pull/2262) 噪音异常——强制记录所有异常 -- [#2264](https://github.com/sanic-org/sanic/pull/2264) 可选的`uvloop` -- [#2270](https://github.com/sanic-org/sanic/pull/2270) 使用多个TLS证书支持虚拟主机 -- [#2277](https://github.com/sanic-org/sanic/pull/2277) 为提高一致性而改变信号路由 - - _购买更改_：如果你是手动路由信号，有一个破碎的变化。 信号路由器的 `get` 不再是 100% 的决定因素。 现在有一个额外的步骤来循环回来的信号，以便在要求上进行适当的匹配。 如果正在使用`app.rapoch`或`bp.poidch`发出信号'发出信号的话，则没有变化。 -- [#2290](https://github.com/sanic-org/sanic/pull/2290) 添加上下文异常 -- [#2291](https://github.com/sanic-org/sanic/pull/2291) -- [#2295](https://github.com/sanic-org/sanic/pull/2295)，[#2316](https://github.com/sanic-org/sanic/pull/2316)，[#2331](https://github.com/sanic-org/sanic/pull/23331) 重新调整CLI和应用程序状态，使用新的显示和更多的命令对等性 -- [#2302](https://github.com/sanic-org/sanic/pull/2302) 在定义时间添加路由环境 -- [#2304](https://github.com/sanic-org/sanic/pull/2304) 命名任务和新的 API 用于管理背景任务 -- [#2307](https://github.com/sanic-org/sanic/pull/2307) 在应用自动重新加载时，提供已更改文件的见解。 -- [#2308](https://github.com/sanic-org/sanic/pull/2308) 安装后自动扩展应用程序[Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) 并提供第一类支持访问扩展。 -- [#2309](https://github.com/sanic-org/sanic/pull/2309) -- [#2313](https://github.com/sanic-org/sanic/pull/2313) 支持额外配置实现使用 -- [#2321](https://github.com/sanic-org/sanic/pull/2321) -- [#2327](https://github.com/sanic-org/sanic/pull/2327) 防止对单个请求发送多个或混合的答复 -- [#2330](https://github.com/sanic-org/sanic/pull/2330) 环境变量定制类型投射器 -- [#2332](https://github.com/sanic-org/sanic/pull/2332) 使所有废弃通知保持一致 -- [#2335](https://github.com/sanic-org/sanic/pull/2335) 允许下划线开始实例名称 - -### 错误修正 - -- [#2273](https://github.com/sanic-org/sanic/pull/2273) 替换分配给`websocket_handshake` -- [#2285](https://github.com/sanic-org/sanic/pull/2285) 修复启动日志中的IPv6 显示 -- [#2299](https://github.com/sanic-org/sanic/pull/2299) 从异常处理器调度`http.lifecyle.response` - -### 废弃和移除 - -- [#2306](https://github.com/sanic-org/sanic/pull/2306) 移除弃用的项目 - - `Sanic` 和 `Blueprint` 可能不再具有附加于它们的任意属性 - - `Sanic` 和 `Blueprint` 被迫有符合要求的名称 +- [#2390](https://github.com/sanic-org/sanic/pull/2390) Clear deprecation warning in `asyncio.get_event_loop` + +## Version 21.12.1 + +- [#2349](https://github.com/sanic-org/sanic/pull/2349) Only display MOTD on startup +- [#2354](https://github.com/sanic-org/sanic/pull/2354) Ignore name argument in Python 3.7 +- [#2355](https://github.com/sanic-org/sanic/pull/2355) Add config.update support for all config values + +## Version 21.12.0 + +### Features + +- [#2260](https://github.com/sanic-org/sanic/pull/2260) Allow early Blueprint registrations to still apply later added objects +- [#2262](https://github.com/sanic-org/sanic/pull/2262) Noisy exceptions - force logging of all exceptions +- [#2264](https://github.com/sanic-org/sanic/pull/2264) Optional `uvloop` by configuration +- [#2270](https://github.com/sanic-org/sanic/pull/2270) Vhost support using multiple TLS certificates +- [#2277](https://github.com/sanic-org/sanic/pull/2277) Change signal routing for increased consistency + - _BREAKING CHANGE_: If you were manually routing signals there is a breaking change. The signal router's `get` is no longer 100% determinative. There is now an additional step to loop thru the returned signals for proper matching on the requirements. If signals are being dispatched using `app.dispatch` or `bp.dispatch`, there is no change. +- [#2290](https://github.com/sanic-org/sanic/pull/2290) Add contextual exceptions +- [#2291](https://github.com/sanic-org/sanic/pull/2291) Increase join concat performance +- [#2295](https://github.com/sanic-org/sanic/pull/2295), [#2316](https://github.com/sanic-org/sanic/pull/2316), [#2331](https://github.com/sanic-org/sanic/pull/2331) Restructure of CLI and application state with new displays and more command parity with `app.run` +- [#2302](https://github.com/sanic-org/sanic/pull/2302) Add route context at definition time +- [#2304](https://github.com/sanic-org/sanic/pull/2304) Named tasks and new API for managing background tasks +- [#2307](https://github.com/sanic-org/sanic/pull/2307) On app auto-reload, provide insight of changed files +- [#2308](https://github.com/sanic-org/sanic/pull/2308) Auto extend application with [Sanic Extensions](https://sanicframework.org/en/plugins/sanic-ext/getting-started.html) if it is installed, and provide first class support for accessing the extensions +- [#2309](https://github.com/sanic-org/sanic/pull/2309) Builtin signals changed to `Enum` +- [#2313](https://github.com/sanic-org/sanic/pull/2313) Support additional config implementation use case +- [#2321](https://github.com/sanic-org/sanic/pull/2321) Refactor environment variable hydration logic +- [#2327](https://github.com/sanic-org/sanic/pull/2327) Prevent sending multiple or mixed responses on a single request +- [#2330](https://github.com/sanic-org/sanic/pull/2330) Custom type casting on environment variables +- [#2332](https://github.com/sanic-org/sanic/pull/2332) Make all deprecation notices consistent +- [#2335](https://github.com/sanic-org/sanic/pull/2335) Allow underscore to start instance names + +### Bugfixes + +- [#2273](https://github.com/sanic-org/sanic/pull/2273) Replace assignation by typing for `websocket_handshake` +- [#2285](https://github.com/sanic-org/sanic/pull/2285) Fix IPv6 display in startup logs +- [#2299](https://github.com/sanic-org/sanic/pull/2299) Dispatch `http.lifecyle.response` from exception handler + +### Deprecations and Removals + +- [#2306](https://github.com/sanic-org/sanic/pull/2306) Removal of deprecated items + - `Sanic` and `Blueprint` may no longer have arbitrary properties attached to them + - `Sanic` and `Blueprint` forced to have compliant names - alphanumeric + `_` + `-` - - 必须以字母或`_`开头。 - - `load_env`关键词参数 `Sanic` - - `sanic.exceptions.abot` - - `sanic.views.compositionView` + - must start with letter or `_` + - `load_env` keyword argument of `Sanic` + - `sanic.exceptions.abort` + - `sanic.views.CompositionView` - `sanic.response.StreamingHTTPResponse` - - _注意:_ `stream()`响应方法(如果你通过了一个可调用的流媒体函数)已被弃用,将在 v22.6 中删除。 您应该将所有流媒体响应升级到新风格：https\://sanicframework.org/en/guide/advanced/streaming.html#response-串流 -- [#2320](https://github.com/sanic-org/sanic/pull/2320) 从配置中删除应用实例以进行错误处理设置 + - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming +- [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting -### 开发者基础设施 +### Developer infrastructure -- [#2251](https://github.com/sanic-org/sanic/pull/2251) 更改安装命令 -- [#2286](https://github.com/sanic-org/sanic/pull/2286) 更改编解码复杂性阈值从 5 到 10 -- [#2287](https://github.com/sanic-org/sanic/pull/2287) 更新主机测试函数名以免被覆盖 -- [#2292](https://github.com/sanic-org/sanic/pull/2292) 错误故障CI -- [#2311](https://github.com/sanic-org/sanic/pull/2311) [#2324](https://github.com/sanic-org/sanic/pull/224) 不对PR草案进行测试 -- [#2336](https://github.com/sanic-org/sanic/pull/2336) 从覆盖面检查中删除路径 -- [#2338](https://github.com/sanic-org/sanic/pull/2338) 测试端口清理 +- [#2251](https://github.com/sanic-org/sanic/pull/2251) Change dev install command +- [#2286](https://github.com/sanic-org/sanic/pull/2286) Change codeclimate complexity threshold from 5 to 10 +- [#2287](https://github.com/sanic-org/sanic/pull/2287) Update host test function names so they are not overwritten +- [#2292](https://github.com/sanic-org/sanic/pull/2292) Fail CI on error +- [#2311](https://github.com/sanic-org/sanic/pull/2311), [#2324](https://github.com/sanic-org/sanic/pull/2324) Do not run tests for draft PRs +- [#2336](https://github.com/sanic-org/sanic/pull/2336) Remove paths from coverage checks +- [#2338](https://github.com/sanic-org/sanic/pull/2338) Cleanup ports on tests -### 改进文档 +### Improved Documentation -- [#2269](https://github.com/sanic-org/sanic/pull/2269)，[#2329](https://github.com/sanic-org/sanic/pull/2329)，[#2333](https://github.com/sanic-org/sanic/pull/233) 清理typos和修复语言 +- [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2329), [#2333](https://github.com/sanic-org/sanic/pull/2333) Cleanup typos and fix language -### 其他事项 +### Miscellaneous -- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) 添加 Python 3.10 支持 -- [#2279](https://github.com/sanic-org/sanic/pull/2279)，[#2317](https://github.com/sanic-org/sanic/pull/2317)，[#2322](https://github.com/sanic-org/sanic/pull/232) 添加/正确缺失的类型注释 -- [#2305](https://github.com/sanic-org/sanic/pull/2305) 修复使用现代实现的例子 +- [#2257](https://github.com/sanic-org/sanic/pull/2257), [#2294](https://github.com/sanic-org/sanic/pull/2294), [#2341](https://github.com/sanic-org/sanic/pull/2341) Add Python 3.10 support +- [#2279](https://github.com/sanic-org/sanic/pull/2279), [#2317](https://github.com/sanic-org/sanic/pull/2317), [#2322](https://github.com/sanic-org/sanic/pull/2322) Add/correct missing type annotations +- [#2305](https://github.com/sanic-org/sanic/pull/2305) Fix examples to use modern implementations -## 21.9.3 版本 +## Version 21.9.3 -- 通过清理恢复v21.9.2 \* +_Rerelease of v21.9.2 with some cleanup_ -## 第21.9.2 版 +## Version 21.9.2 -- [#2268](https://github.com/sanic-org/sanic/pull/2268) -- [#2310](https://github.com/sanic-org/sanic/pull/2310) +- [#2268](https://github.com/sanic-org/sanic/pull/2268) Make HTTP connections start in IDLE stage, avoiding delays and error messages +- [#2310](https://github.com/sanic-org/sanic/pull/2310) More consistent config setting with post-FALLBACK_ERROR_FORMAT apply -## 21.9.1 版本 +## Version 21.9.1 -- [#2259](https://github.com/sanic-org/sanic/pull/2259) 允许不符合要求的错误处理 +- [#2259](https://github.com/sanic-org/sanic/pull/2259) Allow non-conforming ErrorHandlers -## 版本21.9.0 +## Version 21.9.0 -### 功能 +### Features -- [#2158](https://github.com/sanic-org/sanic/pull/2158)，[#2248](https://github.com/sanic-org/sanic/pull/2248) 全面整修I/O至websockets -- [#2160](https://github.com/sanic-org/sanic/pull/2160) 将新的17个信号添加到服务器并请求生命周期 -- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto`退回格式化异常) -- [#2184](https://github.com/sanic-org/sanic/pull/2184) -- [#2200](https://github.com/sanic-org/sanic/pull/2200) 接受标题解析 -- [#2207](https://github.com/sanic-org/sanic/pull/2207) 日志远程地址如果可用 -- [#2209](https://github.com/sanic-org/sanic/pull/2209) 向BP组添加方便方法 -- [#2216](https://github.com/sanic-org/sanic/pull/2216) 将默认消息添加到 SanicExceptions -- [#2225](https://github.com/sanic-org/sanic/pull/2225) -- [#2236](https://github.com/sanic-org/sanic/pull/2236) 允许Falsey(但不是)从路由处理器中回复 -- [#2238](https://github.com/sanic-org/sanic/pull/2238) 在蓝图组中加上“异常”装饰符 -- [#2244](https://github.com/sanic-org/sanic/pull/2244) 对服务文件或目录的静态明确指令(例如: `static(..., resource_type="file")` -- [#2245](https://github.com/sanic-org/sanic/pull/2245) 在连接任务取消时关闭HTTP循环 +- [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) Complete overhaul of I/O to websockets +- [#2160](https://github.com/sanic-org/sanic/pull/2160) Add new 17 signals into server and request lifecycles +- [#2162](https://github.com/sanic-org/sanic/pull/2162) Smarter `auto` fallback formatting upon exception +- [#2184](https://github.com/sanic-org/sanic/pull/2184) Introduce implementation for copying a Blueprint +- [#2200](https://github.com/sanic-org/sanic/pull/2200) Accept header parsing +- [#2207](https://github.com/sanic-org/sanic/pull/2207) Log remote address if available +- [#2209](https://github.com/sanic-org/sanic/pull/2209) Add convenience methods to BP groups +- [#2216](https://github.com/sanic-org/sanic/pull/2216) Add default messages to SanicExceptions +- [#2225](https://github.com/sanic-org/sanic/pull/2225) Type annotation convenience for annotated handlers with path parameters +- [#2236](https://github.com/sanic-org/sanic/pull/2236) Allow Falsey (but not-None) responses from route handlers +- [#2238](https://github.com/sanic-org/sanic/pull/2238) Add `exception` decorator to Blueprint Groups +- [#2244](https://github.com/sanic-org/sanic/pull/2244) Explicit static directive for serving file or dir (ex: `static(..., resource_type="file")`) +- [#2245](https://github.com/sanic-org/sanic/pull/2245) Close HTTP loop when connection task cancelled -### 错误修正 +### Bugfixes -- [#2188](https://github.com/sanic-org/sanic/pull/2188) 修复对块请求结束的处理 -- [#2195](https://github.com/sanic-org/sanic/pull/2195) 解决静态请求处理意外错误 -- [#2208](https://github.com/sanic-org/sanic/pull/2208) -- [#2211](https://github.com/sanic-org/sanic/pull/2211) 固定用于处理异常的 asgi 应用程序调用 -- [#2213](https://github.com/sanic-org/sanic/pull/2213) 修复错误，在这个错误中，没有记录除数 -- [#2231](https://github.com/sanic-org/sanic/pull/2231) 清理结束任务，在战略地点使用“abort()”以避免染色套接字 -- [#2247](https://github.com/sanic-org/sanic/pull/2247) 修复调试模式下自动重新加载状态记录 -- [#2246](https://github.com/sanic-org/sanic/pull/2246) 为BP账户，但没有路由 +- [#2188](https://github.com/sanic-org/sanic/pull/2188) Fix the handling of the end of a chunked request +- [#2195](https://github.com/sanic-org/sanic/pull/2195) Resolve unexpected error handling on static requests +- [#2208](https://github.com/sanic-org/sanic/pull/2208) Make blueprint-based exceptions attach and trigger in a more intuitive manner +- [#2211](https://github.com/sanic-org/sanic/pull/2211) Fixed for handling exceptions of asgi app call +- [#2213](https://github.com/sanic-org/sanic/pull/2213) Fix bug where ws exceptions not being logged +- [#2231](https://github.com/sanic-org/sanic/pull/2231) Cleaner closing of tasks by using `abort()` in strategic places to avoid dangling sockets +- [#2247](https://github.com/sanic-org/sanic/pull/2247) Fix logging of auto-reload status in debug mode +- [#2246](https://github.com/sanic-org/sanic/pull/2246) Account for BP with exception handler but no routes -### 开发者基础设施 +### Developer infrastructure -- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP Unit tests with raw 客户端 -- [#2199](https://github.com/sanic-org/sanic/pull/2199) 切换到解码器 -- [#2214](https://github.com/sanic-org/sanic/pull/2214) 尝试重启Windows 测试 -- [#2229](https://github.com/sanic-org/sanic/pull/2229) 将`HttpProtocol`重新因素变成一个基准类 -- [#2230](https://github.com/sanic-org/sanic/pull/2230) 重新因素`server.py`到多文件模块 +- [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP unit tests with raw client +- [#2199](https://github.com/sanic-org/sanic/pull/2199) Switch to codeclimate +- [#2214](https://github.com/sanic-org/sanic/pull/2214) Try Reopening Windows Tests +- [#2229](https://github.com/sanic-org/sanic/pull/2229) Refactor `HttpProtocol` into a base class +- [#2230](https://github.com/sanic-org/sanic/pull/2230) Refactor `server.py` into multi-file module -### 其他事项 +### Miscellaneous -- [#2173](https://github.com/sanic-org/sanic/pull/2173) 删除重复的依赖关系和 PEP 517 支持 -- [#2193](https://github.com/sanic-org/sanic/pull/2193)，[#2196](https://github.com/sanic-org/sanic/pull/2196)，[#2217](https://github.com/sanic-org/sanic/pull/2217) +- [#2173](https://github.com/sanic-org/sanic/pull/2173) Remove Duplicated Dependencies and PEP 517 Support +- [#2193](https://github.com/sanic-org/sanic/pull/2193), [#2196](https://github.com/sanic-org/sanic/pull/2196), [#2217](https://github.com/sanic-org/sanic/pull/2217) Type annotation changes -## 版本21.6.1 +## Version 21.6.1 -**错误修复** +**Bugfixes** - [#2178](https://github.com/sanic-org/sanic/pull/2178) Update sanic-routing to allow for better splitting of complex URI templates - [#2183](https://github.com/sanic-org/sanic/pull/2183) Proper - 处理块请求机构以解析日志中的幽灵503 -- [#2181](https://github.com/sanic-org/sanic/pull/2181) 解决异常日志中的 - 回归问题 -- [#2201](https://github.com/sanic-org/sanic/pull/2201) 清理管道请求中的 - 请求 + handling of chunked request bodies to resolve phantom 503 in logs +- [#2181](https://github.com/sanic-org/sanic/pull/2181) Resolve + regression in exception logging +- [#2201](https://github.com/sanic-org/sanic/pull/2201) Cleanup + request info in pipelined requests -## 版本21.6.0 +## Version 21.6.0 -**特征** +**Features** - [#2094](https://github.com/sanic-org/sanic/pull/2094) Add `response.eof()` method for closing a stream in a handler -- [#2097](https://github.com/sanic-org/sanic/pull/2097) 允许 - 不区分大小写的 HTTP 升级标题 +- [#2097](https://github.com/sanic-org/sanic/pull/2097) Allow + case-insensitive HTTP Upgrade header - [#2104](https://github.com/sanic-org/sanic/pull/2104) Explicit usage of CIMultiDict getters @@ -561,30 +561,30 @@ _当前LTS版本_ - [#2109](https://github.com/sanic-org/sanic/pull/2109) Consistent use of error loggers -- [#2114](https://github.com/sanic-org/sanic/pull/2114) 新的 - `client_ip` 访问连接信息实例 +- [#2114](https://github.com/sanic-org/sanic/pull/2114) New + `client_ip` access of connection info instance - [#2119](https://github.com/sanic-org/sanic/pull/2119) Alternatate - 类实例化的`Config` 和 `Sanic.ctx` + classes on instantiation for `Config` and `Sanic.ctx` -- [#2133](https://github.com/sanic-org/sanic/pull/2133) 实现 - 新版本的 AST 路由器 +- [#2133](https://github.com/sanic-org/sanic/pull/2133) Implement + new version of AST router - - `alpha` 和 `string`param - 类型之间的适当区别 - - 添加一个 `slug` 参数类型，例如：`` - - 废弃foo:string`而改成`。 - - 废弃foo:number`而改成`。 + - Proper differentiation between `alpha` and `string` param + types + - Adds a `slug` param type, example: `` + - Deprecates `` in favor of `` + - Deprecates `` in favor of `` - Adds a `route.uri` accessor - [#2136](https://github.com/sanic-org/sanic/pull/2136) CLI - 改进使用新的可选参数 + improvements with new optional params -- [#2137](https://github.com/sanic-org/sanic/pull/2137) 在 URL 生成器中添加 - `version_prefix` +- [#2137](https://github.com/sanic-org/sanic/pull/2137) Add + `version_prefix` to URL builders -- [#2140](https://github.com/sanic-org/sanic/pull/2140) 事件 - 自动注册 with `EVENT_AUTORGISTER` +- [#2140](https://github.com/sanic-org/sanic/pull/2140) Event + autoregistration with `EVENT_AUTOREGISTER` - [#2146](https://github.com/sanic-org/sanic/pull/2146), [#2147](https://github.com/sanic-org/sanic/pull/2147) Require @@ -593,192 +593,193 @@ _当前LTS版本_ - [#2150](https://github.com/sanic-org/sanic/pull/2150) Infinitely reusable and nestable `Blueprint` and `BlueprintGroup` -- [#2154](https://github.com/sanic-org/sanic/pull/2154) 将 - `websockets` 依赖关系升级为最小版本 +- [#2154](https://github.com/sanic-org/sanic/pull/2154) Upgrade + `websockets` dependency to min version -- [#2155](https://github.com/sanic-org/sanic/pull/2155) 允许 - 增加最大标题尺寸：`REQUEST_MAX_HEADER_SIZE` +- [#2155](https://github.com/sanic-org/sanic/pull/2155) Allow for + maximum header sizes to be increased: `REQUEST_MAX_HEADER_SIZE` -- [#2157](https://github.com/sanic-org/sanic/pull/2157) 允许应用 - 出厂模式在 CLI +- [#2157](https://github.com/sanic-org/sanic/pull/2157) Allow app + factory pattern in CLI -- [#2165](https://github.com/sanic-org/sanic/pull/2165) 将 HTTP - 方法更改为enums +- [#2165](https://github.com/sanic-org/sanic/pull/2165) Change HTTP + methods to enums -- [#2167](https://github.com/sanic-org/sanic/pull/2167) 允许 - 自动重新加载附加目录 +- [#2167](https://github.com/sanic-org/sanic/pull/2167) Allow + auto-reloading on additional directories -- [#2168](https://github.com/sanic-org/sanic/pull/2168) 添加简单的 - HTTP 服务器到 CLI +- [#2168](https://github.com/sanic-org/sanic/pull/2168) Add simple + HTTP server to CLI -- [#2170](https://github.com/sanic-org/sanic/pull/2170) 附加的 - 方法附加`HTTPMethodView` +- [#2170](https://github.com/sanic-org/sanic/pull/2170) Additional + methods for attaching `HTTPMethodView` -**错误修复** +**Bugfixes** - [#2091](https://github.com/sanic-org/sanic/pull/2091) Fix `UserWarning` in ASGI mode for missing `__slots__` -- [#2099](https://github.com/sanic-org/sanic/pull/2099) 修复静态 - 请求处理记录异常于404 -- [#2110](https://github.com/sanic-org/sanic/pull/2110) 修复 - request.args.pop 去除不一致的参数 -- [#2107](https://github.com/sanic-org/sanic/pull/2107) 修理 - 引导load_env -- [#2127](https://github.com/sanic-org/sanic/pull/2127) 请确认 - ASGI ws 子协议是一个列表 -- [#2128](https://github.com/sanic-org/sanic/pull/2128) 修复问题 - 蓝图异常处理程序没有始终如一地路由到 - 适当处理程序 - -**废弃和删除** +- [#2099](https://github.com/sanic-org/sanic/pull/2099) Fix static + request handler logging exception on 404 +- [#2110](https://github.com/sanic-org/sanic/pull/2110) Fix + request.args.pop removes parameters inconsistently +- [#2107](https://github.com/sanic-org/sanic/pull/2107) Fix type + hinting for load_env +- [#2127](https://github.com/sanic-org/sanic/pull/2127) Make sure + ASGI ws subprotocols is a list +- [#2128](https://github.com/sanic-org/sanic/pull/2128) Fix issue + where Blueprint exception handlers do not consistently route to + proper handler + +**Deprecations and Removals** - [#2156](https://github.com/sanic-org/sanic/pull/2156) Remove config value `REQUEST_BUFFER_QUEUE_SIZE` - [#2170](https://github.com/sanic-org/sanic/pull/2170) - `CompositionView` 已废弃，并在21.12中标记为移除。 -- [#2172](https://github.com/sanic-org/sanic/pull/2170) 废弃 + `CompositionView` deprecated and marked for removal in 21.12 +- [#2172](https://github.com/sanic-org/sanic/pull/2170) Deprecate StreamingHTTPResponse -**开发者基础设施** +**Developer infrastructure** -- [#2149](https://github.com/sanic-org/sanic/pull/2149) 删除 - Travis CI 支持GitHub 操作 +- [#2149](https://github.com/sanic-org/sanic/pull/2149) Remove + Travis CI in favor of GitHub Actions -**改进文档** +**Improved Documentation** -- [#2164](https://github.com/sanic-org/sanic/pull/2164) 修复 - 文档中的类型 -- [#2100](https://github.com/sanic-org/sanic/pull/2100) 移除不存在的参数的 - 文档 +- [#2164](https://github.com/sanic-org/sanic/pull/2164) Fix typo in + documentation +- [#2100](https://github.com/sanic-org/sanic/pull/2100) Remove + documentation for non-existent arguments -## 21.3.2 版本 +## Version 21.3.2 -**错误修复** +**Bugfixes** -- [#2081](https://github.com/sanic-org/sanic/pull/2081) 在 websocket 连接上禁用 - 响应超时 +- [#2081](https://github.com/sanic-org/sanic/pull/2081) Disable + response timeout on websocket connections - [#2085](https://github.com/sanic-org/sanic/pull/2085) Make sure that blueprints with no slash is maintained when applied -## 版本21.3.1 +## Version 21.3.1 -**错误修复** +**Bugfixes** -- [#2076](https://github.com/sanic-org/sanic/pull/2076) 子文件夹内的静态文件 - 不可访问 (404) +- [#2076](https://github.com/sanic-org/sanic/pull/2076) Static files + inside subfolders are not accessible (404) -## 版本21.3.0 +## Version 21.3.0 -发布 -笔记 +Release +Notes -**特征** +**Features** - [#1876](https://github.com/sanic-org/sanic/pull/1876) Unified - 串流服务器 + streaming server - [#2005](https://github.com/sanic-org/sanic/pull/2005) New - `Request.id` 属性 -- [#2008](https://github.com/sanic-org/sanic/pull/2008) 允许 - Pathlib 路径对象传递给`app.static()` + `Request.id` property +- [#2008](https://github.com/sanic-org/sanic/pull/2008) Allow + Pathlib Path objects to be passed to `app.static()` helper - [#2010](https://github.com/sanic-org/sanic/pull/2010), [#2031](https://github.com/sanic-org/sanic/pull/2031) New - 启动-优化路由器 + startup-optimized router - [#2018](https://github.com/sanic-org/sanic/pull/2018) - [#2064](https://github.com/sanic-org/sanic/pull/2064) 主服务器进程的侦听器 -- [#2032](https://github.com/sanic-org/sanic/pull/2032) 添加原始的 - 头信息以请求对象 + [#2064](https://github.com/sanic-org/sanic/pull/2064) Listeners + for main server process +- [#2032](https://github.com/sanic-org/sanic/pull/2032) Add raw + header info to request object - [#2042](https://github.com/sanic-org/sanic/pull/2042) [#2060](https://github.com/sanic-org/sanic/pull/2060) [#2061](https://github.com/sanic-org/sanic/pull/2061) Introduce Signals API - [#2043](https://github.com/sanic-org/sanic/pull/2043) Add `__str__` and `__repr__` to Sanic and Blueprint -- [#2047](https://github.com/sanic-org/sanic/pull/2047) 启用 - 版本并在蓝图组上严格闪光灯 +- [#2047](https://github.com/sanic-org/sanic/pull/2047) Enable + versioning and strict slash on BlueprintGroup - [#2053](https://github.com/sanic-org/sanic/pull/2053) Make - `get_app` name 参数是可选的 -- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON编码器 - 通过应用程序更改 -- [#2063](https://github.com/sanic-org/sanic/pull/2063) App 和 - 连接级别环境对象 - -**错误修复** - -- 解析[#1420](https://github.com/sanic-org/sanic/pull/1420) - `url_for` ，其中`strict_slashes` 正在开启路径，结束于 `/` -- 解析[#1525](https://github.com/sanic-org/sanic/pull/1525) - 路由不正确，有一些特殊字符 -- 解析[#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI - 物体头 -- 解析[#1722](https://github.com/sanic-org/sanic/pull/1722) - 在区块模式中使用curl -- 解析[#1730](https://github.com/sanic-org/sanic/pull/1730) - ASGI 串流响应额外内容 -- 解析[#1749](https://github.com/sanic-org/sanic/pull/1749) - 还原破损的中间件边缘案件 + `get_app` name argument optional +- [#2055](https://github.com/sanic-org/sanic/pull/2055) JSON encoder + change via app +- [#2063](https://github.com/sanic-org/sanic/pull/2063) App and + connection level context objects + +**Bugfixes** + +- Resolve [#1420](https://github.com/sanic-org/sanic/pull/1420) + `url_for` where `strict_slashes` are on for a path ending in `/` +- Resolve [#1525](https://github.com/sanic-org/sanic/pull/1525) + Routing is incorrect with some special characters +- Resolve [#1653](https://github.com/sanic-org/sanic/pull/1653) ASGI + headers in body +- Resolve [#1722](https://github.com/sanic-org/sanic/pull/1722) + Using curl in chunk mode +- Resolve [#1730](https://github.com/sanic-org/sanic/pull/1730) + Extra content in ASGI streaming response +- Resolve [#1749](https://github.com/sanic-org/sanic/pull/1749) + Restore broken middleware edge cases - Resolve [#1785](https://github.com/sanic-org/sanic/pull/1785) [#1804](https://github.com/sanic-org/sanic/pull/1804) Synchronous error handlers -- 解析[#1790](https://github.com/sanic-org/sanic/pull/1790) - 协议错误不支持 async 错误处理程序 #1790 -- 解析[#1824](https://github.com/sanic-org/sanic/pull/1824) - 超时特定方法 +- Resolve [#1790](https://github.com/sanic-org/sanic/pull/1790) + Protocol errors did not support async error handlers #1790 +- Resolve [#1824](https://github.com/sanic-org/sanic/pull/1824) + Timeout on specific methods - Resolve [#1875](https://github.com/sanic-org/sanic/pull/1875) Response timeout error from all routes after returning several timeouts from a specific route -- 解析[#1988](https://github.com/sanic-org/sanic/pull/1988) - 用身体处理安全方法 -- [#2001](https://github.com/sanic-org/sanic/pull/2001) 提升 - 值错误，因为cookie max-age 不是整数 +- Resolve [#1988](https://github.com/sanic-org/sanic/pull/1988) + Handling of safe methods with body +- [#2001](https://github.com/sanic-org/sanic/pull/2001) Raise + ValueError when cookie max-age is not an integer -**废弃和删除** +**Deprecations and Removals** -- [#2007](https://github.com/sanic-org/sanic/pull/2007)\* 配置 - 使用 `from_envvar` \* 配置使用 `from_pyfile` \* 配置使用 +- [#2007](https://github.com/sanic-org/sanic/pull/2007) \* Config + using `from_envvar` \* Config using `from_pyfile` \* Config using `from_object` -- [#2009](https://github.com/sanic-org/sanic/pull/2009) 删除Sanic - 测试客户端到自己的包 +- [#2009](https://github.com/sanic-org/sanic/pull/2009) Remove Sanic + test client to its own package - [#2036](https://github.com/sanic-org/sanic/pull/2036), [#2037](https://github.com/sanic-org/sanic/pull/2037) Drop Python - 3.6 -- `Request.endpoint` 已不推荐使用 `Request.name` -- 处理器类型名称前缀已删除 (静态、websocket 等) + 3.6 support +- `Request.endpoint` deprecated in favor of `Request.name` +- handler type name prefixes removed (static, websocket, etc) -**开发者基础设施** +**Developer infrastructure** - [#1995](https://github.com/sanic-org/sanic/pull/1995) Create FUNDING.yml -- [#2013](https://github.com/sanic-org/sanic/pull/2013) 将codeql - 添加到CI 管道中 -- [#2038](https://github.com/sanic-org/pull/2038) Codecov - 配置更新 -- [#2049](https://github.com/sanic-org/sanic/pull/2049) 更新 - 设置，使用 `find_packes` +- [#2013](https://github.com/sanic-org/sanic/pull/2013) Add codeql + to CI pipeline +- [#2038](https://github.com/sanic-org/sanic/pull/2038) Codecov + configuration updates +- [#2049](https://github.com/sanic-org/sanic/pull/2049) Updated + setup.py to use `find_packages` -**改进文档** +**Improved Documentation** - [#1218](https://github.com/sanic-org/sanic/pull/1218) - 文件缺失。\* -- [#1608](https://github.com/sanic-org/sanic/pull/1608) 添加 - 卡车文档和 LTS + Documentation for sanic.log.\* is missing +- [#1608](https://github.com/sanic-org/sanic/pull/1608) Add + documentation on calver and LTS - [#1731](https://github.com/sanic-org/sanic/pull/1731) Support mounting application elsewhere than at root path -- [#2006](https://github.com/sanic-org/sanic/pull/2006) 升级 - 类型注释并改进文档字符串和 API 文档 -- [#2052](https://github.com/sanic-org/sanic/pull/2052) 修复一些 - 示例和文档 - -**杂项** - -- `Request.route` 属性 -- 更好的Websocket 子协议支持 -- 传递了 - 时用蓝图组中的中间件解决bug -- 将蓝图和Sanic之间的通用逻辑移动到混合物 -- 路由命名更改为更加一致 - - 请求端点是路由名称 - - 路由名称已完全空格 -- 一些新的便利装饰符： +- [#2006](https://github.com/sanic-org/sanic/pull/2006) Upgraded + type annotations and improved docstrings and API documentation +- [#2052](https://github.com/sanic-org/sanic/pull/2052) Fix some + examples and docs + +**Miscellaneous** + +- `Request.route` property +- Better websocket subprotocols support +- Resolve bug with middleware in Blueprint Group when passed + callable +- Moves common logic between Blueprint and Sanic into mixins +- Route naming changed to be more consistent + - request endpoint is the route name + - route names are fully namespaced +- Some new convenience decorators: - `@app.main_process_start` - `@app.main_process_stop` - `@app.befor_server_start` @@ -787,276 +788,282 @@ _当前LTS版本_ - `@app.after _server_stop` - `@app.on_request` - `@app.on_response` -- 修复不包含 `HEAD` 的 `Alle` 标题 -- 在 `url_for` 中使用 "name" 关键字用于"static"路由，在那里不存在 - 名称 -- 不使用命名参数，无法拥有多个`app.static()` -- 在文件路径上使用 "filename" 关键字在 `url_for` -- `取消引号`而不是自动' -- `routes_all` 是导线 -- 处理器参数只是 kwarg -- `request.match_info` 现在是缓存的(而不是计算的)属性 -- 未知的静态文件 mimetype 以 `application/octet-stream` 格式发送 -- `url_for`中的`_host`关键字 -- 如果没有指定 - ，为文本和 js 内容类型添加字符集默认值到 `utf-8` -- 路由的版本可以是字符串、浮点型变量或整数 -- 路由有 ctx 属性 -- 应用程序有`routes_static`, `routes_dynamic`, `routes_regex` -- [#2044](https://github.com/sanic-org/sanic/pull/2044) 代码清理 - 并重新排料中 -- [#2072](https://github.com/sanic-org/sanic/pull/2072) 删除 +- Fixes `Allow` header that did not include `HEAD` +- Using "name" keyword in `url_for` for a "static" route where + name does not exist +- Cannot have multiple `app.static()` without using the named param +- Using "filename" keyword in `url_for` on a file route +- `unquote` in route def (not automatic) +- `routes_all` is tuples +- Handler arguments are kwarg only +- `request.match_info` is now a cached (and not computed) property +- Unknown static file mimetype is sent as `application/octet-stream` +- `_host` keyword in `url_for` +- Add charset default to `utf-8` for text and js content types if + not specified +- Version for a route can be str, float, or int +- Route has ctx property +- App has `routes_static`, `routes_dynamic`, `routes_regex` +- [#2044](https://github.com/sanic-org/sanic/pull/2044) Code cleanup + and refactoring +- [#2072](https://github.com/sanic-org/sanic/pull/2072) Remove `BaseSanic` metaclass -- [#2074](https://github.com/sanic-org/sanic/pull/2074) 性能 - 调整 `handle_request_` +- [#2074](https://github.com/sanic-org/sanic/pull/2074) Performance + adjustments in `handle_request_` -## 第20.12.3 版 +## Version 20.12.3 -**错误修复** +**Bugfixes** -- [#2021](https://github.com/sanic-org/sanic/pull/2021) 从websocket 处理器名称中删除 - 前缀 +- [#2021](https://github.com/sanic-org/sanic/pull/2021) Remove + prefix from websocket handler name -## 第20.12.2版 +## Version 20.12.2 -**依赖** +**Dependencies** -- [#2026](https://github.com/sanic-org/sanic/pull/2026) 修复uvloop - 至 0.14 因为0.15 drops Python 3.6 支持 -- [#2029](https://github.com/sanic-org/sanic/pull/2029) 删除旧的 - 字符要求，在硬的多词要求中添加 +- [#2026](https://github.com/sanic-org/sanic/pull/2026) Fix uvloop + to 0.14 because 0.15 drops Python 3.6 support +- [#2029](https://github.com/sanic-org/sanic/pull/2029) Remove old + chardet requirement, add in hard multidict requirement -## 第19.12.5版 +## Version 19.12.5 -**依赖** +**Dependencies** - [#2025](https://github.com/sanic-org/sanic/pull/2025) Fix uvloop - 到 0.14 因为0.15 drops Python 3.6 支持 -- [#2027](https://github.com/sanic-org/sanic/pull/2027) 删除旧的 - chardet 要求，在硬的多词要求中添加 - -## 版本20.12.0 - -**特征** - -- [#1993](https://github.com/sanic-org/sanic/pull/1993) 添加禁用 - 应用注册 -- [#1945](https://github.com/sanic-org/sanic/pull/1945) 静态路由 - 更详细，如果找不到文件 -- [#1954](https://github.com/sanic-org/sanic/pull/1954) 修复静态 - 路由注册在蓝图上 -- [#1961](https://github.com/sanic-org/sanic/pull/1961) 添加 Python - 3.9 支持 + to 0.14 because 0.15 drops Python 3.6 support +- [#2027](https://github.com/sanic-org/sanic/pull/2027) Remove old + chardet requirement, add in hard multidict requirement + +## Version 20.12.0 + +**Features** + +- [#1993](https://github.com/sanic-org/sanic/pull/1993) Add disable + app registry +- [#1945](https://github.com/sanic-org/sanic/pull/1945) Static route + more verbose if file not found +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + routes registration on a blueprint +- [#1961](https://github.com/sanic-org/sanic/pull/1961) Add Python + 3.9 support - [#1962](https://github.com/sanic-org/sanic/pull/1962) Sanic CLI - 升级 + upgrade - [#1967](https://github.com/sanic-org/sanic/pull/1967) Update - aiofile 版本要求 + aiofile version requirements - [#1969](https://github.com/sanic-org/sanic/pull/1969) Update - multidict requirements -- [#1970](https://github.com/sanic-org/sanic/pull/1970) 添加py.typed - 文件 + multidict version requirements +- [#1970](https://github.com/sanic-org/sanic/pull/1970) Add py.typed + file - [#1972](https://github.com/sanic-org/sanic/pull/1972) Speed optimization in request handler -- [#1979](https://github.com/sanic-org/sanic/pull/1979) 添加应用 - 注册表和 Sanic 类级应用程序检索器 +- [#1979](https://github.com/sanic-org/sanic/pull/1979) Add app + registry and Sanic class level app retrieval -**错误修复** +**Bugfixes** -- [#1965](https://github.com/sanic-org/sanic/pull/1965) 修正Chunked - 传输-编码在 ASGI 串流响应中 +- [#1965](https://github.com/sanic-org/sanic/pull/1965) Fix Chunked + Transport-Encoding in ASGI streaming response -**废弃和删除** +**Deprecations and Removals** -- [#1981](https://github.com/sanic-org/sanic/pull/1981) 清理和 - 删除已废弃的代码 +- [#1981](https://github.com/sanic-org/sanic/pull/1981) Cleanup and + remove deprecated code -**开发者基础设施** +**Developer infrastructure** -- [#1956](https://github.com/sanic-org/sanic/pull/1956) 修正负载 - 模块测试 +- [#1956](https://github.com/sanic-org/sanic/pull/1956) Fix load + module test - [#1973](https://github.com/sanic-org/sanic/pull/1973) Transition - Travis从.org 到 .com + Travis from .org to .com - [#1986](https://github.com/sanic-org/sanic/pull/1986) Update tox - 要求 + requirements -**改进文档** +**Improved Documentation** - [#1951](https://github.com/sanic-org/sanic/pull/1951) - 文档改进 -- [#1983](https://github.com/sanic-org/sanic/pull/1983) 移除测试.rst 中的 - 重复内容 -- [#1984](https://github.com/sanic-org/sanic/pull/1984) 修复 - 路由.rst + Documentation improvements +- [#1983](https://github.com/sanic-org/sanic/pull/1983) Remove + duplicate contents in testing.rst +- [#1984](https://github.com/sanic-org/sanic/pull/1984) Fix typo in + routing.rst -## 20.9.1 版本 +## Version 20.9.1 -**错误修复** +**Bugfixes** -- [#1954](https://github.com/sanic-org/sanic/pull/1954) 修复静态 - 路由注册在蓝图上 -- [#1957](https://github.com/sanic-org/sanic/pull/1957) 删除ASGI流体中的 - 重复标题 +- [#1954](https://github.com/sanic-org/sanic/pull/1954) Fix static + route registration on blueprints +- [#1957](https://github.com/sanic-org/sanic/pull/1957) Removes + duplicate headers in ASGI streaming body -## 第19.12.3 版 +## Version 19.12.3 -**错误修复** +**Bugfixes** -- [#1959](https://github.com/sanic-org/sanic/pull/1959) 删除ASGI流体中的 - 重复的头部 +- [#1959](https://github.com/sanic-org/sanic/pull/1959) Removes + duplicate headers in ASGI streaming body -## 版本20.9.0 +## Version 20.9.0 -**特征** +**Features** -- [#1887](https://github.com/sanic-org/sanic/pull/1887) 在 websockets (均为sanic server and ASGI) 传递 - 子协议 +- [#1887](https://github.com/sanic-org/sanic/pull/1887) Pass + subprotocols in websockets (both sanic server and ASGI) - [#1894](https://github.com/sanic-org/sanic/pull/1894) - 在应用实例上自动设置 `test_mode` 标志 -- [#1903](https://github.com/sanic-org/sanic/pull/1903) 添加新的 - 统一方法来更新应用值 + Automatically set `test_mode` flag on app instance +- [#1903](https://github.com/sanic-org/sanic/pull/1903) Add new + unified method for updating app values - [#1906](https://github.com/sanic-org/sanic/pull/1906), [#1909](https://github.com/sanic-org/sanic/pull/1909) Adds - WEBSOCKET_PING_TIMEOUT和WEBSOCKET_PING_ING_INTERVAL configuration - 值 + WEBSOCKET_PING_TIMEOUT and WEBSOCKET_PING_INTERVAL configuration + values - [#1935](https://github.com/sanic-org/sanic/pull/1935) httpx - 版本依赖关系更新，它预定在 v20.12 中被移除为 - 依赖关系。 -- [#1937](https://github.com/sanic-org/sanic/pull/1937) 已添加自动、 - 文本和 json 回退错误处理程序(v21.3, 默认为 - 更改表格为 auto) + version dependency updated, it is slated for removal as a + dependency in v20.12 +- [#1937](https://github.com/sanic-org/sanic/pull/1937) Added auto, + text, and json fallback error handlers (in v21.3, the default will + change form html to auto) -**错误修复** +**Bugfixes** -- [#1897](https://github.com/sanic-org/sanic/pull/1897) 解析流中未读字节的 - 异常 +- [#1897](https://github.com/sanic-org/sanic/pull/1897) Resolves + exception from unread bytes in stream -**废弃和删除** +**Deprecations and Removals** - [#1903](https://github.com/sanic-org/sanic/pull/1903) - config.from_envar, config.from_pyfile, 和 config.from_object 是 - 废弃并设置为 v21.3 + config.from_envar, config.from_pyfile, and config.from_object are + deprecated and set to be removed in v21.3 -**开发者基础设施** +**Developer infrastructure** - [#1890](https://github.com/sanic-org/sanic/pull/1890), - [#1891](https://github.com/sanic-org/sanic/pull/1891) 更新isort - 调用以兼容新的 API -- [#1893](https://github.com/sanic-org/sanic/pull/1893) 从setup.cfg 中删除 - 版本 -- [#1924](https://github.com/sanic-org/sanic/pull/1924) 添加 + [#1891](https://github.com/sanic-org/sanic/pull/1891) Update isort + calls to be compatible with new API +- [#1893](https://github.com/sanic-org/sanic/pull/1893) Remove + version section from setup.cfg +- [#1924](https://github.com/sanic-org/sanic/pull/1924) Adding \--strict-markers for pytest -**改进文档** +**Improved Documentation** -- [#1922](https://github.com/sanic-org/sanic/pull/1922) 在README 中添加明确的 - ASGI 遵守情况 +- [#1922](https://github.com/sanic-org/sanic/pull/1922) Add explicit + ASGI compliance to the README -## 20.6.3 版本 +## Version 20.6.3 -**错误修复** +**Bugfixes** -- [#1884](https://github.com/sanic-org/sanic/pull/1884) 还原 - 更改为多处理模式 +- [#1884](https://github.com/sanic-org/sanic/pull/1884) Revert + change to multiprocessing mode -## 20.6.2 版本 +## Version 20.6.2 -**特征** +**Features** - [#1641](https://github.com/sanic-org/sanic/pull/1641) Socket - 绑定适合IPv6和UNIX套接字 - -## 20.6.1 版本 - -**特征** - -- [#1760](https://github.com/sanic-org/sanic/pull/1760) 在 websocket 路由中添加版本 - 参数 -- [#1866](https://github.com/sanic-org/sanic/pull/1866) 添加`sanic` - 作为入口点命令 -- [#1880](https://github.com/sanic-org/sanic/pull/1880) 为url_for用途的websockets添加处理函数名 - -**错误修复** - -- [#1776](https://github.com/sanic-org/sanic/pull/1776) - 主机参数问题的 Bug 修复 -- [#1842](https://github.com/sanic-org/sanic/pull/1842) 修复静态 - _处理程序拾取错误 -- [#1827](https://github.com/sanic-org/sanic/pull/1827) 在 OSX py38 和 Windows 上修复读取器 -- [#1848](https://github.com/sanic-org/sanic/pull/1848) 反转 - named_response_midlware 的执行顺序，以匹配正常的响应中间件执行顺序 + binding implemented properly for IPv6 and UNIX sockets + +## Version 20.6.1 + +**Features** + +- [#1760](https://github.com/sanic-org/sanic/pull/1760) Add version + parameter to websocket routes +- [#1866](https://github.com/sanic-org/sanic/pull/1866) Add `sanic` + as an entry point command +- [#1880](https://github.com/sanic-org/sanic/pull/1880) Add handler + names for websockets for url_for usage + +**Bugfixes** + +- [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for + host parameter issue with lists +- [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static + _handler pickling error +- [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader + on OSX py38 and Windows +- [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse + named_response_middlware execution order, to match normal response + middleware execution order - [#1853](https://github.com/sanic-org/sanic/pull/1853) Fix pickle error when attempting to pickle an application which contains websocket routes -**废弃和删除** +**Deprecations and Removals** -- [#1739](https://github.com/sanic-org/sanic/pull/1739) 废弃 - body_bytes并入体 +- [#1739](https://github.com/sanic-org/sanic/pull/1739) Deprecate + body_bytes to merge into body -**开发者基础设施** +**Developer infrastructure** -- [#1852](https://github.com/sanic-org/sanic/pull/1852) 修复CI test env Python nightlies 上的 +- [#1852](https://github.com/sanic-org/sanic/pull/1852) Fix naming + of CI test env on Python nightlies - [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust - websockets 版本以设置py -- [#1869](https://github.com/sanic-org/sanic/pull/1869) 包装 - run()'s "protocol" 类型注释在选项[] + websockets version to setup.py +- [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap + run()'s "protocol" type annotation in Optional[] -**改进文档** +**Improved Documentation** -- [#1846](https://github.com/sanic-org/sanic/pull/1846) 更新文档 - 以澄清响应中间件执行顺序 -- [#1865](https://github.com/sanic-org/sanic/pull/1865) 修复正在隐藏文档的 rst - 格式问题 +- [#1846](https://github.com/sanic-org/sanic/pull/1846) Update docs + to clarify response middleware execution order +- [#1865](https://github.com/sanic-org/sanic/pull/1865) Fixing rst + format issue that was hiding documentation -## 版本20.6.0 +## Version 20.6.0 -_释放但无意省略的 PR #1880，所以被 -20.6.1_ 取代。 +_Released, but unintentionally omitting PR #1880, so was replaced by +20.6.1_ -## 版本20.3.0 +## Version 20.3.0 -**特征** +**Features** - [#1762](https://github.com/sanic-org/sanic/pull/1762) Add `srv.start_serving()` and `srv.serve_forever()` to `AsyncioServer` - [#1767](https://github.com/sanic-org/sanic/pull/1767) Make Sanic - 可在 `hypercorn -k trio myweb.app` 上使用 -- [#1768](https://github.com/sanic-org/sanic/pull/1768) 没有 - 对正常错误和预审错误页面的跟踪 -- [#1769](https://github.com/sanic-org/sanic/pull/1769) 代码清理文件回复中的 -- [#1793](https://github.com/sanic-org/sanic/pull/1793)和 - [#1819](https://github.com/sanic-org/sanic/pull/1819) 将 - `str.form()` 升级为f-字符串。 -- [#1798](https://github.com/sanic-org/sanic/pull/1798) 允许 - MacOS 上与Python 3.8的多个工作者。 -- [#1820](https://github.com/sanic-org/sanic/pull/1820) 不在异常中设置 - 内容类型和内容长度标题 - -**错误修复** - -- [#1748](https://github.com/sanic-org/sanic/pull/1748) 移除在 Python 3.8 的`asyncio.Event` 中的 - 循环 + usable on `hypercorn -k trio myweb.app` +- [#1768](https://github.com/sanic-org/sanic/pull/1768) No + tracebacks on normal errors and prettier error pages +- [#1769](https://github.com/sanic-org/sanic/pull/1769) Code cleanup + in file responses +- [#1793](https://github.com/sanic-org/sanic/pull/1793) and + [#1819](https://github.com/sanic-org/sanic/pull/1819) Upgrade + `str.format()` to f-strings +- [#1798](https://github.com/sanic-org/sanic/pull/1798) Allow + multiple workers on MacOS with Python 3.8 +- [#1820](https://github.com/sanic-org/sanic/pull/1820) Do not set + content-type and content-length headers in exceptions + +**Bugfixes** + +- [#1748](https://github.com/sanic-org/sanic/pull/1748) Remove loop + argument in `asyncio.Event` in Python 3.8 - [#1764](https://github.com/sanic-org/sanic/pull/1764) Allow route decorators to stack up again -- [#1789](https://github.com/sanic-org/sanic/pull/1789) 使用产生错误的\`url_for'的主机修复 -- [#1808](https://github.com/sanic-org/sanic/pull/1808) 修正Ctrl+C - 和Windows 测试 +- [#1789](https://github.com/sanic-org/sanic/pull/1789) Fix tests + using hosts yielding incorrect `url_for` +- [#1808](https://github.com/sanic-org/sanic/pull/1808) Fix Ctrl+C + and tests on Windows -**废弃和删除** +**Deprecations and Removals** -- [#1800](https://github.com/sanic-org/sanic/pull/1800) 以一流的方式开始 - 弃置，移除 - `body_init`, `body_pub`和`body_finish` +- [#1800](https://github.com/sanic-org/sanic/pull/1800) Begin + deprecation in way of first-class streaming, removal of + `body_init`, `body_push`, and `body_finish` - [#1801](https://github.com/sanic-org/sanic/pull/1801) Complete deprecation from [#1666](https://github.com/sanic-org/sanic/pull/1666) of dictionary context on `request` objects. -- [#1807](https://github.com/sanic-org/sanic/pull/1807) 删除可直接从应用程序读取的 - 服务器配置 args +- [#1807](https://github.com/sanic-org/sanic/pull/1807) Remove + server config args that can be read directly from app - [#1818](https://github.com/sanic-org/sanic/pull/1818) Complete deprecation of `app.remove_route` and `request.raw_args` -**依赖** +**Dependencies** - [#1794](https://github.com/sanic-org/sanic/pull/1794) Bump `httpx` to 0.11.1 @@ -1064,50 +1071,49 @@ _释放但无意省略的 PR #1880，所以被 `ASGIDispatch` from top-level `httpx` (from third-party deprecation) -**开发者基础设施** +**Developer infrastructure** -- [#1833](https://github.com/sanic-org/sanic/pull/1833) 解决了 - 损坏的文档版本 +- [#1833](https://github.com/sanic-org/sanic/pull/1833) Resolve + broken documentation builds -**改进文档** +**Improved Documentation** -- [#1755](https://github.com/sanic-org/sanic/pull/1755) +- [#1755](https://github.com/sanic-org/sanic/pull/1755) Usage of `response.empty()` - [#1778](https://github.com/sanic-org/sanic/pull/1778) Update README -- [#1783](https://github.com/sanic-org/sanic/pull/1783) 修复类型 -- [#1784](https://github.com/sanic-org/sanic/pull/1784) 更正了 - 更改了 MD 移动到 RST +- [#1783](https://github.com/sanic-org/sanic/pull/1783) Fix typo +- [#1784](https://github.com/sanic-org/sanic/pull/1784) Corrected + changelog for docs move of MD to RST ([#1691](https://github.com/sanic-org/sanic/pull/1691)) -- [#1803](https://github.com/sanic-org/sanic/pull/1803) 更新 - 配置文件以匹配DEFAULT_CONFIG -- [#1814](https://github.com/sanic-org/sanic/pull/1814) 更新 +- [#1803](https://github.com/sanic-org/sanic/pull/1803) Update + config docs to match DEFAULT_CONFIG +- [#1814](https://github.com/sanic-org/sanic/pull/1814) Update + getting_started.rst +- [#1814](https://github.com/sanic-org/sanic/pull/1814) Update getting_started.rst -- [#1821](https://github.com/sanic-org/sanic/pull/1821) 更新到 - 部署 -- [#1822](https://github.com/sanic-org/sanic/pull/1822) 更新文档 - 并修改于 20.3 -- [#1834](https://github.com/sanic-org/sanic/pull/1834) - 侦听器顺序 +- [#1821](https://github.com/sanic-org/sanic/pull/1821) Update to + deployment +- [#1834](https://github.com/sanic-org/sanic/pull/1834) Order of + listeners -## 版本19.12.0 +## Version 19.12.0 -**错误修复** +Version 19.12.0 -- 修复蓝图中间件应用 +- Fix blueprint middleware application - 目前，任何蓝图中间件都已注册，而不论 - 是用哪个蓝图来注册的。 正在应用于所有由 `@app` 和 `@bluprint` 创建的 - 路由。 + Currently, any blueprint middleware registered, irrespective of + which blueprint was used to do so, was being applied to all of the + routes created by the `@app` and `@blueprint` alike. - 作为此更改的一部分，基于蓝图的中间件应用程序 - 是根据它们的注册地点强制执行的。 + As part of this change, the blueprint based middleware application + is enforced based on where they are registered. - If you register a middleware via `@blueprint.middleware` then it will apply only to the routes defined by the blueprint. - - 如果您通过 `@bluprint_group.middleware` - 注册了一个中间软件，它将适用于所有基于蓝图的路由，这些路由属于群组的 - 部分。 + - If you register a middleware via `@blueprint.middleware` then it + will apply only to the routes defined by the blueprint. - If you define a middleware via `@app.middleware` then it will be applied on all available routes ([#37](https://github.com/sanic-org/sanic/issues/37)) @@ -1120,15 +1126,15 @@ _释放但无意省略的 PR #1880，所以被 [AttributeError]{.title-ref}. This fix makes the availability of [SERVER_NAME]{.title-ref} on our [app.config]{.title-ref} an optional behavior. - ([No. 1707](https://github.com/sanic-org/sanic/issues/1707)) + ([#1707](https://github.com/sanic-org/sanic/issues/1707)) -**改进文档** +**Improved Documentation** -- 将文档从MD移动到RST +- Move docs from MD to RST - 将所有文档从Markdown移动到调整后的文本，如 - 的其他文档，统一方案并使它在未来更容易地更新到 - 更新文档。 + Moved all docs from markdown to restructured text like the rest of + the docs to unify the scheme and make it easier in the future to + update documentation. ([#1691](https://github.com/sanic-org/sanic/issues/1691)) - Fix documentation for [get]{.title-ref} and [getlist]{.title-ref} of @@ -1139,386 +1145,386 @@ _释放但无意省略的 PR #1880，所以被 [request.args]{.title-ref} behavior ([#1704](https://github.com/sanic-org/sanic/issues/1704)) -## 版本19.6.3 +## Version 19.6.3 -**特征** +**Features** -- 启用 Towncrier 支持 +- Enable Towncrier Support As part of this feature, [towncrier]{.title-ref} is being introduced as a mechanism to partially automate the process of generating and managing change logs as part of each of pull requests. - ([No. 1631](https://github.com/sanic-org/sanic/issues/1631)) + ([#1631](https://github.com/sanic-org/sanic/issues/1631)) -**改进文档** +**Improved Documentation** -- 文件基础设施变化 +- Documentation infrastructure changes - Enable having a single common [CHANGELOG]{.title-ref} file for both GitHub page and documentation - - 修复 Sphinix 废弃警告 + - Fix Sphinix deprecation warnings - Fix documentation warnings due to invalid [rst]{.title-ref} indentation - Enable common contribution guidelines file across GitHub and documentation via [CONTRIBUTING.rst]{.title-ref} ([#1631](https://github.com/sanic-org/sanic/issues/1631)) -## 版本19.6.2 +## Version 19.6.2 -**特征** +**Features** -- [#1562](https://github.com/sanic-org/sanic/pull/1562) 去除 - `aiohttp` 依赖关系，并根据 - [requests-async](https://github.com/encode/requests-async) 创建新的`SanicTestClient` -- [#1475](https://github.com/sanic-org/sanic/pull/1475) 添加了ASGI - 支持(Beta) +- [#1562](https://github.com/sanic-org/sanic/pull/1562) Remove + `aiohttp` dependency and create new `SanicTestClient` based upon + [requests-async](https://github.com/encode/requests-async) +- [#1475](https://github.com/sanic-org/sanic/pull/1475) Added ASGI + support (Beta) - [#1436](https://github.com/sanic-org/sanic/pull/1436) Add Configure support from object string -**错误修复** +**Bugfixes** -- [#1587](https://github.com/sanic-org/sanic/pull/1587) 添加缺失的 - 句柄给预期头部。 +- [#1587](https://github.com/sanic-org/sanic/pull/1587) Add missing + handle for Expect header. - [#1560](https://github.com/sanic-org/sanic/pull/1560) Allow to disable Transfer-Encoding: chunked. -- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix 宽松的 - 关机。 +- [#1558](https://github.com/sanic-org/sanic/pull/1558) Fix graceful + shutdown. - [#1594](https://github.com/sanic-org/sanic/pull/1594) Strict - 斜线行为修复 + Slashes behavior fix -**废弃和删除** +**Deprecations and Removals** - [#1544](https://github.com/sanic-org/sanic/pull/1544) Drop - 依附于打分上 + dependency on distutil - [#1562](https://github.com/sanic-org/sanic/pull/1562) Drop support for Python 3.5 -- [#1568](https://github.com/sanic-org/sanic/pull/1568) 废弃 - 路由移动。 +- [#1568](https://github.com/sanic-org/sanic/pull/1568) Deprecate + route removal. -.. 警告：：警告 +.. warning:: Warning ``` -Sanic 将不支持 Python 3.5 版本的 19.6 和前进。 -然而，版本 18。 2LTS 将有其支持期延长期延时 -2020年12月，因此通过 Python\'s 官方支持版本 -3。 ，定于2020年9月到期。 +Sanic will not support Python 3.5 from version 19.6 and forward. +However, version 18.12LTS will have its support period extended thru +December 2020, and therefore passing Python\'s official support version +3.5, which is set to expire in September 2020. ``` -## 版本19.3 +## Version 19.3 -**特征** +**Features** - [#1497](https://github.com/sanic-org/sanic/pull/1497) Add support for zero-length and RFC 5987 encoded filename for multipart/form-data requests. -- [#1484](https://github.com/sanic-org/sanic/pull/1484) `sanic.cookies.cookie`的 - `expires`属性的类型现在被强制执行到 - 的类型是`datetime`。 +- [#1484](https://github.com/sanic-org/sanic/pull/1484) The type of + `expires` attribute of `sanic.cookies.Cookie` is now enforced to + be of type `datetime`. -- [#1482](https://github.com/sanic-org/sanic/pull/1482) 添加支持 - 的`sanic.Sanic.add_route()` 的 - 至`sanic.Blueprint.add_route()` 。 +- [#1482](https://github.com/sanic-org/sanic/pull/1482) Add support + for the `stream` parameter of `sanic.Sanic.add_route()` available + to `sanic.Blueprint.add_route()`. -- [#1481](https://github.com/sanic-org/sanic/pull/1481) 接受路径参数的 - 负值，类型为 `int` 或 `num` 。 +- [#1481](https://github.com/sanic-org/sanic/pull/1481) Accept + negative values for route parameters with type `int` or `number`. -- [#1476](https://github.com/sanic-org/sanic/pull/1476) 废弃了 - 的使用 `sanic.request.Request.raw_args` - 它有一个基本的 - 缺陷，它会丢弃重复查询字符串参数。 添加 - `sanic.request.Requery_args` 作为原始的 - use-case。 +- [#1476](https://github.com/sanic-org/sanic/pull/1476) Deprecated + the use of `sanic.request.Request.raw_args` - it has a fundamental + flaw in which is drops repeated query string parameters. Added + `sanic.request.Request.query_args` as a replacement for the + original use-case. -- [#1472](https://github.com/sanic-org/sanic/pull/1472) 移除请求类`repr`实现中的 - 意外的`None` 检查。 此 - 将请求的默认`repr` 从 ``改为 - \\` +- [#1472](https://github.com/sanic-org/sanic/pull/1472) Remove an + unwanted `None` check in Request class `repr` implementation. This + changes the default `repr` of a Request from `` to + `` -- [#1470](https://github.com/sanic-org/sanic/pull/1470) 添加2个新的 - 参数到 `sanic.app.Sanic.create_server` +- [#1470](https://github.com/sanic-org/sanic/pull/1470) Added 2 new + parameters to `sanic.app.Sanic.create_server`: - - `return_asyncio_server` - 是否返回 - asyncio.Server。 + - `return_asyncio_server` - whether to return an + asyncio.Server. - `asyncio_server_kwargs` - kwargs to pass to `loop.create_server` for the event loop that sanic is using. > - 这是一个突破性的变化。 + This is a breaking change. -- [#1499](https://github.com/sanic-org/sanic/pull/1499) 添加了测试和基准路由分辨率为 - 的测试案例。 +- [#1499](https://github.com/sanic-org/sanic/pull/1499) Added a set + of test cases that test and benchmark route resolution. -- [#1457](https://github.com/sanic-org/sanic/pull/1457) - 的类型在 `sanic.cookies.cookie` 中的 `max-age` 值现在是强制执行 - 为整数。 非整数值替换为 \`0'。 +- [#1457](https://github.com/sanic-org/sanic/pull/1457) The type of + the `"max-age"` value in a `sanic.cookies.Cookie` is now enforced + to be an integer. Non-integer values are replaced with `0`. -- [#1445](https://github.com/sanic-org/sanic/pull/1445) 将 - `endpoint` 属性添加到传入的 `request` 中，包含处理器函数的 - 名称。 +- [#1445](https://github.com/sanic-org/sanic/pull/1445) Added the + `endpoint` attribute to an incoming `request`, containing the name + of the handler function. -- [#1423](https://github.com/sanic-org/sanic/pull/1423) 改进了 - 请求流。 `request.stream` 现在是一个已退回的大小 - 而不是一个无限制的队列。 现在呼叫者必须调用 - `request.stream.read()` 而不是一个 - `required request.stream.get()` 以阅读身体的每一部分。 +- [#1423](https://github.com/sanic-org/sanic/pull/1423) Improved + request streaming. `request.stream` is now a bounded-size buffer + instead of an unbounded queue. Callers must now call + `await request.stream.read()` instead of + `await request.stream.get()` to read each portion of the body. - 这是一个突破性的变化。 + This is a breaking change. -**错误修复** +This is a breaking change. - [#1502](https://github.com/sanic-org/sanic/pull/1502) Sanic was prefetching `time.time()` and updating it once per second to avoid - excessive `time.time()` calls. 观察到 - 在一些情况下造成内存泄漏。 预获取 - 的好处似乎微不足道，因此这个好处已被删除。 修复 + excessive `time.time()` calls. The implementation was observed to + cause memory leaks in some cases. The benefit of the prefetch + appeared to negligible, so this has been removed. Fixes [#1500](https://github.com/sanic-org/sanic/pull/1500) -- [#1501](https://github.com/sanic-org/sanic/pull/1501)修复了 - 自动读取加载器中的一个错误，当过程作为模块启动时， - "python -m init0.mod1", 在这种情况下, sanic server 开始于 - `init0/mod1.py` , 启用了 `debug` , 并在 - `init0` 中导入另一个模块. -- [#1376](https://github.com/sanic-org/sanic/pull/1376) 允许sanic - 测试客户端在构建一个 `port=None` - 时绑定到随机端口 -- [#1399](https://github)。 om/sanic-org/sanic/pull/1399)增加了 - 在蓝图组中指定中间件的能力。 所以从组中的蓝图中生成的所有 - 路径都应用了 - 中间件. -- [#1442](https://github.com/sanic-org/sanic/pull/1442) 允许 - 使用 `SANIC_ACCESS_LOG` 环境变量到 - 启用/禁用访问日志时未明确传递到 - `app.run()` 。 这将允许在使用枪炮运行时禁用访问日志，例如 - 。 - -**开发者基础设施** - -- [#1529](https://github.com/sanic-org/sanic/pull/1529) 更新 - 项目 PyPI 凭据 -- [#1515](https://github.com/sanic-org/sanic/pull/1515) fixed linter - issue causing travis building succession(fix #1514) -- [#1490](https://github.com/sanic-org/sanic/pull/1490) 修复python - 版本在编译中 -- [#1478](https://github.com/sanic-org/sanic/pull/1478) 升级 - 设置工具版本并在构建过程中使用本机文档 -- [#1464](https://github.com/sanic-org/sanic/pull/14644) 升级 - pytest 并修复capg 单元测试 - -**改进文档** +- [#1501](https://github.com/sanic-org/sanic/pull/1501) Fix a bug in + the auto-reloader when the process was launched as a module i.e. + `python -m init0.mod1` where the sanic server is started in + `init0/mod1.py` with `debug` enabled and imports another module in + `init0`. +- [#1376](https://github.com/sanic-org/sanic/pull/1376) Allow sanic + test client to bind to a random port by specifying `port=None` + when constructing a `SanicTestClient` +- [#1399](https://github.com/sanic-org/sanic/pull/1399) Added the + ability to specify middleware on a blueprint group, so that all + routes produced from the blueprints in the group have the + middleware applied. +- [#1442](https://github.com/sanic-org/sanic/pull/1442) Allow the + the use the `SANIC_ACCESS_LOG` environment variable to + enable/disable the access log when not explicitly passed to + `app.run()`. This allows the access log to be disabled for example + when running via gunicorn. + +**Developer infrastructure** + +- [#1529](https://github.com/sanic-org/sanic/pull/1529) Update + project PyPI credentials +- [#1515](https://github.com/sanic-org/sanic/pull/1515) fix linter + issue causing travis build failures (fix #1514) +- [#1490](https://github.com/sanic-org/sanic/pull/1490) Fix python + version in doc build +- [#1478](https://github.com/sanic-org/sanic/pull/1478) Upgrade + setuptools version and use native docutils in doc build +- [#1464](https://github.com/sanic-org/sanic/pull/1464) Upgrade + pytest, and fix caplog unit tests + +**Improved Documentation** - [#1516](https://github.com/sanic-org/sanic/pull/1516) Fix typo at - 是例外文档 -- [#1510](https://github.com/sanic-org/sanic/pull/1510) fixe typo in + the exception documentation +- [#1510](https://github.com/sanic-org/sanic/pull/1510) fix typo in Asyncio example - [#1486](https://github.com/sanic-org/sanic/pull/1486) - 文档类型 -- [#1477](https://github.com/sanic-org/sanic/pull/1477) 修理文法 + Documentation typo +- [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar in README.md -- [#1489](https://github.com/sanic-org/sanic/pull/1489) 添加 - "databases" 到扩展列表 -- [#1483](https://github.com/sanic-org/sanic/pull/1483) 在扩展列表中添加 - sanic-zipkin -- [#1487](https://github.com/sanic-org/sanic/pull/1487) 删除了链接 - 从扩展列表中删除 Sanic-OAuth, +- [#1489](https://github.com/sanic-org/sanic/pull/1489) Added + "databases" to the extensions list +- [#1483](https://github.com/sanic-org/sanic/pull/1483) Add + sanic-zipkin to extensions list +- [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link + to deleted repo, Sanic-OAuth, from the extensions list - [#1460](https://github.com/sanic-org/sanic/pull/1460) 18.12 changelog - [#1449](https://github.com/sanic-org/sanic/pull/1449) Add example of amending request object -- [#1446](https://github.com/sanic-org/sanic/pull/1446) 更新 +- [#1446](https://github.com/sanic-org/sanic/pull/1446) Update README -- [#1444](https://github.com/sanic-org/sanic/pull/14444) 更新 +- [#1444](https://github.com/sanic-org/sanic/pull/1444) Update README -- [#1443](https://github.com/sanic-org/sanic/pull/1443) 更新 - README，包括新的徽标 -- [#1440](https://github.com/sanic-org/sanic/pull/1440) 修复小的 - 类型和 pip安装指令不匹配 +- [#1443](https://github.com/sanic-org/sanic/pull/1443) Update + README, including new logo +- [#1440](https://github.com/sanic-org/sanic/pull/1440) fix minor + type and pip install instruction mismatch - [#1424](https://github.com/sanic-org/sanic/pull/1424) - 文档改进 + Documentation Enhancements -注： 19.3.0 被跳过用于封装目的，没有在 -PyPI 上发布 +Note: 19.3.0 was skipped for packagement purposes and not released on +PyPI -## 18.12 版本 +## Version 18.12 ### 18.12.0 -- 变更： +- Changes: - - 代码片测试覆盖率从81%提高到91%。 - - 在static_file - 文档中添加串流大量文件和主机示例 - - 添加方法以在请求 + - Improved codebase test coverage from 81% to 91%. + - Added stream_large_files and host examples in static_file + document + - Added methods to append and finish body content on Request (#1379) - - Windows ci 支持与 .appveyor.yml 集成 - - 为 AF_INET6 和 AF_UNIX 套接字使用添加文档 - - 采用黑色/isort来换代币 - - 连接丢失时取消任务 - - 简化请求 ip 和端口检索逻辑。 - - 处理负载配置文件中的配置错误。 - - CI 与 codecov 集成 - - 为配置部分添加未接文档。 - - 已弃用 Handler.log - - 固定的 httptools 要求到版本 0.0.10 + - -- 修复： - - - 修复 `remove_entity_headers` 函数(#1415) - - 修复蓝图 - 蓝图使用默认的 url_prefix时，使用 os.path。 避免无效的 - url_prefix 像api//v1 f8a6af1 那样将`http` 模块重命名为 - `helpers` 以防止与内置的 Python HTp - 库 (fixes #1323) 发生冲突 - - 修复窗口上的无功者 - - 修复清理记录器命名空间 - - 修复装饰器示例中缺少的引用 - - 使用引用参数修复重定向 - - 修复最新蓝图代码 - - 修复与 Markdown 列表相关的 latex 文档构建。 - - 修复app.py 中的循环异常处理 - - 修复窗口和其他平台中的内容长度不匹配 - - 修复静态文件的范围头处理 (#1402) - - 修复记录器并使其工作 (#1397) - - 修复多处理测试中的 pikcle->选取的类型 - - 修复选取蓝图更改蓝图在蓝图中的 - "name" 部分中传递的字符串，以便匹配蓝图模块属性名称的 - 名称。 这使得 - 蓝图能够在没有错误的情况下被选取和卸载， - 是在 - Windows中以多处理模式运行Sanic的要求。 Added a test for pickling and unpickling blueprints + - Integrated with .appveyor.yml for windows ci support + - Added documentation for AF_INET6 and AF_UNIX socket usage + - Adopt black/isort for codestyle + - Cancel task when connection_lost + - Simplify request ip and port retrieval logic + - Handle config error in load config file. + - Integrate with codecov for CI + - Add missed documentation for config section. + - Deprecate Handler.log + - Pinned httptools requirement to version 0.0.10+ + +- Fixes: + + - Fix `remove_entity_headers` helper function (#1415) + - Fix TypeError when use Blueprint.group() to group blueprint + with default url_prefix, Use os.path.normpath to avoid invalid + url_prefix like api//v1 f8a6af1 Rename the `http` module to + `helpers` to prevent conflicts with the built-in Python http + library (fixes #1323) + - Fix unittests on windows + - Fix Namespacing of sanic logger + - Fix missing quotes in decorator example + - Fix redirect with quoted param + - Fix doc for latest blueprint code + - Fix build of latex documentation relating to markdown lists + - Fix loop exception handling in app.py + - Fix content length mismatch in windows and other platform + - Fix Range header handling for static files (#1402) + - Fix the logger and make it work (#1397) + - Fix type pikcle->pickle in multiprocessing test + - Fix pickling blueprints Change the string passed in the + "name" section of the namedtuples in Blueprint to match the + name of the Blueprint module attribute name. This allows + blueprints to be pickled and unpickled, without errors, which + is a requirement of running Sanic in multiprocessing mode in + Windows. Added a test for pickling and unpickling blueprints Added a test for pickling and unpickling sanic itself Added a test for enabling multiprocessing on an app with a blueprint (only useful to catch this bug if the tests are run on Windows). - - 修复日志文档 + - Fix document for logging -## 版本 0.8 +## Version 0.8 **0.8.3** -- 变更： - - 所有权更改为 org 'sanic-org' +- Changes: + - Ownership changed to org 'sanic-org' **0.8.0** -- 变更： - - 添加服务器发送事件扩展 (Innokty Lebedev) - - 优化处理 request_handler_task 取消 (Ashley +- Changes: + - Add Server-Sent Events extension (Innokenty Lebedev) + - Graceful handling of request_handler_task cancellation (Ashley Sommer) - - 在重定向前Sanize URL (aveao) - - 添加url_bytes到请求 (johndoe46) - - py37 支持travisci(yunstanford) - - 自动装入器支持 OSX (garyo) - - 添加 UUID 路由支持 (Volodymyr Maksymiv) - - 添加可用响应流 (Ashley Sommer) - - 添加弱项到请求时段(vopankov) - - 由于废弃 - (yunstanford) 从测试灯具中移除 ubuntu 12.04 - - 允许在add_route (kinware) 中流媒体处理程序 - - 使用 travis_retry for tox (Raphael Deem) - - 更新测试客户端的 aiothttp 版本 (yunstanford) - - 添加重定向导导入以提高清晰度(yingshaoxo) - - 更新 HTTP 实体标题 (Arnulfo Solis) - - 添加注册监听方法 (Stephan Fitzpatrick) - - 删除 Windows 的 uvloop/ujson 依赖项 (abuckenheimer) - - 204/304答复的内容长度标题(Arnulfo Soli) - - 扩展 WebSocketProtocol 参数并添加文档 (Bob Olde + - Sanitize URL before redirection (aveao) + - Add url_bytes to request (johndoe46) + - py37 support for travisci (yunstanford) + - Auto reloader support for OSX (garyo) + - Add UUID route support (Volodymyr Maksymiv) + - Add pausable response streams (Ashley Sommer) + - Add weakref to request slots (vopankov) + - remove ubuntu 12.04 from test fixture due to deprecation + (yunstanford) + - Allow streaming handlers in add_route (kinware) + - use travis_retry for tox (Raphael Deem) + - update aiohttp version for test client (yunstanford) + - add redirect import for clarity (yingshaoxo) + - Update HTTP Entity headers (Arnulfo Solís) + - Add register_listener method (Stephan Fitzpatrick) + - Remove uvloop/ujson dependencies for Windows (abuckenheimer) + - Content-length header on 204/304 responses (Arnulfo Solís) + - Extend WebSocketProtocol arguments and add docs (Bob Olde Hampsink, yunstanford) - - 更新开发状态从 alpha 到beta (Maksim + - Update development status from pre-alpha to beta (Maksim Anisenkov) - - KeepAlive 超时日志级别更改为调试(Arnulfo Soli) - - 因为pest-dev/pytest#3170 (Maksim + - KeepAlive Timeout log level changed to debug (Arnulfo Solís) + - Pin pytest to 3.3.2 because of pytest-dev/pytest#3170 (Maksim Aniskenov) - - 安装 Python 3.5 和 3.6 到码头容器进行测试 (Shahin + - Install Python 3.5 and 3.6 on docker container for tests (Shahin Azad) - - 添加支持蓝图组和嵌套(Elias Tarhini) - - 移除窗口设置的 uvloop(Aleksandr Kurlov) + - Add support for blueprint groups and nesting (Elias Tarhini) + - Remove uvloop for windows setup (Aleksandr Kurlov) - Auto Reload (Yaser Amari) - - 文档更新/修复(多个贡献者) -- 修复： - - 修复：Linux自动重新加载(Ashley Sommer) - - 修复：aiothttp >= 3.3.0 (Ashley Sommer) - - 修复：在窗口上默认禁用自动重新加载 (abuckenheimer) - - 修复 (1143)：用枪炮关闭访问日志 (hqy) - - 修复 (1268)：文件响应的支持状态代码 (Cosmo Borsky) - - 修复 (1266)：将 content_type 标志添加到 Sanic.statil (Cosmo Borsky) - - 修复：从add_websocket_route - 中缺少子协议参数(ciscorn) - - 修复 (1242)：CI 头的响应 (yunstanford) - - 修复 (1237): 添加 websockets 的版本约束 (yunstanford) - - 修复 (1231): 内存泄漏- 总是释放资源 (Phillip Xu) - - 修复 (1221)：如果存在传输，请提出truthy (Raphael + - Documentation updates/fixups (multiple contributors) +- Fixes: + - Fix: auto_reload in Linux (Ashley Sommer) + - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) + - Fix: disable auto_reload by default on windows (abuckenheimer) + - Fix (1143): Turn off access log with gunicorn (hqy) + - Fix (1143): Turn off access log with gunicorn (hqy) + - Fix (1266): Add content_type flag to Sanic.static (Cosmo Borsky) + - Fix: subprotocols parameter missing from add_websocket_route + (ciscorn) + - Fix (1242): Responses for CI header (yunstanford) + - Fix (1237): add version constraint for websockets (yunstanford) + - Fix (1231): memory leak - always release resource (Phillip Xu) + - Fix (1221): make request truthy if transport exists (Raphael Deem) - - 修复aiohttp>=3.1.0 (Ashley Sommer) - - 修复所有示例(PyManiacGR, kot83) - - 修复 (1158)：默认在调试模式下自动重新加载 (Raphael Deem) - - 修复 (1136): ErrorHandler.response 处理器调用限制性过强的 + - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) + - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) + - Fix (1158): default to auto_reload in debug mode (Raphael Deem) + - Fix (1136): ErrorHandler.response handler call too restrictive (Julien Castiaux) - - 修复：原始需要类似字节的对象 (云) - - 修复 (1120): 将列表传递到路由装饰器's host arg - (Timothy Ebiuwe) - - 修复：多部分/形式数据解析器中的错误(DirkGuijt) - - 修复：值为 null - 时缺少参数的异常(NyanKiyoshi) - - 修复：参数检查 (Howie Hu) - - 修复 (1089): 带有命名参数和不同的 - 方法的路由问题 (yunstanford) - - 修复(1085)：以多工模式处理信号(yunstanford) - - 修复：readme.rst中的单引号(成本) - - 修复：方法类型 (Dmitry Dygalo) - - 修复：Log_response 正确的IP和端口输出(Wibowo + - Fix: raw requires bytes-like object (cloudship) + - Fix (1120): passing a list in to a route decorator's host arg + (Timothy Ebiuwhe) + - Fix: Bug in multipart/form-data parser (DirkGuijt) + - Fix: Exception for missing parameter when value is null + (NyanKiyoshi) + - Fix: Parameter check (Howie Hu) + - Fix (1089): Routing issue with named parameters and different + methods (yunstanford) + - Fix (1085): Signal handling in multi-worker mode (yunstanford) + - Fix: single quote in readme.rst (Cosven) + - Fix: method typos (Dmitry Dygalo) + - Fix: log_response correct output for ip and port (Wibowo Arindrarto) - - 修复(1042)：异常处理(Raphael Deem) - - 修正：中文 URI (Howie Hu) - - 修复 (1079)：当自己的传送无时超时 (Raphael + - Fix (1042): Exception Handling (Raphael Deem) + - Fix: Chinese URIs (Howie Hu) + - Fix (1079): timeout bug when self.transport is None (Raphael Deem) - - 修复 (1074)：在路由有斜线时修复 strit_slash(Raphael + - Fix (1074): fix strict_slashes when route has slash (Raphael Deem) - - 修复 (1050): 将 samesite cookie 添加到 cookie keys (Raphael Deem) - - 修复 (1065)：允许在服务器启动后添加任务 (Raphael Deem) - - 修复 (1061)：在未经授权的异常中双引号 (Raphael + - Fix (1050): add samesite cookie to cookie keys (Raphael Deem) + - Fix (1065): allow add_task after server starts (Raphael Deem) + - Fix (1061): double quotes in unauthorized exception (Raphael Deem) - - 修复 (1062)：将应用程序注入到 add_task 方法 (Raphael Deem) - - 修正: 更新 environment.yml for readthedocs (Eli Uriegas) + - Fix (1062): inject the app in add_task method (Raphael Deem) + - Fix: update environment.yml for readthedocs (Eli Uriegas) - Fix: Cancel request task when response timeout is triggered (Jeong YunWon) - Fix (1052): Method not allowed response for RFC7231 compliance (Raphael Deem) - - 修复：IPv6 地址和 Socket 数据格式 (Dan Palmer) + - Fix: IPv6 Address and Socket Data Format (Dan Palmer) -注：更新日志保持在 0.1 和 0.7之间 +Note: Changelog was unmaintained between 0.1 and 0.7 -## 版本 0.1 +## Version 0.1 **0.1.7** -- 反转静态URL和目录参数以适应spec +- Reversed static url and directory arguments to meet spec **0.1.6** -- 静态文件 -- Lazy Cookie 加载 +- Static files +- Lazy Cookie Loading **0.1.5** -- Cookie -- 蓝图监听器和顺序 -- 快速路由器 -- 修复：在中等以上大小的帖子请求中读取不完整的文件 -- 断开︰ 事后开始和之前停止现在作为他们的 - 第一个参数 +- Cookies +- Blueprint listeners and ordering +- Faster Router +- Fix: Incomplete file reads on medium+ sized post requests +- Breaking: after_start and before_stop now pass sanic as their + first argument **0.1.4** -- 多处理 +- Multiprocessing **0.1.3** -- 蓝图支持 -- 快速响应处理 +- Blueprint support +- Faster Response processing **0.1.1 - 0.1.2** -- 通过 CI 更新 pypi 的字符串 +- Struggling to update pypi via CI **0.1.0** -- 向公众发布 +- Released to public From cae1a442891650f83767ff16a82dacbd82f4d91a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 07:11:28 +0200 Subject: [PATCH 475/698] New translations introduction.md (Chinese Simplified) --- guide/content/zh/guide/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/introduction.md b/guide/content/zh/guide/introduction.md index 74ef2300af..7cb4d6d8c0 100644 --- a/guide/content/zh/guide/introduction.md +++ b/guide/content/zh/guide/introduction.md @@ -1,4 +1,4 @@ -# 一. 导言 +# 介绍(Introduction) Sanic 是 Python 的 3.8+ 网页服务器和网页框架，它写得更快。 它允许使用 Python 3.5中添加的异步/等待语法，这使您的代码不受阻挡和快速。 From 35a34f7b426dbfbd8bdf453b845e91f2e3b03d8f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 08:40:27 +0200 Subject: [PATCH 476/698] New translations introduction.md (Chinese Simplified) --- guide/content/zh/guide/introduction.md | 56 +++++++++++++------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/guide/content/zh/guide/introduction.md b/guide/content/zh/guide/introduction.md index 7cb4d6d8c0..adb87640ff 100644 --- a/guide/content/zh/guide/introduction.md +++ b/guide/content/zh/guide/introduction.md @@ -1,6 +1,6 @@ # 介绍(Introduction) -Sanic 是 Python 的 3.8+ 网页服务器和网页框架，它写得更快。 它允许使用 Python 3.5中添加的异步/等待语法，这使您的代码不受阻挡和快速。 +Sanic 是 Python3.8+ Web 服务器和 Web 框架，旨在提高性能。 它允许使用 Python3.5 中添加的 async/await 异步语法，这使得您的代码有效地避免阻塞从而达到提升响应速度的目的。 .. attrs:: :class: introduction-table @@ -17,55 +17,55 @@ Sanic 是 Python 的 3.8+ 网页服务器和网页框架，它写得更快。 ## 什么是？ -首先，在你跳进水面之前，你应该知道Sanic与其他框架不同。 +首先，在入坑之前， 您应该知道 Sanic 框架和其他的框架相比是与众不同的。 -就在第一句中，因为Sanic 是 _both_a **framework** 和 **web server** 。 我们将在部署部分更多地谈论这个问题。 +Sanic 不仅仅是一个**框架（framework）**，更是一个**服务器（web server）** 我们将在部署（deployment ）章节更多地谈论这个问题。 -但请记住，Sanic 从盒子中带有你需要写、部署和缩放生产级网页应用程序的一切。 🚀 +但是，请记住，Sanic 具备开箱即用的功能，它可以用于编写，部署和扩展生产级 Web 应用程序。 🚀 ## 目标 -> 提供一个简单的方式来启动和运行一个易于构建的高性能的 HTTP 服务器， 扩大并最终扩大规模。 +> 提供一种简单且快速，集创建和启动于一体的方法，来实现一个易于修改和拓展的 HTTP 服务器 -## 功能 +## 功能(Features) -.. 列: +.. column:: ``` -### Core - -- Built in, **_fast_** web server -- Production ready -- Highly scalable -- ASGI compliant -- Simple and intuitive API design -- By the community, for the community +### 核心(Core) + +- 内置高性能的web server +- 生产就绪 +- 高度可扩展性 +- 遵循 ASGI 规范 +- 简单直观的API设计 +- 由社区强力驱动 ``` -.. 列: +.. column:: ``` -### Sanic Extensions [[learn more](../plugins/sanic-ext/getting-started.md)] - -- CORS protection -- Template rendering with Jinja -- Dependency injection into route handlers -- OpenAPI documentation with Redoc and/or Swagger -- Predefined, endpoint-specific response serializers -- Request query arguments and body input validation -- Auto create `HEAD`, `OPTIONS`, and `TRACE` endpoints +### 扩展(Sanic Extensions) [[learn more](../plugins/sanic-ext/getting-started.md)] + +- **CORS** 保护 +- 使用 **Jinja** 进行模板渲染 +- 将其他对象通过 **Dependency injection** （依赖注入）到路由处理程序中 +- 使用 **Redoc** 和/或 **Swagger** 编写 OpenAPI 文档 +- 预先定义好的**序列化函数**(eg `json` `text`)、作用于不同的路由入口（serializers） +- 请求查询参数和正文输入的**验证器**（validation） +- **自动创建** HEAD、OPTIONS 和 TRACE 入口（auto create） ``` ## 赞助商 -查看[打开集体](https://opencollective.com/sanic-org)来了解更多关于帮助融资Sanic的信息。 +[点击这里](https://opencollective.com/sanic-org)来了解更多关于帮助融资Sanic的信息。 ## 加入社区 讨论的主要渠道是[社区论坛](https://community.sanicframework.org/)。 还有一个 [Discord 服务器](https://discord.gg/RARQzAEMAA) 进行现场讨论和聊天。 -Stackoverflow \`[sanic]' 标签由项目维护者[积极监视](https://stackoverflow.com/questions/tagged/sanic)。 +Stackoverflow \`[sanic]' 标签由项目维护者[积极关注](https://stackoverflow.com/questions/tagged/sanic)。 ## 贡献 -我们总是乐于得到新的捐助。 我们有[标记的问题对任何想要开始的人来说都是好的](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner)，欢迎[questions/answers/discussion on on the forums](https://community.sanicframework.org/)。 请查看我们的[贡献指南](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst)。 +我们非常欢迎新的贡献者加入。 我们[有很清晰的issue标记对于那些想要快速上手的人](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner)，欢迎[ 在社区上提问/回答/讨论](https://community.sanicframework.org/)。 请查看我们的[贡献指南](https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst)。 From bbb4df55e81ebc3df55ea1814b366a946284f414 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 08:40:28 +0200 Subject: [PATCH 477/698] New translations getting-started.md (Chinese Simplified) --- guide/content/zh/guide/getting-started.md | 31 +++++++++++------------ 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/guide/content/zh/guide/getting-started.md b/guide/content/zh/guide/getting-started.md index 8fccd7898f..8c43d6326d 100644 --- a/guide/content/zh/guide/getting-started.md +++ b/guide/content/zh/guide/getting-started.md @@ -1,47 +1,46 @@ -# 正在开始 +# 快速上手 -在我们开始之前，请确保您正在运行 Python 3.8或更高版本。 目前，Sanic正在与 Python 版本 3.8 - 3.11一起工作。 +在我们开始之前，请确保您正在运行 Python 3.8或更高版本。 目前，Sanic可以运行在Python 版本 3.8 - 3.11上。 ## 安装 ```sh -pip 安装sanic +pip install sanic ``` -## 您好，全局应用程序 +## Hello, world 应用案例 -.. 列: +.. column:: ``` -If you have ever used one of the many decorator based frameworks, this probably looks somewhat familiar to you. - +如果你之前有使用过基于装饰器的web应用，那么Sanic的语法可能对你来说会很亲切。 -.. note:: +.. 注意:: - If you are coming from Flask or another framework, there are a few important things to point out. Remember, Sanic aims for performance, flexibility, and ease of use. These guiding principles have tangible impact on the API and how it works. + 如果您来自 Flask 或其他框架，有一些重要的事情需要指出。 请记住，Sanic 的目标是性能(performance)、灵活性(flexibility) 和易用性(ease of use)。 这些指导原则对 API 及其工作方式产生了切实的影响。 ``` -.. 列: +.. column:: ```` ```python -from sanic importing Sanic +from sanic import Sanic from sanic.response import text app = Sanic("MyHelloWorldApp") -@app. et("/") +@app.get("/") async def hello_world(request): return text("Hello, world.") ``` ```` -### 重要的注意事项 +### 重要提示 -- 每个请求处理程序都可以同步(`def hello_world`)，也可以同步(`async def hello_world`)。 除非你有明确的理由，否则总是使用 "async"。 -- "request" 对象始终是你处理器的第一个参数。 其它框架在要导入的上下文变量中传递这一点。 在 "async" 世界中 这种情况不会很好地发挥作用，因此更容易(更干净和业绩更好)对此加以明确说明。 -- 您**必须** 使用响应类型。 其他框架允许您有一个返回值，如：`return "Hello, world."` 或者 `return {"foo": "bar"}`。 但是，为了进行这种隐性的呼叫，链中的某个地方需要花费宝贵的时间来确定你的意思。 因此，萨尼克以牺牲这个容易为代价，决定要求明确呼叫。 +- 每一个请求响应函数都可以使用同步方式（`def hello_world`）和异步方式（`async def hello_world`）进行声明。 除非您有一个明确的需求和完善的使用方法，否则的话，请尽量使用 async 来声明响应函数。 +- `request` 对象始终是响应函数的第一个参数。 其他框架在需要导入的上下文变量中进行传递。 在 `async`的世界里，如果使用隐式传递，那么它将无法完美的运行，更何况还要兼顾简洁且高效的表现形式。 +- 您 必须 使用 Response 或继承自 Response 的类作为响应类型。 在许多其他框架中，它们允许您使用诸如 `return "Hello World"` 或者 `return {"foo":"bar"}` 的方式来进行返回， 但是为了执行这类隐式调用，需要在响应流程中的某个位置花费大量的时间来确定您到底想要表达什么意思。 因此，在Sanic的返回语句中，需要明确的指定返回的数据类型（eg `return json({"foo":"bar"})` 或 `return text("Hello world")`） ### 正在运行 From 2ce8efe6ade8457a36c7ee1e29a32571c5a267da Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 11:41:29 +0200 Subject: [PATCH 478/698] New translations getting-started.md (Chinese Simplified) --- guide/content/zh/guide/getting-started.md | 40 +++++++++++------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/guide/content/zh/guide/getting-started.md b/guide/content/zh/guide/getting-started.md index 8c43d6326d..df801cdb9b 100644 --- a/guide/content/zh/guide/getting-started.md +++ b/guide/content/zh/guide/getting-started.md @@ -2,13 +2,13 @@ 在我们开始之前，请确保您正在运行 Python 3.8或更高版本。 目前，Sanic可以运行在Python 版本 3.8 - 3.11上。 -## 安装 +## 安装（Install） ```sh pip install sanic ``` -## Hello, world 应用案例 +## Helloworld案例 .. column:: @@ -42,15 +42,15 @@ async def hello_world(request): - `request` 对象始终是响应函数的第一个参数。 其他框架在需要导入的上下文变量中进行传递。 在 `async`的世界里，如果使用隐式传递，那么它将无法完美的运行，更何况还要兼顾简洁且高效的表现形式。 - 您 必须 使用 Response 或继承自 Response 的类作为响应类型。 在许多其他框架中，它们允许您使用诸如 `return "Hello World"` 或者 `return {"foo":"bar"}` 的方式来进行返回， 但是为了执行这类隐式调用，需要在响应流程中的某个位置花费大量的时间来确定您到底想要表达什么意思。 因此，在Sanic的返回语句中，需要明确的指定返回的数据类型（eg `return json({"foo":"bar"})` 或 `return text("Hello world")`） -### 正在运行 +### 运行(Running) -.. 列: +.. column:: ``` 让我们把上面的文件保存为 `server.py`。然后启动它。 ``` -.. 列: +.. column:: ```` ```sh @@ -58,30 +58,30 @@ sanic server ``` ```` -.. 注： +.. note:: ``` 这**另一个**重要的区别。其它框架包含在开发服务器中，并明确表示它仅用于开发用途。 Sanic的情况正好相反。 -**打包服务器已准备就绪。** +**Sanic内置的web服务器是生产就绪的。** ``` -## 无声扩展 +## Sanic 拓展 -无知的特色清单的目的是要有一个清洁和无见解的特色清单。 该项目不想要求您以某种方式构建您的应用程序，并试图避免指定特定的开发模式。 有一些第三方插件由社区构建和维护，用于添加额外的功能，这些功能不符合核心存储库的要求。 +Sanic 致力于构建一个简洁且没有任何偏见的特征表。 该项目不想要求您以某种方式构建应用程序，并试图避免指定特定的开发模式。 有许多由社区构建和维护的第三方插件，用于添加不符合核心库要求的附加功能。 -但是，为了帮助API开发者\*\*，Sanic 组织维持一个名为[Sanic Extensions](../plugins/sanic-ext/getting-started.md)的官方插件，提供各种各样的谷物，其中包括： +但是，为了**帮助API开发者**，Sanic 组织维护了一个名为[Sanic Extensions](../plugins/sanic-ext/getting-started.md)的官方插件，提供各种各样的常见解决方案，其中包括： -- **OpenAPI** 文档与 Redoc 或 Swagger +- 使用 **Redoc** 和/或 **Swagger** 编写 OpenAPI 文档 - **CORS** 保护 -- **依赖注入** 对路由处理程序 -- 请求查询参数和正文输入 **验证** -- 自动创建 `HEAD`, `OPTIONS` 和 `TRACE` 终点 -- 预定义的端点特定响应序列转换器 +- 将其他对象通过 **Dependency injection** （依赖注入）到路由处理程序中 +- 请求查询参数和正文输入的**验证器**（validation） +- **自动创建** HEAD、OPTIONS 和 TRACE 入口（auto create） +- - 预先定义好的**序列化函数**(eg `json` `text`)、作用于不同的路由入口（serializers） -设置它的首选方法是与 Sanic 一起安装，但你也可以自己安装这个软件包。 +最好的安装方式就是在安装 Sanic 的同时一并安装 Sanic 拓展，当然，您也可以独立安装： -.. 列: +.. column:: ```` ```sh @@ -89,7 +89,7 @@ pip install sanic[ext] ``` ```` -.. 列: +.. column:: ```` ```sh @@ -97,9 +97,9 @@ pip install sanic sanic-ext ``` ```` -从 v21.12开始，萨尼语将在同一环境中自动设置萨尼克扩展。 您还可以访问另外两个应用程序属性： +从 v21.12 开始，如果在相同的环境中，Sanic 将自动设置 Sanic 扩展。 您可以通过以下的两种方式来进行访问拓展功能: - `app.extend()` - 用于配置 Sanic 扩展 -- `app.ext` - 附加到应用程序的`Extend`实例 +- `app.ext` - 注入到应用程序的扩展实例 请参阅[插件文档](../plugins/sanic-ext/getting-started.md) 了解如何使用和使用插件的更多信息 From b8ae30a18b1749f5c01506fce9025e2757a59363 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 29 Feb 2024 11:41:31 +0200 Subject: [PATCH 479/698] New translations app.md (Chinese Simplified) --- guide/content/zh/guide/basics/app.md | 30 ++++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/zh/guide/basics/app.md b/guide/content/zh/guide/basics/app.md index 76f971ee8b..4ad8beaf2a 100644 --- a/guide/content/zh/guide/basics/app.md +++ b/guide/content/zh/guide/basics/app.md @@ -6,15 +6,15 @@ title: Sanic 应用程序 请参阅API文档： [sanic.app](/api/sanic.app) -## 实例 +## 实例(Instance) -.. 列: +.. column:: ``` -The most basic building block is the :class:`sanic.app.Sanic` instance. It is not required, but the custom is to instantiate this in a file called `server.py`. +最基本的构建块是 :class: `sanic.app.Sanic` 实例。这不是必需的，但习惯是在名为 `server.py` 的文件中实例化它。 ``` -.. 列: +.. column:: ```` ```python @@ -26,17 +26,17 @@ app = Sanic("MyHelloWorldApp") ``` ```` -## 应用程序上下文： +## 应用上下文(Application context) -大多数应用程序将需要在代码库的不同部分之间共享/再利用数据或物体。 Sanic 帮助在应用程序实例上提供 `ctx` 对象。 它是开发者附加应用整个生命周期中应该存在的任何对象或数据的可用空间。 +大多数应用程序都需要跨代码库的不同部分共享/重用数据或对象。 Sanic 帮助在应用程序实例上提供 `ctx` 对象。 它是开发者附加应用整个生命周期中应该存在的任何对象或数据的可用空间。 -.. 列: +.. column:: ``` 最常见的模式是将数据库实例附加到应用程序中。 ``` -.. 列: +.. column:: ```` ```python @@ -48,10 +48,10 @@ app.ctx.db = Database() .. 列: ``` -While the previous example will work and is illustrative, it is typically considered best practice to attach objects in one of the two application startup [listeners](./listeners). +虽然前面的示例可以工作并且具有说明性，但通常将对象在应用的开始或结束的生命周期里添加是比较合适的 ``` -.. 列: +.. column:: ```` ```python @@ -63,15 +63,15 @@ async def attach_db(app, loop): ``` ```` -## 应用程序注册表 +## App 注册表(App Registry) -.. 列: +.. column:: ``` 当您实例化一个 Sanic 实例时，它可以稍后从 Sanic 应用程序注册表中检索。 例如，如果您需要从无法访问的地方访问您的 Sanic 实例，这可能是有用的。 ``` -.. 列: +.. column:: ```` ```python @@ -80,14 +80,14 @@ from sanic import Sanic app = Sanic("my_awesome_server") -# 路径/to/some where_else.py +# ./path/to/somewhere_else.py from sanic import Sanic app = Sanic.get_app("my_awesome_server") ``` ```` -.. 列: +.. column:: ``` If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name. From 399a88783109f61ce505351314d52d83c08fb364 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 1 Mar 2024 07:28:32 +0200 Subject: [PATCH 480/698] New translations websockets.md (Japanese) --- guide/content/ja/guide/advanced/websockets.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/content/ja/guide/advanced/websockets.md b/guide/content/ja/guide/advanced/websockets.md index afba802505..7f7eb0ec19 100644 --- a/guide/content/ja/guide/advanced/websockets.md +++ b/guide/content/ja/guide/advanced/websockets.md @@ -51,15 +51,15 @@ from sanic import Request, Websocket @app.websocket("/feed") async def feed(request: Request, ws: Websocket): while True: - data = "hello!" - print("Sending: " + data) + data = "こんにちは！" + print("送信中: " + data) await ws.send(data) data = await ws.recv() - print("Received: " + data) + print("受信: " + data) ``` ```` -.. 列:: +.. column:: ``` forループ内の`Websocket`オブジェクトを繰り返すだけで、ループを簡素化できます。 @@ -67,7 +67,7 @@ forループ内の`Websocket`オブジェクトを繰り返すだけで、ルー *v22.9*に追加されました ``` -.. 列:: +.. column:: ```` ```python From 18cdf4da70806f86bcd2d95db1a230b695259121 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 7 Mar 2024 09:07:59 +0200 Subject: [PATCH 481/698] New translations versioning.md (Chinese Simplified) --- guide/content/zh/guide/advanced/versioning.md | 36 ++++++++----------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/guide/content/zh/guide/advanced/versioning.md b/guide/content/zh/guide/advanced/versioning.md index 4999d9a2da..39bc5b76ab 100644 --- a/guide/content/zh/guide/advanced/versioning.md +++ b/guide/content/zh/guide/advanced/versioning.md @@ -25,7 +25,7 @@ Adding a version will add a `/v{version}` url prefix to your endpoints. # /v1/text @app.route("/text", version=1) def handle_request(request): - return response. ext("Hello world! 版本 1") + return response. ext("Hello world! Version 1") # /v2/text @app.route("/text", version=2) @@ -60,55 +60,49 @@ def handle_request(request): .. 列: ``` -In order to simplify the management of the versioned blueprints, you can provide a version number in the blueprint -group. The same will be inherited to all the blueprint grouped under it if the blueprints don't already override the -same information with a value specified while creating a blueprint instance. +为了简化版本化蓝图的管理，您可以在蓝图中提供版本号组。如果蓝图还没有覆盖，那么同样的将被继承到分组在它下面的所有蓝图与创建蓝图实例时指定的值相同的信息。 -When using blueprint groups for managing the versions, the following order is followed to apply the Version prefix to -the routes being registered. +当使用蓝图组来管理版本时，遵循以下顺序将Version前缀应用于正在注册的路由。 -1. Route Level configuration -2. Blueprint level configuration -3. Blueprint Group level configuration - -If we find a more pointed versioning specification, we will pick that over the more generic versioning specification -provided under the Blueprint or Blueprint Group +1. 路由级别配置 +2. 蓝图级配置 +3. 组级配置 ``` .. 列: ```` ```python -从 sanic.blueprints 导入蓝图A.format@@1 esponse import json +from sanic.blueprints import Blueprint +from sanic.response import json bp1 = Blueprint( name="blueprint-1", url_prefix="/bp1", - version=1。 5 , + version=1.25, ) bp2 = Blueprint( name="blueprint-2", url_prefix="/bp2", - -group = Blueprint. 路由( +group = Blueprint.group( [bp1, bp2], url_prefix="/bp-group", version="v2", ) -# GET /v1。 5/bp-group/bp1/endpoint-1 -@bp1。 et("/endpoint-1") +# GET /v1.25/bp-group/bp1/endpoint-1 +@bp1.get("/endpoint-1") async def handle_endpoint_1_bp1(request): - return json({"Source": "bluprint-1/endpoint-1"}) + return json({"Source": "blueprint-1/endpoint-1"}) # GET /v2/bp-group/bp2/endpoint-2 -@bp2. et("/endpoint-1") +@bp2.get("/endpoint-1") async def handle_endpoint_1_bp2(request): return json({"Source": "blueprint-2/endpoint-1"}) # GET /v1/bp-group/bp2/endpoint-2 -@bp2. et("/endpoint-2", version=1) +@bp2.get("/endpoint-2", version=1) async def handle_endpoint_2_bp2(request): return json({"Source": "blueprint-2/endpoint-2"}) ``` From 5c3c7211de9f2be7b9838a986837058e7771e664 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 7 Mar 2024 09:08:00 +0200 Subject: [PATCH 482/698] New translations cors.md (Chinese Simplified) --- guide/content/zh/guide/how-to/cors.md | 30 +++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/zh/guide/how-to/cors.md b/guide/content/zh/guide/how-to/cors.md index 7fc5894825..97f393ea3b 100644 --- a/guide/content/zh/guide/how-to/cors.md +++ b/guide/content/zh/guide/how-to/cors.md @@ -38,27 +38,27 @@ app.register_middleware(add_cors_headers, "response") ## `cors.py` ```python -从输入导入Iterable +from typing import Iterable -def _add_cors_headers(响应) 方法: Iterable[str]) -> 无: +def _add_cors_headers(response, methods: Iterable[str]) -> None: allow_methods = list(set(methods)) - 如果"OPTIONS" 不在allow_methods: - allow_methods. pend("OPTIONS") - headers = 哇， - "Access-Control-Allow-Methods"：","。 oin(allow_methods), - "Access-Control-Allow-origin": mydomain. om, + if "OPTIONS" not in allow_methods: + allow_methods.append("OPTIONS") + headers = { + "Access-Control-Allow-Methods": ",".join(allow_methods), + "Access-Control-Allow-Origin": "mydomain.com", "Access-Control-Allow-Credentials": "true", - “Access Control-Allow-Headers”: ( - "original, 内容类型，接受，" + "Access-Control-Allow-Headers": ( + "origin, content-type, accept, " "authorization, x-xsrf-token, x-request-id" - , + ), } - 响应。 eaders.extend(headers) + response.headers.extend(headers) def add_cors_headers(request, response): - if request. ethod != "OPTIONS": - methods = [方法是请求的。 退出.methods] - _add_cors_headers(响应, 方法) + if request.method != "OPTIONS": + methods = [method for method in request.route.methods] + _add_cors_headers(response, methods) ``` ## `options.py` @@ -135,4 +135,4 @@ connection: keep-alive 此外，结算社区的一些资源： -- [极好的卫生](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) +- [很棒的Sanic](https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) From 92b1fc0a5f16fc0de9979dc77aaecf41c574300d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sat, 23 Mar 2024 08:26:06 -0400 Subject: [PATCH 483/698] New translations websockets.md (Japanese) --- guide/content/ja/guide/advanced/websockets.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/guide/advanced/websockets.md b/guide/content/ja/guide/advanced/websockets.md index 7f7eb0ec19..a86a8abd9c 100644 --- a/guide/content/ja/guide/advanced/websockets.md +++ b/guide/content/ja/guide/advanced/websockets.md @@ -35,11 +35,11 @@ async def feed(request: Request, ws: Websocket): .. 列:: ``` -Typically, a websocket handler will want to hold open a loop. +一般的に、ウェブソケットハンドラはループを開いたままにします。 -It can then use the `send()` and `recv()` methods on the second object injected into the handler. +そして、ハンドラに注入された 2 番目のオブジェクトの `send()` メソッドと `recv()` メソッドを使用します。 -This example is a simple endpoint that echos back to the client messages that it receives. +この例は、受信したメッセージをクライアントにエコーバックする単純なエンドポイントです。 ``` .. 列:: From 3c5efaf6a120827a50c384c0705c92a9fddb53e1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Apr 2024 06:32:04 -0400 Subject: [PATCH 484/698] New translations html5tagger.md (Japanese) --- guide/content/ja/plugins/sanic-ext/templating/html5tagger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md b/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md index baba439d0b..7a13eae73b 100644 --- a/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md +++ b/guide/content/ja/plugins/sanic-ext/templating/html5tagger.md @@ -4,4 +4,4 @@ title: Sanic Extensions - html5tagger # 近日公開 -See [GitHub])(https\://github.com/sanic-org/html5tagger/) +[sanic-org/html5tagger on GitHub](https://github.com/sanic-org/html5tagger/) を参照してください。 From 40ca29e96e4d457b54f9c6f7691b0c76dc88e28c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Apr 2024 06:33:23 -0400 Subject: [PATCH 485/698] New translations html5tagger.md (Korean) --- guide/content/ko/plugins/sanic-ext/templating/html5tagger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/plugins/sanic-ext/templating/html5tagger.md b/guide/content/ko/plugins/sanic-ext/templating/html5tagger.md index ab2c64ccdb..0321dbdb63 100644 --- a/guide/content/ko/plugins/sanic-ext/templating/html5tagger.md +++ b/guide/content/ko/plugins/sanic-ext/templating/html5tagger.md @@ -4,4 +4,4 @@ title: Sanic Extensions - html5tagger # Coming soon -See [GitHub])(https\://github.com/sanic-org/html5tagger/) +See [sanic-org/html5tagger on GitHub](https://github.com/sanic-org/html5tagger/) From 86c8beab598aeb872f3a4e28fca40760a935f057 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Apr 2024 06:34:39 -0400 Subject: [PATCH 486/698] New translations html5tagger.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/templating/html5tagger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md b/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md index aac8d92735..e3790c4e7a 100644 --- a/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md +++ b/guide/content/zh/plugins/sanic-ext/templating/html5tagger.md @@ -4,4 +4,4 @@ title: Sanic 扩展 - html5tagger # 即将开始 -See [GitHub](https://github.com/sanic-org/html5tagger/) +见 [sanic-org/html5tagger on GitHub](https://github.com/sanic-org/html5tagger/) From 4229c4e9f18fd58657616f327d6abe6810a01bb9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Apr 2024 08:09:27 -0400 Subject: [PATCH 487/698] New translations configuration.md (Japanese) --- guide/content/ja/plugins/sanic-ext/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/configuration.md b/guide/content/ja/plugins/sanic-ext/configuration.md index 41891c6bc8..f0db931894 100644 --- a/guide/content/ja/plugins/sanic-ext/configuration.md +++ b/guide/content/ja/plugins/sanic-ext/configuration.md @@ -237,7 +237,7 @@ app.config.OAS_URL_PREFIX = "/apidocs" - **タイプ**: `str` - **Default**: `"/swagger-config"` -- **説明**: Swagger configurtaion を提供するパス +- **説明**: Swagger 設定を提供するパス ### `oas_uri_to_json` From 8f6486ccf87cebd4cb2e1046a7583ffbd4b5bf56 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Apr 2024 08:10:39 -0400 Subject: [PATCH 488/698] New translations configuration.md (Korean) --- guide/content/ko/plugins/sanic-ext/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/plugins/sanic-ext/configuration.md b/guide/content/ko/plugins/sanic-ext/configuration.md index 1443cfc6e9..2debb7e779 100644 --- a/guide/content/ko/plugins/sanic-ext/configuration.md +++ b/guide/content/ko/plugins/sanic-ext/configuration.md @@ -237,7 +237,7 @@ Be very careful if you place `*` here. Do not do this unless you know what you a - **Type**: `str` - **Default**: `"/swagger-config"` -- **Description**: Path to serve the Swagger configurtaion +- **Description**: Path to serve the Swagger configuration ### `oas_uri_to_json` From a4d858532563094d36dfd389ec0d16c9cfac982f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Mon, 1 Apr 2024 08:11:58 -0400 Subject: [PATCH 489/698] New translations configuration.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/plugins/sanic-ext/configuration.md b/guide/content/zh/plugins/sanic-ext/configuration.md index c9594e290a..58ec95a2c9 100644 --- a/guide/content/zh/plugins/sanic-ext/configuration.md +++ b/guide/content/zh/plugins/sanic-ext/configuration.md @@ -237,7 +237,7 @@ app.config.OAS_URL_PREFIX = "/apidocs" - **类型**: `str` - **Default**: `"/swagger-config"` -- **描述**：服务的 Swagger 配置路径 +- **描述**：为 Swagger 配置服务的路径 ### `oas_uri_to_json` From 485bfd2cddd7f1d7b5351e9261dc6dbb715d1e74 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 3 Apr 2024 12:13:35 -0400 Subject: [PATCH 490/698] New translations autodoc.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/openapi/autodoc.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md index f4e82d0f0e..b912f9ef34 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md @@ -1,17 +1,17 @@ --- -title: Sanic 扩展 - 自动文档 +title: Sanic 扩展 - 自动生成文档 --- # 自动文档 -要使文档端点变得更容易，Sanic 扩展将使用函数的 docstring 来填充您的文档。 +要使得创建API文档页面变得更容易，Sanic 扩展可以使用函数的 docstring 来自动化填充您的文档。 ## 摘要和说明 .. 列: ``` -函数的 docstring 将用于创建摘要和描述。 从这里的例子中你可以看到， docstring 已被解析成第一行作为总结。 和字符串的其余部分作为描述。 +函数的 docstring 将用于创建摘要和描述。 从这里的例子中你可以看到， docstring 已被解析成：第一行作为总结，字符串的其余部分作为描述。 ``` .. 列: @@ -48,7 +48,7 @@ async def handler(request, something: str): ``` ```` -## 操作级别 YAML +## 操作级别的 YAML .. 列: From 8cae91b89b43db96a5dd0ebdc979240f36984785 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 3 Apr 2024 13:25:15 -0400 Subject: [PATCH 491/698] New translations autodoc.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/openapi/autodoc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md index b912f9ef34..91b44c99f9 100644 --- a/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md +++ b/guide/content/zh/plugins/sanic-ext/openapi/autodoc.md @@ -53,9 +53,9 @@ async def handler(request, something: str): .. 列: ``` -你可以通过将有效的 OpenAPI YAML 添加到文档字符串来扩展这个。只需添加一行包含 `openapi:`, 然后是你的 YAML。 +通过将有效的 OpenAPI YAML 添加到文档字符串中，你可以扩展自动文档功能。只需在文档字符串中添加一行包含 `openapi:` 的字符串，后面跟随你提供的 YAML 即可。 -示例中显示的 "---" 是*不需要*。 只是为了帮助视觉辨认YAML是文档的一个独特部分。 +在示例中，"---" 这个标记是*非必要的*，它只是为了帮助将 YAML 在视觉上与文档的其他部分区分开来。 ``` .. 列: From 99fe94d126b289826e5431d067135d6d61ceb635 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 4 Apr 2024 15:16:08 +0300 Subject: [PATCH 492/698] New translations custom.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/custom.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/plugins/sanic-ext/custom.md b/guide/content/zh/plugins/sanic-ext/custom.md index 19b15fc171..fa0d51caa1 100644 --- a/guide/content/zh/plugins/sanic-ext/custom.md +++ b/guide/content/zh/plugins/sanic-ext/custom.md @@ -6,7 +6,7 @@ title: Sanic 扩展 - 自定义 可以创建您自己的自定义扩展。 -22.9版本添加了 `Extend.register` [method](#extension-preregistration)。 这使得在应用程序中添加自定义支出变得极为容易。 +22.9版本添加了 `Extend.register` [method](#extension-preregistration)。 这使得向应用程序添加自定义扩展变得非常容易。 ## 扩展的解析度 From 2cd9203c4cb4421c31a6a2a57034deee27a29fd6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 4 Apr 2024 16:37:01 +0300 Subject: [PATCH 493/698] New translations request.md (Chinese Simplified) --- guide/content/zh/guide/basics/request.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/guide/content/zh/guide/basics/request.md b/guide/content/zh/guide/basics/request.md index e79725308b..4cc6ada5cd 100644 --- a/guide/content/zh/guide/basics/request.md +++ b/guide/content/zh/guide/basics/request.md @@ -2,14 +2,14 @@ 查看 API 文档： [sanic.request](/api/sanic.request) -The :class:`sanic.request.Request` instance contains **a lot** of helpful information available on its parameters. 详情请参阅[API 文档](https://sanic.readthedocs.io/)。 +:class: `sanic.request.Request` 实例包含了许多有用的信息，这些信息可以在其参数中获得。 详情请参阅[API 文档](https://sanic.readthedocs.io/)。 -As we saw in the section on [handlers](./handlers), the first argument in a route handler is usually the :class:`sanic.request.Request` object. 因为Sanic 是一个异步框架，处理程序将运行在一个[asyncio.Task\`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task)内，并将由事件循环进行安排。 这意味着处理程序将在一个孤立的环境中执行，而请求对象将是该处理程序的唯一任务。 +正如我们在 [handlers](./handlers) 部分中所看到的，路由处理器的第一个参数通常是 :class:`sanic.request.Request` 对象。 因为Sanic是一个异步框架，处理器将在一个 [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) 内运行，并由事件循环调度。 这意味着处理器将在一个隔离的上下文中执行，并且请求对象对于该处理器是唯一的。 .. 列: ``` -根据惯例，这个论点叫做`request`，但你可以给它命名你想要的。 参数的名称不重要。以下两个处理程序都是有效的。 +按照惯例，参数被命名为`request`，但您可以根据需要随意命名。参数的名称并不重要。以下两个处理器的写法都是有效的。 ``` .. 列: @@ -31,7 +31,7 @@ async def atypical_use_case(req): .. 列: ``` -注释请求对象是超级简单。 +注释请求对象超级简单。 ``` @@ -51,14 +51,15 @@ async def typed_handler(request: Request): .. tip:: ``` -为方便起见，假定您正在使用一个现代的 IDE，您应该利用类型注释来帮助代码完成和文档。 这在使用 "request" 对象时特别有用，因为它有 **MANY** 属性和方法。 - -要查看可用属性和方法的完整清单，请参阅[API 文档](/api/sanic.request)。 +为了您的方便，假设您正在使用现代的集成开发环境（IDE），您应该利用类型注解来帮助代码自动完成和文档编写。这在使用request对象时尤为有用，因为它具有**许多**属性和方法。 + +要查看可用属性和方法的完整列表，请参阅[API文档] +(/api/sanic.request)。 ``` ## 正文内容 -`Request`对象允许您以几种不同方式访问请求主体的内容。 +`Request`对象允许您以几种不同的方式访问请求体的内容。 ### JSON @@ -82,7 +83,7 @@ $ curl localhost:8000 -d '{"foo": "bar"}' ``` ```` -### 原始文件 +### 原始数据 .. 列: From 3f92db591cf252673c8486356214f85ff8e8d7ee Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 4 Apr 2024 16:37:02 +0300 Subject: [PATCH 494/698] New translations custom.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/custom.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/custom.md b/guide/content/zh/plugins/sanic-ext/custom.md index fa0d51caa1..f33d0808e6 100644 --- a/guide/content/zh/plugins/sanic-ext/custom.md +++ b/guide/content/zh/plugins/sanic-ext/custom.md @@ -8,19 +8,19 @@ title: Sanic 扩展 - 自定义 22.9版本添加了 `Extend.register` [method](#extension-preregistration)。 这使得向应用程序添加自定义扩展变得非常容易。 -## 扩展的解析度 +## 扩展的构成 -所有扩展必须是子类“扩展”。 +所有的扩展都必须继承自 Extension 类。 ### 必填 -- `name`: 按惯例, 名称是一个小写字符串 -- `启动`: 添加扩展时运行的方法 +- `name`: 按惯例, 名称是一个纯小写字符串 +- `startup`: 当扩展被添加时运行的方法 -### 可选的 +### 可选项 -- `label`：返回MOTD中有关扩展的额外信息的方法 -- `included`：返回是否启用扩展名布尔值的方法 (可以用来检查配置状态) +- `label`: 一个在 MOTD 中返回有关扩展的附加信息的方法 +- `included`: 一个返回布尔值的方法，用于确定扩展是否应该启用（例如，可以用于检查配置状态） ### 示例 From c2c6a895243767f7a842a748f9e345c5cad8f393 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 12:40:58 +0300 Subject: [PATCH 495/698] New translations health-monitor.md (Japanese) --- guide/content/ja/plugins/sanic-ext/health-monitor.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/health-monitor.md b/guide/content/ja/plugins/sanic-ext/health-monitor.md index b3051a49fa..1f9a0f63f9 100644 --- a/guide/content/ja/plugins/sanic-ext/health-monitor.md +++ b/guide/content/ja/plugins/sanic-ext/health-monitor.md @@ -13,7 +13,7 @@ Sanic Extensionsを設定して、作業工程の健全性を監視できます .. 列:: ``` -ヘルスモニターは無効になっています。使用したい場合はオプトインする必要があります。 +ヘルスモニターは無効になっています。使用したい場合はオプトインしてエンドポイントを有効にする必要があります。 ``` .. 列:: @@ -21,6 +21,7 @@ Sanic Extensionsを設定して、作業工程の健全性を監視できます ```` ```python app.config.HEALTH = True +app.config.HEALTH_ENDPOINT = True ``` ```` From 1ab3a23d1a248b465354e38d53e083dd5d6a2ba9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 12:40:59 +0300 Subject: [PATCH 496/698] New translations health-monitor.md (Korean) --- guide/content/ko/plugins/sanic-ext/health-monitor.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/guide/content/ko/plugins/sanic-ext/health-monitor.md b/guide/content/ko/plugins/sanic-ext/health-monitor.md index 82b8271f95..16111a0896 100644 --- a/guide/content/ko/plugins/sanic-ext/health-monitor.md +++ b/guide/content/ko/plugins/sanic-ext/health-monitor.md @@ -13,7 +13,7 @@ You can setup Sanic Extensions to monitor the health of your worker processes. T .. column:: ``` -Out of the box, the health monitor is disabled. You will need to opt-in if you would like to use it. +Out of the box, the health monitor is disabled. You will need to opt-in and enable the endpoint if you would like to use it. ``` .. column:: @@ -21,6 +21,7 @@ Out of the box, the health monitor is disabled. You will need to opt-in if you w ```` ```python app.config.HEALTH = True +app.config.HEALTH_ENDPOINT = True ``` ```` @@ -68,8 +69,8 @@ $ curl http://localhost:8000/__health__ ## Configuration -| Key | Type | Default | Description | -| --------------------------------------------------------------------------------- | ------ | --------------- | --------------------------------------------------------------------------- | +| Key | Type | Default | Description | +| --------------------------------------------------------------------------------- | ------ | --------------- | ------------------------------------------------------------------------------------------- | | HEALTH | `bool` | `False` | Whether to enable this extension. | | HEALTH_ENDPOINT | `bool` | `False` | Whether to enable the diagnostics endpoint. | | HEALTH_MAX_MISSES | `int` | `3` | The number of consecutive misses before a worker process is restarted. | From 39ceb5b4cd29f97e4ca94b3898385feb6fd83324 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 12:41:01 +0300 Subject: [PATCH 497/698] New translations health-monitor.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/health-monitor.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/guide/content/zh/plugins/sanic-ext/health-monitor.md b/guide/content/zh/plugins/sanic-ext/health-monitor.md index ae016637d3..1533584684 100644 --- a/guide/content/zh/plugins/sanic-ext/health-monitor.md +++ b/guide/content/zh/plugins/sanic-ext/health-monitor.md @@ -13,7 +13,7 @@ title: 神经扩展-健康监测 .. 列: ``` -在方框中，健康监视器被禁用。如果您想要使用它，您需要选择进入它。 +离开框，健康监视器被禁用。如果您想要使用它，您需要选择进入并启用端点。 ``` .. 列: @@ -21,6 +21,7 @@ title: 神经扩展-健康监测 ```` ```python app.config.HEALTH = True +app.config.HEALTH_ENDPOINT = True ``` ```` From ce6287ff3dac060dda180be6e1ea041974707e26 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:31:57 +0300 Subject: [PATCH 498/698] New translations built-with-sanic.md (Japanese) --- guide/content/ja/built-with-sanic.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/built-with-sanic.md b/guide/content/ja/built-with-sanic.md index 3294ba15e6..c2b3f33fd1 100644 --- a/guide/content/ja/built-with-sanic.md +++ b/guide/content/ja/built-with-sanic.md @@ -41,7 +41,7 @@ layout: メイン ### コード：GitHubの場所 -私たちのコードはすべてオープンで、GitHubの公開審査の栄光を浴びています。 なぜ魔法を隠すのですか? 詳細は format@@0(https\://github.com/sanic-org/sanic/tree/main/guide) をご覧ください。 先に進み、覗き見を取る、フォーク、それで遊ぶ、それを壊す(そして親切にそれを修正する)。 +私たちのコードはすべてオープンで、GitHubの公開審査の栄光を浴びています。 なぜ魔法を隠すのですか? 詳細は format@@0(https://github.com/sanic-org/sanic/tree/main/guide) をご覧ください。 先に進み、覗き見を取る、フォーク、それで遊ぶ、それを壊す(そして親切にそれを修正する)。 オープンソースは単なる流行語ではありません私たちの精神です 私たち自身よりも大きなものを一緒に作ることです 私たちのコードは、共同でのイノベーション、開発のための遊び場、そして実際のSanicの実例を証明しています。 From 0a4d5c2f71fdd3d80baa790ccd8ed48e8355dd03 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:31:59 +0300 Subject: [PATCH 499/698] New translations proxy-headers.md (Japanese) --- .../ja/guide/advanced/proxy-headers.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/guide/content/ja/guide/advanced/proxy-headers.md b/guide/content/ja/guide/advanced/proxy-headers.md index 4aaca3d313..347557787e 100644 --- a/guide/content/ja/guide/advanced/proxy-headers.md +++ b/guide/content/ja/guide/advanced/proxy-headers.md @@ -78,7 +78,7 @@ async def forwarded(request): ) ``` -*** +--- ##### 例1 @@ -121,7 +121,7 @@ app.config.REAL_IP_HEADER = "x-real-ip" ``` ```` -*** +--- ##### 例2 @@ -166,7 +166,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例3 @@ -209,7 +209,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例4 @@ -247,7 +247,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例5 @@ -287,7 +287,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例6 @@ -328,7 +328,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例7 @@ -369,7 +369,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例8 @@ -409,7 +409,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例9 @@ -449,7 +449,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例10 @@ -489,7 +489,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例11 @@ -532,7 +532,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例12 From 97caabca478a7b863c9b94d47884b44fc1d7eba3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:04 +0300 Subject: [PATCH 500/698] New translations cookies.md (Japanese) --- guide/content/ja/guide/basics/cookies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/basics/cookies.md b/guide/content/ja/guide/basics/cookies.md index d31d7a0c9f..f5a3bac2fe 100644 --- a/guide/content/ja/guide/basics/cookies.md +++ b/guide/content/ja/guide/basics/cookies.md @@ -68,7 +68,7 @@ Response Cookieは辞書の値のように設定でき、次のパラメータ - `secure_prefix: bool` - Cookieに`__Secure-`プレフィックスを追加するかどうか。 - `partitioned: bool` - クッキーをパーティションとしてマークするかどうか。 -これらの値の意味と使用状況をよりよく理解するためには、format@@0(https\://developer.mozilla.org/en-US/docs/Web/HTTP/Cookie)のformat@@1(https\://developer.mozilla.org/docs/Web/HTTP/Cookie)を読むと便利かもしれません。 +これらの値の意味と使用状況をよりよく理解するためには、format@@0(https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookie)のformat@@1(https://developer.mozilla.org/docs/Web/HTTP/Cookie)を読むと便利かもしれません。 .. tip:: FYI From 2305594fa56a84e192261d4dbfa3ec46f536733c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:05 +0300 Subject: [PATCH 501/698] New translations handlers.md (Japanese) --- guide/content/ja/guide/basics/handlers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/guide/basics/handlers.md b/guide/content/ja/guide/basics/handlers.md index e433c9a24a..3785e3ff60 100644 --- a/guide/content/ja/guide/basics/handlers.md +++ b/guide/content/ja/guide/basics/handlers.md @@ -69,7 +69,7 @@ async def foo_handler(request): ``` ```` -*** +--- ## _async_についての単語。 @@ -140,7 +140,7 @@ Instead, try using a client that is `async/await` capable. Your server will than Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package (sanic-testing) 😉. ``` -*** +--- ## 完全に注釈を付けられたハンドラです From 08b3b987de48bbb3db9a6344ca9bbdc726008a1a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:09 +0300 Subject: [PATCH 502/698] New translations request.md (Japanese) --- guide/content/ja/guide/basics/request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/basics/request.md b/guide/content/ja/guide/basics/request.md index 5a942b473b..d1820d093f 100644 --- a/guide/content/ja/guide/basics/request.md +++ b/guide/content/ja/guide/basics/request.md @@ -2,7 +2,7 @@ API ドキュメント: [sanic.request](/api/sanic.request) を参照してください。 -:class:`sanic.request.Request`インスタンスには、パラメータで入手可能な役立つ情報がたくさん含まれています。 詳細については、format@@0(https\://sanic.readthedocs.io/)を参照してください。 +:class:`sanic.request.Request`インスタンスには、パラメータで入手可能な役立つ情報がたくさん含まれています。 詳細については、format@@0(https://sanic.readthedocs.io/)を参照してください。 [handlers](./handlers) のセクションで見たとおり、ルートハンドラの最初の引数は通常、 :class:`sanic.request.Request` オブジェクトです。 Sanic は非同期フレームワークなので、ハンドラは[`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task)の中で実行され、イベントループによってスケジュールされます。 これは、ハンドラが分離されたコンテキストで実行され、リクエストオブジェクトはそのハンドラのタスクに固有であることを意味します。 From b083e3b86c4d239cfc8db6ad7f8be036e43c345c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:11 +0300 Subject: [PATCH 503/698] New translations routing.md (Japanese) --- guide/content/ja/guide/basics/routing.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/guide/content/ja/guide/basics/routing.md b/guide/content/ja/guide/basics/routing.md index bc77198980..2f7af7c719 100644 --- a/guide/content/ja/guide/basics/routing.md +++ b/guide/content/ja/guide/basics/routing.md @@ -100,7 +100,7 @@ async def handler(request): return text('OK') ``` -[MDN Docs](https\://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST ### PUT @@ -469,14 +469,14 @@ async def handler(request, foo: str, ext: str): ``` ```` -| 定義 | 例 | ファイル名 | 拡張 | -| ---------------------------------- | ----------- | -------- | ---------- | -| \ | page.txt | `"page"` | `"txt"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| 定義 | 例 | ファイル名 | 拡張 | +| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | +| \file:ext | page.txt | `"page"` | `"txt"` | +| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | +| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | ファイル拡張子は、特別なパラメータタイプ`ext`を使用して一致させることができます。 これは、ファイル名として他のタイプのパラメータを指定することができる特別な形式を使用します。 上の表に示されているように、1つまたは複数の特定の拡張子を指定します。 @@ -542,7 +542,7 @@ app.route(r"/image/\d+)\.jpg>") @app.get(r"/\d+).jpg>") # NOT OK ``` -format@@0(https\://docs.python.org/3/library/re.html) を参照してください。 +format@@0(https://docs.python.org/3/library/re.html) を参照してください。 ## URLの生成 From 30d594d893dc3620d813535078482ae04a942946 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:15 +0300 Subject: [PATCH 504/698] New translations exceptions.md (Japanese) --- guide/content/ja/guide/best-practices/exceptions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/best-practices/exceptions.md b/guide/content/ja/guide/best-practices/exceptions.md index c25ddd30d2..b1d3c635fc 100644 --- a/guide/content/ja/guide/best-practices/exceptions.md +++ b/guide/content/ja/guide/best-practices/exceptions.md @@ -14,7 +14,7 @@ async def no_no(request): raise SanicException("Something went wrong .", status_code=501) ``` -Sanicは多くの標準的な例外を提供します。 それぞれが自動的にレスポンス内に適切なHTTPステータスコードを発生させます。 詳細については、format@@0(https\://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) を参照してください。 +Sanicは多くの標準的な例外を提供します。 それぞれが自動的にレスポンス内に適切なHTTPステータスコードを発生させます。 詳細については、format@@0(https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#module-sanic.exceptions) を参照してください。 .. 列:: From a1df5b843b2460564ad4550dbc1ebfa3765540d1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:16 +0300 Subject: [PATCH 505/698] New translations logging.md (Japanese) --- guide/content/ja/guide/best-practices/logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/best-practices/logging.md b/guide/content/ja/guide/best-practices/logging.md index b5880803cf..4cfc2a3f19 100644 --- a/guide/content/ja/guide/best-practices/logging.md +++ b/guide/content/ja/guide/best-practices/logging.md @@ -1,6 +1,6 @@ # ログ -Sanicはformat@@0(https\://docs.python.org/3/howto/logging.html)に基づいてリクエストの異なるタイプのログ(アクセスログ、エラーログ)を行うことができます。 新しい設定を作成したい場合は、Pythonロギングに関する基本的な知識を持っている必要があります。 +Sanicはformat@@0(https://docs.python.org/3/howto/logging.html)に基づいてリクエストの異なるタイプのログ(アクセスログ、エラーログ)を行うことができます。 新しい設定を作成したい場合は、Pythonロギングに関する基本的な知識を持っている必要があります。 ## クイックスタート From 6f2de48a9a2e5b7647ae526a66f2912734af7f17 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:18 +0300 Subject: [PATCH 506/698] New translations caddy.md (Japanese) --- guide/content/ja/guide/deployment/caddy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/deployment/caddy.md b/guide/content/ja/guide/deployment/caddy.md index 326ac05a65..d1406f75b0 100644 --- a/guide/content/ja/guide/deployment/caddy.md +++ b/guide/content/ja/guide/deployment/caddy.md @@ -71,4 +71,4 @@ app.example.com { } ``` -詳細については、format@@0(https\://caddyserver.com/docs/)を参照してください。 +詳細については、format@@0(https://caddyserver.com/docs/)を参照してください。 From 8fa0df0a9350bc037e250ee4029f571b0c3a0291 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:19 +0300 Subject: [PATCH 507/698] New translations docker.md (Japanese) --- guide/content/ja/guide/deployment/docker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/deployment/docker.md b/guide/content/ja/guide/deployment/docker.md index 2ab66084ad..c115fa5753 100644 --- a/guide/content/ja/guide/deployment/docker.md +++ b/guide/content/ja/guide/deployment/docker.md @@ -2,7 +2,7 @@ ## はじめに -長い間、環境はデプロイにとって困難な問題でした。 プロジェクトに矛盾する構成がある場合は、それらの解決に多くの時間を費やす必要があります。 幸いなことに、仮想化は私たちに良い解決策を提供します。 Dockerはその一つです。 Dockerを知らない場合は、format@@0(https\://www\.docker.com/)をご覧ください。 +長い間、環境はデプロイにとって困難な問題でした。 プロジェクトに矛盾する構成がある場合は、それらの解決に多くの時間を費やす必要があります。 幸いなことに、仮想化は私たちに良い解決策を提供します。 Dockerはその一つです。 Dockerを知らない場合は、format@@0(https://www.docker.com/)をご覧ください。 ## ビルド画像 From 17d68c276c19c595848dadb1ea6f86f3e20ada25 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:23 +0300 Subject: [PATCH 508/698] New translations authentication.md (Japanese) --- guide/content/ja/guide/how-to/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/authentication.md b/guide/content/ja/guide/how-to/authentication.md index c6ac86a3bd..5c33b060d7 100644 --- a/guide/content/ja/guide/how-to/authentication.md +++ b/guide/content/ja/guide/how-to/authentication.md @@ -76,7 +76,7 @@ def protected(wrapped): このデコレータパターンは format@@0(/ja/guide/best-practices/decorators.md) から取得されます。 -*** +--- ```bash $ curl localhost:9999/secret -i From 0a4a108231779a3d4e23a40cc06cd11ebcb84d3e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:24 +0300 Subject: [PATCH 509/698] New translations autodiscovery.md (Japanese) --- guide/content/ja/guide/how-to/autodiscovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/autodiscovery.md b/guide/content/ja/guide/how-to/autodiscovery.md index a0929ea7d9..2b4b55029b 100644 --- a/guide/content/ja/guide/how-to/autodiscovery.md +++ b/guide/content/ja/guide/how-to/autodiscovery.md @@ -158,7 +158,7 @@ def print_something(app, loop): logger.debug("something @ nested") ``` -*** +--- ```text here is the dir tree From d2a3e674dd746608ef246112aa3f5daa61c3c690 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:25 +0300 Subject: [PATCH 510/698] New translations cors.md (Japanese) --- guide/content/ja/guide/how-to/cors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/guide/how-to/cors.md b/guide/content/ja/guide/how-to/cors.md index 8b37caf73d..ce31516505 100644 --- a/guide/content/ja/guide/how-to/cors.md +++ b/guide/content/ja/guide/how-to/cors.md @@ -109,7 +109,7 @@ def setup_options(app: Sanic, _): app.router.finalize() ``` -*** +--- ``` $ curl localhost:9999/ -i @@ -135,4 +135,4 @@ connection: keep-alive また、コミュニティからいくつかのリソースをチェックアウトします。 -- format@@0(https\://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) +- format@@0(https://github.com/mekicha/awesome-sanic/blob/master/README.md#frontend) From e9f82043fab9635476186f895d85410b12e04522 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:29 +0300 Subject: [PATCH 511/698] New translations orm.md (Japanese) --- guide/content/ja/guide/how-to/orm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/orm.md b/guide/content/ja/guide/how-to/orm.md index d8217fa619..d453c21178 100644 --- a/guide/content/ja/guide/how-to/orm.md +++ b/guide/content/ja/guide/how-to/orm.md @@ -15,7 +15,7 @@ Sanicアプリケーションへの統合はかなり簡単です: ## Mayim -Mayimはformat@@0(https\://ahopkins.github.io/mayim/guide/extensions.html#sanic)と一緒に出荷します。 確かに拡張機能なしで Mayim を実行することは可能ですが、すべての format@@0(https\://sanic )を処理するために推奨されています。 ev/ja/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html) +Mayimはformat@@0(https://ahopkins.github.io/mayim/guide/extensions.html#sanic)と一緒に出荷します。 確かに拡張機能なしで Mayim を実行することは可能ですが、すべての format@@0(https://sanic )を処理するために推奨されています。 ev/ja/guide/basics/listeners.html) and [dependency injections](https://sanic.dev/en/plugins/sanic-ext/injection.html) .. 列:: From c575d69a6be018982824c0fb9a5d2b8405b04666 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:31 +0300 Subject: [PATCH 512/698] New translations static-redirects.md (Japanese) --- guide/content/ja/guide/how-to/static-redirects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/static-redirects.md b/guide/content/ja/guide/how-to/static-redirects.md index 0ebb0c9ca6..911784438c 100644 --- a/guide/content/ja/guide/how-to/static-redirects.md +++ b/guide/content/ja/guide/how-to/static-redirects.md @@ -105,7 +105,7 @@ body { ![lake](/assets/images/grottoes.jpg) -*** +--- また、コミュニティからいくつかのリソースをチェックアウトします。 From bb9ab269e9b2254b9c05c412b57bbabefa79a21e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:32 +0300 Subject: [PATCH 513/698] New translations table-of-contents.md (Japanese) --- .../ja/guide/how-to/table-of-contents.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/ja/guide/how-to/table-of-contents.md b/guide/content/ja/guide/how-to/table-of-contents.md index 40573f370a..c530aa4584 100644 --- a/guide/content/ja/guide/how-to/table-of-contents.md +++ b/guide/content/ja/guide/how-to/table-of-contents.md @@ -6,12 +6,12 @@ title: 目次 一般的な質問やユーザーケースに答えるための完全な作業例をまとめました。 ほとんどの部分では、例は可能な限り最小限ですが、完全で実行可能なソリューションである必要があります。 -| ページ | どうすればいいですか... | -| :-------------------------------------------------- | :------------------------------------------------------ | -| format@@0(./mounting.md) | ... アプリケーションをルートの上にあるパスにマウントしますか? | -| [Authentication](./authentication.md) | ... 認証と承認を制御する? | -| [Autodiscovery](./autodiscovery.md) | ... アプリケーションの構築に使用しているコンポーネントを自動的に発見しますか? | -| [CORS](./cors.md) | ... CORS のアプリケーションを設定しますか？ | -| [ORM](./orm) | ... SanicとORMを使用しますか? | -| format@@0(./static-redirects.md) | ... 静的リダイレクトの設定 | -| [TLS/SSL/HTTPS](./tls.md) | ... HTTPS経由でSanicを実行しますか？
... HTTPをHTTPSにリダイレクトしますか? | +| ページ | どうすればいいですか... | +| :------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ | +| format@@0(./mounting.md) | ... アプリケーションをルートの上にあるパスにマウントしますか? | +| [Authentication](./authentication.md) | ... 認証と承認を制御する? | +| [Autodiscovery](./autodiscovery.md) | ... アプリケーションの構築に使用しているコンポーネントを自動的に発見しますか? | +| [CORS](./cors.md) | ... CORS のアプリケーションを設定しますか？ | +| [ORM](./orm) | ... SanicとORMを使用しますか? | +| format@@0(./static-redirects.md) | ... 静的リダイレクトの設定 | +| [TLS/SSL/HTTPS](./tls.md) | ... HTTPS経由でSanicを実行しますか？
... HTTPをHTTPSにリダイレクトしますか? | From c6fe5fbdced08cf52f2992c6e00ba32d7926fcd2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:34 +0300 Subject: [PATCH 514/698] New translations tls.md (Japanese) --- guide/content/ja/guide/how-to/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/how-to/tls.md b/guide/content/ja/guide/how-to/tls.md index 77aa5c1a5b..17bc327aee 100644 --- a/guide/content/ja/guide/how-to/tls.md +++ b/guide/content/ja/guide/how-to/tls.md @@ -188,7 +188,7 @@ async def runner(app, app_server): ## ドメイン名の証明書を取得する -format@@0(https\://letsencrypt.org/)から無料で証明書を取得できます。 パッケージマネージャーから [certbot](https://certbot.eff.org/) をインストールし、証明書を要求します。 +format@@0(https://letsencrypt.org/)から無料で証明書を取得できます。 パッケージマネージャーから [certbot](https://certbot.eff.org/) をインストールし、証明書を要求します。 ```sh sudo certbot certonly --key-type ecdsa --preferred-chain "ISRG Root X1" -d example.com -d www.example.com From d1fa7d34a81e6ad07ea0385de7e98584732c2423 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:36 +0300 Subject: [PATCH 515/698] New translations introduction.md (Japanese) --- guide/content/ja/guide/introduction.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/ja/guide/introduction.md b/guide/content/ja/guide/introduction.md index 1f0282a488..6e867d6d33 100644 --- a/guide/content/ja/guide/introduction.md +++ b/guide/content/ja/guide/introduction.md @@ -58,14 +58,14 @@ Sanic は Python 3.8+ のウェブサーバーであり、高速化のために ## スポンサー情報 -format@@0(https\://opencollective.com/sanic-org) をご覧ください。 +format@@0(https://opencollective.com/sanic-org) をご覧ください。 ## コミュニティに参加する -ディスカッションの主なチャンネルは、format@@0(https\://community.sanicframework.org/)にあります。 ライブディスカッションやチャットのための[Discord Server](https://discord.gg/FARQzAEMAA)もあります。 +ディスカッションの主なチャンネルは、format@@0(https://community.sanicframework.org/)にあります。 ライブディスカッションやチャットのための[Discord Server](https://discord.gg/FARQzAEMAA)もあります。 -Stackoverflow `[sanic]` タグはプロジェクトメンテナーによってformat@@1(https\://stackoverflow\.com/questions/tagged/sanic)です。 +Stackoverflow `[sanic]` タグはプロジェクトメンテナーによってformat@@1(https://stackoverflow.com/questions/tagged/sanic)です。 ## 貢献 -私たちは常に新しい貢献をしています。 We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). format@@0(https\://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst)をご覧ください。 +私たちは常に新しい貢献をしています。 We have [marked issues good for anyone looking to get started](https://github.com/sanic-org/sanic/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner), and welcome [questions/answers/discussion on the forums](https://community.sanicframework.org/). format@@0(https://github.com/sanic-org/sanic/blob/master/CONTRIBUTING.rst)をご覧ください。 From 12892e8392fa47187e342c2365f4dff67ff31ac7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:38 +0300 Subject: [PATCH 516/698] New translations configuration.md (Japanese) --- .../content/ja/guide/running/configuration.md | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/guide/content/ja/guide/running/configuration.md b/guide/content/ja/guide/running/configuration.md index 6258f2361b..d28730a1ab 100644 --- a/guide/content/ja/guide/running/configuration.md +++ b/guide/content/ja/guide/running/configuration.md @@ -242,40 +242,40 @@ app = Sanic(..., config=Config(converters=[UUID])) ## 組み込み値 -| **変数** | **デフォルト** | **説明** | -| ------------------------------------------------------------ | --------------- | -------------------------------------------------------------------------------------------- | -| ACCESS_LOG | True | アクセスログを無効または有効にする | -| 拡張されました。 | True | [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) が既存の仮想環境にある場合にロードされるかどうかを制御する | -| AUTO_RELOAD | True | ファイルが変更されたときにアプリケーションが自動的にリロードされるかどうかを制御します | -| number@@0 自動登録 | True | 存在しない信号で `app.event()` メソッドを使用して `True` を使用すると自動的に作成され、例外は発生しません。 | -| FORMAT | html | 例外がキャッチされて処理されていない場合のエラー応答のフォーマット | -| 前に進みました。 | X-Forwarded-For | クライアントとプロキシIPを含むHTTPヘッダー「X-Forwarded-For」の名前 | -| FORWARDED_SECRET | なし | 特定のプロキシ サーバーを安全に識別するために使用します (下記参照) | -| タイムアウト | 15.0 | アイドル状態でない接続を強制終了するまで待機する時間 (秒) | -| 検査 | False | インスペクタを有効にするかどうか | -| INSPECTOR_HOST | localhost | インスペクタのホスト | -| インポートします。 | 6457 | インスペクターのポート | -| キー | - | インスペクタの TLS キー | -| INSPECTOR_TLS_CERT | * | インスペクタの TLS 証明書 | -| INSPECTOR_API_KEY | - | インスペクタの API キー | -| ALIVE_TIMEOUT | 120 | TCPコネクションを保持する期間 (秒) | -| 保持します。 | True | Falseのときは生き残りを無効にします | -| MOTD | True | 起動時にMOTD (メッセージ) を表示するかどうか | -| MOTD_表示 | {} | MOTD に追加の任意のデータを表示するキー/値のペア | -| NOISY_EXCEPTIONS | False | すべての `quiet` 例外をログに記録する | -| PROXIES_COUNT | なし | アプリの前にあるプロキシサーバーの数（例：nginx、下記参照） | -| REAL_IP_HEADER | なし | 実際のクライアントIPを含むHTTPヘッダーの名前 | -| 登録 | True | アプリレジストリを有効にするかどうか | -| リクエストのBUFF_サイズ | 65536 | リクエストを一時停止する前のリクエストバッファサイズ。デフォルトは64KBです。 | -| リクエストID | X-リクエストID | リクエスト/相関IDを含む "X-Request-ID" HTTP ヘッダーの名前 | -| 最大サイズ | 100000000 | リクエストの大きさ（バイト）は100メガバイトです | -| 要求される最大ヘッダのサイズ | 8192 | リクエストヘッダがどれくらい大きいか(バイト)、デフォルトは8192バイト | -| 要求時間 | 60 | リクエスト到着までにかかる時間 (秒) | -| タイムアウト | 60 | 応答の処理にかかる時間 (秒) | -| UVLoopを使用します。 | True | `uvloop` を使用するループポリシーをオーバーライドします。 `app.run`でのみサポートされています。 | -| 最大サイズ | 2^20 | 受信メッセージの最大サイズ (バイト) | -| Ping_INTERVAL | 20 | Pingフレームは、ping_interval 秒ごとに送信されます。 | -| ping_timeout | 20 | ping_timeout 秒後に Pong が受信されなかった場合、接続は切断されます | +| **変数** | **デフォルト** | **説明** | +| ------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------- | +| ACCESS_LOG | True | アクセスログを無効または有効にする | +| 拡張されました。 | True | [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) が既存の仮想環境にある場合にロードされるかどうかを制御する | +| AUTO_RELOAD | True | ファイルが変更されたときにアプリケーションが自動的にリロードされるかどうかを制御します | +| number@@0 自動登録 | True | 存在しない信号で `app.event()` メソッドを使用して `True` を使用すると自動的に作成され、例外は発生しません。 | +| FORMAT | html | 例外がキャッチされて処理されていない場合のエラー応答のフォーマット | +| 前に進みました。 | X-Forwarded-For | クライアントとプロキシIPを含むHTTPヘッダー「X-Forwarded-For」の名前 | +| FORWARDED_SECRET | なし | 特定のプロキシ サーバーを安全に識別するために使用します (下記参照) | +| タイムアウト | 15.0 | アイドル状態でない接続を強制終了するまで待機する時間 (秒) | +| 検査 | False | インスペクタを有効にするかどうか | +| INSPECTOR_HOST | localhost | インスペクタのホスト | +| インポートします。 | 6457 | インスペクターのポート | +| キー | - | インスペクタの TLS キー | +| INSPECTOR_TLS_CERT | * | インスペクタの TLS 証明書 | +| INSPECTOR_API_KEY | - | インスペクタの API キー | +| ALIVE_TIMEOUT | 120 | TCPコネクションを保持する期間 (秒) | +| 保持します。 | True | Falseのときは生き残りを無効にします | +| MOTD | True | 起動時にMOTD (メッセージ) を表示するかどうか | +| MOTD_表示 | {} | MOTD に追加の任意のデータを表示するキー/値のペア | +| NOISY_EXCEPTIONS | False | すべての `quiet` 例外をログに記録する | +| PROXIES_COUNT | なし | アプリの前にあるプロキシサーバーの数（例：nginx、下記参照） | +| REAL_IP_HEADER | なし | 実際のクライアントIPを含むHTTPヘッダーの名前 | +| 登録 | True | アプリレジストリを有効にするかどうか | +| リクエストのBUFF_サイズ | 65536 | リクエストを一時停止する前のリクエストバッファサイズ。デフォルトは64KBです。 | +| リクエストID | X-リクエストID | リクエスト/相関IDを含む "X-Request-ID" HTTP ヘッダーの名前 | +| 最大サイズ | 100000000 | リクエストの大きさ（バイト）は100メガバイトです | +| 要求される最大ヘッダのサイズ | 8192 | リクエストヘッダがどれくらい大きいか(バイト)、デフォルトは8192バイト | +| 要求時間 | 60 | リクエスト到着までにかかる時間 (秒) | +| タイムアウト | 60 | 応答の処理にかかる時間 (秒) | +| UVLoopを使用します。 | True | `uvloop` を使用するループポリシーをオーバーライドします。 `app.run`でのみサポートされています。 | +| 最大サイズ | 2^20 | 受信メッセージの最大サイズ (バイト) | +| Ping_INTERVAL | 20 | Pingフレームは、ping_interval 秒ごとに送信されます。 | +| ping_timeout | 20 | ping_timeout 秒後に Pong が受信されなかった場合、接続は切断されます | .. tip:: FYI From 9eac79e218b19fbe1d5d25f6e2d70d64f17606aa Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:41 +0300 Subject: [PATCH 517/698] New translations manager.md (Japanese) --- guide/content/ja/guide/running/manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/running/manager.md b/guide/content/ja/guide/running/manager.md index 3b284c4f73..606ce8ed38 100644 --- a/guide/content/ja/guide/running/manager.md +++ b/guide/content/ja/guide/running/manager.md @@ -564,7 +564,7 @@ Sanicが何をしようとしているのかを説明する前に、`start_metho `fork` と `forkserver` メソッドは Unix システムでのみ使用でき、`spawn` は Windows で利用できる唯一のメソッドです。 選択肢がある Unix システムでは、`fork` は一般的にデフォルトのシステムメソッドです。 -これらのメソッドの違いについては、format@@0(https\://docs.python.org/3/library/multiprocessing.html#context-and-start-methods)を参照してください。 ただし、重要なことは、基本的に親プロセスのメモリ全体を子プロセスにコピーすることです。 `spawn` は新しいプロセスを作成し、そのプロセスにアプリケーションをロードします。 CLIを使っていない場合は、`__name__ == "__main__"`ブロックの中に、Sanic `run` を入れ子にする必要があります。 +これらのメソッドの違いについては、format@@0(https://docs.python.org/3/library/multiprocessing.html#context-and-start-methods)を参照してください。 ただし、重要なことは、基本的に親プロセスのメモリ全体を子プロセスにコピーすることです。 `spawn` は新しいプロセスを作成し、そのプロセスにアプリケーションをロードします。 CLIを使っていない場合は、`__name__ == "__main__"`ブロックの中に、Sanic `run` を入れ子にする必要があります。 ### サニックメソッドと開始方法 From a88fd14e09c71ed512124575bb58fcfbeb4baa30 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:43 +0300 Subject: [PATCH 518/698] New translations running.md (Japanese) --- guide/content/ja/guide/running/running.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/guide/running/running.md b/guide/content/ja/guide/running/running.md index 6f8a923b6f..c977fa52f4 100644 --- a/guide/content/ja/guide/running/running.md +++ b/guide/content/ja/guide/running/running.md @@ -322,7 +322,7 @@ elif __name__ == "__main__": | **sock** | `なし` | サーバーが接続を受け入れるソケット。 | | **works** | `1` | spawn するワーカープロセスの数。 高速では使用できません。 | | **ループ** | `なし` | 非同期互換イベントループ。 何も指定されていない場合、Sanic は独自のイベントループを作成します。 | -| **protocol** | `HttpProtocol` | asyncio.protocolのサブクラス。 | +| **protocol** | `HttpProtocol` | asyncio.protocolのサブクラス。 | | **バージョン** | `HTTP.VERSION_1` | 使用する HTTP バージョン (`HTTP.VERSION_1` または `HTTP.VERSION_3` )。 | | **access_log** | `True` | リクエスト処理時にログを有効にします（サーバーが大幅に遅くなります）。 | | **auto_reload** | `なし` | ソースディレクトリの自動リロードを有効にします。 | @@ -524,7 +524,7 @@ hypercorn myapp:app ASGIを使用する場合、いくつか注意すべきことがあります: 1. Sanic ウェブサーバを使用する場合、websocketsは`websockets`パッケージを使用して実行されます。 ASGI モードでは、ウェブソケットは ASGI サーバで管理されるため、このパッケージは必要ありません。 -2. ASGIの寿命プロトコル https\://asgi.readthedocs.io/en/latest/specs/lifespan.htmlは、起動とシャットダウンの2つのサーバーイベントのみをサポートしています。 Sanicは、起動前、起動後、シャットダウン前、シャットダウン後の4つを持っています。 したがって、ASGIモードで 起動イベントとシャットダウンイベントは連続して実行され、実際にはサーバープロセスの開始と終了の周りには実行されません(それ以降はASGIサーバーによって制御されます)。 ですから、`after_server_start` と `before_server_stop` を使うのがベストです。 +2. ASGIの寿命プロトコル https://asgi.readthedocs.io/en/latest/specs/lifespan.htmlは、起動とシャットダウンの2つのサーバーイベントのみをサポートしています。 Sanicは、起動前、起動後、シャットダウン前、シャットダウン後の4つを持っています。 したがって、ASGIモードで 起動イベントとシャットダウンイベントは連続して実行され、実際にはサーバープロセスの開始と終了の周りには実行されません(それ以降はASGIサーバーによって制御されます)。 ですから、`after_server_start` と `before_server_stop` を使うのがベストです。 ### トリオ From 8b4c7177ff6724d4dcc6a1149aed0f9f9e12a400 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:44 +0300 Subject: [PATCH 519/698] New translations help.md (Japanese) --- guide/content/ja/help.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/help.md b/guide/content/ja/help.md index e0df6041f1..8c4e475210 100644 --- a/guide/content/ja/help.md +++ b/guide/content/ja/help.md @@ -27,6 +27,6 @@ Best place to turn for quick answers and live chat `Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) ``` -*** +--- [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic)の`[sanic]`タグも積極的に監視しています。 From 3646b68c6121da02eae0f9e4deb034282505c7b6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:46 +0300 Subject: [PATCH 520/698] New translations code-of-conduct.md (Japanese) --- guide/content/ja/organization/code-of-conduct.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guide/content/ja/organization/code-of-conduct.md b/guide/content/ja/organization/code-of-conduct.md index fdd48a1b88..e07d63d85c 100644 --- a/guide/content/ja/organization/code-of-conduct.md +++ b/guide/content/ja/organization/code-of-conduct.md @@ -52,7 +52,7 @@ further defined and clarified by project maintainers. ## Enforcement -adam\@sanicframework.org のプロジェクト チームに連絡することで、虐待、嫌がらせ、またはその他の受け入れられない行動のインスタンスが +adam@sanicframework.org のプロジェクト チームに連絡することで、虐待、嫌がらせ、またはその他の受け入れられない行動のインスタンスが 報告される可能性があります。 のすべての苦情は審査され調査され、 が状況に対して必要かつ適切であると判断される対応となります。 The project team is @@ -68,5 +68,4 @@ obligated to maintain confidentiality with regard to the reporter of an incident で利用できる [Contributor Covenant][version] から適用されます。 [homepage]: http://contributor-covenant.org - [version]: http://contributor-covenant.org/version/1/4/ From c5789629fb31e805c66e5f77f54f1b382f5dde19 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:47 +0300 Subject: [PATCH 521/698] New translations contributing.md (Japanese) --- guide/content/ja/organization/contributing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/organization/contributing.md b/guide/content/ja/organization/contributing.md index 089082832c..2ec7dce872 100644 --- a/guide/content/ja/organization/contributing.md +++ b/guide/content/ja/organization/contributing.md @@ -2,7 +2,7 @@ ご興味をお持ちいただきありがとうございます! Sanicは常に貢献者を探しています。 貢献するコードが不快であれば、ソース・ファイルにdocstringを追加したり、[Sanic User Guide](https://github) を手伝ってください。 om/sanic-org/sanic-guide: ドキュメントまたは実装例を提供することにより、当然のことです! -我々は,性別,性的指向,障害,民族性,宗教その他の個人的特性にかかわらず,すべての人に友好的で安全で歓迎的な環境を提供することにコミットしている。 format@@0(https\://github.com/sanic-org/sanic/blob/master/CONDUCT.md) は行動の標準を設定します。 +我々は,性別,性的指向,障害,民族性,宗教その他の個人的特性にかかわらず,すべての人に友好的で安全で歓迎的な環境を提供することにコミットしている。 format@@0(https://github.com/sanic-org/sanic/blob/master/CONDUCT.md) は行動の標準を設定します。 ## インストール @@ -142,7 +142,7 @@ Sanicはコードの一貫性を維持するために、以下のツールを使 きれいにする ``` -詳細については、format@@0(https\://tox.readthedocs.io/en/latest/index.html)を参照してください。 +詳細については、format@@0(https://tox.readthedocs.io/en/latest/index.html)を参照してください。 ## プルリクエスト @@ -154,7 +154,7 @@ Sanicはコードの一貫性を維持するために、以下のツールを使 4. すべてのプルリクエストは `isort` と `black` 要件に一致する必要があります。 5. 免除が与えられない限り、全てのプルリクエストは **PROPERLY** 型に注釈を付ける必要があります。 6. すべてのプルリクエストは、既存のコードと一致している必要があります。 -7. 任意の一般的なインターフェイスから何かを削除/変更することにした場合、非推奨メッセージは format@@0(https\://sanicframework.org/ja/guide/project/polices.html#deprecation )に従って同行する必要があります。 +7. 任意の一般的なインターフェイスから何かを削除/変更することにした場合、非推奨メッセージは format@@0(https://sanicframework.org/ja/guide/project/polices.html#deprecation )に従って同行する必要があります。 8. 新しい機能を実装する場合は、少なくとも1つの単位テストが必要です。 9. 例は次のいずれかでなければなりません: - Sanicの使い方の例 From 63c787ce5183712772ca4c826cbdc85957001459 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:48 +0300 Subject: [PATCH 522/698] New translations policies.md (Japanese) --- guide/content/ja/organization/policies.md | 50 +++++++++++------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/guide/content/ja/organization/policies.md b/guide/content/ja/organization/policies.md index 1c6d3283c4..72a278009e 100644 --- a/guide/content/ja/organization/policies.md +++ b/guide/content/ja/organization/policies.md @@ -2,7 +2,7 @@ ## Versioning -Sanic は format@@0(https\://calver.org/), "calver" を使用しています。 具体的には、パターンは次のとおりです。 +Sanic は format@@0(https://calver.org/), "calver" を使用しています。 具体的には、パターンは次のとおりです。 ``` YY.MM.MICRO @@ -12,9 +12,9 @@ YY.MM.MICRO ## 脆弱性の報告 -セキュリティ上の脆弱性が発見された場合は、GitHub で問題を **作成しない** ようお願いします。 代わりに、コミュニティフォーラムで format@@0(https\://community.sanicframework.org/g/core-devs) を参照してください。 ログインすると、メッセージボタンをクリックしてコア開発者にメッセージを送信できます。 +セキュリティ上の脆弱性が発見された場合は、GitHub で問題を **作成しない** ようお願いします。 代わりに、コミュニティフォーラムで format@@0(https://community.sanicframework.org/g/core-devs) を参照してください。 ログインすると、メッセージボタンをクリックしてコア開発者にメッセージを送信できます。 -あるいは、Adam Hopkins の Discordにプライベートメッセージを送信することもできます。 format@@0(https\://discord.gg/FARQzAEMAA) で彼を見つけてください。 +あるいは、Adam Hopkins の Discordにプライベートメッセージを送信することもできます。 format@@0(https://discord.gg/FARQzAEMAA) で彼を見つけてください。 これは、チームが問題に対処して解決するまで問題を公表しないようにするのに役立ちます。 @@ -35,28 +35,28 @@ YY.MM.MICRO Sanicは12月に年に一度長期サポートリリース(別名「LTS」)をリリースしています。 LTSリリースでは、**24ヶ月**のバグ修正とセキュリティアップデートを受け取ります。 年間を通じた中間リリースは3ヶ月ごとに行われ、その後のリリースまでサポートされています。 -| バージョン | リリース | LTS | サポート | -| ----- | ---------- | ------------ | ---- | -| 23.12 | 2023-12-31 | 2025年から12年まで | ✅ | -| 23.6 | 2023-07-25 | | ⚪ | -| 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | 2024年～12年まで | ☑️ | -| 22.9 | 2022-09-29 | | ⚪ | -| 22.6 | 2022-06-30 | | ⚪ | -| 22.3 | 2022-03-31 | | ⚪ | -| 21.12 | 2021-12-26 | | ⚪ | -| 21.9 | 2021-09-30 | | ⚪ | -| 21.6 | 2021-06-27 | | ⚪ | -| 21.3 | 2021-03-21 | | ⚪ | -| 20.12 | 2020-12-29 | | ⚪ | -| 20.9 | 2020-09-30 | | ⚪ | -| 20.6 | 2020-06-28 | | ⚪ | -| 20.3 | 2020-05-14 | | ⚪ | -| 19.12 | 2019-12-27 | | ⚪ | -| 19.9 | 2019-10-12 | | ⚪ | -| 19.6 | 2019-06-21 | | ⚪ | -| 19.3 | 2019-03-23 | | ⚪ | -| 18.12 | 2018-12-27 | | ⚪ | +| バージョン | リリース | LTS | サポート | +| ------------------------------------- | ---------- | ------------ | ---- | +| 23.12 | 2023-12-31 | 2025年から12年まで | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | 2024年～12年まで | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | | 0.8.3 | 2018-09-13 | | ⚪ | | 0.7.0 | 2017-12-06 | | ⚪ | | 0.6.0 | 2017-08-03 | | ⚪ | From 04722776de5fce602b41137a3affb818709e6eff Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:32:55 +0300 Subject: [PATCH 523/698] New translations injection.md (Japanese) --- guide/content/ja/plugins/sanic-ext/injection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/injection.md b/guide/content/ja/plugins/sanic-ext/injection.md index 6387f575fb..62c0b2a8b1 100644 --- a/guide/content/ja/plugins/sanic-ext/injection.md +++ b/guide/content/ja/plugins/sanic-ext/injection.md @@ -320,7 +320,7 @@ result ## 一般的なタイプ -format@@0(https\://docs.python.org/3/library/typing.html#typing.Generic)を使用するときは、気をつけてください。 Sanicの依存性注入が機能する方法は、型の定義全体に一致することです。 したがって、`Foo` は `Foo[str] ` と同じではありません。 型が推測されるので、format@@0(#the-higher-level-api-using-dependency) を使用しようとすると、これは特に難しいことがあります。 +format@@0(https://docs.python.org/3/library/typing.html#typing.Generic)を使用するときは、気をつけてください。 Sanicの依存性注入が機能する方法は、型の定義全体に一致することです。 したがって、`Foo` は `Foo[str] ` と同じではありません。 型が推測されるので、format@@0(#the-higher-level-api-using-dependency) を使用しようとすると、これは特に難しいことがあります。 .. 列:: From 8f2400a5351025943e4dcea29aa0df3e0a382758 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:02 +0300 Subject: [PATCH 524/698] New translations decorators.md (Japanese) --- guide/content/ja/plugins/sanic-ext/openapi/decorators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/openapi/decorators.md b/guide/content/ja/plugins/sanic-ext/openapi/decorators.md index 9d7d893619..daaf85adb2 100644 --- a/guide/content/ja/plugins/sanic-ext/openapi/decorators.md +++ b/guide/content/ja/plugins/sanic-ext/openapi/decorators.md @@ -470,7 +470,7 @@ openapi.exclude(bp=some_blueprint) ## Pydanticとの統合 -Pydanticモデルはformat@@0(https\://pydantic-docs.helpmanual.io/usage/schema/)を生成する機能を持っています。 +Pydanticモデルはformat@@0(https://pydantic-docs.helpmanual.io/usage/schema/)を生成する機能を持っています。 .. 列:: From 2a95d8dd8083b44dec2763ad58823f7df812ac83 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:05 +0300 Subject: [PATCH 525/698] New translations jinja.md (Japanese) --- guide/content/ja/plugins/sanic-ext/templating/jinja.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/templating/jinja.md b/guide/content/ja/plugins/sanic-ext/templating/jinja.md index a02c38b884..df307b8608 100644 --- a/guide/content/ja/plugins/sanic-ext/templating/jinja.md +++ b/guide/content/ja/plugins/sanic-ext/templating/jinja.md @@ -10,7 +10,7 @@ Sanic Extensions は、テンプレートをルートハンドラに簡単に統 **現在、 [Jinja](https://github.com/pallets/jinja/)のみサポートしています。** -format@@0(https\://jinja.palletsprojects.com/en/3.1.x/) テンプレートを作成する方法に慣れていない場合は、format@@1を参照してください。 +format@@0(https://jinja.palletsprojects.com/en/3.1.x/) テンプレートを作成する方法に慣れていない場合は、format@@1を参照してください。 Sanic Extensionsは、環境にインストールされている場合、自動的にJinjaをセットアップしてロードします。 したがって、必要なセットアップはJinjaのインストールだけです。 From 4b1376a647bf7562d3f472597f125360491b7c6e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:06 +0300 Subject: [PATCH 526/698] New translations validation.md (Japanese) --- guide/content/ja/plugins/sanic-ext/validation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/validation.md b/guide/content/ja/plugins/sanic-ext/validation.md index 87cb2e2a50..54c8e82904 100644 --- a/guide/content/ja/plugins/sanic-ext/validation.md +++ b/guide/content/ja/plugins/sanic-ext/validation.md @@ -10,7 +10,7 @@ Webアプリケーションの最も一般的に実装されている機能の1 ### Dataclassの検証 -format@@0(https\://docs.python.org/3/library/dataclasses.html)の導入により、Pythonは定義されたスキーマを満たすオブジェクトを簡単に作成できました。 しかし、標準ライブラリは型チェック検証のみをサポートしており、実行時の検証ではありません。 Sanic Extensionsは、 `dataclasses`を使って受信するリクエストに対して実行時の検証を行う機能を追加します。 `pydantic`または`attrs`のいずれかがインストールされている場合は、それらのライブラリのいずれかを使用することもできます。 +format@@0(https://docs.python.org/3/library/dataclasses.html)の導入により、Pythonは定義されたスキーマを満たすオブジェクトを簡単に作成できました。 しかし、標準ライブラリは型チェック検証のみをサポートしており、実行時の検証ではありません。 Sanic Extensionsは、 `dataclasses`を使って受信するリクエストに対して実行時の検証を行う機能を追加します。 `pydantic`または`attrs`のいずれかがインストールされている場合は、それらのライブラリのいずれかを使用することもできます。 .. 列:: From bda4ea14271e53d2243f468b96e14f13e9d29fba Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:09 +0300 Subject: [PATCH 527/698] New translations v21.12.md (Japanese) --- guide/content/ja/release-notes/2021/v21.12.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.12.md b/guide/content/ja/release-notes/2021/v21.12.md index 829e05b5a0..17bb2ee99a 100644 --- a/guide/content/ja/release-notes/2021/v21.12.md +++ b/guide/content/ja/release-notes/2021/v21.12.md @@ -526,6 +526,6 @@ Sanicについての本は、コア開発者の一人[@ahopkins](https://github. そして、[@miss85246](https://github.com/miss85246)と[@ZinkLu](https://github.com/ZinkLu)に感謝します。 -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From a6d084200649052e1da8b8de21e676195db2a6f6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:10 +0300 Subject: [PATCH 528/698] New translations v21.3.md (Japanese) --- guide/content/ja/release-notes/2021/v21.3.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.3.md b/guide/content/ja/release-notes/2021/v21.3.md index 5a41716a33..77cb2353b8 100644 --- a/guide/content/ja/release-notes/2021/v21.3.md +++ b/guide/content/ja/release-notes/2021/v21.3.md @@ -43,7 +43,7 @@ format@@0(../advanced/streaming.md#response-streaming) についてもっと読 ### ルーターのオーバーホール -古いSanicルータは正規表現に基づいていました。 また、実行時に変更が困難になった癖も多数あり、パフォーマンス上の問題も生じた。 この変更は長年にわたって行われており、format@@0(https\://community.sanicframework.org/t/a-fast-new-router/649/41) でルーターをコンパイルしました。 年間を通して追加の改善を探してください。 +古いSanicルータは正規表現に基づいていました。 また、実行時に変更が困難になった癖も多数あり、パフォーマンス上の問題も生じた。 この変更は長年にわたって行われており、format@@0(https://community.sanicframework.org/t/a-fast-new-router/649/41) でルーターをコンパイルしました。 年間を通して追加の改善を探してください。 外向きのAPIは後方互換性を保っています。 ただし、ルーター内の何かにアクセスしている場合は、いくつかの変更に気づくことがあります。 例: @@ -53,13 +53,13 @@ format@@0(../advanced/streaming.md#response-streaming) についてもっと読 4. ルートにマッチする新しい``パターンがあります 5. 少なくとも 1 つのルートが定義されていないアプリケーションを起動することはできません。 -ルーターは以下のリポジトリにあります: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router)。format@@0(https\://pypi.org/project/sanic-routing/) +ルーターは以下のリポジトリにあります: [sanic-org/sanic-router](https://github.com/sanic-org/sanic-router)。format@@0(https://pypi.org/project/sanic-routing/) ### Signals API ⭐️ _BETA 機能: v21.6_ で確定する API -新しいルータの利点として、format@@0(https\://github.com/sanic-org/sanic/issues/1630)にも電力を供給できることが挙げられます。 この機能は現在一般向けにリリースされており、パブリックAPIは最終的な形で変更されない可能性があります。 +新しいルータの利点として、format@@0(https://github.com/sanic-org/sanic/issues/1630)にも電力を供給できることが挙げられます。 この機能は現在一般向けにリリースされており、パブリックAPIは最終的な形で変更されない可能性があります。 この機能の中核的なアイデアは次のとおりです。 @@ -181,13 +181,13 @@ def convert_to_snake_case(request): ### `testing`ライブラリを削除しました -Sanic 社内テスト クライアントは削除されました。 これは [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) と、それ自身のformat@@0(https\://pypi.org/project/sanic-testing/)にあります。 +Sanic 社内テスト クライアントは削除されました。 これは [sanic-org/sanic-testing](https://github.com/sanic-org/sanic-testing) と、それ自身のformat@@0(https://pypi.org/project/sanic-testing/)にあります。 `sanic-testing`がインストールされている場合は、以前のように`Sanic()`アプリケーション・インスタンスで利用可能になります。 ですから、**のみ**変更する必要があるのは、テストスイートの要件に`sanic-testing`を追加することです。 ### アプリケーションと接続レベルのコンテキスト (`ctx`) オブジェクト -Version 19.9 format@@0(https\://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API この便利な構文により、リクエストオブジェクトにプロパティやデータを簡単にアタッチすることができます(例えば、 ミドルウェアで)、他の場所でアプリケーション情報を再利用します。 +Version 19.9 format@@0(https://github.com/sanic-org/sanic/pull/1666/files) the `request.ctx` API この便利な構文により、リクエストオブジェクトにプロパティやデータを簡単にアタッチすることができます(例えば、 ミドルウェアで)、他の場所でアプリケーション情報を再利用します。 同様に、この概念は2つの場所で拡張されています: @@ -249,11 +249,11 @@ request.conn_info.ctx.foo=3 ### チャットはDiscordに移動しました -Gitterのチャットルームは段階的に廃止されることに一歩近づいた。 その場所でformat@@0(https\://discord.gg/FARQzAEMAA)を開きました。 +Gitterのチャットルームは段階的に廃止されることに一歩近づいた。 その場所でformat@@0(https://discord.gg/FARQzAEMAA)を開きました。 ### Open Collective -Sanic Community Organization は format@@0(https\://opencollective.com/sanic-org) を開き、Sanic の開発を経済的にサポートしたい人を対象にしています。 +Sanic Community Organization は format@@0(https://opencollective.com/sanic-org) を開き、Sanic の開発を経済的にサポートしたい人を対象にしています。 ### 2021 Release Manager @@ -267,6 +267,6 @@ Sanic Community Organization は format@@0(https\://opencollective.com/sanic-org To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) を中国語に翻訳する -*** +--- すべてのPRへのリンクなどを取得するには、チェンジログをチェックしてください。 From 9809ab13229ad126028a36bd160ffc3f58e695f7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:11 +0300 Subject: [PATCH 529/698] New translations v21.6.md (Japanese) --- guide/content/ja/release-notes/2021/v21.6.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.6.md b/guide/content/ja/release-notes/2021/v21.6.md index fa31c59f6d..071fa30188 100644 --- a/guide/content/ja/release-notes/2021/v21.6.md +++ b/guide/content/ja/release-notes/2021/v21.6.md @@ -38,11 +38,11 @@ async def handler(request, foo: str, bar: float): ### バージョン0.7ルーターのアップグレード -これには数多くのバグ修正が含まれており、v0.6 よりも広範囲のエッジケースをより優雅に処理します。 サポートされていないパターンがあれば、format@@0(https\://github.com/sanic-org/sanic-routing/issues) を報告してください。 `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases) で解決されたいくつかの問題を見ることができます。 +これには数多くのバグ修正が含まれており、v0.6 よりも広範囲のエッジケースをより優雅に処理します。 サポートされていないパターンがあれば、format@@0(https://github.com/sanic-org/sanic-routing/issues) を報告してください。 `sanic-routing` [release notes](https://github.com/sanic-org/sanic-routing/releases) で解決されたいくつかの問題を見ることができます。 ### `eof()`でインラインストリーミング -バージョン21.3にはformat@@0(https\://sanic.dev/ja/guide/release-notes/v21.3.html#what-to-know)が含まれています。 導入されたパターンがデフォルトになります (下記参照)。 便宜上、新しい `response.eof()` メソッドが含まれています。 最終的なデータがクライアントにプッシュされると呼び出されます。 +バージョン21.3にはformat@@0(https://sanic.dev/ja/guide/release-notes/v21.3.html#what-to-know)が含まれています。 導入されたパターンがデフォルトになります (下記参照)。 便宜上、新しい `response.eof()` メソッドが含まれています。 最終的なデータがクライアントにプッシュされると呼び出されます。 ```python @app.route("/") @@ -305,7 +305,7 @@ class DummyView(HTTPMethodView, attach=Sanic.get_app(), uri="/"): ### Discordとサポートフォーラム -まだコミュニティに参加していない場合は、[Discord server](https://discord.gg/FARQzAEMAA)とformat@@0(https\://community.sanicframework.org/)に参加してください。 また、Twitterで[@sanicframework](https://twitter.com/sanicframework)をフォローしてください。 +まだコミュニティに参加していない場合は、[Discord server](https://discord.gg/FARQzAEMAA)とformat@@0(https://community.sanicframework.org/)に参加してください。 また、Twitterで[@sanicframework](https://twitter.com/sanicframework)をフォローしてください。 ### SCO2022の投票 @@ -347,6 +347,6 @@ SCO傘に新しいプロジェクトを追加しました: [`sanic-ext`](https:/ [@vltr](https://github.com/vltr) [@ZinkLu](https://github.com/zinklu) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From 2d6bc1a370a2cc6ef18f5fa964cc2852261974da Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:13 +0300 Subject: [PATCH 530/698] New translations v21.9.md (Japanese) --- guide/content/ja/release-notes/2021/v21.9.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/release-notes/2021/v21.9.md b/guide/content/ja/release-notes/2021/v21.9.md index 37a6161764..d84cf34020 100644 --- a/guide/content/ja/release-notes/2021/v21.9.md +++ b/guide/content/ja/release-notes/2021/v21.9.md @@ -235,6 +235,6 @@ v21.9のリリースから、SCOは`sanic-openapi`パッケージを非推奨に そして、[@miss85246](https://github.com/miss85246)と[@ZinkLu](https://github.com/ZinkLu)に感謝します。 -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From 1bef179150bb24be4851c7448117a688fae37192 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:14 +0300 Subject: [PATCH 531/698] New translations v22.12.md (Japanese) --- guide/content/ja/release-notes/2022/v22.12.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.12.md b/guide/content/ja/release-notes/2022/v22.12.md index b66e49a84e..6ffe0a1e6c 100644 --- a/guide/content/ja/release-notes/2022/v22.12.md +++ b/guide/content/ja/release-notes/2022/v22.12.md @@ -185,6 +185,6 @@ Sanicにもっと関心がある場合は、[Discordサーバー](https://discor [@todddialpad](https://github.com/todddialpad) [@Tronic](https://github.com/Tronic) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From d912959ef2c0bfd330d27c0b717683dfd9997c0a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:15 +0300 Subject: [PATCH 532/698] New translations v22.3.md (Japanese) --- guide/content/ja/release-notes/2022/v22.3.md | 22 ++++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.3.md b/guide/content/ja/release-notes/2022/v22.3.md index b692ee53ba..08cda60b29 100644 --- a/guide/content/ja/release-notes/2022/v22.3.md +++ b/guide/content/ja/release-notes/2022/v22.3.md @@ -61,14 +61,14 @@ async def handler(request, filename, ext): いくつかの潜在的な例: -| 定義 | 例 | ファイル名 | 拡張 | -| ---------------------------------- | ----------- | -------- | ---------- | -| \ | page.txt | `"page"` | `"txt"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| 定義 | 例 | ファイル名 | 拡張 | +| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | +| \file:ext | page.txt | `"page"` | `"txt"` | +| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | +| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | ### 🚨 _BREAKING CHANGE_ - パスパラメータの空でない文字列の一致 @@ -86,7 +86,7 @@ async def handler(request, foo) 通常の非推奨ポリシーから離れて、Sanic サーバーをマルチサーブにアップグレードするプロセスの一部として `GunicornWorker` が削除されました。 この決定は、存在している間にも、Sanicを展開するための最適な戦略ではなかったため、主に部分的に行われました。 -`gunicorn`を使用してSanicをデプロイしたい場合は、format@@0(https\://www\.uvicorn.org/#running-with-gunicorn)を使用して実行することをお勧めします。 これにより、SanicはASGIアプリケーションとして`uvicorn`を通じて効果的に実行されます。 `uvicorn`をインストールすると、このパターンにアップグレードできます。 +`gunicorn`を使用してSanicをデプロイしたい場合は、format@@0(https://www.uvicorn.org/#running-with-gunicorn)を使用して実行することをお勧めします。 これにより、SanicはASGIアプリケーションとして`uvicorn`を通じて効果的に実行されます。 `uvicorn`をインストールすると、このパターンにアップグレードできます。 ``` pip install uvicorn @@ -225,6 +225,6 @@ Sanicは接頭辞付きの環境変数を設定値として読み込みます。 [@SerGeRybakov](https://github.com/SerGeRybakov) [@Tronic](https://github.com/Tronic) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From cec6dbe6e78eb078d146f97e31c93e57f09d2f32 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:16 +0300 Subject: [PATCH 533/698] New translations v22.6.md (Japanese) --- guide/content/ja/release-notes/2022/v22.6.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.6.md b/guide/content/ja/release-notes/2022/v22.6.md index a5e418f394..1315a0a52b 100644 --- a/guide/content/ja/release-notes/2022/v22.6.md +++ b/guide/content/ja/release-notes/2022/v22.6.md @@ -34,11 +34,11 @@ app.run(debug=True, auto_tls=True) ``` ```` -この機能は `ASGI` モードまたは `PRODUCTION` モードで実行している場合は使用できません。 Sanic を本番環境で実行する場合、正規のベンダー経由で購入した実際の TLS 証明書を使用するか、format@@0(https\://letsencrypt.org/) を使用する必要があります。 +この機能は `ASGI` モードまたは `PRODUCTION` モードで実行している場合は使用できません。 Sanic を本番環境で実行する場合、正規のベンダー経由で購入した実際の TLS 証明書を使用するか、format@@0(https://letsencrypt.org/) を使用する必要があります。 ### HTTP/3 Server 🚀 -2022 年6 月に、IETF は、HTTP/3 の仕様である [RFC 9114](https://www.rfc-editor.org/rfc/rfc91114.html) を最終決定し公開しました。 要するに、HTTP/3 は HTTP/1.1 や HTTP/2 とは異なるプロトコルです。なぜなら、TCPの代わりにUDP経由でHTTPを実装するからです。 新しいHTTPプロトコルは、Webページの読み込み時間を短縮し、古い標準のいくつかの問題を解決します。 format@@0(https\://http3-explained.haxx.se/) の新しいウェブテクノロジーを使うことをお勧めします。 従来のツールは動作しないため、format@@0(https\://curl.se/docs/http3.html)をインストールする必要があります。 +2022 年6 月に、IETF は、HTTP/3 の仕様である [RFC 9114](https://www.rfc-editor.org/rfc/rfc91114.html) を最終決定し公開しました。 要するに、HTTP/3 は HTTP/1.1 や HTTP/2 とは異なるプロトコルです。なぜなら、TCPの代わりにUDP経由でHTTPを実装するからです。 新しいHTTPプロトコルは、Webページの読み込み時間を短縮し、古い標準のいくつかの問題を解決します。 format@@0(https://http3-explained.haxx.se/) の新しいウェブテクノロジーを使うことをお勧めします。 従来のツールは動作しないため、format@@0(https://curl.se/docs/http3.html)をインストールする必要があります。 Sanic server provides HTTP/3 support using [aioquic](https://github.com/aiortc/aioquic). **インストールする必要があります** @@ -168,6 +168,6 @@ app = Sanic("Test", loads=loads) [@timmo001](https://github.com/timmo001) [@zozzz](https://github.com/zozzz) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From c8e6664c6d9dbc42573ed7f5502ed8c3dc3f4df9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:17 +0300 Subject: [PATCH 534/698] New translations v22.9.md (Japanese) --- guide/content/ja/release-notes/2022/v22.9.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.9.md b/guide/content/ja/release-notes/2022/v22.9.md index e6497e051c..33dc1c97bf 100644 --- a/guide/content/ja/release-notes/2022/v22.9.md +++ b/guide/content/ja/release-notes/2022/v22.9.md @@ -254,7 +254,7 @@ async def high_priority(_): ### カスタムの `loads` 関数 -Sanicはアプリのインスタンス化時にformat@@0(https\://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic)を追加する機能をサポートしています。 同じ機能が `loads` に拡張され、デシリアライズ時に使用されます。 +Sanicはアプリのインスタンス化時にformat@@0(https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic)を追加する機能をサポートしています。 同じ機能が `loads` に拡張され、デシリアライズ時に使用されます。 ```python from json import load @@ -344,6 +344,6 @@ app.config.DEPRECEATION_FILTER = "ignore" [@timgates42](https://github.com/timgates42) [@Tronic](https://github.com/Tronic) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From 6bf0e0ca2484e9e99658559187b46722b43160bf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:19 +0300 Subject: [PATCH 535/698] New translations v23.12.md (Japanese) --- guide/content/ja/release-notes/2023/v23.12.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/release-notes/2023/v23.12.md b/guide/content/ja/release-notes/2023/v23.12.md index 7a08b57a0d..46b93ab6ef 100644 --- a/guide/content/ja/release-notes/2023/v23.12.md +++ b/guide/content/ja/release-notes/2023/v23.12.md @@ -180,6 +180,6 @@ async def after_reload_trigger(_, changed): [@tjni](https://github.com/tjni) [@Tronic](https://github.com/Tronic) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From 649eb16409cfd42610a52b6f70d9d00f7d884477 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:20 +0300 Subject: [PATCH 536/698] New translations v23.3.md (Japanese) --- guide/content/ja/release-notes/2023/v23.3.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guide/content/ja/release-notes/2023/v23.3.md b/guide/content/ja/release-notes/2023/v23.3.md index b0e65eefeb..fcdd5619a5 100644 --- a/guide/content/ja/release-notes/2023/v23.3.md +++ b/guide/content/ja/release-notes/2023/v23.3.md @@ -224,7 +224,7 @@ request.cookies.foo request.cookies.getlist("foo") ``` -format@@0(https\://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie)の作成もサポートされています。 +format@@0(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#partitioned_cookie)の作成もサポートされています。 ```py response.cookies.add_cookie(..., partitioned=True) @@ -232,7 +232,7 @@ response.cookies.add_cookie(..., partitioned=True) ### 🚨 _BREAKING CHANGE_ - より強力な `SanicException` -Sanicは基本クラスの例外として`SanicException`をしばらく含んでいます。 これは `status_code` などを追加するために拡張できます。format@@0(http\://localhost:8080/ja/guide/best-practics/exceptions.html) +Sanicは基本クラスの例外として`SanicException`をしばらく含んでいます。 これは `status_code` などを追加するために拡張できます。format@@0(http://localhost:8080/ja/guide/best-practics/exceptions.html) **今です**、様々な例外をすべて使うのが簡単になりました。 一般的に使用される例外は、ルートレベルモジュールから直接インポートできます。 @@ -257,7 +257,7 @@ raise ServerError(headers={"foo": "bar"}) これの部分は、以前は位置引数がキーワードのみであるということです。 -format@@0(https\://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions)にある各エラーの実装を確認することをお勧めします。 +format@@0(https://sanic.readthedocs.io/en/stable/sanic/api/exceptions.html#module-sanic.exceptions)にある各エラーの実装を確認することをお勧めします。 ### 🚨 _BREAKING 変更_ - `Request.accept` 機能をよりパフォーマンスと仕様準拠に更新します。 @@ -325,7 +325,7 @@ app = Sanic(..., certloader_class=MyCertLoader) バージョン22.9では、Sanicはv23.3がルートを重複した名前で登録できるようにすることを発表しました。 次のエラーが表示された場合は、その変更によるものです。 -> sanic.exceptions.ServerError: ルート名が重複しています: SomeApp.some_handler。 `name` パラメータを使用することで、名前を変更する必要があります。 クラスと関数名から派生した暗黙的な名前を変更することもできます。 詳細は https\://sanic.dev/ja/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed を参照してください。 +> sanic.exceptions.ServerError: ルート名が重複しています: SomeApp.some_handler。 `name` パラメータを使用することで、名前を変更する必要があります。 クラスと関数名から派生した暗黙的な名前を変更することもできます。 詳細は https://sanic.dev/ja/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed を参照してください。 これを見ている場合は、ルートに明示的な名前を使用することをオプトインする必要があります。 @@ -416,6 +416,6 @@ assert request.cookies.getlist("foo") == ["bar"] [@Tracyca209](https://github.com/Tracyca209) [@Tronic](https://github.com/Tronic) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From 60cfbf39ec33f646a6c8e5e55eba2cd3493f996b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:21 +0300 Subject: [PATCH 537/698] New translations v23.6.md (Japanese) --- guide/content/ja/release-notes/2023/v23.6.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/release-notes/2023/v23.6.md b/guide/content/ja/release-notes/2023/v23.6.md index f32744f8e1..152329d4ba 100644 --- a/guide/content/ja/release-notes/2023/v23.6.md +++ b/guide/content/ja/release-notes/2023/v23.6.md @@ -194,6 +194,6 @@ async def main_process_start(app): [@Thirumalai](https://github.com/Thirumalai) [@Tronic](https://github.com/Tronic) -*** +--- -あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https\://opencollective.com/sanic-org/) +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From a12f1c98bf168e4a46cd2ce4965dd51e82e0d63f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:28 +0300 Subject: [PATCH 538/698] New translations changelog.md (Japanese) --- guide/content/ja/release-notes/changelog.md | 26 ++++++++++----------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/guide/content/ja/release-notes/changelog.md b/guide/content/ja/release-notes/changelog.md index bde23a6d5a..9f45248076 100644 --- a/guide/content/ja/release-notes/changelog.md +++ b/guide/content/ja/release-notes/changelog.md @@ -256,7 +256,7 @@ _当時の状況により、v.23.9はスキップされました。 _ - `request.is_safe` - `request.is_idempotent` - `request.is_cacheable` - - _参照_ format@@0(https\://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _これらが適用される時の詳細_ + - _参照_ format@@0(https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) _これらが適用される時の詳細_ - [#2522](https://github.com/sanic-org/sanic/pull/2522) ASGIに常にサーバーの場所を表示する - [#2526](https://github.com/sanic-org/sanic/pull/2526) 適切な場合に304を返すための静的ファイルのキャッシュ管理のサポート - [#2533](https://github.com/sanic-org/sanic/pull/2533) リファクタリング`_static_request_handler` @@ -351,7 +351,7 @@ _当時の状況により、v.23.9はスキップされました。 _ ### 特徴 - [#2347](https://github.com/sanic-org/sanic/pull/2347) マルチアプリケーション・サーバー用 API - - 🚨 _BREAKING CHANGE_: 古い `sanic.worker.GunicornWorker` が \*\*削除されました。 Sanic を `gunicorn` で実行するには、`uvicorn` format@@0(https\://www\.uvicorn.org/#running-with-gunicorn) で実行する必要があります。 + - 🚨 _BREAKING CHANGE_: 古い `sanic.worker.GunicornWorker` が \*\*削除されました。 Sanic を `gunicorn` で実行するには、`uvicorn` format@@0(https://www.uvicorn.org/#running-with-gunicorn) で実行する必要があります。 - 🧁 _SIDE EFFECT_: 名前付きバックグラウンドタスクがPython 3.7 でもサポートされるようになりました - [#2357](https://github.com/sanic-org/sanic/pull/2357) `Request.credentials` として `Authorization` ヘッダーを解析 - [#2361](https://github.com/sanic-org/sanic/pull/2361) 設定オプションを追加して、アプリケーションの起動時に`Touchup`ステップをスキップします @@ -453,7 +453,7 @@ _当時の状況により、v.23.9はスキップされました。 _ - `sanic.exceptions.abort` - `sanic.views.CompositionView` - `sanic.response.StreamingHTTPResponse` - - _注意:_ `stream()` レスポンスメソッド (呼び出し可能なストリーミング関数を渡す) は廃止され、v22.6 で削除されます。 新しいスタイルのすべてのストリーミング応答をアップグレードする必要があります: https\://sanicframework.org/ja/guide/advanced/streaming.html#response-stream + - _注意:_ `stream()` レスポンスメソッド (呼び出し可能なストリーミング関数を渡す) は廃止され、v22.6 で削除されます。 新しいスタイルのすべてのストリーミング応答をアップグレードする必要があります: https://sanicframework.org/ja/guide/advanced/streaming.html#response-stream - [#2320](https://github.com/sanic-org/sanic/pull/2320) Configからエラーハンドラ設定用アプリインスタンスを削除します ### 開発者のインフラストラクチャ @@ -792,7 +792,7 @@ Notes 名が存在しない\"静的\"ルートに`url_for`で\"name\" キーワードを使用する ``` - 名前付きの param を使用せずに複数の `app.static()` を持つことはできません -- ファイルルート上で`url_for`の"filename" キーワードを使用する +- ファイルルート上で`url_for`の\"filename\" キーワードを使用する - ルートデフの`unquote` (自動ではありません) - `routes_all`はタプルです - ハンドラの引数はkwargのみです @@ -983,7 +983,7 @@ Notes - [#1776](https://github.com/sanic-org/sanic/pull/1776) ホストパラメータのリストに関するバグ修正 - [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static - _handler pickling error + \_handler pickling error - [#1827](https://github.com/sanic-org/sanic/pull/1827) OSX py38 と Windows のリローダー を修正 - [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse @@ -1005,7 +1005,7 @@ Notes - [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust websockets version to setup.py - [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap - run()の"protocol" 型アノテーションオプション[] + run()の\"protocol\" 型アノテーションオプション\[\] **ドキュメントの改善** @@ -1322,7 +1322,7 @@ December 2020, and therefore passing Python\'s official support version - [#1477](https://github.com/sanic-org/sanic/pull/1477) README.md で文法 を修正 - [#1489](https://github.com/sanic-org/sanic/pull/1489) Added - "databases" to the extensions list + \"databases\" to the extensions list - [#1483](https://github.com/sanic-org/sanic/pull/1483) 拡張リストに sanic-zipkinを追加する - [#1487](https://github.com/sanic-org/sanic/pull/1487) @@ -1385,9 +1385,9 @@ PyPI ではリリースされません。 - Windowsや他のプラットフォームでコンテンツの長さが一致しない問題を修正 - 固定ファイルの範囲ヘッダーの処理を修正 (#1402) - ロガーを修正して動作させます(#1397) - - マルチプロセッシングテストでpikcle->pickle型を修正 + - マルチプロセッシングテストでpikcle-\>pickle型を修正 - ブループリント内の名前付きタプルの - "name" セクションで渡された文字列をブループリントモジュール属性名の + \"name\" セクションで渡された文字列をブループリントモジュール属性名の 名に合わせて変更します。 This allows blueprints to be pickled and unpickled, without errors, which is a requirement of running Sanic in multiprocessing mode in @@ -1403,7 +1403,7 @@ PyPI ではリリースされません。 **0.8.3** - 変更点: - - 所有権を組織に変更しました 'sanic-org' + - 所有権を組織に変更しました \'sanic-org\' **0.8.0** @@ -1443,7 +1443,7 @@ PyPI ではリリースされません。 - ドキュメントの更新/修正 (複数の投稿者) - 修正: - 修正: Linux で auto_reload (Ashley Sommer) - - 修正:aiohttp >= 3.3.0 (Ashley Sommer) + - 修正:aiohttp \>= 3.3.0 (Ashley Sommer) - 修正: windows ではデフォルトで auto_reload を無効にする (abuckenheimer) - 修正 (1143): gunicorn (hqy) でアクセスログをオフにする - Fix (1268): ファイル応答のステータスコードをサポート (Cosmo Borsky) @@ -1455,13 +1455,13 @@ PyPI ではリリースされません。 - 修正 (1231): メモリリーク - 常にリソースをリリース (フィリップXu) - Fix (1221): トランスポートが存在する場合はリクエストを真にする (Raphael Deem) - - aiohttp>=3.1.0（Ashley Sommer）のテストに失敗する問題を修正 + - aiohttp\>=3.1.0（Ashley Sommer）のテストに失敗する問題を修正 - try_everything の例を修正 (PyManiacGR, kot83) - Fix (1158): デバッグモードで auto_reload がデフォルト(Raphel Deem) - Fix (11136): ErrorHandler.response ハンドラの呼び出しが制限されています (Julien Castiaux) - 修正: raw requires bytes-like object (cloudship) - - Fix (1120): passing a list in to a route decorator's host arg + - Fix (1120): passing a list in to a route decorator\'s host arg (Timothy Ebiuwhe) - 修正: マルチパート/フォームデータパーサのバグ(DirkGuijt) - Fix: Exception for missing parameter when value is null From 06dabf774d3f1bd7dd5d2de98c2c7d8378028a71 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:31 +0300 Subject: [PATCH 539/698] New translations proxy-headers.md (Korean) --- .../ko/guide/advanced/proxy-headers.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/guide/content/ko/guide/advanced/proxy-headers.md b/guide/content/ko/guide/advanced/proxy-headers.md index ff151b592b..ab38575482 100644 --- a/guide/content/ko/guide/advanced/proxy-headers.md +++ b/guide/content/ko/guide/advanced/proxy-headers.md @@ -78,7 +78,7 @@ async def forwarded(request): ) ``` -*** +--- ##### Example 1 @@ -121,7 +121,7 @@ app.config.REAL_IP_HEADER = "x-real-ip" ``` ```` -*** +--- ##### Example 2 @@ -168,7 +168,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 3 @@ -211,7 +211,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 4 @@ -249,7 +249,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 5 @@ -289,7 +289,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 6 @@ -330,7 +330,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 7 @@ -371,7 +371,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 8 @@ -411,7 +411,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 9 @@ -451,7 +451,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 10 @@ -491,7 +491,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 11 @@ -534,7 +534,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### Example 12 From e82993d6c1ab420c1c2e284cae7e8078e37427a9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:37 +0300 Subject: [PATCH 540/698] New translations handlers.md (Korean) --- guide/content/ko/guide/basics/handlers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ko/guide/basics/handlers.md b/guide/content/ko/guide/basics/handlers.md index dd9e98b21b..90a73ec7a9 100644 --- a/guide/content/ko/guide/basics/handlers.md +++ b/guide/content/ko/guide/basics/handlers.md @@ -69,7 +69,7 @@ async def foo_handler(request): ``` ```` -*** +--- ## A word about _async_... @@ -140,7 +140,7 @@ Instead, try using a client that is `async/await` capable. Your server will than Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package (sanic-testing) 😉. ``` -*** +--- ## A fully annotated handler From 24d61c164f6c41fab925f029c82644c06b5c42c6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:42 +0300 Subject: [PATCH 541/698] New translations routing.md (Korean) --- guide/content/ko/guide/basics/routing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/ko/guide/basics/routing.md b/guide/content/ko/guide/basics/routing.md index 243b8a0e9a..d36c6653b9 100644 --- a/guide/content/ko/guide/basics/routing.md +++ b/guide/content/ko/guide/basics/routing.md @@ -469,14 +469,14 @@ async def handler(request, foo: str, ext: str): ``` ```` -| definition | example | filename | extension | -| ---------------------------------- | ----------- | -------- | ---------- | -| \ | page.txt | `"page"` | `"txt"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| definition | example | filename | extension | +| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | +| \file:ext | page.txt | `"page"` | `"txt"` | +| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | +| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | File extensions can be matched using the special `ext` parameter type. It uses a special format that allows you to specify other types of parameter types as the file name, and one or more specific extensions as shown in the example table above. From 69d0502c2004adcd0a950bd0fc369593ca0a9ada Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:51 +0300 Subject: [PATCH 542/698] New translations authentication.md (Korean) --- guide/content/ko/guide/how-to/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/how-to/authentication.md b/guide/content/ko/guide/how-to/authentication.md index 28e1bc29ad..9b107b4a9b 100644 --- a/guide/content/ko/guide/how-to/authentication.md +++ b/guide/content/ko/guide/how-to/authentication.md @@ -76,7 +76,7 @@ def protected(wrapped): This decorator pattern is taken from the [decorators page](/en/guide/best-practices/decorators.md). -*** +--- ```bash $ curl localhost:9999/secret -i From 2bfc16f82e0249b7b125d95c41b5d9abda05cc43 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:52 +0300 Subject: [PATCH 543/698] New translations autodiscovery.md (Korean) --- guide/content/ko/guide/how-to/autodiscovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/how-to/autodiscovery.md b/guide/content/ko/guide/how-to/autodiscovery.md index 90cda60083..ab590c4881 100644 --- a/guide/content/ko/guide/how-to/autodiscovery.md +++ b/guide/content/ko/guide/how-to/autodiscovery.md @@ -158,7 +158,7 @@ def print_something(app, loop): logger.debug("something @ nested") ``` -*** +--- ```text here is the dir tree From da469f5146c35ae6f5994cd654f111e0219e66ed Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:53 +0300 Subject: [PATCH 544/698] New translations cors.md (Korean) --- guide/content/ko/guide/how-to/cors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/how-to/cors.md b/guide/content/ko/guide/how-to/cors.md index 250b0aea74..53d4ebe3c3 100644 --- a/guide/content/ko/guide/how-to/cors.md +++ b/guide/content/ko/guide/how-to/cors.md @@ -109,7 +109,7 @@ def setup_options(app: Sanic, _): app.router.finalize() ``` -*** +--- ``` $ curl localhost:9999/ -i From 5fe60b7bf35c1a9eb0efc5bce840147769a3c3c5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:33:58 +0300 Subject: [PATCH 545/698] New translations static-redirects.md (Korean) --- guide/content/ko/guide/how-to/static-redirects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/how-to/static-redirects.md b/guide/content/ko/guide/how-to/static-redirects.md index 0fb99202bf..d177756bfc 100644 --- a/guide/content/ko/guide/how-to/static-redirects.md +++ b/guide/content/ko/guide/how-to/static-redirects.md @@ -105,7 +105,7 @@ body { ![lake](/assets/images/grottoes.jpg) -*** +--- Also, checkout some resources from the community: From b5a5328bf9173ebae4a3ac4a2856aec64af0b569 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:02 +0300 Subject: [PATCH 546/698] New translations table-of-contents.md (Korean) --- .../ko/guide/how-to/table-of-contents.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/ko/guide/how-to/table-of-contents.md b/guide/content/ko/guide/how-to/table-of-contents.md index af8da93a77..d2aeba0461 100644 --- a/guide/content/ko/guide/how-to/table-of-contents.md +++ b/guide/content/ko/guide/how-to/table-of-contents.md @@ -6,12 +6,12 @@ title: Table of Contents We have compiled fully working examples to answer common questions and user cases. For the most part, the examples are as minimal as possible, but should be complete and runnable solutions. -| Page | How do I ... | -| :------------------------------------------ | :------------------------------------------------------------------ | -| [Application mounting](./mounting.md) | ... mount my application at some path above the root? | -| [Authentication](./authentication.md) | ... control authentication and authorization? | -| [Autodiscovery](./autodiscovery.md) | ... autodiscover the components I am using to build my application? | -| [CORS](./cors.md) | ... configure my application for CORS? | -| [ORM](./orm) | ... use an ORM with Sanic? | -| ["Static" Redirects](./static-redirects.md) | ... configure static redirects | -| [TLS/SSL/HTTPS](./tls.md) | ... run Sanic via HTTPS?
... redirect HTTP to HTTPS? | +| Page | How do I ... | +| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Application mounting](./mounting.md) | ... mount my application at some path above the root? | +| [Authentication](./authentication.md) | ... control authentication and authorization? | +| [Autodiscovery](./autodiscovery.md) | ... autodiscover the components I am using to build my application? | +| [CORS](./cors.md) | ... configure my application for CORS? | +| [ORM](./orm) | ... use an ORM with Sanic? | +| ["Static" Redirects](./static-redirects.md) | ... configure static redirects | +| [TLS/SSL/HTTPS](./tls.md) | ... run Sanic via HTTPS?
... redirect HTTP to HTTPS? | From 4a436396843a11ecb978a140e04f4cd1b0155c01 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:08 +0300 Subject: [PATCH 547/698] New translations configuration.md (Korean) --- .../content/ko/guide/running/configuration.md | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/guide/content/ko/guide/running/configuration.md b/guide/content/ko/guide/running/configuration.md index 89dacd7f7a..5b6bd45745 100644 --- a/guide/content/ko/guide/running/configuration.md +++ b/guide/content/ko/guide/running/configuration.md @@ -242,40 +242,40 @@ app = Sanic(..., config=Config(converters=[UUID])) ## Builtin values -| **Variable** | **Default** | **Description** | -| -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| ACCESS_LOG | True | Disable or enable access log | -| AUTO_EXTEND | True | Control whether [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) will load if it is in the existing virtual environment | -| AUTO_RELOAD | True | Control whether the application will automatically reload when a file changes | -| EVENT_AUTOREGISTER | True | When `True` using the `app.event()` method on a non-existing signal will automatically create it and not raise an exception | -| FALLBACK_ERROR_FORMAT | html | Format of error response if an exception is not caught and handled | -| FORWARDED_FOR_HEADER | X-Forwarded-For | The name of "X-Forwarded-For" HTTP header that contains client and proxy ip | -| FORWARDED_SECRET | None | Used to securely identify a specific proxy server (see below) | -| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | How long to wait to force close non-idle connection (sec) | -| INSPECTOR | False | Whether to enable the Inspector | -| INSPECTOR_HOST | localhost | The host for the Inspector | -| INSPECTOR_PORT | 6457 | The port for the Inspector | -| INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | -| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | -| INSPECTOR_API_KEY | - | The API key for the Inspector | -| KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | -| KEEP_ALIVE | True | Disables keep-alive when False | -| MOTD | True | Whether to display the MOTD (message of the day) at startup | -| MOTD_DISPLAY | {} | Key/value pairs to display additional, arbitrary data in the MOTD | -| NOISY_EXCEPTIONS | False | Force all `quiet` exceptions to be logged | -| PROXIES_COUNT | None | The number of proxy servers in front of the app (e.g. nginx; see below) | -| REAL_IP_HEADER | None | The name of "X-Real-IP" HTTP header that contains real client ip | -| REGISTER | True | Whether the app registry should be enabled | -| REQUEST_BUFFER_SIZE | 65536 | Request buffer size before request is paused, default is 64 Kib | -| REQUEST_ID_HEADER | X-Request-ID | The name of "X-Request-ID" HTTP header that contains request/correlation ID | -| REQUEST_MAX_SIZE | 100000000 | How big a request may be (bytes), default is 100 megabytes | -| REQUEST_MAX_HEADER_SIZE | 8192 | How big a request header may be (bytes), default is 8192 bytes | -| REQUEST_TIMEOUT | 60 | How long a request can take to arrive (sec) | -| RESPONSE_TIMEOUT | 60 | How long a response can take to process (sec) | -| USE_UVLOOP | True | Whether to override the loop policy to use `uvloop`. Supported only with `app.run`. | -| WEBSOCKET_MAX_SIZE | 2^20 | Maximum size for incoming messages (bytes) | -| WEBSOCKET_PING_INTERVAL | 20 | A Ping frame is sent every ping_interval seconds. | -| WEBSOCKET_PING_TIMEOUT | 20 | Connection is closed when Pong is not received after ping_timeout seconds | +| **Variable** | **Default** | **Description** | +| -------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| ACCESS_LOG | True | Disable or enable access log | +| AUTO_EXTEND | True | Control whether [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) will load if it is in the existing virtual environment | +| AUTO_RELOAD | True | Control whether the application will automatically reload when a file changes | +| EVENT_AUTOREGISTER | True | When `True` using the `app.event()` method on a non-existing signal will automatically create it and not raise an exception | +| FALLBACK_ERROR_FORMAT | html | Format of error response if an exception is not caught and handled | +| FORWARDED_FOR_HEADER | X-Forwarded-For | The name of "X-Forwarded-For" HTTP header that contains client and proxy ip | +| FORWARDED_SECRET | None | Used to securely identify a specific proxy server (see below) | +| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | How long to wait to force close non-idle connection (sec) | +| INSPECTOR | False | Whether to enable the Inspector | +| INSPECTOR_HOST | localhost | The host for the Inspector | +| INSPECTOR_PORT | 6457 | The port for the Inspector | +| INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | +| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | +| INSPECTOR_API_KEY | - | The API key for the Inspector | +| KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | +| KEEP_ALIVE | True | Disables keep-alive when False | +| MOTD | True | Whether to display the MOTD (message of the day) at startup | +| MOTD_DISPLAY | {} | Key/value pairs to display additional, arbitrary data in the MOTD | +| NOISY_EXCEPTIONS | False | Force all `quiet` exceptions to be logged | +| PROXIES_COUNT | None | The number of proxy servers in front of the app (e.g. nginx; see below) | +| REAL_IP_HEADER | None | The name of "X-Real-IP" HTTP header that contains real client ip | +| REGISTER | True | Whether the app registry should be enabled | +| REQUEST_BUFFER_SIZE | 65536 | Request buffer size before request is paused, default is 64 Kib | +| REQUEST_ID_HEADER | X-Request-ID | The name of "X-Request-ID" HTTP header that contains request/correlation ID | +| REQUEST_MAX_SIZE | 100000000 | How big a request may be (bytes), default is 100 megabytes | +| REQUEST_MAX_HEADER_SIZE | 8192 | How big a request header may be (bytes), default is 8192 bytes | +| REQUEST_TIMEOUT | 60 | How long a request can take to arrive (sec) | +| RESPONSE_TIMEOUT | 60 | How long a response can take to process (sec) | +| USE_UVLOOP | True | Whether to override the loop policy to use `uvloop`. Supported only with `app.run`. | +| WEBSOCKET_MAX_SIZE | 2^20 | Maximum size for incoming messages (bytes) | +| WEBSOCKET_PING_INTERVAL | 20 | A Ping frame is sent every ping_interval seconds. | +| WEBSOCKET_PING_TIMEOUT | 20 | Connection is closed when Pong is not received after ping_timeout seconds | .. tip:: FYI From d0bbbbf9a0a0c822aeaa4d825743c00b3ea32272 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:10 +0300 Subject: [PATCH 548/698] New translations inspector.md (Korean) --- guide/content/ko/guide/running/inspector.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/content/ko/guide/running/inspector.md b/guide/content/ko/guide/running/inspector.md index c8310877d9..2c6bb1d1a8 100644 --- a/guide/content/ko/guide/running/inspector.md +++ b/guide/content/ko/guide/running/inspector.md @@ -81,11 +81,11 @@ Remember, the Inspector is not running on your Sanic application. It is a sepera The Inspector comes with the following built-in commands. -| CLI Command | HTTP Action | Description | -| ------------------ | ---------------------------------- | ------------------------------------------------------------------------ | -| `inspect` | `GET /` | Display basic details about the running application. | -| `inspect reload` | `POST /reload` | Trigger a reload of all server workers. | -| `inspect shutdown` | `POST /shutdown` | Trigger a shutdown of all processes. | +| CLI Command | HTTP Action | Description | +| ------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `inspect` | `GET /` | Display basic details about the running application. | +| `inspect reload` | `POST /reload` | Trigger a reload of all server workers. | +| `inspect shutdown` | `POST /shutdown` | Trigger a shutdown of all processes. | | `inspect scale N` | `POST /scale`
`{"replicas": N}` | Scale the number of workers. Where `N` is the target number of replicas. | ## Custom Commands From c29095f9fdf5a665f2641cfc66701e45b402293a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:13 +0300 Subject: [PATCH 549/698] New translations running.md (Korean) --- guide/content/ko/guide/running/running.md | 34 +++++++++++------------ 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/guide/content/ko/guide/running/running.md b/guide/content/ko/guide/running/running.md index 4be2300da5..aafc297c8f 100644 --- a/guide/content/ko/guide/running/running.md +++ b/guide/content/ko/guide/running/running.md @@ -311,29 +311,29 @@ elif __name__ == "__main__": To use the low-level `run` API, after defining an instance of `sanic.Sanic`, we can call the run method with the following keyword arguments: -| Parameter | Default | Description | -| :---------------------------------------: | :--------------: | :---------------------------------------------------------------------------------------- | -| **host** | `"127.0.0.1"` | Address to host the server on. | -| **port** | `8000` | Port to host the server on. | -| **unix** | `None` | Unix socket name to host the server on (instead of TCP). | -| **dev** | `False` | Equivalent to `debug=True` and `auto_reload=True`. | -| **debug** | `False` | Enables debug output (slows server). | -| **ssl** | `None` | SSLContext for SSL encryption of worker(s). | -| **sock** | `None` | Socket for the server to accept connections from. | +| Parameter | Default | Description | +| :---------------------------------------: | :--------------: | :------------------------------------------------------------------------------------------------------------------------ | +| **host** | `"127.0.0.1"` | Address to host the server on. | +| **port** | `8000` | Port to host the server on. | +| **unix** | `None` | Unix socket name to host the server on (instead of TCP). | +| **dev** | `False` | Equivalent to `debug=True` and `auto_reload=True`. | +| **debug** | `False` | Enables debug output (slows server). | +| **ssl** | `None` | SSLContext for SSL encryption of worker(s). | +| **sock** | `None` | Socket for the server to accept connections from. | | **workers** | `1` | Number of worker processes to spawn. Cannot be used with fast. | | **loop** | `None` | An asyncio-compatible event loop. If none is specified, Sanic creates its own event loop. | | **protocol** | `HttpProtocol` | Subclass of asyncio.protocol. | -| **version** | `HTTP.VERSION_1` | The HTTP version to use (`HTTP.VERSION_1` or `HTTP.VERSION_3`). | -| **access_log** | `True` | Enables log on handling requests (significantly slows server). | -| **auto_reload** | `None` | Enables auto-reload on the source directory. | -| **reload_dir** | `None` | A path or list of paths to directories the auto-reloader should watch. | +| **version** | `HTTP.VERSION_1` | The HTTP version to use (`HTTP.VERSION_1` or `HTTP.VERSION_3`). | +| **access_log** | `True` | Enables log on handling requests (significantly slows server). | +| **auto_reload** | `None` | Enables auto-reload on the source directory. | +| **reload_dir** | `None` | A path or list of paths to directories the auto-reloader should watch. | | **noisy_exceptions** | `None` | Whether to set noisy exceptions globally. None means leave as default. | -| **motd** | `True` | Whether to display the startup message. | -| **motd_display** | `None` | A dict with extra key/value information to display in the startup message | +| **motd** | `True` | Whether to display the startup message. | +| **motd_display** | `None` | A dict with extra key/value information to display in the startup message | | **fast** | `False` | Whether to maximize worker processes. Cannot be used with workers. | | **verbosity** | `0` | Level of logging detail. Max is 2. | | **auto_tls** | `False` | Whether to auto-create a TLS certificate for local development. Not for production. | -| **single_process** | `False` | Whether to run Sanic in a single process. | +| **single_process** | `False` | Whether to run Sanic in a single process. | .. column:: @@ -524,7 +524,7 @@ hypercorn myapp:app A couple things to note when using ASGI: 1. When using the Sanic webserver, websockets will run using the `websockets` package. In ASGI mode, there is no need for this package since websockets are managed in the ASGI server. -2. The ASGI lifespan protocol https\://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. +2. The ASGI lifespan protocol https://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. ### Trio From 675c67bf721f4dc44d7dfd6e2ccdff44441d1ea3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:14 +0300 Subject: [PATCH 550/698] New translations help.md (Korean) --- guide/content/ko/help.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/help.md b/guide/content/ko/help.md index f84355e054..91880e2861 100644 --- a/guide/content/ko/help.md +++ b/guide/content/ko/help.md @@ -27,6 +27,6 @@ Good for sharing snippets of code and longer support queries `Questions and Help` category on the [Forums](https://community.sanicframework.org/c/questions-and-help/6) ``` -*** +--- We also actively monitor the `[sanic]` tag on [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic). From 7e81dd5b66d62501787821db9670ebcb22ba3e59 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:15 +0300 Subject: [PATCH 551/698] New translations code-of-conduct.md (Korean) --- guide/content/ko/organization/code-of-conduct.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guide/content/ko/organization/code-of-conduct.md b/guide/content/ko/organization/code-of-conduct.md index 84f0f12d5f..905c7cdda8 100644 --- a/guide/content/ko/organization/code-of-conduct.md +++ b/guide/content/ko/organization/code-of-conduct.md @@ -55,7 +55,7 @@ further defined and clarified by project maintainers. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at adam\@sanicframework.org. All +reported by contacting the project team at adam@sanicframework.org. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. @@ -71,5 +71,4 @@ This Code of Conduct is adapted from the [Contributor Covenant][homepage], versi available at [http://contributor-covenant.org/version/1/4][version] [homepage]: http://contributor-covenant.org - [version]: http://contributor-covenant.org/version/1/4/ From 62e0e23458dfa401cc275b704f21a31ed8725cbf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:17 +0300 Subject: [PATCH 552/698] New translations policies.md (Korean) --- guide/content/ko/organization/policies.md | 62 +++++++++++------------ 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/guide/content/ko/organization/policies.md b/guide/content/ko/organization/policies.md index 5870095910..e581dfdf8c 100644 --- a/guide/content/ko/organization/policies.md +++ b/guide/content/ko/organization/policies.md @@ -35,37 +35,37 @@ We also use the yearly release cycle in conjunction with our governance model, c Sanic releases a long term support release (aka "LTS") once a year in December. The LTS releases receive bug fixes and security updates for **24 months**. Interim releases throughout the year occur every three months, and are supported until the subsequent release. -| Version | Release | LTS | Supported | -| ------- | ---------- | ------------- | --------- | -| 23.12 | 2023-12-31 | until 2025-12 | ✅ | -| 23.6 | 2023-07-25 | | ⚪ | -| 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | -| 22.9 | 2022-09-29 | | ⚪ | -| 22.6 | 2022-06-30 | | ⚪ | -| 22.3 | 2022-03-31 | | ⚪ | -| 21.12 | 2021-12-26 | | ⚪ | -| 21.9 | 2021-09-30 | | ⚪ | -| 21.6 | 2021-06-27 | | ⚪ | -| 21.3 | 2021-03-21 | | ⚪ | -| 20.12 | 2020-12-29 | | ⚪ | -| 20.9 | 2020-09-30 | | ⚪ | -| 20.6 | 2020-06-28 | | ⚪ | -| 20.3 | 2020-05-14 | | ⚪ | -| 19.12 | 2019-12-27 | | ⚪ | -| 19.9 | 2019-10-12 | | ⚪ | -| 19.6 | 2019-06-21 | | ⚪ | -| 19.3 | 2019-03-23 | | ⚪ | -| 18.12 | 2018-12-27 | | ⚪ | -| 0.8.3 | 2018-09-13 | | ⚪ | -| 0.7.0 | 2017-12-06 | | ⚪ | -| 0.6.0 | 2017-08-03 | | ⚪ | -| 0.5.4 | 2017-05-09 | | ⚪ | -| 0.4.1 | 2017-02-28 | | ⚪ | -| 0.3.1 | 2017-02-09 | | ⚪ | -| 0.2.0 | 2017-01-14 | | ⚪ | -| 0.1.9 | 2016-12-25 | | ⚪ | -| 0.1.0 | 2016-10-16 | | ⚪ | +| Version | Release | LTS | Supported | +| ------------------------------------- | ---------- | ------------- | --------- | +| 23.12 | 2023-12-31 | until 2025-12 | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | +| 0.8.3 | 2018-09-13 | | ⚪ | +| 0.7.0 | 2017-12-06 | | ⚪ | +| 0.6.0 | 2017-08-03 | | ⚪ | +| 0.5.4 | 2017-05-09 | | ⚪ | +| 0.4.1 | 2017-02-28 | | ⚪ | +| 0.3.1 | 2017-02-09 | | ⚪ | +| 0.2.0 | 2017-01-14 | | ⚪ | +| 0.1.9 | 2016-12-25 | | ⚪ | +| 0.1.0 | 2016-10-16 | | ⚪ | ☑️ = security fixes\ ✅ = full support\ From a8fc4242bbb51def5dd063a88afc12581c5e13d8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:23 +0300 Subject: [PATCH 553/698] New translations cors.md (Korean) --- .../content/ko/plugins/sanic-ext/http/cors.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/ko/plugins/sanic-ext/http/cors.md b/guide/content/ko/plugins/sanic-ext/http/cors.md index d5e4f2ba4e..4d12e745aa 100644 --- a/guide/content/ko/plugins/sanic-ext/http/cors.md +++ b/guide/content/ko/plugins/sanic-ext/http/cors.md @@ -49,18 +49,18 @@ connection: keep-alive The true power of CORS protection, however, comes into play once you start configuring it. Here is a table of all of the options. -| Key | Type | Default | Description | -| --------------------------- | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `CORS_ALLOW_HEADERS` | `str` or `List[str]` | `"*"` | The list of headers that will appear in `access-control-allow-headers`. | +| Key | Type | Default | Description | +| --------------------------- | -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `CORS_ALLOW_HEADERS` | `str` or `List[str]` | `"*"` | The list of headers that will appear in `access-control-allow-headers`. | | `CORS_ALWAYS_SEND` | `bool` | `True` | When `True`, will always set a value for `access-control-allow-origin`. When `False`, will only set it if there is an `Origin` header. | | `CORS_AUTOMATIC_OPTIONS` | `bool` | `True` | When the incoming preflight request is received, whether to automatically set values for `access-control-allow-headers`, `access-control-max-age`, and `access-control-allow-methods` headers. If `False` these values will only be set on routes that are decorated with the `@cors` decorator. | -| `CORS_EXPOSE_HEADERS` | `str` or `List[str]` | `""` | Specific list of headers to be set in `access-control-expose-headers` header. | +| `CORS_EXPOSE_HEADERS` | `str` or `List[str]` | `""` | Specific list of headers to be set in `access-control-expose-headers` header. | | `CORS_MAX_AGE` | `str`, `int`, `timedelta` | `0` | The maximum number of seconds the preflight response may be cached using the `access-control-max-age` header. A falsey value will cause the header to not be set. | -| `CORS_METHODS` | `str` or `List[str]` | `""` | The HTTP methods that the allowed origins can access, as set on the `access-control-allow-methods` header. | -| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | The origins that are allowed to access the resource, as set on the `access-control-allow-origin` header. | -| `CORS_SEND_WILDCARD` | `bool` | `False` | If `True`, will send the wildcard `*` origin instead of the `origin` request header. | -| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | Whether to set the `access-control-allow-credentials` header. | -| `CORS_VARY_HEADER` | `bool` | `True` | Whether to add `vary` header, when appropriate. | +| `CORS_METHODS` | `str` or `List[str]` | `""` | The HTTP methods that the allowed origins can access, as set on the `access-control-allow-methods` header. | +| `CORS_ORIGINS` | `str`, `List[str]`, `re.Pattern` | `"*"` | The origins that are allowed to access the resource, as set on the `access-control-allow-origin` header. | +| `CORS_SEND_WILDCARD` | `bool` | `False` | If `True`, will send the wildcard `*` origin instead of the `origin` request header. | +| `CORS_SUPPORTS_CREDENTIALS` | `bool` | `False` | Whether to set the `access-control-allow-credentials` header. | +| `CORS_VARY_HEADER` | `bool` | `True` | Whether to add `vary` header, when appropriate. | _For the sake of brevity, where the above says `List[str]` any instance of a `list`, `set`, `frozenset`, or `tuple` will be acceptable. Alternatively, if the value is a `str`, it can be a comma delimited list._ From a8b805b054def1ba246a25ea6ccdcf8134a37aa8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:26 +0300 Subject: [PATCH 554/698] New translations logger.md (Korean) --- guide/content/ko/plugins/sanic-ext/logger.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ko/plugins/sanic-ext/logger.md b/guide/content/ko/plugins/sanic-ext/logger.md index 0ea5f309b8..cd3ae04b7b 100644 --- a/guide/content/ko/plugins/sanic-ext/logger.md +++ b/guide/content/ko/plugins/sanic-ext/logger.md @@ -32,7 +32,7 @@ When enabled, the extension will create a `multoprocessing.Queue`. It will remov ## Configuration -| Key | Type | Default | Description | -| ------------------------------------------------------------------------------------- | ------ | ------- | ------------------------------------------------------- | +| Key | Type | Default | Description | +| ------------------------------------------------------------------------------------- | ------ | ------- | ----------------------------------------------------------------------- | | LOGGING | `bool` | `False` | Whether to enable this extension. | | LOGGING_QUEUE_MAX_SIZE | `int` | `4096` | The max size of the queue before messages are rejected. | From c6f1b7288b326457e9ad23079d2596ef66e518a2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:31 +0300 Subject: [PATCH 555/698] New translations ui.md (Korean) --- .../ko/plugins/sanic-ext/openapi/ui.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/guide/content/ko/plugins/sanic-ext/openapi/ui.md b/guide/content/ko/plugins/sanic-ext/openapi/ui.md index fd1f4182e6..6e72718396 100644 --- a/guide/content/ko/plugins/sanic-ext/openapi/ui.md +++ b/guide/content/ko/plugins/sanic-ext/openapi/ui.md @@ -14,17 +14,17 @@ Sanic Extensions comes with both Redoc and Swagger interfaces. You have a choice ## Config options -| **Key** | **Type** | **Default** | **Desctiption** | -| -------------------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `OAS_IGNORE_HEAD` | `bool` | `True` | Whether to display `HEAD` endpoints. | -| `OAS_IGNORE_OPTIONS` | `bool` | `True` | Whether to display `OPTIONS` endpoints. | -| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Redoc HTML | -| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Swagger HTML | +| **Key** | **Type** | **Default** | **Desctiption** | +| -------------------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OAS_IGNORE_HEAD` | `bool` | `True` | Whether to display `HEAD` endpoints. | +| `OAS_IGNORE_OPTIONS` | `bool` | `True` | Whether to display `OPTIONS` endpoints. | +| `OAS_PATH_TO_REDOC_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Redoc HTML | +| `OAS_PATH_TO_SWAGGER_HTML` | `Optional[str]` | `None` | Path to HTML to override the default Swagger HTML | | `OAS_UI_DEFAULT` | `Optional[str]` | `"redoc"` | Can be set to `redoc` or `swagger`. Controls which UI to display on the base route. If set to `None`, then the base route will not be setup. | -| `OAS_UI_REDOC` | `bool` | `True` | Whether to enable Redoc UI. | -| `OAS_UI_SWAGGER` | `bool` | `True` | Whether to enable Swagger UI. | -| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | URI path to the OpenAPI config used by Swagger | -| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | URI path to the JSON document. | -| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | URI path to Redoc. | -| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI path to Swagger. | -| `OAS_URL_PREFIX` | `str` | `"/docs"` | URL prefix to use for the Blueprint for OpenAPI docs. | +| `OAS_UI_REDOC` | `bool` | `True` | Whether to enable Redoc UI. | +| `OAS_UI_SWAGGER` | `bool` | `True` | Whether to enable Swagger UI. | +| `OAS_URI_TO_CONFIG` | `str` | `"/openapi-config"` | URI path to the OpenAPI config used by Swagger | +| `OAS_URI_TO_JSON` | `str` | `"/openapi.json"` | URI path to the JSON document. | +| `OAS_URI_TO_REDOC` | `str` | `"/redoc"` | URI path to Redoc. | +| `OAS_URI_TO_SWAGGER` | `str` | `"/swagger"` | URI path to Swagger. | +| `OAS_URL_PREFIX` | `str` | `"/docs"` | URL prefix to use for the Blueprint for OpenAPI docs. | From 114b4697d4257f06f258d598bb4b0d49c93543b7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:36 +0300 Subject: [PATCH 556/698] New translations v21.12.md (Korean) --- guide/content/ko/release-notes/2021/v21.12.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2021/v21.12.md b/guide/content/ko/release-notes/2021/v21.12.md index 2b80536a32..4d5da222a3 100644 --- a/guide/content/ko/release-notes/2021/v21.12.md +++ b/guide/content/ko/release-notes/2021/v21.12.md @@ -526,6 +526,6 @@ Thank you to everyone that participated in this release: :clap: And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From fdb17b33b5b744165050f7d43c9f6e3f9e15376c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:37 +0300 Subject: [PATCH 557/698] New translations v21.3.md (Korean) --- guide/content/ko/release-notes/2021/v21.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2021/v21.3.md b/guide/content/ko/release-notes/2021/v21.3.md index 2539e750b2..e06d93b290 100644 --- a/guide/content/ko/release-notes/2021/v21.3.md +++ b/guide/content/ko/release-notes/2021/v21.3.md @@ -267,6 +267,6 @@ Thank you to everyone that participated in this release: :clap: To [@ConnorZhang](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for translating our documents into Chinese, -*** +--- Make sure to checkout the changelog to get links to all the PRs, etc. From e73afbbc293988968ff0458209495706f1065fbd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:39 +0300 Subject: [PATCH 558/698] New translations v21.6.md (Korean) --- guide/content/ko/release-notes/2021/v21.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2021/v21.6.md b/guide/content/ko/release-notes/2021/v21.6.md index 98453a86f4..f262e68e44 100644 --- a/guide/content/ko/release-notes/2021/v21.6.md +++ b/guide/content/ko/release-notes/2021/v21.6.md @@ -347,6 +347,6 @@ Thank you to everyone that participated in this release: :clap: [@vltr](https://github.com/vltr) [@ZinkLu](https://github.com/zinklu) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From a70c7fbdbdbfb422372e23adea73bff449668d01 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:40 +0300 Subject: [PATCH 559/698] New translations v21.9.md (Korean) --- guide/content/ko/release-notes/2021/v21.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2021/v21.9.md b/guide/content/ko/release-notes/2021/v21.9.md index 8b3b8149de..7b53c52f6b 100644 --- a/guide/content/ko/release-notes/2021/v21.9.md +++ b/guide/content/ko/release-notes/2021/v21.9.md @@ -235,6 +235,6 @@ Thank you to everyone that participated in this release: :clap: And, a special thank you to [@miss85246](https://github.com/miss85246) and [@ZinkLu](https://github.com/ZinkLu) for their tremendous work keeping the documentation synced and translated into Chinese. -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able, [financial contributions](https://opencollective.com/sanic-org/). From d58a195825d6c54d27b65e97c17e45b283dbb49d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:41 +0300 Subject: [PATCH 560/698] New translations v22.12.md (Korean) --- guide/content/ko/release-notes/2022/v22.12.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2022/v22.12.md b/guide/content/ko/release-notes/2022/v22.12.md index 0134d40494..c52c14d155 100644 --- a/guide/content/ko/release-notes/2022/v22.12.md +++ b/guide/content/ko/release-notes/2022/v22.12.md @@ -185,6 +185,6 @@ Thank you to everyone that participated in this release: :clap: [@todddialpad](https://github.com/todddialpad) [@Tronic](https://github.com/Tronic) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 78ee3991baed803ee9b68655e1605bae1953f03d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:42 +0300 Subject: [PATCH 561/698] New translations v22.3.md (Korean) --- guide/content/ko/release-notes/2022/v22.3.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/ko/release-notes/2022/v22.3.md b/guide/content/ko/release-notes/2022/v22.3.md index 90efaa047d..f39d38eb92 100644 --- a/guide/content/ko/release-notes/2022/v22.3.md +++ b/guide/content/ko/release-notes/2022/v22.3.md @@ -61,14 +61,14 @@ async def handler(request, filename, ext): Some potential examples: -| definition | example | filename | extension | -| ---------------------------------- | ----------- | -------- | ---------- | -| \ | page.txt | `"page"` | `"txt"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| definition | example | filename | extension | +| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | +| \file:ext | page.txt | `"page"` | `"txt"` | +| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | +| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | ### 🚨 _BREAKING CHANGE_ - Path parameter matching of non-empty strings @@ -225,6 +225,6 @@ Thank you to everyone that participated in this release: :clap: [@SerGeRybakov](https://github.com/SerGeRybakov) [@Tronic](https://github.com/Tronic) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From ae7383cb8c5b6ade421c9efdaec0806cf80f8aab Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:43 +0300 Subject: [PATCH 562/698] New translations v22.6.md (Korean) --- guide/content/ko/release-notes/2022/v22.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2022/v22.6.md b/guide/content/ko/release-notes/2022/v22.6.md index 73b893c498..18c212e82a 100644 --- a/guide/content/ko/release-notes/2022/v22.6.md +++ b/guide/content/ko/release-notes/2022/v22.6.md @@ -168,6 +168,6 @@ Thank you to everyone that participated in this release: :clap: [@timmo001](https://github.com/timmo001) [@zozzz](https://github.com/zozzz) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From c465ead2f728023d3b0b3012bc3890f2bf0a66c2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:45 +0300 Subject: [PATCH 563/698] New translations v22.9.md (Korean) --- guide/content/ko/release-notes/2022/v22.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2022/v22.9.md b/guide/content/ko/release-notes/2022/v22.9.md index b1ea8bf5d1..1e16034361 100644 --- a/guide/content/ko/release-notes/2022/v22.9.md +++ b/guide/content/ko/release-notes/2022/v22.9.md @@ -344,6 +344,6 @@ Thank you to everyone that participated in this release: :clap: [@timgates42](https://github.com/timgates42) [@Tronic](https://github.com/Tronic) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 79d46912dcfab5a0725fe82d046b0d23a0de4cb1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:46 +0300 Subject: [PATCH 564/698] New translations v23.12.md (Korean) --- guide/content/ko/release-notes/2023/v23.12.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2023/v23.12.md b/guide/content/ko/release-notes/2023/v23.12.md index 6694a10d2e..c6a622ecb2 100644 --- a/guide/content/ko/release-notes/2023/v23.12.md +++ b/guide/content/ko/release-notes/2023/v23.12.md @@ -180,6 +180,6 @@ Thank you to everyone that participated in this release: :clap: [@tjni](https://github.com/tjni) [@Tronic](https://github.com/Tronic) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From c7dace42bf5bb27657d4f945ab1d0578a80209cc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:47 +0300 Subject: [PATCH 565/698] New translations v23.3.md (Korean) --- guide/content/ko/release-notes/2023/v23.3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ko/release-notes/2023/v23.3.md b/guide/content/ko/release-notes/2023/v23.3.md index 70dc746698..7b098e2430 100644 --- a/guide/content/ko/release-notes/2023/v23.3.md +++ b/guide/content/ko/release-notes/2023/v23.3.md @@ -325,7 +325,7 @@ app = Sanic(..., certloader_class=MyCertLoader) In version 22.9, Sanic announced that v23.3 would deprecate allowing routes to be registered with duplicate names. If you see the following error, it is because of that change: -> sanic.exceptions.ServerError: Duplicate route names detected: SomeApp.some_handler. You should rename one or more of them explicitly by using the `name` param, or changing the implicit name derived from the class and function name. For more details, please see https\://sanic.dev/en/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed +> sanic.exceptions.ServerError: Duplicate route names detected: SomeApp.some_handler. You should rename one or more of them explicitly by using the `name` param, or changing the implicit name derived from the class and function name. For more details, please see https://sanic.dev/en/guide/release-notes/v23.3.html#duplicated-route-names-are-no-longer-allowed If you are seeing this, you should opt-in to using explicit names for your routes. @@ -416,6 +416,6 @@ Thank you to everyone that participated in this release: :clap: [@Tracyca209](https://github.com/Tracyca209) [@Tronic](https://github.com/Tronic) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 299c7c6a4dbc5ec098bc361b6a2634de2cedc0cf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:48 +0300 Subject: [PATCH 566/698] New translations v23.6.md (Korean) --- guide/content/ko/release-notes/2023/v23.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/release-notes/2023/v23.6.md b/guide/content/ko/release-notes/2023/v23.6.md index 74a3260c2b..0444dfd3dd 100644 --- a/guide/content/ko/release-notes/2023/v23.6.md +++ b/guide/content/ko/release-notes/2023/v23.6.md @@ -194,6 +194,6 @@ Thank you to everyone that participated in this release: :clap: [@Thirumalai](https://github.com/Thirumalai) [@Tronic](https://github.com/Tronic) -*** +--- If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 274f754fe955f3573352a0cf75f0e1e6a9d1460b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:55 +0300 Subject: [PATCH 567/698] New translations changelog.md (Korean) --- guide/content/ko/release-notes/changelog.md | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/guide/content/ko/release-notes/changelog.md b/guide/content/ko/release-notes/changelog.md index b98df20c9e..f6754f0457 100644 --- a/guide/content/ko/release-notes/changelog.md +++ b/guide/content/ko/release-notes/changelog.md @@ -453,7 +453,7 @@ _Current LTS version_ - `sanic.exceptions.abort` - `sanic.views.CompositionView` - `sanic.response.StreamingHTTPResponse` - - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming + - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https://sanicframework.org/en/guide/advanced/streaming.html#response-streaming - [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting ### Developer infrastructure @@ -789,10 +789,10 @@ Notes - `@app.on_request` - `@app.on_response` - Fixes `Allow` header that did not include `HEAD` -- Using "name" keyword in `url_for` for a "static" route where +- Using \"name\" keyword in `url_for` for a \"static\" route where name does not exist - Cannot have multiple `app.static()` without using the named param -- Using "filename" keyword in `url_for` on a file route +- Using \"filename\" keyword in `url_for` on a file route - `unquote` in route def (not automatic) - `routes_all` is tuples - Handler arguments are kwarg only @@ -982,7 +982,7 @@ Notes - [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for host parameter issue with lists - [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static - _handler pickling error + \_handler pickling error - [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader on OSX py38 and Windows - [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse @@ -1004,7 +1004,7 @@ Notes - [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust websockets version to setup.py - [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap - run()'s "protocol" type annotation in Optional[] + run()\'s \"protocol\" type annotation in Optional\[\] **Improved Documentation** @@ -1321,7 +1321,7 @@ December 2020, and therefore passing Python\'s official support version - [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar in README.md - [#1489](https://github.com/sanic-org/sanic/pull/1489) Added - "databases" to the extensions list + \"databases\" to the extensions list - [#1483](https://github.com/sanic-org/sanic/pull/1483) Add sanic-zipkin to extensions list - [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link @@ -1384,9 +1384,9 @@ PyPI - Fix content length mismatch in windows and other platform - Fix Range header handling for static files (#1402) - Fix the logger and make it work (#1397) - - Fix type pikcle->pickle in multiprocessing test + - Fix type pikcle-\>pickle in multiprocessing test - Fix pickling blueprints Change the string passed in the - "name" section of the namedtuples in Blueprint to match the + \"name\" section of the namedtuples in Blueprint to match the name of the Blueprint module attribute name. This allows blueprints to be pickled and unpickled, without errors, which is a requirement of running Sanic in multiprocessing mode in @@ -1402,7 +1402,7 @@ PyPI **0.8.3** - Changes: - - Ownership changed to org 'sanic-org' + - Ownership changed to org \'sanic-org\' **0.8.0** @@ -1442,7 +1442,7 @@ PyPI - Documentation updates/fixups (multiple contributors) - Fixes: - Fix: auto_reload in Linux (Ashley Sommer) - - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) + - Fix: broken tests for aiohttp \>= 3.3.0 (Ashley Sommer) - Fix: disable auto_reload by default on windows (abuckenheimer) - Fix (1143): Turn off access log with gunicorn (hqy) - Fix (1268): Support status code for file response (Cosmo Borsky) @@ -1454,13 +1454,13 @@ PyPI - Fix (1231): memory leak - always release resource (Phillip Xu) - Fix (1221): make request truthy if transport exists (Raphael Deem) - - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) + - Fix failing tests for aiohttp\>=3.1.0 (Ashley Sommer) - Fix try_everything examples (PyManiacGR, kot83) - Fix (1158): default to auto_reload in debug mode (Raphael Deem) - Fix (1136): ErrorHandler.response handler call too restrictive (Julien Castiaux) - Fix: raw requires bytes-like object (cloudship) - - Fix (1120): passing a list in to a route decorator's host arg + - Fix (1120): passing a list in to a route decorator\'s host arg (Timothy Ebiuwhe) - Fix: Bug in multipart/form-data parser (DirkGuijt) - Fix: Exception for missing parameter when value is null From b0849fd877c2e8ae361cf86fc20f8b765e206382 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:58 +0300 Subject: [PATCH 568/698] New translations proxy-headers.md (Chinese Simplified) --- .../zh/guide/advanced/proxy-headers.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/guide/content/zh/guide/advanced/proxy-headers.md b/guide/content/zh/guide/advanced/proxy-headers.md index 557a701d34..c5365da924 100644 --- a/guide/content/zh/guide/advanced/proxy-headers.md +++ b/guide/content/zh/guide/advanced/proxy-headers.md @@ -78,7 +78,7 @@ async def forwarded(request): ) ``` -*** +--- ##### 例1 @@ -121,7 +121,7 @@ Paper ``` ```` -*** +--- ##### 例2 @@ -168,7 +168,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例3 @@ -211,7 +211,7 @@ Paper ``` ```` -*** +--- ##### 例4 @@ -249,7 +249,7 @@ Power ``` ```` -*** +--- ##### 例5 @@ -289,7 +289,7 @@ Power ``` ```` -*** +--- ##### 例6 @@ -330,7 +330,7 @@ Power ``` ```` -*** +--- ##### 例7 @@ -371,7 +371,7 @@ Paper ``` ```` -*** +--- ##### 例8 @@ -411,7 +411,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -*** +--- ##### 例9 @@ -451,7 +451,7 @@ WP ``` ```` -*** +--- ##### 例10 @@ -491,7 +491,7 @@ WP ``` ```` -*** +--- ##### 例11 @@ -534,7 +534,7 @@ Power ``` ```` -*** +--- ##### 例12 From e6c7e3789e776172757653d17cb994e4e04d64bf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:34:59 +0300 Subject: [PATCH 569/698] New translations signals.md (Chinese Simplified) --- guide/content/zh/guide/advanced/signals.md | 40 +++++++++++----------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/guide/content/zh/guide/advanced/signals.md b/guide/content/zh/guide/advanced/signals.md index c403988adc..b691c669da 100644 --- a/guide/content/zh/guide/advanced/signals.md +++ b/guide/content/zh/guide/advanced/signals.md @@ -118,28 +118,28 @@ async def my_signal_handler(conn_info): 这些信号是现有的信号，以及处理者的论据和附加条件（如有）。 -| 事件名称 | 参数 | 条件 | -| -------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- | -| `http.routing.before` | 请求 | | -| `http.routing.after ` | 请求, 路由, kwargs, 处理程序 | | -| `http.handler.befor` | 请求 | | -| `http.handler.after ` | 请求 | | -| `http.lifecycle.begin` | conn_info | | -| `http.lifecycle.read_head` | 头部 | | -| `http.lifecycle.request` | 请求 | | -| `http.lifecycle.handle` | 请求 | | -| `http.lifecycle.read_body` | 正文内容 | | -| `http.lifecycle.excition` | 请求异常 | | -| `http.lifecycle.response` | 请求回复 | | -| `http.lifecycle.send` | 数据 | | -| `http.lifecycle.complete` | conn_info | | +| 事件名称 | 参数 | 条件 | +| -------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | +| `http.routing.before` | 请求 | | +| `http.routing.after ` | 请求, 路由, kwargs, 处理程序 | | +| `http.handler.befor` | 请求 | | +| `http.handler.after ` | 请求 | | +| `http.lifecycle.begin` | conn_info | | +| `http.lifecycle.read_head` | 头部 | | +| `http.lifecycle.request` | 请求 | | +| `http.lifecycle.handle` | 请求 | | +| `http.lifecycle.read_body` | 正文内容 | | +| `http.lifecycle.excition` | 请求异常 | | +| `http.lifecycle.response` | 请求回复 | | +| `http.lifecycle.send` | 数据 | | +| `http.lifecycle.complete` | conn_info | | | `http.midleware.before` | 请求回复 | \`{"attach_to": "request"}" 或 "{"attach_to": "response"}" | | `http.midleware.after ` | 请求回复 | \`{"attach_to": "request"}" 或 "{"attach_to": "response"}" | -| `server.exception.report` | 应用，异常 | | -| `server.init.before` | 应用，循环 | | -| `server.init.after ` | 应用，循环 | | -| `server.shutdown.before` | 应用，循环 | | -| `server.shutdown.after ` | 应用，循环 | | +| `server.exception.report` | 应用，异常 | | +| `server.init.before` | 应用，循环 | | +| `server.init.after ` | 应用，循环 | | +| `server.shutdown.before` | 应用，循环 | | +| `server.shutdown.after ` | 应用，循环 | | 22.9版本增加了`http.handler.before`和`http.handler.after`。 From 9c9452a09a2bc3d8b4d40cd954d1225efa673bce Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:02 +0300 Subject: [PATCH 570/698] New translations websockets.md (Chinese Simplified) --- guide/content/zh/guide/advanced/websockets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/advanced/websockets.md b/guide/content/zh/guide/advanced/websockets.md index 57d4c9c86c..636fdaf3f7 100644 --- a/guide/content/zh/guide/advanced/websockets.md +++ b/guide/content/zh/guide/advanced/websockets.md @@ -1,6 +1,6 @@ # Websockets -Sanic 提供了一个易于使用的 [websockets]顶部的摘要(https\://websockets.readthedocs.io/en/stable/)。 +Sanic 提供了一个易于使用的 [websockets]顶部的摘要(https://websockets.readthedocs.io/en/stable/)。 ## 路由 From bfbbe3c6c8d240394296a463ecaf21eba5392edc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:05 +0300 Subject: [PATCH 571/698] New translations handlers.md (Chinese Simplified) --- guide/content/zh/guide/basics/handlers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/guide/basics/handlers.md b/guide/content/zh/guide/basics/handlers.md index 442db8913e..e6f1f5acb5 100644 --- a/guide/content/zh/guide/basics/handlers.md +++ b/guide/content/zh/guide/basics/handlers.md @@ -69,7 +69,7 @@ async def foo_handler(request): ``` ```` -*** +--- ## 关于 _async_... @@ -140,7 +140,7 @@ Instead, try using a client that is `async/await` capable. Your server will than Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package (sanic-testing) 😉. ``` -*** +--- ## 一个完整注释的处理程序 From db01b5427898fcba1b54764d9135359873cf8779 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:07 +0300 Subject: [PATCH 572/698] New translations listeners.md (Chinese Simplified) --- guide/content/zh/guide/basics/listeners.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/content/zh/guide/basics/listeners.md b/guide/content/zh/guide/basics/listeners.md index c4f68b9ea3..e6b4d93883 100644 --- a/guide/content/zh/guide/basics/listeners.md +++ b/guide/content/zh/guide/basics/listeners.md @@ -161,14 +161,14 @@ async def setup_db(app): 侦听器按启动时的申报顺序执行，并在拆解时反向排序。 -| | 阶段 | 订单 | -| --------------------- | ------ | ------------------------------------------------------------------ | +| | 阶段 | 订单 | +| --------------------- | ------ | -------------------------------------------------------------------------------------------------- | | `main_process_start` | 主要启动 | 普通:稍微ly_smiling_face: ⬇️ | | `befor_server_start` | 工作人员启动 | 普通:稍微ly_smiling_face: ⬇️ | | `After _server_start` | 工作人员启动 | 普通:稍微ly_smiling_face: ⬇️ | -| `before_server_stop` | 工人关机 | 🙃 ⬆️ reverse | -| `After _server_stop` | 工人关机 | 🙃 ⬆️ reverse | -| `main_process_stop` | 主要关机 | 🙃 ⬆️ reverse | +| `before_server_stop` | 工人关机 | 🙃 ⬆️ reverse | +| `After _server_stop` | 工人关机 | 🙃 ⬆️ reverse | +| `main_process_stop` | 主要关机 | 🙃 ⬆️ reverse | 鉴于以下情况，如果我们运行两名工人，我们应该在控制台中看到这一点。 From 970b9e496fcbfd74b78146dc1f57ba9efda49307 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:11 +0300 Subject: [PATCH 573/698] New translations routing.md (Chinese Simplified) --- guide/content/zh/guide/basics/routing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/zh/guide/basics/routing.md b/guide/content/zh/guide/basics/routing.md index da121a5fca..897911b1ef 100644 --- a/guide/content/zh/guide/basics/routing.md +++ b/guide/content/zh/guide/basics/routing.md @@ -469,14 +469,14 @@ Async def 处理程序(请求，foo: str, ext: str): ``` ```` -| 定义 | 示例 | 文件名 | 扩展 | -| ---------------------------------- | ----------- | -------- | ----------- | -| \ | 页次 | `"page"` | `"txt"` | -| \ | jpg | `"cat"` | \`"jpg"" | -| \ | jpg | `"cat"` | \`"jpg"" | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | +| 定义 | 示例 | 文件名 | 扩展 | +| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | --------------------------- | +| \file:ext | 页次 | `"page"` | `"txt"` | +| \file:ext=jpg | jpg | `"cat"` | \`"jpg"" | +| \file:ext=jpg\\\|png\\\|gif\\\|svg | jpg | `"cat"` | \`"jpg"" | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | 文件扩展名可以使用特殊的 `ext` 参数类型匹配。 它使用特殊格式，允许您指定其他类型的参数类型作为文件名。 和上面的示例表所示的一个或多个具体扩展。 From 0eeed46894baae7b92a058c95647e908e58ec0c1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:12 +0300 Subject: [PATCH 574/698] New translations tasks.md (Chinese Simplified) --- guide/content/zh/guide/basics/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/basics/tasks.md b/guide/content/zh/guide/basics/tasks.md index 25359e7ad9..edc3902c48 100644 --- a/guide/content/zh/guide/basics/tasks.md +++ b/guide/content/zh/guide/basics/tasks.md @@ -6,7 +6,7 @@ title: 背景任务 ## 创建任务 -在异步Python中使用 [tasks]通常是可取和非常方便的。 (https\://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) Sanic 提供了一种方便的方法，可以将任务添加到当前的 **running** 循环中。 它与`asyncio.create_task`有些相似。 在 'App' 循环运行之前添加任务, 见下一个部分。 +在异步Python中使用 [tasks]通常是可取和非常方便的。 (https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) Sanic 提供了一种方便的方法，可以将任务添加到当前的 **running** 循环中。 它与`asyncio.create_task`有些相似。 在 'App' 循环运行之前添加任务, 见下一个部分。 ```python async def notify_server_started_after _fif_seconds(): From a7e4ec84a7e4ec100532a95d933925741ea4a469 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:21 +0300 Subject: [PATCH 575/698] New translations authentication.md (Chinese Simplified) --- guide/content/zh/guide/how-to/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/authentication.md b/guide/content/zh/guide/how-to/authentication.md index 9935a00247..f718528ebe 100644 --- a/guide/content/zh/guide/how-to/authentication.md +++ b/guide/content/zh/guide/how-to/authentication.md @@ -76,7 +76,7 @@ def protected(wrapped): 这种装饰模式取自[装饰品页面](/en/guide/best practices/decorators.md)。 -*** +--- ```bash $ curl localhost:99999/secret -i From be6cf75934d9fa46b2715ee3b80874f30e483e4d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:22 +0300 Subject: [PATCH 576/698] New translations autodiscovery.md (Chinese Simplified) --- guide/content/zh/guide/how-to/autodiscovery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/autodiscovery.md b/guide/content/zh/guide/how-to/autodiscovery.md index a0e9399677..238555db14 100644 --- a/guide/content/zh/guide/how-to/autodiscovery.md +++ b/guide/content/zh/guide/how-to/autodiscovery.md @@ -158,7 +158,7 @@ def print_something(app, loop): logger.debug("some @ 嵌套") ``` -*** +--- ```text here is the dir tree From cb782db1deb6eb9a4f9677efd2f92f505e9eac9f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:23 +0300 Subject: [PATCH 577/698] New translations cors.md (Chinese Simplified) --- guide/content/zh/guide/how-to/cors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/cors.md b/guide/content/zh/guide/how-to/cors.md index 97f393ea3b..b4a87058d1 100644 --- a/guide/content/zh/guide/how-to/cors.md +++ b/guide/content/zh/guide/how-to/cors.md @@ -109,7 +109,7 @@ def setup_options(app: Sanic, _): app.router.finalize() ``` -*** +--- ``` $ curl localhost:9999/ -i From c76e0025b6f974055aa9bba13c72d3d69168ff01 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:29 +0300 Subject: [PATCH 578/698] New translations static-redirects.md (Chinese Simplified) --- guide/content/zh/guide/how-to/static-redirects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/how-to/static-redirects.md b/guide/content/zh/guide/how-to/static-redirects.md index 15aa850291..4bc6dd54e7 100644 --- a/guide/content/zh/guide/how-to/static-redirects.md +++ b/guide/content/zh/guide/how-to/static-redirects.md @@ -99,7 +99,7 @@ body { ![lake](/assets/images/grottoes.jpg) -*** +--- 此外，结算社区的一些资源： From 1543fe114aa70b4af8f54e114e35a87952188c50 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:30 +0300 Subject: [PATCH 579/698] New translations table-of-contents.md (Chinese Simplified) --- .../content/zh/guide/how-to/table-of-contents.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/zh/guide/how-to/table-of-contents.md b/guide/content/zh/guide/how-to/table-of-contents.md index a3cb53ad9a..c2034c1d4c 100644 --- a/guide/content/zh/guide/how-to/table-of-contents.md +++ b/guide/content/zh/guide/how-to/table-of-contents.md @@ -6,12 +6,12 @@ title: 目录 我们汇编了充分运作的例子，以回答共同的问题和用户案例。 在大多数情况下，这些例子尽可能少一些，但应该是完整和可运作的解决办法。 -| 页 | 如何做... | -| :-------------------------------- | :------------------------------------------------- | -| [应用程序挂载](./mounting.md) | ... 将我的应用程序挂载到root上方的某个路径？ | -| [Authentication](./认证.md) | ... 控制认证和授权？ | -| [Autodiscovery](./autocovery.md) | ... 自动发现我用来构建应用程序的组件？ | -| [CORS](./cors.md) | ... 配置我的 CORS 应用程序？ | -| [ORM](./orm) | ... 使用 Sanic 的 ORM 吗？ | -| ["静态" 重定向](./static-redirects.md) | ... 配置静态重定向 | +| 页 | 如何做... | +| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | +| [应用程序挂载](./mounting.md) | ... 将我的应用程序挂载到root上方的某个路径？ | +| [Authentication](./认证.md) | ... 控制认证和授权？ | +| [Autodiscovery](./autocovery.md) | ... 自动发现我用来构建应用程序的组件？ | +| [CORS](./cors.md) | ... 配置我的 CORS 应用程序？ | +| [ORM](./orm) | ... 使用 Sanic 的 ORM 吗？ | +| ["静态" 重定向](./static-redirects.md) | ... 配置静态重定向 | | [TLS/SSL/HTTPS](./tls.md) | ... 通过 HTTPS 运行 Sanic 吗？
... 将 HTTP 重定向到 HTTPS？ | From 9e0b7d016f43a5fcaf24ce109fa4dd580dc069b9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:35 +0300 Subject: [PATCH 580/698] New translations configuration.md (Chinese Simplified) --- .../content/zh/guide/running/configuration.md | 68 +++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/guide/content/zh/guide/running/configuration.md b/guide/content/zh/guide/running/configuration.md index 3a2ab1c3cf..8dba9cffd5 100644 --- a/guide/content/zh/guide/running/configuration.md +++ b/guide/content/zh/guide/running/configuration.md @@ -242,40 +242,40 @@ app = Sanic(..., config=Config(converters=[UUID])) ## 内置值 -| **变量** | **默认** | **描述** | -| -------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------- | -| ACCESS_LOG | 真的 | 禁用或启用访问日志 | -| AUTO_EXTEND | 真的 | 控制 [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) 是否会在现有虚拟环境中加载 | -| AUTO_RELOAD | 真的 | 控制文件更改时应用程序是否会自动重新加载 | -| EVENT_AUTOREGISTER | 真的 | 当`True`使用`app.event()`方法在不存在的信号上将自动创建它，而不会引起异常 | -| FALLBACK_ERROR_FORMAT | .html | 未捕获和处理异常时的错误响应格式 | -| FORWARDED_FOR_HEADER | X-转发-输入 | 包含客户端和代理IP的 "X-Forwarded-for" HTTP 头名称 | -| FORWARDED_SECRET | 无 | 用于安全识别特定代理服务器(见下文) | -| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | 强制关闭非空闲连接等待多长时间 (秒) | -| INSPECTO | 错误 | 是否启用检查器 | -| INSPECTOR_HOST | 本地主机 | 检查专员的主机 | -| INSPECTOR_PORT | 6457 | 检查员的端口 | -| INSPECTOR_TLS_TITLE | - | 检查员的TLS密钥 | -| INSPECTOR_TLS_CERT | * | 检查员的TLS证书 | -| INSPECTOR_API_KEY | - | 检查员的 API 密钥 | -| KEEP_ALIVEUT | 120 | 保持TCP连接打开多长时间(秒) | -| KEEP_ALIVE | 真的 | False 时禁用保持生命值 | -| MOTD | 真的 | 启动时是否显示 MOTD (当天消息) | -| MOTD_DISPLAY | {} | Key/value 对应显示额外的任意数据 | -| NOISY_EXCEPTIONS | 错误 | 强制所有“安静”异常被记录 | -| PROXIES _COUNT | 无 | 在应用程序前面的代理服务器数量 (例如，nginx；见下方) | -| VIP_HEADER | 无 | 包含真实客户端IP的 "X-Real-IP" HTTP 头名称 | -| 注册 | 真的 | 是否启用应用注册 | -| REQUEST_BUFFER_SIZE | 65536 | 请求暂停前请求缓冲区大小，默认是 64 Kib | -| REQUEST_HEADER | X-请求-ID | 包含请求/关联ID的 "X-Request-ID" HTTP 头名称 | -| REQUEST_MAX_SIZE | 100000000 | 请求的大小可能是 (bytes), 默认是 100 megabytes | -| REQUEST_MAX_HEADER_SIZE | 8192 | 请求头可能有多大(字节)，默认值为8192字节 | -| REQUEST_TIMEOUT | 60 | 到达请求可能需要多长时间(秒) | -| 重置_TIMEOUT | 60 | 处理过程可能需要多长时间(秒) | -| USE_UVLOOP | 真的 | 是否覆盖循环策略使用 `uvloop` 。 只支持 `app.run` 。 | -| WEBSOCKET_MAX_SIZE | 2^20 | 收到消息的最大大小(字节) | -| WEBSOCKET_INTERVAL | 20 | 每个ping_interval 秒都会发送一个Ping 帧。 | -| WEBSOCKET_PING_TIMEOUT | 20 | 当Pong在ping_timeout秒后未收到时，连接将被关闭 | +| **变量** | **默认** | **描述** | +| -------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------- | +| ACCESS_LOG | 真的 | 禁用或启用访问日志 | +| AUTO_EXTEND | 真的 | 控制 [Sanic Extensions](../../plugins/sanic-ext/getting-started.md) 是否会在现有虚拟环境中加载 | +| AUTO_RELOAD | 真的 | 控制文件更改时应用程序是否会自动重新加载 | +| EVENT_AUTOREGISTER | 真的 | 当`True`使用`app.event()`方法在不存在的信号上将自动创建它，而不会引起异常 | +| FALLBACK_ERROR_FORMAT | .html | 未捕获和处理异常时的错误响应格式 | +| FORWARDED_FOR_HEADER | X-转发-输入 | 包含客户端和代理IP的 "X-Forwarded-for" HTTP 头名称 | +| FORWARDED_SECRET | 无 | 用于安全识别特定代理服务器(见下文) | +| GRACEFUL_SHUTDOWN_TIMEOUT | 15.0 | 强制关闭非空闲连接等待多长时间 (秒) | +| INSPECTO | 错误 | 是否启用检查器 | +| INSPECTOR_HOST | 本地主机 | 检查专员的主机 | +| INSPECTOR_PORT | 6457 | 检查员的端口 | +| INSPECTOR_TLS_TITLE | - | 检查员的TLS密钥 | +| INSPECTOR_TLS_CERT | * | 检查员的TLS证书 | +| INSPECTOR_API_KEY | - | 检查员的 API 密钥 | +| KEEP_ALIVEUT | 120 | 保持TCP连接打开多长时间(秒) | +| KEEP_ALIVE | 真的 | False 时禁用保持生命值 | +| MOTD | 真的 | 启动时是否显示 MOTD (当天消息) | +| MOTD_DISPLAY | {} | Key/value 对应显示额外的任意数据 | +| NOISY_EXCEPTIONS | 错误 | 强制所有“安静”异常被记录 | +| PROXIES _COUNT | 无 | 在应用程序前面的代理服务器数量 (例如，nginx；见下方) | +| VIP_HEADER | 无 | 包含真实客户端IP的 "X-Real-IP" HTTP 头名称 | +| 注册 | 真的 | 是否启用应用注册 | +| REQUEST_BUFFER_SIZE | 65536 | 请求暂停前请求缓冲区大小，默认是 64 Kib | +| REQUEST_HEADER | X-请求-ID | 包含请求/关联ID的 "X-Request-ID" HTTP 头名称 | +| REQUEST_MAX_SIZE | 100000000 | 请求的大小可能是 (bytes), 默认是 100 megabytes | +| REQUEST_MAX_HEADER_SIZE | 8192 | 请求头可能有多大(字节)，默认值为8192字节 | +| REQUEST_TIMEOUT | 60 | 到达请求可能需要多长时间(秒) | +| 重置_TIMEOUT | 60 | 处理过程可能需要多长时间(秒) | +| USE_UVLOOP | 真的 | 是否覆盖循环策略使用 `uvloop` 。 只支持 `app.run` 。 | +| WEBSOCKET_MAX_SIZE | 2^20 | 收到消息的最大大小(字节) | +| WEBSOCKET_INTERVAL | 20 | 每个ping_interval 秒都会发送一个Ping 帧。 | +| WEBSOCKET_PING_TIMEOUT | 20 | 当Pong在ping_timeout秒后未收到时，连接将被关闭 | .. tip:: FYI From b3553f076c81ad3631cdf0092155c9ad15e500a0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:36 +0300 Subject: [PATCH 581/698] New translations development.md (Chinese Simplified) --- guide/content/zh/guide/running/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/running/development.md b/guide/content/zh/guide/running/development.md index 8ec2420aea..97b76e3b3c 100644 --- a/guide/content/zh/guide/running/development.md +++ b/guide/content/zh/guide/running/development.md @@ -272,7 +272,7 @@ sanic path.to:app --dev --no-repl ## 自动TLS证书 -当在 `DEBUG` 模式下运行时，您可以要求Sanic 处理本地主机临时TLS 证书的设置。 如果您想要访问 'https\://' 本地发展环境，这将是很有帮助的。 +当在 `DEBUG` 模式下运行时，您可以要求Sanic 处理本地主机临时TLS 证书的设置。 如果您想要访问 'https://' 本地发展环境，这将是很有帮助的。 此功能由 [mkcert](https://github.com/FiloSottile/mkcert) 或 [trustme](https://github.com/python-trio/trustme) 提供。 两者都是好的选择，但也有一些差异。 `Trustme` 是一个 Python 库，可以安装在 `pip` 里的环境。 这使得可以轻松地处理Envrionment，但在运行 HTTP/3 服务器时是不兼容的。 `mkcert`可能是一个更多的安装过程，但可以安装本地CA并使其更容易使用。 From c4693f1ff72da7b756ad3f5da5577a50dc34eb2f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:38 +0300 Subject: [PATCH 582/698] New translations manager.md (Chinese Simplified) --- guide/content/zh/guide/running/manager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/running/manager.md b/guide/content/zh/guide/running/manager.md index b10abc05de..5894f52a8c 100644 --- a/guide/content/zh/guide/running/manager.md +++ b/guide/content/zh/guide/running/manager.md @@ -130,7 +130,7 @@ _在 v22.12中添加_ ## 使用工人流程之间的共享环境 -Python 提供了几种方法用于[交换对象](https\://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between en-processes)、 [synchronizing](https\://docs.python.org/3/library/multiprocessing.html#synization-between process)和[sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-honen-processes) 之间的流程。 这通常涉及来自`multiprocessing` 和 `ctypes` 模块的对象。 +Python 提供了几种方法用于[交换对象](https://docs.python.org/3/library/multiprocessing.html#exchanging-objects-between en-processes)、 [synchronizing](https://docs.python.org/3/library/multiprocessing.html#synization-between process)和[sharing state](https://docs.python.org/3/library/multiprocessing.html#sharing-state-honen-processes) 之间的流程。 这通常涉及来自`multiprocessing` 和 `ctypes` 模块的对象。 如果你熟悉这些对象以及如何与它们合作， 你会很乐意知道， Sanic 提供了一个 API 用于在你的工序之间分享这些物体。 如果你不熟悉， 鼓励您阅读以上链接的 Python 文档，然后尝试一些示例，然后执行共享环境。 From 263d9aaffd5175520bf67d8c10cb5b4ce4e823aa Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:40 +0300 Subject: [PATCH 583/698] New translations running.md (Chinese Simplified) --- guide/content/zh/guide/running/running.md | 48 +++++++++++------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/guide/content/zh/guide/running/running.md b/guide/content/zh/guide/running/running.md index 86f2f029f9..6fdbdd6080 100644 --- a/guide/content/zh/guide/running/running.md +++ b/guide/content/zh/guide/running/running.md @@ -311,29 +311,29 @@ elif __name__ == "__main__": 要使用低级别的 `run` API，在定义一个 `sanic.Sanic` 实例后，我们可以使用以下关键词参数来调用运行方法： -| 参数 | 默认设置 | 描述 | -| :---------------------------------------: | :-------------: | :--------------------------------------------------------------------- | -| **主机** | `"127.0.0.1"` | 服务器主机地址已开启。 | -| **端口** | `8000` | 服务器端口已开启。 | -| **unix** | `无` | 服务器主机的 Unix 套接字名称 (而不是TCP)。 | -| **dev** | `False` | 等于`debug=True`和`auto_reload=True`。 | -| **debug** | `False` | 启用调试输出 (慢速服务器)。 | -| **ssl** | `无` | SSLContext for SSL 加密 (s)。 | -| **sock** | `无` | Socket 让服务器接受连接。 | -| **Workers** | `1` | 要生成的工序数量。 无法快速使用。 | -| **循环** | `无` | 一个异步兼容的事件循环。 如果没有具体说明，Sanic将创建自己的事件循环。 | +| 参数 | 默认设置 | 描述 | +| :---------------------------------------: | :-------------: | :------------------------------------------------------------------------------------- | +| **主机** | `"127.0.0.1"` | 服务器主机地址已开启。 | +| **端口** | `8000` | 服务器端口已开启。 | +| **unix** | `无` | 服务器主机的 Unix 套接字名称 (而不是TCP)。 | +| **dev** | `False` | 等于`debug=True`和`auto_reload=True`。 | +| **debug** | `False` | 启用调试输出 (慢速服务器)。 | +| **ssl** | `无` | SSLContext for SSL 加密 (s)。 | +| **sock** | `无` | Socket 让服务器接受连接。 | +| **Workers** | `1` | 要生成的工序数量。 无法快速使用。 | +| **循环** | `无` | 一个异步兼容的事件循环。 如果没有具体说明，Sanic将创建自己的事件循环。 | | **protocol** | `HttpProtocol` | asyncio.protocol的子类。 | | **版本** | `HTTPVERSION_1` | 要使用的 HTTP 版本 (`HTTP.VERSION_1` 或 `HTTP.VERSION_3`). | -| **access_log** | `True` | 启用处理请求的日志 (大大减慢服务器)。 | -| **auto_reload** | `无` | 启用源目录自动重新加载。 | -| **reload_dir** | `无` | 自动读取加载器应该监视的目录路径或路径列表。 | -| **noisy_exceptions** | `无` | 是否设置全局噪音异常。 没有表示离开为默认值。 | -| **motd** | `True` | 是否显示启动消息。 | -| **motd_display** | `无` | 在启动消息中显示额外的密钥/值信息 | -| **fast** | `False` | 是否最大化工人工序。 无法与工人一起使用。 | -| **详细化** | `0` | 日志的详细级别。 最大值为 2。 | -| **自动_tls** | `False` | 是否为本地开发自动创建TLS证书。 不是生产的。 | -| **单独处理** | `False` | 是否在一个过程中运行 Sanic。 | +| **access_log** | `True` | 启用处理请求的日志 (大大减慢服务器)。 | +| **auto_reload** | `无` | 启用源目录自动重新加载。 | +| **reload_dir** | `无` | 自动读取加载器应该监视的目录路径或路径列表。 | +| **noisy_exceptions** | `无` | 是否设置全局噪音异常。 没有表示离开为默认值。 | +| **motd** | `True` | 是否显示启动消息。 | +| **motd_display** | `无` | 在启动消息中显示额外的密钥/值信息 | +| **fast** | `False` | 是否最大化工人工序。 无法与工人一起使用。 | +| **详细化** | `0` | 日志的详细级别。 最大值为 2。 | +| **自动_tls** | `False` | 是否为本地开发自动创建TLS证书。 不是生产的。 | +| **单独处理** | `False` | 是否在一个过程中运行 Sanic。 | .. 列: @@ -473,7 +473,7 @@ app.run(version=3) ``` ```` -要同时运行一个 HTTP/3 和 HTTP/1.1 服务器，您可以使用 v22.3 引入的 [application multi-servve](../release-notes/v22.3.html#application-multi-servve)。 这将自动添加一个 [Alt-Svc](https\://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ Alt-Svc) 头到您的 HTTP/1.1 请求让客户端知道它也是可用的 HTTP/3。 +要同时运行一个 HTTP/3 和 HTTP/1.1 服务器，您可以使用 v22.3 引入的 [application multi-servve](../release-notes/v22.3.html#application-multi-servve)。 这将自动添加一个 [Alt-Svc](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ Alt-Svc) 头到您的 HTTP/1.1 请求让客户端知道它也是可用的 HTTP/3。 .. 列: @@ -524,7 +524,7 @@ uvicorn myapp:app 使用ASGI时要注意的几件事： 1. 当使用 Sanic 网络服务器时，websockets 将使用 `websockets` 软件包运行。 在 ASGI 模式下，没有必要使用这个软件包，因为websockets 是在 ASGI 服务器上管理的。 -2. ASGI 生命周期协议 https\://asgi.readthedocs.io/en/latest/specs/lifespan.html，只支持两个服务器事件：启动和关机。 萨里语有四个：启动前、启动后、关闭前和关机。 因此，以ASGI模式， 启动和关闭事件将连续运行，而不是围绕服务器进程开始和结束(因为现在是由 ASGI 服务器控制的)。 因此，最好使用 `after _server_start` 和 `previ_server_stop` 。 +2. ASGI 生命周期协议 https://asgi.readthedocs.io/en/latest/specs/lifespan.html，只支持两个服务器事件：启动和关机。 萨里语有四个：启动前、启动后、关闭前和关机。 因此，以ASGI模式， 启动和关闭事件将连续运行，而不是围绕服务器进程开始和结束(因为现在是由 ASGI 服务器控制的)。 因此，最好使用 `after _server_start` 和 `previ_server_stop` 。 ### 特里奥文 @@ -538,7 +538,7 @@ Sanic在Trio上运行时有实验支持： [Gunicorn](http://gunicorn.org/) ("Green Unicorn") 是一个基于UNIX的操作系统的 WSGI HTTP 服务器。 这是一个基于 Ruby Unicorn项目的前叉工人模型。 -若要与 Gunicorn一起运行 Sanic 应用程序，您需要使用 [uvicorn]的适配器(https\://www\.uvicorn.org/)。 确保uvicorn已经安装并运行它与 `uvicorn.workers.UvicornWorker` for Gunicorn worker-class参数： +若要与 Gunicorn一起运行 Sanic 应用程序，您需要使用 [uvicorn]的适配器(https://www.uvicorn.org/)。 确保uvicorn已经安装并运行它与 `uvicorn.workers.UvicornWorker` for Gunicorn worker-class参数： ```sh gunicorn myapp:app --binding 0.0.0:1337 --worker-classuvicorn.workers.UvicornWorker From 1116fbfa5f6d1625ad428a102febbc8a513858fb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:40 +0300 Subject: [PATCH 584/698] New translations help.md (Chinese Simplified) --- guide/content/zh/help.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/help.md b/guide/content/zh/help.md index 11052a6e66..103c969c62 100644 --- a/guide/content/zh/help.md +++ b/guide/content/zh/help.md @@ -27,6 +27,6 @@ layout: 主界面 [论坛](https://community.sanicframework.org/c/questions-and-help/6)上的「问题与帮助」（Questions and Help） ``` -*** +--- 我们还积极监视 [Stack Overflow](https://stackoverflow.com/questions/tagged/sanic) 上的\`[sanic]'标签。 From fa606ebcda92a761d0167ad18f692a87b5b583b5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:42 +0300 Subject: [PATCH 585/698] New translations code-of-conduct.md (Chinese Simplified) --- guide/content/zh/organization/code-of-conduct.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guide/content/zh/organization/code-of-conduct.md b/guide/content/zh/organization/code-of-conduct.md index 2704a63246..303972a49f 100644 --- a/guide/content/zh/organization/code-of-conduct.md +++ b/guide/content/zh/organization/code-of-conduct.md @@ -53,7 +53,7 @@ further defined and clarified by project maintainers. ## 执行 -可能是通过联系项目团队Adam\@sanicframework.org报告的滥用、骚扰或其他令人无法接受的行为。 所有 +可能是通过联系项目团队Adam@sanicframework.org报告的滥用、骚扰或其他令人无法接受的行为。 所有 申诉都将得到审查和调查，结果将产生 被认为是必要和适合当时情况的答复。 项目组负责 对事件报告者保密。 @@ -69,5 +69,4 @@ members of the project's leadership. [http://contributor-covenant.org/version/1/4][version] [homepage]: http://contributor-Covenant.org - [version]: http://contributor-covenant.org/version/1/4/ From a6ba9f46e8a0c64c55f3ca535deddae81706da85 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:43 +0300 Subject: [PATCH 586/698] New translations contributing.md (Chinese Simplified) --- guide/content/zh/organization/contributing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/zh/organization/contributing.md b/guide/content/zh/organization/contributing.md index 5193f4c598..1e086b7ed0 100644 --- a/guide/content/zh/organization/contributing.md +++ b/guide/content/zh/organization/contributing.md @@ -18,9 +18,9 @@ pip install -e ".[dev]" `Sanic` 不使用 `requirements*.txt` 文件来管理与此相关的任何依赖关系，以简化管理依赖关系所需的努力。 请确保您已经阅读并理解文档的下面一节，其中解释了`sanic` 如何管理`setup.py`文件中的依赖关系。 -| 依赖类型 | 用法 | 安装 | -| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------- | -| 所需经费 | 智能正常运行所需的最低依赖关系 | `pip3 install -e .` | +| 依赖类型 | 用法 | 安装 | +| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ----------------------------------------------------------------------------------------------- | +| 所需经费 | 智能正常运行所需的最低依赖关系 | `pip3 install -e .` | | tests_request / extras_require['test'] | 运行 `sanic` 设备测试所需的依赖关系 | \`pip3 install -e '.[test]' | | extras_require['dev'] | 增加捐款的额外发展要求 | \`pip3 install -e '.[dev]' | | extras_require['docs'] | 建立和加强卫生文档所需的依赖关系 | \`pip3 install -e '.[docs]' | @@ -142,7 +142,7 @@ tox -e 文档 做得很好 ``` -欲了解更多详情，请参阅[tox documentation](https\://tox.readthedocs.io/en/ index.html)。 +欲了解更多详情，请参阅[tox documentation](https://tox.readthedocs.io/en/ index.html)。 ## 拉取请求 From 0a1e27476ce5ed3a27c64799a568f74a7b8a6988 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:35:45 +0300 Subject: [PATCH 587/698] New translations policies.md (Chinese Simplified) --- guide/content/zh/organization/policies.md | 44 +++++++++++------------ 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/guide/content/zh/organization/policies.md b/guide/content/zh/organization/policies.md index 24e8b68553..4b01b842e0 100644 --- a/guide/content/zh/organization/policies.md +++ b/guide/content/zh/organization/policies.md @@ -35,28 +35,28 @@ YY.MMM.MMRO 12月，Sanic每年发布一次长期支持释放（又名“LTS”）。 LTS 版本在 **24 个月**中获得错误修复和安全更新。 全年的临时释放每三个月进行一次，并在随后的释放之前得到支持。 -| 版本 | 发布 | LTS | 支持的 | -| ----- | ---------- | ------- | --- | -| 23.12 | 2023-12-31 | 2025-12 | ✅ | -| 23.6 | 2023-07-25 | | ⚪ | -| 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | 2024-12 | ☑️ | -| 22.9 | 2022-09-29 | | ⚪ | -| 22.6 | 2022-06-30 | | ⚪ | -| 22.3 | 2022-03-31 | | ⚪ | -| 21.12 | 2021-12-26 | | ⚪ | -| 21.9 | 2021-09-30 | | ⚪ | -| 21.6 | 2021-06-27 | | ⚪ | -| 21.3 | 2021-03-21 | | ⚪ | -| 20.12 | 2020-12-29 | | ⚪ | -| 20.9 | 2020-09-30 | | ⚪ | -| 20.6 | 2020-06-28 | | ⚪ | -| 20.3 | 2020-05-14 | | ⚪ | -| 19.12 | 2019-12-27 | | ⚪ | -| 19.9 | 2019-10-12 | | ⚪ | -| 19.6 | 2019-06-21 | | ⚪ | -| 19.3 | 2019-03-23 | | ⚪ | -| 18.12 | 2018-12-27 | | ⚪ | +| 版本 | 发布 | LTS | 支持的 | +| ------------------------------------- | ---------- | ------- | --- | +| 23.12 | 2023-12-31 | 2025-12 | ✅ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | 2024-12 | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | | 0.8.3 | 2018-09-13 | | ⚪ | | 0.7.0 | 2017-12-06 | | ⚪ | | 0.6.0 | 2017-08-03 | | ⚪ | From 60d85efa5bb85dad123298f66a25c9925e2a4b81 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:02 +0300 Subject: [PATCH 588/698] New translations v21.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.12.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/release-notes/2021/v21.12.md b/guide/content/zh/release-notes/2021/v21.12.md index 46225b4c7f..ee1670dd45 100644 --- a/guide/content/zh/release-notes/2021/v21.12.md +++ b/guide/content/zh/release-notes/2021/v21.12.md @@ -526,6 +526,6 @@ Thank you to everyone that participated in this release: :clap: 并且，特别感谢你[@miss85246](https://github.com/miss85246)和[@ZinkLu](https://github.com/ZinkLu)做了大量工作，使文档同步并翻译成中文。 -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From f92fb977a5817365987ccd009ab0242096cd780b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:03 +0300 Subject: [PATCH 589/698] New translations v21.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/release-notes/2021/v21.3.md b/guide/content/zh/release-notes/2021/v21.3.md index 2e343a1ae2..53134b7484 100644 --- a/guide/content/zh/release-notes/2021/v21.3.md +++ b/guide/content/zh/release-notes/2021/v21.3.md @@ -267,6 +267,6 @@ Thank you to everyone that participated in this release: :clap: [@ConnorZhang](https://github.com/miss85246)和[@ZinkLu](https://github.com/ZinkLu)将我们的文件翻译成中文。 -*** +--- 确保检查更新日志以获取所有PR等链接。 From 3195266a3e66e53ce67620e2d9499380078526b2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:05 +0300 Subject: [PATCH 590/698] New translations v21.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.6.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/zh/release-notes/2021/v21.6.md b/guide/content/zh/release-notes/2021/v21.6.md index a9c1fd07e9..f923124dce 100644 --- a/guide/content/zh/release-notes/2021/v21.6.md +++ b/guide/content/zh/release-notes/2021/v21.6.md @@ -42,7 +42,7 @@ async def handler(request, foo: str, bar: float): ### 内联 `eof()` -第21.3版包括[如何处理流媒体的重大变化](https\://sanic.dev/en/guide/release-notes/v21.3.html#what to-know)。 采用的模式将成为缺省模式（见下文）。 为方便起见，列入了一个新的`response.eof()`方法。 一旦最终数据被推送到客户端，它应被调用： +第21.3版包括[如何处理流媒体的重大变化](https://sanic.dev/en/guide/release-notes/v21.3.html#what to-know)。 采用的模式将成为缺省模式（见下文）。 为方便起见，列入了一个新的`response.eof()`方法。 一旦最终数据被推送到客户端，它应被调用： ```python @app.route("/") @@ -305,7 +305,7 @@ DummyView(HTTPMethodView, attach=app, uri="/"): ### Discord 和支持论坛 -如果你还没有加入我们的社区，你可以通过加入 [Discord 服务器] (https\://discord.gg/RARQzAEMAA) 和 [Community Forums](https://community.sanicframework.org/) 来成为一个组成部分。 另外，在Twitter上关注[@sanicframework](https://twitter.com/sanicframework)。 +如果你还没有加入我们的社区，你可以通过加入 [Discord 服务器] (https://discord.gg/RARQzAEMAA) 和 [Community Forums](https://community.sanicframework.org/) 来成为一个组成部分。 另外，在Twitter上关注[@sanicframework](https://twitter.com/sanicframework)。 ### 上海合作组织2022年选举 @@ -347,6 +347,6 @@ Thank you to everyone that participated in this release: :clap: [@vltr](https://github.com/vltr) [@ZinkLu](https://github.com/zinklu) -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够，[财务贡献](https://opencollective.com/sanic-org/)。 From ea9735ec1898e6461da276ae268423a938278b59 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:06 +0300 Subject: [PATCH 591/698] New translations v21.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2021/v21.9.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/release-notes/2021/v21.9.md b/guide/content/zh/release-notes/2021/v21.9.md index 763e6949f8..877253bca6 100644 --- a/guide/content/zh/release-notes/2021/v21.9.md +++ b/guide/content/zh/release-notes/2021/v21.9.md @@ -235,6 +235,6 @@ Thank you to everyone that participated in this release: :clap: 并且，特别感谢你[@miss85246](https://github.com/miss85246)和[@ZinkLu](https://github.com/ZinkLu)做了大量工作，使文档同步并翻译成中文。 -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够，[财务贡献](https://opencollective.com/sanic-org/)。 From d27ab523ea79b8eced1993bb98e01817ed6e881b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:07 +0300 Subject: [PATCH 592/698] New translations v22.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.12.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/release-notes/2022/v22.12.md b/guide/content/zh/release-notes/2022/v22.12.md index 5a5b5d0c71..1f5163fbb3 100644 --- a/guide/content/zh/release-notes/2022/v22.12.md +++ b/guide/content/zh/release-notes/2022/v22.12.md @@ -185,6 +185,6 @@ Thank you to everyone that participated in this release: :clap: [@todddialpad](https://github.com/todddialpad) [@ -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From ed1357bf73e0f05a046e4107ba59ab072115e23d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:08 +0300 Subject: [PATCH 593/698] New translations v22.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.3.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/guide/content/zh/release-notes/2022/v22.3.md b/guide/content/zh/release-notes/2022/v22.3.md index e7d3fd7eea..b502c935f2 100644 --- a/guide/content/zh/release-notes/2022/v22.3.md +++ b/guide/content/zh/release-notes/2022/v22.3.md @@ -61,14 +61,14 @@ async def 处理(请求, 文件名, ext): 一些潜在的例子： -| 定义 | 示例 | 文件名 | 扩展 | -| ---------------------------------- | ----------- | -------- | ----------- | -| \ | 页次 | `"page"` | `"txt"` | -| \ | jpg | `"cat"` | \`"jpg"" | -| \ | jpg | `"cat"` | \`"jpg"" | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | +| 定义 | 示例 | 文件名 | 扩展 | +| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | --------------------------- | +| \file:ext | 页次 | `"page"` | `"txt"` | +| \file:ext=jpg | jpg | `"cat"` | \`"jpg"" | +| \file:ext=jpg\\\|png\\\|gif\\\|svg | jpg | `"cat"` | \`"jpg"" | +| \ | 123.txt | `123` | `"txt"` | +| \ | 123.svg | `123` | `"svg"` | +| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | ### 🚨 _Breaking变换_ - 非空字符串路径参数 @@ -225,6 +225,6 @@ Thank you to everyone that participated in this release: :clap: [@SerGeRybakov](https://github.com/SerGeRybakov) [@Tronic](https://github.com/Tronic) -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 6f225882f953eda134d6ac8b3ef5fb49665f8269 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:09 +0300 Subject: [PATCH 594/698] New translations v22.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/release-notes/2022/v22.6.md b/guide/content/zh/release-notes/2022/v22.6.md index d20a5349db..fc0d94fb16 100644 --- a/guide/content/zh/release-notes/2022/v22.6.md +++ b/guide/content/zh/release-notes/2022/v22.6.md @@ -168,6 +168,6 @@ Thank you to everyone that participated in this release: :clap: [@timmo001](https://github.com/timmo001) [@zozzz](https://github.com/zozzz) -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 50b939b574fb78784dad9f0dfd98e8eac6ed0526 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:10 +0300 Subject: [PATCH 595/698] New translations v22.9.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.9.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/release-notes/2022/v22.9.md b/guide/content/zh/release-notes/2022/v22.9.md index 7e8afc0a58..023e3598ba 100644 --- a/guide/content/zh/release-notes/2022/v22.9.md +++ b/guide/content/zh/release-notes/2022/v22.9.md @@ -254,7 +254,7 @@ async def hig_priority(_): ### 自定义 `loads` 函数 -Sanic 支持在实例化应用程序时添加 [自定义 `dumps` 函数] (https\://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic)。 同一功能已扩展到 `loads`, 当反序列化时将使用它。 +Sanic 支持在实例化应用程序时添加 [自定义 `dumps` 函数] (https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic)。 同一功能已扩展到 `loads`, 当反序列化时将使用它。 ```python 从 json 导入负载 @@ -344,6 +344,6 @@ Thank you to everyone that participated in this release: :clap: [@timgates42](https://github.com/timgates42) [@Tronic](https://github.com/Tronic) -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 9806d194260ed61984774102b72733f11dc2a441 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:12 +0300 Subject: [PATCH 596/698] New translations v23.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.12.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/release-notes/2023/v23.12.md b/guide/content/zh/release-notes/2023/v23.12.md index f8ec203ad9..7741fac421 100644 --- a/guide/content/zh/release-notes/2023/v23.12.md +++ b/guide/content/zh/release-notes/2023/v23.12.md @@ -180,6 +180,6 @@ Thank you to everyone that participated in this release: :clap: [@tjni](https://github.com/tjni) [@Tronic](https://github.com/Tronic) -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 03cb40216a12af3b662f8b5aa8507e22cec405d9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:13 +0300 Subject: [PATCH 597/698] New translations v23.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.3.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/zh/release-notes/2023/v23.3.md b/guide/content/zh/release-notes/2023/v23.3.md index 3f6a2a4ce0..4c5c559112 100644 --- a/guide/content/zh/release-notes/2023/v23.3.md +++ b/guide/content/zh/release-notes/2023/v23.3.md @@ -232,7 +232,7 @@ cookie.getlist("foo") ### 🚨 _Breaking变换_ - 更加一致和强大的 `SanicException` -Sanic已经有一段时间将`SanicException`作为基本类别的例外。 可将其扩展到添加`status_code`等（详见http\://localhost:8080/en/guide/best practices/exceptions.html）。 +Sanic已经有一段时间将`SanicException`作为基本类别的例外。 可将其扩展到添加`status_code`等（详见http://localhost:8080/en/guide/best practices/exceptions.html）。 **NOW**，使用所有不同的例外已变得更加容易。 通常使用的异常可以直接从 root 级模块导入。 @@ -325,7 +325,7 @@ app = Sanic(...certloader_class=MyCertLoader) 在第22.9版中，Sanic宣布说，V23.3不允许使用重复名称注册路线。 如果你看到以下错误，它是因为这种改变： -> 异常。服务器错误：检测到重复的路由名称：有人App.some_handler。 您应该使用 "name" 参数来明确重命名其中一个或多个， 或更改来自类和函数名称的隐含名称。 欲了解更多详情，请访问https\://sanic.dev/en/guide/release-notes/v23.3.html#carbated-route-names-are-no longer-allowed +> 异常。服务器错误：检测到重复的路由名称：有人App.some_handler。 您应该使用 "name" 参数来明确重命名其中一个或多个， 或更改来自类和函数名称的隐含名称。 欲了解更多详情，请访问https://sanic.dev/en/guide/release-notes/v23.3.html#carbated-route-names-are-no longer-allowed 如果你看到这一点，你应该选择为你的路线使用明确的名称。 @@ -416,6 +416,6 @@ Thank you to everyone that participated in this release: :clap: [@Tracyca209](https://github.com/Tracyca209) [@Tronic](https://github.com/Tronic) -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 8d98c9894dde37914e2aab3a3c60cb513551dcbc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:14 +0300 Subject: [PATCH 598/698] New translations v23.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2023/v23.6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/release-notes/2023/v23.6.md b/guide/content/zh/release-notes/2023/v23.6.md index f45729cc33..ea2e4de4c2 100644 --- a/guide/content/zh/release-notes/2023/v23.6.md +++ b/guide/content/zh/release-notes/2023/v23.6.md @@ -194,6 +194,6 @@ Thank you to everyone that participated in this release: :clap: [@Thirumalai](https://github.com/Thirumalai) [@Tronic](https://github.com/Tronic) -*** +--- 如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 0f5ea5edded78b2a61a664f5f412afc60f491292 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Fri, 5 Apr 2024 14:36:20 +0300 Subject: [PATCH 599/698] New translations changelog.md (Chinese Simplified) --- guide/content/zh/release-notes/changelog.md | 26 ++++++++++----------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/guide/content/zh/release-notes/changelog.md b/guide/content/zh/release-notes/changelog.md index c4bbf8da4a..d98113271d 100644 --- a/guide/content/zh/release-notes/changelog.md +++ b/guide/content/zh/release-notes/changelog.md @@ -453,7 +453,7 @@ _当前LTS版本_ - `sanic.exceptions.abort` - `sanic.views.CompositionView` - `sanic.response.StreamingHTTPResponse` - - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https\://sanicframework.org/en/guide/advanced/streaming.html#response-streaming + - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https://sanicframework.org/en/guide/advanced/streaming.html#response-streaming - [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting ### Developer infrastructure @@ -789,10 +789,10 @@ Notes - `@app.on_request` - `@app.on_response` - Fixes `Allow` header that did not include `HEAD` -- Using "name" keyword in `url_for` for a "static" route where +- Using \"name\" keyword in `url_for` for a \"static\" route where name does not exist - Cannot have multiple `app.static()` without using the named param -- Using "filename" keyword in `url_for` on a file route +- Using \"filename\" keyword in `url_for` on a file route - `unquote` in route def (not automatic) - `routes_all` is tuples - Handler arguments are kwarg only @@ -982,7 +982,7 @@ Notes - [#1776](https://github.com/sanic-org/sanic/pull/1776) Bug fix for host parameter issue with lists - [#1842](https://github.com/sanic-org/sanic/pull/1842) Fix static - _handler pickling error + \_handler pickling error - [#1827](https://github.com/sanic-org/sanic/pull/1827) Fix reloader on OSX py38 and Windows - [#1848](https://github.com/sanic-org/sanic/pull/1848) Reverse @@ -1004,7 +1004,7 @@ Notes - [#1857](https://github.com/sanic-org/sanic/pull/1857) Adjust websockets version to setup.py - [#1869](https://github.com/sanic-org/sanic/pull/1869) Wrap - run()'s "protocol" type annotation in Optional[] + run()\'s \"protocol\" type annotation in Optional\[\] **Improved Documentation** @@ -1320,7 +1320,7 @@ This is a breaking change. - [#1477](https://github.com/sanic-org/sanic/pull/1477) Fix grammar in README.md - [#1489](https://github.com/sanic-org/sanic/pull/1489) Added - "databases" to the extensions list + \"databases\" to the extensions list - [#1483](https://github.com/sanic-org/sanic/pull/1483) Add sanic-zipkin to extensions list - [#1487](https://github.com/sanic-org/sanic/pull/1487) Removed link @@ -1383,9 +1383,9 @@ PyPI - Fix content length mismatch in windows and other platform - Fix Range header handling for static files (#1402) - Fix the logger and make it work (#1397) - - Fix type pikcle->pickle in multiprocessing test + - Fix type pikcle-\>pickle in multiprocessing test - Fix pickling blueprints Change the string passed in the - "name" section of the namedtuples in Blueprint to match the + \"name\" section of the namedtuples in Blueprint to match the name of the Blueprint module attribute name. This allows blueprints to be pickled and unpickled, without errors, which is a requirement of running Sanic in multiprocessing mode in @@ -1401,7 +1401,7 @@ PyPI **0.8.3** - Changes: - - Ownership changed to org 'sanic-org' + - Ownership changed to org \'sanic-org\' **0.8.0** @@ -1441,7 +1441,7 @@ PyPI - Documentation updates/fixups (multiple contributors) - Fixes: - Fix: auto_reload in Linux (Ashley Sommer) - - Fix: broken tests for aiohttp >= 3.3.0 (Ashley Sommer) + - Fix: broken tests for aiohttp \>= 3.3.0 (Ashley Sommer) - Fix: disable auto_reload by default on windows (abuckenheimer) - Fix (1143): Turn off access log with gunicorn (hqy) - Fix (1143): Turn off access log with gunicorn (hqy) @@ -1453,13 +1453,13 @@ PyPI - Fix (1231): memory leak - always release resource (Phillip Xu) - Fix (1221): make request truthy if transport exists (Raphael Deem) - - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) - - Fix failing tests for aiohttp>=3.1.0 (Ashley Sommer) + - Fix failing tests for aiohttp\>=3.1.0 (Ashley Sommer) + - Fix failing tests for aiohttp\>=3.1.0 (Ashley Sommer) - Fix (1158): default to auto_reload in debug mode (Raphael Deem) - Fix (1136): ErrorHandler.response handler call too restrictive (Julien Castiaux) - Fix: raw requires bytes-like object (cloudship) - - Fix (1120): passing a list in to a route decorator's host arg + - Fix (1120): passing a list in to a route decorator\'s host arg (Timothy Ebiuwhe) - Fix: Bug in multipart/form-data parser (DirkGuijt) - Fix: Exception for missing parameter when value is null From c1f6c645221f75fd06dbb4cf49aa621a547a0199 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 10:36:10 +0300 Subject: [PATCH 600/698] New translations logging.md (Japanese) --- .../ja/guide/best-practices/logging.md | 181 ++++++++++++++---- 1 file changed, 149 insertions(+), 32 deletions(-) diff --git a/guide/content/ja/guide/best-practices/logging.md b/guide/content/ja/guide/best-practices/logging.md index 4cfc2a3f19..09a90f0afa 100644 --- a/guide/content/ja/guide/best-practices/logging.md +++ b/guide/content/ja/guide/best-practices/logging.md @@ -2,8 +2,12 @@ Sanicはformat@@0(https://docs.python.org/3/howto/logging.html)に基づいてリクエストの異なるタイプのログ(アクセスログ、エラーログ)を行うことができます。 新しい設定を作成したい場合は、Pythonロギングに関する基本的な知識を持っている必要があります。 +But, don't worry, out of the box Sanic ships with some sensible logging defaults. デバッグモードであるかどうかに応じてログをフォーマットする `AutoFormatter` を使用します。 これを後で強制する方法をお見せします。 + ## クイックスタート +Let's start by looking at what logging might look like in local development. このために、Sanicが提供するデフォルトのロギング設定を使用し、開発モードでSanicを実行するようにします。 + .. 列:: ``` @@ -24,68 +28,182 @@ app = Sanic('logging_example') async def test(request): logger.info('Here is your log') return text('Hello World!') +``` +```` -if __name__ == "__main__": - app.run(debug=True, access_log=True) +.. 列:: + +``` +Because we are specifically trying to look at the development logs, we will make sure to run Sanic in development mode. ``` + +.. 列:: + +```` +```sh +sanic path.to.server:app --dev +``` ```` サーバーが実行されると、このようなログが表示されます。 -```text -[2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 -[2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] -``` +![Sanic Logging Start](/assets/images/logging-debug-start.png) サーバーにリクエストを送信すると、ログメッセージが出力されます。 -```text -[2021-01-04 15:26:28 +0200] [1929659] [INFO] ログ -[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: http://localhost:8000/ 200 -1 +![Sanic Logging Access](/assets/images/logging-debug-access.png) + +Some important points to note: + +- The default log level in **production** mode is `INFO`. +- The default log level in **debug** mode is `DEBUG`. +- When in **debug** mode, the log messages will not have a timestamp (except on access logs). +- Sanic will try to colorize the logs if the terminal supports it. If you are running in Docker with docker-compose, you may need to set `tty: true` in your `docker-compose.yml` file to see the colors. + +## Sanic's loggers + +Out of the box, Sanic ships with five loggers: + +| **Logger Name** | **Use Case** | +| ------------------ | ---------------------------------------------- | +| `sanic.root` | Used to log internal messages. | +| `sanic.error` | Used to log error logs. | +| `sanic.access` | Used to log access logs. | +| `sanic.server` | Used to log server logs. | +| `sanic.websockets` | Used to log websocket logs. | + +.. column:: + +``` +If you want to use these loggers yourself, you can import them from `sanic.log`. +``` + +.. column:: + +```` +```python +from sanic.log import logger, error_logger, access_logger, server_logger, websockets_logger + +logger.info('This is a root logger message') +``` +```` + +.. warning:: + +``` +Feel free to use the root logger and the error logger yourself. But, you probably don't want to use the access logger, server logger, or websockets logger directly. These are used internally by Sanic and are configured to log in a specific way. If you want to change the way these loggers log, you should change the logging configuration. +``` + +## Default logging configuration + +Sanic ships with a default logging configuration that is used when you do not provide your own. This configuration is stored in `sanic.log.LOGGING_CONFIG_DEFAULTS`. + +```python +{ + 'version': 1, + 'disable_existing_loggers': False, + 'loggers': { + 'sanic.root': {'level': 'INFO', 'handlers': ['console']}, + 'sanic.error': { + 'level': 'INFO', + 'handlers': ['error_console'], + 'propagate': True, + 'qualname': 'sanic.error' + }, + 'sanic.access': { + 'level': 'INFO', + 'handlers': ['access_console'], + 'propagate': True, + 'qualname': 'sanic.access' + }, + 'sanic.server': { + 'level': 'INFO', + 'handlers': ['console'], + 'propagate': True, + 'qualname': 'sanic.server' + }, + 'sanic.websockets': { + 'level': 'INFO', + 'handlers': ['console'], + 'propagate': True, + 'qualname': 'sanic.websockets' + } + }, + 'handlers': { + 'console': { + 'class': 'logging.StreamHandler', + 'formatter': 'generic', + 'stream': sys.stdout + }, + 'error_console': { + 'class': 'logging.StreamHandler', + 'formatter': 'generic', + 'stream': sys.stderr + }, + 'access_console': { + 'class': 'logging.StreamHandler', + 'formatter': 'access', + 'stream': sys.stdout + } + }, + 'formatters': { + 'generic': {'class': 'sanic.logging.formatter.AutoFormatter'}, + 'access': {'class': 'sanic.logging.formatter.AutoAccessFormatter'} + } +} ``` ## サイニックロガーの変更 +.. column:: + +``` 独自のロギング設定を使用するには、`logging.config.dictConfig` を使用するか、Sanic アプリを初期化する際に `log_config` を使用します。 +``` + +.. column:: +```` ```python app = Sanic('logging_example', log_config=LOGGING_CONFIG) if __name__ == "__main__": - app.run(access_log=False) + app.run(access_log=False) ``` +```` -.. tip:: FYI +.. column:: ``` -Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. - -This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. - -For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +But, what if you do not want to control the logging completely, just change the formatter for example? Here, we will import the default logging config and modify only the parts that we want to force (for example) to use the `ProdFormatter` all of the time. ``` -## 設定 +.. column:: -Sanic のデフォルトのロギング設定は `sanic.log.LOGGING_CONFIG_DEFAULTS` です。 +```` +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS -.. 列:: +LOGGING_CONFIG_DEFAULTS['formatters']['generic']['class'] = 'sanic.logging.formatter.ProdFormatter' +LOGGING_CONFIG_DEFAULTS['formatters']['access']['class'] = 'sanic.logging.formatter.ProdAccessFormatter' +app = Sanic('logging_example', log_config=LOGGING_CONFIG_DEFAULTS) ``` -There are three loggers used in sanic, and must be defined if you want to create your own logging configuration: +```` + +.. tip:: FYI -| **Logger Name** | **Use Case** | -|-----------------|-------------------------------| -| `sanic.root` | Used to log internal messages. | -| `sanic.error` | Used to log error logs. | -| `sanic.access` | Used to log access logs. | ``` +Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. -.. 列:: +This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. -### ログの形式 +For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +``` + +## Access logger additional parameters -Python(`asctime`, `levelname`, `message`)で提供されるデフォルトのパラメータに加えて、Sanicはアクセスロガーの追加パラメータを提供しています。 +Sanic provides additional parameters to the access logger. | ログのコンテキストパラメータ | パラメータの値 | Datatype | | -------------- | ------------------------------------ | -------- | @@ -93,9 +211,8 @@ Python(`asctime`, `levelname`, `message`)で提供されるデフォルトのパ | `request` | `request.method + " " + request.url` | `str` | | `status` | `response` | `int` | | `byte` | `len(response.body)` | `int` | +| `duration` | | `float` | -デフォルトのアクセスログ形式は以下の通りです: +## Legacy logging -```text -%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d -``` +Many logging changes were introduced in Sanic 24.3. The main changes were related to logging formats. If you prefer the legacy logging format, you can use the `sanic.logging.formatter.LegacyFormatter` and `sanic.logging.formatter.LegacyAccessFormatter` formatters. From 71b4b2d9d55c73d9fba34256d31241d77c937b9b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 10:36:11 +0300 Subject: [PATCH 601/698] New translations logging.md (Korean) --- .../ko/guide/best-practices/logging.md | 181 ++++++++++++++---- 1 file changed, 149 insertions(+), 32 deletions(-) diff --git a/guide/content/ko/guide/best-practices/logging.md b/guide/content/ko/guide/best-practices/logging.md index acc2791c88..629127030d 100644 --- a/guide/content/ko/guide/best-practices/logging.md +++ b/guide/content/ko/guide/best-practices/logging.md @@ -2,8 +2,12 @@ Sanic allows you to do different types of logging (access log, error log) on the requests based on the [Python logging API](https://docs.python.org/3/howto/logging.html). You should have some basic knowledge on Python logging if you want to create a new configuration. +But, don't worry, out of the box Sanic ships with some sensible logging defaults. Out of the box it uses an `AutoFormatter` that will format the logs depending upon whether you are in debug mode or not. We will show you how to force this later on. + ## Quick Start +Let's start by looking at what logging might look like in local development. For this, we will use the default logging configuration that Sanic provides and make sure to run Sanic in development mode. + .. column:: ``` @@ -24,68 +28,182 @@ app = Sanic('logging_example') async def test(request): logger.info('Here is your log') return text('Hello World!') +``` +```` + +.. column:: -if __name__ == "__main__": - app.run(debug=True, access_log=True) ``` +Because we are specifically trying to look at the development logs, we will make sure to run Sanic in development mode. +``` + +.. column:: + +```` +```sh +sanic path.to.server:app --dev +``` ```` After the server is running, you should see logs like this. -```text -[2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 -[2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] -``` +![Sanic Logging Start](/assets/images/logging-debug-start.png) You can send a request to server and it will print the log messages. -```text -[2021-01-04 15:26:28 +0200] [1929659] [INFO] Here is your log -[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: GET http://localhost:8000/ 200 -1 +![Sanic Logging Access](/assets/images/logging-debug-access.png) + +Some important points to note: + +- The default log level in **production** mode is `INFO`. +- The default log level in **debug** mode is `DEBUG`. +- When in **debug** mode, the log messages will not have a timestamp (except on access logs). +- Sanic will try to colorize the logs if the terminal supports it. If you are running in Docker with docker-compose, you may need to set `tty: true` in your `docker-compose.yml` file to see the colors. + +## Sanic's loggers + +Out of the box, Sanic ships with five loggers: + +| **Logger Name** | **Use Case** | +| ------------------ | ---------------------------------------------- | +| `sanic.root` | Used to log internal messages. | +| `sanic.error` | Used to log error logs. | +| `sanic.access` | Used to log access logs. | +| `sanic.server` | Used to log server logs. | +| `sanic.websockets` | Used to log websocket logs. | + +.. column:: + +``` +If you want to use these loggers yourself, you can import them from `sanic.log`. +``` + +.. column:: + +```` +```python +from sanic.log import logger, error_logger, access_logger, server_logger, websockets_logger + +logger.info('This is a root logger message') +``` +```` + +.. warning:: + +``` +Feel free to use the root logger and the error logger yourself. But, you probably don't want to use the access logger, server logger, or websockets logger directly. These are used internally by Sanic and are configured to log in a specific way. If you want to change the way these loggers log, you should change the logging configuration. +``` + +## Default logging configuration + +Sanic ships with a default logging configuration that is used when you do not provide your own. This configuration is stored in `sanic.log.LOGGING_CONFIG_DEFAULTS`. + +```python +{ + 'version': 1, + 'disable_existing_loggers': False, + 'loggers': { + 'sanic.root': {'level': 'INFO', 'handlers': ['console']}, + 'sanic.error': { + 'level': 'INFO', + 'handlers': ['error_console'], + 'propagate': True, + 'qualname': 'sanic.error' + }, + 'sanic.access': { + 'level': 'INFO', + 'handlers': ['access_console'], + 'propagate': True, + 'qualname': 'sanic.access' + }, + 'sanic.server': { + 'level': 'INFO', + 'handlers': ['console'], + 'propagate': True, + 'qualname': 'sanic.server' + }, + 'sanic.websockets': { + 'level': 'INFO', + 'handlers': ['console'], + 'propagate': True, + 'qualname': 'sanic.websockets' + } + }, + 'handlers': { + 'console': { + 'class': 'logging.StreamHandler', + 'formatter': 'generic', + 'stream': sys.stdout + }, + 'error_console': { + 'class': 'logging.StreamHandler', + 'formatter': 'generic', + 'stream': sys.stderr + }, + 'access_console': { + 'class': 'logging.StreamHandler', + 'formatter': 'access', + 'stream': sys.stdout + } + }, + 'formatters': { + 'generic': {'class': 'sanic.logging.formatter.AutoFormatter'}, + 'access': {'class': 'sanic.logging.formatter.AutoAccessFormatter'} + } +} ``` ## Changing Sanic loggers +.. column:: + +``` To use your own logging config, simply use `logging.config.dictConfig`, or pass `log_config` when you initialize Sanic app. +``` +.. column:: + +```` ```python app = Sanic('logging_example', log_config=LOGGING_CONFIG) if __name__ == "__main__": - app.run(access_log=False) + app.run(access_log=False) ``` +```` -.. tip:: FYI +.. column:: ``` -Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. - -This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. - -For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +But, what if you do not want to control the logging completely, just change the formatter for example? Here, we will import the default logging config and modify only the parts that we want to force (for example) to use the `ProdFormatter` all of the time. ``` -## Configuration +.. column:: -Sanic's default logging configuration is: `sanic.log.LOGGING_CONFIG_DEFAULTS`. +```` +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS -.. column:: +LOGGING_CONFIG_DEFAULTS['formatters']['generic']['class'] = 'sanic.logging.formatter.ProdFormatter' +LOGGING_CONFIG_DEFAULTS['formatters']['access']['class'] = 'sanic.logging.formatter.ProdAccessFormatter' +app = Sanic('logging_example', log_config=LOGGING_CONFIG_DEFAULTS) ``` -There are three loggers used in sanic, and must be defined if you want to create your own logging configuration: +```` + +.. tip:: FYI -| **Logger Name** | **Use Case** | -|-----------------|-------------------------------| -| `sanic.root` | Used to log internal messages. | -| `sanic.error` | Used to log error logs. | -| `sanic.access` | Used to log access logs. | ``` +Logging in Python is a relatively cheap operation. However, if you are serving a high number of requests and performance is a concern, all of that time logging out access logs adds up and becomes quite expensive. -.. column:: +This is a good opportunity to place Sanic behind a proxy (like nginx) and to do your access logging there. You will see a *significant* increase in overall performance by disabling the `access_log`. -### Log format +For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` +``` -In addition to default parameters provided by Python (`asctime`, `levelname`, `message`), Sanic provides additional parameters for access logger with. +## Access logger additional parameters + +Sanic provides additional parameters to the access logger. | Log Context Parameter | Parameter Value | Datatype | | --------------------- | ------------------------------------ | -------- | @@ -93,9 +211,8 @@ In addition to default parameters provided by Python (`asctime`, `levelname`, `m | `request` | `request.method + " " + request.url` | `str` | | `status` | `response` | `int` | | `byte` | `len(response.body)` | `int` | +| `duration` | | `float` | -The default access log format is: +## Legacy logging -```text -%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d -``` +Many logging changes were introduced in Sanic 24.3. The main changes were related to logging formats. If you prefer the legacy logging format, you can use the `sanic.logging.formatter.LegacyFormatter` and `sanic.logging.formatter.LegacyAccessFormatter` formatters. From b32c05753de10efc9243e72eb6f7c9db44063829 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 10:36:12 +0300 Subject: [PATCH 602/698] New translations logging.md (Chinese Simplified) --- .../zh/guide/best-practices/logging.md | 193 ++++++++++++++---- 1 file changed, 155 insertions(+), 38 deletions(-) diff --git a/guide/content/zh/guide/best-practices/logging.md b/guide/content/zh/guide/best-practices/logging.md index 0730e2e78e..28a3638a5e 100644 --- a/guide/content/zh/guide/best-practices/logging.md +++ b/guide/content/zh/guide/best-practices/logging.md @@ -2,8 +2,12 @@ Sanic 允许您根据[Python log, 错误日志](https://docs.python.org/3/howto/logging.html)对请求进行不同类型的日志(访问日志, 错误日志)。 如果您想要创建一个新的配置，您应该在 Python 日志记录中获得一些基本知识。 +But, don't worry, out of the box Sanic ships with some sensible logging defaults. 在方框中，它使用一个 `AutoFormatter` 来格式化日志，取决于您是否处于调试模式。 我们将告诉你如何稍后强制这个操作。 + ## 快速开始 +Let's start by looking at what logging might look like in local development. 为此，我们将使用 Sanic 提供的默认日志配置，并确保在开发模式中运行 Sanic。 + .. 列: ``` @@ -24,78 +28,191 @@ app = Sanic('logging_example') async def test(request): logger.info('Here is your log') return text('Hello World!') +``` +```` -if __name__ == "__main__": - app.run(debug=True, access_log=True) +.. 列: + +``` +Because we are specifically trying to look at the development logs, we will make sure to run Sanic in development mode. ``` + +.. 列: + +```` +```sh +sanic path.to.server:app --dev +``` ```` 在服务器运行后，你应该看到像这样的日志。 -```text -[2021-01-04 15:26:26 +0200] [1929659] [INFO] Goin' Fast @ http://127.0.0.1:8000 -[2021-01-04 15:26:26 +0200] [1929659] [INFO] Starting worker [1929659] -``` +![Sanic Logging Start](/assets/images/logging-debug-start.png) 您可以向服务器发送请求，它将打印日志消息。 -```text -[2021-01-04 15:26:28 +0200] [1929659] [INFO] Here is your log -[2021-01-04 15:26:28 +0200] - (sanic.access)[INFO][127.0.0.1:44228]: GET http://localhost:8000/ 200 -1 +![Sanic Logging Access](/assets/images/logging-debug-access.png) + +Some important points to note: + +- The default log level in **production** mode is `INFO`. +- The default log level in **debug** mode is `DEBUG`. +- When in **debug** mode, the log messages will not have a timestamp (except on access logs). +- Sanic will try to colorize the logs if the terminal supports it. If you are running in Docker with docker-compose, you may need to set `tty: true` in your `docker-compose.yml` file to see the colors. + +## Sanic's loggers + +Out of the box, Sanic ships with five loggers: + +| **Logger Name** | **Use Case** | +| ------------------ | ---------------------------------------------- | +| `sanic.root` | Used to log internal messages. | +| `sanic.error` | Used to log error logs. | +| `sanic.access` | Used to log access logs. | +| `sanic.server` | Used to log server logs. | +| `sanic.websockets` | Used to log websocket logs. | + +.. column:: + +``` +If you want to use these loggers yourself, you can import them from `sanic.log`. +``` + +.. column:: + +```` +```python +from sanic.log import logger, error_logger, access_logger, server_logger, websockets_logger + +logger.info('This is a root logger message') +``` +```` + +.. warning:: + +``` +Feel free to use the root logger and the error logger yourself. But, you probably don't want to use the access logger, server logger, or websockets logger directly. These are used internally by Sanic and are configured to log in a specific way. If you want to change the way these loggers log, you should change the logging configuration. +``` + +## Default logging configuration + +Sanic ships with a default logging configuration that is used when you do not provide your own. This configuration is stored in `sanic.log.LOGGING_CONFIG_DEFAULTS`. + +```python +{ + 'version': 1, + 'disable_existing_loggers': False, + 'loggers': { + 'sanic.root': {'level': 'INFO', 'handlers': ['console']}, + 'sanic.error': { + 'level': 'INFO', + 'handlers': ['error_console'], + 'propagate': True, + 'qualname': 'sanic.error' + }, + 'sanic.access': { + 'level': 'INFO', + 'handlers': ['access_console'], + 'propagate': True, + 'qualname': 'sanic.access' + }, + 'sanic.server': { + 'level': 'INFO', + 'handlers': ['console'], + 'propagate': True, + 'qualname': 'sanic.server' + }, + 'sanic.websockets': { + 'level': 'INFO', + 'handlers': ['console'], + 'propagate': True, + 'qualname': 'sanic.websockets' + } + }, + 'handlers': { + 'console': { + 'class': 'logging.StreamHandler', + 'formatter': 'generic', + 'stream': sys.stdout + }, + 'error_console': { + 'class': 'logging.StreamHandler', + 'formatter': 'generic', + 'stream': sys.stderr + }, + 'access_console': { + 'class': 'logging.StreamHandler', + 'formatter': 'access', + 'stream': sys.stdout + } + }, + 'formatters': { + 'generic': {'class': 'sanic.logging.formatter.AutoFormatter'}, + 'access': {'class': 'sanic.logging.formatter.AutoAccessFormatter'} + } +} ``` ## 正在更改 Sanic logger +.. column:: + +``` 要使用您自己的日志配置，只需使用 `logging.config.dictConfig`，或通过 `log_config` 来初始化Sanic 应用程序。 +``` + +.. column:: +```` ```python app = Sanic('logging_example', log_config=LOGGING_CONFIG) if __name__ == "__main__": - app.run(access_log=False) + app.run(access_log=False) ``` +```` -.. tip:: FYI +.. column:: ``` -在 Python 中登录是一个相对便宜的操作。 然而，如果你正在满足大量的请求，执行情况令人关切。 所有这些时间都增加了访问日志，费用都很高。 - -这是一个很好的机会，可以将 Sanic 放置在代理背后(如nginx)，并在那里进行访问日志。 您将通过禁用 `access_log` 来看到整体性能的大幅提高。 - -为了最佳生产性能，建议运行 Sanic，禁用了 `debug` 和 `access_log` ：`app.run(debug=False, access_log=False)` +But, what if you do not want to control the logging completely, just change the formatter for example? Here, we will import the default logging config and modify only the parts that we want to force (for example) to use the `ProdFormatter` all of the time. ``` -## 配置 +.. column:: -Sanic默认日志配置为：`sanic.log.LOGING_CONFIG_DEFAULTS`。 +```` +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS -.. 列: +LOGGING_CONFIG_DEFAULTS['formatters']['generic']['class'] = 'sanic.logging.formatter.ProdFormatter' +LOGGING_CONFIG_DEFAULTS['formatters']['access']['class'] = 'sanic.logging.formatter.ProdAccessFormatter' +app = Sanic('logging_example', log_config=LOGGING_CONFIG_DEFAULTS) ``` -有三名伐木者用于卫生系统。 如果您想要创建自己的日志配置，则必须定义： +```` + +.. tip:: FYI -| **日志名称** | **使用案例** | -|-----------------|-----------------------| -| `sanic。 oot` | 用于记录内部消息. -| `sanic.error` | 用于日志错误日志. | -| `sanic.access` | 用于日志访问日志 ``` +在 Python 中登录是一个相对便宜的操作。 然而，如果你正在满足大量的请求，执行情况令人关切。 所有这些时间都增加了访问日志，费用都很高。 -.. 列: +这是一个很好的机会，可以将 Sanic 放置在代理背后(如nginx)，并在那里进行访问日志。 您将通过禁用 `access_log` 来看到整体性能的大幅提高。 -### 日志格式 +为了最佳生产性能，建议运行 Sanic，禁用了 `debug` 和 `access_log` ：`app.run(debug=False, access_log=False)` +``` -除了Python提供的默认参数外(`asctime`, `levelname`, `message`)，Sanic还提供了访问日志的额外参数。 +## Access logger additional parameters -| 日志上下文参数 | 参数值 | Datatype | -| --------- | ----------------------------------- | -------- | -| `host` | `request.ip` | `str` | -| `request` | `request.methods + " + request.url` | `str` | -| `status` | `response` | `int` | -| `byte` | `len(response.body)` | `int` | +Sanic provides additional parameters to the access logger. -默认访问日志格式是： +| 日志上下文参数 | 参数值 | Datatype | +| ---------- | ----------------------------------- | -------- | +| `host` | `request.ip` | `str` | +| `request` | `request.methods + " + request.url` | `str` | +| `status` | `response` | `int` | +| `byte` | `len(response.body)` | `int` | +| `duration` | | `float` | -```text -%(asctime)s - (%(name)s)[%(levelname)s][%(host)s]: %(request)s %(message)s %(status)d %(byte)d -``` +## Legacy logging + +Many logging changes were introduced in Sanic 24.3. The main changes were related to logging formats. If you prefer the legacy logging format, you can use the `sanic.logging.formatter.LegacyFormatter` and `sanic.logging.formatter.LegacyAccessFormatter` formatters. From b65ca76fdf4c5593d0d1f57ebaf7495befcbba61 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 11:33:42 +0300 Subject: [PATCH 603/698] New translations logging.md (Japanese) --- .../ja/guide/best-practices/logging.md | 66 +++++++++---------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/guide/content/ja/guide/best-practices/logging.md b/guide/content/ja/guide/best-practices/logging.md index 09a90f0afa..052be98a3f 100644 --- a/guide/content/ja/guide/best-practices/logging.md +++ b/guide/content/ja/guide/best-practices/logging.md @@ -2,11 +2,11 @@ Sanicはformat@@0(https://docs.python.org/3/howto/logging.html)に基づいてリクエストの異なるタイプのログ(アクセスログ、エラーログ)を行うことができます。 新しい設定を作成したい場合は、Pythonロギングに関する基本的な知識を持っている必要があります。 -But, don't worry, out of the box Sanic ships with some sensible logging defaults. デバッグモードであるかどうかに応じてログをフォーマットする `AutoFormatter` を使用します。 これを後で強制する方法をお見せします。 +しかし、Sanicは、箱の中からいくつかの賢明なロギングデフォルトで出荷されます。 デバッグモードであるかどうかに応じてログをフォーマットする `AutoFormatter` を使用します。 これを後で強制する方法をお見せします。 ## クイックスタート -Let's start by looking at what logging might look like in local development. このために、Sanicが提供するデフォルトのロギング設定を使用し、開発モードでSanicを実行するようにします。 +まずは、ローカル開発におけるロギングの様子を見てみましょう。 このために、Sanicが提供するデフォルトのロギング設定を使用し、開発モードでSanicを実行するようにします。 .. 列:: @@ -34,7 +34,7 @@ async def test(request): .. 列:: ``` -Because we are specifically trying to look at the development logs, we will make sure to run Sanic in development mode. +開発ログを確認しようとしているので、Sanicを必ず開発モードで実行します。 ``` .. 列:: @@ -53,32 +53,32 @@ sanic path.to.server:app --dev ![Sanic Logging Access](/assets/images/logging-debug-access.png) -Some important points to note: +注意すべきいくつかの重要なポイント: -- The default log level in **production** mode is `INFO`. -- The default log level in **debug** mode is `DEBUG`. -- When in **debug** mode, the log messages will not have a timestamp (except on access logs). -- Sanic will try to colorize the logs if the terminal supports it. If you are running in Docker with docker-compose, you may need to set `tty: true` in your `docker-compose.yml` file to see the colors. +- **production** モードのデフォルトのログレベルは `INFO` です。 +- **debug** モードのデフォルトのログレベルは `DEBUG` です。 +- **debug** モードの場合、ログメッセージにタイムスタンプはありません(アクセスログを除く)。 +- Sanicはターミナルがそれをサポートしている場合、ログを色付けしようとします。 Docker で docker-compose を実行している場合は、`docker-compose.yml` ファイルに `tty: true` を設定して色を確認する必要があります。 -## Sanic's loggers +## Sanicのロガー -Out of the box, Sanic ships with five loggers: +サニック号には5つのロガーが搭載されています。 -| **Logger Name** | **Use Case** | -| ------------------ | ---------------------------------------------- | -| `sanic.root` | Used to log internal messages. | -| `sanic.error` | Used to log error logs. | -| `sanic.access` | Used to log access logs. | -| `sanic.server` | Used to log server logs. | -| `sanic.websockets` | Used to log websocket logs. | +| **Logger Name** | **ユースケース** | +| ------------------ | ------------------------ | +| `sanic.root` | 内部メッセージのログに使用されます。 | +| `sanic.error` | エラーログを記録するために使用されます。 | +| `sanic.access` | アクセスログを記録するために使用されます。 | +| `sanic.server` | サーバログのログに使用します。 | +| `sanic.websockets` | ウェブソケットのログを記録するために使用します。 | -.. column:: +.. 列:: ``` -If you want to use these loggers yourself, you can import them from `sanic.log`. +これらのロガーを自分で使いたい場合は、 `sanic.log` からインポートできます。 ``` -.. column:: +.. 列:: ```` ```python @@ -88,15 +88,15 @@ logger.info('This is a root logger message') ``` ```` -.. warning:: +.. 警告:: ``` -Feel free to use the root logger and the error logger yourself. But, you probably don't want to use the access logger, server logger, or websockets logger directly. These are used internally by Sanic and are configured to log in a specific way. If you want to change the way these loggers log, you should change the logging configuration. +ルートロガーとエラーロガーを自由に使用してください。 ただし、アクセスロガー、サーバーロガー、またはwebsocketsロガーを直接使用したくない場合があります。 これらはSanicによって内部で使用され、特定の方法でログインするように設定されています。 これらのロガーのログの方法を変更したい場合は、ログの設定を変更する必要があります。 ``` -## Default logging configuration +## デフォルトのログ設定 -Sanic ships with a default logging configuration that is used when you do not provide your own. This configuration is stored in `sanic.log.LOGGING_CONFIG_DEFAULTS`. +Sanic は、独自のロギング設定を提供しない場合に使用されるデフォルトのロギング設定を持っています。 この設定は `sanic.log.LOGGING_CONFIG_DEFAULTS` に保存されます。 ```python { @@ -155,13 +155,13 @@ Sanic ships with a default logging configuration that is used when you do not pr ## サイニックロガーの変更 -.. column:: +.. 列:: ``` 独自のロギング設定を使用するには、`logging.config.dictConfig` を使用するか、Sanic アプリを初期化する際に `log_config` を使用します。 ``` -.. column:: +.. 列:: ```` ```python @@ -172,13 +172,13 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列:: ``` -But, what if you do not want to control the logging completely, just change the formatter for example? Here, we will import the default logging config and modify only the parts that we want to force (for example) to use the `ProdFormatter` all of the time. +しかし、ロギングを完全に制御したくない場合は、例えばフォーマッタを変更してください。 ここでは、デフォルトのロギング設定をインポートし、常に`ProdFormatter`を使用するように強制する部分(例えば)のみを変更します。 ``` -.. column:: +.. 列:: ```` ```python @@ -201,9 +201,9 @@ This is a good opportunity to place Sanic behind a proxy (like nginx) and to do For optimal production performance, it is advised to run Sanic with `debug` and `access_log` disabled: `app.run(debug=False, access_log=False)` ``` -## Access logger additional parameters +## アクセスロガーの追加パラメータ -Sanic provides additional parameters to the access logger. +Sanicはアクセスロガーに追加のパラメータを提供します。 | ログのコンテキストパラメータ | パラメータの値 | Datatype | | -------------- | ------------------------------------ | -------- | @@ -213,6 +213,6 @@ Sanic provides additional parameters to the access logger. | `byte` | `len(response.body)` | `int` | | `duration` | | `float` | -## Legacy logging +## レガシーログ -Many logging changes were introduced in Sanic 24.3. The main changes were related to logging formats. If you prefer the legacy logging format, you can use the `sanic.logging.formatter.LegacyFormatter` and `sanic.logging.formatter.LegacyAccessFormatter` formatters. +Sanic 24.3では多くのロギング変更が導入されました。 主な変更点は、ロギングフォーマットに関連していました。 従来のログ形式を使用する場合は、`sanic.logging.formatter.LegacyFormatter.LegacyFormatter` と `sanic.logging.formatter.LegacyAccessFormatter` 形式を使用します。 From 626bb40a4062acec47ec8a137ed878ed7f4b4e1f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 11:36:07 +0300 Subject: [PATCH 604/698] New translations logging.md (Chinese Simplified) --- .../zh/guide/best-practices/logging.md | 96 +++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/guide/content/zh/guide/best-practices/logging.md b/guide/content/zh/guide/best-practices/logging.md index 28a3638a5e..7bab5b6990 100644 --- a/guide/content/zh/guide/best-practices/logging.md +++ b/guide/content/zh/guide/best-practices/logging.md @@ -2,11 +2,11 @@ Sanic 允许您根据[Python log, 错误日志](https://docs.python.org/3/howto/logging.html)对请求进行不同类型的日志(访问日志, 错误日志)。 如果您想要创建一个新的配置，您应该在 Python 日志记录中获得一些基本知识。 -But, don't worry, out of the box Sanic ships with some sensible logging defaults. 在方框中，它使用一个 `AutoFormatter` 来格式化日志，取决于您是否处于调试模式。 我们将告诉你如何稍后强制这个操作。 +但不要担心的是，沙尼克船在箱子里有一些合理的日志缺失。 在方框中，它使用一个 `AutoFormatter` 来格式化日志，取决于您是否处于调试模式。 我们将告诉你如何稍后强制这个操作。 ## 快速开始 -Let's start by looking at what logging might look like in local development. 为此，我们将使用 Sanic 提供的默认日志配置，并确保在开发模式中运行 Sanic。 +让我们首先看看本地开发中日志可能看起来像是什么。 为此，我们将使用 Sanic 提供的默认日志配置，并确保在开发模式中运行 Sanic。 .. 列: @@ -34,7 +34,7 @@ async def test(request): .. 列: ``` -Because we are specifically trying to look at the development logs, we will make sure to run Sanic in development mode. +因为我们正在特别试图查看发展记录，因此我们将确保在发展模式中运行萨尼克。 ``` .. 列: @@ -47,56 +47,56 @@ sanic path.to.server:app --dev 在服务器运行后，你应该看到像这样的日志。 -![Sanic Logging Start](/assets/images/logging-debug-start.png) +![Sanic Logging Star](/assets/images/logging-debug-start.png) 您可以向服务器发送请求，它将打印日志消息。 -![Sanic Logging Access](/assets/images/logging-debug-access.png) +![Sanic 日志Access](/assets/images/logging-debug-access.png) -Some important points to note: +需要注意的一些重要要点： -- The default log level in **production** mode is `INFO`. -- The default log level in **debug** mode is `DEBUG`. -- When in **debug** mode, the log messages will not have a timestamp (except on access logs). -- Sanic will try to colorize the logs if the terminal supports it. If you are running in Docker with docker-compose, you may need to set `tty: true` in your `docker-compose.yml` file to see the colors. +- **production** 模式下的默认日志级别是 `INFO` 。 +- **debug** 模式下的默认日志级别是 `DEBUG` 。 +- 在 **debug** 模式中，日志消息将没有时间戳(访问日志除外)。 +- 如果终端支持它，Sanic将尝试对日志进行颜色。 如果你正在Docker中使用docker-compose，你可能需要在你的`docker-compose.yml`文件中设置`tty：true`来查看颜色。 -## Sanic's loggers +## Sanic伐木者 -Out of the box, Sanic ships with five loggers: +在箱子里，有五艘伐木船的萨尼克船： -| **Logger Name** | **Use Case** | -| ------------------ | ---------------------------------------------- | -| `sanic.root` | Used to log internal messages. | -| `sanic.error` | Used to log error logs. | -| `sanic.access` | Used to log access logs. | -| `sanic.server` | Used to log server logs. | -| `sanic.websockets` | Used to log websocket logs. | +| **Logger Name** | **使用大小写** | +| ------------------ | --------------- | +| `sanic.root` | 用于记录内部消息。 | +| `sanic.error` | 用于记录错误日志。 | +| `sanic.access` | 用于日志访问日志。 | +| `sanic.server` | 用于记录服务器日志。 | +| `sanic.websockets` | 用于记录 Web 套接字日志。 | -.. column:: +.. 列: ``` -If you want to use these loggers yourself, you can import them from `sanic.log`. +如果你想要自己使用这些记录器，你可以从 `sanic.log`中导入它们。 ``` -.. column:: +.. 列: ```` ```python -from sanic.log import logger, error_logger, access_logger, server_logger, websockets_logger +来自sanic.log logger, error_logger, access_logger, server_logger, websockets_logger -logger.info('This is a root logger message') +logger.info('这是一个root logger message') ``` ```` -.. warning:: +.. 警告：: ``` -Feel free to use the root logger and the error logger yourself. But, you probably don't want to use the access logger, server logger, or websockets logger directly. These are used internally by Sanic and are configured to log in a specific way. If you want to change the way these loggers log, you should change the logging configuration. +请随时使用您自己的Root日志和错误日志。 但您可能不想直接使用访问日志、服务器记录器或Websockets记录器。 这些是由 Sanic 内部使用的，并被配置为以特定方式登录。 如果你想要更改这些日志记录的方式，你应该更改日志的配置。 ``` -## Default logging configuration +## 默认日志配置 -Sanic ships with a default logging configuration that is used when you do not provide your own. This configuration is stored in `sanic.log.LOGGING_CONFIG_DEFAULTS`. +当您不提供自己的时候，默认日志配置为 Sanic 飞船。 此配置存储在 `sanic.log.LOGGING_CONFIG_DEFAULTS` 中。 ```python { @@ -155,13 +155,13 @@ Sanic ships with a default logging configuration that is used when you do not pr ## 正在更改 Sanic logger -.. column:: +.. 列: ``` 要使用您自己的日志配置，只需使用 `logging.config.dictConfig`，或通过 `log_config` 来初始化Sanic 应用程序。 ``` -.. column:: +.. 列: ```` ```python @@ -172,22 +172,22 @@ if __name__ == "__main__": ``` ```` -.. column:: +.. 列: ``` -But, what if you do not want to control the logging completely, just change the formatter for example? Here, we will import the default logging config and modify only the parts that we want to force (for example) to use the `ProdFormatter` all of the time. +但是，如果你不想完全控制日志记录, 那么如何改变格式化程序？ 在这里，我们将导入默认的日志配置，并且只修改我们想要随时使用 "ProdFormatter" 的部件。 ``` -.. column:: +.. 列: ```` ```python -from sanic.log import LOGGING_CONFIG_DEFAULTS +from sanic.log import LOGING_CONFIGG_DEFAULTS -LOGGING_CONFIG_DEFAULTS['formatters']['generic']['class'] = 'sanic.logging.formatter.ProdFormatter' -LOGGING_CONFIG_DEFAULTS['formatters']['access']['class'] = 'sanic.logging.formatter.ProdAccessFormatter' +LOGING_CONFIG_DEFAULTS ['formations']['generic']['class'] = 'sanic.logging.formter.ProdFormatter' +LOGING_CONFIG_DEFAULTS['格式']['access']['class'] = 'sanic.logging.form.ter.ProdAccessFormatter' -app = Sanic('logging_example', log_config=LOGGING_CONFIG_DEFAULTS) +app = Sanic('logging_example', log_config=LOGING_CONFIG_FAULTS) ``` ```` @@ -201,18 +201,18 @@ app = Sanic('logging_example', log_config=LOGGING_CONFIG_DEFAULTS) 为了最佳生产性能，建议运行 Sanic，禁用了 `debug` 和 `access_log` ：`app.run(debug=False, access_log=False)` ``` -## Access logger additional parameters +## 访问记录器附加参数 -Sanic provides additional parameters to the access logger. +Sanic 为访问日志提供额外参数。 -| 日志上下文参数 | 参数值 | Datatype | -| ---------- | ----------------------------------- | -------- | -| `host` | `request.ip` | `str` | -| `request` | `request.methods + " + request.url` | `str` | -| `status` | `response` | `int` | -| `byte` | `len(response.body)` | `int` | -| `duration` | | `float` | +| 日志上下文参数 | 参数值 | Datatype | +| --------- | ----------------------------------- | -------- | +| `host` | `request.ip` | `str` | +| `request` | `request.methods + " + request.url` | `str` | +| `status` | `response` | `int` | +| `byte` | `len(response.body)` | `int` | +| `持续时间` | | `float` | -## Legacy logging +## 旧日志记录 -Many logging changes were introduced in Sanic 24.3. The main changes were related to logging formats. If you prefer the legacy logging format, you can use the `sanic.logging.formatter.LegacyFormatter` and `sanic.logging.formatter.LegacyAccessFormatter` formatters. +Sanic 24.3引入了许多伐木变化。 主要的变动与伐木格式有关。 如果你喜欢旧版日志格式，你可以使用 `sanic.logging.formter.LegacyFormatter` 和 `sanic.logging.formter.LegacyAccessFormatter` 格式。 From d6b10b701fb0aac78ee1eec76e7ead0f1f86bb6c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 18:57:06 +0300 Subject: [PATCH 605/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index 8c7c04184c..6e1ea40b3e 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -1,5 +1,5 @@ --- -title: 闪电般快速的异步 Python Web 框架 +title: 快如闪电的异步 Python Web 框架 layout: 首页 features: - title: 简单轻便 From 7ff0ed060e4a7417641d636685325449f93d3561 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 19:55:00 +0300 Subject: [PATCH 606/698] New translations help.md (Chinese Simplified) --- guide/content/zh/help.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/content/zh/help.md b/guide/content/zh/help.md index 103c969c62..0e315690c7 100644 --- a/guide/content/zh/help.md +++ b/guide/content/zh/help.md @@ -10,11 +10,11 @@ layout: 主界面 .. column:: ``` -### Discord :speech_cloon: +### Discord 💬 -快速答案与在线聊天的最好出处 +快速获取答案与在线聊天的最好去处 -[Discord 服务器]的 `#sanic-support` 频道(https://discord.gg/FARQzAEMAA) +[Discord 聊天室](https://discord.gg/FARQzAEMAA) 的 `#sanic-support` 频道 ``` .. column:: From 9f733f5a3a6feb944bd646bd663e269002ec7b98 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 19:55:02 +0300 Subject: [PATCH 607/698] New translations index.md (Chinese Simplified) --- guide/content/zh/index.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/guide/content/zh/index.md b/guide/content/zh/index.md index 6e1ea40b3e..714aa47bfe 100644 --- a/guide/content/zh/index.md +++ b/guide/content/zh/index.md @@ -3,20 +3,20 @@ title: 快如闪电的异步 Python Web 框架 layout: 首页 features: - title: 简单轻便 - details: 直观的 API 具有智能默认设置且无臃肿，让您可以直接开始构建应用程序。 + details: 直观、智能、精简的API，让您可以直接开始构建应用程序。 - title: 灵巧无束 - details: 按照您的意愿进行自由创建，不会对您造成任何约束 - - title: 易于拓展 - details: 关注应用的速度和可伸缩性 随时为大大小小的网络应用程序提供支持 + details: 可以用您自己的方式进行创作，不会对您造成任何约束 + - title: 高效且可拓展 + details: 关注应用的速度和可扩展性 随时为大大小小的网络应用程序提供支持 - title: 生产就绪 details: 开箱即用，Sanic 不仅是一个框架，也是一个服务器，并随时准备驱动您的 Web 应用 - title: 备受信赖 - details: Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步 Web 框架 + details: Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步python Web 框架 - title: 社区驱动 - details: 从社区来，到社区去。Sanic 由社区维护和管理 + details: 从社区来，到社区去。Sanic 由社区共同维护和管理 --- -### :hig_voltag: 闪电般快速的异步 Python Web 框架 +### ⚡ 快如闪电的异步 Python Web 框架 .. attrs:: :class: columns is-multiline mt-6 @@ -27,21 +27,21 @@ features: #### 简单轻便 - 直观的 API 具有智能默认设置且无臃肿，让您可以直接开始构建应用程序。 + 直观、智能、精简的API，让您可以直接开始构建应用程序。 .. attrs:: :class: column is-4 #### 灵巧无束 - 按照您的意愿进行自由创建，不会对您造成任何约束 + 可以用您自己的方式进行创作，不会对您造成任何约束 .. attrs:: :class: column is-4 - #### 易于拓展 + #### 高效且可拓展 - 关注应用的速度和可伸缩性，可随时为大大小小的网络应用程序提供支持 + 关注应用的速度和可扩展性，可随时为大大小小的网络应用程序提供支持 .. attrs:: :class: column is-4 @@ -55,14 +55,14 @@ features: #### 备受信赖 - Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步 Web 框架 + Sanic 是 PyPI 最受欢迎的框架之一，是顶级的异步python Web 框架 .. attrs:: :class: column is-4 #### 社区驱动 - 从社区来，到社区去。Sanic 由社区维护和管理 + 从社区来，到社区去。Sanic 由社区共同维护和管理 ``` .. attrs:: @@ -82,7 +82,7 @@ features: .. tab:: 生产级别（Production-grade） ```` -在安装后，Sanic 将为您提供开箱即用的可扩展生产级服务器所需的所有工具！ +开箱即用，在安装后，Sanic 为您提供创建高扩展性、生产级服务器需的所有工具！ 甚至包括[完整的 TLS 支持](/zh/guide/how-to/tls)。 @@ -149,14 +149,14 @@ async def feed(request: Request, ws: Websocket): .. tab:: 静态文件（Static files） ```` -建立静态文件服务当然是既直观又容易。只需配置一个入口并且指定一个文件或一个目录文件夹即可。 +为静态文件服务当然是既直观又容易。只需配置一个入口并且指定一个文件或一个目录文件夹即可。 ```python app.static("/", "/path/to/index.html") app.static("/uploads/", "/path/to/uploads/") ``` -此外，为目录提供服务还有两个附加功能：自动提供索引和自动提供文件浏览器。 +此外，当参数是目录时，还有两个附加功能：自动提供索引和自动提供文件浏览器。 Sanic 可以自动将 `index.html` (或任何其他命名文件) 作为目录或其子目录中的索引页。 @@ -168,7 +168,7 @@ app.static( ) ``` -之后，设置 Sanic 以显示文件浏览器。 +让 Sanic 以显示文件浏览器需要这样设置。 ![image](/assets/images/directory-view.png) From 25e9fc6be009e28455e99e16817bc8b840425dc9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 20:56:19 +0300 Subject: [PATCH 608/698] New translations app.md (Chinese Simplified) --- guide/content/zh/guide/basics/app.md | 194 +++++++++++++-------------- 1 file changed, 97 insertions(+), 97 deletions(-) diff --git a/guide/content/zh/guide/basics/app.md b/guide/content/zh/guide/basics/app.md index 4ad8beaf2a..1a0aacb5af 100644 --- a/guide/content/zh/guide/basics/app.md +++ b/guide/content/zh/guide/basics/app.md @@ -45,7 +45,7 @@ app.ctx.db = Database() ``` ```` -.. 列: +.. column:: ``` 虽然前面的示例可以工作并且具有说明性，但通常将对象在应用的开始或结束的生命周期里添加是比较合适的 @@ -63,7 +63,7 @@ async def attach_db(app, loop): ``` ```` -## App 注册表(App Registry) +## App 注册(App Registry) .. column:: @@ -90,45 +90,45 @@ app = Sanic.get_app("my_awesome_server") .. column:: ``` -If you call `Sanic.get_app("non-existing")` on an app that does not exist, it will raise :class:`sanic.exceptions.SanicException` by default. You can, instead, force the method to return a new instance of Sanic with that name. +如果您在不存在的应用程序上调用 Sanic.get_app("non-existing") ，默认情况下它将引发 :class:`sanic.exceptions.SanicException`。但是，您也可以强制该方法返回具有该名称的 Sanic 的新实例。 ``` -.. 列: +.. column:: ```` ```python app = Sanic.get_app( - "不存在", + "non-existing", force_create=True, ) ``` ```` -.. 列: +.. column:: ``` -如果有 **只有** 个Sanic 实例注册，那么调用 `Sanic.get_app()` 但没有参数将返回这个实例 +如果有 **只有** 一个Sanic 实例注册，那么调用 `Sanic.get_app()` 但没有参数将返回这个实例 ``` -.. 列: +.. column:: ```` ```python -Sanic("我唯一的应用") +Sanic("My only app") app = Sanic.get_app() ``` ```` -## 配置 +## 配置(Configuration) .. 列: ``` -Sanic 持有`Sanic` 实例的 `config` 属性中的配置。配置可以像字典一样使用 do-notation **OR** 进行修改。 +Sanic 将所有的配置文件存储在`Sanic`实例的`config`属性当中，你可以通过`.`点的方式或者直接把`Sanic.config`当作一个数组去修改配置 ``` -.. 列: +.. column:: ```` ```python @@ -137,7 +137,7 @@ app = Sanic('myapp') app.config.DB_NAME = 'appdb' app.config['DB_USER'] = 'appuser' -db_setting= { +db_settings = { 'DB_HOST': 'localhost', 'DB_NAME': 'appdb', 'DB_USER': 'appuser' @@ -146,54 +146,54 @@ app.config.update(db_settings) ``` ```` -.. 注：浮动通知 +.. note:: 注意一下 ```` -config key _should_ 是上层的，但这主要是通过公约进行的，小写将大部分时间起作用。 +通常来说，Config 的键应该是大写的，但是多数情况下，小写也能正常工作 ```python -app.config.GOD = "yay!" -app.config.bad = "board" +app.config.GOOD = "yay!" +app.config.bad = "boo" ``` ```` -稍后会有很多[更详细的配置](../running/configuration.md)。 +这里有更多关于配置的使用方法[更详细的配置](../running/configuration.md)。 -## 工厂模式 +## 工厂模式(Factory pattern) -Many of the examples in these docs will show the instantiation of the :class:`sanic.app.Sanic` instance in a file called `server.py` in the "global scope" (i.e. not inside a function). 这是非常简单的“hello world”风格应用程序的常见模式，但使用工厂模式往往是有益的。 +文档中大多数案例都是在`server.py`的顶层（不是在一个函数中）实例化Sanic这个对象 :class:`sanic.app.Sanic` 这是非常简单的“hello world”风格应用程序的常见形式，但使用工厂模式往往具有更高的扩展性。 "工厂" 只是一个函数返回你想要使用的对象的实例。 这允许您抽象对象的实例化, 但也可能使它更容易隔离应用程序实例。 -.. 列: +.. column:: ``` 超级简单的出厂模式看起来像这样： ``` -.. 列: +.. column:: ```` ```python # ./path/to/server.py -从.path.to.config 从.path.to.some中导入 Sanic -中导入MyConfig -lueprint导入bp +from sanic import Sanic +from .path.to.config import MyConfig +from .path.to.some.blueprint import bp def create_app(config=MyConfig) -> Sanic: app = Sanic("MyApp", config=config) - app. lueprint(bp) + app.blueprint(bp) return app ``` ```` -.. 列: +.. column:: ``` 当我们稍后开始运行 Sanic时，你会知道Sanic CLI 可以检测到这种模式并使用它来运行你的应用程序。 ``` -.. 列: +.. column:: ```` ```sh @@ -201,29 +201,29 @@ sanic path.to.server:create_app ``` ```` -## 自定义 +## 自定义(Customization) Sanic 应用程序实例可以通过各种不同的实例实例为您的应用程序需要量身定制的。 详情请查看[API 文档](/api/sanic.app)。 -### 自定义配置 +### 自定义配置(Custom configuration) -.. 列: +.. column:: ``` -This simplest form of custom configuration would be to pass your own object directly into that Sanic application instance +这种最简单的自定义配置形式是将您自己的对象直接传递到该 Sanic 应用程序实例中 -If you create a custom configuration object, it is *highly* recommended that you subclass the :class:`sanic.config.Config` option to inherit its behavior. You could use this option for adding properties, or your own set of custom logic. +如果您创建自定义配置对象，*强烈*建议您对 :class:`sanic.config.Config` 选项进行子类化以继承其行为。 您可以使用此选项添加属性或您自己的一组自定义逻辑。 -*Added in v21.6* +*在 v21.6 中添加* ``` -.. 列: +.. column:: ```` ```python -from sanic.config 导入配置 +from sanic.config import Config class MyConfig(Config): FOO = "bar" @@ -232,13 +232,13 @@ app = Sanic(..., config=MyConfig()) ``` ```` -.. 列: +.. column:: ``` 此功能的一个有用例子是如果您想使用一个格式不同于 [supported]的配置文件 (. /running/configuration.md#using-sanicupdateconfig)。 ``` -.. 列: +.. column:: ```` ```python @@ -274,17 +274,17 @@ app = Sanic(toml_config.APP_NAME, config=toml_config) ``` ```` -### 自定义环境 +### 自定义上下文 -.. 列: +.. column:: ``` -By default, the application context is a [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) that allows you to set any properties you want on it. However, you also have the option of passing any object whatsoever instead. +默认情况下，应用程序上下文是一个 [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace)，它允许您设置您想要的任何属性。 但是，您也可以选择传递任何对象。 -*Added in v21.6* +*在 v21.6 中添加* ``` -.. 列: +.. column:: ```` ```python @@ -305,72 +305,72 @@ app = Sanic(..., ctx=MyContext()) ### 自定义请求 -.. 列: +.. column:: ``` -有时有你自己的 `Request` 类并告诉Sanic 使用它而不是默认值是有帮助的。 一个例子是如果您想修改默认“请求”。 d`生成器。 +有时拥有自己的“Request”类会很有帮助，并告诉 Sanic 使用它而不是默认的。 一个例子是，如果您想修改默认的“request.id”生成器。 -... 注意：重要的 +.. note:: Important - 必须记住，您正在通过 *class* 而不是类的实例。 +重要的是要记住，您传递的是 *class* 而不是该类的实例。 ``` -.. 列: +.. column:: ```` ```python -导入时间 +import time -from sanic import Request, Sanic, 文本 +from sanic import Request, Sanic, text -class NanoSecondRequest(请求): - @classmethodology +class NanoSecondRequest(Request): + @classmethod def generate_id(*_): - 返回时间 ime_ns() + return time.time_ns() app = Sanic(..., request_class=NanoSecondRequest) @app.get("/") async def handler(request): - retext(str(request.id)) + return text(str(request.id)) ``` ```` -### 自定义错误处理程序 +### 自定义错误响应函数(Custom error handler) -.. 列: +.. column:: ``` -查看[异常处理](../best practices/exceptions.md#custom-error-handling) +查看[异常处理](../best practices/exceptions.md#custom-error-handling) 获取更多信息 ``` -.. 列: +.. column:: ```` ```python -来自病原体。 andlers 导入 ErrorHandler +from sanic.handlers import ErrorHandler class CustomErrorHandler(ErrorHandler): - def default(自己，请求，请求) 异常: - '' 处理错误, 没有分配给''' - # 你自定义错误处理逻辑。 .. - return super().default(请求，异常) + def default(self, request, exception): + ''' handles errors that have no error handlers assigned ''' + # You custom error handling logic... + return super().default(request, exception) app = Sanic(..., error_handler=CustomErrorHandler()) ``` ```` -### 自定义转储函数 +### 自定义dumps函数 -.. 列: +.. column:: ``` 有时可能需要或需要提供一个自定义函数来序列一个 JSON 数据对象。 ``` -.. 列: +.. column:: ```` ```python @@ -381,13 +381,13 @@ app = Sanic(__name__, dumps=dumps) ``` ```` -.. 列: +.. column:: ``` 或者，或许使用另一个库或创建您自己的库。 ``` -.. 列: +.. column:: ```` ```python @@ -397,9 +397,9 @@ app = Sanic("MyApp", dumps=dumps) ``` ```` -### 自定义负载函数 +### 自定义loads函数 -.. 列: +.. column:: ``` 类似于“dumps”，您也可以为反序列化数据提供自定义函数。 @@ -407,11 +407,11 @@ app = Sanic("MyApp", dumps=dumps) *添加于v22.9* ``` -.. 列: +.. column:: ```` ```python -from orjson import load +from orjson import loads app = Sanic("MyApp", loads=loads) ``` @@ -427,42 +427,42 @@ sanic.app.Sanic[sanic.config.Config, types.SimpleNamespace] 它指的是两种一般类型： -1. 第一个是配置对象的类型。 It defaults to :class:`sanic.config.Config`, but can be any subclass of that. +1. 第一个是配置对象的类型。 它默认为 :class: `sanic.config.Config`，但可以是它的任何子类。 2. 第二种是应用程序上下文的类型。 它默认了 [`SimpleNamespace()`](https://docs.python.org/3/library/types.html#types.SimpleNamespace)，但上面显示的 **任何对象** 。 让我们看看如何改变类型的一些例子。 -.. 列: +.. column:: ``` -Consider this example where we pass a custom subclass of :class:`sanic.config.Config` and a custom context object. +考虑这个示例，其中我们传递了 :class:`sanic.config.Config` 的自定义子类和自定义上下文对象。 ``` -.. 列: +.. column:: ```` ```python -从病原体导入Sanic -onfig importing config +from sanic import Sanic +from sanic.config import Config -clusive Config(Config): +class CustomConfig(Config): pass -appp = Sanic("test", config=CustomConfig()) -reenal_type(app) # N: 公开类型是 "sanic" pp.Sanic[main.CustomConfig, types.SimpleNamespace]" +app = Sanic("test", config=CustomConfig()) +reveal_type(app) # N: Revealed type is "sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace]" ``` ``` sanic.app.Sanic[main.CustomConfig, types.SimpleNamespace] ``` ```` -.. 列: +.. column:: ``` 同样，当传递自定义上下文对象时，类型将会改变以反映这一点。 ``` -.. 列: +.. column:: ```` ```python @@ -479,13 +479,13 @@ sanic.app.Sanic[sanic.config.Config, main.Foo] ``` ```` -.. 列: +.. column:: ``` 当然，您可以将配置和上下文设置为自定义类型。 ``` -.. 列: +.. column:: ```` ```python @@ -520,21 +520,21 @@ MyApp = TypeAlias("MyApp", Sanic[Config, MyContext]) ```python # ./path/to/listeners.py -from myapp.types importing MyApp +from myapp.types import MyApp def add_listeners(app: MyApp): - @app. efor_server_start + @app.before_server_start async def before_server_start(app: MyApp): - # 使用您完全输入的应用程序实例 - 正在等待应用。 tx.db.connect() + # do something with your fully typed app instance + await app.ctx.db.connect() ``` ```python # ./path/to/server.py -从 myapp.types 导入 MyApp -从myapp.context 从myapp 导入 MyContext -onfig importer MyConfig -from myapp.listeners importing add_listeners +from myapp.types import MyApp +from myapp.context import MyContext +from myapp.config import MyConfig +from myapp.listeners import add_listeners app = Sanic("myapp", config=MyConfig(), ctx=MyContext()) add_listeners(app) @@ -542,7 +542,7 @@ add_listeners(app) _添加于 v23.6_ -### 自定义已输入请求 +### 自定义request请求 Sanic还允许您自定义请求对象的类型。 如果您想要将自定义属性添加到请求对象，这是有用的， 或者能够访问您输入的应用程序实例的自定义属性。 @@ -562,7 +562,7 @@ sanic.request.Request[ 让我们看看如何改变类型的一些例子。 -.. 列: +.. column:: ``` 扩展到上面的完整示例，在这个示例中有一个自定义应用程序实例的类型别名， 我们还可以创建一个自定义请求类型，以便我们可以访问这些类型的注释。 @@ -570,7 +570,7 @@ sanic.request.Request[ 当然，您不需要输入别名才能工作。 我们只是在这里显示它们来削减显示的代码数量。 ``` -.. 列: +.. column:: ```` ```python @@ -586,7 +586,7 @@ def add_routes(app: MyApp): ``` ```` -.. 列: +.. column:: ``` 也许您有一个生成自定义上下文对象的自定义请求对象。 您可以输入注解来正确访问这些属性，如这里所示。 From 83ca5d6b0d23ce93b0dc9c5d19b8fa4e98e6263b Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 20:56:20 +0300 Subject: [PATCH 609/698] New translations getting-started.md (Chinese Simplified) --- guide/content/zh/guide/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/guide/getting-started.md b/guide/content/zh/guide/getting-started.md index df801cdb9b..5d122b120e 100644 --- a/guide/content/zh/guide/getting-started.md +++ b/guide/content/zh/guide/getting-started.md @@ -68,7 +68,7 @@ sanic server ## Sanic 拓展 -Sanic 致力于构建一个简洁且没有任何偏见的特征表。 该项目不想要求您以某种方式构建应用程序，并试图避免指定特定的开发模式。 有许多由社区构建和维护的第三方插件，用于添加不符合核心库要求的附加功能。 +Sanic 有意打造一个干净且不带偏见的功能列表。 该项目不想要求您以某种方式构建应用程序，并试图避免指定特定的开发模式。 有许多由社区构建和维护的第三方插件，用于添加不符合核心库要求的附加功能。 但是，为了**帮助API开发者**，Sanic 组织维护了一个名为[Sanic Extensions](../plugins/sanic-ext/getting-started.md)的官方插件，提供各种各样的常见解决方案，其中包括： @@ -97,7 +97,7 @@ pip install sanic sanic-ext ``` ```` -从 v21.12 开始，如果在相同的环境中，Sanic 将自动设置 Sanic 扩展。 您可以通过以下的两种方式来进行访问拓展功能: +从 v21.12 开始，如果处于同一环境中，Sanic 将自动安装 Sanic 扩展。 您可以通过以下的两个属性来进行访问拓展功能: - `app.extend()` - 用于配置 Sanic 扩展 - `app.ext` - 注入到应用程序的扩展实例 From 54ea9986fb81fa047abe466028377d54bed59e80 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Apr 2024 20:56:21 +0300 Subject: [PATCH 610/698] New translations introduction.md (Chinese Simplified) --- guide/content/zh/guide/introduction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/guide/introduction.md b/guide/content/zh/guide/introduction.md index adb87640ff..512cba8cc7 100644 --- a/guide/content/zh/guide/introduction.md +++ b/guide/content/zh/guide/introduction.md @@ -15,7 +15,7 @@ Sanic 是 Python3.8+ Web 服务器和 Web 框架，旨在提高性能。 它允 | Stats | [![Monthly Downloads](https://img.shields.io/pypi/dm/sanic.svg)](https://pepy.tech/project/sanic) [![Weekly Downloads](https://img.shields.io/pypi/dw/sanic.svg)](https://pepy.tech/project/sanic) [![Conda downloads](https://img.shields.io/conda/dn/conda-forge/sanic.svg)](https://anaconda.org/conda-forge/sanic) | ``` -## 什么是？ +## 是什么？(What is it?) 首先，在入坑之前， 您应该知道 Sanic 框架和其他的框架相比是与众不同的。 @@ -62,7 +62,7 @@ Sanic 不仅仅是一个**框架（framework）**，更是一个**服务器（we ## 加入社区 -讨论的主要渠道是[社区论坛](https://community.sanicframework.org/)。 还有一个 [Discord 服务器](https://discord.gg/RARQzAEMAA) 进行现场讨论和聊天。 +讨论的主要渠道是[社区论坛](https://community.sanicframework.org/)。 还有一个 [Discord 聊天室](https://discord.gg/RARQzAEMAA) 进行现场讨论和聊天。 Stackoverflow \`[sanic]' 标签由项目维护者[积极关注](https://stackoverflow.com/questions/tagged/sanic)。 From feffbe633f80a8ea25f1b2b0c1d75ea5168a5f15 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 12:04:33 +0300 Subject: [PATCH 611/698] New translations handlers.md (Chinese Simplified) --- guide/content/zh/guide/basics/handlers.md | 30 +++++++++++------------ 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/zh/guide/basics/handlers.md b/guide/content/zh/guide/basics/handlers.md index e6f1f5acb5..decf21db29 100644 --- a/guide/content/zh/guide/basics/handlers.md +++ b/guide/content/zh/guide/basics/handlers.md @@ -1,20 +1,20 @@ -# Handlers +# 响应函数(Handlers) -下一个重要的构件块是你的 _handlers_。 它们有时也被称为“视野”。 +下一个重要的构件块是你的 _handlers_。 它们有时也被称为“视图”。 -In Sanic, a handler is any callable that takes at least a :class:`sanic.request.Request` instance as an argument, and returns either an :class:`sanic.response.HTTPResponse` instance, or a coroutine that does the same. +在 Sanic 中，响应函数可以是任何一个可调用程序，它至少以一个 :class:`sanic.request.Request` 实例作为参数，并返回一个 :class:`sanic.response.HTTPResponse` 实例或一个执行其他操作的协同程序作为响应。 -.. 列: +.. column:: ``` -啊？😕 +嗯哼？😕 -是一个 **函数**; 要么同步，要么异步函数。 +响应函数仅仅是一个 **函数**，可以是同步的，也可以是异步的。 -处理程序的任务是响应一个端点并做一些事情。 这是您的大多数业务逻辑将要走的地方。 +响应函数的任务是响应一个请求入口并做一些数据操作。 这是您的大多数业务逻辑将要走的地方。 ``` -.. 列: +.. column:: ```` ```python @@ -26,15 +26,15 @@ async def i_am_ALSO_a_handler(request): ``` ```` -需要注意的另外两个重要项目： +还有另外两个点需要注意一下： -1. You almost _never_ will want to use :class:`sanic.response.HTTPresponse` directly. 使用[方便方法](./response#methods)非常简单。 +1. 你可以不用直接使用 :class:`sanic.response.HTTPresponse` 实例去返回数据 使用一些内置封装好的[返回函数](./response#methods)将会变的更加简单。 - - `从 sanic import json` - - `从 sanic import html` - - `从 Sanic 导入重定向` - - _等_ -2. 我们会在[串流部分](../advanced/streaming#response-streaming)中看到的，您并不总是需要返回一个对象。 如果您使用此较低级别的 API，您可以控制处理器内响应的流量，并且返回对象未被使用。 + - `from sanic import json` + - `from sanic import html` + - `from sanic import redirect` + - _etc_ +2. 我们会在[流媒体部分](../advanced/streaming#response-streaming)中看到的，您并不总是需要返回一个对象。 如果您使用此较低级别的 API，您可以控制处理器内响应的流量，并且返回对象未被使用。 .. 提示：浮动通知 From 12328f0a4cb660374e8d19663e060f5198bacaf3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 13:05:20 +0300 Subject: [PATCH 612/698] New translations handlers.md (Chinese Simplified) --- guide/content/zh/guide/basics/handlers.md | 102 +++++++++++----------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/guide/content/zh/guide/basics/handlers.md b/guide/content/zh/guide/basics/handlers.md index decf21db29..8eae6cd27f 100644 --- a/guide/content/zh/guide/basics/handlers.md +++ b/guide/content/zh/guide/basics/handlers.md @@ -28,36 +28,36 @@ async def i_am_ALSO_a_handler(request): 还有另外两个点需要注意一下： -1. 你可以不用直接使用 :class:`sanic.response.HTTPresponse` 实例去返回数据 使用一些内置封装好的[返回函数](./response#methods)将会变的更加简单。 +1. 你可以不用直接使用 :class:`sanic.response.HTTPresponse` 实例去返回数据 使用一些内置封装好的[便捷方法](./response#methods)，将会变的更加简单。 - `from sanic import json` - `from sanic import html` - `from sanic import redirect` - _etc_ -2. 我们会在[流媒体部分](../advanced/streaming#response-streaming)中看到的，您并不总是需要返回一个对象。 如果您使用此较低级别的 API，您可以控制处理器内响应的流量，并且返回对象未被使用。 +2. 我们会在[流媒体部分](../advanced/streaming#response-streaming)中看到的，您并不总是需要返回一个对象。 如果您使用这个底层的 API，您可以在处理程序内部控制响应的流程，并且不需要使用返回对象。 -.. 提示：浮动通知 +.. tip:: 提示 ``` -如果你想了解更多关于封装你的逻辑的信息，结帐[基于类的视图](../advanced/class-based-views.md)。现在，我们将继续只是基于函数的视图。 +如果你想了解更多关于封装逻辑的内容，可以查阅[基于类的视图](../advanced/class-based-views.md)。现在，我们将继续仅基于函数的视图讲解。 ``` -### 一个简单的基于功能的处理程序 +### 一个简单的基于函数的处理器 -创建路由处理程序的最常见方式是装饰函数。 它为路线定义建立简单的视觉标识。 我们将了解更多关于[路由](./routing.md) +创建路由处理程序的最常见方式是装饰函数。 它为路由定义创建了一个视觉上简洁的标识。 我们稍后将了解更多关于[路由](./routing.md) -.. 列: +.. column:: ``` -Let's look at a practical example. +让我们来看一个实际的例子。 -- We use a convenience decorator on our app instance: `@app.get()` -- And a handy convenience method for generating out response object: `text()` +- 我们在应用实例上使用了一个便捷装饰器：`@app.get()` +- 以及一个用于生成响应对象的便捷方法：`text()` -Mission accomplished 💪 +任务完成💪 ``` -.. 列: +.. column:: ```` ```python @@ -65,7 +65,7 @@ from sanic import text @app.get("/foo") async def foo_handler(request): - return text("我说了！") + return text("I said foo!") ``` ```` @@ -73,7 +73,7 @@ async def foo_handler(request): ## 关于 _async_... -.. 列: +.. column:: ``` 完全可以写入同步处理程序。 @@ -86,26 +86,26 @@ async def foo_handler(request): - 或大约**31.76** 请求/秒 ``` -.. 列: +.. column:: ```` ```python @app.get("/sync") def sync_handler(request): time.sleep(0.1) - return text("完成") + return text("Done.") ``` ```` -.. 列: +.. column:: ``` -Just by changing to the asynchronous alternative `asyncio.sleep()`, we see an incredible change in performance. 🚀 +只需将 `time.sleep()` 更改为异步替代方案 `asyncio.sleep()`，我们就能看到性能有了显著提升。 🚀 -Using the same four (4) worker processes: +同样使用四个（4）工作进程： -- **115,590** requests in 30.08s -- Or, about **3,843.17** requests/second +- 在30.08秒内处理了 **115,590** 个请求 +- 或者说，大约每秒处理 **3,843.17** 个请求 .. attrs:: :class: is-size-2 @@ -113,38 +113,38 @@ Using the same four (4) worker processes: 🤯 ``` -.. 列: +.. column:: ```` ```python @app.get("/async") async def async_handler(request): - 等待asyncio.sleep(0.1) - return text("完成") + await asyncio.sleep(0.1) + return text("Done.") ``` ```` -好的... 这是一个荒谬的过于戏剧性的结果。 你们所看到的任何基准都本质上是非常偏颇的。 这个示例是为了在网上显示`async/await`的好处。 结果肯定会有所不同。 诸如Sanic和其他异步Python图书馆之类的工具不是使事情变得更快的神奇子弹。 它们使它们更有效率。 +好的... 这是一个夸张得离谱的结果。 你们所看到的任何基准都本质上是非常偏颇的。 这个例子旨在极度展示`async/await`在web开发领域的优势。 结果肯定会有所不同。 像Sanic和其他异步Python库并非神奇的解决方案，能自动让程序运行更快。 它们使程序执行更加高效。 -在我们的例子中，异步版本要好得多，因为当一个请求正在睡觉时， 它能够开始另一个和另一个，以及另一个... +在我们的示例中，异步版本之所以表现优秀，是因为当一个请求在“睡眠”（等待）时，它可以开始处理另一个请求，然后再处理下一个、下一个、下一个……以此类推，实现并行处理多个请求，从而大大提高服务器的吞吐量。 -但这是要点！ 沙漠之所以迅速，是因为它需要现有的资源，并挤压了可用资源的业绩。 它可以同时处理许多请求，这意味着每秒要有更多的请求。 +但是，这就是关键所在！ Sanic之所以快，是因为它充分利用可用资源并榨取其性能潜力。 它可以同时处理大量请求，这就意味着每秒能够处理更多的请求。 -.. 提示：常见错误！ +.. 提示：一个常见的误区！ ``` -Don't do this! You need to ping a website. What do you use? `pip install your-fav-request-library` 🙈 +当你你需要对一个网站进行ping操作。你会用什么工具？`pip install 你最爱的请求库 `，我劝你不要这样做🙈 -Instead, try using a client that is `async/await` capable. Your server will thank you. Avoid using blocking tools, and favor those that play well in the asynchronous ecosystem. If you need recommendations, check out [Awesome Sanic](https://github.com/mekicha/awesome-sanic). +而应该尝试使用支持`async/await`功能的客户端。你的服务器会因此说`谢谢你`，避免使用阻塞型工具，尽量选择能良好适应异步生态系统中的工具。如果你需要推荐，可以查看[Awesome Sanic](https://github.com/mekicha/awesome-sanic).。 -Sanic uses [httpx](https://www.python-httpx.org/) inside of its testing package (sanic-testing) 😉. +Sanic在其测试包（sanic-testing）中使用了[httpx](https://www.python-httpx.org/) 😜。 ``` --- -## 一个完整注释的处理程序 +## 一个带完整注解的处理器 -对于那些使用类型注释的人... +对于那些使用类型注解的人... ```python from sanic.response import HTTPResponse, text @@ -155,45 +155,45 @@ async def typed_handler(request: Request) -> HTTPResponse: return text("Done.") ``` -## 命名您的处理程序 +## 为您的处理器命名 -所有处理程序都是自动命名的。 这对调试和生成模板中的 URL非常有用。 未指定时，将使用的名称是函数的名称。 +所有处理器都会自动命名。 这对于调试和在模板中生成URL非常有用。 如果不特别指定，将使用的名称就是函数的名 -.. 列: +.. column:: ``` 例如，这个处理程序将被命名为“foo_handler”。 ``` -.. 列: +.. column:: ```` ```python -# Handler 名称将是“foo_handler” +# Handler name will be "foo_handler" @app.get("/foo") async def foo_handler(request): - return text("我说了！") + return text("I said foo!") ``` ```` -.. 列: +.. column:: ``` -然而，你可以把`name`的参数传递给装饰师来覆盖这个问题。 +同样，您可以通过向装饰器传递`name`参数来指定名称。 ``` -.. 列: +.. column:: ```` ```python -# Handler 名称将是“foo” +# Handler name will be "foo" @app.get("/foo", name="foo") async def foo_handler(request): - return text("我说了！") + return text("I said foo!") ``` ```` -.. 列: +.. column:: ``` 事实上，正如你将要做的那样，可能有时候你**MUST** 提供一个名称。 例如，如果你在同一函数上使用两个装饰器，你需要为其中至少一个提供一个名称。 @@ -201,17 +201,17 @@ async def foo_handler(request): 如果您不这样做，您将会遇到一个错误，您的应用程序将不会启动。名称**必须** 在您的应用程序中是唯一的。 ``` -.. 列: +.. column:: ```` ```python -# 两个处理器，相同的函数， -# 不同的名字： +# Two handlers, same function, +# different names: # - "foo_arg" # - "foo" -@app。 et("/foo/", name="foo_arg") +@app.get("/foo/", name="foo_arg") @app.get("/foo") -异步脚(请求，arg=Non): - return text("我说了！") +async def foo(request, arg=None): + return text("I said foo!") ``` ```` From 1f3b1c622f740f503f381d15bc88a85272ce9792 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 16:54:53 +0300 Subject: [PATCH 613/698] New translations request.md (Chinese Simplified) --- guide/content/zh/guide/basics/request.md | 118 +++++++++++------------ 1 file changed, 58 insertions(+), 60 deletions(-) diff --git a/guide/content/zh/guide/basics/request.md b/guide/content/zh/guide/basics/request.md index 4cc6ada5cd..aa7409f023 100644 --- a/guide/content/zh/guide/basics/request.md +++ b/guide/content/zh/guide/basics/request.md @@ -1,76 +1,74 @@ -# 请求 +# 请求(Request) 查看 API 文档： [sanic.request](/api/sanic.request) -:class: `sanic.request.Request` 实例包含了许多有用的信息，这些信息可以在其参数中获得。 详情请参阅[API 文档](https://sanic.readthedocs.io/)。 +:class: `sanic.request.Request` 实例的参数中包含大量有用的信息。 详情请参阅[API 文档](https://sanic.readthedocs.io/)。 -正如我们在 [handlers](./handlers) 部分中所看到的，路由处理器的第一个参数通常是 :class:`sanic.request.Request` 对象。 因为Sanic是一个异步框架，处理器将在一个 [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) 内运行，并由事件循环调度。 这意味着处理器将在一个隔离的上下文中执行，并且请求对象对于该处理器是唯一的。 +正如我们在 [响应函数(Handlers)](./handlers) 部分中所看到的，路由处理器的第一个参数通常是 :class:`sanic.request.Request` 对象。 因为Sanic是一个异步框架，处理器将在一个 [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) 内运行，并由事件循环（event loop）调度。 这意味着处理器将在一个隔离的上下文中执行，并且请求对象（Rquest）将是该处理器任务所独有的。 -.. 列: +.. column:: ``` 按照惯例，参数被命名为`request`，但您可以根据需要随意命名。参数的名称并不重要。以下两个处理器的写法都是有效的。 ``` -.. 列: +.. column:: ```` ```python @app.get("/foo") async def typical_use_case(request): - return text("我说了！") + return text("I said foo!") ``` ```python -@app. et("/foo") +@app.get("/foo") async def atypical_use_case(req): - return text("我说了！") + return text("I said foo!") ``` ```` -.. 列: +.. column:: ``` -注释请求对象超级简单。 - +对请求的对象添加一个注解变的超级简单 ``` -.. 列: +.. column:: ```` ```python -来自sanic.request -from sanic.request import text +from sanic.request import Request +from sanic.response import text -@app.get("/输入") +@app.get("/typed") async def typed_handler(request: Request): - return text("完成") + return text("Done.") ``` ```` -.. tip:: +.. tip:: 提示 ``` -为了您的方便，假设您正在使用现代的集成开发环境（IDE），您应该利用类型注解来帮助代码自动完成和文档编写。这在使用request对象时尤为有用，因为它具有**许多**属性和方法。 +为了方便起见，假设您正在使用现代IDE，您应当利用类型注解来辅助完成代码提示和文档编写。这对于使用request对象时尤其有帮助，因为它具有**许多**属性和方法。 -要查看可用属性和方法的完整列表，请参阅[API文档] -(/api/sanic.request)。 +若要查看所有可用属性和方法的完整列表，请参阅 [API 文档](/api/sanic.request). ``` -## 正文内容 +## 请求体(Body) -`Request`对象允许您以几种不同的方式访问请求体的内容。 +`Request`对象允许您用以下几种不同的方式访问请求体的内容。 -### JSON +### JSON（json数据） -.. 列: +.. column:: ``` **参数**: `request.json` -**Description**: 已解析的 JSON 对象 +**描述**: 已解析的 JSON 对象 ``` -.. 列: +.. column:: ```` ```bash @@ -83,44 +81,44 @@ $ curl localhost:8000 -d '{"foo": "bar"}' ``` ```` -### 原始数据 +### Raw（原始数据） -.. 列: +.. column:: ``` **参数**: `request.body` **描述**: 请求正文中的原始字节 ``` -.. 列: +.. column:: ```` ```bash -$ curl localhost:8000 -d '{"foo": "bar"}" -``' +$ curl localhost:8000 -d '{"foo": "bar"}' +``` ```python ->> print(request.body) -b'{"foo": "bar"}" +>>> print(request.body) +b'{"foo": "bar"}' ``` ```` -### 形式 +### Form（表单数据） -.. 列: +.. column:: ``` -**Parameter**: `request.form` -**Description**: The form data +**参数**: `request.form` +**描述**: 表单数据 -.. tip:: FYI +.. tip:: 额外补充 - The `request.form` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. +`request.form`对象是几种类型之一，它是一个字典，其中每个值都是一个列表。这是因为HTTP协议允许单个键被重复用来发送多个值。 - Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +大多数情况下，您可能希望使用`.get()`方法访问第一个元素而不是一个列表。如果您确实需要所有项的列表，您可以使用`.getlist()`方法。 ``` -.. 列: +.. column:: ```` ```bash @@ -128,36 +126,36 @@ $ curl localhost:8000 -d 'foo=bar' ``` ```python ->> > print(request.body) +>>> print(request.body) b'foo=bar' ->> Print(request). orm) -{'foot': ['bar']} +>>> print(request.form) +{'foo': ['bar']} ->> Print(request.form.get("foo")) +>>> print(request.form.get("foo")) bar ->> Print(request.form.getlist("foo")) +>>> print(request.form.getlist("foo")) ['bar'] ``` ```` -### 上传完成 +### Uploaded（上传文件） -.. 列: +.. column:: ``` -**Parameter**: `request.files` -**Description**: The files uploaded to the server +**参数**: `request.files` +**描述**: 上传给服务器的文件数据 -.. tip:: FYI +.. tip:: 额外提示 - The `request.files` object is one of a few types that is a dictionary with each value being a list. This is because HTTP allows a single key to be reused to send multiple values. +`request.files`对象是一种字典类型的实例，其中每个值都是一个列表。这是由于HTTP协议允许单个键被重复用来发送多个文件。 - Most of the time you will want to use the `.get()` method to access the first element and not a list. If you do want a list of all items, you can use `.getlist()`. +大多数时候，您可能希望通过`.get()`方法获取并访问第一个文件对象而非整个列表。如果您确实需要获取所有文件项的列表，您可以使用`.getlist()`方法。 ``` -.. 列: +.. column:: ```` ```bash @@ -179,21 +177,21 @@ File(type='application/octet-stream', body=b'hello\n', name='TEST') ``` ```` -## 二. 背景 +## 上下文(Context) ### 请求上下文内容 -`request.ctx`对象是您的游戏场，可以存储您需要的关于请求的任何信息。 这只适用于请求的持续时间，是请求独有的。 +request.ctx 对象是存储请求相关信息的地方。 它仅在请求的生命周期内存在，并且是针对该请求独一无二的。 -这可以与所有请求共享的 `app.ctx` 对象混合。 请注意不要混淆他们！ +这与app.ctx对象形成了对比，后者是在所有请求间共享的。 务必注意不要混淆它们！ -默认情况下，`request.ctx`对象是 `SimpleNamespace`，允许您在它上设置任意属性。 Sanic将不会为任何东西使用此对象，所以你可以自由地使用它，不管你想不必担心名称冲突。 +默认情况下，request.ctx对象是一个SimpleNamespace对象，允许您在其上设置任意属性。 Sanic不会对此对象做任何用途，因此您可以自由地按照需要使用它，无需担心名称冲突问题。 ````python -### Typical use case +### 典型应用场景 -This is often used to store items like authenticated user details. We will get more into [middleware](./middleware.md) later, but here is a simple example. +这种做法常用于存储诸如认证用户详情之类的数据。我们将在后面的[middleware](./middleware.md)部分详细介绍，但这里先给出一个简单的示例。 ```python @app.on_request From 1cf643a85f271f05ab00af33d0f2ef2941a16259 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 18:02:48 +0300 Subject: [PATCH 614/698] New translations request.md (Chinese Simplified) --- guide/content/zh/guide/basics/request.md | 121 ++++++++++++----------- 1 file changed, 61 insertions(+), 60 deletions(-) diff --git a/guide/content/zh/guide/basics/request.md b/guide/content/zh/guide/basics/request.md index aa7409f023..c844b7381c 100644 --- a/guide/content/zh/guide/basics/request.md +++ b/guide/content/zh/guide/basics/request.md @@ -205,21 +205,22 @@ async def hi_my_name_is(request): return text(f"Hi, my name is {request.ctx.user.name}") ```` -正如你可以看到的那样，`请求'。 tx`对象是一个很好的地方来存储您需要在多个处理程序中访问的信息，使您的代码更加DRY和更容易维护。 但是，我们将在[中间件部分](./中间件部分)中学习。 您也可以使用它来存储来自一个中间件的信息，这些信息将用于另一个中间件中。 +如您所见，`request.ctx`对象是一个很好的位置，用于存储您需要在多个处理器中访问的信息，从而使您的代码更加遵循DRY原则（Don't Repeat Yourself），也更易于维护。 但是，正如我们在中间件章节中将要学习的那样，您还可以使用它来存储在一个中间件中产生的信息，这些信息将在另一个中间件中使用。 -### 连接环境 +### 连接上下文(Connection context) -.. 列: +.. column:: ``` -Often times your API will need to serve multiple concurrent (or consecutive) requests to the same client. This happens, for example, very often with progressive web apps that need to query multiple endpoints to get data. -The HTTP protocol calls for an easing of overhead time caused by the connection with the use of [keep alive headers](../deployment/configuration.md#keep-alive-timeout). +很多时候，您的API需要为同一客户端并发（或连续）处理多个请求。这种情况在需要查询多个端点以获取数据的渐进式Web应用程序中经常发生。 -When multiple requests share a single connection, Sanic provides a context object to allow those requests to share state. +HTTP协议要求通过使用 [保持连接头](../deployment/configuration.md#keep-alive-timeout).来减轻由连接引起的开销时间。 + +当多个请求共享单个连接时，Sanic提供了一个上下文对象，允许这些请求共享状态。 ``` -.. 列: +.. column:: ```` ```python @@ -242,25 +243,25 @@ request.conn_info.ctx.foo=3 ``` ```` -.. 警告：: +.. warning:: ``` -虽然这看起来是一个方便的地方来存储通过单个HTTP连接请求之间的信息。 不假设单个连接上的所有请求来自单个终端用户。 这是因为HTTP 代理和负载均衡器可以将多个多个连接连接到您的服务器。 +虽然对于通过单一HTTP连接在请求之间存储信息而言，这是一个便利的位置，但不要假定单个连接上的所有请求都来自同一个最终用户。这是因为HTTP代理和负载均衡器可能会将多个连接复用到单个到服务器的连接中。 -**DO Not** 使用它来存储有关单个用户的信息。为此使用 `request.ctx` 对象。 +**切勿** 使用此机制来存储关于单个用户的信息。为此目的应使用`request.ctx`对象。 ``` -### 自定义请求对象 +### 自定义请求对象(Custom Request Objects) -As dicussed in [application customization](./app.md#custom-requests), you can create a subclass of :class:`sanic.request.Request` to add additional functionality to the request object. 这有助于添加特定于您应用程序的附加属性或方法。 +正如在[自定义app](./app.md#custom-requests)部分讨论的那样，您可以创建:class:`sanic.request.Request`的一个子类，以向请求对象添加更多功能。 这对于添加专属于您的应用程序的额外属性或方法非常有用。 -.. 列: +.. column:: ``` -例如，请想象您的应用程序发送一个包含用户ID的自定义标题。 您可以创建一个自定义请求对象，解析该标头并为您存储用户 ID。 +例如，设想您的应用程序发送了一个包含用户ID的自定义头部。您可以创建一个自定义请求对象，它将解析该头部并将用户ID为您存储起来。 ``` -.. 列: +.. column:: ```` ```python @@ -275,7 +276,7 @@ app = Sanic("Example", request_class=CustomRequest) ``` ```` -.. 列: +.. column:: ``` 现在，您可以在处理器中访问 `user_id` 属性。 @@ -291,19 +292,19 @@ async def handler(request: CustomRequest): ``` ```` -### 自定义请求内容 +### 自定义请求上下文（Custom Request Context） -默认情况下，请求上下文(`request.ctx`) 是一个[`Simpenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) 对象，允许您在它上设置任意属性。 虽然这对于在您的应用程序中重新使用逻辑非常有用， 在发展经验中可能很困难，因为IDE将不知道有哪些属性。 +默认情况下，请求上下文(`request.ctx`) 是一个[`Simpenamespace`](https://docs.python.org/3/library/types.html#types.SimpleNamespace) 对象，允许您在它上设置任意属性。 尽管在整个应用程序中重用这一逻辑非常有助于提高效率，但在开发过程中可能会遇到困难，因为IDE无法知道有哪些可用的属性。 -为了帮助解决这个问题，您可以创建一个将被使用的自定义请求上下文对象，而不是默认的\`SimpleNamespace'。 这可以让您在上下文对象中添加提示并让它们在您的 IDE 中可用。 +为了解决这个问题，您可以创建一个自定义请求上下文对象，以替代默认的`SimpleNamespace`。 这样您可以在上下文对象中添加类型提示，并使其在您的IDE中可用。 -.. 列: +.. column:: ``` -Start by subclassing the :class:`sanic.request.Request` class to create a custom request type. Then, you will need to add a `make_context()` method that returns an instance of your custom context object. *NOTE: the `make_context` method should be a static method.* +首先，通过继承 :class:`sanic.request.Request` 类来创建自定义请求类型。接着，您需要添加一个 `make_context()` 方法，该方法返回您的自定义上下文对象实例。*注意：`make_context` 方法应为静态方法。* ``` -.. 列: +.. column:: ```` ```python @@ -325,59 +326,59 @@ class CustomContext: ``` ```` -.. 注： +.. note:: 注意 ``` -这是一个神秘的电源用户功能，它使得在大代码折叠中具有请求上下文对象变得非常方便。 当然，这是不需要的，但可能很有帮助。 +这是一个Sanic高级用户的特性，使得在大型代码库中拥有类型化的请求上下文对象变得极为方便。当然这不是必需的，但会非常有帮助。 ``` _添加于 v23.6_ -## 参数 +## 路径参数（Parameters） -.. 列: +.. column:: ``` -从路径参数中提取的值作为参数注入到处理程序中，或更具体地作为关键字参数注入。 [路由部分](./routing.md) 中有更多关于这一点的详细信息。 +从路径参数中提取的值会被注入到处理器作为参数，更具体地说，是以关键字参数的形式。关于这一点，在[路由章节](./routing.md)中有更多详细信息。 ``` -.. 列: +.. column:: ```` ```python @app.route('/tag/') -Async def tag_handler(请求，标签): - return text("Tag - {}"。 ormat(标签)) +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) -# 或明确作为关键词参数 -@app。 oute('/tag/') -async def tag_handler(请求, *, 标签): - return text("Tag - {}".format (tag)) +# or, explicitly as keyword arguments +@app.route('/tag/') +async def tag_handler(request, *, tag): + return text("Tag - {}".format(tag)) ``` ```` -## 参数 +## 查询参数（Arguments） 在 "request" 实例上有两个属性来获取查询参数： - `request.args` - `requery_args` -这些允许您访问请求路径中的查询参数(URL中`?`后面的部分)。 +这些让您能够从请求路径中访问查询参数（URL中`?`号后面的部分）。 -### 典型的使用情况 +### 典型应用场景 -在大多数情况下，您将想使用 `request.args` 对象来访问查询参数。 这将是解析的查询字符串。 +在大多数情况下，您将想使用 `request.args` 对象来访问查询参数。 它是解析后的查询字符串，存储为一个字典。 -这是迄今最常见的模式。 +迄今为止，这是最常见的模式。 -.. 列: +.. column:: ``` -考虑一个我们想要用来搜索某些东西的 `/search` 端点的例子。 +考虑这样一个示例：我们有一个带有`q`参数的`/search`路由入口，我们希望使用这个参数来进行搜索。 ``` -.. 列: +.. column:: ```` ```python @@ -392,51 +393,51 @@ async def search(request): ### 解析查询字符串 -但有时您可能想要以原始字符串或导管列表的形式访问查询字符串。 为此，您可以使用 `request.query_string` 和 `request.query_args` 属性。 +然而，在某些情况下，您可能希望以原始字符串形式或元组列表形式访问查询字符串。 为此，您可以使用`request.query_string` 和 `request.query_args` 属性。 -还应该注意的是，HTTP允许单个键的多个值。 虽然`request.args`看起来像一个常规字典，但它实际上是一种特殊的类型，允许一个单个键的多个值。 您可以使用 `request.args.getlist()` 方法访问这个。 +此外还应注意，HTTP协议允许单个键拥有多个值。 虽然`request.args`看起来像一个常规字典，但实际上它是一种特殊类型，允许单个键对应多个值。 您可以通过`request.args.getlist()`方法来访问这些多个值。 -- `requery_string` - 原始查询字符串 -- `requery_args` - 解析的查询字符串为导游列表 -- `request.args` - 解析的查询字符串为 _特殊_ 字典 - - `request.args.get()` - 获取关键字的第一个值 (像普通字典一样) - - `request.args.getlist()` - 获取所有键值 +- `request.query_string` - 原始查询字符串 +- `request.query_args` - 解析成元组的查询字符串 +- `request.args` - 解析成字典的查询字符串 + - `request.args.get()` - 获取查询参数中对应key的第一个值 (像普通字典一样) + - `request.args.getlist()` - 取查询参数中对应key的所有值（返回一个数组） ```sh curl "http://localhost:8000?key1=val1&key2=val2&key1=val3" ``` ```python ->>> Print(request.args) +>>> print(request.args) {'key1': ['val1', 'val3'], 'key2': ['val2']} ->> print(request.args.get("key1")) +>>> print(request.args.get("key1")) val1 ->> print(request.args. etlist("key1")) +>>> print(request.args.getlist("key1")) ['val1', 'val3'] ->> Print(request.query_args) +>>> print(request.query_args) [('key1', 'val1'), ('key2', 'val2'), ('key1', 'val3')] ->> > 打印(request.query_string) +>>> print(request.query_string) key1=val1&key2=val2&key1=val3 ``` -.. tip:: FYI +.. tip:: 额外提示 ``` -"request.args"对象是几种类型的字典之一，每个值都是一个列表。 这是因为HTTP允许重用单个键来发送多个值。 +`request.args`对象是一种字典类型的实例，其中每个值都是一个列表。这是由于HTTP协议允许单个参数名多次出现以传输多个值。 -大多数您想使用 `.get()` 方法访问第一个元素而不是列表的时间。 如果您确实想要列出所有项目，您可以使用 `.getlist()` 。 +大多数情况下，您可能希望使用`.get()`方法来获取并访问第一个元素而非整个列表。但如果确实需要获取所有项目组成的列表，您可以使用`.getlist()`方法。 ``` -## 当前请求获取 +## 获取当前请求对象 -有时您可能会在无法访问的地方发现您需要访问您的应用程序中的当前请求。 一个典型的例子可能是 `logging` 格式。 您可以使用 `Request.get_current()` 方法获取当前请求(如果有)。 +有时您可能会发现在应用程序中的某个位置无法直接访问当前请求， 比如在日志格式化时。 此时，您可以使用Request.get_current()来获取当前请求（如果需要的话）。 -记住，请求对象仅限于正在运行处理程序的单个[[asyncio.Task\`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task)。 如果你没有执行这项任务，没有请求对象。 +请记住，请求对象只限于运行处理器的那个单独的 [`asyncio.Task`](https://docs.python.org/3/library/asyncio-task.html#asyncio.Task) 内。 如果您不在那个任务中，就不会存在请求对象。 ```python import logging From 6fee2835f4c1ab833e292f06f5326659b10a7aa6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 18:02:49 +0300 Subject: [PATCH 615/698] New translations response.md (Chinese Simplified) --- guide/content/zh/guide/basics/response.md | 153 +++++++++++----------- 1 file changed, 76 insertions(+), 77 deletions(-) diff --git a/guide/content/zh/guide/basics/response.md b/guide/content/zh/guide/basics/response.md index e5fb104e35..5a64a3f32b 100644 --- a/guide/content/zh/guide/basics/response.md +++ b/guide/content/zh/guide/basics/response.md @@ -1,16 +1,16 @@ -# 答复 +# 响应(Response) -所有 [handlers](./handlers.md) _通常_返回一个响应对象， [middleware](./midd) 可以选择返回一个响应对象。 +所有 [handlers](./handlers.md) _通常_返回一个响应对象， [middleware](./midd) 可以选择是否返回一个响应对象。 -2. 澄清该陈述： +解释一下 -- unless the handler is a streaming endpoint handling its own pattern for sending bytes to the client, the return value must be an instance of :class:`sanic.response.HTTPResponse` (to learn more about this exception see [streaming responses](../advanced/streaming.md#response-streaming)). 在 **最多** 个案件中，您需要返回响应。 -- 如果中间件返回响应对象，这将被用来代替处理程序所做的任何(见 [middleware](./midd) 来了解更多)。 +- 除非处理器是一个流式响应，即发送字节到客户端模式的流式路由，否则返回值必须是:class:`sanic.response.HTTPResponse`类的实例（要了解更多关于这一例外情况，请参[阅流式响应](../advanced/streaming.md#response-streaming)） 否则，您需要返回一个响应。 +- 如果中间件确实返回了一个响应对象，则会使用该响应对象代替处理器原本的行为（更多细节请参阅 [中间件](./middleware.md) 部分）。 -最基本的处理程序看起来就像下面一样。 The :class:`sanic.response.HTTPResponse` object will allow you to set the status, body, and headers to be returned to the client. +一个最基本的处理器可能如下所示。 使用 :class:`sanic.response.HTTPResponse` 类对象，您可以设置要返回给客户端的状态码、主体内容以及头部信息。 ```python -从 HTTPResponse, Sanic +from sanic import HTTPResponse, Sanic app = Sanic("TestApp") @@ -19,22 +19,22 @@ def handler(_): return HTTPResponse() ``` -然而，通常较容易使用下文讨论的一种方便方法。 +然而，通常使用下文讨论的一些便捷方法更为简单。 -## 方法 +## 响应方式(Methods) -生成响应对象的最简单方法是使用一个方便函数。 +生成响应对象最简便的方式是使用以下便捷函数。 -### 文本 +### Text（文本） -.. 列: +.. column:: ``` -**默认内容类型**: `text/plain; charset=utf-8` +**默认Content-Type**: `text/plain; charset=utf-8` **描述**: 返回纯文本 ``` -.. 列: +.. column:: ```` ```python @@ -46,16 +46,16 @@ async def handler(request): ``` ```` -### HTML +### HTML（HTML） -.. 列: +.. column:: ``` -**默认内容类型**: `text/html; charset=utf-8` +**默认Content-Type**: `text/html; charset=utf-8` **描述**: 返回一个 HTML 文档 ``` -.. 列: +.. column:: ```` ```python @@ -67,16 +67,16 @@ async def handler(request): ``` ```` -### JSON +### JSON（JSON） -.. 列: +.. column:: ``` **默认 Content-Type**: `application/json` -**Description**: 返回 JSON 文档 +**描述**: 返回 JSON 数据 ``` -.. 列: +.. column:: ```` ```python @@ -88,9 +88,9 @@ async def handler(request): ``` ```` -默认情况下，是 [`ujson`](https://github.com/ultrajson/ultrajson)的 Sanic 船舶，作为其JSON 编码器。 如果未安装 `ujson` ，它将返回到标准库`json` 模块。 +默认情况下，Sanic 使用 [`ujson`](https://github.com/ultrajson/ultrajson) 作为其首选的 JSON 解析器。 如果`ujson`模块没有被安装，程序将会退回到使用标准库中的`json`模块。 -如果你想要更改这一点是非常简单的。 +想要改变默认的json解析器，非常简单 ```python from sanic import json @@ -99,24 +99,24 @@ from orjson import dumps json({"foo": "bar"}, dumps=dumps) ``` -您还可以声明在初始化时在全局使用哪些实现： +您还可以在初始化时全局声明在整个应用程序中使用哪个json解析器 ```python -从 orjson 导入转储 +from orjson import dumps -应用 = Sanic(..., dumps=dumps) +app = Sanic(..., dumps=dumps) ``` -### 文件 +### File（文件） -.. 列: +.. column:: ``` -**默认内容类型**：N/ +**默认Content-Type**：N/A **描述**：返回一个文件 ``` -.. 列: +.. column:: ```` ```python @@ -124,11 +124,11 @@ from sanic import file @app.route("/") async def handler(request): - return 等待文件 ("/path/to/whatever.png") + return await file("/path/to/whatever.png") ``` ```` -Sanic 将检查该文件，并尝试和猜其mime 类型并使用一个适当的内容类型值。 如果您想要： +Sanic 将会检查该文件，并尝试猜测其 MIME 类型，然后为内容类型使用合适的值。 如果您愿意，也可以明确指定： ```python file("/path/to/whatever.png", mime_type="image/png") @@ -137,19 +137,19 @@ file("/path/to/whatever.png", mime_type="image/png") 您也可以选择覆盖文件名称： ```python -file("/path/to/whatever.png", filename="超级超棒不可思议的.png") +file("/path/to/whatever.png", filename="super-awesome-incredible.png") ``` -### 文件流 +### File Streaming（文件流） -.. 列: +.. column:: ``` -**默认内容类型**: N/A +**默认Content-Type**: N/A **描述**: 流一个文件到一个客户端, 当像视频一样流出大文件时有用。 ``` -.. 列: +.. column:: ```` ```python @@ -161,18 +161,18 @@ async def handler(request): ``` ```` -和`file()`方法一样，`file_stream()`会尝试确定文件的 mime 类型。 +与 `file()` 方法类似，`file_stream()` 也会尝试确定文件的 MIME 类型。 -### 原始文件 +### Raw（原始数据） -.. 列: +.. column:: ``` **默认Content-Type**: `application/octet-stream` -**Description**: 发送原始字节而不对正文进行编码 +**描述**: 发送原始字节而不对正文进行编码 ``` -.. 列: +.. column:: ```` ```python @@ -180,24 +180,24 @@ from sanic import raw @app.route("/") async def handler(request): - return raw(B"raw bytes") + return raw(b"raw bytes") ``` ```` -### 重定向 +### Redirect（重定向） -.. 列: +.. column:: ``` **默认Content-Type**: `text/html; charset=utf-8` -**Description**: 发送一个 `302` 响应来将客户重定向到另一个路径 +**描述**: 发送一个 `302` 响应来将客户重定向到另一个URL ``` -.. 列: +.. column:: ```` ```python -from sanic import redirecte +from sanic import redirect @app.route("/") async def handler(request): @@ -205,61 +205,60 @@ async def handler(request): ``` ```` -### 空的 +### Empty（空返回） -.. 列: +.. column:: ``` -**默认 Content-Type**: N/A -**Description**: 为响应[RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) +**默认 Content-Type**: N/A +**描述**: 对于按照 [RFC 2616](https://tools.ietf.org/search/rfc2616#section-7.2.1) 规定响应空消息 ``` -.. 列: +.. column:: ```` ```python -来自sanic import 空 +from sanic import empty @app.route("/") async def handler(request): return empty() ``` -默认`204` 状态。 +默认的状态码是 `204` ```` -## 默认状态 +## Default Status（默认状态码） -响应默认的 HTTP 状态代码是 \`200'。 如果您需要更改它，它可以通过响应方式完成。 +响应默认的 HTTP 状态代码是 `200'。 如果您需要更改它，它可以通过在响应函数中传入指定的`status\`。 ```python @app.post("/") async def create_new(request): - new_thing = 等待do_create(request) + new_thing = await do_create(request) return json({"created": True, "id": new_thing.thing_id}, status=201) ``` -## 返回 JSON 数据 +## Returning JSON data（返回json数据） -Starting in v22.12, When you use the `sanic.json` convenience method, it will return a subclass of `HTTPResponse` called :class:`sanic.response.types.JSONResponse`. This object will -have several convenient methods available to modify common JSON body. +从 v22.12 版本开始，当您使用 `sanic.json` 的便捷方法时，它将返回一个名为 :class:`sanic.response.types.JSONResponse` 的 `HTTPResponse` 子类。 此对象将提供多个便捷方法来修改常见的 JSON 正文。 ```python -从沙尼导入 json +from sanic import json resp = json(...) ``` -- `resp.set_body()` - 设定JSON对象的正文到传递的值 -- `resp.append()` - 追加一个 `list.append` 这个物体的值(仅当root JSON 是一个数组时才起作用) -- `resp.extend()` - 将一个值扩展到物体像`list.extend` (仅当root JSON 是一个数组时才能工作) -- `resp.update()` - 更新像`dict.update` 这样的物体(仅当root JSON是一个对象时才工作) -- `resp.pop()` - 弹出一个 `list.pop` 或 `dict.pop` 等值(仅当root JSON 是数组或对象时才起作用) +- `resp.set_body()` - 将 JSON 对象的正文设置为传递的值 +- `resp.append()` - 向正文追加一个值，如同 `list.append`（仅当根 JSON 是数组时有效） +- `resp.extend()` - 将一个值扩展到正文中，如同 `list.extend`（仅当根 JSON 是数组时有效） +- `resp.update()` -使用类似 `dict.update` 的方式更新正文（仅当根 JSON 是对象时有效） +- `resp.pop()` - 移除并返回一个值，如同 `list.pop` 或 `dict.pop`（仅当根 JSON 是数组或对象时有效） -.. 警告：: +.. warning:: 警告⚠ ``` -原生的 Python 对象作为`raw_body` 存储在 `JSONResponse` 对象上。 虽然用新值覆盖此值是安全的，但是你应该**不应该**试图变换它。 你应该使用上面列出的方法。 +原始 Python 对象作为 `raw_body` 存储在 `JSONResponse` 对象上。虽然您可以安全地用新值覆盖这个值，但您应该**不要**尝试对其进行修改。相反，您应该使用上面列出的方法进行操作。 ``` ```python @@ -279,20 +278,20 @@ resp.raw_body.update({"something": "else"}) ``` ```python -# 或者，甚至将其视为列表 +# Or, even treat it like a list resp = json(["foo", "bar"]) -# 这是非常重要的 -resp. aw_body = ["foo", "bar", "something", "else"] +# This is OKAY +resp.raw_body = ["foo", "bar", "something", "else"] -# 这是更好的 -resp. xtend(["something", "else"]) +# This is better +resp.extend(["something", "else"]) -# 这也很适合 +# This is also works well resp.append("something") resp.append("else") -# 这不是很重要的 +# This is NOT OKAY resp.raw_body.append("something") ``` From 3d4a257dd724034beedd1b61fc68de1eca270beb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 21:24:20 +0300 Subject: [PATCH 616/698] New translations routing.md (Chinese Simplified) --- guide/content/zh/guide/basics/routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/basics/routing.md b/guide/content/zh/guide/basics/routing.md index 897911b1ef..742c5df593 100644 --- a/guide/content/zh/guide/basics/routing.md +++ b/guide/content/zh/guide/basics/routing.md @@ -1,4 +1,4 @@ -# 路由 +# 路由(Routing) .. 列: From e3db3d4deab39b8c709dd34a5e345d48394e6dd2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 22:36:57 +0300 Subject: [PATCH 617/698] New translations app.md (Chinese Simplified) --- guide/content/zh/guide/basics/app.md | 30 ++++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/guide/content/zh/guide/basics/app.md b/guide/content/zh/guide/basics/app.md index 1a0aacb5af..3c8ce82279 100644 --- a/guide/content/zh/guide/basics/app.md +++ b/guide/content/zh/guide/basics/app.md @@ -6,7 +6,7 @@ title: Sanic 应用程序 请参阅API文档： [sanic.app](/api/sanic.app) -## 实例(Instance) +## 实例（Instance） .. column:: @@ -28,7 +28,7 @@ app = Sanic("MyHelloWorldApp") ## 应用上下文(Application context) -大多数应用程序都需要跨代码库的不同部分共享/重用数据或对象。 Sanic 帮助在应用程序实例上提供 `ctx` 对象。 它是开发者附加应用整个生命周期中应该存在的任何对象或数据的可用空间。 +大多数应用程序都需要跨代码库的不同部分共享/重用数据或对象。 Sanic 帮助在应用程序实例上提供 `ctx` 对象。 它是开发者可以在应用程序整个生命周期中附加任何应存在的对象或数据的自由空间。 .. column:: @@ -68,7 +68,7 @@ async def attach_db(app, loop): .. column:: ``` -当您实例化一个 Sanic 实例时，它可以稍后从 Sanic 应用程序注册表中检索。 例如，如果您需要从无法访问的地方访问您的 Sanic 实例，这可能是有用的。 +当您实例化一个 Sanic 类时，它可以稍后从 `Sanic` 提供的方法`get_app()`中获取到这个实例。 例如，如果您需要从无法访问的地方访问您的 Sanic 实例，这可能是有用的。 ``` .. column:: @@ -90,7 +90,7 @@ app = Sanic.get_app("my_awesome_server") .. column:: ``` -如果您在不存在的应用程序上调用 Sanic.get_app("non-existing") ，默认情况下它将引发 :class:`sanic.exceptions.SanicException`。但是，您也可以强制该方法返回具有该名称的 Sanic 的新实例。 +如果您调用 Sanic.get_app("non-existing") 尝试去获取一个不存在的实例时，默认情况下它将引发 :class:`sanic.exceptions.SanicException`。但是，您也可以通过指定`force_create=True`强制该方法返回具有该名称的 Sanic 的新实例。 ``` .. column:: @@ -107,7 +107,7 @@ app = Sanic.get_app( .. column:: ``` -如果有 **只有** 一个Sanic 实例注册，那么调用 `Sanic.get_app()` 但没有参数将返回这个实例 +如果有 **只有** 一个Sanic 实例，那么不带参数，直接调用 `Sanic.get_app()` 将返回这个实例 ``` .. column:: @@ -167,7 +167,7 @@ app.config.bad = "boo" .. column:: ``` -超级简单的出厂模式看起来像这样： +一个简单的出厂模式看起来像这样： ``` .. column:: @@ -203,7 +203,7 @@ sanic path.to.server:create_app ## 自定义(Customization) -Sanic 应用程序实例可以通过各种不同的实例实例为您的应用程序需要量身定制的。 +在实例化阶段，可以根据您的应用程序需求以多种方式自定义 Sanic 应用程序实例。 详情请查看[API 文档](/api/sanic.app)。 @@ -235,7 +235,7 @@ app = Sanic(..., config=MyConfig()) .. column:: ``` -此功能的一个有用例子是如果您想使用一个格式不同于 [supported]的配置文件 (. /running/configuration.md#using-sanicupdateconfig)。 +此功能的一个有用例子是如，果您想使用一个格式不同于 [supported]的配置文件 (. /running/configuration.md#using-sanicupdateconfig)。 ``` .. column:: @@ -312,7 +312,7 @@ app = Sanic(..., ctx=MyContext()) -.. note:: Important +.. note:: 重点 重要的是要记住，您传递的是 *class* 而不是该类的实例。 ``` @@ -506,7 +506,7 @@ sanic.app.Sanic[main.CustomConfig, main.Foo] ``` ```` -如果您为应用程序实例创建一个自定义类型别名，以便您可以使用它来批注听器和处理器，此模式就特别有用。 +如果为应用程序实例创建了自定义类型别名，则这种模式特别有用，因为您可以使用它来注解监听器和处理器。 ```python # ./path/to/types.py @@ -544,7 +544,7 @@ _添加于 v23.6_ ### 自定义request请求 -Sanic还允许您自定义请求对象的类型。 如果您想要将自定义属性添加到请求对象，这是有用的， 或者能够访问您输入的应用程序实例的自定义属性。 +Sanic还允许您自定义请求对象的类型。 如果您想向请求对象添加自定义属性，或者能够访问具有类型的应用程序实例的自定义属性，这将非常有用。 Sanic 请求实例的正确、默认类型是： @@ -558,16 +558,16 @@ sanic.request.Request[ 它指的是两种一般类型： 1. 第一个是应用程序实例的类型。 默认为`sanic.app.Sanic[sanic.config.Config、types.SimpleNamespace]`，但可以是这个分类中的任何一个子类。 -2. 第二种是请求上下文的类型。 它默认了 `types.SimpleNamespace`，但可以在 [自定义请求](#custom-requests) 中显示**任何对象** 。 +2. 第二种是请求上下文的类型。 默认为`types.SimpleNamespace`，但可以是如上所示 [自定义请求](#custom-requests) 中的**任何对象**。 让我们看看如何改变类型的一些例子。 .. column:: ``` -扩展到上面的完整示例，在这个示例中有一个自定义应用程序实例的类型别名， 我们还可以创建一个自定义请求类型，以便我们可以访问这些类型的注释。 +在上述包含自定义应用程序实例类型别名的完整示例基础上，我们还可以创建自定义请求类型，以便访问相同的类型注解。 -当然，您不需要输入别名才能工作。 我们只是在这里显示它们来削减显示的代码数量。 +当然，要实现这一功能并不需要类型别名。此处仅展示它们是为了减少显示的代码量。 ``` .. column:: @@ -589,7 +589,7 @@ def add_routes(app: MyApp): .. column:: ``` -也许您有一个生成自定义上下文对象的自定义请求对象。 您可以输入注解来正确访问这些属性，如这里所示。 +也许您有一个生成自定义上下文对象的自定义请求对象。您可以像这里所示那样通过类型注解正确地使用 IDE 访问这些属性。 ``` .. 列: From 2b91f20dfa7b350b26174a0cac5cf7396f91eba8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Tue, 9 Apr 2024 22:36:58 +0300 Subject: [PATCH 618/698] New translations routing.md (Chinese Simplified) --- guide/content/zh/guide/basics/routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/basics/routing.md b/guide/content/zh/guide/basics/routing.md index 742c5df593..f49a1794bd 100644 --- a/guide/content/zh/guide/basics/routing.md +++ b/guide/content/zh/guide/basics/routing.md @@ -1,6 +1,6 @@ # 路由(Routing) -.. 列: +.. column:: ``` So far we have seen a lot of this decorator in different forms. From 0aeea4cfb5c872997237c8b08cbc8a49a2e78af9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 00:24:43 +0300 Subject: [PATCH 619/698] New translations handlers.md (Chinese Simplified) --- guide/content/zh/guide/basics/handlers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/zh/guide/basics/handlers.md b/guide/content/zh/guide/basics/handlers.md index 8eae6cd27f..19bacc42cb 100644 --- a/guide/content/zh/guide/basics/handlers.md +++ b/guide/content/zh/guide/basics/handlers.md @@ -196,9 +196,9 @@ async def foo_handler(request): .. column:: ``` -事实上，正如你将要做的那样，可能有时候你**MUST** 提供一个名称。 例如，如果你在同一函数上使用两个装饰器，你需要为其中至少一个提供一个名称。 +事实上，正如你将会遇到的情况，有时您**必须**提供名称。例如，如果您在同一函数上使用两个装饰器，那么至少需要为其中一个提供名称。 -如果您不这样做，您将会遇到一个错误，您的应用程序将不会启动。名称**必须** 在您的应用程序中是唯一的。 +如果不这样做，您将收到错误，并且您的应用将无法启动。在您的应用中，名称**必须**是唯一的。 ``` .. column:: From a95d4b92bc39fff671386c6f31dcbb400f91e45e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 00:24:44 +0300 Subject: [PATCH 620/698] New translations listeners.md (Chinese Simplified) --- guide/content/zh/guide/basics/listeners.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/basics/listeners.md b/guide/content/zh/guide/basics/listeners.md index e6b4d93883..b1eca2c3a2 100644 --- a/guide/content/zh/guide/basics/listeners.md +++ b/guide/content/zh/guide/basics/listeners.md @@ -1,4 +1,4 @@ -# 监听器 +# 监听器(Listeners) Sanic为您提供了八(8)个机会，将操作注入到您的应用程序服务器的生命周期。 这不包括 [signals](../advanced/signals.md)，它允许进一步的自定义注入。 From 73ce663eda33b317917f3d43a4a691b88dd59c23 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 00:24:45 +0300 Subject: [PATCH 621/698] New translations request.md (Chinese Simplified) --- guide/content/zh/guide/basics/request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/basics/request.md b/guide/content/zh/guide/basics/request.md index c844b7381c..5aaee24e08 100644 --- a/guide/content/zh/guide/basics/request.md +++ b/guide/content/zh/guide/basics/request.md @@ -31,7 +31,7 @@ async def atypical_use_case(req): .. column:: ``` -对请求的对象添加一个注解变的超级简单 +为请求的对象添加一个注解变是超级简单的 ``` .. column:: From 7e441b647230999aafc98ed60c32fd479a0c4c42 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 00:24:46 +0300 Subject: [PATCH 622/698] New translations routing.md (Chinese Simplified) --- guide/content/zh/guide/basics/routing.md | 478 +++++++++++------------ 1 file changed, 239 insertions(+), 239 deletions(-) diff --git a/guide/content/zh/guide/basics/routing.md b/guide/content/zh/guide/basics/routing.md index f49a1794bd..78dd721ba0 100644 --- a/guide/content/zh/guide/basics/routing.md +++ b/guide/content/zh/guide/basics/routing.md @@ -3,12 +3,12 @@ .. column:: ``` -So far we have seen a lot of this decorator in different forms. +至今为止，我们已经看到了这个装饰器的不同形式。 -But what is it? And how do we use it? +但它究竟是什么？以及我们应该如何使用它呢？ ``` -.. 列: +.. column:: ```` ```python @@ -25,50 +25,50 @@ But what is it? And how do we use it? ## 添加路由 -.. 列: +.. column:: ``` -The most basic way to wire up a handler to an endpoint is with `app.add_route()`. +将处理函数连接到路由入口的最基本方法是使用 `app.add_route()`。 -See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.Sanic.url_for) for more details. +详情请参考 [API 文档](https://sanic.readthedocs.io/en/stable/sanic/api_reference.html#sanic.app.Sanic.url_for) ``` -.. 列: +.. column:: ```` ```python -async def 处理器(请求): +async def handler(request): return text("OK") app.add_route(handler, "/test") ``` ```` -.. 列: +.. column:: ``` -默认情况下，路由是可用的 HTTP `GET` 调用。您可以更改处理程序来响应一个或多个HTTP方法。 +默认情况下，路由可通过 HTTP `GET` 请求访问。您可以更改处理函数，使其响应一种或多种 HTTP 方法。 ``` -.. 列: +.. column:: ```` ```python app.add_route( handler, '/test', - meths=["POST", "PUT", + methods=["POST", "PUT"], ) ``` ```` -.. 列: +.. column:: ``` -使用装饰符语法, 前面的示例与此相同。 +使用装饰器语法，前面的例子等同于下面这样。 ``` -.. 列: +.. column:: ```` ```python @@ -78,21 +78,21 @@ async def handler(request): ``` ```` -## HTTP 方法 +## HTTP 方法(HTTP methods) -每种标准HTTP方法都有一个方便装饰器。 +每种标准 HTTP 方法都有一个便捷的装饰器。 -### 获取 +### GET ```python @app.get('/test') -async def 处理器(请求): - 返回文本('OK') +async def handler(request): + return text('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/GET) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) -### 帖子 +### POST ```python @app.post('/test') @@ -100,14 +100,14 @@ async def handler(request): return text('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/POST) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) -### 弹出 +### PUT ```python @app.put('/test') -async def 处理器(请求): - 返回文本('OK') +async def handler(request): + return text('OK') ``` [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) @@ -116,109 +116,109 @@ async def 处理器(请求): ```python @app.patch('/test') -async def 处理器(请求): - 返回文本('OK') +async def handler(request): + return text('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/PATCH) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) -### 删除 +### DELETE ```python @app.delete('/test') -async def 处理器(请求): - 返回文本('OK') +async def handler(request): + return text('OK') ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/DELETE) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/DELETE) -### 黑色 +### HEAD ```python @app.head('/test') -async def 处理器(请求): +async def handler(request): return empty() ``` -[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTPMethods/HEAD) +[MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD) -### 选项 +### OPTIONS ```python @app.options('/test') -async def 处理器(请求): +async def handler(request): return empty() ``` [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) -.. 警告：: +.. warning:: 警告⚠ ```` -默认情况下，Sanic **只**在不安全的 HTTP 方法上消耗传入的请求机构：“POST`、`PUT`、`PATCH`、`DELETE`”。 如果您想要在 HTTP 请求中在任何其他方法上接收数据，， 您将需要做以下两个选项之一： +默认情况下，Sanic 只会在非安全 HTTP 方法（`POST`、`PUT`、`PATCH`、`DELETE`）上接受传入的请求正文。如果您想在任何其他方法上接收 HTTP 请求中的数据，您需要采取以下两种选项之一： -**选项#1 - 告诉Sanic使用`ignore_body`** +**选项 #1 - 使用 `ignore_body` 告诉 Sanic 去接受请求体** ```python -@app。 赤道("/path", ignore_body=False) +@app.request("/path", ignore_body=False) async def handler(_): ... ``` -**Option #2 - 手动使用 `receive_body`** +**选项 #2 - 在处理函数中手动使用 `receive_body` 接受请求体** ```python -@app. et("/path") -async def 处理器(请求: 请求): - 等待request.receive_body() +@app.get("/path") +async def handler(request: Request): + await request.receive_body() ``` ```` -## 路径参数 +## 路径参数（Path parameters） -.. 列: +.. column:: ``` -Sanic 允许模式匹配，也允许从 URL 路径中提取值。然后这些参数作为关键词参数在路由处理器中注入。 +Sanic 支持模式匹配，可以从 URL 路径中提取参数，并将这些参数作为关键字参数注入到路由处理函数中。 ``` -.. 列: +.. column:: ```` ```python @app.get("/tag/") -async def tag_handler(请求，标签): - return text("Tag - {}".form(标签)) +async def tag_handler(request, tag): + return text("Tag - {}".format(tag)) ``` ```` -.. 列: +.. column:: ``` -您可以声明参数类型。匹配时将强制执行，并且还将输入变量。 +您可以为参数声明一个类型。在匹配时，该类型将被强制执行，并且还会对该变量进行类型转换。 ``` .. 列: ```` ```python -@app.get("/fo/") +@app.get("/foo/") async def uuid_handler(request, foo_id: UUID): - return text("UUUID - {}".format (fo_id)) + return text("UUID - {}".format(foo_id)) ``` ```` -.. 列: +.. column:: ``` -对于一些标准类型，如`str`、`int`和`UUID`，Sanic可以从函数签名中推断路径参数类型。 这意味着可能并非总是需要在路径参数定义中包含类型。 +对于一些标准类型，如 `str`、`int` 和 `UUID`，Sanic 可以从函数签名中推断路径参数的类型。这意味着在路径参数定义中不一定总是需要包含类型。 ``` -.. 列: +.. column:: ```` ```python -@app。 et("/foo/") # 路径参数 -async def uuid_handler不存在:uuid (请求) foo_id: UUID: - return text("UUID - {}" ormat(fo_id)) +@app.get("/foo/") # Notice there is no :uuid in the path parameter +async def uuid_handler(request, foo_id: UUID): + return text("UUID - {}".format(foo_id)) ``` ```` @@ -226,139 +226,139 @@ async def uuid_handler不存在:uuid (请求) foo_id: UUID: ### `str` -.. 列: +.. column:: ``` -**Regular expression applied**: `r"[^/]+"` -**Cast type**: `str` -**Example matches**: +**正则表达式**: `r"[^/]+"` +**转换类型**: `str` +**匹配案例**: - `/path/to/Bob` - `/path/to/Python%203` -Beginning in v22.3 `str` will *not* match on empty strings. See `strorempty` for this behavior. +从 v22.3 版本开始，`str` 将不会匹配空字符串。对于这种行为，请参见 `strorempty`。 ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理器(请求, foo: str): +async def handler(request, foo: str): ... ``` ```` ### `strorempty` -.. 列: +.. column:: ``` -**Regular expression applied**: `r"[^/]*"` -**Cast type**: `str` -**Example matches**: +**正则表达式**: `r"[^/]*"` +**转换类型**: `str` +**匹配案例**: - `/path/to/Bob` - `/path/to/Python%203` - `/path/to/` -Unlike the `str` path parameter type, `strorempty` can also match on an empty string path segment. +与 `str` 路径参数类型不同，`strorempty` 也可以匹配空字符串路径段。 -*Added in v22.3* +*添加于 v22.3* ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理器(请求, foo: str): +async def handler(request, foo: str): ... ``` ```` ### `int` -.. 列: +.. column:: ``` -**正则表达式已应用**: `r"-?\d+" -**Cast 类型**: `int` -**示例匹配** : +**正则表达式**: `r"-?\d+"` +**转换类型**: `int` +**匹配案例**: - `/path/to/10` - `/path/to/-10` -_不匹配浮点, 十六进制, octal等_ +_不匹配浮点数(float)、十六进制(hex)、八进制(octal)等_ ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理器(请求, foo: int): +async def handler(request, foo: int): ... ``` ```` ### `float` -.. 列: +.. column:: ``` -**正则表达式已应用**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)" -**投射类型**: `float` -**示例匹配**: +**正则表达式**: `r"-?(?:\d+(?:\.\d*)?|\.\d+)"` +**转换类型**: `float` +**匹配案例**: - `/path/to/10` - `/path/to/-10` - `/path/to/1.5` ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理器(请求，foo: float): +async def handler(request, foo: float): ... ``` ```` ### `alpha` -.. 列: +.. column:: ``` -**正则表达式已应用**：`r'[A-Za-z]+"` -**快速类型**：`str` -**示例匹配**： +**正则表达式**: `r"[A-Za-z]+"` +**转换类型**: `str` +**匹配实例**: - `/path/to/Bob` - `/path/to/Python` -_不匹配数字， 或空格或其他特殊字符_ +_不匹配数字(digit)、空格(space )或其他特殊字符(special character)_ ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理器(请求, foo: str): +async def handler(request, foo: str): ... ``` ```` ### `slug` -.. 列: +.. column:: ``` -**正则表达式**：`r'[a-z0-9]+(?:-[a-z0-9]+)*" -**快速类型**：`str` -**示例匹配**： +**正则表达式**: `r"[a-z0-9]+(?:-[a-z0-9]+)*"` +**转换类型**: `str` +**匹配案例**: - `/path/to/some-news-story` - `/path/to/or-has-digits-123` @@ -366,167 +366,167 @@ Async def 处理器(请求, foo: str): *添加于v21.6* ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -async def 处理器(请求，文章: str): +async def handler(request, article: str): ... ``` ```` ### `path` -.. 列: +.. column:: ``` -**正则表达式已应用**: `r"[^/].*?" -**快速类型**: `str` -**示例匹配**: +**正则表达式**: `r"[^/].*?"` +**转换类型**: `str` +**匹配案例**: - `/path/to/hello` - `/path/to/hello.txt` - `/path/to/hello/world.txt` ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理器(请求, foo: str): +async def handler(request, foo: str): ... ``` ```` -.. 警告：: +.. warning:: 警告 ``` -因为这将在`/`上匹配， 你应该仔细和彻底地测试你使用`path`的模式，这样他们就不会捕获打算用于另一端点的流量。 此外，根据您如何使用这种类型，您可能会在应用程序中创建一条横向脆弱性。 你的任务是保护你的终点不受这种影响。 但如果您需要帮助，请在我们的社区频道中寻求帮助:) +由于 `path` 类型会匹配 `/` 符号，您应在使用 `path` 类型时务必小心，并彻底测试您的模式，以免捕获到原本打算发往其他端点的流量。另外，根据您如何使用这种类型，可能会在您的应用程序中引入路径遍历漏洞。防止此类漏洞是您的责任，但如有需要，请随时在我们的社区频道寻求帮助:) ``` ### `ymd` -.. 列: +.. column:: ``` -**正则表达式已应用**: `r"^([12]\d{3}( 0[1-9]|1[0-2])-( 0[1-9]|[12]\d|3[01])"" -**Cast类型**: `datetime. -**示例匹配**: +**正则表达式**: `r"^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))"` +**转换类型**: `datetime.date` +**匹配案例**: - `/path/to/2021-03-28` ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理程序(请求，foo: datetime.date): +async def handler(request, foo: datetime.date): ... ``` ```` ### `uuid` -.. 列: +.. column:: ``` -**Regular expression applied**: `r"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}"` -**Cast type**: `UUID` -**Example matches**: +**正则表达式**: `r"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}"` +**转换类型**: `UUID` +**匹配案例**: - `/path/to/123a123a-a12a-1a1a-a1a1-1a12a1a12345` ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理器(请求, foo: UUID): +async def handler(request, foo: UUID): ... ``` ```` ### ext -.. 列: +.. column:: ``` -**正则表达式**：n/a -**铸造类型**：*varies* -**示例匹配**： +**正则表达式**: n/a +**转换类型**: *varies* +**匹配案例**: ``` -.. 列: +.. column:: ```` ```python @app.route("/path/to/") -Async def 处理程序(请求，foo: str, ext: str): +async def handler(request, foo: str, ext: str): ... ``` ```` | 定义 | 示例 | 文件名 | 扩展 | | -------------------------------------------------------- | ----------------------------------------------------------- | -------- | --------------------------- | -| \file:ext | 页次 | `"page"` | `"txt"` | -| \file:ext=jpg | jpg | `"cat"` | \`"jpg"" | -| \file:ext=jpg\\\|png\\\|gif\\\|svg | jpg | `"cat"` | \`"jpg"" | +| \file:ext | page.txt | `"page"` | `"txt"` | +| \file:ext=jpg | cat.jpg | `"cat"` | \`"jpg"" | +| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | \`"jpg"" | | \ | 123.txt | `123` | `"txt"` | | \ | 123.svg | `123` | `"svg"` | | \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | -文件扩展名可以使用特殊的 `ext` 参数类型匹配。 它使用特殊格式，允许您指定其他类型的参数类型作为文件名。 和上面的示例表所示的一个或多个具体扩展。 +可以通过特殊的 ext 参数类型来匹配文件扩展名。 它采用一种特殊格式，允许您指定其他类型的参数作为文件名，并如上文示例表格所示，指定一个或多个特定扩展名。 -它不支持 `path` 参数类型。 +它**不支持** `path` 参数类型。 _添加于 v22.3_ ### 正则表达式 -.. 列: +.. column:: ``` -**正则表达式已应用**：_无论你插入了什么样的 -**投射类型**：`str` -**示例匹配**： +**正则表达式**: _whatever you insert_ +**转换类型**: `str` +**匹配案例**: - `/path/to/2021-01-01` -这使你能够自由地定义你使用的特定匹配模式。 +这样您就可以自由地为您的应用场景定义特定的匹配模式。 -在所显示的示例中，我们正在寻找一个 `YYYY-MM-DD` 格式的日期。 +在所示示例中，我们正在查找符合 `YYYY-MM-DD` 格式的日期。 ``` -.. 列: +.. column:: ```` ```python @app.route(r"/path/to/") -async def 处理程序(请求，foo: str): +async def handler(request, foo: str): ... ``` ```` ### 正则表达式匹配 -与复杂的路由相比，上述例子往往太简单， 我们使用完全不同的路由匹配模式，所以我们将在这里详细解释正则表达式匹配的高级用途。 +相比于复杂的路由，上述例子往往过于简单，我们采用了完全不同的路由匹配模式，因此这里将详细解释正则表达式匹配的高级用法。 -有时候你想要匹配路由的一部分： +有时，您可能只想匹配路由的一部分： ```text /image/123456789.jpg ``` -如果你想要匹配文件模式，但仅捕获数字部分，你需要做一些regex funn 😄: +如果你想要匹配包含文件模式，并仅捕获其中的数字部分，那么确实需要运用一些正则表达式的技巧 😄： ```python app.route(r"/image/\d+)\.jpg>") ``` -此外，所有这些都应当是可以接受的： +此外，所有以下这些匹配项也都是可以的： ```python @app.get(r"/") # matching on the full pattern @@ -535,81 +535,81 @@ app.route(r"/image/\d+)\.jpg>") @app.get(r"/[a-z]{3}).(?:txt)>") # defining a single named matching group, with one or more non-matching groups ``` -而且，如果使用一个命名匹配组，它必须与段标签相同。 +另外，如果使用命名匹配组，其名称必须与段标签相同。 ```python @app.get(r"/\d+).jpg>") # OK @app.get(r"/\d+).jpg>") # NOT OK ``` -更多常规使用方法，请参阅[正则表达式操作](https://docs.python.org/3/library/re.html) +有关更多常规正则表达式用法，请参考 [正则表达式操作](https://docs.python.org/3/library/re.html) 。 -## 正在生成 URL +## 动态访问(Generating a URL) -.. 列: +.. column:: ``` -Sanic 提供了一个基于处理方法名称：`app.url_for()`生成URL的方法。 如果你想要避免硬编码URL路径到你的应用，那么这将是有用的；相反，你只能引用处理程序名称。 +Sanic 提供了一种基于处理程序方法名称生成 URL 的方法：`app.url_for()`。当您希望避免在应用中硬编码 URL 路径时，这非常有用；您可以仅引用处理程序名称即可。 ``` -.. 列: +.. column:: ```` ```python -@app。 oute('/') +@app.route('/') async def index(request): - # 为端点 `post_handler` - url = app. rl_for('post_handler', post_id=5) + # generate a URL for the endpoint `post_handler` + url = app.url_for('post_handler', post_id=5) - # 重定向到 "/posts/5" + # Redirect to `/posts/5` return redirect(url) -@app. oute('/posts/') +@app.route('/posts/') async def post_handler(request, post_id): ... ``` ```` -.. 列: +.. column:: ``` -您可以传递任意数量的关键字参数。 任何为 _not_ 的请求参数都将作为查询字符串的一部分实现。 +您可以传递任意数量的关键字参数。任何不是请求参数的项都将作为查询字符串的一部分实现。 ``` -.. 列: +.. column:: ```` ```python -claim app.url_for( +assert app.url_for( "post_handler", post_id=5, arg_one="one", arg_two="two", -) =="/posts/5?arg_one=one&arg_two=two" +) == "/posts/5?arg_one=one&arg_two=two" ``` ```` -.. 列: +.. column:: ``` -还支持通过单个查询键的多个值。 +同样支持对单一查询键传入多个值。 ``` -.. 列: +.. column:: ```` ```python -claim app.url_for( +assert app.url_for( "post_handler", post_id=5, - arg_one=["one", "two", -) =="/posts/5?arg_one=one=one&arg_one=two" + arg_one=["one", "two"], +) == "/posts/5?arg_one=one&arg_one=two" ``` ```` ### 特殊关键字参数 -详见API Docs。 +See API 文档 for more details. ```python app.url_for("post_handler", post_id=5, arg_one="one", _anchor="anchor") @@ -628,15 +628,15 @@ app.url_for("post_handler", post_id=5, arg_one=["one", "two"], arg_two=2, _ancho # 'http://another_server:8888/posts/5?arg_one=one&arg_one=two&arg_two=2#anchor' ``` -### 自定义路由名称 +### 自定义路由名称(Customizing a route name) -.. 列: +.. column:: ``` -在注册路由时可以通过 `name` 参数使用自定义路由名称。 +可以通过在注册路由时传递 `name` 参数来自定义路由名称。 ``` -.. 列: +.. column:: ```` ```python @@ -646,13 +646,13 @@ def handler(request): ``` ```` -.. 列: +.. column:: ``` -现在，使用此自定义名称检索URL +现在，可以使用这个自定义名称来检索 URL。 ``` -.. 列: +.. column:: ```` ```python @@ -660,63 +660,63 @@ assert app.url_for("get_handler", foo="bar") == "/get?foo=bar" ``` ```` -## Websockets路由 +## Websockets 路由（Websockets routes） -.. 列: +.. column:: ``` -Websocket 路由器类似于HTTP方法。 +WebSocket 路由的工作方式与 HTTP 方法类似。 ``` -.. 列: +.. column:: ```` ```python -async def 处理器(请求) ws： +async def handler(request, ws): message = "Start" - 而True： - 等待w。 end(message) - message = 等待ws.recv() + while True: + await ws.send(message) + message = await ws.recv() app.add_websocket_route(handler, "/test") ``` ```` -.. 列: +.. column:: ``` -它还有一个方便装饰器。 +它还提供了一个便捷装饰器。 ``` -.. 列: +.. column:: ```` ```python @app.websocket("/test") -async def handler(request, w): +async def handler(request, ws): message = "Start" while True: - request ws.send(message) - message = 等待ws.recv() + await ws.send(message) + message = await ws.recv() ``` ```` -阅读[websockets部分](/guide/advanced/websockets.md)以了解如何工作的更多信息。 +请阅读[WebSocket 部分](/zh/guide/advanced/websockets.md)，了解更多关于它们如何工作的内容。 -## 严格斜线 +## 严格匹配分隔符(Strict slashes) -.. 列: +.. column:: ``` -Sanic 路由可以被配置为完全匹配是否存在尾随斜线： `/`。 这可以在几个级别上进行配置，按照这个先后顺序排列： +Sanic 路由可以根据 URL 是否包含尾部斜杠（/）进行严格的匹配配置。这一配置可以在以下几个层级进行，并遵循以下优先级顺序： -1。 Route -2. 蓝图 -3. 蓝图组 -4 应用程序 +1. 路由（Route） +2. 蓝图（Blueprint） +3. 蓝图组（BlueprintGroup） +4. 应用程序（Application） ``` -.. 列: +.. column:: ```` ```python @@ -755,42 +755,42 @@ group = Blueprint.group([bp1, bp2], strict_slashes=True) ``` ```` -## 静态文件 +## 静态文件(Static files) -.. 列: +.. column:: ``` -In order to serve static files from Sanic, use `app.static()`. +为了在 Sanic 中提供静态文件服务，请使用 `app.static()` 方法。 -The order of arguments is important: +参数的顺序很重要： -1. Route the files will be served from -2. Path to the files on the server +1. 文件将被服务的路由地址 +2. 服务器上的文件实际路径 -See [API docs](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic.static) for more details. +欲了解更多信息，请参阅 [API 文档](https://sanic.readthedocs.io/en/stable/sanic/api/app.html#sanic.app.Sanic.static)。 ``` -.. 列: +.. column:: ```` ```python -app.static("/static/", "/path/to/directory") +app.static("/static/", "/path/to/directory/") ``` ```` .. tip:: ``` -通常最佳做法是以斜杠结束您的目录路径(`/this/is/a/directory/`)。这会通过更明确地去除模糊性。 +通常最好以尾部斜杠（/）结束您的目录路径（如 `/this/is/a/directory/`）。这样做能够更明确地消除歧义。 ``` -.. 列: +.. column:: ``` -您也可以为个别文件服务。 +您也可以单独提供单个文件的服务。 ``` -.. 列: +.. column:: ```` ```python @@ -798,44 +798,44 @@ app.static("/", "/path/to/index.html") ``` ```` -.. 列: +.. column:: ``` -命名您的端点有时也是有用的 +有时为你指定入口提供一个名称也会有所帮助。 ``` -.. 列: +.. column:: ```` ```python app.static( "/user/uploads/", "/path/to/uploads/", - name="上传", + name="uploads", ) ``` ```` -.. 列: +.. column:: ``` -检索URL与处理程序相似。但当我们需要一个目录中的特定文件时，我们也可以添加 `filename` 参数。 +获取 URL 的工作方式与处理程序类似。但是，当我们需要获取目录中的特定文件时，还可以添加 `filename` 参数。 ``` -.. 列: +.. column:: ```` ```python -claim app.url_for( +assert app.url_for( "static", name="static", - filename="filename="文件。 xt", + filename="file.txt", ) == "/static/file.txt" ``` ```python -sapp. rl_for( +assert app.url_for( "static", - name="上传", + name="uploads", filename="image.png", ) == "/user/uploads/image.png" @@ -845,23 +845,23 @@ sapp. rl_for( .. tip:: ```` -如果你要多道`static()`路由，那么*强烈*建议你手动命名。 这几乎肯定会缓解发现缺陷的可能性。 +如果您打算设置多个 `static()` 路由，强烈建议您手动为它们命名。这样做几乎可以肯定能缓解潜在的难以发现的错误问题。 ```python -app.static("/user/uploads/", "/path/to/uploads/", name="上传") +app.static("/user/uploads/", "/path/to/uploads/", name="uploads") app.static("/user/profile/", "/path/to/profile/", name="profile_pics") ``` ```` -#### 自动索引服务 +#### 自动索引服务（Auto index serving） -.. 列: +.. column:: ``` -如果你有一个静态文件目录，应该通过索引页面来使用，你可以提供索引的文件名。 现在，当到达该目录 URL 时，索引页面将被服务。 +如果您有一目录静态文件应通过索引页面提供服务，您可以提供该索引页面的文件名。这样一来，当访问该目录 URL 时，系统将会自动提供索引页面服务。 ``` -.. 列: +.. column:: ```` ```python @@ -871,37 +871,37 @@ app.static("/foo/", "/path/to/foo/", index="index.html") _添加于 v23.3_ -#### 文件浏览器 +#### 文件浏览器（File browser） -.. 列: +.. column:: ``` -当使用静态处理器的目录时，Sanic可以被配置为显示基本文件浏览器，而不是使用 `directory_view=True`。 +当从静态处理器提供目录服务时，可以配置 Sanic 使用 `directory_view=True` 来显示一个基本的文件浏览器。 ``` -.. 列: +.. column:: ```` ```python app.static("/uploads/", "/path/to/dir", directory_view=True) - +``` ```` -您的浏览器现在有一个可浏览的目录： +现在您可以在 Web 浏览器中浏览该目录了： ![image](/assets/images/directory-view.png) _添加于 v23.3_ -## 路由环境 +## 路由上下文(Route context) -.. 列: +.. column:: ``` -当路由被定义时，您可以添加任何数量的关键字参数与 `ctx_` 前缀。 这些值将被注入到路由 `ctx` 对象中。 +在定义路由时，您可以添加任意数量以 `ctx_` 前缀的关键字参数。这些值将被注入到路由的 `ctx` 对象中。 ``` -.. 列: +.. column:: ```` ```python From 773ed2ccca94d5943d19a8ea2071479efc0533ba Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 10:24:30 +0300 Subject: [PATCH 623/698] New translations listeners.md (Chinese Simplified) --- guide/content/zh/guide/basics/listeners.md | 88 +++++++++++----------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/guide/content/zh/guide/basics/listeners.md b/guide/content/zh/guide/basics/listeners.md index b1eca2c3a2..8bf14799fc 100644 --- a/guide/content/zh/guide/basics/listeners.md +++ b/guide/content/zh/guide/basics/listeners.md @@ -1,76 +1,76 @@ # 监听器(Listeners) -Sanic为您提供了八(8)个机会，将操作注入到您的应用程序服务器的生命周期。 这不包括 [signals](../advanced/signals.md)，它允许进一步的自定义注入。 +Sanic 提供了八个（8）机会让您在应用程序服务器生命周期的不同阶段注入操作。 这还不包括[信号](../advanced/signals.md)，后者允许进一步自定义注入。 -在你的主要Sanic 进程上\*\*只运行两个(2)(每次通话一次) +有两个（2）**仅**在主 Sanic 进程中运行（即每次调用 `sanic server.app` 时运行一次）。 - `main_process_start` - `main_process_stop` -还有两（2）如果自动重新加载已打开，则只在读取过程中运行 \*\*。 +另外有两个（2）是在启用自动重载功能时**仅**在重载进程中运行的。 - `reload_process_start` - `reload_process_stop` \*在 v22.3中添加 `reload_process_start` 和 `reload_process_stop` \* -有四(4)使您能够在服务器启动或关闭时执行启动/拆解代码。 +还有四个（4）允许您在服务器启动(startup)或关闭(teardown )时执行启动/清理代码。 -- `befor_server_start` -- `After _server_start` +- `before_server_start` +- `after_server_start` - `before_server_stop` -- `After _server_stop` +- `after_server_stop` -工序的生命周期看起来就像这样： +工作者进程的生命周期如下所示： -.. mermaid: +.. mermaid:: ``` -序列图 +sequenceDiagram autonumber -参与进程 -参与员工 -参与者监听器 -参与者处理器 -进程注释：无声服务器。 pp -循环 - 进程->列表: @app。 ain_process_start - Listener->>>Handler: Invoke event manager +participant Process +participant Worker +participant Listener +participant Handler +Note over Process: sanic server.app +loop + Process->>Listener: @app.main_process_start + Listener->>Handler: Invoke event handler end -Process->> Workers: Run workers -roop starting each worker - roop - Worker->Listener: @app. efore_server_start - Listener->>>Handler: Invoke event handler - +Process->>Worker: Run workers +loop Start each worker + loop + Worker->>Listener: @app.before_server_start + Listener->>Handler: Invoke event handler + end Note over Worker: Server status: started - roop - Worker->Listener: @app. fter_server_start - Listener->>>Handler: Invoke Event Event + loop + Worker->>Listener: @app.after_server_start + Listener->>Handler: Invoke event handler end - Note over Worker: Server status: possible + Note over Worker: Server status: ready end -Process->Workers: Graceful shutdown -roop Stop each worker - roop - Worker->Listener: @app. efore_server_stop - Listener->>>Handler: Invoke event handler +Process->>Worker: Graceful shutdown +loop Stop each worker + loop + Worker->>Listener: @app.before_server_stop + Listener->>Handler: Invoke event handler end - Note over Worker: Server status: 停止 - 循环 - Worker->Listener: @app. fter_server_stop + Note over Worker: Server status: stopped + loop + Worker->>Listener: @app.after_server_stop Listener->>Handler: Invoke event handler - ender - Note over Work: Server status: closed + end + Note over Worker: Server status: closed end loop - Process->>Listener: @app. ain_process_stop - Listener->>>处理程序：Invoke 事件处理程序 -结尾 -进程注释：退出 + Process->>Listener: @app.main_process_stop + Listener->>Handler: Invoke event handler +end +Note over Process: exit ``` -读取器进程在这个工人进程之外生活在负责启动和停止萨尼克进程的进程内。 请考虑以下示例： +重新加载进程位于负责启动和停止 Sanic 进程的外部进程内，独立于上述工作者进程之外运行。 请看下面的例子： ```python @app.reload_process_start @@ -86,7 +86,7 @@ async def before_start(*_): print(">>>>>> before_start <<<<<<") ``` -如果此应用程序运行时启用自动重新加载功能，当读取器进程开始时将调用 "reload_start" 函数。 "main_start" 函数也会在主进程开始时调用。 **HOWEVER**，每次启动的工作流程将调用一次`before_start`函数， 并且随后每次保存一个文件并重启该工作人员。 +如果该应用程序在开启自动重载的情况下运行，当重新加载进程启动时，会调用一次 `reload_start` 函数。 当主进程启动时，`main_start` 函数也会被调用一次。 **然而**，`before_start` 函数会在每个启动的工作者进程中被调用一次，并且每当文件保存导致工作者进程重启时，也会再次调用。 ## 正在附加侦听器 From 95ed48072fc7940c5177e6f9d8dd1179b8edb4aa Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 12:09:08 +0300 Subject: [PATCH 624/698] New translations cookies.md (Chinese Simplified) --- guide/content/zh/guide/basics/cookies.md | 88 ++++++++++++------------ 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/guide/content/zh/guide/basics/cookies.md b/guide/content/zh/guide/basics/cookies.md index 464b955ccf..75fa3e2daa 100644 --- a/guide/content/zh/guide/basics/cookies.md +++ b/guide/content/zh/guide/basics/cookies.md @@ -1,14 +1,14 @@ -# Cookie +# Cookies -## 正在阅读 +## 读取(Reading) -.. 列: +.. column:: ``` -Cookie 可以通过 `Request` 对象的 `cookies` 字典访问。 +可以通过 `Request` 对象的 `cookies` 字典来访问 Cookies。 ``` -.. 列: +.. column:: ```` ```python @@ -19,72 +19,72 @@ async def test(request): ``` ```` -.. tip:: FYI +.. tip:: 提示一下 ``` -💡 "request.cookies"对象是几种类型的字典之一，每个值都是 "list"。 这是因为HTTP允许重用单个键来发送多个值。 +💡 `request.cookies` 对象是一种具有列表值的字典类型之一。这是因为在 HTTP 中，允许使用单个键重复以发送多个值。 -大部分时间你想使用 `.get()` 方法来访问第一个元素，而不是一个 `list` 。 如果你确实想要一个所有项目的 `list` ，你可以使用 `.getlist()` 。 +大部分情况下，您可能希望使用 `.get()` 方法获取第一个元素而不是一个 `list`。如果您确实需要所有项目组成的 `list`，可以使用 `.getlist()` 方法。 -*添加于v23.3* +*该功能在 v23.3 版本中添加* ``` -## 写入中 +## 写入(Writing) -.. 列: +.. column:: ``` -返回响应时，cookie可以在 "Response" 对象上设置: "response.cookies" 此对象是 `CookieJar` 的一个实例，这是一个特殊的词典，它将自动为您写出响应标题。 +在返回响应时，可以通过 `Response` 对象上的 `response.cookies` 设置 cookie。该对象是 `CookieJar` 类的一个实例，这是一种特殊类型的字典，它会自动为您写入响应头部信息。 ``` -.. 列: +.. column:: ```` ```python -@app。 oute("/cookie") +@app.route("/cookie") async def test(request): - response = text("在此响应中有cookie") - 响应。 dd_cookie( + response = text("There's a cookie up in this response") + response.add_cookie( "test", - "它正常工作! , - domain=". umyummy-cookie。 om", + "It worked!", + domain=".yummy-yummy-cookie.com", httponly=True - - 返回响应 + ) + return response ``` ```` -响应 cookie 可以设置为字典值，并且有以下参数可用： +响应中的 cookie 可以像设置字典值一样设置，并且具有以下可用参数： -- `路径：str` - 此 cookie 适用的 URL 的子集。 默认值为 `/`。 -- `domain: str` - 指定 cookie 有效的域名。 一个明确指定的域必须始终以点开始。 -- `max_age: int` - cookie 应该使用的秒数。 -- `过期：日期时间` - 客户端浏览器过期的 cookie 时间。 通常最好使用最大年龄。 -- `secure: bool` - 指定是否只能通过 HTTPS 发送 cookie 默认值为“True”。 -- `http：ool` - 指定 cookie 是否被 JavaScript 读取。 -- `samesite: str` - 可用值: Lax, Strict and None 默认为\`Lax'。 -- `comment: str` - 备注(metadata)。 -- `host_prefix: bool` - 是否将 `__Host-` 前缀添加到 cookie。 -- `secure_prefix: bool` - 是否将 `__Secure-` 前缀添加到 cookie。 -- `分区：bool` - 是否将 cookie 标记为分区。 +- `path: str` - 指定该 cookie 适用的 URL 子集， 默认为 `/`。 +- `domain: str` - 指定 cookie 有效的域名 。 显式指定的域名必须始终以点号开始。 +- `max_age: int` - 表示 cookie 应该存活的时间（秒）。 +- `expires: datetime` - 指定 cookie 在客户端浏览器上过期的时间。 通常最好使用 `max_age`。 +- `secure: bool` - 表示该 cookie 是否仅通过 HTTPS 发送， 默认为 `True`。 +- `httponly: bool` - 表示是否禁止 JavaScript 读取该 cookie 。 +- `samesite: str` - 可选值包括 Lax、Strict 和 None， 默认为\`Lax'。 +- `comment: str` - 用于提供 cookie 的注释（元数据）。 +- `host_prefix: bool` - 指定是否为 cookie 添加 __Host- 前缀。 +- `secure_prefix: bool` - 指定是否为 cookie 添加 __Secure- 前缀。 +- `partitioned: bool` - 表示是否标记该 cookie 为分区（partitioned）cookie。 -为了更好地理解这些数值的影响和用法，阅读[MDN文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)[setting cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie)可能会有帮助。 +为了更好地理解这些参数的作用和使用场景，阅读[MDN文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) 和 [关于设置cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie)的相关文档可能会有所帮助。 -.. tip:: FYI +.. tip:: 提示一下 ``` -默认情况下，Sanic会将 `secure` 标志设置为 `True` ，以确保只能通过 HTTPS 发送cookie 作为合理的默认值。 这不应对本地发展产生影响，因为通过 HTTP 提供安全的 cookie 仍应发送至 `localhost` 。 欲了解更多信息，您应该在[secure cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies)上阅读[MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure)。 +默认情况下，Sanic 会将 `secure` 标志设为 `True`，确保 cookie 只通过 HTTPS 安全传输，这是一个明智的默认设置。这对于本地开发来说一般不会有影响，因为在 HTTP 上安全的 cookie 仍然会被发送到 `localhost`。了解更多的信息，你可能需要阅读 [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies) 和 [安全 cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Secure). ``` -## 删除中 +## 删除(Deleting) -.. 列: +.. column:: ``` -Cookie 可以用语义或明确的方式移除。 +Cookie 可以通过语义化方式或明确方式移除。 ``` -.. 列: +.. column:: ```` ```python @@ -101,18 +101,18 @@ async def test(request): return response ``` -*Don't forget to add `path` or `domain` if needed!* +*别忘了在必要时添加 `path` 或 `domain`！* ```` -## 吃了 +## 食用(Eating) -.. 列: +.. column:: ``` -Sanic 喜欢cookie +Sanic 喜欢吃 cookies，给你也分一块！ ``` -.. 列: +.. column:: ``` .. attrs:: From 0d8355ab3a35c80002d86cfce594621ce57b3d3e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 12:09:09 +0300 Subject: [PATCH 625/698] New translations headers.md (Chinese Simplified) --- guide/content/zh/guide/basics/headers.md | 106 +++++++++++------------ 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/guide/content/zh/guide/basics/headers.md b/guide/content/zh/guide/basics/headers.md index f2f31c746a..b49b3d869f 100644 --- a/guide/content/zh/guide/basics/headers.md +++ b/guide/content/zh/guide/basics/headers.md @@ -1,26 +1,26 @@ -# 信头 +# 请求头(Headers) -请求和响应头分别在 `Request` 和 `HTTPResponse` 对象中可用。 他们使用 [`multidict` 包](https://multidict.readthocs.io/en/stable/multidict.html#cimultidict) 让单个键有多个值。 +请求和响应头分别在 `Request` 和 `HTTPResponse` 对象中起作用。 它们利用了 [multidict 包](https://multidict.readthedocs.io/en/stable/multidict.html#cimultidict)，该包允许单个键拥有多个值。 -.. tip:: FYI +.. tip:: 提示一下 ``` -解析后头键会转换为 *lowercase*。头部不考虑大小写。 +解析时，头部键会被转换为**小写**形式。对于头部字段名称不考虑大小写。 ``` -## 请求 +## 请求（Request） -Sanic确实试图在请求头上实现某种正常化，然后将它们提交给开发者。 并为普通用途案件进行一些可能有意义的抽查。 +Sanic 在将请求头呈现给开发者之前，确实会尝试对它们进行一些规范化处理，并针对常见用例提取一些潜在有意义的信息。 -.. 列: +.. column:: ``` -#### Tokens +#### 认证信息（Tokens） -认证令牌在 `Token ` 或 `Wearer 中被提取到请求对象： `request.token` 。 +格式为 `Token ` 或 `Bearer ` 的授权令牌会被提取到请求对象中，即：`request.token`。 ``` -.. 列: +.. column:: ```` ```python @@ -42,27 +42,27 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 ``` ```` -### 代理信头 +### 代理头(Proxy headers) -Sanic对代理头有特殊处理。 详情请查看[代理头](/guide/advanced/proxy-headers.md)部分。 +Sanic 对于代理头（proxy headers）信息有特别的处理方式。 更多详情请参阅[代理头](/zh/guide/advanced/proxy-headers.md)章节。 -### 主机头和动态URL设计 +### 主机标头和动态URL的构建(Host header and dynamic URL construction) -.. 列: +.. column:: ``` -有效主机*可通过 `request.host`获取。 这不一定与主机头相同，因为它喜欢代理转发的主机，并且可以通过服务器名称设置强制执行。 +通过 request.host 可获取到有效主机名。有效主机名不一定与主机头相同，因为它优先采用代理转发的主机名，并且可以通过服务器名称设置强制指定。 -网络应用通常应使用此访问器，以便不论如何部署，它们都能够正常运行。 如果需要，实际主机头可以通过“请求”找到。 eaders` +Web 应用通常应使用此访问器，以便无论部署方式如何都能保持相同的功能。如有需要，实际主机头可以通过 request.headers 获取。 -有效主机也用于通过 `required 构造动态 URL 。 rl_for`, 它使用请求来确定处理程序的外部地址。 +有效主机名还用于通过 request.url_for 动态构建 URL，该方法使用请求来确定处理器的外部地址。 -提示：请警惕恶意客户端 +.. tip:: 警惕恶意客户端 - 这些URL可以通过发送误导的主机头来操纵。 `app.url_for` 如果是关注的话应该被使用。 + 这些 URL 可能通过发送误导性主机头信息被操纵。如果对此有所顾虑，建议改用 `app.url_for`。 ``` -.. 列: +.. column:: ```` ```python @@ -91,15 +91,15 @@ curl localhost:8000/hosts ``` ```` -### 其他标题 +### 其他请求头(Other headers) -.. 列: +.. column:: ``` -所有请求标题都在 `request.headers` 上可用，可以用字典形式访问。 大写不被视为头件，可以使用大写或小写键访问。 +所有请求头都可以通过 `request.headers` 访问，可以以字典形式访问这些头信息。对于头信息的大小写不作考虑，因此可以使用大写或小写键来访问。 ``` -.. 列: +.. column:: ```` ```python @@ -152,78 +152,78 @@ curl localhost:9999/headers -H "Foo: one" -H "FOO: two"|jq ``` ```` -.. tip:: FYI +.. tip:: 提示一下 ``` -💡 request.headers对象是几种类型的字典之一，每个值都是一个列表。 这是因为HTTP允许重用单个键来发送多个值。 +💡 `request.headers` 对象是一种特殊类型的字典，其中每个值都是一个列表。这是因为 HTTP 协议允许同一键被复用以发送多个值。 -您想要使用 .get() 或 . 的大部分时间。 etone() 方法来访问第一个元素而不是列表。如果你确实想要一个所有项目的列表，你可以使用 .getall()。 +大多数时候，您可能想要通过 .get() 或 .getone() 方法获取第一个元素而非整个列表。如果您确实需要获取所有项目的列表，可以使用 .getall() 方法。 ``` -### 请求ID +### 请求ID（Request ID） -.. 列: +.. column:: ``` -通常，跟踪通过 `X-Request-ID` 文件头的请求是方便或必要的。您可以轻松访问 `request.id` 。 +通常，通过 `X-Request-ID` 头部追踪请求是很方便或必要的。您可以轻松地通过以下方式访问该请求ID：`request.id`。 ``` -.. 列: +.. column:: ```` ```python @app.route("/") -async def 处理器(请求): - return text(request). d) +async def handler(request): + return text(request.id) ``` ```sh curl localhost:8000 \ - - H "X-Request-ID: ABCDEF12345679" + -H "X-Request-ID: ABCDEF12345679" ABCDEF12345679 ``` ```` -## 答复 +## 响应(Response) -Sanic 将自动为您设置以下响应头(在适当时)： +Sanic 会自动为您设置以下响应头部（在适当的情况下）： - `content-length` - `content-type` - `connection` - `transfer-encoding` -在大多数情况下，您永远不必担心设置这些信头。 +在大多数情况下，您无需担心设置这些响应头的信息。 -.. 列: +.. column:: ``` -您想要设置的任何其他页眉都可以在路由处理器或响应中间件中完成。 +如果您想设置任何其他头部，可以在路由处理器中或响应中间件中完成。 ``` -.. 列: +.. column:: ```` ```python @app.route("/") async def handler(request): - return text("完成"). , headers={"content-language": "en-US"}) + return text("Done.", headers={"content-language": "en-US"}) @app.middleware("response") async def add_csp(request, response): - 响应。 eaders["content-security policy"] = "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'' + response.headers["content-security-policy"] = "default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self'; style-src 'self';base-uri 'self';form-action 'self'" ``` ```` -.. 列: +.. column:: ``` -A common [middleware](middleware.md) you might want is to add a `X-Request-ID` header to every response. As stated above: `request.id` will provide the ID from the incoming request. But, even if no ID was supplied in the request headers, one will be automatically supplied for you. +一个常见的[中间件](middleware.md)应用场景是向每个响应添加一个 `X-Request-ID` 头部。如上所述：`request.id` 将提供来自传入请求的 ID。但是，即使请求头中没有提供 ID，也会自动为您提供一个 ID。 -[See API docs for more details](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#sanic.request.Request.id) +[有关更多详细信息，请查阅 API 文档](https://sanic.readthedocs.io/en/latest/sanic/api_reference.html#sanic.request.Request.id) ``` -.. 列: +.. column:: ```` ```python @@ -231,18 +231,18 @@ A common [middleware](middleware.md) you might want is to add a `X-Request-ID` h async def handler(request): return text(str(request.id)) -@app. n_response +@app.on_response async def add_request_id_header(request, response): - response.headers["X-Request-ID"] = request。 d + response.headers["X-Request-ID"] = request.id ``` ```sh curl localhost:8000 -i -HTTP/1。 200 OK -X-Request-ID： 805a958e-9906-4e7a-8fe0-cbe83590431b -内容长度： 36 -连接： 保持 -内容类型： text/pla；charset=utf-8 +HTTP/1.1 200 OK +X-Request-ID: 805a958e-9906-4e7a-8fe0-cbe83590431b +content-length: 36 +connection: keep-alive +content-type: text/plain; charset=utf-8 805a958e-9906-4e7a-8fe0-cbe83590431b ``` From be81384f1d5d7689e282fa96e81dba93f886dff7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 12:09:11 +0300 Subject: [PATCH 626/698] New translations listeners.md (Chinese Simplified) --- guide/content/zh/guide/basics/listeners.md | 144 ++++++++++----------- 1 file changed, 72 insertions(+), 72 deletions(-) diff --git a/guide/content/zh/guide/basics/listeners.md b/guide/content/zh/guide/basics/listeners.md index 8bf14799fc..cf1fe3e180 100644 --- a/guide/content/zh/guide/basics/listeners.md +++ b/guide/content/zh/guide/basics/listeners.md @@ -88,91 +88,91 @@ async def before_start(*_): 如果该应用程序在开启自动重载的情况下运行，当重新加载进程启动时，会调用一次 `reload_start` 函数。 当主进程启动时，`main_start` 函数也会被调用一次。 **然而**，`before_start` 函数会在每个启动的工作者进程中被调用一次，并且每当文件保存导致工作者进程重启时，也会再次调用。 -## 正在附加侦听器 +## 注册监听器(Attaching a listener) -.. 列: +.. column:: ``` -作为侦听器设置函数的过程类似于声明路由。 +将函数设置为监听器的过程类似于声明路由。 -正在运行的 `Sanic()` 实例被注入到侦听器中。 +当前正在运行的 `Sanic()` 实例会被注入到监听器中。 ``` -.. 列: +.. column:: ```` ```python async def setup_db(app): - app.ctx.db = 等待db_setup() + app.ctx.db = await db_setup() -app.register_listener(setup_db, "previ_server_start") +app.register_listener(setup_db, "before_server_start") ``` ```` -.. 列: +.. column:: ``` -“Sanic”应用实例也有一个方便装饰器。 +`Sanic` 应用实例还提供了一个便利的装饰器。 ``` -.. 列: +.. column:: ```` ```python -@app.listener("prev_server_start") +@app.listener("before_server_start") async def setup_db(app): - app.ctx.db = 等待db_setup() + app.ctx.db = await db_setup() ``` ```` -.. 列: +.. column:: ``` -在 v22.3 之前，应用程序实例和当前事件循环都被注入到函数中。 然而，默认情况下只注入应用程序实例。 如果您的函数签名同时接受，那么应用程序和循环都会像这里显示的那样被注入。 +在 v22.3 版本之前，应用程序实例和当前事件循环都会被注入到函数中。然而，默认情况下只会注入应用程序实例。如果您的函数签名同时接受这两个参数，那么应用程序实例和循环将会像下面所示那样都被注入。 ``` -.. 列: +.. column:: ```` ```python -@app.listener("prev_server_start") +@app.listener("before_server_start") async def setup_db(app, loop): - app.ctx.db = 等待db_setup() + app.ctx.db = await db_setup() ``` ```` -.. 列: +.. column:: ``` -您可以进一步缩短装饰。如果您拥有一个自动完成的 IDE，这将是很有帮助的。 +您甚至可以进一步缩短装饰器。这对于具有自动补全功能的 IDE 尤其有用。 ``` -.. 列: +.. column:: ```` ```python @app.before_server_start async def setup_db(app): - app.ctx.db = 等待db_setup() + app.ctx.db = await db_setup() ``` ```` -## 执行顺序 +## 执行顺序(Order of execution) -侦听器按启动时的申报顺序执行，并在拆解时反向排序。 +在启动期间，监听器按照声明的顺序执行，在关闭期间则按照声明的反向顺序执行。 -| | 阶段 | 订单 | -| --------------------- | ------ | -------------------------------------------------------------------------------------------------- | -| `main_process_start` | 主要启动 | 普通:稍微ly_smiling_face: ⬇️ | -| `befor_server_start` | 工作人员启动 | 普通:稍微ly_smiling_face: ⬇️ | -| `After _server_start` | 工作人员启动 | 普通:稍微ly_smiling_face: ⬇️ | -| `before_server_stop` | 工人关机 | 🙃 ⬆️ reverse | -| `After _server_stop` | 工人关机 | 🙃 ⬆️ reverse | -| `main_process_stop` | 主要关机 | 🙃 ⬆️ reverse | +| | 执行阶段 | 执行顺序 | +| --------------------- | --------------- | ------------- | +| `main_process_start` | main startup | regular 🙂 ⬇️ | +| `before_server_start` | worker startup | regular 🙂 ⬇️ | +| `after_server_start` | worker startup | regular 🙂 ⬇️ | +| `before_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `after_server_stop` | worker shutdown | 🙃 ⬆️ reverse | +| `main_process_stop` | main shutdown | 🙃 ⬆️ reverse | -鉴于以下情况，如果我们运行两名工人，我们应该在控制台中看到这一点。 +鉴于以下设置，如果我们运行两个工作者进程，我们预期会在控制台看到以下输出： -.. 列: +.. column:: ```` ```python @@ -180,37 +180,37 @@ async def setup_db(app): async def listener_1(app, loop): print("listener_1") -@appp efor_server_start -async def listener_2(app, loor): +@app.before_server_start +async def listener_2(app, loop): print("listener_2") -@app. istener("after_server_start") -async def listener_3(app, rol): +@app.listener("after_server_start") +async def listener_3(app, loop): print("listener_3") -@app. fter_server_start -async def listener_4(app, loor): +@app.after_server_start +async def listener_4(app, loop): print("listener_4") -@app. istener("before_server_stop") -async def listener_5(app, rol): +@app.listener("before_server_stop") +async def listener_5(app, loop): print("listener_5") -@app. efor_server_stop -async def listener_6(app, loor): +@app.before_server_stop +async def listener_6(app, loop): print("listener_6") -@app. istener("after_server_stop") -async def listener_7(app, rol): +@app.listener("after_server_stop") +async def listener_7(app, loop): print("listener_7") -@app. fter_server_stop -async def listener_8(app, loor): +@app.after_server_stop +async def listener_8(app, loop): print("listener_8") ``` ```` -.. 列: +.. column:: ```` ```bash @@ -239,39 +239,39 @@ async def listener_8(app, loor): [pid: 1000000] [INFO] listener_9 [pid: 1000000] [INFO] Server Stopped ``` -In the above example, notice how there are three processes running: +在上面的例子中，请注意存在三个运行中的进程： - `pid: 1000000` - The *main* process - `pid: 1111111` - Worker 1 - `pid: 1222222` - Worker 2 -*Just because our example groups all of one worker and then all of another, in reality since these are running on separate processes, the ordering between processes is not guaranteed. But, you can be sure that a single worker will **always** maintain its order.* +*尽管我们的示例先展示了所有属于一个工作者（worker）的输出，然后展示了另一个工作者（worker）的所有输出，但在实际情况中，由于这些进程是在不同的进程中运行的，不同进程之间的执行顺序并不保证一致。但是，您完全可以确定的是，单一工作者（worker）进程 **总是** 会保持其内部执行顺序不变。* ```` -.. tip:: FYI +.. tip:: 提示一下 ``` -这个结果的实际结果是，如果`pre_server_start`中的第一个监听器设置了数据库连接。 注册后的侦听器可以在启动和停止时依靠该连接存活。 +这种情况的实际结果是，如果在 `before_server_start` 处理器中的第一个监听器设置了数据库连接，那么在此之后注册的监听器可以依赖于在它们启动和停止时该连接都处于活跃状态。 ``` -### 优先权 +### 优先级（Priority） -.. 新：v23.12 +.. new:: v23.12 ``` -在 v23.12，监听器中添加了 `priority` 关键字参数。这允许调整监听器的执行顺序。 默认优先级是 `0`。优先级较高的侦听器将先执行。 具有相同优先级的侦听器将按照他们注册的顺序执行。 此外，连接到 `app` 实例的侦听器将在连接到 `Blueprint` 实例的侦听器之前执行。 +自 v23.12 版本起，向监听器添加了 `priority` 关键字参数。这允许精细调整监听器执行顺序。默认优先级为 `0`。优先级较高的监听器将首先执行。相同优先级的监听器将按照注册的顺序执行。此外，附加到 `app` 实例的监听器将优先于附加到 `Blueprint` 实例的监听器执行。 ``` -总体上，决定执行顺序的规则如下： +决定执行顺序的整体规则如下： -1. 按降序排序 -2. 蓝图监听器之前的应用程序监听器 -3. 注册订单 +1. 先级降序排列 +2. 应用程序级别的监听器优先于蓝图级别的监听器执行 +3. 按照注册顺序执行 -.. 列: +.. column:: ```` -As an example, consider the following, which will print: +作为示例，考虑以下内容，它将打印： ```bash third @@ -284,7 +284,7 @@ bp_first ``` ```` -.. 列: +.. column:: ```` ```python @@ -292,27 +292,27 @@ bp_first async def first(app): print("first") -@app。 istener("before_server_start", priority=2) +@app.listener("before_server_start", priority=2) async def second(app): print("second") -@app. efor_server_start(priority=3) +@app.before_server_start(priority=3) async def third(app): print("third") -@bp.befor_server_start +@bp.before_server_start async def bp_first(app): print("bp_first") -@bp. istener("before_server_start", priority=2) +@bp.listener("before_server_start", priority=2) async def bp_second(app): print("bp_second") -@bp. efor_server_start(priority=3) +@bp.before_server_start(priority=3) async def bp_third(app): print("bp_third") -@app。 efore_server_start +@app.before_server_start async def fourth(app): print("fourth") @@ -320,11 +320,11 @@ app.blueprint(bp) ``` ```` -## ASGI 模式 +## ASGI 模式 (ASGI Mode) -如果您正在使用 ASGI 服务器运行您的应用程序，请注意以下变化： +如果你使用ASGI服务器运行应用程序，请注意以下变化： - `reload_process_start` 和 `reload_process_stop` 将被**忽略** - `main_process_start` 和 `main_process_stop` 将被**忽略** -- `befor_server_start` 将尽早运行，并且将在 `After _server_start` 之前运行，但是从技术上讲，服务器已经在那个地点运行。 -- `after _server_stop`将会尽早运行，并且会在 `before_server_stop` 之后运行，但从技术上讲，服务器仍然在那个地点运行 +- `before_server_start` 尽可能早地运行，并且将在 `after_server_start ` 之前执行，但从技术上讲，在此时服务器已经启动了 +- `after_server_stop` 尽可能晚地运行，并且将在 `before_server_stop` 之后执行，但从技术上讲，在此时服务器仍在运行中 From 30c132230c92b79184b066f2ab99c6232f1315c8 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 12:09:12 +0300 Subject: [PATCH 627/698] New translations middleware.md (Chinese Simplified) --- guide/content/zh/guide/basics/middleware.md | 137 ++++++++++---------- 1 file changed, 68 insertions(+), 69 deletions(-) diff --git a/guide/content/zh/guide/basics/middleware.md b/guide/content/zh/guide/basics/middleware.md index 80bfcfd838..a6c0671e2e 100644 --- a/guide/content/zh/guide/basics/middleware.md +++ b/guide/content/zh/guide/basics/middleware.md @@ -1,6 +1,6 @@ -# 中间件 +# 中间件(Middleware) -听众允许您在工作流程的生命周期中附加功能， 中间件允许您在HTTP流的生命周期中附加功能。 +监听器（listeners ）允许您将功能附加到工作进程的生命周期中，中间件（middleware ）则允许您将功能附加到HTTP流的生命周期中。 ```python @app.on_request @@ -8,7 +8,7 @@ async def example(request): print("I execute before the handler.") ``` -您可以执行 _befor_ 的处理程序或者执行 _after _。 +您可以选择在处理器执行前或执行后执行中间件。 ```python @app.on_response @@ -16,7 +16,7 @@ async def example(request, response): print("I execute after the handler.") ``` -.. mermaid: +.. mermaid:: ``` sequenceDiagram @@ -43,66 +43,66 @@ end Note over Worker: Deliver response ``` -## 附加中间件 +## 注册中间件（Attaching middleware） -.. 列: +.. column:: ``` -现在也许应该看起来很熟悉。 您需要做的只是当您想要执行中间件时声明：在 "request" 或 "response" 上。 +到现在为止，这个概念应该已经很熟悉了。您需要做的只是声明何时希望中间件执行：是在请求（`request`）阶段还是响应（`response`）阶段。 ``` -.. 列: +.. column:: ```` ```python async def extract_user(request): - request.ctx.user = request_user_from_request(request) + request.ctx.user = await extract_user_from_request(request) app.register_middleware(extract_user, "request") ``` ```` -.. 列: +.. column:: ``` -同样，“Sanic”应用实例也有一个方便装饰器。 +同样，`Sanic` 应用实例也提供了一个便捷的装饰器。 ``` -.. 列: +.. column:: ```` ```python -@app.midleware("request") +@app.middleware("request") async def extract_user(request): - request.ctx.user = request_user_from_request(request) + request.ctx.user = await extract_user_from_request(request) ``` ```` -.. 列: +.. column:: ``` -响应中间件同时收到“request”和“response”两个参数。 +响应中间件同时接收 `request` 和 `response` 参数。 ``` -.. 列: +.. column:: ```` ```python -@app.midleware('response') +@app.middleware('response') async def prevent_xss(request, response): response.headers["x-xss-protection"] = "1; mode=block" ``` ```` -.. 列: +.. column:: ``` -您可以进一步缩短装饰。如果您拥有一个自动完成的 IDE，这将是很有帮助的。 +您甚至可以进一步简化装饰器。如果您使用的IDE支持自动补全，这将非常有帮助。 -这是首选用法，这是我们今后使用的方法。 +这是首选用法，也是我们后续将会采用的方式。 ``` -.. 列: +.. column:: ```` ```python @@ -116,37 +116,37 @@ async def prevent_xss(request, response): ``` ```` -## 修改 +## 修改（Modification） -中间件可以修改它被指定的请求或响应参数，只要它不返回它。 +只要中间件不返回请求或响应参数，它可以修改接收到的请求或响应参数。 -.. 列: +.. column:: ``` #### 执行顺序 -1. 请求中间行：`add_key` -2. 路由处理：`index` -3. 响应中间行：`prevent_xss` -4. 响应中间行程：`cust_banner` +1. Request middleware: `add_key` +2. Route handler: `index` +3. Response middleware: `prevent_xss` +4. Response middleware: `custom_banner` ``` -.. 列: +.. column:: ```` ```python -@app。 n_request -async def add_key(请求): - # 任意数据可能存储在请求的上下文中: - 请求。 tx.foo = "bar" +@app.on_request +async def add_key(request): + # Arbitrary data may be stored in request context: + request.ctx.foo = "bar" @app.on_response async def custom_banner(request, response): - response. eaders["Server"] = "Fake-Server" + response.headers["Server"] = "Fake-Server" @app.on_response async def prevent_xss(request, response): - response. eaders["x-xss-protection"] = "1; mode=block" + response.headers["x-xss-protection"] = "1; mode=block" @app.get("/") async def index(request): @@ -155,46 +155,45 @@ async def index(request): ``` ```` -.. 列: +.. column:: ``` -您可以修改 `request.match_info` 。例如，一个有用的功能可以用于中间件将`a-slug` 转换为 `a_slug` 。 +您可以修改 `request.match_info`。例如，在中间件中，可以利用这一有用特性将 `a-slug` 转换为 `a_slug`。 ``` -.. 列: +.. column:: ```` ```python @app.on_request -def convert_slug_to_underly(request: - request.match_info["slug"] = request.match_info["slug"].replace("-"_") +def convert_slug_to_underscore(request: Request): + request.match_info["slug"] = request.match_info["slug"].replace("-", "_") -@app. et("/") -async def 处理器(请求) slug): +@app.get("/") +async def handler(request, slug): return text(slug) ``` ``` -$ curl localhost:99999/foo-bar-baz +$ curl localhost:9999/foo-bar-baz foo_bar_baz ``` ```` -## 早期响应 +## 提前响应(Resonding early) -.. 列: +.. column:: ``` -If middleware returns a `HTTPResponse` object, the request will stop processing and the response will be returned. If this occurs to a request before the route handler is reached, the handler will **not** be called. Returning a response will also prevent any further middleware from running. - +如果中间件返回一个 `HTTPResponse` 对象，则请求处理将停止，并返回该响应。如果在到达路由处理器之前发生这种情况，则不会调用处理器。返回响应也将阻止任何其他中间件继续执行。 ``` -.. tip:: +.. tip:: 提示 ``` -您可以返回 `None` 值来停止执行中间件处理程序，以允许请求正常处理。 这可能有助于早日返回以避免处理中间件处理器内的请求。 +您可以在中间件处理器中返回 `None` 值来停止执行，以允许请求正常进行处理。当使用早期返回机制避免在此中间件处理器内部处理请求时，这一做法十分有用。 ``` -.. 列: +.. column:: ```` ```python @@ -208,13 +207,13 @@ async def halt_response(request, response): ``` ```` -## 执行顺序 +## 执行顺序(Order of execution) -请求中间件在已声明的订单中执行。 响应中间件在 **逆序** 中执行。 +请求中间件按照声明的顺序执行。 响应中间件按**相反顺序**执行。 -鉴于以下情况，我们应该在控制台上看到这一点。 +按照下面的代码，我们应该期望在控制台看到这样的输出结果。 -.. 列: +.. column:: ```` ```python @@ -222,47 +221,47 @@ async def halt_response(request, response): async def middleware_1(request): print("middleware_1") -@appp. n_request +@app.on_request async def middleware_2(request): print("middleware_2") -@app. n_response +@app.on_response async def middleware_3(request, response): print("middleware_3") -@app. n_response +@app.on_response async def middleware_4(request, response): print("middleware_4") -@app. et("/handler") +@app.get("/handler") async def handler(request): - print("~handler ~") - return text("完成") + print("~ handler ~") + return text("Done.") ``` ```` -.. 列: +.. column:: ```` ```bash middleware_1 middleware_2 -~ +~ handler ~ middleware_4 middleware_3 -[INFO][127.0.0.1:4478]: GET http://localhost:8000/handler 200 5 +[INFO][127.0.0.1:44788]: GET http://localhost:8000/handler 200 5 ``` ```` -### 中间件优先级 +### 中间件优先级（Middleware priority） -.. 列: +.. column:: ``` -您可以通过赋予它更高的优先级来修改中间件的执行顺序。这发生在中间件定义内。 值越高，相对于其他中间件执行的越早。中间件的默认优先级是 `0'。 +您可以通过分配更高的优先级来修改中间件执行的顺序。这一操作在定义中间件时进行。优先级值越高，相对于其他中间件，其执行就越早。默认情况下，中间件的优先级为 `0`。 ``` -.. 列: +.. column:: ```` ```python @@ -276,4 +275,4 @@ async def high_priority(request): ``` ```` -_添加于 v22.9_ +\*添加于 v22.9 \* From 416eecac9c6a4118e512068b015a578a5c6385a2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 12:09:14 +0300 Subject: [PATCH 628/698] New translations tasks.md (Chinese Simplified) --- guide/content/zh/guide/basics/tasks.md | 46 +++++++++++++------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/guide/content/zh/guide/basics/tasks.md b/guide/content/zh/guide/basics/tasks.md index edc3902c48..0ce1048a65 100644 --- a/guide/content/zh/guide/basics/tasks.md +++ b/guide/content/zh/guide/basics/tasks.md @@ -2,50 +2,50 @@ title: 背景任务 --- -# 背景任务 +# 后台任务(Background tasks) -## 创建任务 +## 创建任务(Creating Tasks) -在异步Python中使用 [tasks]通常是可取和非常方便的。 (https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task) Sanic 提供了一种方便的方法，可以将任务添加到当前的 **running** 循环中。 它与`asyncio.create_task`有些相似。 在 'App' 循环运行之前添加任务, 见下一个部分。 +在异步 Python 中，常常希望能够方便地使用任务[tasks](https://docs.python.org/3/library/asyncio-task.html#asyncio.create_task)。 Sanic 提供了一种便捷的方法，可以将任务添加到当前**正在运行**的循环中， 类似于 `asyncio.create_task`。 若要在“App”循环启动前添加任务，请参阅下一节内容。 ```python -async def notify_server_started_after _fif_seconds(): - 等待asyncio.sleep(5) - print('Server successful started!') +async def notify_server_started_after_five_seconds(): + await asyncio.sleep(5) + print('Server successfully started!') -app.add_task(notify_server_started_after_first_five _seconds()) +app.add_task(notify_server_started_after_five_seconds()) ``` -.. 列: +.. column:: ``` -Sanic 会尝试自动注入应用，将其作为参数传递给任务。 +Sanic 会尝试自动注入应用实例，并将其作为参数传递给任务。 ``` -.. 列: +.. column:: ```` ```python async def auto_inject(app): - 等待 asyncio.sleep(5) + await asyncio.sleep(5) print(app.name) app.add_task(auto_inject) ``` ```` -.. 列: +.. column:: ``` -或者你可以明确传递`app`的参数。 +或者，您可以显式地传递 `app` 参数。 ``` -.. 列: +.. column:: ```` ```python async def explicit_inject(app): - required asyncio.sleep(5) + await asyncio.sleep(5) print(app.name) app.add_task(explicit_inject(app)) @@ -54,17 +54,17 @@ app.add_task(explicit_inject(app)) ## 在 `app.run` 之前添加任务 -在“app.run”之前添加后台任务是可能的。 若要在应用程序运行前添加任务，建议不要通过Coroutine对象 (e)。 一个通过调用 `async` 调用来创建的东西，但只是传递可调用和 Sanic将在 **每个工人** 上创建可调用物体。 注意：添加的任务将以 `before_server_start` 的形式运行，从而在每个工人（而不是主工）上运行。 这对[这个问题](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668)[这个问题](https://github.com/sanic-org/sanic/issues/2139)有某些后果，详情请参阅。 +在应用运行之前（即在调用 app.run 之前），可以添加后台任务。 建议在这种情况下不要传递协程对象（即通过调用异步可调用函数创建的对象），而是仅传递可调用函数，Sanic 会在**每个工作进程**中自行创建协程对象。 请注意，这样添加的任务会在每个工作进程内以 `before_server_start `任务的形式运行，而不是在主进程中运行。 这一点具有特定的影响，请参阅该问题下的[这条评论](https://github.com/sanic-org/sanic/issues/2139#issuecomment-868993668) 在 [issue](https://github.com/sanic-org/sanic/issues/2139) 以获取更多细节。 -要添加主进程的工作，请考虑将工作添加到[`@app.main_process_start`](./listeners.md)。 注意：工人在完成此工作之前不会开始工作。 +若要在主进程中添加任务，请考虑使用装饰器 [`@app.main_process_start`](./listeners.md) 来添加任务。 请注意，直到这些任务完成，工作进程才开始启动。 -.. 列: +.. column:: ``` -在 `app.run` 之前添加任务的示例 +在 `app.run` 之前添加任务的示例代码 ``` -.. 列: +.. column:: ```` ```python @@ -81,12 +81,12 @@ app.run(...) ``` ```` -## 命名的任务 +## 命名任务(Named tasks) -.. 列: +.. column:: ``` -创建任务时，您可以通过 "name" 要求Sanic 为您记录它。 +创建任务时，通过提供一个`name`，你可以让Sanic帮你跟踪这个任务。 ``` .. 列: From 9aabe1d0c0941f9e018f537d5fa3ffc367485b30 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 14:07:52 +0300 Subject: [PATCH 629/698] New translations class-based-views.md (Chinese Simplified) --- .../zh/guide/advanced/class-based-views.md | 110 +++++++++--------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/guide/content/zh/guide/advanced/class-based-views.md b/guide/content/zh/guide/advanced/class-based-views.md index 59241cd4af..7c969975d0 100644 --- a/guide/content/zh/guide/advanced/class-based-views.md +++ b/guide/content/zh/guide/advanced/class-based-views.md @@ -2,17 +2,17 @@ ## 为什么要使用它？ -.. 列: +.. column:: ``` ### 问题所在 -设计 API 时的常见思路是在根据 HTTP 请求方法的不同而产生不同响应的同一端点上实现多种功能。 +设计API时常见的一个模式是在同一路由入口上根据HTTP方法实现多种功能。 -虽然这两种选项都可以，但它们并不是良好的设计思维，随着你的项目的发展，可能很难长期维护。 +虽然这两种方案都能正常工作，但它们并不是良好的设计实践，并且随着项目的增长，可能会随着时间推移变得难以维护。 ``` -.. 列: +.. column:: ```` ```python @@ -41,15 +41,15 @@ async def bar(request): ``` ```` -.. 列: +.. column:: ``` ### 解决方案 -基于类的视图只是实现请求响应行为的类。 它们提供了一种在同一端点划分不同 HTTP 请求类型的处理方法。 +基于类的视图本质上是实现响应请求行为的类。它们提供了一种方式，在同一路由入口上将不同类型的HTTP请求处理方式进行模块化管理。 ``` -.. 列: +.. column:: ```` ```python @@ -69,16 +69,16 @@ app.add_route(FooBar.as_view(), "/foobar") ``` ```` -## 定义一个视图 +## 定义视图 (Defining a view) -基于类的视图应当继承 :class:`sanic.views.HTTPMethodView`。 然后，您可以使用相应 HTTP 方法的名称来实现类方法。 如果收到一个没有定义方法的请求，将生成一个 \`405: Method not allowed' 响应。 +一个基于类的视图应继承自 :class:`sanic.views.HTTPMethodView`. 然后，您可以实现与相应HTTP方法同名的类方法。 如果接收到的方法未定义的请求，将生成`405: Method not allowed`的响应。 -.. 列: +.. column:: ``` -要在一个 URL 端点注册一个基于类的视图，需要使用 `app.add_route` 方法。 第一个参数应该是实现了`as_view`方法的定义类，第二个参数应该是 URL 端点。 +在路由入口上注册基于类的视图时，通常使用 `app.add_route` 方法。第一个参数应当是已定义的类，并调用其 `as_view` 方法，第二个参数则是该视图要绑定的URL路由入口。 -可用的方法是： +可用的方法包括： - get - post @@ -89,7 +89,7 @@ app.add_route(FooBar.as_view(), "/foobar") - options ``` -.. 列: +.. column:: ```` ```python @@ -101,7 +101,7 @@ class SimpleView(HTTPMethodView): def get(self, request): return text("I am get method") - # 也支持 async 语法 + # You can also use async syntax async def post(self, request): return text("I am post method") @@ -118,110 +118,110 @@ app.add_route(SimpleView.as_view(), "/") ``` ```` -## 路径参数 +## 路径参数（Path parameters） -.. 列: +.. column:: ``` -您可以完全按照[路由部分](/guide/basics/routing.md)中讨论的方式使用路径参数。 +您可以完全按照[路由部分](/zh/guide/basics/routing.md)中讨论的方式来使用路径参数。 ``` -.. 列: +.. column:: ```` ```python class NameView(HTTPMethodView): def get(self, request, name): - return text("Hello {}".format (name)) + return text("Hello {}".format(name)) -app.add_route(NameView.asp.as_view(), "/") +app.add_route(NameView.as_view(), "/") ``` ```` -## 装饰器 +## 装饰器（Decorators） -正如[装饰器部分](/guide/best-practices/decorators.md)中所讨论的，您通常需要使用装饰器向端点添加功能。 您与 CBV 有两个选项： +正如在[装饰器](/zh/guide/best-practices/decorators.md)部分讨论的那样，您经常需要通过使用装饰器为路由入口添加功能。 对于基于类的视图（CBV），有两种选择： -1. 应用于视图中的 _全部_ HTTP 方法 -2. 单独应用于视图中的 HTTP 方法 +1. 应用于视图中的**所有**HTTP方法 +2. 分别应用于视图中的各个HTTP方法 -让我们看看这些选项是什么样子： +让我们来看一下这两种选项的样子： -.. 列: +.. column:: ``` -### 应用于所有方法 +### 应用于视图中的所有HTTP方法 -如果您想要将任何装饰符添加到类中，您可以设置 "装饰符" 类变量。 当调用`as_view`时，这些将应用于该类。 +若要向此类添加任何装饰器，您可以设置 `decorators` 类变量。当调用 `as_view` 时，这些装饰器将会应用于此类。 ``` -.. 列: +.. column:: ```` ```python -class ViewWidDecorator(HTTPMethodView): +class ViewWithDecorator(HTTPMethodView): decorators = [some_decorator_here] - def get(self, request, pass). 姓名: - 退货文本("Hello I have a decorator") + def get(self, request, name): + return text("Hello I have a decorator") - def post(self, 请求，名称： - return text("Hello I also a Decorator") + def post(self, request, name): + return text("Hello I also have a decorator") -app dd_route(ViewWidDecorator.as_view(), "/url") +app.add_route(ViewWithDecorator.as_view(), "/url") ``` ```` -.. 列: +.. column:: ``` -### 应用于个别方法 +### 分别应用于视图中的各个HTTP方法 -但是如果你只想装饰一些方法而不是所有方法，你可以如这里所示。 +但是，如果您只想装饰某些方法而不是所有方法，则可以如以下所示操作。 ``` -.. 列: +.. column:: ```` ```python -class Viewwitwithout Decorator(HTTPMethodView): +class ViewWithSomeDecorator(HTTPMethodView): - @static方法 + @staticmethod @some_decorator_here - def get(request 姓名: - 退货文本("Hello I have a decorator") + def get(request, name): + return text("Hello I have a decorator") - def post(self, 请求 姓名： - return text("Hello I no some decorators") + def post(self, request, name): + return text("Hello I do not have any decorators") @some_decorator_here - def patch(self, 请求，名称： - 返回文本("Hello I have a decorator") + def patch(self, request, name): + return text("Hello I have a decorator") ``` ```` -## 正在生成 URL +## 动态路由(Generating a URL) -.. 列: +.. column:: ``` -这就像[生成任何其它URL](/guide/basics/routing.md#generating-a-url)一样，只是类名称是端点的一部分。 +这就像[生成任何其他URL](/zh/guide/basics/routing.md#generating-a-url)一样工作，只不过类名是路由入口的一部分。 ``` -.. 列: +.. column:: ```` ```python @app.route("/") def index(request): - url = app. rl_for("SpecialClassView") + url = app.url_for("SpecialClassView") return redirect(url) class SpecialClassView(HTTPMethodView): - def get(self, 请求: - 返回文本("您好，来自特殊类视图! + def get(self, request): + return text("Hello from the Special Class View!") -应用。 dd_route(SpecialClassView.as_view), "/special_class_view") +app.add_route(SpecialClassView.as_view(), "/special_class_view") ``` ```` From e9716425319caee2bc780dbf99aee844ef88da05 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 14:07:54 +0300 Subject: [PATCH 630/698] New translations proxy-headers.md (Chinese Simplified) --- .../zh/guide/advanced/proxy-headers.md | 284 +++++++++--------- 1 file changed, 142 insertions(+), 142 deletions(-) diff --git a/guide/content/zh/guide/advanced/proxy-headers.md b/guide/content/zh/guide/advanced/proxy-headers.md index c5365da924..2203952d58 100644 --- a/guide/content/zh/guide/advanced/proxy-headers.md +++ b/guide/content/zh/guide/advanced/proxy-headers.md @@ -1,68 +1,68 @@ -# 代理配置 +# 代理配置 (Proxy configuration) -当您使用反向代理服务器 (例如nginx) 时，`request.ip` 的值将包含代理的 IP，通常是 `127.0.0.1` 。 几乎总是**不是**你想要的。 +当您使用反向代理服务器（例如nginx）时，`request.ip` 的值将包含代理的IP地址，通常是 `127.0.0.1`。 几乎在所有情况下，这都不是您所期望得到的结果。 -Sanic 可能被配置为使用代理头来确定真正的客户端 IP，可用于“request.remote_addr”。 完整的外部 URL 也是从标题字段 _如果可用的话_构建的。 +Sanic 可以配置为使用代理头信息来确定真实的客户端IP地址，该地址可通过 `request.remote_addr` 获取。 如果有提供的话，完整的外部URL也会从头字段中构建出来。 -.. 提示：浮动通知 +.. tip:: 注意一下 ``` -如果没有适当的防范措施，恶意客户可能会使用代理头来歪曲自己的IP。 为了避免这种问题，除非明确启用，否则Sanic不会使用任何代理标题。 +未经适当防护措施，恶意客户端可能会利用代理头信息伪造自己的IP地址。为了避免这类问题，Sanic默认不使用任何代理头信息，除非明确启用此功能。 ``` -.. 列: +.. column:: ``` -逆向代理后面的服务必须配置以下[配置值](/guide/deplement/configuration.md): +部署在反向代理之后的服务必须配置以下[配置值](/zh/guide/deployment/configuration.md)之一或多者： - `FORWARDED_SECRET` - `REAL_IP_HEADER` - `PROXIES_COUNT` ``` -.. 列: +.. column:: ```` ```python -app.config.FORWARDED_SECRET = "超级duper-secret" +app.config.FORWARDED_SECRET = "super-duper-secret" app.config.REAL_IP_HEADER = "CF-Connecting-IP" -app.config.PROXIEs_COUNT = 2 +app.config.PROXIES_COUNT = 2 ``` ```` -## 转发标题 +## 转发头(Forwarded header) -为了使用 `Forwarded` 标题，您应该将 `app.config.FORWARDED_SECRET` 设置为信任的代理服务器已知的值。 此密钥用于安全识别特定代理服务器。 +为了使用“Forwarded”头信息，您应该将 `app.config.FORWARDED_SECRET` 设置为可信代理服务器所知的一个值。 这个密钥用于安全地识别特定的代理服务器。 -神秘忽略任何没有密钥的元素，如果没有设置秘密，甚至不会解析标题。 +如果没有设置密钥，Sanic会忽略任何没有密钥的秘密元素，甚至不会解析该头信息。 -所有其它代理头在找到可信任的转发元素时被忽略，因为它已经包含了有关客户端的完整信息。 +一旦找到可信的转发元素，所有其他代理头信息都将被忽略，因为可信的转发元素已经携带了关于客户端的完整信息。 -若要了解更多关于 `Forwarded` 标题，请阅读相关的 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) 和 [Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) 文章。 +要了解更多关于Forwarded头信息的内容，请阅读相关的 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) 和[Nginx](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/) 文章。 -## 传统代理信头 +## 常见的代理请求头(Traditional proxy headers) -### IP 头 +### IP Headers -当你的代理转发你已知的标题中的 IP 地址时，你可以告诉Sanic 什么是 `REAL_IP_HEADER` 配置值。 +当您的代理通过某个已知头信息传递IP地址时，您可以使用 `REAL_IP_HEADER` 配置值告诉Sanic这个头信息是什么。 -### X-转发-输入 +### X-Forwarded-For -此页眉通常包含一个通过代理服务器的每层IP地址链。 设置 `PROXIES_COUNT` 告诉Sanic寻找客户端的实际IP地址。 此值应等于 _expected_number 的 IP 地址。 +此头信息通常包含经过每一层代理的IP地址链。 设置 PROXIES_COUNT 告诉Sanic应深入到哪一层以获取实际的客户端IP地址。 这个值应等于链中IP地址预期的数量。 -### 其他X-headers +### Other X-headers -如果客户端IP找到这些方法之一，Sanic对URL部分使用以下标题： +如果通过上述方法找到了客户端IP地址，Sanic会使用以下头信息来构建URL各部分： -- x-转发-proto -- x转发主机 -- x转发端口 -- x转发路径 -- x 方案 +- x-forwarded-proto +- x-forwarded-host +- x-forwarded-port +- x-forwarded-path +- x-scheme -## 示例： +## 示例 -在下面的例子中，所有请求都将假定终点看起来像这样： +在以下示例中，所有请求都将以如下形式的路由入口为基础进行演示： ```python @app.route("/fwd") @@ -80,20 +80,20 @@ async def forwarded(request): --- -##### 例1 +##### 例一(Example 1) -如果没有配置FORWARDED_SECRET, X-headers 应该受到尊重。 +若未配置`FORWARDED_SECRET`，应尊重x-headers ```sh curl localhost:8000/fwd \ - -H 'Forwar: for=1.1.1, for=injected;host="[:2]";proto=https://;host=me.tld;path="/app/";secret=mySecret,for=brochen;secret=b0rked, for=127。 .0.3;scheme=http;port=1234' \ - -H "X-Real-IP: 127.0.0.2" - -H "X-For: 127.0.1" - - H "X-Scheme: w" - - H "Host: local.site" | jq + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq ``` -.. 列: +.. column:: ```` ```python @@ -103,18 +103,18 @@ app.config.REAL_IP_HEADER = "x-real-ip" ``` ```` -.. 列: +.. column:: ```` ```bash -# curl replacement -Paper - "remote_addr": "127.0.0.0.2", +# curl response +{ + "remote_addr": "127.0.0.2", "scheme": "ws", - "server_name": "local. ite”, + "server_name": "local.site", "server_port": 80, - "forwarded": 许诺, - "for": "127. .0.2", + "forwarded": { + "for": "127.0.0.2", "proto": "ws" } } @@ -123,20 +123,20 @@ Paper --- -##### 例2 +##### 例二(Example 2) -FORWARDED_SECRET 已配置 +`FORWARDED_SECRET` 已配置 ```sh curl localhost:8000/fwd \ - -H 'Forwar: for=1.1.1, for=injected;host="[:2]";proto=https://;host=me.tld;path="/app/";secret=mySecret,for=brochen;secret=b0rked, for=127。 .0.3;scheme=http;port=1234' \ - -H "X-Real-IP: 127.0.0.2" - -H "X-For: 127.0.1" - - H "X-Scheme: w" - - H "Host: local.site" | jq + -H 'Forwarded: for=1.1.1.1, for=injected;host=", for="[::2]";proto=https;host=me.tld;path="/app/";secret=mySecret,for=broken;;secret=b0rked, for=127.0.0.3;scheme=http;port=1234' \ + -H "X-Real-IP: 127.0.0.2" \ + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ + -H "Host: local.site" | jq ``` -.. 列: +.. column:: ```` ```python @@ -147,7 +147,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash @@ -170,19 +170,19 @@ app.config.FORWARDED_SECRET = "mySecret" --- -##### 例3 +##### 例三(Example 3) -空转发头 -> 使用 X-headers +空`Forwarded`头信息 -> 使用`X-headers` ```sh curl localhost:8000/fwd \ -H "X-Real-IP: 127.0.0.2" \ - -H "X-For: 127.0.1" \ - -H "X-Scheme: w" + -H "X-Forwarded-For: 127.0.1.1" \ + -H "X-Scheme: ws" \ -H "Host: local.site" | jq ``` -.. 列: +.. column:: ```` ```python @@ -193,18 +193,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash -# curl replacement -Paper - "remote_addr": "127.0.0.0.2", +# curl response +{ + "remote_addr": "127.0.0.2", "scheme": "ws", - "server_name": "local. ite”, + "server_name": "local.site", "server_port": 80, - "forwarded": 许诺, - "for": "127. .0.2", + "forwarded": { + "for": "127.0.0.2", "proto": "ws" } } @@ -213,16 +213,16 @@ Paper --- -##### 例4 +##### 例四(Example 4) -页眉已存在，但不匹配任何内容 +存在头信息但无法匹配任何内容 ```sh curl localhost:8000/fwd \ - -H "Forwar: nomatch" | jq + -H "Forwarded: nomatch" | jq ``` -.. 列: +.. column:: ```` ```python @@ -238,7 +238,7 @@ app.config.FORWARDED_SECRET = "mySecret" ```` ```bash # curl response -Power +{ "remote_addr": "", "scheme": "http", "server_name": "localhost", @@ -251,17 +251,17 @@ Power --- -##### 例5 +##### 例五(Example 5) -转发头，但没有匹配的密钥 -> 使用 X-headers +`Forwarded`头信息存在，但无匹配的密钥 -> 使用`X-headers` ```sh curl localhost:8000/fwd \ - -H "Forwar: for=1.1.1;secret=x, for=127.0.0.1" + -H "Forwarded: for=1.1.1.1;secret=x, for=127.0.0.1" \ -H "X-Real-IP: 127.0.0.2" | jq ``` -.. 列: +.. column:: ```` ```python @@ -272,18 +272,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash -# curl reply -Power - "remote_addr": "127.0.0.0 ", +# curl response +{ + "remote_addr": "127.0.0.2", "scheme": "http", "server_name": "localhost", "server_port": 8000, - "forwarded": 许诺, - "for": "127. 0.2" + "forwarded": { + "for": "127.0.0.2" } } ``` @@ -291,16 +291,16 @@ Power --- -##### 例6 +##### 例六(Example 6) -不同格式化并击中标题两端的标题 +不同格式化方式，同时触及头信息两端的情况 ```sh curl localhost:8000/fwd \ - -H 'Forward: Secret="mysecret";For=127.0.0.4;Port=1234' | jq + -H 'Forwarded: Secret="mySecret";For=127.0.0.4;Port=1234' | jq ``` -.. 列: +.. column:: ```` ```python @@ -311,19 +311,19 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash -# curl reply -Power - "remote_addr": "127.0.0.0 ", +# curl response +{ + "remote_addr": "127.0.0.4", "scheme": "http", "server_name": "localhost", "server_port": 1234, - "forwarded": Power - "secret": "mysecret", - "for": "127. .0.4", + "forwarded": { + "secret": "mySecret", + "for": "127.0.0.4", "port": 1234 } } @@ -332,16 +332,16 @@ Power --- -##### 例7 +##### 例七(Example 7) -测试逃逸(如果你看到有人正在执行引用的对等内容，请修改此选项) +测试转义字符（如果发现有人实现引用对，请修改此处） ```sh curl localhost:8000/fwd \ - -H 'Forwar: for=test;quoted="\,x=x;y=\";secret=mysecret' | jq + -H 'Forwarded: for=test;quoted="\,x=x;y=\";secret=mySecret' | jq ``` -.. 列: +.. column:: ```` ```python @@ -352,20 +352,20 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash -# curl replacement -Paper +# curl response +{ "remote_addr": "test", "scheme": "http", "server_name": "localhost", "server_port": 8000, - "forwarded": 许诺, + "forwarded": { "for": "test", - "quoted": "\,x=x; =\\", - "secret": "mysecret" + "quoted": "\\,x=x;y=\\", + "secret": "mySecret" } } ``` @@ -373,16 +373,16 @@ Paper --- -##### 例8 +##### 例八(Example 8) -由格式错误的字段 #1 隔绝的绝密项 +密钥信息因格式错误的字段而被隔绝 #1 ```sh curl localhost:8000/fwd \ - -H 'Forwar: for=test;secret=mySecret;b0rked;proto=wss;' | jq + -H 'Forwarded: for=test;secret=mySecret;b0rked;proto=wss;' | jq ``` -.. 列: +.. column:: ```` ```python @@ -393,7 +393,7 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash @@ -413,16 +413,16 @@ app.config.FORWARDED_SECRET = "mySecret" --- -##### 例9 +##### 例九(Example 9) -由格式不正确的字段 #2 隔热绝的密钥 +密钥信息因格式错误的字段而被隔绝 #2 ```sh curl localhost:8000/fwd \ - -H 'Forwar: for=test;b0rked;secret=mySecret;proto=wss' | jq + -H 'Forwarded: for=test;b0rked;secret=mySecret;proto=wss' | jq ``` -.. 列: +.. column:: ```` ```python @@ -433,18 +433,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash # curl response -WP +{ "remote_addr": "", "scheme": "wss", "server_name": "localhost", "server_port": 8000, - "forwarded": 许诺 - "secret": "mysecret", + "forwarded": { + "secret": "mySecret", "proto": "wss" } } @@ -453,16 +453,16 @@ WP --- -##### 例10 +##### 例十(Example 10) -意外终止不应丢失现有可接受的值 +意外终止不应丢失现有的有效值 ```sh curl localhost:8000/fwd \ - -H 'Forwar: b0rked;secret=mySecret;proto=wss' | jq + -H 'Forwarded: b0rked;secret=mySecret;proto=wss' | jq ``` -.. 列: +.. column:: ```` ```python @@ -473,18 +473,18 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash # curl response -WP +{ "remote_addr": "", "scheme": "wss", "server_name": "localhost", "server_port": 8000, - "forwarded": 许诺 - "secret": "mysecret", + "forwarded": { + "secret": "mySecret", "proto": "wss" } } @@ -493,16 +493,16 @@ WP --- -##### 例11 +##### 例十一(Example 11) -实地正常化 +字段标准化 ```sh curl localhost:8000/fwd \ -H 'Forwarded: PROTO=WSS;BY="CAFE::8000";FOR=unknown;PORT=X;HOST="A:2";PATH="/With%20Spaces%22Quoted%22/sanicApp?key=val";SECRET=mySecret' | jq ``` -.. 列: +.. column:: ```` ```python @@ -513,22 +513,22 @@ app.config.FORWARDED_SECRET = "mySecret" ``` ```` -.. 列: +.. column:: ```` ```bash # curl response -Power +{ "remote_addr": "", "scheme": "wss", "server_name": "a", "server_port": 2, - "转发": Power - "原始": "wss", - "by": "[cafe:8000]", - "主机": "a:2", - "路径": "/With Spaces\"Quoted\"/sanicApp? ey=val", - "secret": "mysecret" + "forwarded": { + "proto": "wss", + "by": "[cafe::8000]", + "host": "a:2", + "path": "/With Spaces\"Quoted\"/sanicApp?key=val", + "secret": "mySecret" } } ``` @@ -536,16 +536,16 @@ Power --- -##### 例12 +##### 例十二(Example 12) -使用“by”字段作为密钥 +使用 "by" 字段作为密钥 ```sh curl localhost:8000/fwd \ - -H 'Forward: for=1.2.3.4; by=_proxySecret' | jq + -H 'Forwarded: for=1.2.3.4; by=_proxySecret' | jq ``` -.. 列: +.. column:: ```` ```python @@ -556,18 +556,18 @@ app.config.FORWARDED_SECRET = "_proxySecret" ``` ```` -.. 列: +.. column:: ```` ```bash # curl response -Power - "remote_addr": "1.2.3。 ", +{ + "remote_addr": "1.2.3.4", "scheme": "http", "server_name": "localhost", "server_port": 8000, - "forwarded": 许诺, - "for": "1. .3.4", + "forwarded": { + "for": "1.2.3.4", "by": "_proxySecret" } } From 2fa341d4fed6ee5aacb03c1c5532a006f47e5762 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 14:07:55 +0300 Subject: [PATCH 631/698] New translations streaming.md (Chinese Simplified) --- guide/content/zh/guide/advanced/streaming.md | 96 ++++++++++---------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/guide/content/zh/guide/advanced/streaming.md b/guide/content/zh/guide/advanced/streaming.md index d6956695ff..b5f38ce7fb 100644 --- a/guide/content/zh/guide/advanced/streaming.md +++ b/guide/content/zh/guide/advanced/streaming.md @@ -1,18 +1,18 @@ -# 流流 +# 流式传输(Streaming) -## 请求流 +## 请求流(Request streaming) -Sanic 允许您在字节到达时开始处理客户端发送的数据。 +Sanic 允许您流式处理客户端发送的数据，以便在字节到达时立即开始处理数据。 -.. 列: +.. column:: ``` -当在端点启用时，您可以使用 `request.stream.read()`。 +当在路由入口上启用流式处理时，您可以使用 `await request.stream.read()` 来流式读取请求体。 -这个方法将在身体完成后返回 `None` 。 +当请求体读取完毕时，该方法将返回 `None`。 ``` -.. 列: +.. column:: ```` ```python @@ -31,99 +31,99 @@ class SimpleView(HTTPMethodView): ``` ```` -.. 列: +.. column:: ``` -它也可以在装饰器中用关键字参数启用... +也可以在装饰器中通过关键字参数启用该功能... ``` -.. 列: +.. column:: ```` ```python @app.post("/stream", stream=True) async def handler(request): ... - body = 等待request.stream.read() + body = await request.stream.read() ... ``` ```` -.. 列: +.. column:: ``` -... 或 "add_route()" 方法。 +... 或者使用`add_route()` 方法 ``` -.. 列: +.. column:: ```` ```python bp.add_route( bp_handler, "/bp_stream", - meths=["POST"], + methods=["POST"], stream=True, ) ``` ```` -.. tip:: FYI +.. tip:: 提示一下 ``` -只有帖子、放置和补丁装饰者有流参数。 +只有post、put和patch这三个装饰器具有stream参数。 ``` -## 响应串流 +## 响应流（Response streaming） -.. 列: +.. column:: ``` -Sanic 允许您将内容流到客户端。 +Sanic 支持向客户端流式传输内容。 ``` -.. 列: +.. column:: ```` ```python @app.route("/") async def test(request): - response = request.reply (content_type="text/csv") - 等待响应。 end("foo,") - 正在等待答复。 end("bar") + response = await request.respond(content_type="text/csv") + await response.send("foo,") + await response.send("bar") - # 可选，您可以通过调用来明确结束流： - 等待响应.eof() + # Optionally, you can explicitly end the stream by calling: + await response.eof() ``` ```` -这在您想要将内容流到外部服务的客户端（如数据库）时是有用的。 例如，您可以通过 "asyncpg" 提供的异步光标将数据库记录流到客户端。 +在需要将源自外部服务（例如数据库）的内容实时传输给客户端的情况下，这项功能非常有用。 举例来说，您可以利用`asyncpg`提供的异步游标将数据库记录逐条流式传输至客户端。 ```python @app.route("/") async def index(request): - response = 等待请求。 espond() - conn = 等待 asyncpg.connect(database='test') - 带有con的异步值。 赎金(): - 异步以内嵌方式记录。 ursor('SELECT generate_series(0, 10)'): - 等待响应.send(records[0]) + response = await request.respond() + conn = await asyncpg.connect(database='test') + async with conn.transaction(): + async for record in conn.cursor('SELECT generate_series(0, 10)'): + await response.send(record[0]) ``` -您可以通过调用 "等待响应.eof()" 来明确结束一个流。 它是一个替换"等待响应.send("", True)"的方便方法。 应该调用 **一次** 之后\* 你的处理程序确定它没有什么可以发送到客户端。 当它是可选的 \* 与 Sanic 服务器使用时，如果您在 ASGI 模式中运行 Sanic ，那么您**必须** 明确终止流。 +您可以通过调用 `await response.eof()` 显式结束一个流。 这是一个便捷方法，替代了 `await response.send("", True)`。 在处理器确定已无任何内容需要发送回客户端后，应调用**一次**此方法。 管在Sanic服务器中使用它是可选的，但如果在ASGI模式下运行Sanic，则必须显式终止流。 -_在 v21.6_ 中，调用 `eof` 变成可选的 +_自v21.6版本起，调用`eof`变为可选_ -## 文件串流 +## 文件流(File streaming) -.. 列: +.. column:: ``` -Sanic 提供 `sanic.response.file_stream` 函数，在您想要发送一个大文件时是有用的。 它返回一个 `StreamingHTTPResponse` 对象，默认情况下将使用区块传输编码；因此Sanic 不在响应中添加 `Content-Length` HTTP头部。 +Sanic 提供了一个名为 `sanic.response.file_stream` 的函数，当您需要发送大文件时，这个函数非常有用。它会返回一个 `StreamingHTTPResponse` 对象，默认采用分块传输编码；因此，Sanic 不会在响应中添加 `Content-Length` HTTP 头部信息。 -典型的使用案例可能是将视频文件串流。 +典型应用场景可能是流式传输视频文件。 ``` -.. 列: +.. column:: ```` ```python @@ -141,29 +141,29 @@ async def handler_file_stream(request): ``` ```` -.. 列: +.. column:: ``` -如果你想要使用 `Content-Length` 标题，你可以仅仅通过添加 `Content-Length` 标题来禁用区块传输编码并手动添加它。 +如果您希望使用 `Content-Length` 头部信息，可以通过禁用分块传输编码并手动添加它来实现。只需简单地向响应中添加 `Content-Length` 头部即可。 ``` -.. 列: +.. column:: ```` ```python -from aiofiles importos as async_os +from aiofiles import os as async_os from sanic.response import file_stream -@app. oute("/") +@app.route("/") async def index(request): file_path = "/srv/www/whatever.png" - file_stat = 等待async_os. tat(file_path) - headers = {"Content-Length": str(file_stat. t_size)} + file_stat = await async_os.stat(file_path) + headers = {"Content-Length": str(file_stat.st_size)} - 返回等待文件流( + return await file_stream( file_path, headers=headers, - + ) ``` ```` From 38e870bd77bdf0adf523d7a24bd146ed6d78c57f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 14:07:57 +0300 Subject: [PATCH 632/698] New translations versioning.md (Chinese Simplified) --- guide/content/zh/guide/advanced/versioning.md | 51 ++++++++++--------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/guide/content/zh/guide/advanced/versioning.md b/guide/content/zh/guide/advanced/versioning.md index 39bc5b76ab..6d976c6cf9 100644 --- a/guide/content/zh/guide/advanced/versioning.md +++ b/guide/content/zh/guide/advanced/versioning.md @@ -1,31 +1,31 @@ -# Versioning +# 版本控制（Versioning） -API 构建中的标准做法是将版本添加到您的端点。 这使您能够轻松区分不兼容的端点，当您尝试并以破解的方式更改您的 API。 +在API构建的标准实践中，向路由入口添加版本是一种常见做法。 这样，当您在未来以破坏性方式更改API时，可以轻松区分不兼容的路由入口。 -Adding a version will add a `/v{version}` url prefix to your endpoints. +添加版本号将会在您的路由入口前加上 `/v{version}` 形式的URL前缀。 -版本可以是 `int`、`float`、`str`。 可接受值： +版本可以是 `int`、`float`、`str`类型 下列值都为有效值： - `1`, `2`, `3` - `1.1`, `2.25`, `3.0` -- `"1", `v1", `"v1.1"` +- `"1"`, `"v1"`, `"v1.1"` -## 每条路由 +## 单个路由（Per route） -.. 列: +.. column:: ``` -您可以直接将版本号传递给路由。 +您可以直接向路由传递版本号。 ``` -.. 列: +.. column:: ```` ```python # /v1/text @app.route("/text", version=1) def handle_request(request): - return response. ext("Hello world! Version 1") + return response.text("Hello world! Version 1") # /v2/text @app.route("/text", version=2) @@ -34,42 +34,44 @@ def handle_request(request): ``` ```` -## 每个蓝图 +## 单个蓝图（Per Blueprint） -.. 列: +.. column:: ``` -您也可以将版本号传递到蓝图，这将适用于该蓝图中的所有路线。 +您还可以向蓝图传递版本号，这样该版本号将应用于该蓝图内的所有路由。 ``` -.. 列: +.. column:: ```` ```python -bp = Blueprint("test", url_prefix="/fo", version=1) +bp = Blueprint("test", url_prefix="/foo", version=1) -# /v1/fo/html +# /v1/foo/html @bp.route("/html") def handle_request(request): return response.html("

Hello world!

") ``` ```` -## 每个蓝图组 +## 单个蓝图组（Per Blueprint Group） -.. 列: +.. column:: ``` -为了简化版本化蓝图的管理，您可以在蓝图中提供版本号组。如果蓝图还没有覆盖，那么同样的将被继承到分组在它下面的所有蓝图与创建蓝图实例时指定的值相同的信息。 +为了简化版本化蓝图的管理，您可以在蓝图组中提供一个版本号。如果蓝图在创建实例时未指定覆盖相同信息的值，那么同一版本号将自动应用于该蓝图组下的所有蓝图。 + +在使用蓝图组管理版本时，将按照以下顺序将Version前缀应用于正在注册的路由： -当使用蓝图组来管理版本时，遵循以下顺序将Version前缀应用于正在注册的路由。 +1. 路由级别的配置 +2. 蓝图级别的配置 +3. 蓝图组级别的配置 -1. 路由级别配置 -2. 蓝图级配置 -3. 组级配置 +如果我们发现更具体的版本化规范，我们将优先选择它，而不是蓝图或蓝图组中提供的更通用的版本化规范。 ``` -.. 列: +.. column:: ```` ```python @@ -84,6 +86,7 @@ bp1 = Blueprint( bp2 = Blueprint( name="blueprint-2", url_prefix="/bp2", +) group = Blueprint.group( [bp1, bp2], From 7be2835b24593fdb5e95436204e6540b186b1c4c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 14:07:58 +0300 Subject: [PATCH 633/698] New translations websockets.md (Chinese Simplified) --- guide/content/zh/guide/advanced/websockets.md | 72 +++++++++---------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/guide/content/zh/guide/advanced/websockets.md b/guide/content/zh/guide/advanced/websockets.md index 636fdaf3f7..62bcbed8d2 100644 --- a/guide/content/zh/guide/advanced/websockets.md +++ b/guide/content/zh/guide/advanced/websockets.md @@ -1,88 +1,88 @@ # Websockets -Sanic 提供了一个易于使用的 [websockets]顶部的摘要(https://websockets.readthedocs.io/en/stable/)。 +Sanic 提供了一个基于 [websockets](https://websockets.readthedocs.io/en/stable/) 的易于使用的抽象层 -## 路由 +## 路由(Routing) -.. 列: +.. column:: ``` -Websocket 处理程序可以绑定到路由器，类似于常规处理程序。 +Websocket 处理程序可以像常规处理程序那样连接到路由器上。 ``` -.. 列: +.. column:: ```` ```python from sanic import Request, Websocket -async def Feed(request: Request, ws: Websocket): - pask +async def feed(request: Request, ws: Websocket): + pass -appp dd_websocket_route(feed, "/feed") +app.add_websocket_route(feed, "/feed") ``` ```python from sanic import Request, Websocket -@app. ebsocket("/feed") -async def Feed(request, ws: Websocket): - passe +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + pass ``` ```` -## Handler +## 定义响应函数(Handler) -.. 列: +.. column:: ``` -通常情况下，一个 websocket 处理程序将会保持打开一个循环。 +通常情况下，websocket 处理程序会维持一个循环保持打开状态。 -然后它可以在注入处理器的第二个对象上使用 `send()` 和 `recv()` 方法。 +然后，可以在注入到处理程序的第二个对象上调用 `send()` 和 `recv()` 方法。 -这个示例是一个简单的端点，回溯到它收到的客户端消息。 +下面是一个简单的示例，该端点接收来自客户端的消息并将其回显给客户端。 ``` -.. 列: +.. column:: ```` ```python -来自sanic import Request, Websocket +from sanic import Request, Websocket -@app. ebsocket("/feed") -async def Feed(请求: 请求, ws: Websocket: +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): while True: - data = "hello! - 打印("发送：" + 数据) - 等待ws。 end(data) - data = 等待ws。 ecv() - 打印("接收：" + 数据) + data = "hello!" + print("Sending: " + data) + await ws.send(data) + data = await ws.recv() + print("Received: " + data) ``` ```` -.. 列: +.. column:: ``` -You can simplify your loop by just iterating over the `Websocket` object in a for loop. +您可以通过在一个for循环中迭代 `Websocket` 对象来简化您的循环。 -*Added in v22.9* +*该特性在v22.9版本中添加* ``` -.. 列: +.. column:: ```` ```python -来自sanic import Request, Websocket +from sanic import Request, Websocket -@app. ebsocket("/feed") -async def Feed(请求: 请求, ws: Websocket: - async for msg in w: - 等待w. end(msg) +@app.websocket("/feed") +async def feed(request: Request, ws: Websocket): + async for msg in ws: + await ws.send(msg) ``` ```` -## 配置 +## 配置(Configuration) -详见[配置部分](/guide/deplement/configuration.md)，但默认值显示在下面。 +更多详情请参阅[配置部分](/zh/guide/deployment/configuration.md)，不过下面列出了默认值。 ```python app.config.WEBSOCKET_MAX_SIZE = 2 ** 20 From d5f8f7036119c447c7d3e6d9a16628f8ef7cca95 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 14:07:59 +0300 Subject: [PATCH 634/698] New translations tasks.md (Chinese Simplified) --- guide/content/zh/guide/basics/tasks.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/guide/content/zh/guide/basics/tasks.md b/guide/content/zh/guide/basics/tasks.md index 0ce1048a65..dcdabddfe0 100644 --- a/guide/content/zh/guide/basics/tasks.md +++ b/guide/content/zh/guide/basics/tasks.md @@ -89,7 +89,7 @@ app.run(...) 创建任务时，通过提供一个`name`，你可以让Sanic帮你跟踪这个任务。 ``` -.. 列: +.. column:: ```` ```python @@ -97,13 +97,13 @@ app.add_task(troub_work, name="low_task") ``` ```` -.. 列: +.. column:: ``` -您现在可以使用`get_task`从应用程序中的任何地方检索该任务实例。 +现在，你可以在应用程序的任何地方使用`get_task`来检索该任务实例。 ``` -.. 列: +.. column:: ```` ```python @@ -111,13 +111,13 @@ task = app.get_task("slow_task") ``` ```` -.. 列: +.. column:: ``` -如果该任务需要取消，你可以使用 "cancel_task" 来完成。请确保你"等待"。 +如果需要取消该任务，你可以使用`cancel_task`来完成。确保对它进行`await`调用。 ``` -.. 列: +.. column:: ```` ```python @@ -125,13 +125,13 @@ await app.cancel_task("slow_task") ``` ```` -.. 列: +.. column:: ``` -所有注册的任务都可以在 `app.tasks` 属性中找到。为了防止被取消的任务填充，您可能想要运行 `app。 urge_tasks`将清除任何已完成或已取消的任务。 +所有已注册的任务都可以在`app.tasks`属性中找到。为了避免被取消的任务占用空间，你可能想要运行`app.purge_tasks`，它会清除所有已完成或被取消的任务。 ``` -.. 列: +.. column:: ```` ```python @@ -139,7 +139,7 @@ app.purge_tasks() ``` ```` -这种模式在 `websockets` 中特别有用： +这种模式在处理`websockets`时尤其有用： ```python async def receiver(ws): @@ -163,4 +163,4 @@ async def feed(request, ws): request.app.purge_tasks() ``` -_添加于 v21.12_ +\*添加于 v21.12 \* From 6a11ec978f8be02f229f390ee23d37a81aca4352 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 15:10:53 +0300 Subject: [PATCH 635/698] New translations signals.md (Chinese Simplified) --- guide/content/zh/guide/advanced/signals.md | 282 ++++++++++----------- 1 file changed, 141 insertions(+), 141 deletions(-) diff --git a/guide/content/zh/guide/advanced/signals.md b/guide/content/zh/guide/advanced/signals.md index b691c669da..2057626226 100644 --- a/guide/content/zh/guide/advanced/signals.md +++ b/guide/content/zh/guide/advanced/signals.md @@ -1,63 +1,63 @@ -# 信号 +# 信号(Signals) -信号为您的应用程序的一部分提供了一种方法来告诉另一个部分发生了一些事情。 +信号提供了一种方式，使得应用程序的一部分能够通知另一部分发生了某件事情。 ```python @app.signal("user.registration.created") async def send_registration_email(**context): - 等待 send_email(context["email"], template="registration") + await send_email(context["email"], template="registration") -@app. ost("/register") +@app.post("/register") async def handle_registration(request): - 等待do_registration(request) - 等待请求。 pp.apparch( - "user.registration" 恢复了", + await do_registration(request) + await request.app.dispatch( + "user.registration.created", context={"email": request.json.email} -}) + }) ``` -## 添加信号 +## 添加信号(Adding a signal) -.. 列: +.. column:: ``` -用于添加信号的 API 与添加路由非常相似。 +添加信号的 API 与添加路由非常相似。 ``` -.. 列: +.. column:: ```` ```python async def my_signal_handler(): - print("发生了什么") + print("something happened") -app.add_signal(my_signal_handler, "something.oced.ohmy") +app.add_signal(my_signal_handler, "something.happened.ohmy") ``` ```` -.. 列: +.. column:: ``` -但也许一种略为方便的方法是使用内置装饰器。 +但是，也许使用内置装饰器的方法更为便捷一些。 ``` -.. 列: +.. column:: ```` ```python -@app.signal("something.semed.ohmy") -async def my_signal_handler(: - print("发生什么") +@app.signal("something.happened.ohmy") +async def my_signal_handler(): + print("something happened") ``` ```` -.. 列: +.. column:: ``` -如果信号需要条件，请确保在添加处理器时添加它们。 +如果信号需要满足某些条件，请确保在添加处理器时添加这些条件。 ``` -.. 列: +.. column:: ```` ```python @@ -76,104 +76,104 @@ async def my_signal_handler2(): ``` ```` -.. 列: +.. column:: ``` 信号也可以在蓝图上声明 ``` -.. 列: +.. column:: ```` ```python bp = Blueprint("foo") -@bp.signal("something.semed.ohmy") +@bp.signal("something.happened.ohmy") async def my_signal_handler(): - print("发生什么") + print("something happened") ``` ```` -## 内置信号 +## 内置信号(Built-in signals) -除了发出新的信号外，还有一些内在信号是从萨尼克本身发出的。 这些信号的存在为开发者提供了更多的机会，可以将功能添加到请求和服务器的周期中。 +除了创建新的信号外，Sanic 自身还分发了一些内置信号。 这些信号的存在是为了为开发者提供更多机会在请求和服务器生命周期中添加功能。 \*添加于 v21.9 \* -.. 列: +.. column:: ``` -您可以像其他任何信号一样将它们附加到应用程序或蓝图实例。 +您可以像对待其他任何信号一样，将它们附加到应用或蓝图实例上。 ``` -.. 列: +.. column:: ```` ```python @app.signal("http.lifecycle.complete") async def my_signal_handler(conn_info): - print("连接已关闭") + print("Connection has been closed") ``` ```` -这些信号是现有的信号，以及处理者的论据和附加条件（如有）。 +这些信号是可用的信号，包括处理器所需处理的参数以及（如果有）附带的条件。 -| 事件名称 | 参数 | 条件 | -| -------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | -| `http.routing.before` | 请求 | | -| `http.routing.after ` | 请求, 路由, kwargs, 处理程序 | | -| `http.handler.befor` | 请求 | | -| `http.handler.after ` | 请求 | | -| `http.lifecycle.begin` | conn_info | | -| `http.lifecycle.read_head` | 头部 | | -| `http.lifecycle.request` | 请求 | | -| `http.lifecycle.handle` | 请求 | | -| `http.lifecycle.read_body` | 正文内容 | | -| `http.lifecycle.excition` | 请求异常 | | -| `http.lifecycle.response` | 请求回复 | | -| `http.lifecycle.send` | 数据 | | -| `http.lifecycle.complete` | conn_info | | -| `http.midleware.before` | 请求回复 | \`{"attach_to": "request"}" 或 "{"attach_to": "response"}" | -| `http.midleware.after ` | 请求回复 | \`{"attach_to": "request"}" 或 "{"attach_to": "response"}" | -| `server.exception.report` | 应用，异常 | | -| `server.init.before` | 应用，循环 | | -| `server.init.after ` | 应用，循环 | | -| `server.shutdown.before` | 应用，循环 | | -| `server.shutdown.after ` | 应用，循环 | | +| 事件名称（Event name） | 参数（Arguments） | 条件（Conditions） | +| -------------------------- | ------------------------------- | --------------------------------------------------------- | +| `http.routing.before` | request | | +| `http.routing.after` | request, route, kwargs, handler | | +| `http.handler.before` | request | | +| `http.handler.after` | request | | +| `http.lifecycle.begin` | conn_info | | +| `http.lifecycle.read_head` | head | | +| `http.lifecycle.request` | request | | +| `http.lifecycle.handle` | request | | +| `http.lifecycle.read_body` | body | | +| `http.lifecycle.exception` | request, exception | | +| `http.lifecycle.response` | request, response | | +| `http.lifecycle.send` | data | | +| `http.lifecycle.complete` | conn_info | | +| `http.middleware.before` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `http.middleware.after` | request, response | `{"attach_to": "request"}` or `{"attach_to": "response"}` | +| `server.exception.report` | app, exception | | +| `server.init.before` | app, loop | | +| `server.init.after` | app, loop | | +| `server.shutdown.before` | app, loop | | +| `server.shutdown.after` | app, loop | | -22.9版本增加了`http.handler.before`和`http.handler.after`。 +22.9版本增加了 `http.handler.before` 和 `http.handler.after` 。 -版本23.6增加了“server.exception.report”。 +版本23.6增加了 `server.exception.report` 。 -.. 列: +.. column:: ``` -为了更容易使用内置信号，有一个 `Enum` 对象包含所有允许的内嵌。 使用现代IDE，这将有助于您不需要记住事件名称的完整列表作为字符串。 +为了更方便地使用内置信号，这里有一个包含所有允许内置信号的 `Enum` 对象。在现代 IDE 中，这将有助于您无需记忆作为字符串形式的所有事件名称列表。 -*添加于 v21.12* +*从 v21.12 版本开始新增* ``` -.. 列: +.. column:: ```` ```python -from sanic.signs import Event +from sanic.signals import Event -@app.signal(Event.HTTP_LIFECYCLE_COMPerTE) +@app.signal(Event.HTTP_LIFECYCLE_COMPLETE) async def my_signal_handler(conn_info): - print("连接已关闭") + print("Connection has been closed") ``` ```` -## 事件 +## 事件(Events) -.. 列: +.. column:: ``` -信号来自一个 _event_。事件只是以下模式中的一个字符串： +信号基于某个 _事件_ 。事件实际上就是一个遵循以下模式的字符串： ``` -.. 列: +.. column:: ```` ``` @@ -181,22 +181,22 @@ namespace.reference.action ``` ```` -.. 提示：事件必须有三个部分。 如果您不知道要使用什么，请尝试这些模式： +.. tip:: 事件必须包含三个部分。 如果您不确定该如何使用，请尝试以下模式： ``` -- `my_app.something.oced` -- `sanic.notific.hello` +- `my_app.something.happened` +- `sanic.notice.hello` ``` -### 事件参数 +### 事件参数(Event parameters) -.. 列: +.. column:: ``` -事件可以是“动态”并声明使用与 [路径参数] (../basics/routing.md#path参数)相同的语法。这允许根据任意值进行匹配。 +事件可以是“动态”的，并使用与[路径参数](../basics/routing.md#path-parameters)相同的语法进行声明。这样就可以基于任意值进行匹配。 ``` -.. 列: +.. column:: ```` ```python @@ -204,92 +204,92 @@ namespace.reference.action async def signal_handler(thing): print(f"[signal_handler] {thing=}") -@appp. et("/") -async def 触发器(请求): - 等待app.prespatch("foo.bar.baz") - return response.text("完成") +@app.get("/") +async def trigger(request): + await app.dispatch("foo.bar.baz") + return response.text("Done.") ``` ```` -签出[路径参数](../basics/routing.md#path参数)以获取关于允许类型定义的更多信息。 +有关允许的类型定义的更多信息，请查阅[路径参数](../basics/routing.md#path-parameters)。 -.. 信息：事件的第三部分 (动作) 可能是动态的： +.. info:: 只有事件的第三部分（动作）可以是动态的： ``` - `foo.bar.` 🆗 - `foo..baz` ❌ ``` -### 等待中 +### 等待(Waiting) -.. 列: +.. column:: ``` -除了执行信号处理程序外，您的应用程序可以等待事件触发的时间。 +除了执行信号处理器之外，您的应用程序还可以等待某个事件被触发。 ``` -.. 列: +.. column:: ```` ```python -等待app.event("foo.bar.baz") - +await app.event("foo.bar.baz") +``` ```` -.. 列: +.. column:: ``` -**IMPORTANT**：等待是一个阻止函数。因此，你很可能想要这个函数在[背景任务](../basics/tasks.md)中运行。 +**重要提示**：等待是一个阻塞函数。因此，您可能希望将其在一个[后台任务](../basics/tasks.md)中运行。 ``` -.. 列: +.. column:: ```` ```python async def wait_for_event(app): while True: - print("> 等待") - 等待应用。 vent("foo.bar. 日") + print("> waiting") + await app.event("foo.bar.baz") print("> event found\n") -@app. fter_server_start -async def after _server_start(app, loop): +@app.after_server_start +async def after_server_start(app, loop): app.add_task(wait_for_event(app)) ``` ```` -.. 列: +.. column:: ``` -如果你的事件是用动态路径定义的，你可以使用 "*" 来捕捉任何动作。 +如果您的事件使用了动态路径定义，您可以使用 `*` 来捕获任何动作。 ``` -.. 列: +.. column:: ```` ```python -@app.signal("foo.bar. +@app.signal("foo.bar.") ... -等待app.event("foo.bar.*") +await app.event("foo.bar.*") ``` ```` -## 正在发送 +## 触发/派发/分发(Dispatching) -_今后，Sanic将自动发送一些事件以帮助开发人员将其绑定到生命周期活动中。_ +_在未来，Sanic 将自动分发一些事件以帮助开发者接入生命周期事件。_ -.. 列: +.. column:: ``` -调度一个事件会做两个事情： +触发一个事件将会执行两件事： -1，执行事件定义的任何信号处理和 -2。 解决“等待”事件完成的任何问题。 +1. 执行该事件上定义的所有信号处理器， +2. 处理所有正在“等待”该事件完成的任务。 ``` -.. 列: +.. column:: ```` ```python @@ -297,22 +297,22 @@ _今后，Sanic将自动发送一些事件以帮助开发人员将其绑定到 async def foo_bar(thing): print(f"{thing=}") -等待app.appailch("foo.bar.baz") +await app.dispatch("foo.bar.baz") ``` ``` thing=baz ``` ```` -### 二. 背景 +### 上下文(Context) -.. 列: +.. column:: ``` -有时您可能会发现需要将额外信息传递到信号处理器。 在我们上面的第一个例子中，我们希望我们的电子邮件注册过程有用户的电子邮件地址。 +有时您可能会发现有必要向信号处理器传递额外信息。在上面的第一个示例中，我们希望电子邮件注册过程能拥有用户的电子邮件地址。 ``` -.. 列: +.. column:: ```` ```python @@ -320,8 +320,8 @@ thing=baz async def send_registration_email(**context): print(context) -等待应用。 ispatch( - "user.registration" 恢复了", +await app.dispatch( + "user.registration.created", context={"hello": "world"} ) ``` @@ -330,71 +330,71 @@ async def send_registration_email(**context): ``` ```` -.. tip:: FYI +.. tip:: 提示一下 ``` -在后台任务中发出信号。 +信号是在后台任务中分发的。 ``` -### 蓝图 +### 蓝图(Blueprints) -正在发送蓝图信号的概念与 [middleware]相似(../basics/midleware.md)。 从应用层面做的任何事情都会被推到蓝图。 然而，在蓝图上派遣部队只会执行该蓝图上所确定的信号。 +触发蓝图信号的概念类似于 [中间件](../basics/middleware.md). 从应用级别所做的任何操作都将传递到蓝图。 然而，在蓝图上触发信号时，只会执行该蓝图上定义的信号。 -.. 列: +.. column:: ``` -或许一个例子更容易解释： +或许来个例子更容易解释： ``` -.. 列: +.. column:: ```` ```python bp = Blueprint("bp") -app_count = 0 -bp_count = 0 +app_counter = 0 +bp_counter = 0 -@app.signal("foo). ar.baz") +@app.signal("foo.bar.baz") def app_signal(): - non-local app_count - app_count += 1 + nonlocal app_counter + app_counter += 1 -@bp. ignal("foo.bar.baz") +@bp.signal("foo.bar.baz") def bp_signal(): - non-local bp_count - bp_count += 1 + nonlocal bp_counter + bp_counter += 1 ``` ```` -.. 列: +.. column:: ``` -正在运行 `app.appotich("foo.bar.baz")` 将执行两个信号。 +运行 `app.dispatch("foo.bar.baz")` 将会执行两个信号。 ``` -.. 列: +.. column:: ```` ```python -正在等待 app.appoquarch("foo.bar.baz") -确认app_count == 1 -申述bp_count == 1 +await app.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 1 ``` ```` -.. 列: +.. column:: ``` -运行 `bp.apparch("foo.bar.baz")` 只会执行蓝图信号。 +运行 `bp.dispatch("foo.bar.baz")` 将只执行蓝图上的信号。 ``` -.. 列: +.. column:: ```` ```python -等待bp.apparch("foo.bar.baz") -conflict app_count == 1 -conflict bp_count == 2 +await bp.dispatch("foo.bar.baz") +assert app_counter == 1 +assert bp_counter == 2 ``` ```` From 3f88dea62a9975107d95e90d850d745753e5b2a7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 10 Apr 2024 15:10:54 +0300 Subject: [PATCH 636/698] New translations versioning.md (Chinese Simplified) --- guide/content/zh/guide/advanced/versioning.md | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/guide/content/zh/guide/advanced/versioning.md b/guide/content/zh/guide/advanced/versioning.md index 6d976c6cf9..5e21bfc75c 100644 --- a/guide/content/zh/guide/advanced/versioning.md +++ b/guide/content/zh/guide/advanced/versioning.md @@ -111,29 +111,29 @@ async def handle_endpoint_2_bp2(request): ``` ```` -## 版本前缀 +## 版本前缀(Version prefix) -如上文所见，适用于路由的 `version` 总是生成的 URI 路径中的第一个部分。 因此，为了能够在版本之前添加路径段, 每个传递`version`参数的地方, 你也可以通过 `version_prefix`. +如上所述，应用于路由的版本始终是生成URI路径中的第一个部分。 因此，为了能够在版本之前添加路径部分，您在传入版本参数的所有位置都可以同时传入`version_prefix`参数，从而实现这一目的。 -`version_prefix`参数可以定义于： +`version_prefix` 参数可以定义于： -- `app.route` 和 `bp.route` 装饰符 (也包括所有方便装饰师) +- `app.route` 和 `bp.route` 装饰器 (也包括所有便捷的装饰器） - `Blueprint` 实例 -- `Blueprint.group` 构造函数 +- `Blueprint.group` 构造函数 - `BlueprintGroup` 实例 -- `app.bluprint` 注册 +- `使用 `app.blueprint\` 注册蓝图时 -如果在多个地方有定义，则更具体的定义优先于较一般的定义。 这个列表提供了这个等级。 +如果有多个位置定义，较具体的定义会覆盖较一般的定义。 本列表提供了这一层级关系。 -`version_prefix`的默认值是 `/v`。 +版本控制前缀`version_prefix`的默认值是 `/v`。 -.. 列: +.. column:: ``` -一个经常请求的功能是能够在`/api`上挂载版本路由。这可以很容易地通过`version_prefix`来完成。 +一个常被要求的功能是在 `/api` 上挂载版本化的路由。这可以通过 `version_prefix` 轻松实现。 ``` -.. 列: +.. column:: ```` ```python @@ -142,13 +142,13 @@ app.route("/my/path", version=1, version_prefix="/api/v") ``` ```` -.. 列: +.. column:: ``` -或许一个更令人信服的用法是将所有的`/api`路由加载到一个单一的`蓝图组'。 +或许一个更具说服力的用法是将所有 `/api` 路由加载到单个 `BlueprintGroup` 中。 ``` -.. 列: +.. column:: ```` ```python @@ -166,16 +166,16 @@ app.blueprint(api) ``` ```` -因此，我们可以了解到路由的 URI 是： +因此我们可以得知，一个路由的 URI 是由下面基本构成的： ``` -version_prefix + 版本 + url_prefix + URI 定义 +version_prefix + version + url_prefix + URI definition ``` -.. tip:: +.. tip:: 提示 ```` -Just like with `url_prefix`, it is possible to define path parameters inside a `version_prefix`. It is perfectly legitimate to do this. Just remember that every route will have that parameter injected into the handler. +就像 `url_prefix` 一样，在 `version_prefix` 内部定义路径参数也是可能的。这样做完全合理。但请记住，每个路由都会将该参数注入到处理器中。 ```python version_prefix="//v" From 35c99c3872be2e4d5349d13af3b974fe69007878 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 23 Jun 2024 01:49:21 +0300 Subject: [PATCH 637/698] New translations request.md (Japanese) --- guide/content/ja/guide/basics/request.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/guide/content/ja/guide/basics/request.md b/guide/content/ja/guide/basics/request.md index d1820d093f..fa39536332 100644 --- a/guide/content/ja/guide/basics/request.md +++ b/guide/content/ja/guide/basics/request.md @@ -188,11 +188,9 @@ File(type='application/octet-stream', body=b'hello\n', name='TEST') デフォルトでは `request.ctx` オブジェクトは `SimpleNamespace` オブジェクトで、任意の属性を設定できます。 Sanicはこのオブジェクトを何にも使用しないので、名前の衝突を心配することなく自由に使用できます。 -````python - -### Typical use case +### 典型的な使用例 -This is often used to store items like authenticated user details. We will get more into [middleware](./middleware.md) later, but here is a simple example. +これは、認証されたユーザーの詳細などのアイテムを格納するためによく使用されます。 あとで [middleware](./middleware.md) に入りますが、ここに簡単な例があります。 ```python @app.on_request @@ -204,7 +202,7 @@ async def hi_my_name_is(request): if not request.ctx.user: return text("Hmm... I don't know you) return text(f"Hi, my name is {request.ctx.user.name}") -```` +``` ご覧のとおり、 `request. tx`オブジェクトは、複数のハンドラにアクセスするために必要な情報を格納するのに最適な場所です。 しかし、format@@0(./middleware) で学びます。 d)を使用して、別のミドルウェアから情報を保存することもできます。 From beec90a223cf1c9b624facc649f5d8c39efd063c Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 23 Jun 2024 01:49:23 +0300 Subject: [PATCH 638/698] New translations request.md (Korean) --- guide/content/ko/guide/basics/request.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/guide/content/ko/guide/basics/request.md b/guide/content/ko/guide/basics/request.md index c3dd8d08d9..def760cd80 100644 --- a/guide/content/ko/guide/basics/request.md +++ b/guide/content/ko/guide/basics/request.md @@ -188,8 +188,6 @@ This can be constrasted with the `app.ctx` object which is shared across all req The `request.ctx` object by default is a `SimpleNamespace` object allowing you to set arbitrary attributes on it. Sanic will not use this object for anything, so you are free to use it however you want without worrying about name clashes. -````python - ### Typical use case This is often used to store items like authenticated user details. We will get more into [middleware](./middleware.md) later, but here is a simple example. @@ -204,7 +202,7 @@ async def hi_my_name_is(request): if not request.ctx.user: return text("Hmm... I don't know you) return text(f"Hi, my name is {request.ctx.user.name}") -```` +``` As you can see, the `request.ctx` object is a great place to store information that you need to access in multiple handlers making your code more DRY and easier to maintain. But, as we will learn in the [middleware section](./middleware.md), you can also use it to store information from one middleware that will be used in another. From c3195e1ffd3154c8bf28ccdfffeebe29b927e1d3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 23 Jun 2024 01:49:24 +0300 Subject: [PATCH 639/698] New translations request.md (Chinese Simplified) --- guide/content/zh/guide/basics/request.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/guide/content/zh/guide/basics/request.md b/guide/content/zh/guide/basics/request.md index 5aaee24e08..f387bdb28f 100644 --- a/guide/content/zh/guide/basics/request.md +++ b/guide/content/zh/guide/basics/request.md @@ -187,11 +187,9 @@ request.ctx 对象是存储请求相关信息的地方。 它仅在请求的生 默认情况下，request.ctx对象是一个SimpleNamespace对象，允许您在其上设置任意属性。 Sanic不会对此对象做任何用途，因此您可以自由地按照需要使用它，无需担心名称冲突问题。 -````python - ### 典型应用场景 -这种做法常用于存储诸如认证用户详情之类的数据。我们将在后面的[middleware](./middleware.md)部分详细介绍，但这里先给出一个简单的示例。 +这常常用来存储像认证用户详细信息这样的项目。 稍后我们会更多地进入 [middleware](./medileware.md)，但这是一个简单的例子。 ```python @app.on_request @@ -203,7 +201,7 @@ async def hi_my_name_is(request): if not request.ctx.user: return text("Hmm... I don't know you) return text(f"Hi, my name is {request.ctx.user.name}") -```` +``` 如您所见，`request.ctx`对象是一个很好的位置，用于存储您需要在多个处理器中访问的信息，从而使您的代码更加遵循DRY原则（Don't Repeat Yourself），也更易于维护。 但是，正如我们在中间件章节中将要学习的那样，您还可以使用它来存储在一个中间件中产生的信息，这些信息将在另一个中间件中使用。 @@ -276,13 +274,13 @@ app = Sanic("Example", request_class=CustomRequest) ``` ```` -.. column:: +.. 列: ``` 现在，您可以在处理器中访问 `user_id` 属性。 ``` -.. 列: +.. column:: ```` ```python @@ -366,7 +364,7 @@ async def tag_handler(request, *, tag): 这些让您能够从请求路径中访问查询参数（URL中`?`号后面的部分）。 -### 典型应用场景 +### 典型的使用情况 在大多数情况下，您将想使用 `request.args` 对象来访问查询参数。 它是解析后的查询字符串，存储为一个字典。 From 71213bc705a27ce48a1538e627c9cfb3f6352214 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:14:21 +0300 Subject: [PATCH 640/698] New translations listeners.md (Japanese) --- guide/content/ja/guide/basics/listeners.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/guide/content/ja/guide/basics/listeners.md b/guide/content/ja/guide/basics/listeners.md index 9afa449294..db4413323d 100644 --- a/guide/content/ja/guide/basics/listeners.md +++ b/guide/content/ja/guide/basics/listeners.md @@ -256,11 +256,7 @@ In the above example, notice how there are three processes running: ### 優先度 -.. new:: v23.12 - -``` -v23.12 では `priority` キーワード引数がリスナーに追加されました。これによりリスナーの実行順序を微調整できます。 デフォルトの優先度は `0` です。優先度が高いリスナーは最初に実行されます。 同じ優先度を持つリスナーは、登録された順に実行されます。 さらに、 `app` インスタンスにアタッチされたリスナーは、 `Blueprint` インスタンスにアタッチされたリスナーの前に実行されます。 -``` +v23.12 では `priority` キーワード引数がリスナーに追加されました。 これにより、リスナーの実行順序を微調整できます。 デフォルトの優先度は `0` です。 優先度が高いリスナーが最初に実行されます。 同じ優先度を持つリスナーは、登録された順に実行されます。 さらに、 `app` インスタンスにアタッチされたリスナーは、 `Blueprint` インスタンスにアタッチされたリスナーの前に実行されます。 全体的に実行の順序を決定するためのルールは次のとおりです。 From 58edc8eb0ff2da945556662004797971e3abfefe Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:14:44 +0300 Subject: [PATCH 641/698] New translations development.md (Japanese) --- guide/content/ja/guide/running/development.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/guide/content/ja/guide/running/development.md b/guide/content/ja/guide/running/development.md index 6080a1d55a..5b83a7935e 100644 --- a/guide/content/ja/guide/running/development.md +++ b/guide/content/ja/guide/running/development.md @@ -76,11 +76,7 @@ sanic path.to:app -r -R /path/to/one -R /path/to/two ## 開発REPL -.. new:: v23.12 - -``` -Sanic CLI には、アプリケーションとやり取りするために使用できる REPL (別名「read-eval-print loop」)が付属しています。 これはデバッグとテストに役立ちます。REPL は引数なしで `python` を実行するときに得られる対話型シェルです。 -``` +Sanic CLI には、アプリケーションとやり取りするために使用できる REPL (別名「read-eval-print loop」)が付属しています。 これはデバッグやテストに役立ちます。 REPL は引数なしで `python` を実行すると得られる対話型シェルです。 .. 列:: @@ -231,9 +227,9 @@ _v23.12_ に追加されました .. 列:: ``` -デバッグモードにしたい場合は、自動リロードを実行している**と**、`dev=True`を渡すことができます。 これは**debug + auto reload**と同等です。 +デバッグモードにしたい場合は、自動リロードを実行している**と**、`dev=True`を渡すことができます。 これは**debug + auto reload + REPL** と同等です。 -*v22.3*に追加されました +*v22.3* に追加されました ``` .. 列:: @@ -248,13 +244,10 @@ sanic path.to:app -d ``` も使用できます。 ```` -.. new:: v23.12 +v23.12 の `--dev` フラグに追加すると、REPLを開始することができます。 詳細は、format@@0(./development.md#development-repl) セクションを参照してください。 -``` -`--dev` フラグに v23.12 を追加すると、REPLを開始することができます。format@@0()を参照してください。 詳細は development.md#development-repl) セクションを参照してください。 - -V23 の時点。 2, `--dev` フラグは `--debug --reload --repl` とほぼ同じです。 `--dev` を使用すると、明示的に `--repl` フラグを渡すと、REPL を開始する必要があります。 -``` +v23.12 では、`--dev` フラグは `--debug --reload -repl` とほぼ同じです。 `--dev` を使用すると、明示的に `--repl` フラグを渡すと、REPL を開始する必要があります。 +v23.12 より前の `--dev` フラグは `--debug --reload` によく似ています。 .. 列:: From 3881468e2bf6b4edc5e44a318eee96d52da30fbc Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:14:46 +0300 Subject: [PATCH 642/698] New translations manager.md (Japanese) --- guide/content/ja/guide/running/manager.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/guide/content/ja/guide/running/manager.md b/guide/content/ja/guide/running/manager.md index 606ce8ed38..f1c4c0a919 100644 --- a/guide/content/ja/guide/running/manager.md +++ b/guide/content/ja/guide/running/manager.md @@ -412,15 +412,11 @@ async def ready(app: Sanic, _): ### 追跡されていないプロセス -.. new:: v23.12 +Sanicは全プロセスの状態を追跡します。 これは、 [multiplexer](./manager#access-to-the-multiplexer) オブジェクト、または [Inspector](./manager#inspector) からプロセスの状態にアクセスできることを意味します。 -``` -Out of the box, Sanic will track the state of all processes. This means that you can access the state of the process from the [multiplexer](./manager#access-to-the-multiplexer) object, or from the [Inspector](./manager#inspector). - -See [worker state](./manager#worker-state) for more information. +詳細は format@@0(./manager#worker-state) を参照してください。 -Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. -``` +バックグラウンドプロセスが長時間実行されていない場合もあります。 完了まで一度実行し、それらは終了します。 完了すると `FAILED` または `COMPLETED` のいずれかになります。 .. 列:: @@ -447,11 +443,7 @@ _v23.12_ に追加されました ### 再起動可能なカスタムプロセス -.. new:: v23.12 - -``` -トランジェントであるカスタムプロセスは**常に起動可能**になります。つまり、自動再起動は想定どおりに動作します。 ただし、プロセスを手動で再起動できますが、オートリローダーで再起動できない場合はどうなりますか? -``` +トランジェントであるカスタムプロセスは、**常に**再び起動可能になります。 つまり、自動再起動は想定どおりに動作します。 ただし、プロセスを手動で再起動できますが、オートリローダーで再起動できない場合はどうなりますか? .. 列:: @@ -495,11 +487,7 @@ _v23.12_ に追加されました ### オンザフライプロセス管理 -.. new:: v23.12 - -``` -カスタムプロセスは通常 `main_process_ready` リスナーに追加されます。 ただし、アプリケーションの開始後にプロセスを追加したい場合があります。 例えば、リクエストハンドラからプロセスを追加することができます。multiplexer はこれを行うためのメソッドを提供します。 -``` +カスタムプロセスは通常 `main_process_ready` リスナーに追加されます。 ただし、アプリケーションの開始後にプロセスを追加したい場合があります。 たとえば、リクエストハンドラからプロセスを追加したい場合があります。 マルチプレクサはこれを行う方法を提供します。 .. 列:: From e5b48af13ad5953d11563740bf8a1aa29a2e67ea Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:15:21 +0300 Subject: [PATCH 643/698] New translations changelog.md (Japanese) --- guide/content/ja/release-notes/changelog.md | 46 +++++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/guide/content/ja/release-notes/changelog.md b/guide/content/ja/release-notes/changelog.md index 9f45248076..ffc52a8b4e 100644 --- a/guide/content/ja/release-notes/changelog.md +++ b/guide/content/ja/release-notes/changelog.md @@ -7,12 +7,54 @@ content_class: 更新履歴 🔶 現在のリリース\ 🔷 LTS リリース -## バージョン23.12.0 🔶🔷 +## バージョン24.6.0 🔶 _現在のバージョン_ ### 特徴 +- [#2838](https://github.com/sanic-org/sanic/pull/2838) リクエストクッキー「getlist」を簡素化する +- [#2850](https://github.com/sanic-org/sanic/pull/2850) Unix ソケットは `pathlib.Path` を使用できるようになりました +- [#2931](https://github.com/sanic-org/sanic/pull/2931) [#2958](https://github.com/sanic-org/sanic/pull/2958) ログの改善点 +- [#2947](https://github.com/sanic-org/sanic/pull/2947) .message フィールドを空ではない例外にする +- [#2961](https://github.com/sanic-org/sanic/pull/2961) [#2964](https://github.com/sanic-org/sanic/pull/2964) カスタム名生成を許可する + +### バグ修正 + +- [#2919](https://github.com/sanic-org/sanic/pull/2919) websockets で非推奨の通知を削除する +- [#2937](https://github.com/sanic-org/sanic/pull/2937) ASGIモードで応答ストリーミングエラーを解決する +- [#2959](https://github.com/sanic-org/sanic/pull/2959) Python 3.12 deprecation notic を解決する +- [#2960](https://github.com/sanic-org/sanic/pull/2960) 騒々しい例外に対する適切な意図を確認する +- [#2970](https://github.com/sanic-org/sanic/pull/2970) [#2978](https://github.com/sanic-org/sanic/pull/2978) 3.12 の不足している依存関係を修正します。 +- [#2971](https://github.com/sanic-org/sanic/pull/2971) ミドルウェアの例外が見つからないルートでエラーが発生した問題を修正しました。 +- [#2973](https://github.com/sanic-org/sanic/pull/2973) `transport.close`と`transport.abort`のchedulingロジックを解決します。 +- [#2976](https://github.com/sanic-org/sanic/pull/2976) `secure=False`で作成されたクッキーの削除を修正 +- [#2979](https://github.com/sanic-org/sanic/pull/2979) 体長が悪い場合にエラーを投げます +- [#2980](https://github.com/sanic-org/sanic/pull/2980) ボディエンコーディングの不良時にエラーを投げる。 + +### 非推奨と削除 + +- [#2899](https://github.com/sanic-org/sanic/pull/2899) HTTPX が影響を受けない環境の REPL から誤った行を削除します +- [#2962](https://github.com/sanic-org/sanic/pull/2962) マージエンティティヘッダーの削除 + +### 開発者のインフラストラクチャ + +- [#2882](https://github.com/sanic-org/sanic/pull/2882) [#2896](https://github.com/sanic-org/sanic/pull/2896) ポート選択によるテストを改善するために動的なポートフィクスチャーを適用する +- [#2887](https://github.com/sanic-org/sanic/pull/2887) docker image builds の更新 +- [#2932](https://github.com/sanic-org/sanic/pull/2932) Ruff を使ってコードベースをクリーンアップする + +### ドキュメントの改善 + +- [#2924](https://github.com/sanic-org/sanic/pull/2924) html5tagger page +- [#2930](https://github.com/sanic-org/sanic/pull/2930) Sanic Extensions README.md +- [#2934](https://github.com/sanic-org/sanic/pull/2934) ヘルスチェック文書に文脈を追加する +- [#2936](https://github.com/sanic-org/sanic/pull/2936) ワーカーマネージャーのドキュメントを改善する +- [#2955](https://github.com/sanic-org/sanic/pull/2955) `request.md`のフォーマットが間違っているのを修正しました + +## バージョン23.12.0 🔷 + +### 特徴 + - [#2775](https://github.com/sanic-org/sanic/pull/2775) 任意のプロセスを開始して再起動する - [#2811](https://github.com/sanic-org/sanic/pull/2811) シャットダウン時のクリーナープロセス管理 - [#2812](https://github.com/sanic-org/sanic/pull/2812) オープンなウェブソケットでタスクのトレースバックを抑制する @@ -34,8 +76,6 @@ _現在のバージョン_ - [#2803](https://github.com/sanic-org/sanic/pull/2803) MOTD の追加データ表示を修正する -### 非推奨と削除 - ### 開発者のインフラストラクチャ - [#2796](https://github.com/sanic-org/sanic/pull/2796) ユニットテストケースをリファクタリングする From 60fa4b8dadd08f5922c8bed222b1648fe49c0a14 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:15:31 +0300 Subject: [PATCH 644/698] New translations listeners.md (Korean) --- guide/content/ko/guide/basics/listeners.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/guide/content/ko/guide/basics/listeners.md b/guide/content/ko/guide/basics/listeners.md index 33a20b379a..d30d8fb88e 100644 --- a/guide/content/ko/guide/basics/listeners.md +++ b/guide/content/ko/guide/basics/listeners.md @@ -256,11 +256,7 @@ The practical result of this is that if the first listener in `before_server_sta ### Priority -.. new:: v23.12 - -``` In v23.12, the `priority` keyword argument was added to listeners. This allows for fine-tuning the order of execution of listeners. The default priority is `0`. Listeners with a higher priority will be executed first. Listeners with the same priority will be executed in the order they were registered. Furthermore, listeners attached to the `app` instance will be executed before listeners attached to a `Blueprint` instance. -``` Overall the rules for deciding the order of execution are as follows: From 6728f7e2264dc3e68269bb3d386fa1507aae5e8a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:15:53 +0300 Subject: [PATCH 645/698] New translations development.md (Korean) --- guide/content/ko/guide/running/development.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/guide/content/ko/guide/running/development.md b/guide/content/ko/guide/running/development.md index 03f7c5b47d..2b1753fb99 100644 --- a/guide/content/ko/guide/running/development.md +++ b/guide/content/ko/guide/running/development.md @@ -76,11 +76,7 @@ sanic path.to:app -r -R /path/to/one -R /path/to/two ## Development REPL -.. new:: v23.12 - -``` The Sanic CLI comes with a REPL (aka "read-eval-print loop") that can be used to interact with your application. This is useful for debugging and testing. A REPL is the interactive shell that you get when you run `python` without any arguments. -``` .. column:: @@ -231,7 +227,7 @@ _Added in v23.12_ .. column:: ``` -If you would like to be in debug mode **and** have the Automatic Reloader running, you can pass `dev=True`. This is equivalent to **debug + auto reload**. +If you would like to be in debug mode **and** have the Automatic Reloader running, you can pass `dev=True`. This is equivalent to **debug + auto reload + REPL**. *Added in v22.3* ``` @@ -248,13 +244,10 @@ sanic path.to:app -d ``` ```` -.. new:: v23.12 - -``` Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Development REPL](./development.md#development-repl) section for more information. As of v23.12, the `--dev` flag is roughly equivalent to `--debug --reload --repl`. Using `--dev` will require you to expressly begin the REPL by hitting "ENTER", while passing the `--repl` flag explicitly starts it. -``` +Before v23.12, the `--dev` flag is more similar to `--debug --reload`. .. column:: From 97702af21411becee5f44db6e013daaf742ff585 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:15:55 +0300 Subject: [PATCH 646/698] New translations manager.md (Korean) --- guide/content/ko/guide/running/manager.md | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/guide/content/ko/guide/running/manager.md b/guide/content/ko/guide/running/manager.md index b71685420e..7114db3450 100644 --- a/guide/content/ko/guide/running/manager.md +++ b/guide/content/ko/guide/running/manager.md @@ -412,15 +412,11 @@ async def ready(app: Sanic, _): ### Tracked v. untracked processes -.. new:: v23.12 - -``` Out of the box, Sanic will track the state of all processes. This means that you can access the state of the process from the [multiplexer](./manager#access-to-the-multiplexer) object, or from the [Inspector](./manager#inspector). See [worker state](./manager#worker-state) for more information. Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. -``` .. column:: @@ -447,11 +443,7 @@ _Added in v23.12_ ### Restartable custom processes -.. new:: v23.12 - -``` -A custom process that is transient will **always** be restartable. That means the auto-restart will work as expected. However, what if you want to be able to *manually* restart a process, but not have it be restarted by the auto-reloader? -``` +A custom process that is transient will **always** be restartable. That means the auto-restart will work as expected. However, what if you want to be able to _manually_ restart a process, but not have it be restarted by the auto-reloader? .. column:: @@ -495,11 +487,7 @@ _Added in v23.12_ ### On the fly process management -.. new:: v23.12 - -``` Custom processes are usually added in the `main_process_ready` listener. However, there may be times when you want to add a process after the application has started. For example, you may want to add a process from a request handler. The multiplexer provides a method for doing this. -``` .. column:: From c034d0f4cf7f423c562d6aea3fd59f6640c47c44 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:16:28 +0300 Subject: [PATCH 647/698] New translations changelog.md (Korean) --- guide/content/ko/release-notes/changelog.md | 46 +++++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/guide/content/ko/release-notes/changelog.md b/guide/content/ko/release-notes/changelog.md index f6754f0457..1451f54dd1 100644 --- a/guide/content/ko/release-notes/changelog.md +++ b/guide/content/ko/release-notes/changelog.md @@ -7,12 +7,54 @@ content_class: changelog 🔶 Current release\ 🔷 In support LTS release -## Version 23.12.0 🔶🔷 +## Version 24.6.0 🔶 _Current version_ ### Features +- [#2838](https://github.com/sanic-org/sanic/pull/2838) Simplify request cookies `getlist` +- [#2850](https://github.com/sanic-org/sanic/pull/2850) Unix sockets can now use `pathlib.Path` +- [#2931](https://github.com/sanic-org/sanic/pull/2931) [#2958](https://github.com/sanic-org/sanic/pull/2958) Logging improvements +- [#2947](https://github.com/sanic-org/sanic/pull/2947) Make the .message field on exceptions non-empty +- [#2961](https://github.com/sanic-org/sanic/pull/2961) [#2964](https://github.com/sanic-org/sanic/pull/2964) Allow for custom name generation + +### Bugfixes + +- [#2919](https://github.com/sanic-org/sanic/pull/2919) Remove deprecation notice in websockets +- [#2937](https://github.com/sanic-org/sanic/pull/2937) Resolve response streaming error when in ASGI mode +- [#2959](https://github.com/sanic-org/sanic/pull/2959) Resolve Python 3.12 deprecation notic +- [#2960](https://github.com/sanic-org/sanic/pull/2960) Ensure proper intent for noisy exceptions +- [#2970](https://github.com/sanic-org/sanic/pull/2970) [#2978](https://github.com/sanic-org/sanic/pull/2978) Fix missing dependencies for 3.12 +- [#2971](https://github.com/sanic-org/sanic/pull/2971) Fix middleware exceptions on Not Found routes with error in middleware +- [#2973](https://github.com/sanic-org/sanic/pull/2973) Resolve cheduling logic for `transport.close` and `transport.abort` +- [#2976](https://github.com/sanic-org/sanic/pull/2976) Fix deleting a cookie that was created with `secure=False` +- [#2979](https://github.com/sanic-org/sanic/pull/2979) Throw error on bad body length +- [#2980](https://github.com/sanic-org/sanic/pull/2980) Throw error on bad body encoding + +### Deprecations and Removals + +- [#2899](https://github.com/sanic-org/sanic/pull/2899) Remove erroneous line from REPL impacting environments without HTTPX +- [#2962](https://github.com/sanic-org/sanic/pull/2962) Merge entity header removal + +### Developer infrastructure + +- [#2882](https://github.com/sanic-org/sanic/pull/2882) [#2896](https://github.com/sanic-org/sanic/pull/2896) Apply dynamic port fixture for improving tests with port selection +- [#2887](https://github.com/sanic-org/sanic/pull/2887) Updates to docker image builds +- [#2932](https://github.com/sanic-org/sanic/pull/2932) Cleanup code base with Ruff + +### Improved Documentation + +- [#2924](https://github.com/sanic-org/sanic/pull/2924) Cleanup markdown on html5tagger page +- [#2930](https://github.com/sanic-org/sanic/pull/2930) Cleanup typo on Sanic Extensions README.md +- [#2934](https://github.com/sanic-org/sanic/pull/2934) Add more context to the health check documents +- [#2936](https://github.com/sanic-org/sanic/pull/2936) Improve worker manager documentation +- [#2955](https://github.com/sanic-org/sanic/pull/2955) Fixed wrong formatting in `request.md` + +## Version 23.12.0 🔷 + +### Features + - [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes - [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown - [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket @@ -34,8 +76,6 @@ _Current version_ - [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data -### Deprecations and Removals - ### Developer infrastructure - [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases From 2c833cb4b9b99c1e816d0d03e6aac0665d11e40f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:16:37 +0300 Subject: [PATCH 648/698] New translations listeners.md (Chinese Simplified) --- guide/content/zh/guide/basics/listeners.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/guide/content/zh/guide/basics/listeners.md b/guide/content/zh/guide/basics/listeners.md index cf1fe3e180..9f9655eec9 100644 --- a/guide/content/zh/guide/basics/listeners.md +++ b/guide/content/zh/guide/basics/listeners.md @@ -256,11 +256,7 @@ async def listener_8(app, loop): ### 优先级（Priority） -.. new:: v23.12 - -``` -自 v23.12 版本起，向监听器添加了 `priority` 关键字参数。这允许精细调整监听器执行顺序。默认优先级为 `0`。优先级较高的监听器将首先执行。相同优先级的监听器将按照注册的顺序执行。此外，附加到 `app` 实例的监听器将优先于附加到 `Blueprint` 实例的监听器执行。 -``` +在v23.12中，将`priority`关键词参数添加到听众中。 这使得可以微调听器的执行顺序。 默认优先级是 `0'。 优先级较高的监听器将先执行。 具有相同优先级的侦听器将按照他们注册的顺序执行。 此外，连接到 `app`实例的侦听器将在连接到`Blueprint\` 实例的侦听器之前执行。 决定执行顺序的整体规则如下： @@ -268,7 +264,7 @@ async def listener_8(app, loop): 2. 应用程序级别的监听器优先于蓝图级别的监听器执行 3. 按照注册顺序执行 -.. column:: +.. 列: ```` 作为示例，考虑以下内容，它将打印： From 86eac4c6c43728e6507b92463fbac86c3945ec85 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:16:59 +0300 Subject: [PATCH 649/698] New translations development.md (Chinese Simplified) --- guide/content/zh/guide/running/development.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/guide/content/zh/guide/running/development.md b/guide/content/zh/guide/running/development.md index 97b76e3b3c..63896a08bd 100644 --- a/guide/content/zh/guide/running/development.md +++ b/guide/content/zh/guide/running/development.md @@ -76,11 +76,7 @@ sanic path.to:app -r -R /path/to/one -R /path/to/two ## Development REPL -.. 新：v23.12 - -``` -Sanic CLI 带有一个 REPL (又名“读-写循环”)，可用来与您的应用程序进行交互。 这对调试和测试非常有用。REPL是你在没有任何参数的情况下运行python时得到的交互式外壳。 -``` +Sanic CLI 带有一个 REPL (又名“读-写循环”)，可用来与您的应用程序进行交互。 这对调试和测试非常有用。 一个 REPL 是当你在没有任何参数的情况下运行 `python` 时得到的交互式外壳。 .. 列: @@ -231,7 +227,7 @@ _添加于 v23.12_ .. 列: ``` -如果你想要处于调试模式**和** 运行自动重新加载器，你可以通过 `dev=True`。 这相当于**调试+自动重新加载**。 +如果你想要处于调试模式**和** 运行自动重新加载器，你可以通过 `dev=True`。 这相当于**调试+自动重新加载+重新加载**。 *添加于v22.3* ``` @@ -248,13 +244,10 @@ sanic path.to:app -d ``` ```` -.. 新：v23.12 +在 v23.12 `--dev` 旗帜上添加了能够启动一个REPL 详见[Development REPL](./development.md#development-reply)部分。 -``` -Added to the `--dev` flag in v23.12 is the ability to start a REPL. See the [Development REPL](./development.md#development-repl) section for more information. - -As of v23.12, the `--dev` flag is roughly equivalent to `--debug --reload --repl`. Using `--dev` will require you to expressly begin the REPL by hitting "ENTER", while passing the `--repl` flag explicitly starts it. -``` +到 v23.12，`--dev` 旗帜大致等于`--debug --reload --reload --repli`。 使用 "--dev" 将需要你明确开头点击 "ENTER"，然后通过 "--repli" 旗帜明确开头。 +在 v23.12之前，"--dev" 旗帜更类似于“--debug --reload\`”。 .. 列: From 5b87624e29f20744ab9eed3b79d5b03dee6c650a Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:17:00 +0300 Subject: [PATCH 650/698] New translations manager.md (Chinese Simplified) --- guide/content/zh/guide/running/manager.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/guide/content/zh/guide/running/manager.md b/guide/content/zh/guide/running/manager.md index 5894f52a8c..ffe0e1bad9 100644 --- a/guide/content/zh/guide/running/manager.md +++ b/guide/content/zh/guide/running/manager.md @@ -412,15 +412,11 @@ async def ready(app: Sanic, _): ### 跟踪或未跟踪的进程 -.. 新：v23.12 +Sanic 将从盒子中追踪所有进程的状态。 这意味着您可以从 [multiplexer](./manager#access-to-the-multiplexer)对象或从 [Inspector](./manager#inspector)访问过程状态。 -``` -Out of the box, Sanic will track the state of all processes. This means that you can access the state of the process from the [multiplexer](./manager#access-to-the-multiplexer) object, or from the [Inspector](./manager#inspector). - -See [worker state](./manager#worker-state) for more information. +详见[工人状态](./manager#worker-state)。 -Sometimes it is helpful to run background processes that are not long-running. You run them once until completion and then they exit. Upon completion, they will either be in `FAILED` or `COMPLETED` state. -``` +有时运行并非长期运行的背景进程是有益的。 你运行一次，直到完成，然后他们退出。 完成后，它们将处于`FAILED`或`COMPLETED`状态。 .. 列: @@ -447,11 +443,7 @@ _添加于 v23.12_ ### 可重新启动自定义进程 -.. 新：v23.12 - -``` -临时性的自定义进程将**总是可以重启。这意味着自动重启将会如预期的那样正常工作。 然而，如果你想要能够*手动*重新启动一个过程，但它不会被自动重新加载器重新启动？ -``` +临时性的自定义进程将\*\*总是可以重启。 这意味着自动重启将按预期进行。 然而，如果你想要能够_手动_重新启动一个过程，但它不会被自动重新加载器重新启动？ .. 列: @@ -495,11 +487,7 @@ _添加于 v23.12_ ### 飞行过程管理 -.. 新：v23.12 - -``` -自定义进程通常在 `main_process_ready` 监听器中添加。 然而，有时候您想要在应用程序启动后添加一个过程。 例如，您可能想要从请求处理器中添加一个进程。多路程序提供了这样做的方法。 -``` +自定义进程通常在 `main_process_ready` 监听器中添加。 然而，有时候您想要在应用程序启动后添加一个过程。 例如，您可能想要从请求处理器中添加一个过程。 多路程序提供了这样做的方法。 .. 列: From b5eafca17379ad5e75a3e71f9c3a2d5346275f9e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 15:17:33 +0300 Subject: [PATCH 651/698] New translations changelog.md (Chinese Simplified) --- guide/content/zh/release-notes/changelog.md | 66 +++++++++++++++++---- 1 file changed, 53 insertions(+), 13 deletions(-) diff --git a/guide/content/zh/release-notes/changelog.md b/guide/content/zh/release-notes/changelog.md index d98113271d..151c7dc73e 100644 --- a/guide/content/zh/release-notes/changelog.md +++ b/guide/content/zh/release-notes/changelog.md @@ -7,12 +7,54 @@ content_class: 更新日志 :larg_orange_diamond: Current release :larg_blu_diamond: In support LTS release -## Version 23.12.0 🔶🔷 +## 版本24.6.0 :larg_orange_diamond: _当前版本_ ### Features +- [#2838](https://github.com/sanic-org/sanic/pull/2838) 简化请求 cookie `getlist` +- [#2850](https://github.com/sanic-org/sanic/pull/2850) Unix sockets 现在可以使用 `pathlib.Path` +- [#2931](https://github.com/sanic-org/sanic/pull/2931)[#2958](https://github.com/sanic-org/sanic/pull/2958) 日志改进 +- [#2947](https://github.com/sanic-org/sanic/pull/2947) 使异常的 .message 字段非空 +- [#2961](https://github.com/sanic-org/sanic/pull/2961) [#2964](https://github.com/sanic-org/pull/2964) 允许自定义名称生成 + +### Bugfixes + +- [#2919](https://github.com/sanic-org/sanic/pull/2919) 移除websockets中的废弃通知 +- [#2937](https://github.com/sanic-org/sanic/pull/2937) 在ASGI 模式中解决流媒体响应错误 +- [#2959](https://github.com/sanic-org/sanic/pull/2959) 解析Python 3.12废弃噪音 +- [#2960](https://github.com/sanic-org/sanic/pull/2960) +- [#2970](https://github.com/sanic-org/sanic/pull/2970)[#2978](https://github.com/sanic-org/sanic/pull/2978) 修复缺少的3.12依赖关系。 +- [#2971](https://github.com/sanic-org/sanic/pull/2971) 修复在未发现的路径上的中间件异常，中间件中出现错误 +- [#2973](https://github.com/sanic-org/sanic/pull/2973) 解析`transport.close`和`transport.abort` +- [#2976](https://github.com/sanic-org/sanic/pull/2976) 修复删除由 `secure=False` 创建的 cookie +- [#2979](https://github.com/sanic-org/sanic/pull/2979) 抛出错误的身体长度 +- [#2980](https://github.com/sanic-org/sanic/pull/2980) 丢弃错误的物体编码错误 + +### Deprecations and Removals + +- [#2899](https://github.com/sanic-org/sanic/pull/2899) 从REPL中删除错误的行，从而影响没有HTTPX的环境 +- [#2962](https://github.com/sanic-org/sanic/pull/2962) 合并实体头部删除 + +### 开发者基础设施 + +- [#2882](https://github.com/sanic-org/sanic/pull/2882) [#2896](https://github.com/sanic-org/sanic/pull/2896) 应用动态端口固定来改进端口选择测试 +- [#2887](https://github.com/sanic-org/sanic/pull/2887) 更新到码头图像版本 +- [#2932](https://github.com/sanic-org/sanic/pull/2932) 用Ruff 清理代码库 + +### Improved Documentation + +- [#2924](https://github.com/sanic-org/sanic/pull/2924) cleanup markdown on html5tagger page +- [#2930](https://github.com/sanic-org/sanic/pull/2930) Sanic Extension README.md +- [#2934](https://github.com/sanic-org/sanic/pull/2934) +- [#2936](https://github.com/sanic-org/sanic/pull/2936) +- [#2955](https://github.com/sanic-org/sanic/pull/2955) 修复了`request.md`中错误的格式化。 + +## 版本23.12.0 :larg_blu_diamond: + +### Features + - [#2775](https://github.com/sanic-org/sanic/pull/2775) Start and restart arbitrary processes - [#2811](https://github.com/sanic-org/sanic/pull/2811) Cleaner process management in shutdown - [#2812](https://github.com/sanic-org/sanic/pull/2812) Suppress task cancel traceback on open websocket @@ -34,9 +76,7 @@ _当前版本_ - [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data -### Deprecations and Removals - -### Developer infrastructure +### 开发者基础设施 - [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases - [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU @@ -98,7 +138,7 @@ _Due to circumstances at the time, v.23.9 was skipped._ - [#2777](https://github.com/sanic-org/sanic/pull/2777) Remove Python 3.7 support -### 开发者基础设施 +### Developer infrastructure - [#2766](https://github.com/sanic-org/sanic/pull/2766) Unpin setuptools version - [#2779](https://github.com/sanic-org/sanic/pull/2779) Run keep alive tests in loop to get available port @@ -224,7 +264,7 @@ _当前LTS版本_ - [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered -### Bugfixes +### 错误修正 - [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation - [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility @@ -267,7 +307,7 @@ _当前LTS版本_ - [#2546](https://github.com/sanic-org/sanic/pull/2546) Add deprecation warning filter - [#2550](https://github.com/sanic-org/sanic/pull/2550) Middleware priority and performance enhancements -### 错误修正 +### Bugfixes - [#2495](https://github.com/sanic-org/sanic/pull/2495) Prevent directory traversion with static files - [#2515](https://github.com/sanic-org/sanic/pull/2515) Do not apply double slash to paths in certain static dirs in Blueprints @@ -296,7 +336,7 @@ _当前LTS版本_ ## Version 22.6.1 -### Bugfixes +### 错误修正 - [#2477](https://github.com/sanic-org/sanic/pull/2477) Sanic static directory fails when folder name ends with ".." @@ -369,7 +409,7 @@ _当前LTS版本_ - [sanic-routing#58](https://github.com/sanic-org/sanic-routing/pull/58) Default matching on non-empty strings only, and new `strorempty` pattern type - 🚨 _BREAKING CHANGE_: Previously a route with a dynamic string parameter (`/` or `/`) would match on any string, including empty strings. It will now **only** match a non-empty string. To retain the old behavior, you should use the new parameter type: `/`. -### 错误修正 +### Bugfixes - [#2373](https://github.com/sanic-org/sanic/pull/2373) Remove `error_logger` on websockets - [#2381](https://github.com/sanic-org/sanic/pull/2381) Fix newly assigned `None` in task registry @@ -466,7 +506,7 @@ _当前LTS版本_ - [#2336](https://github.com/sanic-org/sanic/pull/2336) Remove paths from coverage checks - [#2338](https://github.com/sanic-org/sanic/pull/2338) Cleanup ports on tests -### Improved Documentation +### 改进文档 - [#2269](https://github.com/sanic-org/sanic/pull/2269), [#2329](https://github.com/sanic-org/sanic/pull/2329), [#2333](https://github.com/sanic-org/sanic/pull/2333) Cleanup typos and fix language @@ -491,7 +531,7 @@ _Rerelease of v21.9.2 with some cleanup_ ## Version 21.9.0 -### Features +### 功能 - [#2158](https://github.com/sanic-org/sanic/pull/2158), [#2248](https://github.com/sanic-org/sanic/pull/2248) Complete overhaul of I/O to websockets - [#2160](https://github.com/sanic-org/sanic/pull/2160) Add new 17 signals into server and request lifecycles @@ -507,7 +547,7 @@ _Rerelease of v21.9.2 with some cleanup_ - [#2244](https://github.com/sanic-org/sanic/pull/2244) Explicit static directive for serving file or dir (ex: `static(..., resource_type="file")`) - [#2245](https://github.com/sanic-org/sanic/pull/2245) Close HTTP loop when connection task cancelled -### Bugfixes +### 错误修正 - [#2188](https://github.com/sanic-org/sanic/pull/2188) Fix the handling of the end of a chunked request - [#2195](https://github.com/sanic-org/sanic/pull/2195) Resolve unexpected error handling on static requests @@ -518,7 +558,7 @@ _Rerelease of v21.9.2 with some cleanup_ - [#2247](https://github.com/sanic-org/sanic/pull/2247) Fix logging of auto-reload status in debug mode - [#2246](https://github.com/sanic-org/sanic/pull/2246) Account for BP with exception handler but no routes -### Developer infrastructure +### 开发者基础设施 - [#2194](https://github.com/sanic-org/sanic/pull/2194) HTTP unit tests with raw client - [#2199](https://github.com/sanic-org/sanic/pull/2199) Switch to codeclimate From d33fcffa5bc32ade18b008bd53eb66a25d91cccd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 16:11:32 +0300 Subject: [PATCH 652/698] New translations logger.md (Japanese) --- guide/content/ja/plugins/sanic-ext/logger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/plugins/sanic-ext/logger.md b/guide/content/ja/plugins/sanic-ext/logger.md index 4294fd6f38..c8fa9d7308 100644 --- a/guide/content/ja/plugins/sanic-ext/logger.md +++ b/guide/content/ja/plugins/sanic-ext/logger.md @@ -28,7 +28,7 @@ app.config.LOGGING = True ## どのように機能します -有効にすると、拡張機能は `multoprocessing.Queue` を作成します。 format@@0(../../guide/best-practices/logging.md) 上のすべてのハンドラを削除し、[`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler) に置き換えます。 メッセージがログされると、ハンドラによってキューにプッシュされます。 バックグラウンドプロセスで元々あったログハンドラを読み取ることができます つまり、通常どおりにロギングを設定することができ、「ただ動作する」ことができます。 +有効にすると、拡張機能は `multiprocessing.Queue` を作成します。 format@@0(../../guide/best-practices/logging.md) 上のすべてのハンドラを削除し、[`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler) に置き換えます。 メッセージがログされると、ハンドラによってキューにプッシュされます。 バックグラウンドプロセスで元々あったログハンドラを読み取ることができます つまり、通常どおりにロギングを設定することができ、「ただ動作する」ことができます。 ## 設定 From 98f91deda08b9632d2ce9a8362570e413f1550e7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 16:12:02 +0300 Subject: [PATCH 653/698] New translations logger.md (Korean) --- guide/content/ko/plugins/sanic-ext/logger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/plugins/sanic-ext/logger.md b/guide/content/ko/plugins/sanic-ext/logger.md index cd3ae04b7b..76e61e7f0a 100644 --- a/guide/content/ko/plugins/sanic-ext/logger.md +++ b/guide/content/ko/plugins/sanic-ext/logger.md @@ -28,7 +28,7 @@ app.config.LOGGING = True ## How does it work -When enabled, the extension will create a `multoprocessing.Queue`. It will remove all handlers on the [default Sanic loggers](../../guide/best-practices/logging.md) and replace them with a [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler). When a message is logged, it will be pushed into the queue by the handler, and read by the background process to the log handlers that were originally in place. This means you can still configure logging as normal and it should "just work." +When enabled, the extension will create a `multiprocessing.Queue`. It will remove all handlers on the [default Sanic loggers](../../guide/best-practices/logging.md) and replace them with a [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler). When a message is logged, it will be pushed into the queue by the handler, and read by the background process to the log handlers that were originally in place. This means you can still configure logging as normal and it should "just work." ## Configuration From abea51c4ce8d428b7ad39aedb65851057c1d2b2d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 16:12:33 +0300 Subject: [PATCH 654/698] New translations v24.6.md (Japanese) --- guide/content/ja/release-notes/2024/v24.6.md | 135 +++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 guide/content/ja/release-notes/2024/v24.6.md diff --git a/guide/content/ja/release-notes/2024/v24.6.md b/guide/content/ja/release-notes/2024/v24.6.md new file mode 100644 index 0000000000..9a2a91027e --- /dev/null +++ b/guide/content/ja/release-notes/2024/v24.6.md @@ -0,0 +1,135 @@ +--- +title: バージョン 24.6 +--- + +# バージョン 24.6 + +.. TOC:: + +## はじめに + +これはバージョン24format@@0(../../organization/policyes.md#release-schedule)の最初のリリースです。 v24のリリースケイデンスは、数年前から若干変更されている可能性があります。 最新のアップデートについては、Discordサーバーの最新情報を確認してください。 何か問題が発生した場合は、 [GitHub](https://github.com/sanic-org/sanic/issues/new/choose) にご注意ください。 + +## 知っておくべきこと + +[Changelog](../changelog.html) の詳細。 注目すべき新機能や破損した機能、アップグレードする機能: + +### ログの改善 + +既定のログパターンは、ターミナルセッションからの閲覧時により開発者にやさしいものにするためにクリーンアップされています。 これには色の使用とあまり冗長な書式設定が含まれます。 + +SanicはサーバがDEBUGモードかどうかに応じて2つのわずかなバリエーションを選択します。 使用することで、常に色を削除することを選択できます。 + +```python +app.config.NO_COLOR = True +``` + +TTY端末ではなくログから色が自動的に取り除かれます。 + +Sanicは`sanic.logging.formatter.AutoFormatter` と `sanic.logging.formatter.AutoAccessFormatter` を使用して、DEBUGとPRODフォーマッタを自動的に切り替えます。 もちろん、適切な名前のフォーマッタを使用して、1つのバージョンまたは他のバージョンを強制することができます + +#### DEBUGモード中 + +```python +sanic.logging.formatter.DebugFormatter +sanic.logging.formatter.DebugAccessFormatter +``` + +![](/assets/images/logging-dev.png) + +#### PRODモード + +```python +sanic.logging.formatter.ProdFormatter +sanic.logging.formatter.ProdAccessFormatter +``` + +![](/assets/images/logging-prod.png) + +#### Legacy + +古い形式のログを好む場合は、ログフォーマッタとして保存されています: `sanic.logging.formatter.LegacyFormatter.LegacyAccessFormatter.LegacyAccessFormatter` 。 + +これらのフォーマッタを実装する一つの方法: + +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_CONFIG_DEFAULTS["formatters"] = { + "generic": { + "class": "sanic.logging.formatter.LegacyFormatter" + }, + "access": { + "class": "sanic.logging.formatter.LegacyAccessFormatter" + }, +} +``` + +#### 新しいJSONフォーマット + +また、他の第三部ロギングプラットフォームとの統合のために、ログを JSON 形式で出力する新しい JSON ログフォーマッタもあります。 + +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_CONFIG_DEFAULTS["formatters"] = { + "generic": { + "class": "sanic.logging.formatter.JSONFormatter" + }, + "access": { + "class": "sanic.logging.formatter.JSONAccessFormatter" + }, +} +``` + +### Unix ソケットでパスを使用する + +サーバに Unix ソケットを作成するときに、文字列ベースのパスの代わりに `pathlib.Path` オブジェクトを渡すことでそれを実行できるようになりました。 + +### カスタムルート名 + +`generate_name`メソッドは、カスタムの`Sanic`または`Blueprint`のいずれかで上書きできます。 これにより、任意にルート名を変更することができます。 + +```python +from sanic import Sanic, text, + +class Custom(Sanic): + def generate_name(self, *objects): + existing = self._generate_name(*objects) + return existing.upper() + +app = Sanic("Foo") + +@app.get("/") +async def handler(request): + return text(request.name) # FOO.HANDLER + + +return app +``` + +### 🚨 BREAKING 変更点 + +1. `Request.cookies.getlist` は常に`list`を返します。 これは、 `key` の cookie が存在しない場合、 `None` の代わりに `list` になります。 既存の動作を保持するには、`Request.cookies.getlist("something", None)`を使用してください。 + +## ありがとうございます + +このリリースに参加いただき、ありがとうございます： :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@DeJayDev](https://github.com/DeJayDev) +[@ekzhang](https://github.com/ekzhang) +[@Huy-Ngo](https://github.com/Huy-Ngo) +[@iAndriy](https://github.com/iAndriy) +[@jakkaz](https://github.com/jakkaz) +[@Nano112](https://github.com/Nano112) +[@prryplatypus](https://github.com/prryplatypus) +[@razodactyl](https://github.com/razodactyl) +[@Tronic](https://github.com/Tronic) +[@wieczorek1990](https://github.com/wieczorek1990) + +--- + +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From 7903815066479012ed2c89dce447162ca9822a16 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 16:12:34 +0300 Subject: [PATCH 655/698] New translations logger.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/logger.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/plugins/sanic-ext/logger.md b/guide/content/zh/plugins/sanic-ext/logger.md index 55bd921d4f..4d59adc1d7 100644 --- a/guide/content/zh/plugins/sanic-ext/logger.md +++ b/guide/content/zh/plugins/sanic-ext/logger.md @@ -28,7 +28,7 @@ app.config.LOGING = True ## 如何工作 -启用时，扩展将创建 `multoprocessing.Queue` 。 它将移除[默认 Sanic loggers](../../guide/best practices/logging.md) 上的所有处理程序，并将其替换为 [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler)。 当消息被记录时，它将被处理器推送到队列。 并通过后台进程读取原有的日志处理程序。 这意味着您仍然可以将日志配置为正常，它应该“只能工作”。 +如果启用，扩展将创建 `multiprocessing.Queue` 。 它将移除[默认 Sanic loggers](../../guide/best practices/logging.md) 上的所有处理程序，并将其替换为 [`QueueHandler`](https://docs.python.org/3/library/logging.handlers.html#queuehandler)。 当消息被记录时，它将被处理器推送到队列。 并通过后台进程读取原有的日志处理程序。 这意味着您仍然可以将日志配置为正常，它应该“只能工作”。 ## 配置 From d3032fa417be63de32c2245acb2d45b89b27a8eb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 16:12:44 +0300 Subject: [PATCH 656/698] New translations v24.6.md (Korean) --- guide/content/ko/release-notes/2024/v24.6.md | 135 +++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 guide/content/ko/release-notes/2024/v24.6.md diff --git a/guide/content/ko/release-notes/2024/v24.6.md b/guide/content/ko/release-notes/2024/v24.6.md new file mode 100644 index 0000000000..5d3adebd60 --- /dev/null +++ b/guide/content/ko/release-notes/2024/v24.6.md @@ -0,0 +1,135 @@ +--- +title: Version 24.6 +--- + +# Version 24.6 + +.. toc:: + +## Introduction + +This is the first release of the version 24 [release cycle](../../organization/policies.md#release-schedule). The release cadence for v24 may be slightly altered from years past. Make sure to stay up to date in the Discord server for latest updates. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](../changelog.html). Notable new or breaking features, and what to upgrade: + +### Logging improvements + +The default logging patterns have been cleaned up to make them much more developer-friendly when viewing from a terminal session. This includes the use of color and less verbose formatting. + +Sanic will select between two slight variations depending upon whether your server is in DEBUG mode. You can always opt to remove colors by using: + +```python +app.config.NO_COLOR = True +``` + +The color will automatically be stripped out from logs not in TTY terminal. + +Sanic will switch between the DEBUG and PROD formatters automatically using `sanic.logging.formatter.AutoFormatter` and `sanic.logging.formatter.AutoAccessFormatter`. Of course, you can force one version or the other using the appropriately named formatters + +#### In DEBUG mode + +```python +sanic.logging.formatter.DebugFormatter +sanic.logging.formatter.DebugAccessFormatter +``` + +![](/assets/images/logging-dev.png) + +#### In PROD mode + +```python +sanic.logging.formatter.ProdFormatter +sanic.logging.formatter.ProdAccessFormatter +``` + +![](/assets/images/logging-prod.png) + +#### Legacy + +If you prefer the old-style of logging, these have been preserved for you as logging formatters: `sanic.logging.formatter.LegacyFormatter` and `sanic.logging.formatter.LegacyAccessFormatter`. + +One way to implement these formatters: + +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_CONFIG_DEFAULTS["formatters"] = { + "generic": { + "class": "sanic.logging.formatter.LegacyFormatter" + }, + "access": { + "class": "sanic.logging.formatter.LegacyAccessFormatter" + }, +} +``` + +#### New JSON formatter + +There also is a new JSON log formatter that will output the logs in JSON format for integration with other third part logging platforms. + +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_CONFIG_DEFAULTS["formatters"] = { + "generic": { + "class": "sanic.logging.formatter.JSONFormatter" + }, + "access": { + "class": "sanic.logging.formatter.JSONAccessFormatter" + }, +} +``` + +### Using Paths in unix sockets + +When creating a unix socket for your server, you can now perform that by passing a `pathlib.Path` object instead of just a string-based path + +### Custom route names + +You can override the `generate_name` method on either a custom `Sanic` or a `Blueprint`. This will allow you to modify the route names at will. + +```python +from sanic import Sanic, text, + +class Custom(Sanic): + def generate_name(self, *objects): + existing = self._generate_name(*objects) + return existing.upper() + +app = Sanic("Foo") + +@app.get("/") +async def handler(request): + return text(request.name) # FOO.HANDLER + + +return app +``` + +### 🚨 BREAKING CHANGES + +1. `Request.cookies.getlist` always returns a `list`. This means when no cookie of `key` exists, it will be an empty `list` instead of `None`. Use `Request.cookies.getlist("something", None)` to retain existing behavior. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@DeJayDev](https://github.com/DeJayDev) +[@ekzhang](https://github.com/ekzhang) +[@Huy-Ngo](https://github.com/Huy-Ngo) +[@iAndriy](https://github.com/iAndriy) +[@jakkaz](https://github.com/jakkaz) +[@Nano112](https://github.com/Nano112) +[@prryplatypus](https://github.com/prryplatypus) +[@razodactyl](https://github.com/razodactyl) +[@Tronic](https://github.com/Tronic) +[@wieczorek1990](https://github.com/wieczorek1990) + +--- + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From e7f7aaa66592c49d2eaa2cedb6e59f9b3ad285d4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 30 Jun 2024 16:12:45 +0300 Subject: [PATCH 657/698] New translations v24.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2024/v24.6.md | 135 +++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 guide/content/zh/release-notes/2024/v24.6.md diff --git a/guide/content/zh/release-notes/2024/v24.6.md b/guide/content/zh/release-notes/2024/v24.6.md new file mode 100644 index 0000000000..bdb729a27c --- /dev/null +++ b/guide/content/zh/release-notes/2024/v24.6.md @@ -0,0 +1,135 @@ +--- +title: 版本24.6 +--- + +# 版本24.6 + +.. toc:: + +## 一. 导言 + +这是版本 24 [发行周期] (../../organization/policies.md#release-schedule) 的第一次版本。 与过去几年相比，释放24人的队伍可能略有改变。 请确保在Discord服务器上更新最新信息。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出一个问题。 + +## 了解什么 + +更多详细信息在 [Changelog](../changelog.html)。 显著的新功能或破损功能以及升级内容： + +### 日志改进 + +默认日志模式已被清理，以使它们在从终端会话中查看时更方便开发者。 这包括使用颜色和较少详细的格式化。 + +Sanic 将根据您的服务器是否处于DEBUG模式选择两种轻微的变量。 您总是可以选择通过使用以下方式删除颜色： + +```python +app.config.NO_COLOR = True +``` + +颜色将自动从TTY 终端中删除日志。 + +Sanic 将使用 `sanic.logging.formatter.AutoFormatter` 和 `sanic.logging.formatter.AutoAccessFormatter` 自动切换DEBUG 和 PROD 格式格式。 当然，您可以使用适当命名的格式强制一个或另一个版本 + +#### 在 DEBUG 模式 + +```python +sanic.logging.formatter.DebugFormatter +sanic.logging.formatter.DebugAccessFormatter +``` + +![](/assets/images/logging-dev.png) + +#### 在PROD模式 + +```python +sanic.logging.formatter.ProdFormatter +sanic.logging.formatter.ProdAccessFormatter +``` + +![](/assets/images/logging-prod.png) + +#### 遗留问题 + +如果你喜欢旧式的伐木，它们将作为日志格式保存给你：`sanic.logging.formter.LegacyFormatter`和`sanic.logging.formter.LegacessFormatter`。 + +实现这些格式化的一种方式： + +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_CONFIG_DEFAULTS["formatters"] = { + "generic": { + "class": "sanic.logging.formatter.LegacyFormatter" + }, + "access": { + "class": "sanic.logging.formatter.LegacyAccessFormatter" + }, +} +``` + +#### 新 JSON 格式化器 + +还有一个新的 JSON 日志格式化器，它将以JSON 格式输出日志以便与其他第三部分日志平台合并。 + +```python +from sanic.log import LOGGING_CONFIG_DEFAULTS + +LOGGING_CONFIG_DEFAULTS["formatters"] = { + "generic": { + "class": "sanic.logging.formatter.JSONFormatter" + }, + "access": { + "class": "sanic.logging.formatter.JSONAccessFormatter" + }, +} +``` + +### 在 unix 套接字中使用路径 + +当为您的服务器创建一个unix 套接字时，您现在可以通过通过 `pathlib.Path` 对象而不是一个基于字符串的路径来执行它。 + +### 自定义路由名称 + +您可以在自定义 `Sanic` 或 `Blueprint` 上覆盖`generate_name` 方法。 这将允许您随意修改路由名称。 + +```python +from sanic import Sanic, text, + +class Custom(Sanic): + def generate_name(self, *objects): + existing = self._generate_name(*objects) + return existing.upper() + +app = Sanic("Foo") + +@app.get("/") +async def handler(request): + return text(request.name) # FOO.HANDLER + + +return app +``` + +### 🚨 Breaking 更改 + +1. `Request.cookies.getlist` 总是返回 `list` 。 这意味着，如果没有 `key` 的 cookie 时，它将是空的 `list` 而不是 `None'。 使用 `Request.cookies.getlist("something", None)\` 来保留现有的行为。 + +## 谢谢你 + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@ashleysommer](https://github.com/ashleysommer) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@DeJayDev](https://github.com/DeJayDev) +[@ekzhang](https://github.com/ekzhang) +[@Huy-Ngo](https://github.com/Huy-Ngo) +[@iAndriy](https://github.com/iAndriy) +[@jakkaz](https://github.com/jakkaz) +[@Nano112](https://github.com/Nano112) +[@prryplatypus](https://github.com/prryplatypus) +[@razodactyl](https://github.com/razodactyl) +[@Tronic](https://github.com/Tronic) +[@wieczorek1990](https://github.com/wieczorek1990) + +--- + +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From c8eb62e349f7179479c7c6627a97f61370f4154d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Jul 2024 16:46:31 +0300 Subject: [PATCH 658/698] New translations v24.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2024/v24.6.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/zh/release-notes/2024/v24.6.md b/guide/content/zh/release-notes/2024/v24.6.md index bdb729a27c..e4a2d48113 100644 --- a/guide/content/zh/release-notes/2024/v24.6.md +++ b/guide/content/zh/release-notes/2024/v24.6.md @@ -8,15 +8,15 @@ title: 版本24.6 ## 一. 导言 -这是版本 24 [发行周期] (../../organization/policies.md#release-schedule) 的第一次版本。 与过去几年相比，释放24人的队伍可能略有改变。 请确保在Discord服务器上更新最新信息。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出一个问题。 +这是版本 24 [发行周期] (../../organization/policies.md#release-schedule) 的首个版本。 与过去几年相比，释放24人的队伍可能略有改变。 请确保你已经加入了Discord服务器来跟进最新信息。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出问题。 -## 了解什么 +## 需要了解的内容 -更多详细信息在 [Changelog](../changelog.html)。 显著的新功能或破损功能以及升级内容： +更多详细信息在 [Changelog](../changelog.html) 可供查阅。 引人注目的新功能或破坏性更新以及升级内容： ### 日志改进 -默认日志模式已被清理，以使它们在从终端会话中查看时更方便开发者。 这包括使用颜色和较少详细的格式化。 +默认日志格式已得到清理，因此当从控制台会话阅览日志时，对开发者会更加友好。 这包括使用颜色和较少详细的格式化。 Sanic 将根据您的服务器是否处于DEBUG模式选择两种轻微的变量。 您总是可以选择通过使用以下方式删除颜色： From eb824693c5d89d0d3fc2e2b01ea8c49d0836a986 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 7 Jul 2024 18:34:55 +0300 Subject: [PATCH 659/698] New translations v24.6.md (Chinese Simplified) --- guide/content/zh/release-notes/2024/v24.6.md | 28 ++++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/guide/content/zh/release-notes/2024/v24.6.md b/guide/content/zh/release-notes/2024/v24.6.md index e4a2d48113..57b0933ce8 100644 --- a/guide/content/zh/release-notes/2024/v24.6.md +++ b/guide/content/zh/release-notes/2024/v24.6.md @@ -8,7 +8,7 @@ title: 版本24.6 ## 一. 导言 -这是版本 24 [发行周期] (../../organization/policies.md#release-schedule) 的首个版本。 与过去几年相比，释放24人的队伍可能略有改变。 请确保你已经加入了Discord服务器来跟进最新信息。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出问题。 +这是版本 24 [发行周期] (../../organization/policies.md#release-schedule) 的首个版本。 v24 的发布节奏可能与过去几年略有不同。 请确保你已经加入了Discord服务器来跟进最新信息。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出问题。 ## 需要了解的内容 @@ -16,17 +16,17 @@ title: 版本24.6 ### 日志改进 -默认日志格式已得到清理，因此当从控制台会话阅览日志时，对开发者会更加友好。 这包括使用颜色和较少详细的格式化。 +默认日志格式已得到清理，因此当从控制台会话阅览日志时，对开发者会更加友好。 这包括：使用颜色进行高亮和减少冗余内容。 -Sanic 将根据您的服务器是否处于DEBUG模式选择两种轻微的变量。 您总是可以选择通过使用以下方式删除颜色： +Sanic 将根据您的服务器是否处于 DEBUG 模式在两种细微变化之间进行选择。 您始终可以选择使用以下方法去除日志打印的颜色： ```python app.config.NO_COLOR = True ``` -颜色将自动从TTY 终端中删除日志。 +颜色将自动从非 TTY 终端的日志中去除。 -Sanic 将使用 `sanic.logging.formatter.AutoFormatter` 和 `sanic.logging.formatter.AutoAccessFormatter` 自动切换DEBUG 和 PROD 格式格式。 当然，您可以使用适当命名的格式强制一个或另一个版本 +在使用`sanic.logging.formatter.AutoFormatter`和`sanic.logging.formatter.AutoAccessFormatter`时，Sanic会自动根据 DEBUG 和 PROD 模式进行日志格式的切换。 当然，你可以使用适当命名的格式化程序强制使用一个版本或另一个版本 #### 在 DEBUG 模式 @@ -48,7 +48,7 @@ sanic.logging.formatter.ProdAccessFormatter #### 遗留问题 -如果你喜欢旧式的伐木，它们将作为日志格式保存给你：`sanic.logging.formter.LegacyFormatter`和`sanic.logging.formter.LegacessFormatter`。 +如果您更喜欢旧式的日志记录，这些日志格式化程序也为你保留了这类格式：`sanic.logging.formatter.LegacyFormatter`和`sanic.logging.formatter.LegacyAccessFormatter`。 实现这些格式化的一种方式： @@ -65,9 +65,9 @@ LOGGING_CONFIG_DEFAULTS["formatters"] = { } ``` -#### 新 JSON 格式化器 +#### 新 JSON formatter -还有一个新的 JSON 日志格式化器，它将以JSON 格式输出日志以便与其他第三部分日志平台合并。 +还有一个新的 JSON 日志格式化器（Formatter），它将以JSON 格式输出日志以便与其他第三方日志平台集成。 ```python from sanic.log import LOGGING_CONFIG_DEFAULTS @@ -82,9 +82,9 @@ LOGGING_CONFIG_DEFAULTS["formatters"] = { } ``` -### 在 unix 套接字中使用路径 +### 在 unix 套接字中使用Path -当为您的服务器创建一个unix 套接字时，您现在可以通过通过 `pathlib.Path` 对象而不是一个基于字符串的路径来执行它。 +在为服务器创建 unix 套接字时，现在可以通过传递`pathlib.Path`对象（而不是仅基于字符串的路径）来执行此操作。 ### 自定义路由名称 @@ -108,13 +108,13 @@ async def handler(request): return app ``` -### 🚨 Breaking 更改 +### 🚨 破坏性更改 1. `Request.cookies.getlist` 总是返回 `list` 。 这意味着，如果没有 `key` 的 cookie 时，它将是空的 `list` 而不是 `None'。 使用 `Request.cookies.getlist("something", None)\` 来保留现有的行为。 -## 谢谢你 +## 特别鸣谢 -Thank you to everyone that participated in this release: :clap: +感谢参与到本次迭代的所有人：:clap: [@ahopkins](https://github.com/ahopkins) [@ashleysommer](https://github.com/ashleysommer) @@ -132,4 +132,4 @@ Thank you to everyone that participated in this release: :clap: --- -如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 +如果您喜欢这个项目，请考虑参与贡献。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，提供一些案例，加入交流并让您的声音为人所知，如果您能够：[财务捐款](https://opencollective.com/sanic-org/)，那再好不过了。 From 1ae61dc1dfe5ccd9ef38345f7b3561fbd0c7b782 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 13:13:51 +0200 Subject: [PATCH 660/698] New translations cors.md (Japanese) --- guide/content/ja/plugins/sanic-ext/http/cors.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/http/cors.md b/guide/content/ja/plugins/sanic-ext/http/cors.md index 2726a56bd7..3c82b9be49 100644 --- a/guide/content/ja/plugins/sanic-ext/http/cors.md +++ b/guide/content/ja/plugins/sanic-ext/http/cors.md @@ -69,11 +69,11 @@ _上記の「リスト[str]」と書かれている簡潔さのために、`リ .. 列:: ``` -特定のルートのアプリ全体の設定を上書きする必要がある場合もあります。 これを可能にするには、 `@sanic_ext.cors()` デコレータを使用して、ルート固有の値を設定します。 +It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. -このデコレータで上書きできる値は次のとおりです。 +The values that can be overridden with this decorator are: -- `origins` +- `origin` - `expose_headers` - `allow_headers` - `allow_methods` @@ -87,10 +87,10 @@ _上記の「リスト[str]」と書かれている簡潔さのために、`リ ```python from sanic_ext import cors -app.config.CORS_ORIGinS = "https://foo.com" +app.config.CORS_ORIGINS = "https://foo.com" @app.get("/", host="bar.com") -@cors(origs="https://bar.com") +@cors(origin="https://bar.com") async def hello_world(request): return text("Hello, world.") ``` From 4ca6f5d8b367e450d8f3ab904392149e1a9823ad Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 13:13:52 +0200 Subject: [PATCH 661/698] New translations cors.md (Korean) --- guide/content/ko/plugins/sanic-ext/http/cors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ko/plugins/sanic-ext/http/cors.md b/guide/content/ko/plugins/sanic-ext/http/cors.md index 4d12e745aa..53701868a9 100644 --- a/guide/content/ko/plugins/sanic-ext/http/cors.md +++ b/guide/content/ko/plugins/sanic-ext/http/cors.md @@ -73,7 +73,7 @@ It may sometimes be necessary to override app-wide settings for a specific route The values that can be overridden with this decorator are: -- `origins` +- `origin` - `expose_headers` - `allow_headers` - `allow_methods` @@ -90,7 +90,7 @@ from sanic_ext import cors app.config.CORS_ORIGINS = "https://foo.com" @app.get("/", host="bar.com") -@cors(origins="https://bar.com") +@cors(origin="https://bar.com") async def hello_world(request): return text("Hello, world.") ``` From 7e5617fcc527adda53497fa2f1f888da2c90f10e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 13:13:53 +0200 Subject: [PATCH 662/698] New translations cors.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/http/cors.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/http/cors.md b/guide/content/zh/plugins/sanic-ext/http/cors.md index 51dabb91f6..f868d8ff27 100644 --- a/guide/content/zh/plugins/sanic-ext/http/cors.md +++ b/guide/content/zh/plugins/sanic-ext/http/cors.md @@ -69,12 +69,12 @@ _For the sake of brevity, where the above says `List[str]` any instance of a `li .. 列: ``` -有时可能需要覆盖特定路由的应用程序设置。 为了允许这一点，您可以使用 `@sanic_ext.cors()` 装饰符来设置不同的路径特定值。 +It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. -此装饰符可以覆盖的值是： +The values that can be overridden with this decorator are: -- `origins` -- `expose_headers' +- `origin` +- `expose_headers` - `allow_headers` - `allow_methods` - `supports_credentials` @@ -90,7 +90,7 @@ from sanic_ext import cors app.config.CORS_ORIGINS = "https://foo.com" @app.get("/", host="bar.com") -@cors(origins="https://bar.com") +@cors(origin="https://bar.com") async def hello_world(request): return text("Hello, world.") ``` From db87ba8136cfa8aae98488d52acf60eaeb7ef7e1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:33:23 +0200 Subject: [PATCH 663/698] New translations cors.md (Japanese) --- guide/content/ja/plugins/sanic-ext/http/cors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/plugins/sanic-ext/http/cors.md b/guide/content/ja/plugins/sanic-ext/http/cors.md index 3c82b9be49..50f9f8a81f 100644 --- a/guide/content/ja/plugins/sanic-ext/http/cors.md +++ b/guide/content/ja/plugins/sanic-ext/http/cors.md @@ -69,9 +69,9 @@ _上記の「リスト[str]」と書かれている簡潔さのために、`リ .. 列:: ``` -It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. +特定のルートのアプリ全体の設定を上書きする必要がある場合もあります。 これを可能にするには、 `@sanic_ext.cors()` デコレータを使用して、ルート固有の値を設定します。 -The values that can be overridden with this decorator are: +このデコレータで上書きできる値は次のとおりです。 - `origin` - `expose_headers` From 005c22e5d802ed125a632980276f220d2b745b46 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:33:38 +0200 Subject: [PATCH 664/698] New translations routing.md (Japanese) --- guide/content/ja/guide/basics/routing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/ja/guide/basics/routing.md b/guide/content/ja/guide/basics/routing.md index 2f7af7c719..6ee0fb5578 100644 --- a/guide/content/ja/guide/basics/routing.md +++ b/guide/content/ja/guide/basics/routing.md @@ -469,14 +469,14 @@ async def handler(request, foo: str, ext: str): ``` ```` -| 定義 | 例 | ファイル名 | 拡張 | -| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | -| \file:ext | page.txt | `"page"` | `"txt"` | -| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | -| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| 定義 | 例 | ファイル名 | 拡張 | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| | 123.txt | `123` | `"txt"` | +| | 123.svg | `123` | `"svg"` | +| | 3.14.tar.gz | `3.14` | `"tar.gz"` | ファイル拡張子は、特別なパラメータタイプ`ext`を使用して一致させることができます。 これは、ファイル名として他のタイプのパラメータを指定することができる特別な形式を使用します。 上の表に示されているように、1つまたは複数の特定の拡張子を指定します。 From f1b524f40ea6d1259f0e65f166736e0b1bb116ca Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:34:00 +0200 Subject: [PATCH 665/698] New translations cors.md (Chinese Simplified) --- guide/content/zh/plugins/sanic-ext/http/cors.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guide/content/zh/plugins/sanic-ext/http/cors.md b/guide/content/zh/plugins/sanic-ext/http/cors.md index f868d8ff27..08d7e9baa1 100644 --- a/guide/content/zh/plugins/sanic-ext/http/cors.md +++ b/guide/content/zh/plugins/sanic-ext/http/cors.md @@ -69,12 +69,12 @@ _For the sake of brevity, where the above says `List[str]` any instance of a `li .. 列: ``` -It may sometimes be necessary to override app-wide settings for a specific route. To allow for this, you can use the `@sanic_ext.cors()` decorator to set different route-specific values. +有时可能需要覆盖特定路由的应用程序设置。 为了允许这一点，您可以使用 `@sanic_ext.cors()` 装饰符来设置不同的路径特定值。 -The values that can be overridden with this decorator are: +此装饰符可以覆盖的值是： - `origin` -- `expose_headers` +- `expose_headers' - `allow_headers` - `allow_methods` - `supports_credentials` @@ -90,7 +90,7 @@ from sanic_ext import cors app.config.CORS_ORIGINS = "https://foo.com" @app.get("/", host="bar.com") -@cors(origin="https://bar.com") +@cors(orig="https://bar.com") async def hello_world(request): return text("Hello, world.") ``` From 1a43def9708624f98453d32ec006d7e4cab824e2 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:34:01 +0200 Subject: [PATCH 666/698] New translations configuration.md (Japanese) --- guide/content/ja/guide/running/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/running/configuration.md b/guide/content/ja/guide/running/configuration.md index d28730a1ab..42ab3df109 100644 --- a/guide/content/ja/guide/running/configuration.md +++ b/guide/content/ja/guide/running/configuration.md @@ -256,7 +256,7 @@ app = Sanic(..., config=Config(converters=[UUID])) | INSPECTOR_HOST | localhost | インスペクタのホスト | | インポートします。 | 6457 | インスペクターのポート | | キー | - | インスペクタの TLS キー | -| INSPECTOR_TLS_CERT | * | インスペクタの TLS 証明書 | +| INSPECTOR_TLS_CERT | - | インスペクタの TLS 証明書 | | INSPECTOR_API_KEY | - | インスペクタの API キー | | ALIVE_TIMEOUT | 120 | TCPコネクションを保持する期間 (秒) | | 保持します。 | True | Falseのときは生き残りを無効にします | From 36e0a0f4ebca413cfb3951ad248ad2a53c6be4c1 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:34:05 +0200 Subject: [PATCH 667/698] New translations running.md (Japanese) --- guide/content/ja/guide/running/running.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/running/running.md b/guide/content/ja/guide/running/running.md index c977fa52f4..98c4b45a5e 100644 --- a/guide/content/ja/guide/running/running.md +++ b/guide/content/ja/guide/running/running.md @@ -524,7 +524,7 @@ hypercorn myapp:app ASGIを使用する場合、いくつか注意すべきことがあります: 1. Sanic ウェブサーバを使用する場合、websocketsは`websockets`パッケージを使用して実行されます。 ASGI モードでは、ウェブソケットは ASGI サーバで管理されるため、このパッケージは必要ありません。 -2. ASGIの寿命プロトコル https://asgi.readthedocs.io/en/latest/specs/lifespan.htmlは、起動とシャットダウンの2つのサーバーイベントのみをサポートしています。 Sanicは、起動前、起動後、シャットダウン前、シャットダウン後の4つを持っています。 したがって、ASGIモードで 起動イベントとシャットダウンイベントは連続して実行され、実際にはサーバープロセスの開始と終了の周りには実行されません(それ以降はASGIサーバーによって制御されます)。 ですから、`after_server_start` と `before_server_stop` を使うのがベストです。 +2. ASGIの寿命プロトコル は、起動とシャットダウンの2つのサーバーイベントのみをサポートしています。 Sanicは、起動前、起動後、シャットダウン前、シャットダウン後の4つを持っています。 したがって、ASGIモードで 起動イベントとシャットダウンイベントは連続して実行され、実際にはサーバープロセスの開始と終了の周りには実行されません(それ以降はASGIサーバーによって制御されます)。 ですから、`after_server_start` と `before_server_stop` を使うのがベストです。 ### トリオ From f57a42354e6326f3daaabe99e5ed1e9227779253 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:34:31 +0200 Subject: [PATCH 668/698] New translations v22.3.md (Japanese) --- guide/content/ja/release-notes/2022/v22.3.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/ja/release-notes/2022/v22.3.md b/guide/content/ja/release-notes/2022/v22.3.md index 08cda60b29..0728ffc1e5 100644 --- a/guide/content/ja/release-notes/2022/v22.3.md +++ b/guide/content/ja/release-notes/2022/v22.3.md @@ -61,14 +61,14 @@ async def handler(request, filename, ext): いくつかの潜在的な例: -| 定義 | 例 | ファイル名 | 拡張 | -| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | -| \file:ext | page.txt | `"page"` | `"txt"` | -| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | -| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| 定義 | 例 | ファイル名 | 拡張 | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| | 123.txt | `123` | `"txt"` | +| | 123.svg | `123` | `"svg"` | +| | 3.14.tar.gz | `3.14` | `"tar.gz"` | ### 🚨 _BREAKING CHANGE_ - パスパラメータの空でない文字列の一致 From 62f81d82eaf03f0da0931f8092335f16b56d20cb Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:34:56 +0200 Subject: [PATCH 669/698] New translations routing.md (Korean) --- guide/content/ko/guide/basics/routing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/ko/guide/basics/routing.md b/guide/content/ko/guide/basics/routing.md index d36c6653b9..109d9eb2df 100644 --- a/guide/content/ko/guide/basics/routing.md +++ b/guide/content/ko/guide/basics/routing.md @@ -469,14 +469,14 @@ async def handler(request, foo: str, ext: str): ``` ```` -| definition | example | filename | extension | -| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | -| \file:ext | page.txt | `"page"` | `"txt"` | -| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | -| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| definition | example | filename | extension | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| | 123.txt | `123` | `"txt"` | +| | 123.svg | `123` | `"svg"` | +| | 3.14.tar.gz | `3.14` | `"tar.gz"` | File extensions can be matched using the special `ext` parameter type. It uses a special format that allows you to specify other types of parameter types as the file name, and one or more specific extensions as shown in the example table above. From 21100299ec337920957ac8da13cfd64a5788d6c3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:35:19 +0200 Subject: [PATCH 670/698] New translations configuration.md (Korean) --- guide/content/ko/guide/running/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/running/configuration.md b/guide/content/ko/guide/running/configuration.md index 5b6bd45745..057ea4b318 100644 --- a/guide/content/ko/guide/running/configuration.md +++ b/guide/content/ko/guide/running/configuration.md @@ -256,7 +256,7 @@ app = Sanic(..., config=Config(converters=[UUID])) | INSPECTOR_HOST | localhost | The host for the Inspector | | INSPECTOR_PORT | 6457 | The port for the Inspector | | INSPECTOR_TLS_KEY | - | The TLS key for the Inspector | -| INSPECTOR_TLS_CERT | * | The TLS certificate for the Inspector | +| INSPECTOR_TLS_CERT | - | The TLS certificate for the Inspector | | INSPECTOR_API_KEY | - | The API key for the Inspector | | KEEP_ALIVE_TIMEOUT | 120 | How long to hold a TCP connection open (sec) | | KEEP_ALIVE | True | Disables keep-alive when False | From f4f01f7c63e152f70705f3fc5348bc5f2721c95f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:35:23 +0200 Subject: [PATCH 671/698] New translations running.md (Korean) --- guide/content/ko/guide/running/running.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/running/running.md b/guide/content/ko/guide/running/running.md index aafc297c8f..8bf91256a0 100644 --- a/guide/content/ko/guide/running/running.md +++ b/guide/content/ko/guide/running/running.md @@ -524,7 +524,7 @@ hypercorn myapp:app A couple things to note when using ASGI: 1. When using the Sanic webserver, websockets will run using the `websockets` package. In ASGI mode, there is no need for this package since websockets are managed in the ASGI server. -2. The ASGI lifespan protocol https://asgi.readthedocs.io/en/latest/specs/lifespan.html, supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. +2. The ASGI lifespan protocol , supports only two server events: startup and shutdown. Sanic has four: before startup, after startup, before shutdown, and after shutdown. Therefore, in ASGI mode, the startup and shutdown events will run consecutively and not actually around the server process beginning and ending (since that is now controlled by the ASGI server). Therefore, it is best to use `after_server_start` and `before_server_stop`. ### Trio From c9877ab95f9384d20d168f071730107fdd5b56bf Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:35:48 +0200 Subject: [PATCH 672/698] New translations v22.3.md (Korean) --- guide/content/ko/release-notes/2022/v22.3.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/ko/release-notes/2022/v22.3.md b/guide/content/ko/release-notes/2022/v22.3.md index f39d38eb92..ecec7630ec 100644 --- a/guide/content/ko/release-notes/2022/v22.3.md +++ b/guide/content/ko/release-notes/2022/v22.3.md @@ -61,14 +61,14 @@ async def handler(request, filename, ext): Some potential examples: -| definition | example | filename | extension | -| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | ---------- | -| \file:ext | page.txt | `"page"` | `"txt"` | -| \file:ext=jpg | cat.jpg | `"cat"` | `"jpg"` | -| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | `"jpg"` | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | `"tar.gz"` | +| definition | example | filename | extension | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------- | ---------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| \ | cat.jpg | `"cat"` | `"jpg"` | +| | 123.txt | `123` | `"txt"` | +| | 123.svg | `123` | `"svg"` | +| | 3.14.tar.gz | `3.14` | `"tar.gz"` | ### 🚨 _BREAKING CHANGE_ - Path parameter matching of non-empty strings From fa914246369d3e6627f06694338a2800511b8ffd Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:36:13 +0200 Subject: [PATCH 673/698] New translations routing.md (Chinese Simplified) --- guide/content/zh/guide/basics/routing.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/zh/guide/basics/routing.md b/guide/content/zh/guide/basics/routing.md index 78dd721ba0..670095b73c 100644 --- a/guide/content/zh/guide/basics/routing.md +++ b/guide/content/zh/guide/basics/routing.md @@ -469,14 +469,14 @@ async def handler(request, foo: str, ext: str): ``` ```` -| 定义 | 示例 | 文件名 | 扩展 | -| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | --------------------------- | -| \file:ext | page.txt | `"page"` | `"txt"` | -| \file:ext=jpg | cat.jpg | `"cat"` | \`"jpg"" | -| \file:ext=jpg\\\|png\\\|gif\\\|svg | cat.jpg | `"cat"` | \`"jpg"" | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | +| 定义 | 示例 | 文件名 | 扩展 | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------- | --------------------------- | +| \ | page.txt | `"page"` | `"txt"` | +| \ | cat.jpg | `"cat"` | \`"jpg"" | +| \ | cat.jpg | `"cat"` | \`"jpg"" | +| | 123.txt | `123` | `"txt"` | +| | 123.svg | `123` | `"svg"` | +| | 3.14.tar.gz | `3.14` | \`"tar.gz"" | 可以通过特殊的 ext 参数类型来匹配文件扩展名。 它采用一种特殊格式，允许您指定其他类型的参数作为文件名，并如上文示例表格所示，指定一个或多个特定扩展名。 From 469d63a0d974edb320e2ca238afce4c45e7d13a6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:36:34 +0200 Subject: [PATCH 674/698] New translations configuration.md (Chinese Simplified) --- guide/content/zh/guide/running/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/running/configuration.md b/guide/content/zh/guide/running/configuration.md index 8dba9cffd5..a0e226a848 100644 --- a/guide/content/zh/guide/running/configuration.md +++ b/guide/content/zh/guide/running/configuration.md @@ -256,7 +256,7 @@ app = Sanic(..., config=Config(converters=[UUID])) | INSPECTOR_HOST | 本地主机 | 检查专员的主机 | | INSPECTOR_PORT | 6457 | 检查员的端口 | | INSPECTOR_TLS_TITLE | - | 检查员的TLS密钥 | -| INSPECTOR_TLS_CERT | * | 检查员的TLS证书 | +| INSPECTOR_TLS_CERT | - | 检查员的TLS证书 | | INSPECTOR_API_KEY | - | 检查员的 API 密钥 | | KEEP_ALIVEUT | 120 | 保持TCP连接打开多长时间(秒) | | KEEP_ALIVE | 真的 | False 时禁用保持生命值 | From 7bb31312d2c240235216f46c4c665bdbbb1d5e86 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:36:38 +0200 Subject: [PATCH 675/698] New translations running.md (Chinese Simplified) --- guide/content/zh/guide/running/running.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/running/running.md b/guide/content/zh/guide/running/running.md index 6fdbdd6080..4616e2585f 100644 --- a/guide/content/zh/guide/running/running.md +++ b/guide/content/zh/guide/running/running.md @@ -524,7 +524,7 @@ uvicorn myapp:app 使用ASGI时要注意的几件事： 1. 当使用 Sanic 网络服务器时，websockets 将使用 `websockets` 软件包运行。 在 ASGI 模式下，没有必要使用这个软件包，因为websockets 是在 ASGI 服务器上管理的。 -2. ASGI 生命周期协议 https://asgi.readthedocs.io/en/latest/specs/lifespan.html，只支持两个服务器事件：启动和关机。 萨里语有四个：启动前、启动后、关闭前和关机。 因此，以ASGI模式， 启动和关闭事件将连续运行，而不是围绕服务器进程开始和结束(因为现在是由 ASGI 服务器控制的)。 因此，最好使用 `after _server_start` 和 `previ_server_stop` 。 +2. ASGI 生命周期协议 ，只支持两个服务器事件：启动和关机。 萨里语有四个：启动前、启动后、关闭前和关机。 因此，以ASGI模式， 启动和关闭事件将连续运行，而不是围绕服务器进程开始和结束(因为现在是由 ASGI 服务器控制的)。 因此，最好使用 `after _server_start` 和 `previ_server_stop` 。 ### 特里奥文 From a7a0cdd36ed9fb1a930fb094a49890674555297d Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Sun, 22 Dec 2024 14:37:03 +0200 Subject: [PATCH 676/698] New translations v22.3.md (Chinese Simplified) --- guide/content/zh/release-notes/2022/v22.3.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guide/content/zh/release-notes/2022/v22.3.md b/guide/content/zh/release-notes/2022/v22.3.md index b502c935f2..96ac53b94a 100644 --- a/guide/content/zh/release-notes/2022/v22.3.md +++ b/guide/content/zh/release-notes/2022/v22.3.md @@ -61,14 +61,14 @@ async def 处理(请求, 文件名, ext): 一些潜在的例子： -| 定义 | 示例 | 文件名 | 扩展 | -| -------------------------------------------------------- | ----------------------------------------------------------- | -------- | --------------------------- | -| \file:ext | 页次 | `"page"` | `"txt"` | -| \file:ext=jpg | jpg | `"cat"` | \`"jpg"" | -| \file:ext=jpg\\\|png\\\|gif\\\|svg | jpg | `"cat"` | \`"jpg"" | -| \ | 123.txt | `123` | `"txt"` | -| \ | 123.svg | `123` | `"svg"` | -| \ | 3.14.tar.gz | `3.14` | \`"tar.gz"" | +| 定义 | 示例 | 文件名 | 扩展 | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -------- | --------------------------- | +| \ | 页次 | `"page"` | `"txt"` | +| \ | jpg | `"cat"` | \`"jpg"" | +| \ | jpg | `"cat"` | \`"jpg"" | +| | 123.txt | `123` | `"txt"` | +| | 123.svg | `123` | `"svg"` | +| | 3.14.tar.gz | `3.14` | \`"tar.gz"" | ### 🚨 _Breaking变换_ - 非空字符串路径参数 From cc1ed9e1d539dcdc750a8aaa0429e41cfd9d8722 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:50:39 +0200 Subject: [PATCH 677/698] New translations policies.md (Japanese) --- guide/content/ja/organization/policies.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/organization/policies.md b/guide/content/ja/organization/policies.md index 72a278009e..035b235bd1 100644 --- a/guide/content/ja/organization/policies.md +++ b/guide/content/ja/organization/policies.md @@ -37,10 +37,12 @@ Sanicは12月に年に一度長期サポートリリース(別名「LTS」)を | バージョン | リリース | LTS | サポート | | ------------------------------------- | ---------- | ------------ | ---- | -| 23.12 | 2023-12-31 | 2025年から12年まで | ✅ | +| 24.12 | 2024-12-31 | 2026年から12年まで | ✅ | +| 24.6 | 2024-06-30 | | ⚪ | +| 23.12 | 2023-12-31 | 2025年から12年まで | ☑️ | | 23.6 | 2023-07-25 | | ⚪ | | 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | 2024年～12年まで | ☑️ | +| 22.12 | 2022-12-27 | | ☑️ | | 22.9 | 2022-09-29 | | ⚪ | | 22.6 | 2022-06-30 | | ⚪ | | 22.3 | 2022-03-31 | | ⚪ | From bba7dd9074fbd45e878a827b120af93ee336d222 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:51:08 +0200 Subject: [PATCH 678/698] New translations changelog.md (Japanese) --- guide/content/ja/release-notes/changelog.md | 31 +++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/guide/content/ja/release-notes/changelog.md b/guide/content/ja/release-notes/changelog.md index ffc52a8b4e..af4a6c37ff 100644 --- a/guide/content/ja/release-notes/changelog.md +++ b/guide/content/ja/release-notes/changelog.md @@ -7,12 +7,39 @@ content_class: 更新履歴 🔶 現在のリリース\ 🔷 LTS リリース -## バージョン24.6.0 🔶 +## バージョン24.12.0 🔶🔷 _現在のバージョン_ ### 特徴 +- [#3019](https://github.com/sanic-org/sanic/pull/3019) `sanic` CLI にカスタムコマンドを追加する + +### バグ修正 + +- [#2992](https://github.com/sanic-org/sanic/pull/2992) `mixins.startup.serve` UnboundLocalError を修正 +- [#3000](https://github.com/sanic-org/sanic/pull/3000) `dumps`呼び出し可能な戻り値タイプの`bytes`に対する`JSONResponse`メソッドの型迷惑を修正しました +- [#3009](https://github.com/sanic-org/sanic/pull/3009) `False`に設定すると、`SanicException.quiet`属性の処理を修正します。 +- [#3014](https://github.com/sanic-org/sanic/pull/3014) 入力内容をクリーンアップする +- [#3015](https://github.com/sanic-org/sanic/pull/3015) 該当する場合、プロセスグループ全体を倒す +- [#3016](https://github.com/sanic-org/sanic/pull/3016) HTTPMethodView クラスで get メソッドの互換性のない型注釈を修正しました + +### 非推奨と削除 + +- [#3020](https://github.com/sanic-org/sanic/pull/3020) Python 3.8 サポートを削除 + +### 開発者のインフラストラクチャ + +- [#3017](https://github.com/sanic-org/sanic/pull/3017) Cleanup setup.cfg + +### ドキュメントの改善 + +- [#3007](https://github.com/sanic-org/sanic/pull/3007) `sanic-ext`のドキュメントでtypoを修正する + +## バージョン 24.6.0 + +### 特徴 + - [#2838](https://github.com/sanic-org/sanic/pull/2838) リクエストクッキー「getlist」を簡素化する - [#2850](https://github.com/sanic-org/sanic/pull/2850) Unix ソケットは `pathlib.Path` を使用できるようになりました - [#2931](https://github.com/sanic-org/sanic/pull/2931) [#2958](https://github.com/sanic-org/sanic/pull/2958) ログの改善点 @@ -206,7 +233,7 @@ _当時の状況により、v.23.9はスキップされました。 _ - [#2712](https://github.com/sanic-org/sanic/pull/2712) リダイレクトを作成するために `'https'` を使用した例を改善しました -## バージョン22.12.0 🔷 +## バージョン 22.12.0 現在のLTSバージョン_ From 13746010a2473e520458ea39fe3abdac9e9940e4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:51:46 +0200 Subject: [PATCH 679/698] New translations policies.md (Korean) --- guide/content/ko/organization/policies.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/guide/content/ko/organization/policies.md b/guide/content/ko/organization/policies.md index e581dfdf8c..e6aca704dd 100644 --- a/guide/content/ko/organization/policies.md +++ b/guide/content/ko/organization/policies.md @@ -37,10 +37,12 @@ Sanic releases a long term support release (aka "LTS") once a year in December. | Version | Release | LTS | Supported | | ------------------------------------- | ---------- | ------------- | --------- | -| 23.12 | 2023-12-31 | until 2025-12 | ✅ | +| 24.12 | 2024-12-31 | until 2026-12 | ✅ | +| 24.6 | 2024-06-30 | | ⚪ | +| 23.12 | 2023-12-31 | until 2025-12 | ☑️ | | 23.6 | 2023-07-25 | | ⚪ | | 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | until 2024-12 | ☑️ | +| 22.12 | 2022-12-27 | | ☑️ | | 22.9 | 2022-09-29 | | ⚪ | | 22.6 | 2022-06-30 | | ⚪ | | 22.3 | 2022-03-31 | | ⚪ | From 8afc038a170b9606c741151b8bbfcca48023e0b3 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:52:13 +0200 Subject: [PATCH 680/698] New translations changelog.md (Korean) --- guide/content/ko/release-notes/changelog.md | 31 +++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/guide/content/ko/release-notes/changelog.md b/guide/content/ko/release-notes/changelog.md index 1451f54dd1..8e7597b27a 100644 --- a/guide/content/ko/release-notes/changelog.md +++ b/guide/content/ko/release-notes/changelog.md @@ -7,12 +7,39 @@ content_class: changelog 🔶 Current release\ 🔷 In support LTS release -## Version 24.6.0 🔶 +## Version 24.12.0 🔶🔷 _Current version_ ### Features +- [#3019](https://github.com/sanic-org/sanic/pull/3019) Add custom commands to `sanic` CLI + +### Bugfixes + +- [#2992](https://github.com/sanic-org/sanic/pull/2992) Fix `mixins.startup.serve` UnboundLocalError +- [#3000](https://github.com/sanic-org/sanic/pull/3000) Fix type annocation for `JSONResponse` method for return type `bytes` allowed for `dumps` callable +- [#3009](https://github.com/sanic-org/sanic/pull/3009) Fix `SanicException.quiet` attribute handling when set to `False` +- [#3014](https://github.com/sanic-org/sanic/pull/3014) Cleanup some typing +- [#3015](https://github.com/sanic-org/sanic/pull/3015) Kill the entire process group if applicable +- [#3016](https://github.com/sanic-org/sanic/pull/3016) Fix incompatible type annotation of get method in the HTTPMethodView class + +### Deprecations and Removals + +- [#3020](https://github.com/sanic-org/sanic/pull/3020) Remove Python 3.8 support + +### Developer infrastructure + +- [#3017](https://github.com/sanic-org/sanic/pull/3017) Cleanup setup.cfg + +### Improved Documentation + +- [#3007](https://github.com/sanic-org/sanic/pull/3007) Fix typo in documentation for `sanic-ext` + +## Version 24.6.0 + +### Features + - [#2838](https://github.com/sanic-org/sanic/pull/2838) Simplify request cookies `getlist` - [#2850](https://github.com/sanic-org/sanic/pull/2850) Unix sockets can now use `pathlib.Path` - [#2931](https://github.com/sanic-org/sanic/pull/2931) [#2958](https://github.com/sanic-org/sanic/pull/2958) Logging improvements @@ -206,7 +233,7 @@ _Due to circumstances at the time, v.23.9 was skipped._ - [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect -## Version 22.12.0 🔷 +## Version 22.12.0 _Current LTS version_ From 4516e3ce9ada8836e08582bfdfe4094f7ccb6eb9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:52:51 +0200 Subject: [PATCH 681/698] New translations policies.md (Chinese Simplified) --- guide/content/zh/organization/policies.md | 64 ++++++++++++----------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/guide/content/zh/organization/policies.md b/guide/content/zh/organization/policies.md index 4b01b842e0..7033022360 100644 --- a/guide/content/zh/organization/policies.md +++ b/guide/content/zh/organization/policies.md @@ -35,37 +35,39 @@ YY.MMM.MMRO 12月，Sanic每年发布一次长期支持释放（又名“LTS”）。 LTS 版本在 **24 个月**中获得错误修复和安全更新。 全年的临时释放每三个月进行一次，并在随后的释放之前得到支持。 -| 版本 | 发布 | LTS | 支持的 | -| ------------------------------------- | ---------- | ------- | --- | -| 23.12 | 2023-12-31 | 2025-12 | ✅ | -| 23.6 | 2023-07-25 | | ⚪ | -| 23.3 | 2023-03-26 | | ⚪ | -| 22.12 | 2022-12-27 | 2024-12 | ☑️ | -| 22.9 | 2022-09-29 | | ⚪ | -| 22.6 | 2022-06-30 | | ⚪ | -| 22.3 | 2022-03-31 | | ⚪ | -| 21.12 | 2021-12-26 | | ⚪ | -| 21.9 | 2021-09-30 | | ⚪ | -| 21.6 | 2021-06-27 | | ⚪ | -| 21.3 | 2021-03-21 | | ⚪ | -| 20.12 | 2020-12-29 | | ⚪ | -| 20.9 | 2020-09-30 | | ⚪ | -| 20.6 | 2020-06-28 | | ⚪ | -| 20.3 | 2020-05-14 | | ⚪ | -| 19.12 | 2019-12-27 | | ⚪ | -| 19.9 | 2019-10-12 | | ⚪ | -| 19.6 | 2019-06-21 | | ⚪ | -| 19.3 | 2019-03-23 | | ⚪ | -| 18.12 | 2018-12-27 | | ⚪ | -| 0.8.3 | 2018-09-13 | | ⚪ | -| 0.7.0 | 2017-12-06 | | ⚪ | -| 0.6.0 | 2017-08-03 | | ⚪ | -| 0.5.4 | 2017-05-09 | | ⚪ | -| 0.4.1 | 2017-02-28 | | ⚪ | -| 0.3.1 | 2017-02-09 | | ⚪ | -| 0.2.0 | 2017-01-14 | | ⚪ | -| 0.1.9 | 2016-12-25 | | ⚪ | -| 0.1.0 | 2016-10-16 | | ⚪ | +| 版本 | 发布 | LTS | 支持的 | +| ------------------------------------- | ---------- | --------- | --- | +| 24.12 | 2024-12-31 | 到 2026-12 | ✅ | +| 24.6 | 2024-06-30 | | ⚪ | +| 23.12 | 2023-12-31 | 2025-12 | ☑️ | +| 23.6 | 2023-07-25 | | ⚪ | +| 23.3 | 2023-03-26 | | ⚪ | +| 22.12 | 2022-12-27 | | ☑️ | +| 22.9 | 2022-09-29 | | ⚪ | +| 22.6 | 2022-06-30 | | ⚪ | +| 22.3 | 2022-03-31 | | ⚪ | +| 21.12 | 2021-12-26 | | ⚪ | +| 21.9 | 2021-09-30 | | ⚪ | +| 21.6 | 2021-06-27 | | ⚪ | +| 21.3 | 2021-03-21 | | ⚪ | +| 20.12 | 2020-12-29 | | ⚪ | +| 20.9 | 2020-09-30 | | ⚪ | +| 20.6 | 2020-06-28 | | ⚪ | +| 20.3 | 2020-05-14 | | ⚪ | +| 19.12 | 2019-12-27 | | ⚪ | +| 19.9 | 2019-10-12 | | ⚪ | +| 19.6 | 2019-06-21 | | ⚪ | +| 19.3 | 2019-03-23 | | ⚪ | +| 18.12 | 2018-12-27 | | ⚪ | +| 0.8.3 | 2018-09-13 | | ⚪ | +| 0.7.0 | 2017-12-06 | | ⚪ | +| 0.6.0 | 2017-08-03 | | ⚪ | +| 0.5.4 | 2017-05-09 | | ⚪ | +| 0.4.1 | 2017-02-28 | | ⚪ | +| 0.3.1 | 2017-02-09 | | ⚪ | +| 0.2.0 | 2017-01-14 | | ⚪ | +| 0.1.9 | 2016-12-25 | | ⚪ | +| 0.1.0 | 2016-10-16 | | ⚪ | ☑️ = security fixes\ :check_mark_buton: = 完全支持\ From 9debd348c3f81f70be1fe05c7b4f1ece37caba8e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:53:19 +0200 Subject: [PATCH 682/698] New translations changelog.md (Chinese Simplified) --- guide/content/zh/release-notes/changelog.md | 57 +++++++++++++++------ 1 file changed, 42 insertions(+), 15 deletions(-) diff --git a/guide/content/zh/release-notes/changelog.md b/guide/content/zh/release-notes/changelog.md index 151c7dc73e..9b7b87a7b1 100644 --- a/guide/content/zh/release-notes/changelog.md +++ b/guide/content/zh/release-notes/changelog.md @@ -7,12 +7,39 @@ content_class: 更新日志 :larg_orange_diamond: Current release :larg_blu_diamond: In support LTS release -## 版本24.6.0 :larg_orange_diamond: +## 版本24.12.0 :larg_orange_diamond::larg_blu_diamond: _当前版本_ ### Features +- [#3019](https://github.com/sanic-org/sanic/pull/3019) 在 `sanic` CLI 中添加自定义命令 + +### Bugfixes + +- [#2992](https://github.com/sanic-org/sanic/pull/2992) 修复`mixins.startup.serve` UnboundLocalError +- [#3000](https://github.com/sanic-org/sanic/pull/3000) +- [#3009](https://github.com/sanic-org/sanic/pull/3009) Fix `SanicException.quet` 属性处理设置为 `False` +- [#3014](https://github.com/sanic-org/sanic/pull/3014) 清理一些输入 +- [#3015](https://github.com/sanic-org/sanic/pull/3015) 如果适用，则杀死整个流程组 +- [#3016](https://github.com/sanic-org/sanic/pull/3016) 修复在 HTTPMethodView 类中获取方法的不兼容类型注释 + +### Deprecations and Removals + +- [#3020](https://github.com/sanic-org/sanic/pull/3020) 删除 Python 3.8 支持 + +### 开发者基础设施 + +- [#3017](https://github.com/sanic-org/sanic/pull/3017) Cleanup setup.cfg + +### Improved Documentation + +- [#3007](https://github.com/sanic-org/sanic/pull/3007) 修复`sanic-ext`的文档类型 + +## 版本24.6.0 + +### Features + - [#2838](https://github.com/sanic-org/sanic/pull/2838) 简化请求 cookie `getlist` - [#2850](https://github.com/sanic-org/sanic/pull/2850) Unix sockets 现在可以使用 `pathlib.Path` - [#2931](https://github.com/sanic-org/sanic/pull/2931)[#2958](https://github.com/sanic-org/sanic/pull/2958) 日志改进 @@ -32,7 +59,7 @@ _当前版本_ - [#2979](https://github.com/sanic-org/sanic/pull/2979) 抛出错误的身体长度 - [#2980](https://github.com/sanic-org/sanic/pull/2980) 丢弃错误的物体编码错误 -### Deprecations and Removals +### 废弃和移除 - [#2899](https://github.com/sanic-org/sanic/pull/2899) 从REPL中删除错误的行，从而影响没有HTTPX的环境 - [#2962](https://github.com/sanic-org/sanic/pull/2962) 合并实体头部删除 @@ -76,7 +103,7 @@ _当前版本_ - [#2803](https://github.com/sanic-org/sanic/pull/2803) Fix MOTD display for extra data -### 开发者基础设施 +### Developer infrastructure - [#2796](https://github.com/sanic-org/sanic/pull/2796) Refactor unit test cases - [#2801](https://github.com/sanic-org/sanic/pull/2801) Fix `test_fast` when there is only one CPU @@ -198,7 +225,7 @@ _Due to circumstances at the time, v.23.9 was skipped._ - [#2651](https://github.com/sanic-org/sanic/pull/2651) ASGI websocket to pass thru bytes as is - [#2697](https://github.com/sanic-org/sanic/pull/2697) Fix comparison between datetime aware and naive in `file` when using `If-Modified-Since` -### 废弃和移除 +### Deprecations and Removals - [#2666](https://github.com/sanic-org/sanic/pull/2666) Remove deprecated `__blueprintname__` property @@ -206,7 +233,7 @@ _Due to circumstances at the time, v.23.9 was skipped._ - [#2712](https://github.com/sanic-org/sanic/pull/2712) Improved example using `'https'` to create the redirect -## Version 22.12.0 🔷 +## 版本22.12.0 _当前LTS版本_ @@ -238,7 +265,7 @@ _当前LTS版本_ - [#2639](https://github.com/sanic-org/sanic/pull/2639) Add `unquote` to `add_route` method - [#2640](https://github.com/sanic-org/sanic/pull/2640) ASGI websockets to receive `text` or `bytes` -### Bugfixes +### 错误修正 - [#2607](https://github.com/sanic-org/sanic/pull/2607) Force socket shutdown before close to allow rebinding - [#2590](https://github.com/sanic-org/sanic/pull/2590) Use actual `StrEnum` in Python 3.11+ @@ -246,7 +273,7 @@ _当前LTS版本_ - [#2627](https://github.com/sanic-org/sanic/pull/2627) Crash ASGI application on lifespan failure - [#2635](https://github.com/sanic-org/sanic/pull/2635) Resolve error with low-level server creation on Windows -### Deprecations and Removals +### 废弃和移除 - [#2608](https://github.com/sanic-org/sanic/pull/2608) [#2630](https://github.com/sanic-org/sanic/pull/2630) Signal conditions and triggers saved on `signal.extra` - [#2626](https://github.com/sanic-org/sanic/pull/2626) Move to HTTP Inspector @@ -264,7 +291,7 @@ _当前LTS版本_ - [#2585](https://github.com/sanic-org/sanic/pull/2585) Improved error message when no applications have been registered -### 错误修正 +### Bugfixes - [#2578](https://github.com/sanic-org/sanic/pull/2578) Add certificate loader for in process certificate creation - [#2591](https://github.com/sanic-org/sanic/pull/2591) Do not use sentinel identity for `spawn` compatibility @@ -330,7 +357,7 @@ _当前LTS版本_ ## Version 22.6.2 -### Bugfixes +### 错误修正 - [#2522](https://github.com/sanic-org/sanic/pull/2522) Always show server location in ASGI @@ -358,7 +385,7 @@ _当前LTS版本_ - [#2453](https://github.com/sanic-org/sanic/pull/2453) Move verbosity filtering to logger - [#2475](https://github.com/sanic-org/sanic/pull/2475) Expose getter for current request using `Request.get_current()` -### 错误修正 +### Bugfixes - [#2448](https://github.com/sanic-org/sanic/pull/2448) Fix to allow running with `pythonw.exe` or places where there is no `sys.stdout` - [#2451](https://github.com/sanic-org/sanic/pull/2451) Trigger `http.lifecycle.request` signal in ASGI mode @@ -432,7 +459,7 @@ _当前LTS版本_ - [#2405](https://github.com/sanic-org/sanic/pull/2405) Upgrade tests for `sanic-routing` changes - [sanic-testing#35](https://github.com/sanic-org/sanic-testing/pull/35) Allow for httpx v0.22 -### Improved Documentation +### 改进文档 - [#2350](https://github.com/sanic-org/sanic/pull/2350) Fix link in README for ASGI - [#2398](https://github.com/sanic-org/sanic/pull/2398) Document middleware on_request and on_response @@ -453,7 +480,7 @@ _当前LTS版本_ ## Version 21.12.0 -### Features +### 功能 - [#2260](https://github.com/sanic-org/sanic/pull/2260) Allow early Blueprint registrations to still apply later added objects - [#2262](https://github.com/sanic-org/sanic/pull/2262) Noisy exceptions - force logging of all exceptions @@ -476,13 +503,13 @@ _当前LTS版本_ - [#2332](https://github.com/sanic-org/sanic/pull/2332) Make all deprecation notices consistent - [#2335](https://github.com/sanic-org/sanic/pull/2335) Allow underscore to start instance names -### Bugfixes +### 错误修正 - [#2273](https://github.com/sanic-org/sanic/pull/2273) Replace assignation by typing for `websocket_handshake` - [#2285](https://github.com/sanic-org/sanic/pull/2285) Fix IPv6 display in startup logs - [#2299](https://github.com/sanic-org/sanic/pull/2299) Dispatch `http.lifecyle.response` from exception handler -### Deprecations and Removals +### 废弃和移除 - [#2306](https://github.com/sanic-org/sanic/pull/2306) Removal of deprecated items - `Sanic` and `Blueprint` may no longer have arbitrary properties attached to them @@ -496,7 +523,7 @@ _当前LTS版本_ - _NOTE:_ the `stream()` response method (where you pass a callable streaming function) has been deprecated and will be removed in v22.6. You should upgrade all streaming responses to the new style: https://sanicframework.org/en/guide/advanced/streaming.html#response-streaming - [#2320](https://github.com/sanic-org/sanic/pull/2320) Remove app instance from Config for error handler setting -### Developer infrastructure +### 开发者基础设施 - [#2251](https://github.com/sanic-org/sanic/pull/2251) Change dev install command - [#2286](https://github.com/sanic-org/sanic/pull/2286) Change codeclimate complexity threshold from 5 to 10 From aa8a3b81bc732017ee5549e0825211fbe34e3462 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:53:21 +0200 Subject: [PATCH 683/698] New translations commands.md (Japanese) --- guide/content/ja/guide/advanced/commands.md | 73 +++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 guide/content/ja/guide/advanced/commands.md diff --git a/guide/content/ja/guide/advanced/commands.md b/guide/content/ja/guide/advanced/commands.md new file mode 100644 index 0000000000..30bd448117 --- /dev/null +++ b/guide/content/ja/guide/advanced/commands.md @@ -0,0 +1,73 @@ +# カスタムCLIコマンド + +.. new:: v24.12 の新機能 + +``` +This feature was added in version 24.12 +``` + +Sanic は Sanic サーバを実行するための [CLI](../running/running.html#running-via-command) を搭載しています。 場合によっては、独自のコマンドを実行するためにCLIを強化する必要があるかもしれません。 コマンドは以下の基本パターンを使用して呼び出されます。 + +```sh +sanic path.to:app exec [--arg=value] +``` + +.. 列:: + +``` +To enable this, you can use your `Sanic` app instance to wrap functions that can be callable from the CLI using the `@app.command` decorator. +``` + +.. 列:: + +```` +```python +@app.command +async def hello(name="world"): + print(f"Hello, {name}.") +``` +```` + +.. 列:: + +``` +Now, you can easily invoke this command using the `exec` action. +``` + +.. 列:: + +```` +```sh +sanic path.to:app exec hello --name=Adam +``` +```` + +コマンドハンドラは同期または非同期のどちらでも構いません。 ハンドラは、CLI から渡される任意の数のキーワード引数を受け入れることができます。 + +.. 列:: + +``` +By default, the name of the function will be the command name. You can override this by passing the `name` argument to the decorator. +``` + +.. 列:: + +```` +```python +@app.command(name="greet") +async def hello(name="world"): + print(f"Hello, {name}.") +``` + +```sh +sanic path.to:app exec greet --name=Adam +``` +```` + +.. 警告:: + +``` +This feature is still in **BETA** and may change in future versions. There is no type coercion or validation on the arguments passed in from the CLI, and the CLI will ignore any return values from the command handler. Future enhancements and changes are likely. +``` + +_V24.12_に追加しました From 21c6fb7aa860d838dc4c8d6660e3d5a5b4eca8c5 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:53:22 +0200 Subject: [PATCH 684/698] New translations v24.12.md (Japanese) --- guide/content/ja/release-notes/2024/v24.12.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 guide/content/ja/release-notes/2024/v24.12.md diff --git a/guide/content/ja/release-notes/2024/v24.12.md b/guide/content/ja/release-notes/2024/v24.12.md new file mode 100644 index 0000000000..039a3ae84c --- /dev/null +++ b/guide/content/ja/release-notes/2024/v24.12.md @@ -0,0 +1,80 @@ +--- +title: バージョン 24.12 +--- + +# バージョン 24.12 + +.. TOC:: + +## はじめに + +これはバージョン24format@@0(../../organization/policyes.md#release-schedule)の最初のリリースです。 v24のリリースケイデンスは、数年前から若干変更されている可能性があります。 最新のアップデートについては、Discordサーバーの最新情報を確認してください。 何か問題が発生した場合は、 [GitHub](https://github.com/sanic-org/sanic/issues/new/choose) にご注意ください。 + +## 知っておくべきこと + +[Changelog](../changelog.html) の詳細。 注目すべき新機能や破損した機能、アップグレードする機能: + +### 👶 _BETA_ カスタムCLIコマンド + +`sanic` CLI ユーティリティを使用すると、カスタムコマンドを呼び出すことができます。 コマンドは、以下のデコレータ構文を使用して追加できます。 + +```python +@app.command +async def foo(one, two: str, three: str = "..."): + logger.info(f"FOO {one=} {two=} {three=}") + + +@app.command +def bar(): + logger.info("BAR") + + +@app.command(name="qqq") +async def baz(): + logger.info("BAZ") +``` + +これらは `exec` コマンドを使用して呼び出されます。 + +```sh +sanic server:app exec [--arg=value] +``` + +関数の署名の引数は、引数として追加されます。 例: + +```sh +sanic server:app exec command --one=1 --two=2 --three=3 +``` + +.. 警告:: + +``` +This is in **BETA** and the functionality is subject to change in upcoming versions. +``` + +### Python 3.13 のサポートを追加 + +サポートされているバージョンに Python 3.13 を追加しました。 + +### Python 3.8 のサポートを削除 + +Python 3.8 は寿命の終わりに達しました。 Sanic は Python 3.8 のサポートを廃止しており、Python 3.9 以降が必要です。 + +### 古いレスポンスCookieアクセサリが削除されました + +v23 より前に、`Response` オブジェクトの Cookie が設定され、辞書オブジェクトとしてアクセスされました。 これは v23.3 で廃止され、新しい format@@0(../2023/v23.3.html#more-convenient-methods-for-setting-and-deleting-cookies) が追加されました。 古いパターンは削除されました。 + +## ありがとうございます + +このリリースに参加いただき、ありがとうございます： :clap: + +[@ahopkins](https://github.com/ahopkins) +[@C5H12O5](https://github.com/C5H12O5) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@HyperKiko](https://github.com/HyperKiko) +[@imnotjames](https://github.com/imnotes) +[@pygithub.com/pygithub.com/pygithub.com/pygeek) + +--- + +あなたがプロジェクトを楽しんでいるなら、貢献を検討してください。 もちろん私たちはコード貢献は大好きですが、どんな形でも貢献できます。 ドキュメントを書いたり、ユースケースを示したり、会話に参加したり、声を知らせたりすることを検討してください。format@@0(https://opencollective.com/sanic-org/) From 738d2673a7c942f810b8b18dd723b1f0baa1d8a9 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:53:23 +0200 Subject: [PATCH 685/698] New translations commands.md (Korean) --- guide/content/ko/guide/advanced/commands.md | 73 +++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 guide/content/ko/guide/advanced/commands.md diff --git a/guide/content/ko/guide/advanced/commands.md b/guide/content/ko/guide/advanced/commands.md new file mode 100644 index 0000000000..8f2cf07176 --- /dev/null +++ b/guide/content/ko/guide/advanced/commands.md @@ -0,0 +1,73 @@ +# Custom CLI Commands + +.. new:: New in v24.12 + +``` +This feature was added in version 24.12 +``` + +Sanic ships with a [CLI](../running/running.html#running-via-command) for running the Sanic server. Sometimes, you may have the need to enhance that CLI to run your own custom commands. Commands are invoked using the following basic pattern: + +```sh +sanic path.to:app exec [--arg=value] +``` + +.. column:: + +``` +To enable this, you can use your `Sanic` app instance to wrap functions that can be callable from the CLI using the `@app.command` decorator. +``` + +.. column:: + +```` +```python +@app.command +async def hello(name="world"): + print(f"Hello, {name}.") +``` +```` + +.. column:: + +``` +Now, you can easily invoke this command using the `exec` action. +``` + +.. column:: + +```` +```sh +sanic path.to:app exec hello --name=Adam +``` +```` + +Command handlers can be either synchronous or asynchronous. The handler can accept any number of keyword arguments, which will be passed in from the CLI. + +.. column:: + +``` +By default, the name of the function will be the command name. You can override this by passing the `name` argument to the decorator. +``` + +.. column:: + +```` +```python +@app.command(name="greet") +async def hello(name="world"): + print(f"Hello, {name}.") +``` + +```sh +sanic path.to:app exec greet --name=Adam +``` +```` + +.. warning:: + +``` +This feature is still in **BETA** and may change in future versions. There is no type coercion or validation on the arguments passed in from the CLI, and the CLI will ignore any return values from the command handler. Future enhancements and changes are likely. +``` + +_Added in v24.12_ From b22de8a946629e110d4fa2a618ee6bbb9d2fe51f Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:53:24 +0200 Subject: [PATCH 686/698] New translations v24.12.md (Korean) --- guide/content/ko/release-notes/2024/v24.12.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 guide/content/ko/release-notes/2024/v24.12.md diff --git a/guide/content/ko/release-notes/2024/v24.12.md b/guide/content/ko/release-notes/2024/v24.12.md new file mode 100644 index 0000000000..227cb5aaa5 --- /dev/null +++ b/guide/content/ko/release-notes/2024/v24.12.md @@ -0,0 +1,80 @@ +--- +title: Version 24.12 +--- + +# Version 24.12 + +.. toc:: + +## Introduction + +This is the first release of the version 24 [release cycle](../../organization/policies.md#release-schedule). The release cadence for v24 may be slightly altered from years past. Make sure to stay up to date in the Discord server for latest updates. If you run into any issues, please raise a concern on [GitHub](https://github.com/sanic-org/sanic/issues/new/choose). + +## What to know + +More details in the [Changelog](../changelog.html). Notable new or breaking features, and what to upgrade: + +### 👶 _BETA_ Custom CLI commands + +The `sanic` CLI utility now allows for custom commands to be invoked. Commands can be added using the decorator syntax below. + +```python +@app.command +async def foo(one, two: str, three: str = "..."): + logger.info(f"FOO {one=} {two=} {three=}") + + +@app.command +def bar(): + logger.info("BAR") + + +@app.command(name="qqq") +async def baz(): + logger.info("BAZ") +``` + +These are invoked using the `exec` command as follows. + +```sh +sanic server:app exec [--arg=value] +``` + +Any arguments in the function's signature will be added as arguments. For example: + +```sh +sanic server:app exec command --one=1 --two=2 --three=3 +``` + +.. warning:: + +``` +This is in **BETA** and the functionality is subject to change in upcoming versions. +``` + +### Add Python 3.13 support + +We have added Python 3.13 to the supported versions. + +### Remove Python 3.8 support + +Python 3.8 reached end-of-life. Sanic is now dropping support for Python 3.8, and requires Python 3.9 or newer. + +### Old response cookie accessors removed + +Prior to v23, cookies on `Response` objects were set and accessed as dictionary objects. That was deprecated in v23.3 when the new [convenience methods](../2023/v23.3.html#more-convenient-methods-for-setting-and-deleting-cookies) were added. The old patterns have been removed. + +## Thank you + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@C5H12O5](https://github.com/C5H12O5) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@HyperKiko](https://github.com/HyperKiko) +[@imnotjames](https://github.com/imnotjames) +[@pygeek](https://github.com/pygeek) + +--- + +If you enjoy the project, please consider contributing. Of course we love code contributions, but we also love contributions in any form. Consider writing some documentation, showing off use cases, joining conversations and making your voice known, and if you are able: [financial contributions](https://opencollective.com/sanic-org/). From 59a8e35c19c5dc8723d34b191f3b213cb04ee6e4 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:53:25 +0200 Subject: [PATCH 687/698] New translations commands.md (Chinese Simplified) --- guide/content/zh/guide/advanced/commands.md | 73 +++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 guide/content/zh/guide/advanced/commands.md diff --git a/guide/content/zh/guide/advanced/commands.md b/guide/content/zh/guide/advanced/commands.md new file mode 100644 index 0000000000..531fa428b6 --- /dev/null +++ b/guide/content/zh/guide/advanced/commands.md @@ -0,0 +1,73 @@ +# 自定义 CLI 命令 + +.. 新：v24.12 + +``` +This feature was added in version 24.12 +``` + +使用 [CLI]的Sanic 飞船(../running/running.html#running-via-command) 运行Sanic 服务器。 有时，您可能需要提高CLI来运行您自己的自定义命令。 命令使用以下基本模式： + +```sh +sanic path.to:app exec [--arg=value] +``` + +.. 列: + +``` +To enable this, you can use your `Sanic` app instance to wrap functions that can be callable from the CLI using the `@app.command` decorator. +``` + +.. 列: + +```` +```python +@app.command +async def hello(name="world"): + print(f"Hello, {name}.") +``` +```` + +.. 列: + +``` +Now, you can easily invoke this command using the `exec` action. +``` + +.. 列: + +```` +```sh +sanic path.to:app exec hello --name=Adam +``` +```` + +命令处理程序可以是同步或异步的。 处理程序可以接受任何一些关键词参数，这些参数将从CLI传递。 + +.. 列: + +``` +By default, the name of the function will be the command name. You can override this by passing the `name` argument to the decorator. +``` + +.. 列: + +```` +```python +@app.command(name="greet") +async def hello(name="world"): + print(f"Hello, {name}.") +``` + +```sh +sanic path.to:app exec greet --name=Adam +``` +```` + +.. 警告：: + +``` +This feature is still in **BETA** and may change in future versions. There is no type coercion or validation on the arguments passed in from the CLI, and the CLI will ignore any return values from the command handler. Future enhancements and changes are likely. +``` + +_添加于 v24.12_ From e8315fa8bc3332998640fd1ddd23eddde6f836f0 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Wed, 1 Jan 2025 01:53:26 +0200 Subject: [PATCH 688/698] New translations v24.12.md (Chinese Simplified) --- guide/content/zh/release-notes/2024/v24.12.md | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 guide/content/zh/release-notes/2024/v24.12.md diff --git a/guide/content/zh/release-notes/2024/v24.12.md b/guide/content/zh/release-notes/2024/v24.12.md new file mode 100644 index 0000000000..8fe38230cf --- /dev/null +++ b/guide/content/zh/release-notes/2024/v24.12.md @@ -0,0 +1,80 @@ +--- +title: 24.12 版本 +--- + +# 24.12 版本 + +.. toc:: + +## 一. 导言 + +这是版本 24 [发行周期] (../../organization/policies.md#release-schedule) 的第一次版本。 与过去几年相比，释放24人的队伍可能略有改变。 请确保在Discord服务器上更新最新信息。 如果您遇到任何问题，请在 [GitHub](https://github.com/sanic-org/sanic/issues/new/selecte) 上提出一个问题。 + +## 了解什么 + +更多详细信息在 [Changelog](../changelog.html)。 显著的新功能或破损功能以及升级内容： + +### 👶 _BETA_自定义 CLI 命令 + +现在`sanic` CLI 实用程序允许调用自定义命令。 命令可以使用下面的装饰符语法添加。 + +```python +@app.command +async def foo(one, two: str, three: str = "..."): + logger.info(f"FOO {one=} {two=} {three=}") + + +@app.command +def bar(): + logger.info("BAR") + + +@app.command(name="qqq") +async def baz(): + logger.info("BAZ") +``` + +这些命令使用下面的`exec`命令。 + +```sh +sanic server:app exec [--arg=value] +``` + +函数签名中的任何参数都将作为参数添加。 例如： + +```sh +sanic server:app exec command --one=1 --two=2 --three=3 +``` + +.. 警告：: + +``` +This is in **BETA** and the functionality is subject to change in upcoming versions. +``` + +### 添加 Python 3.13 支持 + +我们已经将 Python 3.13 添加到支持的版本。 + +### 删除 Python 3.8 支持 + +Python 3.8寿命终结。 Sanic 正在放弃对 Python 3.8的支持，需要 Python 3.9 或更高版本。 + +### 旧响应 cookie 存取器已删除 + +在 v23 之前，在 "Response" 对象上的 cookie 被设置为字典对象并被访问。 在 v23.3 中添加了新的 [方便方法] (../2023/v23.3.html#more-facilent-methods-for-setting-deleting-cookies)时，这种做法被废弃。 旧模式已被移除。 + +## 谢谢你 + +Thank you to everyone that participated in this release: :clap: + +[@ahopkins](https://github.com/ahopkins) +[@C5H12O5](https://github.com/C5H12O5) +[@ChihweiLHBird](https://github.com/ChihweiLHBird) +[@HyperKiko](https://github.com/HyperKiko) +[@imnotjames](https://github.com/imnotjames) +[@pygeek](https://github.com/pygeek) + +--- + +如果您喜欢这个项目，请考虑捐款。 当然，我们喜欢代码贡献，但我们也喜欢任何形式的贡献。 考虑撰写一些文档，显示关闭的情况，加入对话并让您的声音为人所知，如果您能够：[金融贡献](https://opencollective.com/sanic-org/)。 From 81c10a00b0dab31dc1e8f5b56b6a6bc74c5f633e Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 13:19:34 +0200 Subject: [PATCH 689/698] New translations getting-started.md (Japanese) --- guide/content/ja/guide/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/getting-started.md b/guide/content/ja/guide/getting-started.md index 00189a8fc3..938650bf22 100644 --- a/guide/content/ja/guide/getting-started.md +++ b/guide/content/ja/guide/getting-started.md @@ -1,6 +1,6 @@ # はじめに -始める前に、Python 3.8 以上を実行していることを確認してください。 現在、SanicはPythonバージョン3.8 - 3.11で動作します。 +Before we begin, make sure you are running Python 3.9 or higher. Currently, Sanic is works with Python versions 3.9 – 3.13. ## インストール From 00708a056488a8eaebaf387352fb7eba04ab3223 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 13:19:35 +0200 Subject: [PATCH 690/698] New translations introduction.md (Japanese) --- guide/content/ja/guide/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/introduction.md b/guide/content/ja/guide/introduction.md index 6e867d6d33..2d329019da 100644 --- a/guide/content/ja/guide/introduction.md +++ b/guide/content/ja/guide/introduction.md @@ -1,6 +1,6 @@ # はじめに -Sanic は Python 3.8+ のウェブサーバーであり、高速化のために書かれたウェブフレームワークです。 Python 3.5 で追加された async/await 構文を使用することができます。これにより、コードをノンブロッキングでスピーディーにすることができます。 +Sanic is a Python 3.9+ web server and web framework that’s written to go fast. Python 3.5 で追加された async/await 構文を使用することができます。これにより、コードをノンブロッキングでスピーディーにすることができます。 .. attrs:: :class: 紹介テーブル From 99429028e55dcede517208f7d8611b0bbd3439b6 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 13:19:36 +0200 Subject: [PATCH 691/698] New translations getting-started.md (Korean) --- guide/content/ko/guide/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/getting-started.md b/guide/content/ko/guide/getting-started.md index 67fc26f940..1b9b2e042b 100644 --- a/guide/content/ko/guide/getting-started.md +++ b/guide/content/ko/guide/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -Before we begin, make sure you are running Python 3.8 or higher. Currently, Sanic is works with Python versions 3.8 – 3.11. +Before we begin, make sure you are running Python 3.9 or higher. Currently, Sanic is works with Python versions 3.9 – 3.13. ## Install From e7ef4f37c762e4c9c7c80902fdf2e13ed9d56617 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 13:19:38 +0200 Subject: [PATCH 692/698] New translations introduction.md (Korean) --- guide/content/ko/guide/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ko/guide/introduction.md b/guide/content/ko/guide/introduction.md index 2e0b730f54..0e67eaf473 100644 --- a/guide/content/ko/guide/introduction.md +++ b/guide/content/ko/guide/introduction.md @@ -1,6 +1,6 @@ # Introduction -Sanic is a Python 3.8+ web server and web framework that’s written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy. +Sanic is a Python 3.9+ web server and web framework that’s written to go fast. It allows the usage of the async/await syntax added in Python 3.5, which makes your code non-blocking and speedy. .. attrs:: :class: introduction-table From 68919bec67d255826739b5afb1b2ba1d494b8e61 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 13:19:39 +0200 Subject: [PATCH 693/698] New translations getting-started.md (Chinese Simplified) --- guide/content/zh/guide/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/getting-started.md b/guide/content/zh/guide/getting-started.md index 5d122b120e..3ca79f66b6 100644 --- a/guide/content/zh/guide/getting-started.md +++ b/guide/content/zh/guide/getting-started.md @@ -1,6 +1,6 @@ # 快速上手 -在我们开始之前，请确保您正在运行 Python 3.8或更高版本。 目前，Sanic可以运行在Python 版本 3.8 - 3.11上。 +Before we begin, make sure you are running Python 3.9 or higher. Currently, Sanic is works with Python versions 3.9 – 3.13. ## 安装（Install） From 1450f83f062a7ddddec7aa720c592e34b5f8fc23 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 13:19:40 +0200 Subject: [PATCH 694/698] New translations introduction.md (Chinese Simplified) --- guide/content/zh/guide/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/introduction.md b/guide/content/zh/guide/introduction.md index 512cba8cc7..6d8640d6b6 100644 --- a/guide/content/zh/guide/introduction.md +++ b/guide/content/zh/guide/introduction.md @@ -1,6 +1,6 @@ # 介绍(Introduction) -Sanic 是 Python3.8+ Web 服务器和 Web 框架，旨在提高性能。 它允许使用 Python3.5 中添加的 async/await 异步语法，这使得您的代码有效地避免阻塞从而达到提升响应速度的目的。 +Sanic is a Python 3.9+ web server and web framework that’s written to go fast. 它允许使用 Python3.5 中添加的 async/await 异步语法，这使得您的代码有效地避免阻塞从而达到提升响应速度的目的。 .. attrs:: :class: introduction-table From 56f394a75c8c209780358e5e16da65f33d867416 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 14:45:13 +0200 Subject: [PATCH 695/698] New translations getting-started.md (Japanese) --- guide/content/ja/guide/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/getting-started.md b/guide/content/ja/guide/getting-started.md index 938650bf22..bcf3ca4992 100644 --- a/guide/content/ja/guide/getting-started.md +++ b/guide/content/ja/guide/getting-started.md @@ -1,6 +1,6 @@ # はじめに -Before we begin, make sure you are running Python 3.9 or higher. Currently, Sanic is works with Python versions 3.9 – 3.13. +始める前に、Python 3.9 以上を実行していることを確認してください。 現在、SanicはPythonバージョン3.9 – 3.13で動作しています。 ## インストール From e596eb5747fa08023bbecf34b270217e43c48642 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 14:45:26 +0200 Subject: [PATCH 696/698] New translations introduction.md (Japanese) --- guide/content/ja/guide/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/ja/guide/introduction.md b/guide/content/ja/guide/introduction.md index 2d329019da..e99c4581ee 100644 --- a/guide/content/ja/guide/introduction.md +++ b/guide/content/ja/guide/introduction.md @@ -1,6 +1,6 @@ # はじめに -Sanic is a Python 3.9+ web server and web framework that’s written to go fast. Python 3.5 で追加された async/await 構文を使用することができます。これにより、コードをノンブロッキングでスピーディーにすることができます。 +Sanic は Python 3.9+ のウェブサーバーであり、高速化のために書かれたウェブフレームワークです。 Python 3.5 で追加された async/await 構文を使用することができます。これにより、コードをノンブロッキングでスピーディーにすることができます。 .. attrs:: :class: 紹介テーブル From 9c7fd0c4b25e36508e906f036da818ffac585fc7 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 14:47:47 +0200 Subject: [PATCH 697/698] New translations getting-started.md (Chinese Simplified) --- guide/content/zh/guide/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/getting-started.md b/guide/content/zh/guide/getting-started.md index 3ca79f66b6..25d7f02d17 100644 --- a/guide/content/zh/guide/getting-started.md +++ b/guide/content/zh/guide/getting-started.md @@ -1,6 +1,6 @@ # 快速上手 -Before we begin, make sure you are running Python 3.9 or higher. Currently, Sanic is works with Python versions 3.9 – 3.13. +在我们开始之前，请确保您正在运行 Python 3.9 或更多。 目前，Sanic 正在使用 Python 版本 3.9 - 3.13。 ## 安装（Install） From e6d5f40b437b8aecd6e7757a60f8213a7a085269 Mon Sep 17 00:00:00 2001 From: Adam Hopkins Date: Thu, 2 Jan 2025 14:47:59 +0200 Subject: [PATCH 698/698] New translations introduction.md (Chinese Simplified) --- guide/content/zh/guide/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/content/zh/guide/introduction.md b/guide/content/zh/guide/introduction.md index 6d8640d6b6..cdff86ed17 100644 --- a/guide/content/zh/guide/introduction.md +++ b/guide/content/zh/guide/introduction.md @@ -1,6 +1,6 @@ # 介绍(Introduction) -Sanic is a Python 3.9+ web server and web framework that’s written to go fast. 它允许使用 Python3.5 中添加的 async/await 异步语法，这使得您的代码有效地避免阻塞从而达到提升响应速度的目的。 +Sanic 是 Python 3.9+ 网页服务器和网页框架，这是写得快的。 它允许使用 Python3.5 中添加的 async/await 异步语法，这使得您的代码有效地避免阻塞从而达到提升响应速度的目的。 .. attrs:: :class: introduction-table