geoips.config package#

Submodules#

geoips.config.config module#

GeoIPS configuration loader.

Provides GeoIPSConfig — an immutable, layered configuration container that merges defaults, project YAML overrides, and environment variable overrides with a well-defined priority order.

class geoips.config.config.GeoIPSConfig(project_config_path: str | None = None)[source]#

Bases: object

Immutable, layered GeoIPS configuration container.

Configuration is loaded once at construction time with this priority (highest wins):

Environment variables (GEOIPS_* and unprefixed aliases)
Project-level .geoips.yaml file
Pydantic model Field defaults (lowest)

The resulting configuration is frozen — all mutations must be done via model_copy(update=...), which returns a new instance.

Parameters:: project_config_path (str or None, optional) – Override the project config search path. If None, the standard search locations are used.

get(key: str, default: Any = None) → Any[source]#

Get a configuration value by legacy uppercase key.

Parameters:

key (str) – The uppercase legacy key (e.g. GEOIPS_OUTDIRS).
default (Any, optional) – Value to return if the key is not found.

Returns:

The configuration value, or default.

Return type:

Any

property plugins: Any#

Accessor for configuration contributed by external plugin packages.

Returns a namespace supporting attribute access (config.plugins.my_pkg), item access (config.plugins["my_pkg"]), .get(), and iteration over registered plugin names. Plugin modules are imported lazily on first access.

to_legacy_dict() → dict[str, Any][source]#

Return the full configuration as a flat uppercase dictionary.

This mirrors the shape of the old PATHS dict from geoips.filenames.base_paths for backward compatibility.

Deprecated: The flat uppercase dictionary is a backwards-compatibility layer and is slated for removal in a future release. New code should access settings via the structured GeoIPSConfig / GeoSettings attributes instead. geoips.config.schema.GEOIPS_ENV_MAP is the authoritative list of supported environment variables and settings.

Returns:: Flat uppercase-keyed configuration dictionary.
Return type:: dict[str, Any]

geoips.config.config.get_config(project_config_path: str | None = None) → GeoIPSConfig[source]#

Return the singleton GeoIPSConfig instance.

Creates the configuration on first call. Subsequent calls return the cached instance.

Parameters:: project_config_path (str or None, optional) – Override the project config search path (only used on first call).
Returns:: The singleton configuration instance.
Return type:: GeoIPSConfig

geoips.config.config.make_dirs(path: str) → str[source]#

Create directories, catching exceptions if directory already exists.

Parameters:: path (str) – Path to directory to create.
Returns:: path if successfully created.
Return type:: str

geoips.config.plugins module#

Plugin-contributed configuration support for GeoIPS.

External plugin packages can register their own configuration settings with GeoIPS by exposing a ConfigPlugin via the geoips.config_plugins entry-point group:

# in my_pkg/config.py
from pydantic import BaseModel, Field
from geoips.config import ConfigPlugin


class MyPkgSettings(BaseModel):
    max_workers: int = Field(4, description="Max parallel workers.")
    tile_cache: str | None = None


CONFIG_PLUGIN = ConfigPlugin(name="my_pkg", settings_model=MyPkgSettings)

# in pyproject.toml
[project.entry-points."geoips.config_plugins"]
my_pkg = "my_pkg.config:CONFIG_PLUGIN"

The settings are then available as config.plugins.my_pkg.max_workers, may be set in .geoips.yaml under geoips.plugins.my_pkg, and are overridable via auto-generated environment variables of the form GEOIPS_PLUGIN_<PKG>_<FIELD> (e.g. GEOIPS_PLUGIN_MY_PKG_MAX_WORKERS).

Discovery and per-plugin validation are lazy: plugin modules are only imported when config.plugins is first accessed, and each plugin’s settings are only validated on first access, so a misconfigured plugin cannot break importing geoips.config for everyone.

geoips.config.plugins.CONFIG_PLUGIN_GROUP = 'geoips.config_plugins'#: Entry-point group external packages use to register configuration.

