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: Callable[[bytes], Union[T, str]] = <function ByteReader.<lambda>>) → Union[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: Optional[str] = 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: Optional[str] = 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

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[lib.utility.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

The path where the catalog is dumped for caching.

property dirname

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

download_cached(*download_data: lib.utility.DownloadData)

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

property filename

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[[Union[str, int], Optional[str], int], List[lib.catalogsdb.CatalogObject]], catalogs: Dict[int, lib.catalogsdb.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[lib.catalogsdb.CatalogObject]

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

Should use _make_catalog_object() for convenience.

meta: ClassVar[lib.catalogsdb.Catalog]

holds metadata about a catalog

property state_cache_filename

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

lib.catalogfactory.catalog_dirname(meta: lib.catalogsdb.Catalog)

Catalogsdb Interface

Code to create and manipulate a kstars catalog database.

class lib.catalogsdb.CATALOGS(value)

Bases: str, enum.Enum

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, color: str = '', image: Optional[str] = None, license: str = '', maintainer: str = '', timestamp: datetime.datetime = datetime.datetime(2021, 8, 11, 15, 18, 23, 372537))

Bases: object

Catalog Metadata.

author: str = ''

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

color: str = ''

The color that the catalog’s objects are being rendered in

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: Optional[str] = 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

The email address of the maintainer.

property maintainer_name

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.datetime(2021, 8, 11, 15, 18, 23, 372537)

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

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: Union[int, pykstars.ObjectType] = <property object>, ra: float = 0, dec: float = 0, magnitude: Optional[float] = None, name: str = '', long_name: str = '', catalog_identifier: str = '', major_axis: Optional[float] = None, minor_axis: Optional[float] = None, position_angle: Optional[float] = None, flux: Optional[float] = 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: Optional[float] = None
hash: bytes = b''
long_name: str = ''
magnitude: Optional[float] = None
major_axis: Optional[float] = None
minor_axis: Optional[float] = None
name: str = ''
oid: bytes = b''
position_angle: Optional[float] = None
ra: float = 0
trixel: int = 0
property type
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) → Optional[lib.catalogsdb.Catalog]

Load catalog metadata from the database.

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

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

insert_objects(objs: Iterator[lib.catalogsdb.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: lib.catalogsdb.Catalog) → None

Add a catalog cat to the database.

remove_catalog(id: int) → None
retrieve_objects(catalog: Union[str, int], query: Optional[str] = None, limit: int = - 1) → List[lib.catalogsdb.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: lib.catalogsdb.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: sqlite3.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_builtins.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_builtins.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_builtins.pybind11_object

The types of CatalogObjects

Members:

STAR

CATALOGSTAR

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>
CATALOGSTAR = <ObjectType.CATALOGSTAR: 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.

Available Catalogs