pydantic-env-manager 0.1.0__tar.gz

pydantic_env_manager-0.1.0/.gitignore

@@ -0,0 +1,223 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local scratch directory
+.local/

pydantic_env_manager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yashu Ranparia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydantic_env_manager-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: pydantic-env-manager
+Version: 0.1.0
+Summary: Manage .env and .env.example for FastAPI/Pydantic apps: declare variables once in your Settings class; files stay complete and agents can check them without reading secrets.
+Project-URL: Homepage, https://github.com/YashuRanparia/pydantic-env-manager
+Project-URL: Issues, https://github.com/YashuRanparia/pydantic-env-manager/issues
+Author: Yashu Ranparia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,dotenv,env,fastapi,pydantic,pydantic-settings,settings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic-settings>=2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pydantic-env-manager
+
+**Stop hand-editing `.env.example`. Your `Settings` class already knows every variable. Let it write the files.**
+
+```bash
+pip install pydantic-env-manager
+pydantic-env-manager sync app.settings:Settings
+```
+
+That's the whole setup. Declare each variable once, in your Pydantic v2 `BaseSettings` class, and `.env.example` and `.env` follow.
+
+## Sound familiar?
+
+- A teammate adds `STRIPE_WEBHOOK_SECRET` to the code and forgets `.env.example`. You find out when staging crashes.
+- A new hire clones the repo, copies `.env.example`, and spends an hour finding which variables are missing.
+- `.env.example` says `PORT=3000`. The code says `8000`. Nobody knows which is right.
+- You don't want a tool that rewrites your `.env` and wipes the values you tuned.
+
+`pydantic-env-manager` fixes this, and it's safe to run on a real project.
+
+## What you get
+
+| File | What happens |
+|---|---|
+| `.env.example` | Regenerated from `Settings` on every run, with type, default and required-ness for each variable. It never holds a secret. |
+| `.env` | Merge-only. Missing keys are appended. Your values, comments and order stay exactly as you left them. Nothing is deleted. |
+
+## See it work
+
+```python
+# app/settings.py
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="APP_", env_file=".env")
+
+    port: int = Field(8000, description="HTTP port")
+    debug: bool = False
+    api_key: SecretStr  # required, no default
+```
+
+```bash
+pydantic-env-manager sync  app.settings:Settings   # write .env.example, merge missing keys into .env
+pydantic-env-manager check app.settings:Settings   # write nothing; exit 1 if files have drifted (CI-friendly)
+```
+
+Your generated `.env.example`:
+
+```
+# APP_PORT (int, default: 8000) - HTTP port
+APP_PORT=8000
+
+# APP_DEBUG (bool, default: false)
+APP_DEBUG=false
+
+# APP_API_KEY (SecretStr, secret, required)
+APP_API_KEY=
+```
+
+Your existing `.env` keeps `APP_PORT=9000` and every comment you wrote. Only the keys it was missing are added.
+
+## Why you can trust it with your `.env`
+
+- **Your `.env` is never overwritten.** Existing values, comments and order are preserved. Unrecognised keys are kept too.
+- **Secrets are never written.** `SecretStr` and `SecretBytes` values stay blank in every file.
+- **Running it twice changes nothing.** Unchanged files aren't rewritten, and writes are atomic, so a crash can't leave a half-written file.
+- **One dependency.** It needs only `pydantic-settings`. The CLI uses the standard library.
+
+## Catch drift before it ships
+
+`check` writes nothing and exits `1` if `.env.example` is stale or `.env` is missing keys. Add it to CI and a forgotten variable fails the build instead of production:
+
+```bash
+pydantic-env-manager check app.settings:Settings
+```
+
+It also works as a pre-commit hook. See the [usage guide](https://github.com/YashuRanparia/pydantic-env-manager/blob/main/docs/usage.md).
+
+## Prefer to stay in Python?
+
+```python
+from pydantic_env_manager import sync_env, check_env
+
+sync_env(Settings)    # SyncResult(example_changed, env_changed)
+check_env(Settings)   # CheckReport(problems, notes, missing)
+```
+
+For local dev, subclass `EnvManagedSettings` and set `env_sync_on_init = True`. Both files then sync whenever your settings load. It's opt-in and skipped when `CI` or `PROD` is set. If a write fails, it logs a warning and your app still starts.
+
+## Great with AI coding agents
+
+Deny your agent access to `.env` and point it at `.env.example`. That file always matches your code and lists every variable with its type, default and required-ness. It holds no secret values, so the agent gets the full picture and none of your credentials.
+
+## Try it in two minutes
+
+1. `pip install pydantic-env-manager`
+2. Run `pydantic-env-manager sync your_module:Settings`
+3. Open `.env.example` to see your variables. Your `.env` only gains missing keys; none of your existing values change.
+
+Requires Python ≥ 3.9 and `pydantic-settings` ≥ 2. Full details are in the [usage guide](https://github.com/YashuRanparia/pydantic-env-manager/blob/main/docs/usage.md).
+
+## License
+
+MIT

pydantic_env_manager-0.1.0/README.md

@@ -0,0 +1,106 @@
+# pydantic-env-manager
+
+**Stop hand-editing `.env.example`. Your `Settings` class already knows every variable. Let it write the files.**
+
+```bash
+pip install pydantic-env-manager
+pydantic-env-manager sync app.settings:Settings
+```
+
+That's the whole setup. Declare each variable once, in your Pydantic v2 `BaseSettings` class, and `.env.example` and `.env` follow.
+
+## Sound familiar?
+
+- A teammate adds `STRIPE_WEBHOOK_SECRET` to the code and forgets `.env.example`. You find out when staging crashes.
+- A new hire clones the repo, copies `.env.example`, and spends an hour finding which variables are missing.
+- `.env.example` says `PORT=3000`. The code says `8000`. Nobody knows which is right.
+- You don't want a tool that rewrites your `.env` and wipes the values you tuned.
+
+`pydantic-env-manager` fixes this, and it's safe to run on a real project.
+
+## What you get
+
+| File | What happens |
+|---|---|
+| `.env.example` | Regenerated from `Settings` on every run, with type, default and required-ness for each variable. It never holds a secret. |
+| `.env` | Merge-only. Missing keys are appended. Your values, comments and order stay exactly as you left them. Nothing is deleted. |
+
+## See it work
+
+```python
+# app/settings.py
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="APP_", env_file=".env")
+
+    port: int = Field(8000, description="HTTP port")
+    debug: bool = False
+    api_key: SecretStr  # required, no default
+```
+
+```bash
+pydantic-env-manager sync  app.settings:Settings   # write .env.example, merge missing keys into .env
+pydantic-env-manager check app.settings:Settings   # write nothing; exit 1 if files have drifted (CI-friendly)
+```
+
+Your generated `.env.example`:
+
+```
+# APP_PORT (int, default: 8000) - HTTP port
+APP_PORT=8000
+
+# APP_DEBUG (bool, default: false)
+APP_DEBUG=false
+
+# APP_API_KEY (SecretStr, secret, required)
+APP_API_KEY=
+```
+
+Your existing `.env` keeps `APP_PORT=9000` and every comment you wrote. Only the keys it was missing are added.
+
+## Why you can trust it with your `.env`
+
+- **Your `.env` is never overwritten.** Existing values, comments and order are preserved. Unrecognised keys are kept too.
+- **Secrets are never written.** `SecretStr` and `SecretBytes` values stay blank in every file.
+- **Running it twice changes nothing.** Unchanged files aren't rewritten, and writes are atomic, so a crash can't leave a half-written file.
+- **One dependency.** It needs only `pydantic-settings`. The CLI uses the standard library.
+
+## Catch drift before it ships
+
+`check` writes nothing and exits `1` if `.env.example` is stale or `.env` is missing keys. Add it to CI and a forgotten variable fails the build instead of production:
+
+```bash
+pydantic-env-manager check app.settings:Settings
+```
+
+It also works as a pre-commit hook. See the [usage guide](https://github.com/YashuRanparia/pydantic-env-manager/blob/main/docs/usage.md).
+
+## Prefer to stay in Python?
+
+```python
+from pydantic_env_manager import sync_env, check_env
+
+sync_env(Settings)    # SyncResult(example_changed, env_changed)
+check_env(Settings)   # CheckReport(problems, notes, missing)
+```
+
+For local dev, subclass `EnvManagedSettings` and set `env_sync_on_init = True`. Both files then sync whenever your settings load. It's opt-in and skipped when `CI` or `PROD` is set. If a write fails, it logs a warning and your app still starts.
+
+## Great with AI coding agents
+
+Deny your agent access to `.env` and point it at `.env.example`. That file always matches your code and lists every variable with its type, default and required-ness. It holds no secret values, so the agent gets the full picture and none of your credentials.
+
+## Try it in two minutes
+
+1. `pip install pydantic-env-manager`
+2. Run `pydantic-env-manager sync your_module:Settings`
+3. Open `.env.example` to see your variables. Your `.env` only gains missing keys; none of your existing values change.
+
+Requires Python ≥ 3.9 and `pydantic-settings` ≥ 2. Full details are in the [usage guide](https://github.com/YashuRanparia/pydantic-env-manager/blob/main/docs/usage.md).
+
+## License
+
+MIT

pydantic_env_manager-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pydantic-env-manager"
+version = "0.1.0"
+description = "Manage .env and .env.example for FastAPI/Pydantic apps: declare variables once in your Settings class; files stay complete and agents can check them without reading secrets."
+readme = "README.md"
+keywords = ["pydantic", "pydantic-settings", "fastapi", "dotenv", "env", "settings", "cli"]
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Yashu Ranparia" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic-settings>=2"]
+
+[project.urls]
+Homepage = "https://github.com/YashuRanparia/pydantic-env-manager"
+Issues = "https://github.com/YashuRanparia/pydantic-env-manager/issues"
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[project.scripts]
+pydantic-env-manager = "pydantic_env_manager.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pydantic_env_manager"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

pydantic_env_manager-0.1.0/src/pydantic_env_manager/__init__.py

@@ -0,0 +1,4 @@
+from .sync import CheckReport, EnvManagedSettings, SyncResult, check_env, sync_env
+
+__version__ = "0.1.0"
+__all__ = ["CheckReport", "EnvManagedSettings", "SyncResult", "check_env", "sync_env"]

pydantic_env_manager-0.1.0/src/pydantic_env_manager/cli.py

@@ -0,0 +1,53 @@
+"""Command line interface: `pydantic-env-manager sync|check module:Class`."""
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import sys
+from typing import List, Optional
+
+from pydantic_settings import BaseSettings
+
+from .sync import check_env, sync_env
+
+
+def _load(target: str) -> type:
+    module, _, name = target.partition(":")
+    if not module or not name:
+        raise SystemExit(f"error: expected 'module:Class', got {target!r}")
+    sys.path.insert(0, os.getcwd())  # console scripts don't have cwd on sys.path
+    try:
+        cls = getattr(importlib.import_module(module), name)
+    except (ImportError, AttributeError) as exc:
+        raise SystemExit(f"error: cannot load {target}: {exc}")
+    if not (isinstance(cls, type) and issubclass(cls, BaseSettings)):
+        raise SystemExit(f"error: {target} is not a pydantic-settings BaseSettings subclass")
+    return cls
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="pydantic-env-manager", description=__doc__)
+    sub = p.add_subparsers(dest="command", required=True)
+    for name, help_ in (("sync", "write .env.example and merge into .env"), ("check", "exit 1 if files have drifted")):
+        s = sub.add_parser(name, help=help_)
+        s.add_argument("target", help="import path, e.g. app.settings:Settings")
+        s.add_argument("--env", help="default: the class's env_file, else .env")
+        s.add_argument("--example", help="default: .env.example next to the env file")
+    args = p.parse_args(argv)
+    cls = _load(args.target)
+
+    if args.command == "sync":
+        res = sync_env(cls, args.env, args.example)
+        print("updated" if any(res) else "already in sync")
+        return 0
+    report = check_env(cls, args.env, args.example)
+    for line in report.notes:
+        print(f"note: {line}")
+    for line in report.problems:
+        print(f"drift: {line}", file=sys.stderr)
+    return 1 if report.problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pydantic_env_manager-0.1.0/src/pydantic_env_manager/envfile.py

@@ -0,0 +1,110 @@
+"""Line-preserving merge of VarSpecs into an existing .env file."""
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Set, Tuple
+
+from .render import env_line
+from .schema import VarSpec
+
+EXTRAS_HEADING = "# Your additional env variables"
+_KEY = re.compile(r"^\s*(?:export\s+)?([A-Za-z_][\w.-]*)\s*=(.*)$", re.S)
+
+# item: (key or None, lines, leading_comment_lines)
+Item = Tuple[Optional[str], List[str], List[str]]
+
+
+def _closes(rest: str, quote: str) -> bool:
+    """True if `rest` contains the closing quote for a value that opened with `quote`."""
+    i = 0
+    while i < len(rest):
+        if quote == '"' and rest[i] == "\\":
+            i += 2
+            continue
+        if rest[i] == quote:
+            return True
+        i += 1
+    return False
+
+
+def _parse(text: str) -> List[Item]:
+    lines = re.findall(r"[^\n]*\n|[^\n]+", text)
+    items: List[Item] = []
+    comments: List[str] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        m = _KEY.match(line.rstrip("\r\n"))
+        if m:
+            chunk = [line]
+            value = m.group(2).lstrip()
+            if value[:1] in ("'", '"') and not _closes(value[1:], value[0]):
+                while i + 1 < len(lines):  # multi-line quoted value
+                    i += 1
+                    chunk.append(lines[i])
+                    if _closes(lines[i], value[0]):
+                        break
+            items.append((m.group(1), chunk, comments))
+            comments = []
+        elif line.lstrip().startswith("#"):
+            comments.append(line)
+        else:  # blank or unparseable: keep verbatim
+            items.append((None, comments + [line], []))
+            comments = []
+        i += 1
+    if comments:
+        items.append((None, comments, []))
+    return items
+
+
+def _norm(key: str, case_sensitive: bool) -> str:
+    return key if case_sensitive else key.upper()
+
+
+def keys_in(text: str, case_sensitive: bool = False) -> Set[str]:
+    return {_norm(k, case_sensitive) for k, _, _ in _parse(text) if k}
+
+
+def merge(text: str, specs: List[VarSpec], case_sensitive: bool = False) -> str:
+    """Append missing keys and move unknown keys under a trailing heading.
+
+    Existing values, comments and order of known keys are untouched.
+    """
+    eol = "\r\n" if "\r\n" in text else "\n"
+    known = {s.key for s in specs}
+    kept: List[str] = []
+    extras: List[str] = []
+    present: Set[str] = set()
+    for key, lines, comments in _parse(text):
+        if key is None:
+            kept += lines
+        elif _norm(key, case_sensitive) in known:
+            present.add(_norm(key, case_sensitive))
+            kept += comments + lines
+        else:
+            extras += [c for c in comments if c.strip() != EXTRAS_HEADING] + lines
+
+    def nl(lines: List[str]) -> List[str]:
+        return [x if x.endswith("\n") else x + eol for x in lines]
+
+    kept, extras = nl(kept), nl(extras)
+    missing = [s for s in specs if s.key not in present]
+    if not missing and not extras:
+        return text
+    while kept and not kept[-1].strip():  # trailing blanks are regenerated below
+        kept.pop()
+    out = kept
+    if missing:
+        block: List[str] = []
+        for s in missing:
+            block += ([f"# REQUIRED{eol}"] if s.required else []) + [env_line(s) + eol]
+        out += ([eol] if out else []) + block
+    if extras:
+        out += ([eol] if out else []) + [EXTRAS_HEADING + eol] + extras
+    return "".join(out)
+
+
+def missing_and_extra(text: str, specs: List[VarSpec], case_sensitive: bool = False) -> Tuple[List[str], List[str]]:
+    have = keys_in(text, case_sensitive)
+    known = {s.key for s in specs}
+    return [s.key for s in specs if s.key not in have], sorted(have - known)

pydantic_env_manager-0.1.0/src/pydantic_env_manager/render.py

@@ -0,0 +1,38 @@
+"""Render .env-style text from VarSpecs."""
+from __future__ import annotations
+
+import re
+from typing import List
+
+from .schema import VarSpec
+
+_PLAIN = re.compile(r"^[\w./:@%+,=-]*$")
+
+
+def quote(value: str) -> str:
+    """Quote a value only when .env parsers would otherwise misread it."""
+    if _PLAIN.match(value):
+        return value
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n") + '"'
+
+
+def env_line(spec: VarSpec) -> str:
+    return f"{spec.key}={quote(spec.default)}"
+
+
+def annotation(spec: VarSpec) -> str:
+    parts = [spec.type]
+    if spec.secret:
+        parts.append("secret")
+    if spec.required:
+        parts.append("required")
+    elif not spec.secret:
+        parts.append(f"default: {spec.default or None}")
+    text = f"# {spec.key} ({', '.join(parts)})"
+    return f"{text} - {spec.description}" if spec.description else text
+
+
+def render_example(specs: List[VarSpec], source: str, eol: str = "\n") -> str:
+    blocks = [f"# Generated by pydantic-env-manager from {source}. Do not edit by hand."]
+    blocks += [annotation(s) + eol + env_line(s) for s in specs]
+    return (eol + eol).join(blocks) + eol

pydantic_env_manager-0.1.0/src/pydantic_env_manager/schema.py

@@ -0,0 +1,75 @@
+"""Introspect a BaseSettings class into a flat list of env var specs."""
+from __future__ import annotations
+
+import enum
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, List, Optional, Type, get_args
+
+from pydantic import AliasChoices, AliasPath, SecretBytes, SecretStr
+from pydantic_settings import BaseSettings
+
+log = logging.getLogger(__name__)
+_SECRETS = (SecretStr, SecretBytes)
+
+
+@dataclass
+class VarSpec:
+    key: str
+    type: str
+    default: str  # rendered default; "" when none (or secret)
+    required: bool
+    secret: bool
+    description: str
+
+
+def resolve_key(cls: Type[BaseSettings], name: str, field: Any) -> Optional[str]:
+    """Env var name for a field, or None if it can't be expressed as one."""
+    cfg = cls.model_config
+    alias = field.validation_alias
+    if isinstance(alias, AliasChoices):
+        alias = alias.choices[0]
+    if isinstance(alias, AliasPath):
+        log.warning("skipping %s.%s: AliasPath is not supported", cls.__name__, name)
+        return None
+    # pydantic-settings does not apply env_prefix to aliased fields
+    key = alias if alias else (cfg.get("env_prefix") or "") + name
+    return key if cfg.get("case_sensitive") else key.upper()
+
+
+def _is_secret(annotation: Any) -> bool:
+    if isinstance(annotation, type) and issubclass(annotation, _SECRETS):
+        return True
+    return any(_is_secret(a) for a in get_args(annotation))
+
+
+def _type_name(annotation: Any) -> str:
+    if isinstance(annotation, type) and not get_args(annotation):
+        return annotation.__name__
+    return str(annotation).replace("typing.", "")
+
+
+def _render_default(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, enum.Enum):
+        value = value.value
+    if isinstance(value, bool):
+        return str(value).lower()
+    if isinstance(value, (list, tuple, set, dict)):
+        return json.dumps(sorted(value) if isinstance(value, set) else value, default=str)
+    return str(value)
+
+
+def collect(cls: Type[BaseSettings]) -> List[VarSpec]:
+    specs = []
+    for name, field in cls.model_fields.items():
+        key = resolve_key(cls, name, field)
+        if key is None:
+            continue
+        secret = _is_secret(field.annotation)
+        required = field.is_required()
+        default = "" if secret or required else _render_default(field.get_default(call_default_factory=True))
+        specs.append(VarSpec(key, _type_name(field.annotation), default, required, secret, field.description or ""))
+    return specs

pydantic_env_manager-0.1.0/src/pydantic_env_manager/sync.py

@@ -0,0 +1,128 @@
+"""Public API: sync_env, check_env and the EnvManagedSettings boot hook."""
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, ClassVar, List, NamedTuple, Optional, Tuple, Type, Union
+
+from pydantic_settings import BaseSettings
+
+from . import envfile
+from .render import render_example
+from .schema import collect
+
+log = logging.getLogger(__name__)
+PathLike = Union[str, "os.PathLike[str]"]
+
+
+class SyncResult(NamedTuple):
+    example_changed: bool
+    env_changed: bool
+
+
+class CheckReport(NamedTuple):
+    problems: List[str]  # fail the check
+    notes: List[str]  # informational only
+    missing: List[str]  # env keys declared in Settings but absent from .env
+
+
+def _paths(
+    cls: Type[BaseSettings], env_file: Optional[PathLike], example_file: Optional[PathLike]
+) -> Tuple[Path, Path]:
+    if env_file is None:
+        cfg = cls.model_config.get("env_file")
+        env_file = (cfg[0] if isinstance(cfg, (list, tuple)) else cfg) or ".env"
+    env_path = Path(env_file)
+    return env_path, Path(example_file) if example_file else env_path.with_name(".env.example")
+
+
+def _read(path: Path) -> Optional[str]:
+    if not path.exists():
+        return None
+    with open(path, encoding="utf-8", newline="") as f:
+        return f.read()
+
+
+def _write(path: Path, text: str, private: bool) -> bool:
+    """Atomically write `text`; returns False (and touches nothing) if unchanged."""
+    if _read(path) == text:
+        return False
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=path.name + ".")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as f:
+            f.write(text)
+        if path.exists():
+            os.chmod(tmp, path.stat().st_mode & 0o777)
+        elif not private:
+            os.chmod(tmp, 0o644)
+        os.replace(tmp, path)
+    except BaseException:
+        os.unlink(tmp)
+        raise
+    return True
+
+
+def _example_text(cls: Type[BaseSettings], example: Path) -> str:
+    old = _read(example) or ""
+    eol = "\r\n" if "\r\n" in old else "\n"
+    return render_example(collect(cls), f"{cls.__module__}.{cls.__qualname__}", eol)
+
+
+def sync_env(
+    cls: Type[BaseSettings], env_file: Optional[PathLike] = None, example_file: Optional[PathLike] = None
+) -> SyncResult:
+    """Regenerate .env.example and merge missing keys into .env."""
+    env, example = _paths(cls, env_file, example_file)
+    cs = bool(cls.model_config.get("case_sensitive"))
+    merged = envfile.merge(_read(env) or "", collect(cls), cs)
+    return SyncResult(
+        _write(example, _example_text(cls, example), private=False),
+        _write(env, merged, private=True),
+    )
+
+
+def check_env(
+    cls: Type[BaseSettings], env_file: Optional[PathLike] = None, example_file: Optional[PathLike] = None
+) -> CheckReport:
+    """Report drift without writing anything. A missing .env is skipped (e.g. in CI)."""
+    env, example = _paths(cls, env_file, example_file)
+    problems: List[str] = []
+    notes: List[str] = []
+    missing: List[str] = []
+    if _read(example) != _example_text(cls, example):
+        problems.append(f"{example} is out of date")
+    env_text = _read(env)
+    if env_text is None:
+        notes.append(f"{env} not found, skipped")
+    else:
+        missing, extra = envfile.missing_and_extra(
+            env_text, collect(cls), bool(cls.model_config.get("case_sensitive"))
+        )
+        if missing:
+            problems.append(f"{env} is missing: {', '.join(missing)}")
+        if extra:
+            notes.append(f"{env} has keys not in settings: {', '.join(extra)}")
+    return CheckReport(problems, notes, missing)
+
+
+def _skip_boot_sync() -> bool:
+    return any(os.environ.get(v, "").lower() not in ("", "0", "false") for v in ("CI", "PROD"))
+
+
+class EnvManagedSettings(BaseSettings):
+    """BaseSettings that syncs .env / .env.example on creation when `env_sync_on_init = True`.
+
+    Dev convenience only: skipped when CI or PROD is set; failures only warn.
+    """
+
+    env_sync_on_init: ClassVar[bool] = False
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        if type(self).env_sync_on_init and not _skip_boot_sync():
+            try:
+                sync_env(type(self))
+            except Exception as exc:  # never break the app over a dev convenience
+                log.warning("pydantic-env-manager: sync failed: %s", exc)

pydantic_env_manager-0.1.0/tests/test_pydantic_env_manager.py

@@ -0,0 +1,360 @@
+import logging
+from typing import ClassVar
+
+import pytest
+from pydantic import AliasChoices, AliasPath, Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from pydantic_env_manager import EnvManagedSettings, check_env, sync_env
+from pydantic_env_manager.cli import main
+from pydantic_env_manager.envfile import EXTRAS_HEADING, merge
+from pydantic_env_manager.schema import collect
+
+
+class S(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="APP_")
+    port: int = Field(8000, description="HTTP port")
+    debug: bool = False
+    name: str  # required
+    token: SecretStr = SecretStr("hunter2")
+    url: str = Field("x", validation_alias="DB_URL")  # alias bypasses prefix
+    multi: str = Field("a", validation_alias=AliasChoices("FIRST", "second"))
+    skipped: str = Field("a", validation_alias=AliasPath("a", 0))
+
+
+def by_key():
+    return {s.key: s for s in collect(S)}
+
+
+def test_key_resolution():
+    specs = by_key()
+    assert set(specs) == {"APP_PORT", "APP_DEBUG", "APP_NAME", "APP_TOKEN", "DB_URL", "FIRST"}
+
+
+def test_case_sensitive():
+    class C(BaseSettings):
+        model_config = SettingsConfigDict(case_sensitive=True)
+        Mixed: int = 1
+
+    assert [s.key for s in collect(C)] == ["Mixed"]
+
+
+def test_classvar_constants_are_not_env_vars():
+    class C(BaseSettings):
+        name: str = "x"
+        MAX_RETRIES: ClassVar[int] = 3
+
+    assert [s.key for s in collect(C)] == ["NAME"]
+    assert C().MAX_RETRIES == 3
+
+
+def test_spec_values():
+    s = by_key()
+    assert (s["APP_PORT"].default, s["APP_DEBUG"].default) == ("8000", "false")
+    assert s["APP_NAME"].required and s["APP_NAME"].default == ""
+    assert s["APP_TOKEN"].secret and s["APP_TOKEN"].default == ""  # secret never leaks
+
+
+def test_sync_creates_both_files(tmp_path):
+    env, ex = tmp_path / ".env", tmp_path / ".env.example"
+    assert sync_env(S, env, ex) == (True, True)
+    example = ex.read_text()
+    assert "# APP_PORT (int, default: 8000) - HTTP port\nAPP_PORT=8000" in example
+    assert "# APP_NAME (str, required)\nAPP_NAME=\n" in example
+    assert "hunter2" not in example + env.read_text()
+    assert "# REQUIRED\nAPP_NAME=\n" in env.read_text()
+
+
+def test_sync_is_idempotent(tmp_path):
+    env, ex = tmp_path / ".env", tmp_path / ".env.example"
+    sync_env(S, env, ex)
+    assert sync_env(S, env, ex) == (False, False)
+
+
+def test_env_merge_preserves_and_moves_extras(tmp_path):
+    env, ex = tmp_path / ".env", tmp_path / ".env.example"
+    env.write_text(
+        "# my port\nAPP_PORT=9000  # inline\nOTHER=1\n\n# keep me\nexport APP_NAME='bob'\n"
+        'MULTI="line1\nline2"\n# about extra\nEXTRA=2\n'
+    )
+    sync_env(S, env, ex)
+    out = env.read_text()
+    assert out.startswith("# my port\nAPP_PORT=9000  # inline\n")  # untouched, in order
+    assert "# keep me\nexport APP_NAME='bob'\n" in out
+    assert out.index("APP_DEBUG=false") < out.index(EXTRAS_HEADING)  # missing keys before extras
+    tail = out[out.index(EXTRAS_HEADING):]
+    assert tail == f'{EXTRAS_HEADING}\nOTHER=1\nMULTI="line1\nline2"\n# about extra\nEXTRA=2\n'
+    assert out.count(EXTRAS_HEADING) == 1
+    assert sync_env(S, env, ex).env_changed is False
+
+
+def test_merge_noop_returns_text_untouched():
+    text = "APP_PORT=1\n\n\n"
+    specs = [s for s in collect(S) if s.key == "APP_PORT"]
+    assert merge(text, specs) == text
+
+
+def test_merge_case_insensitive_and_crlf():
+    specs = [s for s in collect(S) if s.key in ("APP_PORT", "APP_DEBUG")]
+    out = merge("app_port=1\r\n", specs)
+    assert out == "app_port=1\r\n\r\nAPP_DEBUG=false\r\n"
+
+
+def test_no_trailing_newline():
+    specs = [s for s in collect(S) if s.key in ("APP_PORT", "APP_DEBUG")]
+    assert merge("APP_PORT=1", specs) == "APP_PORT=1\n\nAPP_DEBUG=false\n"
+
+
+def test_check(tmp_path):
+    env, ex = tmp_path / ".env", tmp_path / ".env.example"
+    assert check_env(S, env, ex).problems  # nothing generated yet
+    sync_env(S, env, ex)
+    assert check_env(S, env, ex).problems == []
+    env.write_text(env.read_text() + "STRAY=1\n")
+    r = check_env(S, env, ex)
+    assert r.problems == [] and "STRAY" in r.notes[0]  # extras never fail
+    env.write_text("APP_PORT=1\n")
+    r = check_env(S, env, ex)
+    assert "missing" in r.problems[0] and "APP_PORT" not in r.missing and "APP_NAME" in r.missing
+    ex.write_text("stale\n")
+    assert any("out of date" in p for p in check_env(S, env, ex).problems)
+
+
+def test_check_skips_absent_env(tmp_path):
+    ex = tmp_path / ".env.example"
+    sync_env(S, tmp_path / "tmp.env", ex)
+    assert check_env(S, tmp_path / ".env", ex).problems == []
+
+
+def test_check_does_not_write(tmp_path):
+    check_env(S, tmp_path / ".env", tmp_path / ".env.example")
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_cli(tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "cli_settings.py").write_text(
+        "from pydantic_settings import BaseSettings\nclass Settings(BaseSettings):\n    port: int = 1\n"
+    )
+    assert main(["check", "cli_settings:Settings"]) == 1
+    assert main(["sync", "cli_settings:Settings"]) == 0
+    assert main(["check", "cli_settings:Settings"]) == 0
+    assert (tmp_path / ".env").exists() and (tmp_path / ".env.example").exists()
+    with pytest.raises(SystemExit):
+        main(["check", "cli_settings:Nope"])
+
+
+def _boot_cls(tmp_path):
+    class B(EnvManagedSettings):
+        model_config = SettingsConfigDict(env_file=str(tmp_path / ".env"))
+        env_sync_on_init = True
+        port: int = 1
+
+    return B
+
+
+@pytest.fixture
+def clean_env(monkeypatch):
+    monkeypatch.delenv("CI", raising=False)
+    monkeypatch.delenv("PROD", raising=False)
+
+
+def test_boot_sync_writes(tmp_path, clean_env):
+    _boot_cls(tmp_path)()
+    assert (tmp_path / ".env").exists() and (tmp_path / ".env.example").exists()
+
+
+@pytest.mark.parametrize("var", ["CI", "PROD"])
+def test_boot_sync_skipped_in_ci_or_prod(tmp_path, clean_env, monkeypatch, var):
+    monkeypatch.setenv(var, "true")
+    _boot_cls(tmp_path)()
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_boot_sync_failure_only_warns(tmp_path, clean_env, caplog):
+    cls = _boot_cls(tmp_path / "missing_dir")
+    with caplog.at_level(logging.WARNING):
+        assert cls().port == 1  # app still starts
+    assert "sync failed" in caplog.text
+
+
+def test_boot_sync_off_by_default(tmp_path, clean_env):
+    class Off(EnvManagedSettings):
+        model_config = SettingsConfigDict(env_file=str(tmp_path / ".env"))
+
+    Off()
+    assert list(tmp_path.iterdir()) == []
+
+
+# --- edge cases ---------------------------------------------------------------
+
+
+def test_unchanged_files_not_rewritten(tmp_path):
+    env, ex = tmp_path / ".env", tmp_path / ".env.example"
+    sync_env(S, env, ex)
+    before = (env.stat().st_ino, env.stat().st_mtime_ns, ex.stat().st_ino, ex.stat().st_mtime_ns)
+    sync_env(S, env, ex)
+    assert before == (env.stat().st_ino, env.stat().st_mtime_ns, ex.stat().st_ino, ex.stat().st_mtime_ns)
+
+
+def test_write_is_atomic_on_failure(tmp_path, monkeypatch):
+    env, ex = tmp_path / ".env", tmp_path / ".env.example"
+    env.write_text("APP_PORT=1\n")
+    monkeypatch.setattr("pydantic_env_manager.sync.os.replace", lambda *a: (_ for _ in ()).throw(OSError("boom")))
+    with pytest.raises(OSError):
+        sync_env(S, env, ex)
+    assert env.read_text() == "APP_PORT=1\n"  # original intact
+    assert not ex.exists()
+    assert [p.name for p in tmp_path.iterdir()] == [".env"]  # no temp files left behind
+
+
+def test_no_temp_files_after_success(tmp_path):
+    sync_env(S, tmp_path / ".env", tmp_path / ".env.example")
+    assert sorted(p.name for p in tmp_path.iterdir()) == [".env", ".env.example"]
+
+
+def test_file_modes(tmp_path):
+    sync_env(S, tmp_path / ".env", tmp_path / ".env.example")
+    assert (tmp_path / ".env").stat().st_mode & 0o777 == 0o600
+    assert (tmp_path / ".env.example").stat().st_mode & 0o777 == 0o644
+
+
+def test_existing_env_mode_preserved(tmp_path):
+    env = tmp_path / ".env"
+    env.write_text("X=1\n")
+    env.chmod(0o640)
+    sync_env(S, env, tmp_path / ".env.example")
+    assert env.stat().st_mode & 0o777 == 0o640
+
+
+@pytest.mark.parametrize(
+    "default, expected",
+    [
+        ("plain", "plain"),
+        ("", ""),
+        ("has space", '"has space"'),
+        ("a#b", '"a#b"'),
+        ('say "hi"', '"say \\"hi\\""'),
+        ("back\\slash", '"back\\\\slash"'),
+        ("two\nlines", '"two\\nlines"'),
+        ("$HOME", '"$HOME"'),
+    ],
+)
+def test_quote(default, expected):
+    from pydantic_env_manager.render import quote
+
+    assert quote(default) == expected
+
+
+def test_special_char_defaults_in_example(tmp_path):
+    class Q(BaseSettings):
+        a: str = "has space # not a comment"
+        b: str = 'q"uote'
+
+    ex = tmp_path / ".env.example"
+    sync_env(Q, tmp_path / ".env", ex)
+    text = ex.read_text()
+    assert 'A="has space # not a comment"\n' in text
+    assert 'B="q\\"uote"\n' in text
+
+
+def test_assorted_field_types(tmp_path):
+    import enum
+    from typing import Dict, List, Optional
+
+    class Color(enum.Enum):
+        RED = "red"
+
+    class T(BaseSettings):
+        opt: Optional[str] = None
+        opt_req: Optional[int]
+        items: List[int] = [1, 2]
+        mapping: Dict[str, int] = {"a": 1}
+        color: Color = Color.RED
+        secret_req: SecretStr
+
+    specs = {s.key: s for s in collect(T)}
+    assert set(specs) == {"OPT", "OPT_REQ", "ITEMS", "MAPPING", "COLOR", "SECRET_REQ"}
+    assert specs["OPT"].default == ""
+    assert specs["OPT_REQ"].required
+    assert specs["SECRET_REQ"].required and specs["SECRET_REQ"].default == ""
+    ex = tmp_path / ".env.example"
+    sync_env(T, tmp_path / ".env", ex)
+    assert sync_env(T, tmp_path / ".env", ex) == (False, False)  # still idempotent
+
+
+def test_empty_settings_class(tmp_path):
+    class Empty(BaseSettings):
+        pass
+
+    assert collect(Empty) == []
+    assert sync_env(Empty, tmp_path / ".env", tmp_path / ".env.example") == (True, True)
+    assert sync_env(Empty, tmp_path / ".env", tmp_path / ".env.example") == (False, False)
+    assert check_env(Empty, tmp_path / ".env", tmp_path / ".env.example").problems == []
+
+
+def test_merge_empty_env():
+    specs = [s for s in collect(S) if s.key == "APP_PORT"]
+    assert merge("", specs) == "APP_PORT=8000\n"
+
+
+def test_merge_malformed_and_duplicate_lines_kept():
+    specs = [s for s in collect(S) if s.key == "APP_PORT"]
+    text = "garbage line\nAPP_PORT=1\nAPP_PORT=2\n=novalue\n"
+    out = merge(text, specs)
+    assert out == text  # nothing missing, nothing extra: byte-for-byte
+
+
+def test_merge_comment_stays_with_moved_extra():
+    specs = [s for s in collect(S) if s.key == "APP_PORT"]
+    out = merge("# about x\nX=1\nAPP_PORT=1\n", specs)
+    assert out == f"APP_PORT=1\n\n{EXTRAS_HEADING}\n# about x\nX=1\n"
+
+
+def test_merge_never_duplicates_existing_extras_heading():
+    specs = [s for s in collect(S) if s.key == "APP_PORT"]
+    first = merge("APP_PORT=1\nX=1\n", specs)
+    assert merge(first, specs) == first
+    assert first.count(EXTRAS_HEADING) == 1
+
+
+def test_merge_unterminated_quote_does_not_crash():
+    specs = [s for s in collect(S) if s.key == "APP_PORT"]
+    out = merge('BROKEN="never closed\nAPP_PORT=1\n', specs)
+    assert "APP_PORT=1" in out and "BROKEN" in out
+
+
+def test_merge_value_with_hash_and_equals_untouched():
+    specs = [s for s in collect(S) if s.key == "APP_PORT"]
+    text = "APP_PORT=a=b#c\n"
+    assert merge(text, specs) == text
+
+
+def test_crlf_example_preserved(tmp_path):
+    ex = tmp_path / ".env.example"
+    ex.write_bytes(b"old\r\n")
+    sync_env(S, tmp_path / ".env", ex)
+    data = ex.read_bytes()
+    assert b"\r\n" in data and b"\n" not in data.replace(b"\r\n", b"")
+
+
+def test_check_missing_example_is_a_problem(tmp_path):
+    (tmp_path / ".env").write_text("")
+    assert any("out of date" in p for p in check_env(S, tmp_path / ".env", tmp_path / ".env.example").problems)
+
+
+def test_env_file_taken_from_model_config(tmp_path):
+    class C(BaseSettings):
+        model_config = SettingsConfigDict(env_file=str(tmp_path / "custom.env"))
+        a: int = 1
+
+    sync_env(C)
+    assert (tmp_path / "custom.env").exists() and (tmp_path / ".env.example").exists()
+
+
+def test_cli_bad_target(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(SystemExit):
+        main(["check", "no_colon_here"])
+    with pytest.raises(SystemExit):
+        main(["check", "does_not_exist_mod:Settings"])