From: Sarah Hoffmann Date: Tue, 29 Aug 2023 10:14:44 +0000 (+0200) Subject: fix typos and grammar issues X-Git-Tag: v4.3.0~13^2 X-Git-Url: https://git.openstreetmap.org./nominatim.git/commitdiff_plain/cafd8e2b1ed6ce823fb0bf66673d98450372457c fix typos and grammar issues --- diff --git a/docs/admin/Deployment-PHP.md b/docs/admin/Deployment-PHP.md index 0e253d3d..92c1a4ec 100644 --- a/docs/admin/Deployment-PHP.md +++ b/docs/admin/Deployment-PHP.md @@ -13,8 +13,8 @@ to run a web service. Please refer to the documentation of for background information on configuring the services. !!! Note - Throughout this page, we assume that your Nominatim project directory is - located in `/srv/nominatim-project` and that you have installed Nominatim + Throughout this page, we assume your Nominatim project directory is + located in `/srv/nominatim-project` and you have installed Nominatim using the default installation prefix `/usr/local`. If you have put it somewhere else, you need to adjust the commands and configuration accordingly. diff --git a/docs/admin/Deployment-Python.md b/docs/admin/Deployment-Python.md index fcbe9486..c3cca59b 100644 --- a/docs/admin/Deployment-Python.md +++ b/docs/admin/Deployment-Python.md @@ -1,16 +1,18 @@ # Deploying the Nominatim Python frontend -The Nominatim can be run as a Python-based web application. You have the +The Nominatim can be run as a Python-based +[ASGI web application](https://asgi.readthedocs.io/en/latest/). You have the choice between [Falcon](https://falcon.readthedocs.io/en/stable/) and [Starlette](https://www.starlette.io/) as the ASGI framework. -This section gives a quick overview on how to configure Nginx to server +This section gives a quick overview on how to configure Nginx to serve Nominatim. Please refer to the documentation of -[Nginx](https://nginx.org/en/docs/) for background information on how to configure it. +[Nginx](https://nginx.org/en/docs/) for background information on how +to configure it. !!! Note - Throughout this page, we assume that your Nominatim project directory is - located in `/srv/nominatim-project` and that you have installed Nominatim + Throughout this page, we assume your Nominatim project directory is + located in `/srv/nominatim-project` and you have installed Nominatim using the default installation prefix `/usr/local`. If you have put it somewhere else, you need to adjust the commands and configuration accordingly. @@ -21,7 +23,7 @@ Nominatim. Please refer to the documentation of ### Installing the required packages -The recommended way to deploy Python ASGI application is to run +The recommended way to deploy a Python ASGI application is to run the ASGI runner (uvicorn)[https://uvicorn.org/] together with (gunicorn)[https://gunicorn.org/] HTTP server. We use Falcon here as the web framework. @@ -38,7 +40,7 @@ virtualenv /srv/nominatim-venv ### Setting up Nominatim as a systemd job -Next you need to set up the application that serves Nominatim. This is +Next you need to set up the service that runs the Nominatim frontend. This is easiest done with a systemd job. Create the following file `/etc/systemd/system/nominatim.service`: @@ -55,9 +57,9 @@ Environment="PYTHONPATH=/usr/local/lib/nominatim/lib-python/" User=www-data Group=www-data WorkingDirectory=/srv/nominatim-project -ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 14 -k uvicorn.workers.UvicornWorker nominatim.server.falcon.server:run_wsgi +ExecStart=/srv/nominatim-venv/bin/gunicorn -b unix:/run/nominatim.sock -w 4 -k uvicorn.workers.UvicornWorker nominatim.server.falcon.server:run_wsgi ExecReload=/bin/kill -s HUP $MAINPID -StandardOutput=append:/ssd/nominatim/log/gunicorn.log +StandardOutput=append:/var/log/gunicorn-nominatim.log StandardError=inherit PrivateTmp=true TimeoutStopSec=5 @@ -67,6 +69,11 @@ KillMode=mixed WantedBy=multi-user.target ``` +This sets up gunicorn with 4 workers (`-w 4` in ExecStart). Each worker runs +its own Python process using +[`NOMINATIM_API_POOL_SIZE`](../customize/Settings.md#nominatim_api_pool_size) +connections to the database to serve requests in parallel. + Make the new service known to systemd and start it: ``` sh diff --git a/docs/admin/Import.md b/docs/admin/Import.md index 7eb4d403..0fd5ec29 100644 --- a/docs/admin/Import.md +++ b/docs/admin/Import.md @@ -317,7 +317,7 @@ To run Nominatim via webservers like Apache or nginx, please continue reading ## Enabling search by category phrases -If you want to be able to search for places by their type using +To be able to search for places by their type using [special phrases](https://wiki.openstreetmap.org/wiki/Nominatim/Special_Phrases) you also need to import these key phrases like this: diff --git a/docs/api/Details.md b/docs/api/Details.md index 5992f952..c50378c5 100644 --- a/docs/api/Details.md +++ b/docs/api/Details.md @@ -2,12 +2,11 @@ Show all details about a single place saved in the database. -This API endpoint is meant for visual inspection of the data in the database -and is meant for use with [Nominatim-UI](https://github.com/osm-search/nominatim-ui/). +This API endpoint is meant for visual inspection of the data in the database, +mainly together with [Nominatim-UI](https://github.com/osm-search/nominatim-ui/). The parameters of the endpoint and the output may change occasionally between versions of Nominatim. Do not rely on the output in scripts or applications. - !!! warning The details endpoint at https://nominatim.openstreetmap.org may not used in scripts or bots at all. @@ -56,7 +55,7 @@ This section lists additional optional parameters. |-----------| ----- | ------- | | json_callback | function name | _unset_ | -When given, then JSON output will be wrapped in a callback function with +When set, then JSON output will be wrapped in a callback function with the given name. See [JSONP](https://en.wikipedia.org/wiki/JSONP) for more information. diff --git a/docs/api/Lookup.md b/docs/api/Lookup.md index 15b8c8c3..a2ba714e 100644 --- a/docs/api/Lookup.md +++ b/docs/api/Lookup.md @@ -114,7 +114,7 @@ options can be used at a time. |-----------| ----- | ------- | | polygon_threshold | floating-point number | 0.0 | -When one og the polygon_* outputs is chosen, return a simplified version +When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry. diff --git a/docs/api/Reverse.md b/docs/api/Reverse.md index 27d0b60c..548b245c 100644 --- a/docs/api/Reverse.md +++ b/docs/api/Reverse.md @@ -153,17 +153,17 @@ The layers filter allows to select places by themes. The `address` layer contains all places that make up an address: address points with house numbers, streets, inhabited places (suburbs, villages, -cities, states tec.) and administrative boundaries. +cities, states etc.) and administrative boundaries. -The `poi` layer selects all point of interest. This includes classic POIs like -restaurants, shops, hotels but also less obvious features like recycling bins, -guideposts or benches. +The `poi` layer selects all point of interest. This includes classic points +of interest like restaurants, shops, hotels but also less obvious features +like recycling bins, guideposts or benches. The `railway` layer includes railway infrastructure like tracks. Note that in Nominatim's standard configuration, only very few railway features are imported into the database. -The `natural` layer collects feautures like rivers, lakes and mountains. While +The `natural` layer collects feautures like rivers, lakes and mountains while the `manmade` layer functions as a catch-all for features not covered by the other layers. @@ -185,7 +185,7 @@ options can be used at a time. |-----------| ----- | ------- | | polygon_threshold | floating-point number | 0.0 | -When one og the polygon_* outputs is chosen, return a simplified version +When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry. diff --git a/docs/api/Search.md b/docs/api/Search.md index 20a35b08..a45ec36f 100644 --- a/docs/api/Search.md +++ b/docs/api/Search.md @@ -201,7 +201,7 @@ The `railway` layer includes railway infrastructure like tracks. Note that in Nominatim's standard configuration, only very few railway features are imported into the database. -The `natural` layer collects feautures like rivers, lakes and mountains. While +The `natural` layer collects feautures like rivers, lakes and mountains while the `manmade` layer functions as a catch-all for features not covered by the other layers. @@ -271,7 +271,7 @@ options can be used at a time. |-----------| ----- | ------- | | polygon_threshold | floating-point number | 0.0 | -When one og the polygon_* outputs is chosen, return a simplified version +When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry. @@ -294,7 +294,7 @@ Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split into many different OSM ways due to different characteristics. Nominatim will attempt to detect such duplicates and only return one match. Setting -this parameter is set to 0 disables this deduplication mechanism and +this parameter to 0 disables this deduplication mechanism and ensures that all results are returned. | Parameter | Value | Default | diff --git a/docs/customize/Settings.md b/docs/customize/Settings.md index ef0e1f21..8245e309 100644 --- a/docs/customize/Settings.md +++ b/docs/customize/Settings.md @@ -650,8 +650,10 @@ versions of Nominatim. Sets the maximum number of database connections available for a single instance of Nominatim. When configuring the maximum number of connections that your -PostgreSQL database can handle, you need at least ` * ` -connections. +PostgreSQL database can handle, you need at least +`NOMINATIM_API_POOL_SIZE` * `` connections. +For configuring the number of workers, refer to the section about +[Deploying the Python frontend](../admin/Deployment-Python.md). #### NOMINATIM_QUERY_TIMEOUT @@ -744,6 +746,6 @@ This settings enables [SQL debugging](https://docs.sqlalchemy.org/en/20/core/engines.html#dbengine-logging) by SQLAlchemy. This can be helpful when debugging some bugs with internal query handling. It should only be used together with the CLI query functions. -Enabling it for server mode may have intended consequences. Use the `debug` +Enabling it for server mode may have unintended consequences. Use the `debug` parameter instead, which prints information on how the search is executed including SQL statements. diff --git a/docs/library/Configuration.md b/docs/library/Configuration.md index f673a27d..b97c2ccd 100644 --- a/docs/library/Configuration.md +++ b/docs/library/Configuration.md @@ -3,8 +3,8 @@ When using Nominatim through the library, it can be configured in exactly the same way as when running as a service. This means that you should have created a [project directory](../admin/Import.md#creating-the-project-directory) -which contains all files belonging to the Noinatim instance. It can also contain -an `.env` file with configuration options. Setting configuration paramters +which contains all files belonging to the Nominatim instance. It can also contain +an `.env` file with configuration options. Setting configuration parameters via environment variables works as well. Configuration options are resolved in the following order: diff --git a/docs/library/Getting-Started.md b/docs/library/Getting-Started.md index 77724e67..88f25eb6 100644 --- a/docs/library/Getting-Started.md +++ b/docs/library/Getting-Started.md @@ -3,8 +3,7 @@ The Nominatim search frontend can directly be used as a Python library in scripts and applications. When you have imported your own Nominatim database, then it is no longer necessary to run a full web service for it and access -the database through http requests. With the Nominatim library it is possible -to access all search functionality directly from your Python code. There are +the database through http requests. There are also less constraints on the kinds of data that can be accessed. The library allows to get access to more detailed information about the objects saved in the database. @@ -14,8 +13,8 @@ in the database. 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. Use is only recommended for advanced Python - programmers at the moment. + of the PYTHONPATH is required. At the moment, use is only recommended for + developers wit some experience in Python. ## Installation @@ -55,7 +54,7 @@ This code snippet implements a simple search for the town if 'Brugge': if not results: print('Cannot find Brugge') else: - print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}') + print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}') ``` === "NominatimAPI" @@ -71,7 +70,7 @@ This code snippet implements a simple search for the town if 'Brugge': if not results: print('Cannot find Brugge') else: - print(f'Found a place at {results[0].centroid.x},{results[1].centroid.y}') + print(f'Found a place at {results[0].centroid.x},{results[0].centroid.y}') ``` The Nominatim library is designed around @@ -83,8 +82,8 @@ significantly. For smaller scripts there is also a synchronous wrapper around the API. By using `NominatimAPI`, you get exactly the same interface using classic functions. -The examples in this chapter will always show how work with both of the -implementations. The documentation itself will refer usually only to +The examples in this chapter will always show-case both +implementations. The documentation itself will usually refer only to 'Nominatim API class' when both flavours are meant. If a functionality is available only for the synchronous or asynchronous version, this will be explicitly mentioned. @@ -104,7 +103,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. -The second way to configure your Nominatim setup is through environment variables. +Yo may also configure Nominatim be setting environment variables. Normally, Nominatim will check the operating system environment. This can be overwritten by giving the constructor a dictionary of configuration parameters. @@ -209,8 +208,8 @@ results should be presented. As with the names in the result itself, the places in `address_rows` contain all possible name translation for each row. The library has a helper class `Locale` which helps extracting a name of a -place in the preferred language. It gets a list of language code in the -order of preference. So +place in the preferred language. It takes a single parameter with a list +of language codes in the order of preference. So ``` python locale = napi.Locale(['fr', 'en']) diff --git a/docs/library/Input-Parameter-Types.md b/docs/library/Input-Parameter-Types.md index 5ee11425..9227dc32 100644 --- a/docs/library/Input-Parameter-Types.md +++ b/docs/library/Input-Parameter-Types.md @@ -7,8 +7,8 @@ in the query functions of the API object. 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. +require references to places in the database. Below the possible +types for place identification are listed. All types are dataclasses. ### PlaceID diff --git a/docs/library/Low-Level-DB-Access.md b/docs/library/Low-Level-DB-Access.md index 5101777e..acd93fd1 100644 --- a/docs/library/Low-Level-DB-Access.md +++ b/docs/library/Low-Level-DB-Access.md @@ -1,13 +1,13 @@ # Low-level connections The `NominatimAPIAsync` class allows to directly access the underlying -database connection to explore the data more directly. Nominatim uses +database connection to explore the raw data. 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 +API object. This returns a `SearchConnection` object described below +wrapped in a context manager. 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 diff --git a/docs/library/Result-Handling.md b/docs/library/Result-Handling.md index af2a8184..e2803f9f 100644 --- a/docs/library/Result-Handling.md +++ b/docs/library/Result-Handling.md @@ -1,7 +1,7 @@ # Result handling -The search functions of the Nominatim API always return a result object that -contains the full raw information about the place that is available in the +The search functions of the Nominatim API always return a result object +with the raw information about the place that is available in the database. This section discusses data types used in the results and utility functions that allow further processing of the results. @@ -9,8 +9,8 @@ functions that allow further processing of the results. ### Sources -Nominatim takes the result data from multiple souces. The `source_table` field -in the result describes, from which source the result was retrived. +Nominatim takes the result data from multiple sources. The `source_table` field +in the result describes, from which source the result was retrieved. ::: nominatim.api.SourceTable options: @@ -21,15 +21,15 @@ in the result describes, from which source the result was retrived. When the `address_details` parameter is set, then functions return not only information about the result place but also about the place that -make up the address. This information is almost always required, when you +make up the address. This information is almost always required when you want to present the user with a human-readable description of the result. See also [Localization](#localization) below. The address details are available in the `address_rows` field as a ordered list of `AddressLine` objects with the country information last. The list also contains the result place itself and some artificial entries, for example, -for the housenumber or the country code. This makes processing and creating -a full address easiert. +for the house number or the country code. This makes processing and creating +a full address easier. ::: nominatim.api.AddressLine options: diff --git a/nominatim/api/types.py b/nominatim/api/types.py index d6e80496..c96b3f59 100644 --- a/nominatim/api/types.py +++ b/nominatim/api/types.py @@ -315,8 +315,8 @@ class DataLayer(enum.Flag): for reverse and forward search. """ ADDRESS = enum.auto() - """ The address layer contains all places that have a fully qualified - address that includes a house number (or a house name equivalent, + """ The address layer contains all places relavant for addresses: + fully qualified addresses with a house number (or a house name equivalent, for some addresses) and places that can be part of an address like roads, cities, states. """ diff --git a/nominatim/tokenizer/base.py b/nominatim/tokenizer/base.py index 51afd540..061cff36 100644 --- a/nominatim/tokenizer/base.py +++ b/nominatim/tokenizer/base.py @@ -238,7 +238,7 @@ class AbstractTokenizer(ABC): Arguments: conn: Open connection to the database which may be used to - retrive the words. + retrieve the words. num: Maximum number of words to return. """