more library documentation

docs/library/Input-Parameter-Types.md

@@ -1,28 +1,51 @@
-# Input parameters
+# Input Parameter Types
+
+This page describes in more detail some of the input parameter types used
+in the query functions of the API object.
 
 ## Place identification
 
+The [details](NominatimAPI.md#nominatim.api.core.NominatimAPI.details) and
+[lookup](NominatimAPI.md#nominatim.api.core.NominatimAPI.lookup) functions
+require references to places in the database. Below are listed the possible
+types for place identification. All types are dataclasses.
+
+### PlaceID
+
 ::: nominatim.api.PlaceID
     options:
         heading_level: 6
 
+### OsmID
+
 ::: nominatim.api.OsmID
     options:
         heading_level: 6
 
-## Geometries
+## Geometry types
 
 ::: nominatim.api.GeometryFormat
     options:
         heading_level: 6
+        members_order: source
+
+## Geometry input
+
+### Point
 
 ::: nominatim.api.Point
     options:
         heading_level: 6
+        show_signature_annotations: True
+
+### Bbox
 
 ::: nominatim.api.Bbox
     options:
         heading_level: 6
+        show_signature_annotations: True
+        members_order: source
+        group_by_category: False
 
 ## Layers
 

docs/library/Low-Level-DB-Access.md

@@ -1,5 +1,56 @@
 # Low-level connections
 
+The `NominatimAPIAsync` class allows to directly access the underlying
+database connection to explore the data more directly. Nominatim uses
+[SQLAlchemy](https://docs.sqlalchemy.org/) for building queries. Please
+refer to the documentation of the library to understand how to write SQL.
+
+To get access to a search connection, use the `begin()` function of your
+API object. The function returns a context manager. Use with a `with`
+statement. This returns a `SearchConnection` object described below. Its
+`t` property has definitions for all Nominatim search tables. For an
+overview of available tables, refer to the
+[Development Layout](../develop/Database-Layout.md) in in the development
+chapter. Note that only tables that are needed for search are accessible
+as SQLAlchemy tables.
+
+!!! warning
+    The database layout is not part of the API definition and may change
+    without notice. If you play with the low-level access functions, you
+    need to be prepared for such changes.
+
+Here is a simple example, which prints how many places are available in
+the placex table:
+
+```
+import asyncio
+from pathlib import Path
+import sqlalchemy as sa
+from nominatim.api import NominatimAPIAsync
+
+async def print_table_size():
+    api = NominatimAPIAsync(Path('.'))
+
+    async with api.begin() as conn:
+        cnt = await conn.scalar(sa.select(sa.func.count()).select_from(conn.t.placex))
+        print(f'placex table has {cnt} rows.')
+
+asyncio.run(print_table_size())
+```
+
+!!! warning
+    Low-level connections may only be used to read data from the database.
+    Do not use it to add or modify data or you might break Nominatim's
+    normal functions.
+
+## SearchConnection class
+
 ::: nominatim.api.SearchConnection
     options:
+        members:
+            - scalar
+            - execute
+            - get_class_table
+            - get_db_property
+            - get_property
         heading_level: 6

docs/library/Result-Handling.md

@@ -14,6 +14,10 @@
 
 ## Localization
 
+Results are always returned with the full list of available names.
+
+### Locale
+
 ::: nominatim.api.Locales
     options:
         heading_level: 6

nominatim/api/core.py

@@ -373,7 +373,8 @@ class NominatimAPI:
             or `None` if the place could not be found in the database.
 
             Parameters:
-              place: Description of the place to look up. See PlaceRef below
+              place: Description of the place to look up. See
+                     [Place identification](Input-Parameter-Types.md#place-identification)
                      for the various ways to reference a place.
 
             Other parameters:
@@ -455,7 +456,8 @@ class NominatimAPI:
             Each result is a dataclass with the fields detailed below.
 
             Parameters:
-              places: List of descriptions of the place to look up. See PlaceRef below
+              places: List of descriptions of the place to look up. See
+                      [Place identification](Input-Parameter-Types.md#place-identification)
                       for the various ways to reference a place.
 
             Other parameters:

nominatim/api/types.py

@@ -22,18 +22,40 @@ from nominatim.errors import UsageError
 
 @dataclasses.dataclass
 class PlaceID:
-    """ Reference an object by Nominatim's internal ID.
+    """ Reference a place by Nominatim's internal ID.
+
+        A PlaceID may reference place from the main table placex, from
+        the interpolation tables or the postcode tables. Place IDs are not
+        stable between installations. You may use this type theefore only
+        with place IDs obtained from the same database.
     """
     place_id: int
+    """
+    The internal ID of the place to reference.
+    """
 
 
 @dataclasses.dataclass
 class OsmID:
-    """ Reference by the OSM ID and potentially the basic category.
+    """ Reference a place by its OSM ID and potentially the basic category.
+
+        The OSM ID may refer to places in the main table placex and OSM
+        interpolation lines.
     """
     osm_type: str
+    """ OSM type of the object. Must be one of `N`(node), `W`(way) or
+        `R`(relation).
+    """
     osm_id: int
+    """ The OSM ID of the object.
+    """
     osm_class: Optional[str] = None
+    """ The same OSM object may appear multiple times in the database under
+        different categories. The optional class parameter allows to distinguish
+        the different categories and corresponds to the key part of the category.
+        If there are multiple objects in the database and `osm_class` is
+        left out, then one of the objects is returned at random.
+    """
 
     def __post_init__(self) -> None:
         if self.osm_type not in ('N', 'W', 'R'):
@@ -135,12 +157,15 @@ WKB_BBOX_HEADER_LE = b'\x01\x03\x00\x00\x20\xE6\x10\x00\x00\x01\x00\x00\x00\x05\
 WKB_BBOX_HEADER_BE = b'\x00\x20\x00\x00\x03\x00\x00\x10\xe6\x00\x00\x00\x01\x00\x00\x00\x05'
 
 class Bbox:
-    """ A bounding box in WSG84 projection.
+    """ A bounding box in WGS84 projection.
 
         The coordinates are available as an array in the 'coord'
         property in the order (minx, miny, maxx, maxy).
     """
     def __init__(self, minx: float, miny: float, maxx: float, maxy: float) -> None:
+        """ Create a new bounding box with the given coordinates in WGS84
+            projection.
+        """
         self.coords = (minx, miny, maxx, maxy)
 
 
@@ -197,7 +222,7 @@ class Bbox:
     @staticmethod
     def from_wkb(wkb: Union[None, str, bytes]) -> 'Optional[Bbox]':
         """ Create a Bbox from a bounding box polygon as returned by
-            the database. Return s None if the input value is None.
+            the database. Returns `None` if the input value is None.
         """
         if wkb is None:
             return None
@@ -259,13 +284,30 @@ class Bbox:
 
 
 class GeometryFormat(enum.Flag):
-    """ Geometry output formats supported by Nominatim.
+    """ All search functions support returning the full geometry of a place in
+        various formats. The internal geometry is converted by PostGIS to
+        the desired format and then returned as a string. It is possible to
+        request multiple formats at the same time.
     """
     NONE = 0
+    """ No geometry requested. Alias for a empty flag.
+    """
     GEOJSON = enum.auto()
+    """
+    [GeoJSON](https://geojson.org/) format
+    """
     KML = enum.auto()
+    """
+    [KML](https://en.wikipedia.org/wiki/Keyhole_Markup_Language) format
+    """
     SVG = enum.auto()
+    """
+    [SVG](http://www.w3.org/TR/SVG/paths.html) format
+    """
     TEXT = enum.auto()
+    """
+    [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) format
+    """
 
 
 class DataLayer(enum.Flag):