arcsecond 3.8.0__tar.gz → 3.9.0__tar.gz

arcsecond-3.9.0/.github/workflows/docsdeploy.yml

@@ -0,0 +1,28 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+    - name: Setup node
+      uses: actions/setup-node@v5
+      with:
+        node-version: '24'
+        cache: 'npm'
+    - run: npm ci
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.READ_PACKAGE_TOKEN }}
+        CI: true
+    - name: Deploy docs
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: ./deploy.sh

{arcsecond-3.8.0 → arcsecond-3.9.0}/.github/workflows/pythonpublish.yml

@@ -22,7 +22,7 @@ jobs:
             exit 1
           fi
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Validate pyproject.toml version matches tag
         run: |
@@ -41,7 +41,7 @@ jobs:
           PY
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 
@@ -54,4 +54,4 @@ jobs:
       - name: Publish to PyPI (OIDC)
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          packages-dir: dist
+          packages-dir: dist

{arcsecond-3.8.0 → arcsecond-3.9.0}/.github/workflows/tests.yml

@@ -14,10 +14,10 @@ jobs:
         python-version: [ '3.10', '3.11', '3.12', '3.13' ]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -39,7 +39,7 @@ jobs:
 
       - name: Upload coverage artifact (only on 3.12)
         if: matrix.python-version == '3.12'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: coverage
           path: coverage.xml
@@ -49,10 +49,10 @@ jobs:
     needs: tests
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Download coverage artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           name: coverage
           path: .
@@ -65,10 +65,10 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 
@@ -87,4 +87,4 @@ jobs:
 
       - name: Check imports with isort
         run: |
-          isort --check-only --profile black arcsecond tests
+          isort --check-only --profile black arcsecond tests

{arcsecond-3.8.0 → arcsecond-3.9.0}/.gitignore

@@ -20,3 +20,4 @@ node_modules
 
 /coverage.xml
 .env
+.claude

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcsecond
-Version: 3.8.0
+Version: 3.9.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,15 +36,16 @@ 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
+Provides-Extra: webcam
+Requires-Dist: aiohttp>=3.9; extra == 'webcam'
+Requires-Dist: opencv-python-headless<5,>=4.10; extra == 'webcam'
 Description-Content-Type: text/markdown
 
 [![Deploy Docs](https://github.com/arcsecond-io/cli/actions/workflows/docsdeploy.yml/badge.svg)](https://github.com/arcsecond-io/cli/actions/workflows/docsdeploy.yml) [![Downloads](http://pepy.tech/badge/arcsecond)](http://pepy.tech/project/arcsecond)

{arcsecond-3.8.0 → arcsecond-3.9.0}/arcsecond/api/resources.py

@@ -6,53 +6,76 @@ 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")
+    target_relation_key = "targets"
+    target_writable_fields = (
+        "id",
+        "pk",
+        "object",
+        "name",
+        "identifier",
+        "target_class",
+        "mode",
+        "color",
+        "notes",
+        "tags",
+        "profile",
+        "organisation",
+    )
 
     def _ensure_iterable(self, values):
         if values is None:
             return None
+        if isinstance(values, dict):
+            return [values]
         if isinstance(values, (str, int)):
             return [values]
         return list(values)
 
-    def _normalise_target_references(self, targets):
+    def _target_payload_identity(self, target):
+        if target.get("id") is not None:
+            return ("id", target["id"])
+        if target.get("pk") is not None:
+            return ("pk", target["pk"])
+        return (
+            "composite",
+            target.get("target_class"),
+            target.get("identifier"),
+            target.get("name"),
+            target.get("mode"),
+        )
+
+    def _normalise_target_payloads(self, targets):
         values = self._ensure_iterable(targets)
         if values is None:
             return None
 
-        refs = []
+        payloads = []
         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 not isinstance(target, dict):
+                raise ArcsecondError(
+                    "Target list helpers expect target payload dictionaries, not scalar IDs or UUIDs. "
+                    "Pass dictionaries such as `plan_target_payload(...).payload` or target objects returned "
+                    "by `api.targets.read()/list()/upsert()`."
                 )
-                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]
+
+            payload = {
+                key: value
+                for key, value in target.items()
+                if key in self.target_writable_fields and value is not None
+            }
+            if not payload:
+                raise ArcsecondError(
+                    "Target dictionaries must include at least one writable target field."
+                )
+
+            payloads.append(payload)
+        return payloads
 
     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)
