ntask 1.0.0__tar.gz

ntask-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Sean Nieuwoudt
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ntask-1.0.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: ntask
+Version: 1.0.0
+Summary: A Python-native task runner with content-hash caching and DAG execution.
+Author-email: Sean Nieuwoudt <sean@underwulf.com>
+License: BSD-3-Clause
+Keywords: task-runner,build-system,make,just,ci
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7
+Requires-Dist: xxhash>=3.4
+Requires-Dist: pathspec>=0.12
+Requires-Dist: anyio>=4.3
+Requires-Dist: watchfiles>=0.22
+Requires-Dist: textual>=0.80
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: hypothesis>=6.98; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: moto>=5.0; extra == "dev"
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == "s3"
+Provides-Extra: gcs
+Requires-Dist: google-cloud-storage>=2.14; extra == "gcs"
+Provides-Extra: all
+Requires-Dist: boto3>=1.34; extra == "all"
+Requires-Dist: google-cloud-storage>=2.14; extra == "all"
+Dynamic: license-file
+
+# ntask
+
+A Python-native task runner with content-hash caching and DAG execution.
+
+```bash
+pip install ntask
+```
+
+## Why
+
+Your Makefile runs everything every time. Your Justfile has no dependency graph. Your `tasks.py` for Invoke is five years old, has no types, and you still have to write `ctx.run`. This is what a task runner looks like when you start over with caching, types, and a DAG.
+
+## Quickstart
+
+Create a `tasks.py`:
+
+```python
+from ntask import task, cached, depends, shell
+
+@task
+def install():
+    shell("pip install -e .")
+
+@task
+@cached(inputs=["src/**/*.py", "tests/**/*.py"])
+def test(pattern: str = "", verbose: bool = False):
+    """Run the test suite."""
+    flags = "-v" if verbose else ""
+    k = f"-k {pattern}" if pattern else ""
+    shell(f"pytest {flags} {k}")
+
+@task
+@cached(inputs=["src/**/*.py"])
+def lint():
+    shell("ruff check src/")
+
+@task
+def check():
+    """All quality checks."""
+    depends(lint, test)
+```
+
+Run:
+
+```bash
+ntask --list                       # show every registered task
+ntask test --pattern=auth --verbose
+ntask check                        # lint + test in order; both cache
+ntask check -j                     # all CPU cores; bare -j picks the count
+ntask watch test                   # rerun on every src/ or tests/ change
+ntask --why test                   # explain why the last cache lookup missed
+ntask --graph check                # ASCII DAG (mermaid / dot also available)
+```
+
+The second time you run `ntask check`, both `lint` and `test` are content-hash cache hits and finish in milliseconds. Change one file in `src/` and only the affected tasks rerun, transitively.
+
+## Team cache
+
+Share cache hits across machines via S3 (or GCS, HTTP, NFS):
+
+```toml
+# pyproject.toml
+[tool.ntask.remote_cache]
+type = "s3"
+bucket = "my-team-cache"
+```
+
+```bash
+pip install ntask[s3]
+ntask check                        # first person populates, the rest hit instantly
+ntask check --offline              # skip the remote for fast dev loops
+```
+
+S3-compatibles (MinIO, R2, B2) take an `endpoint_url`. GCS and HTTP backends work the same way; the HTTP backend is plain `GET`/`PUT`/`HEAD` over stdlib `urllib`, so any object store with PUT enabled is fair game.
+
+## Live DAG display
+
+Run `ntask check` from an interactive terminal and a Textual TUI shows a live tree of the DAG with per-task state icons and durations. Pipe the output, set `tui = false` in `[tool.ntask]`, or pass `--no-tui` to fall back to the line-based renderer.
+
+## Other things you'll reach for
+
+- **Exclusive tasks.** `@task(parallel=False)` makes a task a DAG-wide barrier: it waits for everything in flight to drain, then runs alone. Use it for releases, migrations, anything that mutates shared state.
+- **Monorepos.** `@group("api")` over a class namespaces every task method as `api.<name>`. Cross-group dependencies via `@task(deps=[Other.task, ...])` or string fqns.
+- **Capture output.** `shell("git rev-parse HEAD", capture=True)` returns a `ShellResult` with `.stdout`, `.stderr`, `.returncode`, `.duration`, `.ok`.
+- **Force a rerun.** `ntask --force <task>` bypasses the cache for that one task. `ntask --no-cache` ignores the cache entirely. `ntask clean` wipes entry manifests; `ntask clean --all` wipes the whole `.ntask/` directory.
+
+## Examples
+
+Six runnable, self-contained examples under [`examples/`](examples/):
+
+| #                                            | Demonstrates                                   |
+|----------------------------------------------|------------------------------------------------|
+| [01-hello](examples/01-hello/)               | Smallest possible cached task                  |
+| [02-python-lib](examples/02-python-lib/)     | install / lint / typecheck / test / build      |
+| [03-parallel](examples/03-parallel/)         | `-j N` fan-out and `parallel=False` barrier    |
+| [04-watch](examples/04-watch/)               | `ntask watch` rerun-on-change loop             |
+| [05-remote-cache](examples/05-remote-cache/) | local-fs remote backend shared between clones  |
+| [06-monorepo](examples/06-monorepo/)         | `@group(...)` namespacing and cross-group deps |
+
+`cd` into any directory and run `ntask --list`.
+
+## Features
+
+| feature                          | ntask |  make   |  just   | invoke  |  doit   |   poe   |
+|----------------------------------|:-----:|:-------:|:-------:|:-------:|:-------:|:-------:|
+| Typed Python tasks               |  yes  |   no    |   no    | partial |   no    | partial |
+| Content-hash input caching       |  yes  | partial |   no    |   no    | partial |   no    |
+| Transitive cache-key propagation |  yes  |   no    |   no    |   no    | partial |   no    |
+| Remote cache (S3/GCS/HTTP)       |  yes  |   no    |   no    |   no    |   no    |   no    |
+| DAG dependency resolution        |  yes  |   yes   |   no    | partial |   yes   |   no    |
+| Type-hint to CLI args            |  yes  |   no    | partial | partial |   no    |   yes   |
+| Parallel DAG execution (`-j`)    |  yes  |   yes   |   no    |   no    |   yes   |   no    |
+| Live DAG TUI                     |  yes  |   no    |   no    |   no    |   no    |   no    |
+| Windows first-class              |  yes  | partial |   yes   |   yes   |   yes   |   yes   |
+
+Cache miss messages name the specific file or env change that caused the invalidation. `ntask --why <task>` prints the full breakdown.
+
+## Docs
+
+- [Technical handbook](docs/guide.md) - the comprehensive reference, every flag and config key
+- [Tutorial: replace your Makefile in 10 minutes](docs/tutorial.md)
+- [Caching: the full contract](docs/caching.md)
+- [Migrating from Make / just / Invoke / Poe](docs/migration.md)
+- [Short API reference](docs/reference.md)
+- [Roadmap](docs/roadmap.md)
+
+Requirements: Python 3.11 or newer. BSD-3-Clause.
+
+## License
+
+BSD-3-Clause. Copyright © 2026 Sean Nieuwoudt.

