akkudoktoreos.core.databaseabc.DatabaseBackendABC

class akkudoktoreos.core.databaseabc.DatabaseBackendABC(*args: Any, **kwargs: Any)

Bases: DatabaseABC, SingletonMixin

Abstract base class for database backends.

All operations accept an optional namespace argument. Implementations should treat None as the default/root namespace. Concrete implementations can map namespace -> native namespace (LMDB DBI) or emulate namespaces (SQLite uses a namespace column).

__init__(**kwargs: Any) → None

Initialize the DatabaseBackendABC base.

Parameters:: **kwargs – Backend-specific options (ignored by base).

Methods

`__init__`(**kwargs)	Initialize the DatabaseBackendABC base.
`close`()	Close the database connection and cleanup resources.
`count_records`([start_key, end_key, namespace])	Count records in [start_key, end_key) excluding metadata in specified namespace.
`delete_records`(keys[, namespace])	Delete multiple records by key from the specified namespace.
`deserialize_data`(data)	Optionally decompress stored data.
`flush`([namespace])	Force synchronization of pending writes to storage (optional per-namespace).
`get_backend_stats`([namespace])	Get backend-specific statistics; implementations may return namespace-specific data.
`get_key_range`([namespace])	Return (min_key, max_key) in the given namespace or (None, None) if empty.
`get_metadata`([namespace])	Load metadata for a given namespace.
`iterate_records`([start_key, end_key, ...])	Iterate over records for a namespace with optional bounds.
`open`([namespace])	Open database connection and optionally set default namespace.
`provider_id`()	Return the unique identifier for the database provider.
`reset_instance`()	Resets the singleton instance, forcing it to be recreated on next access.
`save_records`(records[, namespace])	Save multiple records into the specified namespace (or default).
`serialize_data`(data)	Optionally compress raw pickled data before storage.
`set_metadata`(metadata, *[, namespace])	Save metadata for a given namespace.

Attributes

`compression`	Whether to compress stored values.
`compression_level`	Compression level for database record data.
`config`
`is_open`	Return whether the database connection is open.
`storage_path`	Storage path for the database.
`connection`
`lock`
`default_namespace`

__init__(**kwargs: Any) → None

Initialize the DatabaseBackendABC base.

Parameters:: **kwargs – Backend-specific options (ignored by base).

connection: Any

lock: allocate_lock

default_namespace: str | None

property is_open: bool: Return whether the database connection is open.

static __new__(cls: Type[SingletonMixin], *args: Any, **kwargs: Any) → SingletonMixin

Creates or returns the singleton instance of the class.

Ensures thread-safe instance creation by locking during the first instantiation.

Parameters:

*args – Positional arguments for instance creation (ignored if instance exists).
**kwargs – Keyword arguments for instance creation (ignored if instance exists).

Returns:

The singleton instance of the derived class.

Return type:

SingletonMixin

abstractmethod close() → None: Close the database connection and cleanup resources.

property compression: bool: Whether to compress stored values.

property compression_level: int: Compression level for database record data.

config = ConfigEOS(general=GeneralSettings(home_assistant_addon=False, version='0.2.0.dev58204789', data_folder_path=Path('/home/docs/.local/share/net.akkudoktor.eos'), data_output_subpath='output', latitude=52.52, longitude=13.405, timezone='Europe/Berlin', data_output_path=Path('/home/docs/.local/share/net.akkudoktor.eos/output'), config_folder_path=Path('/home/docs/checkouts/readthedocs.org/user_builds/akkudoktor-eos/checkouts/latest/docs'), config_file_path=Path('/home/docs/checkouts/readthedocs.org/user_builds/akkudoktor-eos/checkouts/latest/docs/EOS.config.json')), cache=CacheCommonSettings(subpath='cache', cleanup_interval=300.0), database=DatabaseCommonSettings(provider=None, compression_level=9, initial_load_window_h=None, keep_duration_h=None, autosave_interval_sec=10, compaction_interval_sec=604800, batch_size=100, providers=['LMDB', 'SQLite']), ems=EnergyManagementCommonSettings(startup_delay=5, interval=300.0, mode=None), logging=LoggingCommonSettings(console_level='INFO', file_level=None, file_path=Path('/home/docs/.local/share/net.akkudoktor.eos/output/eos.log')), devices=DevicesCommonSettings(batteries=None, max_batteries=None, electric_vehicles=None, max_electric_vehicles=None, inverters=None, max_inverters=None, home_appliances=None, max_home_appliances=None, measurement_keys=[]), measurement=MeasurementCommonSettings(historic_hours=17520, load_emr_keys=None, grid_export_emr_keys=None, grid_import_emr_keys=None, pv_production_emr_keys=None, keys=[]), optimization=OptimizationCommonSettings(horizon_hours=24, interval=3600, algorithm='GENETIC', genetic=GeneticCommonSettings(individuals=300, generations=400, seed=None, penalties=None), keys=[]), prediction=PredictionCommonSettings(hours=48, historic_hours=48), elecprice=ElecPriceCommonSettings(provider=None, charges_kwh=None, vat_rate=1.19, elecpriceimport=ElecPriceImportCommonSettings(import_file_path=None, import_json=None), energycharts=ElecPriceEnergyChartsCommonSettings(bidding_zone=<EnergyChartsBiddingZones.DE_LU: 'DE-LU'>), providers=['ElecPriceAkkudoktor', 'ElecPriceEnergyCharts', 'ElecPriceImport']), feedintariff=FeedInTariffCommonSettings(provider=None, provider_settings=FeedInTariffCommonProviderSettings(FeedInTariffFixed=None, FeedInTariffImport=None), providers=['FeedInTariffFixed', 'FeedInTariffImport']), load=LoadCommonSettings(provider=None, provider_settings=LoadCommonProviderSettings(LoadAkkudoktor=None, LoadVrm=None, LoadImport=None), providers=['LoadAkkudoktor', 'LoadAkkudoktorAdjusted', 'LoadVrm', 'LoadImport']), pvforecast=PVForecastCommonSettings(provider=None, provider_settings=PVForecastCommonProviderSettings(PVForecastImport=None, PVForecastVrm=None), planes=None, max_planes=0, providers=['PVForecastAkkudoktor', 'PVForecastVrm', 'PVForecastImport'], planes_peakpower=[], planes_azimuth=[], planes_tilt=[], planes_userhorizon=[], planes_inverter_paco=[]), weather=WeatherCommonSettings(provider=None, provider_settings=WeatherCommonProviderSettings(WeatherImport=None), providers=['BrightSky', 'ClearOutside', 'WeatherImport']), server=ServerCommonSettings(host='127.0.0.1', port=8503, verbose=False, startup_eosdash=True, eosdash_host=None, eosdash_port=None), utils=UtilsCommonSettings(), adapter=AdapterCommonSettings(provider=None, homeassistant=HomeAssistantAdapterCommonSettings(config_entity_ids=None, load_emr_entity_ids=None, grid_export_emr_entity_ids=None, grid_import_emr_entity_ids=None, pv_production_emr_entity_ids=None, device_measurement_entity_ids=None, device_instruction_entity_ids=None, solution_entity_ids=None, homeassistant_entity_ids=[], eos_solution_entity_ids=[], eos_device_instruction_entity_ids=[]), nodered=NodeREDAdapterCommonSettings(host='127.0.0.1', port=1880), providers=['HomeAssistant', 'NodeRED']))

