config

openplaces configuration management

Hierarchical configuration system with interactive first-use setup.

Priority (highest to lowest): 1. User config (~/.config/openplaces/<username>.yaml) - User-specific overrides 2. Project config (./openplaces.yaml) - Project defaults 3. Built-in defaults - Fallback values

On first use, users are prompted to customize directory paths or accept defaults.

Classes

OpenPlacesConfig

Configuration manager with interactive first-use setup.

Functions

get_config(→ OpenPlacesConfig)	Get or create the global configuration instance.
reset_config()	Delete user config file and reset to defaults.
show_config()	Display current configuration file location and contents.
show_credentials()	Show credentials file path and registered services (no secrets printed).
edit_config()	Open user config file in default editor.
reload_config(→ OpenPlacesConfig)	Reload configuration from disk.

Module Contents

class openplaces.config.OpenPlacesConfig(project_config_path: pathlib.Path | None = None, interactive: bool = True)

Configuration manager with interactive first-use setup.

get_dir(name: str) → pathlib.Path

Get directory path by name.

Parameters:

name (str) – Directory name (e.g., ‘raw’, ‘core’, ‘out’)

Returns:

Resolved directory path

Return type:

Path

Raises:

KeyError – If directory name not found

list_directories() → dict[str, pathlib.Path]

Return dictionary of all configured directories.

add_custom_directory(name: str, path: str, description: str = '')

Add a custom directory to configuration.

Parameters:

• name (str) – Directory key name

• path (str) – Directory path (relative or absolute)

• description (str, optional) – Description of directory purpose

property data_root: pathlib.Path

Data root directory.

property core_dir: pathlib.Path

Core processed data directory.

property external_dir: pathlib.Path

External data sources directory.

property raw_dir: pathlib.Path

Raw downloaded data directory.

property cache_dir: pathlib.Path

Cache directory for intermediate files.

property heap_dir: pathlib.Path

Heap directory for freshly unzipped data.

property logs_dir: pathlib.Path

Heap directory for freshly unzipped data.

property out_dir: pathlib.Path

Output data directory.

property share_dir: pathlib.Path

Shared data directory.

property models_dir: pathlib.Path

Models directory.

property reports_dir: pathlib.Path

Reports directory.

property credentials_path: pathlib.Path

Path to the credentials file.

get_credentials(service_id: str) → dict

Return credential dict for service_id from credentials.yaml.

Parameters:

service_id – Key used in credentials.yaml (e.g. 'google_streetview').

Returns:

Credential fields for the service (e.g. {'api_key': '...'})

Return type:

dict

Raises:

ValueError – If service_id is absent from the credentials file, with a ready-to-paste YAML snippet showing what to add.

get(key: str, default: Any = None) → Any

Get configuration value with optional default.

openplaces.config.get_config(interactive: bool = True) → OpenPlacesConfig

Get or create the global configuration instance.

Parameters:

interactive (bool, default False) – Whether to prompt user for configuration on first use. Should be False for normal imports, True for CLI setup commands.

Returns:

The global configuration instance

Return type:

OpenPlacesConfig

openplaces.config.reset_config()

Delete user config file and reset to defaults.

This will trigger the interactive setup on next import.

openplaces.config.show_config()

Display current configuration file location and contents.

openplaces.config.show_credentials()

Show credentials file path and registered services (no secrets printed).

openplaces.config.edit_config()

Open user config file in default editor.

openplaces.config.reload_config(interactive: bool = False) → OpenPlacesConfig

Reload configuration from disk.

Parameters:

interactive (bool, default False) – Whether to prompt if config doesn’t exist.

Returns:

Fresh configuration instance

Return type:

OpenPlacesConfig