Skip to content

Commit

Permalink
Merge branch '1026-add-messsagepack-support' of https://github.com/ar…
Browse files Browse the repository at this point in the history
…thurprioli/falcon into 1026-add-messsagepack-support
  • Loading branch information
arthurprioli committed Nov 20, 2024
2 parents 918ba30 + 4db15eb commit ef7a39d
Show file tree
Hide file tree
Showing 16 changed files with 619 additions and 144 deletions.
98 changes: 48 additions & 50 deletions .github/workflows/cibuildwheel.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,54 @@ jobs:
name: cibw-sdist
path: dist/falcon-*

publish-sdist:
name: publish-sdist
needs:
- build-sdist
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 2

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Download artifacts
uses: actions/download-artifact@v4
with:
pattern: cibw-sdist
path: dist
merge-multiple: true

- name: Check collected artifacts
run: |
tools/check_dist.py ${{ github.event_name == 'release' && format('-r {0}', github.ref) || '' }}
- name: Upload sdist to release
uses: AButler/[email protected]
if: github.event_name == 'release'
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
files: 'dist/*.tar.gz'

- name: Publish sdist and pure-Python wheel to TestPyPI
uses: pypa/gh-action-pypi-publish@release/v1
if: github.event_name == 'workflow_dispatch'
with:
password: ${{ secrets.TEST_PYPI_TOKEN }}
repository-url: https://test.pypi.org/legacy/

- name: Publish sdist and pure-Python wheel to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
if: github.event_name == 'release'
with:
password: ${{ secrets.PYPI_TOKEN }}

build-wheels:
name: ${{ matrix.python }}-${{ matrix.platform.name }}
needs: build-sdist
Expand Down Expand Up @@ -123,59 +171,9 @@ jobs:
name: cibw-wheel-${{ matrix.python }}-${{ matrix.platform.name }}
path: wheelhouse/falcon-*.whl

publish-sdist:
name: publish-sdist
needs:
- build-sdist
- build-wheels
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 2

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Download artifacts
uses: actions/download-artifact@v4
with:
pattern: cibw-sdist
path: dist
merge-multiple: true

- name: Check collected artifacts
run: |
tools/check_dist.py ${{ github.event_name == 'release' && format('-r {0}', github.ref) || '' }}
- name: Upload sdist to release
uses: AButler/[email protected]
if: github.event_name == 'release'
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
files: 'dist/*.tar.gz'

- name: Publish sdist and pure-Python wheel to TestPyPI
uses: pypa/gh-action-pypi-publish@release/v1
if: github.event_name == 'workflow_dispatch'
with:
password: ${{ secrets.TEST_PYPI_TOKEN }}
repository-url: https://test.pypi.org/legacy/

- name: Publish sdist and pure-Python wheel to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
if: github.event_name == 'release'
with:
password: ${{ secrets.PYPI_TOKEN }}

publish-wheels:
name: publish-wheels
needs:
- build-sdist
- build-wheels
- publish-sdist
runs-on: ubuntu-latest
Expand Down
5 changes: 4 additions & 1 deletion .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,11 @@ build:
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py

# Optionally build your docs in additional formats such as PDF and ePub
formats:
- pdf
- pdf

# We recommend specifying your dependencies to enable reproducible builds:
# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
Expand Down
3 changes: 3 additions & 0 deletions AUTHORS
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,9 @@ listed below by date of first contribution:
* Agustin Arce (aarcex3)
* Christian Grossmüller (chgad)
* Sai Prathik R (prathik2401)
* Akshay Awate (AkshayAwate)
* Jasper Spaans (jap)
* Alessandro Chitarrini (chitvs)

(et al.)

Expand Down
1 change: 1 addition & 0 deletions docs/api/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,4 @@ Framework Reference
inspect
util
testing
typing
83 changes: 83 additions & 0 deletions docs/api/typing.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
Typing
======

Type checking support was introduced in version 4.0. While most of the library is
now typed, further type annotations may be added throughout the 4.x release cycle.
To improve them, we may introduce changes to the typing that do not affect
runtime behavior, but may surface new or different errors with type checkers.

.. role:: python(code)
:language: python

.. note::
All undocumented type aliases coming from ``falcon._typing`` are considered
private to the framework itself, and not meant for annotating applications
using Falcon. To that end, it is advisable to only use classes from the
public interface, and public aliases from :mod:`falcon.typing`, e.g.:

.. code-block:: python
class MyResource:
def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:
resp.media = {'message': 'Hello, World!'}
If you still decide to reuse the private aliases anyway, they should
preferably be imported inside :python:`if TYPE_CHECKING:` blocks in order
to avoid possible runtime errors after an update.
Also, make sure to :ref:`let us know <chat>` which essential aliases are
missing from the public interface!


Known Limitations
-----------------

Falcon's emphasis on flexibility and performance presents certain
challenges when it comes to adding type annotations to the existing code base.

