From 2ed2b2b85cd67c0b38a45f795d4cc74aed1c078c Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Sat, 14 Sep 2024 21:43:06 +0200 Subject: [PATCH] make sure __init__ of writers is documented --- src/osmium/_osmium.pyi | 4 ++-- src/osmium/back_reference_writer.py | 32 ++++++++++++++------------ src/osmium/forward_reference_writer.py | 32 ++++++++++++++------------ 3 files changed, 36 insertions(+), 32 deletions(-) diff --git a/src/osmium/_osmium.pyi b/src/osmium/_osmium.pyi index 5f969c41..46c41b37 100644 --- a/src/osmium/_osmium.pyi +++ b/src/osmium/_osmium.pyi @@ -121,7 +121,7 @@ class SimpleWriter: The writer writes out the objects in the order it receives them. It is the responsibility of the caller to ensure to follow the - [ordering conventions][the-order-of-osm-files] + [ordering conventions][order-in-osm-files] for OSM files. The SimpleWriter should normally used as a context manager. If you @@ -278,7 +278,7 @@ class IdTracker: The function scans through the reference file `filename`, finds all the objects this tracker references and applies `add_references()` to them. The reference file is expected to be - [sorted][the-order-of-osm-files]. + [sorted][order-in-osm-files]. The _relation_depth_ parameter controls how nested relations are handled. When set to 0 then only way and node references of diff --git a/src/osmium/back_reference_writer.py b/src/osmium/back_reference_writer.py index c0e0fad6..b323f4cd 100644 --- a/src/osmium/back_reference_writer.py +++ b/src/osmium/back_reference_writer.py @@ -21,27 +21,29 @@ class BackReferenceWriter: is closed, it writes the final file, mixing together the referenced objects from the original file and the written data. - `outfile` is the name of the output file to write. The file must - not yet exist unless `overwrite` is set to True. - - `ref_src` is the OSM input file, where to take the reference objects - from. This is usually the same file the data to be written is taken - from. - - The writer will by default remove all tags from referenced objects, - so that they do not appear as stray objects in the file. Set - `remove_tags` to False to keep the tags. - - The writer will not complete nested relations by default. If you - need nested relations, set `relation_depth` to the minimum depth - to which relations shall be completed. - The writer should usually be used as a context manager. """ def __init__(self, outfile: str, ref_src: str, overwrite: bool=False, remove_tags: bool=True, relation_depth: int = 0): + """ Create a new writer. + + `outfile` is the name of the output file to write. The file must + not yet exist unless `overwrite` is set to True. + + `ref_src` is the OSM input file, where to take the reference objects + from. This is usually the same file the data to be written is taken + from. + + The writer will by default remove all tags from referenced objects, + so that they do not appear as stray objects in the file. Set + `remove_tags` to False to keep the tags. + + The writer will not complete nested relations by default. If you + need nested relations, set `relation_depth` to the minimum depth + to which relations shall be completed. + """ self.outfile = outfile self.tmpdir = TemporaryDirectory() self.writer = SimpleWriter(str(Path(self.tmpdir.name, 'back_writer.osm.pbf'))) diff --git a/src/osmium/forward_reference_writer.py b/src/osmium/forward_reference_writer.py index 78127f91..be74563e 100644 --- a/src/osmium/forward_reference_writer.py +++ b/src/osmium/forward_reference_writer.py @@ -22,21 +22,6 @@ class ForwardReferenceWriter: writer is closed, the references are collected from the reference file and written out together with the collected data into the final file. - `outfile` is the name of the output file to write. The file must - not yet exist unless `overwrite` is set to True. - - `ref_src` is the OSM input file, where to take the reference objects - from. This is usually the same file the data to be written is taken - from. - - The writer will collect back references by default to make the - file reference-complete. Set `back_references=False` to disable - this behaviour. - - The writer will not complete nested relations by default. If you - need nested relations, set `relation_depth` to the minimum depth - to which relations shall be completed. - The writer should usually be used as a context manager. """ @@ -44,6 +29,23 @@ def __init__(self, outfile: str, ref_src: str, overwrite: bool=False, back_references: bool=True, remove_tags: bool=True, forward_relation_depth: int=0, backward_relation_depth: int=1) -> None: + """ Create a new writer. + + `outfile` is the name of the output file to write. The file must + not yet exist unless `overwrite` is set to True. + + `ref_src` is the OSM input file, where to take the reference objects + from. This is usually the same file the data to be written is taken + from. + + The writer will collect back-references by default to make the + file reference-complete. Set `back_references=False` to disable + this behaviour. + + The writer will not complete nested relations by default. If you + need nested relations, set `relation_depth` to the minimum depth + to which relations shall be completed. + """ self.outfile = outfile self.tmpdir: Optional['TemporaryDirectory[Any]'] = TemporaryDirectory() self.writer = SimpleWriter(str(Path(self.tmpdir.name, 'forward_writer.osm.pbf')))