task-checkpoint 0.1.0__tar.gz

task_checkpoint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1nvisibleCat
+
+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.

task_checkpoint-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include task_pool *.py
+recursive-include tests *.py
+exclude LAB_PROMO_NOTES.md
+exclude TASK_POOL_DESIGN_NOTES.zh.md
+global-exclude .DS_Store
+global-exclude __pycache__
+global-exclude *.py[cod]

task_checkpoint-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: task-checkpoint
+Version: 0.1.0
+Summary: A small Python library for resumable task pools in long-running scripts.
+Author: 1nvisibleCat
+License-Expression: MIT
+Keywords: checkpoint,task-checkpoint,task-pool,resume,batch-processing,job-queue
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Task Pool
+
+Task Pool is a small Python library for long-running scripts that need to process many small jobs without losing progress.
+
+Turn a fragile `for` loop into a resumable task pool.
+
+When a run stops halfway, Task Pool remembers what is done, what is running, and what still needs work. You can restart the script and continue from the last known point.
+
+Use it for crawling, experiments, data analysis, batch API calls, file processing, and other work where unfinished items should be easy to resume.
+
+It feels like a tiny job queue, but stays inside your Python script. For local use, no database server, message queue, or service setup is needed.
+
+## Quickstart
+
+Install it with:
+
+```bash
+pip install task-checkpoint
+```
+
+Put one URL per line:
+
+```text
+https://example.com/a
+https://example.com/b
+https://example.com/c
+```
+
+Then process the file as a task pool:
+
+```python
+from task_pool import TaskPool
+
+
+pool = TaskPool("urls.txt")
+
+def fetch_one(payload):
+    fetch_url(payload["line"])
+
+
+pool.for_each(fetch_one)
+```
+
+You can also use a regular loop:
+
+```python
+for payload in pool:
+    fetch_url(payload["line"])
+```
+
+If you need task metadata, use `iter_tasks()`:
+
+```python
+for task in pool.iter_tasks():
+    url = task.payload["line"]
+    result = fetch_url(url)
+    save_result(task.key, result)
+```
+
+Each completed task is committed. If an exception is raised, the current task is rolled back to `not_start` and the exception is raised again.
+
+For very small scripts, a lambda also works:
+
+```python
+pool.for_each(lambda payload: fetch_url(payload["line"]))
+```
+
+You can print a small progress summary:
+
+```python
+print(pool.stats())
+# {"total": 10, "not_start": 3, "pending": 0, "committed": 7}
+```
+
+For structured jobs, use a JSON task pool:
+
+```python
+pool = TaskPool("tasks.json")
+
+pool.append({"input_path": "data/a.json", "method": "baseline"})
+pool.append({"input_path": "data/b.json", "method": "baseline"})
+```
+
+## Manual Control
+
+Use `lease()` when you want one task at a time and need explicit control.
+
+```python
+pool = TaskPool("tasks.json")
+
+with pool.lease() as task:
+    if task is None:
+        return
+
+    do_work(task.payload)
+```
+
+If there is no task to process, `lease()` returns `None`.
+
+Leaving the `with` block normally commits the task. If an exception is raised, the task is rolled back automatically.
+
+## Store Selection
+
+You can choose a store by file suffix:
+
+```python
+TaskPool("tasks.json")      # JSONFileStore
+TaskPool("tasks.sqlite")    # SQLiteStore
+TaskPool("tasks.sqlite3")   # SQLiteStore
+TaskPool("tasks.db")        # SQLiteStore
+TaskPool("rows.csv")        # CSVRowStore with sidecar state
+TaskPool("rows.tsv")        # CSVRowStore with sidecar state
+TaskPool("urls.txt")        # TextLineStore with sidecar state
+```
+
+You can also pass a store explicitly:
+
+```python
+from task_pool import JSONFileStore, SQLiteStore, TaskPool
+
+
+pool = TaskPool(JSONFileStore("tasks.json"))
+pool = TaskPool(SQLiteStore("tasks.db"))
+```
+
+## Source Files
+
+Task Pool can also read tasks from source files.
+
+### Text files
+
+```python
+pool = TaskPool("urls.txt")
+```
+
+Example:
+
+```text
+https://example.com/a
+https://example.com/b
+https://example.com/c
+```
+
+Each non-empty line becomes a task:
+
+```python
+{
+    "line": "https://example.com/a",
+    "line_number": 1,
+}
+```
+
+### CSV and TSV files
+
+```python
+pool = TaskPool("rows.csv")
+pool = TaskPool("rows.tsv")
+```
+
+By default, CSV and TSV files are read with a header row:
+
+```csv
+code,name
+A0001,Alpha
+A0002,Beta
+```
+
+The first row becomes:
+
+```python
+{"code": "A0001", "name": "Alpha"}
+```
+
+For files without headers:
+
+```python
+pool = TaskPool.csv("rows.csv", has_header=False)
+pool = TaskPool.tsv("rows.tsv", has_header=False)
+```
+
+Rows are named `col1`, `col2`, and so on:
+
+```python
+{"col1": "A0001", "col2": "Alpha"}
+```
+
+Source files are not modified. Progress is stored in a sidecar JSON file, for example:
+
+```text
+rows.csv.task_pool.json
+urls.txt.task_pool.json
+```
+
+## Task Status
+
+Each task has one of these statuses:
+
+- `not_start`
+- `pending`
+- `committed`
+
+The common flow is:
+
+```text
+not_start -> pending -> committed
+                  |
+                  -> not_start
+```
+
+`pending` means a worker has leased the task and is currently processing it.
+
+## Notes
+
+- The default store is `JSONFileStore("task_pool.json")`.
+- Payloads are stored as JSON.
+- JSON and source-backed stores use file locks and atomic writes.
+- SQLite is better for larger pools or heavier concurrent use.
+- Source-backed stores keep the source file unchanged and write progress to a sidecar JSON file.

