API reference

`DB`

A database which holds events and catalogues.

`catalogues` `property`

Returns:

Type	Description
`set[Catalogue]`	The catalogues in the database.

`doc` `property`

Returns:

Type	Description
`Doc`	The database Doc.

`events` `property`

Returns:

Type	Description
`set[Event]`	The events in the database.

`init(doc=None)`

Creates a database.

Parameters:

Name	Type	Description	Default
`doc`	`Doc \| None`	An optional Doc.	`None`

`create_catalogue(*, name, author, uuid=None, tags=None, attributes=None, events=None)`

Creates a catalogue in the database.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the catalogue.	required
`author`	`str`	The author of the catalogue.	required
`uuid`	`UUID \| str \| bytes \| bytearray \| None`	The optional UUID of the catalogue.	`None`
`tags`	`list[str] \| None`	The optional tags of the catalogue.	`None`
`attributes`	`dict[str, Any] \| None`	The optional attributes of the catalogue.	`None`
`events`	`Iterable[Event] \| Event \| None`	The initial event(s) in the catalogue.	`None`

Returns:

Type	Description
`Catalogue`	The created Catalogue.

`create_event(*, start, stop, author, uuid=None, tags=None, products=None, rating=None, attributes=None)`

Creates an event in the database.

Parameters:

Name	Type	Description	Default
`start`	`datetime \| int \| float \| str`	The start date of the event.	required
`stop`	`datetime \| int \| float \| str`	The stop date of the event.	required
`author`	`str`	The author of the event.	required
`uuid`	`UUID \| str \| bytes \| bytearray \| None`	The optional UUID of the event.	`None`
`tags`	`list[str] \| None`	The optional tags of the event.	`None`
`products`	`list[str] \| None`	The optional products of the event.	`None`
`rating`	`int \| None`	The optional rating of the event.	`None`
`attributes`	`dict[str, Any] \| None`	The optional attributes of the catalogue.	`None`

Returns:

Type	Description
`Event`	The created Event.

`from_dict(db_dict, doc=None)` `classmethod`

Creates a database from a dictionary.

Parameters:

Name	Type	Description	Default
`db_dict`	`dict[str, Any]`	The dictionary.	required
`doc`	`Doc \| None`	An optional Doc.	`None`

Returns:

Type	Description
`'DB'`	The created database.

`from_json(data, doc=None)` `classmethod`

Creates a database from a JSON string.

Parameters:

Name	Type	Description	Default
`data`	`str`	The JSON string.	required
`doc`	`Doc \| None`	An optional Doc.	`None`

Returns:

Type	Description
`'DB'`	The created database.

`get_catalogue(uuid_or_name)`

Parameters:

Name	Type	Description	Default
`uuid_or_name`	`UUID \| str`	The UUID of the catalogue to get, or its name.	required

Returns:

Type	Description
`Catalogue`	The catalogue with the given UUID or name.

`get_event(uuid)`

Parameters:

Name	Type	Description	Default
`uuid`	`UUID \| str`	The UUID of the event to get.	required

Returns:

Type	Description
`Event`	The event with the given UUID.

`on_create_catalogue(callback)`

Registers a callback to be called when a catalogue is created.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[Catalogue], None]`	The callback to call with the created catalogue.	required

`on_create_event(callback)`

Registers a callback to be called when an event is created.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[Event], None]`	The callback to call with the created event.	required

`sync(db)`

Keeps the database in sync with another database. Mostly used for tests.

Parameters:

Name	Type	Description	Default
`db`	`'DB'`	The database to keep in sync with this one.	required

`to_dict()`

Returns:

Type	Description
`dict[str, Any]`	The database as a dictionary.

`to_json()`

Returns:

Type	Description
`str`	The database as a JSON string.

`Event` `dataclass`

Bases: Mixin

`attributes` `property` `writable`

Returns:

Type	Description
`dict[str, Any]`	The attributes.

`author` `property` `writable`

Returns:

Type	Description
`str`	The author.

`db` `property`

Returns:

