carconnectivity-plugin-database 0.1a19__py3-none-any.whl

carconnectivity_plugins/database/agents/trip_agent.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+import threading
+
+import logging
+from datetime import datetime, timezone, timedelta
+
+from sqlalchemy.exc import DatabaseError
+
+from carconnectivity.observable import Observable
+from carconnectivity.vehicle import GenericVehicle
+
+from carconnectivity_plugins.database.agents.base_agent import BaseAgent
+from carconnectivity_plugins.database.model.trip import Trip
+from carconnectivity_plugins.database.model.location import Location
+
+if TYPE_CHECKING:
+    from typing import Optional
+    from sqlalchemy.orm import scoped_session
+    from sqlalchemy.orm.session import Session
+
+    from carconnectivity.attributes import EnumAttribute, FloatAttribute
+
+    from carconnectivity_plugins.database.plugin import Plugin
+    from carconnectivity_plugins.database.model.vehicle import Vehicle
+
+LOG: logging.Logger = logging.getLogger("carconnectivity.plugins.database.agents.trip_agent")
+
+
+class TripAgent(BaseAgent):
+    """
+    Agent responsible for tracking vehicle trips based on vehicle state changes.
+    This agent monitors the vehicle's state (ignition on/off, driving) and automatically
+    creates and manages trip records in the database. It tracks trip start/end times and
+    odometer readings.
+    Attributes:
+        session (Session): SQLAlchemy database session for persisting trip data.
+        vehicle (Vehicle): The vehicle being monitored for trip tracking.
+        last_carconnectivity_state (Optional[GenericVehicle.State]): The last known state
+            of the vehicle to detect state transitions.
+        trip (Optional[Trip]): The currently active trip, if any.
+    Raises:
+        ValueError: If vehicle or vehicle.carconnectivity_vehicle is None during initialization.
+    Notes:
+        - A new trip is started when the vehicle transitions to IGNITION_ON or DRIVING state.
+        - A trip is ended when the vehicle transitions from IGNITION_ON/DRIVING to another state.
+        - If a previous trip is still open during startup or when starting a new trip,
+          it will be logged and closed.
+        - Trip records include start/end dates and odometer readings when available.
+    """
+
+    def __init__(self, database_plugin: Plugin, session_factory: scoped_session[Session], vehicle: Vehicle) -> None:
+        if vehicle is None or vehicle.carconnectivity_vehicle is None:
+            raise ValueError("Vehicle or its carconnectivity_vehicle attribute is None")
+        self.database_plugin: Plugin = database_plugin
+        self.session_factory: scoped_session[Session] = session_factory
+        self.vehicle: Vehicle = vehicle
+        self.last_carconnectivity_state: Optional[GenericVehicle.State] = None
+        self.last_parked_position_latitude: Optional[float] = None
+        self.last_parked_position_longitude: Optional[float] = None
+        self.last_parked_position_time: Optional[datetime] = None
+
+        with self.session_factory() as session:
+            self.trip: Optional[Trip] = session.query(Trip).filter(Trip.vehicle == vehicle).order_by(Trip.start_date.desc()).first()
+            self.trip_lock: threading.RLock = threading.RLock()
+            if self.trip is not None:
+                if self.trip.destination_date is None:
+                    LOG.info("Last trip for vehicle %s is still open during startup, closing it now", vehicle.vin)
+        self.session_factory.remove()
+
+        vehicle.carconnectivity_vehicle.state.add_observer(self.__on_state_change, Observable.ObserverEvent.UPDATED)
+        self.__on_state_change(vehicle.carconnectivity_vehicle.state, Observable.ObserverEvent.UPDATED)
+
+        vehicle.carconnectivity_vehicle.position.latitude.add_observer(self._on_position_latitude_change, Observable.ObserverEvent.UPDATED)
+        self._on_position_latitude_change(vehicle.carconnectivity_vehicle.position.latitude, Observable.ObserverEvent.UPDATED)
+
+        vehicle.carconnectivity_vehicle.position.longitude.add_observer(self._on_position_longitude_change, Observable.ObserverEvent.UPDATED)
+        self._on_position_longitude_change(vehicle.carconnectivity_vehicle.position.longitude, Observable.ObserverEvent.UPDATED)
+
+    def __on_state_change(self, element: EnumAttribute[GenericVehicle.State], flags: Observable.ObserverEvent) -> None:
+        del flags
+        if element.enabled:
+            if self.vehicle.carconnectivity_vehicle is None:
+                raise ValueError("Vehicle's carconnectivity_vehicle attribute is None")
+            if element.enabled and element.value is not None:
+                if self.last_carconnectivity_state is not None:
+                    with self.session_factory() as session:
+                        with self.trip_lock:
+                            if self.trip is not None:
+                                self.trip = session.merge(self.trip)
+                                session.refresh(self.trip)
+                            if self.last_carconnectivity_state not in (GenericVehicle.State.IGNITION_ON, GenericVehicle.State.DRIVING) \
+                                    and element.value in (GenericVehicle.State.IGNITION_ON, GenericVehicle.State.DRIVING):
+                                if self.trip is not None:
+                                    LOG.warning("Starting new trip for vehicle %s while previous trip is still open, closing previous trip first",
+                                                self.vehicle.vin)
+                                    self.trip = None
+                                LOG.info("Starting new trip for vehicle %s", self.vehicle.vin)
+                                start_date: datetime = element.last_updated if element.last_updated is not None else datetime.now(tz=timezone.utc)
+                                new_trip: Trip = Trip(vin=self.vehicle.vin, start_date=start_date)
+                                if self.vehicle.carconnectivity_vehicle.odometer.enabled and \
+                                        self.vehicle.carconnectivity_vehicle.odometer.value is not None:
+                                    new_trip.start_odometer = self.vehicle.carconnectivity_vehicle.odometer.value
+                                if not self._update_trip_position(session=session, trip=new_trip, start=True):
+                                    # if now no position is available try the last known position that is not older than 5min
+                                    if self.last_parked_position_latitude is not None and self.last_parked_position_longitude is not None \
+                                            and self.last_parked_position_time is not None \
+                                            and self.last_parked_position_time < (start_date - timedelta(minutes=5)):
+                                        self._update_trip_position(session=session, trip=new_trip, start=True,
+                                                                   latitude=self.last_parked_position_latitude,
+                                                                   longitude=self.last_parked_position_longitude)
+                                try:
+                                    session.add(new_trip)
+                                    session.commit()
+                                    LOG.debug('Added new trip for vehicle %s to database', self.vehicle.vin)
+                                    self.trip = new_trip
+                                except DatabaseError as err:
+                                    session.rollback()
+                                    LOG.error('DatabaseError while adding trip for vehicle %s to database: %s', self.vehicle.vin, err)
+                                    self.database_plugin.healthy._set_value(value=False)  # pylint: disable=protected-access
+                            elif self.last_carconnectivity_state in (GenericVehicle.State.IGNITION_ON, GenericVehicle.State.DRIVING) \
+                                    and element.value not in (GenericVehicle.State.IGNITION_ON, GenericVehicle.State.DRIVING):
+                                if self.trip is not None and not self.trip.is_completed():
+                                    LOG.info("Ending trip for vehicle %s", self.vehicle.vin)
+                                    try:
+                                        self.trip.destination_date = element.last_updated if element.last_updated is not None else datetime.now(tz=timezone.utc)
+                                        if self.vehicle.carconnectivity_vehicle.odometer.enabled and \
+                                                self.vehicle.carconnectivity_vehicle.odometer.value is not None:
+                                            self.trip.destination_odometer = self.vehicle.carconnectivity_vehicle.odometer.value
+                                            LOG.debug('Set destination odometer %.2f for trip of vehicle %s', self.trip.destination_odometer, self.vehicle.vin)
+                                        if self._update_trip_position(session=session, trip=self.trip, start=False):
+                                            self.trip = None
+                                        session.commit()
+                                    except DatabaseError as err:
+                                        session.rollback()
+                                        LOG.error('DatabaseError while ending trip for vehicle %s in database: %s', self.vehicle.vin, err)
+                                        self.database_plugin.healthy._set_value(value=False)  # pylint: disable=protected-access
+                    self.session_factory.remove()
+                self.last_carconnectivity_state = element.value
+
+    def _on_position_latitude_change(self, element: FloatAttribute, flags: Observable.ObserverEvent) -> None:
+        del flags
+        if element.enabled and element.value is not None:
+            self.last_parked_position_latitude = element.value
+            self.last_parked_position_time = element.last_changed
+            self._on_position_change()
+
+    def _on_position_longitude_change(self, element: FloatAttribute, flags: Observable.ObserverEvent) -> None:
+        del flags
+        if element.enabled and element.value is not None:
+            self.last_parked_position_longitude = element.value
+            self.last_parked_position_time = element.last_changed
+            self._on_position_change()
+
+    def _on_position_change(self) -> None:
+        # Check if there is a finished trip that lacks destination position. We allow 5min after destination_date to set the position.
+        if self.trip is not None:
+            with self.session_factory() as session:
+                with self.trip_lock:
+                    self.trip = session.merge(self.trip)
+                    session.refresh(self.trip)
+                    if self.trip.destination_date is not None and self.trip.destination_position_latitude is None \
+                            and self.last_parked_position_time is not None \
+                            and self.last_parked_position_time < (self.trip.destination_date + timedelta(minutes=5)):
+                        self._update_trip_position(session, self.trip, start=False,
+                                                   latitude=self.last_parked_position_latitude,
+                                                   longitude=self.last_parked_position_longitude)
+            self.session_factory.remove()
+
+    def _update_trip_position(self, session: Session, trip: Trip, start: bool,
+                              latitude: Optional[float] = None, longitude: Optional[float] = None) -> bool:
+        if self.vehicle.carconnectivity_vehicle is None:
+            raise ValueError("Vehicle's carconnectivity_vehicle attribute is None")
+        if latitude or longitude is None:
+            if self.vehicle.carconnectivity_vehicle.position.enabled and self.vehicle.carconnectivity_vehicle.position.latitude.enabled \
+                    and self.vehicle.carconnectivity_vehicle.position.longitude.enabled \
+                    and self.vehicle.carconnectivity_vehicle.position.latitude.value is not None \
+                    and self.vehicle.carconnectivity_vehicle.position.longitude.value is not None:
+                latitude = self.vehicle.carconnectivity_vehicle.position.latitude.value
+                longitude = self.vehicle.carconnectivity_vehicle.position.longitude.value
+        if latitude is not None and longitude is not None:
+            if start:
+                if trip.start_position_latitude is None and trip.start_position_longitude is None:
+                    try:
+                        trip.start_position_latitude = self.vehicle.carconnectivity_vehicle.position.latitude.value
+                        trip.start_position_longitude = self.vehicle.carconnectivity_vehicle.position.longitude.value
+                        session.commit()
+                    except DatabaseError as err:
+                        session.rollback()
+                        LOG.error('DatabaseError while updating position for trip of vehicle %s in database: %s', self.vehicle.vin, err)
+                        self.database_plugin.healthy._set_value(value=False)  # pylint: disable=protected-access
+                if trip.start_location is None and self.vehicle.carconnectivity_vehicle.position.location.enabled:
+                    location: Location = Location.from_carconnectivity_location(location=self.vehicle.carconnectivity_vehicle.position.location)
+                    try:
+                        location = session.merge(location)
+                        trip.start_location = location
+                        session.commit()
+                    except DatabaseError as err:
+                        session.rollback()
+                        LOG.error('DatabaseError while merging location for trip of vehicle %s in database: %s', self.vehicle.vin, err)
+                        self.database_plugin.healthy._set_value(value=False)  # pylint: disable=protected-access
+                return True
+            else:
+                if trip.destination_position_latitude is None and trip.destination_position_longitude is None:
+                    try:
+                        trip.destination_position_latitude = self.vehicle.carconnectivity_vehicle.position.latitude.value
+                        trip.destination_position_longitude = self.vehicle.carconnectivity_vehicle.position.longitude.value
+                        session.commit()
+                    except DatabaseError as err:
+                        session.rollback()
+                        LOG.error('DatabaseError while updating position for trip of vehicle %s in database: %s', self.vehicle.vin, err)
+                        self.database_plugin.healthy._set_value(value=False)  # pylint: disable=protected-access
+                if trip.destination_location is None and self.vehicle.carconnectivity_vehicle.position.location.enabled:
+                    location: Location = Location.from_carconnectivity_location(location=self.vehicle.carconnectivity_vehicle.position.location)
+                    try:
+                        location = session.merge(location)
+                        trip.destination_location = location
+                        session.commit()
+                    except DatabaseError as err:
+                        session.rollback()
+                        LOG.error('DatabaseError while merging location for trip of vehicle %s in database: %s', self.vehicle.vin, err)
+                        self.database_plugin.healthy._set_value(value=False)  # pylint: disable=protected-access
+                return True
+        return False