One notable limitation involves using custom :class:`~falcon.Request` and/or
:class:`~falcon.Response` types in callbacks that are passed back
to the framework, such as when adding an
:meth:`error handler <falcon.App.add_error_handler>`.
For instance, the following application might unexpectedly not pass type
checking:

.. code-block:: python
from typing import Any
from falcon import App, HTTPInternalServerError, Request, Response
class MyRequest(Request):
...
def handle_os_error(req: MyRequest, resp: Response, ex: Exception,
params: dict[str, Any]) -> None:
raise HTTPInternalServerError(title='OS error!') from ex
app = App(request_type=MyRequest)
app.add_error_handler(OSError, handle_os_error)
(We are working on addressing this limitation at the time of writing --
please see the following GitHub issue for the progress, and possible solutions:
`#2372 <https://github.com/falconry/falcon/issues/2372>`__.)

Another known inconsistency is the typing of the
:class:`converter interface <falcon.routing.BaseConverter>`, where certain
subclasses (such as :class:`~falcon.routing.PathConverter`) declare a different
input type than the base ``convert()`` method.
(See also the discussions and possible solutions on the GitHub issue
`#2396 <https://github.com/falconry/falcon/issues/2396>`__.)

.. important::
The above issues are only typing limitations that have no effect outside of
type checking -- applications will work just fine at runtime!


Public Type Aliases
-------------------

.. automodule:: falcon.typing
:members:
6 changes: 0 additions & 6 deletions docs/api/util.rst
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,3 @@ Other

.. autoclass:: falcon.ETag
:members:

Type Aliases
------------

.. automodule:: falcon.typing
:members:
38 changes: 38 additions & 0 deletions docs/changes/4.0.2.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
Changelog for Falcon 4.0.2
==========================

Summary
-------

This is a minor point release to fix some missed re-exports for type checkers.
In addition, we have also included a couple of documentation improvements.


Fixed
-----

- Running Mypy on code that uses parts of ``falcon.testing``
would previously lead to errors like::

Name "falcon.testing.TestClient" is not defined

This has been fixed by explicitly exporting the names that are
imported into the ``falcon.testing`` namespace. (`#2387 <https://github.com/falconry/falcon/issues/2387>`__)


Misc
----

- The printable PDF version of our documentation was enabled on Read the Docs. (`#2365 <https://github.com/falconry/falcon/issues/2365>`__)


Contributors to this Release
----------------------------

Many thanks to those who contributed to this bugfix release:

- `AkshayAwate <https://github.com/AkshayAwate>`__
- `CaselIT <https://github.com/CaselIT>`__
- `chitvs <https://github.com/chitvs>`__
- `jap <https://github.com/jap>`__
- `vytas7 <https://github.com/vytas7>`__
4 changes: 2 additions & 2 deletions docs/changes/4.1.0.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Falcon 4.1 is in development. The progress is tracked via the
on GitHub.


Changes to Supported Platforms
------------------------------
.. Changes to Supported Platforms
.. ------------------------------
.. NOTE(vytas): No changes to the supported platforms (yet).
Expand Down
1 change: 1 addition & 0 deletions docs/changes/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ Changelogs
.. toctree::

4.1.0 <4.1.0>
4.0.2 <4.0.2>
4.0.1 <4.0.1>
4.0.0 <4.0.0>
3.1.3 <3.1.3>
Expand Down
42 changes: 42 additions & 0 deletions docs/user/faq.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1347,3 +1347,45 @@ Alternatively, you can set the Cookie header directly as demonstrated in this ve
To include multiple values, simply use ``"; "`` to separate each name-value
pair. For example, if you were to pass ``{'Cookie': 'xxx=yyy; hello=world'}``,
you would get ``{'cookies': {'xxx': 'yyy', 'hello': 'world'}}``.

Why do I see no error tracebacks in my ASGI application?
--------------------------------------------------------

When using Falcon with an ASGI server like Uvicorn,
you might notice that server errors do not include any traceback by default.
This behavior differs from WSGI, where the PEP-3333 specification defines the
`wsgi.errors <https://peps.python.org/pep-3333/#environ-variables>`__ stream
(which Falcon utilizes to log unhandled
:class:`internal server errors <falcon.HTTPInternalServerError>`).

Since there is no standardized way to log errors back to the ASGI server,
the framework simply opts to log them using the ``falcon``
:class:`logger <logging.Logger>`.

The easiest way to get started is configuring the root logger via
:func:`logging.basicConfig`:

.. code:: python
import logging
import falcon
import falcon.asgi
logging.basicConfig(
format="%(asctime)s [%(levelname)s] %(message)s", level=logging.INFO)
class FaultyResource:
async def on_get(self, req, resp):
raise ValueError('foo')
app = falcon.asgi.App()
app.add_route('/things', FaultyResource())
By adding the above logging configuration, you should now see tracebacks logged
to :any:`stderr <sys.stderr>` when accessing ``/things``.

For additional details on this topic,
please refer to :ref:`debugging_asgi_applications`.
Loading

0 comments on commit ef7a39d

Please sign in to comment.