ntask-1.0.0/README.md

@@ -0,0 +1,131 @@
+# ntask
+
+A Python-native task runner with content-hash caching and DAG execution.
+
+```bash
+pip install ntask
+```
+
+## Why
+
+Your Makefile runs everything every time. Your Justfile has no dependency graph. Your `tasks.py` for Invoke is five years old, has no types, and you still have to write `ctx.run`. This is what a task runner looks like when you start over with caching, types, and a DAG.
+
+## Quickstart
+
+Create a `tasks.py`:
+
+```python
+from ntask import task, cached, depends, shell
+
+@task
+def install():
+    shell("pip install -e .")
+
+@task
+@cached(inputs=["src/**/*.py", "tests/**/*.py"])
+def test(pattern: str = "", verbose: bool = False):
+    """Run the test suite."""
+    flags = "-v" if verbose else ""
+    k = f"-k {pattern}" if pattern else ""
+    shell(f"pytest {flags} {k}")
+
+@task
+@cached(inputs=["src/**/*.py"])
+def lint():
+    shell("ruff check src/")
+
+@task
+def check():
+    """All quality checks."""
+    depends(lint, test)
+```
+
+Run:
+
+```bash
+ntask --list                       # show every registered task
+ntask test --pattern=auth --verbose
+ntask check                        # lint + test in order; both cache
+ntask check -j                     # all CPU cores; bare -j picks the count
+ntask watch test                   # rerun on every src/ or tests/ change
+ntask --why test                   # explain why the last cache lookup missed
+ntask --graph check                # ASCII DAG (mermaid / dot also available)
+```
+
+The second time you run `ntask check`, both `lint` and `test` are content-hash cache hits and finish in milliseconds. Change one file in `src/` and only the affected tasks rerun, transitively.
+
+## Team cache
+
+Share cache hits across machines via S3 (or GCS, HTTP, NFS):
+
+```toml
+# pyproject.toml
+[tool.ntask.remote_cache]
+type = "s3"
+bucket = "my-team-cache"
+```
+
+```bash
+pip install ntask[s3]
+ntask check                        # first person populates, the rest hit instantly
+ntask check --offline              # skip the remote for fast dev loops
+```
+
+S3-compatibles (MinIO, R2, B2) take an `endpoint_url`. GCS and HTTP backends work the same way; the HTTP backend is plain `GET`/`PUT`/`HEAD` over stdlib `urllib`, so any object store with PUT enabled is fair game.
+
+## Live DAG display
+
+Run `ntask check` from an interactive terminal and a Textual TUI shows a live tree of the DAG with per-task state icons and durations. Pipe the output, set `tui = false` in `[tool.ntask]`, or pass `--no-tui` to fall back to the line-based renderer.
+
+## Other things you'll reach for
+
+- **Exclusive tasks.** `@task(parallel=False)` makes a task a DAG-wide barrier: it waits for everything in flight to drain, then runs alone. Use it for releases, migrations, anything that mutates shared state.
+- **Monorepos.** `@group("api")` over a class namespaces every task method as `api.<name>`. Cross-group dependencies via `@task(deps=[Other.task, ...])` or string fqns.
+- **Capture output.** `shell("git rev-parse HEAD", capture=True)` returns a `ShellResult` with `.stdout`, `.stderr`, `.returncode`, `.duration`, `.ok`.
+- **Force a rerun.** `ntask --force <task>` bypasses the cache for that one task. `ntask --no-cache` ignores the cache entirely. `ntask clean` wipes entry manifests; `ntask clean --all` wipes the whole `.ntask/` directory.
+
+## Examples
+
+Six runnable, self-contained examples under [`examples/`](examples/):
+
+| #                                            | Demonstrates                                   |
+|----------------------------------------------|------------------------------------------------|
+| [01-hello](examples/01-hello/)               | Smallest possible cached task                  |
+| [02-python-lib](examples/02-python-lib/)     | install / lint / typecheck / test / build      |
+| [03-parallel](examples/03-parallel/)         | `-j N` fan-out and `parallel=False` barrier    |
+| [04-watch](examples/04-watch/)               | `ntask watch` rerun-on-change loop             |
+| [05-remote-cache](examples/05-remote-cache/) | local-fs remote backend shared between clones  |
+| [06-monorepo](examples/06-monorepo/)         | `@group(...)` namespacing and cross-group deps |
+
+`cd` into any directory and run `ntask --list`.
+
+## Features
+
+| feature                          | ntask |  make   |  just   | invoke  |  doit   |   poe   |
+|----------------------------------|:-----:|:-------:|:-------:|:-------:|:-------:|:-------:|
+| Typed Python tasks               |  yes  |   no    |   no    | partial |   no    | partial |
+| Content-hash input caching       |  yes  | partial |   no    |   no    | partial |   no    |
+| Transitive cache-key propagation |  yes  |   no    |   no    |   no    | partial |   no    |
+| Remote cache (S3/GCS/HTTP)       |  yes  |   no    |   no    |   no    |   no    |   no    |
+| DAG dependency resolution        |  yes  |   yes   |   no    | partial |   yes   |   no    |
+| Type-hint to CLI args            |  yes  |   no    | partial | partial |   no    |   yes   |
+| Parallel DAG execution (`-j`)    |  yes  |   yes   |   no    |   no    |   yes   |   no    |
+| Live DAG TUI                     |  yes  |   no    |   no    |   no    |   no    |   no    |
+| Windows first-class              |  yes  | partial |   yes   |   yes   |   yes   |   yes   |
+
+Cache miss messages name the specific file or env change that caused the invalidation. `ntask --why <task>` prints the full breakdown.
+
+## Docs
+
+- [Technical handbook](docs/guide.md) - the comprehensive reference, every flag and config key
+- [Tutorial: replace your Makefile in 10 minutes](docs/tutorial.md)
+- [Caching: the full contract](docs/caching.md)
+- [Migrating from Make / just / Invoke / Poe](docs/migration.md)
+- [Short API reference](docs/reference.md)
+- [Roadmap](docs/roadmap.md)
+
+Requirements: Python 3.11 or newer. BSD-3-Clause.
+
+## License
+
+BSD-3-Clause. Copyright © 2026 Sean Nieuwoudt.

