Switch from config init to BaseSettings

Dockerfile

@@ -12,7 +12,8 @@ EXPOSE ${PORT}
 
 COPY .docker/run.sh ./
 
-COPY tests/test_config.json ./
-ENV OPTIMADE_CONFIG_FILE /app/test_config.json
+ARG CONFIG_FILE=tests/test_config.json
+COPY ${CONFIG_FILE} ./config.json
+ENV OPTIMADE_CONFIG_FILE /app/config.json
 
 CMD ["/app/run.sh"]

INSTALL.md

@@ -5,17 +5,21 @@
 This package may be used to setup and run an [OPTIMADE index meta-database](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#index-meta-database).
 Install the package via `pip install optimade[server]`.
 
-The preferred method of configuring the server is to use a [JSON file](example_json.config) and setting the `optimade_config_file` environment variable to point to the location of this JSON file. The server can also be configured via environmet variables prefixed with `optimade_` and the corresponding variable names in `ServerConfig` in `optimade/server/config.py`. These environment variables are not case sensitive, so both `OPTIMADE_CONFIG_FILE` and `optimade_config_file` are valid.
+This python OPTIMADE implementation can be configured in two ways:
+First, the server can be configured via environment variables prefixed with `optimade_` and the corresponding variable names in `ServerConfig` in the [`config.py` file](optimade/server/config.py). These take precedence. These environment variables are not case sensitive, so both `OPTIMADE_CONFIG_FILE` and `optimade_config_file` are valid.
+Second, and the preferred method of configuring the server, is to use a [JSON file](example_json.config) with the bulk of the configuration and setting the `optimade_config_file` environment variable to point to the absolute location of this JSON file. By default this points to `~/.optimade.json` which can also be used to store the configuration if you don't want to set `optimade_config_file`.
 
+For any configuration parameters not set by the above two, the defaults in built into `ServerConfig` in `optimade.server.config` will be used.
 
-The index meta-database is set up to populate a `mongomock` in-memory database with resources from a static `json` file containing the `child` resources you, as a database provider, want to serve under this index meta-database.
+There is a built-in index meta-database set up to populate a `mongomock` in-memory database with resources from a static `json` file containing the `child` resources you, as a database provider, want to serve under this index meta-database. The location of that `json` file is controllable using the `index_links_path` property of the configuration or setting via the environment variable `optimade_index_links_path`.
 
 Running the index meta-database is then as simple as writing `./run.sh index` in a terminal from the root of this package.
 You can find it at the base URL: <http://localhost:5001/v0.10.1>.
 
+Here is an example of how it may look to start your server:
 ```shell
 :~$ export OPTIMADE_CONFIG_FILE=/home/optimade_server/config.json
-:~$ ./optimade/optimade-python-tools/run.sh index
+:~$ ./path/to/optimade/run.sh index
 ```
 
 ## Full development installation
@@ -45,7 +49,7 @@ py.test
 # Install pre-commit environment (e.g., auto-formats code on `git commit`)
 pre-commit install
 
-# Optional: Install MongoDB (and set `use_real_mongodb = true`)
+# Optional: Install MongoDB (and set `use_real_mongo = true`)
 # Below method installs in conda environment and
 # - starts server in background
 # - ensures and uses ~/dbdata directory to store data

docker-compose.yml

@@ -8,6 +8,7 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
+        CONFIG_FILE: tests/test_config.json
         PORT: 5000
     environment:
       MAIN: main
@@ -20,6 +21,7 @@ services:
       context: .
       dockerfile: Dockerfile
       args:
+        CONFIG_FILE: tests/test_config.json
         PORT: 5001
     environment:
       MAIN: main_index

example_config.json

@@ -6,22 +6,19 @@
     "links_collection": "optimade_links",
     "references_collection": "optimade_references",
     "structures_collection": "optimade_structures",
-    "page_limit": 20,
-    "page_limit_max": 500,
-    "default_db": "test_server",
-    "base_url": null,
+    "default_db": "example_server",
+    "base_url": "https://optimade.example.org",
     "implementation": {
         "name": "Example implementation",
-        "version": "0.7.0",
         "source_url": "https://github.com/Materials-Consortia/optimade-python-tools",
-        "maintainer": null
+        "maintainer": {"email": "[email protected]"}
     },
     "provider": {
         "name": "Example provider",
         "description": "Provider used for examples, not to be assigned to a real database",
         "prefix": "exmpl",
         "homepage": "https://example.com",
-        "index_base_url": "http://localhost:5001"
+        "index_base_url": "https://example.com/index"
     },
     "provider_fields": {
         "structures": [
@@ -37,4 +34,4 @@
             "chemical_formula_anonymous": "formula_anonymous"
         }
     }
-}
+}

optimade/server/config.py

@@ -1,7 +1,11 @@
 import os
 import json
 from typing import Any, Optional, Dict, List
-from typing_extensions import Literal
+
+try:
+    from typing import Literal
+except ImportError:
+    from typing_extensions import Literal
 from pathlib import Path
 from warnings import warn
 
