From a987f22cfb7343289ff4ea42d8cf6979636e9c00 Mon Sep 17 00:00:00 2001 From: Sarah Hoffmann Date: Wed, 23 Aug 2023 00:23:40 +0200 Subject: [PATCH 1/1] more library documentation --- docs/library/Input-Parameter-Types.md | 27 ++++++++++++-- docs/library/Low-Level-DB-Access.md | 51 ++++++++++++++++++++++++++ docs/library/Result-Handling.md | 4 +++ nominatim/api/core.py | 6 ++-- nominatim/api/types.py | 52 ++++++++++++++++++++++++--- 5 files changed, 131 insertions(+), 9 deletions(-) diff --git a/docs/library/Input-Parameter-Types.md b/docs/library/Input-Parameter-Types.md index e6b5138c..dae560b2 100644 --- a/docs/library/Input-Parameter-Types.md +++ b/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 diff --git a/docs/library/Low-Level-DB-Access.md b/docs/library/Low-Level-DB-Access.md index 371989eb..5101777e 100644 --- a/docs/library/Low-Level-DB-Access.md +++ b/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 diff --git a/docs/library/Result-Handling.md b/docs/library/Result-Handling.md index 8c9972b6..e2e0bc91 100644 --- a/docs/library/Result-Handling.md +++ b/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 diff --git a/nominatim/api/core.py b/nominatim/api/core.py index fb03d2df..f17973dc 100644 --- a/nominatim/api/core.py +++ b/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: diff --git a/nominatim/api/types.py b/nominatim/api/types.py index 214dcab8..1927f69a 100644 --- a/nominatim/api/types.py +++ b/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): -- 2.39.5