freeports_analysis.formats.utils.deserialize
Utils for creating deserialize routines and functions
Functions
|
Convert a percentage string to float value. |
|
Decorator factory that creates a deserializer function for TextBlock metadata. |
|
Convert a string to a Currency enum value. |
|
Convert a date string to a date object using multiple possible formats. |
|
Cast to float in a more loose way than the standard python float namely it removes dots or commas and spaces around the string and handles thousand separators. |
|
Cast to int in a more loose way than the standard python int namely it remove dots or commas and spaces around the string |
|
Normalize a string by stripping whitespace from both ends. |
- freeports_analysis.formats.utils.deserialize.perc_to_float(perc: str, norm: bool = True) float
Convert a percentage string to float value.
Handles various percentage string formats by: - Normalizing the string (removing spaces, converting commas to dots) - Removing percentage signs (if percentage sign is present,
the number gets normalized dividing by 100)
Optionally converting to decimal form (dividing by 100)
- Parameters:
perc (str) – The percentage string to convert (may contain ‘%’, ‘,’, or ‘.’)
norm (bool, optional) – Whether to normalize the result by dividing by 100 (default True) If False, returns the raw numeric value from the string
- Returns:
The converted float value
- Return type:
float
- Raises:
ValueError – If the string cannot be converted to a float after processing
Examples
>>> perc_to_float("5.5%") 0.055 >>> perc_to_float("25,5", norm=False) 25.5 >>> perc_to_float("10 %") 0.1
- freeports_analysis.formats.utils.deserialize.standard_deserialization(cost_and_value_interpret_int: bool = True, quantity_interpret_float: bool = False) Callable[[Callable[[TextBlock], Equity | Bond]], Callable[[TextBlock], Equity | Bond]]
Decorator factory that creates a deserializer function for TextBlock metadata.
This decorator factory creates a standardized deserialization pipeline that transforms TextBlock metadata into structured financial data objects (Equity or Bond). It handles the complete conversion process including type validation, error handling, and financial instrument type detection.
- Parameters:
cost_and_value_interpret_int (bool, optional) – If True, interpret market value and acquisition cost as integers before casting to float. This is useful for handling numbers with thousand separators. Default is True.
quantity_interpret_float (bool, optional) – If True, interpret quantity column as float before casting to int. This handles decimal quantities that should be rounded to integers. Default is False.
- Returns:
A decorator that wraps deserializer functions with standardized processing
- Return type:
Callable[[DeserializeFunc], DeserializeFunc]
Notes
This decorator provides a comprehensive deserialization pipeline that: - Converts text metadata to appropriate Python types - Handles international number formats (commas, dots, spaces) - Supports multiple date formats - Detects financial instrument type (Equity vs Bond) - Provides graceful error handling with detailed logging - Supports Promise objects for deferred value resolution - Validates company names against target lists
The deserialization process extracts the following fields: - company: Normalized company name - company_match: Original matched text - subfund: Subfund identifier - market_value: Numeric market value - currency: Currency enum - nominal_quantity: Quantity as integer - perc_net_assets: Percentage as float - acquisition_cost: Acquisition cost as float - acquisition_currency: Acquisition currency enum - maturity: For bonds only - interest_rate: For bonds only
Examples
>>> @standard_deserialization() >>> def my_deserializer(blk: TextBlock) -> Equity | Bond: >>> # Custom deserialization logic can be added here >>> # The standard processing is applied automatically >>> pass
- freeports_analysis.formats.utils.deserialize.to_currency(data: str) Currency
Convert a string to a Currency enum value.
- Parameters:
data (str) – The currency string to convert (e.g. “USD”, “EUR”)
- Returns:
The corresponding Currency enum value
- Return type:
- Raises:
KeyError – If the string doesn’t match any Currency enum member
Notes
The input string is normalized to uppercase before matching against the Currency enum members. Both 3-letter ISO codes and common names are supported (e.g., “EUR” and “EURO” both map to Currency.EUR).
- freeports_analysis.formats.utils.deserialize.to_date(data: str) date
Convert a date string to a date object using multiple possible formats.
- Parameters:
data (str) – The date string to parse
- Returns:
The parsed date object
- Return type:
date
- Raises:
ValueError – If the string doesn’t match any of the supported date formats
Notes
The function tries multiple date formats in order: - ISO format (YYYY-MM-DD, YYYY/MM/DD) - European format (DD/MM/YYYY, DD.MM.YYYY) - US format (MM-DD-YYYY) - Short formats (DD/MM/YY, MM/YY)
The first matching format is used for parsing.
- freeports_analysis.formats.utils.deserialize.to_float(data: str) float
Cast to float in a more loose way than the standard python float namely it removes dots or commas and spaces around the string and handles thousand separators.
- Parameters:
data (str) – number written in string form
- Returns:
casted result
- Return type:
float
- Raises:
ValueError – the resulting processed string cannot be casted to float
Notes
This function handles various numeric formats including: - Thousand separators (e.g., “1.000.000” -> 1000000.0) - Decimal separators (both ‘.’ and ‘,’) - Mixed separators (e.g., “1,000.50” -> 1000.5) - Whitespace around numbers
- freeports_analysis.formats.utils.deserialize.to_int(data: str) int
Cast to int in a more loose way than the standard python int namely it remove dots or commas and spaces around the string
- Parameters:
data (str) – number written in string form
- Returns:
casted result
- Return type:
int
- Raises:
ValueError – the resulting processed string cannot be casted to int
Notes
This function handles integer formats including: - Thousand separators (e.g., “1.000” -> 1000) - Whitespace around numbers - Decimal points with zero mantissa (e.g., “100.0” -> 100)
Raises ValueError if the number has a non-zero mantissa.
- freeports_analysis.formats.utils.deserialize.to_str(data: str) str
Normalize a string by stripping whitespace from both ends.
- Parameters:
data (str) – The input string to be normalized
- Returns:
The stripped string
- Return type:
str