add replicaton module to reference documentation

docs/reference/Replication.md

@@ -0,0 +1,13 @@
+# Replication
+
+## Replication server
+
+::: osmium.replication.ReplicationServer
+::: osmium.replication.OsmosisState
+::: osmium.replication.DownloadResult
+
+
+## Repliction utils
+
+::: osmium.replication.get_replication_header
+::: osmium.replication.ReplicationHeader

mkdocs.yaml

@@ -45,6 +45,7 @@ nav:
       - Geometry Processing: 'reference/Geometry-Functions.md'
       - Area Building: 'reference/Area.md'
       - Indexes: 'reference/Indexes.md'
+      - Replication: 'reference/Replication.md'
       - Exceptions: 'reference/Exceptions.md'
 
 exclude_docs: |

src/osmium/replication/__init__.py

@@ -5,3 +5,9 @@
 # Copyright (C) 2023 Sarah Hoffmann <[email protected]> and others.
 # For a full list of authors see the git log.
 from ._replication import *
+
+from .server import (ReplicationServer as ReplicationServer,
+                     OsmosisState as OsmosisState,
+                     DownloadResult as DownloadResult)
+from .utils import (ReplicationHeader as ReplicationHeader,
+                    get_replication_header as get_replication_header)

src/osmium/replication/server.py

@@ -28,29 +28,41 @@
 LOG.addHandler(logging.NullHandler())
 
 class OsmosisState(NamedTuple):
+    """ Represents a state file of a replication server.
+    """
     sequence: int
+    "The ID of the replication change on the server."
     timestamp: dt.datetime
+    "Date until when changes are contained in the change file."
 
 class DownloadResult(NamedTuple):
+    """ Downloaded change.
+    """
     id: int
+    "The ID of the latest downloaded replication change on the server."
     reader: MergeInputReader
+    "[osmium.MergeInputReader][] with all downloaded changes."
     newest: int
+    "ID of the newest change available on the server."
 
 class ReplicationServer:
     """ Represents a connection to a  server that publishes replication data.
         Replication change files allow to keep local OSM data up-to-date without
         downloading the full dataset again.
 
-        `url` contains the base URL of the replication service. This is the
-        directory that contains the state file with the current state. If the
-        replication service serves something other than osc.gz files, set
-        the `diff_type` to the given file suffix.
-
         ReplicationServer may be used as a context manager. In this case, it
         internally keeps a connection to the server making downloads faster.
     """
 
     def __init__(self, url: str, diff_type: str = 'osc.gz') -> None:
+        """ Set up the connection to a replication server.
+
+            `url` contains the base URL of the replication service. This is
+            the directory that contains the state file with the current
+            state. If the replication service serves something other
+            than osc.gz files, set the `diff_type` to the given file suffix.
+        """
+
         self.baseurl = url
         self.diff_type = diff_type
         self.extra_request_params: dict[str, Any] = dict(timeout=60, stream=True)

src/osmium/replication/utils.py

@@ -15,9 +15,14 @@
 LOG = logging.getLogger('pyosmium')
 
 class ReplicationHeader(NamedTuple):
+    """ Description of a replication state.
+    """
     url: Optional[str]
+    "Base URL of the replication service."
     sequence: Optional[int]
+    "ID of the change file on the server."
     timestamp: Optional[dt.datetime]
+    "Date of latest changes contained in the diff file."
 
 
 def get_replication_header(fname: str) -> ReplicationHeader: