Merge branch 'main' into #14-add-range-option-for-paramdbcommit_history

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ on:
 
 env:
   PYTHON_VERSION: "3.10"
-  POETRY_VERSION: "1.3.2"
+  POETRY_VERSION: "1.4.0"
 
 jobs:
   ci:

.github/workflows/github-pages.yml

@@ -5,7 +5,7 @@ on: workflow_dispatch
 env:
   PYTHON_VERSION: "3.10"
   POETRY_VERSION: "1.3.2"
-  PARAMDB_VERSION: "0.1.0"
+  PARAMDB_VERSION: "0.2.0"
 
 jobs:
   build:

.gitignore

@@ -12,9 +12,8 @@ jupyter_execute/
 # Python
 __pycache__/
 .mypy_cache/
-.coverage
 .pytest_cache/
-.ipynb_checkpoints/
+.coverage
 
 # Data files
 *.db

CHANGELOG.md

@@ -7,14 +7,30 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-- Implement loading data from a specified commit ID
+## [0.2.0] (Mar 8 2023)
+
+### Added
+
+- Ability to specify commit ID in `ParamDB.load()`
+- `ParamData.parent` and `ParamData.root` properties
+- Mixins `ParentType[PT]` and `RootType[PT]` to type cast parent and root
+- Parameter collection classes `ParamList` and `ParamDict`
+- Database now ignores dataclass fields where `init` is `False`
+
+### Removed
+
+- `CommitNotFoundError` (replaced with built-in `IndexError`)
+- Private `_last_updated` dataclass field in parameter dataclasses
 
 ## [0.1.0] (Feb 24 2023)
 
