reorganise main includes

Avoid any clutter in the main 'osmium' module as far as possible.

lib/osmium.cc

@@ -107,7 +107,10 @@ PYBIND11_MODULE(_osmium, m) {
           py::arg("filename"),
           "Apply a chain of handlers.");
 
-    py::class_<pyosmium::BaseHandler>(m, "BaseHandler");
+    py::class_<pyosmium::BaseHandler>(m, "BaseHandler",
+             "Base class for all handlers in pyosmium. Any class inheriting "
+             "from this class can be used in functions that require a "
+             "handler-like object.");
     py::class_<pyosmium::BaseFilter, pyosmium::BaseHandler>(m, "BaseFilter")
         .def("enable_for", &pyosmium::BaseFilter::enable_for,
              py::arg("entities"),

src/osmium/__init__.py

@@ -4,51 +4,27 @@
 #
 # Copyright (C) 2024 Sarah Hoffmann <[email protected]> and others.
 # For a full list of authors see the git log.
-from typing import Any
 
-from osmium._osmium import *
-from osmium.helper import *
-from osmium.simple_handler import SimpleHandler
-from osmium.file_processor import FileProcessor, zip_processors
-from osmium.back_reference_writer import BackReferenceWriter
-from osmium.forward_reference_writer import ForwardReferenceWriter
+from ._osmium import (InvalidLocationError as InvalidLocationError,
+                      apply as apply,
+                      BaseHandler as BaseHandler,
+                      BaseFilter as BaseFilter,
+                      BufferIterator as BufferIterator,
+                      SimpleWriter as SimpleWriter,
+                      NodeLocationsForWays as NodeLocationsForWays,
+                      OsmFileIterator as OsmFileIterator,
+                      IdTracker as IdTracker)
+from .helper import (make_simple_handler as make_simple_handler,
+                     WriteHandler as WriteHandler,
+                     MergeInputReader as MergeInputReader)
+from .simple_handler import (SimpleHandler as SimpleHandler)
+from .file_processor import (FileProcessor as FileProcessor,
+                             zip_processors as zip_processors)
+from .back_reference_writer import BackReferenceWriter as BackReferenceWriter
+from .forward_reference_writer import ForwardReferenceWriter as ForwardReferenceWriter
 import osmium.io
 import osmium.osm
 import osmium.index
 import osmium.geom
 import osmium.area
 import osmium.filter
-
-# WriteHandler no longer exists. SimpleWriter can now function as a handler.
-class WriteHandler(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.
-    """
-
-    def __init__(self, filename: str, bufsz: int=4096*1024, filetype: str="") -> None:
-        super().__init__(filename, bufsz=bufsz, filetype=filetype)
-
-
-def _merge_apply(self: osmium.MergeInputReader, *handlers: Any, idx: str = '', simplify: bool = True) -> None:
-    """ Apply collected data to a handler. The data will be sorted first.
-        If `simplify` is true (default) then duplicates will be eliminated
-        and only the newest version of each object kept. If `idx` is given
-        a node location cache with the given type will be created and
-        applied when creating the ways. Note that a diff file normally does
-        not contain all node locations to reconstruct changed ways. If the
-        full way geometries are needed, create a persistent node location
-        cache during initial import of the area and reuse it when processing
-        diffs. After the data
-        has been applied the buffer of the MergeInputReader is empty and
-        new data can be added for the next round of application.
-    """
-    if idx:
-        lh = NodeLocationsForWays(osmium.index.create_map(idx))
-        lh.ignore_errors()
-        self._apply_internal(lh, *handlers, simplify=simplify)
-
-    self._apply_internal(*handlers, simplify=simplify)
-
-osmium.MergeInputReader.apply = _merge_apply # type: ignore[method-assign]

src/osmium/area.pyi

@@ -5,7 +5,8 @@
 # Copyright (C) 2024 Sarah Hoffmann <[email protected]> and others.
 # For a full list of authors see the git log.
 
-from . import BaseHandler, HandlerLike, BufferIterator
+from . import BaseHandler, BufferIterator
+from ._osmium import HandlerLike
 
 class AreaManagerSecondPassHandler(BaseHandler): ...
 

src/osmium/helper.py

@@ -4,10 +4,17 @@
 #
 # Copyright (C) 2024 Sarah Hoffmann <[email protected]> and others.
 # For a full list of authors see the git log.
-from typing import Optional, Callable, TypeVar
+from typing import Optional, Callable, TypeVar, TYPE_CHECKING
 
-from osmium.simple_handler import SimpleHandler
-from osmium.osm import Node, Way, Relation, Area, Changeset
+from .simple_handler import SimpleHandler
+from .osm import Node, Way, Relation, Area, Changeset
+from .index import create_map
+from ._osmium import SimpleWriter, NodeLocationsForWays
+
+from ._osmium import MergeInputReader as MergeInputReader
+
+if TYPE_CHECKING:
+    from ._osmium import HandlerLike
 
 T = TypeVar('T')
 HandlerFunc = Optional[Callable[[T], None]]
@@ -38,3 +45,38 @@ class __HandlerWithCallbacks(SimpleHandler):
         setattr(__HandlerWithCallbacks, "changeset", staticmethod(changeset))
 
     return __HandlerWithCallbacks()
+
+
+# WriteHandler no longer exists. SimpleWriter can now function as a handler.
+class WriteHandler(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.
+    """
+
+    def __init__(self, filename: str, bufsz: int=4096*1024, filetype: str="") -> None:
+        super().__init__(filename, bufsz=bufsz, filetype=filetype)
+
+
+def _merge_apply(self: MergeInputReader, *handlers: 'HandlerLike', idx: str = '', simplify: bool = True) -> None:
+    """ Apply collected data to a handler. The data will be sorted first.
+        If `simplify` is true (default) then duplicates will be eliminated
+        and only the newest version of each object kept. If `idx` is given
+        a node location cache with the given type will be created and
+        applied when creating the ways. Note that a diff file normally does
+        not contain all node locations to reconstruct changed ways. If the
+        full way geometries are needed, create a persistent node location
+        cache during initial import of the area and reuse it when processing
+        diffs. After the data
+        has been applied the buffer of the MergeInputReader is empty and
+        new data can be added for the next round of application.
+    """
+    if idx:
+        lh = NodeLocationsForWays(create_map(idx))
+        lh.ignore_errors()
+        self._apply_internal(lh, *handlers, simplify=simplify)
+
+    self._apply_internal(*handlers, simplify=simplify)
+
+MergeInputReader.apply = _merge_apply # type: ignore[method-assign]