class geoips.config.plugins.ConfigPlugin(name: str, settings_model: type[pydantic.main.BaseModel], env_overrides: ~typing.Mapping[str, str] = <factory>)[source]#

Bases: object

Describes the configuration a plugin package contributes to GeoIPS.

Parameters:

name (str) – The plugin namespace key. Settings are exposed as config.plugins.<name> and live under geoips.plugins.<name> in the YAML config file. Must match the entry-point name.
settings_model (type[pydantic.BaseModel]) – A pydantic model describing the plugin’s settings. Fields should provide defaults (or be Optional) so that importing GeoIPS never fails when the plugin is installed but unconfigured.
env_overrides (Mapping[str, str], optional) – Optional explicit environment-variable aliases mapping a full env var name to a model-relative dotted field path (e.g. {"MY_LEGACY_VAR": "max_workers"}). Auto-generated variables are always available in addition to these.

env_overrides: Mapping[str, str]#

name: str#

settings_model: type[pydantic.main.BaseModel]#

geoips.config.plugins.ENV_VAR_PREFIX = 'GEOIPS_PLUGIN'#: Prefix for auto-generated plugin environment variables.

class geoips.config.plugins.PluginSettingsNamespace(resolver, names)[source]#

Bases: object

Attribute/dict accessor for resolved plugin settings.

Access a plugin’s validated settings via config.plugins.<name> or config.plugins["<name>"]. Iterating yields the registered plugin names.

get(name: str, default: Any = None) → Any[source]#: Return the settings for name, or default if not registered.

geoips.config.plugins.build_plugin_env_map(plugins: Mapping[str, ConfigPlugin] | None = None) → dict[str, str][source]#

Return the combined env var -> plugins.<pkg>.<field> map.

Raises:: ConfigError – If a plugin env var collides with a core GeoIPS env var or with another plugin’s env var.

geoips.config.plugins.cast_plugin_target(target: str, raw: str) → Any[source]#: Cast a raw env value for a plugins.<pkg>.<field> target path.

geoips.config.plugins.discover_config_plugins(*, refresh: bool = False) → dict[str, geoips.config.plugins.ConfigPlugin][source]#

Discover and return all registered config plugins, keyed by name.

Results are cached after the first call unless refresh is True.

Raises:: ConfigError – If an entry point does not load a ConfigPlugin, if its declared name does not match the entry-point name, or if two plugins share a name.

geoips.config.plugins.env_var_for(pkg: str, dotted_field: str) → str[source]#

Return the auto-generated env var name for a plugin field.

Parameters:

pkg (str) – The plugin name.
dotted_field (str) – The model-relative dotted field path (e.g. "cache.tile_dir").

Returns:

The environment variable name (e.g. GEOIPS_PLUGIN_MY_PKG_CACHE_TILE_DIR).

Return type:

str

geoips.config.plugins.field_comment(model_cls: type[pydantic.main.BaseModel], name: str) → str[source]#

Return a human-readable comment for a field.

Prefers the field’s description; appends (default: ...) for scalar fields with a simple default. Nested-model and factory defaults are not expanded (their contents render as their own YAML lines).

geoips.config.plugins.full_model_defaults(model_cls: type[pydantic.main.BaseModel]) → dict[str, Any][source]#

Return a full default dump of a model when instantiable, else partial.

Uses model_dump() when the model has no required fields; otherwise falls back to _model_defaults(), which omits required fields.

geoips.config.plugins.is_nested_model(annotation: Any) → type[pydantic.main.BaseModel] | None[source]#: Return the nested pydantic model for an annotation, or None.

geoips.config.plugins.leaf_field_paths(model_cls: type[pydantic.main.BaseModel], prefix: str = '') → frozenset[str][source]#: Return the set of dotted leaf field paths for a pydantic model tree.

geoips.config.plugins.plugin_field_env_map(plugin: ConfigPlugin) → dict[str, str][source]#: Return a mapping of env var name to model-relative dotted field path.

geoips.config.plugins.resolve_plugin_settings(plugin: ConfigPlugin, yaml_values: Mapping[str, Any] | None) → BaseModel[source]#

Resolve a plugin’s settings with defaults < YAML < env precedence.

Parameters:

plugin (ConfigPlugin) – The plugin to resolve.
yaml_values (Mapping or None) – The geoips.plugins.<pkg> sub-mapping from the project config, if any.

Returns:

A validated instance of the plugin’s settings model.

Return type:

pydantic.BaseModel

Raises:

ConfigError – If the merged values fail validation against the plugin’s model.

geoips.config.schema module#

Pydantic schema models for GeoIPS configuration.

Defines the structure, types, and defaults for all GeoIPS configuration values. Models are frozen (immutable) to prevent accidental mutation.

pydantic model geoips.config.schema.CacheSettings[source]#

Bases: BaseModel

Cache directory and backend configuration.

Fields:

cache_dir (str | None)
data_cache_dir (str | None)
data_cache_longterm_geolocation_static (str)
data_cache_shortterm_calibrated_data (str)
data_cache_shortterm_geolocation_dynamic (str)
data_cache_shortterm_geolocation_solar_angles (str)
geolocation_cache_backend (str)
satpy_cache_shortterm_calibrated_data (str)
satpy_cache_shortterm_geolocation_solar_angles (str)
satpy_data_cache_dir (str | None)

field cache_dir: str | None = None#: Base cache directory (defaults to the platform cache dir).

field data_cache_dir: str | None = None#: Data cache directory (defaults to cache_dir).

field data_cache_longterm_geolocation_static: str = 'longterm/geolocation/static'#: Long-term static geolocation cache subpath.

field data_cache_shortterm_calibrated_data: str = 'shortterm/calibrated_data'#: Short-term calibrated data cache subpath.

field data_cache_shortterm_geolocation_dynamic: str = 'shortterm/geolocation/dynamic'#: Short-term dynamic geolocation cache subpath.

field data_cache_shortterm_geolocation_solar_angles: str = 'shortterm/geolocation/solar'#: Short-term solar-angle geolocation cache subpath.

field geolocation_cache_backend: str = 'memmap'#: Geolocation cache backend (e.g. ‘memmap’).

field satpy_cache_shortterm_calibrated_data: str = 'shortterm/calibrated_data'#: Short-term Satpy calibrated data cache subpath.

field satpy_cache_shortterm_geolocation_solar_angles: str = 'shortterm/geolocation/solar'#: Short-term Satpy solar-angle cache subpath.

field satpy_data_cache_dir: str | None = None#: Satpy data cache directory (defaults to cache_dir).

pydantic model geoips.config.schema.FeatureSettings[source]#

Bases: BaseModel

Boolean feature toggles controlling GeoIPS behavior.

Fields:

no_color (bool)
operational_user (bool)
rebuild_registries (bool)
rich_console_output (bool)
use_pydantic (bool)

field no_color: bool = False#: Disable colored console output.

field operational_user: bool = False#: Enable operational-user behavior.

field rebuild_registries: bool = True#: Rebuild plugin registries automatically when needed.

field rich_console_output: bool = False#: Enable rich-formatted console output.

field use_pydantic: bool = False#: Use pydantic-based plugin validation.

