cassini

Home

Bases: HomeTierBase

Home Tier.

This, or a subclass of this should generally be the first entry in your hierarchy, essentially represents the top level folder in your hierarchy.

Source code in cassini/defaults/tiers.py

class Home(HomeTierBase):
    """
    Home `Tier`.

    This, or a subclass of this should generally be the first entry in your hierarchy, essentially represents the top
    level folder in your hierarchy.
    """

    pretty_type = "Home"

WorkPackage

Bases: NotebookTierBase

WorkPackage Tier.

Intended to contain all the work towards a particular goal. i.e. prove that we can do this.

Next level down are Experiments.

Source code in cassini/defaults/tiers.py

class WorkPackage(NotebookTierBase):
    """
    WorkPackage Tier.

    Intended to contain all the work towards a particular goal. i.e. prove that we can do this.

    Next level down are `Experiment`s.
    """

    pretty_type = "WorkPackage"
    name_part_template = "WP{}"
    short_type = "wp"

    @property
    def exps(self) -> Sequence[TierABC]:
        """
        Gets a list of all this `WorkPackage`s experiments.
        """
        return list(self)

exps property

exps

Gets a list of all this WorkPackages experiments.

Experiment

Bases: NotebookTierBase

Experiment Tier.

Just below WorkPackage, experiments are intended to be collections of samples and datasets that work towards the goal of the parent WorkPackage.

Each Experiment has a number of samples.

Source code in cassini/defaults/tiers.py

class Experiment(NotebookTierBase):
    """
    Experiment `Tier`.

    Just below `WorkPackage`, experiments are intended to be collections of samples and datasets that work towards the
    goal of the parent `WorkPackage`.

    Each `Experiment` has a number of samples.
    """

    pretty_type = "Experiment"
    name_part_template = ".{}"
    short_type = "exp"

    @property
    def techniques(self) -> Sequence[str]:
        """
        Convenience property for looking up all the techniques that have been performed on samples in this experiment.

        Notes
        -----
        This just checks for the existence of DataSet folders, and not if they have anything in them!
        """
        techs = []
        for entry in os.scandir(self.folder):
            if entry.is_dir() and not ignore_dir(entry.name):
                techs.append(entry.name)
        return techs

    def setup_technique(self, name: str) -> None:
        """
        Convenience method for adding a new technique to this experiment.

        Essentially just creates a new folder for it in the appropriate location.

        This folder can then be filled with `DataSet`s
        """
        print("Making Data Folder")
        folder = self.folder / name

        if folder.exists():
            raise FileExistsError(f"{folder} exists already")

        with FileMaker() as maker:
            maker.mkdir(folder)

        print("Done")

    @property
    def smpls(self) -> Sequence[TierABC]:
        """
        Get a list of this `Experiment`s samples.
        """
        return list(self)

techniques property

techniques

Convenience property for looking up all the techniques that have been performed on samples in this experiment.

Notes

This just checks for the existence of DataSet folders, and not if they have anything in them!

smpls property

smpls

Get a list of this Experiments samples.

setup_technique

setup_technique(name)

Convenience method for adding a new technique to this experiment.

Essentially just creates a new folder for it in the appropriate location.

This folder can then be filled with DataSets

Source code in cassini/defaults/tiers.py

def setup_technique(self, name: str) -> None:
    """
    Convenience method for adding a new technique to this experiment.

    Essentially just creates a new folder for it in the appropriate location.

    This folder can then be filled with `DataSet`s
    """
    print("Making Data Folder")
    folder = self.folder / name

    if folder.exists():
        raise FileExistsError(f"{folder} exists already")

    with FileMaker() as maker:
        maker.mkdir(folder)

    print("Done")

Sample

Bases: NotebookTierBase

Sample Tier.

A Sample is intended to represent some object that you collect data on.

As such, each sample has its own DataSets.

Notes

A Sample id can't start with a number and can't contain '-' (dashes), as these confuse the name parser.

Source code in cassini/defaults/tiers.py

