feat(DISPLAY-001): add underlying mode switching
This commit is contained in:
Bu5hm4nn
322
app/domain/conversions.py
Normal file
322
app/domain/conversions.py
Normal file
@@ -0,0 +1,322 @@
|
||||
"""Conversion layer for display mode switching.
|
||||
|
||||
Provides functions to convert positions between different display modes:
|
||||
- GLD: shares (for GLD ETF)
|
||||
- XAU_OZ: troy ounces of gold
|
||||
- XAU_G: grams of gold
|
||||
- GCF: gold futures contracts (GC=F)
|
||||
|
||||
All conversions use the position's entry_date for historical accuracy.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import date
|
||||
from decimal import Decimal
|
||||
|
||||
from app.domain.instruments import GC_F_OUNCES_PER_CONTRACT, gld_ounces_per_share
|
||||
from app.models.position import Position
|
||||
|
||||
# Constants
|
||||
GRAMS_PER_OUNCE = Decimal("31.1035") # 1 troy oz = 31.1035 grams
|
||||
|
||||
|
||||
def _gld_shares_to_ounces(position: Position, reference_date: date | None = None) -> Decimal:
|
||||
"""Convert GLD shares to troy ounces using historical backing ratio."""
|
||||
if position.underlying != "GLD":
|
||||
raise ValueError(f"Cannot convert non-GLD position ({position.underlying}) to ounces")
|
||||
if position.unit != "shares":
|
||||
raise ValueError(f"GLD position must be in shares, got {position.unit}")
|
||||
|
||||
oz_per_share = gld_ounces_per_share(reference_date or position.entry_date)
|
||||
return position.quantity * oz_per_share
|
||||
|
||||
|
||||
def _gld_shares_to_grams(position: Position, reference_date: date | None = None) -> Decimal:
|
||||
"""Convert GLD shares to grams using historical backing ratio."""
|
||||
ounces = _gld_shares_to_ounces(position, reference_date)
|
||||
return ounces * GRAMS_PER_OUNCE
|
||||
|
||||
|
||||
def _gld_shares_to_contracts(position: Position, reference_date: date | None = None) -> Decimal:
|
||||
"""Convert GLD shares to GC=F contracts."""
|
||||
ounces = _gld_shares_to_ounces(position, reference_date)
|
||||
return ounces / GC_F_OUNCES_PER_CONTRACT
|
||||
|
||||
|
||||
def _ounces_to_gld_shares(ounces: Decimal, reference_date: date | None = None) -> Decimal:
|
||||
"""Convert troy ounces to GLD shares using historical backing ratio."""
|
||||
oz_per_share = gld_ounces_per_share(reference_date or date.today())
|
||||
if oz_per_share <= 0:
|
||||
raise ValueError("GLD ounces per share must be positive")
|
||||
return ounces / oz_per_share
|
||||
|
||||
|
||||
def _grams_to_gld_shares(grams: Decimal, reference_date: date | None = None) -> Decimal:
|
||||
"""Convert grams to GLD shares using historical backing ratio."""
|
||||
ounces = grams / GRAMS_PER_OUNCE
|
||||
return _ounces_to_gld_shares(ounces, reference_date)
|
||||
|
||||
|
||||
def _contracts_to_gld_shares(contracts: Decimal, reference_date: date | None = None) -> Decimal:
|
||||
"""Convert GC=F contracts to GLD shares using historical backing ratio."""
|
||||
ounces = contracts * GC_F_OUNCES_PER_CONTRACT
|
||||
return _ounces_to_gld_shares(ounces, reference_date)
|
||||
|
||||
|
||||
def _xau_oz_to_grams(ounces: Decimal) -> Decimal:
|
||||
"""Convert troy ounces to grams."""
|
||||
return ounces * GRAMS_PER_OUNCE
|
||||
|
||||
|
||||
def _xau_g_to_ounces(grams: Decimal) -> Decimal:
|
||||
"""Convert grams to troy ounces."""
|
||||
return grams / GRAMS_PER_OUNCE
|
||||
|
||||
|
||||
def _xau_oz_to_contracts(ounces: Decimal) -> Decimal:
|
||||
"""Convert troy ounces to GC=F contracts."""
|
||||
return ounces / GC_F_OUNCES_PER_CONTRACT
|
||||
|
||||
|
||||
def _contracts_to_xau_oz(contracts: Decimal) -> Decimal:
|
||||
"""Convert GC=F contracts to troy ounces."""
|
||||
return contracts * GC_F_OUNCES_PER_CONTRACT
|
||||
|
||||
|
||||
def position_to_display_units(
|
||||
position: Position,
|
||||
display_mode: str,
|
||||
reference_date: date | None = None,
|
||||
) -> tuple[Decimal, str]:
|
||||
"""Convert a position to display units based on the selected display mode.
|
||||
|
||||
Args:
|
||||
position: The position to convert
|
||||
display_mode: One of "GLD", "XAU_OZ", "XAU_G", "GCF"
|
||||
reference_date: Date for historical conversion (defaults to position.entry_date)
|
||||
|
||||
Returns:
|
||||
Tuple of (quantity in display units, display unit label)
|
||||
|
||||
Examples:
|
||||
>>> from datetime import date
|
||||
>>> from decimal import Decimal
|
||||
>>> from app.models.position import create_position
|
||||
>>> pos = create_position("GLD", Decimal("100"), "shares", Decimal("230"))
|
||||
>>> qty, unit = position_to_display_units(pos, "XAU_OZ")
|
||||
>>> float(qty) > 0 and unit == "oz"
|
||||
True
|
||||
"""
|
||||
ref_date = reference_date or position.entry_date
|
||||
|
||||
if display_mode == "GLD":
|
||||
# Show GLD shares as-is
|
||||
if position.underlying == "GLD" and position.unit == "shares":
|
||||
return position.quantity, "shares"
|
||||
# Convert other formats to GLD shares
|
||||
if position.underlying == "GLD" and position.unit == "oz":
|
||||
shares = _ounces_to_gld_shares(position.quantity, ref_date)
|
||||
return shares, "shares"
|
||||
if position.underlying == "GLD" and position.unit == "g":
|
||||
shares = _grams_to_gld_shares(position.quantity, ref_date)
|
||||
return shares, "shares"
|
||||
if position.underlying == "GC=F" and position.unit == "contracts":
|
||||
shares = _contracts_to_gld_shares(position.quantity, ref_date)
|
||||
return shares, "shares"
|
||||
# XAU positions
|
||||
if position.underlying == "XAU":
|
||||
if position.unit == "oz":
|
||||
shares = _ounces_to_gld_shares(position.quantity, ref_date)
|
||||
return shares, "shares"
|
||||
if position.unit == "g":
|
||||
shares = _grams_to_gld_shares(position.quantity, ref_date)
|
||||
return shares, "shares"
|
||||
|
||||
elif display_mode == "XAU_OZ":
|
||||
# Show everything in troy ounces
|
||||
if position.underlying == "GLD" and position.unit == "shares":
|
||||
ounces = _gld_shares_to_ounces(position, ref_date)
|
||||
return ounces, "oz"
|
||||
if position.underlying == "GLD" and position.unit == "oz":
|
||||
return position.quantity, "oz"
|
||||
if position.underlying == "GLD" and position.unit == "g":
|
||||
return _xau_g_to_ounces(position.quantity), "oz"
|
||||
if position.underlying == "GC=F" and position.unit == "contracts":
|
||||
ounces = position.quantity * GC_F_OUNCES_PER_CONTRACT
|
||||
return ounces, "oz"
|
||||
if position.underlying == "XAU":
|
||||
if position.unit == "oz":
|
||||
return position.quantity, "oz"
|
||||
if position.unit == "g":
|
||||
return _xau_g_to_ounces(position.quantity), "oz"
|
||||
|
||||
elif display_mode == "XAU_G":
|
||||
# Show everything in grams
|
||||
if position.underlying == "GLD" and position.unit == "shares":
|
||||
grams = _gld_shares_to_grams(position, ref_date)
|
||||
return grams, "g"
|
||||
if position.underlying == "GLD" and position.unit == "oz":
|
||||
ounces = position.quantity
|
||||
return _xau_oz_to_grams(ounces), "g"
|
||||
if position.underlying == "GLD" and position.unit == "g":
|
||||
return position.quantity, "g"
|
||||
if position.underlying == "GC=F" and position.unit == "contracts":
|
||||
ounces = position.quantity * GC_F_OUNCES_PER_CONTRACT
|
||||
return _xau_oz_to_grams(ounces), "g"
|
||||
if position.underlying == "XAU":
|
||||
if position.unit == "oz":
|
||||
return _xau_oz_to_grams(position.quantity), "g"
|
||||
if position.unit == "g":
|
||||
return position.quantity, "g"
|
||||
|
||||
elif display_mode == "GCF":
|
||||
# Show everything in GC=F contracts
|
||||
if position.underlying == "GLD" and position.unit == "shares":
|
||||
contracts = _gld_shares_to_contracts(position, ref_date)
|
||||
return contracts, "contracts"
|
||||
if position.underlying == "GLD" and position.unit == "oz":
|
||||
contracts = _xau_oz_to_contracts(position.quantity)
|
||||
return contracts, "contracts"
|
||||
if position.underlying == "GLD" and position.unit == "g":
|
||||
ounces = _xau_g_to_ounces(position.quantity)
|
||||
contracts = _xau_oz_to_contracts(ounces)
|
||||
return contracts, "contracts"
|
||||
if position.underlying == "GC=F" and position.unit == "contracts":
|
||||
return position.quantity, "contracts"
|
||||
if position.underlying == "XAU":
|
||||
if position.unit == "oz":
|
||||
contracts = _xau_oz_to_contracts(position.quantity)
|
||||
return contracts, "contracts"
|
||||
if position.unit == "g":
|
||||
ounces = _xau_g_to_ounces(position.quantity)
|
||||
contracts = _xau_oz_to_contracts(ounces)
|
||||
return contracts, "contracts"
|
||||
|
||||
# Fallback: return as-is
|
||||
return position.quantity, position.unit
|
||||
|
||||
|
||||
def collateral_to_display_units(
|
||||
gold_ounces: float,
|
||||
display_mode: str,
|
||||
reference_date: date | None = None,
|
||||
) -> tuple[float, str]:
|
||||
"""Convert collateral amount to display units.
|
||||
|
||||
Args:
|
||||
gold_ounces: Collateral amount in troy ounces
|
||||
display_mode: One of "GLD", "XAU_OZ", "XAU_G", "GCF"
|
||||
reference_date: Date for historical conversion (defaults to today)
|
||||
|
||||
Returns:
|
||||
Tuple of (amount in display units, display unit label)
|
||||
"""
|
||||
from decimal import Decimal
|
||||
|
||||
oz_decimal = Decimal(str(gold_ounces))
|
||||
ref_date = reference_date or date.today()
|
||||
|
||||
if display_mode == "GLD":
|
||||
shares = _ounces_to_gld_shares(oz_decimal, ref_date)
|
||||
return float(shares), "shares"
|
||||
elif display_mode == "XAU_OZ":
|
||||
return gold_ounces, "oz"
|
||||
elif display_mode == "XAU_G":
|
||||
grams = _xau_oz_to_grams(oz_decimal)
|
||||
return float(grams), "g"
|
||||
elif display_mode == "GCF":
|
||||
contracts = _xau_oz_to_contracts(oz_decimal)
|
||||
return float(contracts), "contracts"
|
||||
|
||||
return gold_ounces, "oz"
|
||||
|
||||
|
||||
def price_per_display_unit(
|
||||
price_per_oz: float,
|
||||
display_mode: str,
|
||||
reference_date: date | None = None,
|
||||
) -> float:
|
||||
"""Convert price per ounce to price per display unit.
|
||||
|
||||
Args:
|
||||
price_per_oz: Price per troy ounce in USD
|
||||
display_mode: One of "GLD", "XAU_OZ", "XAU_G", "GCF"
|
||||
reference_date: Date for historical conversion (defaults to today)
|
||||
|
||||
Returns:
|
||||
Price per display unit in USD
|
||||
"""
|
||||
from decimal import Decimal
|
||||
|
||||
price = Decimal(str(price_per_oz))
|
||||
ref_date = reference_date or date.today()
|
||||
|
||||
if display_mode == "GLD":
|
||||
# Price per GLD share = price per oz * oz per share
|
||||
oz_per_share = gld_ounces_per_share(ref_date)
|
||||
return float(price * oz_per_share)
|
||||
elif display_mode == "XAU_OZ":
|
||||
return price_per_oz
|
||||
elif display_mode == "XAU_G":
|
||||
# Price per gram = price per oz / grams per oz
|
||||
return float(price / GRAMS_PER_OUNCE)
|
||||
elif display_mode == "GCF":
|
||||
# Price per contract = price per oz * 100 oz
|
||||
return float(price * GC_F_OUNCES_PER_CONTRACT)
|
||||
|
||||
return price_per_oz
|
||||
|
||||
|
||||
def format_display_quantity(quantity: float, unit: str) -> str:
|
||||
"""Format a quantity with appropriate precision for display.
|
||||
|
||||
Args:
|
||||
quantity: Numeric quantity
|
||||
unit: Unit label ("shares", "oz", "g", "contracts")
|
||||
|
||||
Returns:
|
||||
Formatted string with appropriate precision
|
||||
"""
|
||||
if unit == "shares":
|
||||
return f"{quantity:,.0f}"
|
||||
elif unit == "contracts":
|
||||
return f"{quantity:,.0f}"
|
||||
elif unit == "oz":
|
||||
return f"{quantity:,.4f}"
|
||||
elif unit == "g":
|
||||
return f"{quantity:,.2f}"
|
||||
else:
|
||||
return f"{quantity:,.4f}"
|
||||
|
||||
|
||||
def get_display_mode_label(display_mode: str) -> str:
|
||||
"""Get human-readable label for display mode.
|
||||
|
||||
Args:
|
||||
display_mode: One of "GLD", "XAU_OZ", "XAU_G", "GCF"
|
||||
|
||||
Returns:
|
||||
Human-readable label
|
||||
"""
|
||||
labels = {
|
||||
"GLD": "GLD Shares",
|
||||
"XAU_OZ": "Gold (Troy Ounces)",
|
||||
"XAU_G": "Gold (Grams)",
|
||||
"GCF": "GC=F Contracts",
|
||||
}
|
||||
return labels.get(display_mode, display_mode)
|
||||
|
||||
|
||||
def get_display_mode_options() -> dict[str, str]:
|
||||
"""Get display mode options for UI selector.
|
||||
|
||||
Returns:
|
||||
Dictionary mapping mode codes to display labels
|
||||
"""
|
||||
return {
|
||||
"GLD": "GLD Shares",
|
||||
"XAU_OZ": "Gold Ounces (troy)",
|
||||
"XAU_G": "Gold Grams",
|
||||
"GCF": "GC=F Contracts",
|
||||
}
|
||||
Reference in New Issue
Block a user