mercuto-client 0.3.0__py3-none-any.whl → 0.3.4a3__py3-none-any.whl

mercuto_client/modules/media.py

@@ -0,0 +1,324 @@
+import os
+from datetime import timedelta
+from typing import TYPE_CHECKING, Literal, Optional
+
+from pydantic import TypeAdapter
+
+if TYPE_CHECKING:
+    from ..client import MercutoClient
+
+from datetime import datetime
+
+from ..exceptions import MercutoHTTPException
+from . import PayloadType
+from ._util import BaseModel
+
+
+class Image(BaseModel):
+    code: str
+    project: str
+    mime_type: str
+    size_bytes: int
+    name: str
+    access_url: str
+    access_expires: datetime
+    camera: Optional[str] = None
+    timestamp: Optional[datetime] = None
+    event: Optional[str] = None
+
+
+class Video(BaseModel):
+    code: str
+    project: str
+    start_time: datetime
+    end_time: datetime
+
+    mime_type: str
+    size_bytes: int
+    name: str
+
+    access_url: str
+    access_expires: datetime
+
+    event: Optional[str] = None
+    camera: Optional[str] = None
+
+
+class _VideoUploadInitializeResponse(BaseModel):
+    request_id: str
+    presigned_put_url: str
+    presigned_url_expires: datetime
+
+
+class Healthcheck(BaseModel):
+    status: str
+
+
+class CameraTrigger(BaseModel):
+    trigger_channel: str
+    pre_interval: timedelta = timedelta(seconds=10)
+    post_interval: timedelta = timedelta(seconds=10)
+    enabled: bool = True
+    trigger_greater_than: Optional[float] = None
+    trigger_less_than: Optional[float] = None
+
+
+class Camera(BaseModel):
+    code: str
+    project: str
+    label: str
+    triggers: list[CameraTrigger]
+    camera_type: Literal['BOSCH', 'DIRECT_RTSP',
+                         'STATIC', 'ROCKFIELD-CAMERA-SERVER-VERSION-2']
+    encode_timestamp: bool = True
+    encode_blur: bool = False
+    blur_steps: Optional[int] = None
+    blur_sigma: Optional[float] = None
+    tunnel_address: Optional[str] = None
+    tunnel_port: Optional[int] = None
+    tunnel_username: Optional[str] = None
+    tunnel_password: Optional[str] = None
+    tunnel_key: Optional[str] = None
+    camera_ip: Optional[str] = None
+    camera_port: Optional[int] = None
+    camera_username: Optional[str] = None
+    camera_password: Optional[str] = None
+    camera_serial: Optional[str] = None
+    rtsp_url: Optional[str] = None
+
+
+# --- TypeAdapters for lists ---
+_ImagelistAdapter = TypeAdapter(list[Image])
+_VideolistAdapter = TypeAdapter(list[Video])
+
+
+class MercutoMediaService:
+    def __init__(self, client: 'MercutoClient', path: str = '/media') -> None:
+        self._client = client
+        self._path = path
+
+    def healthcheck(self) -> Healthcheck:
+        r = self._client.request(f"{self._path}/healthcheck", "GET")
+        return Healthcheck.model_validate_json(r.text)
+
+    # --- Images ---
+
+    def list_images(self, project: str,
+                    camera: Optional[str] = None,
+                    event: Optional[str] = None,
+                    start_time: Optional[datetime] = None,
+                    end_time: Optional[datetime] = None,
+                    limit: int = 10,
+                    offset: int = 0,
+                    ascending: bool = True) -> list[Image]:
+        params: PayloadType = {
+            'project': project,
+            'limit': limit,
+            'offset': offset,
+            'ascending': ascending
+        }
+        if camera is not None:
+            params["camera"] = camera
+        if event is not None:
+            params["event"] = event
+        if start_time is not None:
+            if start_time.tzinfo is None:
+                raise ValueError("start_time must be timezone-aware")
+            params["start_time"] = start_time.isoformat()
+        if end_time is not None:
+            if end_time.tzinfo is None:
+                raise ValueError("end_time must be timezone-aware")
+            params["end_time"] = end_time.isoformat()
+        r = self._client.request(f"{self._path}/images", "GET", params=params)
+        return _ImagelistAdapter.validate_json(r.text)
+
+    def get_image(self, image_code: str) -> Image:
+        r = self._client.request(f"{self._path}/images/{image_code}", "GET")
+        return Image.model_validate_json(r.text)
+
+    def delete_image(self, image_code: str) -> None:
+        self._client.request(f"{self._path}/images/{image_code}", "DELETE")
+
+    def upload_image(self, filename: str, project: str,
+                     camera: Optional[str] = None,
+                     timestamp: Optional[datetime] = None,
+                     event: Optional[str] = None,
+                     filedata: Optional[bytes] = None) -> Image:
+        """
+        Upload an image to the media service.
+        Provide either filename (path to file) or filedata (bytes of file) + filename (reference only).
+        """
+        params: PayloadType = {
+            'project': project
+        }
+        if camera is not None:
+            params["camera"] = camera
+        if timestamp is not None:
+            if timestamp.tzinfo is None:
+                raise ValueError("timestamp must be timezone-aware")
+            params["timestamp"] = timestamp.isoformat()
+        if event is not None:
+            params["event"] = event
+
+        if filedata is not None:
+            from io import BytesIO
+            r = self._client.request(
+                f"{self._path}/images", "PUT", params=params, files={'file': (filename, BytesIO(filedata))})
+            return Image.model_validate_json(r.text)
+        else:
+            with open(filename, 'rb') as f:
+                r = self._client.request(
+                    f"{self._path}/images", "PUT", params=params, files={'file': f})
+        return Image.model_validate_json(r.text)
+
+    # --- Videos ---
+
+    def list_videos(self, project: str,
+                    camera: Optional[str] = None,
+                    event: Optional[str] = None,
+                    start_time: Optional[datetime] = None,
+                    end_time: Optional[datetime] = None,
+                    limit: int = 10,
+                    offset: int = 0,
+                    ascending: bool = True) -> list[Video]:
+        params: PayloadType = {
+            'project': project,
+            'limit': limit,
+            'offset': offset,
+            'ascending': ascending
+        }
+        if camera is not None:
+            params["camera"] = camera
+        if event is not None:
+            params["event"] = event
+        if start_time is not None:
+            if start_time.tzinfo is None:
+                raise ValueError("start_time must be timezone-aware")
+            params["start_time"] = start_time.isoformat()
+        if end_time is not None:
+            if end_time.tzinfo is None:
+                raise ValueError("end_time must be timezone-aware")
+            params["end_time"] = end_time.isoformat()
+        r = self._client.request(f"{self._path}/videos", "GET", params=params)
+        return _VideolistAdapter.validate_json(r.text)
+
+    def get_video(self, video_code: str) -> Video:
+        r = self._client.request(f"{self._path}/videos/{video_code}", "GET")
+        return Video.model_validate_json(r.text)
+
+    def upload_video(self, filename: str, project: str,
+                     start_time: datetime,
+                     end_time: datetime,
+                     camera: Optional[str] = None,
+                     event: Optional[str] = None) -> str:
+        """
+        Upload a video file to the media service.
+        This is a multi-step process.
+        First, the request is initialized to get an upload URL.
+        Then, the file is uploaded to the provided URL.
+        Finally, the upload is finalized.
+
+        :returns: A request ID used to track the status of the uploaded video processing. Pass this to the /requests/{request_id} endpoint
+        to check the status and get the video_id once processing is complete.
+        """
+        import mimetypes
+        mime_type = mimetypes.guess_type(filename, strict=False)[0]
+        if mime_type is None:
+            raise ValueError(
+                f"Could not determine MIME type for file: {filename}")
+        if mime_type not in {'video/mp4', 'video/avi', 'video/mov', 'video/mkv'}:
+            raise ValueError(f"Unsupported video MIME type: {mime_type}")
+
+        # 1. Make the initialize upload request
+        init_payload: PayloadType = {
+            'start_time': start_time.isoformat(),
+            'end_time': end_time.isoformat(),
+            'mime_type': mime_type,
+            'filename': os.path.basename(filename)
+        }
+        if camera is not None:
+            init_payload['camera'] = camera
+        if event is not None:
+            init_payload['event'] = event
+        init_request = self._client.request(f"{self._path}/videos", "POST", json=init_payload,
+                                            params={'project': project, 'action': 'initialize'})
+        init_request_response = _VideoUploadInitializeResponse.model_validate_json(
+            init_request.text)
+
+        # 2. Upload the video file
+        with open(filename, 'rb') as f:
+            resp = self._client.session().put(init_request_response.presigned_put_url,
+                                              data=f, verify=self._client.verify_ssl)
+            if not resp.ok:
+                raise MercutoHTTPException(
+                    f"Video upload failed: {resp.text}", resp.status_code)
+
+        # 3. Finalize the upload
+        self._client.request(f"{self._path}/videos", "POST", params={
+            'project': project,
+            'action': 'commit',
+            'request_id': init_request_response.request_id
+        })
+
+        return init_request_response.request_id
+
+    # --- Cameras ---
+
+    def create_camera(self, project: str,
+                      label: str,
+                      triggers: list[CameraTrigger],
+                      encode_timestamp: bool = True,
+                      encode_blur: bool = False,
+                      blur_steps: Optional[int] = None,
+                      blur_sigma: Optional[float] = None,
+                      tunnel_address: Optional[str] = None,
+                      tunnel_port: Optional[int] = None,
+                      tunnel_username: Optional[str] = None,
+                      tunnel_password: Optional[str] = None,
+                      tunnel_key: Optional[str] = None,
+                      camera_ip: Optional[str] = None,
+                      camera_port: Optional[int] = None,
+                      camera_username: Optional[str] = None,
+                      camera_password: Optional[str] = None,
+                      camera_serial: Optional[str] = None,
+                      camera_type: Literal['BOSCH', 'DIRECT_RTSP', 'STATIC',
+                                           'ROCKFIELD-CAMERA-SERVER-VERSION-2'] = 'DIRECT_RTSP',
+                      rtsp_url: Optional[str] = None,) -> Camera:
+        payload: PayloadType = {
+            'label': label,
+            'encode_timestamp': encode_timestamp,
+            'encode_blur': encode_blur,
+        }
+        if blur_steps is not None:
+            payload['blur_steps'] = blur_steps
+        if blur_sigma is not None:
+            payload['blur_sigma'] = blur_sigma
+        if tunnel_address is not None:
+            tunnel_payload: PayloadType = {
+                'address': tunnel_address,
+                'port': tunnel_port,
+                'username': tunnel_username,
+                'password': tunnel_password,
+                'key': tunnel_key
+            }
+            payload['ssh_tunnel'] = tunnel_payload
+        if camera_ip is not None:
+            payload['camera_ip'] = camera_ip
+        if camera_port is not None:
+            payload['camera_port'] = camera_port
+        if camera_username is not None:
+            payload['camera_username'] = camera_username
+        if camera_password is not None:
+            payload['camera_password'] = camera_password
+        if camera_serial is not None:
+            payload['camera_serial'] = camera_serial
+        payload['camera_type'] = camera_type
+        if rtsp_url is not None:
+            payload['rtsp_url'] = rtsp_url
+
+        if triggers:
+            payload['triggers'] = [trigger.model_dump(mode='json') for trigger in triggers]  # type: ignore
+
+        r = self._client.request(
+            f"{self._path}/cameras", "PUT", json=payload, params={'project': project})
+        return Camera.model_validate_json(r.text)

mercuto_client/modules/notifications.py

@@ -0,0 +1,88 @@
+from typing import TYPE_CHECKING, Literal, Optional
+
+from pydantic import TypeAdapter
+
+if TYPE_CHECKING:
+    from ..client import MercutoClient
+
+from ._util import BaseModel
+
+ContactMethod = Literal['EMAIL', 'SMS']
+
+
+class ContactGroup(BaseModel):
+    code: str
+    project: str
+    label: str
+    users: dict[str, list[ContactMethod]]
+
+
+class NotificationAttachment(BaseModel):
+    """
+    Attachment to include in the notification.
+    """
+    filename: str
+    presigned_url: str  # Presigned URL to fetch the attachment from.
+    mime_type: str
+
+
+class Healthcheck(BaseModel):
+    status: str
+
+
+# --- TypeAdapters for lists ---
+_ContactGroupListAdapter = TypeAdapter(list[ContactGroup])
+
+
+class MercutoNotificationService:
+    def __init__(self, client: 'MercutoClient', path: str = '/notifications') -> None:
+        self._client = client
+        self._path = path
+
+    def healthcheck(self) -> Healthcheck:
+        r = self._client.request(f"{self._path}/healthcheck", "GET")
+        return Healthcheck.model_validate_json(r.text)
+
+    def list_contact_groups(self, project: str) -> list[ContactGroup]:
+        r = self._client.request(f"{self._path}/contact-groups", "GET", params={"project": project})
+        return _ContactGroupListAdapter.validate_json(r.text)
+
+    def get_contact_group(self, code: str) -> ContactGroup:
+        r = self._client.request(f"{self._path}/contact-groups/{code}", "GET")
+        return ContactGroup.model_validate_json(r.text)
+
+    def create_contact_group(self, project: str, label: str, users: dict[str, list[ContactMethod]]) -> ContactGroup:
+        r = self._client.request(f"{self._path}/contact-groups", "PUT", json={
+            "project": project,
+            "label": label,
+            "users": users
+        })
+        return ContactGroup.model_validate_json(r.text)
+
+    def issue_notification(self, contact_group: str, subject: str, html: str,
+                           alternative_plaintext: Optional[str] = None,
+                           attachments: Optional[list[NotificationAttachment]] = None,
+                           unsubscribe_placeholder_text: Optional[str] = None) -> None:
+        """
+        Issue a notification to all contacts within a contact group, based on their contact preferences.
+
+        :param contact_group: The code of the contact group to send the notification to.
+        :param subject: The subject of the notification (i.e. email subject line).
+        :param html: The HTML content of the notification.
+        :param alternative_plaintext: Optional plaintext alternative for the notification.
+            Alternative plaintext is used for SMS notifications and for email clients that do not support HTML.
+        :param attachments: Optional list of attachments to include in the notification.
+            Only applicable for email notifications.
+        :param unsubscribe_placeholder_text: Optional placeholder text for unsubscribe links.
+            Any text matching this placeholder will be replaced with an unsubscribe link for email notifications.
+        :return: None
+        """
+
+        self._client.request(f"{self._path}/contact-groups/{contact_group}/notify", "POST", json={
+            "subject": subject,
+            "html": html,
+            "alternative_plaintext": alternative_plaintext,
+            "attachments": [attachment.model_dump() for attachment in attachments] if attachments else [],
+            "unsubscribe_placeholder_text": unsubscribe_placeholder_text
+        })
+        return

mercuto_client/modules/reports.py

@@ -0,0 +1,222 @@
+from datetime import datetime
+from typing import (TYPE_CHECKING, BinaryIO, Literal, Optional, Protocol,
+                    TypedDict)
+
+from pydantic import AwareDatetime, TypeAdapter
+
+from ..exceptions import MercutoHTTPException
+from . import PayloadType
+from ._util import BaseModel
+
+if TYPE_CHECKING:
+    from ..client import MercutoClient
+
+
+class ReportConfiguration(BaseModel):
+    code: str
+    project: str
+    label: str
+    revision: str
+    schedule: Optional[str] = None
+    contact_group: Optional[str] = None
+    last_scheduled: Optional[AwareDatetime] = None
+    custom_policy: Optional[str] = None
+
+
+ReportLogStatus = Literal['PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED']
+
+
+class ReportLog(BaseModel):
+    code: str
+    report_configuration: str
+    scheduled_start: Optional[AwareDatetime]
+    actual_start: AwareDatetime
+    actual_finish: Optional[AwareDatetime]
+    status: ReportLogStatus
+    message: Optional[str]
+    access_url: Optional[str]
+    mime_type: Optional[str]
+    filename: Optional[str]
+
+
+class ReportSourceCodeRevision(BaseModel):
+    code: str
+    project: Optional[str]
+    revision_date: AwareDatetime
+    description: str
+    source_code_url: str
+
+
+class Healthcheck(BaseModel):
+    status: str
+
+
+_ReportConfigurationListAdapter = TypeAdapter(list[ReportConfiguration])
+_ReportLogListAdapter = TypeAdapter(list[ReportLog])
+
+"""
+The below types are used for defining report generation functions.
+They are provided for type-checking and helpers for users writing custom reports.
+"""
+
+
+class ReportHandlerResultLike(Protocol):
+    filename: str
+    mime_type: str
+    data: bytes
+
+
+class ReportHandlerResult(BaseModel):
+    filename: str
+    mime_type: str
+    data: bytes
+
+
+class HandlerRequest(TypedDict):
+    timestamp: datetime
+
+
+class HandlerContext(TypedDict):
+    service_token: str
+    project_code: str
+    report_code: str
+    log_code: str
+    client: 'MercutoClient'
+
+
+class ReportHandler(Protocol):
+    def __call__(self,
+                 request: 'HandlerRequest',
+                 context: 'HandlerContext') -> 'ReportHandlerResultLike':
+        ...
+
+
+class MercutoReportService:
+    def __init__(self, client: 'MercutoClient', path: str = '/reports') -> None:
+        self._client = client
+        self._path = path
+
+    def healthcheck(self) -> Healthcheck:
+        r = self._client.request(f"{self._path}/healthcheck", "GET")
+        return Healthcheck.model_validate_json(r.text)
+
+    def list_report_configurations(self, project: str) -> list['ReportConfiguration']:
+        """
+        List scheduled reports for a specific project.
+        """
+        params: PayloadType = {
+            'project': project
+        }
+        r = self._client.request(
+            f'{self._path}/configurations', 'GET', params=params)
+        return _ReportConfigurationListAdapter.validate_json(r.text)
+
+    def create_report_configuration(self, project: str, label: str, schedule: str, revision: str,
+                                    contact_group: Optional[str] = None, custom_policy: Optional[str] = None) -> ReportConfiguration:
+        """
+        Create a new scheduled report using the provided source code revision.
+        """
+        json: PayloadType = {
+            'project': project,
+            'label': label,
+            'schedule': schedule,
+            'revision': revision,
+        }
+        if contact_group is not None:
+            json['contact_group'] = contact_group
+        if custom_policy is not None:
+            json['custom_policy'] = custom_policy
+        r = self._client.request(
+            f'{self._path}/configurations', 'PUT', json=json)
+        return ReportConfiguration.model_validate_json(r.text)
+
+    def generate_report(self, report: str, timestamp: datetime, mark_as_scheduled: bool = False) -> ReportLog:
+        """
+        Trigger generation of a scheduled report for a specific timestamp.
+        """
+        r = self._client.request(f'{self._path}/configurations/{report}/generate', 'POST', json={
+            'timestamp': timestamp.isoformat(),
+            'mark_as_scheduled': mark_as_scheduled
+        })
+        return ReportLog.model_validate_json(r.text)
+
+    def list_report_logs(self, project: str, report: Optional[str] = None) -> list[ReportLog]:
+        """
+        List report log entries for a specific project.
+        """
+        params: PayloadType = {
+            'project': project
+        }
+        if report is not None:
+            params['configuration'] = report
+        r = self._client.request(
+            f'{self._path}/logs', 'GET', params=params)
+        return _ReportLogListAdapter.validate_json(r.text)
+
+    def get_report_log(self, log: str) -> ReportLog:
+        """
+        Get a specific report log entry.
+        """
+        r = self._client.request(
+            f'{self._path}/logs/{log}', 'GET')
+        return ReportLog.model_validate_json(r.text)
+
+    def create_report_revision(self, revision_date: datetime,
+                               description: str,
+                               project: Optional[str],
+                               source_code: BinaryIO) -> ReportSourceCodeRevision:
+        """
+        Create a new report source code revision.
+
+        A report should be a python file that defines a function called `generate_report`
+        that takes two arguments: `request` and `context`, and returns an object with
+        `filename`, `mime_type`, and `data` attributes. It can also be a package with __init__.py
+        defining the `generate_report` function.
+
+        You can use the `mercuto_client.modules.reports.ReportHandler` protocol
+        to type hint your report function. Example:
+        ```python
+        from mercuto_client.modules.reports import ReportHandler, HandlerRequest, HandlerContext, ReportHandlerResult
+        def generate_report(request: HandlerRequest, context: HandlerContext) -> ReportHandlerResult:
+            # Your report generation logic here
+            return ReportHandlerResult(
+                filename="report.pdf",
+                mime_type="application/pdf",
+                data=b"PDF binary data here"
+            )
+        ```
+        The request parameter contains information about the report generation request,
+        and the context parameter provides access to the Mercuto client and metadata about
+        the report being generated. The MercutoClient provided in the context can be used
+        to fetch any additional data required for the report. It will be authenticated
+        using a service token with VIEW_PROJECT permission and VIEW_TENANT permission.
+
+        Params:
+            project (str): The project code.
+            revision_date (datetime): The date of the revision.
+            description (str): A description of the revision.
+            source_code (io.BinaryIO): The report source code file, either a .py file or a .zip package.
+
+        """
+        # Create the revision metadata
+        json: PayloadType = {
+            'revision_date': revision_date.isoformat(),
+            'description': description,
+        }
+        if project is not None:
+            json['project'] = project
+        r = self._client.request(f'{self._path}/revisions', 'PUT', json=json)
+        revision = ReportSourceCodeRevision.model_validate_json(r.text)
+
+        # Upload the source code
+        r = self._client.request(
+            f'{self._path}/revisions/{revision.code}', 'PATCH')
+        upload_url = r.json()['target_source_code_url']
+        upload_url = self._client.session().put(upload_url,
+                                                data=source_code, verify=self._client.verify_ssl)
+        if not upload_url.ok:
+            raise MercutoHTTPException(
+                f"Failed to upload report source code: {upload_url.status_code} {upload_url.text}",
+                upload_url.status_code
+            )
+        return revision

mercuto_client/util.py

@@ -53,7 +53,7 @@ def get_free_space_excluding_files(directory: str) -> int:
     :return: Free bytes available in the partition after subtracting file sizes.
     """
     # Get partition's free space
-    total, used, free = shutil.disk_usage(directory)
+    _, _, free = shutil.disk_usage(directory)
 
     # Calculate the total size of files in the directory
     files_size = get_directory_size(directory)

{mercuto_client-0.3.0.dist-info → mercuto_client-0.3.4a3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mercuto-client
-Version: 0.3.0
+Version: 0.3.4a3
 Summary: Library for interfacing with Rockfield's Mercuto API
 Author-email: Daniel Whipp <daniel.whipp@rocktech.com.au>
 License-Expression: AGPL-3.0-only