odse 0.1.0__py3-none-any.whl

ods_e/__init__.py

@@ -0,0 +1,13 @@
+"""
+ODS-E: Open Data Schema for Energy
+
+A Python library for validating and transforming energy asset data
+using the ODS-E specification.
+"""
+
+__version__ = "0.1.0"
+
+from .validator import validate, validate_file
+from .transformer import transform, transform_stream
+
+__all__ = ["validate", "validate_file", "transform", "transform_stream"]

ods_e/transformer.py

@@ -0,0 +1,139 @@
+"""
+ODS-E Transformer
+
+Transforms OEM-specific data formats to ODS-E schema.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional, Union
+
+
+def transform(
+    data: Union[str, Path],
+    source: str,
+    asset_id: Optional[str] = None,
+    timezone: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """
+    Transform OEM data to ODS-E format.
+
+    Args:
+        data: Path to data file or data string
+        source: OEM source identifier (e.g., "huawei", "enphase", "solarman")
+        asset_id: Optional asset identifier to include in output
+        timezone: Optional timezone for timestamp conversion
+
+    Returns:
+        List of ODS-E formatted records
+    """
+    transformer = _get_transformer(source)
+    return transformer.transform(data, asset_id=asset_id, timezone=timezone)
+
+
+def transform_stream(
+    data: Union[str, Path],
+    source: str,
+    **kwargs,
+) -> Iterator[Dict[str, Any]]:
+    """
+    Stream transform OEM data to ODS-E format.
+
+    Useful for large files where loading all records into memory
+    is not practical.
+
+    Args:
+        data: Path to data file
+        source: OEM source identifier
+        **kwargs: Additional arguments passed to transformer
+
+    Yields:
+        ODS-E formatted records one at a time
+    """
+    transformer = _get_transformer(source)
+    yield from transformer.transform_stream(data, **kwargs)
+
+
+def _get_transformer(source: str):
+    """Get the appropriate transformer for the source."""
+    transformers = {
+        "huawei": HuaweiTransformer(),
+        "enphase": EnphaseTransformer(),
+        "solarman": SolarmanTransformer(),
+    }
+
+    source_lower = source.lower()
+    if source_lower not in transformers:
+        raise ValueError(
+            f"Unknown source '{source}'. "
+            f"Supported sources: {list(transformers.keys())}"
+        )
+
+    return transformers[source_lower]
+
+
+class BaseTransformer:
+    """Base class for OEM transformers."""
+
+    def transform(
+        self,
+        data: Union[str, Path],
+        **kwargs,
+    ) -> List[Dict[str, Any]]:
+        """Transform data to ODS-E format."""
+        raise NotImplementedError
+
+    def transform_stream(
+        self,
+        data: Union[str, Path],
+        **kwargs,
+    ) -> Iterator[Dict[str, Any]]:
+        """Stream transform data to ODS-E format."""
+        # Default implementation: yield from transform()
+        yield from self.transform(data, **kwargs)
+
+
+class HuaweiTransformer(BaseTransformer):
+    """Transform Huawei FusionSolar data to ODS-E."""
+
+    ERROR_CODES = {
+        "normal": [0, 1, 2, 3, 256, 512, 1025, 1026, 1280, 1281, 1536, 1792, 2048, 2304, 40960, 49152],
+        "warning": [513, 514, 772, 773, 774],
+        "critical": [768, 770, 771, 45056],
+        "fault": [769, 1024],
+    }
+
+    def transform(self, data: Union[str, Path], **kwargs) -> List[Dict[str, Any]]:
+        # Placeholder implementation
+        return []
+
+    def _map_error_code(self, code: int) -> str:
+        for error_type, codes in self.ERROR_CODES.items():
+            if code in codes:
+                return error_type
+        return "unknown"
+
+
+class EnphaseTransformer(BaseTransformer):
+    """Transform Enphase Envoy data to ODS-E."""
+
+    def transform(self, data: Union[str, Path], **kwargs) -> List[Dict[str, Any]]:
+        # Placeholder implementation
+        return []
+
+
+class SolarmanTransformer(BaseTransformer):
+    """Transform Solarman Logger data to ODS-E."""
+
+    STATE_MAPPING = {
+        "Normal": "normal",
+        "Operating": "normal",
+        "Warning": "warning",
+        "Fault": "fault",
+        "Error": "fault",
+        "Offline": "offline",
+        "Standby": "standby",
+    }
+
+    def transform(self, data: Union[str, Path], **kwargs) -> List[Dict[str, Any]]:
+        # Placeholder implementation
+        return []

ods_e/validator.py

@@ -0,0 +1,185 @@
+"""
+ODS-E Validator
+
+Validates energy data against ODS-E JSON schemas.
+"""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Union
+
+
+@dataclass
+class ValidationError:
+    """Represents a validation error."""
+    path: str
+    message: str
+    code: str
+
+
+@dataclass
+class ValidationResult:
+    """Result of a validation operation."""
+    is_valid: bool
+    errors: List[ValidationError]
+    warnings: List[ValidationError]
+    level: str = "schema"
+
+
+def validate(
+    data: Union[dict, str, Path],
+    level: str = "schema",
+    capacity_kw: Optional[float] = None,
+    latitude: Optional[float] = None,
+    longitude: Optional[float] = None,
+) -> ValidationResult:
+    """
+    Validate data against ODS-E production-timeseries schema.
+
+    Args:
+        data: Dictionary, JSON string, or path to JSON file
+        level: Validation level - "schema" or "semantic"
+        capacity_kw: Asset capacity in kW (required for semantic validation)
+        latitude: Asset latitude (optional, for nighttime checks)
+        longitude: Asset longitude (optional, for nighttime checks)
+
+    Returns:
+        ValidationResult with is_valid status and any errors/warnings
+    """
+    # Parse input
+    if isinstance(data, (str, Path)):
+        if Path(data).exists():
+            with open(data) as f:
+                data = json.load(f)
+        else:
+            data = json.loads(data)
+
+    errors = []
+    warnings = []
+
+    # Schema validation
+    errors.extend(_validate_schema(data))
+
+    # Semantic validation
+    if level == "semantic" and not errors:
+        sem_errors, sem_warnings = _validate_semantic(
+            data, capacity_kw, latitude, longitude
+        )
+        errors.extend(sem_errors)
+        warnings.extend(sem_warnings)
+
+    return ValidationResult(
+        is_valid=len(errors) == 0,
+        errors=errors,
+        warnings=warnings,
+        level=level,
+    )
+
+
+def validate_file(
+    file_path: Union[str, Path],
+    level: str = "schema",
+    **kwargs,
+) -> ValidationResult:
+    """
+    Validate a JSON file containing ODS-E data.
+
+    Args:
+        file_path: Path to JSON file
+        level: Validation level
+        **kwargs: Additional arguments passed to validate()
+
+    Returns:
+        ValidationResult
+    """
+    return validate(Path(file_path), level=level, **kwargs)
+
+
+def _validate_schema(data: dict) -> List[ValidationError]:
+    """Validate against JSON schema."""
+    errors = []
+
+    # Required fields
+    required = ["timestamp", "kWh", "error_type"]
+    for field in required:
+        if field not in data:
+            errors.append(ValidationError(
+                path=f"$.{field}",
+                message=f"Required field '{field}' is missing",
+                code="REQUIRED_FIELD_MISSING",
+            ))
+
+    if errors:
+        return errors
+
+    # Type validation
+    if not isinstance(data.get("kWh"), (int, float)):
+        errors.append(ValidationError(
+            path="$.kWh",
+            message=f"Expected number, got {type(data.get('kWh')).__name__}",
+            code="TYPE_MISMATCH",
+        ))
+
+    # Enum validation
+    valid_error_types = [
+        "normal", "warning", "critical", "fault",
+        "offline", "standby", "unknown"
+    ]
+    if data.get("error_type") not in valid_error_types:
+        errors.append(ValidationError(
+            path="$.error_type",
+            message=f"Value '{data.get('error_type')}' not in enum {valid_error_types}",
+            code="ENUM_MISMATCH",
+        ))
+
+    # Bounds validation
+    if isinstance(data.get("kWh"), (int, float)) and data["kWh"] < 0:
+        errors.append(ValidationError(
+            path="$.kWh",
+            message="kWh must be >= 0",
+            code="OUT_OF_BOUNDS",
+        ))
+
+    if "PF" in data:
+        pf = data["PF"]
+        if isinstance(pf, (int, float)) and (pf < 0 or pf > 1):
+            errors.append(ValidationError(
+                path="$.PF",
+                message="Power factor must be between 0 and 1",
+                code="OUT_OF_BOUNDS",
+            ))
+
+    return errors
+
+
+def _validate_semantic(
+    data: dict,
+    capacity_kw: Optional[float],
+    latitude: Optional[float],
+    longitude: Optional[float],
+) -> tuple:
+    """Validate semantic constraints."""
+    errors = []
+    warnings = []
+
+    # Physical bounds check
+    if capacity_kw and isinstance(data.get("kWh"), (int, float)):
+        # Assume 1-hour interval for simplicity
+        max_kwh = capacity_kw * 1.1
+        if data["kWh"] > max_kwh:
+            warnings.append(ValidationError(
+                path="$.kWh",
+                message=f"kWh ({data['kWh']}) exceeds maximum possible ({max_kwh}) for {capacity_kw}kW capacity",
+                code="EXCEEDS_PHYSICAL_MAXIMUM",
+            ))
+
+    # State/production consistency
+    if data.get("error_type") == "offline" and data.get("kWh", 0) > 10:
+        warnings.append(ValidationError(
+            path="$",
+            message=f"Significant production ({data['kWh']} kWh) reported with error_type 'offline'",
+            code="STATE_PRODUCTION_MISMATCH",
+        ))
+
+    return errors, warnings

odse-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: odse
+Version: 0.1.0
+Summary: Open Data Schema for Energy - validation and transformation library
+Author-email: Asoba Corporation <support@asoba.co>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AsobaCloud/odse
+Project-URL: Documentation, https://docs.asoba.co/ona-protocol/overview
+Project-URL: Repository, https://github.com/AsobaCloud/odse
+Keywords: energy,solar,iot,data,schema,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software 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
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# ODS-E: Open Data Schema for Energy
+
+[![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+ODS-E is an open specification for standardizing energy asset data from IoT devices, enabling interoperability across the renewable energy ecosystem.
+
+## Why ODS-E?
+
+- **No Vendor Lock-in**: Your data works with any ODS-E compatible system
+- **Faster Integrations**: Pre-built transforms for common OEMs (Huawei, Enphase, Solarman)
+- **Analytics-Ready**: Standardized error taxonomy and semantic validation
+- **Future-Proof**: CC-BY-SA licensed specification ensures extensions stay open
+
+## Quick Start
+
+```bash
+pip install odse
+```
+
+```python
+from ods_e import validate, transform
+
+# Validate ODS-E data
+result = validate("production_data.json")
+
+# Transform from OEM format
+ods_data = transform("huawei_export.csv", source="huawei")
+```
+
+## Repository Structure
+
+```
+ona-protocol/
+├── LICENSE-SPEC.md       # CC-BY-SA 4.0 (specification, schemas, transforms)
+├── LICENSE-CODE.md       # Apache 2.0 (reference implementation, tools)
+├── spec/                 # Specification documents
+├── schemas/              # JSON Schema definitions
+├── transforms/           # OEM transform specifications
+├── src/                  # Reference implementation
+└── tools/                # CLI tools
+```
+
+## Core Schema
+
+```json
+{
+  "timestamp": "2026-02-05T14:00:00Z",
+  "kWh": 847.5,
+  "error_type": "normal",
+  "PF": 0.98
+}
+```
+
+**Required fields:**
+- `timestamp` - ISO 8601 with timezone
+- `kWh` - Active energy (≥ 0)
+- `error_type` - One of: `normal`, `warning`, `critical`, `fault`, `offline`, `standby`, `unknown`
+
+## Supported OEMs
+
+| OEM | Format | Status |
+|-----|--------|--------|
+| Huawei FusionSolar | CSV, API | ✅ Included |
+| Enphase Envoy | JSON, API | ✅ Included |
+| Solarman Logger | CSV | ✅ Included |
+| SolarEdge | JSON API | ✅ Included |
+| Fronius | JSON API | ✅ Included |
+| Switch Energy | CSV | ✅ Included |
+
+## License
+
+- **Specification, Schemas, Transforms**: [CC-BY-SA 4.0](LICENSE-SPEC.md)
+- **Reference Implementation, Tools**: [Apache 2.0](LICENSE-CODE.md)
+
+## Documentation
+
+- [Full Documentation](https://docs.asoba.co/ona-protocol)
+- [Schema Reference](https://docs.asoba.co/ona-protocol/schemas)
+- [Transform Guide](https://docs.asoba.co/ona-protocol/transforms)
+
+## Contributing
+
+Contributions are welcome. Schema and transform contributions must be licensed under CC-BY-SA 4.0.
+
+---
+
+Maintained by [Asoba Corporation](https://asoba.co)

odse-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ods_e/__init__.py,sha256=1cgVXnHduy-sFJL6IeexDekVE9J1MZccMkUen0FoaNQ,340
+ods_e/transformer.py,sha256=H1PLEFKORTq99HGpDnzKInoqYb5u276iELq6L1bRUC0,3826
+ods_e/validator.py,sha256=oXLCH1Jqpa9HPwjz9DqW0Gzp4Z-qh-D-wp6ehG0m1VQ,5131
+odse-0.1.0.dist-info/METADATA,sha256=yna_LYJo5krC2uNKaxQyOxx-guDif-EfLArtSpuxwcA,3989
+odse-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+odse-0.1.0.dist-info/entry_points.txt,sha256=Q57qBjBH3FOsovuCw3cXGcxveUPKsp2CTLnm0CEwEpk,40
+odse-0.1.0.dist-info/top_level.txt,sha256=HrO3os1RN2ICfcAKoeXAxwvQ0C9nz8q7_kF8aYGCTbM,6
+odse-0.1.0.dist-info/RECORD,,

odse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

odse-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+odse = ods_e.cli:main

odse-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ods_e