Update parser API docs. #307

lemon24 · Sep 2, 2024 · c51d8fb · c51d8fb
1 parent 182902c
commit c51d8fb
Show file tree

Hide file tree

Showing 4 changed files with 44 additions and 16 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -11,6 +11,12 @@ Version 3.15
 
 Unreleased
 
+* Update the parser API to expose HTTP information to the updater. (:issue:`307`)
+
+  .. note::
+
+    The (unstable) :class:`.RetrieverType` protocol used by custom retrievers changed.
+
 
 Version 3.14
 ------------

diff --git a/docs/dev.rst b/docs/dev.rst
@@ -378,8 +378,14 @@ Requests session plugins:
 Retriever / parser split:
 
 * :issue:`205#issuecomment-766321855`
-* split exception hierarchy (not implemented as of 3.9): :issue:`218#issuecomment-1687094315`
-
+* split exception hierarchy (not implemented as of 3.15): :issue:`218#issuecomment-1687094315`
+* API overview as of 3.14, meant to show the dataflow: :issue:`307#issuecomment-2266647310`
+* ~ideal API (mostly implemented in 3.15): :issue:`307#issuecomment-2281797898`
+
+  * exposes HTTP information (so it can be used by the updater)
+  * introduces ~internal RetrieveError and NotModified :exc:`ParseError` subclasses;
+    notably, this doesn't really follow the split exception hierarchy mentioned above,
+    and is only meant to surface HTTP information in error cases
 
 Alternative feed parsers:
 

diff --git a/docs/internal.rst b/docs/internal.rst
@@ -54,6 +54,14 @@ Protocols
     :members:
     :special-members: __call__
 
+.. autoexception:: RetrieveError
+    :show-inheritance:
+    :members:
+
+.. autoexception:: NotModified
+    :show-inheritance:
+    :members:
+
 .. autoclass:: FeedForUpdateRetrieverType
     :members:
     :show-inheritance:
@@ -92,25 +100,16 @@ Data objects
 .. autoclass:: RetrieveResult
     :members:
 
-.. autoclass:: ParsedFeed
+.. autoclass:: RetrievedFeed
     :members:
 
-.. module:: reader._types
-
-.. autoclass:: FeedData
-    :members:
-    :undoc-members:
-
-.. autoclass:: EntryData
+.. autoclass:: ParseResult
     :members:
-    :undoc-members:
 
-.. todo:: the following should be in the storage section, when we get one
-
-.. autoclass:: FeedForUpdate
+.. autoclass:: ParsedFeed
     :members:
 
-.. autoclass:: EntryForUpdate
+.. autoclass:: HTTPInfo
     :members:
 
 
@@ -171,6 +170,9 @@ but at least one other implementation needs to exists before that.
 
 .. _changes:
 
+Change tracking
+~~~~~~~~~~~~~~~
+
 .. autoclass:: ChangeTrackingStorageType()
     :members:
     :show-inheritance:
@@ -193,12 +195,26 @@ but at least one other implementation needs to exists before that.
 Data objects
 ~~~~~~~~~~~~
 
+.. autoclass:: FeedData
+    :members:
+    :undoc-members:
+
+.. autoclass:: EntryData
+    :members:
+    :undoc-members:
+
 .. autoclass:: FeedFilter
     :members:
 
 .. autoclass:: EntryFilter
     :members:
 
+.. autoclass:: FeedForUpdate
+    :members:
+
+.. autoclass:: EntryForUpdate
+    :members:
+
 .. autoclass:: FeedUpdateIntent
     :members:
 

diff --git a/src/reader/_parser/__init__.py b/src/reader/_parser/__init__.py
@@ -336,7 +336,7 @@ def process_feed_for_update(self, feed: FeedForUpdate) -> FeedForUpdate:
 class ParseResult(_namedtuple_compat, Generic[F, E]):
     """The result of retrieving and parsing a feed, regardless of the outcome."""
 
-    #: The feed (a :class:`FeedArgument`, usually a :class:`FeedForUpdate`).
+    #: The feed (a :class:`FeedArgument`, usually a :class:`.FeedForUpdate`).
     feed: F
 
     #: One of: