Skip to content

Home

Jump to bottom
Amit Deb edited this page Dec 30, 2025 · 3 revisions

Zetten

Zetten is a deterministic task runner for Python backend projects.

You define what to run and what inputs it depends on.
Zetten decides when to run it.

The same configuration behaves the same:

  • locally
  • in CI
  • across environments

Zetten is intentionally small, explicit, and predictable.

Mental Model

Think of Zetten as an execution engine, not a framework.

  • Tasks are explicit
  • Inputs are declared
  • Execution is deterministic
  • Results are cached
  • Output is CI-safe

There is no implicit behavior.

What Is a Task?

A task consists of:

  • a command to run
  • a list of input paths
  • optional dependencies on other tasks

Example:

[tool.zetten.tasks.test]
cmd = "pytest"
inputs = ["src/", "tests/"]

Determinism

Zetten is deterministic by design.

  • The same inputs produce the same task hash
  • The same task graph executes the same way
  • Local runs behave the same as CI runs

There is no environment-based guessing.

Caching

Task results are cached based on:

  • the task command
  • declared input files and directories
  • task dependencies

If nothing relevant changes, Zetten reuses the cached result.

Cached tasks are always reported explicitly.

Dependency Graph

Tasks form a directed acyclic graph (DAG).

  • Dependencies always run before dependents
  • Independent tasks may run in parallel
  • Cycles are detected and reported as errors

You can inspect the graph with:

zetten graph

Execution Model

Zetten runs tasks using a worker pool.

  • Tasks run in parallel when possible
  • Execution order is deterministic
  • Behavior is identical locally and in CI

There are no execution modes.

Exit Codes

Exit codes are stable and CI-safe:

  • 0 - all tasks succeeded
  • 1 - a task failed
  • 2 - user error (bad config, unknown task, not initialized)
  • 3 - internal Zetten error

These semantics are guaranteed.

Configuration

Configuration is explicit by design.

There is:

  • no templating
  • no conditionals
  • no implicit task discovery

Configuration lives in:

  • pyproject.toml (preferred)
  • zetten.toml (legacy or minimal projects)

If the configuration is missing or ambiguous, Zetten fails with an explanation.

What Zetten Is Not

Zetten is not:

  • a framework
  • a workflow engine
  • a plugin system
  • a background service
  • a runtime dependency of your application

It is a small execution tool.

Getting Started

Summary

Zetten is:

  • deterministic
  • cache-aware
  • parallel by default
  • explicit by design

Simple to use.
Hard to misuse.
Boring on purpose.

Clone this wiki locally