chorelib 0.1.0__tar.gz

chorelib-0.1.0/LICENSE

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

chorelib-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: chorelib
+Version: 0.1.0
+Summary: Python build automation framework with decorator-based DSL
+Keywords: build,automation,make,async,task-runner
+Author: Atsuo Ishimoto
+Author-email: Atsuo Ishimoto <atsuoishimoto@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Framework :: AsyncIO
+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
+Requires-Python: >=3.10
+Project-URL: Documentation, https://chorelib.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/atsuoishimoto/chorelib
+Project-URL: Issues, https://github.com/atsuoishimoto/chorelib/issues
+Project-URL: Repository, https://github.com/atsuoishimoto/chorelib
+Description-Content-Type: text/markdown
+
+# chorelib
+
+A Python build automation framework — like Make, but in Python.
+chorelib focuses on keeping Make-style speed and rebuild behavior while letting you write build logic in real Python.
+
+chorelib uses a decorator-based DSL for defining build rules and tasks, with dependency management, parallel execution, and mtime-based rebuild detection.
+
+## Features
+
+- **Decorator-based DSL** — Define build rules with `@rule` and tasks with `@task`, using familiar Python syntax
+- **Regex target patterns** — Match multiple targets with regex and use backreferences (`\1`) in dependency specifications
+- **Async parallel execution** — Run independent build steps concurrently with configurable worker count
+- **mtime-based rebuild** — Skip up-to-date targets automatically, just like Make
+- **Custom mtime functions** — Override mtime checking per target pattern to manage non-file resources (databases, S3 objects, etc.)
+- **Order-only prerequisites** — `needs` dependencies ensure build order without triggering rebuilds
+- **Auto-generated help** — `-h` shows usage with target documentation from docstrings, `-l` lists all available targets
+- **Zero dependencies** — Pure Python, no external packages required
+
+**Best for:** developers who want Make-like rebuild behavior but need Python for complex logic or non-file resources.
+It also works well as a simple task runner for everyday scripts.
+
+## Installation
+
+```bash
+pip install chorelib
+```
+
+## Quick Start
+
+Here is a Makefile and its chorelib equivalent side by side.
+
+**Makefile:**
+
+```makefile
+CC=gcc
+CFLAGS=-I.
+DEPS = hello.h
+OBJS = main.o hello.o
+.PHONY: clean
+
+%.o: %.c $(DEPS)
+	$(CC) -c -o $@ $< $(CFLAGS)
+
+hello.exe: $(OBJS)
+	$(CC) -o $@ $^
+
+clean:
+	rm -f $(OBJS) hello.exe
+```
+
+**chorelib (`make.py`):**
+
+```python
+import re
+from chorelib import Main, command, rule, task
+
+APP = "hello.exe"
+CC = "gcc"
+CFLAGS = ["-c", "-I."]
+DEPS = ["hello.h"]
+OBJS = ["hello.o", "main.o"]
+
+@rule(APP, depends=OBJS, default=True)
+def link(target, deps, needs):
+    """Build executable"""
+    command(CC, "-o", target, deps)
+
+@rule(re.compile(r"(.+)\.o"), depends=(r"\1.c", DEPS))
+def compile(target, deps, needs):
+    command(CC, "-o", target, deps[0], CFLAGS)
+
+@task
+def clean():
+    """Remove the built files."""
+    command("rm", "-f", OBJS, APP)
+
+if __name__ == "__main__":
+    Main().run()
+```
+
+```bash
+uv run python make.py              # Build default target
+uv run python make.py clean        # Run the clean task
+uv run python make.py -w 4         # Build with 4 parallel workers
+uv run python make.py -r           # Force rebuild all
+uv run python make.py -h           # Show help with target docs
+uv run python make.py -l           # List all available targets
+```
+
+`-h` displays usage information along with target documentation extracted from docstrings:
+
+```
+$ uv run python make.py -h
+usage: make.py [-h] [-C DIRECTORY] [-w WORKERS] [-r] [-l] [-v] [-V] [targets ...]
+
+Sample build script for building a C program using chorelib.
+
+hello.exe [default]:
+    Build executable
+
+clean:
+    Remove the built files.
+
+rebuild:
+    Clean and rebuild all files.
+
+execute:
+    Rebuild and execute the program.
+...
+```
+
+`-l` lists all registered targets with their types, dependencies, and builder functions:
+
+```
+$ uv run python make.py -l
+[rule] hello.exe:
+  depends: hello.o, main.o
+  needs:
+  function: link
+
+[rule] re: (.+)\.o:
+  depends: \1.c, hello.h
+  needs:
+  function: compile
+
+[task] clean:
+  needs:
+  builder: clean
+...
+```
+
+## Why chorelib over Make?
+
+| | Make | chorelib |
+|---|---|---|
+| Pattern rules | `%.o: %.c` | `r"^(.+)\.o"` with backreferences |
+| Variables & logic | Limited macro language | Full Python |
+| Parallel builds | `make -j4` | `python make.py -w 4` |
+| Non-file targets | `.PHONY` | `@task` decorator |
+| Custom mtime | Not supported | `@mtime` decorator for databases, remote objects, etc. |
+| Dependencies | File-only | Files, functions, or any callable |
+
+## License
+
+MIT

chorelib-0.1.0/README.md

@@ -0,0 +1,145 @@
+# chorelib
+
+A Python build automation framework — like Make, but in Python.
+chorelib focuses on keeping Make-style speed and rebuild behavior while letting you write build logic in real Python.
+
+chorelib uses a decorator-based DSL for defining build rules and tasks, with dependency management, parallel execution, and mtime-based rebuild detection.
+
+## Features
+
+- **Decorator-based DSL** — Define build rules with `@rule` and tasks with `@task`, using familiar Python syntax
+- **Regex target patterns** — Match multiple targets with regex and use backreferences (`\1`) in dependency specifications
+- **Async parallel execution** — Run independent build steps concurrently with configurable worker count
+- **mtime-based rebuild** — Skip up-to-date targets automatically, just like Make
+- **Custom mtime functions** — Override mtime checking per target pattern to manage non-file resources (databases, S3 objects, etc.)
+- **Order-only prerequisites** — `needs` dependencies ensure build order without triggering rebuilds
+- **Auto-generated help** — `-h` shows usage with target documentation from docstrings, `-l` lists all available targets
+- **Zero dependencies** — Pure Python, no external packages required
+
+**Best for:** developers who want Make-like rebuild behavior but need Python for complex logic or non-file resources.
+It also works well as a simple task runner for everyday scripts.
+
+## Installation
+
+```bash
+pip install chorelib
+```
+
+## Quick Start
+
+Here is a Makefile and its chorelib equivalent side by side.
+
+**Makefile:**
+
+```makefile
+CC=gcc
+CFLAGS=-I.
+DEPS = hello.h
+OBJS = main.o hello.o
+.PHONY: clean
+
+%.o: %.c $(DEPS)
+	$(CC) -c -o $@ $< $(CFLAGS)
+
+hello.exe: $(OBJS)
+	$(CC) -o $@ $^
+
+clean:
+	rm -f $(OBJS) hello.exe
+```
+
+**chorelib (`make.py`):**
+
+```python
+import re
+from chorelib import Main, command, rule, task
+
+APP = "hello.exe"
+CC = "gcc"
+CFLAGS = ["-c", "-I."]
+DEPS = ["hello.h"]
+OBJS = ["hello.o", "main.o"]
+
+@rule(APP, depends=OBJS, default=True)
+def link(target, deps, needs):
+    """Build executable"""
+    command(CC, "-o", target, deps)
+
+@rule(re.compile(r"(.+)\.o"), depends=(r"\1.c", DEPS))
+def compile(target, deps, needs):
+    command(CC, "-o", target, deps[0], CFLAGS)
+
+@task
+def clean():
+    """Remove the built files."""
+    command("rm", "-f", OBJS, APP)
+
+if __name__ == "__main__":
+    Main().run()
+```
+
+```bash
+uv run python make.py              # Build default target
+uv run python make.py clean        # Run the clean task
+uv run python make.py -w 4         # Build with 4 parallel workers
+uv run python make.py -r           # Force rebuild all
+uv run python make.py -h           # Show help with target docs
+uv run python make.py -l           # List all available targets
+```
+
+`-h` displays usage information along with target documentation extracted from docstrings:
+
+```
+$ uv run python make.py -h
+usage: make.py [-h] [-C DIRECTORY] [-w WORKERS] [-r] [-l] [-v] [-V] [targets ...]
+
+Sample build script for building a C program using chorelib.
+
+hello.exe [default]:
+    Build executable
+
+clean:
+    Remove the built files.
+
+rebuild:
+    Clean and rebuild all files.
+
+execute:
+    Rebuild and execute the program.
+...
+```
+
+`-l` lists all registered targets with their types, dependencies, and builder functions:
+
+```
+$ uv run python make.py -l
+[rule] hello.exe:
+  depends: hello.o, main.o
+  needs:
+  function: link
+
+[rule] re: (.+)\.o:
+  depends: \1.c, hello.h
+  needs:
+  function: compile
+
+[task] clean:
+  needs:
+  builder: clean
+...
+```
+
+## Why chorelib over Make?
+
+| | Make | chorelib |
+|---|---|---|
+| Pattern rules | `%.o: %.c` | `r"^(.+)\.o"` with backreferences |
+| Variables & logic | Limited macro language | Full Python |
+| Parallel builds | `make -j4` | `python make.py -w 4` |
+| Non-file targets | `.PHONY` | `@task` decorator |
+| Custom mtime | Not supported | `@mtime` decorator for databases, remote objects, etc. |
+| Dependencies | File-only | Files, functions, or any callable |
+
+## License
+
+MIT

chorelib-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "chorelib"
+version = "0.1.0"
+description = "Python build automation framework with decorator-based DSL"
+readme = "README.md"
+authors = [
+    { name = "Atsuo Ishimoto", email = "atsuoishimoto@gmail.com" }
+]
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["build", "automation", "make", "async", "task-runner"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/atsuoishimoto/chorelib"
+Repository = "https://github.com/atsuoishimoto/chorelib"
+Documentation = "https://chorelib.readthedocs.io/en/latest/"
+Issues = "https://github.com/atsuoishimoto/chorelib/issues"
+
+[build-system]
+requires = ["uv_build>=0.8.15,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "ruff>=0.15.0",
+    "sphinx>=8.1.3",
+    "sphinx-rtd-theme>=3.1.0",
+]
+
+[tool.ruff]
+lint.select = [
+  "E4",
+  "E7",
+  "E9",
+  "F",
+  "I"
+]
+line-length = 99

chorelib-0.1.0/src/chorelib/.ruff_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by ruff.
+*

chorelib-0.1.0/src/chorelib/.ruff_cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

chorelib-0.1.0/src/chorelib/__init__.py

@@ -0,0 +1,48 @@
+"""Chorelib: An async-first Python build automation framework.
+
+Provides a decorator-based DSL for defining build rules and tasks with
+dependency management, parallel execution, and mtime-based rebuild detection.
+
+Typical usage::
+
+    import chorelib
+
+    @chorelib.rule("output.txt", depends="input.txt")
+    def build_output(target, depends, needs):
+        chorelib.shell(f"cp {depends[0]} {target}")
+
+    if __name__ == "__main__":
+        chorelib.Main().run()
+"""
+
+from .depmain import Main
+from .deprunner import schedule
+from .ruledef import RuleSet
+from .utils import command, message, shell
+
+__version__ = "0.1.0"
+
+# Default RuleSet instance used by the module-level decorators.
+# Users can use `@chorelib.rule(...)` and `@chorelib.task` directly
+# without creating a RuleSet manually.
+_default_rules = RuleSet()
+rule = _default_rules.rule
+task = _default_rules.task
+mtime = _default_rules.mtime
+
+# Global verbosity level controlling message output.
+# 0 = normal, 1 = verbose, 2 = debug messages, 3+ = logging debug.
+verbose: int = 0
+
+__all__ = [
+    "RuleSet",
+    "rule",
+    "task",
+    "mtime",
+    "Main",
+    "schedule",
+    "verbose",
+    "command",
+    "message",
+    "shell",
+]

chorelib-0.1.0/src/chorelib/depgraph.py

@@ -0,0 +1,122 @@
+"""Dependency graph construction and cycle detection.
+
+Builds a directed acyclic graph (DAG) of build targets and their
+dependencies. Detects circular dependencies via depth-first search
+before any build execution begins.
+"""
+
+from typing import Any
+
+from .errors import RuleError
+from .ruledef import RuleBase, RuleSet, Task
+
+
+class BuildInfo:
+    """A node in the dependency graph representing a single build target.
+
+    Attributes:
+        target: The target name (file path or task name).
+        rule: The Rule or Task that produces this target.
+        depends: List of dependency target names that trigger rebuilds.
+        needs: List of order-only prerequisite target names.
+    """
+
+    def __init__(self, target: str, rule: RuleBase, depends: list[str], needs: list[str]) -> None:
+        self.rule = rule
+        self.target = target
+        self.depends = depends
+        self.needs = needs
+
+    def __repr__(self) -> str:
+        return f"<BuildInfo> {self.rule}:{self.target}:{self.depends}:{self.needs}"
+
+    def is_task(self) -> bool:
+        """Return True if this node represents a Task (always-execute)."""
+        return isinstance(self.rule, Task)
+
+    def run_builder(self) -> Any:
+        """Execute the builder function for this target."""
+        return self.rule.run_builder(target=self.target, depends=self.depends, needs=self.needs)
+
+
+class DepGraph:
+    """Dependency graph that manages BuildInfo nodes and detects cycles.
+
+    Nodes are registered by recursively resolving each target's dependencies
+    through the RuleSet. After registration, ``detectloop`` should be called
+    to verify the graph is acyclic.
+    """
+
+    def __init__(self) -> None:
+        self._nodes: dict[str, BuildInfo] = {}
+
+    def addtarget(self, ruleset: RuleSet, target: str) -> bool:
+        """Add a target and all its transitive dependencies to the graph.
+
+        Returns:
+            True if the target was newly registered, False if already present.
+        """
+        return self._register(ruleset, target)
+
+    def get(self, target: str) -> BuildInfo | None:
+        """Return the BuildInfo node for a target, or None if not registered."""
+        return self._nodes.get(target)
+
+    def _register(self, ruleset: RuleSet, target: str) -> bool:
+        """Recursively register a target and its dependencies.
+
+        Looks up the matching rule in the ruleset, creates a BuildInfo node,
+        and recurses into each dependency and need.
+        """
+        if target in self._nodes:
+            return False
+
+        ret = ruleset.select_rule(target)
+        if ret:
+            rule, deps, needs = ret
+            node = BuildInfo(target, rule, deps, needs)
+            self._nodes[target] = node
+
+            # Recursively register all dependencies
+            for dep in deps:
+                self._register(ruleset, dep)
+
+            # Recursively register all order-only prerequisites
+            for need in needs:
+                self._register(ruleset, need)
+
+        return True
+
+    def detectloop(self) -> None:
+        """Detect circular dependencies in the graph using DFS.
+
+        Raises:
+            RuleError: If a dependency cycle is found.
+        """
+        done: set[BuildInfo] = set()
+
+        def _walk(node: BuildInfo, seen: set[BuildInfo]) -> None:
+            """DFS traversal tracking the current path in ``seen``."""
+            if node in seen:
+                raise RuleError(f"Dependency cycle detected: {node}")
+
+            if node in done:
+                return
+
+            seen.add(node)
+            try:
+                for dep in node.depends:
+                    depnode = self._nodes.get(dep)
+                    if depnode:
+                        _walk(depnode, seen)
+                for need in node.needs:
+                    neednode = self._nodes.get(need)
+                    if neednode:
+                        _walk(neednode, seen)
+            finally:
+                seen.remove(node)
+            done.add(node)
+
+        for node in self._nodes.values():
+            seen: set[BuildInfo] = set()
+            _walk(node, seen)