class Sample(NotebookTierBase):
    """
    Sample `Tier`.

    A `Sample` is intended to represent some object that you collect data on.

    As such, each sample has its own `DataSet`s.

    Notes
    -----
    A `Sample` id can't start with a number and can't contain `'-'` (dashes), as these confuse the name parser.
    """

    pretty_type = "Sample"
    name_part_template = "{}"
    id_regex = r"([^0-9^-][^-]*)"

    @cached_prop
    def folder(self) -> Path:
        assert self.parent
        return self.parent.folder

    @property
    def datasets(self) -> Sequence[TierABC]:
        """
        Convenient way of getting a list of `DataSet`s this sample has.
        """
        assert self.parent
        assert self.child_cls
        assert isinstance(self.parent, Experiment)

        techs = []
        for technique in self.parent.techniques:
            dataset = self.child_cls(*self.identifiers, technique, project=self.project)
            if dataset.exists():
                techs.append(dataset)
        return techs

    def __iter__(self) -> Iterator[TierABC]:
        return iter(self.datasets)

datasets property

datasets

Convenient way of getting a list of DataSets this sample has.

DataSet

Bases: FolderTierBase

DataSet Tier.

The final tier, intended to represent a folder containing a collection of files relating to a particular Sample.

Source code in cassini/defaults/tiers.py

class DataSet(FolderTierBase):
    """
    `DataSet` Tier.

    The final tier, intended to represent a folder containing a collection of files relating to a particular `Sample`.
    """

    pretty_type = "DataSet"
    short_type = "dset"
    name_part_template = "-{}"

    id_regex = r"(.+)"

    @cached_prop
    def folder(self) -> Path:
        assert self.parent

        return self.parent / self.id / self.parent.id

    def exists(self) -> bool:
        return self.folder.exists()

    def __truediv__(self, other: Any) -> Path:
        return cast(Path, self.folder / other)

    def __iter__(self) -> Iterator["os.DirEntry[Any]"]:
        """
        Call `os.scandir` on `self.folder`.
        """
        yield from os.scandir(self.folder)

    def __fspath__(self) -> str:
        return self.folder.__fspath__()

__iter__

__iter__()

Call os.scandir on self.folder.

Source code in cassini/defaults/tiers.py

def __iter__(self) -> Iterator["os.DirEntry[Any]"]:
    """
    Call `os.scandir` on `self.folder`.
    """
    yield from os.scandir(self.folder)

Project

Represents your project. Understands your naming convention, and your project hierarchy.

Some hooks are provided to customize setup and launching behaviour, see __before_setup_files__, __after_setup_files__, __before_launch__ and __after_launch__.

Parameters:

Name	Type	Description	Default
hierarchy	Sequence[Type[BaseTier]]	Sequence of TierBase subclasses representing the hierarchy for this project. i.e. earlier entries are stored in higher level directories.	required
project_folder	Union[str, Path]	path to home directory. Note this also accepts a path to a file, but will take project_folder.parent in that case. This enables __file__ to be used if you want project_folder to be based in the same dir.	required

Attributes:

Name	Type	Description
__before_setup_files__	List[Callable[[Project], None]]	Sequence of callables that are called, in order, first thing when project.setup_files() is called. Project is the calling project instance.
__after_setup_files__	List[Callable[[Project], None]]	Sequence of callables that are called, in order, last thing project.setup_files() is called. Note __after_setup_files__ are only called if the project hasn't already been setup.
__before_launch__	List[Callable[[Project, Union[LabApp, None]], None]]	Sequence of callables that are called first thing when project.launch() is ran. Project is the current project and LabApp is the lab app being launched.
__after_launch__	List[Callable[[Project, Union[LabApp, None]], None]]	Sequence of callables that are called last thing after project.launch() is ran. Project is the current project and LabApp is the lab app being launched.

Notes

This class is a singleton i.e. only 1 instance per interpreter can be created.

Source code in cassini/core.py

