equity-aggregator 0.1.1__py3-none-any.whl → 0.1.5__py3-none-any.whl

equity_aggregator/adapters/data_sources/reference_lookup/openfigi.py

@@ -82,7 +82,7 @@ async def fetch_equity_identification(
 
     cached = load_cache(cache_key)
     if cached is not None:
-        logger.debug("Loaded %d OpenFIGI records from cache.", len(cached))
+        logger.info("Loaded %d OpenFIGI records from cache.", len(cached))
         return cached
 
     # resolve identities using the provided client or a default one
@@ -92,7 +92,7 @@ async def fetch_equity_identification(
     )
 
     save_cache(cache_key, identities)
-    logger.debug("Saved %d OpenFIGI identification records to cache.", len(identities))
+    logger.info("Saved %d OpenFIGI identification records to cache.", len(identities))
     return identities
 
 
@@ -412,16 +412,32 @@ def _to_query_record(equity: RawEquity) -> dict[str, str]:
     """
     Converts a RawEquity object into a dictionary for querying OpenFIGI.
 
+    Specifically requests "Common Stock" securities to avoid duplicates from
+    depositary receipts (DRs), American depositary receipts (ADRs), and other
+    equity-like instruments that represent the same underlying company.
+
     Args:
         equity (RawEquity): The equity containing ISIN, CUSIP, or symbol.
 
     Returns:
-        dict[str, str]: A dict with idType, idValue, and marketSecDes.
+        dict[str, str]: A dict with idType, idValue, and securityType.
     """
     if equity.isin:
-        return {"idType": "ID_ISIN", "idValue": equity.isin, "marketSecDes": "Equity"}
+        return {
+            "idType": "ID_ISIN",
+            "idValue": equity.isin,
+            "securityType": "Common Stock",
+        }
 
     if equity.cusip:
-        return {"idType": "ID_CUSIP", "idValue": equity.cusip, "marketSecDes": "Equity"}
-
-    return {"idType": "TICKER", "idValue": equity.symbol, "marketSecDes": "Equity"}
+        return {
+            "idType": "ID_CUSIP",
+            "idValue": equity.cusip,
+            "securityType": "Common Stock",
+        }
+
+    return {
+        "idType": "TICKER",
+        "idValue": equity.symbol,
+        "securityType": "Common Stock",
+    }

equity_aggregator/cli/dispatcher.py

@@ -25,23 +25,26 @@ def run_command(fn: callable) -> None:
         raise SystemExit(1) from None
 
 
-def dispatch_command(args: Namespace) -> None:
+def dispatch_command(args: Namespace, handlers: dict | None = None) -> None:
     """
     Dispatch execution to the appropriate command handler.
 
     Args:
         args: Parsed command line arguments from argparse.
+        handlers: Optional dictionary mapping command names to handler functions.
+            If not provided, uses the default production handlers.
 
     Raises:
         ValueError: If the command is not recognised.
     """
-    commands = {
-        "seed": lambda: run_command(seed),
-        "export": lambda: run_command(lambda: export(args.output_dir, download)),
-        "download": lambda: run_command(download),
-    }
-
-    handler = commands.get(args.cmd)
+    if handlers is None:
+        handlers = {
+            "seed": lambda: run_command(seed),
+            "export": lambda: run_command(lambda: export(args.output_dir, download)),
+            "download": lambda: run_command(download),
+        }
+
+    handler = handlers.get(args.cmd)
     if handler:
         handler()
     else:

equity_aggregator/cli/main.py

@@ -1,16 +1,18 @@
 # cli/main.py
 
-import os
 import signal
+from collections.abc import Callable
+from typing import Any
 
 from equity_aggregator.logging_config import configure_logging
 
 from .config import determine_log_level
 from .dispatcher import dispatch_command
 from .parser import create_parser
+from .signals import handle_sigint
 
 
-def main() -> None:
+def main(dispatcher: Callable[[Any], None] | None = None) -> None:
     """
     Entry point for the equity-aggregator CLI application.
 
@@ -26,11 +28,18 @@ def main() -> None:
     4. Configures the application logging system
     5. Dispatches to the selected command handler
 
+    Args:
+        dispatcher: Optional callable to dispatch commands. If not provided,
+            uses the default dispatch_command function.
+
     Raises:
         SystemExit: When command execution fails or invalid arguments provided.
     """
-    # Immediate force exit on Ctrl+C
-    signal.signal(signal.SIGINT, lambda s, f: os._exit(130))
+    if dispatcher is None:
+        dispatcher = dispatch_command
+
+    # Install signal handler for clean Ctrl+C handling
+    signal.signal(signal.SIGINT, handle_sigint)
 
     # Create the argument parser with all CLI options and subcommands
     parser = create_parser()
@@ -45,4 +54,4 @@ def main() -> None:
     configure_logging(log_level)
 
     # Dispatch execution to the appropriate command handler
-    dispatch_command(args)
+    dispatcher(args)

equity_aggregator/cli/parser.py

@@ -68,7 +68,7 @@ def _add_subcommands(parser: argparse.ArgumentParser) -> None:
         "seed",
         help="aggregate enriched canonical equity data sourced from data feeds",
         description="execute the full aggregation pipeline to collect equity "
-        "data from authoritative feeds (Euronext, LSE, SEC, XETRA), enrich "
+        "data from discovery feeds (LSEG, SEC, XETRA), enrich "
         "it with data from enrichment feeds, and store as canonical equities",
     )
 

