### Compile and install pyosmium from source

Source: https://docs.osmcode.org/pyosmium/latest

Builds and installs the Python bindings from the source directory. Optionally use --user to install for the current user.

```bash
pip install [--user] .
```

--------------------------------

### Install pyosmium via pip

Source: https://docs.osmcode.org/pyosmium/latest

Recommended installation method using pip. Installs the 'osmium' package.

```bash
pip install osmium
```

--------------------------------

### Install build dependencies on Debian/Ubuntu

Source: https://docs.osmcode.org/pyosmium/latest

Installs required system packages for building pyosmium from source on Debian/Ubuntu-like systems.

```bash
sudo apt-get install python3-dev build-essential cmake \
                     libexpat1-dev zlib1g-dev libbz2-dev
```

--------------------------------

### Convert OSM objects to WKT using WKTFactory

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/03-Working-with-Geometries

Instantiates a WKTFactory and converts nodes, ways, and areas to WKT strings. Requires a FileProcessor with .with_areas() to get areas. The example ignores relations by setting wkt to None.

```python
fab = osmium.geom.WKTFactory()

for o in osmium.FileProcessor('../data/buildings.opl').with_areas():
    if o.is_node():
        wkt = fab.create_point(o.location)
    elif o.is_way() and not o.is_closed():
        wkt = fab.create_linestring(o.nodes)
    elif o.is_area():
        wkt = fab.create_multipolygon(o)
    else:
        wkt = None # ignore relations
```

--------------------------------

### Create state file from import file

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/10-Replication-Tools

Creates a state file with the sequence ID where updates should start, using the OSM file used for the initial database import. Prints the replication service URL.

```bash
pyosmium-get-changes -O <osmfile.osm.pbf> -f sequence.state -v

```

--------------------------------

### Convert OPL to PBF with FileProcessor

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/06-Writing-Data

Complete example converting a file from OPL to PBF format. Reads objects with FileProcessor and writes them with writer.add(o).

```python
with osmium.SimpleWriter('buildings.osm.pbf') as  writer:
    for o in osmium.FileProcessor('buildings.opl'):
        writer.add(o)

```

--------------------------------

### Create state file from a date

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/10-Replication-Tools

Creates a state file using a specific date (timestamp from OSM API) to determine the starting sequence ID. Prints the replication service URL.

```bash
pyosmium-get-changes -D 2007-01-01T14:16:21Z -f sequence.state -v

```

--------------------------------

### Bootstrap replication source with --ignore-osmosis-headers and --server

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/10-Replication-Tools

Use when the file lacks replication info or to switch servers. Automatically finds the starting sequence ID from the file's age, updates the file, and stores the new source for future runs.

```bash
pyosmium-up-to-date --ignore-osmosis-headers --server <replication URL> <osmfile.osm.pbf>

```

--------------------------------

### Output of filtered processing example

Source: https://docs.osmcode.org/pyosmium/latest/cookbooks/Enhance-Tags

Sample output from the filtered processing example, showing object IDs and their French names.

```text
193121816 has the French name Vaduz.
3696525426 has the French name Liechtenstein.
9798887324 has the French name Schweizerisches Generalkonsulat.
159018431 has the French name Rhein.
424869 has the French name Rhein.
8497 has the French name Rhein-Route.
12464 has the French name Seen-Route.
16239 has the French name Österreich.
19664 has the French name Seen-Route - Etappe 9.
27939 has the French name Cycling in Switzerland.
51701 has the French name Schweiz/Suisse/Svizzera/Svraz.
74942 has the French name Vorarlberg.
102638 has the French name Rhein-Route - Etappe 3.
102666 has the French name Österreich - Schweiz.
102877 has the French name Österreich — Liechtenstein.
123924 has the French name Rhein.
302442 has the French name Schweizer Hauptstrassen.
1155955 has the French name Liechtenstein.
1550322 has the French name Österreich — Schweiz / Suisse / Svizzera.
1665395 has the French name Via Alpina Red.
1686631 has the French name Graubünden/Grischun/Grigioni.
1687006 has the French name Sankt Gallen.
2128682 has the French name Rätikon.
2171555 has the French name EuroVelo 15 - Rheinradweg.
2668952 has the French name European Union / Union Européenne / Europäische Union.
2698607 has the French name Alps.
11342353 has the French name Appenzeller Alpen.
12579662 has the French name Via Alpina Green.
12729625 has the French name Eurozone.
13376469 has the French name Member States of the European Union / États members de l'Union européenne / Mitgliedstaaten der Europäischen Union.

```

