Ctrl+K

API

Contents

API#

Utilities#

class lib.utility.ByteReader(line: bytes)#

Bases: object

A utility class to read from binary files where each data field corresponds to a byte range in a line.

get(begin: int, end: int, d_type: ~typing.Callable[[bytes], ~lib.utility.T | str] = <function ByteReader.<lambda>>) → T | str#

Get data from the byte-range begin to end and convert it with d_type.

Parameters:

  • begin – beginning of the data range

  • end – end of the data range

  • d_type – A function that takes a bytestring and converts it to some type T, defaults to decoding as utf-8 string.

class lib.utility.DownloadData(url: str, filename: str | None = None, _path: str = '')#

Bases: object

Holds information about downloadable data. Usually the user supplies filename and url and the path is then supplied programatically by download() or lib.catalogfactory.Factory.download_cached().

filename: str | None = None#

the filename that the file shall be saved under

open(*args, **kwargs)#

Open the downloaded file (if it exists).

Corresponds to the built-in io.open() with the first argument presupplied.

property path: str#

The path to the downloaded file.

Raises:

RuntimeError – when the file does not exist (both at assignment and at retrieval)

url: str#

the url where the file shall be downloaded from

lib.utility.download(download_dir: str, download_data: Iterable[DownloadData])#

Downloads a file from DownloadData.url for each member of download_data and saves it in the download_dir.

This function also sets DownloadData.path to the downloaded file.

Catalog Base Class#

The basic plumbing and template for creating custom catalogs.

class lib.catalogfactory.Factory(cache_dir: str, data_dir: str)#

Bases: object

The base class for all catalogs.

Parameters:

  • cache_dir – the path to the cache directory

  • data_dir – the path to the data directory

Each catalog subclasses this class. The class variable meta is overwritten by a catalog to specify catalog metadata.

Because of caching, the modifications to the state of the class instance is not persistent. Therefore the _state , which is persisted by pickling should be used.

These methods are commonly overwritten:

  • The method __post_init__() may be overwritten to perform initialization as an alternative to the constructor.

  • The method get_data() may be overwritten to acquire the catalog data.

  • The method load_objects() may be overwritten to retrieve objects from the catalog data.

  • The method get_dublicates() may be overwritten to identify dublicates between catalogs.

To overwrite those methods is less common:

  • The method is_fresh() may be overwritten to customize the detection of an outdated cache.

property _download_dir#

Path to the download directory for the catalog.

_in_cache_dir(path: str) → str#

Transforms a path relative to the cache directory to an absolute path.

_in_data_dir(path: str) → str#

Transforms a path relative to the data directory to an absolute path.

_in_download_dir(path: str) → str#

Transforms a path relative to the download directory to an absolute path.

_make_catalog_object(*args, **kwargs)#

Constructs a lib.catalogsdb.CatalogObject with the field catalog prebound to the current catalog. All other arguments are passed through to the constructor.

_state#

Storage for persistend state. Is being synced to disk.

property catalog_cache_filename: str#

The path where the catalog is dumped for caching.

property dirname: str#

The filename for the generated catalog. (without extension) Used to label the cache directory.

download_cached(*download_data: DownloadData)#

Download a file and cache it. Uses is_fresh().

property filename: str#

The filename for the generated catalog. (with extension)

get_data() → None#

This method can be overwritten to download catalog data into _download_dir().

See lib.utility.DownloadData and download_cached().

get_dublicates(query_fn: Callable[[str | int, str | None, int], List[CatalogObject]], catalogs: Dict[int, Catalog]) → Iterator[Set[Tuple[int, bytes]]]#

Returns an iterator of sets of catalog-id and object hash pairs. Those sets signify the dublicate objects. The catalog database can be queried by the query_fn which is basically lib.catalogsdb.CatalogsDB.retrieve_objects(). catalogs is a dict of catalog id and meta information.

is_fresh(path: str) → bool#

Returns wether the file under path is to considered fresh to be loaded from cache.

The standard implementation checks if the file’s m-time is more or as recent as the m-time of the module file.

load_objects() → Iterator[CatalogObject]#

A generator that yields lib.catalogsdb.CatalogObject to be inserted into the catalog database.

Should use _make_catalog_object() for convenience.

meta: ClassVar[Catalog]#

holds metadata about a catalog

property state_cache_filename: str#

The directory where the state of the catalog class instance is cached.

lib.catalogfactory.catalog_dirname(meta: Catalog)#

Catalogsdb Interface#

Code to create and manipulate a kstars catalog database.

class lib.catalogsdb.CATALOGS#

Bases: SimpleNamespace

An Enumeration of hardcoded catalog names.

