From 4cd624c1abd0972a72a3e72aee6b1b6859c13a90 Mon Sep 17 00:00:00 2001
From: lemon24 <damian.adrian24@gmail.com>
Date: Fri, 21 Jun 2024 00:18:56 +0300
Subject: [PATCH] Recipe for adding custom request headers. #337

---
 docs/internal.rst           | 11 +++++---
 examples/custom_headers.py  | 50 +++++++++++++++++++++++++++++++++++++
 examples/parser_only.py     |  2 +-
 src/reader/_parser/_lazy.py |  2 +-
 4 files changed, 60 insertions(+), 5 deletions(-)
 create mode 100644 examples/custom_headers.py

diff --git a/docs/internal.rst b/docs/internal.rst
index 6124dc40..0bb79bf7 100644
--- a/docs/internal.rst
+++ b/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
diff --git a/examples/custom_headers.py b/examples/custom_headers.py
new file mode 100644
index 00000000..1e473bed
--- /dev/null
+++ b/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!")
diff --git a/examples/parser_only.py b/examples/parser_only.py
index 59cd4bc5..fffeb713 100644
--- a/examples/parser_only.py
+++ b/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
diff --git a/src/reader/_parser/_lazy.py b/src/reader/_parser/_lazy.py
index aeb7a104..d3e8e1a9 100644
--- a/src/reader/_parser/_lazy.py
+++ b/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.