Repository navigation
[Suggestion] Package needs an API #203
Description
Both for usability and to clarify what is protected by semver.
At a minimum, it looks like plot.plot1 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
-
I recommend renaming one of the
plotmodule or function so that they don't conflict if you expose the function as part of the root-level__init__.pyimports. ↩
Activity
[-]Package needs an API[/-][+][Suggestion] Package needs an API[/+]jan-janssen commentedon Aug 12, 2026
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.