-- Create parameter data classes (`Param` and `Struct`)
-- Create database class `ParamDB` to store parameters in a SQLite file
-- Add ability to retrieve the commit history as `CommitEntry` objects
-- Create [documentation website](https://painterqubits.github.io/paramdb)
+### Added
+
+- Parameter data base class `ParamData`
+- Parameter base dataclasses (`Param` and `Struct`)
+- Database class `ParamDB` to store parameters in a SQLite file
+- Ability to retrieve the commit history as `CommitEntry` objects
 
-[unreleased]: https://github.com/PainterQubits/paramdb/compare/v0.1.0...main
+[unreleased]: https://github.com/PainterQubits/paramdb/compare/v0.2.0...main
+[0.2.0]: https://github.com/PainterQubits/paramdb/releases/tag/v0.2.0
 [0.1.0]: https://github.com/PainterQubits/paramdb/releases/tag/v0.1.0

README.md

@@ -16,24 +16,33 @@ Install the latest version of ParamDB using pip:
 pip install -U paramdb --extra-index-url https://painterqubits.github.io/paramdb/releases
 ```
 
-The `extra-index-url` parameter is needed since ParamDB is not published to PyPI yet.
+The `extra-index-url` parameter is needed since ParamDB is not published to PyPI yet. If
+you are using a Python package manager, add
+`https://painterqubits.github.io/paramdb/releases` as a secondary source. For example, for
+[Poetry] the command is
+
+```
+poetry source add --secondary paramdb https://painterqubits.github.io/paramdb/releases
+```
+
+Then the package can be installed like any other (e.g. `poetry add paramdb`).
+
+[poetry]: https://python-poetry.org
 
 <!-- end installation -->
 
 ## Usage
 
 ParamDB has two main components:
 
-- **Parameted Data**: Base classes that are used to defined the structure of parameter
-  data, which consists of parameters
-  ([`Param`](https://painterqubits.github.io/paramdb/api-reference#paramdb.Param)) and
-  groups of parameters, called structures
-  ([`Struct`](https://painterqubits.github.io/paramdb/api-reference#paramdb.Struct)).
+- [**Parameter Data**]: Base classes that are used to defined the structure and
+  functionality of parameter data.
+
+- [**Database**]: A database object that commits and loads parameter data to a persistent
+  file.
 
-- **Database**: A database object
-  ([`ParamDB`](https://painterqubits.github.io/paramdb/api-reference#paramdb.ParamDB))
-  that commits and loads parameter data to a persistent file.
+See the [api reference] for more information.
 
-See the [usage page](https://painterqubits.github.io/paramdb/usage) on the documentation
-website for examples and more information. Also see the
-[api reference](https://painterqubits.github.io/paramdb/api-reference).
+[**parameter data**]: https://painterqubits.github.io/paramdb/parameter-data.html
+[**database**]: https://painterqubits.github.io/paramdb/database.html
+[api reference]: https://painterqubits.github.io/paramdb/api-reference

docs/_static/jupyter-sphinx.css

@@ -0,0 +1,9 @@
+/* Override styles for Jupyter Sphinx. */
+
+.jupyter_container .cell_input > div {
+  margin-bottom: 0.4rem;
+}
+
+.jupyter_container .cell_output > div {
+  margin-top: 0;
+}

docs/api-reference.md

@@ -10,26 +10,36 @@
 .. autoclass:: ParamData
 ```
 
+```{eval-rst}
+.. autoclass:: Param
+```
+
 ```{eval-rst}
 .. autoclass:: Struct
-   :show-inheritance:
 ```
 
 ```{eval-rst}
-.. autoclass:: Param
-   :show-inheritance:
+.. autoclass:: ParamList
 ```
 
-## Database
+```{eval-rst}
+.. autoclass:: ParamDict
+```
 
 ```{eval-rst}
-.. autoclass:: ParamDB
+.. autoclass:: ParentType
 ```
 
 ```{eval-rst}
-.. autoclass:: CommitEntry
+.. autoclass:: RootType
+```
+
+## Database
+
+```{eval-rst}
+.. autoclass:: ParamDB
 ```
 
 ```{eval-rst}
-.. autoclass:: CommitNotFoundError
+.. autoclass:: CommitEntry
 ```

docs/conf.py

@@ -1,40 +1,39 @@
-# pylint: skip-file
-# type: ignore
-
 # See https://www.sphinx-doc.org/en/master/usage/configuration.html for all options
 
 # Project information
 project = "ParamDB"
 copyright = "2023, California Institute of Technology"
 author = "Alex Hadley"
-release = "0.1.0"
+release = "0.2.0"
 
 # General configuration
 extensions = [
     "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
-    "sphinx_rtd_theme",
     "sphinx_copybutton",
     "jupyter_sphinx",
 ]
 
 # HTML output options
-html_theme = "sphinx_rtd_theme"
-html_theme_options = {"navigation_depth": 3}
+html_theme = "furo"
+html_static_path = ["_static"]
 
 # MyST options
 myst_heading_anchors = 3
 
 # Autodoc options
 # See https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
 autodoc_default_options = {"members": True, "member-order": "bysource"}
+autodoc_inherit_docstrings = False
 
 
 # Autodoc custom signature and return annotation processing
 def process_signature(app, what, name, obj, options, signature, return_annotation):
     if isinstance(signature, str):
         signature = signature.replace("~", "")
+        signature = signature.replace("collections.abc.", "")
+        signature = signature.replace("paramdb._param_data._collections.", "")
         signature = signature.replace("paramdb._database.", "")
     if isinstance(return_annotation, str):
         return_annotation = return_annotation.replace("paramdb._database.", "")

docs/database.md

@@ -0,0 +1,99 @@
+# Database
+
+```{py:currentmodule} paramdb
+
+```
+
+<!-- Jupyter Sphinx setup -->
+
+```{jupyter-execute}
+:hide-code:
+
+from __future__ import annotations
+import os
+from tempfile import TemporaryDirectory
+tmp_dir = TemporaryDirectory()
+os.chdir(tmp_dir.name)
+os.makedirs("path/to")
+```
+
+The database is represented by a {py:class}`ParamDB` object. A path is passed, and a new
+database file is created if it does not already exist. We can parameterize the class with
+the root data type in order for its methods (e.g. {py:meth}`ParamDB.commit`) work properly
+with type checking. For example:
+
+```{jupyter-execute}
+from dataclasses import dataclass
+from paramdb import Struct, Param, ParamDB
+
+@dataclass
+class Root(Struct):
+    param: CustomParam
+
+@dataclass
+class CustomParam(Param):
+    value: float
+
+param_db = ParamDB[Root]("path/to/param.db")
+```
+
+```{important}
+The {py:class}`ParamDB` object should be created once per project and imported by other
+files that access the database.
+```
+
+```{note}
+Dataclass fields created with `init=False` will not be stored in or restored from the
+database. See [`dataclasses.field`] for more information.
+```
+
+## Commit and Load
+
+Data can be committed using {py:meth}`ParamDB.commit` and loaded using
+{py:meth}`ParamDB.load`, which either loads the most recent commit, or takes a specific
+commit ID. Note that commit IDs start from 1. For example:
+
+```{jupyter-execute}
+root = Root(param=CustomParam(value=1.23))
+param_db.commit("Initial commit", root)
+root.param.value += 1
+param_db.commit("Increment param value", root)
+```
+
+We can then load the most recent commit:
+
+```{jupyter-execute}
+param_db.load()
+```
+
+Or a specific previous commit:
+
+```{jupyter-execute}
+param_db.load(1)
+```
+
+```{warning}
+Simultaneous database operations have not been tested yet. Simultaneous read operations
+(e.g. calls to {py:meth}`ParamDB.load`) are likely ok, but simultaneous write operations
+(e.g. calls to {py:meth}`ParamDB.commit`) may raise an exception.
+```
+
+## Commit History
+
+We can get a list of commits (as {py:class}`CommitEntry` objects) using the
+{py:meth}`ParamDB.commit_history` method.
+
+```{jupyter-execute}
+param_db.commit_history()
+```
+
+<!-- Jupyter Sphinx cleanup -->
+
+```{jupyter-execute}
+:hide-code:
+
+# Gets ride of PermissionError on Windows
+param_db._engine.dispose()
+```
+
+[`dataclasses.field`]: https://docs.python.org/3/library/dataclasses.html#dataclasses.field

docs/index.md

@@ -11,7 +11,8 @@
 :maxdepth: 2
 
 installation
-usage
+parameter-data
+database
 api-reference
 changelog
 license