Skip to content

config

CONFIG: ServerConfig

This singleton loads the config from a hierarchy of sources (see customise_sources) and makes it importable in the server code.

DEFAULT_CONFIG_FILE_PATH: str

Default configuration file path.

This variable is used as the fallback value if the environment variable OPTIMADE_CONFIG_FILE is not set.

Note

It is set to: pathlib.Path.home()/.optimade.json

For Unix-based systems (Linux) this will be equivalent to ~/.optimade.json.

LogLevel (Enum)

Replication of logging LogLevels

  • notset
  • debug
  • info
  • warning
  • error
  • critical

ServerConfig (BaseSettings) pydantic-model

This class stores server config parameters in a way that can be easily extended for new config file types.

aliases: Dict[Literal['links', 'references', 'structures'], Dict[str, str]] pydantic-field

A mapping between field names in the database with their corresponding OPTIMADE field names, broken down by endpoint.

base_url: str pydantic-field

Base URL for this implementation

database_backend: SupportedBackend pydantic-field

Which database backend to use out of the supported backends.

debug: bool pydantic-field

Turns on Debug Mode for the OPTIMADE Server implementation

default_db: str pydantic-field

ID of /links endpoint resource for the chosen default OPTIMADE implementation (only relevant for the index meta-database)

elastic_hosts: List[Dict] pydantic-field

Host settings to pass through to the Elasticsearch class.

implementation: Implementation pydantic-field

Introspective information about this OPTIMADE implementation

index_base_url: AnyHttpUrl pydantic-field

An optional link to the base URL for the index meta-database of the provider.

Absolute path to a JSON file containing the MongoDB collecton of links entries (documents) to serve under the /links endpoint of the index meta-database. NB! As suggested in the previous sentence, these will only be served when using a MongoDB-based backend.

insert_test_data: bool pydantic-field

Insert test data into each collection on server initialisation. If true, the configured backend will be populated with test data on server start. Should be disabled for production usage.

length_aliases: Dict[Literal['links', 'references', 'structures'], Dict[str, str]] pydantic-field

A mapping between a list property (or otherwise) and an integer property that defines the length of that list, for example elements -> nelements. The standard aliases are applied first, so this dictionary must refer to the API fields, not the database fields.

Mongo collection name for /links endpoint resources

log_dir: Path pydantic-field

Folder in which log files will be saved.

log_level: LogLevel pydantic-field

Logging level for the OPTIMADE server.

mongo_database: str pydantic-field

Mongo database for collection data

mongo_uri: str pydantic-field

URI for the Mongo server

page_limit: int pydantic-field

Default number of resources per page

page_limit_max: int pydantic-field

Max allowed number of resources per page

provider: Provider pydantic-field

General information about the provider of this OPTIMADE implementation

provider_fields: Dict[Literal['links', 'references', 'structures'], List[str]] pydantic-field

A list of additional fields to be served with the provider's prefix attached, broken down by endpoint.

references_collection: str pydantic-field

Mongo collection name for /references endpoint resources

root_path: str pydantic-field

Sets the FastAPI app root_path parameter. This can be used to serve the API under a path prefix behind a proxy or as a sub-application of another FastAPI app. See https://fastapi.tiangolo.com/advanced/sub-applications/#technical-details-root_path for details.

structures_collection: str pydantic-field

Mongo collection name for /structures endpoint resources

use_real_mongo: bool pydantic-field

DEPRECATED: force usage of MongoDB over any other backend.

Config

This is a pydantic model Config object that modifies the behaviour of ServerConfig by adding a prefix to the environment variables that override config file values. It has nothing to do with the OPTIMADE config.

customise_sources(init_settings, env_settings, file_secret_settings) classmethod

Priority of config settings sources:

  1. Passed arguments upon initialization of ServerConfig.
  2. Environment variables, matching the syntax: "OPTIMADE_" or "optimade_" + <config_name>, e.g., OPTIMADE_LOG_LEVEL=debug or optimade_log_dir=~/logs_dir/optimade/.
  3. Configuration file (JSON/YAML) taken from:
  4. Environment variable OPTIMADE_CONFIG_FILE.
  5. Default location (see DEFAULT_CONFIG_FILE_PATH).
  6. Settings from secret file (see pydantic documentation for more information).