class Project:
    """
    Represents your project. Understands your naming convention, and your project hierarchy.

    Some hooks are provided to customize setup and launching behaviour, see
    `__before_setup_files__`, `__after_setup_files__`, `__before_launch__` and `__after_launch__`.

    Parameters
    ----------
    hierarchy : Sequence[Type[BaseTier]]
        Sequence of `TierBase` subclasses representing the hierarchy for this project. i.e. earlier entries are stored
        in higher level directories.
    project_folder : Union[str, Path]
        path to home directory. Note this also accepts a path to a file, but will take `project_folder.parent` in that
        case. This enables `__file__` to be used if you want `project_folder` to be based in the same dir.


    Attributes
    ----------
    __before_setup_files__ : List[Callable[[Project], None]]
        Sequence of callables that are called, in order, first thing when `project.setup_files()` is called.
        `Project` is the calling project instance.
    __after_setup_files__ : List[Callable[[Project], None]]
        Sequence of callables that are called, in order, last thing `project.setup_files()` is called.

        Note
        ----
        `__after_setup_files__` are only called _if_ the project hasn't already been setup.

    __before_launch__ : List[Callable[[Project, Union[LabApp, None]], None]]
        Sequence of callables that are called first thing when `project.launch()` is ran.
        `Project` is the current project and `LabApp` is the lab app being launched.
    __after_launch__ : List[Callable[[Project, Union[LabApp, None]], None]]
        Sequence of callables that are called last thing after `project.launch()` is ran.
        `Project` is the current project and `LabApp` is the lab app being launched.

    Notes
    -----
    This class is a singleton i.e. only 1 instance per interpreter can be created.
    """

    def __new__(cls, *args: Any, **kwargs: Any) -> Project:
        if env.project:
            raise RuntimeError(
                "Attempted to create new Project instance, only 1 instance permitted per interpreter"
            )
        instance = object.__new__(cls)
        env.project = instance
        return instance

    def __init__(
        self, hierarchy: Sequence[Type[TierABC]], project_folder: Union[str, Path]
    ) -> None:
        self._rank_map: Dict[Type[TierABC], int] = {}
        self._hierarchy: Sequence[Type[TierABC]] = []

        self.__before_setup_files__: List[Callable[[Project], None]] = []
        self.__after_setup_files__: List[Callable[[Project], None]] = []

        self.__before_launch__: List[
            Callable[[Project, Union[LabApp, None]], None]
        ] = []
        self.__after_launch__: List[Callable[[Project, Union[LabApp, None]], None]] = []

        self.hierarchy: Sequence[Type[TierABC]] = hierarchy

        project_folder_path = Path(project_folder).resolve()
        self.project_folder: Path = (
            project_folder_path
            if project_folder_path.is_dir()
            else project_folder_path.parent
        )

        self.template_env: PathLibEnv = PathLibEnv(
            autoescape=jinja2.select_autoescape(["html", "xml"]),
            loader=jinja2.FileSystemLoader(self.template_folder),
        )

    @property
    def hierarchy(self) -> Sequence[Type[TierABC]]:
        """
        Sequence of `TierBase` subclasses representing the hierarchy for this project. i.e. earlier entries are stored
        in higher level directories.
        """
        return self._hierarchy

    @hierarchy.setter
    def hierarchy(self, hierarchy: Sequence[Type[TierABC]]):
        self._hierarchy = hierarchy

        for rank, tier_cls in enumerate(hierarchy):
            self._rank_map[tier_cls] = rank

    @property
    def rank_map(self):
        """
        Maps `Tier` types to their position in the hierarchy.
        """
        return self._rank_map

    @property
    def home(self) -> TierABC:
        """
        Get the home `Tier`.
        """
        return self.hierarchy[0](project=self)

    def env(self, name: str) -> TierABC:
        """
        Initialise the global environment to a particular `Tier` that is retrieved by parsing `name`.

        This will set the value of `env.o`.

        Warnings
        --------
        This should only really be called once (or only with 1 name). Otherwise this could create some unexpected
        behaviour.
        """
        obj = self.__getitem__(name)

        if env.o and name != env.o.name:
            warn(
                (
                    f"Overwriting the global Tier {env.o} for this interpreter. This may cause unexpected behaviour. "
                    f"If you wish to create Tier objects that aren't the current Tier I recommend initialising them "
                    f"directly e.g. obj = MyTier('id1', 'id2')"
                )
            )

        env.update(obj)
        return obj

    def get_tier(self, identifiers: Tuple[str, ...]) -> TierABC:
        """
        Get a tier for a given set of identifiers.
        """
        cls = self.hierarchy[len(identifiers)]
        return cls(*identifiers, project=self)

    def get_child_cls(self, tier_cls: Type[TierABC]) -> Union[None, Type[TierABC]]:
        """
        Get the child class of a given tier class. Returns None if there is no child class
        """
        rank = self.rank_map[tier_cls]
        if rank + 1 > (len(self.hierarchy) - 1):
            return None
        else:
            cls = self.hierarchy[rank + 1]  # I don't understand why annotation needed?
            return cls

    def get_parent_cls(self, tier_cls: Type[TierABC]) -> Union[None, Type[TierABC]]:
        """
        Get the parent class of a given tier class. Returns None if there is no parent class
        """
        rank = self.rank_map[tier_cls]
        if rank - 1 < 0:
            return None
        else:
            cls = self.hierarchy[rank - 1]
            return cls

    def __getitem__(self, name: str) -> TierABC:
        """
        Retrieve a tier object from the project by name.

        Parameters
        ----------
        name : str
            Parsable name to get the tier object by. To get your `Home` just provide `Home.name`.

        Returns
        -------
        tier : TierBase
            Tier retrieved from project.
        """
        if name == self.home.name:
            obj = self.home
        else:
            identifiers = self.parse_name(name)
            if not identifiers:
                raise ValueError(f"Name {name} not recognised as identifying any Tier")
            obj = self.get_tier(identifiers)
        return obj

    @soft_prop
    def template_folder(self) -> Path:
        """
        Overwritable property providing where templates will be stored for this project.
        """
        return self.project_folder / "templates"

    def setup_files(self) -> TierABC:
        """
        Setup files needed for this project.

        Will put everything you need in `project_folder` to get going.

        Note
        ----
        This does not call `__after_setup_files__` if the project already exists.

        """
        for func in self.__before_setup_files__:
            func(self)

        home = self.home

        if home.exists():
            return home

        print("Setting up project.")

        with FileMaker() as maker:
            print("Creating templates folder")
            maker.mkdir(self.template_folder)
            print("Success")

            for tier_cls in self.hierarchy:
                if not issubclass(tier_cls, NotebookTierBase):
                    continue

                maker.mkdir(self.template_folder / tier_cls.pretty_type)
                print("Copying over default template")
                maker.copy_file(
                    config.BASE_TEMPLATE,
                    self.template_folder / tier_cls.default_template,
                )
                print("Done")

        print("Setting up Home Tier")
        home.setup_files()
        print("Success")

        for func in self.__after_setup_files__:
            func(self)

        return home

    def launch(
        self, app: Union[LabApp, None] = None, patch_pythonpath: bool = True
    ) -> LabApp:
        """
        Jump off point for a cassini project.

        Sets up required files for your project, monkeypatches `PYTHONPATH` to make your project available throughout
        and launches a jupyterlab server.

        This explicitly associates an instance of the Jupyter server with a particular project.

        Parameters
        ----------
        app : LabApp
            A ready made Jupyter Lab app (By defuault will just create a new one).
        patch_pythonpath : bool
            Add `self.project_folder` to the `PYTHONPATH`? (defaults to `True`)
        """
        for func in self.__before_launch__:
            func(self, app)

        self.setup_files()

        if patch_pythonpath:
            py_path = os.environ.get("PYTHONPATH", "")
            project_path = str(self.project_folder.resolve())
            os.environ["PYTHONPATH"] = (
                py_path + os.pathsep + project_path if py_path else project_path
            )

        if app is None:
            app = CassiniLabApp()

        app.launch_instance()

        for func in self.__after_launch__:
            func(self, app)

        return app

    def parse_name(self, name: str) -> Tuple[str, ...]:
        """
        Parses a string that corresponds to a `Tier` and returns a list of its identifiers.

        returns an empty tuple if not a valid name.

        Parameters
        ----------
        name : str
            name to parse

        Returns
        -------
        identifiers : tuple
            identifiers extracted from name, empty tuple if `None` found

        Notes
        -----
        This works in a slightly strange - but robust way!

        e.g.

            >>> name = 'WP2.3c'

        it will loop through each entry in `cls.hierarchy` (skipping home!), and then perform a search on `name` with
        that regex:

            >>> WorkPackage.name_part_regex
            WP(\\d+)
            >>> match = re.search(WorkPackage.name_part_regex, name)

        If there's no match, it will return `()`, if there is, it stores the `id` part:

            >>> wp_id = match.group(1)  # in python group 0 is the whole match
            >>> wp_id
            2

        Then it removes the whole match from the name:

            >>> name = name[match.end(0):]
            >>> name
            .3c

        Then it moves on to the next tier

            >>> Experiment.name_part_regex
            '\\.(\\d+)'
            >>> match = re.search(WorkPackage.name_part_regex, name)

        If there's a match it extracts the id, and substracts the whole string from name and moves on, continuing this
        loop until it's gone through the whole hierarchy.

        The whole name has to be a valid id, or it will return `()` e.g.

            >>> TierBase.parse_name('WP2.3')
            ('2', '3')
            >>> TierBase.parse_name('WP2.u3')
            ()
        """
        parts = self.hierarchy[1:]
        ids: List[str] = []
        for tier_cls in parts:
            pattern = tier_cls.name_part_regex
            match = re.search(pattern, name)
            if match and match.start(0) == 0:
                ids.append(match.group(1))
                name = name[match.end(0) :]
            else:
                break
        if name:  # if there's any residual text then it's not a valid name!
            return tuple()
        else:
            return tuple(ids)

    def __repr__(self) -> str:
        return f"<Project at: '{self.project_folder}' hierarchy: '{self.hierarchy}' ({env})>"