--------------------------------

### Apply handler with osmium.apply and show output

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/05-Working-with-Handlers

Applies the PrintHandler to an OSM file using osmium.apply. The output shows the printed entities for the example file buildings.opl.

```python
import osmium

my_handler = PrintHandler()

osmium.apply('buildings.opl', my_handler)

```

```text
n1: location=45.0000000/13.0000000 tags={}
n2: location=45.0001000/13.0000000 tags={}
n3: location=45.0001000/13.0001000 tags={}
n4: location=45.0000000/13.0001000 tags={entrance=yes}
n11: location=45.0000100/13.0000100 tags={}
n12: location=45.0000500/13.0000100 tags={}
n13: location=45.0000500/13.0000500 tags={}
n14: location=45.0000100/13.0000500 tags={}
w1: nodes=[1,2,3,4,1] tags={amenity=restaurant}
w2: nodes=[11,12,13,14,11] tags={}
r1: members=[w1,w2], tags={type=multipolygon,building=yes}

```

--------------------------------

### Read from buffer and compute statistics

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/07-Input-Formats-And-Other-Sources

This example reads OSM data from a URL into a buffer and computes node/way/relation counts using osmium.io.FileBuffer. The file format must be explicitly given.

```python
import urllib.request as urlrequest

data = urlrequest.urlopen('https://example.com/some.osm.gz').read()

counter = {'n': 0, 'w': 0, 'r': 0}

for o in osmium.FileProcessor(osmium.io.FileBuffer(data, 'osm.gz')):
    counter[o.type_str()] += 1

print("Nodes: %d" % counter['n'])
print("Ways: %d" % counter['w'])
print("Relations: %d" % counter['r'])

```

--------------------------------

### Basic pyosmium-up-to-date command

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/10-Replication-Tools

Updates the given OSM file using the replication source stored in the file. Repeats the command to get newer data, resuming from the last update point.

```bash
pyosmium-up-to-date <osmfile.osm.pbf>

```

--------------------------------

### Copy tags into a Python dictionary

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/02-Extracting-Object-Data

Shows how to save the tag list for later use by converting it to a Python dictionary with dict(o.tags). The example collects tags from objects in a different file path.

```python
saved_tags = []

for o in osmium.FileProcessor('../data/buildings.opl'):
    if o.tags:
        saved_tags.append(dict(o.tags))

print("Saved tags:", saved_tags)

```

--------------------------------

### Write custom objects with mutable.Node

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/06-Writing-Data

Create custom objects that mimic OSM attributes. This example writes four random points using a custom class and the mutable.Node constructor.

```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))

```

--------------------------------

### Filter and modify OSM tags with osmium.FileProcessor

Source: https://docs.osmcode.org/pyosmium/latest/cookbooks/Enhance-Tags

Processes an OSM PBF file with a filter for the 'name:fr' key, removes that tag from each object, and writes the modified objects to an OPL file using osmium.SimpleWriter. The example shows how to use osmium.FileProcessor with a KeyFilter and a handler for filtered objects.

```python
with osmium.SimpleWriter('../data/out/buildings.opl', overwrite=True) as writer:
    fp = osmium.FileProcessor('../data/liechtenstein.osm.pbf')\
        .with_filter(osmium.filter.KeyFilter('name:fr'))\
        .handler_for_filtered(writer)
    for obj in fp:
        tags = {k: v for k, v in obj.tags if k != 'name:fr'}
        # ... do more stuff here
        writer.add(obj.replace(tags=tags))
```

--------------------------------

### ReplicationServer.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/Replication

Initializes a connection to a replication server with the given base URL and diff file suffix.

```APIDOC
## ReplicationServer.__init__

### Description
Set up the connection to a replication server.

### Method
__init__

### Signature
`__init__(url: str, diff_type: str = 'osc.gz') -> None`

### Parameters
- **url** (str) - Required - The base URL of the replication service, containing the state file.
- **diff_type** (str) - Optional - The file suffix for diff files. Defaults to 'osc.gz'.

### Returns
None
```

