Deploying to gh-pages from @ litestar-org/litestar@25f57a6 🚀

litestar-org · Jan 20, 2025 · 4cfb847 · 4cfb847
1 parent 56d9025
commit 4cfb847
Show file tree

Hide file tree

Showing 529 changed files with 463,342 additions and 0 deletions.
diff --git a/3962/.buildinfo b/3962/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 40249242fdd1c6895fda4ca83f4ca6eb
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/3962/_downloads/52dc67503af9349c016af0f44cbbfc1d/us_state_lookup.json b/3962/_downloads/52dc67503af9349c016af0f44cbbfc1d/us_state_lookup.json
@@ -0,0 +1,218 @@
+[
+  {
+    "name": "Alabama",
+    "abbreviation": "AL"
+  },
+  {
+    "name": "Alaska",
+    "abbreviation": "AK"
+  },
+  {
+    "name": "Arizona",
+    "abbreviation": "AZ"
+  },
+  {
+    "name": "Arkansas",
+    "abbreviation": "AR"
+  },
+  {
+    "name": "California",
+    "abbreviation": "CA"
+  },
+  {
+    "name": "Colorado",
+    "abbreviation": "CO"
+  },
+  {
+    "name": "Connecticut",
+    "abbreviation": "CT"
+  },
+  {
+    "name": "Delaware",
+    "abbreviation": "DE"
+  },
+  {
+    "name": "District Of Columbia",
+    "abbreviation": "DC"
+  },
+  {
+    "name": "Florida",
+    "abbreviation": "FL"
+  },
+  {
+    "name": "Georgia",
+    "abbreviation": "GA"
+  },
+  {
+    "name": "Guam",
+    "abbreviation": "GU"
+  },
+  {
+    "name": "Hawaii",
+    "abbreviation": "HI"
+  },
+  {
+    "name": "Idaho",
+    "abbreviation": "ID"
+  },
+  {
+    "name": "Illinois",
+    "abbreviation": "IL"
+  },
+  {
+    "name": "Indiana",
+    "abbreviation": "IN"
+  },
+  {
+    "name": "Iowa",
+    "abbreviation": "IA"
+  },
+  {
+    "name": "Kansas",
+    "abbreviation": "KS"
+  },
+  {
+    "name": "Kentucky",
+    "abbreviation": "KY"
+  },
+  {
+    "name": "Louisiana",
+    "abbreviation": "LA"
+  },
+  {
+    "name": "Maine",
+    "abbreviation": "ME"
+  },
+  {
+    "name": "Maryland",
+    "abbreviation": "MD"
+  },
+  {
+    "name": "Massachusetts",
+    "abbreviation": "MA"
+  },
+  {
+    "name": "Michigan",
+    "abbreviation": "MI"
+  },
+  {
+    "name": "Minnesota",
+    "abbreviation": "MN"
+  },
+  {
+    "name": "Mississippi",
+    "abbreviation": "MS"
+  },
+  {
+    "name": "Missouri",
+    "abbreviation": "MO"
+  },
+  {
+    "name": "Montana",
+    "abbreviation": "MT"
+  },
+  {
+    "name": "Nebraska",
+    "abbreviation": "NE"
+  },
+  {
+    "name": "Nevada",
+    "abbreviation": "NV"
+  },
+  {
+    "name": "New Hampshire",
+    "abbreviation": "NH"
+  },
+  {
+    "name": "New Jersey",
+    "abbreviation": "NJ"
+  },
+  {
+    "name": "New Mexico",
+    "abbreviation": "NM"
+  },
+  {
+    "name": "New York",
+    "abbreviation": "NY"
+  },
+  {
+    "name": "North Carolina",
+    "abbreviation": "NC"
+  },
+  {
+    "name": "North Dakota",
+    "abbreviation": "ND"
+  },
+  {
+    "name": "Ohio",
+    "abbreviation": "OH"
+  },
+  {
+    "name": "Oklahoma",
+    "abbreviation": "OK"
+  },
+  {
+    "name": "Oregon",
+    "abbreviation": "OR"
+  },
+  {
+    "name": "Palau",
+    "abbreviation": "PW"
+  },
+  {
+    "name": "Pennsylvania",
+    "abbreviation": "PA"
+  },
+  {
+    "name": "Puerto Rico",
+    "abbreviation": "PR"
+  },
+  {
+    "name": "Rhode Island",
+    "abbreviation": "RI"
+  },
+  {
+    "name": "South Carolina",
+    "abbreviation": "SC"
+  },
+  {
+    "name": "South Dakota",
+    "abbreviation": "SD"
+  },
+  {
+    "name": "Tennessee",
+    "abbreviation": "TN"
+  },
+  {
+    "name": "Texas",
+    "abbreviation": "TX"
+  },
+  {
+    "name": "Utah",
+    "abbreviation": "UT"
+  },
+  {
+    "name": "Vermont",
+    "abbreviation": "VT"
+  },
+  {
+    "name": "Virginia",
+    "abbreviation": "VA"
+  },
+  {
+    "name": "Washington",
+    "abbreviation": "WA"
+  },
+  {
+    "name": "West Virginia",
+    "abbreviation": "WV"
+  },
+  {
+    "name": "Wisconsin",
+    "abbreviation": "WI"
+  },
+  {
+    "name": "Wyoming",
+    "abbreviation": "WY"
+  }
+]
diff --git a/3962/_images/done-john-2.png b/3962/_images/done-john-2.png
diff --git a/3962/_images/done-john.png b/3962/_images/done-john.png
diff --git a/3962/_images/dto_data.png b/3962/_images/dto_data.png
diff --git a/3962/_images/exception-handlers.jpg b/3962/_images/exception-handlers.jpg
diff --git a/3962/_images/explicit_field_renaming.png b/3962/_images/explicit_field_renaming.png
diff --git a/3962/_images/field_renaming_strategy.png b/3962/_images/field_renaming_strategy.png
diff --git a/3962/_images/get_todo_list.png b/3962/_images/get_todo_list.png
diff --git a/3962/_images/hello_world.png b/3962/_images/hello_world.png
diff --git a/3962/_images/initial_pattern.png b/3962/_images/initial_pattern.png
diff --git a/3962/_images/max_nested_depth.png b/3962/_images/max_nested_depth.png
diff --git a/3962/_images/missing-query.png b/3962/_images/missing-query.png
diff --git a/3962/_images/nested_collection_exclude.png b/3962/_images/nested_collection_exclude.png
diff --git a/3962/_images/nested_exclude.png b/3962/_images/nested_exclude.png
diff --git a/3962/_images/patch_handlers.png b/3962/_images/patch_handlers.png
diff --git a/3962/_images/put_handlers.png b/3962/_images/put_handlers.png
diff --git a/3962/_images/pycharm-config-cli.png b/3962/_images/pycharm-config-cli.png
diff --git a/3962/_images/pycharm-config-uvicorn.png b/3962/_images/pycharm-config-uvicorn.png
diff --git a/3962/_images/pycharm-debug.png b/3962/_images/pycharm-debug.png
diff --git a/3962/_images/read_only_fields_error.png b/3962/_images/read_only_fields_error.png
diff --git a/3962/_images/rps_dependency-injection.svg b/3962/_images/rps_dependency-injection.svg
diff --git a/3962/_images/rps_files.svg b/3962/_images/rps_files.svg
diff --git a/3962/_images/rps_json.svg b/3962/_images/rps_json.svg
diff --git a/3962/_images/rps_params.svg b/3962/_images/rps_params.svg
diff --git a/3962/_images/rps_plaintext.svg b/3962/_images/rps_plaintext.svg
diff --git a/3962/_images/rps_serialization.svg b/3962/_images/rps_serialization.svg
diff --git a/3962/_images/simple_exclude.png b/3962/_images/simple_exclude.png
diff --git a/3962/_images/simple_receive_data.png b/3962/_images/simple_receive_data.png
diff --git a/3962/_images/swagger-dataclass-bad-body.png b/3962/_images/swagger-dataclass-bad-body.png
diff --git a/3962/_images/swagger-dict-vs-dataclass.png b/3962/_images/swagger-dict-vs-dataclass.png
diff --git a/3962/_images/swagger-get-example-request.png b/3962/_images/swagger-get-example-request.png
diff --git a/3962/_images/swagger-get.png b/3962/_images/swagger-get.png
diff --git a/3962/_images/swagger-post-dict-response.png b/3962/_images/swagger-post-dict-response.png
diff --git a/3962/_images/template_engine_callable.png b/3962/_images/template_engine_callable.png
diff --git a/3962/_images/todos-done.png b/3962/_images/todos-done.png
diff --git a/3962/_images/todos-not-done.png b/3962/_images/todos-not-done.png
diff --git a/3962/_images/vs-code-add-config.png b/3962/_images/vs-code-add-config.png
diff --git a/3962/_images/vs-code-config-litestar.png b/3962/_images/vs-code-config-litestar.png
diff --git a/3962/_images/vs-code-debug.png b/3962/_images/vs-code-debug.png
diff --git a/3962/_images/vs-code-select-config.png b/3962/_images/vs-code-select-config.png
diff --git a/3962/_sources/admonitions/sync-to-thread-info.rst.txt b/3962/_sources/admonitions/sync-to-thread-info.rst.txt
@@ -0,0 +1,21 @@
+.. admonition:: Synchronous and asynchronous callables
+    :class: important
+
+    Both synchronous and asynchronous callables are supported. One important aspect of
+    this is that using a synchronous function which perform blocking operations, such
+    as I/O or computationally intensive tasks, can potentially block the main thread
+    running the event loop, and in turn block the whole application.
+
+    To mitigate this, the ``sync_to_thread`` parameter can be set to ``True``, which
+    will result in the function being run in a thread pool.
+
+    If a synchronous function is non-blocking, setting ``sync_to_thread`` to ``False``
+    will tell Litestar that the user is sure about its behavior
+    and the function can be treated as non-blocking.
+
+    If a synchronous function is passed, without setting an explicit ``sync_to_thread``
+    value, a warning will be raised.
+
+    .. seealso::
+
+        :doc:`/topics/sync-vs-async`
diff --git a/3962/_sources/benchmarks.rst.txt b/3962/_sources/benchmarks.rst.txt
@@ -0,0 +1,122 @@
+Benchmarks
+==========
+
+Methodology
+-----------
+
+- Benchmarking is done using the
+  `bombardier <https://github.com/codesenberg/bombardier>`__ benchmarking tool.
+- Benchmarks are run on a dedicated machine, with a base Debian 11 installation.
+- Each framework is contained within its own docker container, running on a dedicated
+  CPU core (using the ``cset shield`` command and the ``--cpuset-cpus`` option for
+  docker)
+- Tests for the frameworks are written to make them as comparable as possible while
+  completing the same tasks (you can see them
+  `here <https://github.com/litestar-org/api-performance-tests/tree/main/frameworks>`__)
+- Each application is run using `uvicorn <https://www.uvicorn.org/>`__ with
+  **one worker** and `uvloop <https://uvloop.readthedocs.io/>`__
+- Test data has been randomly generated and is being imported from a shared module
+- All frameworks are used with their "stock" configuration, i.e. without applying any
+  additional optimizations. All tests have been written according to the respective
+  official documentation, applying the practices shown there
+
+Results
+-------
+
+..  note::
+    If a result is missing for a specific framework that means either
+
+    - The framework does not support this functionality (this will be mentioned in the
+      test description)
+    - More than 0.1% of responses were dropped
+
+JSON
+~~~~
+
+Serializing a dictionary into JSON
+
+.. figure:: /images/benchmarks/rps_json.svg
+   :alt: RPS JSON
+
+   RPS JSON
+
+.. note::
+    Because all frameworks are being used in their "stock" configuration, Litestar will
+    run the data through `msgspec <https://jcristharif.com/msgspec/>`_ and FastAPI
+    through `Pydantic <https://docs.pydantic.dev/latest/>`_
+
+
+Serialization
+~~~~~~~~~~~~~
+
+Serializing Pydantic models and dataclasses into JSON
+
+.. figure:: /images/benchmarks/rps_serialization.svg
+   :alt: RPS serializing Pydantic models and dataclasses into JSON
+
+   RPS serializing Pydantic models and dataclasses into JSON
+
+
+Files
+~~~~~
+
+.. figure:: /images/benchmarks/rps_files.svg
+   :alt: RPS files
+
+   RPS files
+
+.. note::
+    Synchronous file responses are not / only partially supported for Sanic and Quart
+
+
+Path and query parameter handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*All responses return “No Content”*
+
+-  No params: No path parameters
+-  Path params: Single path parameter, coerced into an integer
+-  Query params: Single query parameter, coerced into an integer
+-  Mixed params: A path and a query parameters, coerced into integers
+
+.. figure:: /images/benchmarks/rps_params.svg
+   :alt: RPS path and query parameters
+
+   RPS path and query parameters
+
+Dependency injection
+~~~~~~~~~~~~~~~~~~~~
+
+-  Resolving 3 nested synchronous dependencies
+-  Resolving 3 nested asynchronous dependencies (only supported by ``Litestar`` and ``FastAPI``)
+-  Resolving 3 nested synchronous, and 3 nested asynchronous dependencies (only supported by ``Litestar`` and ``FastAPI``)
+
+.. figure:: /images/benchmarks/rps_dependency-injection.svg
+   :alt: RPS Dependency injection
+
+   RPS Dependency injection
+
+
+.. note::
+    Dependency injection is not supported by Starlette.
+
+
+Plaintext
+~~~~~~~~~
+
+.. figure:: /images/benchmarks/rps_plaintext.svg
+   :alt: RPS Plaintext
+
+   RPS Plaintext
+
+Interpreting the results
+------------------------
+
+An interpretation of these results should be approached with caution, as is the case for nearly all benchmarks.
+A high score in a test does not necessarily translate to high performance of **your** application and **your** use case.
+For almost any test you can probably write an app that performs better or worse at a comparable task **in your scenario**.
+
+While trying to design the tests in a way that simulate somewhat realistic scenarios, they can never give an exact
+representation of how a real world application behaves and performs, where, aside from the workload, many other factors
+come into play. These tests were mainly written to be used internally for Litestar development, to help us locate and
+track performance regressions and improvements.
diff --git a/3962/_sources/contribution-guide.rst.txt b/3962/_sources/contribution-guide.rst.txt
@@ -0,0 +1,3 @@
+:orphan:
+
+.. include:: ../CONTRIBUTING.rst