From: Sarah Hoffmann Date: Tue, 22 Aug 2023 20:16:34 +0000 (+0200) Subject: finish configuration section X-Git-Tag: v4.3.0~13^2~10 X-Git-Url: https://git.openstreetmap.org./nominatim.git/commitdiff_plain/558c42ec83a5a01e238af2fa4faa6a992af3f77a finish configuration section --- diff --git a/docs/library/Configuration.md b/docs/library/Configuration.md index 19b8feb8..f673a27d 100644 --- a/docs/library/Configuration.md +++ b/docs/library/Configuration.md @@ -1,4 +1,24 @@ -# Configuration class +# Configuration + +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 +via environment variables works as well. + +Configuration options are resolved in the following order: + +* from the OS environment (or the dictionary given in `environ`, + (see NominatimAPI.md#nominatim.api.core.NominatimAPI.__init__) +* from the .env file in the project directory of the installation +* from the default installation in the configuration directory + +For more information on configuration via dotenv and a list of possible +configuration parameters, see the [Configuration page](../customize/Settings.md). + + +## `Configuration` class ::: nominatim.config.Configuration options: diff --git a/nominatim/api/core.py b/nominatim/api/core.py index c21e03f6..fb03d2df 100644 --- a/nominatim/api/core.py +++ b/nominatim/api/core.py @@ -47,10 +47,10 @@ class NominatimAPIAsync: project_dir: Path to the [project directory](../admin/Import.md#creating-the-project-directory) of the local Nominatim installation. - environ: Mapping of additional - [configuration parameters](../customize/Settings.md). - These will override default configuration and configuration - from the project directory. + environ: Mapping of [configuration parameters](../customize/Settings.md). + When set, replaces any configuration via environment variables. + Settings in this mapping also have precedence over any + parameters found in the `.env` file of the project directory. loop: The asyncio event loop that will be used when calling functions. Only needed, when a custom event loop is used and the Python version is 3.9 or earlier. @@ -321,10 +321,10 @@ class NominatimAPI: project_dir: Path to the [project directory](../admin/Import.md#creating-the-project-directory) of the local Nominatim installation. - environ: Mapping of additional - [configuration parameters](../customize/Settings.md). - These will override default configuration and configuration - from the project directory. + environ: Mapping of [configuration parameters](../customize/Settings.md). + When set, replaces any configuration via environment variables. + Settings in this mapping also have precedence over any + parameters found in the `.env` file of the project directory. """ self._loop = asyncio.new_event_loop() self._async_api = NominatimAPIAsync(project_dir, environ, loop=self._loop) diff --git a/nominatim/config.py b/nominatim/config.py index 03b5e254..3344a425 100644 --- a/nominatim/config.py +++ b/nominatim/config.py @@ -47,15 +47,8 @@ def flatten_config_list(content: Any, section: str = '') -> List[Any]: class Configuration: - """ The `Configuration` class wraps access to the local configuration - options as described in the [Configuration page](../customize/Settings.md). - - Nominatim uses dotenv to configure the software. Configuration options - are resolved in the following order: - - * from the OS environment (or the dictionary given in `environ`) - * from the .env file in the project directory of the installation - * from the default installation in the configuration directory + """ This class wraps access to the configuration settings + for the Nominatim instance in use. All Nominatim configuration options are prefixed with 'NOMINATIM_' to avoid conflicts with other environment variables. All settings can @@ -104,8 +97,6 @@ class Configuration: def get_bool(self, name: str) -> bool: """ Return the given configuration parameter as a boolean. - Values of '1', 'yes' and 'true' are accepted as truthy values, - everything else is interpreted as false. Parameters: name: Name of the configuration parameter with the NOMINATIM_ @@ -140,8 +131,17 @@ class Configuration: def get_str_list(self, name: str) -> Optional[List[str]]: """ Return the given configuration parameter as a list of strings. The values are assumed to be given as a comma-sparated list and - will be stripped before returning them. On empty values None - is returned. + will be stripped before returning them. + + Parameters: + name: Name of the configuration parameter with the NOMINATIM_ + prefix removed. + + Returns: + (List[str]): The comma-split parameter as a list. The + elements are stripped of leading and final spaces before + being returned. + (None): The configuration parameter was unset or empty. """ raw = getattr(self, name) @@ -150,9 +150,16 @@ class Configuration: def get_path(self, name: str) -> Optional[Path]: """ Return the given configuration parameter as a Path. - If a relative path is configured, then the function converts this - into an absolute path with the project directory as root path. - If the configuration is unset, None is returned. + + Parameters: + name: Name of the configuration parameter with the NOMINATIM_ + prefix removed. + + Returns: + (Path): A Path object of the parameter value. + If a relative path is configured, then the function converts this + into an absolute path with the project directory as root path. + (None): The configuration parameter was unset or empty. """ value = getattr(self, name) if not value: