REST API Application Factory Reference

This reference describes create_app and load_config for developers constructing REST API applications. It covers their parameters, return values, validation, input precedence and supported overrides. Shared environment defaults and key-file constraints are listed in REST API Configuration Reference; command usage is listed in dioptra-api Command Reference.

create_app

create_app(env: str | None = None, injector: injector.Injector | None = None, *, settings: dioptra.restapi.config.BaseConfig | None = None, overrides: collections.abc.Mapping[str, object] | None = None) → flask.app.Flask

Construct an API application after validating its settings.

Supply a mode and optional overrides, or supply a previously resolved settings instance. The settings belong to this application and must not be mutated. They contain the signing key, so do not print or serialize them. Invalid or conflicting settings fail before extensions or default clients initialize. A supplied settings instance is validated; if the mode environment variable is present, it is ignored with a warning.

Parameters

• env – dev or prod. When resolving settings, omission selects DIOPTRA_RESTAPI_ENV. Do not supply this with settings.

• injector – Injector used by RESTX views. If omitted, construct one with the default services. A supplied injector does not alter policy.

• settings – A configuration returned by load_config. Do not combine it with env or overrides.

• overrides – Typed values for settings accepted by load_config. They precede named environment inputs and defaults. Do not supply these with settings.

Returns

An initialized and configured Flask application.

Raises

ValueError – If settings inputs conflict or configuration validation fails.

Input Forms

Call form	Behavior
settings=None	Resolve configuration using env, overrides and the current environment.
Resolved settings with env=None and overrides=None.	Validate that instance without ambient configuration resolution.
Resolved settings with any non-None env or overrides.	Raise ValueError. An empty overrides mapping also conflicts.

With supplied settings, a present DIOPTRA_RESTAPI_ENV is ignored and produces a warning. Supplied settings are an alternative input form, not another precedence level.

Mode Precedence

When create_app resolves configuration (settings=None), it selects the mode from these sources, in descending priority. The same rule applies to load_config.

Priority	Source	When selected
1	env argument.	The argument is not None.
2	DIOPTRA_RESTAPI_ENV.	env is omitted or None.

There is no default mode. The selected value must be dev or prod; missing, empty or unsupported values raise ValueError. An invalid explicit argument does not fall back to the environment variable. For example, env="" fails even when DIOPTRA_RESTAPI_ENV=prod. Platform restrictions are listed in REST API Configuration Reference.

load_config

load_config(env: str | None = None, *, overrides: collections.abc.Mapping[str, object] | None = None) → dioptra.restapi.config.BaseConfig

Resolve a fresh API configuration from one environment snapshot.

Explicit typed overrides precede named environment inputs and class defaults. The protected key file must already exist; resolution never creates or repairs it. The returned instance belongs to one application and must not be mutated. It contains the signing key, so do not print or serialize it. Later environment changes affect future resolution, not applications using this instance. DIOPTRA_MAX_PAGE_SIZE applies to paginated endpoints and must be at least 10. Session protection accepts basic, strong or None; the environment string none selects None.

Parameters

• env – dev or prod. If omitted, select DIOPTRA_RESTAPI_ENV.

• overrides – Mapping of schema setting names to typed values, plus the optional SECRET_KEY_FILE path. Unsupported names are rejected. See the schema and class defaults for the accepted settings.

Returns

A validated development or production configuration, including the key read from the selected file and the resolved database and service URIs.

Raises

ValueError – If mode, settings, retired environment inputs, or the selected key file fail validation. Diagnostics do not include credential values.

Typed Overrides

For each setting, resolution uses these sources in descending priority.

1. The typed value in overrides.

2. Its named environment variable, when supported.

3. The packaged default.

An invalid selected value is rejected without falling back. Override keys use the resolved attribute names below. Environment defaults and value constraints are defined in Environment Variables.

Overrides with environment inputs

Attribute	Environment variable
SECRET_KEY_FILE	DIOPTRA_RESTAPI_SECRET_KEY_FILE
LOGIN_DISABLED	DIOPTRA_LOGIN_DISABLED
SESSION_PROTECTION	DIOPTRA_SESSION_PROTECTION
REMEMBER_COOKIE_DURATION	DIOPTRA_REMEMBER_COOKIE_DURATION
REMEMBER_COOKIE_SECURE	DIOPTRA_REMEMBER_COOKIE_SECURE
SQLALCHEMY_DATABASE_URI	DIOPTRA_RESTAPI_DATABASE_URI
DIOPTRA_CORS_ORIGIN, DIOPTRA_SWAGGER_PATH, DIOPTRA_BASE_URL, DIOPTRA_MAX_PAGE_SIZE	Same name as the attribute.
RQ_REDIS_URI, MLFLOW_TRACKING_URI	Same name as the attribute.
DIOPTRA_RESTAPI_LOG_AS_JSON, DIOPTRA_RESTAPI_LOG_LEVEL	Same name as the attribute.

Override values use Python types rather than environment-string conversion.

• Boolean overrides require Python booleans.

• Integer overrides require integers and reject booleans.

Additional Python value rules

Attribute	Accepted values
SECRET_KEY_FILE	Nonempty string or pathlib.Path; explicit None is invalid.
SESSION_PROTECTION	basic, strong or Python None. Strings are case-insensitive; "none" becomes None.
DIOPTRA_SWAGGER_PATH	Documentation-path string, or Python False to disable API documentation.
DIOPTRA_BASE_URL	Nonempty scheme string, or Python None for the unset default.

Python-only overrides

Attribute	Default	Constraints
DEBUG	True in dev; False in prod.	Boolean; production rejects True.
TESTING	False	Boolean; does not select a mode or relax production/platform policy.
REMEMBER_COOKIE_NAME	dioptra_remember_token	Nonempty string.
SQLALCHEMY_TRACK_MODIFICATIONS	False	Boolean.
USE_MOCK_EQUIVALENCY	False	Boolean; no current API consumer.

CONFIG_NAME and SECRET_KEY cannot be overridden directly. Mode selection sets CONFIG_NAME; the protected file supplies SECRET_KEY. Other unsupported names are also rejected.