jobflow 0.1.17__tar.gz → 0.1.19__tar.gz

{jobflow-0.1.17/src/jobflow.egg-info → jobflow-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: jobflow
-Version: 0.1.17
+Version: 0.1.19
 Summary: jobflow is a library for writing computational workflows
 Author-email: Alex Ganose <a.ganose@imperial.ac.uk>
 License: modified BSD
@@ -34,19 +34,20 @@ Requires-Dist: pydash
 Provides-Extra: ulid
 Requires-Dist: python-ulid; extra == "ulid"
 Provides-Extra: docs
-Requires-Dist: autodoc_pydantic==2.0.1; extra == "docs"
-Requires-Dist: furo==2023.9.10; extra == "docs"
-Requires-Dist: ipython==8.20.0; extra == "docs"
-Requires-Dist: myst_parser==2.0.0; extra == "docs"
-Requires-Dist: nbsphinx==0.9.3; extra == "docs"
+Requires-Dist: autodoc_pydantic==2.1.0; extra == "docs"
+Requires-Dist: furo==2024.8.6; extra == "docs"
+Requires-Dist: ipython==8.29.0; extra == "docs"
+Requires-Dist: myst_parser==4.0.0; extra == "docs"
+Requires-Dist: nbsphinx==0.9.5; extra == "docs"
 Requires-Dist: sphinx-copybutton==0.5.2; extra == "docs"
-Requires-Dist: sphinx==7.2.6; extra == "docs"
+Requires-Dist: sphinx==8.1.3; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: pre-commit>=2.12.1; extra == "dev"
+Requires-Dist: typing_extensions; python_version < "3.11" and extra == "dev"
 Provides-Extra: tests
 Requires-Dist: moto==4.2.13; extra == "tests"
-Requires-Dist: pytest-cov==4.1.0; extra == "tests"
-Requires-Dist: pytest==7.4.4; extra == "tests"
+Requires-Dist: pytest-cov==6.0.0; extra == "tests"
+Requires-Dist: pytest==8.3.3; extra == "tests"
 Provides-Extra: vis
 Requires-Dist: matplotlib; extra == "vis"
 Requires-Dist: pydot; extra == "vis"
@@ -54,20 +55,22 @@ Provides-Extra: fireworks
 Requires-Dist: FireWorks; extra == "fireworks"
 Provides-Extra: strict
 Requires-Dist: FireWorks==2.0.3; extra == "strict"
-Requires-Dist: PyYAML==6.0.1; extra == "strict"
-Requires-Dist: maggma==0.61.0; extra == "strict"
-Requires-Dist: matplotlib==3.8.2; extra == "strict"
-Requires-Dist: monty==2023.11.3; extra == "strict"
+Requires-Dist: PyYAML==6.0.2; extra == "strict"
+Requires-Dist: maggma==0.70.0; extra == "strict"
+Requires-Dist: matplotlib==3.9.2; extra == "strict"
+Requires-Dist: monty==2024.10.21; extra == "strict"
 Requires-Dist: moto==4.2.13; extra == "strict"
 Requires-Dist: networkx==3.2.1; extra == "strict"
-Requires-Dist: pydantic-settings==2.1.0; extra == "strict"
-Requires-Dist: pydantic==2.5.3; extra == "strict"
-Requires-Dist: pydash==7.0.6; extra == "strict"
+Requires-Dist: pydantic-settings==2.6.1; extra == "strict"
+Requires-Dist: pydantic==2.9.2; extra == "strict"
+Requires-Dist: pydash==8.0.4; extra == "strict"
 Requires-Dist: pydot==2.0.0; extra == "strict"
-Requires-Dist: typing-extensions==4.9.0; extra == "strict"
-Requires-Dist: python-ulid==2.2.0; extra == "strict"
+Requires-Dist: python-ulid==3.0.0; extra == "strict"
+Requires-Dist: typing-extensions==4.12.2; extra == "strict"
 
-# jobflow
+<div align="center">
+
+# ![Jobflow](docs/_static/img/jobflow_logo.svg)
 
 [![tests](https://img.shields.io/github/actions/workflow/status/materialsproject/jobflow/testing.yml?branch=main&label=tests)](https://github.com/materialsproject/jobflow/actions?query=workflow%3Atesting)
 [![code coverage](https://img.shields.io/codecov/c/gh/materialsproject/jobflow/main)](https://codecov.io/gh/materialsproject/jobflow/)
@@ -75,11 +78,14 @@ Requires-Dist: python-ulid==2.2.0; extra == "strict"
 ![supported python versions](https://img.shields.io/pypi/pyversions/jobflow)
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.05995/status.svg)](https://doi.org/10.21105/joss.05995)
 
+</div>
+
 [Documentation](https://materialsproject.github.io/jobflow/) | [PyPI](https://pypi.org/project/jobflow/) | [GitHub](https://github.com/materialsproject/jobflow) | [Paper](https://doi.org/10.21105/joss.05995)
 
 Jobflow is a free, open-source library for writing and executing workflows. Complex
 workflows can be defined using simple python functions and executed locally or on
-arbitrary computing resources using the [FireWorks][fireworks] workflow manager.
+arbitrary computing resources using the [jobflow-remote][jfr] or [FireWorks][fireworks]
+workflow managers.
 
 Some features that distinguish jobflow are dynamic workflows, easy compositing and
 connecting of workflows, and the ability to store workflow outputs across multiple
@@ -98,7 +104,7 @@ Some of its features include:
   way to build complex workflows.
 - Integration with multiple databases (MongoDB, S3, GridFS, and more) through the
   [Maggma][maggma] package.
-- Support for the [FireWorks][fireworks] workflow management system, allowing workflow
+- Support for the [jobflow-remote][jfr] and [FireWorks][fireworks] workflow management systems, allowing workflow
   execution on multicore machines or through a queue, on a single machine or multiple
   machines.
 - Support for dynamic workflows — workflows that modify themselves or create new ones
@@ -192,6 +198,7 @@ Jobflow was designed by Alex Ganose, Anubhav Jain, Gian-Marco Rignanese, David W
 
 [maggma]: https://materialsproject.github.io/maggma/
 [fireworks]: https://materialsproject.github.io/fireworks/
+[jfr]: https://matgenix.github.io/jobflow-remote
 [help-forum]: https://matsci.org/c/fireworks
 [issues]: https://github.com/materialsproject/jobflow/issues
 [changelog]: https://materialsproject.github.io/jobflow/changelog.html

{jobflow-0.1.17 → jobflow-0.1.19}/README.md

@@ -1,4 +1,6 @@
-# jobflow
+<div align="center">
+
+# ![Jobflow](docs/_static/img/jobflow_logo.svg)
 
 [![tests](https://img.shields.io/github/actions/workflow/status/materialsproject/jobflow/testing.yml?branch=main&label=tests)](https://github.com/materialsproject/jobflow/actions?query=workflow%3Atesting)
 [![code coverage](https://img.shields.io/codecov/c/gh/materialsproject/jobflow/main)](https://codecov.io/gh/materialsproject/jobflow/)
@@ -6,11 +8,14 @@
 ![supported python versions](https://img.shields.io/pypi/pyversions/jobflow)
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.05995/status.svg)](https://doi.org/10.21105/joss.05995)
 
+</div>
+
 [Documentation](https://materialsproject.github.io/jobflow/) | [PyPI](https://pypi.org/project/jobflow/) | [GitHub](https://github.com/materialsproject/jobflow) | [Paper](https://doi.org/10.21105/joss.05995)
 
 Jobflow is a free, open-source library for writing and executing workflows. Complex
 workflows can be defined using simple python functions and executed locally or on
-arbitrary computing resources using the [FireWorks][fireworks] workflow manager.
+arbitrary computing resources using the [jobflow-remote][jfr] or [FireWorks][fireworks]
+workflow managers.
 
 Some features that distinguish jobflow are dynamic workflows, easy compositing and
 connecting of workflows, and the ability to store workflow outputs across multiple
@@ -29,7 +34,7 @@ Some of its features include:
   way to build complex workflows.
 - Integration with multiple databases (MongoDB, S3, GridFS, and more) through the
   [Maggma][maggma] package.
-- Support for the [FireWorks][fireworks] workflow management system, allowing workflow
+- Support for the [jobflow-remote][jfr] and [FireWorks][fireworks] workflow management systems, allowing workflow
   execution on multicore machines or through a queue, on a single machine or multiple
   machines.
 - Support for dynamic workflows — workflows that modify themselves or create new ones
@@ -123,6 +128,7 @@ Jobflow was designed by Alex Ganose, Anubhav Jain, Gian-Marco Rignanese, David W
 
 [maggma]: https://materialsproject.github.io/maggma/
 [fireworks]: https://materialsproject.github.io/fireworks/
+[jfr]: https://matgenix.github.io/jobflow-remote
 [help-forum]: https://matsci.org/c/fireworks
 [issues]: https://github.com/materialsproject/jobflow/issues
 [changelog]: https://materialsproject.github.io/jobflow/changelog.html

{jobflow-0.1.17 → jobflow-0.1.19}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools >= 42", "versioningit ~= 1.0", "wheel"]
+requires = ["setuptools >= 42", "versioningit >= 1,< 4", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -38,32 +38,32 @@ dependencies = [
 [project.optional-dependencies]
 ulid = ["python-ulid"]
 docs = [
-    "autodoc_pydantic==2.0.1",
-    "furo==2023.9.10",
-    "ipython==8.20.0",
-    "myst_parser==2.0.0",
-    "nbsphinx==0.9.3",
+    "autodoc_pydantic==2.1.0",
+    "furo==2024.8.6",
+    "ipython==8.29.0",
+    "myst_parser==4.0.0",
+    "nbsphinx==0.9.5",
     "sphinx-copybutton==0.5.2",
-    "sphinx==7.2.6",
+    "sphinx==8.1.3",
 ]
-dev = ["pre-commit>=2.12.1"]
-tests = ["moto==4.2.13", "pytest-cov==4.1.0", "pytest==7.4.4"]
+dev = ["pre-commit>=2.12.1", "typing_extensions; python_version < '3.11'"]
+tests = ["moto==4.2.13", "pytest-cov==6.0.0", "pytest==8.3.3"]
 vis = ["matplotlib", "pydot"]
 fireworks = ["FireWorks"]
 strict = [
     "FireWorks==2.0.3",
-    "PyYAML==6.0.1",
-    "maggma==0.61.0",
-    "matplotlib==3.8.2",
-    "monty==2023.11.3",
+    "PyYAML==6.0.2",
+    "maggma==0.70.0",
+    "matplotlib==3.9.2",
+    "monty==2024.10.21",
     "moto==4.2.13",
     "networkx==3.2.1",
-    "pydantic-settings==2.1.0",
-    "pydantic==2.5.3",
-    "pydash==7.0.6",
+    "pydantic-settings==2.6.1",
+    "pydantic==2.9.2",
+    "pydash==8.0.4",
     "pydot==2.0.0",
-    "typing-extensions==4.9.0",
-    "python-ulid==2.2.0",
+    "python-ulid==3.0.0",
+    "typing-extensions==4.12.2",
 ]
 
 [project.urls]
@@ -121,7 +121,9 @@ exclude_lines = [
 
 [tool.ruff]
 target-version = "py39"
-ignore-init-module-imports = true
+output-format = "concise"
+
+[tool.ruff.lint]
 select = [
     "B",      # flake8-bugbear
     "C4",     # flake8-comprehensions
@@ -159,6 +161,7 @@ ignore = [
     "DTZ005",
     "FBT001",
     "FBT002",
+    "ISC001",
     "PLR0911", # too-many-return-statements
     "PLR0912", # too-many-branches
     "PLR0913", # too-many-arguments
@@ -170,10 +173,11 @@ ignore = [
 pydocstyle.convention = "numpy"
 isort.known-first-party = ["jobflow"]
 
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 # F401: unused import
 "__init__.py" = ["F401"]
 # D: pydocstyle
 # PLR2004: magic-value-comparison
 # PT004: pytest-missing-fixture-name-underscore
 "**/tests/*" = ["ANN", "ARG001", "D", "PLR2004", "PT004", "S101"]
+"docs/tutorials/*" = ["D", "PLR2004"]

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/core/flow.py

@@ -67,6 +67,11 @@ class Flow(MSONable):
         automatically when a flow is included in the jobs array of another flow.
         The object identified by one UUID of the list should be contained in objects
         identified by its subsequent elements.
+    metadata
+        A dictionary of information that will get stored in the Flow collection.
+    metadata_updates
+        A list of updates for the metadata that will be applied to any dynamically
+        generated sub Flow/Job.
 
     Raises
     ------
@@ -128,6 +133,8 @@ class Flow(MSONable):
         order: JobOrder = JobOrder.AUTO,
         uuid: str = None,
         hosts: list[str] = None,
+        metadata: dict[str, Any] = None,
+        metadata_updates: list[dict[str, Any]] = None,
     ):
         from jobflow.core.job import Job
 
@@ -141,6 +148,8 @@ class Flow(MSONable):
         self.order = order
         self.uuid = uuid
         self.hosts = hosts or []
+        self.metadata = metadata or {}
+        self.metadata_updates = metadata_updates or []
 
         self._jobs: tuple[Flow | Job, ...] = ()
         self.add_jobs(jobs)
@@ -158,9 +167,8 @@ class Flow(MSONable):
         self, idx: int | slice, value: Flow | Job | Sequence[Flow | Job]
     ) -> None:
         """Set the job(s) or subflow(s) at the given index/slice."""
-        if (
-            not isinstance(value, (Flow, jobflow.Job, tuple, list))
-            or isinstance(value, (tuple, list))
+        if not isinstance(value, (Flow, jobflow.Job, tuple, list)) or (
+            isinstance(value, (tuple, list))
             and not all(isinstance(v, (Flow, jobflow.Job)) for v in value)
         ):
             raise TypeError(
@@ -191,7 +199,7 @@ class Flow(MSONable):
         if other not in self:
             raise ValueError(f"{other!r} not found in flow")
         new_flow = deepcopy(self)
-        new_flow.jobs = tuple([job for job in new_flow if job != other])
+        new_flow.jobs = tuple(job for job in new_flow if job != other)
         return new_flow
 
     def __repr__(self, level: int = 0, prefix: str = "") -> str:
@@ -583,7 +591,7 @@ class Flow(MSONable):
                 dict_mod=dict_mod,
             )
 
-    def append_name(self, append_str: str, prepend: bool = False):
+    def append_name(self, append_str: str, prepend: bool = False, dynamic: bool = True):
         """
         Append a string to the name of the flow and all jobs contained in it.
 
@@ -600,7 +608,7 @@ class Flow(MSONable):
             self.name += append_str
 
         for job in self:
-            job.append_name(append_str, prepend=prepend)
+            job.append_name(append_str, prepend=prepend, dynamic=dynamic)
 
     def update_metadata(
         self,
@@ -609,9 +617,10 @@ class Flow(MSONable):
         function_filter: Callable = None,
         dict_mod: bool = False,
         dynamic: bool = True,
+        callback_filter: Callable[[Flow | Job], bool] = lambda _: True,
     ):
         """
-        Update the metadata of all Jobs in the Flow.
+        Update the metadata of the Flow and/or its Jobs.
 
         Note that updates will be applied to jobs in nested Flow.
 
@@ -631,6 +640,10 @@ class Flow(MSONable):
         dynamic
             The updates will be propagated to Jobs/Flows dynamically generated at
             runtime.
+        callback_filter
+            A function that takes a Flow or Job instance and returns True if updates
+            should be applied to that instance. Allows for custom filtering logic.
+            Applies recursively to nested Flows and Jobs so best be specific.
 
         Examples
         --------
@@ -647,16 +660,45 @@ class Flow(MSONable):
         The ``metadata`` of both jobs could be updated as follows:
 
         >>> flow.update_metadata({"tag": "addition_job"})
+
+        Or using a callback filter to only update flows containing a specific maker:
+
+        >>> flow.update_metadata(
+        ...     {"material_id": 42},
+        ...     callback_filter=lambda flow: SomeMaker in map(type, flow)
+        ...     and flow.name == "flow name"
+        ... )
         """
-        for job in self:
-            job.update_metadata(
+        from jobflow.utils.dict_mods import apply_mod
+
+        for job_or_flow in self:
+            job_or_flow.update_metadata(
                 update,
                 name_filter=name_filter,
                 function_filter=function_filter,
                 dict_mod=dict_mod,
                 dynamic=dynamic,
+                callback_filter=callback_filter,
             )
 
+        if callback_filter(self) is False:
+            return
+
+        if dict_mod:
+            apply_mod(update, self.metadata)
+        else:
+            self.metadata.update(update)
+
+        if dynamic:
+            dict_input = {
+                "update": update,
+                "name_filter": name_filter,
+                "function_filter": function_filter,
+                "dict_mod": dict_mod,
+                "callback_filter": callback_filter,
+            }
+            self.metadata_updates.append(dict_input)
+
     def update_config(
         self,
         config: jobflow.JobConfig | dict,

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/core/job.py

@@ -6,14 +6,17 @@ import logging
 import typing
 import warnings
 from dataclasses import dataclass, field
+from typing import cast, overload
 
 from monty.json import MSONable, jsanitize
+from typing_extensions import Self
 
 from jobflow.core.reference import OnMissing, OutputReference
 from jobflow.utils.uid import suid
 
 if typing.TYPE_CHECKING:
     from collections.abc import Hashable, Sequence
+    from pathlib import Path
     from typing import Any, Callable
 
     from networkx import DiGraph
@@ -65,7 +68,24 @@ class JobConfig(MSONable):
     response_manager_config: dict = field(default_factory=dict)
 
 
-def job(method: Callable = None, **job_kwargs):
+@overload
+def job(method: Callable | None = None) -> Callable[..., Job]:
+    pass
+
+
+@overload
+def job(method: Callable, **job_kwargs) -> Callable[..., Job]:
+    pass
+
+
+@overload
+def job(method: None = None, **job_kwargs) -> Callable[..., Callable[..., Job]]:
+    pass
+
+
+def job(
+    method: Callable | None = None, **job_kwargs
+) -> Callable[..., Job] | Callable[..., Callable[..., Job]]:
     """
     Wrap a function to produce a :obj:`Job`.
 
@@ -277,12 +297,12 @@ class Job(MSONable):
     --------
     Builtin functions such as :obj:`print` can be specified.
 
-    >>> print_task = Job(function=print, args=("I am a job", ))
+    >>> print_task = Job(function=print, function_args=("I am a job", ))
 
     Or other functions of the Python standard library.
 
     >>> import os
-    >>> Job(function=os.path.join, args=("folder", "filename.txt"))
+    >>> Job(function=os.path.join, function_args=("folder", "filename.txt"))
 
     To use custom functions, the functions should be importable (i.e. not
     defined in another function). For example, if the following function is defined
@@ -290,7 +310,7 @@ class Job(MSONable):
 
     >>> def add(a, b):
     ...     return a + b
-    >>> add_job = Job(function=add, args=(1, 2))
+    >>> add_job = Job(function=add, function_args=(1, 2))
 
     More details are given in the :obj:`job` decorator docstring.
 
@@ -313,6 +333,7 @@ class Job(MSONable):
         hosts: list[str] = None,
         metadata_updates: list[dict[str, Any]] = None,
         config_updates: list[dict[str, Any]] = None,
+        name_updates: list[dict[str, Any]] = None,
         **kwargs,
     ):
         from copy import deepcopy
@@ -322,7 +343,6 @@ class Job(MSONable):
         function_args = () if function_args is None else function_args
         function_kwargs = {} if function_kwargs is None else function_kwargs
         uuid = suid() if uuid is None else uuid
-        metadata = {} if metadata is None else metadata
         config = JobConfig() if config is None else config
 
         # make a deep copy of the function (means makers do not share the same instance)
@@ -333,10 +353,11 @@ class Job(MSONable):
         self.uuid = uuid
         self.index = index
         self.name = name
-        self.metadata = metadata
+        self.metadata = metadata or {}
         self.config = config
         self.hosts = hosts or []
         self.metadata_updates = metadata_updates or []
+        self.name_updates = name_updates or []
         self.config_updates = config_updates or []
         self._kwargs = kwargs
 
@@ -526,7 +547,7 @@ class Job(MSONable):
         self.uuid = uuid
         self.output = self.output.set_uuid(uuid)
 
-    def run(self, store: jobflow.JobStore) -> Response:
+    def run(self, store: jobflow.JobStore, job_dir: Path = None) -> Response:
         """
         Run the job.
 
@@ -581,7 +602,9 @@ class Job(MSONable):
             function = types.MethodType(function, bound)
 
         response = function(*self.function_args, **self.function_kwargs)
-        response = Response.from_job_returns(response, self.output_schema)
+        response = Response.from_job_returns(
+            response, self.output_schema, job_dir=job_dir
+        )
 
         if response.replace is not None:
             response.replace = prepare_replace(response.replace, self)
@@ -604,6 +627,8 @@ class Job(MSONable):
                     new_jobs.update_metadata(**metadata_update, dynamic=True)
                 for config_update in self.config_updates:
                     new_jobs.update_config(**config_update, dynamic=True)
+                for name_update in self.name_updates:
+                    new_jobs.append_name(**name_update, dynamic=True)
 
         if self.config.response_manager_config:
             passed_config = self.config.response_manager_config
@@ -872,7 +897,7 @@ class Job(MSONable):
                         dict_mod=dict_mod,
                     )
 
-    def append_name(self, append_str: str, prepend: bool = False):
+    def append_name(self, append_str: str, prepend: bool = False, dynamic: bool = True):
         """
         Append a string to the name of the job.
 
@@ -882,12 +907,18 @@ class Job(MSONable):
             A string to append.
         prepend
             Prepend the name rather than appending it.
+        dynamic
+            The updates will be propagated to Jobs/Flows dynamically generated at
+            runtime.
         """
         if prepend:
             self.name = append_str + self.name
         else:
             self.name += append_str
 
+        if dynamic:
+            self.name_updates.append({"append_str": append_str, "prepend": prepend})
+
     def update_metadata(
         self,
         update: dict[str, Any],
@@ -895,6 +926,7 @@ class Job(MSONable):
         function_filter: Callable = None,
         dict_mod: bool = False,
         dynamic: bool = True,
+        callback_filter: Callable[[jobflow.Flow | Job], bool] = lambda _: True,
     ):
         """
         Update the metadata of the job.
@@ -918,6 +950,9 @@ class Job(MSONable):
         dynamic
             The updates will be propagated to Jobs/Flows dynamically generated at
             runtime.
+        callback_filter
+            A function that takes a Flow or Job instance and returns True if updates
+            should be applied to that instance. Allows for custom filtering logic.
 
         Examples
         --------
@@ -936,11 +971,16 @@ class Job(MSONable):
         will not only set the `example` metadata to the `test_job`, but also to all the
         new Jobs that will be generated at runtime by the ExampleMaker.
 
-        `update_metadata` can be called multiple times with different `name_filter` or
-        `function_filter` to control which Jobs will be updated.
+        `update_metadata` can be called multiple times with different filters to control
+        which Jobs will be updated. For example, using a callback filter:
 
-        At variance, if `dynamic` is set to `False` the `example` metadata will only be
-        added to the `test_job` and not to the generated Jobs.
+        >>> test_job.update_metadata(
+        ...     {"material_id": 42},
+        ...     callback_filter=lambda job: isinstance(job.maker, SomeMaker)
+        ... )
+
+        At variance, if `dynamic` is set to `False` the metadata will only be
+        added to the filtered Jobs and not to any generated Jobs.
         """
         from jobflow.utils.dict_mods import apply_mod
 
@@ -950,6 +990,7 @@ class Job(MSONable):
                 "name_filter": name_filter,
                 "function_filter": function_filter,
                 "dict_mod": dict_mod,
+                "callback_filter": callback_filter,
             }
             self.metadata_updates.append(dict_input)
 
@@ -957,7 +998,6 @@ class Job(MSONable):
         function_filter = getattr(function_filter, "__wrapped__", function_filter)
         function = getattr(self.function, "__wrapped__", self.function)
 
-        # if function_filter is not None and function_filter != self.function:
         if function_filter is not None and function_filter != function:
             return
 
@@ -966,6 +1006,9 @@ class Job(MSONable):
         ):
             return
 
+        if callback_filter(self) is False:
+            return
+
         # if we get to here then we pass all the filters
         if dict_mod:
             apply_mod(update, self.metadata)
@@ -1134,8 +1177,8 @@ class Job(MSONable):
         prepend
             Insert the UUIDs at the beginning of the list rather than extending it.
         """
-        if not isinstance(hosts_uuids, (list, tuple)):
-            hosts_uuids = [hosts_uuids]  # type: ignore
+        if isinstance(hosts_uuids, str):
+            hosts_uuids = [hosts_uuids]
         if prepend:
             self.hosts[0:0] = hosts_uuids
         else:
@@ -1170,6 +1213,8 @@ class Response(typing.Generic[T]):
         Stop any children of the current flow.
     stop_jobflow
         Stop executing all remaining jobs.
+    job_dir
+        The directory where the job was run.
     """
 
     output: T = None
@@ -1179,13 +1224,15 @@ class Response(typing.Generic[T]):
     stored_data: dict[Hashable, Any] = None
     stop_children: bool = False
     stop_jobflow: bool = False
+    job_dir: str | Path = None
 
     @classmethod
     def from_job_returns(
         cls,
         job_returns: Any | None,
         output_schema: type[BaseModel] = None,
-    ) -> Response:
+        job_dir: str | Path = None,
+    ) -> Self:
         """
         Generate a :obj:`Response` from the outputs of a :obj:`Job`.
 
@@ -1199,6 +1246,8 @@ class Response(typing.Generic[T]):
         output_schema
             A pydantic model associated with the job. Used to enforce a schema for the
             outputs.
+        job_dir
+            The directory where the job was run.
 
         Raises
         ------
@@ -1215,17 +1264,18 @@ class Response(typing.Generic[T]):
                 # only apply output schema if there is no replace.
                 job_returns.output = apply_schema(job_returns.output, output_schema)
 
-            return job_returns
+            job_returns.job_dir = job_dir
+            return cast(Self, job_returns)
 
         if isinstance(job_returns, (list, tuple)):
             # check that a Response object is not given as one of many outputs
-            for r in job_returns:
-                if isinstance(r, Response):
+            for resp in job_returns:
+                if isinstance(resp, Response):
                     raise ValueError(
                         "Response cannot be returned in combination with other outputs."
                     )
 
-        return cls(output=apply_schema(job_returns, output_schema))
+        return cls(output=apply_schema(job_returns, output_schema), job_dir=job_dir)
 
 
 def apply_schema(output: Any, schema: type[BaseModel] | None):

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/core/maker.py

@@ -261,7 +261,7 @@ def recursive_call(
 
     if isinstance(class_filter, Maker):
         # Maker instance supplied rather than a Maker class
-        class_filter = class_filter.__class__
+        class_filter = class_filter.__class__  # type: ignore[assignment]
 
     def _filter(nested_obj: Maker):
         # Filter the Maker object
@@ -269,9 +269,7 @@ def recursive_call(
             return False
         if name_filter is not None and name_filter not in nested_obj.name:
             return False
-        if class_filter is not None and not isinstance(nested_obj, class_filter):
-            return False
-        return True
+        return class_filter is None or isinstance(nested_obj, class_filter)
 
     d = obj.as_dict()
 

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/core/reference.py

@@ -82,7 +82,7 @@ class OutputReference(MSONable):
     OutputReference(1234, ['key'], [0], .value)
     """
 
-    __slots__ = ("uuid", "attributes", "output_schema")
+    __slots__ = ("attributes", "output_schema", "uuid")
 
     def __init__(
         self,

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/core/store.py

@@ -17,6 +17,7 @@ if typing.TYPE_CHECKING:
     from typing import Any, Optional, Union
 
     from maggma.core import Sort
+    from typing_extensions import Self
 
     from jobflow.core.schemas import JobStoreDocument
 
@@ -545,9 +546,9 @@ class JobStore(Store):
         )
 
     @classmethod
-    def from_file(cls: type[T], db_file: str | Path, **kwargs) -> T:
+    def from_file(cls, db_file: str | Path, **kwargs) -> Self:
         """
-        Create an JobStore from a database file.
+        Create a JobStore from a database file.
 
         Two options are supported for the database file. The file should be in json or
         yaml format.
@@ -555,7 +556,7 @@ class JobStore(Store):
         The simplest format is a monty dumped version of the store, generated using:
 
         >>> from monty.serialization import dumpfn
-        >>> dumpfn("job_store.yaml", job_store)
+        >>> dumpfn(job_store, "job_store.yaml")
 
         Alternatively, the file can contain the keys docs_store, additional_stores and
         any other keyword arguments supported by the :obj:`JobStore` constructor. The
@@ -605,7 +606,7 @@ class JobStore(Store):
         return cls.from_dict_spec(store_info, **kwargs)
 
     @classmethod
-    def from_dict_spec(cls: type[T], spec: dict, **kwargs) -> T:
+    def from_dict_spec(cls, spec: dict, **kwargs) -> Self:
         """
         Create an JobStore from a dict specification.
 

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/managers/fireworks.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import typing
 
 from fireworks import FiretaskBase, Firework, FWAction, Workflow, explicit_serialize
+from fireworks.utilities.fw_serializers import recursive_serialize, serialize_fw
+from monty.json import jsanitize
 
 if typing.TYPE_CHECKING:
     from collections.abc import Sequence
@@ -197,3 +199,16 @@ class JobFiretask(FiretaskBase):
             defuse_workflow=response.stop_jobflow,
             defuse_children=response.stop_children,
         )
+
+    @serialize_fw
+    @recursive_serialize
+    def to_dict(self) -> dict:
+        """
+        Serialize version of the FireTask.
+
+        Overrides the original method to explicitly jsanitize the Job
+        to handle cases not properly handled by fireworks, like a Callable.
+        """
+        d = dict(self)
+        d["job"] = jsanitize(d["job"].as_dict())
+        return d

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/managers/local.py

@@ -15,8 +15,8 @@ logger = logging.getLogger(__name__)
 
 def run_locally(
     flow: jobflow.Flow | jobflow.Job | list[jobflow.Job],
-    log: bool = True,
-    store: jobflow.JobStore = None,
+    log: bool | str = True,
+    store: jobflow.JobStore | None = None,
     create_folders: bool = False,
     root_dir: str | Path | None = None,
     ensure_success: bool = False,
@@ -30,8 +30,11 @@ def run_locally(
     ----------
     flow : Flow | Job | list[Job]
         A job or flow.
-    log : bool
-        Whether to print log messages.
+    log : bool | str
+        Controls logging. Defaults to True. Can be:
+        - False: disable logging
+        - True: use default logging format (read from ~/.jobflow.yaml)
+        - str: custom logging format string (e.g. "%(message)s" for more concise output)
     store : JobStore
         A job store. If a job store is not specified then
         :obj:`JobflowSettings.JOB_STORE` will be used. By default this is a maggma
@@ -46,7 +49,7 @@ def run_locally(
         Raise an error if the flow was not executed successfully.
     allow_external_references : bool
         If False all the references to other outputs should be from other Jobs
-        of the Flow.
+        of the same Flow.
     raise_immediately : bool
         If True, raise an exception immediately if a job fails. If False, continue
         running the flow and only raise an exception at the end if the flow did not
@@ -58,7 +61,7 @@ def run_locally(
         The responses of the jobs, as a dict of ``{uuid: {index: response}}``.
     """
     from collections import defaultdict
-    from datetime import datetime
+    from datetime import datetime, timezone
     from pathlib import Path
     from random import randint
 
@@ -77,7 +80,7 @@ def run_locally(
     store.connect()
 
     if log:
-        initialize_logger()
+        initialize_logger(fmt=log if isinstance(log, str) else "")
 
     flow = get_flow(flow, allow_external_references=allow_external_references)
 
@@ -152,7 +155,7 @@ def run_locally(
 
     def _get_job_dir():
         if create_folders:
-            time_now = datetime.utcnow().strftime(SETTINGS.DIRECTORY_FORMAT)
+            time_now = datetime.now(tz=timezone.utc).strftime(SETTINGS.DIRECTORY_FORMAT)
             job_dir = root_dir / f"job_{time_now}-{randint(10000, 99999)}"
             job_dir.mkdir()
             return job_dir
@@ -165,6 +168,8 @@ def run_locally(
             with cd(job_dir):
                 response, jobflow_stopped = _run_job(job, parents)
 
+            if response is not None:
+                response.job_dir = job_dir
             encountered_bad_response = encountered_bad_response or response is None
             if jobflow_stopped:
                 return False

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/settings.py

@@ -11,6 +11,8 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 from jobflow import JobStore
 
 DEFAULT_CONFIG_FILE_PATH = Path("~/.jobflow.yaml").expanduser().as_posix()
+DEFAULT_LOG_FORMAT = "%(asctime)s %(levelname)s %(message)s"
+DEFAULT_DIRECTORY_FORMAT = "%Y-%m-%d-%H-%M-%S-%f"
 
 
 def _default_additional_store():
@@ -28,7 +30,7 @@ class JobflowSettings(BaseSettings):
     """
     Settings for jobflow.
 
-    The default way to modify these is to modify ~/.jobflow.yaml. Alternatively,
+    The default way to modify these is to create a ~/.jobflow.yaml. Alternatively,
     the environment variable ``JOBFLOW_CONFIG_FILE`` can be set to point to a yaml file
     with jobflow settings.
 
@@ -114,9 +116,18 @@ class JobflowSettings(BaseSettings):
         "accepted formats.",
     )
     DIRECTORY_FORMAT: str = Field(
-        "%Y-%m-%d-%H-%M-%S-%f",
+        DEFAULT_DIRECTORY_FORMAT,
         description="Date stamp format used to create directories",
     )
+    LOG_FORMAT: str = Field(
+        DEFAULT_LOG_FORMAT,
+        description="""Logging format string. Common format codes:
+    - %(message)s - The logged message
+    - %(asctime)s - Human-readable time
+    - %(levelname)s - DEBUG, INFO, WARNING, ERROR, or CRITICAL
+    - %(name)s - Logger name
+    See Python logging documentation for more format codes.""",
+    )
 
     UID_TYPE: str = Field(
         "uuid4", description="Type of unique identifier to use to track jobs. "

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/utils/__init__.py

@@ -1,4 +1,5 @@
 """Utility functions for logging, enumerations and manipulating dictionaries."""
+
 from jobflow.utils.enum import ValueEnum
 from jobflow.utils.find import (
     contains_flow_or_job,

jobflow-0.1.19/src/jobflow/utils/log.py

@@ -0,0 +1,41 @@
+"""Tools for logging."""
+
+from __future__ import annotations
+
+import logging
+
+
+def initialize_logger(level: int = logging.INFO, fmt: str = "") -> logging.Logger:
+    """Initialize the default logger.
+
+    Parameters
+    ----------
+    level
+        The log level.
+    fmt
+        Custom logging format string. Defaults to JobflowSettings.LOG_FORMAT.
+        Common format codes:
+        - %(message)s - The logged message
+        - %(asctime)s - Human-readable time
+        - %(levelname)s - DEBUG, INFO, WARNING, ERROR, or CRITICAL
+        See Python logging documentation for more format codes.
+
+    Returns
+    -------
+    Logger
+        A logging instance with customized formatter and handlers.
+    """
+    import sys
+
+    from jobflow import SETTINGS
+
+    log = logging.getLogger("jobflow")
+    log.setLevel(level)
+    log.handlers = []  # reset logging handlers if they already exist
+
+    formatter = logging.Formatter(fmt or SETTINGS.LOG_FORMAT)
+
+    screen_handler = logging.StreamHandler(stream=sys.stdout)
+    screen_handler.setFormatter(formatter)
+    log.addHandler(screen_handler)
+    return log

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/utils/uid.py

@@ -1,4 +1,5 @@
 """Tools for generating UUIDs."""
+
 from __future__ import annotations
 
 from uuid import UUID
@@ -11,7 +12,7 @@ except ImportError:  # pragma: no cover
         "Install it with `pip install jobflow[ulid]` or `pip install python-ulid`."
     )
 
-    class ULID:  # type: ignore
+    class ULID:  # type: ignore[no-redef]
         """Fake ULID class for raising import error."""
 
         def __init__(self, *args, **kwargs):

{jobflow-0.1.17 → jobflow-0.1.19}/src/jobflow/utils/uuid.py

@@ -1,4 +1,5 @@
 """Tools for generating UUIDs."""
+
 from monty.dev import deprecated
 
 

{jobflow-0.1.17 → jobflow-0.1.19/src/jobflow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: jobflow
-Version: 0.1.17
+Version: 0.1.19
 Summary: jobflow is a library for writing computational workflows
 Author-email: Alex Ganose <a.ganose@imperial.ac.uk>
 License: modified BSD
@@ -34,19 +34,20 @@ Requires-Dist: pydash
 Provides-Extra: ulid
 Requires-Dist: python-ulid; extra == "ulid"
 Provides-Extra: docs
-Requires-Dist: autodoc_pydantic==2.0.1; extra == "docs"
-Requires-Dist: furo==2023.9.10; extra == "docs"
-Requires-Dist: ipython==8.20.0; extra == "docs"
-Requires-Dist: myst_parser==2.0.0; extra == "docs"
-Requires-Dist: nbsphinx==0.9.3; extra == "docs"
+Requires-Dist: autodoc_pydantic==2.1.0; extra == "docs"
+Requires-Dist: furo==2024.8.6; extra == "docs"
+Requires-Dist: ipython==8.29.0; extra == "docs"
+Requires-Dist: myst_parser==4.0.0; extra == "docs"
+Requires-Dist: nbsphinx==0.9.5; extra == "docs"
 Requires-Dist: sphinx-copybutton==0.5.2; extra == "docs"
-Requires-Dist: sphinx==7.2.6; extra == "docs"
+Requires-Dist: sphinx==8.1.3; extra == "docs"
 Provides-Extra: dev
 Requires-Dist: pre-commit>=2.12.1; extra == "dev"
+Requires-Dist: typing_extensions; python_version < "3.11" and extra == "dev"
 Provides-Extra: tests
 Requires-Dist: moto==4.2.13; extra == "tests"
-Requires-Dist: pytest-cov==4.1.0; extra == "tests"
-Requires-Dist: pytest==7.4.4; extra == "tests"
+Requires-Dist: pytest-cov==6.0.0; extra == "tests"
+Requires-Dist: pytest==8.3.3; extra == "tests"
 Provides-Extra: vis
 Requires-Dist: matplotlib; extra == "vis"
 Requires-Dist: pydot; extra == "vis"
@@ -54,20 +55,22 @@ Provides-Extra: fireworks
 Requires-Dist: FireWorks; extra == "fireworks"
 Provides-Extra: strict
 Requires-Dist: FireWorks==2.0.3; extra == "strict"
-Requires-Dist: PyYAML==6.0.1; extra == "strict"
-Requires-Dist: maggma==0.61.0; extra == "strict"
-Requires-Dist: matplotlib==3.8.2; extra == "strict"
-Requires-Dist: monty==2023.11.3; extra == "strict"
+Requires-Dist: PyYAML==6.0.2; extra == "strict"
+Requires-Dist: maggma==0.70.0; extra == "strict"
+Requires-Dist: matplotlib==3.9.2; extra == "strict"
+Requires-Dist: monty==2024.10.21; extra == "strict"
 Requires-Dist: moto==4.2.13; extra == "strict"
 Requires-Dist: networkx==3.2.1; extra == "strict"
-Requires-Dist: pydantic-settings==2.1.0; extra == "strict"
-Requires-Dist: pydantic==2.5.3; extra == "strict"
-Requires-Dist: pydash==7.0.6; extra == "strict"
+Requires-Dist: pydantic-settings==2.6.1; extra == "strict"
+Requires-Dist: pydantic==2.9.2; extra == "strict"
+Requires-Dist: pydash==8.0.4; extra == "strict"
 Requires-Dist: pydot==2.0.0; extra == "strict"
-Requires-Dist: typing-extensions==4.9.0; extra == "strict"
-Requires-Dist: python-ulid==2.2.0; extra == "strict"
+Requires-Dist: python-ulid==3.0.0; extra == "strict"
+Requires-Dist: typing-extensions==4.12.2; extra == "strict"
 
-# jobflow
+<div align="center">
+
+# ![Jobflow](docs/_static/img/jobflow_logo.svg)
 
 [![tests](https://img.shields.io/github/actions/workflow/status/materialsproject/jobflow/testing.yml?branch=main&label=tests)](https://github.com/materialsproject/jobflow/actions?query=workflow%3Atesting)
 [![code coverage](https://img.shields.io/codecov/c/gh/materialsproject/jobflow/main)](https://codecov.io/gh/materialsproject/jobflow/)
@@ -75,11 +78,14 @@ Requires-Dist: python-ulid==2.2.0; extra == "strict"
 ![supported python versions](https://img.shields.io/pypi/pyversions/jobflow)
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.05995/status.svg)](https://doi.org/10.21105/joss.05995)
 
+</div>
+
 [Documentation](https://materialsproject.github.io/jobflow/) | [PyPI](https://pypi.org/project/jobflow/) | [GitHub](https://github.com/materialsproject/jobflow) | [Paper](https://doi.org/10.21105/joss.05995)
 
 Jobflow is a free, open-source library for writing and executing workflows. Complex
 workflows can be defined using simple python functions and executed locally or on
-arbitrary computing resources using the [FireWorks][fireworks] workflow manager.
+arbitrary computing resources using the [jobflow-remote][jfr] or [FireWorks][fireworks]
+workflow managers.
 
 Some features that distinguish jobflow are dynamic workflows, easy compositing and
 connecting of workflows, and the ability to store workflow outputs across multiple
@@ -98,7 +104,7 @@ Some of its features include:
   way to build complex workflows.
 - Integration with multiple databases (MongoDB, S3, GridFS, and more) through the
   [Maggma][maggma] package.
-- Support for the [FireWorks][fireworks] workflow management system, allowing workflow
+- Support for the [jobflow-remote][jfr] and [FireWorks][fireworks] workflow management systems, allowing workflow
   execution on multicore machines or through a queue, on a single machine or multiple
   machines.
 - Support for dynamic workflows — workflows that modify themselves or create new ones
@@ -192,6 +198,7 @@ Jobflow was designed by Alex Ganose, Anubhav Jain, Gian-Marco Rignanese, David W
 
 [maggma]: https://materialsproject.github.io/maggma/
 [fireworks]: https://materialsproject.github.io/fireworks/
+[jfr]: https://matgenix.github.io/jobflow-remote
 [help-forum]: https://matsci.org/c/fireworks
 [issues]: https://github.com/materialsproject/jobflow/issues
 [changelog]: https://materialsproject.github.io/jobflow/changelog.html

jobflow-0.1.19/src/jobflow.egg-info/requires.txt

@@ -0,0 +1,52 @@
+PyYAML
+maggma>=0.57.0
+monty>=2023.9.25
+networkx
+pydantic-settings>=2.0.3
+pydantic>=2.0.1
+pydash
+
+[dev]
+pre-commit>=2.12.1
+
+[dev:python_version < "3.11"]
+typing_extensions
+
+[docs]
+autodoc_pydantic==2.1.0
+furo==2024.8.6
+ipython==8.29.0
+myst_parser==4.0.0
+nbsphinx==0.9.5
+sphinx-copybutton==0.5.2
+sphinx==8.1.3
+
+[fireworks]
+FireWorks
+
+[strict]
+FireWorks==2.0.3
+PyYAML==6.0.2
+maggma==0.70.0
+matplotlib==3.9.2
+monty==2024.10.21
+moto==4.2.13
+networkx==3.2.1
+pydantic-settings==2.6.1
+pydantic==2.9.2
+pydash==8.0.4
+pydot==2.0.0
+python-ulid==3.0.0
+typing-extensions==4.12.2
+
+[tests]
+moto==4.2.13
+pytest-cov==6.0.0
+pytest==8.3.3
+
+[ulid]
+python-ulid
+
+[vis]
+matplotlib
+pydot

jobflow-0.1.17/src/jobflow/utils/log.py

@@ -1,29 +0,0 @@
-"""Tools for logging."""
-
-import logging
-
-
-def initialize_logger(level: int = logging.INFO) -> logging.Logger:
-    """Initialize the default logger.
-
-    Parameters
-    ----------
-    level
-        The log level.
-
-    Returns
-    -------
-    Logger
-        A logging instance with customized formatter and handlers.
-    """
-    import sys
-
-    log = logging.getLogger("jobflow")
-    log.setLevel(level)
-    log.handlers = []  # reset logging handlers if they already exist
-
-    fmt = logging.Formatter("%(asctime)s %(levelname)s %(message)s")
-    screen_handler = logging.StreamHandler(stream=sys.stdout)
-    screen_handler.setFormatter(fmt)
-    log.addHandler(screen_handler)
-    return log

jobflow-0.1.17/src/jobflow.egg-info/requires.txt

@@ -1,49 +0,0 @@
-PyYAML
-maggma>=0.57.0
-monty>=2023.9.25
-networkx
-pydantic-settings>=2.0.3
-pydantic>=2.0.1
-pydash
-
-[dev]
-pre-commit>=2.12.1
-
-[docs]
-autodoc_pydantic==2.0.1
-furo==2023.9.10
-ipython==8.20.0
-myst_parser==2.0.0
-nbsphinx==0.9.3
-sphinx-copybutton==0.5.2
-sphinx==7.2.6
-
-[fireworks]
-FireWorks
-
-[strict]
-FireWorks==2.0.3
-PyYAML==6.0.1
-maggma==0.61.0
-matplotlib==3.8.2
-monty==2023.11.3
-moto==4.2.13
-networkx==3.2.1
-pydantic-settings==2.1.0
-pydantic==2.5.3
-pydash==7.0.6
-pydot==2.0.0
-typing-extensions==4.9.0
-python-ulid==2.2.0
-
-[tests]
-moto==4.2.13
-pytest-cov==4.1.0
-pytest==7.4.4
-
-[ulid]
-python-ulid
-
-[vis]
-matplotlib
-pydot