abstractmethod count_records(start_key: bytes | None = None, end_key: bytes | None = None, *, namespace: str | None = None) → int

Count records in [start_key, end_key) excluding metadata in specified namespace.

Excludes metadata records.

abstractmethod delete_records(keys: Iterable[bytes], namespace: str | None = None) → int

Delete multiple records by key from the specified namespace.

Parameters:

keys – Iterable that provides the Byte keys to delete.
namespace – Optional namespace.

Returns:

Number of records actually deleted.

deserialize_data(data: bytes) → bytes

Optionally decompress stored data.

Parameters:: data – Stored bytes.
Returns:: Raw pickled bytes (decompressed if needed).

abstractmethod flush(namespace: str | None = None) → None: Force synchronization of pending writes to storage (optional per-namespace).

abstractmethod get_backend_stats(namespace: str | None = None) → dict[str, Any]: Get backend-specific statistics; implementations may return namespace-specific data.

abstractmethod get_key_range(namespace: str | None = None) → tuple[bytes | None, bytes | None]: Return (min_key, max_key) in the given namespace or (None, None) if empty.

abstractmethod get_metadata(namespace: str | None = None) → bytes | None

Load metadata for a given namespace.

Returns None if no metadata exists.

Parameters:: namespace (Optional[str]) – Optional namespace whose metadata to retrieve.
Returns:: The loaded metadata, or None if not found.
Return type:: Optional[bytes]

abstractmethod iterate_records(start_key: bytes | None = None, end_key: bytes | None = None, namespace: str | None = None, reverse: bool = False) → Iterator[tuple[bytes, bytes]]

Iterate over records for a namespace with optional bounds.

Parameters:

start_key – Inclusive start key, or None.
end_key – Exclusive end key, or None.
namespace – Optional namespace to target.
reverse – If True iterate in descending key order.

Yields:

Tuples of (key, record).

abstractmethod open(namespace: str | None = None) → None

Open database connection and optionally set default namespace.

Parameters:: namespace – Optional default namespace to prepare.
Raises:: RuntimeError – If the database cannot be opened.

abstractmethod provider_id() → str

Return the unique identifier for the database provider.

To be implemented by derived classes.

classmethod reset_instance() → None: Resets the singleton instance, forcing it to be recreated on next access.

abstractmethod save_records(records: Iterable[tuple[bytes, bytes]], namespace: str | None = None) → int

Save multiple records into the specified namespace (or default).

Parameters:

records – Iterable providing key, value tuples ordered by key: - key: Byte key (sortable) for the record. - value: Serialized (and optionally compressed) bytes to store.
namespace – Optional namespace.

Returns:

Number of records saved.

Raises:

RuntimeError – If DB not open or write failed.

serialize_data(data: bytes) → bytes

Optionally compress raw pickled data before storage.

Parameters:: data – Raw pickled bytes.
Returns:: Possibly compressed bytes.

abstractmethod set_metadata(metadata: bytes | None, *, namespace: str | None = None) → None

Save metadata for a given namespace.

Metadata is treated separately from data records and stored as a single object.

Parameters:

metadata (bytes) – Arbitrary metadata to save or None to delete metadata.
namespace (Optional[str]) – Optional namespace under which to store metadata.

property storage_path: Path: Storage path for the database.