Fix ZIP Timestamps Error in Homebrew Python Hatchling

Set SOURCE_DATE_EPOCH to a value >= 315532800 (1980-01-01 UTC) in your formula before the virtualenv install — for example add ENV['SOURCE_DATE_EPOCH'] = [Time.now.to_i, 315532800].max.to_s to kosmorro.rb. That prevents the python zipfile (zipfile.ZipInfo) error during hatchling python wheel builds; upgrading to a hatchling release that clamps timestamps is a longer-term fix.

Contents

• Homebrew formula fix: set SOURCE_DATE_EPOCH (homebrew python)
• Why the error happens (python zipfile)
• Alternative resolutions: upgrade hatchling, bottles, pinning (hatchling python)
• How to reproduce, test, and debug (zip timestamps)
• Patch example for kosmorro.rb
• Sources
• Conclusion

Homebrew formula fix: set SOURCE_DATE_EPOCH (homebrew python)

Short version: add a build-time environment variable in the formula so wheel builders stamp files with a legal DOS timestamp.

Why this is the least-invasive fix

• It’s tiny and local to the kosmorro build.
• It avoids changing packaging backends or vendoring patched packages.
• It fixes the immediate ValueError from Python’s zip handling.

Recommended code (insert before virtualenv install):

def install
 # Ensure any build-time timestamp is at least 1980-01-01 UTC
 ENV["SOURCE_DATE_EPOCH"] = [Time.now.to_i, 315532800].max.to_s

 # Optional: make conversions use UTC to avoid negative local tz offsets
 # ENV["TZ"] = "UTC"

 virtualenv_install_with_resources
end

Notes

• 315532800 is the Unix timestamp for 1980-01-01 00:00:00 UTC. Zip stores DOS timestamps and zipfile rejects dates earlier than that.
• Using the clamp [Time.now.to_i, 315532800].max.to_s keeps builds non-statically-dated on normal machines while guaranteeing the DOS minimum.
• You can instead hard-code "315532800" if you want fully reproducible build timestamps for this formula.
• If you prefer, set ENV["TZ"]="UTC" as an extra safeguard against build-time conversions to a negative local offset (see the CPython issue linked below). That’s optional.

After the change:

• Rebuild from source: brew reinstall --build-from-source --verbose kosmorro (or brew install --build-from-source kosmorro).
• The pip/hatchling wheel build step should no longer raise ValueError: ZIP does not support timestamps before 1980.

Why the error happens (python zipfile)

Short explanation: Zip archives store file modification times using a DOS date/time format that has a minimum of 1980‑01‑01. If a build backend stamps files with an epoch timestamp before that, Python’s zipfile.ZipInfo raises a ValueError.

Key mechanics

• Many PEP 517 build backends (hatchling, setuptools, etc.) set file mtimes in generated wheels using SOURCE_DATE_EPOCH when that environment variable exists. The reproducible-build ecosystem relies on that variable to make builds deterministic.
• If SOURCE_DATE_EPOCH is 0 or otherwise earlier than 1980, wheel builders may use it directly (or convert it to local time incorrectly), producing a pre‑1980 timestamp that zipfile.ZipInfo rejects.
• There have been concrete reports and fixes: see the CPython issue about negative timezone offsets and zip timestamp underflow and the hatchling PR that clamps timestamps to 1980 to avoid the problem.

Relevant reads

• Homebrew documents reproducible builds and explicitly notes ZIP/ DOS timestamp constraints and the need for a value >= 315532800: https://docs.brew.sh/Reproducible-Builds
• The Reproducible Builds project documents SOURCE_DATE_EPOCH and recommends clamping for ZIP: https://reproducible-builds.org/docs/source-date-epoch/
• CPython issue describing timezone conversion underflow behavior: https://github.com/python/cpython/issues/134261
• The hatchling PR that implements a clamp to 1980 for build timestamps: https://github.com/pypa/hatch/pull/1999

In practice this means: the termcolor 3.3.0 packaging (or one of its build-time dependencies such as hatch-vcs/hatchling) ends up stamping files with a timestamp that zip rejects. Homebrew’s build environment can expose this when SOURCE_DATE_EPOCH is set to a value earlier than 1980 (or when a backend mishandles timezone conversion).

Alternative resolutions: upgrade hatchling, bottles, pinning (hatchling python)

If you prefer not to change the formula environment, other options exist — each has tradeoffs.

1. Wait for / require a patched hatchling

