Data writers

osmium.SimpleWriter

Bases: osmium._osmium.BaseHandler

Basic writer for OSM data. The SimpleWriter can write out object that are explicitly passed or function as a handler and write out all objects it receives. It is also possible to mix these two modes of operations.

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 for OSM files.

The SimpleWriter should normally used as a context manager. If you don't use it in a with context, don't forget to call close(), when writing is finished.

__init__(file: Union[str, os.PathLike[str], File], bufsz: int = ..., header: Optional[Header] = ..., overwrite: bool = ..., filetype: str = ...) -> None

Initiate a new writer for the given file. The writer will refuse to overwrite an already existing file unless overwrite is explicitly set to True.

The file type is usually determined from the file extension. If you want to explicitly set the filetype (for example, when writing to standard output '-'), then use a File object. Using the filetype parameter to set the file type is deprecated and only works when the file is a string.

The header parameter can be used to set a custom header in the output file. What kind of information can be written into the file header depends on the file type.

The optional parameter bufsz sets the size of the buffers used for collecting the data before they are written out. The default size is 4MB. Larger buffers are normally better but you should be aware that there are normally multiple buffers in use during the write process.

add(obj: object) -> None

Add a new object to the file. The function will try to determine the kind of object automatically.

add_node(node: object) -> None

Add a new node to the file. The node may be a Node object or its mutable variant or any other Python object that implements the same attributes.

add_relation(relation: object) -> None

Add a new relation to the file. The relation may be a Relation object or its mutable variant or any other Python object that implements the same attributes.

add_way(way: object) -> None

Add a new way to the file. The way may be a Way object or its mutable variant or any other Python object that implements the same attributes.

close() -> None

Flush the remaining buffers and close the writer. While it is not strictly necessary to call this function explicitly, it is still strongly recommended to close the writer as soon as possible, so that the buffer memory can be freed.

osmium.WriteHandler

Bases: osmium._osmium.SimpleWriter

(Deprecated) Handler function that writes all data directly to a file.

This is now simply an alias for SimpleWriter. Please refer to its documentation.

osmium.BackReferenceWriter

Writer that adds referenced objects, so that all written objects are reference-complete.

The collected data is first written into a temporary file and the necessary references are tracked internally. When the writer is closed, it writes the final file, mixing together the referenced objects from the original file and the written data.

The writer should usually be used as a context manager.

__init__(outfile: Union[str, os.PathLike[str], File], ref_src: Union[str, os.PathLike[str], File, FileBuffer], 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.

add(obj: Any) -> None

Write an arbitrary OSM object. This can be either an osmium object or a Python object that has the appropriate attributes.

add_node(n: Any) -> None

Write out an OSM node.

add_relation(r: Any) -> None

Write out an OSM relation.

add_way(w: Any) -> None

Write out an OSM way.

close() -> None

Close the writer and write out the final file.

The function will be automatically called when the writer is used as a context manager.

osmium.ForwardReferenceWriter

Writer that adds forward-referenced objects optionally also making the final file reference complete. An object is a forward reference when it directly or indirectly needs one of the objects originally written out.

The collected data is first written into a temporary file, When the writer is closed, the references are collected from the reference file and written out together with the collected data into the final file.

The writer should usually be used as a context manager.

__init__(outfile: Union[str, os.PathLike[str], File], ref_src: Union[str, os.PathLike[str], File, FileBuffer], 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.

add(obj: Any) -> None

Write an arbitrary OSM object. This can be either an osmium object or a Python object that has the appropriate attributes.

add_node(n: Any) -> None

Write out an OSM node.

add_relation(r: Any) -> None

Write out an OSM relation.

add_way(w: Any) -> None

Write out an OSM way.

close() -> None

Close the writer and write out the final file.

The function will be automatically called when the writer is used as a context manager.