carconnectivity_plugins/database/model/__init__.py

@@ -0,0 +1,19 @@
+""" This module contains the database model for car connectivity plugins."""
+
+from .charging_state import ChargingState  # noqa: F401
+from .charging_rate import ChargingRate  # noqa: F401
+from .charging_power import ChargingPower  # noqa: F401
+from .charging_session import ChargingSession  # noqa: F401
+from .charging_station import ChargingStation  # noqa: F401
+from .climatization_state import ClimatizationState  # noqa: F401
+from .connection_state import ConnectionState  # noqa: F401
+from .drive import Drive  # noqa: F401
+from .drive_level import DriveLevel  # noqa: F401
+from .drive_range import DriveRange  # noqa: F401
+from .drive_range_full import DriveRangeEstimatedFull  # noqa: F401
+from .location import Location  # noqa: F401
+from .outside_temperature import OutsideTemperature  # noqa: F401
+from .state import State  # noqa: F401
+from .tag import Tag  # noqa: F401
+from .trip import Trip  # noqa: F401
+from .vehicle import Vehicle  # noqa: F401

carconnectivity_plugins/database/model/alembic.ini

@@ -0,0 +1,100 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = carconnectivity_schema
+
+# template used to generate migration files
+# file_template = %%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python-dateutil library that can be
+# installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to dateutil.tz.gettz()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to vwsfriend-schema/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator"
+# version_locations = %(here)s/bar:%(here)s/bat:vwsfriend-schema/versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. Valid values are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+version_path_separator = os  # default: use os.pathsep
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = sqlite:///carconnectivity-schema/reference.db
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

