openstef-core 4.0.0__tar.gz

openstef_core-4.0.0/.gitignore

@@ -0,0 +1,146 @@
+# SPDX-FileCopyrightText: 2017-2025 Contributors to the OpenSTEF project <openstef@lfenergy.org> # noqa E501>
+# SPDX-License-Identifier: MPL-2.0
+
+# Core
+config.user.yaml
+git-template
+.DS_Store
+tmp
+
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Packaging and build artifacts
+.Python
+build/
+dist/
+downloads/
+wheels/
+share/python-wheels/
+sdist/
+.eggs/
+*.egg-info/
+*.egg
+.installed.cfg
+MANIFEST
+
+# uv
+.uv/
+
+# Ruff
+.ruff_cache/
+
+# Pyright
+.pyright/
+# pyright-report/
+
+# Test, coverage, tox
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.cover/
+cover/
+pytest-report.xml
+.tox/
+.nox/
+coverage.xml
+
+# Hypothesis
+.hypothesis/
+
+# Cython
+cython_debug/
+
+# Type checkers (misc)
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pytype/
+.pyre/
+
+# Sphinx
+docs/_build/
+docs/source/api/generated/
+docs/source/tutorials/
+docs/source/benchmarks/
+docs/source/user_guide/**/quick_start_tutorial.py
+docs/source/user_guide/**/feature_engineering_tutorial.py
+docs/source/user_guide/**/datasets_tutorial.py
+docs/source/user_guide/**/backtesting_tutorial.py
+
+# docs/_doctrees/
+# docs/_static_gen/
+
+# Editors: JetBrains
+.idea/
+
+# Editors: VS Code (allow shared configs)
+.vscode/*
+
+# Jupyter / IPython
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+
+# Spyder / Rope
+.spyderproject
+.spyproject
+.ropeproject
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# PEP 582
+__pypackages__/
+
+# web frameworks / services
+*.sqlite
+*.sqlite3
+*.log
+instance/
+.webassets-cache
+celerybeat-schedule
+celerybeat.pid
+*.sage.py
+tmp/
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Project outputs
+output/
+prof/
+certificates/
+
+# Output artifacts
+*.html
+*.pkl
+
+# Benchmark outputs
+benchmark_results*/
+
+# Local dataset files
+liander_dataset/
+
+# Mlflow
+/mlflow
+/mlflow_artifacts_local
+
+.github/instructions
+
+# Jupyter notebook cache (myst-nb execution outputs)
+.jupyter_cache/
+docs/build.zip

openstef_core-4.0.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: openstef-core
+Version: 4.0.0
+Summary: Core functionality for OpenSTEF, a framework for short-term energy forecasting.
+Project-URL: Documentation, https://openstef.github.io/openstef/index.html
+Project-URL: Homepage, https://lfenergy.org/projects/openstef/
+Project-URL: Issues, https://github.com/OpenSTEF/openstef/issues
+Project-URL: Repository, https://github.com/OpenSTEF/openstef
+Author-email: "Alliander N.V" <openstef@lfenergy.org>
+License-Expression: MPL-2.0
+Keywords: energy,forecasting,machinelearning
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4.0,>=3.12
+Requires-Dist: joblib<2,>=1
+Requires-Dist: numpy<3,>=2.3.2
+Requires-Dist: pandas<3,>=2.3.1
+Requires-Dist: pyarrow>=21
+Requires-Dist: pydantic-extra-types<3,>=2.10.5
+Requires-Dist: pydantic<3,>=2.12.4
+Provides-Extra: benchmark
+Requires-Dist: huggingface-hub>=1.2.2; extra == 'benchmark'
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# openstef-core

openstef_core-4.0.0/README.md

@@ -0,0 +1,7 @@
+<!--
+SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# openstef-core

