Merge branch 'main' into develop

litestar-org · Mar 27, 2024 · c056bec · c056bec
2 parents 422a6ed + 636e917
commit c056bec
Show file tree

Hide file tree

Showing 37 changed files with 741 additions and 298 deletions.
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -1669,6 +1669,25 @@
         "code",
         "test"
       ]
+    },
+    {
+      "login": "haryle",
+      "name": "harryle",
+      "avatar_url": "https://avatars.githubusercontent.com/u/64817481?v=4",
+      "profile": "https://github.com/haryle",
+      "contributions": [
+        "code",
+        "test"
+      ]
+    },
+    {
+      "login": "ubernostrum",
+      "name": "James Bennett",
+      "avatar_url": "https://avatars.githubusercontent.com/u/12384?v=4",
+      "profile": "http://www.b-list.org/",
+      "contributions": [
+        "bug"
+      ]
     }
   ],
   "contributorsPerLine": 7,

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -6,6 +6,8 @@ on:
   push:
     branches:
       - main
+      - develop
+      - v3.0
 
 jobs:
   docs:
@@ -22,7 +24,7 @@ jobs:
       - uses: pdm-project/setup-pdm@v4
         name: Set up PDM
         with:
-          python-version: "3.11"
+          python-version: "3.12"
           allow-python-prereleases: false
           cache: true
           cache-dependency-path: |
@@ -38,9 +40,17 @@ jobs:
         run: pdm run python tools/build_docs.py docs-build
         if: github.event_name == 'release'
 
-      - name: Build dev docs
-        run: pdm run python tools/build_docs.py docs-build --version dev
-        if: github.event_name == 'push'
+      - name: Build docs (main branch)
+        run: pdm run python tools/build_docs.py docs-build --version main
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+      - name: Build docs (develop branch)
+        run: pdm run python tools/build_docs.py docs-build --version develop
+        if: github.event_name == 'push' && github.ref == 'refs/heads/develop'
+
+      - name: Build docs (v3.0 branch)
+        run: pdm run python tools/build_docs.py docs-build --version 3-dev
+        if: github.event_name == 'push' && github.ref == 'refs/heads/v3.0'
 
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -23,7 +23,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.3.2"
+    rev: "v0.3.4"
     hooks:
       - id: ruff
         args: ["--fix"]
@@ -42,7 +42,7 @@ repos:
         exclude: "test*|examples*|tools"
         args: ["--use-tuple"]
   - repo: https://github.com/ariebovenberg/slotscheck
-    rev: v0.17.3
+    rev: v0.19.0
     hooks:
       - id: slotscheck
         exclude: "test_*|docs|.github"

diff --git a/README.md b/README.md
@@ -550,6 +550,10 @@ see [the contribution guide](CONTRIBUTING.rst).
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/hugovk"><img src="https://avatars.githubusercontent.com/u/1324225?v=4?s=100" width="100px;" alt="Hugo van Kemenade"/><br /><sub><b>Hugo van Kemenade</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=hugovk" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://error418.github.io"><img src="https://avatars.githubusercontent.com/u/7716544?v=4?s=100" width="100px;" alt="Michael Gerbig"/><br /><sub><b>Michael Gerbig</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=error418" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/crisog"><img src="https://avatars.githubusercontent.com/u/40803711?v=4?s=100" width="100px;" alt="CrisOG"/><br /><sub><b>CrisOG</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/issues?q=author%3Acrisog" title="Bug reports">🐛</a> <a href="https://github.com/litestar-org/litestar/commits?author=crisog" title="Code">💻</a> <a href="https://github.com/litestar-org/litestar/commits?author=crisog" title="Tests">⚠️</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/haryle"><img src="https://avatars.githubusercontent.com/u/64817481?v=4?s=100" width="100px;" alt="harryle"/><br /><sub><b>harryle</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/commits?author=haryle" title="Code">💻</a> <a href="https://github.com/litestar-org/litestar/commits?author=haryle" title="Tests">⚠️</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.b-list.org/"><img src="https://avatars.githubusercontent.com/u/12384?v=4?s=100" width="100px;" alt="James Bennett"/><br /><sub><b>James Bennett</b></sub></a><br /><a href="https://github.com/litestar-org/litestar/issues?q=author%3Aubernostrum" title="Bug reports">🐛</a></td>
     </tr>
   </tbody>
 </table>

diff --git a/docs/_static/versions.json b/docs/_static/versions.json
@@ -1 +1 @@
-{ "versions": ["1", "2", "dev"], "latest": "2" }
+{ "versions": ["1", "2", "main", "develop", "3-dev"], "latest": "2" }
diff --git a/docs/examples/testing/test_health_check_async.py b/docs/examples/testing/test_health_check_async.py
@@ -1,3 +1,5 @@
+from typing import AsyncIterator
+
 import pytest
 
 from litestar import Litestar, MediaType, get
