[Git][debian-gis-team/pyosmium][master] 4 commits: New upstream version 4.0.2
Bas Couwenberg (@sebastic)
gitlab at salsa.debian.org
Sat Oct 19 17:05:21 BST 2024
Bas Couwenberg pushed to branch master at Debian GIS Project / pyosmium
Commits:
12edf90e by Bas Couwenberg at 2024-10-19T17:53:37+02:00
New upstream version 4.0.2
- - - - -
9be4cfa4 by Bas Couwenberg at 2024-10-19T17:53:43+02:00
Update upstream source from tag 'upstream/4.0.2'
Update to upstream version '4.0.2'
with Debian dir e65d582f347d5ecc2850b7d75a78735248ce0e4a
- - - - -
9e24848d by Bas Couwenberg at 2024-10-19T17:53:55+02:00
New upstream release.
- - - - -
7d682591 by Bas Couwenberg at 2024-10-19T17:55:02+02:00
Set distribution to unstable.
- - - - -
15 changed files:
- CHANGELOG.md
- debian/changelog
- docs/reference/Dataclasses.md
- + docs/reference/Replication.md
- docs/user_manual/06-Writing-Data.md
- lib/replication.cc
- mkdocs.yaml
- src/osmium/osm/mutable.py
- src/osmium/replication/__init__.py
- src/osmium/replication/_replication.pyi
- src/osmium/replication/server.py
- src/osmium/replication/utils.py
- src/osmium/version.py
- test/test_writer.py
- tools/pyosmium-get-changes
Changes:
=====================================
CHANGELOG.md
=====================================
@@ -4,6 +4,17 @@
All notable changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/).
+## [4.0.2] - 2024-10-19
+
+### Fixed
+
+- set proper default 'osc.gz' for prefixes on replication servers
+
+### Added
+
+- add documentation for writing custom objects and replication module
+
+
## [4.0.1] - 2024-09-27
### Fixed
=====================================
debian/changelog
=====================================
@@ -1,3 +1,9 @@
+pyosmium (4.0.2-1) unstable; urgency=medium
+
+ * New upstream release.
+
+ -- Bas Couwenberg <sebastic at debian.org> Sat, 19 Oct 2024 17:54:52 +0200
+
pyosmium (4.0.1-1) unstable; urgency=medium
* New upstream release.
=====================================
docs/reference/Dataclasses.md
=====================================
@@ -42,3 +42,10 @@ valid.
::: osmium.osm.Box
::: osmium.osm.Location
+
+## Mutable OSM objects
+
+::: osmium.osm.mutable.OSMObject
+::: osmium.osm.mutable.Node
+::: osmium.osm.mutable.Way
+::: osmium.osm.mutable.Relation
=====================================
docs/reference/Replication.md
=====================================
@@ -0,0 +1,14 @@
+# Replication
+
+## Replication server
+
+::: osmium.replication.ReplicationServer
+::: osmium.replication.OsmosisState
+::: osmium.replication.DownloadResult
+
+
+## Replication utils
+
+::: osmium.replication.newest_change_from_file
+::: osmium.replication.get_replication_header
+::: osmium.replication.ReplicationHeader
=====================================
docs/user_manual/06-Writing-Data.md
=====================================
@@ -69,6 +69,59 @@ You can also write data that is not based on OSM input data at all. The write
functions will accept any Python object that mimics the attributes of a
node, way or relation.
+Here is a simple example that writes out four random points:
+
+!!! example
+ ``` python
+ from random import uniform
+
+ class RandomNode:
+ def __init__(self, name, id):
+ self.id = id
+ self.location = (uniform(-180, 180), uniform(-90, 90))
+ self.tags = {'name': name}
+
+ with osmium.SimpleWriter('points.opl') as writer:
+ for i in range(4):
+ writer.add_node(RandomNode(f"Random {i}", i))
+ ```
+
+The following table gives an overview over the recognised attributes and
+acceptable types. If an attribute is missing, then pyosmium will choose a
+suitable default or leave the attribute out completely from the output if
+that is possible.
+
+| attribute | types |
+|-----------|----------------------------|
+| id | `int` |
+| version | `int` (positive non-zero value) |
+| visible | `bool` |
+| changeset | `int` (positive non-zero value) |
+| timestamp | `str` or `datetime` (will be translated to UTC first) |
+| uid | `int` |
+| tags | [osmium.osm.TagList][], a dict-like object or a list of tuples, where each tuple contains a (key, value) string pair |
+| user | `str` |
+| location | _(node only)_ [osmium.osm.Location][] or a tuple of lon/lat coordinates |
+| nodes | _(way only)_ [osmium.osm.NodeRefList][] or a list consisting of either [osmium.osm.NodeRef][]s or simple node ids |
+| members | _(relation only)_ [osmium.osm.RelationMemberList][] or a list consisting of either [osmium.osm.RelationMember][]s or tuples of `(type, id, role)`. The member type must be a single character 'n', 'w' or 'r'. |
+
+The `osmium.osm.mutable` module offers pure Python-object versions of `Node`,
+`Way` and `Relation` to make the creation of custom objects easier. Any of
+the allowable attributes may be set in the constructor. This makes the
+example for writing random points a bit shorter:
+
+!!! example
+ ``` python
+ from random import uniform
+
+ with osmium.SimpleWriter('points.opl') as writer:
+ for i in range(4):
+ writer.add_node(osmium.osm.mutable.Node(
+ id=i, location = (uniform(-180, 180), uniform(-90, 90)),
+ tags={'name': f"Random {i}"}))
+ ```
+
+
## Writer types
pyosmium implements three different writer classes: the basic
=====================================
lib/replication.cc
=====================================
@@ -42,6 +42,5 @@ PYBIND11_MODULE(_replication, m)
reader.close();
return handler.last_change;
- },
- "Find the date of the most recent change in a file.");
+ });
}
=====================================
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/osm/mutable.py
=====================================
@@ -19,14 +19,7 @@ if TYPE_CHECKING:
Sequence[Union[osmium.osm.RelationMember, Tuple[str, int, str]]]]
class OSMObject:
- """Mutable version of ``osmium.osm.OSMObject``. It exposes the following
- attributes ``id``, ``version``, ``visible``, ``changeset``, ``timestamp``,
- ``uid`` and ``tags``. Timestamps may be strings or datetime objects.
- Tags can be an osmium.osm.TagList, a dict-like object
- or a list of tuples, where each tuple contains a (key value) string pair.
-
- If the ``base`` parameter is given in the constructor, then the object
- will be initialised first from the attributes of this base object.
+ """ Mutable version of [osmium.osm.OSMObject][].
"""
def __init__(self, base: Optional['OSMObjectLike'] = None,
@@ -34,6 +27,15 @@ class OSMObject:
visible: Optional[bool] = None, changeset: Optional[int] = None,
timestamp: Optional[datetime] = None, uid: Optional[int] = None,
tags: Optional['TagSequence'] = None, user: Optional[str] = None) -> None:
+ """ Initialise an object with the following optional
+ attributes: `id`, `version`, `visible`, `changeset`, `timestamp`,
+ `uid` and `tags`. Timestamps may be strings or datetime objects.
+ Tags can be an osmium.osm.TagList, a dict-like object
+ or a list of tuples, where each tuple contains a (key value) string pair.
+
+ If the `base` parameter is given in the constructor, then the object
+ will be initialised first from the attributes of this base object.
+ """
if base is None:
self.id = id
self.version = version
@@ -55,14 +57,18 @@ class OSMObject:
class Node(OSMObject):
- """The mutable version of ``osmium.osm.Node``. It inherits all attributes
- from osmium.osm.mutable.OSMObject and adds a `location` attribute. This
- may either be an `osmium.osm.Location` or a tuple of lon/lat coordinates.
+ """ The mutable version of [osmium.osm.Node][].
"""
def __init__(self, base: Optional[Union['Node', 'osmium.osm.Node']] = None,
location: Optional['LocationLike'] = None,
**attrs: Any) -> None:
+ """ Initialise a node with all optional attributes
+ from osmium.osm.mutable.OSMObject as well as a `location` attribute.
+ This may either be an [osmium.osm.Location][] or a tuple of
+ lon/lat coordinates.
+
+ """
OSMObject.__init__(self, base=base, **attrs)
if base is None:
self.location = location
@@ -71,14 +77,16 @@ class Node(OSMObject):
class Way(OSMObject):
- """The mutable version of ``osmium.osm.Way``. It inherits all attributes
- from osmium.osm.mutable.OSMObject and adds a `nodes` attribute. This may
- either be and ``osmium.osm.NodeList`` or a list consisting of
- ``osmium.osm.NodeRef`` or simple node ids.
+ """ The mutable version of [osmium.osm.Way][].
"""
def __init__(self, base: Optional[Union['Way', 'osmium.osm.Way']] = None,
nodes: Optional['NodeSequence'] = None, **attrs: Any) -> None:
+ """ Initialise a way with all optional attributes
+ from osmium.osm.mutable.OSMObject as well as a `nodes` attribute.
+ This may either be an [osmium.osm.NodeRefList][] or a list
+ consisting of [osmium.osm.NodeRef][] or simple node ids.
+ """
OSMObject.__init__(self, base=base, **attrs)
if base is None:
self.nodes = nodes
@@ -86,15 +94,18 @@ class Way(OSMObject):
self.nodes = nodes if nodes is not None else base.nodes
class Relation(OSMObject):
- """The mutable version of ``osmium.osm.Relation``. It inherits all attributes
- from osmium.osm.mutable.OSMObject and adds a `members` attribute. This
- may either be an ``osmium.osm.RelationMemberList`` or a list consisting
- of ``osmium.osm.RelationMember`` or tuples of (type, id, role). The
- member type should be a single character 'n', 'w' or 'r'.
+ """ The mutable version of [osmium.osm.Relation][].
"""
def __init__(self, base: Optional[Union['Relation', 'osmium.osm.Relation']] = None,
members: Optional['MemberSequence'] = None, **attrs: Any) -> None:
+ """ Initialise a relation with all optional attributes
+ from osmium.osm.mutable.OSMObject as well as a `members` attribute.
+ This may either be an [osmium.osm.RelationMemberList][] or
+ a list consisting of [osmium.osm.RelationMember][] or
+ tuples of (type, id, role). The
+ member type must be a single character 'n', 'w' or 'r'.
+ """
OSMObject.__init__(self, base=base, **attrs)
if base is None:
self.members = members
=====================================
src/osmium/replication/__init__.py
=====================================
@@ -4,4 +4,11 @@
#
# Copyright (C) 2023 Sarah Hoffmann <lonvia at denofr.de> and others.
# For a full list of authors see the git log.
-from ._replication import *
+
+from ._replication import (newest_change_from_file as newest_change_from_file)
+
+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/_replication.pyi
=====================================
@@ -6,4 +6,6 @@
# For a full list of authors see the git log.
import datetime
-def newest_change_from_file(filename: str) -> datetime.datetime: ...
+def newest_change_from_file(filename: str) -> datetime.datetime:
+ """ Find the data of the most recent change in a file.
+ """
=====================================
src/osmium/replication/server.py
=====================================
@@ -28,29 +28,41 @@ LOG = logging.getLogger('pyosmium')
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 @@ from osmium.osm import NOTHING
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:
=====================================
src/osmium/version.py
=====================================
@@ -11,7 +11,7 @@ Version information.
# the major version
pyosmium_major = '4.0'
# current release (Pip version)
-pyosmium_release = '4.0.1'
+pyosmium_release = '4.0.2'
# libosmium version shipped with the Pip release
libosmium_version = '2.20.0'
=====================================
test/test_writer.py
=====================================
@@ -5,6 +5,7 @@
# Copyright (C) 2022 Sarah Hoffmann.
from contextlib import contextmanager
from collections import OrderedDict
+from datetime import datetime, timezone, timedelta
import uuid
import pytest
@@ -54,6 +55,7 @@ class O:
(O(uid=987), '0 v0 dV c0 t i987 u T'),
(O(timestamp='2012-04-14T20:58:35Z'), '0 v0 dV c0 t2012-04-14T20:58:35Z i0 u T'),
(O(timestamp=mkdate(2009, 4, 14, 20, 58, 35)), '0 v0 dV c0 t2009-04-14T20:58:35Z i0 u T'),
+ (O(timestamp=datetime(2009, 4, 14, 20, 58, 35, tzinfo=timezone(timedelta(hours=1)))), '0 v0 dV c0 t2009-04-14T19:58:35Z i0 u T'),
(O(timestamp='1970-01-01T00:00:01Z'), '0 v0 dV c0 t1970-01-01T00:00:01Z i0 u T')
])
class TestWriteAttributes:
=====================================
tools/pyosmium-get-changes
=====================================
@@ -129,7 +129,7 @@ def get_arg_parser(from_main=False):
help="Format the data should be saved in.")
parser.add_argument('--server', action='store', dest='server_url',
help='Base URL of the replication server')
- parser.add_argument('--diff-type', action='store', dest='server_diff_type',
+ parser.add_argument('--diff-type', action='store', dest='server_diff_type', default='osc.gz',
help='File format used by the replication server (default: osc.gz)')
parser.add_argument('--cookie', dest='cookie',
help='Netscape-style cookie jar file to read cookies from '
View it on GitLab: https://salsa.debian.org/debian-gis-team/pyosmium/-/compare/7e23132bd255065d638963ebbf66b8ae1f9d0b3d...7d682591cafc2fd59c87166f2b9c3f061cd59643
--
View it on GitLab: https://salsa.debian.org/debian-gis-team/pyosmium/-/compare/7e23132bd255065d638963ebbf66b8ae1f9d0b3d...7d682591cafc2fd59c87166f2b9c3f061cd59643
You're receiving this email because of your account on salsa.debian.org.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/pkg-grass-devel/attachments/20241019/435a39a3/attachment-0001.htm>
More information about the Pkg-grass-devel
mailing list