osmium - Processing OSM files

Osmium processes files by reading data from a file and applying them to a processing chain. Pyosmium offers a simplified wrapper to this interface with the SimpleHandler class from which an OSM file processor can easily be derived.

For more fine grained control of the processing chain, the more basic functions and processors are exported as well in this module.

Input Handlers

An input handler provides the base class for writing custom data processors. They take input data, usually from a file, and forward it to handler functions.

class osmium.SimpleHandler

The most generic of OSM data handlers. Derive your data processor from this class and implement callbacks for each object type you are interested in. The following data types are recognised: node, way, relation, area and changeset. A callback takes exactly one parameter which is the object. Note that all objects that are handed into the handler are only readable and are only valid until the end of the callback is reached. Any data that should be retained must be copied into other data structures.

apply_buffer(self: osmium._osmium.SimpleHandler, buffer: buffer, format: str, locations: bool = False, idx: str = 'flex_mem') → None

Apply the handler to a string buffer. The buffer must be a byte string.

apply_file(self: osmium._osmium.SimpleHandler, filename: object, locations: bool = False, idx: str = 'flex_mem') → None

Apply the handler to the given file. If locations is true, then a location handler will be applied before, which saves the node positions. In that case, the type of this position index can be further selected in idx. If an area callback is implemented, then the file will be scanned twice and a location handler and a handler for assembling multipolygons and areas from ways will be executed.

SimpleWriter

The writer class can be used to create an OSM file. The writer is able to handle native osmium.osm objects as well as any Python object that exposes the same attributes. It is not necessary to implement the full list of attributes as any missing attributes will be replaced with a sensible default value when writing. See Mutable OSM Objects for a detailed discussion of the data formats understood for each attribute.

Warning

Writers are considerably faster in handling native osmium data types than Python objects. You should therefore avoid converting objects whereever possible. This is not only true for the OSM data types like Node, Way and Relation but also for tag lists, node lists and member lists.

class osmium.SimpleWriter

The most generic class to write osmium objects into a file. The writer takes a file name as its mandatory parameter. The file must not yet exist. The file type to output is determined from the file extension. The second (optional) parameter is the buffer size. osmium caches the output data in an internal memory buffer before writing it on disk. This parameter allows changing the default buffer size of 4MB. Larger buffers are normally better but you should be aware that there are normally multiple buffers in use during the write process.

add_node(self: osmium._osmium.SimpleWriter, node: object) → None

Add a new node to the file. The node may be an osmium.osm.Node object, an osmium.osm.mutable.Node object or any other Python object that implements the same attributes.

add_relation(self: osmium._osmium.SimpleWriter, relation: object) → None

Add a new relation to the file. The relation may be an osmium.osm.Relation object, an osmium.osm.mutable.Relation object or any other Python object that implements the same attributes.

add_way(self: osmium._osmium.SimpleWriter, way: object) → None

Add a new way to the file. The way may be an osmium.osm.Way object, an osmium.osm.mutable.Way object or any other Python object that implements the same attributes.

close(self: osmium._osmium.SimpleWriter) → 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.

Low-level Functions and Classes

osmium.apply(*args, **kwargs)

Overloaded function.

  1. apply(reader: osmium::io::Reader, handler: BaseHandler) -> None

Apply a chain of handlers.

  1. apply(reader: osmium::io::Reader, node_handler: osmium._osmium.NodeLocationsForWays) -> None

Apply a chain of handlers.

  1. apply(reader: osmium::io::Reader, node_handler: osmium._osmium.NodeLocationsForWays, handler: BaseHandler) -> None

Apply a chain of handlers.

osmium.make_simple_handler(node: Optional[Callable[[Node], None]] = None, way: Optional[Callable[[Way], None]] = None, relation: Optional[Callable[[Relation], None]] = None, area: Optional[Callable[[Area], None]] = None, changeset: Optional[Callable[[Changeset], None]] = None) → SimpleHandler

Convenience function that creates a SimpleHandler from a set of callback functions. Each of the parameters takes an optional callable that must expect a single positional parameter with the object being processed.