+        normalised_targets = self._normalise_target_payloads(targets)
         if normalised_targets is not None:
-            payload[self._target_key_from_payload(payload, target_key=target_key)] = (
-                normalised_targets
-            )
+            payload[target_key or self.target_relation_key] = normalised_targets
         return payload or None
 
     def create(self, json=None, targets=None, target_key=None, **fields):
@@ -74,14 +97,14 @@ class ArcsecondTargetListsResource(ArcsecondAPIEndpoint):
         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)
+        key = target_key or self.target_relation_key
         raw_targets = (target_list or {}).get(key, [])
-        refs = self._normalise_target_references(raw_targets) or []
+        refs = self._normalise_target_payloads(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)})
+        target_key = target_key or self.target_relation_key
+        return self.update(id_name_uuid, **{target_key: self._normalise_target_payloads(targets)})
 
     def clear_targets(self, id_name_uuid, target_key=None):
         return self.set_targets(id_name_uuid, [], target_key=target_key)
@@ -92,9 +115,14 @@ class ArcsecondTargetListsResource(ArcsecondAPIEndpoint):
             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)
+        current_identities = {
+            self._target_payload_identity(target): target for target in current_refs
+        }
+        for target in self._normalise_target_payloads(targets) or []:
+            identity = self._target_payload_identity(target)
+            if identity not in current_identities:
+                current_refs.append(target)
+                current_identities[identity] = target
         return self.update(id_name_uuid, **{key: current_refs})
 
     def remove_targets(self, id_name_uuid, targets, target_key=None):
@@ -103,8 +131,15 @@ class ArcsecondTargetListsResource(ArcsecondAPIEndpoint):
             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]