@@ -21,12 +23,12 @@ async def test_health_check() -> None:
 
 
 @pytest.fixture(scope="function")
-def test_client() -> AsyncTestClient:
-    return AsyncTestClient(app=app)
+async def test_client() -> AsyncIterator[AsyncTestClient[Litestar]]:
+    async with AsyncTestClient(app=app) as client:
+        yield client
 
 
-async def test_health_check_with_fixture(test_client: AsyncTestClient) -> None:
-    async with test_client as client:
-        response = await client.get("/health-check")
-        assert response.status_code == HTTP_200_OK
-        assert response.text == "healthy"
+async def test_health_check_with_fixture(test_client: AsyncTestClient[Litestar]) -> None:
+    response = await test_client.get("/health-check")
+    assert response.status_code == HTTP_200_OK
+    assert response.text == "healthy"
diff --git a/docs/examples/testing/test_health_check_sync.py b/docs/examples/testing/test_health_check_sync.py
@@ -1,3 +1,5 @@
+from typing import Iterator
+
 import pytest
 
 from litestar import Litestar, MediaType, get
@@ -21,12 +23,12 @@ def test_health_check() -> None:
 
 
 @pytest.fixture(scope="function")
-def test_client() -> TestClient:
-    return TestClient(app=app)
+def test_client() -> Iterator[TestClient[Litestar]]:
+    with TestClient(app=app) as client:
+        yield client
 
 
-def test_health_check_with_fixture(test_client: TestClient) -> None:
-    with test_client as client:
-        response = client.get("/health-check")
-        assert response.status_code == HTTP_200_OK
-        assert response.text == "healthy"
+def test_health_check_with_fixture(test_client: TestClient[Litestar]) -> None:
+    response = test_client.get("/health-check")
+    assert response.status_code == HTTP_200_OK
+    assert response.text == "healthy"
diff --git a/docs/release-notes/changelog.rst b/docs/release-notes/changelog.rst
@@ -3,6 +3,121 @@
 2.x Changelog
 =============
 
+.. changelog:: 2.7.1
+    :date: 2024-03-22
+
+    .. change:: add default encoders for `Enums` and `EnumMeta`
+        :type: bugfix
+        :pr: 3193
+
+        This addresses an issue when serializing ``Enums`` that was reported in discord.
+
+    .. change:: replace TestClient.__enter__ return type with Self
+        :type: bugfix
+        :pr: 3194
+
+        ``TestClient.__enter__`` and ``AsyncTestClient.__enter__`` return ``Self``.
+        If you inherit ``TestClient``, its ``__enter__`` method should return derived class's instance
+        unless override the method. ``Self`` is a more flexible return type.
+
+    .. change:: use the full path for fetching openapi.json
+        :type: bugfix
+        :pr: 3196
+        :issue: 3047
+
+        This specifies the ``spec-url`` and ``apiDescriptionUrl`` of Rapidoc, and Stoplight Elements as absolute
+        paths relative to the root of the site.
+
+        This ensures that both of the send the request for the JSON of the OpenAPI schema to the right endpoint.
+
+    .. change:: JSON schema ``examples`` were OpenAPI formatted
+        :type: bugfix
+        :pr: 3224
+        :issue: 2849
+
+        The generated ``examples`` in *JSON schema* objects were formatted as:
+
+        .. code-block:: json
+
+            "examples": {
+              "some-id": {
+                "description": "Lorem ipsum",
+                "value": "the real beef"
+              }
+           }
+
+        However, above is OpenAPI example format, and must not be used in JSON schema
+        objects. Schema objects follow different formatting:
+
+        .. code-block:: json
+
+            "examples": [
+              "the real beef"
+           ]
+
+        * Explained in `APIs You Won't Hate blog post <https://medium.com/apis-you-wont-hate/openapi-v3-1-and-json-schema-2019-09-6862cf3db959>`_.
+        * `Schema objects spec <https://spec.openapis.org/oas/v3.1.0#schema-object>`_
+        * `OpenAPI example format spec <https://spec.openapis.org/oas/v3.1.0#example-object>`_.
+
+        This is referenced at least from parameters, media types and components.
+
+        The technical change here is to define ``Schema.examples`` as ``list[Any]`` instead
+        of ``list[Example]``. Examples can and must still be defined as ``list[Example]``
+        for OpenAPI objects (e.g. ``Parameter``, ``Body``) but for JSON schema ``examples``
+        the code now internally generates/converts ``list[Any]`` format instead.
+
+        Extra confusion here comes from the OpenAPI 3.0 vs OpenAPI 3.1 difference.
+        OpenAPI 3.0 only allowed ``example`` (singular) field in schema objects.
+        OpenAPI 3.1 supports the full JSON schema 2020-12 spec and so ``examples`` array
+        in schema objects.
+
+        Both ``example`` and ``examples`` seem to be supported, though the former is marked
+        as deprecated in the latest specs.
+
+        This can be tested over at https://editor-next.swagger.io by loading up the
+        OpenAPI 3.1 Pet store example. Then add ``examples`` in ``components.schemas.Pet``
+        using the both ways and see the Swagger UI only render the example once it's
+        properly formatted (it ignores is otherwise).
+
+    .. change:: queue_listener handler for Python >= 3.12
+        :type: bugfix
+        :pr: 3185
+        :issue: 2954
+
+        - Fix the ``queue_listener`` handler for Python 3.12
+
+        Python 3.12 introduced a new way to configure ``QueueHandler`` and ``QueueListener`` via
+        ``logging.config.dictConfig()``. As described in the
+        `logging documentation <https://docs.python.org/3/library/logging.config.html#configuring-queuehandler-and-queuelistener>`_.
+
+        The listener still needs to be started & stopped, as previously.
+        To do so, we've introduced ``LoggingQueueListener``.
+
+        And as stated in the doc:
+        * Any custom queue handler and listener classes will need to be defined with the same initialization signatures
+        as `QueueHandler <https://docs.python.org/3/library/logging.handlers.html#logging.handlers.QueueHandler>`_ and
+        `QueueListener <https://docs.python.org/3/library/logging.handlers.html#logging.handlers.QueueListener>`_.
+
+    .. change:: extend openapi meta collected from domain models
+        :type: bugfix
+        :pr: 3237
+        :issue: 3232
+
+        :class:`~litestar.typing.FieldDefinition` s pack any OpenAPI metadata onto a ``KwargDefinition`` instance when
+        types are parsed from domain models.
+
+        When we produce a DTO type, we transfer this meta from the `KwargDefinition` to a `msgspec.Meta` instance,
+        however so far this has only included constraints, not attributes such as descriptions, examples and title.
+
+        This change ensures that we transfer the openapi meta for the complete intersection of fields that exist on b
+        oth `KwargDefinition` and `Meta`.
+
+    .. change:: kwarg ambiguity exc msg for path params
+        :type: bugfix
+        :pr: 3261
+
+        Fixes the way we construct the exception message when there is a kwarg ambiguity detected for path parameters.
+
 .. changelog:: 2.7.0
     :date: 2024-03-10
 
