Skip to content

Commit ae7226e

Browse files
committed
add replicaton module to reference documentation
1 parent 695273d commit ae7226e

File tree

5 files changed

+42
-5
lines changed

5 files changed

+42
-5
lines changed

docs/reference/Replication.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Replication
2+
3+
## Replication server
4+
5+
::: osmium.replication.ReplicationServer
6+
::: osmium.replication.OsmosisState
7+
::: osmium.replication.DownloadResult
8+
9+
10+
## Repliction utils
11+
12+
::: osmium.replication.get_replication_header
13+
::: osmium.replication.ReplicationHeader

mkdocs.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ nav:
4545
- Geometry Processing: 'reference/Geometry-Functions.md'
4646
- Area Building: 'reference/Area.md'
4747
- Indexes: 'reference/Indexes.md'
48+
- Replication: 'reference/Replication.md'
4849
- Exceptions: 'reference/Exceptions.md'
4950

5051
exclude_docs: |

src/osmium/replication/__init__.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,9 @@
55
# Copyright (C) 2023 Sarah Hoffmann <[email protected]> and others.
66
# For a full list of authors see the git log.
77
from ._replication import *
8+
9+
from .server import (ReplicationServer as ReplicationServer,
10+
OsmosisState as OsmosisState,
11+
DownloadResult as DownloadResult)
12+
from .utils import (ReplicationHeader as ReplicationHeader,
13+
get_replication_header as get_replication_header)

src/osmium/replication/server.py

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,29 +28,41 @@
2828
LOG.addHandler(logging.NullHandler())
2929

3030
class OsmosisState(NamedTuple):
31+
""" Represents a state file of a replication server.
32+
"""
3133
sequence: int
34+
"The ID of the replication change on the server."
3235
timestamp: dt.datetime
36+
"Date until when changes are contained in the change file."
3337

3438
class DownloadResult(NamedTuple):
39+
""" Downloaded change.
40+
"""
3541
id: int
42+
"The ID of the latest downloaded replication change on the server."
3643
reader: MergeInputReader
44+
"[osmium.MergeInputReader][] with all downloaded changes."
3745
newest: int
46+
"ID of the newest change available on the server."
3847

3948
class ReplicationServer:
4049
""" Represents a connection to a server that publishes replication data.
4150
Replication change files allow to keep local OSM data up-to-date without
4251
downloading the full dataset again.
4352
44-
`url` contains the base URL of the replication service. This is the
45-
directory that contains the state file with the current state. If the
46-
replication service serves something other than osc.gz files, set
47-
the `diff_type` to the given file suffix.
48-
4953
ReplicationServer may be used as a context manager. In this case, it
5054
internally keeps a connection to the server making downloads faster.
5155
"""
5256

5357
def __init__(self, url: str, diff_type: str = 'osc.gz') -> None:
58+
""" Set up the connection to a replication server.
59+
60+
`url` contains the base URL of the replication service. This is
61+
the directory that contains the state file with the current
62+
state. If the replication service serves something other
63+
than osc.gz files, set the `diff_type` to the given file suffix.
64+
"""
65+
5466
self.baseurl = url
5567
self.diff_type = diff_type
5668
self.extra_request_params: dict[str, Any] = dict(timeout=60, stream=True)

src/osmium/replication/utils.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,14 @@
1515
LOG = logging.getLogger('pyosmium')
1616

1717
class ReplicationHeader(NamedTuple):
18+
""" Description of a replication state.
19+
"""
1820
url: Optional[str]
21+
"Base URL of the replication service."
1922
sequence: Optional[int]
23+
"ID of the change file on the server."
2024
timestamp: Optional[dt.datetime]
25+
"Date of latest changes contained in the diff file."
2126

2227

2328
def get_replication_header(fname: str) -> ReplicationHeader:

0 commit comments

Comments
 (0)