--------------------------------

### Access tags with bracket notation and get()

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/02-Extracting-Object-Data

Shows how to check for a tag's existence with 'in' and access it using bracket notation (raises ValueError if missing) or the get() method (returns a default value instead of throwing).

```python
for o in osmium.FileProcessor('buildings.opl'):
    # When using the bracket notation, make sure the tag exists.
    if 'entrance' in o.tags:
        print('entrace =', o.tags['entrance'])

    # The get() function never throws.
    print('building =', o.tags.get('building', '<unset>')

```

--------------------------------

### Create SimpleWriter instance

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/06-Writing-Data

Instantiate a SimpleWriter with a filename. The output format is determined by the file prefix. Overwriting existing files is refused unless overwrite=true is passed.

```python
writer = osmium.SimpleWriter('my_extra_data.osm.pbf')

```

--------------------------------

### osmium.osm.NodeRefList.is_closed

Source: https://docs.osmcode.org/pyosmium/latest/reference/Dataclasses

Checks if a way is closed (start and end node are the same).

```APIDOC
## osmium.osm.NodeRefList.is_closed

### Description
Returns True if the start and end node are the same (synonym for `ends_have_same_id`).

### Method
`is_closed() -> bool`

### Returns
- **bool** - True if the way is closed.

```

--------------------------------

### osmium.MergeInputReader.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/Handler-Processing

Initializes a new MergeInputReader.

```APIDOC
## osmium.MergeInputReader.__init__

### Description
Initializes a new reader.

### Method
__init__

### Parameters
None

### Return Value
None
```

--------------------------------

### osmium.osm.NodeRefList.ends_have_same_location

Source: https://docs.osmcode.org/pyosmium/latest/reference/Dataclasses

Checks if the start and end node of a way are at the same location.

```APIDOC
## osmium.osm.NodeRefList.ends_have_same_location

### Description
Returns True if the start and end node of the way are at the same location. Expects that the coordinates of the way nodes have been loaded (SimpleHandler apply functions and `FileProcessor.with_locations()`). If the locations are not present then the function always returns true.

### Method
`ends_have_same_location() -> bool`

### Returns
- **bool** - True if the start and end node are at the same location.

```

--------------------------------

### Create FileProcessor with KeyFilter

Source: https://docs.osmcode.org/pyosmium/latest/cookbooks/Filtering-Data-By-Tags

Creates a FileProcessor that returns all objects with an 'amenity' key. This is the first step in filtering schools.

```python
fp = osmium.FileProcessor('../data/liechtenstein.osm.pbf').with_filter(osmium.filter.KeyFilter('amenity'))

```

--------------------------------

### osmium.osm.NodeRefList.ends_have_same_id

Source: https://docs.osmcode.org/pyosmium/latest/reference/Dataclasses

Checks if the start and end node of a way have the same ID.

```APIDOC
## osmium.osm.NodeRefList.ends_have_same_id

### Description
Returns True if the start and end node are exactly the same.

### Method
`ends_have_same_id() -> bool`

### Returns
- **bool** - True if the start and end node are the same.

```

--------------------------------

### osmium.NodeLocationsForWays.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/Handler-Processing

Initiates a new NodeLocationsForWays handler.

```APIDOC
## osmium.NodeLocationsForWays.__init__

### Description
Initiates a new handler using the given location table to cache the node coordinates.

### Method
__init__

### Parameters
- **locations** (LocationTable) - Required - The location table to use for caching node coordinates.

### Return Value
None
```

--------------------------------

### TagFilter: OR and AND combinations

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/04-Working-with-Filters

TagFilter matches whole tags given as two-element tuples. The first example uses two tags in one filter, which acts as an OR (objects with either 'highway=primary' or 'surface=asphalt'). The second example chains two TagFilter calls, which acts as an AND (objects with both tags).

