tescmd 0.1.2__py3-none-any.whl

tescmd/models/config.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Profile(BaseModel):
+    """A named profile grouping common CLI settings."""
+
+    region: str = "na"
+    vin: str | None = None
+    output_format: str | None = None
+    client_id: str | None = None
+    client_secret: str | None = None
+
+
+class AppSettings(BaseSettings):
+    """Application-wide settings populated from environment variables and .env file."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="TESLA_",
+        extra="ignore",
+    )
+
+    client_id: str | None = None
+    client_secret: str | None = None
+    domain: str | None = None
+    vin: str | None = None
+
+    @field_validator("domain", mode="before")
+    @classmethod
+    def _lowercase_domain(cls, v: str | None) -> str | None:
+        """Tesla Fleet API rejects domains with uppercase characters."""
+        if v is not None:
+            return v.lower()
+        return v
+
+    region: str = "na"
+    token_file: str | None = None
+    config_dir: str = "~/.config/tescmd"
+    output_format: str | None = None
+    profile: str = "default"
+    setup_tier: str | None = None
+    github_repo: str | None = None
+    access_token: str | None = None
+    refresh_token: str | None = None
+
+    # Cache settings (TESLA_CACHE_ENABLED, TESLA_CACHE_TTL, TESLA_CACHE_DIR)
+    cache_enabled: bool = True
+    cache_ttl: int = 60
+    cache_dir: str = "~/.cache/tescmd"
+
+    # Command protocol: auto | signed | unsigned
+    # auto = use signed when keys available, fall back to unsigned
+    # signed = require signed (error if no keys)
+    # unsigned = force legacy REST path
+    command_protocol: str = "auto"
+
+    # Display units (TESLA_TEMP_UNIT, TESLA_DISTANCE_UNIT, TESLA_PRESSURE_UNIT)
+    temp_unit: str = "F"
+    distance_unit: str = "mi"
+    pressure_unit: str = "psi"

tescmd/models/energy.py

@@ -0,0 +1,56 @@
+"""Pydantic models for Tesla energy products (Powerwall, Solar)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+_EXTRA_ALLOW = ConfigDict(extra="allow")
+
+
+class EnergySite(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    energy_site_id: int
+    resource_type: str | None = None
+    site_name: str | None = None
+    gateway_id: str | None = None
+
+
+class LiveStatus(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    solar_power: float | None = None
+    battery_power: float | None = None
+    grid_power: float | None = None
+    load_power: float | None = None
+    grid_status: str | None = None
+    battery_level: float | None = None
+    percentage_charged: float | None = None
+
+
+class SiteInfo(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    energy_site_id: int | None = None
+    site_name: str | None = None
+    resource_type: str | None = None
+    backup_reserve_percent: float | None = None
+    default_real_mode: str | None = None
+    storm_mode_enabled: bool | None = None
+    installation_date: str | None = None
+
+
+class CalendarHistory(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    serial_number: str | None = None
+    time_series: list[dict[str, Any]] = []
+
+
+class GridImportExportConfig(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    disallow_charge_from_grid_with_solar_installed: bool | None = None
+    customer_preferred_export_rule: str | None = None

tescmd/models/sharing.py

@@ -0,0 +1,26 @@
+"""Pydantic models for Tesla vehicle sharing (drivers and invites)."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+_EXTRA_ALLOW = ConfigDict(extra="allow")
+
+
+class ShareDriverInfo(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    share_user_id: int | None = None
+    email: str | None = None
+    status: str | None = None
+    public_key: str | None = None
+
+
+class ShareInvite(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    id: str | None = None
+    code: str | None = None
+    created_at: str | None = None
+    expires_at: str | None = None
+    status: str | None = None

tescmd/models/user.py

@@ -0,0 +1,37 @@
+"""Pydantic models for Tesla user account data."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+_EXTRA_ALLOW = ConfigDict(extra="allow")
+
+
+class UserInfo(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    email: str | None = None
+    full_name: str | None = None
+    profile_image_url: str | None = None
+
+
+class UserRegion(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    region: str | None = None
+    fleet_api_base_url: str | None = None
+
+
+class VehicleOrder(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    order_id: str | None = None
+    vin: str | None = None
+    model: str | None = None
+    status: str | None = None
+
+
+class FeatureConfig(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    signaling: dict[str, bool] | None = None

tescmd/models/vehicle.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+_EXTRA_ALLOW = ConfigDict(extra="allow")
+
+
+class Vehicle(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    vin: str
+    display_name: str | None = None
+    state: str = "unknown"
+    vehicle_id: int | None = None
+    access_type: str | None = None
+
+
+class DriveState(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    latitude: float | None = None
+    longitude: float | None = None
+    heading: int | None = None
+    speed: int | None = None
+    power: int | None = None
+    shift_state: str | None = None
+    timestamp: int | None = None
+
+
+class ChargeState(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    battery_level: int | None = None
+    battery_range: float | None = None
+    charge_limit_soc: int | None = None
+    charging_state: str | None = None
+    charge_rate: float | None = None
+    charger_voltage: int | None = None
+    charger_actual_current: int | None = None
+    charge_port_door_open: bool | None = None
+    minutes_to_full_charge: int | None = None
+    scheduled_charging_start_time: int | None = None
+    charger_type: str | None = None
+    ideal_battery_range: float | None = None
+    est_battery_range: float | None = None
+    usable_battery_level: int | None = None
+    charge_energy_added: float | None = None
+    charge_miles_added_rated: float | None = None
+    charger_power: int | None = None
+    time_to_full_charge: float | None = None
+    scheduled_charging_mode: str | None = None
+    scheduled_departure_time_minutes: int | None = None
+    preconditioning_enabled: bool | None = None
+    battery_heater_on: bool | None = None
+    charge_port_latch: str | None = None
+    conn_charge_cable: str | None = None
+
+
+class ClimateState(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    inside_temp: float | None = None
+    outside_temp: float | None = None
+    driver_temp_setting: float | None = None
+    passenger_temp_setting: float | None = None
+    is_climate_on: bool | None = None
+    fan_status: int | None = None
+    defrost_mode: int | None = None
+    seat_heater_left: int | None = None
+    seat_heater_right: int | None = None
+    steering_wheel_heater: bool | None = None
+    cabin_overheat_protection: str | None = None
+    cabin_overheat_protection_actively_cooling: bool | None = None
+    is_auto_conditioning_on: bool | None = None
+    is_preconditioning: bool | None = None
+    seat_heater_rear_left: int | None = None
+    seat_heater_rear_center: int | None = None
+    seat_heater_rear_right: int | None = None
+    bioweapon_defense_mode: bool | None = None
+
+
+class SoftwareUpdateInfo(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    status: str | None = None
+    version: str | None = None
+    install_perc: int | None = None
+    expected_duration_sec: int | None = None
+    scheduled_time_ms: int | None = None
+    download_perc: int | None = None
+
+
+class VehicleState(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    locked: bool | None = None
+    odometer: float | None = None
+    sentry_mode: bool | None = None
+    car_version: str | None = None
+    door_driver_front: int | None = None
+    door_driver_rear: int | None = None
+    door_passenger_front: int | None = None
+    door_passenger_rear: int | None = None
+    window_driver_front: int | None = None
+    window_driver_rear: int | None = None
+    window_passenger_front: int | None = None
+    window_passenger_rear: int | None = None
+    ft: int | None = None
+    rt: int | None = None
+    homelink_nearby: bool | None = None
+    is_user_present: bool | None = None
+    center_display_state: int | None = None
+    dashcam_state: str | None = None
+    remote_start_enabled: bool | None = None
+    tpms_pressure_fl: float | None = None
+    tpms_pressure_fr: float | None = None
+    tpms_pressure_rl: float | None = None
+    tpms_pressure_rr: float | None = None
+    software_update: SoftwareUpdateInfo | None = None
+
+
+class VehicleConfig(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    car_type: str | None = None
+    trim_badging: str | None = None
+    exterior_color: str | None = None
+    wheel_type: str | None = None
+    can_accept_navigation_requests: bool | None = None
+    can_actuate_trunks: bool | None = None
+    eu_vehicle: bool | None = None
+    has_seat_cooling: bool | None = None
+    motorized_charge_port: bool | None = None
+    plg: bool | None = None
+    roof_color: str | None = None
+
+
+class GuiSettings(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    gui_distance_units: str | None = None
+    gui_temperature_units: str | None = None
+    gui_charge_rate_units: str | None = None
+
+
+class VehicleData(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    vin: str
+    display_name: str | None = None
+    state: str = "unknown"
+    vehicle_id: int | None = None
+    charge_state: ChargeState | None = None
+    climate_state: ClimateState | None = None
+    drive_state: DriveState | None = None
+    vehicle_state: VehicleState | None = None
+    vehicle_config: VehicleConfig | None = None
+    gui_settings: GuiSettings | None = None
+
+
+class SuperchargerInfo(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    name: str | None = None
+    location: dict[str, float] | None = None
+    distance_miles: float | None = None
+    total_stalls: int | None = None
+    available_stalls: int | None = None
+
+
+class DestChargerInfo(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    name: str | None = None
+    location: dict[str, float] | None = None
+    distance_miles: float | None = None
+
+
+class NearbyChargingSites(BaseModel):
+    model_config = _EXTRA_ALLOW
+
+    superchargers: list[SuperchargerInfo] = []
+    destination_charging: list[DestChargerInfo] = []
+    congestion_sync_time_utc_secs: int | None = None
+    timestamp: int | None = None

tescmd/output/__init__.py

@@ -0,0 +1,5 @@
+"""Output formatting for tescmd."""
+
+from tescmd.output.formatter import OutputFormatter
+
+__all__ = ["OutputFormatter"]

tescmd/output/formatter.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any
+
+from rich.console import Console
+
+from tescmd.output.json_output import format_json_error, format_json_response
+from tescmd.output.rich_output import DisplayUnits, RichOutput
+
+if TYPE_CHECKING:
+    from io import TextIOBase
+
+
+class OutputFormatter:
+    """Unified output formatter that auto-detects JSON vs Rich output.
+
+    Selection logic:
+
+    * If *force_format* is provided, use it unconditionally.
+    * Otherwise, if *stream* (default ``sys.stdout``) is a TTY, use ``"rich"``.
+    * If the stream is **not** a TTY (piped / redirected), use ``"json"``.
+
+    When the format is ``"quiet"``, a :class:`rich.console.Console` writing to
+    *stderr* is used so that normal stdout stays empty.
+
+    Error stream routing:
+
+    * **JSON / piped** — errors go to **stderr** so stdout stays clean for
+      machine-parseable data (callers can safely ``| jq``).
+    * **Rich / TTY** — errors stay on **stdout** because the user is looking
+      at the terminal directly; splitting streams would be worse UX.
+    * Interactive prompts (wake confirmation, enrollment approval) always use
+      stdout via Rich since they are inherently TTY-only.
+    """
+
+    def __init__(
+        self,
+        *,
+        stream: TextIOBase | Any | None = None,
+        force_format: str | None = None,
+        units: DisplayUnits | None = None,
+    ) -> None:
+        self._stream = stream or sys.stdout
+        if force_format is not None:
+            self._format = force_format
+        elif hasattr(self._stream, "isatty") and self._stream.isatty():
+            self._format = "rich"
+        else:
+            self._format = "json"
+
+        # Build the Rich console — quiet mode writes to stderr.
+        if self._format == "quiet":
+            self._console = Console(stderr=True)
+        else:
+            self._console = Console()
+
+        # Separate stderr console for error output so stdout stays clean
+        # for machine-parseable data (JSON, piped workflows).
+        self._error_console = Console(stderr=True)
+
+        self._rich = RichOutput(self._console, units=units)
+        self._cache_meta: dict[str, Any] | None = None
+
+    # ------------------------------------------------------------------
+    # Public helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def format(self) -> str:
+        """Return the active output format (``"rich"``, ``"json"``, or ``"quiet"``)."""
+        return self._format
+
+    @property
+    def console(self) -> Console:
+        """Return the underlying :class:`Console` instance."""
+        return self._console
+
+    @property
+    def rich(self) -> RichOutput:
+        """Return the underlying :class:`RichOutput` instance."""
+        return self._rich
+
+    def set_cache_meta(
+        self,
+        *,
+        hit: bool,
+        age_seconds: int,
+        ttl_seconds: int,
+    ) -> None:
+        """Store cache metadata to be included in the next JSON output."""
+        self._cache_meta = {
+            "hit": hit,
+            "age_seconds": age_seconds,
+            "ttl_seconds": ttl_seconds,
+        }
+
+    def output(self, data: Any, *, command: str) -> None:
+        """Emit *data* using the current format.
+
+        * **json** — prints :func:`format_json_response` to stdout.
+        * **rich** / **quiet** — delegates to :attr:`rich` methods when the
+          data type is recognised, otherwise falls back to
+          :meth:`RichOutput.info` with a ``str()`` representation.
+        """
+        if self._format == "json":
+            print(format_json_response(data=data, command=command, cache_meta=self._cache_meta))
+            self._cache_meta = None
+        else:
+            # Rich / quiet fallback — callers normally use self.rich directly
+            # for typed output; this is a catch-all.
+            self._rich.info(str(data))
+
+    @property
+    def error_console(self) -> Console:
+        """Return the stderr :class:`Console` for error output."""
+        return self._error_console
+
+    def output_error(self, *, code: str, message: str, command: str) -> None:
+        """Emit an error using the current format.
+
+        * **json** — prints :func:`format_json_error` to stderr.
+        * **rich** / **quiet** — prints via :meth:`RichOutput.error` (stdout,
+          since TTY users see the terminal directly).
+        """
+        if self._format == "json":
+            print(
+                format_json_error(code=code, message=message, command=command),
+                file=sys.stderr,
+            )
+        else:
+            self._rich.error(message)

tescmd/output/json_output.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def _serialize(obj: Any) -> Any:
+    """Convert *obj* to a JSON-friendly structure.
+
+    * :class:`pydantic.BaseModel` instances are dumped via
+      :meth:`~pydantic.BaseModel.model_dump` with *exclude_none=True*.
+    * Lists are recursed element-wise.
+    * Dicts are recursed value-wise (nested Pydantic models are serialized).
+    * Everything else is returned as-is (``json.dumps`` handles the rest via
+      *default=str*).
+    """
+    if isinstance(obj, BaseModel):
+        return obj.model_dump(exclude_none=True)
+    if isinstance(obj, dict):
+        return {k: _serialize(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_serialize(item) for item in obj]
+    return obj
+
+
+def format_json_response(
+    *,
+    data: Any,
+    command: str,
+    cache_meta: dict[str, Any] | None = None,
+) -> str:
+    """Return a JSON envelope for a successful response.
+
+    The envelope has the shape::
+
+        {
+          "ok": true,
+          "command": "<command>",
+          "data": <serialised payload>,
+          "timestamp": "<ISO-8601 UTC>",
+          "_cache": {"hit": true, "age_seconds": N, "ttl_seconds": M}  // optional
+        }
+    """
+    envelope: dict[str, Any] = {
+        "ok": True,
+        "command": command,
+        "data": _serialize(data),
+        "timestamp": datetime.now(UTC).isoformat(),
+    }
+    if cache_meta is not None:
+        envelope["_cache"] = cache_meta
+    return json.dumps(envelope, indent=2, default=str)
+
+
+def format_json_error(
+    *,
+    code: str,
+    message: str,
+    command: str,
+    **extra: Any,
+) -> str:
+    """Return a JSON envelope for an error response.
+
+    The envelope has the shape::
+
+        {
+          "ok": false,
+          "command": "<command>",
+          "error": {"code": "...", "message": "...", ...extra},
+          "timestamp": "<ISO-8601 UTC>"
+        }
+    """
+    error_body: dict[str, Any] = {"code": code, "message": message, **extra}
+    envelope: dict[str, Any] = {
+        "ok": False,
+        "command": command,
+        "error": error_body,
+        "timestamp": datetime.now(UTC).isoformat(),
+    }
+    return json.dumps(envelope, indent=2, default=str)