+        refs_to_remove = {
+            self._target_payload_identity(target)
+            for target in (self._normalise_target_payloads(targets) or [])
+        }
+        remaining_refs = [
+            ref
+            for ref in current_refs
+            if self._target_payload_identity(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):

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

@@ -37,8 +37,6 @@ services:
       - 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:

{arcsecond-3.8.0 → arcsecond-3.9.0}/arcsecond/hosting/local.py

@@ -125,12 +125,8 @@ def write_docker_compose_file() -> Path:
         print("docker-compose.yml is already up to date.")
         return dest
 
-    latest_dest = Path.cwd() / "docker-compose.latest.yml"
-    latest_dest.write_bytes(expected_content)
-    print(
-        "docker-compose.yml differs from the latest packaged version. "
-        f"Wrote new template to: {latest_dest}"
-    )
+    dest.write_bytes(expected_content)
+    print("docker-compose.yml has been updated to the latest version.")
     return dest
 
 

{arcsecond-3.8.0 → arcsecond-3.9.0}/arcsecond/webcam/proxy.py

@@ -68,10 +68,16 @@ def _detect_webcams_sync(max_index: int = _MAX_PROBE) -> list[WebcamInfo]:
 # aiohttp request handlers
 # ---------------------------------------------------------------------------
 
+async def handle_health(request):
+    """GET /health — simple liveness check."""
+    from aiohttp import web
+    return web.json_response({'status': 'ok'})
+
+
 async def handle_detect(request):
     """GET /detect — return JSON list of attached webcams."""
     from aiohttp import web
-    loop = asyncio.get_event_loop()
+    loop = asyncio.get_running_loop()
     webcams = await loop.run_in_executor(None, _detect_webcams_sync)
     return web.json_response([asdict(w) for w in webcams])
 
@@ -86,7 +92,7 @@ async def handle_stream(request):
     await ws.prepare(request)
     logger.info("Webcam proxy: client connected to stream for device index %d", index)
 
-    loop = asyncio.get_event_loop()
+    loop = asyncio.get_running_loop()
     cap: cv2.VideoCapture = await loop.run_in_executor(None, cv2.VideoCapture, index)
 
     if not await loop.run_in_executor(None, cap.isOpened):
@@ -109,9 +115,12 @@ async def handle_stream(request):
             b64 = await loop.run_in_executor(None, _read_and_encode)
             if b64 is None:
                 logger.warning("Webcam proxy: cap.read() failed for device %d, stopping.", index)
+                await ws.send_str(json.dumps({'type': 'error', 'message': f'Device lost at index {index}.'}))
                 break
             await ws.send_str(json.dumps({'type': 'frame', 'format': 'jpeg/base64', 'data': b64}))
             await asyncio.sleep(_FRAME_INTERVAL)
+    except (ConnectionResetError, ConnectionError):
+        logger.info("Webcam proxy: client disconnected from device %d.", index)
     finally:
         await loop.run_in_executor(None, cap.release)
         logger.info("Webcam proxy: device %d released.", index)
@@ -128,6 +137,7 @@ def run(host: str = '0.0.0.0', port: int = 8765):
     from aiohttp import web
 
     app = web.Application()
+    app.router.add_get('/health', handle_health)
     app.router.add_get('/detect', handle_detect)
     app.router.add_get('/stream/{index}', handle_stream)
 

{arcsecond-3.8.0 → arcsecond-3.9.0}/docs/.vitepress/config.js

@@ -2,16 +2,28 @@ module.exports = {
   title: 'Arcsecond CLI',
   description: 'The command-line / Python module of Arcsecond.',
   base: '/cli/',
+  cleanUrls: true,
   themeConfig: {
     nav: [
-      { text: 'Home', link: '/' },
       { text: 'Arcsecond Docs', link: 'https://docs.arcsecond.io' }
     ],
     sidebar: [
       {
-        text: 'Guide',
+        text: 'Getting Started',
+        items: [
+          { text: 'Install & Login', link: '/install' },
+          { text: 'Data Upload', link: '/upload' }
+        ]
+      },
+      {
+        text: 'Self-Hosting',
+        items: [
+          { text: 'Webcam Proxy', link: '/webcam' }
+        ]
+      },
+      {
+        text: 'Python API',
         items: [
-          { text: 'Install', link: '/install' },
           { text: 'API Basics', link: '/api-basics' },
           { text: 'Resources', link: '/resources' }
         ]

arcsecond-3.9.0/docs/.vitepress/theme/custom.css

@@ -0,0 +1,35 @@
+:root {
+  --vp-c-brand-1: #081c4d;
+  --vp-c-brand-2: #0b2462;
+  --vp-c-brand-3: #0e2d77;
+  --vp-c-brand-soft: rgba(8, 28, 77, 0.14);
+}
+
+.dark {
+  --vp-c-brand-1: #6ba6dc;
+  --vp-c-brand-2: #82b4e3;
+  --vp-c-brand-3: #528fc8;
+  --vp-c-brand-soft: rgba(107, 166, 220, 0.18);
+}
+
+.VPHomeHero .image-container {
+  width: 220px;
+  height: 220px;
+}
+
+.VPHomeHero .image-src {
+  max-width: 120px;
+  max-height: 120px;
+}
+
+@media (min-width: 640px) {
+  .VPHomeHero .image-container {
+    width: 260px;
+    height: 260px;
+  }
+
+  .VPHomeHero .image-src {
+    max-width: 120px;
+    max-height: 120px;
+  }
+}

{arcsecond-3.8.0 → arcsecond-3.9.0}/docs/api-basics.md

@@ -25,7 +25,7 @@ api = ArcsecondAPI(config, subdomain="my-observatory")
 
 Authentication with the Python module currently relies on your Arcsecond keys.
 
-### With the CLI
+### Reuse CLI credentials
 
 Login once from the command line:
 
@@ -33,18 +33,19 @@ Login once from the command line:
 arcsecond login
 ```
 
-This stores your credentials locally in `~/.config/arcsecond/config.ini`.
+This stores your credentials locally in `~/.config/arcsecond/config.ini`, which
+`ArcsecondConfig()` will load automatically.
 
 To skip prompts:
 
 ```bash
-arcsecond login --username <username> --access_key <key>
+arcsecond login --username <username> --type access --key <access-key>
 ```
 
 or:
 
 ```bash
-arcsecond login --username <username> --upload_key <key>
+arcsecond login --username <username> --type upload --key <upload-key>
 ```
 
 Once that is done, Python code can reuse the stored configuration:
@@ -56,7 +57,7 @@ config = ArcsecondConfig()
 api = ArcsecondAPI(config)
 ```
 
-### In Python Code
+### Authenticate in Python code
 
 You can also authenticate directly in Python code:
 
@@ -89,3 +90,8 @@ backend or local automation contexts, never in browser-side code.
 
 For Python scripts that only need to upload data, prefer an Upload Key. For broader
 resource management, use an Access Key.
+
+## Next Step
+
+Once authenticated, move to [Resources](/resources) for the generic CRUD helpers,
+target planning utilities, and target list management helpers.

arcsecond-3.9.0/docs/index.md

@@ -0,0 +1,36 @@
+---
+layout: home
+title: Arcsecond CLI
+description: Arcsecond CLI
+hero:
+  name: Arcsecond CLI
+  tagline: A lightweight command-line and Python client for Arcsecond resources, target workflows, and data uploads.
+  image:
+    src: /img/icon-logo.png
+    alt: Arcsecond CLI
+  actions:
+    - theme: brand
+      text: Install & Login
+      link: /install
+    - theme: alt
+      text: Python API
+      link: /api-basics
+    - theme: alt
+      text: Resources
+      link: /resources
+features:
+  - title: Lightweight CLI
+    details: Install the package, log in once, and use simple commands for resource access and uploads.
+  - title: Python API
+    details: Reuse the same credentials in code, work with generic CRUD endpoints, and plan target payloads safely.
+  - title: Data Upload
+    details: Upload datasets and all-sky camera images from the CLI or from Python automation.
+footer: MIT Licensed | Copyright © 2018-present Arcsecond.io (F52 Tech).
+---
+
+Arcsecond CLI gives you two entry points:
+
+- the `arcsecond` command-line tool for day-to-day operations
+- the `arcsecond` Python module for automation and integration
+
+Use the sidebar to move directly to installation, authentication, uploads, and the Python resource helpers.

arcsecond-3.9.0/docs/install.md

@@ -0,0 +1,78 @@
+---
+sidebar: true
+---
+
+# Install & Login
+
+Simply issue the following in a Terminal:
+
+```bash
+pip install arcsecond
+```
+
+To upgrade an existing Arcsecond installation:
+
+```bash
+pip install --upgrade arcsecond
+```
+
+The help is available like any other command-line tool:
+
+```bash
+arcsecond --help
+```
+
+For subcommands:
+
+```bash
+arcsecond <command> --help
+```
+
+The Arcsecond CLI works like a tool such as `git`: `arcsecond` is the main entry
+point, followed by a command. Many commands directly map to Arcsecond resources.
+
+## Authentication
+
+To use the CLI, you need an Arcsecond account. In your settings page on
+[arcsecond.io](https://www.arcsecond.io) you will find two kinds of credentials:
+
+- an Access Key for broad access to your resources
+- an Upload Key for upload-only workflows
+
+Use an Access Key only on trusted computers. If you only need to upload files,
+prefer an Upload Key.
+
+### Interactive login
+
+Run:
+
+```bash
+arcsecond login
+```
+
+The CLI will prompt for:
+
+- `username`
+- `type` (`access` or `upload`)
+- `key`
+
+Your credential is stored locally in `~/.config/arcsecond/config.ini`.
+
+### Non-interactive login
+
+To skip prompts, pass all values explicitly:
+
+```bash
+arcsecond login --username <username> --type access --key <access-key>
+```
+
+or:
+
+```bash
+arcsecond login --username <username> --type upload --key <upload-key>
+```
+
+Logging in again overwrites the stored credential if the login succeeds.
+
+If you think a key is compromised, regenerate it from your profile settings on
+[arcsecond.io](https://www.arcsecond.io). The CLI cannot regenerate keys for you.