geoips.config.schema.GEOIPS_ENV_MAP: dict[str, str] = {'ANNOTATED_IMAGERY_PATH': 'output_paths.annotated_imagery', 'BOXNAME': 'boxname', 'CLEAN_IMAGERY_PATH': 'output_paths.clean_imagery', 'DEFAULT_QUEUE': 'default_queue', 'FINAL_DATA_PATH': 'output_paths.final_data', 'GEOIPSDATA': 'output_paths.geoipsdata', 'GEOIPS_ANCILDAT': 'output_paths.ancildat', 'GEOIPS_ANCILDAT_AUTOGEN': 'output_paths.ancildat_autogen', 'GEOIPS_BASEDIR': 'basedir', 'GEOIPS_CACHE_DIR': 'cache.cache_dir', 'GEOIPS_COPYRIGHT': 'copyright', 'GEOIPS_COPYRIGHT_ABBREVIATED': 'copyright_abbreviated', 'GEOIPS_DATA_CACHE_DIR': 'cache.data_cache_dir', 'GEOIPS_DATA_CACHE_DIR_LONGTERM_GEOLOCATION_STATIC': 'cache.data_cache_longterm_geolocation_static', 'GEOIPS_DATA_CACHE_DIR_SHORTTERM_CALIBRATED_DATA': 'cache.data_cache_shortterm_calibrated_data', 'GEOIPS_DATA_CACHE_DIR_SHORTTERM_GEOLOCATION_DYNAMIC': 'cache.data_cache_shortterm_geolocation_dynamic', 'GEOIPS_DATA_CACHE_DIR_SHORTTERM_GEOLOCATION_SOLAR_ANGLES': 'cache.data_cache_shortterm_geolocation_solar_angles', 'GEOIPS_DEPENDENCIES_DIR': 'dependencies_dir', 'GEOIPS_DOCS_URL': 'docs_url', 'GEOIPS_GEOLOCATION_CACHE_BACKEND': 'cache.geolocation_cache_backend', 'GEOIPS_LOGGING_DATEFMT_STRING': 'logging.datefmt_string', 'GEOIPS_LOGGING_FMT_STRING': 'logging.fmt_string', 'GEOIPS_LOGGING_LEVEL': 'logging.level', 'GEOIPS_NO_COLOR': 'features.no_color', 'GEOIPS_OPERATIONAL_USER': 'features.operational_user', 'GEOIPS_OUTDIRS': 'outdirs', 'GEOIPS_PACKAGES_DIR': 'packages_dir', 'GEOIPS_PREGENERATED_DYNAMIC_GEOLOCATION': 'pregenerated_dynamic_geolocation', 'GEOIPS_PREGENERATED_STATIC_GEOLOCATION': 'pregenerated_static_geolocation', 'GEOIPS_RCFILE': 'rcfile', 'GEOIPS_REBUILD_REGISTRIES': 'features.rebuild_registries', 'GEOIPS_REPLACE_OUTPUT_PATHS': 'replace_output_paths', 'GEOIPS_RICH_CONSOLE_OUTPUT': 'features.rich_console_output', 'GEOIPS_TC_DECKS_DB': 'output_paths.tc_decks_db', 'GEOIPS_TC_DECKS_DIR': 'output_paths.tc_decks_dir', 'GEOIPS_TC_DECKS_TYPE': 'tc_decks_type', 'GEOIPS_TESTDATA_DIR': 'testdata_dir', 'GEOIPS_TEST_OUTPUT_CHECKER_THRESHOLD_IMAGE': 'test.output_checker_threshold_image', 'GEOIPS_TEST_PRINT_TEXT_OUTPUT_CHECKER_TO_CONSOLE': 'test.print_text_output_checker_to_console', 'GEOIPS_TEST_PROMPT_TO_OVERWRITE_COMPARISON_FILE_IF_MISMATCH': 'test.prompt_to_overwrite_comparison_file_if_mismatch', 'GEOIPS_TEST_SECTOR_CREATE_ANNOTATED_OUTPUTS': 'test.sector_create_annotated_outputs', 'GEOIPS_TEST_SECTOR_CREATE_GEOTIFF_OUTPUTS': 'test.sector_create_geotiff_outputs', 'GEOIPS_TEST_SUPPRESS_PYTEST_FAILED_LOG_CONTENTS': 'test.suppress_pytest_failed_log_contents', 'GEOIPS_USE_PYDANTIC': 'features.use_pydantic', 'GEOIPS_VERSION': 'version', 'GEOIPS_WARNING_LEVEL': 'warning_level', 'GEOTIFF_IMAGERY_PATH': 'output_paths.geotiff_imagery', 'LOCALSCRATCH': 'output_paths.localscratch', 'LOGDIR': 'output_paths.logdir', 'NO_COLOR': 'features.no_color', 'PRECALCULATED_DATA_PATH': 'output_paths.precalculated_data', 'PREGENERATED_GEOLOCATION_PATH': 'output_paths.pregenerated_geolocation', 'PREREAD_DATA_PATH': 'output_paths.preread_data', 'PREREGISTERED_DATA_PATH': 'output_paths.preregistered_data', 'PRESECTORED_DATA_PATH': 'output_paths.presectored_data', 'PRIVATEWWW': 'output_paths.privatewww', 'PRIVATEWWW_URL': 'privatewww_url', 'PUBLICWWW': 'output_paths.publicwww', 'PUBLICWWW_URL': 'publicwww_url', 'SATPY_DATA_CACHE_DIR': 'cache.satpy_data_cache_dir', 'SATPY_DATA_CACHE_DIR_SHORTTERM_CALIBRATED_DATA': 'cache.satpy_cache_shortterm_calibrated_data', 'SATPY_DATA_CACHE_DIR_SHORTTERM_GEOLOCATION_SOLAR_ANGLES': 'cache.satpy_cache_shortterm_geolocation_solar_angles', 'SCRATCH': 'output_paths.scratch', 'SHAREDSCRATCH': 'output_paths.sharedscratch', 'TCPRIVATEWWW': 'output_paths.tcprivatewww', 'TCPRIVATEWWW_URL': 'tcprivatewww_url', 'TCWWW': 'output_paths.tcwww', 'TCWWW_URL': 'tcwww_url', 'TC_TEMPLATE': 'tc_template'}#