Type	Description
`DB`	The database it belongs to.

`products` `property` `writable`

Returns:

Type	Description
`set[str]`	The products of the event.

`range` `property` `writable`

Returns:

Type	Description
`tuple[datetime, datetime]`	The start and stop dates of the event.

`rating` `property` `writable`

Returns:

Type	Description
`int`	The rating of the event.

`start` `property` `writable`

Returns:

Type	Description
`datetime`	The start date of the event.

`stop` `property` `writable`

Returns:

Type	Description
`datetime`	The stop date of the event.

`tags` `property` `writable`

Returns:

Type	Description
`set[str]`	The tags.

`uuid` `property`

Returns:

Type	Description
`UUID`	The UUID.

`add_products(keys)`

Adds product(s) to the event.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The products to add to the event.	required

`add_tags(keys)`

Adds tags.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The tags to add.	required

`delete()`

Removes the event from the database.

`on_add_products(callback)`

Registers a callback to be called when products are added.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[set[str]], None]`	The callback to call with the added products.	required

`on_add_tags(callback)`

Registers a callback to be called when tags are added.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[set[str]], None]`	The callback to call with the set of added tags.	required

`on_change_author(callback)`

Registers a callback to be called when the event author changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[Any], None]`	The callback to call with the new author.	required

`on_change_range(callback)`

Registers a callback to be called when the event start and/or stop dates change.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[datetime, datetime], None]`	The callback to call with the new range.	required

`on_change_rating(callback)`

Registers a callback to be called when the event rating changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[Any], None]`	The callback to call with the new rating.	required

`on_change_start(callback)`

Registers a callback to be called when the event start date changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[datetime], None]`	The callback to call with the new start date.	required

`on_change_stop(callback)`

Registers a callback to be called when the event stop date changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[datetime], None]`	The callback to call with the new stop date.	required

`on_delete(callback)`

Registers a callback to be called when the event is removed from the database.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[], None]`	The callback to call.	required

`on_remove_attributes(callback)`

Registers a callback to be called when attributes are removed.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[list[str]], None]`	The callback to call with a list of attribute keys that were removed.	required

`on_remove_products(callback)`

Registers a callback to be called when products are removed.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[list[str]], None]`	The callback to call with the removed products.	required

`on_remove_tags(callback)`

Registers a callback to be called when tags are removed:

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[list[str]], None]`	The callback to call with the list of removed tags.	required

`on_set_attributes(callback)`

Registers a callback to be called when attributes are set.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[dict[str, Any]], None]`	The callback to call with a dictionary of attribute items that were set.	required

`remove_attributes(keys)`

Removes attributes.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The attribute keys to remove.	required

`remove_products(keys)`

Removed product(s) from the event.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The products to remove from the event.	required

`remove_tags(keys)`

Removes tags.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The tags to remove.	required

`set_attributes(**kwargs)`

Sets attributes.

Parameters:

Name	Type	Description	Default
`kwargs`	`Any`	The attributes to set.	`{}`

`to_dict()`

Returns:

Type	Description
`dict[str, Any]`	The event as a dictionary.

`Catalogue` `dataclass`

Bases: Mixin

`all_events` `property`

Returns:

Type	Description
`set[Event]`	The (static and dynamic) events in the catalogue.

`attributes` `property` `writable`

Returns:

Type	Description
`dict[str, Any]`	The attributes.

`author` `property` `writable`

Returns:

Type	Description
`str`	The author.

`db` `property`

Returns:

Type	Description
`DB`	The database it belongs to.

`dynamic_events` `property`

Returns:

Type	Description
`set[Event]`	The dynamic events in the catalogue, as defined by `catalogue.set_dynamic_filter(condition)`.

`events` `property` `writable`

Returns:

Type	Description
`set[Event]`	The (static) events in the catalogue.

`name` `property` `writable`

Returns:

Type	Description
`str`	The name of the catalogue.

`tags` `property` `writable`

Returns:

Type	Description
`set[str]`	The tags.

`uuid` `property`

Returns:

Type	Description
`UUID`	The UUID.

`add_events(events)`

Add event(s) to the catalogue.

Parameters:

Name	Type	Description	Default
`events`	`Iterable[Event] \| Event`	The events to add to the catalogue.	required

`add_tags(keys)`

Adds tags.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The tags to add.	required

`delete()`

Removes the catalogue from the database.

`on_add_events(callback)`

Registers a callback to be called when events are added to the catalogue.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[list[Event]], None]`	The callback to call with a list of added events.	required

`on_add_tags(callback)`

Registers a callback to be called when tags are added.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[set[str]], None]`	The callback to call with the set of added tags.	required

`on_change_author(callback)`

Registers a callback to be called when the catalogue author changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[Any], None]`	The callback to call with the new author.	required

`on_change_name(callback)`

Registers a callback to be called when the catalogue name changes.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[str], None]`	The callback to call with the new name.	required

`on_delete(callback)`

Registers a callback to be called when the catalogue is removed from the database.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[], None]`	The callback to call.	required

`on_remove_attributes(callback)`

Registers a callback to be called when attributes are removed.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[list[str]], None]`	The callback to call with a list of attribute keys that were removed.	required

`on_remove_events(callback)`

Registers a callback to be called when events are removed from the catalogue.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[list[str]], None]`	The callback to call with a list of removed event UUIDs.	required

`on_remove_tags(callback)`

Registers a callback to be called when tags are removed:

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[list[str]], None]`	The callback to call with the list of removed tags.	required

`on_set_attributes(callback)`

Registers a callback to be called when attributes are set.

Parameters:

Name	Type	Description	Default
`callback`	`Callable[[dict[str, Any]], None]`	The callback to call with a dictionary of attribute items that were set.	required

`remove_attributes(keys)`

Removes attributes.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The attribute keys to remove.	required

`remove_events(events)`

Removes event(s) from the catalogue.

Parameters:

Name	Type	Description	Default
`events`	`Iterable[Event] \| Event`	The events to remove from the catalogue.	required

`remove_tags(keys)`

Removes tags.

Parameters:

Name	Type	Description	Default
`keys`	`Iterable[str] \| str`	The tags to remove.	required

`set_attributes(**kwargs)`

Sets attributes.

Parameters:

Name	Type	Description	Default
`kwargs`	`Any`	The attributes to set.	`{}`

`set_dynamic_filter(condition=None)`

Sets a condition that will be evaluated when accessing catalogue.dynamic_events. The condition is an expression using the event attributes and/or references to other catalogues, for instance:

catalogue.set_dynamic_filter(f"event.start > datetime(2025, 1, 1) and event.stop <= datetime(2026, 1, 1) and event in catalogue('my_catalogue_name_or_uuid')")

Parameters:

Name	Type	Description	Default
`condition`	`str \| None`	The condition an event needs to match to be part of the catalogue.	`None`

`to_dict(event_as_uuid=False)`

Parameters:

Name	Type	Description	Default
`event_as_uuid`	`bool`	Whether to convert events to their UUID or keep their full content.	`False`

Returns:

Type	Description
`dict[str, Any]`	The catalogue as a dictionary.

`create_catalogue(*, name, author, uuid=None, tags=None, attributes=None, events=None)`

Creates a catalogue in the database.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the catalogue.	required
`author`	`str`	The author of the catalogue.	required
`uuid`	`UUID \| str \| bytes \| bytearray \| None`	The optional UUID of the catalogue.	`None`
`tags`	`list[str] \| None`	The optional tags of the catalogue.	`None`
`attributes`	`dict[str, Any] \| None`	The optional attributes of the catalogue.	`None`
`events`	`Iterable[Event] \| Event \| None`	The initial event(s) in the catalogue.	`None`

Returns:

Type	Description
`Catalogue`	The created Catalogue.

`create_event(*, start, stop, author, uuid=None, tags=None, products=None, rating=None, attributes=None)`

Creates an event in the database.

Parameters:

