enable CI tests for Ubuntu 24

[nominatim.git] / docs / library / Getting-Started.md

diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md
index 88f25eb6ae47f7da198b075713de421c533336b1..22d9681d6fd119c42e67a5b605e47633a870e5ed 100644 (file)
--- a/docs/library/Getting-Started.md
+++ b/docs/library/Getting-Started.md
@@ -12,22 +12,18 @@ in the database.
     The library interface is currently in an experimental stage. There might
     be some smaller adjustments to the public interface until the next version.
 
     The library interface is currently in an experimental stage. There might
     be some smaller adjustments to the public interface until the next version.
 

-    The library also misses a proper installation routine, so some manipulation
-    of the PYTHONPATH is required. At the moment, use is only recommended for
-    developers wit some experience in Python.
-

 ## Installation
 
 To use the Nominatim library, you need access to a local Nominatim database.
 ## Installation
 
 To use the Nominatim library, you need access to a local Nominatim database.

-Follow the [installation and import instructions](../admin/) to set up your
-database.
+Follow the [installation](../admin/Installation.md) and
+[import](../admin/Import.md) instructions to set up your database.
+
+The Nominatim frontend library is contained in the 'nominatim-api' package.
+To install the package from the source tree directly, run:
+
+    pip install packaging/nominatim-api

 
 

-It is not yet possible to install it in the usual way via pip or inside a
-virtualenv. To get access to the library you need to set an appropriate
-PYTHONPATH. With the default installation, the python library can be found
-under `/usr/local/share/nominatim/lib-python`. If you have installed
-Nominatim under a different prefix, adapt the `/usr/local/` part accordingly.
-You can also point the PYTHONPATH to the Nominatim source code.
+Usually, you would want to run this in a virtual environment.

 
 ### A simple search example
 
 
 ### A simple search example
 


@@ -35,7 +31,7 @@ To query the Nominatim database you need to first set up a connection. This
 is done by creating an Nominatim API object. This object exposes all the
 search functions of Nominatim that are also known from its web API.
 
 is done by creating an Nominatim API object. This object exposes all the
 search functions of Nominatim that are also known from its web API.
 

-This code snippet implements a simple search for the town if 'Brugge':
+This code snippet implements a simple search for the town of 'Brugge':

 
 !!! example
     === "NominatimAPIAsync"
 
 !!! example
     === "NominatimAPIAsync"


@@ -43,7 +39,7 @@ This code snippet implements a simple search for the town if 'Brugge':
         from pathlib import Path
         import asyncio
 
         from pathlib import Path
         import asyncio
 

-        import nominatim.api as napi
+        import nominatim_api as napi

 
         async def search(query):
             api = napi.NominatimAPIAsync(Path('.'))
 
         async def search(query):
             api = napi.NominatimAPIAsync(Path('.'))


@@ -61,7 +57,7 @@ This code snippet implements a simple search for the town if 'Brugge':
         ``` python
         from pathlib import Path
 
         ``` python
         from pathlib import Path
 

-        import nominatim.api as napi
+        import nominatim_api as napi

 
         api = napi.NominatimAPI(Path('.'))
 
 
         api = napi.NominatimAPI(Path('.'))
 


@@ -103,7 +99,7 @@ You should have set up this directory as part of the Nominatim import.
 Any configuration found in the `.env` file in this directory will automatically
 used.
 
 Any configuration found in the `.env` file in this directory will automatically
 used.
 

-Yo may also configure Nominatim be setting environment variables.
+You may also configure Nominatim by setting environment variables.

 Normally, Nominatim will check the operating system environment. This can be
 overwritten by giving the constructor a dictionary of configuration parameters.
 
 Normally, Nominatim will check the operating system environment. This can be
 overwritten by giving the constructor a dictionary of configuration parameters.
 


@@ -116,7 +112,7 @@ standard 'nominatim' database:
         from pathlib import Path
         import asyncio
 
         from pathlib import Path
         import asyncio
 

-        import nominatim.api as napi
+        import nominatim_api as napi

 
         config_params = {
             'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
 
         config_params = {
             'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'


@@ -134,7 +130,7 @@ standard 'nominatim' database:
         ``` python
         from pathlib import Path
 
         ``` python
         from pathlib import Path
 

-        import nominatim.api as napi
+        import nominatim_api as napi

 
         config_params = {
             'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'
 
         config_params = {
             'NOMINATIM_DATABASE_DSN': 'pgsql:dbname=belgium'


@@ -161,7 +157,7 @@ Again searching for 'Brugge', this time with a nicely formatted result:
         from pathlib import Path
         import asyncio
 
         from pathlib import Path
         import asyncio
 

-        import nominatim.api as napi
+        import nominatim_api as napi

 
         async def search(query):
             api = napi.NominatimAPIAsync(Path('.'))
 
         async def search(query):
             api = napi.NominatimAPIAsync(Path('.'))


@@ -180,7 +176,7 @@ Again searching for 'Brugge', this time with a nicely formatted result:
         ``` python
         from pathlib import Path
 
         ``` python
         from pathlib import Path
 

-        import nominatim.api as napi
+        import nominatim_api as napi

 
         api = napi.NominatimAPI(Path('.'))
 
 
         api = napi.NominatimAPI(Path('.'))
 


@@ -219,7 +215,7 @@ creates a helper class that returns the name preferably in French. If that is
 not possible, it tries English and eventually falls back to the default `name`
 or `ref`.
 
 not possible, it tries English and eventually falls back to the default `name`
 or `ref`.
 

-The Locale object can be applied to a name dictionary to return the best-matching
+The `Locale` object can be applied to a name dictionary to return the best-matching

 name out of it:
 
 ``` python
 name out of it:
 
 ``` python