Mapping from environment variable names to dotted model field paths.

Used by the config loader to apply env var overrides on top of the settings model. Keys are environment variable names (with or without a GEOIPS_ prefix), and values are dot-separated field paths into the configuration model tree (e.g. features.no_color).

pydantic model geoips.config.schema.GeoSettings[source]#

Bases: BaseModel

Root configuration model for all GeoIPS settings.

Frozen (immutable) after creation. All values are validated against the declared types. Nested models isolate related config groups.

The config loader resolves auto-derived paths (basedir, packages_dir, cache_dir, boxname, output paths) at initialization time.

field base_path: str | None = None#: Path to the installed geoips package (auto-derived).

field basedir: str | None = None#: Base directory for the GeoIPS installation/source.

field boxname: str | None = None#: Hostname/box identifier (auto-derived).

field cache: CacheSettings [Optional]#: Cache directories and backend.

field copyright: str = 'NRL-Monterey'#: Copyright holder.

field copyright_abbreviated: str = 'NRLMRY'#: Abbreviated copyright holder.

field default_queue: str | None = None#: Default job scheduler queue.

field dependencies_dir: str | None = None#: Directory for external dependencies.

field docs_url: str = 'https://nrlmmd-geoips.github.io/geoips/'#: URL for the GeoIPS documentation.

field features: FeatureSettings [Optional]#: Boolean feature toggles.

field home: str | None = None#: Home directory (auto-derived).

field logging: LoggingSettings [Optional]#: Logging configuration.

field outdirs: str [Required]#: Base directory for all GeoIPS output.

field output_paths: OutputPathsSettings [Optional]#: Output sub-directories.

field packages_dir: str | None = None#: Directory containing GeoIPS plugin packages.

field pregenerated_dynamic_geolocation: str = 'longterm_files/geolocation_dynamic'#: Sub-path for pre-generated dynamic geolocation.

field pregenerated_static_geolocation: str = 'longterm_files/geolocation'#: Sub-path for pre-generated static geolocation.

field privatewww_url: str | None = None#: URL for private web output.