Name	Type	Description	Default
`start`	`datetime \| int \| float \| str`	The start date of the event.	required
`stop`	`datetime \| int \| float \| str`	The stop date of the event.	required
`author`	`str`	The author of the event.	required
`uuid`	`UUID \| str \| bytes \| bytearray \| None`	The optional UUID of the event.	`None`
`tags`	`list[str] \| None`	The optional tags of the event.	`None`
`products`	`list[str] \| None`	The optional products of the event.	`None`
`rating`	`int \| None`	The optional rating of the event.	`None`
`attributes`	`dict[str, Any] \| None`	The optional attributes of the catalogue.	`None`

Returns:

Type	Description
`Event`	The created Event.

`get_catalogue(uuid_or_name)`

Parameters:

Name	Type	Description	Default
`uuid_or_name`	`UUID \| str`	The UUID or the name of the catalogue to get.	required

Returns:

Type	Description
`Catalogue`	The catalogue with the given UUID or name.

`get_event(uuid)`

Parameters:

Name	Type	Description	Default
`uuid`	`UUID \| str`	The UUID of the event to get.	required

Returns:

Type	Description
`Event`	The event with the given UUID.

`save()`

Sends local changes to the server.

`log_in(username=None, password=None, save_credentials=True, connect=True)`

Log into the server, optionally save the credentials and connect to a room.

Parameters:

Name	Type	Description	Default
`username`	`str \| None`	The username to use to log in.	`None`
`password`	`str \| None`	The password to use to log in.	`None`
`save_credentials`	`bool`	Whether to save the given username and/or password.	`True`
`connect`	`bool`	Whether to connect to a room after logging in.	`True`

`log_out()`

Log out of the server.

`refresh()`

Receives remote changes from the server.

`set_config(*, host=None, port=None, file_path=None, room_id=None)`

Sets the configuration of the current session.

Parameters:

Name	Type	Description	Default
`host`	`str \| None`	The host name of the database web server.	`None`
`port`	`int \| None`	The port number of the database web server.	`None`
`file_path`	`str \| None`	The path to the file where updates will be stored.	`None`
`room_id`	`str \| None`	The ID of the room to connect to.	`None`

`export_votable_str(catalogues)`

Exports catalogues as a VOTable XML string.

Parameters:

Name	Type	Description	Default
`catalogues`	`Sequence[Catalogue] \| Catalogue`	The catalogue(s) to export.	required

Returns:

Type	Description
`str`	The VOTable as an XML string.

`export_votable_file(catalogues, file_path)`

Exports catalogues to a VOTable file.

Parameters:

Name	Type	Description	Default
`catalogues`	`Sequence[Catalogue] \| Catalogue`	The catalogue(s) to export.	required
`file_path`	`str \| Path`	The path to the exported file.	required

`import_votable_str(xml_content, db, table_name=None)`

Imports a VOTable XML string into a database.

Parameters:

Name	Type	Description	Default
`xml_content`	`str`	The VOTable content as an XML string.	required
`db`	`DB`	The database into which to import the VOTable.	required

`import_votable_file(file_path, db, table_name=None)`

Imports a VOTable file into a database.

Parameters:

Name	Type	Description	Default
`file_path`	`str \| Path`	The VOTable file path.	required
`db`	`DB`	The database into which to import the VOTable.	required

API reference

DB

catalogues property

doc property

events property

__init__(doc=None)

create_catalogue(*, name, author, uuid=None, tags=None, attributes=None, events=None)

create_event(*, start, stop, author, uuid=None, tags=None, products=None, rating=None, attributes=None)

from_dict(db_dict, doc=None) classmethod

from_json(data, doc=None) classmethod

get_catalogue(uuid_or_name)

get_event(uuid)

on_create_catalogue(callback)

on_create_event(callback)

sync(db)

to_dict()

to_json()

Event dataclass

attributes property writable

author property writable

db property

products property writable

range property writable

rating property writable

start property writable

stop property writable

tags property writable

uuid property

add_products(keys)

add_tags(keys)

