# Copyright 2025–2026 European Union
# Author: Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)
# SPDX-License-Identifier: EUPL-1.2
"""
Data model definitions for RadioViz application.
This module defines core data structures for representing data sources, their
origins, storage configurations, and states within the RadioViz application.
It provides immutable dataclasses for data integrity and enumerations for
tracking data provenance and status.
"""
from __future__ import annotations
import sys
from dataclasses import dataclass
from enum import Flag, auto
if sys.version_info >= (3, 11):
from enum import StrEnum
else:
from radioviz.models.legacy import StrEnum
from pathlib import Path
from uuid import UUID
from radioviz.models.roi_model import ROI
from radioviz.models.transform_model import Transform
[docs]
class DataOrigin(StrEnum):
"""
Enumeration of possible data origins.
Represents different sources from which data can originate in the application.
This enumeration is used to categorize data based on how it was obtained or created.
"""
FILE = 'file'
"""Data originates from a file."""
DERIVED = 'derived'
"""Data is derived from other sources."""
SIMULATION = 'simulation'
"""Data is generated through simulation."""
USER = 'user'
"""Data is provided by a user."""
IMPORT = 'import'
"""Data is imported from external sources."""
[docs]
@dataclass(frozen=True)
class SpatialDerivation:
"""
Immutable spatial derivation representation.
Represents the spatial relationship between a derived data source and its parent,
including the region of interest (ROI) and optional transformation applied.
This class is immutable (frozen) to ensure data integrity once created.
"""
parent_id: UUID
"""
:param parent_id: Unique identifier of the parent data source
:type parent_id: UUID
"""
roi: ROI
"""
:param roi: Region of interest defining the spatial extent of the derivation
:type roi: ROI
"""
transform: Transform | None = None
"""
:param transform: Optional spatial transformation applied during derivation, defaults to None
:type transform: Transform | None
"""
[docs]
@dataclass(frozen=True)
class DataSource:
"""
Immutable data source representation.
Represents a data source with its label, origin, and optional parent relationship.
This class is immutable (frozen) to ensure data integrity once created.
"""
label: str
"""
:param label: Human-readable name for the data source
:type label: str
"""
origin: DataOrigin
"""
:param origin: The origin type of the data source
:type origin: DataOrigin
"""
parent: 'DataSource | None' = None
"""
:param parent: Optional parent data source, defaults to None
:type parent: DataSource | None
"""
derivation: SpatialDerivation | None = None
[docs]
@dataclass
class DataStorage:
"""
Data storage configuration.
Represents the storage configuration for data, including the path where data is stored.
This class is mutable to allow updates to storage paths during runtime.
"""
path: Path | None
"""
:param path: Path to the data storage location, or None if not specified
:type path: Path | None
"""
[docs]
class DataKind(StrEnum):
"""
Enumeration of data kinds.
Defines different categories of data based on their nature and usage within the application.
"""
ORIGINAL = 'Original'
"""Original data that has not been processed or modified."""
DERIVED = 'Derived'
"""Data that has been derived from other sources."""
AGGREGATE = 'Aggregate'
"""Aggregated data formed by combining multiple data sources."""
[docs]
class DataState(Flag):
"""
Flags representing data state.
Provides a bitmask-based system for tracking various states of data,
such as whether it has been modified, is persistent, or is transient.
"""
NONE = 0
"""No specific state flags set."""
MODIFIED = auto()
"""Data has been modified since last save."""
PERSISTENT = auto()
"""Data is persisted to storage."""
TRANSIENT = auto()
"""Data exists only temporarily in memory."""