samco-job-lifecycle 0.1.0__tar.gz

samco_job_lifecycle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 samcoai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

samco_job_lifecycle-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: samco-job-lifecycle
+Version: 0.1.0
+Summary: A small, dependency-free state machine for tracking job lifecycles
+Author: samcoai
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# samco-job-lifecycle
+
+A small, dependency-free Python library for tracking the state of a job. It validates transitions, records UTC timestamps, and keeps an in-memory event history. It does not run jobs or store them in a database.
+
+## Install
+
+```sh
+pip install samco-job-lifecycle
+```
+
+## Example
+
+```python
+from samco_job_lifecycle import Job, JobStatus
+
+job = Job("report-42")
+job.start()
+job.succeed()
+
+assert job.status is JobStatus.SUCCEEDED
+assert job.is_terminal
+print(job.events)
+```
+
+Valid paths are `pending -> running -> succeeded|failed|cancelled` and `pending -> cancelled`. Terminal jobs cannot transition again. Invalid changes raise `InvalidTransition`.
+
+Requires Python 3.9 or newer.

samco_job_lifecycle-0.1.0/README.md

@@ -0,0 +1,27 @@
+# samco-job-lifecycle
+
+A small, dependency-free Python library for tracking the state of a job. It validates transitions, records UTC timestamps, and keeps an in-memory event history. It does not run jobs or store them in a database.
+
+## Install
+
+```sh
+pip install samco-job-lifecycle
+```
+
+## Example
+
+```python
+from samco_job_lifecycle import Job, JobStatus
+
+job = Job("report-42")
+job.start()
+job.succeed()
+
+assert job.status is JobStatus.SUCCEEDED
+assert job.is_terminal
+print(job.events)
+```
+
+Valid paths are `pending -> running -> succeeded|failed|cancelled` and `pending -> cancelled`. Terminal jobs cannot transition again. Invalid changes raise `InvalidTransition`.
+
+Requires Python 3.9 or newer.

samco_job_lifecycle-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "samco-job-lifecycle"
+version = "0.1.0"
+description = "A small, dependency-free state machine for tracking job lifecycles"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "samcoai" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

samco_job_lifecycle-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

samco_job_lifecycle-0.1.0/src/samco_job_lifecycle/__init__.py

@@ -0,0 +1,5 @@
+"""Track jobs through a small, explicit lifecycle."""
+
+from .job import Job, JobEvent, JobStatus, InvalidTransition
+
+__all__ = ["Job", "JobEvent", "JobStatus", "InvalidTransition"]

samco_job_lifecycle-0.1.0/src/samco_job_lifecycle/job.py

@@ -0,0 +1,85 @@
+"""In-memory job lifecycle primitives."""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import List, Optional, Tuple
+
+
+class JobStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class InvalidTransition(ValueError):
+    """Raised when a requested state change is not allowed."""
+
+
+@dataclass(frozen=True)
+class JobEvent:
+    status: JobStatus
+    occurred_at: datetime
+    reason: Optional[str] = None
+
+
+_ALLOWED = {
+    JobStatus.PENDING: frozenset((JobStatus.RUNNING, JobStatus.CANCELLED)),
+    JobStatus.RUNNING: frozenset((JobStatus.SUCCEEDED, JobStatus.FAILED, JobStatus.CANCELLED)),
+    JobStatus.SUCCEEDED: frozenset(),
+    JobStatus.FAILED: frozenset(),
+    JobStatus.CANCELLED: frozenset(),
+}
+
+
+@dataclass
+class Job:
+    """A single in-memory job with validated state changes and an event history.
+
+    This class does not execute work or persist data. Its methods mutate the job.
+    """
+
+    id: str
+    status: JobStatus = field(default=JobStatus.PENDING, init=False)
+    _events: List[JobEvent] = field(default_factory=list, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.id, str) or not self.id.strip():
+            raise ValueError("job id must be a non-empty string")
+        self._events.append(JobEvent(self.status, datetime.now(timezone.utc)))
+
+    @property
+    def events(self) -> Tuple[JobEvent, ...]:
+        """Return an immutable view of the recorded state changes."""
+        return tuple(self._events)
+
+    @property
+    def is_terminal(self) -> bool:
+        return not _ALLOWED[self.status]
+
+    def transition(self, status: JobStatus, *, reason: Optional[str] = None) -> JobEvent:
+        """Change status and record a UTC timestamp; reject invalid transitions."""
+        if not isinstance(status, JobStatus):
+            raise TypeError("status must be a JobStatus")
+        if reason is not None and not isinstance(reason, str):
+            raise TypeError("reason must be a string or None")
+        if status not in _ALLOWED[self.status]:
+            raise InvalidTransition(f"cannot transition from {self.status.value} to {status.value}")
+        event = JobEvent(status, datetime.now(timezone.utc), reason)
+        self.status = status
+        self._events.append(event)
+        return event
+
+    def start(self) -> JobEvent:
+        return self.transition(JobStatus.RUNNING)
+
+    def succeed(self) -> JobEvent:
+        return self.transition(JobStatus.SUCCEEDED)
+
+    def fail(self, reason: Optional[str] = None) -> JobEvent:
+        return self.transition(JobStatus.FAILED, reason=reason)
+
+    def cancel(self, reason: Optional[str] = None) -> JobEvent:
+        return self.transition(JobStatus.CANCELLED, reason=reason)