Source code in optimade/server/config.py 
@classmethod
def customise_sources(
    cls,
    init_settings: SettingsSourceCallable,
    env_settings: SettingsSourceCallable,
    file_secret_settings: SettingsSourceCallable,
) -> Tuple[SettingsSourceCallable, ...]:
    """
    **Priority of config settings sources**:

    1. Passed arguments upon initialization of
       [`ServerConfig`][optimade.server.config.ServerConfig].
    2. Environment variables, matching the syntax: `"OPTIMADE_"` or `"optimade_"` +
       `<config_name>`, e.g., `OPTIMADE_LOG_LEVEL=debug` or
       `optimade_log_dir=~/logs_dir/optimade/`.
    3. Configuration file (JSON/YAML) taken from:
       1. Environment variable `OPTIMADE_CONFIG_FILE`.
       2. Default location (see
          [DEFAULT_CONFIG_FILE_PATH][optimade.server.config.DEFAULT_CONFIG_FILE_PATH]).
    4. Settings from secret file (see
       [pydantic documentation](https://pydantic-docs.helpmanual.io/usage/settings/#secret-support)
       for more information).

    """
    return (
        init_settings,
        env_settings,
        config_file_settings,
        file_secret_settings,
    )

set_implementation_version(v) classmethod

Set defaults and modify bypassed value(s)

Source code in optimade/server/config.py 
@validator("implementation", pre=True)
def set_implementation_version(cls, v):
    """Set defaults and modify bypassed value(s)"""
    res = {"version": __version__}
    res.update(v)
    return res

use_real_mongo_override(values) classmethod

Overrides the database_backend setting with MongoDB and raises a deprecation warning.

Source code in optimade/server/config.py 
@root_validator(pre=True)
def use_real_mongo_override(cls, values):
    """Overrides the `database_backend` setting with MongoDB and
    raises a deprecation warning.

    """
    use_real_mongo = values.pop("use_real_mongo", None)
    if use_real_mongo is not None:
        warnings.warn(
            "'use_real_mongo' is deprecated, please set the appropriate 'database_backend' "
            "instead.",
            DeprecationWarning,
        )

        if use_real_mongo:
            values["database_backend"] = SupportedBackend.MONGODB

    return values

SupportedBackend (Enum)

Enumeration of supported database backends

  • elastic: Elasticsearch.
  • mongodb: MongoDB.
  • mongomock: Also MongoDB, but instead of using the pymongo driver to connect to a live Mongo database instance, this will use the mongomock driver, creating an in-memory database, which is mainly used for testing.

config_file_settings(settings)

Configuration file settings source.

Based on the example in the pydantic documentation, this function loads ServerConfig settings from a configuration file.

The file must be of either type JSON or YML/YAML.

Parameters:

Name Type Description Default
settings BaseSettings

The pydantic.BaseSettings class using this function as a pydantic.SettingsSourceCallable.

 required

Returns:

Type Description
Dict[str, Any]

Dictionary of settings as read from a file.
Source code in optimade/server/config.py 
def config_file_settings(settings: BaseSettings) -> Dict[str, Any]:
    """Configuration file settings source.

    Based on the example in the
    [pydantic documentation](https://pydantic-docs.helpmanual.io/usage/settings/#adding-sources),
    this function loads ServerConfig settings from a configuration file.

    The file must be of either type JSON or YML/YAML.

    Parameters:
        settings: The `pydantic.BaseSettings` class using this function as a
            `pydantic.SettingsSourceCallable`.

    Returns:
        Dictionary of settings as read from a file.

    """
    import json
    import os
    import yaml

    encoding = settings.__config__.env_file_encoding
    config_file = Path(os.getenv("OPTIMADE_CONFIG_FILE", DEFAULT_CONFIG_FILE_PATH))

    res = {}
    if config_file.is_file():
        config_file_content = config_file.read_text(encoding=encoding)

        try:
            res = json.loads(config_file_content)
        except json.JSONDecodeError as json_exc:
            try:
                # This can essentially also load JSON files, as JSON is a subset of YAML v1,
                # but I suspect it is not as rigorous
                res = yaml.safe_load(config_file_content)
            except yaml.YAMLError as yaml_exc:
                warnings.warn(
                    f"Unable to parse config file {config_file} as JSON or YAML, using the "
                    "default settings instead..\n"
                    f"Errors:\n  JSON:\n{json_exc}.\n\n  YAML:\n{yaml_exc}"
                )
    else:
        warnings.warn(
            f"Unable to find config file at {config_file}, using the default settings instead."
        )

    if res is None:
        # This can happen if the yaml loading doesn't succeed properly, e.g., if the file is empty.
        warnings.warn(
            "Unable to load any settings from {config_file}, using the default settings instead."
        )
        res = {}

    return res