all_objects = 'all_catalogs'#
master = 'master'#
class lib.catalogsdb.Catalog(id: int, name: str, precedence: float = 0, author: str = '', source: str = '', description: str = '', version: int = 0, mut: bool = True, enabled: bool = True, colors: ~typing.Dict[str, str] = <factory>, image: str | None = None, license: str = '', maintainer: str = '', timestamp: ~datetime.datetime = datetime.datetime(2024, 5, 2, 14, 36, 46, 616567))#

Bases: object

Catalog Metadata.

author: str = ''#

The author of the catalog. Is set to the maintainer if not specified.

property color: str#

The color string that will be saved into the database.

colors: Dict[str, str]#

The color that the catalog’s objects are being rendered in as a dict of the form:

{
    'default': '#[hex rgb color code for default color]',
    '[color scheme file name]': '#[hex rgb color code]'
}

The default color is used when the color for a specific color scheme is not specified.

description: str = ''#

A (brief) description. HTML allowed.

enabled: bool = True#

Whether the catalog is enabled. This is irrelevant for catalog creation.

id: int#

The numeric and unique id of the catalog. Should be chosen greater that the biggest previusly given id.

image: str | None = None#

The path of the preview image of the catalog relative to the data directory.

license: str = ''#

License of the catalog.

maintainer: str = ''#

Maintainer, style: “Name <email>”

property maintainer_email: str | None#

The email address of the maintainer.

property maintainer_name: str#

The email address of the maintainer.

mut: bool = True#

Wether the catalog is mutable. This is irrelevant for catalog creation.

name: str#

The name of the catalog.

precedence: float = 0#

The precedence of the catalog. If an dublicate object exists in another catalog with a higher precedence, it will shadow an object from this catalog. Should be between 0 and 1.

source: str = ''#

The source of the catalog. (url, book, etc…)

timestamp: datetime = datetime.datetime(2024, 5, 2, 14, 36, 46, 616567)#

Timestamp (the build time). Will be set by the build process.

to_dict() → dict[str, any]#
version: int = 0#

Version of the catalog. To be incremented for each content update

class lib.catalogsdb.CatalogObject(trixel: int = 0, hash: bytes = b'', oid: bytes = b'', type: int | ~pykstars.ObjectType = <property object>, ra: float = 0, dec: float = 0, magnitude: float | None = None, name: str = '', long_name: str = '', catalog_identifier: str = '', major_axis: float | None = None, minor_axis: float | None = None, position_angle: float | None = None, flux: float | None = None, catalog: int = 0)#

Bases: object

A DSO in the catalog. Just a simple container. No magic!

Parameters:

  • id – oid of the object

  • oid – oid of the object

  • typed – Type of object

  • ra – Right Ascension

  • dec – Declination

  • magnitude – magnitude (brightness)

  • name – Primary name

  • long_name – Long name (common name)

  • catalog_identifier – a catalog specific identifier

  • catalog – catalog id

  • major_axis – major axis (arcminutes)

  • minor_axis – minor axis (arcminutes)

  • position_angle – position angle (degrees)

  • flux – integrated flux (optional)

catalog: int = 0#
catalog_identifier: str = ''#
dec: float = 0#
flux: float | None = None#
hash: bytes = b''#
long_name: str = ''#
magnitude: float | None = None#
major_axis: float | None = None#
minor_axis: float | None = None#
name: str = ''#
oid: bytes = b''#
position_angle: float | None = None#
ra: float = 0#
trixel: int = 0#
property type: int#
class lib.catalogsdb.CatalogsDB(db_filename: str, htmesh_level: int = 3)#

Bases: object

A utility to manipulate a catalog db in the kstars format.

Wraps and augments the kstars python bindings and is usually not required for catalog packaging.

compile_master_catalog() → None#
dump_catalog(catalog_id: int, file_path: str) → None#
property filename#

Returns the filename of the underlying db.

get_catalog(catalog_id: int) → Catalog | None#

Load catalog metadata from the database.

get_object(catalog: int, hash: bytes)#
import_catalog(file_path: str, overwrite: bool) → None#
insert_object(obj: CatalogObject) → None#

Insert an object into a catalog. Regenerates its hash, trixel and also its oid if it is empty.

insert_objects(objs: Iterator[CatalogObject]) → None#

Insert objects into a catalog. Regenerates their hash, trixel and also their oid if it is empty.

process_dupes(dupes: Set[Tuple[int, bytes]], precedence_ordered: List[int])#

Set the object ids of the object to the same value deterministically.

register_catalog(cat: Catalog) → None#

Add a catalog cat to the database.

remove_catalog(id: int) → None#
retrieve_objects(catalog: str | int, query: str | None = None, limit: int = -1) → List[CatalogObject]#