```python
print("Objects with 'highway=primary' _or_ 'surface=asphalt' tags:",
      sum(1 for o in osmium.FileProcessor('../data/liechtenstein.osm.pbf')
                           .with_filter(osmium.filter.TagFilter(('highway','primary'), ('surface','asphalt')))))

print("Objects with 'highway=primary' _and_ 'surface=asphalt' tags:",
      sum(1 for o in osmium.FileProcessor('../data/liechtenstein.osm.pbf')
                           .with_filter(osmium.filter.TagFilter(('highway','primary')))
                           .with_filter(osmium.filter.TagFilter(('surface','asphalt')))))

```

--------------------------------

### Fixed example: save object IDs instead of views

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/01-First-Steps

Fixed version of the buggy example: saves only the object IDs instead of the full object views. This avoids the RuntimeError and is more memory efficient. The output lists IDs grouped by object type (nodes, ways, relations).

```python
objects = {'n' : [], 'w': [], 'r': []}

for obj in osmium.FileProcessor('buildings.opl'):
    objects[obj.type_str()].append(obj.id)

for otype, olist in objects.items():
    print(f"{otype}: {','.join(str(id) for id in olist)}")

```

```text
n: 1,2,3,4,11,12,13,14
w: 1,2
r: 1

```

--------------------------------

### osmium.osm.Area.inner_rings

Source: https://docs.osmcode.org/pyosmium/latest/reference/Dataclasses

Returns an iterator over all inner rings of the multipolygon. The parameter specifies the outer ring to get inner rings for.

```APIDOC
## osmium.osm.Area.inner_rings

### Description
Returns an iterator over all inner rings of the multipolygon.

### Method
inner_rings

### Signature
`inner_rings(oring: OuterRing) -> InnerRingIterator`

### Parameters
#### Parameters
- **oring** (OuterRing) - Required - The outer ring for which to get inner rings.

### Returns
- **InnerRingIterator** - An iterator over inner rings.

### Example
```python
area = osmium.osm.Area()
for ring in area.inner_rings(outer_ring):
    print(ring)
```
```

--------------------------------

### Create a change file

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/10-Replication-Tools

Downloads the latest changes from the replication server, saves them to newchange.osc.gz, and updates the state file. The server parameter can be omitted for minutely changes from openstreetmap.org.

```bash
pyosmium-get-changes --server <replication server> -f sequence.state -o newchange.osc.gz

```

--------------------------------

### osmium.io.Writer.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/IO

Creates a new Writer for writing OSM data to a file. Allows specifying a custom header, overwrite behavior, and thread pool.

```APIDOC
## osmium.io.Writer.__init__

### Description
Creates a new Writer for writing OSM data to a file. The output may be a filename or a File object. A custom Header can be provided to customize global file information. Overwriting existing files is refused by default unless 'overwrite' is set to True. The writer can use a private or externally provided ThreadPool.

### Method
Constructor

### Signature
`__init__(ffile: Union[str, os.PathLike[str], File], header: Optional[Header] = None, overwrite: bool = False, thread_pool: Optional[ThreadPool] = None) -> None`

### Parameters
- **ffile** (Union[str, os.PathLike[str], File]) - Required - The output file path or File object.
- **header** (Optional[Header]) - Optional - Custom header for global file information.
- **overwrite** (bool) - Optional - Set to True to allow overwriting existing files. Default is False.
- **thread_pool** (Optional[ThreadPool]) - Optional - An externally created thread pool to use for parallel writing.

### Notes
- Not all file formats support all header information.
- If no thread pool is provided, a private one is created implicitly.

```

--------------------------------

### ReplicationServer.apply_diffs

Source: https://docs.osmcode.org/pyosmium/latest/reference/Replication

Downloads diffs starting from a given sequence ID, merges them, and applies them to a handler. Optionally limits download size and end sequence ID.

```APIDOC
## ReplicationServer.apply_diffs

### Description
Download diffs starting with sequence id `start_id`, merge them together and then apply them to handler `handler`.

### Method
apply_diffs

### Signature
`apply_diffs(handler: BaseHandler, start_id: int, max_size: Optional[int] = None, idx: str = '', simplify: bool = True, end_id: Optional[int] = None) -> Optional[int]`

### Parameters
- **handler** (BaseHandler) - Required - The handler to apply the diffs to.
- **start_id** (int) - Required - The sequence id of the first diff to download.
- **max_size** (Optional[int]) - Optional - Maximum size in kB of the internal buffer for downloaded diffs. If not provided, defaults to 1MB when end_id is also not given.
- **idx** (str) - Optional - Location cache to apply to way nodes. Defaults to empty string.
- **simplify** (bool) - Optional - If True (default), only the most recent version of an object is sent to the handler. If False, all versions are sent.
- **end_id** (Optional[int]) - Optional - The highest sequence id to download. If not provided, downloads until the most recent diff is processed.

### Returns
Optional[int] - The sequence id of the last diff downloaded, or None if the download failed completely.
```