@@ -19,8 +134,10 @@
         :pr: 3176
 
         Fix an issue with SSE where JavaScript clients fail to receive an event without data.
-        The `spec <https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream>`_ is not clear in whether or not an event without data is ok.
-        Considering the EventSource "client" is not ok with it, and that it's so easy DX-wise to make the mistake not explicitly sending it, this change fixes it by defaulting to the empty-string
+        The `spec <https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream>`_ is
+        not clear in whether or not an event without data is ok.
+        Considering the EventSource "client" is not ok with it, and that it's so easy DX-wise to make the mistake not
+        explicitly sending it, this change fixes it by defaulting to the empty-string
 
     .. change:: Support ``ResponseSpec(..., examples=[...])``
         :type: feature
@@ -54,7 +171,7 @@
         :pr: 3096
         :issue: 3088
 
-        Automatically encode responses with media type of the form "application/<something>+json" as json.
+        Automatically encode responses with media type of the form ``application/<something>+json`` as json.
 
     .. change:: Allow reusable ``Router`` instances
         :type: feature
@@ -64,7 +181,7 @@
         It was not possible to re-attach a router instance once it was attached. This
         makes that possible.
 
-        The router instance now gets deecopied when it's registered to another router.
+        The router instance now gets deepcopied when it's registered to another router.
 
         The application startup performance gets a hit here, but the same approach is
         already used for controllers and handlers, so this only harmonizes the

diff --git a/docs/usage/applications.rst b/docs/usage/applications.rst
@@ -264,10 +264,13 @@ Parameters that support layering are:
 * :ref:`include_in_schema <usage/openapi/schema_generation:configuring schema generation on a route handler>`
 * :doc:`middleware </usage/middleware/index>`
 * :ref:`opt <handler_opts>`
+* :ref:`request_class <usage/requests:custom request>`
 * :ref:`response_class <usage/responses:custom responses>`
 * :ref:`response_cookies <usage/responses:setting response cookies>`
 * :ref:`response_headers <usage/responses:setting response headers>`
 * :doc:`return_dto </usage/dto/0-basic-use>`
 * ``security``
 * ``tags``
+* ``type_decoders``
 * ``type_encoders``
+* :ref:`websocket_class <usage/websockets:custom websocket>`