Configuration

config ¶

Assembly:                Mappy
Filename:                config.py
Author:                  Terry D. Eppler
Created:                 05-31-2022

Last Modified By:        Terry D. Eppler
Last Modified On:        05-01-2025

       Mappy is a python framework encapsulating Google Maps, geospatial,
       environmental, astronomical, weather, and data-enrichment functionality.
       Copyright ©  2022  Terry Eppler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

You can contact me at: terryeppler@gmail.com or eppler.terry@epa.gov

config.py

Functions:¶

throw_if ¶

throw_if(name: str, value: object) -> None

Validate that a required configuration value is present.

Purpose

Provides a small import-safe guard for required configuration helper inputs. The function is used by environment readers to validate variable names and default path objects before attempting conversion, while preserving the caller-provided value when validation succeeds.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the argument or configuration value being validated.	required
`value`	`object`	Runtime value to validate.	required

Raises:

Type	Description
`ValueError`	Raised when `value` is falsy.

Source code in config.py

def throw_if( name: str, value: object ) -> None:
	"""Validate that a required configuration value is present.

	Purpose:
		Provides a small import-safe guard for required configuration helper inputs.
		The function is used by environment readers to validate variable names and
		default path objects before attempting conversion, while preserving the
		caller-provided value when validation succeeds.

	Args:
		name: Name of the argument or configuration value being validated.
		value: Runtime value to validate.

	Raises:
		ValueError: Raised when ``value`` is falsy.
	"""
	if not value:
		raise ValueError( f'Argument "{name}" cannot be empty!' )

get_bool ¶

get_bool(name: str, default: bool = False) -> bool

Read a Boolean environment variable.

Purpose

Converts optional environment-variable text into a deterministic Boolean value for feature flags and runtime switches. Missing variables return the caller-provided default so importing the configuration module remains safe across local, Streamlit, and deployed environments.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`bool`	Fallback Boolean used when the environment variable is not defined.	`False`

Returns:

Name	Type	Description
`bool`	`bool`	Parsed Boolean value, or `default` when parsing is not possible.

Source code in config.py

def get_bool( name: str, default: bool = False ) -> bool:
	"""Read a Boolean environment variable.

	Purpose:
		Converts optional environment-variable text into a deterministic Boolean
		value for feature flags and runtime switches. Missing variables return the
		caller-provided default so importing the configuration module remains safe
		across local, Streamlit, and deployed environments.

	Args:
		name: Environment variable name.
		default: Fallback Boolean used when the environment variable is not defined.

	Returns:
		bool: Parsed Boolean value, or ``default`` when parsing is not possible.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value is None else value.strip( ).lower( ) in (
				'1',
				'true',
				'yes',
				'y',
				'on'
		)
	except Exception:
		return default

get_int ¶

get_int(name: str, default: int) -> int

Read an integer environment variable.

Purpose

Parses optional integer configuration while preserving a safe fallback when the environment variable is missing, empty, or malformed. This supports deployment-specific settings without making module import dependent on a complete environment.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`int`	Fallback integer used when parsing is not possible.	required

Returns:

Name	Type	Description
`int`	`int`	Parsed integer value, or `default` when parsing fails.

Source code in config.py

def get_int( name: str, default: int ) -> int:
	"""Read an integer environment variable.

	Purpose:
		Parses optional integer configuration while preserving a safe fallback when
		the environment variable is missing, empty, or malformed. This supports
		deployment-specific settings without making module import dependent on a
		complete environment.

	Args:
		name: Environment variable name.
		default: Fallback integer used when parsing is not possible.

	Returns:
		int: Parsed integer value, or ``default`` when parsing fails.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value in (None, '') else int( str( value ).strip( ) )
	except Exception:
		return default

get_float ¶

get_float(name: str, default: float) -> float

Read a floating-point environment variable.

Purpose

Parses optional numeric configuration while preserving a safe fallback when the environment variable is missing, empty, or malformed. This helper is used for runtime settings that may vary between local execution and hosted deployments.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`float`	Fallback floating-point value used when parsing is not possible.	required

Returns:

Name	Type	Description
`float`	`float`	Parsed floating-point value, or `default` when parsing fails.

Source code in config.py

def get_float( name: str, default: float ) -> float:
	"""Read a floating-point environment variable.

	Purpose:
		Parses optional numeric configuration while preserving a safe fallback when
		the environment variable is missing, empty, or malformed. This helper is used
		for runtime settings that may vary between local execution and hosted
		deployments.

	Args:
		name: Environment variable name.
		default: Fallback floating-point value used when parsing is not possible.

	Returns:
		float: Parsed floating-point value, or ``default`` when parsing fails.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value in (None, '') else float( str( value ).strip( ) )
	except Exception:
		return default

get_path ¶

get_path(name: str, default: Path) -> Path

Read a path environment variable.

Purpose

Resolves optional filesystem configuration from the environment while preserving a known default path. The helper keeps log, data, resource, and application paths centralized without interrupting import when deployment configuration is incomplete.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`Path`	Fallback path used when the environment variable is not defined.	required

Returns:

Name	Type	Description
`Path`	`Path`	Resolved environment path, or the resolved fallback path.

Source code in config.py

def get_path( name: str, default: Path ) -> Path:
	"""Read a path environment variable.

	Purpose:
		Resolves optional filesystem configuration from the environment while
		preserving a known default path. The helper keeps log, data, resource, and
		application paths centralized without interrupting import when deployment
		configuration is incomplete.

	Args:
		name: Environment variable name.
		default: Fallback path used when the environment variable is not defined.

	Returns:
		Path: Resolved environment path, or the resolved fallback path.
	"""
	try:
		throw_if( 'name', name )
		throw_if( 'default', default )
		value = os.getenv( name )
		return Path( value ).resolve( ) if value else default.resolve( )
	except Exception:
		return default.resolve( )

get_text ¶

get_text(name: str, default: str) -> str

Read a text environment variable.

Purpose

Returns optional text configuration from the environment while preserving the supplied fallback when the variable is missing or empty. This keeps API, logging, resource, and app metadata configuration centralized and stable during early application startup.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`str`	Fallback text value.	required

Returns:

Name	Type	Description
`str`	`str`	Environment value, or `default` when no usable value exists.

Source code in config.py

def get_text( name: str, default: str ) -> str:
	"""Read a text environment variable.

	Purpose:
		Returns optional text configuration from the environment while preserving
		the supplied fallback when the variable is missing or empty. This keeps API,
		logging, resource, and app metadata configuration centralized and stable
		during early application startup.

	Args:
		name: Environment variable name.
		default: Fallback text value.

	Returns:
		str: Environment value, or ``default`` when no usable value exists.
	"""
	try:
		throw_if( 'name', name )
		value = os.getenv( name )
		return default if value in (None, '') else str( value )
	except Exception:
		return default