Fix EnvVar template parsing on Python 3.14

.github/workflows/tests.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

.gitignore

@@ -16,4 +16,6 @@ venv*/
 .vscode/
 encrypted.env
 baketest.env
-out.env
+out.env
+.codex
+.agents/

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.0.3] - 2026-07-23
+
+### Changed
+- add Python 3.14 to the GitHub Actions test matrix
+- update published Python version classifiers through 3.14
+- constrain `cryptography` to `<47` on Python 3.8 while allowing newer runtimes to resolve current releases
+- limit pytest discovery to the `tests/` suite and ignore `tmp/` helper files
+
+### Fixed
+- restore Python 3.14 compatibility in `EnvVar.vars()` by avoiding `string.Template` pattern access that now raises under 3.14
+- suppress the `cryptography` Python 3.8 deprecation warning during import so `envstack` subprocess tests and CLI startup remain quiet on supported 3.8 installs
+
+---
+
 ## [1.0.2] - 2026-04-01
 
 ### Changed

docs/index.md

@@ -71,6 +71,16 @@ envstack is commonly used for:
 - Pipeline and DCC tooling
 - Shared, hierarchical environment configuration
 
+## Project docs
+
+- [API](api.md)
+- [Comparison](comparison.md)
+- [Design](design.md)
+- [Examples](examples.md)
+- [FAQ](faq.md)
+- [Roadmap](roadmap.md)
+- [Secrets](secrets.md)
+
 ## A simple example
 
 ```yaml

docs/roadmap.md

@@ -0,0 +1,40 @@
+# Roadmap
+
+This document tracks likely near-term improvements and areas we want to
+explore as envstack evolves.
+
+## Near-term backlog
+
+The following items are active candidates for near-term roadmap work:
+
+- API documentation source structure
+- ternary-style expansion modifier
+- regex expansion modifier
+- version tag support
+
+## Performance and benchmarking
+
+envstack does not yet have dedicated benchmark tooling or performance
+regression coverage.
+
+This is likely worth adding soon, especially before larger changes to
+environment resolution, shell startup, or subprocess wrapping.
+
+Two possible directions:
+
+- Build custom benchmark tools tailored to envstack, similar to the benchmark
+  utilities used in sibling projects like `pyseq` and `snapfs`
+- Evaluate an off-the-shelf benchmark framework such as `asv` for repeatable
+  performance tracking over time
+
+Initial benchmark candidates:
+
+- stack loading and environment resolution
+- repeated `envstack -- [COMMAND]` subprocess startup cost
+- shell launch overhead
+- variable tracing and path expansion on larger environment stacks
+
+Future benchmark work should ideally cover both:
+
+- one-off profiling for targeted optimization work
+- regression checks that help catch performance drift across releases

lib/envstack/__init__.py

@@ -34,7 +34,7 @@
 """
 
 __prog__ = "envstack"
-__version__ = "1.0.2"
+__version__ = "1.0.3"
 
 from envstack.env import clear, init, revert, save  # noqa: F401
 from envstack.env import load_environ, resolve_environ  # noqa: F401

lib/envstack/encrypt.py

@@ -37,6 +37,7 @@
 import binascii
 import os
 import secrets
+import warnings
 from base64 import b64decode, b64encode
 from functools import wraps
 
@@ -53,10 +54,19 @@
 algorithms = None
 modes = None
 try:
-    from cryptography.fernet import Fernet, InvalidToken
-    from cryptography.exceptions import InvalidTag
-    from cryptography.hazmat.primitives import padding
-    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    # cryptography emits a Python 3.8 deprecation warning during import.
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore",
+            message=r"Python 3\.8 is no longer supported by the Python core team.*",
+            category=DeprecationWarning,
+            module=r"cryptography(\..*)?$",
+        )
+        from cryptography.fernet import Fernet, InvalidToken
+        from cryptography.exceptions import InvalidTag
+        from cryptography.hazmat.primitives import padding
+        from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
     CRYPTOGRAPHY_AVAILABLE = True
 except ImportError as err:
     log.debug("cryptography module not available: %s", err)

lib/envstack/env.py

@@ -248,7 +248,7 @@ def vars(self):
         >>> v.vars()
         ['FOO', 'BAR']
         """
-        matches = super(EnvVar, self).pattern.findall(str(self.template))
+        matches = type(self).pattern.findall(str(self.template))
         return [key for match in matches for key in match if key]
 
 

pyproject.toml

@@ -4,15 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "envstack"
-version = "1.0.2"
+version = "1.0.3"
 description = "Environment variable composition layer for tools and processes."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.6"
 license = { text = "BSD 3-Clause License" }
 authors = [{ name = "Ryan Galloway", email = "ryan@rsgalloway.com" }]
 dependencies = [
   "PyYAML>=5.1.2",
-  "cryptography>=43.0.1",
+  'cryptography>=43.0.1,<47; python_version < "3.9"',
+  'cryptography>=43.0.1; python_version >= "3.9"',
 ]
 classifiers = [
   "Development Status :: 4 - Beta",
@@ -25,6 +26,9 @@ classifiers = [
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
 ]
 keywords = [
   "environment",

pytest.ini

@@ -1,3 +1,5 @@
 [pytest]
 markers =
     integration: tests that run real subprocesses (slower / OS-dependent)
+testpaths = tests
+norecursedirs = tmp