--------------------------------

### osmium.IdTracker.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/Indexes

Initialise a new empty tracker.

```APIDOC
## osmium.IdTracker.__init__

### Description
Initialise a new empty tracker.

### Method
__init__() -> None

### Parameters
None

### Returns
None
```

--------------------------------

### Bad example: with_locations without nodes raises RuntimeError

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/04-Working-with-Filters

Attempts to use with_locations() on a FileProcessor that does not read nodes, causing a RuntimeError. The output shows the traceback and error message.

```python
for o in osmium.FileProcessor('../data/liechtenstein.osm.pbf', osmium.osm.WAY).with_locations():
    if 'highway' in o.tags:
        osmium.geom.haversine_distance(o.nodes)

```

```text
---------------------------------------------------------------------------

RuntimeError                              Traceback (most recent call last)

Cell In[14], line 1
----> 1 for o in osmium.FileProcessor('../data/liechtenstein.osm.pbf', osmium.osm.WAY).with_locations():
      2     if 'highway' in o.tags:
      3         osmium.geom.haversine_distance(o.nodes)


File ~/osm/dev/pyosmium/build/lib.linux-x86_64-cpython-311/osmium/file_processor.py:46, in FileProcessor.with_locations(self, storage)
     42 """ Enable caching of node locations. This is necessary in order
     43     to get geometries for ways and relations.
     44 """
     45 if not (self._entities & osmium.osm.NODE):
---> 46     raise RuntimeError('Nodes not read from file. Cannot enable location cache.')
     47 if isinstance(storage, str):
     48     self._node_store = osmium.index.create_map(storage)


RuntimeError: Nodes not read from file. Cannot enable location cache.

```

--------------------------------

### open_url(url: urlrequest.Request) -> Any

Source: https://docs.osmcode.org/pyosmium/latest/reference/Replication

Downloads a resource from the given URL and returns its content as a byte sequence.

```APIDOC
## open_url(url: urlrequest.Request) -> Any

### Description
Download a resource from the given URL and return a byte sequence of the content.

### Parameters
- **url** (urlrequest.Request) - Required - The URL to download.

### Returns
- **Any** - The content of the resource as a byte sequence.
```

--------------------------------

### osmium.ForwardReferenceWriter.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/Data-Writers

Creates a new ForwardReferenceWriter instance. The output file must not exist unless overwrite is True. The reference source file provides the referenced objects.

```APIDOC
## osmium.ForwardReferenceWriter.__init__

### Description
Creates a new ForwardReferenceWriter instance. The output file must not exist unless overwrite is True. The reference source file provides the referenced objects.

### Method
Constructor

### Signature
`__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, thread_pool: Optional[ThreadPool] = None) -> None`

### Parameters
- **outfile** (Union[str, os.PathLike[str], File]) - Required - The name of the output file to write. The file must not yet exist unless `overwrite` is set to True.
- **ref_src** (Union[str, os.PathLike[str], File, FileBuffer]) - Required - The OSM input file from which to take reference objects. Usually the same file the data to be written is taken from.
- **overwrite** (bool) - Optional - If True, allows overwriting an existing output file. Default is False.
- **back_references** (bool) - Optional - If True (default), collects back-references to make the file reference-complete. Set to False to disable.
- **remove_tags** (bool) - Optional - If True (default), removes all tags from referenced objects. Set to False to keep tags.
- **forward_relation_depth** (int) - Optional - The minimum depth to which forward relations shall be completed. Default is 0.
- **backward_relation_depth** (int) - Optional - The minimum depth to which backward relations shall be completed. Default is 1.
- **thread_pool** (Optional[ThreadPool]) - Optional - An externally created thread pool to use for parallel IO. If not provided, a private ThreadPool is implicitly created.

### Response
None
```