openstef_core-4.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+[build-system]
+build-backend = "hatchling.build"
+
+requires = [ "hatchling" ]
+
+[project]
+name = "openstef-core"
+version = "4.0.0"
+description = "Core functionality for OpenSTEF, a framework for short-term energy forecasting."
+readme = "README.md"
+keywords = [ "energy", "forecasting", "machinelearning" ]
+license = "MPL-2.0"
+authors = [
+  { name = "Alliander N.V", email = "openstef@lfenergy.org" },
+]
+requires-python = ">=3.12,<4.0"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+dependencies = [
+  "joblib>=1,<2",
+  "numpy>=2.3.2,<3",
+  "pandas>=2.3.1,<3",
+  "pyarrow>=21",
+  "pydantic>=2.12.4,<3",
+  "pydantic-extra-types>=2.10.5,<3",
+]
+
+optional-dependencies.benchmark = [
+  "huggingface-hub>=1.2.2",
+]
+
+urls.Documentation = "https://openstef.github.io/openstef/index.html"
+urls.Homepage = "https://lfenergy.org/projects/openstef/"
+urls.Issues = "https://github.com/OpenSTEF/openstef/issues"
+urls.Repository = "https://github.com/OpenSTEF/openstef"
+
+[tool.hatch.build.targets.wheel]
+packages = [ "src/openstef_core" ]

openstef_core-4.0.0/src/openstef_core/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2017-2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+"""Core functionality for OpenSTEF, a framework for short-term energy forecasting."""

openstef_core-4.0.0/src/openstef_core/base_model.py