hierarchy property writable

hierarchy

Sequence of TierBase subclasses representing the hierarchy for this project. i.e. earlier entries are stored in higher level directories.

rank_map property

rank_map

Maps Tier types to their position in the hierarchy.

home property

home

Get the home Tier.

env

env(name)

Initialise the global environment to a particular Tier that is retrieved by parsing name.

This will set the value of env.o.

Warnings

This should only really be called once (or only with 1 name). Otherwise this could create some unexpected behaviour.

Source code in cassini/core.py

def env(self, name: str) -> TierABC:
    """
    Initialise the global environment to a particular `Tier` that is retrieved by parsing `name`.

    This will set the value of `env.o`.

    Warnings
    --------
    This should only really be called once (or only with 1 name). Otherwise this could create some unexpected
    behaviour.
    """
    obj = self.__getitem__(name)

    if env.o and name != env.o.name:
        warn(
            (
                f"Overwriting the global Tier {env.o} for this interpreter. This may cause unexpected behaviour. "
                f"If you wish to create Tier objects that aren't the current Tier I recommend initialising them "
                f"directly e.g. obj = MyTier('id1', 'id2')"
            )
        )

    env.update(obj)
    return obj

get_tier

get_tier(identifiers)

Get a tier for a given set of identifiers.

Source code in cassini/core.py

