envlatch 0.6.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- envlatch/__init__.py +7 -0
- envlatch/__main__.py +5 -0
- envlatch/_types.py +73 -0
- envlatch/cli.py +119 -0
- envlatch/config.py +98 -0
- envlatch/core.py +251 -0
- envlatch-0.6.1.dist-info/METADATA +433 -0
- envlatch-0.6.1.dist-info/RECORD +12 -0
- envlatch-0.6.1.dist-info/WHEEL +5 -0
- envlatch-0.6.1.dist-info/entry_points.txt +2 -0
- envlatch-0.6.1.dist-info/licenses/LICENSE +21 -0
- envlatch-0.6.1.dist-info/top_level.txt +1 -0
envlatch/__init__.py
ADDED
envlatch/__main__.py
ADDED
envlatch/_types.py
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""Local syntax checks; values never leave these predicates or reach diagnostics."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ipaddress
|
|
6
|
+
import re
|
|
7
|
+
|
|
8
|
+
TYPE_NAMES = ('string', 'integer', 'boolean', 'url', 'port')
|
|
9
|
+
_INTEGER = re.compile(r'[+-]?[0-9]+\Z')
|
|
10
|
+
_DIGITS = re.compile(r'[0-9]+\Z')
|
|
11
|
+
_URL = re.compile(r'[A-Za-z][A-Za-z0-9+.-]*://([^/?#]*)(?:[/?#].*)?\Z')
|
|
12
|
+
_LABEL = re.compile(r'[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\Z')
|
|
13
|
+
_BAD_PERCENT = re.compile(r'%(?![0-9A-Fa-f]{2})')
|
|
14
|
+
_USERINFO = re.compile(r"[A-Za-z0-9._~!$&'()*+,;=:%-]*\Z")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _port(value: str) -> bool:
|
|
18
|
+
if not _DIGITS.fullmatch(value):
|
|
19
|
+
return False
|
|
20
|
+
# Avoid integer-conversion limits even for unusually long input.
|
|
21
|
+
number = value.lstrip('0')
|
|
22
|
+
return bool(number) and (len(number) < 5 or (len(number) == 5 and number <= '65535'))
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _url(value: str) -> bool:
|
|
26
|
+
if (_BAD_PERCENT.search(value)
|
|
27
|
+
or any(char.isspace() or ord(char) < 32 or 127 <= ord(char) <= 159
|
|
28
|
+
or char in '\\<>"{}|^`' for char in value)):
|
|
29
|
+
return False
|
|
30
|
+
match = _URL.fullmatch(value)
|
|
31
|
+
if match is None:
|
|
32
|
+
return False
|
|
33
|
+
try:
|
|
34
|
+
# Parse locally rather than using a URL parser that caches raw inputs.
|
|
35
|
+
netloc = match[1]
|
|
36
|
+
authority = netloc.rsplit('@', 1)[-1]
|
|
37
|
+
if netloc.count('@') > 1 or not authority:
|
|
38
|
+
return False
|
|
39
|
+
if '@' in netloc and not _USERINFO.fullmatch(netloc.rsplit('@', 1)[0]):
|
|
40
|
+
return False
|
|
41
|
+
if authority.startswith('['):
|
|
42
|
+
end = authority.index(']')
|
|
43
|
+
# Require bracketed IPv6 and a well-formed optional port suffix.
|
|
44
|
+
ipaddress.IPv6Address(authority[1:end])
|
|
45
|
+
suffix = authority[end + 1:]
|
|
46
|
+
return not suffix or (suffix.startswith(':') and _port(suffix[1:]))
|
|
47
|
+
if '[' in authority or ']' in authority or authority.count(':') > 1:
|
|
48
|
+
return False
|
|
49
|
+
host, separator, port = authority.partition(':')
|
|
50
|
+
if separator and not _port(port):
|
|
51
|
+
return False
|
|
52
|
+
host = host.encode('idna').decode('ascii').removesuffix('.')
|
|
53
|
+
if not host or len(host) > 253:
|
|
54
|
+
return False
|
|
55
|
+
if re.fullmatch(r'[0-9.]+', host) and '.' in host:
|
|
56
|
+
ipaddress.IPv4Address(host)
|
|
57
|
+
return all(_LABEL.fullmatch(label) for label in host.split('.'))
|
|
58
|
+
except (ValueError, UnicodeError):
|
|
59
|
+
# IDNA/IP exceptions may contain input: never expose their messages.
|
|
60
|
+
return False
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def matches_type(value: str, kind: str) -> bool:
|
|
64
|
+
"""Check the literal dotenv value, without coercion or network access."""
|
|
65
|
+
if kind == 'string':
|
|
66
|
+
return True
|
|
67
|
+
if kind == 'integer':
|
|
68
|
+
return _INTEGER.fullmatch(value) is not None
|
|
69
|
+
if kind == 'boolean':
|
|
70
|
+
return value.lower() in ('true', 'false', '1', '0')
|
|
71
|
+
if kind == 'port':
|
|
72
|
+
return _port(value)
|
|
73
|
+
return kind == 'url' and _url(value)
|
envlatch/cli.py
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
"""Command-line interface for EnvLatch."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
from dataclasses import asdict
|
|
7
|
+
import json
|
|
8
|
+
import sys
|
|
9
|
+
from collections.abc import Sequence
|
|
10
|
+
|
|
11
|
+
from . import __version__
|
|
12
|
+
from .core import InputError, Issue, Report, check
|
|
13
|
+
from .config import Config, load_config
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _summary(report: Report) -> str:
|
|
17
|
+
status = "PASS" if report.valid else "FAIL"
|
|
18
|
+
return (f"{status}: {report.checked_keys} required key(s), "
|
|
19
|
+
f"{report.errors} error(s), {report.warnings} warning(s). Values are never displayed.")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def render_text(report: Report) -> str:
|
|
23
|
+
lines = []
|
|
24
|
+
for issue in report.issues:
|
|
25
|
+
location = issue.path or "<input>"
|
|
26
|
+
if issue.line is not None:
|
|
27
|
+
location += f":{issue.line}"
|
|
28
|
+
lines.append(f"{issue.severity.upper()} [{issue.code}] {location}: {issue.message}")
|
|
29
|
+
lines.append(_summary(report))
|
|
30
|
+
return "\n".join(lines)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def render_json(report: Report, *, status: str | None = None) -> str:
|
|
34
|
+
"""Render the versioned automation format without source values."""
|
|
35
|
+
document = {
|
|
36
|
+
"schema_version": 1,
|
|
37
|
+
"status": status or ("pass" if report.valid else "fail"),
|
|
38
|
+
"template": report.template,
|
|
39
|
+
"environments": list(report.environments),
|
|
40
|
+
"checked_keys": report.checked_keys,
|
|
41
|
+
"errors": report.errors,
|
|
42
|
+
"warnings": report.warnings,
|
|
43
|
+
"issues": [asdict(issue) for issue in report.issues],
|
|
44
|
+
}
|
|
45
|
+
return json.dumps(document, ensure_ascii=True, indent=2, sort_keys=True)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _workflow_data(value: str) -> str:
|
|
49
|
+
return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _workflow_property(value: str) -> str:
|
|
53
|
+
return _workflow_data(value).replace(":", "%3A").replace(",", "%2C")
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def render_github(report: Report) -> str:
|
|
57
|
+
"""Emit escaped GitHub Actions annotations, followed by the normal summary."""
|
|
58
|
+
lines = []
|
|
59
|
+
for issue in report.issues:
|
|
60
|
+
properties = [("title", "EnvLatch: " + issue.code)]
|
|
61
|
+
if issue.path is not None:
|
|
62
|
+
properties.append(("file", issue.path))
|
|
63
|
+
if issue.line is not None:
|
|
64
|
+
properties.append(("line", str(issue.line)))
|
|
65
|
+
metadata = ",".join(f"{key}={_workflow_property(value)}" for key, value in properties)
|
|
66
|
+
lines.append(f"::{issue.severity} {metadata}::{_workflow_data(issue.message)}")
|
|
67
|
+
lines.append(_summary(report))
|
|
68
|
+
return "\n".join(lines)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
72
|
+
parser = argparse.ArgumentParser(
|
|
73
|
+
prog="envlatch",
|
|
74
|
+
description="Check dotenv keys against a template without displaying values.",
|
|
75
|
+
)
|
|
76
|
+
parser.add_argument("--version", action="version", version=f"EnvLatch {__version__}")
|
|
77
|
+
parser.add_argument("--config", metavar="PATH", help="explicit JSON settings file")
|
|
78
|
+
parser.add_argument("--template", metavar="PATH", help="dotenv contract file")
|
|
79
|
+
parser.add_argument("--env", action="append", metavar="PATH",
|
|
80
|
+
help="dotenv file; repeat to overlay files in order (later keys win)")
|
|
81
|
+
strictness = parser.add_mutually_exclusive_group()
|
|
82
|
+
strictness.add_argument("--strict", dest="strict", action="store_true", default=None,
|
|
83
|
+
help="treat extra keys as errors")
|
|
84
|
+
strictness.add_argument("--no-strict", dest="strict", action="store_false", default=None,
|
|
85
|
+
help="treat extra keys as warnings, overriding config strict mode")
|
|
86
|
+
parser.add_argument("--optional", action="append", metavar="KEY",
|
|
87
|
+
help="template key allowed to be missing or blank; repeat for more keys")
|
|
88
|
+
parser.add_argument("--allow-extra", action="append", metavar="PATTERN",
|
|
89
|
+
help="allow extra keys matching a case-sensitive '*'/'?' pattern; repeat for more")
|
|
90
|
+
parser.add_argument("--format", choices=("text", "json", "github"),
|
|
91
|
+
help="output format (default: config setting or text)")
|
|
92
|
+
arguments = parser.parse_args(argv)
|
|
93
|
+
output_format = arguments.format or "text"
|
|
94
|
+
template = arguments.template
|
|
95
|
+
environments = tuple(arguments.env) if arguments.env is not None else None
|
|
96
|
+
try:
|
|
97
|
+
settings = load_config(arguments.config) if arguments.config is not None else Config()
|
|
98
|
+
output_format = arguments.format or settings.output_format
|
|
99
|
+
template = arguments.template if arguments.template is not None else settings.template
|
|
100
|
+
environments = tuple(arguments.env) if arguments.env is not None else settings.environments
|
|
101
|
+
if template is None or environments is None:
|
|
102
|
+
parser.error("provide --template and --env, directly or through --config")
|
|
103
|
+
strict = arguments.strict if arguments.strict is not None else settings.strict
|
|
104
|
+
optional = arguments.optional if arguments.optional is not None else settings.optional_keys
|
|
105
|
+
allowed = arguments.allow_extra if arguments.allow_extra is not None else settings.allow_extra
|
|
106
|
+
report = check(template, environments, strict=strict, optional_keys=optional,
|
|
107
|
+
allow_extra=allowed, types=settings.types)
|
|
108
|
+
except InputError as error:
|
|
109
|
+
if output_format in ("json", "github"):
|
|
110
|
+
report = Report(template or "", tuple(environments or ()), 0,
|
|
111
|
+
(Issue("error", "input_error", None, str(error)),))
|
|
112
|
+
print(render_json(report, status="input_error")
|
|
113
|
+
if output_format == "json" else render_github(report))
|
|
114
|
+
else:
|
|
115
|
+
print(f"ERROR [input_error] {error}", file=sys.stderr)
|
|
116
|
+
return 2
|
|
117
|
+
renderer = {"text": render_text, "json": render_json, "github": render_github}[output_format]
|
|
118
|
+
print(renderer(report))
|
|
119
|
+
return 0 if report.valid else 1
|
envlatch/config.py
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""Load explicit JSON settings without executing configuration code."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
import json
|
|
7
|
+
import os
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
from .core import InputError, validate_types
|
|
11
|
+
|
|
12
|
+
_FIELDS = frozenset(('template', 'env', 'strict', 'optional', 'allow_extra', 'format', 'types'))
|
|
13
|
+
_FORMATS = ('text', 'json', 'github')
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass(frozen=True)
|
|
17
|
+
class Config:
|
|
18
|
+
template: str | None = None
|
|
19
|
+
environments: tuple[str, ...] | None = None
|
|
20
|
+
strict: bool = False
|
|
21
|
+
optional_keys: tuple[str, ...] = ()
|
|
22
|
+
allow_extra: tuple[str, ...] = ()
|
|
23
|
+
output_format: str = 'text'
|
|
24
|
+
types: dict[str, str] = field(default_factory=dict)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class _InvalidJSON(ValueError):
|
|
28
|
+
pass
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _unique_object(pairs):
|
|
32
|
+
result = {}
|
|
33
|
+
for key, value in pairs:
|
|
34
|
+
if key in result:
|
|
35
|
+
raise _InvalidJSON('Duplicate JSON configuration fields are not allowed.')
|
|
36
|
+
result[key] = value
|
|
37
|
+
return result
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _reject_constant(_value):
|
|
41
|
+
raise _InvalidJSON('Non-standard JSON numeric constants are not allowed.')
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _string(value, field: str) -> str:
|
|
45
|
+
if not isinstance(value, str) or not value.strip() or '\x00' in value:
|
|
46
|
+
raise InputError(f"Configuration field '{field}' requires nonempty strings without NUL characters.")
|
|
47
|
+
try:
|
|
48
|
+
value.encode('utf-8')
|
|
49
|
+
except UnicodeError:
|
|
50
|
+
raise InputError(f"Configuration field '{field}' contains invalid Unicode.") from None
|
|
51
|
+
return value
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _strings(value, field: str, *, nonempty: bool = False) -> tuple[str, ...]:
|
|
55
|
+
if not isinstance(value, list) or (nonempty and not value):
|
|
56
|
+
qualifier = 'a nonempty array' if nonempty else 'an array'
|
|
57
|
+
raise InputError(f"Configuration field '{field}' requires {qualifier} of strings.")
|
|
58
|
+
return tuple(_string(item, field) for item in value)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def load_config(path: str | Path) -> Config:
|
|
62
|
+
"""Read settings; configured paths are relative to the config directory."""
|
|
63
|
+
config_path = Path(path)
|
|
64
|
+
try:
|
|
65
|
+
text = config_path.read_text(encoding='utf-8-sig')
|
|
66
|
+
except (OSError, UnicodeError, ValueError):
|
|
67
|
+
raise InputError(f'Cannot read UTF-8 configuration file: {config_path}') from None
|
|
68
|
+
try:
|
|
69
|
+
data = json.loads(text, object_pairs_hook=_unique_object, parse_constant=_reject_constant)
|
|
70
|
+
except json.JSONDecodeError as error:
|
|
71
|
+
raise InputError(f'Invalid JSON configuration: {config_path} (line {error.lineno}, column {error.colno}).') from None
|
|
72
|
+
except _InvalidJSON as error:
|
|
73
|
+
raise InputError(f'{error} File: {config_path}') from None
|
|
74
|
+
except (ValueError, RecursionError):
|
|
75
|
+
raise InputError(f'Invalid JSON configuration: {config_path}') from None
|
|
76
|
+
if not isinstance(data, dict):
|
|
77
|
+
raise InputError('Configuration must be a JSON object.')
|
|
78
|
+
if data.keys() - _FIELDS:
|
|
79
|
+
raise InputError('Unknown configuration option. Allowed options: template, env, strict, optional, allow_extra, format, types.')
|
|
80
|
+
if 'strict' in data and not isinstance(data['strict'], bool):
|
|
81
|
+
raise InputError("Configuration field 'strict' requires a boolean.")
|
|
82
|
+
if 'format' in data and data['format'] not in _FORMATS:
|
|
83
|
+
raise InputError("Configuration field 'format' must be text, json or github.")
|
|
84
|
+
base = config_path.absolute().parent
|
|
85
|
+
template = None
|
|
86
|
+
environments = None
|
|
87
|
+
if 'template' in data:
|
|
88
|
+
template = os.path.abspath(base / _string(data['template'], 'template'))
|
|
89
|
+
if 'env' in data:
|
|
90
|
+
environments = tuple(os.path.abspath(base / value)
|
|
91
|
+
for value in _strings(data['env'], 'env', nonempty=True))
|
|
92
|
+
optional = _strings(data['optional'], 'optional') if 'optional' in data else ()
|
|
93
|
+
allowed = _strings(data['allow_extra'], 'allow_extra') if 'allow_extra' in data else ()
|
|
94
|
+
if 'types' in data and not isinstance(data['types'], dict):
|
|
95
|
+
raise InputError("Configuration field 'types' requires an object mapping names to types.")
|
|
96
|
+
types = validate_types(data.get('types'))
|
|
97
|
+
return Config(template, environments, data.get('strict', False), optional, allowed,
|
|
98
|
+
data.get('format', 'text'), types)
|
envlatch/core.py
ADDED
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
"""The parser keeps only names, line numbers and whether a value is blank."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Iterable, Mapping, Sequence
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
from fnmatch import fnmatchcase
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
import re
|
|
10
|
+
|
|
11
|
+
from ._types import TYPE_NAMES, matches_type
|
|
12
|
+
|
|
13
|
+
_KEY = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
|
|
14
|
+
_EXPORT = re.compile(r"export[ \t]+")
|
|
15
|
+
_EXTRA_PATTERN = re.compile(r"[A-Za-z0-9_*?]+\Z")
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass(frozen=True)
|
|
19
|
+
class Issue:
|
|
20
|
+
"""A safe diagnostic: no raw source lines or environment values."""
|
|
21
|
+
|
|
22
|
+
severity: str
|
|
23
|
+
code: str
|
|
24
|
+
path: str | None
|
|
25
|
+
message: str
|
|
26
|
+
line: int | None = None
|
|
27
|
+
key: str | None = None
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass(frozen=True)
|
|
31
|
+
class Entry:
|
|
32
|
+
key: str
|
|
33
|
+
line: int
|
|
34
|
+
empty: bool
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class Report:
|
|
39
|
+
template: str
|
|
40
|
+
environments: tuple[str, ...]
|
|
41
|
+
checked_keys: int
|
|
42
|
+
issues: tuple[Issue, ...]
|
|
43
|
+
|
|
44
|
+
@property
|
|
45
|
+
def environment(self) -> str:
|
|
46
|
+
"""The final input file, retained for single-file API compatibility."""
|
|
47
|
+
return self.environments[-1]
|
|
48
|
+
|
|
49
|
+
@property
|
|
50
|
+
def errors(self) -> int:
|
|
51
|
+
return sum(issue.severity == "error" for issue in self.issues)
|
|
52
|
+
|
|
53
|
+
@property
|
|
54
|
+
def warnings(self) -> int:
|
|
55
|
+
return sum(issue.severity == "warning" for issue in self.issues)
|
|
56
|
+
|
|
57
|
+
@property
|
|
58
|
+
def valid(self) -> bool:
|
|
59
|
+
return self.errors == 0
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class InputError(Exception):
|
|
63
|
+
"""Invalid input or configuration; messages never contain dotenv values."""
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _closing_quote(value: str) -> int | None:
|
|
67
|
+
quote = value[0]
|
|
68
|
+
escaped = False
|
|
69
|
+
for index in range(1, len(value)):
|
|
70
|
+
character = value[index]
|
|
71
|
+
if quote == '"' and escaped:
|
|
72
|
+
escaped = False
|
|
73
|
+
continue
|
|
74
|
+
if quote == '"' and character == "\\":
|
|
75
|
+
escaped = True
|
|
76
|
+
continue
|
|
77
|
+
if character == quote:
|
|
78
|
+
return index
|
|
79
|
+
return None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _literal_value(value: str) -> str | None:
|
|
83
|
+
"""Extract a literal transient value; None means invalid quoted syntax."""
|
|
84
|
+
value = value.strip()
|
|
85
|
+
if not value or value.startswith("#"):
|
|
86
|
+
return ''
|
|
87
|
+
if value[0] not in ("'", '"'):
|
|
88
|
+
for index, character in enumerate(value):
|
|
89
|
+
if character == "#" and index and value[index - 1].isspace():
|
|
90
|
+
value = value[:index]
|
|
91
|
+
break
|
|
92
|
+
return value.strip()
|
|
93
|
+
|
|
94
|
+
end = _closing_quote(value)
|
|
95
|
+
if end is None:
|
|
96
|
+
return None
|
|
97
|
+
tail = value[end + 1 :].strip()
|
|
98
|
+
if tail and not tail.startswith("#"):
|
|
99
|
+
return None
|
|
100
|
+
return value[1:end]
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _read(path: Path) -> str:
|
|
104
|
+
try:
|
|
105
|
+
return path.read_text(encoding="utf-8-sig")
|
|
106
|
+
except UnicodeError:
|
|
107
|
+
raise InputError(f"Cannot read UTF-8 input: {path}") from None
|
|
108
|
+
except OSError:
|
|
109
|
+
raise InputError(f"Cannot read input file: {path}") from None
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def parse(text: str, path: str) -> tuple[dict[str, Entry], list[Issue]]:
|
|
113
|
+
"""Parse a single-line dotenv dialect and discard all actual values."""
|
|
114
|
+
entries, issues, _ = _parse(text, path, {})
|
|
115
|
+
return entries, issues
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def _parse(text: str, path: str, types: Mapping[str, str]) -> tuple[dict[str, Entry], list[Issue], set[str]]:
|
|
119
|
+
entries: dict[str, Entry] = {}
|
|
120
|
+
issues: list[Issue] = []
|
|
121
|
+
invalid_types: set[str] = set()
|
|
122
|
+
# Stop on malformed syntax so rejected multiline fragments cannot become keys.
|
|
123
|
+
# Only LF/CRLF are physical line boundaries; Unicode in values stays literal.
|
|
124
|
+
for line_number, raw in enumerate(text.removeprefix("\ufeff").split("\n"), 1):
|
|
125
|
+
line = raw.rstrip("\r").strip()
|
|
126
|
+
if not line or line.startswith("#"):
|
|
127
|
+
continue
|
|
128
|
+
if "\x00" in line:
|
|
129
|
+
issues.append(Issue("error", "invalid_syntax", path,
|
|
130
|
+
"NUL characters are not supported.", line_number))
|
|
131
|
+
break
|
|
132
|
+
line = _EXPORT.sub("", line, count=1)
|
|
133
|
+
if "=" not in line:
|
|
134
|
+
issues.append(Issue("error", "invalid_syntax", path,
|
|
135
|
+
"Expected KEY=VALUE.", line_number))
|
|
136
|
+
break
|
|
137
|
+
key, value = line.split("=", 1)
|
|
138
|
+
key = key.strip()
|
|
139
|
+
if not _KEY.fullmatch(key):
|
|
140
|
+
issues.append(Issue("error", "invalid_key", path,
|
|
141
|
+
"Expected an ASCII environment variable name.", line_number))
|
|
142
|
+
break
|
|
143
|
+
literal = _literal_value(value)
|
|
144
|
+
if literal is None:
|
|
145
|
+
issues.append(Issue("error", "invalid_value", path,
|
|
146
|
+
"Expected a single-line value with balanced quotes and no trailing text.",
|
|
147
|
+
line_number, key))
|
|
148
|
+
break
|
|
149
|
+
if key in entries:
|
|
150
|
+
issues.append(Issue("error", "duplicate_key", path,
|
|
151
|
+
f"Duplicate key '{key}'; first defined on line {entries[key].line}.",
|
|
152
|
+
line_number, key))
|
|
153
|
+
continue
|
|
154
|
+
empty = not literal.strip()
|
|
155
|
+
if not empty and key in types and not matches_type(literal, types[key]):
|
|
156
|
+
invalid_types.add(key)
|
|
157
|
+
entries[key] = Entry(key, line_number, empty)
|
|
158
|
+
return entries, issues, invalid_types
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def validate_types(types: Mapping[str, str] | None) -> dict[str, str]:
|
|
162
|
+
"""Copy rules, rejecting malformed settings without echoing their contents."""
|
|
163
|
+
if types is None:
|
|
164
|
+
return {}
|
|
165
|
+
if not isinstance(types, Mapping):
|
|
166
|
+
raise InputError("Type rules must be an object mapping variable names to type names.")
|
|
167
|
+
rules = dict(types)
|
|
168
|
+
if any(not isinstance(key, str) or not _KEY.fullmatch(key) for key in rules):
|
|
169
|
+
raise InputError("Type rules must use ASCII environment variable names.")
|
|
170
|
+
if any(not isinstance(kind, str) or kind not in TYPE_NAMES for kind in rules.values()):
|
|
171
|
+
raise InputError("Type rules must use string, integer, boolean, url or port.")
|
|
172
|
+
return rules
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def check(
|
|
176
|
+
template: str | Path,
|
|
177
|
+
environment: str | Path | Sequence[str | Path],
|
|
178
|
+
*,
|
|
179
|
+
strict: bool = False,
|
|
180
|
+
optional_keys: Iterable[str] = (),
|
|
181
|
+
allow_extra: Iterable[str] = (),
|
|
182
|
+
types: Mapping[str, str] | None = None,
|
|
183
|
+
) -> Report:
|
|
184
|
+
"""Validate a contract against files merged in order, with later keys winning."""
|
|
185
|
+
type_rules = validate_types(types)
|
|
186
|
+
if isinstance(optional_keys, (str, bytes)):
|
|
187
|
+
raise InputError("Optional keys must be a sequence of names, not a single string.")
|
|
188
|
+
try:
|
|
189
|
+
optional_names = tuple(optional_keys)
|
|
190
|
+
except TypeError:
|
|
191
|
+
raise InputError("Optional keys must be an iterable of names.") from None
|
|
192
|
+
if any(not isinstance(key, str) or not _KEY.fullmatch(key) for key in optional_names):
|
|
193
|
+
raise InputError("Optional keys must use ASCII environment variable names.")
|
|
194
|
+
optional = frozenset(optional_names)
|
|
195
|
+
if isinstance(allow_extra, (str, bytes)):
|
|
196
|
+
raise InputError("Allow-extra patterns must be an iterable of patterns, not a single string.")
|
|
197
|
+
try:
|
|
198
|
+
extra_patterns = tuple(allow_extra)
|
|
199
|
+
except TypeError:
|
|
200
|
+
raise InputError("Allow-extra patterns must be an iterable of patterns.") from None
|
|
201
|
+
if any(not isinstance(pattern, str) or not _EXTRA_PATTERN.fullmatch(pattern)
|
|
202
|
+
for pattern in extra_patterns):
|
|
203
|
+
raise InputError("Allow-extra patterns must contain only ASCII letters, digits, underscores, '*' or '?'.")
|
|
204
|
+
template_path = Path(template)
|
|
205
|
+
if isinstance(environment, (str, Path)):
|
|
206
|
+
environment_paths = (Path(environment),)
|
|
207
|
+
else:
|
|
208
|
+
environment_paths = tuple(Path(path) for path in environment)
|
|
209
|
+
if not environment_paths:
|
|
210
|
+
raise InputError("At least one environment file is required.")
|
|
211
|
+
|
|
212
|
+
expected, template_issues = parse(_read(template_path), str(template_path))
|
|
213
|
+
issues = list(template_issues)
|
|
214
|
+
actual: dict[str, Entry] = {}
|
|
215
|
+
sources: dict[str, str] = {}
|
|
216
|
+
invalid_types: set[str] = set()
|
|
217
|
+
for environment_path in environment_paths:
|
|
218
|
+
entries, file_issues, file_invalid_types = _parse(_read(environment_path), str(environment_path), type_rules)
|
|
219
|
+
issues.extend(file_issues)
|
|
220
|
+
actual.update(entries)
|
|
221
|
+
sources.update((key, str(environment_path)) for key in entries)
|
|
222
|
+
invalid_types.difference_update(entries)
|
|
223
|
+
invalid_types.update(file_invalid_types)
|
|
224
|
+
|
|
225
|
+
# A broken contract cannot reliably define required keys.
|
|
226
|
+
if not template_issues:
|
|
227
|
+
for key in sorted(type_rules.keys() - expected.keys()):
|
|
228
|
+
issues.append(Issue("error", "unknown_type_key", str(template_path),
|
|
229
|
+
f"Typed key '{key}' is absent from the template.", key=key))
|
|
230
|
+
for key in sorted(optional - expected.keys()):
|
|
231
|
+
issues.append(Issue("error", "unknown_optional_key", str(template_path),
|
|
232
|
+
f"Optional key '{key}' is absent from the template.", key=key))
|
|
233
|
+
for key in sorted(expected.keys() - optional):
|
|
234
|
+
if key not in actual:
|
|
235
|
+
issues.append(Issue("error", "missing_key", str(environment_paths[-1]),
|
|
236
|
+
f"Required key '{key}' is missing.", key=key))
|
|
237
|
+
elif actual[key].empty:
|
|
238
|
+
issues.append(Issue("error", "empty_value", sources[key],
|
|
239
|
+
f"Required key '{key}' is blank.", actual[key].line, key))
|
|
240
|
+
for key in sorted(actual.keys() - expected.keys()):
|
|
241
|
+
if any(fnmatchcase(key, pattern) for pattern in extra_patterns):
|
|
242
|
+
continue
|
|
243
|
+
issues.append(Issue("error" if strict else "warning", "extra_key", sources[key],
|
|
244
|
+
f"Key '{key}' is absent from the template.", actual[key].line, key))
|
|
245
|
+
for key in sorted(type_rules.keys() & expected.keys() & actual.keys()):
|
|
246
|
+
if key in invalid_types:
|
|
247
|
+
issues.append(Issue("error", "invalid_type", sources[key],
|
|
248
|
+
f"Key '{key}' must have type '{type_rules[key]}'.",
|
|
249
|
+
actual[key].line, key))
|
|
250
|
+
return Report(str(template_path), tuple(str(path) for path in environment_paths),
|
|
251
|
+
len(expected.keys() - optional), tuple(issues))
|
|
@@ -0,0 +1,433 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: envlatch
|
|
3
|
+
Version: 0.6.1
|
|
4
|
+
Summary: Check dotenv files against a contract without exposing values.
|
|
5
|
+
Author: sinzbtw
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/sinzbtw/envlatch
|
|
8
|
+
Project-URL: Documentation, https://github.com/sinzbtw/envlatch#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/sinzbtw/envlatch
|
|
10
|
+
Project-URL: Issues, https://github.com/sinzbtw/envlatch/issues
|
|
11
|
+
Project-URL: Changelog, https://github.com/sinzbtw/envlatch/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: dotenv,environment,configuration,validation,cli
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Operating System :: OS Independent
|
|
23
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
**[English](https://github.com/sinzbtw/envlatch/blob/main/README.md)** | [Русский](https://github.com/sinzbtw/envlatch/blob/main/README.ru.md)
|
|
30
|
+
|
|
31
|
+
# EnvLatch
|
|
32
|
+
|
|
33
|
+
**Catch missing environment variables before your application starts.**
|
|
34
|
+
|
|
35
|
+
[](https://github.com/sinzbtw/envlatch/actions/workflows/ci.yml)
|
|
36
|
+
[](https://www.python.org/)
|
|
37
|
+
[](https://github.com/sinzbtw/envlatch/blob/main/LICENSE)
|
|
38
|
+
|
|
39
|
+
EnvLatch is a small, dependency-free Python command-line tool that checks one or more local `.env` files against the keys in a committed `.env.example`. Use it after onboarding, before running a service, or in a deployment check to find configuration drift early.
|
|
40
|
+
|
|
41
|
+
## What it checks
|
|
42
|
+
|
|
43
|
+
- Every template key is required and nonblank by default; `--optional KEY` allows selected keys to be missing or blank.
|
|
44
|
+
- Unexpected keys produce warnings; `--strict` makes them errors. Use `--allow-extra PATTERN` for explicit exceptions.
|
|
45
|
+
- Duplicate keys and malformed assignments produce errors with line numbers.
|
|
46
|
+
- Reports include variable names and locations, never their values or source lines.
|
|
47
|
+
- Save paths and validation policy in an explicit JSON project config, with CLI overrides.
|
|
48
|
+
- Optionally check selected values as string, integer, boolean, URL or port using JSON `types` rules.
|
|
49
|
+
- Deterministic text, JSON, and GitHub Actions reports use exit codes suitable for scripts and CI.
|
|
50
|
+
|
|
51
|
+
EnvLatch reads files only. It does not load variables into your process, evaluate shell commands, expand references, or read values from the current process environment. It validates presence, nonblank values and explicitly configured type syntax. It does not verify credentials, connect to URLs or check whether a port is available.
|
|
52
|
+
|
|
53
|
+
## Requirements
|
|
54
|
+
|
|
55
|
+
- Python **3.10 or newer**.
|
|
56
|
+
- Windows, Linux, or macOS.
|
|
57
|
+
- UTF-8 input files; a UTF-8 BOM and CRLF line endings are supported.
|
|
58
|
+
|
|
59
|
+
There are no runtime dependencies. Installation uses pip and setuptools as build tooling.
|
|
60
|
+
|
|
61
|
+
## Install from PyPI
|
|
62
|
+
|
|
63
|
+
Once the first PyPI release is published, install EnvLatch in your virtual environment:
|
|
64
|
+
|
|
65
|
+
~~~sh
|
|
66
|
+
python -m pip install envlatch
|
|
67
|
+
envlatch --version
|
|
68
|
+
~~~
|
|
69
|
+
|
|
70
|
+
To upgrade, run `python -m pip install --upgrade envlatch`. The package installs the `envlatch` command and `python -m envlatch`; it does not create your configuration files. In your application, create `.env.example` with the expected keys and a local `.env`, then run `envlatch --template .env.example --env .env`. Clone this repository or download its source archive to use the committed examples below.
|
|
71
|
+
|
|
72
|
+
## Install from source
|
|
73
|
+
|
|
74
|
+
~~~sh
|
|
75
|
+
git clone https://github.com/sinzbtw/envlatch.git
|
|
76
|
+
cd envlatch
|
|
77
|
+
python -m venv .venv
|
|
78
|
+
~~~
|
|
79
|
+
|
|
80
|
+
Activate the virtual environment:
|
|
81
|
+
|
|
82
|
+
~~~powershell
|
|
83
|
+
# Windows PowerShell
|
|
84
|
+
.\.venv\Scripts\Activate.ps1
|
|
85
|
+
~~~
|
|
86
|
+
|
|
87
|
+
~~~sh
|
|
88
|
+
# Linux / macOS
|
|
89
|
+
source .venv/bin/activate
|
|
90
|
+
~~~
|
|
91
|
+
|
|
92
|
+
Then install the checked-out project:
|
|
93
|
+
|
|
94
|
+
~~~sh
|
|
95
|
+
python -m pip install .
|
|
96
|
+
envlatch --version
|
|
97
|
+
~~~
|
|
98
|
+
|
|
99
|
+
If your system uses `python3` instead of `python`, substitute it when creating the virtual environment. EnvLatch is installed from this repository; these instructions do not require a PyPI release.
|
|
100
|
+
|
|
101
|
+
## Quick start
|
|
102
|
+
|
|
103
|
+
The repository includes this `.env.example`:
|
|
104
|
+
|
|
105
|
+
~~~dotenv
|
|
106
|
+
DATABASE_URL=postgresql://localhost/app
|
|
107
|
+
API_TOKEN=replace-me
|
|
108
|
+
PORT=8000
|
|
109
|
+
~~~
|
|
110
|
+
|
|
111
|
+
Create your local configuration and replace the example values as needed:
|
|
112
|
+
|
|
113
|
+
~~~powershell
|
|
114
|
+
# Windows PowerShell
|
|
115
|
+
Copy-Item .env.example .env
|
|
116
|
+
~~~
|
|
117
|
+
|
|
118
|
+
~~~sh
|
|
119
|
+
# Linux / macOS
|
|
120
|
+
cp .env.example .env
|
|
121
|
+
~~~
|
|
122
|
+
|
|
123
|
+
Validate it:
|
|
124
|
+
|
|
125
|
+
~~~sh
|
|
126
|
+
envlatch --template .env.example --env .env
|
|
127
|
+
~~~
|
|
128
|
+
|
|
129
|
+
The module entry point works too:
|
|
130
|
+
|
|
131
|
+
~~~sh
|
|
132
|
+
python -m envlatch --template .env.example --env .env
|
|
133
|
+
~~~
|
|
134
|
+
|
|
135
|
+
A template path and at least one environment file path are required, supplied directly or through `--config`. Template values are illustrative and are **not** defaults: even a key with an empty template value requires a nonblank value in `.env`, unless it is explicitly marked optional. A value such as `replace-me` passes the presence check; replace placeholders with usable configuration yourself.
|
|
136
|
+
|
|
137
|
+
Commit `.env.example`, but keep real environment files local. The included `.gitignore` excludes `.env` and local environment variants.
|
|
138
|
+
|
|
139
|
+
## Examples
|
|
140
|
+
|
|
141
|
+
Require an exact set of keys, useful in automated checks:
|
|
142
|
+
|
|
143
|
+
~~~sh
|
|
144
|
+
envlatch --template .env.example --env .env --strict
|
|
145
|
+
~~~
|
|
146
|
+
|
|
147
|
+
Check files outside the current directory:
|
|
148
|
+
|
|
149
|
+
~~~sh
|
|
150
|
+
envlatch --template config/service.env.example --env config/service.env
|
|
151
|
+
~~~
|
|
152
|
+
|
|
153
|
+
If `.env` omits `API_TOKEN`, leaves `DATABASE_URL` blank, and adds `DEBUG`, EnvLatch reports two errors and one warning. The exit code is `1`. With `--strict`, the unexpected `DEBUG` key becomes a third error. Reports identify the keys without displaying their values.
|
|
154
|
+
|
|
155
|
+
See all CLI options:
|
|
156
|
+
|
|
157
|
+
~~~sh
|
|
158
|
+
envlatch --help
|
|
159
|
+
~~~
|
|
160
|
+
|
|
161
|
+
| Exit code | Meaning |
|
|
162
|
+
| --- | --- |
|
|
163
|
+
| `0` | No errors; warnings may be present. |
|
|
164
|
+
| `1` | Validation errors or invalid dotenv syntax. |
|
|
165
|
+
| `2` | Invalid CLI usage or check settings; unreadable files, invalid JSON config, or non-UTF-8 input. |
|
|
166
|
+
|
|
167
|
+
## Project configuration
|
|
168
|
+
|
|
169
|
+
Store paths and validation policy once, then run:
|
|
170
|
+
|
|
171
|
+
~~~sh
|
|
172
|
+
envlatch --config envlatch.json
|
|
173
|
+
~~~
|
|
174
|
+
|
|
175
|
+
The committed [envlatch.json](https://github.com/sinzbtw/envlatch/blob/main/envlatch.json) checks your local `.env` against `.env.example` in strict mode. Create your local `.env` as described in Quick start. A configuration can use these fields:
|
|
176
|
+
|
|
177
|
+
~~~json
|
|
178
|
+
{
|
|
179
|
+
"template": ".env.example",
|
|
180
|
+
"env": [".env", ".env.local"],
|
|
181
|
+
"strict": true,
|
|
182
|
+
"optional": ["PORT"],
|
|
183
|
+
"allow_extra": ["CI_*"],
|
|
184
|
+
"types": {"DATABASE_URL": "url", "API_TOKEN": "string", "PORT": "port"},
|
|
185
|
+
"format": "text"
|
|
186
|
+
}
|
|
187
|
+
~~~
|
|
188
|
+
|
|
189
|
+
The second environment file in this example must exist; omit it if you do not use an overlay. Configuration stores paths, key names and patterns, not dotenv values. Keep real secrets in local environment files.
|
|
190
|
+
|
|
191
|
+
| Field | Type | Default |
|
|
192
|
+
| --- | --- | --- |
|
|
193
|
+
| `template` | Nonempty path string | Required through config or CLI |
|
|
194
|
+
| `env` | Nonempty array of path strings, in overlay order | Required through config or CLI |
|
|
195
|
+
| `strict` | Boolean | `false` |
|
|
196
|
+
| `optional` | Array of key names | `[]` |
|
|
197
|
+
| `allow_extra` | Array of allowance patterns | `[]` |
|
|
198
|
+
| `types` | Object mapping template key names to type names | `{}` (disabled) |
|
|
199
|
+
| `format` | `text`, `json`, or `github` | `text` |
|
|
200
|
+
|
|
201
|
+
Settings are loaded only when `--config` is supplied. UTF-8, BOM and CRLF are supported; use standard JSON without comments. Unknown fields, duplicate fields, invalid types, blank entries and invalid Unicode are rejected. Paths and strings are literal: shell commands, home shortcuts and environment references are not expanded or executed.
|
|
202
|
+
|
|
203
|
+
### Paths and overrides
|
|
204
|
+
|
|
205
|
+
- Paths inside JSON are resolved relative to the configuration file's directory, so the same configuration works from another working directory. These resolved paths appear as absolute paths in reports.
|
|
206
|
+
- Explicit CLI options override the corresponding configuration setting. CLI `--template` and `--env` paths stay relative to the current working directory.
|
|
207
|
+
- Supplying `--env` replaces the entire configured `env` array. Repeated CLI entries form the new overlay list in their given order.
|
|
208
|
+
- Supplying `--optional` or `--allow-extra` replaces that configured list; repeated flags form the replacement list. An empty array in JSON clears that setting.
|
|
209
|
+
- `--strict` enables strict mode; `--no-strict` disables it even if JSON enables it. These flags are mutually exclusive.
|
|
210
|
+
- `--format` overrides the configured output format. Existing commands without a config continue to work.
|
|
211
|
+
|
|
212
|
+
~~~sh
|
|
213
|
+
envlatch --config envlatch.json --env .env.production --format json
|
|
214
|
+
envlatch --config envlatch.json --no-strict
|
|
215
|
+
~~~
|
|
216
|
+
|
|
217
|
+
For a self-contained example using committed, invented environment values:
|
|
218
|
+
|
|
219
|
+
~~~sh
|
|
220
|
+
envlatch --config examples/config/envlatch.json --format json
|
|
221
|
+
~~~
|
|
222
|
+
|
|
223
|
+
An unreadable or invalid configuration produces exit code `2` without echoing its contents. If the configuration cannot be loaded, output defaults to a text error on standard error; pass `--format json` or `--format github` explicitly to choose structured errors before loading. Missing required paths and invalid CLI arguments remain normal usage errors. JSON structure and types are checked even for fields overridden by CLI. The report's JSON schema remains version `1`.
|
|
224
|
+
|
|
225
|
+
## Optional type checks
|
|
226
|
+
|
|
227
|
+
Add `types` to your JSON configuration to check selected variables. Keys are case-sensitive; type names are lowercase `string`, `integer`, `boolean`, `url`, and `port`:
|
|
228
|
+
|
|
229
|
+
~~~json
|
|
230
|
+
{
|
|
231
|
+
"template": "template.env.example",
|
|
232
|
+
"env": ["development.env"],
|
|
233
|
+
"optional": ["METRICS_PORT"],
|
|
234
|
+
"types": {
|
|
235
|
+
"APP_NAME": "string",
|
|
236
|
+
"WORKERS": "integer",
|
|
237
|
+
"DEBUG": "boolean",
|
|
238
|
+
"DATABASE_URL": "url",
|
|
239
|
+
"PORT": "port",
|
|
240
|
+
"METRICS_PORT": "port"
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
~~~
|
|
244
|
+
|
|
245
|
+
Try the complete [type-checking example](https://github.com/sinzbtw/envlatch/blob/main/examples/types/envlatch.json), including its template and invented environment values:
|
|
246
|
+
|
|
247
|
+
~~~sh
|
|
248
|
+
envlatch --config examples/types/envlatch.json --format json
|
|
249
|
+
~~~
|
|
250
|
+
|
|
251
|
+
| Type | Accepted nonblank values |
|
|
252
|
+
| --- | --- |
|
|
253
|
+
| `string` | Any literal text accepted by the dotenv parser. No further restriction. |
|
|
254
|
+
| `integer` | ASCII decimal digits with an optional leading `+` or `-`, e.g. `0`, `-42`, `+7`. Leading zeroes and arbitrarily large integers are allowed; decimals, exponents and underscores are rejected. |
|
|
255
|
+
| `boolean` | `true` or `false` in any letter case, or exactly `1` or `0`. `yes`, `no`, `on` and `off` are rejected. |
|
|
256
|
+
| `url` | An absolute network URL `scheme://host` with optional credentials, port, path, query and fragment. Schemes start with an ASCII letter and contain letters, digits, `+`, `-` or `.`; examples include `https`, `postgresql` and `redis`. Hosts can be DNS-style names (including localhost and IDNA international names), valid dotted IPv4 or bracketed IPv6. A supplied port must follow the `port` rule. Whitespace, control characters, backslashes, unsafe delimiters and malformed `%HH` escapes are rejected. Relative URLs, `mailto:` and hostless `file:` URLs are unsupported. |
|
|
257
|
+
| `port` | ASCII decimal digits representing **1–65535**, inclusive. Leading zeroes are allowed; signs, zero and fractions are rejected. |
|
|
258
|
+
|
|
259
|
+
- Type checking is opt-in. Omitting `types` or setting it to `{}` preserves v0.5.0 behavior; unlisted keys keep only the existing checks. There is no type inference or new CLI type flag.
|
|
260
|
+
- Checks use literal dotenv values after removing surrounding quotes and unquoted comments. Unquoted outer whitespace is trimmed; whitespace inside quotes stays literal. Escapes, dollar references and shell commands are not decoded or expanded. Values are never converted into application settings.
|
|
261
|
+
- A missing or blank required variable keeps its usual `missing_key` or `empty_value` error, without an additional type error. Optional keys may still be absent or blank; a nonblank optional value must match its configured type. Template values are not type-checked and are never defaults.
|
|
262
|
+
- Only the final winning value after overlays is type-checked; errors point to that definition's file and line. Syntax and duplicate-key errors in every input file remain errors. Strict mode and extra-key allowances do not disable type checks.
|
|
263
|
+
- A mismatch produces `invalid_type` and exit code `1` in all three output formats. Diagnostics contain only the key, expected type and source location. Parsed metadata and reports retain no values; URL credentials and raw validator exception messages are never printed. No network requests are made.
|
|
264
|
+
- Typed names must exist in the template. An unknown name produces `unknown_type_key` and exit code `1`; extra-key allowances cannot declare it. Invalid rule structure, key syntax or unsupported type names produce a safe input error and exit code `2`. Duplicate JSON rules are rejected too.
|
|
265
|
+
- CLI path overrides keep the configured type rules. Existing exit codes, required-key counts and JSON report schema `1` are unchanged.
|
|
266
|
+
|
|
267
|
+
Python callers can use `check(template, environment, types={"PORT": "port", "DEBUG": "boolean"})`, together with existing `optional_keys`, `allow_extra` and `strict` arguments.
|
|
268
|
+
|
|
269
|
+
## Optional keys
|
|
270
|
+
|
|
271
|
+
Some settings enable integrations that are deliberately absent in local development. Repeat `--optional KEY` to allow a declared template key to be missing or blank while keeping other keys required:
|
|
272
|
+
|
|
273
|
+
~~~sh
|
|
274
|
+
envlatch --template examples/optional/.env.example --env .env --optional SENTRY_DSN --optional LOG_LEVEL --strict
|
|
275
|
+
~~~
|
|
276
|
+
|
|
277
|
+
The committed [optional-key example](https://github.com/sinzbtw/envlatch/blob/main/examples/optional/.env.example) declares the usual `DATABASE_URL`, `API_TOKEN`, and `PORT`, plus `SENTRY_DSN` and `LOG_LEVEL`. This self-contained command checks the example without creating local configuration:
|
|
278
|
+
|
|
279
|
+
~~~sh
|
|
280
|
+
envlatch --template examples/optional/.env.example --env .env.example --optional SENTRY_DSN --optional LOG_LEVEL --strict --format json
|
|
281
|
+
~~~
|
|
282
|
+
|
|
283
|
+
- Optional names must exist in the template, with matching case. A typo produces `unknown_optional_key` and exit code `1`, even if that key exists in the environment file.
|
|
284
|
+
- Invalid optional names produce exit code `2`; names use the same ASCII grammar as dotenv keys.
|
|
285
|
+
- Optional keys may be absent, blank, or nonblank. Syntax and duplicate-key checks still apply.
|
|
286
|
+
- `--strict` rejects keys outside the template unless explicitly permitted by `--allow-extra`. Optional keys remain declared settings and do not automatically allow unrelated extra keys.
|
|
287
|
+
- The policy applies to the final merged configuration, so a blank overlay is allowed for an optional key.
|
|
288
|
+
- `checked_keys` in JSON and the text summary count required keys only. JSON schema version remains `1`.
|
|
289
|
+
|
|
290
|
+
Without `--optional`, every template key remains required. Python callers can pass `optional_keys=["SENTRY_DSN", "LOG_LEVEL"]` to `check()`.
|
|
291
|
+
|
|
292
|
+
## Allowed extra keys
|
|
293
|
+
|
|
294
|
+
Shared environment files sometimes contain tool settings that are intentionally outside an application's contract. Repeat `--allow-extra PATTERN` to allow exact names or simple wildcard patterns without weakening other checks:
|
|
295
|
+
|
|
296
|
+
~~~sh
|
|
297
|
+
envlatch --template .env.example --env .env --strict --allow-extra DEBUG --allow-extra 'CI_*'
|
|
298
|
+
~~~
|
|
299
|
+
|
|
300
|
+
The committed [development environment example](https://github.com/sinzbtw/envlatch/blob/main/examples/allow-extra/development.env) contains the three usual application keys plus `DEBUG` and `TOOL_CACHE_DIR`. Try it directly:
|
|
301
|
+
|
|
302
|
+
~~~sh
|
|
303
|
+
envlatch --template .env.example --env examples/allow-extra/development.env --strict --allow-extra DEBUG --allow-extra 'TOOL_*' --format json
|
|
304
|
+
~~~
|
|
305
|
+
|
|
306
|
+
- Patterns are case-sensitive on every OS. `*` matches zero or more characters; `?` matches one character. Quote wildcard patterns so your shell passes them unchanged.
|
|
307
|
+
- Patterns accept ASCII letters, digits, underscores, `*`, and `?` only. Empty patterns and unsupported syntax such as character classes produce an input error (exit code `2`).
|
|
308
|
+
- Matching extra keys produce neither warnings nor errors, with or without `--strict`. Unmatched extra keys keep their normal warning/error behavior. An unused pattern is allowed.
|
|
309
|
+
- An allowance applies only to keys absent from the template. It never makes a required key optional or permits its value to be blank. Even `--allow-extra '*'` preserves required-key checks.
|
|
310
|
+
- Syntax, duplicate-key, file-reading, and optional-key configuration errors remain errors. Overlay order and source locations are preserved.
|
|
311
|
+
- The option works with text, JSON, and GitHub Actions output. JSON schema version `1` and `checked_keys` remain unchanged.
|
|
312
|
+
|
|
313
|
+
Python callers can use `check(template, environment, strict=True, allow_extra=["DEBUG", "CI_*"])`. To make a declared key optional instead, use `--optional KEY`.
|
|
314
|
+
|
|
315
|
+
## Layered environment files
|
|
316
|
+
|
|
317
|
+
Repeat `--env` to validate a shared base configuration with local or deployment overrides:
|
|
318
|
+
|
|
319
|
+
~~~sh
|
|
320
|
+
envlatch --template .env.example --env .env --env .env.local --strict
|
|
321
|
+
~~~
|
|
322
|
+
|
|
323
|
+
Files are applied in command-line order: a later file overrides the same key from an earlier file. Required keys may be spread across files; EnvLatch checks the combined effective configuration. A blank value in a later file overrides an earlier nonblank value and fails validation when the key is required.
|
|
324
|
+
|
|
325
|
+
For example, if `.env` defines `DATABASE_URL` and `API_TOKEN`, and `.env.local` defines `PORT`, the combined configuration satisfies the three-key template. If `.env.local` also contains `API_TOKEN=`, the required token is reported as blank.
|
|
326
|
+
|
|
327
|
+
Duplicate keys within a single file and syntax errors in any input file remain errors, even when a later file overrides the affected key. Diagnostics for effective keys point to the winning definition; missing-key diagnostics refer to the last environment file. JSON reports list `environments` in the exact input order, including on file input errors.
|
|
328
|
+
|
|
329
|
+
The single-file commands above continue to work. These layers are used only for validation; EnvLatch does not modify your process environment.
|
|
330
|
+
|
|
331
|
+
## JSON reports
|
|
332
|
+
|
|
333
|
+
Request a machine-readable report for scripts or CI:
|
|
334
|
+
|
|
335
|
+
~~~sh
|
|
336
|
+
envlatch --template .env.example --env .env --format json
|
|
337
|
+
~~~
|
|
338
|
+
|
|
339
|
+
A successful check of the three-key example produces this JSON structure:
|
|
340
|
+
|
|
341
|
+
~~~json
|
|
342
|
+
{
|
|
343
|
+
"schema_version": 1,
|
|
344
|
+
"status": "pass",
|
|
345
|
+
"template": ".env.example",
|
|
346
|
+
"environments": [".env"],
|
|
347
|
+
"checked_keys": 3,
|
|
348
|
+
"errors": 0,
|
|
349
|
+
"warnings": 0,
|
|
350
|
+
"issues": []
|
|
351
|
+
}
|
|
352
|
+
~~~
|
|
353
|
+
|
|
354
|
+
JSON is deterministic and written to standard output for completed checks and file or configuration input errors. `status` is `pass`, `fail`, or `input_error`. Each issue contains `severity`, `code`, `path`, `message`, `line`, and `key`; `line` and `key` may be `null` when unavailable. Reports never contain environment values.
|
|
355
|
+
|
|
356
|
+
Exit codes remain `0`, `1`, and `2` as listed above. Invalid CLI arguments still produce human-readable usage errors on standard error, even when `--format json` is requested.
|
|
357
|
+
|
|
358
|
+
## GitHub Actions annotations
|
|
359
|
+
|
|
360
|
+
Use `--format github` to turn errors and warnings into native [GitHub Actions annotations](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-an-error-message). After installing EnvLatch and preparing the environment file, add a workflow step:
|
|
361
|
+
|
|
362
|
+
~~~yaml
|
|
363
|
+
- name: Validate environment configuration
|
|
364
|
+
run: envlatch --template .env.example --env .env --strict --format github
|
|
365
|
+
~~~
|
|
366
|
+
|
|
367
|
+
An empty required value produces a workflow command such as:
|
|
368
|
+
|
|
369
|
+
~~~text
|
|
370
|
+
::error title=EnvLatch%3A empty_value,file=.env,line=2::Required key 'TOKEN' is blank.
|
|
371
|
+
~~~
|
|
372
|
+
|
|
373
|
+
- Each diagnostic becomes an `error` or `warning` annotation, with its code in the title and its file/line when available. Missing-key diagnostics have no known line; input errors become general error annotations.
|
|
374
|
+
- A normal PASS/FAIL summary follows the annotations. Successful checks without diagnostics print only that summary.
|
|
375
|
+
- Exit codes stay `0` for success or warnings, `1` for validation errors, and `2` for input/configuration errors. Invalid CLI usage still prints a normal message to standard error.
|
|
376
|
+
- Values and raw dotenv lines remain absent. Command delimiters and line breaks in filenames/messages are escaped so a diagnostic cannot inject another workflow command.
|
|
377
|
+
- Use repository-relative paths for source navigation. GitHub can link to a file present in the repository; local or generated `.env` files still get annotations but may have no source link. Keep real secrets out of Git.
|
|
378
|
+
- The format works with `--optional`, `--allow-extra`, repeated `--env`, and `--strict`. Outside Actions, the workflow commands appear as ordinary text. The default text and JSON formats are unchanged.
|
|
379
|
+
|
|
380
|
+
## Supported dotenv syntax
|
|
381
|
+
|
|
382
|
+
EnvLatch deliberately supports a constrained, single-line dotenv format:
|
|
383
|
+
|
|
384
|
+
~~~dotenv
|
|
385
|
+
# A comment
|
|
386
|
+
APP_NAME = envlatch
|
|
387
|
+
export PORT=8000
|
|
388
|
+
EMPTY=
|
|
389
|
+
MESSAGE="A value containing # a hash"
|
|
390
|
+
LABEL='A literal value'
|
|
391
|
+
HOST=localhost # An inline comment
|
|
392
|
+
FRAGMENT=https://example.invalid/#section
|
|
393
|
+
REFERENCE=$OTHER_VARIABLE
|
|
394
|
+
~~~
|
|
395
|
+
|
|
396
|
+
- Keys match `[A-Za-z_][A-Za-z0-9_]*`; matching is case-sensitive.
|
|
397
|
+
- Spaces around a key, `=`, and an unquoted value are allowed.
|
|
398
|
+
- Blank lines, comments, and the optional `export` prefix are accepted.
|
|
399
|
+
- In unquoted values, `#` starts a comment at the beginning of the value or after whitespace. Otherwise it is part of the value.
|
|
400
|
+
- Single- and double-quoted values can contain `#`. Double-quoted values support escaped double quotes.
|
|
401
|
+
- After a closing quote, only whitespace and a comment are allowed.
|
|
402
|
+
- Dollar references are literal text, with no expansion or shell execution.
|
|
403
|
+
- Quoted multiline values, NUL characters, invalid keys, missing `=`, and duplicate keys are rejected.
|
|
404
|
+
- Required keys with empty or whitespace-only environment values fail the nonblank check.
|
|
405
|
+
|
|
406
|
+
Parsing stops at the first malformed statement in each file, so rejected multiline content cannot become a reported key. Duplicate assignments are reported separately, and later files are still checked.
|
|
407
|
+
|
|
408
|
+
The same parser checks the template and every environment file. Use a dedicated dotenv template, not a shell script.
|
|
409
|
+
|
|
410
|
+
## Development
|
|
411
|
+
|
|
412
|
+
Install an editable checkout in your virtual environment:
|
|
413
|
+
|
|
414
|
+
~~~sh
|
|
415
|
+
python -m pip install -e .
|
|
416
|
+
python -m unittest discover -s tests -v
|
|
417
|
+
~~~
|
|
418
|
+
|
|
419
|
+
The package lives in `src/envlatch/`; tests live in `tests/`. The runtime uses only the Python standard library. GitHub Actions runs the test suite on Linux with Python 3.10 and 3.13, and on Windows with Python 3.13.
|
|
420
|
+
|
|
421
|
+
For a bug report, include your command, Python version, and a minimal example using invented values. Keep both README language versions in sync when changing behavior.
|
|
422
|
+
|
|
423
|
+
GitHub Releases distribute tagged source archives only. Wheels and sdists are uploaded to PyPI, not GitHub Release assets.
|
|
424
|
+
|
|
425
|
+
PyPI uploads use GitHub Actions Trusted Publishing after validation, without a stored PyPI token. Maintainers: see [Publishing](https://github.com/sinzbtw/envlatch/blob/main/PUBLISHING.md) for the one-time setup, automated release checks and recovery instructions.
|
|
426
|
+
|
|
427
|
+
## Community
|
|
428
|
+
|
|
429
|
+
Contributions in English or Russian are welcome. See [Contributing](https://github.com/sinzbtw/envlatch/blob/main/CONTRIBUTING.md), the [Code of Conduct](https://github.com/sinzbtw/envlatch/blob/main/CODE_OF_CONDUCT.md), and the [Security Policy](https://github.com/sinzbtw/envlatch/blob/main/SECURITY.md). Use the [issue forms](https://github.com/sinzbtw/envlatch/issues/new/choose) for ordinary bugs and feature requests; report suspected vulnerabilities privately through the security policy.
|
|
430
|
+
|
|
431
|
+
## License
|
|
432
|
+
|
|
433
|
+
[MIT](https://github.com/sinzbtw/envlatch/blob/main/LICENSE) © 2026 EnvLatch contributors.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
envlatch/__init__.py,sha256=BZAV_bWO5doGy9BgbuId9UbvJZ-Ezk_VRpbTOcCvebg,201
|
|
2
|
+
envlatch/__main__.py,sha256=4SiW4HXGewwTUxgvz9ckg7CbNG4g1k8MMxLhMkzjh9Y,93
|
|
3
|
+
envlatch/_types.py,sha256=uRvbpbM9NeIno2dV682XuzoJf6UgjHByVpDfhw5CMC0,2895
|
|
4
|
+
envlatch/cli.py,sha256=mjuy19VEe_zImHpVu8TDMqWEsqD37Om1U3EQpnOIUX4,5740
|
|
5
|
+
envlatch/config.py,sha256=_5mPTW0yUYa44E_MP2WhtmkQ1NbmT4gOj32WDCXod9k,4144
|
|
6
|
+
envlatch/core.py,sha256=4aB9zbnhqXbdYCAR6j0aPo4S_iKqeGmTFFiMY9AaEuo,10137
|
|
7
|
+
envlatch-0.6.1.dist-info/licenses/LICENSE,sha256=zCxK-zIQINZVQz4AcmVQf2nxHEi1OJnxTrdcP2_76Uc,1064
|
|
8
|
+
envlatch-0.6.1.dist-info/METADATA,sha256=d2Y9CpyMC1rlvR5PBavCE1N4uUrnLwwxBAhKIO_-vOs,23944
|
|
9
|
+
envlatch-0.6.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
10
|
+
envlatch-0.6.1.dist-info/entry_points.txt,sha256=9cvtEvMMrWw1McnlHDmbHs5gCgOlgYrZvothxIg6mpg,47
|
|
11
|
+
envlatch-0.6.1.dist-info/top_level.txt,sha256=FzoFDKGoaP1T9n9jRzMfbW27h9FVCyjJyB5e6YkXuzw,9
|
|
12
|
+
envlatch-0.6.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 sinzbtw
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
envlatch
|