citrascope 0.3.0__tar.gz → 0.5.0__tar.gz

{citrascope-0.3.0 → citrascope-0.5.0}/.github/copilot-instructions.md

@@ -25,7 +25,6 @@ This project is a Python package for interacting with astronomical data and serv
   - `citrascope/web/templates/`: HTML templates
   - `citrascope/web/static/`: CSS and JavaScript files
 - `tests/`: Unit and integration tests
-- `docs/`: Project documentation
 
 ## Testing
 - All new features and bug fixes should include corresponding tests in `tests/`.
@@ -77,7 +76,7 @@ The web interface provides real-time monitoring and configuration for telescope
 
 This project relies on several key Python packages. Below are some of the most important ones and their roles:
 
-- **Click**: Used for building the command-line interface (CLI). The main entry point for the application (`python -m citrascope start`) is implemented using Click.
+- **Click**: Used for building the command-line interface (CLI). The main entry point for the application (`python -m citrascope`) is implemented using Click.
 - **Pydantic-Settings**: Manages configuration and settings, ensuring type safety and validation for environment variables.
 - **Requests** and **HTTPX**: Handle HTTP requests for interacting with the Citra.space API.
 - **Python-Dateutil**: Provides robust date and time parsing utilities.
@@ -102,5 +101,5 @@ For a complete list of dependencies, refer to the `pyproject.toml` file.
 
 ## Additional Notes
 - Keep dependencies minimal and update `pyproject.toml` as needed.