--------------------------------

### osmium.BackReferenceWriter.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/Data-Writers

Creates a new BackReferenceWriter instance. The output file must not exist unless overwrite is True. The reference source file provides the referenced objects.

```APIDOC
## osmium.BackReferenceWriter.__init__

### Description
Creates a new BackReferenceWriter instance. The output file must not exist unless overwrite is True. The reference source file provides the referenced objects.

### Method
Constructor

### Signature
`__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, thread_pool: Optional[ThreadPool] = None)`

### Parameters
- **outfile** (Union[str, os.PathLike[str], File]) - Required - The name of the output file to write. The file must not yet exist unless `overwrite` is set to True.
- **ref_src** (Union[str, os.PathLike[str], File, FileBuffer]) - Required - The OSM input file from which to take reference objects. Usually the same file the data to be written is taken from.
- **overwrite** (bool) - Optional - If True, allows overwriting an existing output file. Default is False.
- **remove_tags** (bool) - Optional - If True (default), removes all tags from referenced objects so they do not appear as stray objects. Set to False to keep tags.
- **relation_depth** (int) - Optional - The minimum depth to which relations shall be completed. Default is 0 (no nested relations).
- **thread_pool** (Optional[ThreadPool]) - Optional - An externally created thread pool to use for parallel IO. If not provided, a private ThreadPool is implicitly created.

### Response
None
```

--------------------------------

### Filter schools with KeyFilter and write with BackReferenceWriter

Source: https://docs.osmcode.org/pyosmium/latest/cookbooks/Filtering-Data-By-Tags

Creates a FileProcessor with a KeyFilter for the 'amenity' key, then uses BackReferenceWriter to write a referentially complete file of schools. The BackReferenceWriter collects references to ensure all referenced objects are included.

```python
fp = osmium.FileProcessor('../data/liechtenstein.osm.pbf').with_filter(osmium.filter.KeyFilter('amenity'))

with osmium.BackReferenceWriter("../data/out/schools_full.osm.pbf", ref_src='../data/liechtenstein.osm.pbf', overwrite=True) as writer:
    for obj in fp:
         if obj.tags['amenity'] == 'school':
             writer.add(obj)

```

--------------------------------

### osmium.make_simple_handler

Source: https://docs.osmcode.org/pyosmium/latest/reference/Handler-Processing

Creates a SimpleHandler from callback functions.

```APIDOC
## osmium.make_simple_handler

### Description
Deprecated 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.

### Method
make_simple_handler

### Parameters
- **node** (HandlerFunc[Node]) - Optional - Callback for node objects.
- **way** (HandlerFunc[Way]) - Optional - Callback for way objects.
- **relation** (HandlerFunc[Relation]) - Optional - Callback for relation objects.
- **area** (HandlerFunc[Area]) - Optional - Callback for area objects.
- **changeset** (HandlerFunc[Changeset]) - Optional - Callback for changeset objects.

### Return Value
SimpleHandler
```

--------------------------------

### Custom DateFilter for FileProcessor

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/04-Working-with-Filters

Defines a Python filter class with a node() callback that returns True for nodes older than 2020, causing them to be filtered out. The example then uses osmium.FileProcessor with the filter to count total objects and objects without old nodes.

```python
import datetime as dt

class DateFilter:

    def node(self, n):
        return n.timestamp < dt.datetime(2020, 1, 1, tzinfo=dt.UTC)


print("Total number of objects:",
      sum(1 for o in osmium.FileProcessor('../data/liechtenstein.osm.pbf')))

print("Without nodes older than 2020:",
      sum(1 for o in osmium.FileProcessor('../data/liechtenstein.osm.pbf')
                           .with_filter(DateFilter())))

```

--------------------------------

### Correct filtered processing with handler_for_filtered and KeyFilter

Source: https://docs.osmcode.org/pyosmium/latest/cookbooks/Enhance-Tags

Correct version of the filtered processing example. The FileProcessor is configured with a KeyFilter and the SimpleWriter as the handler for filtered objects, so only objects with 'name:fr' are processed in the loop. The loop removes the tag and writes the modified object.

