Recipe for adding custom request headers. #337

docs/internal.rst

@@ -219,9 +219,14 @@ Type aliases
 Recipes
 -------
 
-.. include:: ../examples/parser_only.py
+.. include:: ../examples/custom_headers.py
     :start-after: """
-    :end-before: """  # docstring-end
+    :end-before: """
+.. literalinclude:: ../examples/custom_headers.py
+    :start-at: import
 
+.. include:: ../examples/parser_only.py
+    :start-after: """
+    :end-before: """
 .. literalinclude:: ../examples/parser_only.py
-    :start-after: """  # docstring-end
+    :start-at: import

examples/custom_headers.py

@@ -0,0 +1,50 @@
+"""
+Adding custom headers when retrieving feeds
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Example of adding custom request headers with :attr:`.SessionFactory.request_hooks`:
+
+.. code-block:: console
+
+    $ python examples/custom_headers.py
+    updating...
+    server: Hello, world!
+    updated!
+
+"""
+
+# fmt: off
+# flake8: noqa
+
+import http.server
+import threading
+from reader import make_reader
+
+# start a background server that logs the received header
+
+class Handler(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *_): pass
+    def do_GET(self):
+        print("server:", self.headers.get('my-header'))
+        self.send_error(304)
+
+server = http.server.HTTPServer(('localhost', 8080), Handler)
+threading.Thread(target=server.handle_request).start()
+
+# create a reader object
+
+reader = make_reader(':memory:')
+reader.add_feed('http://localhost:8080')
+
+# set up a hook that adds the header to each request
+
+def hook(session, request, **kwargs):
+    request.headers.setdefault('my-header', 'Hello, world!')
+
+reader._parser.session_factory.request_hooks.append(hook)
+
+# updating the feed sends the modified request to the server
+
+print("updating...")
+reader.update_feeds()
+print("updated!")

examples/parser_only.py

@@ -11,7 +11,7 @@
     death and gravity
     Has your password been pwned? Or, how I almost failed to search a 37 GB text file in under 1 millisecond (in Python)
 
-"""  # docstring-end
+"""
 
 import asyncio
 import io

src/reader/_parser/_lazy.py

@@ -72,7 +72,7 @@ def __init__(self) -> None:
         self.parsers_by_mime_type: dict[str, list[tuple[float, ParserType[Any]]]] = {}
         self.parsers_by_url: dict[str, ParserType[Any]] = {}
 
-        #: :class:`~reader._requests_utils.SessionFactory`
+        #: :class:`~reader._parser.requests.SessionFactory`
         #: used to create Requests sessions for retrieving feeds.
         #:
         #: Plugins may add request or response hooks to this.