pyobs-core 2.0.0.dev94__tar.gz → 2.0.0.dev95__tar.gz

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyobs-core
-Version: 2.0.0.dev94
+Version: 2.0.0.dev95
 Summary: robotic telescope software
 Author-email: Tim-Oliver Husser <thusser@uni-goettingen.de>
 License-Expression: MIT

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/calibration/darkbias.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Annotated
 
+from pydantic import Field
+
 from pyobs.interfaces import (
     IBinning,
     IData,
@@ -23,10 +25,12 @@ log = logging.getLogger(__name__)
 class DarkBiasScript(Script):
     """Script for running darks or biases."""
 
-    camera: Annotated[str, IData, IBinning, IWindow, IExposureTime, IImageType]
-    count: int = 20
-    exptime: float = 0
-    binning: tuple[int, int] = (1, 1)
+    camera: Annotated[str, IData, IBinning, IWindow, IExposureTime, IImageType] = Field(
+        description="Name of the camera module to expose with."
+    )
+    count: int = Field(default=20, description="Number of exposures to take.")
+    exptime: float = Field(default=0, description="Exposure time in seconds. 0 takes a bias, anything else a dark.")
+    binning: tuple[int, int] = Field(default=(1, 1), description="Detector binning as (x, y).")
 
     async def can_run(self, data: TaskData | None) -> bool:
         """Whether this config can currently run.

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/calibration/pointing.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Annotated
 
+from pydantic import Field
+
 from pyobs.interfaces import IPointingAltAz, IReady
 from pyobs.robotic.scripts import Script
 from pyobs.robotic.utils.skyflats.pointing import SkyFlatsBasePointing
@@ -17,8 +19,8 @@ log = logging.getLogger(__name__)
 class PointingScript(Script):
     """Script for pointing the telescope for flats."""
 
-    telescope: Annotated[str, IPointingAltAz, IReady]
-    pointing: SkyFlatsBasePointing
+    telescope: Annotated[str, IPointingAltAz, IReady] = Field(description="Name of the telescope module to point.")
+    pointing: SkyFlatsBasePointing = Field(description="Strategy used to compute the flat-field pointing.")
 
     async def can_run(self, data: TaskData | None) -> bool:
         """Whether this config can currently run.

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/calibration/skyflats.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Annotated
 
+from pydantic import Field
+
 from pyobs.interfaces import IBinning, IFilters, IFlatField, IReady, IRoof, ITelescope
 from pyobs.robotic.scripts import Script
 from pyobs.robotic.utils.skyflats.priorities.base import SkyflatPriorities
@@ -21,17 +23,31 @@ FlatFunctions = str | dict[str, str | dict[str, str]]
 class SkyFlatsScript(Script):
     """Script for scheduling and running skyflats using an IFlatField module."""
 
-    roof: Annotated[str, IRoof]
-    telescope: Annotated[str, ITelescope]
-    flatfield: Annotated[str, IBinning, IFilters, IFlatField]
-    functions: FlatFunctions = {}
-    priorities: SkyflatPriorities
-    min_exptime: float = 0.5
-    max_exptime: float = 5
-    timespan: float = 7200
-    filter_change: float = 30
-    count: int = 20
-    readout: dict[str, float] | None = None
+    roof: Annotated[str, IRoof] = Field(description="Name of the roof module, checked to be open before starting.")
+    telescope: Annotated[str, ITelescope] = Field(
+        description="Name of the telescope module, checked to be ready before starting."
+    )
+    flatfield: Annotated[str, IBinning, IFilters, IFlatField] = Field(
+        description="Name of the module that takes the flat-field exposures."
+    )
+    functions: FlatFunctions = Field(
+        default={},
+        description=(
+            "Exposure-time function(s) of solar altitude `h` in degrees, e.g. 'exp(-0.9*(h+3.9))'. "
+            "Either a single expression for all filters/binnings, a dict keyed by binning ('1x1') or "
+            "filter, or a nested dict of binning -> filter -> expression."
+        ),
+    )
+    priorities: SkyflatPriorities = Field(description="Strategy for prioritizing filter/binning combinations.")
+    min_exptime: float = Field(default=0.5, description="Minimum acceptable exposure time in seconds.")
+    max_exptime: float = Field(default=5, description="Maximum acceptable exposure time in seconds.")
+    timespan: float = Field(default=7200, description="Time span in seconds to schedule flats over.")
+    filter_change: float = Field(default=30, description="Estimated time in seconds to change a filter.")
+    count: int = Field(default=20, description="Number of exposures to take per filter/binning combination.")
+    readout: dict[str, float] | None = Field(
+        default=None,
+        description='Readout time in seconds per binning, keyed as "BxB" (e.g. "2x2"). Assumes 0s if unset.',
+    )
 
     async def can_run(self, data: TaskData | None) -> bool:
         """Whether this config can currently run.

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/control/cases.py

@@ -4,6 +4,8 @@ import logging
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 if TYPE_CHECKING:
     from pyobs.robotic.task import TaskData
     from pyobs.utils.time import Time
@@ -16,8 +18,10 @@ log = logging.getLogger(__name__)
 class CasesRunner(Script):
     """Script for distinguishing cases."""
 
-    expression: str
-    cases: dict[str | int | float, Script]
+    expression: str = Field(description="Python expression to evaluate; its value selects which script to run.")
+    cases: dict[str | int | float, Script] = Field(
+        description='Scripts to run, keyed by the value of `expression`. Use key "else" for a fallback.'
+    )
 
     def __get_script(self) -> Script:
         # evaluate condition

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/control/conditional.py

@@ -4,6 +4,8 @@ import logging
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 if TYPE_CHECKING:
     from pyobs.robotic.task import TaskData
     from pyobs.utils.time import Time
@@ -16,9 +18,11 @@ log = logging.getLogger(__name__)
 class ConditionalRunner(Script):
     """Script for running an if condition."""
 
-    condition: str
-    true: Script
-    false: Script | None = None
+    condition: str = Field(description="Python expression to evaluate; run `true` if truthy, `false` otherwise.")
+    true: Script = Field(description="Script to run if `condition` is truthy.")
+    false: Script | None = Field(
+        default=None, description="Script to run if `condition` is falsy. Does nothing if unset."
+    )
 
     def __get_script(self) -> Script | None:
         # evaluate condition

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/control/parallel.py

@@ -4,6 +4,8 @@ import asyncio
 import logging
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 if TYPE_CHECKING:
     from pyobs.robotic.task import TaskData
     from pyobs.utils.time import Time
@@ -22,8 +24,11 @@ async def _run_script(script: Script, data: TaskData | None) -> None:
 class ParallelRunner(Script):
     """Script for running other scripts in parallel."""
 
-    scripts: list[Script]
-    check_all_can_run: bool = True
+    scripts: list[Script] = Field(description="Scripts to run concurrently.")
+    check_all_can_run: bool = Field(
+        default=True,
+        description="If set, all scripts must be able to run for this script to run; otherwise, any one suffices.",
+    )
 
     async def can_run(self, data: TaskData | None) -> bool:
         results = [await s.can_run(data) for s in self.scripts]

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/control/selector.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Annotated
 
+from pydantic import Field
+
 from pyobs.interfaces import IMotion
 from pyobs.interfaces.IMode import IMode
 from pyobs.robotic.scripts import Script
@@ -18,8 +20,8 @@ log = logging.getLogger(__name__)
 class SelectorScript(Script):
     """Script for running Mode Selection."""
 
-    mode: str
-    selector: Annotated[str, IMode, IMotion]
+    mode: str = Field(description="Name of the mode to select.")
+    selector: Annotated[str, IMode, IMotion] = Field(description="Name of the mode-selection module.")
 
     async def can_run(self, data: TaskData | None) -> bool:
         """Whether this config can currently run.

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/control/sequential.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
 
 import astropy.units as u
 from astropy.time import TimeDelta
+from pydantic import Field
 
 if TYPE_CHECKING:
     from pyobs.robotic.task import TaskData
@@ -17,8 +18,11 @@ log = logging.getLogger(__name__)
 class SequentialRunner(Script):
     """Script for running a sequence of other scripts."""
 
-    scripts: list[Script]
-    check_all_can_run: bool = True
+    scripts: list[Script] = Field(description="Scripts to run in sequence, each only if it can run.")
+    check_all_can_run: bool = Field(
+        default=True,
+        description="If set, all scripts must be able to run for this script to run; otherwise, only the first must.",
+    )
 
     async def can_run(self, data: TaskData | None) -> bool:
         if self.check_all_can_run:

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/imaging/autofocus.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING, Annotated
 
+from pydantic import Field
+
 from pyobs.interfaces import IAutoFocus, IMotion, IPointingRaDec, IReady, ITelescope
 from pyobs.robotic.scripts import Script
 from pyobs.utils.time import Time
@@ -16,11 +18,15 @@ log = logging.getLogger(__name__)
 class AutoFocusScript(Script):
     """Script for running autofocus series."""
 
-    autofocus: Annotated[str, IAutoFocus] = "autofocus"
-    telescope: Annotated[str, ITelescope, IPointingRaDec] = "telescope"
-    count: int = 5
-    step: float = 0.1
-    exposure_time: float = 2.0
+    autofocus: Annotated[str, IAutoFocus] = Field(
+        default="autofocus", description="Name of the auto-focus module to run the series with."
+    )
+    telescope: Annotated[str, ITelescope, IPointingRaDec] = Field(
+        default="telescope", description="Name of the telescope module, moved to the target and stopped afterwards."
+    )
+    count: int = Field(default=5, description="Number of focus steps to take in the series.")
+    step: float = Field(default=0.1, description="Focus step size.")
+    exposure_time: float = Field(default=2.0, description="Exposure time in seconds for each focus step.")
 
     async def can_run(self, data: TaskData | None) -> bool:
         """Whether this config can currently run.

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/imaging/imaging.py

@@ -38,26 +38,42 @@ log = logging.getLogger(__name__)
 class AcquisitionConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    enabled: bool = True
-    optional: bool = False
+    enabled: bool = Field(
+        default=True, description="Whether to perform acquisition before starting this configuration."
+    )
+    optional: bool = Field(
+        default=False, description="If acquisition fails, continue without it instead of aborting the script."
+    )
 
 
 class GuidingConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    enabled: bool = True
-    optional: bool = False
+    enabled: bool = Field(default=True, description="Whether to start auto-guiding before starting this configuration.")
+    optional: bool = Field(
+        default=False, description="If starting auto-guiding fails, continue without it instead of aborting the script."
+    )
 
 
 class InstrumentConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    exposure_time: float | ExposureTimeProvider = 0.0
-    count: int = 1
-    image_type: ImageType = ImageType.OBJECT
-    binning: tuple[int, int] = (1, 1)
-    window: tuple[int, int, int, int] | None = None
-    optical_filter: str | None = None
+    exposure_time: float | ExposureTimeProvider = Field(
+        default=0.0, description="Exposure time in seconds, or a provider that computes it dynamically."
+    )
+    count: int = Field(default=1, description="Number of exposures to take with this configuration.")
+    image_type: ImageType = Field(
+        default=ImageType.OBJECT,
+        description="Type of image to take: OBJECT (science), BIAS, DARK, SKYFLAT, FOCUS, ACQUISITION, or GUIDING.",
+    )
+    binning: tuple[int, int] = Field(default=(1, 1), description="Detector binning as (x, y).")
+    window: tuple[int, int, int, int] | None = Field(
+        default=None,
+        description="Detector sub-window as (left, top, width, height). Uses the full frame if unset.",
+    )
+    optical_filter: str | None = Field(
+        default=None, description="Name of the filter to use. Uses the camera's current filter if unset."
+    )
 
     async def get_exposure_time(self) -> float:
         """Return the exposure time, computing it dynamically if needed."""
@@ -69,22 +85,41 @@ class InstrumentConfig(BaseModel):
 class Configuration(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    acquisition_config: AcquisitionConfig = Field(default_factory=AcquisitionConfig)
-    guiding_config: GuidingConfig = Field(default_factory=GuidingConfig)
-    instrument_configs: list[InstrumentConfig] = Field(default_factory=lambda: [InstrumentConfig()])
-    repeats: int = 1
+    acquisition_config: AcquisitionConfig = Field(
+        default_factory=AcquisitionConfig, description="Settings for acquiring the target before exposing."
+    )
+    guiding_config: GuidingConfig = Field(
+        default_factory=GuidingConfig, description="Settings for auto-guiding while exposing."
+    )
+    instrument_configs: list[InstrumentConfig] = Field(
+        default_factory=lambda: [InstrumentConfig()],
+        description="Sequence of instrument configurations to run, in order, once per repeat.",
+    )
+    repeats: int = Field(
+        default=1, description="Number of times to repeat the full sequence of instrument configurations."
+    )
 
 
 class ImagingScript(Script):
     """Default script for imaging configs."""
 
-    configuration: Configuration = Field(default_factory=Configuration)
-
-    camera: Annotated[str, ICamera, IBinning, IWindow, IExposureTime, IImageType]
-    telescope: Annotated[str | None, ITelescope, IPointingRaDec] = None
-    filters: Annotated[str | None, IFilters] = None
-    autoguider: Annotated[str | None, IAutoGuiding] = None
-    acquisition: Annotated[str | None, IAcquisition] = None
+    configuration: Configuration = Field(default_factory=Configuration, description="What to expose and how.")
+
+    camera: Annotated[str, ICamera, IBinning, IWindow, IExposureTime, IImageType] = Field(
+        description="Name of the camera module to expose with."
+    )
+    telescope: Annotated[str | None, ITelescope, IPointingRaDec] = Field(
+        default=None, description="Name of the telescope module to point at the target. Required for OBJECT exposures."
+    )
+    filters: Annotated[str | None, IFilters] = Field(
+        default=None, description="Name of the filter wheel module. Required if any instrument config sets a filter."
+    )
+    autoguider: Annotated[str | None, IAutoGuiding] = Field(
+        default=None, description="Name of the auto-guiding module. Required if guiding is enabled."
+    )
+    acquisition: Annotated[str | None, IAcquisition] = Field(
+        default=None, description="Name of the acquisition module. Required if acquisition is enabled."
+    )
 
     _object_name: str | None = PrivateAttr(default=None)
 

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/script.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 from pyobs.interfaces import FitsHeaderEntry
 from pyobs.utils.serialization import PolymorphicBaseModel
 from pyobs.utils.time import Time
@@ -14,7 +16,7 @@ log = logging.getLogger(__name__)
 
 
 class Script(PolymorphicBaseModel):
-    exptime_done: float = 0.0
+    exptime_done: float = Field(default=0.0, description="Exposure time accumulated so far while running this script.")
 
     _cant_run_reason: str | None = None
 

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/utils/callmodule.py

@@ -41,10 +41,12 @@ def _build_params_model(method, provided_keys):
 class CallModuleScript(Script):
     """Script for calling a method on a module."""
 
-    module: str
-    interface: str
-    method: str
-    params: dict[str, str | int | float] = Field(default_factory=dict)
+    module: str = Field(description="Name of the module to call the method on.")
+    interface: str = Field(description="Full class path of the interface that declares `method`.")
+    method: str = Field(description="Name of the method to call.")
+    params: dict[str, str | int | float] = Field(
+        default_factory=dict, description="Keyword arguments to pass to the method, validated against its signature."
+    )
 
     @model_validator(mode="after")
     def _validate_params(self) -> CallModuleScript:

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/utils/debugtrigger.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import logging
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 if TYPE_CHECKING:
     from pyobs.robotic.task import TaskData
 from pyobs.robotic.scripts import Script
@@ -13,7 +15,7 @@ log = logging.getLogger(__name__)
 class DebugTriggerScript(Script):
     """Script for a debug trigger."""
 
-    triggered: bool = False
+    triggered: bool = Field(default=False, description="Set to True once this script has run.")
 
     async def can_run(self, data: TaskData | None) -> bool:
         return True

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/scripts/utils/log.py

@@ -4,6 +4,8 @@ import logging
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
+from pydantic import Field
+
 if TYPE_CHECKING:
     from pyobs.robotic.task import TaskData
 from pyobs.robotic.scripts import Script
@@ -14,7 +16,7 @@ log = logging.getLogger(__name__)
 class LogScript(Script):
     """Script for logging something."""
 
-    expression: str
+    expression: str = Field(description="Python expression to evaluate and log the value of.")
 
     async def can_run(self, data: TaskData | None) -> bool:
         return True

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/utils/skyflats/priorities/archive.py

@@ -1,5 +1,6 @@
 import astropy.units as u
 from astropy.time import TimeDelta
+from pydantic import Field
 
 from pyobs.robotic.utils.archive import Archive
 from pyobs.utils.enums import ImageType
@@ -11,11 +12,11 @@ from .base import SkyflatPriorities
 class ArchiveSkyflatPriorities(SkyflatPriorities):
     """Calculate flat priorities from an archive."""
 
-    archive: Archive
-    site: str
-    instrument: str
-    filter_names: list[str]
-    binnings: list[int]
+    archive: Archive = Field(description="Archive to query for the timestamp of the last flat per filter/binning.")
+    site: str = Field(description="Site code to filter archive frames by.")
+    instrument: str = Field(description="Instrument code to filter archive frames by.")
+    filter_names: list[str] = Field(description="Filters to compute priorities for.")
+    binnings: list[int] = Field(description="Binnings (as N for NxN) to compute priorities for.")
 
     model_config = {"arbitrary_types_allowed": True}
 

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyobs/robotic/utils/skyflats/priorities/const.py

@@ -1,10 +1,14 @@
+from pydantic import Field
+
 from .base import SkyflatPriorities
 
 
 class ConstSkyflatPriorities(SkyflatPriorities):
     """Constant flat priorities."""
 
-    priorities: dict[tuple[str, tuple[int, int]], float]
+    priorities: dict[tuple[str, tuple[int, int]], float] = Field(
+        description="Fixed priority per (filter, binning) combination."
+    )
 
     async def __call__(self) -> dict[tuple[str, tuple[int, int]], float]:
         return self.priorities

{pyobs_core-2.0.0.dev94 → pyobs_core-2.0.0.dev95}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyobs-core"
-version = "2.0.0.dev94"
+version = "2.0.0.dev95"
 description = "robotic telescope software"
 authors = [{ name = "Tim-Oliver Husser", email = "thusser@uni-goettingen.de" }]
 requires-python = ">=3.11"