[Suggestion] Package needs an API

[liamhuber]

Both for usability and to clarify what is protected by semver.

At a minimum, it looks like plot.plot¹ should be included for QoL, and models.PythonWorkflowDefinitionWorkflow should be included both as the main handle between python and serialized files and to nail down the format contract.

Otherwise, the main entry point seems to be from python_workflow_definition.some_tool_subpackage import load_workflow_json, write_workflow_json. IMO we could survive leaving these a specific imports, but it might be nice to formalize some sort of protocol with those fields as methods, e.g.,

import pathlib
from typing import Protocol, TypeVar

from python_workflow_defintion import models

ToolWorkflow = TypeVar("ToolWorkflow")

class ToolAdapter(Protocol[ToolWorkflow]):
    @staticmethod
    def load_workflow_json(file: str | pathlib.Path, /, **kwargs) -> ToolWorkflow:
        """Read a PWD JSON file and return a workflow representation in the supported tool"""

    @staticmethod
    def write_workflow_json(
            workflow: ToolWorkflow, file: str | pathlib.Path, /, **kwargs
    ) -> None:
        """Given a workflow representation in the supported tool, write it as a PWD JSON file"""

    # But honestly, I'd probably replace both these with from/to methods,
    # and then rely on the file conversions already on the model class instead.

    @staticmethod
    def from_pwd(
        workflow: models.PythonWorkflowDefinitionWorkflow, /, **kwargs
    ) -> ToolWorkflow: ...

    @staticmethod
    def to_pwd(
        workflow: ToolWorkflow, /, **kwargs
    ) -> models.PythonWorkflowDefinitionWorkflow: ...

and then include specific adapters in an import-alarmed way in the API.

Finally, we might have something like

import python_workflow_definition as pwd

tool_wf = pwd.tools.JobflowAdapter.load_workflow_json("some_pwd_wf.json")
...  # Execute, modify, whatever, not the point in this example
pwd.tools.JobflowAdapter.write_workflow_json(tool_wf, "pwf_wf_from_jobflow.json")

...  # maybe in some other session, with some other user, on some other machine

python_model = pwd.PythonWorkflowDefinitionWorkflow.load_json_file("pwf_wf_from_jobflow.json")
# and/or
pwd.plot("pwf_wf_from_jobflow.json")

Footnotes

1. I recommend renaming one of the plot module or function so that they don't conflict if you expose the function as part of the root-level __init__.py imports. ↩

[jan-janssen]

I had a similar discussion with Sebastian in #162 . In general I am open to the idea of modifying the package. At the moment the quick change was making the individual Workflow Management Systems optional dependencies while keeping the code in one framework. Feel free to open a pull request with the corresponding changes.