```python
with osmium.SimpleWriter('../data/out/buildings.opl', overwrite=True) as writer:
    fp = osmium.FileProcessor('../data/liechtenstein.osm.pbf')\
               .with_filter(osmium.filter.KeyFilter('name:fr'))\
               .handler_for_filtered(writer)
    for obj in fp:
        tags = {k: v for k, v in obj.tags if k != 'name:fr'}
        # ... do more stuff here
        writer.add(obj.replace(tags=tags))

```

--------------------------------

### osmium.io.ThreadPool.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/IO

Creates a new ThreadPool with the specified number of threads and worker queue size. Allows fine-grained control over thread usage.

```APIDOC
## osmium.io.ThreadPool.__init__

### Description
Creates a new ThreadPool with the given number of threads and a worker queue with the given maximum size. The number of threads can be specified directly or via environment variables.

### Method
Constructor

### Signature
`__init__(num_threads: int = 0, max_queue_size: int = 0) -> None`

### Parameters
- **num_threads** (int) - Optional - Number of threads. Negative value leaves that many cores unused. 0 uses OSMIUM_POOL_THREADS environment variable or defaults to -2 (all cores except two).
- **max_queue_size** (int) - Optional - Maximum number of data buffers in the queue. 0 reads from OSMIUM_MAX_WORK_QUEUE_SIZE environment variable or defaults to 10.

### Notes
- Minimum number of threads is 1.

```

--------------------------------

### osmium.SimpleWriter.__init__

Source: https://docs.osmcode.org/pyosmium/latest/reference/Data-Writers

Constructor for the SimpleWriter class, used to initialize a writer for OSM data output.

```APIDOC
## osmium.SimpleWriter.__init__

### Description
Initializes a new SimpleWriter for writing OSM data to a file. The writer will refuse to overwrite an existing file unless overwrite is set to True. The file type is usually determined from the file extension, but can be explicitly set using a File object.

### Method
Constructor

### Signature
`__init__(file: Union[str, os.PathLike[str], File], bufsz: int = 4096 * 1024, header: Optional[Header] = None, overwrite: bool = False, thread_pool: Optional[ThreadPool] = None) -> None`

### Parameters
- **file** (Union[str, os.PathLike[str], File]) - Required - The file to write to. Can be a path string, a path-like object, or a File object.
- **bufsz** (int) - Optional - Size of the buffers used for collecting data before writing. Default is 4MB.
- **header** (Optional[Header]) - Optional - Custom header to write into the output file. The kind of information depends on the file type.
- **overwrite** (bool) - Optional - If True, allows overwriting an existing file. Default is False.
- **thread_pool** (Optional[ThreadPool]) - Optional - An externally created thread pool to use for parallel writing. If not provided, a private thread pool is created implicitly.

### Usage Example
```python
with osmium.SimpleWriter('output.osm.pbf') as writer:
    # write objects
    pass
```
```

--------------------------------

### IdFilter: Find a single object by ID

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/04-Working-with-Filters

IdFilter takes an iterable of numbers and passes only objects whose ID matches. This example filters for way ID 1 in the file 'buildings.opl'. Note that this is inefficient for finding a single object because the entire file is scanned.

```python
fp = osmium.FileProcessor('../data/buildings.opl')\
           .with_filter(osmium.filter.EntityFilter(osmium.osm.WAY))\
           .with_filter(osmium.filter.IdFilter([1]))

for o in fp:
    print(o)

```

--------------------------------

### Cache place nodes with PlaceNodeReader and osmium.apply

Source: https://docs.osmcode.org/pyosmium/latest/cookbooks/Adding-Node-Infos-To-Boundaries

Defines a handler class that caches place nodes keyed by their wikidata tag. Uses osmium.apply with two KeyFilter instances to pass only nodes having both 'place' and 'wikidata' tags, then prints the number of cached places. The output '29 places cached.' is shown after the code.

```python
class PlaceNodeReader:

    def __init__(self):
        self.places = {}

    def node(self, n):
        self.places[n.tags['wikidata']] = PlaceInfo(n.id, dict(n.tags), (n.location.lon, n.location.lat))

reader = PlaceNodeReader()

osmium.apply('../data/liechtenstein.osm.pbf',
             osmium.filter.KeyFilter('place').enable_for(osmium.osm.NODE),
             osmium.filter.KeyFilter('wikidata').enable_for(osmium.osm.NODE),
             reader)

print(f"{len(reader.places)} places cached.")
```

