additory 0.1.0a4__py3-none-any.whl → 0.1.1a2__py3-none-any.whl

additory/common/unit_conversions.py

@@ -0,0 +1,338 @@
+"""
+Unit conversion utilities for Additory.
+
+Provides conversion between different units (weight, temperature, distance, etc.).
+"""
+
+from typing import Dict, Optional
+
+
+# Conversion factors to base units
+WEIGHT_TO_KG = {
+    'kg': 1.0,
+    'g': 0.001,
+    'lb': 0.453592,
+    'oz': 0.0283495,
+    'ton': 1000.0
+}
+
+DISTANCE_TO_M = {
+    'm': 1.0,
+    'km': 1000.0,
+    'cm': 0.01,
+    'mi': 1609.34,
+    'ft': 0.3048,
+    'in': 0.0254
+}
+
+VOLUME_TO_L = {
+    'L': 1.0,
+    'mL': 0.001,
+    'gal': 3.78541,  # US gallon
+    'qt': 0.946353,  # US quart
+    'pt': 0.473176,  # US pint
+    'cup': 0.236588  # US cup
+}
+
+TIME_TO_S = {
+    's': 1.0,
+    'min': 60.0,
+    'h': 3600.0,
+    'day': 86400.0,
+    'week': 604800.0
+}
+
+# Built-in exchange rates (as of library version)
+# Note: In production, these would be updated regularly
+DEFAULT_EXCHANGE_RATES = {
+    'USD': 1.0,  # Base currency
+    'EUR': 0.85,
+    'GBP': 0.73,
+    'JPY': 110.0,
+    'CAD': 1.25,
+    'AUD': 1.35,
+    'CHF': 0.92,
+    'CNY': 6.45
+}
+
+# Unit type mappings
+UNIT_TYPES = {
+    # Weight
+    'kg': 'weight', 'g': 'weight', 'lb': 'weight', 'oz': 'weight', 'ton': 'weight',
+    
+    # Temperature
+    'C': 'temperature', 'F': 'temperature', 'K': 'temperature',
+    
+    # Distance
+    'm': 'distance', 'km': 'distance', 'cm': 'distance', 
+    'mi': 'distance', 'ft': 'distance', 'in': 'distance',
+    
+    # Volume
+    'L': 'volume', 'mL': 'volume', 'gal': 'volume', 
+    'qt': 'volume', 'pt': 'volume', 'cup': 'volume',
+    
+    # Time
+    's': 'time', 'min': 'time', 'h': 'time', 'day': 'time', 'week': 'time',
+    
+    # Currency (common ones)
+    'USD': 'currency', 'EUR': 'currency', 'GBP': 'currency', 
+    'JPY': 'currency', 'CAD': 'currency', 'AUD': 'currency',
+    'CHF': 'currency', 'CNY': 'currency'
+}
+
+
+def convert_weight(value: float, from_unit: str, to_unit: str) -> float:
+    """
+    Convert weight between units.
+    
+    Args:
+        value: Value to convert
+        from_unit: Source unit ('kg', 'lb', 'g', 'oz', 'ton')
+        to_unit: Target unit
+        
+    Returns:
+        Converted value
+        
+    Raises:
+        ValueError: If units are not supported
+        
+    Example:
+        kg_value = convert_weight(150, from_unit='lb', to_unit='kg')
+        # Returns: 68.04
+    """
+    if from_unit not in WEIGHT_TO_KG:
+        raise ValueError(f"Unsupported weight unit: {from_unit}")
+    if to_unit not in WEIGHT_TO_KG:
+        raise ValueError(f"Unsupported weight unit: {to_unit}")
+    
+    # Convert to kg, then to target unit
+    kg_value = value * WEIGHT_TO_KG[from_unit]
+    result = kg_value / WEIGHT_TO_KG[to_unit]
+    
+    return result
+
+
+def convert_temperature(value: float, from_unit: str, to_unit: str) -> float:
+    """
+    Convert temperature between units.
+    
+    Args:
+        value: Value to convert
+        from_unit: Source unit ('C', 'F', 'K')
+        to_unit: Target unit
+        
+    Returns:
+        Converted value
+        
+    Raises:
+        ValueError: If units are not supported
+        
+    Example:
+        celsius = convert_temperature(98.6, from_unit='F', to_unit='C')
+        # Returns: 37.0
+    """
+    supported_units = ['C', 'F', 'K']
+    if from_unit not in supported_units:
+        raise ValueError(f"Unsupported temperature unit: {from_unit}")
+    if to_unit not in supported_units:
+        raise ValueError(f"Unsupported temperature unit: {to_unit}")
+    
+    # Convert to Celsius first
+    if from_unit == 'C':
+        celsius = value
+    elif from_unit == 'F':
+        celsius = (value - 32) * 5/9
+    elif from_unit == 'K':
+        celsius = value - 273.15
+    
+    # Convert from Celsius to target
+    if to_unit == 'C':
+        return celsius
+    elif to_unit == 'F':
+        return (celsius * 9/5) + 32
+    elif to_unit == 'K':
+        return celsius + 273.15
+
+
+def convert_distance(value: float, from_unit: str, to_unit: str) -> float:
+    """
+    Convert distance between units.
+    
+    Args:
+        value: Value to convert
+        from_unit: Source unit ('m', 'km', 'mi', 'ft', 'in', 'cm')
+        to_unit: Target unit
+        
+    Returns:
+        Converted value
+        
+    Raises:
+        ValueError: If units are not supported
+    """
+    if from_unit not in DISTANCE_TO_M:
+        raise ValueError(f"Unsupported distance unit: {from_unit}")
+    if to_unit not in DISTANCE_TO_M:
+        raise ValueError(f"Unsupported distance unit: {to_unit}")
+    
+    # Convert to meters, then to target unit
+    meters = value * DISTANCE_TO_M[from_unit]
+    result = meters / DISTANCE_TO_M[to_unit]
+    
+    return result
+
+
+def convert_currency(value: float, from_currency: str, to_currency: str, 
+                    rates: Optional[Dict[str, float]] = None) -> float:
+    """
+    Convert currency between units.
+    
+    Args:
+        value: Value to convert
+        from_currency: Source currency ('USD', 'EUR', 'GBP', etc.)
+        to_currency: Target currency
+        rates: Optional exchange rates dict (if None, uses built-in rates)
+        
+    Returns:
+        Converted value
+        
+    Raises:
+        ValueError: If currencies are not supported
+        
+    Example:
+        eur_value = convert_currency(100, from_currency='USD', to_currency='EUR')
+    """
+    # Use provided rates or default rates
+    exchange_rates = rates if rates is not None else DEFAULT_EXCHANGE_RATES
+    
+    if from_currency not in exchange_rates:
+        raise ValueError(f"Unsupported currency: {from_currency}")
+    if to_currency not in exchange_rates:
+        raise ValueError(f"Unsupported currency: {to_currency}")
+    
+    # Convert to USD, then to target currency
+    usd_value = value / exchange_rates[from_currency]
+    result = usd_value * exchange_rates[to_currency]
+    
+    return result
+
+
+def convert_volume(value: float, from_unit: str, to_unit: str) -> float:
+    """
+    Convert volume between units.
+    
+    Args:
+        value: Value to convert
+        from_unit: Source unit ('L', 'mL', 'gal', 'qt', 'pt', 'cup')
+        to_unit: Target unit
+        
+    Returns:
+        Converted value
+        
+    Raises:
+        ValueError: If units are not supported
+    """
+    if from_unit not in VOLUME_TO_L:
+        raise ValueError(f"Unsupported volume unit: {from_unit}")
+    if to_unit not in VOLUME_TO_L:
+        raise ValueError(f"Unsupported volume unit: {to_unit}")
+    
+    # Convert to liters, then to target unit
+    liters = value * VOLUME_TO_L[from_unit]
+    result = liters / VOLUME_TO_L[to_unit]
+    
+    return result
+
+
+def convert_time(value: float, from_unit: str, to_unit: str) -> float:
+    """
+    Convert time between units.
+    
+    Args:
+        value: Value to convert
+        from_unit: Source unit ('s', 'min', 'h', 'day', 'week')
+        to_unit: Target unit
+        
+    Returns:
+        Converted value
+        
+    Raises:
+        ValueError: If units are not supported
+    """
+    if from_unit not in TIME_TO_S:
+        raise ValueError(f"Unsupported time unit: {from_unit}")
+    if to_unit not in TIME_TO_S:
+        raise ValueError(f"Unsupported time unit: {to_unit}")
+    
+    # Convert to seconds, then to target unit
+    seconds = value * TIME_TO_S[from_unit]
+    result = seconds / TIME_TO_S[to_unit]
+    
+    return result
+
+
+def get_conversion_factor(from_unit: str, to_unit: str, unit_type: str) -> float:
+    """
+    Get conversion factor between two units.
+    
+    Args:
+        from_unit: Source unit
+        to_unit: Target unit
+        unit_type: Type of unit ('weight', 'distance', 'volume', 'time')
+        
+    Returns:
+        Conversion factor
+        
+    Raises:
+        ValueError: If unit type is not supported or units are invalid
+    """
+    if unit_type == 'weight':
+        if from_unit not in WEIGHT_TO_KG or to_unit not in WEIGHT_TO_KG:
+            raise ValueError(f"Invalid weight units: {from_unit}, {to_unit}")
+        return WEIGHT_TO_KG[from_unit] / WEIGHT_TO_KG[to_unit]
+    
+    elif unit_type == 'distance':
+        if from_unit not in DISTANCE_TO_M or to_unit not in DISTANCE_TO_M:
+            raise ValueError(f"Invalid distance units: {from_unit}, {to_unit}")
+        return DISTANCE_TO_M[from_unit] / DISTANCE_TO_M[to_unit]
+    
+    elif unit_type == 'volume':
+        if from_unit not in VOLUME_TO_L or to_unit not in VOLUME_TO_L:
+            raise ValueError(f"Invalid volume units: {from_unit}, {to_unit}")
+        return VOLUME_TO_L[from_unit] / VOLUME_TO_L[to_unit]
+    
+    elif unit_type == 'time':
+        if from_unit not in TIME_TO_S or to_unit not in TIME_TO_S:
+            raise ValueError(f"Invalid time units: {from_unit}, {to_unit}")
+        return TIME_TO_S[from_unit] / TIME_TO_S[to_unit]
+    
+    elif unit_type == 'temperature':
+        raise ValueError("Temperature conversions require special formulas, use convert_temperature()")
+    
+    elif unit_type == 'currency':
+        raise ValueError("Currency conversions require exchange rates, use convert_currency()")
+    
+    else:
+        raise ValueError(f"Unsupported unit type: {unit_type}")
+
+
+def detect_unit_type(unit: str) -> str:
+    """
+    Detect the type of unit.
+    
+    Args:
+        unit: Unit string
+        
+    Returns:
+        Unit type ('weight', 'temperature', 'distance', 'currency', 'volume', 'time')
+        
+    Raises:
+        ValueError: If unit is not recognized
+        
+    Example:
+        unit_type = detect_unit_type('kg')  # Returns: 'weight'
+        unit_type = detect_unit_type('USD')  # Returns: 'currency'
+    """
+    if unit in UNIT_TYPES:
+        return UNIT_TYPES[unit]
+    else:
+        raise ValueError(f"Unknown unit: {unit}")