arcsecond 3.20.2__tar.gz → 4.1.0__tar.gz

arcsecond-4.1.0/.gitattributes

@@ -0,0 +1,6 @@
+# The packaged compose template is compared byte for byte with what an
+# installation holds; a CRLF checkout on Windows would make every file look
+# customised. Markdown and YAML stay LF everywhere.
+*.yml text eol=lf
+*.yaml text eol=lf
+*.md text eol=lf

{arcsecond-3.20.2 → arcsecond-4.1.0}/.github/workflows/tests.yml

@@ -40,6 +40,28 @@ jobs:
           name: coverage
           path: coverage.xml
 
+  # The CLI's operators run it on Windows — the observatory PC — and until
+  # now nothing here ever executed it there. No Docker on this runner; this
+  # covers the pure-Python paths: path handling, the console, the registry
+  # backend of the proxy's login item, and every Windows branch in the suite.
+  tests-windows:
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.12'
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra webcam --group dev
+
+      - name: Test
+        run: uv run pytest -q tests/
+
   scan:
     runs-on: ubuntu-latest
     needs: tests

{arcsecond-3.20.2 → arcsecond-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arcsecond
-Version: 3.20.2
+Version: 4.1.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
@@ -40,12 +40,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Requires-Dist: alpyca==3.1.2
 Requires-Dist: click>=8
-Requires-Dist: configparser
-Requires-Dist: docker
 Requires-Dist: httpx
-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'
@@ -60,7 +56,40 @@ The Command-line interface (CLI) for Arcsecond. It can be used as Python
 module too. The CLI makes it easy to login/register and access Arcsecond resources,
 public and private ones.
 
-[Read the docs](https://docs.arcsecond.io/cli)
+[Read the docs](https://docs.arcsecond.io/reference/cli)
+
+## Running Arcsecond.local
+
+The CLI owns the whole lifecycle of a self-hosted installation; there is no
+`docker` command to type:
+
+```bash
+$ arcsecond setup --lan-host 192.168.1.42   # writes .env and docker-compose.yml
+$ arcsecond start                           # first run downloads the images
+$ arcsecond status
+$ arcsecond logs backend -f
+$ arcsecond restart backend worker          # after editing .env
+$ arcsecond update                          # newer images, refreshed compose file
+$ arcsecond stop
+```
+
+Every one of these finds the installation in the current folder, or in the
+folder `arcsecond setup` last ran in, or where `--dir` points.
+
+## Which server the CLI talks to
+
+The CLI points at one API server at a time — the cloud by default, or a
+server you registered, typically your own Arcsecond.local — and every command
+follows that pointer:
+
+```bash
+$ arcsecond api                     # list them, * marks the current one
+$ arcsecond api use local           # `setup` registered `local` for you
+$ arcsecond login                   # on that server
+```
+
+Credentials are kept per server. For a script or a cron job, `ARCSECOND_API=<name>`
+selects a server for that process alone, without moving the pointer.
 
 ## Configuration
 

{arcsecond-3.20.2 → arcsecond-4.1.0}/README.md

@@ -7,7 +7,40 @@ The Command-line interface (CLI) for Arcsecond. It can be used as Python
 module too. The CLI makes it easy to login/register and access Arcsecond resources,
 public and private ones.
 
-[Read the docs](https://docs.arcsecond.io/cli)
+[Read the docs](https://docs.arcsecond.io/reference/cli)
+
+## Running Arcsecond.local
+
+The CLI owns the whole lifecycle of a self-hosted installation; there is no
+`docker` command to type:
+
+```bash
+$ arcsecond setup --lan-host 192.168.1.42   # writes .env and docker-compose.yml
+$ arcsecond start                           # first run downloads the images
+$ arcsecond status
+$ arcsecond logs backend -f
+$ arcsecond restart backend worker          # after editing .env
+$ arcsecond update                          # newer images, refreshed compose file
+$ arcsecond stop
+```
+
+Every one of these finds the installation in the current folder, or in the
+folder `arcsecond setup` last ran in, or where `--dir` points.
+
+## Which server the CLI talks to
+
+The CLI points at one API server at a time — the cloud by default, or a
+server you registered, typically your own Arcsecond.local — and every command
+follows that pointer:
+
+```bash
+$ arcsecond api                     # list them, * marks the current one
+$ arcsecond api use local           # `setup` registered `local` for you
+$ arcsecond login                   # on that server
+```
+
+Credentials are kept per server. For a script or a cron job, `ARCSECOND_API=<name>`
+selects a server for that process alone, without moving the pointer.
 
 ## Configuration
 

{arcsecond-3.20.2 → arcsecond-4.1.0}/arcsecond/alpaca/dome_probe.py

@@ -17,8 +17,9 @@ from __future__ import annotations
 
 from typing import Any, Callable, Iterable
 
-from .probe import ProbeProgress, ProbeResult, probe_device
+from .probe import ProbeProgress, ProbeResult
 from .probe import iter_probe_labels as _iter_probe_labels
+from .probe import probe_device
 
 # Read-only device descriptors and dome state, in the order we want them
 # presented in the report. Names are PascalCase to match the alpyca surface.

{arcsecond-3.20.2 → arcsecond-4.1.0}/arcsecond/alpaca/telescope_probe.py

@@ -27,10 +27,12 @@ from .probe import (
     ProbeProgress,
     ProbeResult,
     capture,
+)
+from .probe import iter_probe_labels as _iter_probe_labels
+from .probe import (
     probe_device,
     record,
 )
-from .probe import iter_probe_labels as _iter_probe_labels
 
 # Read-only descriptors, optics, site, pointing, motion state and capabilities,
 # in the order we want them presented. Names are PascalCase to match alpyca.

{arcsecond-3.20.2 → arcsecond-4.1.0}/arcsecond/api/config.py

@@ -22,10 +22,31 @@ from .constants import ARCSECOND_API_URL_PROD
 # to end up in the same place as the command that started them.
 CONFIG_DIR_ENV_VAR = "ARCSECOND_CONFIG_DIR"
 
+# Which API server the CLI talks to, when a command does not say.
+#
+# Every registered server has a section of its own in config.ini — its
+# address and the credentials for it together — and this is the name of the
+# one currently pointed at. It is set with `arcsecond api use <name>` and
+# stays set: every later command uses it, so nobody has to type a server on
+# each one. The environment variable is the one-shot override for scripts and
+# cron jobs, which should not move the pointer of whoever sits at the keyboard.
+API_NAME_ENV_VAR = "ARCSECOND_API"
+DEFAULT_API_NAME = "cloud"
+
+# The section that holds the CLI's own settings (the pointer above, the
+# remembered Arcsecond.local install directory...). It is not an API server and
+# must never be read as one. Not configparser's DEFAULT section: values placed
+# there leak into every other section.
+CLI_SECTION = "cli"
+CLI_KEY_API = "api"
+
 
 class ArcsecondConfig(object):
     def __init__(self, **kwargs):
-        self.__api_name = kwargs.get("api_name", "cloud") or "cloud"
+        api_name = kwargs.get("api_name") or ArcsecondConfig.current_api_name()
+        if api_name == CLI_SECTION:
+            raise ArcsecondError(f"'{CLI_SECTION}' is reserved and cannot name an API.")
+        self.__api_name = api_name
         self.__verbose = kwargs.get("verbose", 0) or 0
         if "config" in kwargs.keys():
             self.__config = kwargs.get("config")
@@ -40,6 +61,97 @@ class ArcsecondConfig(object):
     def from_state(cls, state: State):
         return cls(api_name=state.api_name, verbose=state.verbose)
 
+    # ------------------------------------------------------------------
+    # The CLI's own settings: the API pointer and friends
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _read_parser(cls) -> ConfigParser:
+        parser = ConfigParser()
+        parser.read(str(cls.file_path()))
+        return parser
+
+    @classmethod
+    def _write_parser(cls, parser: ConfigParser) -> None:
+        with open(cls.file_path(), "w") as f:
+            parser.write(f)
+
+    @classmethod
+    def read_cli_setting(cls, key: str, default: Optional[str] = None) -> Optional[str]:
+        parser = cls._read_parser()
+        if not parser.has_section(CLI_SECTION):
+            return default
+        value = parser[CLI_SECTION].get(key, "").strip()
+        return value or default
+
+    @classmethod
+    def write_cli_setting(cls, key: str, value: Optional[str]) -> None:
+        """Set one CLI setting; None removes it."""
+        parser = cls._read_parser()
+        if not parser.has_section(CLI_SECTION):
+            parser.add_section(CLI_SECTION)
+        if value is None:
+            parser.remove_option(CLI_SECTION, key)
+        else:
+            parser[CLI_SECTION][key] = value
+        cls._write_parser(parser)
+
+    @classmethod
+    def current_api_name(cls) -> str:
+        """The API the CLI points at: $ARCSECOND_API, else the recorded
+        pointer, else 'cloud'."""
+        override = os.environ.get(API_NAME_ENV_VAR, "").strip()
+        if override:
+            return override
+        return cls.read_cli_setting(CLI_KEY_API) or DEFAULT_API_NAME
+
+    @classmethod
+    def is_api_name_overridden(cls) -> bool:
+        return bool(os.environ.get(API_NAME_ENV_VAR, "").strip())
+
+    @classmethod
+    def set_current_api_name(cls, name: str) -> None:
+        if name not in cls.registered_api_names():
+            raise ArcsecondError(
+                f"No API server is registered under the name '{name}'. "
+                "Register it first:  arcsecond api add <name> <address>"
+            )
+        cls.write_cli_setting(CLI_KEY_API, name)
+
+    @classmethod
+    def registered_api_names(cls) -> list:
+        """'cloud' first, then every section that carries a server address."""
+        parser = cls._read_parser()
+        names = [DEFAULT_API_NAME]
+        for section_name in parser.sections():
+            if section_name in (CLI_SECTION, DEFAULT_API_NAME):
+                continue
+            if parser[section_name].get("api_server", "").strip():
+                names.append(section_name)
+        return names
+
+    @classmethod
+    def remove_api(cls, name: str) -> None:
+        """Forget a registered server, credentials included. The pointer falls
+        back to 'cloud' if it was aimed at the removed one."""
+        if name == DEFAULT_API_NAME:
+            raise ArcsecondError("The 'cloud' API server cannot be removed.")
+        parser = cls._read_parser()
+        if (
+            not parser.has_section(name)
+            or not parser[name].get("api_server", "").strip()
+        ):
+            raise ArcsecondError(
+                f"No API server is registered under the name '{name}'."
+            )
+        parser.remove_section(name)
+        if (
+            parser.has_section(CLI_SECTION)
+            and parser[CLI_SECTION].get(CLI_KEY_API) == name
+        ):
+            parser.remove_option(CLI_SECTION, CLI_KEY_API)
+        cls._write_parser(parser)
+
     @classmethod
     def __old_config_file_path(cls):
         return (Path.home() / ".arcsecond.ini").expanduser()
@@ -118,12 +230,20 @@ class ArcsecondConfig(object):
 
     @property
     def all_apis(self) -> Optional[str]:
-        apis = [f"cloud: {ARCSECOND_API_URL_PROD} (protected)"]
+        """One line per registered server, the current one marked with '*'."""
+        current = ArcsecondConfig.current_api_name()
+
+        def line(name, address, note=""):
+            mark = "*" if name == current else " "
+            return f" {mark} {name}: {address}{note}"
+
+        apis = [line(DEFAULT_API_NAME, ARCSECOND_API_URL_PROD, " (protected)")]
         for section_name in self.__config.sections():
-            section = self.__config[section_name]
-            api_server = section.get("api_server", "")
+            if section_name in (CLI_SECTION, DEFAULT_API_NAME):
+                continue
+            api_server = self.__config[section_name].get("api_server", "")
             if api_server:
-                apis.append(f"{section_name}: {api_server}")
+                apis.append(line(section_name, api_server))
         return "\n".join(apis)
 
     @property

{arcsecond-3.20.2 → arcsecond-4.1.0}/arcsecond/cli.py

@@ -5,11 +5,23 @@ from arcsecond.cloud import (
     api,
     datasets,
     login,
-    me,
     telescopes,
+    upload,
     upload_data,
 )
-from arcsecond.hosting import backups, db, setup
+from arcsecond.docgen import docs
+from arcsecond.hosting import (
+    backups,
+    check_cmd,
+    db,
+    logs,
+    restart,
+    setup,
+    start,
+    status,
+    stop,
+    update,
+)
 from arcsecond.imagesources import commands as imagesources
 
 from . import __version__
@@ -37,26 +49,32 @@ def version():
     click.echo(__version__.__version__)
 
 
-# Read/set API server to use.
+# Which API server every command talks to (`arcsecond api use <name>`).
 main.add_command(api)
 
-# Login to Arcsecond.
+# Login to that server.
 main.add_command(login)
 
-# Read the logged-in user profile.
-main.add_command(me)
-
-# Read the list of existing datasets (for upload purposes).
+# Read the list of existing datasets / telescopes (for upload purposes).
 main.add_command(datasets)
-
-# Read the list of existing telescopes (for upload purposes).
 main.add_command(telescopes)
 
-# Upload a folder of files to a given dataset.
+# Upload a folder of files to a given dataset. `upload-data` is the pre-4.0
+# name, kept hidden so existing scripts keep working.
+main.add_command(upload)
 main.add_command(upload_data)
 
-# Allow to try arcsecond by installing a local version
+# Arcsecond.local: write the installation, then run it — no `docker` to type.
 main.add_command(setup)
+main.add_command(start)
+main.add_command(stop)
+main.add_command(restart)
+main.add_command(status)
+main.add_command(logs)
+main.add_command(update)
+
+# Is it reachable from the rest of the observatory, and if not, why not.
+main.add_command(check_cmd)
 
 # Browse and restore Arcsecond.local DB backups.
 main.add_command(backups)
@@ -73,12 +91,14 @@ main.add_command(imagesources.webcam)
 main.add_command(imagesources.allsky)
 main.add_command(imagesources.proxy)
 
-# Removed: a network camera is a webcam. Kept only to say so — see commands.py.
-main.add_command(imagesources.netcam)
-
 # Local ASCOM Alpaca diagnostics (e.g. `arcsecond alpaca probe dome ...`).
 main.add_command(alpaca_group)
 
+# The tool describing itself: `arcsecond docs commands --out DIR` writes the
+# command reference the documentation site publishes. Hidden — it is for the
+# documentation build, not for operators.
+main.add_command(docs)
+
 
 # `arcsecond proxy start` launches its detached proxy as
 # `python -m arcsecond.cli proxy start --foreground`, which needs this. Going

{arcsecond-3.20.2 → arcsecond-4.1.0}/arcsecond/cloud/__init__.py

@@ -1,24 +1,22 @@
-from .auth import api, login, me
+from .auth import api, login
 from .resources import datasets, telescopes
 from .uploader import (
     DatasetFileUploader,
     DatasetUploadContext,
 )
 from .uploader.constants import Status, Substatus
-from .uploads import (
-    upload_data,
-)
+from .uploads import upload, upload_data
 
 # Re-exported: this is the package's public surface.
 __all__ = [
     "api",
     "login",
-    "me",
     "datasets",
     "telescopes",
     "DatasetFileUploader",
     "DatasetUploadContext",
     "Status",
     "Substatus",
+    "upload",
     "upload_data",
 ]

arcsecond-4.1.0/arcsecond/cloud/auth.py

@@ -0,0 +1,176 @@
+import click
+import httpx
+
+from arcsecond.api import ArcsecondAPI, ArcsecondConfig
+from arcsecond.api.config import API_NAME_ENV_VAR, DEFAULT_API_NAME
+from arcsecond.errors import ArcsecondError
+from arcsecond.options import State, basic_options
+
+pass_state = click.make_pass_decorator(State, ensure=True)
+
+
+@click.command(short_help="Login to your Arcsecond account.")
+@click.option(
+    "--username",
+    required=True,
+    nargs=1,
+    prompt=True,
+    help="Account username (without @). Primary email address is also allowed.",
+)
+@click.option(
+    "--type",
+    required=True,
+    type=click.Choice(["access", "upload"], case_sensitive=False),
+    prompt=True,
+    help="Your access key (a.k.a. API key). Visit your settings page to copy "
+    "and paste it here. One of Access or Upload key must be provided.",
+)
+@click.option(
+    "--key",
+    required=True,
+    nargs=1,
+    prompt=True,
+    help="Your upload key. Visit your settings page to copy and paste it here. One of Access or Upload key must be provided.",
+)
+@basic_options
+@pass_state
+def login(state, username, type, key):
+    """Login to your Arcsecond account, on the API server the CLI points at.
+
+    You must provide either your Access Key, or your Upload Key.
+    By doing so, you choose the level of access you want to store
+    on this computer. The Access Key give a full API access to your
+    data. The Upload Key gives just enough permissions to upload data.
+
+    Both keys can be retrieved from your personal Settings page on
+    https://www.arcsecond.io (or on your own Arcsecond.local).
+
+    Beware that the Key you provide will be stored locally on the file:
+    ~/.config/arcsecond/config.ini
+    """
+    key_name = "access_key" if type == "access" else "upload_key"
+    config = ArcsecondConfig.from_state(state)
+    _, error = ArcsecondAPI(config).login(username, **{key_name: key})
+    if error:
+        click.echo(str(error))
+        return
+    click.echo(
+        click.style("Logged in", fg="green")
+        + f" as @{username} on '{config.api_name}' ({config.api_server})."
+    )
+
+
+# ---------------------------------------------------------------------------
+# `arcsecond api`: the pointer to the server every command talks to
+# ---------------------------------------------------------------------------
+
+PROBE_TIMEOUT = 8.0  # seconds
+
+
+def probe_api_server(address: str):
+    """Whether something answers HTTP at ``address``. Returns (ok, detail).
+
+    A reachability check, not a fingerprint: an Arcsecond server answers its
+    root with 200, but the point is to refuse a typo or a server that is not
+    up yet, and any HTTP answer below 500 proves the address is a live one.
+    """
+    try:
+        response = httpx.get(address, timeout=PROBE_TIMEOUT, follow_redirects=True)
+    except httpx.HTTPError as e:
+        return False, f"{type(e).__name__}: {e}"
+    if response.status_code >= 500:
+        return False, f"the server answered {response.status_code}"
+    return True, f"answered {response.status_code}"
+
+
+class _ApiGroup(click.Group):
+    """`arcsecond api <name> <address>`, the pre-4.0 way of registering a
+    server, still works: two tokens that are not a subcommand mean `add`."""
+
+    def resolve_command(self, ctx, args):
+        if args and args[0] not in self.commands and len(args) == 2:
+            return super().resolve_command(ctx, ["add", *args])
+        return super().resolve_command(ctx, args)
+
+
+@click.group(cls=_ApiGroup, invoke_without_command=True)
+@click.pass_context
+def api(ctx):
+    """The API server the CLI talks to.
+
+    Every command uses one server: the "cloud" (api.arcsecond.io) by
+    default, or any server registered here — typically your own
+    Arcsecond.local. Point the CLI at one and it stays pointed there:
+
+    \b
+      arcsecond api                          list the servers, * marks the current one
+      arcsecond api add local http://localhost:8800
+      arcsecond api use local                every command now talks to it
+      arcsecond api remove local
+
+    Credentials are kept per server, so `arcsecond login` after `api use`
+    logs you in on that server only.
+
+    For a script or a cron job, set ARCSECOND_API=<name> instead: it applies to
+    that process alone and leaves the pointer untouched.
+    """
+    if ctx.invoked_subcommand is None:
+        config = ArcsecondConfig()
+        click.echo(" • Registered API servers (* = current):")
+        click.echo(config.all_apis)
+        if ArcsecondConfig.is_api_name_overridden():
+            click.echo(
+                f"\n   {API_NAME_ENV_VAR} is set, which overrides the recorded pointer "
+                "for this process."
+            )
+
+
+@api.command(name="add", help="Register a server under a name.")
+@click.argument("name", nargs=1)
+@click.argument("address", nargs=1)
+def api_add(name, address):
+    if name == DEFAULT_API_NAME:
+        raise ArcsecondError(
+            "You cannot change the server address of the 'cloud' API server."
+        )
+    config = ArcsecondConfig(api_name=name)
+    config.api_server = address
+    click.echo(f' • Registered the API "{name}" at "{config.api_server}".')
+    if ArcsecondConfig.current_api_name() != name:
+        click.echo(f"   Point the CLI at it with:  arcsecond api use {name}")
+
+
+@api.command(
+    name="use",
+    help="Point every following command at this server (it must answer).",
+)
+@click.argument("name", nargs=1)
+def api_use(name):
+    if name not in ArcsecondConfig.registered_api_names():
+        raise ArcsecondError(
+            f"No API server is registered under the name '{name}'.\n"
+            f"Register it first:  arcsecond api add {name} <address>"
+        )
+    address = ArcsecondConfig(api_name=name).api_server
+    ok, detail = probe_api_server(address)
+    if not ok:
+        raise ArcsecondError(
+            f"'{name}' ({address}) does not answer — {detail}.\n"
+            "The pointer was not moved. Start that server, or check the address."
+        )
+    ArcsecondConfig.set_current_api_name(name)
+    click.echo(
+        click.style(" • The CLI now points at ", fg="green") + f"'{name}' ({address})."
+    )
+    if not ArcsecondConfig(api_name=name).is_logged_in:
+        click.echo("   You are not logged in there yet:  arcsecond login")
+
+
+@api.command(name="remove", help="Forget a registered server and its credentials.")
+@click.argument("name", nargs=1)
+def api_remove(name):
+    was_current = ArcsecondConfig.current_api_name() == name
+    ArcsecondConfig.remove_api(name)
+    click.echo(f' • Removed the API "{name}".')
+    if was_current:
+        click.echo(f"   The CLI points at '{DEFAULT_API_NAME}' again.")

{arcsecond-3.20.2 → arcsecond-4.1.0}/arcsecond/cloud/uploads.py

@@ -14,7 +14,7 @@ from arcsecond.options import State, basic_options
 pass_state = click.make_pass_decorator(State, ensure=True)
 
 
-@click.command()
+@click.command(name="upload")
 @click.argument("folder", required=True, nargs=1)
 @click.option(
     "-d",
@@ -55,7 +55,7 @@ pass_state = click.make_pass_decorator(State, ensure=True)
 )
 @basic_options
 @pass_state
-def upload_data(
+def upload(
     state, folder, dataset=None, telescope=None, raw=None, tags=None, portal=None
 ):
     """
@@ -105,3 +105,14 @@ def upload_data(
     ok = input("\n   ----> OK? (Press Enter) ")
     if ok.strip() == "":
         walk_folder_and_upload_files(DatasetFileUploader, context, folder)
+
+
+# The pre-4.0 name. Same command object underneath, so the two never drift;
+# hidden so that `--help` shows one way of doing it.
+upload_data = click.Command(
+    name="upload-data",
+    callback=upload.callback,
+    params=upload.params,
+    help=upload.help,
+    hidden=True,
+)