Merge branch 'master' into release

Author: gi0baro

.github/workflows/tests.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.8, 3.9, '3.10', '3.11', '3.12', '3.13']
+        python-version: [3.9, '3.10', '3.11', '3.12', '3.13']
 
     services:
       postgres:
@@ -49,7 +49,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.8, 3.9, '3.10', '3.11', '3.12', '3.13']
+        # FIXME: skipping 3.9 due to issues with `psycopg2-binary`
+        # python-version: [3.9, '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4
@@ -71,7 +73,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [3.8, 3.9, '3.10', '3.11', '3.12', '3.13']
+        python-version: [3.9, '3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4

CHANGES.md

@@ -1,6 +1,21 @@
 Emmett changelog
 ================
 
+Version 2.7
+-----------
+
+Released on April 11th 2025, codename Hopper
+
+- Dropped Python 3.8 support
+- Use RSGI spec 1.5
+- Added `Response.stream` helper
+- Added `Pipe.on_stream` method
+- Added `stream` and `StreamPipe` helpers to `tools` module
+- Added Server-Sent-Events helper to `tools.sse`
+- Made `uvloop` dependency optional
+- Removed `uvicorn` dependency extra
+- Added experimental support for `psycopg` 3 in ORM
+
 Version 2.6
 -----------
 

README.md

@@ -49,7 +49,7 @@ The *bloggy* example described in the [Tutorial](https://emmett.sh/docs/latest/t
 
 ## Status of the project
 
-Emmett is production ready and is compatible with Python 3.8 and above versions.
+Emmett is production ready and is compatible with Python 3.9 and above versions.
 
 Emmett follows a *semantic versioning* for its releases, with a `{major}.{minor}.{patch}` scheme for versions numbers, where:
 

docs/deployment.md

@@ -3,12 +3,10 @@ Deployment
 
 Depending on your setup and preferences, there are multiple ways to run Emmett applications. In this chapter, we'll try to document the most common ones.
 
-If you want to use an ASGI server not listed in this section, please refer to its documentation, remembering that your Emmett application object is the actual ASGI application (following spec version 3.0).
-
 Included server
 ---------------
 
-*Changed in version 2.5*
+*Changed in version 2.7*
 
 Emmett comes with [Granian](https://github.com/emmett-framework/granian) as its HTTP server. In order to run your application in production you can just use the included `serve` command:
 
@@ -22,35 +20,27 @@ You can inspect all the available options of the `serve` command using the `--he
 | port | 8000 | Bind port |
 | workers | 1 | Number of worker processes |
 | threads | 1 | Number of threads |
-| threading-mode | workers | Threading implementation (possible values: runtime,workers) |
+| blocking-trheads | 1 | Number of blocking threads |
+| runtime-mode | st | Runtime implementation (possible values: st,mt) |
 | interface | rsgi | Server interface (possible values: rsgi,asgi) |
 | http | auto | HTTP protocol version (possible values: auto,1,2) |
+| http-read-timeout | 10000 | HTTP read timeout (in milliseconds) |
 | ws/no-ws | ws | Enable/disable websockets support |
-| loop | auto | Loop implementation (possible values: auto,asyncio,uvloop) |
+| loop | auto | Loop implementation (possible values: auto,asyncio,rloop,uvloop) |
 | log-level | info | Logging level (possible values: debug,info,warning,error,critical) |
 | backlog | 2048 | Maximum connection queue |
+| backpressure | | Maximum number of requests to process concurrently |
 | ssl-certfile | | Path to SSL certificate file |
 | ssl-keyfile | | Path to SSL key file |
 
-Uvicorn
--------
-
-*Changed in version 2.5*
-
-In case you want to stick with a more popular option, Emmett also comes with included support for [Uvicorn](https://github.com/encode/uvicorn).
-
-You can just use the `emmett[uvicorn]` extra during installation and rely on the `uvicorn` command to serve your application.
-
-Gunicorn
---------
-
-The included server might suit most of the common demands, but whenever you need additional features, you can use [Gunicorn](https://gunicorn.org).
+Other ASGI servers
+------------------
 
-Emmett includes a Gunicorn worker class allowing you to run ASGI applications with the Emmett's environment, while also giving you Gunicorn's fully-featured process management:
+*Changed in version 2.7*
 
-    gunicorn myapp:app -w 4 -k emmett.asgi.workers.EmmettWorker
+Since an Emmett application object is also an [ASGI](https://asgi.readthedocs.io/en/latest/) application, you can serve your project with any [ASGI compliant server](https://asgi.readthedocs.io/en/latest/implementations.html#servers).
 
-This allows you to increase or decrease the number of worker processes on the fly, restart worker processes gracefully, or perform server upgrades without downtime.
+To serve your project with such servers, just refer to the specific server documentation an point it to your application object.
 
 Docker
 ------

docs/installation.md

@@ -4,7 +4,7 @@ Installation
 
 So, how do you get Emmett on your computer quickly? There are many ways you could do that, but the most kick-ass method is virtualenv, so let’s have a look at that first.
 
-You will need Python version 3.8 or higher in order to get Emmett working.
+You will need Python version 3.9 or higher in order to get Emmett working.
 
 virtualenv
 ----------

docs/orm.md

@@ -13,7 +13,7 @@ This is the list of the supported database engines, where we included the name u
 | Supported DBMS | adapter name | python driver |
 | --- | --- | --- |
 | SQLite | sqlite | |
-| PostgreSQL | postgres | psycopg2, pg8000, zxjdbc |
+| PostgreSQL | postgres | psycopg2, pyscopg 3 (experimental), pg8000, zxjdbc |
 | MySQL | mysql | pymysql, mysqldb |
 | MSSQL | mssql | pyodbc |
 | MongoDB | mongo | pymongo |

docs/pipeline.md

@@ -235,16 +235,27 @@ async def foo_monthly(start, end):
 Requests and sockets
 --------------------
 
-*Added in version 2.0*
+*Changed in version 2.7*
 
 The `Pipe`'s methods we saw until now are commonly handled by Emmett on all the routes you define, without distinction between routes handling requests and routes handling websockets.
 
-But since handling the former or the latter ones make a great difference in terms of *flow*, `Pipe`s objects also have two dedicated methods for websockets only, and in particular:
+But since handling the former or the latter ones make a great difference in terms of *flow*, `Pipe`s objects also have one dedicated method for requests and two dedicated methods for websockets only, in particular:
 
+- on\_stream
 - on\_receive
 - on\_send
 
-These two methods accepts only one argument: the message; and they will be called sequentially when receiving or sending messages. Here is an example:
+The `on_stream` method accepts no arguments and it will be called sequentially when a [response stream](./response#streaming-responses) starts. Here is an example:
+
+```python
+from emmett import response
+
+class MyStreamPipe(Pipe):
+    def on_stream(self):
+        response.headers["x-my-stream"] = "true"
+```
+
+The `on_receive` and `on_send` methods accept only one argument instead: the message. These methods will be called sequentially when receiving or sending messages. Here is an example:
 
 ```python
 class WSPipe(Pipe):
@@ -284,6 +295,7 @@ To summarize, here is the complete table of methods available on Emmett pipes:
 | pipe | pipe\_request | pipe\_ws |
 | on\_pipe\_success | | |
 | on\_pipe\_failure | | |
+| | on\_stream | |
 | | | on\_receive |
 | | | on\_send |
 
@@ -356,7 +368,7 @@ from emmett import Injector
 class DateInjector(Injector):
     namespace = "dates"
 
-    def pretty(d):
+    def pretty(self, d):
         # your prettydate code
 
 app.injectors = [DateInjector()]
@@ -376,7 +388,7 @@ You can also expose all the contents of your injectors without specifying the na
 from emmett import Injector
 
 class CommonInjector(Injector):
-    def pretty_date(d):
+    def pretty_date(self, d):
         # your prettydate code
 
 app.injectors = [CommonInjector()]

docs/response.md

@@ -114,6 +114,8 @@ async def response_aiter():
     return response.wrap_aiter(aiterator())
 ```
 
+> **Note:** both `wrap_iter` and `wrap_aiter` perform the iteration outside of the [pipeline](./pipeline). Whenever you need to stream contents and keep the pipeline open or use the global context, you should use the [stream utilities](#streaming-responses) instead.
+
 ### File responses
 
 You can produce responses from file using two different methods in Emmett:
@@ -129,10 +131,74 @@ async def file(name):
 
 @app.route("/io/<name:str>")
 async def io(name):
-    with open(f"assets/{name}", "r") as f:
+    with open(f"assets/{name}", "rb") as f:
         return response.wrap_io(f)
 ```
 
+Streaming responses
+-------------------
+
+*New in version 2.7*
+
+Emmett `Response` object provides a `stream` awaitable method in order to stream content from a generator while keeping the [pipeline](./pipeline) open:
+
+```python
+async def iterator():
+    for _ in range(3):
+        yield b"hello"
+
+@app.route()
+async def response_stream():
+    response.status = 200
+    return await response.stream(iterator())
+```
+
+### Streaming utilities
+
+On top of the `Response.stream` method, Emmett also provides a `StreamPipe` pipe and a `stream` decorator, so you can define your route function as the generator:
+
+```python
+from emmett.tools import StreamPipe, stream
+
+# the following routes behave the same
+@app.route(pipeline=[StreamPipe()])
+async def stream_1():
+    for _ in range(3):
+        yield b"hello"
+
+@app.route()
+@stream()
+async def stream_2():
+    for _ in range(3):
+        yield b"hello"
+```
+
+As you can't change the `Response` object directly in the route anymore, both `StreamPipe` and `stream` accept the same parameters to do so, specifically:
+
+| parameter | type | default |
+| --- | --- | --- |
+| status | `int` | 200 |
+| headers | `dict[str, str]` | `{}` |
+| cookies | `dict[str, Any]` | `{}` |
+
+> **Note:** while `status` will overwrite the existing value, both `headers` and `cookies` will be merged on top of the existing `Response` ones.
+
+### Server-Sent Events
+
+Emmett also provides some specific utilities to stream [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events):
+
+```python
+from emmett.tools import sse
+
+@app.route()
+@sse()
+async def sse_stream():
+    for _ in range(3):
+        yield sse.Event(data={"msg": "hello"})
+```
+
+The `sse` decorator is based on the `stream` one but already configures some headers for you, like the `content-type` and caching. You can still use the same parameters of the `stream` decorator to customise the response.
+
 Message flashing
 ----------------
 

docs/upgrading.md

@@ -13,6 +13,44 @@ Just as a remind, you can update Emmett using *pip*:
 $ pip install -U emmett
 ```
 
+Version 2.7
+-----------
+
+Emmett 2.7 introduces some changes you should be aware of, and some new features you might be interested into.
+
+This release drops support for Python 3.8.
+
+### Breaking changes
+
+#### Serve command arguments
+
+As Emmett 2.7 updates the minimum [Granian](https://github.com/emmett-framework/granian) dependency version, the previous `threading-mode` argument of the `serve` command is now moved to `runtime-mode`.
+In case you specified this argument in previous Emmett versions, please update your code using the following conversion table:
+
+| previous value | new value |
+| --- | --- |
+| `--threading-mode runtime` | `--runtime-mode mt` |
+| `--threading-mode workers` | `--runtime-mode st` |
+
+The serve command also includes some new params you might want to use. Please check the [relevant chapter](./deployment#included-server) of the documentation for more information.
+
+#### Removed uvicorn extra dependency
+
+Prior to 2.7, Emmett provided the `uvicorn` extra dependency. Given the additional work required to keep such dependency extras in sync with other projects release cycles, we no longer offer this facility.
+
+You can still use Uvicorn to serve your Emmett application, you simply need to manage that dependency yourself. See also the [deployment chapter](./deployment) of the documentation.
+
+#### Uvloop is now an optional dependency
+
+Emmett 2.7 doesn't require [uvloop](https://github.com/MagicStack/uvloop) anymore. This dependency is now optional and gated under the `uvloop` extra. If you want to keep using uvloop, you can add it to your project dependencies or switch your Emmett dependency spec to `emmett[uvloop]`.
+
+### New feautures
+
+- [RSGI](https://github.com/emmett-framework/granian/blob/master/docs/spec/RSGI.md) spec 1.5
+- Response [streaming utilities](./response#streaming-responses)
+- First class support for [Server-Sent Events](./response#server-sent-events)
+- Pipes `on_stream` [method](./pipeline#requests-and-sockets)
+
 Version 2.6
 -----------
 

emmett/__version__.py

@@ -1 +1 @@
-__version__ = "2.6.3"
+__version__ = "2.7.0"