envstencil 0.1.0__tar.gz

envstencil-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Kyle Felipe
+
+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.

envstencil-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: envstencil
+Version: 0.1.0
+Summary: CLI Python que gera um .env.example seguro a partir do seu .env — troca os valores por placeholders e preserva comentários e estrutura.
+License: MIT
+License-File: LICENSE
+Keywords: dotenv,env,environment,template,security
+Author: Kyle Felipe
+Author-email: kylefelipe@gmail.com
+Requires-Python: >=3.10,<4
+Classifier: Programming Language :: Python :: 3
+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: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Natural Language :: Portuguese (Brazilian)
+Requires-Dist: click (>=8.0)
+Project-URL: Documentation, https://env-stencil.readthedocs.io/pt/latest/
+Project-URL: Homepage, https://github.com/kylefelipe/env-stencil
+Project-URL: Issues, https://github.com/kylefelipe/env-stencil/issues
+Project-URL: Repository, https://github.com/kylefelipe/env-stencil
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kylefelipe/env-stencil/main/images/logos/envstencil-wordmark.png" alt="EnvStencil" width="320">
+</p>
+
+<p align="center">
+  Gere um <code>.env.example</code> seguro a partir do seu <code>.env</code>, automaticamente.
+</p>
+
+<p align="center">
+  📖 <a href="https://env-stencil.readthedocs.io/pt/latest/">Documentação completa</a>
+</p>
+
+# EnvStencil
+
+[![Documentation Status](https://app.readthedocs.org/projects/env-stencil/badge/?version=latest)](https://env-stencil.readthedocs.io/en/latest/?badge=latest)
+[![CI](https://github.com/kylefelipe/env-stencil/actions/workflows/ci.yml/badge.svg)](https://github.com/kylefelipe/env-stencil/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/github/kylefelipe/env-stencil/graph/badge.svg?token=WTXDCQU4O2)](https://codecov.io/github/kylefelipe/env-stencil)
+
+Sempre quando estamos desenvolvendo, é comum a gente criar um arquivo `.env` com as variáveis de ambiente necessárias e depois ter de gerar um arquivo `.env.example` para que outros desenvolvedores possam criar o seu próprio `.env` a partir dele.
+
+O problema é que essa é uma tarefa muito chata e repetitiva, então o `envstencil` foi criado para automatizar esse processo.
+
+Caso o arquivo `.env` contenha variáveis que não precisam ser sobrescritas no `.env.example`, você pode adicionar o comentário `# envstencil:keep` na linha da variável que deseja manter ou na linha anterior.
+
+## Instalação
+
+**pip** — do PyPI ou direto do git:
+
+```bash
+pip install envstencil
+pip install git+https://github.com/kylefelipe/env-stencil.git
+```
+
+**Poetry** — adiciona `envstencil` como dependência do seu projeto:
+
+```bash
+poetry add envstencil
+poetry add git+https://github.com/kylefelipe/env-stencil.git
+```
+
+Com o repositório já clonado: `pip install .` (ou `poetry install`).
+
+## Uso
+
+```bash
+# Gera .env.example a partir de .env no diretório atual
+envstencil generate
+
+# Especificar arquivo de origem e destino
+envstencil generate .env.production -o .env.production.example
+
+# Ou, gerando a partir do .env padrão
+envstencil generate -o .env.production.example
+
+# Placeholder customizado
+envstencil generate --placeholder "CHANGE_ME"
+
+# Sobrescrever arquivo existente
+envstencil generate --force
+```
+
+## Exemplo
+
+Entrada (`.env`):
+
+```bash
+# Banco de dados
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+STRIPE_SECRET_KEY=sk_live_abc123
+```
+
+Saída (`.env.example`):
+
+```bash
+# Banco de dados
+DATABASE_URL=your_value_here
+STRIPE_SECRET_KEY=your_value_here
+```
+
+## Desenvolvimento
+
+Requer **Poetry 2.0+**. Os grupos `dev` e `doc` são opcionais — `poetry install`
+sozinho instala só o runtime:
+
+```bash
+poetry install --with dev,doc
+```
+
+Tarefas, convenções e fluxo de PR: **[Contribuindo](https://env-stencil.readthedocs.io/pt/latest/contributing/)**.
+

envstencil-0.1.0/README.md

@@ -0,0 +1,89 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kylefelipe/env-stencil/main/images/logos/envstencil-wordmark.png" alt="EnvStencil" width="320">
+</p>
+
+<p align="center">
+  Gere um <code>.env.example</code> seguro a partir do seu <code>.env</code>, automaticamente.
+</p>
+
+<p align="center">
+  📖 <a href="https://env-stencil.readthedocs.io/pt/latest/">Documentação completa</a>
+</p>
+
+# EnvStencil
+
+[![Documentation Status](https://app.readthedocs.org/projects/env-stencil/badge/?version=latest)](https://env-stencil.readthedocs.io/en/latest/?badge=latest)
+[![CI](https://github.com/kylefelipe/env-stencil/actions/workflows/ci.yml/badge.svg)](https://github.com/kylefelipe/env-stencil/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/github/kylefelipe/env-stencil/graph/badge.svg?token=WTXDCQU4O2)](https://codecov.io/github/kylefelipe/env-stencil)
+
+Sempre quando estamos desenvolvendo, é comum a gente criar um arquivo `.env` com as variáveis de ambiente necessárias e depois ter de gerar um arquivo `.env.example` para que outros desenvolvedores possam criar o seu próprio `.env` a partir dele.
+
+O problema é que essa é uma tarefa muito chata e repetitiva, então o `envstencil` foi criado para automatizar esse processo.
+
+Caso o arquivo `.env` contenha variáveis que não precisam ser sobrescritas no `.env.example`, você pode adicionar o comentário `# envstencil:keep` na linha da variável que deseja manter ou na linha anterior.
+
+## Instalação
+
+**pip** — do PyPI ou direto do git:
+
+```bash
+pip install envstencil
+pip install git+https://github.com/kylefelipe/env-stencil.git
+```
+
+**Poetry** — adiciona `envstencil` como dependência do seu projeto:
+
+```bash
+poetry add envstencil
+poetry add git+https://github.com/kylefelipe/env-stencil.git
+```
+
+Com o repositório já clonado: `pip install .` (ou `poetry install`).
+
+## Uso
+
+```bash
+# Gera .env.example a partir de .env no diretório atual
+envstencil generate
+
+# Especificar arquivo de origem e destino
+envstencil generate .env.production -o .env.production.example
+
+# Ou, gerando a partir do .env padrão
+envstencil generate -o .env.production.example
+
+# Placeholder customizado
+envstencil generate --placeholder "CHANGE_ME"
+
+# Sobrescrever arquivo existente
+envstencil generate --force
+```
+
+## Exemplo
+
+Entrada (`.env`):
+
+```bash
+# Banco de dados
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+STRIPE_SECRET_KEY=sk_live_abc123
+```
+
+Saída (`.env.example`):
+
+```bash
+# Banco de dados
+DATABASE_URL=your_value_here
+STRIPE_SECRET_KEY=your_value_here
+```
+
+## Desenvolvimento
+
+Requer **Poetry 2.0+**. Os grupos `dev` e `doc` são opcionais — `poetry install`
+sozinho instala só o runtime:
+
+```bash
+poetry install --with dev,doc
+```
+
+Tarefas, convenções e fluxo de PR: **[Contribuindo](https://env-stencil.readthedocs.io/pt/latest/contributing/)**.

envstencil-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "envstencil"
+version = "0.1.0"
+description = "CLI Python que gera um .env.example seguro a partir do seu .env — troca os valores por placeholders e preserva comentários e estrutura."
+readme = "README.md"
+requires-python = ">=3.10,<4"
+license = { text = "MIT" }
+authors = [
+    { name = "Kyle Felipe", email = "kylefelipe@gmail.com" }
+]
+keywords = ["dotenv", "env", "environment", "template", "security"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Natural Language :: Portuguese (Brazilian)",
+]
+dependencies = [
+    "click>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/kylefelipe/env-stencil"
+Documentation = "https://env-stencil.readthedocs.io/pt/latest/"
+Repository = "https://github.com/kylefelipe/env-stencil"
+Issues = "https://github.com/kylefelipe/env-stencil/issues"
+
+[project.scripts]
+envstencil = "envstencil.cli:main"
+
+[tool.poetry]
+packages = [{ include = "envstencil", from = "src" }]
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.0.0"
+pytest-cov = "^7.1.0"
+isort = "^9.0.1"
+taskipy = "^1.14.1"
+black = "^26.5.1"
+
+[tool.poetry.group.doc]
+optional = true
+
+[tool.poetry.group.doc.dependencies]
+mkdocs-material = "^9.7.7"
+mkdocstrings = "^1.0.6"
+mkdocstrings-python = "^2.0.7"
+mkdocs-click = "^0.9.0"
+mkdocs-macros-plugin = "^1.5.0"
+jinja2 = "^3.1.6"
+
+[tool.isort]
+profile = "black"
+line_length = 79
+
+[tool.black]
+line-length = 79
+target-version = ["py310"]
+
+[tool.pytest.ini_options]
+pythonpath = "."
+addopts = "--doctest-modules"
+
+[tool.taskipy.tasks]
+pre_test = "task lint"
+test = "pytest -s -x --cov=envstencil -vv"
+post_test = "coverage html"
+lint = "black --check --diff . && isort --check --diff ."
+fmt = "isort . && black ."
+docs = "mkdocs serve"

envstencil-0.1.0/src/envstencil/__init__.py

@@ -0,0 +1,17 @@
+"""envstencil — gera um .env.example seguro a partir do seu .env."""
+
+from .core import (
+    DEFAULT_PLACEHOLDER,
+    generate_example,
+    parse_env_file,
+    render_stencil,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_PLACEHOLDER",
+    "generate_example",
+    "parse_env_file",
+    "render_stencil",
+]

envstencil-0.1.0/src/envstencil/cli.py

@@ -0,0 +1,82 @@
+"""Command-line interface for envstencil."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from .core import DEFAULT_PLACEHOLDER, generate_example
+
+
+@click.group()
+@click.version_option()
+def main() -> None:
+    """envstencil — gera um .env.example seguro a partir do seu .env."""
+
+
+@main.command()
+@click.argument(
+    "source",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=".env",
+    required=False,
+)
+@click.option(
+    "-o",
+    "--output",
+    "destination",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Arquivo de saída (padrão: origem + '.example', no mesmo diretório).",
+)
+@click.option(
+    "-p",
+    "--placeholder",
+    default=DEFAULT_PLACEHOLDER,
+    show_default=True,
+    help="Texto usado para substituir cada valor.",
+)
+@click.option(
+    "-f",
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Sobrescreve o arquivo de destino se ele já existir.",
+)
+@click.option(
+    "-b",
+    "--collapse-blank-lines",
+    is_flag=True,
+    default=False,
+    help="Colapsa linhas em branco consecutivas em uma só.",
+)
+def generate(
+    source: Path,
+    destination: Path | None,
+    placeholder: str,
+    force: bool,
+    collapse_blank_lines: bool,
+) -> None:
+    """Gera um .env.example a partir de SOURCE (padrão: .env)."""
+    if destination is None:
+        destination = source.parent / f"{source.name}.example"
+
+    try:
+        result = generate_example(
+            source=source,
+            destination=destination,
+            placeholder=placeholder,
+            force=force,
+            collapse_blank_lines=collapse_blank_lines,
+        )
+    except FileExistsError as exc:
+        raise click.ClickException(str(exc)) from exc
+    except FileNotFoundError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    click.echo(f"✅ {result} gerado a partir de {source}")
+
+
+if __name__ == "__main__":
+    main()

envstencil-0.1.0/src/envstencil/core.py

@@ -0,0 +1,245 @@
+"""Core logic for envstencil: parse .env files and generate a safe .env.example."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_PLACEHOLDER = "your_value_here"
+
+# Matches KEY=VALUE lines, tolerating optional `export ` prefix and spaces
+# around the `=`. Keys follow standard shell/dotenv identifier rules.
+_KEY_VALUE_RE = re.compile(
+    r"^(?P<prefix>export\s+)?(?P<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?P<value>.*)$"
+)
+
+# Opt-in directive that tells envstencil to keep the real value in the stencil
+# instead of replacing it with the placeholder. Accepted either as an inline
+# comment on the pair itself or as a standalone comment on the line above it.
+_KEEP_MARKER_RE = re.compile(r"#\s*envstencil\s*:\s*keep\b", re.IGNORECASE)
+
+
+def _split_inline_comment(value: str) -> tuple[str, str]:
+    """Split a parsed value into ``(value, inline_comment)``.
+
+    An inline comment starts at the first ``#`` that sits outside quotes and is
+    either at the start or preceded by whitespace (dotenv convention). The
+    returned ``inline_comment`` keeps its leading whitespace and the ``#`` so it
+    can be re-appended verbatim; it is ``""`` when there is no inline comment.
+    """
+    quote = ""
+    i = 0
+    while i < len(value):
+        ch = value[i]
+        if quote:
+            if ch == "\\" and quote == '"' and i + 1 < len(value):
+                i += 2
+                continue
+            if ch == quote:
+                quote = ""
+        elif ch in ("'", '"'):
+            quote = ch
+        elif ch == "#" and (i == 0 or value[i - 1].isspace()):
+            head = value[:i].rstrip()
+            return head, value[len(head) :]
+        i += 1
+    return value, ""
+
+
+def _strip_keep_marker(comment: str) -> str:
+    """Remove the `# envstencil:keep` directive from a comment, keeping any other
+    documentation text. Returns the leftover as an inline suffix (a single
+    `" # ..."`), or ``""`` when the comment was only the directive.
+    """
+    cleaned = _KEEP_MARKER_RE.sub("", comment).strip()
+    if not cleaned.strip("#").strip():
+        return ""
+    body = cleaned[1:].lstrip() if cleaned.startswith("#") else cleaned
+    return f" # {body}"
+
+
+@dataclass
+class EnvLine:
+    """Represents one parsed line from a .env file.
+
+    Attributes:
+        raw: The original line text, verbatim.
+        kind: One of `"comment"`, `"blank"`, `"pair"`, or `"unknown"`.
+        key: Variable name, when `kind == "pair"`.
+        value: Variable value without any inline comment, when `kind == "pair"`.
+        prefix: Leading `"export "` when present, otherwise `""`.
+        inline_comment: Trailing `# ...` of a pair, with its leading space.
+        keep: Whether the pair is flagged with `# envstencil:keep`.
+    """
+
+    raw: str
+    kind: str  # "comment", "blank", "pair", "unknown"
+    key: str | None = None
+    value: str | None = None
+    prefix: str = ""
+    inline_comment: str = (
+        ""  # trailing `# ...` on a pair (with its leading space)
+    )
+    keep: bool = False  # pair marked with `# envstencil:keep`
+
+
+def parse_env_file(path: Path) -> list[EnvLine]:
+    """Parse a .env file into ordered EnvLine entries.
+
+    Blank lines and comments are preserved so the structure can be mirrored
+    in the output. The `# envstencil:keep` directive is never kept as an
+    EnvLine: a standalone directive line is dropped (only its effect
+    survives, on the next pair) and an inline directive is stripped from the
+    pair's comment.
+
+    Args:
+        path: Path to the `.env` file to read.
+
+    Returns:
+        The parsed lines, in file order.
+    """
+
+    lines: list[EnvLine] = []
+    text = path.read_text(encoding="utf-8")
+
+    # Set by a standalone `# envstencil:keep` comment and consumed by the next
+    # pair. Blank lines in between are tolerated; any other line clears it.
+    pending_keep = False
+
+    for raw_line in text.splitlines():
+        stripped = raw_line.strip()
+
+        if not stripped:
+            lines.append(EnvLine(raw=raw_line, kind="blank"))
+            continue
+
+        if stripped.startswith("#"):
+            if _KEEP_MARKER_RE.search(stripped):
+                pending_keep = True
+                remainder = _strip_keep_marker(stripped).lstrip()
+                if remainder:
+                    lines.append(EnvLine(raw=remainder, kind="comment"))
+            else:
+                lines.append(EnvLine(raw=raw_line, kind="comment"))
+            continue
+
+        match = _KEY_VALUE_RE.match(stripped)
+        if match:
+            value, inline_comment = _split_inline_comment(match.group("value"))
+            has_inline_marker = bool(_KEEP_MARKER_RE.search(inline_comment))
+            if has_inline_marker:
+                inline_comment = _strip_keep_marker(inline_comment)
+            lines.append(
+                EnvLine(
+                    raw=raw_line,
+                    kind="pair",
+                    key=match.group("key"),
+                    value=value,
+                    prefix=match.group("prefix") or "",
+                    inline_comment=inline_comment,
+                    keep=pending_keep or has_inline_marker,
+                )
+            )
+            pending_keep = False
+            continue
+
+        lines.append(EnvLine(raw=raw_line, kind="unknown"))
+        pending_keep = False
+
+    return lines
+
+
+def _collapse_blank_lines(rows: list[str]) -> list[str]:
+    """Collapse every run of consecutive blank lines down to a single one."""
+    collapsed: list[str] = []
+    prev_blank = False
+    for row in rows:
+        is_blank = not row.strip()
+        if is_blank and prev_blank:
+            continue
+        collapsed.append(row)
+        prev_blank = is_blank
+    return collapsed
+
+
+def render_stencil(
+    lines: list[EnvLine],
+    placeholder: str = DEFAULT_PLACEHOLDER,
+    collapse_blank_lines: bool = False,
+) -> str:
+    """Render parsed EnvLine entries into a .env.example body.
+
+    Every value is replaced with `placeholder` while comments and structure
+    are kept. Inline comments documenting a pair are preserved. Pairs flagged
+    with `# envstencil:keep` keep their real value, and the directive itself
+    never appears in the output.
+
+    Args:
+        lines: Parsed entries from
+            [`parse_env_file`][envstencil.core.parse_env_file].
+        placeholder: Text that replaces each value.
+        collapse_blank_lines: If `True`, reduce every run of consecutive
+            blank lines to a single one.
+
+    Returns:
+        The rendered `.env.example` content, ending with a newline.
+    """
+
+    output_lines: list[str] = []
+
+    for line in lines:
+        if line.kind in ("comment", "blank", "unknown"):
+            output_lines.append(line.raw)
+        elif line.kind == "pair":
+            rendered_value = line.value if line.keep else placeholder
+            output_lines.append(
+                f"{line.prefix}{line.key}={rendered_value}{line.inline_comment}"
+            )
+
+    if collapse_blank_lines:
+        output_lines = _collapse_blank_lines(output_lines)
+
+    return "\n".join(output_lines) + "\n"
+
+
+def generate_example(
+    source: Path,
+    destination: Path,
+    placeholder: str = DEFAULT_PLACEHOLDER,
+    force: bool = False,
+    collapse_blank_lines: bool = False,
+) -> Path:
+    """Read `source` and write a stencil to `destination`.
+
+    Args:
+        source: Path to the source `.env` file.
+        destination: Path of the `.env.example` to write.
+        placeholder: Text that replaces each value.
+        force: If `True`, overwrite `destination` when it already exists.
+        collapse_blank_lines: If `True`, collapse consecutive blank lines.
+
+    Returns:
+        The `destination` path.
+
+    Raises:
+        FileNotFoundError: If `source` does not exist.
+        FileExistsError: If `destination` exists and `force` is `False`.
+    """
+
+    if not source.exists():
+        raise FileNotFoundError(f"Arquivo de origem não encontrado: {source}")
+
+    if destination.exists() and not force:
+        raise FileExistsError(
+            f"{destination} já existe. Use --force para sobrescrever."
+        )
+
+    lines = parse_env_file(source)
+    content = render_stencil(
+        lines,
+        placeholder=placeholder,
+        collapse_blank_lines=collapse_blank_lines,
+    )
+    destination.write_text(content, encoding="utf-8")
+    return destination