taskflow-meter 1.1.0__tar.gz → 1.2.0__tar.gz

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: taskflow-meter
-Version: 1.1.0
+Version: 1.2.0
 Summary: Monitoring interfaces (ASGI, WSGI, datasource) for OpenStack TaskFlow flow execution progress
-Project-URL: Homepage, https://github.com/daipham3213/taskflow-meter
-Project-URL: Source, https://github.com/daipham3213/taskflow-meter
-Project-URL: Issues, https://github.com/daipham3213/taskflow-meter/issues
-Project-URL: Changelog, https://github.com/daipham3213/taskflow-meter/releases
+Project-URL: Homepage, https://github.com/daipham3213/taskflow.meter
+Project-URL: Source, https://github.com/daipham3213/taskflow.meter
+Project-URL: Issues, https://github.com/daipham3213/taskflow.meter/issues
+Project-URL: Changelog, https://github.com/daipham3213/taskflow.meter/releases
 Author-email: Pham Le Gia Dai <daipham.3213@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -15,13 +15,14 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Requires-Dist: oslo-config>=6.9.0
 Requires-Dist: taskflow>=4.2.0
 Provides-Extra: all
@@ -40,6 +41,12 @@ Description-Content-Type: text/markdown
 
 # taskflow-meter
 
+[![ci](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml)
+[![conformance](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml)
+[![PyPI](https://img.shields.io/pypi/v/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![Python versions](https://img.shields.io/pypi/pyversions/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
 Monitoring interfaces — ASGI, WSGI, datasources, transports — for observing
 [OpenStack TaskFlow](https://opendev.org/openstack/taskflow) flow execution
 progress.
@@ -200,7 +207,7 @@ serving an empty stream that cannot be told apart from silence.
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.10+
 - taskflow 4.2.0+
 - oslo.config 6.9.0+
 
@@ -263,8 +270,8 @@ CI also runs the suite with every declared dependency floor installed exactly,
 which is the only job that checks those floors are real. To reproduce it:
 
 ```bash
-uv lock --python 3.11 --resolution lowest-direct
-uv sync --python 3.11 --group dev --all-extras --resolution lowest-direct
+uv lock --python 3.10 --resolution lowest-direct
+uv sync --python 3.10 --group dev --all-extras --resolution lowest-direct
 uv run --frozen --no-sync pytest
 ```
 

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/README.md

@@ -1,5 +1,11 @@
 # taskflow-meter
 
+[![ci](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/ci.yml)
+[![conformance](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml/badge.svg)](https://github.com/daipham3213/taskflow.meter/actions/workflows/conformance.yml)
+[![PyPI](https://img.shields.io/pypi/v/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![Python versions](https://img.shields.io/pypi/pyversions/taskflow-meter.svg)](https://pypi.org/project/taskflow-meter/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
 Monitoring interfaces — ASGI, WSGI, datasources, transports — for observing
 [OpenStack TaskFlow](https://opendev.org/openstack/taskflow) flow execution
 progress.
@@ -160,7 +166,7 @@ serving an empty stream that cannot be told apart from silence.
 
 ## Requirements
 
-- Python 3.11+
+- Python 3.10+
 - taskflow 4.2.0+
 - oslo.config 6.9.0+
 
@@ -223,8 +229,8 @@ CI also runs the suite with every declared dependency floor installed exactly,
 which is the only job that checks those floors are real. To reproduce it:
 
 ```bash
-uv lock --python 3.11 --resolution lowest-direct
-uv sync --python 3.11 --group dev --all-extras --resolution lowest-direct
+uv lock --python 3.10 --resolution lowest-direct
+uv sync --python 3.10 --group dev --all-extras --resolution lowest-direct
 uv run --frozen --no-sync pytest
 ```
 

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/pyproject.toml

@@ -7,7 +7,7 @@ name = "taskflow-meter"
 dynamic = ["version"]
 description = "Monitoring interfaces (ASGI, WSGI, datasource) for OpenStack TaskFlow flow execution progress"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [
@@ -20,6 +20,7 @@ classifiers = [
     "Intended Audience :: System Administrators",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -51,10 +52,10 @@ all = [
 taskflow-meter = "taskflow_meter.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/daipham3213/taskflow-meter"
-Source = "https://github.com/daipham3213/taskflow-meter"
-Issues = "https://github.com/daipham3213/taskflow-meter/issues"
-Changelog = "https://github.com/daipham3213/taskflow-meter/releases"
+Homepage = "https://github.com/daipham3213/taskflow.meter"
+Source = "https://github.com/daipham3213/taskflow.meter"
+Issues = "https://github.com/daipham3213/taskflow.meter/issues"
+Changelog = "https://github.com/daipham3213/taskflow.meter/releases"
 
 # Plugin entry points are declared as their modules land -- one pointing at a
 # module that does not exist yet breaks discovery for the whole group.
@@ -139,7 +140,7 @@ include = [
 
 [tool.ruff]
 line-length = 79
-target-version = "py311"
+target-version = "py310"
 src = ["."]
 
 [tool.ruff.lint]
@@ -174,7 +175,7 @@ force-single-line = true
 docstring-code-format = true
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.10"
 strict = true
 warn_unreachable = true
 files = ["taskflow_meter", "tests", "tools", "examples"]

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.0'
-__version_tuple__ = version_tuple = (1, 1, 0)
+__version__ = version = '1.2.0'
+__version_tuple__ = version_tuple = (1, 2, 0)
 
 __commit_id__ = commit_id = None

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/api/sse.py

@@ -218,5 +218,8 @@ async def aiter_frames(
             await asyncio.sleep(interval)
         else:
             # Sleep, but wake immediately if the client leaves.
-            with contextlib.suppress(TimeoutError):
+            # asyncio.TimeoutError, spelled out: it is the builtin from
+            # 3.11 on, but a class of its own before that, so the bare
+            # name catches nothing on 3.10 and the sleep raises.
+            with contextlib.suppress(asyncio.TimeoutError):
                 await asyncio.wait_for(stop.wait(), interval)

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/collect/listener.py

@@ -28,8 +28,11 @@ import time
 from collections.abc import Callable
 from typing import Any
 
+from taskflow import states
 from taskflow.listeners import base as tf_listeners
+from taskflow.types import failure as tf_failure
 
+from taskflow_meter import models
 from taskflow_meter.events import Event
 from taskflow_meter.events import EventKind
 from taskflow_meter.events import SequenceAllocator
@@ -100,9 +103,25 @@ class MeterListener(tf_listeners.Listener):
     ) -> None:
         extra: dict[str, Any] = {}
         if "result" in details:
+            result = details["result"]
             # Results are arbitrary application objects and are not
             # ours to copy around; their presence is the useful part.
-            extra["has_result"] = details["result"] is not None
+            extra["has_result"] = result is not None
+            # Except when the result *is* the failure, which is the one
+            # thing anybody watching a flow needs the detail of. Rendered
+            # in the same shape the persistence datasource reports, so a
+            # client cannot tell which producer it is reading.
+            if isinstance(result, tf_failure.Failure):
+                # Which one it is follows from the state, not from the
+                # intention: taskflow does not put an intention on these
+                # notifications, and only a revert that itself failed
+                # reaches REVERT_FAILURE.
+                key = (
+                    "revert_failure"
+                    if state == states.REVERT_FAILURE
+                    else "failure"
+                )
+                extra[key] = models.failure_dict(result)
         self._safely(
             EventKind.ATOM_STATE,
             state=state,

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/datasource/base.py

@@ -24,12 +24,14 @@ import abc
 from collections.abc import Iterable
 from dataclasses import dataclass
 from types import TracebackType
-from typing import Self
+from typing import TypeVar
 
 from taskflow_meter.events import Event
 from taskflow_meter.models import AtomSnapshot
 from taskflow_meter.models import FlowSnapshot
 
+_D = TypeVar("_D", bound="DataSource")
+
 #: Flows returned by a single unqualified listing.
 DEFAULT_FLOW_LIMIT = 50
 
@@ -96,7 +98,7 @@ class DataSource(abc.ABC):
     def stop(self) -> None:  # noqa: B027 - optional hook, not abstract
         """Release it again.  Idempotent, and safe to call unstarted."""
 
-    def __enter__(self) -> Self:
+    def __enter__(self: _D) -> _D:
         self.start()
         return self
 

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/datasource/persistence.py

@@ -46,6 +46,7 @@ from taskflow import exceptions as tf_exc
 from taskflow.persistence import backends as tf_backends
 from taskflow.persistence import models as tf_models
 
+from taskflow_meter import models
 from taskflow_meter.datasource.base import DEFAULT_EVENT_LIMIT
 from taskflow_meter.datasource.base import DEFAULT_FLOW_LIMIT
 from taskflow_meter.datasource.base import DataSource
@@ -281,8 +282,10 @@ def _atom_snapshot(detail: Any) -> AtomSnapshot:
         intention=detail.intention,
         progress=float(meta.get(_META_PROGRESS) or 0.0),
         progress_details=meta.get(_META_PROGRESS_DETAILS),
-        failure=_failure_dict(detail.failure),
-        revert_failure=_failure_dict(getattr(detail, "revert_failure", None)),
+        failure=models.failure_dict(detail.failure),
+        revert_failure=models.failure_dict(
+            getattr(detail, "revert_failure", None)
+        ),
         # Carrying results would mean copying arbitrary application data
         # into a monitoring path, so only their presence is reported.  A
         # task that returns None is indistinguishable from one that
@@ -292,17 +295,6 @@ def _atom_snapshot(detail: Any) -> AtomSnapshot:
     )
 
 
-def _failure_dict(failure: Any) -> dict[str, Any] | None:
-    """Render a taskflow Failure, tolerating anything that is not one."""
-    if failure is None:
-        return None
-    try:
-        return dict(failure.to_dict())
-    except Exception:
-        LOG.warning("could not serialise a failure", exc_info=True)
-        return {"unserialisable": repr(failure)}
-
-
 def _epoch(when: Any) -> float | None:
     """Convert a datetime to a float, or give up quietly."""
     try:

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/datasource/sqlalchemy/migrations/env.py

@@ -30,6 +30,17 @@ from taskflow_meter.datasource.sqlalchemy.models import metadata
 config = context.config
 target_metadata = metadata
 
+#: Default name of alembic's own bookkeeping table.  Overridable,
+#: because this schema may share a database with a host service that has
+#: an alembic tree of its own -- and two trees writing one
+#: ``alembic_version`` row each mistake the other's revision for a
+#: missing one.
+DEFAULT_VERSION_TABLE = "alembic_version"
+
+
+def _version_table() -> str:
+    return config.get_main_option("version_table", DEFAULT_VERSION_TABLE)
+
 
 def run_migrations_offline() -> None:
     context.configure(
@@ -37,6 +48,7 @@ def run_migrations_offline() -> None:
         target_metadata=target_metadata,
         literal_binds=True,
         dialect_opts={"paramstyle": "named"},
+        version_table=_version_table(),
     )
     with context.begin_transaction():
         context.run_migrations()
@@ -57,7 +69,11 @@ def run_migrations_online() -> None:
 
 
 def _run(connection: Any) -> None:
-    context.configure(connection=connection, target_metadata=target_metadata)
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        version_table=_version_table(),
+    )
     with context.begin_transaction():
         context.run_migrations()
 

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/datasource/sqlalchemy/source.py

@@ -352,11 +352,23 @@ def _event_from_row(row: Any) -> Event:
     )
 
 
-def upgrade(url: str, revision: str = "head") -> None:
+def upgrade(
+    url: str,
+    revision: str = "head",
+    *,
+    version_table: str | None = None,
+) -> None:
     """Bring a database up to date, the way a deployment should.
 
     Imported lazily: alembic is only needed by whoever runs migrations,
     not by every process that reads the results.
+
+    ``version_table`` renames alembic's bookkeeping table, which matters
+    when this schema shares a database with a host service that migrates
+    its own: both would otherwise keep their revision in
+    ``alembic_version``, and each would read the other's as a revision it
+    has never heard of.  Pass the same name on every upgrade of a given
+    database -- changing it later looks exactly like an unmigrated one.
     """
     from alembic import command
     from alembic.config import Config
@@ -364,4 +376,6 @@ def upgrade(url: str, revision: str = "head") -> None:
     config = Config()
     config.set_main_option("script_location", str(MIGRATIONS))
     config.set_main_option("sqlalchemy.url", url)
+    if version_table is not None:
+        config.set_main_option("version_table", version_table)
     command.upgrade(config, revision)

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/events.py

@@ -19,14 +19,32 @@ datasources, the API and any transport only ever handle one vocabulary.
 
 from __future__ import annotations
 
+import sys
 import threading
 from collections.abc import Mapping
 from dataclasses import asdict
 from dataclasses import dataclass
 from dataclasses import field
-from enum import StrEnum
 from typing import Any
-from typing import Self
+from typing import TypeVar
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        """As much of 3.11's ``StrEnum`` as this module relies on.
+
+        A plain ``str, Enum`` mixin renders as ``EventKind.FLOW_STATE``
+        under ``str()``, and the value is what goes on the wire.
+        """
+
+        def __str__(self) -> str:
+            return str.__str__(self)
+
+
+_E = TypeVar("_E", bound="Event")
 
 
 class EventKind(StrEnum):
@@ -77,7 +95,7 @@ class Event:
         return data
 
     @classmethod
-    def from_dict(cls, data: Mapping[str, Any]) -> Self:
+    def from_dict(cls: type[_E], data: Mapping[str, Any]) -> _E:
         """Rebuild from :meth:`to_dict` output.
 
         Unknown keys are rejected rather than dropped -- a transport

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/fold.py

@@ -55,7 +55,12 @@ def fold(flow: FlowSnapshot, event: Event) -> FlowSnapshot:
     flow = replace(flow, observed_at=max(flow.observed_at, event.ts))
 
     if event.kind is EventKind.FLOW_STATE:
-        return replace(flow, state=event.state)
+        # The name arrives on these events too, and has to be taken from
+        # one of them when the run was seeded by something else: the
+        # in-process producer emits the graph before anything runs, and a
+        # structure event carries no name to seed from.
+        name = _optional_str(event.details.get("flow_name")) or flow.name
+        return replace(flow, state=event.state, name=name)
 
     if event.kind in (EventKind.ATOM_STATE, EventKind.ATOM_PROGRESS):
         if event.atom_name is None:

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/meter.py

@@ -42,7 +42,7 @@ import logging
 import threading
 from collections.abc import AsyncIterator
 from types import TracebackType
-from typing import Self
+from typing import TypeVar
 
 from taskflow_meter.datasource.base import DEFAULT_EVENT_LIMIT
 from taskflow_meter.datasource.base import DEFAULT_FLOW_LIMIT
@@ -58,6 +58,8 @@ from taskflow_meter.poller import Poller
 
 LOG = logging.getLogger(__name__)
 
+_M = TypeVar("_M", bound="Meter")
+
 
 class Meter:
     """Owns a source, a store, a poller, and their lifecycle."""
@@ -180,7 +182,7 @@ class Meter:
             self._holders = 0
             self._stop_locked()
 
-    def __enter__(self) -> Self:
+    def __enter__(self: _M) -> _M:
         self.start()
         return self
 

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/models.py

@@ -20,12 +20,15 @@ producer it is talking to.
 
 from __future__ import annotations
 
+import logging
 from dataclasses import dataclass
 from dataclasses import field
 from typing import Any
 
 from taskflow_meter import states
 
+LOG = logging.getLogger(__name__)
+
 TASK = "task"
 RETRY = "retry"
 
@@ -141,3 +144,20 @@ class FlowSnapshot:
 
 def _clamp(value: float, low: float = 0.0, high: float = 1.0) -> float:
     return max(low, min(high, value))
+
+
+def failure_dict(failure: Any) -> dict[str, Any] | None:
+    """Render a taskflow ``Failure``, tolerating anything that is not one.
+
+    Lives here because both producers report failures and a client must
+    not have to tell which one it is reading: the persistence datasource
+    renders what taskflow stored, the listener renders what taskflow
+    handed it as it happened, and this is the one shape either way.
+    """
+    if failure is None:
+        return None
+    try:
+        return dict(failure.to_dict())
+    except Exception:
+        LOG.warning("could not serialise a failure", exc_info=True)
+        return {"unserialisable": repr(failure)}

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/taskflow_meter/transports/base.py

@@ -25,10 +25,13 @@ from collections.abc import Mapping
 from collections.abc import Sequence
 from types import TracebackType
 from typing import Any
-from typing import Self
+from typing import TypeVar
 
 from taskflow_meter.events import Event
 
+_P = TypeVar("_P", bound="Publisher")
+_S = TypeVar("_S", bound="Subscriber")
+
 
 def to_payload(events: Sequence[Event]) -> dict[str, Any]:
     """The envelope every transport that leaves the process sends.
@@ -64,7 +67,7 @@ class Publisher(abc.ABC):
     def publish(self, events: Sequence[Event]) -> None:
         """Send a batch.  Never called with an empty one."""
 
-    def __enter__(self) -> Self:
+    def __enter__(self: _P) -> _P:
         self.start()
         return self
 
@@ -108,7 +111,7 @@ class Subscriber(abc.ABC):
         rather than being trapped inside one.
         """
 
-    def __enter__(self) -> Self:
+    def __enter__(self: _S) -> _S:
         self.start()
         return self
 

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/tests/integration/test_attach.py

@@ -327,3 +327,50 @@ def test_nothing_is_left_registered_on_the_tasks() -> None:
 
     assert seen == []
     assert threading.active_count() <= before
+
+
+@pytest.mark.integration
+def test_the_flow_keeps_its_name_behind_the_structure_event() -> None:
+    # The graph is emitted before anything runs, so it is the event a run
+    # gets seeded from -- and it carries no flow name. The name arrives on
+    # every state event after it, and has to be taken from one of those or
+    # a client is told the flow is called "".
+    flow = linear_flow.Flow("named-flow").add(ProgressingTask("only"))
+    engine = engines.load(flow)
+
+    with attach(engine) as watched:
+        engine.run()
+        assert watched.flush(5.0)
+        assert watched.store is not None
+        snapshot = watched.store.get_flow(watched.run_id)
+
+    assert snapshot is not None
+    assert snapshot.name == "named-flow"
+
+
+@pytest.mark.integration
+def test_a_failed_task_reports_why_it_failed() -> None:
+    # The state says a task failed; the failure says what of. Reading
+    # persistence has always reported this, and watching the engine has
+    # the failure in hand as it happens.
+    class Exploding(task.Task):
+        def execute(self) -> None:
+            raise ValueError("no appliance answered")
+
+    flow = linear_flow.Flow("demo").add(Exploding("boom"))
+    engine = engines.load(flow)
+
+    with attach(engine) as watched:
+        with pytest.raises(ValueError, match="no appliance answered"):
+            engine.run()
+        assert watched.flush(5.0)
+        assert watched.store is not None
+        atoms = watched.store.get_atoms(watched.run_id)
+
+    assert atoms is not None
+    (atom,) = atoms
+    assert atom.failure is not None
+    assert "ValueError" in atom.failure["exc_type_names"]
+    assert "no appliance answered" in atom.failure["exception_str"]
+    # And the same shape the persistence datasource reports.
+    assert set(atom.failure) >= {"exc_type_names", "exception_str"}

{taskflow_meter-1.1.0 → taskflow_meter-1.2.0}/tests/unit/datasource/sqlalchemy/test_source.py

@@ -374,6 +374,26 @@ def test_upgrade_is_idempotent(tmp_path: Path) -> None:
     upgrade(url)
 
 
+def test_upgrade_can_be_told_where_to_keep_its_revision(
+    tmp_path: Path,
+) -> None:
+    # Sharing a database with a host service that migrates its own schema
+    # means sharing ``alembic_version`` unless this is passed, and each
+    # tree then reads the other's revision as one it has never heard of.
+    url = f"sqlite:///{tmp_path / 'shared.db'}"
+    upgrade(url, version_table="taskflow_meter_version")
+
+    store = SQLADataSource(url)
+    with store.engine.begin() as conn:
+        tables = set(sa.inspect(conn).get_table_names())
+
+    assert "taskflow_meter_version" in tables
+    assert "alembic_version" not in tables
+
+    # And it stays idempotent against the table it was given.
+    upgrade(url, version_table="taskflow_meter_version")
+
+
 def test_the_source_can_be_stopped_and_reused(
     tmp_path: Path,
 ) -> None: