API Reference

Exceptions

API reference for all CentauroDB exception classes.

All exceptions are importable from centaurodb:

from centaurodb import (
    ObjectNotFoundError,
    ObjectAlreadyPersistedError,
    ObjectNotPersistedError,
    UnlinkedParentError,
    ParentHasChildrenError,
    ViewAlreadyExistsError,
    ValuesNotHydratedError,
    ThreadSafetyError,
)

ObjectNotFoundError

Raised when read_object_by_id() finds no matching row.

try:
    coll.read_object_by_id(999, Sensor)
except ObjectNotFoundError as e:
    print(e.model_name)   # "Sensor"
    print(e.id)           # 999
    print(e.collection)   # "monitoring"
    print(e.table)        # "monitoring_objects"

ObjectAlreadyPersistedError

Raised when write_object() is called on an object that has already been written.

obj = Sensor(unit="C")
coll.write_object(obj)
coll.write_object(obj)  # raises ObjectAlreadyPersistedError

Attribute	Type	Description
`model_name`	`str`	Name of the model class
`id`	`int`	Row id of the already-persisted object
`collection`	`str`	Collection name
`table`	`str`	Backing table name

Use duplicate=True to insert a new row, or update_object() to update the existing one.

ObjectNotPersistedError

Raised when an operation requires a persisted object but the object hasn't been written to the database yet. This includes:

update_object() — called on an object that was never written
write_child(), children_of() — called with an unpersisted parent object

obj = Sensor(unit="C")
coll.update_object(obj)  # raises ObjectNotPersistedError

# Also raised for an unpersisted parent:
portfolio = Portfolio(strategy="momentum")  # not yet written
coll.write_child(trade, parent=portfolio)    # raises ObjectNotPersistedError
coll.children_of(portfolio, Trade)          # raises ObjectNotPersistedError

Attribute	Type	Description
`model_name`	`str`	Name of the model class
`collection`	`str`	Collection name
`table`	`str`	Backing table name

Use write_object() to persist the object first.

Raised when write_object() or update_object() is called on a child that has unset parent_ref fields. Every parent_ref must be linked to a persisted parent before writing or updating. See the Relations guide for linking patterns.

trade = Trade(symbol="AAPL")  # trade.portfolio is None
coll.write_object(trade)       # raises UnlinkedParentError

Attribute	Type	Description
`model_name`	`str`	Name of the child model class
`field`	`str`	The `parent_ref` field that is `None`
`parent_model_name`	`str`	Name of the expected parent model class

Use collection.write_child() or set the parent_ref field directly before writing.

ParentHasChildrenError

Raised when delete_object() or delete_objects() targets a parent that still has child rows referencing it via a parent_ref field with on_delete="restrict" (the default). The parent row is left untouched. See Relations — Deleting parents and children.

quest = Quest(name="The Odyssey")
coll.write_object(quest)
coll.write_child(Task(title="Escape the Cyclops"), parent=quest)

coll.delete_object(quest)  # raises ParentHasChildrenError

# Delete the children first, then the parent
coll.delete_objects(Task.fields.quest == quest.row.id)
coll.delete_object(quest)  # works

Attribute	Type	Description
`parent_class`	`str`	Name of the parent model class
`child_class`	`str`	Name of the child model class that still has rows
`field`	`str`	The `parent_ref` field on the child
`collection`	`str`	Collection name

Note that parent_class and child_class are class names (strings), not the classes themselves.

ViewAlreadyExistsError

Raised when create_view() is called for a view that already exists.

coll.create_view("dashboard", Sensor)
coll.create_view("dashboard", Sensor)  # raises ViewAlreadyExistsError

Attribute	Type	Description
`view_name`	`str`	Name of the existing view
`collection`	`str`	Collection name

Use overwrite=True to replace the existing view.

ValuesNotHydratedError

Raised when accessing .df on a time-series model whose values haven't been loaded. See Time-Series — Skip loading values for details.

station = stations.read_object_by_id(1, WeatherStation, hydrate_values=False)
station.df  # raises ValuesNotHydratedError

ThreadSafetyError

Raised when creating an AsyncCollection or AsyncTimeSeriesCollection with an engine that has check_same_thread=True (the SQLite default). See Async Support for the correct setup.

engine = Engine("my.db")  # check_same_thread=True by default
AsyncCollection(engine, "monitoring")  # raises ThreadSafetyError

Fix by setting check_same_thread=False:

engine = Engine("my.db", check_same_thread=False)
AsyncCollection(engine, "monitoring")  # works

Edit this pageorReport an issue

Models

API reference for CentauroModel, CentauroModelSeries, CentauroValues, and RowFields.