pyenvgen 0.1.0__tar.gz

pyenvgen-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: pyenvgen
+Version: 0.1.0
+Summary: Python tool to generate environment variables from schemas
+Author: bastienlc
+Author-email: bastienlc <78959054+bastienlc@users.noreply.github.com>
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: marshmallow>=3.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: tomli-w>=1.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# pyenvgen
+
+> **Warning:** This project was vibe coded and is in early development. Expect breaking changes and incomplete features. Contributions are welcome!
+
+Python tool to generate environment variables from YAML schemas.
+
+1. Define variables in a YAML schema, including types, generation rules, and validation constraints.
+2. Existing values are loaded from the chosen storage backend.
+3. Values are generated (with existing/overridden values taking precedence), then validated.
+4. The final environment is written back to the storage backend.
+
+## Installation
+
+```bash
+pip install pyenvgen
+```
+
+## Usage
+
+```bash
+pyenvgen <schema.yaml> [-s STORAGE] [-o KEY=VALUE ...] [--force]
+```
+
+| Flag               | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `-s`, `--storage`  | Storage backend (default: `stdout`)                    |
+| `-o`, `--override` | Override a value via `KEY=VALUE` (repeatable)          |
+| `--force`          | Regenerate all values, ignoring existing stored values |
+
+```bash
+# Print to stdout
+pyenvgen examples/basic.yaml
+
+# Write to a .env file
+pyenvgen examples/basic.yaml -s .env
+
+# Override a value
+pyenvgen examples/basic.yaml -o APP_PORT=9000
+```
+
+## Schema format
+
+```yaml
+variables:
+  MY_VAR:
+    type: str          # str | int | float | bool (default: str)
+    description: "..."
+    internal: false    # default: false
+    generation:
+      rule: default
+      value: "hello"
+    validation:
+      length:
+        min: 1
+        max: 128
+```
+
+### Variable types
+
+`str`, `int`, `float`, `bool`
+
+### Generation rules
+
+All string fields in generation rules are rendered as **Jinja2 templates** against already-generated values before execution.
+
+- **`default`** – use a static value (supports Jinja2, e.g. `"postgres://{{ HOST }}:{{ PORT }}/app"`)
+- **`command`** – run a shell command and capture its stdout
+- **`openssl`** – generate cryptographic material via the [`cryptography`](https://github.com/pyca/cryptography) package
+
+#### `openssl` commands
+
+| Command   | Description                         | Key args                                                                                    |
+| --------- | ----------------------------------- | ------------------------------------------------------------------------------------------- |
+| `rsa`     | RSA private key (PEM or DER base64) | `key_size` (default 2048), `encoding` (`pem`\|`der_b64`)                                    |
+| `ec`      | EC private key                      | `curve` (`secp256r1`\|`secp384r1`\|`secp521r1`\|`secp256k1`), `encoding` (`pem`\|`der_b64`) |
+| `ed25519` | Ed25519 private key                 | `encoding` (`pem`\|`raw_b64`)                                                               |
+| `x25519`  | X25519 private key                  | `encoding` (`pem`\|`raw_b64`, default `raw_b64`)                                            |
+| `fernet`  | URL-safe base64 Fernet key          | —                                                                                           |
+| `random`  | Random bytes                        | `length` (default 32), `encoding` (`hex`\|`base64`\|`base64url`)                            |
+
+### Validation rules
+
+Backed by [marshmallow](https://github.com/marshmallow-code/marshmallow).
+
+| Rule     | Applies to     | Fields                                         |
+| -------- | -------------- | ---------------------------------------------- |
+| `length` | `str`          | `min`, `max`                                   |
+| `range`  | `int`, `float` | `min`, `max`, `min_inclusive`, `max_inclusive` |
+| `one_of` | any            | `choices: [...]`                               |
+| `regexp` | any            | `pattern`                                      |
+
+### Storage backends
+
+| Value    | Description              |
+| -------- | ------------------------ |
+| `stdout` | Print to standard output |
+| `.env`   | Read/write a `.env` file |
+| `json`   | Read/write a JSON file   |
+| `toml`   | Read/write a TOML file   |
+| `yaml`   | Read/write a YAML file   |
+
+### Special properties
+
+- **`internal: true`** – the variable is generated and available to Jinja2 templates but excluded from the output.

pyenvgen-0.1.0/README.md

@@ -0,0 +1,104 @@
+# pyenvgen
+
+> **Warning:** This project was vibe coded and is in early development. Expect breaking changes and incomplete features. Contributions are welcome!
+
+Python tool to generate environment variables from YAML schemas.
+
+1. Define variables in a YAML schema, including types, generation rules, and validation constraints.
+2. Existing values are loaded from the chosen storage backend.
+3. Values are generated (with existing/overridden values taking precedence), then validated.
+4. The final environment is written back to the storage backend.
+
+## Installation
+
+```bash
+pip install pyenvgen
+```
+
+## Usage
+
+```bash
+pyenvgen <schema.yaml> [-s STORAGE] [-o KEY=VALUE ...] [--force]
+```
+
+| Flag               | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `-s`, `--storage`  | Storage backend (default: `stdout`)                    |
+| `-o`, `--override` | Override a value via `KEY=VALUE` (repeatable)          |
+| `--force`          | Regenerate all values, ignoring existing stored values |
+
+```bash
+# Print to stdout
+pyenvgen examples/basic.yaml
+
+# Write to a .env file
+pyenvgen examples/basic.yaml -s .env
+
+# Override a value
+pyenvgen examples/basic.yaml -o APP_PORT=9000
+```
+
+## Schema format
+
+```yaml
+variables:
+  MY_VAR:
+    type: str          # str | int | float | bool (default: str)
+    description: "..."
+    internal: false    # default: false
+    generation:
+      rule: default
+      value: "hello"
+    validation:
+      length:
+        min: 1
+        max: 128
+```
+
+### Variable types
+
+`str`, `int`, `float`, `bool`
+
+### Generation rules
+
+All string fields in generation rules are rendered as **Jinja2 templates** against already-generated values before execution.
+
+- **`default`** – use a static value (supports Jinja2, e.g. `"postgres://{{ HOST }}:{{ PORT }}/app"`)
+- **`command`** – run a shell command and capture its stdout
+- **`openssl`** – generate cryptographic material via the [`cryptography`](https://github.com/pyca/cryptography) package
+
+#### `openssl` commands
+
+| Command   | Description                         | Key args                                                                                    |
+| --------- | ----------------------------------- | ------------------------------------------------------------------------------------------- |
+| `rsa`     | RSA private key (PEM or DER base64) | `key_size` (default 2048), `encoding` (`pem`\|`der_b64`)                                    |
+| `ec`      | EC private key                      | `curve` (`secp256r1`\|`secp384r1`\|`secp521r1`\|`secp256k1`), `encoding` (`pem`\|`der_b64`) |
+| `ed25519` | Ed25519 private key                 | `encoding` (`pem`\|`raw_b64`)                                                               |
+| `x25519`  | X25519 private key                  | `encoding` (`pem`\|`raw_b64`, default `raw_b64`)                                            |
+| `fernet`  | URL-safe base64 Fernet key          | —                                                                                           |
+| `random`  | Random bytes                        | `length` (default 32), `encoding` (`hex`\|`base64`\|`base64url`)                            |
+
+### Validation rules
+
+Backed by [marshmallow](https://github.com/marshmallow-code/marshmallow).
+
+| Rule     | Applies to     | Fields                                         |
+| -------- | -------------- | ---------------------------------------------- |
+| `length` | `str`          | `min`, `max`                                   |
+| `range`  | `int`, `float` | `min`, `max`, `min_inclusive`, `max_inclusive` |
+| `one_of` | any            | `choices: [...]`                               |
+| `regexp` | any            | `pattern`                                      |
+
+### Storage backends
+
+| Value    | Description              |
+| -------- | ------------------------ |
+| `stdout` | Print to standard output |
+| `.env`   | Read/write a `.env` file |
+| `json`   | Read/write a JSON file   |
+| `toml`   | Read/write a TOML file   |
+| `yaml`   | Read/write a YAML file   |
+
+### Special properties
+
+- **`internal: true`** – the variable is generated and available to Jinja2 templates but excluded from the output.

pyenvgen-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "pyenvgen"
+version = "0.1.0"
+description = "Python tool to generate environment variables from schemas"
+readme = "README.md"
+authors = [
+    { name = "bastienlc", email = "78959054+bastienlc@users.noreply.github.com" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pyyaml>=6.0",
+    "pydantic>=2.0",
+    "marshmallow>=3.0",
+    "jinja2>=3.0",
+    "cryptography>=41.0",
+    "tomli-w>=1.0",
+]
+
+[project.scripts]
+pyenvgen = "pyenvgen.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.20,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.0.2", "pytest-cov>=6.0", "ruff>=0.15.2", "pre-commit>=4.0"]
+
+[tool.coverage.run]
+source = ["src/pyenvgen"]
+
+[tool.coverage.report]
+fail_under = 80

pyenvgen-0.1.0/src/pyenvgen/__init__.py

@@ -0,0 +1 @@
+"""pyenvgen - Python tool to generate environment variables from schemas."""

pyenvgen-0.1.0/src/pyenvgen/cli.py

@@ -0,0 +1,118 @@
+"""CLI entry-point for pyenvgen."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from marshmallow import ValidationError as MarshmallowValidationError
+from pydantic import ValidationError
+
+from pyenvgen.generation import generate_env
+from pyenvgen.schema import EnvSchema
+from pyenvgen.storage import get_storage
+from pyenvgen.validation import validate_env
+
+
+def _load_schema(path: Path) -> EnvSchema:
+    """Load and validate a YAML schema file."""
+    try:
+        with open(path) as f:
+            raw: Any = yaml.safe_load(f)
+    except FileNotFoundError:
+        print(f"Error: schema file not found: {path}")
+        sys.exit(1)
+
+    if not isinstance(raw, dict):
+        print(f"Error: schema file must be a YAML mapping, got {type(raw).__name__}")
+        sys.exit(1)
+
+    try:
+        return EnvSchema.model_validate(raw)
+    except ValidationError as exc:
+        print(f"Schema validation error:\n{exc}")
+        sys.exit(1)
+
+
+def _parse_overrides(override_args: list[str] | None) -> dict[str, str]:
+    """Parse ``KEY=VALUE`` override arguments from the CLI."""
+    overrides: dict[str, str] = {}
+    for item in override_args or []:
+        if "=" not in item:
+            print(f"Error: override must be KEY=VALUE, got '{item}'")
+            sys.exit(1)
+        key, value = item.split("=", 1)
+        overrides[key] = value
+    return overrides
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Main entry-point."""
+    parser = argparse.ArgumentParser(
+        prog="pyenvgen",
+        description="Generate environment variables from a YAML schema.",
+    )
+    parser.add_argument(
+        "schema",
+        type=Path,
+        help="Path to the YAML schema file.",
+    )
+    parser.add_argument(
+        "-s",
+        "--storage",
+        default="stdout",
+        help="Storage backend (default: stdout).",
+    )
+    parser.add_argument(
+        "-o",
+        "--override",
+        action="append",
+        metavar="KEY=VALUE",
+        help="Override a generated value (can be repeated).",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help=(
+            "Regenerate all values, ignoring any values already present in "
+            "the storage backend. Without this flag, existing values are "
+            "preserved and used as the base before new ones are generated."
+        ),
+    )
+
+    args = parser.parse_args(argv)
+
+    # 1. Load & validate schema
+    schema = _load_schema(args.schema)
+
+    # 2. Get storage backend early so we can load existing values
+    backend = get_storage(args.storage)
+
+    # 3. Parse CLI overrides
+    overrides = _parse_overrides(args.override)
+
+    # 4. Load existing values from storage and merge with CLI overrides.
+    #    This happens *before* generation so that existing values are available
+    #    to Jinja templates inside generation rules.  CLI overrides always take
+    #    precedence over stored values; --force skips loading altogether.
+    if args.force:
+        merged: dict[str, str] = overrides
+    else:
+        existing = backend.load()
+        merged = {**existing, **overrides}
+
+    # 5. Generate values (existing / overridden values seed the result dict)
+    generated = generate_env(schema, overrides=merged)
+
+    # 6. Validate generated values against schema (type-cast + constraints)
+    try:
+        validated = validate_env(schema, generated)
+    except MarshmallowValidationError as exc:
+        print(f"Validation error: {exc}")
+        sys.exit(1)
+
+    # 7. Store output
+    backend.store(validated, schema)

pyenvgen-0.1.0/src/pyenvgen/generation/__init__.py

@@ -0,0 +1,215 @@
+"""Generation module – produces environment variable values from schemas.
+
+Each generation rule lives in its own submodule:
+- ``default``  → :mod:`pyenvgen.generation.default`
+- ``command``  → :mod:`pyenvgen.generation.command`
+- ``openssl``  → :mod:`pyenvgen.generation.openssl`
+
+All rule string fields are rendered as Jinja2 templates against the set of
+already-generated variables *before* the rule is executed.  This means any
+rule can reference other variables using ``{{ VAR_NAME }}`` syntax, removing
+the need for a separate ``template`` rule.
+
+This package exposes the public API: :func:`generate_value` and
+:func:`generate_env`.  It also handles topological ordering so that
+variables whose Jinja templates reference others are always generated after
+the variables they depend on.
+"""
+
+from __future__ import annotations
+
+from graphlib import CycleError, TopologicalSorter
+
+import jinja2
+import jinja2.meta
+
+from pyenvgen.schema import (
+    CommandGeneration,
+    DefaultGeneration,
+    EnvSchema,
+    GenerationRule,
+    OpenSSLGeneration,
+)
+
+from pyenvgen.generation.command import generate_command
+from pyenvgen.generation.default import generate_default
+from pyenvgen.generation.openssl import generate_openssl
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class CircularDependencyError(Exception):
+    """Raised when variables form a circular Jinja dependency."""
+
+
+# ---------------------------------------------------------------------------
+# Jinja helpers
+# ---------------------------------------------------------------------------
+
+
+def _render_string(s: str, existing: dict[str, str]) -> str:
+    """Render *s* as a Jinja2 template against *existing* values."""
+    env = jinja2.Environment(undefined=jinja2.StrictUndefined)
+    return env.from_string(s).render(**existing)
+
+
+def _jinja_deps(s: str, all_names: set[str]) -> set[str]:
+    """Return schema variable names referenced in Jinja template string *s*."""
+    env = jinja2.Environment()
+    ast = env.parse(s)
+    refs = jinja2.meta.find_undeclared_variables(ast)
+    return refs & all_names
+
+
+def _rule_template_strings(rule: GenerationRule) -> list[str]:
+    """Return all string fields of *rule* that may contain Jinja templates."""
+    if isinstance(rule, DefaultGeneration):
+        return [rule.value]
+    if isinstance(rule, CommandGeneration):
+        return [rule.command]
+    if isinstance(rule, OpenSSLGeneration):
+        strings = [rule.command]
+        strings.extend(v for v in rule.args.values() if isinstance(v, str))
+        return strings
+    return []  # pragma: no cover
+
+
+def _rule_jinja_deps(rule: GenerationRule, all_names: set[str]) -> set[str]:
+    """Find all schema variable names referenced in Jinja templates within *rule*."""
+    deps: set[str] = set()
+    for s in _rule_template_strings(rule):
+        deps |= _jinja_deps(s, all_names)
+    return deps
+
+
+def _render_rule(rule: GenerationRule, existing: dict[str, str]) -> GenerationRule:
+    """Return a copy of *rule* with all string fields Jinja-rendered against *existing*."""
+    if isinstance(rule, DefaultGeneration):
+        return rule.model_copy(update={"value": _render_string(rule.value, existing)})
+    if isinstance(rule, CommandGeneration):
+        return rule.model_copy(update={"command": _render_string(rule.command, existing)})
+    if isinstance(rule, OpenSSLGeneration):
+        rendered_args = {
+            k: _render_string(v, existing) if isinstance(v, str) else v
+            for k, v in rule.args.items()
+        }
+        return rule.model_copy(
+            update={
+                "command": _render_string(rule.command, existing),
+                "args": rendered_args,
+            }
+        )
+    return rule  # pragma: no cover
+
+
+# ---------------------------------------------------------------------------
+# Topological ordering
+# ---------------------------------------------------------------------------
+
+
+def _topological_order(schema: EnvSchema) -> list[str]:
+    """Return variable names in a safe generation order.
+
+    Every rule's string fields are scanned for Jinja variable references.
+    A variable X depends on Y if any of X's template strings reference Y.
+
+    Raises
+    ------
+    CircularDependencyError
+        If the dependency graph contains a cycle.
+    """
+    all_names = set(schema.variables)
+
+    deps: dict[str, set[str]] = {
+        name: _rule_jinja_deps(var.generation, all_names)
+        for name, var in schema.variables.items()
+    }
+
+    try:
+        return list(TopologicalSorter(deps).static_order())
+    except CycleError as exc:
+        raise CircularDependencyError(
+            f"Circular dependency detected among variables: {exc.args[1]}"
+        ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def generate_value(
+    rule: GenerationRule,
+    existing: dict[str, str] | None = None,
+) -> str:
+    """Dispatch to the appropriate generator for *rule*.
+
+    Before dispatching, all string fields in *rule* are rendered as Jinja2
+    templates against *existing* so that any rule may reference previously
+    generated variables.
+
+    Parameters
+    ----------
+    rule
+        The generation rule from the variable schema.
+    existing
+        Already-generated values used for Jinja template rendering.
+
+    Returns
+    -------
+    str
+        The generated value as a string (will be validated/cast later).
+    """
+    existing = existing or {}
+    rule = _render_rule(rule, existing)
+
+    if rule.rule == "default":
+        assert isinstance(rule, DefaultGeneration)
+        return generate_default(rule)
+    if rule.rule == "command":
+        assert isinstance(rule, CommandGeneration)
+        return generate_command(rule)
+    if rule.rule == "openssl":
+        assert isinstance(rule, OpenSSLGeneration)
+        return generate_openssl(rule)
+
+    raise NotImplementedError(f"Generation rule '{rule.rule}' is not yet implemented")  # pragma: no cover
+
+
+def generate_env(
+    schema: EnvSchema,
+    overrides: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Generate all environment variable values from *schema*.
+
+    Variables are generated in topological order so that Jinja templates can
+    safely reference other variables.
+
+    Parameters
+    ----------
+    schema
+        The parsed environment schema.
+    overrides
+        Values that take precedence over generated ones (e.g. from an
+        existing .env file or CLI arguments).
+
+    Returns
+    -------
+    dict[str, str]
+        Mapping of variable name → generated string value.
+    """
+    overrides = overrides or {}
+    result: dict[str, str] = {}
+
+    for name in _topological_order(schema):
+        if name in overrides:
+            result[name] = overrides[name]
+        else:
+            result[name] = generate_value(
+                schema.variables[name].generation, existing=result
+            )
+
+    return result

pyenvgen-0.1.0/src/pyenvgen/generation/command.py

@@ -0,0 +1,19 @@
+"""Command generation rule – executes a shell command and captures its stdout."""
+
+from __future__ import annotations
+
+import subprocess
+
+from pyenvgen.schema import CommandGeneration
+
+
+def generate_command(rule: CommandGeneration) -> str:
+    """Execute *rule.command* in a shell and return its stripped stdout."""
+    result = subprocess.run(
+        rule.command,
+        shell=True,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()

pyenvgen-0.1.0/src/pyenvgen/generation/default.py

@@ -0,0 +1,10 @@
+"""Default generation rule – returns a literal value from the schema."""
+
+from __future__ import annotations
+
+from pyenvgen.schema import DefaultGeneration
+
+
+def generate_default(rule: DefaultGeneration) -> str:
+    """Return the literal default value from the schema."""
+    return rule.value