task_checkpoint-0.1.0/README.md

@@ -0,0 +1,218 @@
+# Task Pool
+
+Task Pool is a small Python library for long-running scripts that need to process many small jobs without losing progress.
+
+Turn a fragile `for` loop into a resumable task pool.
+
+When a run stops halfway, Task Pool remembers what is done, what is running, and what still needs work. You can restart the script and continue from the last known point.
+
+Use it for crawling, experiments, data analysis, batch API calls, file processing, and other work where unfinished items should be easy to resume.
+
+It feels like a tiny job queue, but stays inside your Python script. For local use, no database server, message queue, or service setup is needed.
+
+## Quickstart
+
+Install it with:
+
+```bash
+pip install task-checkpoint
+```
+
+Put one URL per line:
+
+```text
+https://example.com/a
+https://example.com/b
+https://example.com/c
+```
+
+Then process the file as a task pool:
+
+```python
+from task_pool import TaskPool
+
+
+pool = TaskPool("urls.txt")
+
+def fetch_one(payload):
+    fetch_url(payload["line"])
+
+
+pool.for_each(fetch_one)
+```
+
+You can also use a regular loop:
+
+```python
+for payload in pool:
+    fetch_url(payload["line"])
+```
+
+If you need task metadata, use `iter_tasks()`:
+
+```python
+for task in pool.iter_tasks():
+    url = task.payload["line"]
+    result = fetch_url(url)
+    save_result(task.key, result)
+```
+
+Each completed task is committed. If an exception is raised, the current task is rolled back to `not_start` and the exception is raised again.
+
+For very small scripts, a lambda also works:
+
+```python
+pool.for_each(lambda payload: fetch_url(payload["line"]))
+```
+
+You can print a small progress summary:
+
+```python
+print(pool.stats())
+# {"total": 10, "not_start": 3, "pending": 0, "committed": 7}
+```
+
+For structured jobs, use a JSON task pool:
+
+```python
+pool = TaskPool("tasks.json")
+
+pool.append({"input_path": "data/a.json", "method": "baseline"})
+pool.append({"input_path": "data/b.json", "method": "baseline"})
+```
+
+## Manual Control
+
+Use `lease()` when you want one task at a time and need explicit control.
+
+```python
+pool = TaskPool("tasks.json")
+
+with pool.lease() as task:
+    if task is None:
+        return
+
+    do_work(task.payload)
+```
+
+If there is no task to process, `lease()` returns `None`.
+
+Leaving the `with` block normally commits the task. If an exception is raised, the task is rolled back automatically.
+
+## Store Selection
+
+You can choose a store by file suffix:
+
+```python
+TaskPool("tasks.json")      # JSONFileStore
+TaskPool("tasks.sqlite")    # SQLiteStore
+TaskPool("tasks.sqlite3")   # SQLiteStore
+TaskPool("tasks.db")        # SQLiteStore
+TaskPool("rows.csv")        # CSVRowStore with sidecar state
+TaskPool("rows.tsv")        # CSVRowStore with sidecar state
+TaskPool("urls.txt")        # TextLineStore with sidecar state
+```
+
+You can also pass a store explicitly:
+
+```python
+from task_pool import JSONFileStore, SQLiteStore, TaskPool
+
+
+pool = TaskPool(JSONFileStore("tasks.json"))
+pool = TaskPool(SQLiteStore("tasks.db"))
+```
+
+## Source Files
+
+Task Pool can also read tasks from source files.
+
+### Text files
+
+```python
+pool = TaskPool("urls.txt")
+```
+
+Example:
+
+```text
+https://example.com/a
+https://example.com/b
+https://example.com/c
+```
+
+Each non-empty line becomes a task:
+
+```python
+{
+    "line": "https://example.com/a",
+    "line_number": 1,
+}
+```
+
+### CSV and TSV files
+
+```python
+pool = TaskPool("rows.csv")
+pool = TaskPool("rows.tsv")
+```
+
+By default, CSV and TSV files are read with a header row:
+
+```csv
+code,name
+A0001,Alpha
+A0002,Beta
+```
+
+The first row becomes:
+
+```python
+{"code": "A0001", "name": "Alpha"}
+```
+
+For files without headers:
+
+```python
+pool = TaskPool.csv("rows.csv", has_header=False)
+pool = TaskPool.tsv("rows.tsv", has_header=False)
+```
+
+Rows are named `col1`, `col2`, and so on:
+
+```python
+{"col1": "A0001", "col2": "Alpha"}
+```
+
+Source files are not modified. Progress is stored in a sidecar JSON file, for example:
+
+```text
+rows.csv.task_pool.json
+urls.txt.task_pool.json
+```
+
+## Task Status
+
+Each task has one of these statuses:
+
+- `not_start`
+- `pending`
+- `committed`
+
+The common flow is:
+
+```text
+not_start -> pending -> committed
+                  |
+                  -> not_start
+```
+
+`pending` means a worker has leased the task and is currently processing it.
+
+## Notes
+
+- The default store is `JSONFileStore("task_pool.json")`.
+- Payloads are stored as JSON.
+- JSON and source-backed stores use file locks and atomic writes.
+- SQLite is better for larger pools or heavier concurrent use.
+- Source-backed stores keep the source file unchanged and write progress to a sidecar JSON file.

task_checkpoint-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "task-checkpoint"
+version = "0.1.0"
+description = "A small Python library for resumable task pools in long-running scripts."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "1nvisibleCat" }
+]
+keywords = [
+    "checkpoint",
+    "task-checkpoint",
+    "task-pool",
+    "resume",
+    "batch-processing",
+    "job-queue",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["task_pool*"]
+exclude = ["tests*"]

task_checkpoint-0.1.0/setup.cfg

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