delete()

on_add_products(callback)

on_add_tags(callback)

on_change_author(callback)

on_change_range(callback)

on_change_rating(callback)

on_change_start(callback)

on_change_stop(callback)

on_delete(callback)

on_remove_attributes(callback)

on_remove_products(callback)

on_remove_tags(callback)

on_set_attributes(callback)

remove_attributes(keys)

remove_products(keys)

remove_tags(keys)

set_attributes(**kwargs)

to_dict()

Catalogue dataclass

all_events property

attributes property writable

author property writable

db property

dynamic_events property

events property writable

name property writable

tags property writable

uuid property

add_events(events)

add_tags(keys)

delete()

on_add_events(callback)

on_add_tags(callback)

on_change_author(callback)

on_change_name(callback)

on_delete(callback)

on_remove_attributes(callback)

on_remove_events(callback)

on_remove_tags(callback)

on_set_attributes(callback)

remove_attributes(keys)

remove_events(events)

remove_tags(keys)

set_attributes(**kwargs)

set_dynamic_filter(condition=None)

to_dict(event_as_uuid=False)

create_catalogue(*, name, author, uuid=None, tags=None, attributes=None, events=None)

create_event(*, start, stop, author, uuid=None, tags=None, products=None, rating=None, attributes=None)

get_catalogue(uuid_or_name)

get_event(uuid)

`DB`

`catalogues` `property`

`doc` `property`

`events` `property`

`init(doc=None)`

`create_catalogue(*, name, author, uuid=None, tags=None, attributes=None, events=None)`

`create_event(*, start, stop, author, uuid=None, tags=None, products=None, rating=None, attributes=None)`

`from_dict(db_dict, doc=None)` `classmethod`

`from_json(data, doc=None)` `classmethod`

`get_catalogue(uuid_or_name)`

`get_event(uuid)`

`on_create_catalogue(callback)`

`on_create_event(callback)`

`sync(db)`

`to_dict()`

`to_json()`

`Event` `dataclass`

`attributes` `property` `writable`

`author` `property` `writable`

`db` `property`

`products` `property` `writable`

`range` `property` `writable`

`rating` `property` `writable`

`start` `property` `writable`

`stop` `property` `writable`

`tags` `property` `writable`

`uuid` `property`

`add_products(keys)`

`add_tags(keys)`

`delete()`

`on_add_products(callback)`

`on_add_tags(callback)`

`on_change_author(callback)`

`on_change_range(callback)`

`on_change_rating(callback)`

`on_change_start(callback)`

`on_change_stop(callback)`

`on_delete(callback)`

`on_remove_attributes(callback)`

`on_remove_products(callback)`

`on_remove_tags(callback)`

`on_set_attributes(callback)`

`remove_attributes(keys)`

`remove_products(keys)`

`remove_tags(keys)`

`set_attributes(**kwargs)`

`to_dict()`

`Catalogue` `dataclass`

`all_events` `property`

`attributes` `property` `writable`

`author` `property` `writable`

`db` `property`

`dynamic_events` `property`

`events` `property` `writable`

`name` `property` `writable`

`tags` `property` `writable`

`uuid` `property`

`add_events(events)`

`add_tags(keys)`

`delete()`

`on_add_events(callback)`

`on_add_tags(callback)`

`on_change_author(callback)`

`on_change_name(callback)`

`on_delete(callback)`

`on_remove_attributes(callback)`

`on_remove_events(callback)`

`on_remove_tags(callback)`

`on_set_attributes(callback)`

`remove_attributes(keys)`

`remove_events(events)`

`remove_tags(keys)`

`set_attributes(**kwargs)`

`set_dynamic_filter(condition=None)`

`to_dict(event_as_uuid=False)`

`create_catalogue(*, name, author, uuid=None, tags=None, attributes=None, events=None)`

`create_event(*, start, stop, author, uuid=None, tags=None, products=None, rating=None, attributes=None)`

`get_catalogue(uuid_or_name)`

`get_event(uuid)`

`save()`