@@ -27,7 +31,7 @@ class ServerConfig(BaseSettings):
         "~/.optimade.json", description="File to load alternative defaults from"
     )
     debug: bool = Field(
-        False, description="Turns on Debug Mode for the Optimade Server implementation"
+        False, description="Turns on Debug Mode for the OPTIMADE Server implementation"
     )
     use_real_mongo: bool = Field(
         False, description="Use a real Mongo server rather than MongoMock"
@@ -36,39 +40,62 @@ class ServerConfig(BaseSettings):
         "optimade", description="Mongo database for collection data"
     )
     mongo_uri: str = Field("localhost:27017", description="URI for the Mongo server")
-    links_collection: str = Field("links", description="Collection name for Links")
+    links_collection: str = Field(
+        "links", description="Mongo collection name for /links endpoint resources"
+    )
     references_collection: str = Field(
-        "references", description="Collection name for References"
+        "references",
+        description="Mongo collection name for /references endpoint resources",
     )
     structures_collection: str = Field(
-        "structures", description="Collection name for Structures"
+        "structures",
+        description="Mongo collection name for /structures endpoint resources",
+    )
+    page_limit: int = Field(20, description="Default number of resources per page")
+    page_limit_max: int = Field(
+        500, description="Max allowed number of resources per page"
     )
-    page_limit: int = Field(20, description="Default items per page")
-    page_limit_max: int = Field(500, description="Max items per page")
     default_db: str = Field(
         "test_server",
-        description="ID of the provider's chosen default OPTIMADE API database.",
+        description="ID of /links endpoint resource for the chosen default OPTIMADE implementation (only relevant for the index meta-database)",
     )
     base_url: Optional[str] = Field(
-        None, description="URL for the homepage for this implementation"
+        None, description="Base URL for this implementation"
     )
-    implementation: Implementation = Implementation(
-        name="Example implementation",
-        version=__version__,
-        source_url="https://github.com/Materials-Consortia/optimade-python-tools",
-        maintainer=None,
+    implementation: Implementation = Field(
+        Implementation(
+            name="Example implementation",
+            version=__version__,
+            source_url="https://github.com/Materials-Consortia/optimade-python-tools",
+            maintainer=None,
+        ),
+        description="Introspective information about this OPTIMADE implementation",
     )
-    provider: Provider = Provider(
-        prefix="exmpl",
-        name="Example provider",
-        description="Provider used for examples, not to be assigned to a real database",
-        homepage="https://example.com",
-        index_base_url="http://localhost:5001",
+    provider: Provider = Field(
+        Provider(
+            prefix="exmpl",
+            name="Example provider",
+            description="Provider used for examples, not to be assigned to a real database",
+            homepage="https://example.com",
+            index_base_url="http://localhost:5001",
+        ),
+        description="General information about the provider of this OPTIMADE implementation",
+    )
+    provider_fields: Dict[
+        Literal["links", "references", "structures"], List[str]
+    ] = Field(
+        {},
+        description="A list of additional fields to be served with the provider's prefix attached, broken down by endpoint.",
+    )
+    aliases: Dict[Literal["links", "references", "structures"], Dict[str, str]] = Field(
+        {},
+        description="A mapping between field names in the database with their corresponding OPTIMADE field names, broken down by endpoint.",
     )
-    provider_fields: Dict[Literal["links", "references", "structures"], List[str]] = {}
-    aliases: Dict[Literal["links", "references", "structures"], Dict[str, str]] = {}
 
-    index_links_path: Path = Path(__file__).parent.joinpath("index_links.json")
+    index_links_path: Path = Field(
+        Path(__file__).parent.joinpath("index_links.json"),
+        description="Absolute path to a JSON file containing the MongoDB collection of /links resources for the index meta-database",
+    )
 
     @root_validator(pre=True)
     def load_default_settings(cls, values):

optimade/server/routers/utils.py

@@ -53,15 +53,13 @@ def meta_values(
     else:
         url_path = parse_result.path
 
-    provider = CONFIG.provider.copy()
-
     return ResponseMeta(
         query=ResponseMetaQuery(representation=f"{url_path}?{parse_result.query}"),
         api_version=f"v{__api_version__}",
         time_stamp=datetime.utcnow(),
         data_returned=data_returned,
         more_data_available=more_data_available,
-        provider=provider,
+        provider=CONFIG.provider,
         data_available=data_available,
         implementation=CONFIG.implementation,
         **kwargs,

setup.py

@@ -49,7 +49,7 @@
         "pydantic~=1.4",
         "email_validator",
         "requests~=2.23",
-        "typing-extensions~=3.7.4.1",
+        'typing-extensions~=3.7.4.1;python_version<"3.8"',
     ],
     extras_require={
         "all": all_deps,

tests/test_config.json

@@ -1,20 +1,11 @@
 {
     "debug": false,
-    "use_real_mongo": false,
-    "mongo_database": "optimade",
-    "mongo_uri": "localhost:27017",
-    "links_collection": "links",
-    "references_collection": "references",
-    "structures_collection": "structures",
-    "page_limit": 20,
-    "page_limit_max": 500,
     "default_db": "test_server",
-    "base_url": null,
+    "base_url": "http://localhost:5000",
     "implementation": {
         "name": "Example implementation",
-        "version": "0.7.0",
         "source_url": "https://github.com/Materials-Consortia/optimade-python-tools",
-        "maintainer": null
+        "maintainer": {"email": "[email protected]"}
     },
     "provider": {
         "name": "Example provider",
@@ -37,4 +28,4 @@
             "chemical_formula_anonymous": "formula_anonymous"
         }
     }
-}
+}