-- Document any major changes in `docs/index.md`.
+- Documentation is maintained in the [citra-space/docs](https://github.com/citra-space/docs) repository under `docs/citrascope/`.
 - Use pre-commit hooks for code quality.

{citrascope-0.3.0 → citrascope-0.5.0}/.gitignore

@@ -68,9 +68,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/build/
-
 # PyBuilder
 target/
 

{citrascope-0.3.0 → citrascope-0.5.0}/.vscode/launch.json

@@ -4,29 +4,20 @@
     "version": "0.2.0",
     "configurations": [
         {
-            "name": "Python: citrascope dev start",
+            "name": "Python: citrascope",
             "type": "debugpy",
             "request": "launch",
             "module": "citrascope",
-            "args": ["--dev", "start"],
+            "args": [],
             "console": "integratedTerminal",
             "justMyCode": false
         },
         {
-            "name": "Python: citrascope dev start, keep images",
+            "name": "Python: citrascope (custom port)",
             "type": "debugpy",
             "request": "launch",
             "module": "citrascope",
-            "args": ["--dev", "--keep-images", "start"],
-            "console": "integratedTerminal",
-            "justMyCode": false
-        },
-        {
-            "name": "Python: citrascope dev start DEBUG logging",
-            "type": "debugpy",
-            "request": "launch",
-            "module": "citrascope",
-            "args": ["--dev", "--log-level", "DEBUG", "start"],
+            "args": ["--web-port", "8080"],
             "console": "integratedTerminal",
             "justMyCode": false
         }

{citrascope-0.3.0 → citrascope-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: citrascope
-Version: 0.3.0
+Version: 0.5.0
 Summary: Remotely control a telescope while it polls for tasks, collects and edge processes data, and delivers results and data for further processing.
 Author-email: Patrick McDavid <patrick@citra.space>
 License-Expression: MIT
@@ -9,13 +9,9 @@ Requires-Dist: click
 Requires-Dist: fastapi>=0.104.0
 Requires-Dist: httpx
 Requires-Dist: platformdirs>=4.0.0
-Requires-Dist: pydantic-settings
-Requires-Dist: pytest-cov
 Requires-Dist: python-dateutil
-Requires-Dist: python-json-logger
 Requires-Dist: requests
 Requires-Dist: skyfield
-Requires-Dist: types-python-dateutil
 Requires-Dist: uvicorn[standard]>=0.24.0
 Requires-Dist: websockets>=12.0
 Provides-Extra: all
@@ -38,10 +34,7 @@ Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: sphinx; extra == 'docs'
-Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
-Requires-Dist: sphinx-markdown-builder; extra == 'docs'
+Requires-Dist: types-python-dateutil; extra == 'dev'
 Provides-Extra: indi
 Requires-Dist: pixelemon; extra == 'indi'
 Requires-Dist: plotly; extra == 'indi'
@@ -65,33 +58,46 @@ Remotely control a telescope while it polls for tasks, collects observations, an
 - Connects to configured telescope and camera hardware
 - Acts as a task daemon carrying out and remitting photography tasks
 
+## Documentation
+
+Full documentation is available at [docs.citra.space](https://docs.citra.space/citrascope/).
+
+Documentation source is maintained in the [citra-space/docs](https://github.com/citra-space/docs) repository.
+
 ## Installation
 
-### Install with pipx
+**Important:** CitraScope requires Python 3.10, 3.11, or 3.12.
 
-[pipx](https://pipx.pypa.io/) installs the CLI tool in an isolated environment while making it globally available:
+### Check Your Python Version
 
 ```sh
-pipx install citrascope
+python3 --version
 ```
 
-### Optional Dependencies
+If you don't have a compatible version, install one with [pyenv](https://github.com/pyenv/pyenv):
 
-CitraScope supports different hardware adapters through optional dependency groups:
+```sh
+pyenv install 3.12.0
+pyenv local 3.12.0  # Sets Python 3.12.0 for the current directory
+```
 
-- **INDI adapter** (for Linux-based telescope control):
-  ```sh
-  pipx install citrascope[indi]
-  # or with pip: pip install citrascope[indi]
-  ```
+### Install CitraScope
 
-- **All optional dependencies**:
-  ```sh
-  pipx install citrascope[all]
-  # or with pip: pip install citrascope[all]
-  ```
+**Recommended: Using pip in a virtual environment**
 
-The base installation without optional dependencies supports the NINA adapter, which works via HTTP API calls and does not require additional Python packages.
+```sh
+python3 -m venv citrascope-env
+source citrascope-env/bin/activate  # On Windows: citrascope-env\Scripts\activate
+pip install citrascope
+```
+
+### Optional Dependencies
+
+For Linux-based telescope control (INDI):
+
+```sh
+pip install citrascope[indi]
+```
 
 This provides the `citrascope` command-line tool. To see available commands:
 
@@ -101,16 +107,18 @@ citrascope --help
 
 ## Usage
 
-Run the CLI tool:
+### Starting the Daemon
+
+Run the daemon with:
 
 ```sh
-citrascope start
+citrascope
 ```
 
-To connect to the Citra Dev server:
+By default, this starts the web interface on `http://localhost:24872`. You can customize the port:
 
 ```sh
-citrascope start --dev
+citrascope --web-port 8080
 ```
 
 ## Developer Setup
@@ -174,10 +182,10 @@ Then create a release in the GitHub UI from the new tag. This triggers automatic
 
 If you are using Visual Studio Code, you can run or debug the project directly using the pre-configured launch options in `.vscode/launch.json`:
 
-- **Python: citrascope dev start** — Runs the main entry point with development options.
-- **Python: citrascope dev start DEBUG logging** — Runs with development options and sets log level to DEBUG for more detailed output.
+- **Python: citrascope** — Runs the daemon with default settings
+- **Python: citrascope (custom port)** — Runs with web interface on port 8080
 
-To use these, open the Run and Debug panel in VS Code, select the desired configuration, and click the Run or Debug button. This is a convenient way to start or debug the app without manually entering commands.
+To use these, open the Run and Debug panel in VS Code, select the desired configuration, and click the Run or Debug button.
 
 ## Running Tests
 

{citrascope-0.3.0 → citrascope-0.5.0}/README.md

@@ -9,33 +9,46 @@ Remotely control a telescope while it polls for tasks, collects observations, an
 - Connects to configured telescope and camera hardware
 - Acts as a task daemon carrying out and remitting photography tasks
 
+## Documentation
+
+Full documentation is available at [docs.citra.space](https://docs.citra.space/citrascope/).
+
+Documentation source is maintained in the [citra-space/docs](https://github.com/citra-space/docs) repository.
+
 ## Installation
 
-### Install with pipx
+**Important:** CitraScope requires Python 3.10, 3.11, or 3.12.
 
-[pipx](https://pipx.pypa.io/) installs the CLI tool in an isolated environment while making it globally available:
+### Check Your Python Version
 
 ```sh
-pipx install citrascope
+python3 --version
 ```
 
-### Optional Dependencies
+If you don't have a compatible version, install one with [pyenv](https://github.com/pyenv/pyenv):
 
-CitraScope supports different hardware adapters through optional dependency groups:
+```sh
+pyenv install 3.12.0
+pyenv local 3.12.0  # Sets Python 3.12.0 for the current directory
+```
 
-- **INDI adapter** (for Linux-based telescope control):
-  ```sh
-  pipx install citrascope[indi]
-  # or with pip: pip install citrascope[indi]
-  ```
+### Install CitraScope
 
-- **All optional dependencies**:
-  ```sh
-  pipx install citrascope[all]
-  # or with pip: pip install citrascope[all]
-  ```
+**Recommended: Using pip in a virtual environment**
 
-The base installation without optional dependencies supports the NINA adapter, which works via HTTP API calls and does not require additional Python packages.
+```sh
+python3 -m venv citrascope-env
+source citrascope-env/bin/activate  # On Windows: citrascope-env\Scripts\activate
+pip install citrascope
+```
+
+### Optional Dependencies
+
+For Linux-based telescope control (INDI):
+
+```sh
+pip install citrascope[indi]
+```
 
 This provides the `citrascope` command-line tool. To see available commands:
 
@@ -45,16 +58,18 @@ citrascope --help
 
 ## Usage
 
-Run the CLI tool:
+### Starting the Daemon
+
+Run the daemon with:
 
 ```sh
-citrascope start
+citrascope
 ```
 
-To connect to the Citra Dev server:
+By default, this starts the web interface on `http://localhost:24872`. You can customize the port:
 
 ```sh
-citrascope start --dev
+citrascope --web-port 8080
 ```
 
 ## Developer Setup
@@ -118,10 +133,10 @@ Then create a release in the GitHub UI from the new tag. This triggers automatic
 
 If you are using Visual Studio Code, you can run or debug the project directly using the pre-configured launch options in `.vscode/launch.json`:
 
-- **Python: citrascope dev start** — Runs the main entry point with development options.
-- **Python: citrascope dev start DEBUG logging** — Runs with development options and sets log level to DEBUG for more detailed output.
+- **Python: citrascope** — Runs the daemon with default settings
+- **Python: citrascope (custom port)** — Runs with web interface on port 8080
 
-To use these, open the Run and Debug panel in VS Code, select the desired configuration, and click the Run or Debug button. This is a convenient way to start or debug the app without manually entering commands.
+To use these, open the Run and Debug panel in VS Code, select the desired configuration, and click the Run or Debug button.
 
 ## Running Tests
 

citrascope-0.5.0/citrascope/__main__.py

@@ -0,0 +1,23 @@
+import click
+
+from citrascope.citra_scope_daemon import CitraScopeDaemon
+from citrascope.constants import DEFAULT_WEB_PORT
+from citrascope.settings.citrascope_settings import CitraScopeSettings
+
+
+@click.command()
+@click.option(
+    "--web-port",
+    default=DEFAULT_WEB_PORT,
+    type=int,
+    help=f"Web server port (default: {DEFAULT_WEB_PORT})",
+)
+def cli(web_port):
+    """CitraScope daemon - configure via web UI at http://localhost:24872"""
+    settings = CitraScopeSettings(web_port=web_port)
+    daemon = CitraScopeDaemon(settings)
+    daemon.run()
+
+
+if __name__ == "__main__":
+    cli()

{citrascope-0.3.0 → citrascope-0.5.0}/citrascope/api/citra_api_client.py

@@ -41,7 +41,19 @@ class CitraApiClient(AbstractCitraApiClient):
             return resp.json()
         except httpx.HTTPStatusError as e:
             if self.logger:
-                self.logger.error(f"HTTP error: {e.response.status_code} {e.response.text}")
+                # Check if response is HTML (e.g., Cloudflare error pages)
+                content_type = e.response.headers.get("content-type", "")
+                response_text = e.response.text
+
+                if "text/html" in content_type or response_text.strip().startswith("<"):
+                    # Log only status and a brief message for HTML responses, sometimes we get Cloudflare error pages
+                    self.logger.error(
+                        f"HTTP error: {e.response.status_code} - "
+                        f"Received HTML error page (likely Cloudflare or server error) for {method} {endpoint}"
+                    )
+                else:
+                    # Log full response for non-HTML errors (JSON, plain text, etc.)
+                    self.logger.error(f"HTTP error: {e.response.status_code} {response_text}")
             return None
         except Exception as e:
             if self.logger:

{citrascope-0.3.0 → citrascope-0.5.0}/citrascope/citra_scope_daemon.py

@@ -17,9 +17,6 @@ class CitraScopeDaemon:
         settings: CitraScopeSettings,
         api_client: Optional[AbstractCitraApiClient] = None,
         hardware_adapter: Optional[AbstractAstroHardwareAdapter] = None,
-        enable_web: bool = True,
-        web_host: str = "0.0.0.0",
-        web_port: int = 24872,
     ):
         self.settings = settings
         CITRASCOPE_LOGGER.setLevel(self.settings.log_level)
@@ -33,16 +30,15 @@ class CitraScopeDaemon:
 
         self.api_client = api_client
         self.hardware_adapter = hardware_adapter
-        self.enable_web = enable_web
         self.web_server = None
         self.task_manager = None
         self.ground_station = None
         self.telescope_record = None
         self.configuration_error: Optional[str] = None
+        self._autofocus_in_progress = False
 
-        # Create web server instance if enabled (always start web server)
-        if self.enable_web:
-            self.web_server = CitraScopeWebServer(daemon=self, host=web_host, port=web_port)
+        # Create web server instance (always enabled)
+        self.web_server = CitraScopeWebServer(daemon=self, host="0.0.0.0", port=self.settings.web_port)
 
     def _create_hardware_adapter(self) -> AbstractAstroHardwareAdapter:
         """Factory method to create the appropriate hardware adapter based on settings."""
@@ -73,12 +69,8 @@ class CitraScopeDaemon:
         try:
             if reload_settings:
                 CITRASCOPE_LOGGER.info("Reloading configuration...")
-                # Reload settings from file
-                new_settings = CitraScopeSettings(
-                    dev=("dev.api" in self.settings.host),
-                    log_level=self.settings.log_level,
-                    keep_images=self.settings.keep_images,
-                )
+                # Reload settings from file (preserving web_port)
+                new_settings = CitraScopeSettings(web_port=self.settings.web_port)
                 self.settings = new_settings
                 CITRASCOPE_LOGGER.setLevel(self.settings.log_level)
 
@@ -186,6 +178,9 @@ class CitraScopeDaemon:
                 f"Hardware connected. Slew rate: {self.hardware_adapter.scope_slew_rate_degrees_per_second} deg/sec"
             )
 
+            # Save filter configuration if adapter supports it
+            self._save_filter_config()
+
             self.task_manager = TaskManager(
                 self.api_client,
                 citra_telescope_record,
@@ -205,12 +200,88 @@ class CitraScopeDaemon:
             CITRASCOPE_LOGGER.error(error_msg, exc_info=True)
             return False, error_msg
 
+    def is_autofocus_in_progress(self) -> bool:
+        """Check if autofocus routine is currently running.
+
+        Returns:
+            bool: True if autofocus is in progress, False otherwise
+        """
+        return self._autofocus_in_progress
+
+    def _save_filter_config(self):
+        """Save filter configuration from adapter to settings if supported.
+
+        This method is called:
+        - After hardware initialization to save discovered filters
+        - After autofocus to save updated focus positions
+        - After manual filter focus updates via web API
+
+        Thread safety: This modifies self.settings and writes to disk.
+        Should be called from main daemon thread or properly synchronized.
+        """
+        if not self.hardware_adapter or not self.hardware_adapter.supports_filter_management():
+            return
+
+        try:
+            filter_config = self.hardware_adapter.get_filter_config()
+            if filter_config:
+                self.settings.adapter_settings["filters"] = filter_config
+                self.settings.save()
+                CITRASCOPE_LOGGER.info(f"Saved filter configuration with {len(filter_config)} filters")
+        except Exception as e:
+            CITRASCOPE_LOGGER.warning(f"Failed to save filter configuration: {e}")
+
+    def trigger_autofocus(self) -> tuple[bool, Optional[str]]:
+        """Trigger autofocus routine on the hardware adapter.
+
+        Requires task processing to be manually paused before running.
+        Checks that both:
+        1. Task processing is paused
+        2. No task is currently in-flight
+
+        Returns:
+            Tuple of (success, error_message)
+        """
+        if not self.hardware_adapter:
+            return False, "No hardware adapter initialized"
+
+        if not self.hardware_adapter.supports_filter_management():
+            return False, "Hardware adapter does not support filter management"
+
+        # Prevent concurrent autofocus operations
+        if self._autofocus_in_progress:
+            return False, "Autofocus already in progress"
+
+        # Require task processing to be manually paused
+        if self.task_manager:
+            if self.task_manager.is_processing_active():
+                return False, "Task processing must be paused before running autofocus"
+
+            if self.task_manager.current_task_id is not None:
+                return False, "A task is currently executing. Please wait for it to complete and try again"
+
+        self._autofocus_in_progress = True
+        try:
+            CITRASCOPE_LOGGER.info("Starting autofocus routine...")
+            self.hardware_adapter.do_autofocus()
+
+            # Save updated filter configuration after autofocus
+            self._save_filter_config()
+
+            CITRASCOPE_LOGGER.info("Autofocus routine completed successfully")
+            return True, None
+        except Exception as e:
+            error_msg = f"Autofocus failed: {str(e)}"
+            CITRASCOPE_LOGGER.error(error_msg, exc_info=True)
+            return False, error_msg
+        finally:
+            self._autofocus_in_progress = False
+
     def run(self):
-        # Start web server FIRST if enabled, so users can monitor/configure
+        # Start web server FIRST, so users can monitor/configure
         # The web interface will remain available even if configuration is incomplete
-        if self.enable_web:
-            self.web_server.start()
-            CITRASCOPE_LOGGER.info(f"Web interface available at http://{self.web_server.host}:{self.web_server.port}")
+        self.web_server.start()
+        CITRASCOPE_LOGGER.info(f"Web interface available at http://{self.web_server.host}:{self.web_server.port}")
 
         try:
             # Try to initialize components
@@ -238,6 +309,7 @@ class CitraScopeDaemon:
         """Clean up resources on shutdown."""
         if self.task_manager:
             self.task_manager.stop()
-        if self.enable_web and self.web_server:
+        if self.web_server:
             CITRASCOPE_LOGGER.info("Stopping web server...")
-            self.web_server.stop()
+            if self.web_server.web_log_handler:
+                CITRASCOPE_LOGGER.removeHandler(self.web_server.web_log_handler)

citrascope-0.5.0/citrascope/constants.py

@@ -0,0 +1,23 @@
+"""Application-wide constants for CitraScope.
+
+This module contains all shared constants used across different parts of the application.
+Centralizing these values prevents duplication and circular import issues.
+"""
+
+# ============================================================================
+# API ENDPOINTS
+# ============================================================================
+PROD_API_HOST = "api.citra.space"
+DEV_API_HOST = "dev.api.citra.space"
+DEFAULT_API_PORT = 443
+
+# ============================================================================
+# WEB APP URLs
+# ============================================================================
+PROD_APP_URL = "https://app.citra.space"
+DEV_APP_URL = "https://dev.app.citra.space"
+
+# ============================================================================
+# WEB SERVER
+# ============================================================================
+DEFAULT_WEB_PORT = 24872  # "CITRA" on phone keypad

{citrascope-0.3.0 → citrascope-0.5.0}/citrascope/hardware/abstract_astro_hardware_adapter.py

@@ -20,6 +20,18 @@ class SettingSchemaEntry(TypedDict, total=False):
     options: list[str]  # List of valid options for select/dropdown inputs
 
 
+class FilterConfig(TypedDict):
+    """Type definition for filter configuration.
+
+    Attributes:
+        name: Human-readable filter name (e.g., 'Luminance', 'Red', 'Ha')
+        focus_position: Focuser position for this filter in steps
+    """
+
+    name: str
+    focus_position: int
+
+
 class ObservationStrategy(Enum):
     MANUAL = 1
     SEQUENCE_TO_CONTROLLER = 2
@@ -176,3 +188,52 @@ class AbstractAstroHardwareAdapter(ABC):
             bool: True if alignment was successful, False otherwise.
         """
         pass
+
+    def do_autofocus(self) -> None:
+        """Perform autofocus routine for all filters.
+
+        This is an optional method for adapters that support filter management.
+        Default implementation raises NotImplementedError. Override in subclasses
+        that support autofocus.
+
+        Raises:
+            NotImplementedError: If the adapter doesn't support autofocus
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not support autofocus")
+
+    def supports_filter_management(self) -> bool:
+        """Indicates whether this adapter supports filter/focus management.
+
+        Returns:
+            bool: True if the adapter manages filters and focus positions, False otherwise.
+        """
+        return False
+
+    def get_filter_config(self) -> dict[str, FilterConfig]:
+        """Get the current filter configuration including focus positions.
+
+        Returns:
+            dict: Dictionary mapping filter IDs (as strings) to FilterConfig.
+                  Each FilterConfig contains:
+                  - name (str): Filter name
+                  - focus_position (int): Focuser position for this filter
+
+        Example:
+            {
+                "1": {"name": "Luminance", "focus_position": 9000},
+                "2": {"name": "Red", "focus_position": 9050}
+            }
+        """
+        return {}
+
+    def update_filter_focus(self, filter_id: str, focus_position: int) -> bool:
+        """Update the focus position for a specific filter.
+
+        Args:
+            filter_id: Filter ID as string
+            focus_position: New focus position in steps
+
+        Returns:
+            bool: True if update was successful, False otherwise
+        """
+        return False