docs: apply assorted tweaks before 4.0.0b1 (#2357)

* docs: move frontpage quote example to a separate file

* chore: actually add the new file

* docs(REAME): disable cythonization of editable installs

* docs: remove an empty line from quote.py

* docs: fix a comment and add a note

* chore(changes): aggregate 4.0 contributors so far

AUTHORS

@@ -198,6 +198,7 @@ listed below by date of first contribution:
 * Dave Tapley (davetapley)
 * Agustin Arce (aarcex3)
 * Christian Grossmüller (chgad)
+* Sai Prathik R (prathik2401)
 
 (et al.)
 

CONTRIBUTING.md

@@ -37,6 +37,14 @@ $ pip install -U ruff
 $ ruff format
 ```
 
+You can also reformat your code, and apply safe ``ruff`` fixes, via the
+``reformat`` ``tox`` environment:
+
+```bash
+$ pip install -U tox
+$ tox -e reformat
+```
+
 You can check all this by running ``tox`` from within the Falcon project directory.
 Your environment must be based on CPython 3.10, 3.11, 3.12 or 3.13:
 

README.rst

@@ -278,7 +278,7 @@ available to your app without having to reinstall the package:
 .. code:: bash
 
     $ cd falcon
-    $ pip install -e .
+    $ FALCON_DISABLE_CYTHON=Y pip install -e .
 
 You can manually test changes to the Falcon framework by switching to the
 directory of the cloned repo and then running pytest:

docs/changes/4.0.0.rst

@@ -101,7 +101,9 @@ Many thanks to all of our talented and stylish contributors for this release!
 - `mgorny <https://github.com/mgorny>`__
 - `mihaitodor <https://github.com/mihaitodor>`__
 - `MRLab12 <https://github.com/MRLab12>`__
+- `myusko <https://github.com/myusko>`__
 - `nfsec <https://github.com/nfsec>`__
+- `prathik2401 <https://github.com/prathik2401>`__
 - `RioAtHome <https://github.com/RioAtHome>`__
 - `TigreModerata <https://github.com/TigreModerata>`__
 - `vgerak <https://github.com/vgerak>`__

docs/index.rst

@@ -16,26 +16,8 @@ We like to think of Falcon as the *Dieter Rams* of web frameworks. Falcon
 encourages the REST architectural style, and tries to do as little as possible
 while remaining highly effective.
 
-.. code:: python
-
-    import falcon
-
-    class QuoteResource:
-        def on_get(self, req, resp):
-            """Handles GET requests"""
-            quote = {
-                'quote': (
-                    "I've always been more interested in "
-                    "the future than in the past."
-                ),
-                'author': 'Grace Hopper'
-            }
-
-            resp.media = quote
-
-
-    app = falcon.App()
-    app.add_route('/quote', QuoteResource())
+.. literalinclude:: ../examples/quote.py
+    :language: python
 
 For a fully working example, check out the :ref:`quickstart`.
 

examples/quote.py

@@ -0,0 +1,14 @@
+import falcon
+
+
+class QuoteResource:
+    def on_get(self, req: falcon.Request, resp: falcon.Response) -> None:
+        """Handle GET requests."""
+        resp.media = {
+            'quote': "I've always been more interested in the future than in the past.",
+            'author': 'Grace Hopper',
+        }
+
+
+app = falcon.App()
+app.add_route('/quote', QuoteResource())

falcon/util/mediatypes.py

@@ -216,8 +216,8 @@ def match_score(self, media_type: _MediaType) -> Tuple[int, int, int, int, float
 
 # PERF(vytas): It is possible to cache a classmethod too, but the invocation is
 #   less efficient, especially in the case of a cache hit.
-# NOTE(vytas): Also, if we decide to make these classes public, we either need
-#   to keep these cached parsers private, or to make sure we use frozen classes.
+# NOTE(vytas): Also, if we decide to make these classes public, we need to keep
+#   these cached parsers private.
 _parse_media_type = functools.lru_cache(_MediaType.parse)
 _parse_media_range = functools.lru_cache(_MediaRange.parse)
 

tests/test_examples.py

@@ -13,6 +13,18 @@
 import falcon.testing as testing
 
 
+def test_quote(util):
+    quote = util.load_module('examples/quote.py')
+
+    resp = testing.simulate_get(quote.app, '/quote')
+
+    assert resp.status_code == 200
+    assert resp.json == {
+        'author': 'Grace Hopper',
+        'quote': "I've always been more interested in the future than in the past.",
+    }
+
+
 def test_things(asgi, util):
     suffix = '_asgi' if asgi else ''
     things = util.load_module(f'examples/things{suffix}.py')