def get_tier(self, identifiers: Tuple[str, ...]) -> TierABC:
    """
    Get a tier for a given set of identifiers.
    """
    cls = self.hierarchy[len(identifiers)]
    return cls(*identifiers, project=self)

get_child_cls

get_child_cls(tier_cls)

Get the child class of a given tier class. Returns None if there is no child class

Source code in cassini/core.py

def get_child_cls(self, tier_cls: Type[TierABC]) -> Union[None, Type[TierABC]]:
    """
    Get the child class of a given tier class. Returns None if there is no child class
    """
    rank = self.rank_map[tier_cls]
    if rank + 1 > (len(self.hierarchy) - 1):
        return None
    else:
        cls = self.hierarchy[rank + 1]  # I don't understand why annotation needed?
        return cls

get_parent_cls

get_parent_cls(tier_cls)

Get the parent class of a given tier class. Returns None if there is no parent class

Source code in cassini/core.py

def get_parent_cls(self, tier_cls: Type[TierABC]) -> Union[None, Type[TierABC]]:
    """
    Get the parent class of a given tier class. Returns None if there is no parent class
    """
    rank = self.rank_map[tier_cls]
    if rank - 1 < 0:
        return None
    else:
        cls = self.hierarchy[rank - 1]
        return cls

__getitem__

