Interface for creating and running a project.

Contents

Project: the universal interface for chrisjen projects.

Project(name, id, automatic, library, clerk, idea, workflow=None, report=None, item=None) dataclass

Creates a workflow from settings and applies it.

A project moves through two stages:

1. draft: the settings (idea) are turned into a workflow.
2. apply: the workflow is applied to an item.

Creating a Project drafts it. If automatic is True, the project is also applied.

Use the create class method to create a Project instance unless you are passing all the arguments to the Project instance. The create method is more flexible and converts datatypes, validates arguments, and loads appropriate files and classes.

Parameters:

Name	Type	Description	Default
name	str	name of the project.	required
id	str	unique name for this run of the project.	required
automatic	bool	whether to apply the project as soon as it is created.	required
library	Library	library of the classes used to build the workflow.	required
clerk	FileManager	file manager for the project's files.	required
idea	Idea	settings that describe the project.	required
workflow	Worker | None	the workflow of the project. Defaults to None, in which case it is built by draft.	None
report	Report | None	report generated after the project is applied. Defaults to None, in which case options._DEFAULT_REPORT is used.	None
item	Any	data or object that the workflow is applied to. Defaults to None.	None

Attributes:

Name	Type	Description
result	Any	the result of the last call to apply.

result = dataclasses.field(default=None, init=False, repr=False) class-attribute instance-attribute

Initialization Methods

apply(item=None, **kwargs)

Applies the workflow to item and generates the report.

Parameters:

Name	Type	Description	Default
item	Any	data or object to change. Defaults to None, in which case the project's item is used.	None
**kwargs	Any	keyword arguments passed to the nodes in the workflow.	{}

Returns:

Type	Description
Any	The result of the workflow, which is also stored in result.

Source code in src/chrisjen/interface.py

def apply(self, item: Any = None, **kwargs: Any) -> Any:
    """Applies the workflow to `item` and generates the report.

    Args:
        item: data or object to change. Defaults to `None`, in which case
            the project's `item` is used.
        **kwargs: keyword arguments passed to the nodes in the workflow.

    Returns:
        The result of the workflow, which is also stored in `result`.

    """
    if item is None:
        item = self.item
    self.result = self.workflow.apply(item, **kwargs)
    self.report.generate(self)
    return self.result

create(idea, *, name=None, id=None, automatic=True, library=base.library, clerk=None, **kwargs) classmethod

Creates a project.

Every argument after idea must be passed by keyword.

Parameters:

Name	Type	Description	Default
idea	Idea | MutableMapping[str, Any] | Path | str	settings that describe the project: an Idea, a dict, or the path to a settings file.	required
name	str | None	name of the project. Defaults to None, in which case it is found in idea.	None
id	str | None	unique name for this run. Defaults to None, in which case it is the name of the project and the current date and time.	None
automatic	bool	whether to apply the project as soon as it is created. Defaults to True.	True
library	Library	library of the classes used to build the workflow. Defaults to base.library.	library
clerk	FileManager | Path | str | None	file manager, or the root folder for one. Defaults to None, in which case options._DEFAULT_ROOT is used.	None
**kwargs	Any	other arguments for Project.	{}

Returns:

Type	Description
Project	A Project instance.

Source code in src/chrisjen/interface.py

@classmethod
def create(
    cls,
    idea: base.Idea | MutableMapping[str, Any] | pathlib.Path | str,
    *,
    name: str | None = None,
    id: str | None = None,  # noqa: A002
    automatic: bool = True,
    library: base.Library = base.library,
    clerk: nagata.FileManager | pathlib.Path | str | None = None,
    **kwargs: Any) -> Project:
    """Creates a project.

    Every argument after `idea` must be passed by keyword.

    Args:
        idea: settings that describe the project: an `Idea`, a `dict`, or
            the path to a settings file.
        name: name of the project. Defaults to `None`, in which case it is
            found in `idea`.
        id: unique name for this run. Defaults to `None`, in which case it
            is the name of the project and the current date and time.
        automatic: whether to apply the project as soon as it is created.
            Defaults to `True`.
        library: library of the classes used to build the workflow.
            Defaults to `base.library`.
        clerk: file manager, or the root folder for one. Defaults to
            `None`, in which case `options._DEFAULT_ROOT` is used.
        **kwargs: other arguments for `Project`.

    Returns:
        A `Project` instance.

    """
    idea = _validate_idea(idea)
    name = _validate_name(name, idea)
    return cls(
        name = name,
        id = _validate_id(id, name),
        automatic = automatic,
        library = library,
        clerk = _validate_clerk(clerk, idea),
        idea = idea,
        **kwargs)

draft()

Builds the workflow from the settings.

Source code in src/chrisjen/interface.py

def draft(self) -> None:
    """Builds the `workflow` from the settings."""
    self.workflow = workshop.build_workflow(self)

to_dot(path=None, name=None)

Returns the workflow as a Graphviz dot str.

Parameters:

Name	Type	Description	Default
path	Path | str | None	file to save the text to. Defaults to None.	None
name	str | None	name of the graph. Defaults to the name of the project.	None

Returns:

Type	Description
str	The dot text.

Source code in src/chrisjen/interface.py

def to_dot(
    self,
    path: pathlib.Path | str | None = None,
    name: str | None = None) -> str:
    """Returns the workflow as a Graphviz dot `str`.

    Args:
        path: file to save the text to. Defaults to `None`.
        name: name of the graph. Defaults to the name of the project.

    Returns:
        The dot text.

    """
    return self.workflow.to_dot(path = path, name = name or self.name)

to_mermaid(path=None, name=None)

Returns the workflow as a mermaid flowchart str.

Parameters:

Name	Type	Description	Default
path	Path | str | None	file to save the text to. Defaults to None.	None
name	str | None	name of the chart. Defaults to the name of the project.	None

Returns:

Type	Description
str	The mermaid text.

Source code in src/chrisjen/interface.py

def to_mermaid(
    self,
    path: pathlib.Path | str | None = None,
    name: str | None = None) -> str:
    """Returns the workflow as a mermaid flowchart `str`.

    Args:
        path: file to save the text to. Defaults to `None`.
        name: name of the chart. Defaults to the name of the project.

    Returns:
        The mermaid text.

    """
    return self.workflow.to_mermaid(path = path, name = name or self.name)