Configuration

config ¶

Assembly:                Jimi
Filename:                Config.py
Author:                  Terry D. Eppler
Created:                 05-31-2022

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

       Jimi is a df analysis tool integrating GenAI, GptText Processing, and Machine-Learning
       algorithms for federal analysts.
       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

throw_if ¶

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

Raise an exception when a required value is empty.

Purpose

Provides the shared validation guard used by Jimi configuration helpers and provider wrappers. The function raises a ValueError when a required argument or setting is falsy so callers can fail early before using incomplete runtime configuration.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the argument or configuration value being validated.	required
`value`	`object`	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:
	"""Raise an exception when a required value is empty.

	Purpose:
		Provides the shared validation guard used by Jimi configuration helpers and provider
		wrappers. The function raises a ValueError when a required argument or setting is
		falsy so callers can fail early before using incomplete runtime configuration.

	Args:
		name: Name of the argument or configuration value being validated.
		value: 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

Reads optional Boolean configuration from the environment while preserving safe module import behavior. Missing variables return the supplied default, and recognized true values allow deployment settings to control feature flags without changing source code.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`bool`	Value returned when the environment variable is missing or invalid.	`False`

Returns:

Name	Type	Description
`bool`	`bool`	Parsed Boolean value or the supplied default.

Source code in config.py

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

	Purpose:
		Reads optional Boolean configuration from the environment while preserving safe module
		import behavior. Missing variables return the supplied default, and recognized true
		values allow deployment settings to control feature flags without changing source code.

	Args:
		name: Environment variable name.
		default: Value returned when the environment variable is missing or invalid.

	Returns:
		bool: Parsed Boolean value or the supplied default.
	"""
	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 from the environment while keeping Jimi imports stable when deployment variables are missing, empty, or malformed. The helper supports runtime settings such as token limits, thread counts, and other numeric controls.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`int`	Integer value returned when parsing is not possible.	required

Returns:

Name	Type	Description
`int`	`int`	Parsed integer value or the supplied default.

Source code in config.py

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

	Purpose:
		Parses optional integer configuration from the environment while keeping Jimi imports
		stable when deployment variables are missing, empty, or malformed. The helper supports
		runtime settings such as token limits, thread counts, and other numeric controls.

	Args:
		name: Environment variable name.
		default: Integer value returned when parsing is not possible.

	Returns:
		int: Parsed integer value or the supplied default.
	"""
	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 floating-point configuration from the environment while preserving safe defaults for incomplete deployments. The helper supports model sampling, penalty, and threshold settings that may be supplied outside the source tree.

Parameters:

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

Returns:

Name	Type	Description
`float`	`float`	Parsed floating-point value or the supplied default.

Source code in config.py

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

	Purpose:
		Parses optional floating-point configuration from the environment while preserving
		safe defaults for incomplete deployments. The helper supports model sampling,
		penalty, and threshold settings that may be supplied outside the source tree.

	Args:
		name: Environment variable name.
		default: Floating-point value returned when parsing is not possible.

	Returns:
		float: Parsed floating-point value or the supplied default.
	"""
	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 filesystem path environment variable.

Purpose

Resolves optional filesystem configuration from the environment for paths such as logging locations, storage directories, and external assets. Missing or invalid values fall back to the resolved default path so imports remain stable.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`Path`	Default path used when the environment variable is missing or invalid.	required

Returns:

Name	Type	Description
`Path`	`Path`	Resolved environment path or resolved default path.

Source code in config.py

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

	Purpose:
		Resolves optional filesystem configuration from the environment for paths such as
		logging locations, storage directories, and external assets. Missing or invalid values
		fall back to the resolved default path so imports remain stable.

	Args:
		name: Environment variable name.
		default: Default path used when the environment variable is missing or invalid.

	Returns:
		Path: Resolved environment path or resolved default 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 default for missing or empty variables. The helper centralizes simple text settings used by paths, labels, table names, and provider configuration.

Parameters:

Name	Type	Description	Default
`name`	`str`	Environment variable name.	required
`default`	`str`	Text value returned when the environment variable is missing or empty.	required

Returns:

Name	Type	Description
`str`	`str`	Environment value or supplied default.

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
		default for missing or empty variables. The helper centralizes simple text settings
		used by paths, labels, table names, and provider configuration.

	Args:
		name: Environment variable name.
		default: Text value returned when the environment variable is missing or empty.

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