equity_aggregator/cli/signals.py

@@ -0,0 +1,32 @@
+# cli/signals.py
+
+import os
+import sys
+from types import FrameType
+
+
+def handle_sigint(signum: int, frame: FrameType | None) -> None:  # pragma: no cover
+    """
+    Handle SIGINT (Ctrl+C) by exiting immediately.
+
+    When the user presses Ctrl+C, print a clean message and exit immediately
+    with status code 130 (standard Unix convention for SIGINT). Uses os._exit()
+    for immediate termination and redirects stderr to /dev/null to suppress
+    any process cleanup errors from the parent process manager.
+
+    Args:
+        signum: The signal number (SIGINT).
+        frame: The current stack frame.
+    """
+    print("\nOperation cancelled by user", file=sys.stderr)
+    sys.stderr.flush()
+
+    # Redirect stderr to suppress further output during exit
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stderr.fileno())
+        os.close(devnull)
+    except OSError:
+        pass
+
+    os._exit(130)

equity_aggregator/domain/_utils/__init__.py

@@ -1,6 +1,6 @@
 # _utils/__init__.py
 
 from ._load_converter import get_usd_converter
-from ._merge import merge
+from ._merge import EquityIdentifiers, extract_identifiers, merge
 
-__all__ = ["get_usd_converter", "merge"]
+__all__ = ["get_usd_converter", "merge", "extract_identifiers", "EquityIdentifiers"]

equity_aggregator/domain/_utils/_load_converter.py

@@ -11,6 +11,21 @@ logger = logging.getLogger(__name__)
 
 type RawEquityConverter = Callable[[RawEquity], RawEquity]
 
+# All monetary fields that should be converted to USD
+_MONETARY_FIELDS = [
+    "last_price",
+    "market_cap",
+    "fifty_two_week_min",
+    "fifty_two_week_max",
+    "revenue_per_share",
+    "free_cash_flow",
+    "operating_cash_flow",
+    "total_debt",
+    "revenue",
+    "ebitda",
+    "trailing_eps",
+]
+
 
 def _build_usd_converter_loader() -> Callable[[], RawEquityConverter]:
     """
@@ -75,26 +90,21 @@ def _should_skip_conversion(equity: RawEquity) -> bool:
     """
     Determines whether the conversion process should be skipped for a given equity.
 
-    The function checks if both the last price and market cap are missing, if the
-    currency is not specified, or if the currency is already USD. In any of these
-    cases, conversion is deemed unnecessary and the function returns True.
+    The function only skips conversion if the currency is not specified or if the
+    currency is already USD. This ensures that currency normalisation happens
+    even for records with no monetary values.
 
     Args:
-        equity (RawEquity): The equity object containing last price, market cap,
-            and currency information.
+        equity (RawEquity): The equity object containing price fields and currency
+            information.
 
     Returns:
         bool: True if conversion should be skipped, False otherwise.
     """
-    last_price = equity.last_price
-    market_cap = equity.market_cap
     currency = equity.currency
 
-    return (
-        (last_price is None and market_cap is None)
-        or currency is None
-        or currency == "USD"
-    )
+    # Skip only if currency is missing or already USD
+    return currency is None or currency == "USD"
 
 
 def _get_rate_for_currency(currency: str, rates: dict[str, Decimal]) -> Decimal:
@@ -115,7 +125,7 @@ def _get_rate_for_currency(currency: str, rates: dict[str, Decimal]) -> Decimal:
     """
     rate = rates.get(currency)
     if rate is None:
-        raise ValueError(f"Missing FX rate for currency {currency}")
+        raise ValueError(f"Missing FX rate for currency {currency}.")
     return rate
 
 
@@ -134,11 +144,10 @@ def _build_field_updates(equity: RawEquity, rate: Decimal) -> dict[str, Decimal]
     """
     updates: dict[str, Decimal] = {}
 
-    if equity.last_price is not None:
-        updates["last_price"] = _convert_to_usd(equity.last_price, rate)
-
-    if equity.market_cap is not None:
-        updates["market_cap"] = _convert_to_usd(equity.market_cap, rate)
+    for field_name in _MONETARY_FIELDS:
+        field_value = getattr(equity, field_name)
+        if field_value is not None:
+            updates[field_name] = _convert_to_usd(field_value, rate)
 
     return updates
 
@@ -155,9 +164,9 @@ def _convert_to_usd(figure: Decimal, rate: Decimal) -> Decimal:
         Decimal: The equivalent value in USD, rounded to two decimal places.
 
     Raises:
-        ValueError: If the FX rate is zero.
+        ValueError: If the FX rate is zero or negative.
     """
-    if rate == 0:
-        raise ValueError("FX rate cannot be zero")
+    if rate <= 0:
+        raise ValueError("FX rate must be positive")
 
     return (figure / rate).quantize(Decimal("0.01"))