field publicwww_url: str | None = None#: URL for public web output.

field rcfile: str = ''#: Path to a GeoIPS rc file, if any.

field replace_output_paths: list[str] [Optional]#: Path names to replace when building output filenames.

field tc_decks_type: str = 'bdecks'#: TC decks type (e.g. ‘bdecks’).

field tc_template: str = 'plugins/yaml/sectors/dynamic/tc_web_template.yaml'#: Path to the TC web sector template.

field tcprivatewww_url: str | None = None#: URL for private TC web output.

field tcwww_url: str | None = None#: URL for TC web output.

field test: TestSettings [Optional]#: Test/comparison configuration.

field testdata_dir: str | None = None#: Directory containing GeoIPS test data.

field version: str = '0.0.0'#: GeoIPS version string.

field warning_level: str = 'default'#: Python warnings filter level.

pydantic model geoips.config.schema.LoggingSettings[source]#

Bases: BaseModel

Logging format and level configuration.

Fields:

datefmt_string (str)
fmt_string (str)
level (str)

field datefmt_string: str = '%d_%H%M%S'#: Logging date format string.

field fmt_string: str = '%(asctime)s %(module)12s.py:%(lineno)-4d %(levelname)7s: %(message)s'#: Logging message format string.

field level: str = 'interactive'#: Logging level (interactive, info, debug, …).

pydantic model geoips.config.schema.OutputPathsSettings[source]#

Bases: BaseModel

Sub-paths for data output directories.

Defaults are relative to outdirs. The config loader resolves relative paths to absolute at initialization time. Environment variables or project YAML may override with absolute paths.

field ancildat: str = 'ancildat'#: Static ancillary data.

field ancildat_autogen: str = 'ancildat_autogen'#: Auto-generated ancillary data.

field annotated_imagery: str = 'preprocessed/annotated_imagery'#: Annotated imagery output.

field clean_imagery: str = 'preprocessed/clean_imagery'#: Clean (unannotated) imagery.

field final_data: str = 'preprocessed/final'#: Final processed data output.

field geoipsdata: str = 'geoipsdata'#: Miscellaneous GeoIPS data.

field geotiff_imagery: str = 'preprocessed/geotiff_imagery'#: GeoTIFF imagery output.

field localscratch: str = 'scratch'#: Node-local scratch directory.

field logdir: str = 'logs'#: Log file directory.

field precalculated_data: str = 'preprocessed/algorithms'#: Pre-calculated algorithm data.

field pregenerated_geolocation: str = 'preprocessed/geolocation'#: Pre-generated geolocation data.

field preread_data: str = 'preprocessed/unsectored'#: Pre-read (unsectored) data.

field preregistered_data: str = 'preprocessed/registered'#: Pre-registered intermediate data.

field presectored_data: str = 'preprocessed/sectored'#: Pre-sectored intermediate data.

field privatewww: str = 'preprocessed/privatewww'#: Private web output.

field publicwww: str = 'preprocessed/publicwww'#: Public web output.

field scratch: str = 'scratch'#: General scratch directory.

field sharedscratch: str = 'scratch'#: Shared scratch directory.

field tc_decks_db: str = 'longterm_files/tc/tc_decks.db'#: TC decks database file.

field tc_decks_dir: str = 'longterm_files/tc/decks'#: TC deck files directory.

field tcprivatewww: str = 'preprocessed/tcprivatewww'#: Private TC web output.

field tcwww: str = 'preprocessed/tcwww'#: TC web output.

pydantic model geoips.config.schema.TestSettings[source]#

Bases: BaseModel

Test-related configuration for output checking and comparison.

Fields:

output_checker_threshold_image (float)
print_text_output_checker_to_console (bool)
prompt_to_overwrite_comparison_file_if_mismatch (bool)
sector_create_annotated_outputs (bool)
sector_create_geotiff_outputs (bool)
suppress_pytest_failed_log_contents (bool)

field output_checker_threshold_image: float = 0.05#: Image comparison difference threshold.