carconnectivity_plugins/database/model/base.py

@@ -0,0 +1,4 @@
+"""Module just storing the Base class for SQLAlchemy models."""
+from sqlalchemy.ext.declarative import declarative_base
+
+Base = declarative_base()

carconnectivity_plugins/database/model/carconnectivity_schema/README

@@ -0,0 +1 @@
+Generic single-database configuration.

carconnectivity_plugins/database/model/carconnectivity_schema/env.py

@@ -0,0 +1,78 @@
+# pylint: skip-file
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+
+from alembic import context
+
+from carconnectivity_plugins.database.model.base import Base
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.attributes.get('configure_logger', True):
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+# other values from the config, defined by the needs of env.py,
+# can be acquired:
+# my_important_option = config.get_main_option("my_important_option")
+# ... etc.
+
+
+def run_migrations_offline():
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online():
+    """Run migrations in 'online' mode.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+
+    """
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata, compare_type=True
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

carconnectivity_plugins/database/model/carconnectivity_schema/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade():
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade():
+    ${downgrades if downgrades else "pass"}

carconnectivity_plugins/database/model/charging_power.py

@@ -0,0 +1,52 @@
+""" This module contains the Vehicle charging power database model"""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+
+from datetime import datetime
+
+from sqlalchemy import ForeignKey, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from sqlalchemy_utc import UtcDateTime
+
+from carconnectivity_plugins.database.model.base import Base
+
+
+if TYPE_CHECKING:
+    from sqlalchemy import Constraint
+
+
+class ChargingPower(Base):  # pylint: disable=too-few-public-methods
+    """
+    SQLAlchemy model representing a vehicle's charging power information over a time period.
+    This table stores the power of charging (e.g., in kW) used by a vehicle within
+    a specific date range.
+    Attributes:
+        id (int): Primary key identifier for the charging type record.
+        vin (str): Foreign key reference to the vehicle's VIN in the vehicles table.
+        vehicle (Vehicle): Relationship to the Vehicle model.
+        first_date (datetime): The start date/time of this charging power period.
+        last_date (datetime): The end date/time of this charging power period.
+        power (float, optional): The charging power value, or None if not available.
+    Args:
+        vin (str): The vehicle identification number.
+        first_date (datetime): The start date/time for this charging power record.
+        last_date (datetime): The end date/time for this charging power record.
+        power (Optional[float]): The charging power value.
+    """
+
+    __tablename__: str = 'charging_powers'
+    __table_args__: tuple[Constraint] = (UniqueConstraint("vin", "first_date", name="charging_powers_vin_first_date"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    vin: Mapped[str] = mapped_column(ForeignKey("vehicles.vin"))
+    vehicle: Mapped["Vehicle"] = relationship("Vehicle")
+    first_date: Mapped[datetime] = mapped_column(UtcDateTime)
+    last_date: Mapped[datetime] = mapped_column(UtcDateTime)
+    power: Mapped[Optional[float]]
+
+    def __init__(self, vin: str, first_date: datetime, last_date: datetime, power: Optional[float]) -> None:
+        self.vin = vin
+        self.first_date = first_date
+        self.last_date = last_date
+        self.power = power

carconnectivity_plugins/database/model/charging_rate.py

@@ -0,0 +1,52 @@
+""" This module contains the Vehicle charging rates database model"""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+
+from datetime import datetime
+
+from sqlalchemy import ForeignKey, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from sqlalchemy_utc import UtcDateTime
+
+from carconnectivity_plugins.database.model.base import Base
+
+
+if TYPE_CHECKING:
+    from sqlalchemy import Constraint
+
+
+class ChargingRate(Base):  # pylint: disable=too-few-public-methods
+    """
+    SQLAlchemy model representing a vehicle's charging type information over a time period.
+    This table stores the type of charging (e.g., AC, DC) used by a vehicle within
+    a specific date range.
+    Attributes:
+        id (int): Primary key identifier for the charging type record.
+        vin (str): Foreign key reference to the vehicle's VIN in the vehicles table.
+        vehicle (Vehicle): Relationship to the Vehicle model.
+        first_date (datetime): The start date/time of this charging type period.
+        last_date (datetime): The end date/time of this charging type period.
+        rate (float, optional): The charging rate value, or None if not available.
+    Args:
+        vin (str): The vehicle identification number.
+        first_date (datetime): The start date/time for this charging type record.
+        last_date (datetime): The end date/time for this charging type record.
+        rate (Optional[float]): The charging rate value.
+    """
+
+    __tablename__: str = 'charging_rates'
+    __table_args__: tuple[Constraint] = (UniqueConstraint("vin", "first_date", name="charging_rates_vin_first_date"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    vin: Mapped[str] = mapped_column(ForeignKey("vehicles.vin"))
+    vehicle: Mapped["Vehicle"] = relationship("Vehicle")
+    first_date: Mapped[datetime] = mapped_column(UtcDateTime)
+    last_date: Mapped[datetime] = mapped_column(UtcDateTime)
+    rate: Mapped[Optional[float]]
+
+    def __init__(self, vin: str, first_date: datetime, last_date: datetime, rate: Optional[float]) -> None:
+        self.vin = vin
+        self.first_date = first_date
+        self.last_date = last_date
+        self.rate = rate