freeports_analysis.consts

Provides basic constants and types used by all submodules.

This module facilitates avoiding circular imports by providing shared constants, types, and utility functions for the entire codebase.

Module Attributes

`PromisesResolutionMap`	Type alias for promise resolution mapping.
`PromisesResolutionContext`	Type alias for promise resolution context.

Functions

`flag_from_string`(expression, cls)	Convert a string expression to a Flag object.
`flag_to_string`(flags)	Convert a Flag object to a string representation using bitwise OR syntax.
`flatten_promise_map`(mapping)	Flatten a mapping containing Promise objects by resolving all references.
`input_enum`(enum_cls)	Create an annotated type for Enum input validation.
`input_flags`(flag_cls)	Create an annotated type for Flag input validation.

Classes

`Currency`(*values)	Enumeration of supported currency codes.
`FinancialInstrument`(*values)	Enumeration of financial instrument types.
`Promise`(promise_id)	Base class for deferred value resolution in financial data processing.

Exceptions

CircularPromisesChain

Exception raised when a circular dependency is detected in promise resolution.

exception freeports_analysis.consts.CircularPromisesChain

Exception raised when a circular dependency is detected in promise resolution.

This occurs when a promise chain references itself either directly or indirectly, creating an infinite loop that cannot be resolved.

class freeports_analysis.consts.Currency(*values)

Enumeration of supported currency codes.

Contains standard 3-letter ISO currency codes for major world currencies.

property symbol: str

Get the currency symbol for this currency.

Returns:: The currency symbol
Return type:: str

class freeports_analysis.consts.FinancialInstrument(*values): Enumeration of financial instrument types.

class freeports_analysis.consts.Promise(promise_id: str)

Base class for deferred value resolution in financial data processing.

Implements a promise pattern where values can be resolved later from a mapping.

_id

The unique identifier for this promise

Type:: str

fulfill_with(mapping: PromisesResolutionMap) → Any: Resolves the promised value from the given mapping.

fulfill_with(mapping: Dict[str, Any]) → Any

Resolve this promise’s value from the given mapping.

Parameters:: mapping (PromisesResolutionMap) – Dictionary containing values to resolve promises from
Returns:: The resolved value from the mapping
Return type:: Any

freeports_analysis.consts.PromisesResolutionContext

Type alias for promise resolution context.

A dictionary containing promises and their dependencies during resolution.

alias of Dict[str, Promise | Any]

freeports_analysis.consts.PromisesResolutionMap

Type alias for promise resolution mapping.

A dictionary mapping promise IDs to their resolved values.

alias of Dict[str, Any]

freeports_analysis.consts.flag_from_string(expression: str | list | None, cls: Type[Flag]) → Flag

Convert a string expression to a Flag object.

Parameters:

expression (Optional[Union[str, list]]) – String expression or list of flag names to convert
cls (Type[Flag]) – The Flag class to instantiate

Returns:

Flag object created from the expression

Return type:

Flag

Raises:

ValueError – If the expression contains unsupported operations or invalid flag names

freeports_analysis.consts.flag_to_string(flags: Flag) → str

Convert a Flag object to a string representation using bitwise OR syntax.

Parameters:: flags (Flag) – The flag object to convert to string
Returns:: String representation of flags using ‘|’ as separator
Return type:: str

freeports_analysis.consts.flatten_promise_map(mapping: Dict[str, Any]) → Dict[str, Any]

Flatten a mapping containing Promise objects by resolving all references.

Processes a dictionary that may contain Promise objects, resolving each promise by looking up its value in the mapping until all values are concrete (non-Promise). Detects and prevents circular references that would cause infinite resolution loops.

Parameters:: mapping (PromisesResolutionMap) – Dictionary containing both direct values and Promise objects to be resolved
Returns:: A new dictionary with all Promise objects resolved to their final values
Return type:: PromisesResolutionMap
Raises:: CircularPromisesChain – If a circular reference is detected in the promise resolution chain

Notes

This function implements a depth-first resolution algorithm that follows promise chains until concrete values are found. It maintains a resolution history to detect and prevent infinite loops from circular dependencies.

freeports_analysis.consts.input_enum(enum_cls: Type[S]) → type

Create an annotated type for Enum input validation.

Parameters:: enum_cls (Type[S]) – The Enum class to validate against
Returns:: Annotated type for Pydantic validation
Return type:: type

freeports_analysis.consts.input_flags(flag_cls: Type[T]) → type

Create an annotated type for Flag input validation.

Parameters:: flag_cls (Type[T]) – The Flag class to validate against
Returns:: Annotated type for Pydantic validation
Return type:: type