field print_text_output_checker_to_console: bool = True#: Print text output-checker diffs to the console.

field prompt_to_overwrite_comparison_file_if_mismatch: bool = False#: Prompt to overwrite comparison files on mismatch.

field sector_create_annotated_outputs: bool = False#: Create annotated outputs during sector tests.

field sector_create_geotiff_outputs: bool = False#: Create GeoTIFF outputs during sector tests.

field suppress_pytest_failed_log_contents: bool = False#: Suppress log contents for failed pytest output.

geoips.config.yaml_loader module#

YAML configuration file loading utilities.

Searches for project-level GeoIPS configuration files in multiple locations, following a priority order.

geoips.config.yaml_loader.find_project_config(project_config_path: str | None = None) → str | None[source]#

Find the project-level YAML configuration file.

If project_config_path is supplied, only that path is checked. Otherwise, searches locations returned by _default_search_locations() in order, returning the first file path that exists.

Parameters:: project_config_path (str or None, optional) – Explicit project config path to use instead of the default search locations.
Returns:: Absolute path to the found config file, or None if no file was found during default search.
Return type:: str or None
Raises:: FileNotFoundError – If project_config_path is supplied and does not exist.

geoips.config.yaml_loader.load_project_config(project_config_path: str | None = None) → dict | None[source]#

Load the project-level YAML configuration as a dictionary.

Finds and parses the project config file using find_project_config().

Parameters:: project_config_path (str or None, optional) – Explicit project config path to use instead of the default search locations.
Returns:: Parsed YAML dictionary if a config file was found, otherwise None.
Return type:: dict or None

Module contents#

GeoIPS configuration package.

Provides a layered, YAML-based configuration system with environment variable overrides.

Usage:

from geoips.config import config

print(config.outdirs)
print(config.features.no_color)
print(config["GEOIPS_OUTDIRS"])  # backward-compatible dict access

class geoips.config.ConfigPlugin(name: str, settings_model: type[pydantic.main.BaseModel], env_overrides: ~typing.Mapping[str, str] = <factory>)[source]#

Bases: object

Describes the configuration a plugin package contributes to GeoIPS.

Parameters:

name (str) – The plugin namespace key. Settings are exposed as config.plugins.<name> and live under geoips.plugins.<name> in the YAML config file. Must match the entry-point name.
settings_model (type[pydantic.BaseModel]) – A pydantic model describing the plugin’s settings. Fields should provide defaults (or be Optional) so that importing GeoIPS never fails when the plugin is installed but unconfigured.
env_overrides (Mapping[str, str], optional) – Optional explicit environment-variable aliases mapping a full env var name to a model-relative dotted field path (e.g. {"MY_LEGACY_VAR": "max_workers"}). Auto-generated variables are always available in addition to these.

env_overrides: Mapping[str, str]#

name: str#

settings_model: type[pydantic.main.BaseModel]#

class geoips.config.GeoIPSConfig(project_config_path: str | None = None)[source]#

Bases: object

Immutable, layered GeoIPS configuration container.

Configuration is loaded once at construction time with this priority (highest wins):

Environment variables (GEOIPS_* and unprefixed aliases)
Project-level .geoips.yaml file
Pydantic model Field defaults (lowest)

The resulting configuration is frozen — all mutations must be done via model_copy(update=...), which returns a new instance.

Parameters:: project_config_path (str or None, optional) – Override the project config search path. If None, the standard search locations are used.

get(key: str, default: Any = None) → Any[source]#

Get a configuration value by legacy uppercase key.

Parameters:

key (str) – The uppercase legacy key (e.g. GEOIPS_OUTDIRS).
default (Any, optional) – Value to return if the key is not found.

Returns:

The configuration value, or default.

Return type:

Any

property plugins: Any#

Accessor for configuration contributed by external plugin packages.