samco_job_lifecycle-0.1.0/src/samco_job_lifecycle.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: samco-job-lifecycle
+Version: 0.1.0
+Summary: A small, dependency-free state machine for tracking job lifecycles
+Author: samcoai
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# samco-job-lifecycle
+
+A small, dependency-free Python library for tracking the state of a job. It validates transitions, records UTC timestamps, and keeps an in-memory event history. It does not run jobs or store them in a database.
+
+## Install
+
+```sh
+pip install samco-job-lifecycle
+```
+
+## Example
+
+```python
+from samco_job_lifecycle import Job, JobStatus
+
+job = Job("report-42")
+job.start()
+job.succeed()
+
+assert job.status is JobStatus.SUCCEEDED
+assert job.is_terminal
+print(job.events)
+```
+
+Valid paths are `pending -> running -> succeeded|failed|cancelled` and `pending -> cancelled`. Terminal jobs cannot transition again. Invalid changes raise `InvalidTransition`.
+
+Requires Python 3.9 or newer.

samco_job_lifecycle-0.1.0/src/samco_job_lifecycle.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/samco_job_lifecycle/__init__.py
+src/samco_job_lifecycle/job.py
+src/samco_job_lifecycle.egg-info/PKG-INFO
+src/samco_job_lifecycle.egg-info/SOURCES.txt
+src/samco_job_lifecycle.egg-info/dependency_links.txt
+src/samco_job_lifecycle.egg-info/top_level.txt
+tests/test_job.py

samco_job_lifecycle-0.1.0/src/samco_job_lifecycle.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

samco_job_lifecycle-0.1.0/src/samco_job_lifecycle.egg-info/top_level.txt

@@ -0,0 +1 @@
+samco_job_lifecycle

samco_job_lifecycle-0.1.0/tests/test_job.py

@@ -0,0 +1,41 @@
+import unittest
+
+from samco_job_lifecycle import InvalidTransition, Job, JobStatus
+
+
+class JobTests(unittest.TestCase):
+    def test_success_path_records_ordered_utc_events(self):
+        job = Job("a")
+        job.start()
+        job.succeed()
+        self.assertEqual([event.status for event in job.events], [
+            JobStatus.PENDING, JobStatus.RUNNING, JobStatus.SUCCEEDED,
+        ])
+        self.assertTrue(job.is_terminal)
+        self.assertTrue(all(event.occurred_at.utcoffset().total_seconds() == 0 for event in job.events))
+
+    def test_failure_records_reason(self):
+        job = Job("a")
+        job.start()
+        job.fail("network")
+        self.assertEqual(job.events[-1].reason, "network")
+
+    def test_cancel_pending_and_reject_terminal_transition(self):
+        job = Job("a")
+        job.cancel()
+        with self.assertRaises(InvalidTransition):
+            job.start()
+        self.assertEqual(len(job.events), 2)
+
+    def test_reject_invalid_input(self):
+        with self.assertRaises(ValueError):
+            Job(" ")
+        job = Job("a")
+        with self.assertRaises(InvalidTransition):
+            job.succeed()
+        with self.assertRaises(TypeError):
+            job.transition("running")
+
+
+if __name__ == "__main__":
+    unittest.main()