arcsecond 3.7.3__tar.gz → 3.8.0__tar.gz

{arcsecond-3.7.3 → arcsecond-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcsecond
-Version: 3.7.3
+Version: 3.8.0
 Summary: CLI for arcsecond.io
 Project-URL: Homepage, https://github.com/arcsecond-io/cli
 Project-URL: Issues, https://github.com/arcsecond-io/cli/issues
@@ -36,10 +36,12 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.9
 Requires-Dist: click>=8
 Requires-Dist: configparser
 Requires-Dist: docker
 Requires-Dist: httpx
+Requires-Dist: opencv-python-headless<5,>=4.10
 Requires-Dist: py-machineid
 Requires-Dist: tqdm<5.0.0,>=4.67.1
 Requires-Dist: wait-for-it

{arcsecond-3.7.3 → arcsecond-3.8.0}/arcsecond/__init__.py

@@ -1,4 +1,9 @@
-from .api import ArcsecondAPI, ArcsecondAPIEndpoint, ArcsecondConfig
+from .api import (
+    ArcsecondAPI,
+    ArcsecondAPIEndpoint,
+    ArcsecondConfig,
+    ArcsecondTargetListsResource,
+)
 from .cloud.uploader import (
     AllSkyCameraImageFileUploader,
     AllSkyCameraImageUploadContext,
@@ -7,6 +12,7 @@ from .cloud.uploader import (
 )
 from .cloud.uploader.walker import walk_folder_and_upload_files
 from .errors import ArcsecondError
+from .targets import ArcsecondTargetPayloadPlan, plan_target_payload
 
 name = "arcsecond"
 
@@ -15,9 +21,12 @@ __all__ = [
     "ArcsecondError",
     "ArcsecondConfig",
     "ArcsecondAPIEndpoint",
+    "ArcsecondTargetListsResource",
+    "ArcsecondTargetPayloadPlan",
     "DatasetUploadContext",
     "DatasetFileUploader",
     "AllSkyCameraImageFileUploader",
     "AllSkyCameraImageUploadContext",
+    "plan_target_payload",
     "walk_folder_and_upload_files",
 ]

arcsecond-3.8.0/arcsecond/api/__init__.py

@@ -0,0 +1,11 @@
+from .config import ArcsecondConfig
+from .endpoint import ArcsecondAPIEndpoint
+from .main import ArcsecondAPI
+from .resources import ArcsecondTargetListsResource
+
+__all__ = [
+    "ArcsecondAPI",
+    "ArcsecondConfig",
+    "ArcsecondAPIEndpoint",
+    "ArcsecondTargetListsResource",
+]

{arcsecond-3.7.3 → arcsecond-3.8.0}/arcsecond/api/endpoint.py

@@ -12,6 +12,13 @@ WRITABLE_MEMBERSHIPS = ["superadmin", "admin", "member"]
 
 
 class ArcsecondAPIEndpoint(object):
+    """
+    Generic REST endpoint wrapper for Arcsecond resources.
+
+    It owns transport-level CRUD plus resource-agnostic conveniences such as
+    payload merging, `find_one()`, and `upsert()`.
+    """
+
     def __init__(
         self,
         config: ArcsecondConfig,
@@ -57,6 +64,30 @@ class ArcsecondAPIEndpoint(object):
     def _detail_url(self, uuid_or_id):
         return self._build_url(self.__path, str(uuid_or_id))
 
+    def _build_payload(self, json=None, **fields):
+        payload = {}
+        if json:
+            payload.update(json)
+        payload.update({key: value for key, value in fields.items() if value is not None})
+        return payload or None
+
+    def _extract_results(self, response):
+        if isinstance(response, dict):
+            if isinstance(response.get("results"), list):
+                return response["results"]
+            if response:
+                return [response]
+        elif isinstance(response, list):
+            return response
+        return []
+
+    def _extract_identifier(self, resource, identifier_fields=("uuid", "id", "pk")):
+        for key in identifier_fields:
+            value = resource.get(key)
+            if value is not None:
+                return value
+        return None
+
     def list(self, **filters):
         return self._perform_request(self._list_url(**filters), "get")
 
@@ -65,16 +96,20 @@ class ArcsecondAPIEndpoint(object):
             self._detail_url(id_name_uuid), "get", headers=headers
         )
 
-    def create(self, json=None, files=None, headers=None):
+    def create(self, json=None, files=None, headers=None, **fields):
         return self._perform_request(
-            self._list_url(), "post", json=json, files=files, headers=headers
+            self._list_url(),
+            "post",
+            json=self._build_payload(json=json, **fields),
+            files=files,
+            headers=headers,
         )
 
-    def update(self, id_name_uuid, json=None, files=None, headers=None):
+    def update(self, id_name_uuid, json=None, files=None, headers=None, **fields):
         return self._perform_request(
             self._detail_url(id_name_uuid),
             "patch",
-            json=json,
+            json=self._build_payload(json=json, **fields),
             files=files,
             headers=headers,
         )
@@ -82,6 +117,44 @@ class ArcsecondAPIEndpoint(object):
     def delete(self, id_name_uuid):
         return self._perform_request(self._detail_url(id_name_uuid), "delete")
 
+    def find_one(self, **filters):
+        response, error = self.list(**filters)
+        if error:
+            return None, error
+
+        results = self._extract_results(response)
+        if len(results) == 0:
+            return None, None
+        if len(results) > 1:
+            return (
+                None,
+                ArcsecondError(
+                    f"Expected one '{self.path}' match for filters {filters}, got {len(results)}."
+                ),
+            )
+        return results[0], None
+
+    def upsert(self, match_field="name", json=None, **fields):
+        payload = self._build_payload(json=json, **fields)
+        if payload is None:
+            return None, ArcsecondError("Cannot upsert an empty payload.")
+
+        match_value = payload.get(match_field)
+        if match_value in (None, ""):
+            return self.create(json=payload)
+
+        existing, error = self.find_one(**{match_field: match_value})
+        if error:
+            return None, error
+        if existing is None:
+            return self.create(json=payload)
+
+        identifier = self._extract_identifier(existing)
+        if identifier is None:
+            return None, ArcsecondError(f"Could not find an identifier for '{match_value}'.")
+
+        return self.update(identifier, json=payload)
+
     def _perform_request(self, url, method_name, json=None, files=None, headers=None):
         if self.__config.verbose:
             click.echo(f"Sending {method_name} request to {url}")

{arcsecond-3.7.3 → arcsecond-3.8.0}/arcsecond/api/main.py

@@ -8,6 +8,7 @@ from arcsecond.options import State
 from .config import ArcsecondConfig
 from .constants import API_AUTH_PATH_VERIFY
 from .endpoint import ArcsecondAPIEndpoint
+from .resources import ArcsecondTargetListsResource
 
 __all__ = [
     "ArcsecondAPI",
@@ -40,6 +41,10 @@ class ArcsecondAPI(object):
         self.calibrations = ArcsecondAPIEndpoint(
             self.config, "calibrations", self.subdomain
         )
+        self.targets = ArcsecondAPIEndpoint(self.config, "targets", self.subdomain)
+        self.targetlists = ArcsecondTargetListsResource(
+            self.config, "targetlists", self.subdomain
+        )
 
         self.datapackages = ArcsecondAPIEndpoint(
             self.config, "datapackages", self.subdomain

arcsecond-3.8.0/arcsecond/api/resources.py

@@ -0,0 +1,114 @@
+from arcsecond.errors import ArcsecondError
+
+from .endpoint import ArcsecondAPIEndpoint
+
+
+class ArcsecondTargetListsResource(ArcsecondAPIEndpoint):
+    """Target-list specific helpers built on top of the generic endpoint contract."""
+
+    target_relation_keys = ("targets", "target_uuids", "target_ids")
+
+    def _ensure_iterable(self, values):
+        if values is None:
+            return None
+        if isinstance(values, (str, int)):
+            return [values]
+        return list(values)
+
+    def _normalise_target_references(self, targets):
+        values = self._ensure_iterable(targets)
+        if values is None:
+            return None
+
+        refs = []
+        for target in values:
+            if isinstance(target, dict):
+                ref = (
+                    target.get("uuid")
+                    or target.get("id")
+                    or target.get("pk")
+                    or target.get("name")
+                )
+                if ref is None:
+                    raise ArcsecondError(
+                        "Target dictionaries must include one of: uuid, id, pk or name."
+                    )
+                refs.append(ref)
+            else:
+                refs.append(target)
+        return refs
+
+    def _target_key_from_payload(self, payload, target_key=None):
+        if target_key:
+            return target_key
+        for key in self.target_relation_keys:
+            if payload and key in payload:
+                return key
+        return self.target_relation_keys[0]
+
+    def _build_payload(self, json=None, targets=None, target_key=None, **fields):
+        payload = super()._build_payload(json=json, **fields) or {}
+        normalised_targets = self._normalise_target_references(targets)
+        if normalised_targets is not None:
+            payload[self._target_key_from_payload(payload, target_key=target_key)] = (
+                normalised_targets
+            )
+        return payload or None
+
+    def create(self, json=None, targets=None, target_key=None, **fields):
+        payload = self._build_payload(
+            json=json, targets=targets, target_key=target_key, **fields
+        )
+        return ArcsecondAPIEndpoint.create(self, json=payload)
+
+    def update(self, id_name_uuid, json=None, targets=None, target_key=None, **fields):
+        payload = self._build_payload(
+            json=json, targets=targets, target_key=target_key, **fields
+        )
+        return ArcsecondAPIEndpoint.update(self, id_name_uuid, json=payload)
+
+    def upsert(self, match_field="name", json=None, targets=None, target_key=None, **fields):
+        payload = self._build_payload(
+            json=json, targets=targets, target_key=target_key, **fields
+        )
+        return super().upsert(match_field=match_field, json=payload)
+
+    def _read_target_refs(self, target_list, target_key=None):
+        key = self._target_key_from_payload(target_list or {}, target_key=target_key)
+        raw_targets = (target_list or {}).get(key, [])
+        refs = self._normalise_target_references(raw_targets) or []
+        return key, refs
+
+    def set_targets(self, id_name_uuid, targets, target_key=None):
+        target_key = self._target_key_from_payload({}, target_key=target_key)
+        return self.update(id_name_uuid, **{target_key: self._normalise_target_references(targets)})
+
+    def clear_targets(self, id_name_uuid, target_key=None):
+        return self.set_targets(id_name_uuid, [], target_key=target_key)
+
+    def add_targets(self, id_name_uuid, targets, target_key=None):
+        target_list, error = self.read(id_name_uuid)
+        if error:
+            return None, error
+
+        key, current_refs = self._read_target_refs(target_list, target_key=target_key)
+        for ref in self._normalise_target_references(targets) or []:
+            if ref not in current_refs:
+                current_refs.append(ref)
+        return self.update(id_name_uuid, **{key: current_refs})
+
+    def remove_targets(self, id_name_uuid, targets, target_key=None):
+        target_list, error = self.read(id_name_uuid)
+        if error:
+            return None, error
+
+        key, current_refs = self._read_target_refs(target_list, target_key=target_key)
+        refs_to_remove = set(self._normalise_target_references(targets) or [])
+        remaining_refs = [ref for ref in current_refs if ref not in refs_to_remove]
+        return self.update(id_name_uuid, **{key: remaining_refs})
+
+    def add_target(self, id_name_uuid, target, target_key=None):
+        return self.add_targets(id_name_uuid, [target], target_key=target_key)
+
+    def remove_target(self, id_name_uuid, target, target_key=None):
+        return self.remove_targets(id_name_uuid, [target], target_key=target_key)

{arcsecond-3.7.3 → arcsecond-3.8.0}/arcsecond/cli.py

@@ -10,6 +10,7 @@ from arcsecond.cloud import (
     upload_data,
 )
 from arcsecond.hosting import setup
+from arcsecond.webcam import commands as webcam
 
 from . import __version__
 from .options import State
@@ -59,3 +60,6 @@ main.add_command(upload_data)
 
 # Allow to try arcsecond by installing a local version
 main.add_command(setup)
+
+# Native webcam proxy — lets Docker containers reach USB webcams on the host.
+main.add_command(webcam.webcam)

{arcsecond-3.7.3 → arcsecond-3.8.0}/arcsecond/hosting/docker/docker-compose.yml

@@ -35,6 +35,12 @@ services:
     depends_on:
       - db
       - broker
+    # Allows the backend to reach the host machine via host.docker.internal.
+    # Required on Linux; Docker Desktop on Windows/macOS adds this automatically.
+    # Used by the webcam proxy: set WEBCAM_PROXY_URL=http://host.docker.internal:8765
+    # in your .env file and run `arcsecond webcam start` on the host.
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     env_file:
       # You must have a .env file with secret keys beside this yml file.
       - .env

arcsecond-3.8.0/arcsecond/targets.py

@@ -0,0 +1,211 @@
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional
+
+
+TARGET_CLASS_ASTRONOMICAL_OBJECT = "AstronomicalObject"
+TARGET_CLASS_EXOPLANET = "Exoplanet"
+TARGET_CLASS_STANDARD_STAR = "StandardStar"
+TARGET_CLASS_SOLAR_SYSTEM_PLANET = "SolarSystemPlanet"
+TARGET_CLASS_SMALL_BODY = "SmallBody"
+TARGET_CLASS_MICROLENSING = "Microlensing"
+TARGET_CLASS_TRANSIENT = "Transient"
+
+TARGET_CLASSES = {
+    TARGET_CLASS_ASTRONOMICAL_OBJECT,
+    TARGET_CLASS_EXOPLANET,
+    TARGET_CLASS_STANDARD_STAR,
+    TARGET_CLASS_SOLAR_SYSTEM_PLANET,
+    TARGET_CLASS_SMALL_BODY,
+    TARGET_CLASS_MICROLENSING,
+    TARGET_CLASS_TRANSIENT,
+}
+
+TARGET_MODE_MANUAL = "manual"
+
+TARGET_CLASSES_REQUIRING_NAME = {
+    TARGET_CLASS_ASTRONOMICAL_OBJECT,
+    TARGET_CLASS_EXOPLANET,
+    TARGET_CLASS_STANDARD_STAR,
+    TARGET_CLASS_SOLAR_SYSTEM_PLANET,
+}
+
+TARGET_CLASSES_REQUIRING_IDENTIFIER = {
+    TARGET_CLASS_SMALL_BODY,
+    TARGET_CLASS_MICROLENSING,
+    TARGET_CLASS_TRANSIENT,
+}
+
+
+@dataclass(frozen=True)
+class ArcsecondTargetPayloadPlan:
+    payload: dict[str, Any]
+    target_class: Optional[str]
+    mode: str
+    target_class_source: Optional[str]
+    coordinates_source: Optional[str]
+    warnings: tuple[str, ...] = field(default_factory=tuple)
+    errors: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def is_valid(self) -> bool:
+        return len(self.errors) == 0
+
+
+def _clean_string(value: Optional[str]) -> str:
+    return (value or "").strip()
+
+
+def _normalise_coordinates(coordinates: Optional[Mapping[str, Any]]) -> Optional[dict[str, Any]]:
+    if coordinates is None:
+        return None
+    return {
+        key: value
+        for key, value in dict(coordinates).items()
+        if value is not None
+    }
+
+
+def _validate_target_class(target_class: str, label: str, errors: list[str]) -> None:
+    if target_class and target_class not in TARGET_CLASSES:
+        errors.append(f"{label} '{target_class}' is not a supported Arcsecond target class.")
+
+
+def plan_target_payload(
+    *,
+    name: Optional[str] = None,
+    identifier: Optional[str] = None,
+    target_class: Optional[str] = None,
+    coordinates: Optional[Mapping[str, Any]] = None,
+    inferred_name: Optional[str] = None,
+    inferred_identifier: Optional[str] = None,
+    inferred_target_class: Optional[str] = None,
+    color: Optional[str] = None,
+    notes: Optional[str] = None,
+    profile: Optional[str] = None,
+    organisation: Optional[str] = None,
+    extra_fields: Optional[Mapping[str, Any]] = None,
+) -> ArcsecondTargetPayloadPlan:
+    """
+    Build a backend-compatible target payload while preserving the rule:
+    user-provided values override inferred ones.
+
+    This helper is pure: it does not perform network lookups or create/update targets.
+    It simply turns user input plus optional inferred metadata into a target payload,
+    warnings, and validation errors so callers can inspect the plan before applying it.
+    """
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    user_name = _clean_string(name)
+    user_identifier = _clean_string(identifier)
+    user_target_class = _clean_string(target_class)
+
+    inferred_name = _clean_string(inferred_name)
+    inferred_identifier = _clean_string(inferred_identifier)
+    inferred_target_class = _clean_string(inferred_target_class)
+
+    _validate_target_class(user_target_class, "target_class", errors)
+    _validate_target_class(inferred_target_class, "inferred_target_class", errors)
+
+    effective_name = user_name or inferred_name
+    effective_identifier = user_identifier or inferred_identifier
+    effective_coordinates = _normalise_coordinates(coordinates)
+
+    if not effective_name and not effective_identifier:
+        errors.append("One of name or identifier must be provided.")
+
+    if user_target_class and inferred_target_class and user_target_class != inferred_target_class:
+        warnings.append(
+            f"User-provided target_class '{user_target_class}' overrides inferred target_class '{inferred_target_class}'."
+        )
+
+    payload: dict[str, Any] = {}
+    if effective_name:
+        payload["name"] = effective_name
+    if effective_identifier:
+        payload["identifier"] = effective_identifier
+    for key, value in {
+        "color": color,
+        "notes": notes,
+        "profile": profile,
+        "organisation": organisation,
+    }.items():
+        if value is not None:
+            payload[key] = value
+    if extra_fields:
+        payload.update({key: value for key, value in dict(extra_fields).items() if value is not None})
+
+    if effective_coordinates is not None:
+        if user_target_class and user_target_class != TARGET_CLASS_ASTRONOMICAL_OBJECT:
+            errors.append(
+                "Manual coordinates are currently supported only for 'AstronomicalObject'. "
+                f"Received target_class '{user_target_class}'."
+            )
+
+        effective_target_class = user_target_class or TARGET_CLASS_ASTRONOMICAL_OBJECT
+        target_class_source = "user" if user_target_class else "default"
+        coordinates_source = "user"
+
+        if inferred_target_class and not user_target_class and inferred_target_class != TARGET_CLASS_ASTRONOMICAL_OBJECT:
+            warnings.append(
+                f"Inferred target_class '{inferred_target_class}' is ignored because user-provided coordinates "
+                "require a manual 'AstronomicalObject' payload with the current backend."
+            )
+
+        if not effective_name:
+            errors.append("Manual coordinates require a target name.")
+
+        payload["target_class"] = effective_target_class
+        payload["mode"] = TARGET_MODE_MANUAL
+        payload["object"] = {
+            "name": effective_name or effective_identifier,
+            "equatorial_coordinates": effective_coordinates,
+        }
+
+        return ArcsecondTargetPayloadPlan(
+            payload=payload,
+            target_class=effective_target_class or None,
+            mode=TARGET_MODE_MANUAL,
+            target_class_source=target_class_source,
+            coordinates_source=coordinates_source,
+            warnings=tuple(warnings),
+            errors=tuple(errors),
+        )
+
+    effective_target_class = user_target_class or inferred_target_class
+    target_class_source = None
+    if user_target_class:
+        target_class_source = "user"
+    elif inferred_target_class:
+        target_class_source = "inferred"
+
+    if not effective_target_class:
+        errors.append(
+            "target_class could not be determined. Provide target_class explicitly, provide coordinates, "
+            "or infer the class before creating/updating the target."
+        )
+    else:
+        payload["target_class"] = effective_target_class
+
+        if effective_target_class in TARGET_CLASSES_REQUIRING_NAME and not effective_name:
+            errors.append(f"Target class '{effective_target_class}' requires a name.")
+
+        if effective_target_class in TARGET_CLASSES_REQUIRING_IDENTIFIER and not effective_identifier:
+            errors.append(f"Target class '{effective_target_class}' requires an identifier.")
+
+    if effective_target_class and "object" not in payload:
+        warnings.append(
+            "This payload does not contain manual coordinates. Target creation will rely on the backend "
+            "to resolve the object from name/identifier and target_class."
+        )
+
+    return ArcsecondTargetPayloadPlan(
+        payload=payload,
+        target_class=effective_target_class or None,
+        mode="",
+        target_class_source=target_class_source,
+        coordinates_source=None,
+        warnings=tuple(warnings),
+        errors=tuple(errors),
+    )

arcsecond-3.8.0/arcsecond/webcam/commands.py

@@ -0,0 +1,101 @@
+"""
+Click command group: ``arcsecond webcam``
+
+Sub-commands
+------------
+detect      Scan for attached webcams and print a summary table.
+start       Start the native webcam proxy server so Docker containers can
+            reach USB webcams on this host via host.docker.internal.
+"""
+
+import json
+import logging
+
+import click
+
+logger = logging.getLogger(__name__)
+
+
+@click.group(help="Manage the native webcam proxy for Docker containers.")
+def webcam():
+    pass
+
+
+@webcam.command(name='detect', help="Scan for locally attached webcams and print their details.")
+def detect_cmd():
+    try:
+        import cv2  # noqa: F401
+    except ImportError:
+        click.echo(
+            click.style("Error: ", fg='red') +
+            "opencv-python-headless is not installed.\n"
+            "Run:  pip install opencv-python-headless"
+        )
+        raise SystemExit(1)
+
+    from arcsecond.webcam.proxy import _detect_webcams_sync
+    webcams = _detect_webcams_sync()
+
+    if not webcams:
+        click.echo("No webcams detected.")
+        return
+
+    click.echo(f"Found {len(webcams)} webcam(s):\n")
+    for w in webcams:
+        click.echo(
+            f"  index={w.index}  {w.width}×{w.height}  {w.fps:.1f} fps"
+        )
+
+
+@webcam.command(name='start', help=(
+    "Start the webcam proxy server.\n\n"
+    "The proxy exposes two endpoints that the Arcsecond backend container can "
+    "reach via host.docker.internal:\n\n"
+    "  GET  /detect              — list attached webcams (JSON)\n\n"
+    "  WS   /stream/{index}      — JPEG frame stream\n\n"
+    "Set WEBCAM_PROXY_URL=http://host.docker.internal:<PORT> in your .env file "
+    "so the backend knows where to find the proxy."
+))
+@click.option('--port', default=8765, show_default=True, help="TCP port to listen on.")
+@click.option('--host', default='0.0.0.0', show_default=True, help="Interface to bind.")
+@click.option('--log-level', default='INFO', show_default=True,
+              type=click.Choice(['DEBUG', 'INFO', 'WARNING', 'ERROR'], case_sensitive=False),
+              help="Logging verbosity.")
+def start_cmd(port, host, log_level):
+    try:
+        import aiohttp  # noqa: F401
+    except ImportError:
+        click.echo(
+            click.style("Error: ", fg='red') +
+            "aiohttp is not installed.\n"
+            "Run:  pip install aiohttp"
+        )
+        raise SystemExit(1)
+
+    try:
+        import cv2  # noqa: F401
+    except ImportError:
+        click.echo(
+            click.style("Error: ", fg='red') +
+            "opencv-python-headless is not installed.\n"
+            "Run:  pip install opencv-python-headless"
+        )
+        raise SystemExit(1)
+
+    logging.basicConfig(
+        level=getattr(logging, log_level.upper()),
+        format='%(asctime)s  %(levelname)-8s  %(name)s  %(message)s',
+    )
+
+    click.echo(
+        click.style("Arcsecond webcam proxy", bold=True) +
+        f" listening on {host}:{port}\n"
+        f"  Detection  →  http://{host}:{port}/detect\n"
+        f"  Streaming  →  ws://{host}:{port}/stream/{{index}}\n\n"
+        "Set in your .env file:\n"
+        f"  WEBCAM_PROXY_URL=http://host.docker.internal:{port}\n\n"
+        "Press Ctrl-C to stop."
+    )
+
+    from arcsecond.webcam.proxy import run
+    run(host=host, port=port)