• The upstream fix clamps timestamps to 1980 in the builder (see the hatch PR). Once that version is on PyPI and picked up during the isolated build, the problem disappears.
• Pro: upstream, permanent solution.
• Con: you have to wait for new releases and for pip to install them during PEP 517 builds.

2. Vendor or patch the build backend during the build

• You could vendor a patched hatchling or apply a small patch to the wheel-builder in the build environment.
• Pro: immediate and surgical.
• Con: more brittle, complicated in Homebrew because PEP 517 build isolation installs build dependencies into a temporary environment that Homebrew formulae don’t control easily.

3. Use a bottle (prebuild)

• Build and publish a bottled kosmorro so end users install the binary instead of building wheels on their machines.
• Pro: avoids building termcolor (and others) on the user’s machine.
• Con: extra CI work and you must update bottles for new releases/architectures.

4. Pin termcolor to an older release (temporary)

• Roll back to termcolor 2.5.0 in the resource if that version uses a different build backend.
• Pro: quick workaround.
• Con: avoids the newer release and is temporary.

5. Patch formula to clamp SOURCE_DATE_EPOCH (recommended)

• Minimal, robust, and local. See the example in Homebrew’s own python formula for how Homebrew handles SOURCE_DATE_EPOCH in other formulas.

How to reproduce, test, and debug (zip timestamps)

Commands to reproduce locally (simulate the problematic environment)

• Reproduce the failing build step outside Homebrew:
• env SOURCE_DATE_EPOCH=0 python3.14 -m pip install --no-binary :all: --no-build-isolation --verbose termcolor==3.3.0
• You should see the hatchling wheel build step and a traceback referencing zipfile.ZipInfo and the ValueError if the environment triggers a pre‑1980 timestamp.

Check your Homebrew build environment

• Run Homebrew with verbose/debug to see environment variables:
• brew install --build-from-source --verbose --debug kosmorro
• Inspect the build temporary path shown in the failure logs (e.g., /private/tmp/.../termcolor-3.3.0) to confirm SOURCE_DATE_EPOCH in that environment.

Quick Python check for the zip behavior

• This demonstrates the acceptance/rejection of DOS timestamps:

# save as test_zip.py and run with python3.14
import zipfile

# this should succeed (1980)
z = zipfile.ZipFile("ok.zip", "w")
zi = zipfile.ZipInfo("ok.txt", (1980, 1, 1, 0, 0, 0))
z.writestr(zi, "x")
z.close()
print("ok.zip created")

# this should raise ValueError (1979)
z = zipfile.ZipFile("bad.zip", "w")
zi = zipfile.ZipInfo("bad.txt", (1979, 12, 31, 23, 59, 59))
try:
 z.writestr(zi, "x")
except Exception as e:
 print("expected failure:", type(e).__name__, e)

If your modified formula fixes the build, the pip/hatchling step will proceed and the wheel will be created without the ZIP timestamp error.

Patch example for kosmorro.rb

Minimal patch to the formula (context only):

 def install
- virtualenv_install_with_resources
+ # Ensure ZIP file timestamps are valid for DOS format (>= 1980-01-01 UTC)
+ ENV["SOURCE_DATE_EPOCH"] = [Time.now.to_i, 315532800].max.to_s
+
+ # Optional: avoid timezone conversion surprises (uncomment if needed)
+ # ENV["TZ"] = "UTC"
+
+ virtualenv_install_with_resources
 end

Notes on committing:

• Update the formula in your tap and run brew install --build-from-source kosmorro locally.
• If this is intended as a permanent reproducibility measure, consider leaving the clamp as-is; if you want the build timestamp to reflect build time (but still be safe), use the clamp expression shown above.

Sources

• ZipFile tests fail in negative timezone offsets on reproducible build environments (CPython issue)
• Reproducible Builds - Homebrew Documentation
• Support a SOURCE_DATE_EPOCH prior to 1980 (hatch PR)
• SOURCE_DATE_EPOCH - reproducible-builds.org
• Homebrew python.rb Formula - example of environment handling

Conclusion

The quickest, least invasive way to fix the “ZIP does not support timestamps before 1980” failure when installing termcolor with homebrew python is to ensure the build uses a legal timestamp: add ENV["SOURCE_DATE_EPOCH"] = [Time.now.to_i, 315532800].max.to_s (or "315532800") to kosmorro.rb before virtualenv_install_with_resources. That removes the python zipfile error during hatchling python wheel creation; upgrading to the hatchling release that clamps timestamps is the long-term upstream fix.