Retrieve objects from the catalog (either id or table name). query is inserted as WHERE clause verbatim. The result list size is limited to limit.

To search all catalogs, use lib.catalogsdb.CATALOGS.all_objects first argument.

update_catalog_meta(cat: Catalog) → None#

Update cat in the database.

lib.catalogsdb.partition(lst: Sequence[T], key_fn: Callable[[T], KeyType]) → Dict[KeyType, List[T]]#

Partition lst by the key determined by key.

lib.catalogsdb.raise_if_not_successful(success: Tuple[bool, str]) → None#

Raise a runtime error if the first entry of success is False.

lib.catalogsdb.row_to_catalogobject(row: Row)#
lib.catalogsdb.strip_None(dct: MutableMapping[Any, Any]) → MutableMapping[Any, Any]#

Strip any entries with None values from dct.

Thin bindings for KStars to facilitate trixel indexation from python.

class pykstars.DBManager#

Bases: pybind11_object

compile_master_catalog(self: pykstars.DBManager) → bool#
dump_catalog(self: pykstars.DBManager, catalog_id: int, file_path: QString) → Tuple[bool, QString]#
import_catalog(self: pykstars.DBManager, file_path: QString, overwrite: bool) → Tuple[bool, QString]#
register_catalog(self: pykstars.DBManager, catalog: dict) → Tuple[bool, QString]#
remove_catalog(self: pykstars.DBManager, catalog_id: int) → Tuple[bool, QString]#
update_catalog_meta(self: pykstars.DBManager, catalog: dict) → Tuple[bool, QString]#
update_catalog_views(self: pykstars.DBManager) → bool#
exception pykstars.DatabaseError#

Bases: Exception

class pykstars.Indexer#

Bases: pybind11_object

get_trixel(self: pykstars.Indexer, ra: float, dec: float, convert_epoch: bool = False) → int#

Calculates the trixel number from the right ascention and the declination. The epoch of coordinates is assumed to be J2000.

If the epoch is B1950, convert_epoch has to be set to True.

property level#

Sets the level of the HTMesh/SkyMesh used to index points.

class pykstars.ObjectType#

Bases: pybind11_object

The types of CatalogObjects

Members:

STAR

CATALOG_STAR

PLANET

OPEN_CLUSTER

GLOBULAR_CLUSTER

GASEOUS_NEBULA

PLANETARY_NEBULA

SUPERNOVA_REMNANT

GALAXY

COMET

ASTEROID

CONSTELLATION

MOON

ASTERISM

GALAXY_CLUSTER

DARK_NEBULA

QUASAR

MULT_STAR

RADIO_SOURCE

SATELLITE

SUPERNOVA

NUMBER_OF_KNOWN_TYPES

TYPE_UNKNOWN

ASTERISM = <ObjectType.ASTERISM: 13>#
ASTEROID = <ObjectType.ASTEROID: 10>#
CATALOG_STAR = <ObjectType.CATALOG_STAR: 1>#
COMET = <ObjectType.COMET: 9>#
CONSTELLATION = <ObjectType.CONSTELLATION: 11>#
DARK_NEBULA = <ObjectType.DARK_NEBULA: 15>#
GALAXY = <ObjectType.GALAXY: 8>#
GALAXY_CLUSTER = <ObjectType.GALAXY_CLUSTER: 14>#
GASEOUS_NEBULA = <ObjectType.GASEOUS_NEBULA: 5>#
GLOBULAR_CLUSTER = <ObjectType.GLOBULAR_CLUSTER: 4>#
MOON = <ObjectType.MOON: 12>#
MULT_STAR = <ObjectType.MULT_STAR: 17>#
NUMBER_OF_KNOWN_TYPES = <ObjectType.NUMBER_OF_KNOWN_TYPES: 21>#
OPEN_CLUSTER = <ObjectType.OPEN_CLUSTER: 3>#
PLANET = <ObjectType.PLANET: 2>#
PLANETARY_NEBULA = <ObjectType.PLANETARY_NEBULA: 6>#
QUASAR = <ObjectType.QUASAR: 16>#
RADIO_SOURCE = <ObjectType.RADIO_SOURCE: 18>#
SATELLITE = <ObjectType.SATELLITE: 19>#
STAR = <ObjectType.STAR: 0>#
SUPERNOVA = <ObjectType.SUPERNOVA: 20>#
SUPERNOVA_REMNANT = <ObjectType.SUPERNOVA_REMNANT: 7>#
TYPE_UNKNOWN = <ObjectType.TYPE_UNKNOWN: 255>#
property name#
property value#
pykstars.get_id(object: dict) → bytes#

Calculate the id of an object.

Parameters#

Contents