@@ -0,0 +1,205 @@
+# SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Configuration utilities for OpenSTEF Beam.
+
+This module provides a `BaseConfig` class extending Pydantic's `BaseModel`
+with convenience helpers for reading from and writing to YAML files. It also
+exposes two helper functions `write_yaml_config` and `read_yaml_config` that
+operate on arbitrary config instances or Pydantic models / adapters.
+"""
+
+from pathlib import Path
+from typing import Annotated, Any, Self
+
+import yaml
+from pydantic import BaseModel as PydanticBaseModel
+from pydantic import (
+    BeforeValidator,
+    ConfigDict,
+    GetCoreSchemaHandler,
+    GetJsonSchemaHandler,
+    TypeAdapter,
+    ValidationInfo,
+)
+from pydantic_core import core_schema
+
+
+class BaseModel(PydanticBaseModel):
+    """Base model class for OpenSTEF components."""
+
+    model_config = ConfigDict(protected_namespaces=(), arbitrary_types_allowed=True, ser_json_inf_nan="null")
+
+
+class BaseConfig(PydanticBaseModel):
+    """Base configuration model.
+
+    It configures Pydantic model for safe YAML serialization / deserialization.
+    """
+
+    model_config = ConfigDict(
+        protected_namespaces=(),
+        extra="ignore",
+        arbitrary_types_allowed=False,
+    )
+
+    @classmethod
+    def read_yaml(cls, path: Path) -> Self:
+        """Create an instance from a YAML file.
+
+        Args:
+            path: Path to the YAML file to read.
+
+        Returns:
+            An instance of the config class populated with the file contents.
+        """
+        return read_yaml_config(path, class_type=cls)
+
+    def write_yaml(self, path: Path) -> None:
+        """Write this configuration to a YAML file.
+
+        Args:
+            path: Destination path for the YAML file (will be overwritten).
+        """
+        write_yaml_config(self, path)
+
+
+def write_yaml_config(config: BaseConfig, path: Path) -> None:
+    """Write the config to a YAML file.
+
+    Args:
+        config: The configuration object to serialize.
+        path: Destination path for the YAML file (will be overwritten).
+
+    Example:
+        >>> from pathlib import Path
+        >>> from pydantic import BaseModel
+        >>> class MyConfig(BaseModel):
+        ...     foo: int
+        >>> cfg = MyConfig(foo=123)
+        >>> write_yaml_config(cfg, Path("/tmp/test.yaml"))
+    """
+    with path.open("w", encoding="utf-8") as f:
+        yaml.dump(config.model_dump(mode="json"), f, allow_unicode=True)
+
+
+def read_yaml_config[T: BaseConfig, U](path: Path, class_type: type[T] | TypeAdapter[U]) -> T | U:
+    """Read a configuration object from a YAML file.
+
+    This function supports two kinds of targets:
+
+    * A subclass of `BaseConfig`, in which case Pydantic's `model_validate` is used.
+    * A `TypeAdapter` instance for more advanced / non-`BaseModel` schema validation.
+
+    Args:
+        path: Path to the YAML file to read.
+        class_type: The target type (a `BaseConfig` subclass) or a `TypeAdapter`.
+
+    Returns:
+        A validated configuration instance (either ``T`` or ``U`` depending on
+        the provided ``class_type``).
+    """
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    if isinstance(class_type, TypeAdapter):
+        return class_type.validate_python(data)
+
+    return class_type.model_validate(data)
+
+
+class PydanticStringPrimitive:
+    """Base class for Pydantic-compatible types with string serialization."""
+
+    def __str__(self) -> str:
+        """Convert to string representation."""
+        raise NotImplementedError("Subclasses must implement __str__")
+
+    @classmethod
+    def from_string(cls, s: str) -> Self:
+        """Create an instance from string representation."""
+        raise NotImplementedError("Subclasses must implement from_string")
+
+    @classmethod
+    def validate(cls, v: Any, _info: ValidationInfo | None = None) -> Self:  # noqa: ANN401
+        """Validate and convert input to this type.
+
+        Args:
+            v: Input value to validate.
+            _info: Additional validation info (unused).
+
+        Returns:
+            Validated instance of this type.
+
+        Raises:
+            ValueError: If input cannot be converted to this type.
+        """
+        if isinstance(v, cls):
+            return v
+        if isinstance(v, str):
+            return cls.from_string(v)
+
+        # Subclasses should handle their specific types
+        error_message = f"Cannot convert {v} to {cls.__name__}"
+        raise ValueError(error_message)
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, _source_type: type[Any], _handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        """Define Pydantic validation and serialization behavior.
+
+        Returns:
+            Core schema for Pydantic validation and serialization.
+        """
+        return core_schema.with_info_plain_validator_function(
+            function=cls.validate, serialization=core_schema.plain_serializer_function_ser_schema(cls.__str__)
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(  # noqa: PLW3201
+        cls,
+        _schema: core_schema.CoreSchema,
+        handler: GetJsonSchemaHandler,
+    ) -> dict[str, Any]:
+        """Generate JSON schema for OpenAPI / FastAPI compatibility.
+
+        All string-primitive types serialise as plain strings.
+
+        Returns:
+            JSON schema describing the type as a string.
+        """
+        return {"type": "string"}
+
+    def __eq__(self, other: object) -> bool:
+        """Check equality based on string representation.
+
+        Returns:
+            True if both objects have the same string representation, False otherwise.
+        """
+        if not isinstance(other, self.__class__):
+            return NotImplemented
+        return str(self) == str(other)
+
+    def __hash__(self) -> int:
+        """Return hash based on string representation."""
+        return hash(str(self))
+
+
+def _convert_none_to_nan(v: float | None) -> float:
+    if v is None:
+        return float("nan")
+    return v
+
+
+FloatOrNan = Annotated[float, BeforeValidator(_convert_none_to_nan)]
+
+__all__ = [
+    "BaseConfig",
+    "BaseModel",
+    "FloatOrNan",
+    "PydanticStringPrimitive",
+    "read_yaml_config",
+    "write_yaml_config",
+]

openstef_core-4.0.0/src/openstef_core/constants.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Shared constants for the openstef_core package."""
+
+LIANDER_DATASET_REPO_ID = "OpenSTEF/liander2024-energy-forecasting-benchmark"
+
+
+__all__ = ["LIANDER_DATASET_REPO_ID"]

openstef_core-4.0.0/src/openstef_core/datasets/__init__.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Time series datasets and versioned data access.
+
+This module provides core data structures for handling time series data in OpenSTEF forecasting.
+It includes both simple time series datasets and versioned datasets that track data availability
+over time, enabling realistic backtesting and training and forecasting.
+
+The module supports:
+
+    - Regular time series with consistent sampling intervals
+    - Versioned time series that track when data became available
+    - Validated datasets with domain-specific constraints
+    - Data transformations and validation utilities
+    - Feature concatenation and horizon restriction operations
+"""
+
+from openstef_core.datasets.timeseries_dataset import TimeSeriesDataset, validate_horizons_present
+from openstef_core.datasets.validated_datasets import (
+    EnergyComponentDataset,
+    EnsembleForecastDataset,
+    ForecastDataset,
+    ForecastInputDataset,
+)
+from openstef_core.datasets.versioned_timeseries_dataset import VersionedTimeSeriesDataset
+
+__all__ = [
+    "EnergyComponentDataset",
+    "EnsembleForecastDataset",
+    "ForecastDataset",
+    "ForecastInputDataset",
+    "TimeSeriesDataset",
+    "VersionedTimeSeriesDataset",
+    "validate_horizons_present",
+]