pygaposa 0.1.0__tar.gz

pygaposa-0.1.0/CHANGELOG.rst

@@ -0,0 +1,18 @@
+Changelog
+=========
+
+All notable changes to package_name will be documented here.
+
+The format is based on `Keep a Changelog`_, and this project adheres to `Semantic Versioning`_.
+
+.. _Keep a Changelog: https://keepachangelog.com/en/1.0.0/
+.. _Semantic Versioning: https://semver.org/spec/v2.0.0.html
+
+Categories for changes are: Added, Changed, Deprecated, Removed, Fixed, Security.
+
+
+Version `0.1.0 <https://github.com/your_organisation/package_name/tree/0.1.0>`__
+--------------------------------------------------------------------------------
+
+Release date: YYYY-MM-DD.
+Initial release (to be released).

pygaposa-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2023 Mark Watson <markwatson@cantab.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

pygaposa-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include CHANGELOG.rst
+include LICEN[CS]E*
+include pyproject.toml
+include README.rst
+include requirements*.txt
+
+global-exclude *.py[co]
+global-exclude __pycache__
+global-exclude *~
+global-exclude *.ipynb_checkpoints/*

pygaposa-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.1
+Name: pygaposa
+Version: 0.1.0
+Summary: Unofficial module for access to Gaposa morotized shades cloud API
+Home-page: https://github.com/mwatson2/pygaposa
+Author: Mark Watson
+Author-email: markwatson@cantab.net
+License: MIT
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.6
+Description-Content-Type: text/x-rst
+Provides-Extra: test
+Provides-Extra: docs
+Provides-Extra: dev
+Provides-Extra: all
+License-File: LICENSE
+
+|GHA tests| |Codecov report| |pre-commit| |black|
+
+Gaposa Motorized Shades API
+===========================
+
+This module provides unofficial access to the cloud API for Gaposa motorized shades as used by the RollApp mobile application
+
+
+Contributing
+------------
+
+Contributions are welcome! If you can see a way to improve this module:
+
+- Do click the fork button
+- Make your changes and make a pull request.
+
+Or to report a bug or request something new, make an issue.
+
+.. |GHA tests| image:: https://github.com/mwatson2/pygaposa/workflows/tests/badge.svg
+   :target: https://github.com/mwatson2/pygaposa/actions?query=workflow%3Atests
+   :alt: GHA Status
+.. |Codecov report| image:: https://codecov.io/github/mwatson2/pygaposa/coverage.svg?branch=master
+   :target: https://codecov.io/github/mwatson2/pygaposa?branch=master
+   :alt: Coverage
+.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+   :alt: black

pygaposa-0.1.0/README.rst

@@ -0,0 +1,30 @@
+|GHA tests| |Codecov report| |pre-commit| |black|
+
+Gaposa Motorized Shades API
+===========================
+
+This module provides unofficial access to the cloud API for Gaposa motorized shades as used by the RollApp mobile application
+
+
+Contributing
+------------
+
+Contributions are welcome! If you can see a way to improve this module:
+
+- Do click the fork button
+- Make your changes and make a pull request.
+
+Or to report a bug or request something new, make an issue.
+
+.. |GHA tests| image:: https://github.com/mwatson2/pygaposa/workflows/tests/badge.svg
+   :target: https://github.com/mwatson2/pygaposa/actions?query=workflow%3Atests
+   :alt: GHA Status
+.. |Codecov report| image:: https://codecov.io/github/mwatson2/pygaposa/coverage.svg?branch=master
+   :target: https://codecov.io/github/mwatson2/pygaposa?branch=master
+   :alt: Coverage
+.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
+   :target: https://github.com/psf/black
+   :alt: black

pygaposa-0.1.0/pygaposa/__init__.py

@@ -0,0 +1,10 @@
+from . import __meta__
+from .client import Client
+from .device import Device
+from .gaposa import FirebaseAuthException, Gaposa, GaposaAuthException
+from .group import Group
+from .motor import Motor
+from .room import Room
+from .schedule import Schedule
+
+__version__ = __meta__.version

pygaposa-0.1.0/pygaposa/__meta__.py

@@ -0,0 +1,12 @@
+# `name` is the name of the package as used for `pip install package`
+name = "pygaposa"
+# `path` is the name of the package for `import package`
+path = name.lower().replace("-", "_").replace(" ", "_")
+# Your version number should follow https://python.org/dev/peps/pep-0440 and
+# https://semver.org
+version = "0.1.0"
+author = "Mark Watson"
+author_email = "markwatson@cantab.net"
+description = "Unofficial module for access to Gaposa morotized shades cloud API"
+url = "https://github.com/mwatson2/pygaposa"
+license = "MIT"

pygaposa-0.1.0/pygaposa/api.py

@@ -0,0 +1,252 @@
+import json
+import logging
+from typing import Awaitable, Callable, Literal, Optional, Union
+
+from aiohttp import ClientSession
+from typeguard import check_type
+
+from pygaposa.api_types import (
+    ApiControlRequest,
+    ApiControlRequestChannel,
+    ApiControlResponse,
+    ApiLoginResponse,
+    ApiRequestPayload,
+    ApiScheduleEventRequest,
+    ApiScheduleEventResponse,
+    ApiScheduleRequest,
+    ApiScheduleResponse,
+    ApiUsersResponse,
+    Command,
+    ScheduleEventInfo,
+    ScheduleEventType,
+    ScheduleUpdate,
+)
+
+logging.basicConfig(level=logging.DEBUG)
+
+
+class GaposaApi:
+    """A class for interacting with the GAPOSA API.
+
+    Arguments:
+    ---------
+        websession: An aiohttp ClientSession to use for requests.
+        getToken: A callable that returns a valid Google Authentication token.
+        serverUrl: The URL of the GAPOSA server to use.
+    """
+
+    # serverUrl: str = "https://20230124t120606-dot-gaposa-prod.ew.r.appspot.com"
+    # serverUrl: str = "https://gaposa-prod.ew.r.appspot.com"
+    serverUrl = "https://backend.rollapp.tech"
+
+    def __init__(
+        self,
+        websession: ClientSession,
+        getToken: Callable[[], Awaitable[str]],
+        serverUrl: Optional[str] = None,
+    ):
+        self.serverUrl = serverUrl or GaposaApi.serverUrl
+        self.websession = websession
+        self.getToken = getToken
+        self.logger = logging.getLogger("gaposa")
+
+    def clone(self) -> "GaposaApi":
+        """Create a new GaposaApi instance with the same configuration as this one.
+
+        This enables us to create instances of the API with different configurations,
+        for example for different clients and devices.
+        """
+        result = GaposaApi(self.websession, self.getToken, self.serverUrl)
+        if hasattr(self, "client"):
+            result.setClientAndRole(self.client, self.role)
+        if hasattr(self, "serial"):
+            result.setSerial(self.serial)
+        return result
+
+    def setClientAndRole(self, client: str, role: int):
+        """Set the client and role for this API instance."""
+        self.client = client
+        self.role = role
+
+    def setSerial(self, serial: str):
+        """Set the serial number for this API instance."""
+        self.serial = serial
+
+    async def login(self) -> ApiLoginResponse:
+        """Log in to the GAPOSA API."""
+        response = await self.request("/v1/login")
+        return check_type(response, ApiLoginResponse)
+
+    async def users(self) -> ApiUsersResponse:
+        """Get the list of users for the client set on this API instance."""
+        assert hasattr(self, "client")
+        response = await self.request("/v1/users")
+        return check_type(response, ApiUsersResponse)
+
+    async def control(
+        self,
+        command: Command,
+        scope: Union[Literal["channel"], Literal["group"]],
+        id: str,
+    ):
+        """Send a control command to a channel or group.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        assert hasattr(self, "client")
+        assert hasattr(self, "serial")
+        if scope == "channel":
+            payload: ApiControlRequest = {
+                "serial": self.serial,
+                "data": {"cmd": command.value, "bank": 0, "address": int(id)},
+            }
+        else:
+            payload = {
+                "serial": self.serial,
+                "group": id,
+                "data": {"cmd": command.value},
+            }
+
+        response = await self.request("/v1/control", "POST", payload)
+        return check_type(response, ApiControlResponse)
+
+    async def addSchedule(self, schedule: ScheduleUpdate) -> ApiScheduleResponse:
+        """Add a new schedule. This is a convenience method for addOrUpdateSchedule.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        assert "Id" not in schedule
+        return await self.addOrUpdateSchedule(schedule)
+
+    async def updateSchedule(self, schedule: ScheduleUpdate) -> ApiScheduleResponse:
+        """Update an existing schedule.
+
+        This is a convenience method for addOrUpdateSchedule.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        assert "Id" in schedule
+        return await self.addOrUpdateSchedule(schedule)
+
+    async def addOrUpdateSchedule(
+        self, schedule: ScheduleUpdate
+    ) -> ApiScheduleResponse:
+        """Add or update a schedule.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        assert hasattr(self, "client")
+        assert hasattr(self, "serial")
+        method = "POST" if "Id" not in schedule else "PUT"
+        payload: ApiScheduleRequest = {"serial": self.serial, "schedule": schedule}
+        response = await self.request("/v1/schedules", method, payload)
+        return check_type(response, ApiScheduleResponse)
+
+    async def deleteSchedule(self, Id: str) -> ApiScheduleResponse:
+        """Delete a schedule.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        assert hasattr(self, "client")
+        assert hasattr(self, "serial")
+        payload: ApiScheduleRequest = {"serial": self.serial, "schedule": {"Id": Id}}
+        response = await self.request("/v1/schedules", "DELETE", payload)
+        return check_type(response, ApiScheduleResponse)
+
+    async def addScheduleEvent(
+        self, Id: str, Mode: ScheduleEventType, event: ScheduleEventInfo
+    ) -> ApiScheduleEventResponse:
+        """Add a new event to a schedule.
+
+        This is a convenience method for updateScheduleEvent.
+
+        Schedules have three events for the three possible operations,
+        UP, DONW and PRESET. This is specified in the Mode argument.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        assert hasattr(self, "client")
+        assert hasattr(self, "serial")
+        payload: ApiScheduleEventRequest = {
+            "serial": self.serial,
+            "schedule": {"Id": Id, "Mode": Mode.value},
+            "event": event,
+        }
+        response = await self.request("/v1/schedules/event", "PUT", payload)
+        return check_type(response, ApiScheduleEventResponse)
+
+    async def updateScheduleEvent(
+        self, Id: str, Mode: ScheduleEventType, event: ScheduleEventInfo
+    ) -> ApiScheduleEventResponse:
+        """Update an existing event in a schedule.
+
+        This is a convenience method for addScheduleEvent.
+
+        Schedules have three events for the three possible operations,
+        UP, DONW and PRESET. This is specified in the Mode argument.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        return await self.addScheduleEvent(Id, Mode, event)
+
+    async def deleteScheduleEvent(
+        self, Id: str, Mode: ScheduleEventType
+    ) -> ApiScheduleEventResponse:
+        """Delete an event from a schedule.
+
+        Schedules have three events for the three possible operations,
+        UP, DONW and PRESET. This is specified in the Mode argument.
+
+        This API instance must have been configured with client and device serial
+        before calling this method.
+        """
+        assert hasattr(self, "client")
+        assert hasattr(self, "serial")
+        payload: ApiScheduleEventRequest = {
+            "serial": self.serial,
+            "schedule": {"Id": Id, "Mode": Mode},
+        }
+        response = await self.request("/v1/schedules/event", "DELETE", payload)
+        return check_type(response, ApiScheduleEventResponse)
+
+    async def request(
+        self,
+        endpoint: str,
+        method: str = "GET",
+        payload: Optional[ApiRequestPayload] = None,
+    ):
+        idToken = await self.getToken()
+        headers = {
+            "Content-Type": "application/json",
+            "authorization": f"Bearer {idToken}",
+        }
+        if hasattr(self, "client"):
+            headers["auth"] = json.dumps({"role": self.role, "client": self.client})
+
+        data = json.dumps({"payload": payload}) if payload else None
+
+        response = await self.websession.request(
+            method,
+            self.serverUrl + endpoint,
+            headers=headers,
+            data=data,
+            raise_for_status=True,
+        )
+
+        self.logger.debug(f"Request: {method} {endpoint}")
+        self.logger.debug(f"Headers: {headers}")
+        self.logger.debug(f"Payload: {data}")
+        self.logger.debug(f"Response: {response}")
+
+        responseObject = await response.json()
+
+        self.logger.debug(f"Response object: {responseObject}")
+
+        return responseObject

pygaposa-0.1.0/pygaposa/api_types.py

@@ -0,0 +1,287 @@
+from enum import Enum, IntEnum
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+
+class DeviceInfo(TypedDict):
+    Name: str
+    Serial: str
+
+
+class ClientInfo(TypedDict):
+    Role: int
+    Name: str
+    Devices: List[DeviceInfo]
+
+
+class AuthResult(TypedDict):
+    TermsAgreed: bool
+    UserRole: int
+    Clients: Dict[str, ClientInfo]
+    DateFormat: Any
+    TimeFormat: Any
+    Theme: Any
+
+
+# Response for /v1/login
+class ApiLoginResponse(TypedDict):
+    apiStatus: Literal["Success"]
+    msg: Literal["Auth"]
+    result: AuthResult
+
+
+class UserInfo(TypedDict):
+    CountryID: str
+    EmailAlert: bool
+    Email: str
+    Name: str
+    Role: int
+    Uid: str
+    Active: bool
+    CompoundLocation: str
+    Country: str
+    Joined: Dict[str, int]
+    TermsAgreed: bool
+    CountryCode: str
+    Mobile: str
+
+
+class UsersResult(TypedDict):
+    Info: UserInfo
+
+
+# Response for /v1/users
+class ApiUsersResponse(TypedDict):
+    apiStatus: Literal["success"]
+    msg: Literal["Return user"]
+    result: UsersResult
+
+
+class Command(str, Enum):
+    DOWN = "0xee"
+    UP = "0xdd"
+    STOP = "0xcc"
+    PRESET = "0xad"
+
+
+class EventDays(IntEnum):
+    MON = 0
+    TUE = 1
+    WED = 2
+    THU = 3
+    FRI = 4
+    SAT = 5
+    SUN = 6
+    ALL = 7
+    WEEKDAYS = 8
+    WEEKENDS = 9
+
+
+NumericIdentifier = str
+Location = TypedDict("Location", {"_latitude": float, "_longitude": float})
+EventRepeat = tuple[bool, bool, bool, bool, bool, bool, bool]
+
+
+class State(TypedDict):
+    TimeStamp: str
+    OnLine: bool
+    LastCmd: str
+    Message: str
+
+
+class Info(TypedDict):
+    Name: str
+    ClientId: str
+
+
+class Assistant(TypedDict):
+    Alexa: bool
+    Home: bool
+
+
+class HeartBeat(TypedDict):
+    Subnet: str
+    Channels: int
+    Software: str
+    Signal: int
+    Mode: str
+    Frequency: int
+    Gateway: str
+    Ip: str
+    TxID: list[int]
+
+
+class Channel(TypedDict):
+    StatusCode: int
+    State: str
+    HomeRunning: bool
+    Location: str
+    HomePercent: int
+    Icon: str
+    Name: str
+    HomePaused: bool
+
+
+class RoomInfo(TypedDict):
+    Favourite: bool
+    Motors: list[int]
+    Name: str
+    Icon: str
+
+
+class GroupInfo(TypedDict):
+    Favourite: bool
+    Icon: str
+    Name: str
+    Motors: list[int]
+    Rooms: list[str]
+
+
+class ScheduleInfo(TypedDict):
+    Name: str
+    Groups: list[int]
+    Location: Location
+    Motors: list[int]
+    Icon: str
+    Active: bool
+
+
+class ScheduleUpdate(TypedDict, total=False):
+    Id: NumericIdentifier
+    Name: str
+    Groups: list[int]
+    Location: Location
+    Motors: list[int]
+    Icon: str
+    Active: bool
+
+
+class DeviceDocumentRequired(TypedDict):
+    State: State
+    Info: Info
+    Assistant: Assistant
+    Channels: Dict[str, Channel]
+    Rooms: Dict[str, RoomInfo]  # key is room name
+    Groups: Dict[NumericIdentifier, GroupInfo]
+    HeartBeat: HeartBeat
+    DeletedChannels: List[int]
+    Pending: list
+    Uid: list[str]
+
+
+class DeviceDocument(DeviceDocumentRequired, total=False):
+    Schedule: Dict[NumericIdentifier, ScheduleInfo]
+
+
+class EventMode(TypedDict):
+    SunRise: bool
+    SunSet: bool
+    TimeDay: bool
+
+
+class ScheduleEventInfo(TypedDict):
+    EventRepeat: EventRepeat
+    TimeZone: str
+    Active: bool
+    FutureEvent: bool
+    Submit: bool
+    EventEpoch: int
+    Location: Location
+    Motors: list[int]
+    EventMode: EventMode
+
+
+class NamedItem(TypedDict):
+    Name: str
+
+
+class ScheduleEventType(str, Enum):
+    UP = "UP"
+    DOWN = "DOWN"
+    PRESET = "PRESET"
+
+
+class ApiControlResult(TypedDict):
+    Success: Literal["OK"]
+
+
+class ApiGroupControlData(TypedDict):
+    cmd: str
+
+
+class ApiChannelControlData(TypedDict):
+    cmd: str
+    bank: int
+    address: int
+
+
+# Request for /control
+class ApiControlRequestBase(TypedDict):
+    serial: str
+
+
+class ApiControlRequestGroup(ApiControlRequestBase):
+    group: str
+    data: ApiGroupControlData
+
+
+class ApiControlRequestChannel(ApiControlRequestBase):
+    data: ApiChannelControlData
+
+
+ApiControlRequest = Union[ApiControlRequestChannel, ApiControlRequestGroup]
+
+
+# Response for /control
+class ApiControlResponse(TypedDict):
+    apiCommand: Literal["Success"]
+    msg: Literal["OK"]
+    result: ApiControlResult
+
+
+# Request for /v1/schedules (in "payload" field)
+class ApiScheduleRequest(TypedDict):
+    serial: str
+    schedule: ScheduleUpdate
+
+
+class ApiScheduleDeleteResult(TypedDict):
+    Schedule: bool
+    Down: bool
+    Up: bool
+    Preset: bool
+
+
+# Response for /v1/schedules
+class ApiScheduleResponse(TypedDict):
+    apiStatus: Literal["success"]
+    msg: Union[
+        Literal["Schedule Update"], Literal["Schedule deleted"], Literal["Schedule Add"]
+    ]
+    result: Union[Literal["ok"], ApiScheduleDeleteResult, str]
+
+
+class ScheduleEventSelector(TypedDict):
+    Id: NumericIdentifier
+    Mode: str
+
+
+# Request for /v1/schedules/event (in "payload" field)
+class ApiScheduleEventRequestBase(TypedDict):
+    serial: str
+    schedule: ScheduleEventSelector
+
+
+class ApiScheduleEventRequest(ApiScheduleEventRequestBase, total=False):
+    event: ScheduleEventInfo
+
+
+# Response for /v1/schedules/event
+class ApiScheduleEventResponse(TypedDict):
+    apiStatus: Literal["success"]
+    msg: Literal["Schedule Add"]
+    result: str
+
+
+ApiRequestPayload = Union[
+    ApiScheduleRequest, ApiScheduleEventRequest, ApiControlRequest
+]