```output
29 places cached.
```

--------------------------------

### Buggy example: storing OSM object views causes RuntimeError

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/01-First-Steps

Attempts to store OSM object views in a dictionary and access them after the loop. This fails with a RuntimeError because the views are invalidated once the buffer is gone. Demonstrates that you must copy needed data inside the loop.

```python
# saves object by their type, more about types later
objects = {'n' : [], 'w': [], 'r': []}

for obj in osmium.FileProcessor('buildings.opl'):
    objects[obj.type_str()].append(obj)

for otype, olist in objects.items():
    print(f"{otype}: {','.join(o.id for o in olist)}")

```

```text
Traceback (most recent call last):
  File "bad_ref.py", line 10, in <module>
    print(f"{otype}: {','.join(o.id for o in olist)}")
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "bad_ref.py", line 10, in <genexpr>
    print(f"{otype}: {','.join(o.id for o in olist)}")
                               ^^^^
  File "osmium/osm/types.py", line 313, in id
    return self._pyosmium_data.id()
           ^^^^^^^^^^^^^^^^^^^^^^^^
RuntimeError: Illegal access to removed OSM object

```

--------------------------------

### Import PyOsmium and defaultdict

Source: https://docs.osmcode.org/pyosmium/latest/cookbooks/Adding-Route-Info-To-Ways

Imports the osmium module and defaultdict from collections for use in the script.

```python
import osmium
from collections import defaultdict
```

--------------------------------

### osmium.apply

Source: https://docs.osmcode.org/pyosmium/latest/reference/Handler-Processing

Applies a chain of handlers to an input source.

```APIDOC
## osmium.apply

### Description
Applies a chain of handlers to the given input source. The input source may be a osmium.io.Reader, a file or a file buffer. If one of the handlers is a filter, then processing of the object will be stopped when it does not pass the filter.

### Method
apply

### Parameters
- **reader** (Union[Reader, str, os.PathLike[str], File, FileBuffer]) - Required - The input source.
- **handlers** (HandlerLike) - Required - One or more handlers to apply.

### Return Value
None
```

--------------------------------

### Generate WKT polygon from area rings using outer_rings() and inner_rings()

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/03-Working-with-Geometries

Iterate over outer and inner rings of an area to build a WKT representation. The code checks is_area(), uses outer_rings() and inner_rings(), and prints a POLYGON or MULTIPOLYGON string. The output shows example WKT for areas 2 and 3.

```python
for o in osmium.FileProcessor('../data/buildings.opl').with_areas():
    if o.is_area():
        polygons = []
        for outer in o.outer_rings():
            rings = "(" + ", ".join((f"{n.lon} {n.lat}" for n in outer if n.location.valid())) + ")"
            for inner in o.inner_rings(outer):
                rings += ", (" + ", ".join((f"{n.lon} {n.lat}" for n in outer if n.location.valid())) + ")"
            polygons.append(rings)
        if o.is_multipolygon():
            wkt = f"MULTIPOLYGON(({'), ('.join(polygons)}))"
        else:
            wkt = f"POLYGON({polygons[0]})"
        print(f"Area {o.id}: {wkt}")        

```

```output
Area 2: POLYGON((45.0 13.0, 45.0001 13.0, 45.0001 13.0001, 45.0 13.0001, 45.0 13.0))
Area 3: POLYGON((45.0 13.0, 45.0001 13.0, 45.0001 13.0001, 45.0 13.0001, 45.0 13.0), (45.0 13.0, 45.0001 13.0, 45.0001 13.0001, 45.0 13.0001, 45.0 13.0))

```

--------------------------------

### Mix filters and handlers in osmium.apply

Source: https://docs.osmcode.org/pyosmium/latest/user_manual/05-Working-with-Handlers

Shows how to pass filters and custom handlers to osmium.apply. Filters stop processing for filtered objects, and handlers execute in the order given.

```python
osmium.apply('buildings.opl',
             osmium.filter.EntityFilter(osmium.osm.RELATION),
             my_handler,
             osmium.filter.KeyFilter('route')),
             my_other_handler

```