ntask-1.0.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ntask"
+version = "1.0.0"
+description = "A Python-native task runner with content-hash caching and DAG execution."
+authors = [{name = "Sean Nieuwoudt", email = "sean@underwulf.com"}]
+license = {text = "BSD-3-Clause"}
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["task-runner", "build-system", "make", "just", "ci"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "rich>=13.7",
+    "xxhash>=3.4",
+    "pathspec>=0.12",
+    "anyio>=4.3",
+    "watchfiles>=0.22",
+    "textual>=0.80",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "hypothesis>=6.98",
+    "ruff>=0.3",
+    "mypy>=1.9",
+    "moto>=5.0",
+]
+s3 = ["boto3>=1.34"]
+gcs = ["google-cloud-storage>=2.14"]
+all = ["boto3>=1.34", "google-cloud-storage>=2.14"]
+
+[project.scripts]
+ntask = "ntask._cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "S", "A", "C4", "RUF"]
+ignore = ["S101"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/ntask"]
+
+[[tool.mypy.overrides]]
+module = ["boto3", "botocore.*", "google.*"]
+ignore_missing_imports = true

ntask-1.0.0/setup.cfg

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

ntask-1.0.0/src/ntask/__init__.py

@@ -0,0 +1,21 @@
+"""ntask: a Python-native task runner with content-hash caching and DAG execution."""
+
+from ._depends import depends
+from ._errors import CycleError, DiscoveryError, NtaskError, ShellError
+from ._shell import ShellResult, shell
+from ._task import cached, group, task
+
+__version__ = "1.0.0"
+__all__ = [
+    "CycleError",
+    "DiscoveryError",
+    "NtaskError",
+    "ShellError",
+    "ShellResult",
+    "__version__",
+    "cached",
+    "depends",
+    "group",
+    "shell",
+    "task",
+]

ntask-1.0.0/src/ntask/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from ._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ntask-1.0.0/src/ntask/_cache/__init__.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import os
+import platform
+import sys
+import time
+from pathlib import Path
+
+from .._remote.base import RemoteBackend
+from .._task import Task
+from .body import hash_task_body
+from .key import CacheBreakdown, CacheKeyInputs, InputRecord, compute_cache_key
+from .manifest import compute_input_manifest
+from .outputs import OutputStore
+from .store import CacheEntry, CacheStore
+
+# Module-level flag for warn-once pattern.
+_remote_warn_fired = False
+
+
+def _warn_once_remote_failed(e: BaseException) -> None:
+    """Print a single warning the first time a remote call fails in this process."""
+    global _remote_warn_fired
+    if not _remote_warn_fired:
+        print(
+            f"warning: remote cache unreachable: {type(e).__name__}: {e}. "
+            f"Falling back to local.",
+            file=sys.stderr,
+        )
+        _remote_warn_fired = True
+
+
+def _python_version_str() -> str:
+    return ".".join(str(x) for x in sys.version_info[:3])
+
+
+def _platform_tag_str() -> str:
+    return f"{platform.system()}-{platform.machine()}".lower()
+
+
+class CacheEngine:
+    def __init__(self, root: Path, remote: RemoteBackend | None = None):
+        self.root = root
+        self.store = CacheStore(root=root)
+        self.outputs = OutputStore(root=root)
+        self._remote = remote
+
+    def compute_key_and_breakdown(
+        self,
+        t: Task,
+        *,
+        workspace: Path,
+        upstream_keys_by_dep: dict[str, str],
+    ) -> tuple[str, CacheBreakdown]:
+        cfg = t.cached_config
+        assert cfg is not None
+        manifest = compute_input_manifest(cfg.inputs, root=workspace)
+        body = hash_task_body(t.func)
+        env_values = {
+            name: os.environ[name] if name in os.environ else "<unset>"
+            for name in cfg.env
+        }
+        py_version = _python_version_str()
+        plat_tag = _platform_tag_str()
+
+        # Tuple ordering for cache key matches insertion order of upstream_keys_by_dep.
+        upstream_tuple = tuple(upstream_keys_by_dep.values())
+        key_inputs = CacheKeyInputs(
+            task_fqn=t.fqn,
+            task_body_hash=body,
+            env={name: ("" if v == "<unset>" else v) for name, v in env_values.items()},
+            env_names=cfg.env,
+            input_patterns=cfg.inputs,
+            input_manifest_digest=manifest.digest,
+            root=workspace,
+            upstream_keys=upstream_tuple if cfg.propagate else (),
+            strict=cfg.strict,
+        )
+        key = compute_cache_key(key_inputs)
+
+        input_records = tuple(
+            InputRecord(
+                path=fh.path.relative_to(workspace).as_posix(),
+                digest=fh.digest,
+                mode=fh.mode,
+            )
+            for fh in manifest.files
+        )
+        breakdown = CacheBreakdown(
+            input_patterns=cfg.inputs,
+            inputs=input_records,
+            env_values=env_values,
+            task_body_hash=body,
+            python_version=py_version,
+            platform_tag=plat_tag,
+            upstream_keys_by_dep=dict(upstream_keys_by_dep),
+        )
+        return key, breakdown
+
+    def check(self, t: Task, key: str) -> CacheEntry | None:
+        return self.store.get(t.fqn, key)
+
+    def store_entry(
+        self,
+        t: Task,
+        key: str,
+        *,
+        workspace: Path,
+        duration: float,
+        breakdown: CacheBreakdown,
+        upstream_keys: tuple[str, ...],
+    ) -> CacheEntry:
+        cfg = t.cached_config
+        assert cfg is not None
+        outputs_hash = (
+            self.outputs.capture(cfg.outputs, root=workspace) if cfg.outputs else None
+        )
+        entry = CacheEntry(
+            key=key,
+            outputs_hash=outputs_hash,
+            duration=duration,
+            completed_at=time.time(),
+            upstream_keys=upstream_keys,
+            breakdown=breakdown,
+        )
+        self.store.put(t.fqn, entry)
+        return entry
+
+    def restore_outputs(self, entry: CacheEntry, *, workspace: Path) -> None:
+        if entry.outputs_hash:
+            self.outputs.restore(entry.outputs_hash, root=workspace)
+
+    def check_remote(self, t: Task, key: str) -> CacheEntry | None:
+        """Try remote: if hit, download entry + outputs and populate local store."""
+        if self._remote is None:
+            return None
+        try:
+            entry_dict = self._remote.get_entry(t.fqn, key)
+        except BaseException as e:
+            _warn_once_remote_failed(e)
+            return None
+        if entry_dict is None:
+            return None
+        try:
+            entry = CacheEntry.from_dict(entry_dict)
+        except Exception as e:
+            _warn_once_remote_failed(e)
+            return None
+        # Download outputs into the content-addressed store if needed.
+        if entry.outputs_hash is not None:
+            target_dir = self.outputs._hash_dir(entry.outputs_hash)
+            if not target_dir.exists():
+                try:
+                    self._remote.get_output(entry.outputs_hash, target_dir)
+                except BaseException as e:
+                    _warn_once_remote_failed(e)
+                    return None
+        # Mirror the entry into local store so future runs short-circuit.
+        self.store.put(t.fqn, entry)
+        return entry
+
+    def push_remote(self, t: Task, entry: CacheEntry) -> None:
+        """Upload entry + outputs to remote. Non-fatal on error."""
+        if self._remote is None:
+            return
+        try:
+            self._remote.put_entry(t.fqn, entry.key, entry.to_dict())
+        except BaseException as e:
+            _warn_once_remote_failed(e)
+            return
+        if entry.outputs_hash is not None:
+            source = self.outputs._hash_dir(entry.outputs_hash)
+            if source.is_dir():
+                try:
+                    self._remote.put_output(entry.outputs_hash, source)
+                except BaseException as e:
+                    _warn_once_remote_failed(e)
+

ntask-1.0.0/src/ntask/_cache/body.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import ast
+import inspect
+import textwrap
+from collections.abc import Callable
+from typing import Any
+
+from .hash import hash_bytes
+
+
+def _strip_docstring(tree: ast.AST) -> None:
+    """Remove docstring nodes from functions/classes/modules in-place."""
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef,
+                                 ast.ClassDef, ast.Module)):
+            continue
+        body = node.body
+        if (body and isinstance(body[0], ast.Expr)
+                and isinstance(body[0].value, ast.Constant)
+                and isinstance(body[0].value.value, str)):
+            node.body = body[1:]
+
+
+def hash_task_body_source(source: str) -> str:
+    """Hash source code structurally, ignoring docstrings/comments/whitespace."""
+    tree = ast.parse(textwrap.dedent(source))
+    _strip_docstring(tree)
+    dumped = ast.dump(tree, annotate_fields=False, include_attributes=False)
+    return hash_bytes(dumped.encode())
+
+
+def hash_task_body(func: Callable[..., Any]) -> str:
+    """Structural hash of a function's source. Stable under doc/whitespace/comment noise."""
+    try:
+        source = inspect.getsource(func)
+    except (OSError, TypeError):
+        return hash_bytes(f"<no-source:{func.__qualname__}>".encode())
+    return hash_task_body_source(source)