__getitem__(name)

Retrieve a tier object from the project by name.

Parameters:

Name	Type	Description	Default
name	str	Parsable name to get the tier object by. To get your Home just provide Home.name.	required

Returns:

Name	Type	Description
tier	TierBase	Tier retrieved from project.

Source code in cassini/core.py

def __getitem__(self, name: str) -> TierABC:
    """
    Retrieve a tier object from the project by name.

    Parameters
    ----------
    name : str
        Parsable name to get the tier object by. To get your `Home` just provide `Home.name`.

    Returns
    -------
    tier : TierBase
        Tier retrieved from project.
    """
    if name == self.home.name:
        obj = self.home
    else:
        identifiers = self.parse_name(name)
        if not identifiers:
            raise ValueError(f"Name {name} not recognised as identifying any Tier")
        obj = self.get_tier(identifiers)
    return obj

template_folder

template_folder()

Overwritable property providing where templates will be stored for this project.

Source code in cassini/core.py

@soft_prop
def template_folder(self) -> Path:
    """
    Overwritable property providing where templates will be stored for this project.
    """
    return self.project_folder / "templates"

setup_files

setup_files()

Setup files needed for this project.

Will put everything you need in project_folder to get going.

Note

This does not call __after_setup_files__ if the project already exists.

Source code in cassini/core.py

def setup_files(self) -> TierABC:
    """
    Setup files needed for this project.

    Will put everything you need in `project_folder` to get going.

    Note
    ----
    This does not call `__after_setup_files__` if the project already exists.

    """
    for func in self.__before_setup_files__:
        func(self)

    home = self.home

    if home.exists():
        return home

    print("Setting up project.")

    with FileMaker() as maker:
        print("Creating templates folder")
        maker.mkdir(self.template_folder)
        print("Success")

        for tier_cls in self.hierarchy:
            if not issubclass(tier_cls, NotebookTierBase):
                continue

            maker.mkdir(self.template_folder / tier_cls.pretty_type)
            print("Copying over default template")
            maker.copy_file(
                config.BASE_TEMPLATE,
                self.template_folder / tier_cls.default_template,
            )
            print("Done")

    print("Setting up Home Tier")
    home.setup_files()
    print("Success")

    for func in self.__after_setup_files__:
        func(self)

    return home

launch

launch(app=None, patch_pythonpath=True)

Jump off point for a cassini project.

Sets up required files for your project, monkeypatches PYTHONPATH to make your project available throughout and launches a jupyterlab server.

This explicitly associates an instance of the Jupyter server with a particular project.

Parameters:

Name	Type	Description	Default
app	LabApp	A ready made Jupyter Lab app (By defuault will just create a new one).	None
patch_pythonpath	bool	Add self.project_folder to the PYTHONPATH? (defaults to True)	True

Source code in cassini/core.py