Returns a namespace supporting attribute access (config.plugins.my_pkg), item access (config.plugins["my_pkg"]), .get(), and iteration over registered plugin names. Plugin modules are imported lazily on first access.

to_legacy_dict() → dict[str, Any][source]#

Return the full configuration as a flat uppercase dictionary.

This mirrors the shape of the old PATHS dict from geoips.filenames.base_paths for backward compatibility.

Deprecated: The flat uppercase dictionary is a backwards-compatibility layer and is slated for removal in a future release. New code should access settings via the structured GeoIPSConfig / GeoSettings attributes instead. geoips.config.schema.GEOIPS_ENV_MAP is the authoritative list of supported environment variables and settings.

Returns:: Flat uppercase-keyed configuration dictionary.
Return type:: dict[str, Any]

pydantic model geoips.config.GeoSettings[source]#

Bases: BaseModel

Root configuration model for all GeoIPS settings.

Frozen (immutable) after creation. All values are validated against the declared types. Nested models isolate related config groups.

The config loader resolves auto-derived paths (basedir, packages_dir, cache_dir, boxname, output paths) at initialization time.

field base_path: str | None = None#: Path to the installed geoips package (auto-derived).

field basedir: str | None = None#: Base directory for the GeoIPS installation/source.

field boxname: str | None = None#: Hostname/box identifier (auto-derived).

field cache: CacheSettings [Optional]#: Cache directories and backend.

field copyright: str = 'NRL-Monterey'#: Copyright holder.

field copyright_abbreviated: str = 'NRLMRY'#: Abbreviated copyright holder.

field default_queue: str | None = None#: Default job scheduler queue.

field dependencies_dir: str | None = None#: Directory for external dependencies.

field docs_url: str = 'https://nrlmmd-geoips.github.io/geoips/'#: URL for the GeoIPS documentation.

field features: FeatureSettings [Optional]#: Boolean feature toggles.

field home: str | None = None#: Home directory (auto-derived).

field logging: LoggingSettings [Optional]#: Logging configuration.

field outdirs: str [Required]#: Base directory for all GeoIPS output.

field output_paths: OutputPathsSettings [Optional]#: Output sub-directories.

field packages_dir: str | None = None#: Directory containing GeoIPS plugin packages.

field pregenerated_dynamic_geolocation: str = 'longterm_files/geolocation_dynamic'#: Sub-path for pre-generated dynamic geolocation.

field pregenerated_static_geolocation: str = 'longterm_files/geolocation'#: Sub-path for pre-generated static geolocation.

field privatewww_url: str | None = None#: URL for private web output.

field publicwww_url: str | None = None#: URL for public web output.

field rcfile: str = ''#: Path to a GeoIPS rc file, if any.

field replace_output_paths: list[str] [Optional]#: Path names to replace when building output filenames.

field tc_decks_type: str = 'bdecks'#: TC decks type (e.g. ‘bdecks’).

field tc_template: str = 'plugins/yaml/sectors/dynamic/tc_web_template.yaml'#: Path to the TC web sector template.

field tcprivatewww_url: str | None = None#: URL for private TC web output.

field tcwww_url: str | None = None#: URL for TC web output.

field test: TestSettings [Optional]#: Test/comparison configuration.

field testdata_dir: str | None = None#: Directory containing GeoIPS test data.

field version: str = '0.0.0'#: GeoIPS version string.

field warning_level: str = 'default'#: Python warnings filter level.

geoips.config.get_config(project_config_path: str | None = None) → GeoIPSConfig[source]#

Return the singleton GeoIPSConfig instance.

Creates the configuration on first call. Subsequent calls return the cached instance.

Parameters:: project_config_path (str or None, optional) – Override the project config search path (only used on first call).
Returns:: The singleton configuration instance.
Return type:: GeoIPSConfig

geoips.config.make_dirs(path: str) → str[source]#

Create directories, catching exceptions if directory already exists.

Parameters:: path (str) – Path to directory to create.
Returns:: path if successfully created.
Return type:: str