Cache policies

CacheCompose

Combine multiple policies. Cache hits ONLY when every sub-policy hits.

Useful for "rebuild daily OR when these files change":

CacheCompose(policies=( CacheTTL(duration=timedelta(days=1)), CacheOnChange(paths=("api/cabal.project",)), ))

Fields

CacheForever

Cache forever, keyed only on (command, parent, env_keys).

Use for pure computations whose only inputs are visible to the planner. DO NOT use for installs that fetch the public internet — package repos drift; manual cache busts will be needed.

Fields

CacheNone

Always run the step; never cache its snapshot.

Equivalent to today's behavior. Default for command steps.

CacheOnChange

Rebuild whenever any file under paths changes.

Paths are relative to the source-archive root. File hashes are computed at render time by harmont.keygen (paths are read from the source archive's checkout root).

No env_keys field — file content already covers the invalidation surface.

Fields

CachePolicy

Base — never instantiate directly. Use the helpers below.

CacheTTL

Cache for duration; refresh once per window (UTC-midnight floored).

Two builds within the same UTC day share a key; a build at 00:30 UTC the next day rebuilds.

Fields

compose

Combine multiple cache policies: hit only when every sub-policy hits.

Use to express compound invalidation conditions such as "rebuild daily OR when these files change".

compose(*policies) -> CacheCompose

Returns CacheCompose — A CacheCompose policy for use in .sh(cache=...).

Examples

>>> from datetime import timedelta
>>> import harmont as hm
>>> policy = hm.compose(
...     hm.ttl(timedelta(days=1)),
...     hm.on_change("api/cabal.project"),
... )

forever

Create a permanent cache policy.

The step's snapshot is reused indefinitely, keyed on (command, parent, env_keys). Suitable for deterministic installs where the command string itself encodes the version (e.g. downloading a pinned binary). Do not use for steps that fetch mutable remote resources.

forever(env_keys=()) -> CacheForever

Returns CacheForever — A CacheForever policy for use in .sh(cache=...).

Examples

>>> import harmont as hm
>>> step = hm.sh("curl .../go1.23.tar.gz | tar ...", cache=hm.forever())

on_change

Create a content-addressed cache policy keyed on file hashes.

The step's snapshot is reused until any file under paths changes. Paths are relative to the source-archive root and resolved at render time by the key generator.

on_change(*paths) -> CacheOnChange

Returns CacheOnChange — A CacheOnChange policy for use in .sh(cache=...).

Examples

>>> import harmont as hm
>>> step = hm.sh("pip install -r requirements.txt",
...               cache=hm.on_change("requirements.txt"))

ttl

Create a time-to-live cache policy.

The step's snapshot is reused until duration has elapsed since the last successful run, floored to UTC midnight. Two builds within the same UTC day share a cache key; a build the following day rebuilds.

ttl(duration) -> CacheTTL

Returns CacheTTL — A CacheTTL policy for use in .sh(cache=...).

Examples

>>> from datetime import timedelta
>>> import harmont as hm
>>> step = hm.sh("apt-get update", cache=hm.ttl(timedelta(days=1)))