def launch(
    self, app: Union[LabApp, None] = None, patch_pythonpath: bool = True
) -> LabApp:
    """
    Jump off point for a cassini project.

    Sets up required files for your project, monkeypatches `PYTHONPATH` to make your project available throughout
    and launches a jupyterlab server.

    This explicitly associates an instance of the Jupyter server with a particular project.

    Parameters
    ----------
    app : LabApp
        A ready made Jupyter Lab app (By defuault will just create a new one).
    patch_pythonpath : bool
        Add `self.project_folder` to the `PYTHONPATH`? (defaults to `True`)
    """
    for func in self.__before_launch__:
        func(self, app)

    self.setup_files()

    if patch_pythonpath:
        py_path = os.environ.get("PYTHONPATH", "")
        project_path = str(self.project_folder.resolve())
        os.environ["PYTHONPATH"] = (
            py_path + os.pathsep + project_path if py_path else project_path
        )

    if app is None:
        app = CassiniLabApp()

    app.launch_instance()

    for func in self.__after_launch__:
        func(self, app)

    return app

parse_name

parse_name(name)

Parses a string that corresponds to a Tier and returns a list of its identifiers.

returns an empty tuple if not a valid name.

Parameters:

Name	Type	Description	Default
name	str	name to parse	required

Returns:

Name	Type	Description
identifiers	tuple	identifiers extracted from name, empty tuple if None found

Notes

This works in a slightly strange - but robust way!

e.g.

>>> name = 'WP2.3c'

it will loop through each entry in cls.hierarchy (skipping home!), and then perform a search on name with that regex:

>>> WorkPackage.name_part_regex
WP(\d+)
>>> match = re.search(WorkPackage.name_part_regex, name)

If there's no match, it will return (), if there is, it stores the id part:

>>> wp_id = match.group(1)  # in python group 0 is the whole match
>>> wp_id
2

Then it removes the whole match from the name:

>>> name = name[match.end(0):]
>>> name
.3c

Then it moves on to the next tier

>>> Experiment.name_part_regex
'\.(\d+)'
>>> match = re.search(WorkPackage.name_part_regex, name)

If there's a match it extracts the id, and substracts the whole string from name and moves on, continuing this loop until it's gone through the whole hierarchy.

The whole name has to be a valid id, or it will return () e.g.

>>> TierBase.parse_name('WP2.3')
('2', '3')
>>> TierBase.parse_name('WP2.u3')
()

Source code in cassini/core.py

def parse_name(self, name: str) -> Tuple[str, ...]:
    """
    Parses a string that corresponds to a `Tier` and returns a list of its identifiers.

    returns an empty tuple if not a valid name.

    Parameters
    ----------
    name : str
        name to parse

    Returns
    -------
    identifiers : tuple
        identifiers extracted from name, empty tuple if `None` found

    Notes
    -----
    This works in a slightly strange - but robust way!

    e.g.

        >>> name = 'WP2.3c'

    it will loop through each entry in `cls.hierarchy` (skipping home!), and then perform a search on `name` with
    that regex:

        >>> WorkPackage.name_part_regex
        WP(\\d+)
        >>> match = re.search(WorkPackage.name_part_regex, name)

    If there's no match, it will return `()`, if there is, it stores the `id` part:

        >>> wp_id = match.group(1)  # in python group 0 is the whole match
        >>> wp_id
        2

    Then it removes the whole match from the name:

        >>> name = name[match.end(0):]
        >>> name
        .3c

    Then it moves on to the next tier

        >>> Experiment.name_part_regex
        '\\.(\\d+)'
        >>> match = re.search(WorkPackage.name_part_regex, name)

    If there's a match it extracts the id, and substracts the whole string from name and moves on, continuing this
    loop until it's gone through the whole hierarchy.

    The whole name has to be a valid id, or it will return `()` e.g.

        >>> TierBase.parse_name('WP2.3')
        ('2', '3')
        >>> TierBase.parse_name('WP2.u3')
        ()
    """
    parts = self.hierarchy[1:]
    ids: List[str] = []
    for tier_cls in parts:
        pattern = tier_cls.name_part_regex
        match = re.search(pattern, name)
        if match and match.start(0) == 0:
            ids.append(match.group(1))
            name = name[match.end(0) :]
        else:
            break
    if name:  # if there's any residual text then it's not a valid name!
        return tuple()
    else:
        return tuple(ids)