Metadata-Version: 2.4
Name: esio-units
Version: 0.1.0
Summary: Hub-and-spoke unit conversion library for industrial IoT
Home-page: https://github.com/edgestack/esio-units
Author: EdgeStack
Author-email: info@edgestack.com
Project-URL: Bug Reports, https://github.com/edgestack/esio-units/issues
Project-URL: Source, https://github.com/edgestack/esio-units
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# esio-units

A high-performance hub-and-spoke unit conversion library for industrial IoT applications, designed to handle complex unit conversions with scale and offset support.

## Features

- 🎯 **Hub-and-Spoke Pattern**: Efficient O(N) conversion system instead of O(N²)
- 🔄 **Bidirectional Conversion**: Guaranteed round-trip accuracy
- 📊 **Scale & Offset Support**: Handle device-specific scaling
- 🏭 **Industrial Focus**: Units for oil & gas, manufacturing, utilities
- ⚡ **High Performance**: Optimized for IoT telemetry processing
- 🛡️ **Type Safe**: Full type hints and validation

## Why Hub-and-Spoke?

Traditional unit conversion libraries require N×(N-1) conversion functions for N units. Our hub-and-spoke pattern requires only 2N functions, making it much more maintainable and extensible.

```
Traditional: °F↔°C, °F↔K, °F↔°R, °C↔K, °C↔°R, K↔°R = 6 functions for 4 units
Hub-and-Spoke: °F↔K, °C↔K, °R↔K = 6 functions (3×2) for 4 units
Adding °Ra: Traditional needs +4 functions, Hub-and-spoke needs +2
```

## Installation

```bash
pip install esio-units
```

## Quick Start

```python
from esio_units import convert, convert_with_scale

# Simple conversion
celsius = 25.0
fahrenheit = convert(celsius, 'degC', 'degF')
print(f"{celsius}°C = {fahrenheit}°F")  # 25.0°C = 77.0°F

# With scale and offset (device reports 0-100 for -50°C to +150°C)
device_value = 50  # Mid-scale
actual_celsius = convert_with_scale(
    value=device_value,
    from_unit='percent',
    to_unit='degC',
    from_scale=(0, 100),
    to_scale=(-50, 150)
)
print(f"Device {device_value}% = {actual_celsius}°C")  # Device 50% = 50.0°C

# Round-trip verification
original = 100.5
converted = convert(original, 'psi', 'bar')
back = convert(converted, 'bar', 'psi')
print(f"Round-trip: {original} → {converted} → {back}")
# Round-trip: 100.5 → 6.929 → 100.5
```

## Supported Categories

### Temperature
- Hub: Kelvin (K)
- Units: K, °C (degC), °F (degF), °R (degR)

### Pressure
- Hub: Pascal (Pa)
- Units: Pa, kPa, MPa, bar, psi, atm, mmHg, inHg

### Length
- Hub: Meter (m)
- Units: m, km, cm, mm, ft, in, mi, yd

### Mass
- Hub: Kilogram (kg)
- Units: kg, g, mg, lb, oz, ton, metric_ton

### Volume
- Hub: Cubic Meter (m³)
- Units: m3, L, mL, gal, ft3, bbl, cf

### Flow Rate
- Hub: Cubic Meter per Second (m³/s)
- Units: m3/s, L/s, L/min, gpm, cfm, bbl/day

### Power
- Hub: Watt (W)
- Units: W, kW, MW, hp, BTU/h

### Energy
- Hub: Joule (J)
- Units: J, kJ, MJ, kWh, BTU, cal

### Dimensionless
- Hub: Ratio (0-1)
- Units: ratio, percent, ppm, ppb

## Advanced Usage

### Custom Scale Conversions

```python
from esio_units import ScaleConverter

# Device outputs 4-20mA for 0-100 psi
converter = ScaleConverter(
    from_unit='mA',
    to_unit='psi',
    from_range=(4, 20),
    to_range=(0, 100)
)

current = 12  # mA
pressure = converter.convert(current)
print(f"{current}mA = {pressure} psi")  # 12mA = 50.0 psi
```

### Unit Registry

```python
from esio_units import UnitRegistry

registry = UnitRegistry()

# Get all units in a category
temp_units = registry.get_category_units('temperature')
print(f"Temperature units: {temp_units}")

# Get hub unit for category
hub = registry.get_hub_unit('pressure')
print(f"Pressure hub: {hub}")  # Pressure hub: Pa

# Check if conversion is possible
can_convert = registry.can_convert('degC', 'psi')
print(f"Can convert °C to PSI: {can_convert}")  # False
```

### Validation

```python
from esio_units import validate_conversion

# Check if conversion is valid
is_valid = validate_conversion('degF', 'degC')  # True
is_invalid = validate_conversion('degF', 'kg')  # False

# Get conversion path
from esio_units import get_conversion_path

path = get_conversion_path('psi', 'bar')
print(f"Conversion path: {path}")
# Conversion path: ['psi', 'Pa', 'bar']
```

## Performance

The library is optimized for high-throughput telemetry processing:

- Conversion functions are cached after first use
- No string parsing in hot paths
- Minimal object allocation
- Thread-safe for concurrent processing

## Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=esio_units

# Run specific category tests
pytest tests/test_temperature.py
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see LICENSE file for details

## Acknowledgments

Built for the EdgeStack IoT platform to provide reliable, efficient unit conversions for industrial telemetry data.
