API Reference

All of the following can be imported from paramdb.

Parameter Data

class ParamData

Abstract base class for all parameter data.

to_dict() → dict[str, Any]

Return a dictionary representation of this parameter data object, which can be used to reconstruct the object by passing it to from_dict().

classmethod from_dict(data_dict: dict[str, Any]) → Self

Construct a parameter data object from the given dictionary, usually created by json.loads() and originally constructed by from_dict().

property last_updated: datetime

When any parameter within this parameter data was last updated.

property parent: ParamData

Parent of this parameter data. The parent is defined to be the ParamData object that most recently had this object added as a child.

Raises a ValueError if there is currently no parent, which can occur if the parent is still being initialized.

property root: ParamData

Root of this parameter data. The root is defined to be the first object with no parent when going up the chain of parents.

class ParamInt(x: ConvertibleToInt = 0, /)

class ParamInt(x: str | bytes | bytearray, /, base: SupportsIndex = 10)

Subclass of ParamData and int.

Parameter data integer. All int methods and operations are available; however, note that ordinary int objects will be returned.

property value: int

Primitive value stored by this parameter primitive.

class ParamFloat(x: ConvertibleToFloat = 0.0, /)

Subclass of ParamData and float.

Parameter data float. All float methods and operations are available; however, note that ordinary float objects will be returned.

property value: float

Primitive value stored by this parameter primitive.

class ParamBool(x: object = False, /)

Subclass of ParamInt.

Parameter data boolean. All int and bool methods and operations are available; however, note that ordinary int objects (0 or 1) will be returned.

property value: bool

Primitive value stored by this parameter primitive.

class ParamStr(object: object = '', /)

class ParamStr(object: Buffer = b'', encoding: str = 'utf-8', errors: str = 'strict')

Subclass of ParamData and str.

Parameter data string. All str methods and operations are available; however, note that ordinary str objects will be returned.

property value: str

Primitive value stored by this parameter primitive.

class ParamNone

Subclass of ParamData.

Parameter data None. Just like None, its truth value is false.

property value: None

Primitive value stored by this parameter primitive.

class ParamDataclass(*args: Any, **kwargs: Any)

Subclass of ParamData.

Base class for parameter data classes. Subclasses are automatically converted to data classes. For example:

class CustomParam(ParamDataclass):
    value1: float
    value2: int

Any class keyword arguments (other than those described below) given when creating a subclass are passed internally to the @dataclass() decorator.

If Pydantic is installed, then subclasses will have Pydantic runtime validation enabled by default. This can be disabled using the class keyword argument type_validation. The following Pydantic configuration values are set by default:

• extra: 'forbid' (forbid extra attributes)

• validate_assignment: True (validate on assignment as well as initialization)

• arbitrary_types_allowed: True (allow arbitrary type hints)

• strict: True (disable value coercion, e.g. ‘2’ -> 2)

• validate_default: True (validate default values)

Pydantic configuration options can be updated using the class keyword argument pydantic_config, which will merge new options with the existing configuration. See https://docs.pydantic.dev/latest/api/config for full configuration options.

class ParamFile(path: str, initial_data: InitVar[T | None] = None)

Subclass of ParamDataclass.

Base class for parameter file classes. Subclasses must implement the abstract methods _save_data() and _load_data(). For example:

class ParamText(ParamFile[str]):
    def _save_data(self, path: str, data: str) -> None:
        with open(path, "w", encoding="utf-8") as f:
            f.write(data)

    def _load_data(self, path: str) -> str:
        with open(path, "r", encoding="utf-8") as f:
            return f.read()

path: str

Path to the file represented by this object.

property data: T

Data stored in the file represented by this object.

update_data(data: T) → None

Update the data stored within the file represented by this object.

class ParamDataFrame(path: str, initial_data: InitVar[T | None] = None)

Subclass of ParamFile.

Parameter data Pandas DataFrame, stored in a CSV file (with no index). This class will only be defined if Pandas is installed.

class ParamList(iterable: Iterable[T] | None = None)

Subclass of ParamData and MutableSequence.

Mutable sequence that is also parameter data. It can be initialized from any iterable (like builtin list).

class ParamDict(mapping: Mapping[str, T] | None = None, /, **kwargs: T)

Subclass of ParamData and MutableMapping.

Mutable mapping that is also parameter data. It can be initialized from any mapping or using keyword arguments (like builtin dict).

Keys that do not begin with an underscore can be set via dot notation. Keys, values, and items are returned as dict_keys, dict_values, and dict_items objects.

class ParentType

Mixin for ParamData that sets the type hint for ParamData.parent to type parameter PT. For example:

class CustomParam(ParentType[ParentParam], Param):
    ...

Note that if the parent actually has a different type, the type hint will be incorrect.

class RootType

Mixin for ParamData that sets the type hint for ParamData.root to type parameter PT. For example:

class CustomParam(RootType[RootParam], Param):
    ...

Note that if the root actually has a different type, the type hint will be incorrect.

Database

class ParamDB(path: str)

Parameter database. The database is created in a file at the given path if it does not exist. To work with type checking, this class can be parameterized with a root data type T. For example:

from paramdb import ParamDataclass, ParamDB

class Root(ParamDataclass):
    ...

param_db = ParamDB[Root]("path/to/param.db")

property path: str

Path of the database file.

commit(message: str, data: T, timestamp: datetime | None = None) → CommitEntry

Commit the given data to the database with the given message and return a commit entry for the new commit.

By default, the timestamp will be set to the current time. If a timestamp is given, it is used instead. Naive datetimes will be assumed to be in UTC time.

property num_commits: int

Number of commits in the database.

load(commit_id: int | None = None, *, load_classes: Literal[True] = True) → T

load(commit_id: int | None = None, *, load_classes: Literal[False]) → Any

Load and return data from the database. If a commit ID is given, load from that commit; otherwise, load from the most recent commit. Raise an IndexError if the specified commit does not exist. Note that commit IDs begin at 1.

By default, parameter data, datetime, and Astropy Quantity classes are reconstructed. The relevant parameter data classes must be defined in the current program. However, if load_classes is False, classes are loaded directly from the database as dictionaries with the class name in the key CLASS_NAME_KEY.

load_commit_entry(commit_id: int | None = None) → CommitEntry

Load and return a commit entry from the database. If a commit ID is given, load that commit entry; otherwise, load the most recent commit entry. Raise an IndexError if the specified commit does not exist. Note that commit IDs begin at 1.

commit_history(start: int | None = None, end: int | None = None) → list[CommitEntry]

Retrieve the commit history as a list of CommitEntry objects between the provided start and end indices, which work like slicing a Python list.

commit_history_with_data(start: int | None = None, end: int | None = None, *, load_classes: Literal[True] = True) → list[CommitEntryWithData[T]]

commit_history_with_data(start: int | None = None, end: int | None = None, *, load_classes: Literal[False]) → list[CommitEntryWithData[Any]]

Retrieve the commit history with data as a list of CommitEntryWithData objects between the provided start and end indices, which work like slicing a Python list.

See ParamDB.load() for the behavior of load_classes.

dispose() → None

Dispose of the underlying SQLAlchemy connection pool. Usually this method does not need to be called since disposal happens automatically when the database is garbage collected, and typically only one global database object should be used. However, there are certain cases where it is useful to fully dispose of a database before the end of the program, such as when running a test suite. See https://docs.sqlalchemy.org/en/20/core/connections.html#engine-disposal for more information.

class CommitEntry(id: int, message: str, timestamp: datetime)

Entry for a commit containing the ID, message, and timestamp.

id: int

Commit ID.

message: str

Commit message.

timestamp: datetime

When this commit was created.

class CommitEntryWithData(id: int, message: str, timestamp: datetime, data: T)

Subclass of CommitEntry.

Entry for a commit containing the ID, message, and timestamp, as well as the data.

data: T

Data contained in this commit.

CLASS_NAME_KEY = '__type'

Dictionary key corresponding to an object’s class name in the JSON representation of a ParamDB commit.