Migrating from 0.2.x to 0.3.x

Meta Started Format

Version 0.3.x primarily involved a number of internal changes to make meta-data more stable by implementing validation of meta values.

This required changing the format of tier.started from YYYY/MM/DD to a timezone aware datetime isostring e.g. 2023-08-29 00:00:00+01:00.

Cassini version 0.3.x includes a migration tool to automatically upgrade your meta files to the new format.

Once you have upgraded Cassini, you can run:

python -m cassini.migrate 0.2 0.3 --cassini-project=project.py:project

Where --cassini-project is the path to your project.py, and :project is the name of your project object.

This will iterate through your tiers and upgrade started to the new format. As started is now a datetime, the tool will set the time to the start of the day and use your locale timezone.

Renaming project.py to cas_project.py

It was decided that having a project object in project.py could be a bit confusing, thus in version 0.3.x, Cassini recommends naming the file where you define your project object cas_project.py.

The Cassini JupyterLab gui needs to be able to find your project object. If you use project.launch() to run JupyterLab, this is done automatically.

If launch() isn't used, by default in version 0.2.x, Cassini would look for project.py:project, but in version 0.3.x, it now looks for cas_project.py:project by default.

If you are not using project.launch() to launch JupyterLab, you may need to explicitly point the JupyterLab extension to your project object by setting:

SET CASSINI_PROJECT=project.py:project

On Windows, or on mac/ linux:

export CASSINI_PROJECT=project.py:project

Splitting up TierBase

In Cassini 0.2.x, to create custom Tier classes, you would subclass the TierBase baseclass.

This made it challenging to distinguish when a Tier did or did not have a Notebook and Meta associated with it.

In version 0.3.x TierBase has been split into NotebookTierBase and FolderTierBase. Depending if your Tier has a Notebook or just a folder associated with it, you should use the new baseclass.

Home has no Notebook

In versions prior to 0.3.x the Home tier had a notebook associated with it. This was in part because these used the ipygui and the Home header acted a bit like the Cassini Browser. If you require a Home notebook, you should create a custom subclass of the existing Home class.

For example:

from cassini import Project, NotebookTierBase, WorkPackage, Experiment, Sample, DataSet

class MyHome(NotebookTierBase):
    pretty_type = "Home"

    @property
    def name(self):
        return self.pretty_type

    @property
    def folder(self):
        return self.project.project_folder / (self.child_cls.pretty_type + "s")

    @property
    def file(self):
        return self.project.project_folder / 'Home.ipynb'

    @property
    def meta_file(self):  # notebook tiers _have_ to have meta and highlights now.
        return self.project.project_folder / 'home-meta.json'

    @property
    def highlights_file(self):
        return self.project.project_folder / 'home-hlts.json'

project = Project(hierarchy=[MyHome, WorkPackage, Experiment, Sample, DataSet], project_folder=__file__)

if __name__ == '__main__':
    project.launch()