hipercam.instruments

Protocols and optional abstract base classes for supporting third-party instruments as first-class citizens in the hipercam pipeline.

Plugin discovery is via the hipercam.instruments entry-point group. Third-party packages register themselves with an entry pointing to a module that satisfies InstrumentModuleProtocol.

Example pyproject.toml registration:

[project.entry-points."hipercam.instruments"]
myinstrument = "mypackage.mymodule"

The registered module must expose:

• Rdata — data-reading class (iterable, callable, context-manager)

• supports_server_access — boolean indicating if server access is supported

• get_ccd_pars(resource, server=False) — returns CCD geometry as an OrderedDict

Convenience base class RdataBase is provided for plugin authors who want to reduce boilerplate, but inheriting from it is not required.

Exceptions

IendError

Exception for the standard way to reach the end of a raw data file.

Classes

RdataBase

Optional ABC for data-reading classes.

Functions

discover_instruments(→ dict)	Discover all registered instrument plugins.
available_instruments(→ list)	Return a list of available instrument plugins.
load_instrument(name)	Load and validate a named instrument plugin.

Module Contents

exception hipercam.instruments.IendError

Bases: hipercam.HipercamError

Exception for the standard way to reach the end of a raw data file.

Raised when an attempt is made to read a frame beyond the end of the available data. This allows iterators to die silently on normal end-of-file while still propagating unexpected errors.

class hipercam.instruments.RdataBase

Bases: abc.ABC

Optional ABC for data-reading classes.

Allows for subclasses to be used as a context manager by providing __enter__() and __exit__() methods that delegate to __del__().

__next__() catches IendError and converts it to StopIteration, allowing use of Rdata as an iterator in a for loop or comprehension.

Subclasses must implement __call__(), seek_frame(), and seek_last().

__enter__()

__exit__(*args)

__iter__()

__next__()

abstract __del__()

Release any resources held by this reader, e.g. open file handles.

abstract __call__(nframe: int | None = None)

Reads one exposure from the run the Rdata is attached to. If nframe is None, then it will read the frame it is positioned at. If nframe is an integer > 0, it will try to read that particular frame; if nframe == 0, it reads the last complete frame. nframe == 1 gives the first frame. If all works, an MCCD object is returned. It raises an HendError if it reaches the end of a local disk file. If it fails to read from the server it returns None, but does not raise an Exception in order to allow continued attempts as reading from what might be a growing file.

It maintains an attribute ‘nframe’ corresponding to the frame that the file pointer is positioned to read next (most relevant to reading of a local file). If it is set to read the last file and that file doesn’t change it returns None as a sign of failure.

Parameters:

nframeint

frame number to get, starting at 1. 0 for the last (complete) frame. ‘None’ indicates that the next frame is wanted, unless self.nframe = 0 in which case it will try to get the most recent frame, whatever that is.

Apart from reading the raw bytes, the main job of this routine is to divide up and re-package the bytes read into Windows suitable for constructing CCD objects.

If access via a server is requested, it is assumed that the file being accessed could be being added to.

hipercam.instruments.discover_instruments() → dict

Discover all registered instrument plugins.

Returns a dict mapping instrument name to its importlib.metadata.EntryPoint object.

Built-in instruments (hipercam, ultracam, ultraspec) are always present when the hipercam package is installed, because they are registered in hipercam’s own pyproject.toml.

Example:

from hipercam.instruments import discover_instruments
for name, ep in discover_instruments().items():
    print(name, ep)

hipercam.instruments.available_instruments() → list

Return a list of available instrument plugins.

This is useful to provide a list of possible values for “resource” in the command line scripts like reduce, which expands when plugins are added.

Example:

from hipercam.instruments import available_instruments
print(available_instruments())

hipercam.instruments.load_instrument(name: str)

Load and validate a named instrument plugin.

Loads the module registered under the hipercam.instruments entry-point group with the given name, checks that it exposes all required attributes, and returns it.

Parameters:

namestr

The instrument name as registered in the entry-point group, e.g. 'hipercam', 'ultracam', 'ultraspec'.

Returns:

module

The loaded instrument module.

Raises:

HipercamError

If no plugin with that name is registered, or if the loaded module is missing required attributes.