django-env-loader 1.0.3__py3-none-any.whl

django_env_loader/__init__.py

@@ -0,0 +1,19 @@
+"""Django Env Loader - Gerenciamento robusto de variáveis de ambiente."""
+
+from django_env_loader.exceptions import EnvLoaderError, SecretNotFoundError, ValidationError
+from django_env_loader.loader import DjangoEnvLoader, EnvConfig, EnvLoader
+
+__version__ = "1.0.0"
+__all__ = [
+    "EnvLoader",
+    "DjangoEnvLoader",
+    "EnvConfig",
+    "EnvLoaderError",
+    "SecretNotFoundError",
+    "ValidationError",
+    "env_loader",
+]
+
+# Instância singleton padrão para importação direta
+# Uso: from django_env_loader import env_loader
+env_loader = EnvLoader()

django_env_loader/exceptions.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+# ============================================================================
+# Exceções customizadas
+# ============================================================================
+
+
+class EnvLoaderError(Exception):
+    """Classe base para exceções do EnvLoader."""
+
+
+class SecretNotFoundError(EnvLoaderError):
+    """Exceção levantada quando um secret obrigatório não é encontrado."""
+
+    def __init__(self, key: str, /, searched_locations: list[str] | None = None):
+        self.key = key
+        self.searched_locations = searched_locations or []
+        locations = ", ".join(self.searched_locations) if self.searched_locations else "padrão"
+        super().__init__(f"Secret '{key}' não encontrado. Locais buscados: {locations}")
+
+
+class ValidationError(EnvLoaderError):
+    """Exceção levantada quando a validação de uma variável falha."""
+
+    def __init__(self, key: str, value: Any, reason: str):
+        self.key = key
+        self.value = value
+        self.reason = reason
+        super().__init__(f"Validação falhou para '{key}': {reason} (valor: {value!r})")

django_env_loader/loader.py

@@ -0,0 +1,517 @@
+"""Pacote para gerenciamento de variáveis de ambiente e secrets.
+
+Este módulo fornece uma interface type-safe e extensível para carregar e validar
+variáveis de ambiente, com suporte especial para Docker secrets e integração Django.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TypeVar, overload
+
+from dotenv import load_dotenv
+
+from django_env_loader.exceptions import SecretNotFoundError, ValidationError
+
+__version__ = "1.0.0"
+__all__ = ["EnvLoader", "EnvConfig", SecretNotFoundError, ValidationError]
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+# ============================================================================
+# Configuração
+# ============================================================================
+
+
+@dataclass
+class EnvConfig:
+    """Configuração para o EnvLoader.
+
+    Attributes:
+        env_file: Caminho para arquivo .env (None = auto-detect)
+        secrets_dir: Diretório base para Docker secrets (padrão: /run/secrets)
+        encoding: Encoding para leitura de arquivos
+        prefix: Prefixo para filtrar variáveis (ex: 'DJANGO_')
+        override_existing: Se deve sobrescrever variáveis já definidas
+        auto_cast: Se deve tentar conversão automática de tipos
+        cache_secrets: Se deve cachear secrets lidos de arquivos
+        strict_mode: Se deve levantar exceções em vez de warnings
+        warn_on_missing: Se deve emitir warnings para variáveis não encontradas
+    """
+
+    env_file: Path | str | None = None
+    secrets_dir: Path = field(default_factory=lambda: Path("/run/secrets"))
+    encoding: str = "utf-8"
+    prefix: str = ""
+    override_existing: bool = False
+    auto_cast: bool = True
+    cache_secrets: bool = True
+    strict_mode: bool = False
+    warn_on_missing: bool = True
+
+    def __post_init__(self) -> None:
+        """Valida e normaliza a configuração."""
+        if self.env_file is not None:
+            self.env_file = Path(self.env_file)
+        if isinstance(self.secrets_dir, str):
+            self.secrets_dir = Path(self.secrets_dir)
+
+
+# ============================================================================
+# Conversores de tipo
+# ============================================================================
+
+
+class TypeConverter:
+    """Conversor type-safe de valores de ambiente."""
+
+    @staticmethod
+    def to_bool(value: str | bool) -> bool:
+        """Converte string para boolean de forma segura."""
+        if isinstance(value, bool):
+            return value
+
+        if not isinstance(value, str):
+            raise ValidationError("boolean", value, "Tipo inválido, esperado str ou bool")
+
+        normalized = value.lower().strip()
+
+        if normalized in {"true", "1", "yes", "y", "on", "t", "sim", "s"}:
+            return True
+        if normalized in {"false", "0", "no", "n", "off", "f", "não", "nao", ""}:
+            return False
+
+        raise ValidationError("boolean", value, f"Valor inválido para bool: '{value}'")
+
+    @staticmethod
+    def to_int(value: str | int) -> int:
+        """Converte string para inteiro."""
+        if isinstance(value, int):
+            return value
+        try:
+            return int(str(value).strip())
+        except (ValueError, TypeError) as e:
+            raise ValidationError("int", value, str(e)) from e
+
+    @staticmethod
+    def to_float(value: str | float) -> float:
+        """Converte string para float."""
+        if isinstance(value, float):
+            return value
+        try:
+            return float(str(value).strip())
+        except (ValueError, TypeError) as e:
+            raise ValidationError("float", value, str(e)) from e
+
+    @staticmethod
+    def to_list(value: str | list[str], delimiter: str = ",") -> list[str]:
+        """Converte string delimitada em lista."""
+        if isinstance(value, list):
+            return value
+        if not value:
+            return []
+        return [item.strip() for item in str(value).split(delimiter) if item.strip()]
+
+    @staticmethod
+    def to_dict(value: str | dict[str, str], delimiter: str = ",") -> dict[str, str]:
+        """Converte string 'key=value,key2=value2' em dicionário."""
+        if isinstance(value, dict):
+            return value
+        if not value:
+            return {}
+
+        result: dict[str, str] = {}
+        for item in str(value).split(delimiter):
+            item = item.strip()
+            if "=" in item:
+                k, v = item.split("=", 1)
+                result[k.strip()] = v.strip()
+            elif item:
+                result[item] = ""
+        return result
+
+
+# ============================================================================
+# EnvLoader Principal
+# ============================================================================
+
+
+class EnvLoader:
+    """Gerenciador robusto de variáveis de ambiente e secrets.
+
+    Fornece interface type-safe para carregar, validar e converter variáveis
+    de ambiente e Docker secrets com suporte a cache e validação customizada.
+
+    Exemplo:
+        >>> loader = EnvLoader()
+        >>> db_host = loader.get("DATABASE_URL", required=True)
+        >>> debug = loader.get_bool("DEBUG", default=False)
+        >>> allowed_hosts = loader.get_list("ALLOWED_HOSTS", default=[])
+    """
+
+    _instance: EnvLoader | None = None
+    _initialized: bool = False
+
+    def __new__(cls, config: EnvConfig | None = None) -> EnvLoader:
+        """Implementa padrão Singleton (opcional)."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, config: EnvConfig | None = None) -> None:
+        """Inicializa o loader com configuração opcional.
+
+        Args:
+            config: Configuração customizada (None = configuração padrão)
+        """
+        # Evita reinicialização no padrão Singleton
+        if self._initialized:
+            return
+
+        self.config = config or EnvConfig()
+        self._secrets_cache: dict[str, str] = {}
+        self._load_env_file()
+        self._initialized = True
+
+    def _load_env_file(self) -> None:
+        """Carrega arquivo .env se especificado."""
+        if self.config.env_file:
+            env_path = Path(self.config.env_file)
+            if env_path.is_file():
+                load_dotenv(
+                    env_path,
+                    override=self.config.override_existing,
+                    encoding=self.config.encoding,
+                )
+                logger.debug(f"Arquivo .env carregado: {env_path}")
+            else:
+                msg = f"Arquivo .env não encontrado: {env_path}"
+                if self.config.strict_mode:
+                    raise FileNotFoundError(msg)
+                logger.warning(msg)
+        else:
+            load_dotenv(override=self.config.override_existing, encoding=self.config.encoding)
+
+    def _get_prefixed_key(self, key: str) -> str:
+        """Retorna a chave com prefixo aplicado."""
+        return (
+            f"{self.config.prefix}{key}"
+            if self.config.prefix and not key.startswith(self.config.prefix)
+            else key
+        )
+
+    def _read_secret_file(self, secret_path: Path) -> str | None:
+        """Lê conteúdo de arquivo secret com tratamento de erros."""
+        try:
+            if not secret_path.exists():
+                return None
+
+            content = secret_path.read_text(encoding=self.config.encoding).strip()
+            path_str = str(secret_path)
+
+            if self.config.cache_secrets:
+                self._secrets_cache[path_str] = content  # ← Armazena pelo caminho
+
+            logger.debug(f"Secret lido: {secret_path}")
+            return content
+
+        except (OSError, PermissionError) as e:
+            logger.error(f"Erro ao ler secret {secret_path}: {e}")
+            if self.config.strict_mode:
+                raise
+            return None
+
+    def _get_from_secret(self, key: str) -> str | None:
+        """Tenta obter valor de Docker secret."""
+        secret_path = self.config.secrets_dir / key
+        path_str = str(secret_path)
+
+        # Verifica cache primeiro (pelo caminho do arquivo)
+        if self.config.cache_secrets and path_str in self._secrets_cache:
+            return self._secrets_cache[path_str]
+
+        # Tenta ler do arquivo secret
+        return self._read_secret_file(secret_path)
+
+    def _get_from_env(self, key: str) -> str | None:
+        """Obtém valor de variável de ambiente."""
+        prefixed_key = self._get_prefixed_key(key)
+        return os.environ.get(prefixed_key)
+
+    @overload
+    def get(self, key: str, *, default: T, required: bool = False) -> str | T: ...
+
+    @overload
+    def get(self, key: str, *, default: None = None, required: bool = True) -> str: ...
+
+    def get(
+        self,
+        key: str,
+        *,
+        default: T | None = None,
+        required: bool = False,
+        use_secrets: bool = True,
+    ) -> str | T:
+        """Obtém variável de ambiente ou secret.
+
+        Args:
+            key: Nome da variável (sem prefixo)
+            default: Valor padrão se não encontrado
+            required: Se True, levanta SecretNotFoundError se não encontrado
+            use_secrets: Se deve buscar em Docker secrets
+
+        Returns:
+            Valor da variável ou default
+
+        Raises:
+            SecretNotFoundError: Se required=True e variável não encontrada
+        """
+        value: str | None = None
+        searched: list[str] = []
+
+        # Busca em secrets primeiro
+        if use_secrets:
+            value = self._get_from_secret(key)
+            searched.append(f"secret:{self.config.secrets_dir / key}")
+
+        # Fallback para variável de ambiente
+        if value is None:
+            value = self._get_from_env(key)
+            searched.append(f"env:{self._get_prefixed_key(key)}")
+
+        # Validação
+        if value is None or not value.strip():
+            if required:
+                raise SecretNotFoundError(key, searched)
+
+            if self.config.warn_on_missing and default is None:
+                warnings.warn(f"Variável '{key}' não encontrada", UserWarning, stacklevel=2)
+
+            return default if default is not None else ""
+
+        return value
+
+    def get_bool(
+        self,
+        key: str,
+        *,
+        default: bool = False,
+        required: bool = False,
+        use_secrets: bool = True,
+    ) -> bool:
+        """Obtém variável como boolean."""
+        value = self.get(key, default=str(default), required=required, use_secrets=use_secrets)
+        try:
+            return TypeConverter.to_bool(value)
+        except ValidationError as e:
+            if self.config.strict_mode:
+                raise
+            logger.warning(f"Erro ao converter '{key}' para bool: {e}. Usando default: {default}")
+            return default
+
+    def get_int(
+        self,
+        key: str,
+        *,
+        default: int = 0,
+        required: bool = False,
+        use_secrets: bool = True,
+    ) -> int:
+        """Obtém variável como inteiro."""
+        value = self.get(key, default=str(default), required=required, use_secrets=use_secrets)
+        try:
+            return TypeConverter.to_int(value)
+        except ValidationError as e:
+            if self.config.strict_mode:
+                raise
+            logger.warning(f"Erro ao converter '{key}' para int: {e}. Usando default: {default}")
+            return default
+
+    def get_float(
+        self,
+        key: str,
+        *,
+        default: float = 0.0,
+        required: bool = False,
+        use_secrets: bool = True,
+    ) -> float:
+        """Obtém variável como float."""
+        value = self.get(key, default=str(default), required=required, use_secrets=use_secrets)
+        try:
+            return TypeConverter.to_float(value)
+        except ValidationError as e:
+            if self.config.strict_mode:
+                raise
+            logger.warning(f"Erro ao converter '{key}' para float: {e}. Usando default: {default}")
+            return default
+
+    def get_list(
+        self,
+        key: str,
+        *,
+        default: list[str] | None = None,
+        delimiter: str = ",",
+        required: bool = False,
+        use_secrets: bool = True,
+    ) -> list[str]:
+        """Obtém variável como lista."""
+        if default is None:
+            default = []
+
+        # Tenta obter a variável sem valor padrão
+        value = self.get(key, default=None, required=False, use_secrets=use_secrets)
+
+        if value is None or value == "":
+            # Variável não existe ou é string vazia
+            if required:
+                raise SecretNotFoundError(key, [])
+            return default
+
+        # Variável existe, converte para lista
+        return TypeConverter.to_list(value, delimiter)
+
+    def get_dict(
+        self,
+        key: str,
+        *,
+        default: dict[str, str] | None = None,
+        delimiter: str = ",",
+        required: bool = False,
+        use_secrets: bool = True,
+    ) -> dict[str, str]:
+        """Obtém variável como dicionário."""
+        if default is None:
+            default = {}
+
+        # Tenta obter a variável sem valor padrão
+        value = self.get(key, default=None, required=False, use_secrets=use_secrets)
+
+        if value is None or value == "":
+            # Variável não existe ou é string vazia
+            if required:
+                raise SecretNotFoundError(key, [])
+            return default
+
+        # Variável existe, converte para dicionário
+        return TypeConverter.to_dict(value, delimiter)
+
+    def get_with_validator(
+        self,
+        key: str,
+        validator: Callable[[str], T],
+        *,
+        default: T | None = None,
+        required: bool = False,
+        use_secrets: bool = True,
+    ) -> T | None:
+        """Obtém variável com validação customizada.
+
+        Args:
+            key: Nome da variável
+            validator: Função que valida/converte o valor
+            default: Valor padrão
+            required: Se é obrigatória
+            use_secrets: Se deve buscar em secrets
+
+        Returns:
+            Valor validado ou default
+        """
+        value = self.get(key, default=None, required=required, use_secrets=use_secrets)
+        if value is None:
+            return default
+
+        try:
+            return validator(value)
+        except Exception as e:
+            if self.config.strict_mode:
+                raise ValidationError(key, value, str(e)) from e
+            logger.warning(f"Validação falhou para '{key}': {e}. Usando default")
+            return default
+
+    def is_set(self, key: str, *, use_secrets: bool = True) -> bool:
+        """Verifica se variável está definida e não vazia."""
+        try:
+            value = self.get(key, required=False, use_secrets=use_secrets)
+            return bool(value and str(value).strip())
+        except Exception:
+            return False
+
+    def get_all(self, *, include_secrets: bool = False) -> dict[str, str]:
+        """Retorna todas as variáveis carregadas.
+
+        Args:
+            include_secrets: Se deve incluir secrets em cache
+
+        Returns:
+            Dicionário com todas as variáveis
+        """
+        result = dict(os.environ)
+
+        if include_secrets and self.config.cache_secrets:
+            result.update(self._secrets_cache)
+
+        # Filtra por prefixo se configurado
+        if self.config.prefix:
+            result = {k: v for k, v in result.items() if k.startswith(self.config.prefix)}
+
+        return result
+
+    def clear_cache(self) -> None:
+        """Limpa o cache de secrets."""
+        self._secrets_cache.clear()
+        logger.debug("Cache de secrets limpo")
+
+    @classmethod
+    def reset_singleton(cls) -> None:
+        """Reset do singleton (útil para testes)."""
+        cls._instance = None
+        cls._initialized = False
+
+
+# ============================================================================
+# Utilitários para Django
+# ============================================================================
+
+
+class DjangoEnvLoader(EnvLoader):
+    """Loader especializado para projetos Django.
+
+    Fornece helpers específicos para configurações Django comuns.
+    """
+
+    def __init__(self, config: EnvConfig | None = None) -> None:
+        """Inicializa com defaults para Django."""
+        if config is None:
+            config = EnvConfig(prefix="DJANGO_", auto_cast=True)
+        super().__init__(config)
+
+    def get_database_url(self, default: str | None = None) -> str:
+        """Obtém DATABASE_URL com validação básica."""
+        url = self.get("DATABASE_URL", default=default, required=default is None)
+        # Validação básica de formato
+        if url and "://" not in url:
+            raise ValidationError(
+                "DATABASE_URL", url, "URL inválida (formato esperado: scheme://...)"
+            )
+        return url
+
+    def get_allowed_hosts(self) -> list[str]:
+        """Obtém ALLOWED_HOSTS como lista."""
+        return self.get_list("ALLOWED_HOSTS", default=["localhost", "127.0.0.1"])
+
+    def get_debug(self, default: bool = False) -> bool:
+        """Obtém DEBUG com segurança."""
+        return self.get_bool("DEBUG", default=default)
+
+    def get_secret_key(self) -> str:
+        """Obtém SECRET_KEY (sempre obrigatória)."""
+        return self.get("SECRET_KEY", required=True, use_secrets=True)

django_env_loader/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561
+# This empty file indicates that the django_env_loader package supports type checking

django_env_loader-1.0.3.dist-info/METADATA

@@ -0,0 +1,655 @@
+Metadata-Version: 2.4
+Name: django-env-loader
+Version: 1.0.3
+Summary: Gerenciador robusto de variáveis de ambiente e secrets para Django
+License: MIT
+License-File: LICENSE
+Keywords: django,env,environment,secrets,docker
+Author: Felipe Abreu
+Author-email: felipeabreu.rj@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Project-URL: Homepage, https://github.com/felipeabreu86/django-env-loader
+Project-URL: Repository, https://github.com/felipeabreu86/django-env-loader
+Description-Content-Type: text/markdown
+
+# Django Env Loader
+
+**Gerenciador robusto e type-safe de variáveis de ambiente para projetos Python e Django.**
+
+`django-env-loader` é uma biblioteca moderna que simplifica o gerenciamento de variáveis de ambiente e Docker secrets, oferecendo validação rigorosa, conversão automática de tipos e integração nativa com Django.
+
+---
+
+## ✨ Características
+
+- 🔒 **Type-safe**: Suporte completo a type hints e validação de tipos
+- 🐳 **Docker Secrets**: Suporte nativo a Docker secrets com fallback automático
+- ⚡ **Performance**: Sistema de cache inteligente para secrets
+- 🎯 **Django-ready**: Helpers especializados para configurações Django
+- 🛡️ **Validação robusta**: Conversores seguros com tratamento de erros
+- 🔧 **Configurável**: Prefixos, encoding, strict mode e muito mais
+- 📝 **Bem documentado**: Type hints completos e docstrings detalhadas
+- 🧪 **Testado**: Cobertura de testes > 95%
+
+---
+
+## 📦 Instalação
+
+```bash
+pip install django-env-loader
+```
+
+Para uso com Django (instala dependências adicionais):
+
+```bash
+pip install django-env-loader[django]
+```
+
+---
+
+## 🚀 Quick Start
+
+### Uso básico
+
+```python
+# Forma mais simples - usa instância singleton pré-configurada
+from django_env_loader import env_loader
+
+# Obtém variáveis simples
+api_key = env_loader.get("API_KEY", required=True)
+debug = env_loader.get_bool("DEBUG", default=False)
+port = env_loader.get_int("PORT", default=8000)
+
+# Listas e dicionários
+allowed_hosts = env_loader.get_list("ALLOWED_HOSTS", default=["localhost"])
+database_options = env_loader.get_dict("DB_OPTIONS")  # FORMAT: key1=val1,key2=val2
+```
+
+**Ou crie uma instância customizada:**
+
+```python
+from django_env_loader import EnvLoader, EnvConfig
+from pathlib import Path
+
+config = EnvConfig(env_file=Path(".env.production"), prefix="MYAPP_")
+loader = EnvLoader(config)
+```
+
+### Uso com Django
+
+```python
+# settings.py
+# Opção 1: Singleton simples
+from django_env_loader import env_loader
+
+SECRET_KEY = env_loader.get("SECRET_KEY", required=True)
+DEBUG = env_loader.get_bool("DEBUG", default=False)
+ALLOWED_HOSTS = env_loader.get_list("ALLOWED_HOSTS", default=["localhost"])
+
+# Opção 2: DjangoEnvLoader com helpers especializados
+from django_env_loader import DjangoEnvLoader
+
+env = DjangoEnvLoader()
+
+# Configurações Django com validação automática
+SECRET_KEY = env.get_secret_key()  # Obrigatória, busca em secrets primeiro
+DEBUG = env.get_debug(default=False)
+ALLOWED_HOSTS = env.get_allowed_hosts()
+DATABASE_URL = env.get_database_url()
+
+# Outras configurações
+DATABASES = {
+    'default': dj_database_url.parse(DATABASE_URL)
+}
+
+EMAIL_HOST = env.get("EMAIL_HOST", default="localhost")
+EMAIL_PORT = env.get_int("EMAIL_PORT", default=587)
+EMAIL_USE_TLS = env.get_bool("EMAIL_USE_TLS", default=True)
+```
+
+---
+
+## 📚 Documentação Completa
+
+### Configuração Avançada
+
+O `EnvLoader` aceita uma configuração personalizada através da classe `EnvConfig`:
+
+```python
+from django_env_loader import EnvLoader, EnvConfig
+from pathlib import Path
+
+config = EnvConfig(
+    env_file=Path(".env.production"),  # Arquivo .env customizado
+    secrets_dir=Path("/run/secrets"),  # Diretório de Docker secrets
+    encoding="utf-8",                  # Encoding dos arquivos
+    prefix="MYAPP_",                   # Prefixo para todas as variáveis
+    override_existing=False,           # Não sobrescreve vars já definidas
+    auto_cast=True,                    # Conversão automática de tipos
+    cache_secrets=True,                # Cache de secrets
+    strict_mode=False,                 # False = warnings, True = exceções
+    warn_on_missing=True,              # Avisa sobre variáveis não encontradas
+)
+
+loader = EnvLoader(config)
+```
+
+### Métodos de Obtenção de Variáveis
+
+#### `get()` - Método base
+
+```python
+# Obter string simples
+value = loader.get("MY_VAR", default="default_value")
+
+# Obrigatória (levanta SecretNotFoundError se não encontrada)
+value = loader.get("REQUIRED_VAR", required=True)
+
+# Sem buscar em Docker secrets
+value = loader.get("ENV_ONLY", use_secrets=False)
+```
+
+#### `get_bool()` - Booleanos
+
+Aceita múltiplos formatos: `true/false`, `1/0`, `yes/no`, `on/off`, `sim/não`
+
+```python
+debug = loader.get_bool("DEBUG", default=False)
+maintenance = loader.get_bool("MAINTENANCE_MODE", required=True)
+
+# Valores aceitos para True
+# "true", "1", "yes", "y", "on", "t", "sim", "s"
+
+# Valores aceitos para False
+# "false", "0", "no", "n", "off", "f", "não", "nao", ""
+```
+
+#### `get_int()` - Números inteiros
+
+```python
+port = loader.get_int("PORT", default=8000)
+workers = loader.get_int("WORKERS", required=True)
+timeout = loader.get_int("TIMEOUT", default=30)
+```
+
+#### `get_float()` - Números decimais
+
+```python
+tax_rate = loader.get_float("TAX_RATE", default=0.15)
+temperature = loader.get_float("MAX_TEMP", default=98.6)
+```
+
+#### `get_list()` - Listas
+
+```python
+# Formato: item1,item2,item3
+hosts = loader.get_list("ALLOWED_HOSTS", default=["localhost"])
+
+# Delimitador customizado
+emails = loader.get_list("ADMIN_EMAILS", delimiter=";")
+
+# De variável de ambiente:
+# ALLOWED_HOSTS=example.com,api.example.com,www.example.com
+# Resultado: ["example.com", "api.example.com", "www.example.com"]
+```
+
+#### `get_dict()` - Dicionários
+
+```python
+# Formato: key1=value1,key2=value2
+options = loader.get_dict("DB_OPTIONS")
+
+# Delimitador customizado
+config = loader.get_dict("FEATURE_FLAGS", delimiter=";")
+
+# De variável de ambiente:
+# DB_OPTIONS=timeout=30,pool_size=10,ssl=true
+# Resultado: {"timeout": "30", "pool_size": "10", "ssl": "true"}
+```
+
+#### `get_with_validator()` - Validação customizada
+
+```python
+from typing import Callable
+from datetime import datetime
+
+# Validador de email
+def validate_email(value: str) -> str:
+    if "@" not in value:
+        raise ValueError(f"Email inválido: {value}")
+    return value.lower()
+
+admin_email = loader.get_with_validator(
+    "ADMIN_EMAIL",
+    validator=validate_email,
+    required=True
+)
+
+# Validador de data
+def parse_date(value: str) -> datetime:
+    return datetime.fromisoformat(value)
+
+launch_date = loader.get_with_validator(
+    "LAUNCH_DATE",
+    validator=parse_date,
+    default=datetime.now()
+)
+
+# Validador de URL
+def validate_url(value: str) -> str:
+    if not value.startswith(("http://", "https://")):
+        raise ValueError(f"URL deve começar com http:// ou https://")
+    return value.rstrip("/")
+
+api_url = loader.get_with_validator(
+    "API_URL",
+    validator=validate_url,
+    required=True
+)
+```
+
+### Docker Secrets
+
+O loader busca automaticamente em Docker secrets antes de tentar variáveis de ambiente:
+
+```python
+# Ordem de busca:
+# 1. /run/secrets/DATABASE_PASSWORD (Docker secret)
+# 2. DATABASE_PASSWORD (variável de ambiente)
+
+db_password = loader.get("DATABASE_PASSWORD", required=True, use_secrets=True)
+```
+
+**Exemplo com Docker Compose:**
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  web:
+    image: myapp:latest
+    secrets:
+      - db_password
+      - secret_key
+    environment:
+      - DEBUG=false
+      - DATABASE_HOST=db
+
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+  secret_key:
+    file: ./secrets/secret_key.txt
+```
+
+```python
+# settings.py
+from django_env_loader import DjangoEnvLoader
+
+env = DjangoEnvLoader()
+
+# Busca automaticamente em /run/secrets/SECRET_KEY
+SECRET_KEY = env.get_secret_key()
+
+# Busca em /run/secrets/DATABASE_PASSWORD
+db_password = env.get("DATABASE_PASSWORD", required=True)
+```
+
+### Verificação de Variáveis
+
+```python
+# Verifica se variável existe e não está vazia
+if loader.is_set("FEATURE_FLAG"):
+    enable_feature()
+
+# Obtém todas as variáveis carregadas
+all_vars = loader.get_all(include_secrets=False)
+print(all_vars)
+```
+
+### Gerenciamento de Cache
+
+```python
+# Limpar cache de secrets (útil para recarregar valores)
+loader.clear_cache()
+
+# Reset completo do singleton (útil em testes)
+from django_env_loader import EnvLoader
+EnvLoader.reset_singleton()
+```
+
+---
+
+## 🎯 Casos de Uso Comuns
+
+### 1. Configuração Multi-ambiente
+
+```python
+# .env.development
+DEBUG=true
+DATABASE_URL=sqlite:///db.sqlite3
+ALLOWED_HOSTS=localhost,127.0.0.1
+
+# .env.production
+DEBUG=false
+DATABASE_URL=postgresql://user:pass@db:5432/mydb
+ALLOWED_HOSTS=myapp.com,www.myapp.com
+```
+
+```python
+# settings.py
+import os
+from pathlib import Path
+from django_env_loader import env_loader, EnvLoader, EnvConfig
+
+# Opção 1: Usando singleton com config customizada
+ENVIRONMENT = os.getenv("ENVIRONMENT", "development")
+env_file = Path(f".env.{ENVIRONMENT}")
+
+# Reconfigura o singleton (faça isso antes de qualquer uso)
+EnvLoader.reset_singleton()
+config = EnvConfig(env_file=env_file, strict_mode=True)
+env = EnvLoader(config)
+
+# Opção 2: Criar nova instância (não recomendado se usar singleton em outros lugares)
+# config = EnvConfig(env_file=env_file, strict_mode=True)
+# env = EnvLoader(config)
+
+DEBUG = env.get_bool("DEBUG")
+DATABASE_URL = env.get("DATABASE_URL", required=True)
+ALLOWED_HOSTS = env.get_list("ALLOWED_HOSTS")
+```
+
+### 2. Validação de Configurações Obrigatórias
+
+```python
+from django_env_loader import env_loader, SecretNotFoundError
+
+try:
+    # Garante que variáveis críticas existem
+    api_key = env_loader.get("API_KEY", required=True)
+    secret_key = env_loader.get("SECRET_KEY", required=True)
+    database_url = env_loader.get("DATABASE_URL", required=True)
+
+except SecretNotFoundError as e:
+    print(f"❌ Configuração faltando: {e}")
+    print(f"   Locais buscados: {e.searched_locations}")
+    import sys
+    sys.exit(1)
+```
+
+### 3. Feature Flags
+
+```python
+# .env
+FEATURE_FLAGS=new_ui=true,beta_api=false,analytics=true
+
+# app.py
+from django_env_loader import env_loader
+
+features = env_loader.get_dict("FEATURE_FLAGS")
+
+if features.get("new_ui") == "true":
+    enable_new_ui()
+
+if features.get("beta_api") == "true":
+    enable_beta_api()
+```
+
+### 4. Configuração de Múltiplos Serviços
+
+```python
+from django_env_loader import EnvLoader, EnvConfig
+
+# Serviço de email
+email_config = EnvConfig(prefix="EMAIL_")
+email_loader = EnvLoader(email_config)
+
+EMAIL_CONFIG = {
+    "host": email_loader.get("HOST", default="localhost"),
+    "port": email_loader.get_int("PORT", default=587),
+    "username": email_loader.get("USERNAME"),
+    "password": email_loader.get("PASSWORD", use_secrets=True),
+    "use_tls": email_loader.get_bool("USE_TLS", default=True),
+}
+
+# Serviço de cache
+cache_config = EnvConfig(prefix="REDIS_")
+cache_loader = EnvLoader(cache_config)
+
+REDIS_CONFIG = {
+    "host": cache_loader.get("HOST", default="localhost"),
+    "port": cache_loader.get_int("PORT", default=6379),
+    "db": cache_loader.get_int("DB", default=0),
+    "password": cache_loader.get("PASSWORD", use_secrets=True),
+}
+```
+
+### 5. Integração com Pydantic Settings
+
+```python
+from pydantic_settings import BaseSettings
+from django_env_loader import env_loader
+
+class Settings(BaseSettings):
+    app_name: str = env_loader.get("APP_NAME", default="MyApp")
+    debug: bool = env_loader.get_bool("DEBUG", default=False)
+    database_url: str = env_loader.get("DATABASE_URL", required=True)
+    secret_key: str = env_loader.get("SECRET_KEY", required=True)
+    allowed_hosts: list[str] = env_loader.get_list("ALLOWED_HOSTS")
+
+    class Config:
+        case_sensitive = False
+
+settings = Settings()
+```
+
+---
+
+## 🔒 Segurança
+
+### Boas Práticas
+
+1. **Nunca commite arquivos `.env`** com dados sensíveis
+   ```bash
+   # .gitignore
+   .env
+   .env.*
+   !.env.example
+   ```
+
+2. **Use Docker secrets** para dados sensíveis em produção
+   ```python
+   # Prioriza secrets sobre env vars
+   secret_key = loader.get("SECRET_KEY", use_secrets=True, required=True)
+   ```
+
+3. **Valide configurações** no startup
+   ```python
+   # manage.py ou app startup
+   from django_env_loader import DjangoEnvLoader, SecretNotFoundError
+
+   env = DjangoEnvLoader()
+
+   try:
+       env.get_secret_key()
+       env.get_database_url()
+   except SecretNotFoundError as e:
+       logger.critical(f"Configuração crítica faltando: {e}")
+       sys.exit(1)
+   ```
+
+4. **Use strict_mode** em produção
+   ```python
+   config = EnvConfig(strict_mode=True)
+   loader = EnvLoader(config)
+   # Agora erros de validação levantam exceções em vez de warnings
+   ```
+
+---
+
+## 🧪 Testes
+
+### Testando código que usa EnvLoader
+
+```python
+import pytest
+from django_env_loader import EnvLoader, EnvConfig
+from pathlib import Path
+
+@pytest.fixture
+def loader():
+    """Fixture que cria loader limpo para cada teste."""
+    EnvLoader.reset_singleton()
+    config = EnvConfig(env_file=Path("tests/.env.test"))
+    return EnvLoader(config)
+
+def test_get_database_url(loader, monkeypatch):
+    """Testa obtenção de DATABASE_URL."""
+    monkeypatch.setenv("DATABASE_URL", "postgresql://localhost/testdb")
+
+    url = loader.get("DATABASE_URL", required=True)
+    assert url == "postgresql://localhost/testdb"
+
+def test_missing_required_variable(loader):
+    """Testa erro ao buscar variável obrigatória inexistente."""
+    from django_env_loader import SecretNotFoundError
+
+    with pytest.raises(SecretNotFoundError) as exc_info:
+        loader.get("NONEXISTENT", required=True)
+
+    assert "NONEXISTENT" in str(exc_info.value)
+
+def test_bool_conversion(loader, monkeypatch):
+    """Testa conversão de valores booleanos."""
+    monkeypatch.setenv("FEATURE_ENABLED", "true")
+    assert loader.get_bool("FEATURE_ENABLED") is True
+
+    monkeypatch.setenv("FEATURE_DISABLED", "0")
+    assert loader.get_bool("FEATURE_DISABLED") is False
+```
+
+---
+
+## 📖 API Reference
+
+### Classes Principais
+
+#### `EnvLoader`
+Gerenciador principal de variáveis de ambiente.
+
+**Métodos:**
+- `get(key, *, default, required, use_secrets)` → `str | T`
+- `get_bool(key, *, default, required, use_secrets)` → `bool`
+- `get_int(key, *, default, required, use_secrets)` → `int`
+- `get_float(key, *, default, required, use_secrets)` → `float`
+- `get_list(key, *, default, delimiter, required, use_secrets)` → `list[str]`
+- `get_dict(key, *, default, delimiter, required, use_secrets)` → `dict[str, str]`
+- `get_with_validator(key, validator, *, default, required, use_secrets)` → `T | None`
+- `is_set(key, *, use_secrets)` → `bool`
+- `get_all(*, include_secrets)` → `dict[str, str]`
+- `clear_cache()` → `None`
+- `reset_singleton()` → `None` (class method)
+
+#### `DjangoEnvLoader`
+Subclasse especializada para Django.
+
+**Métodos adicionais:**
+- `get_database_url(default)` → `str`
+- `get_allowed_hosts()` → `list[str]`
+- `get_debug(default)` → `bool`
+- `get_secret_key()` → `str`
+
+#### `EnvConfig`
+Configuração do EnvLoader.
+
+**Atributos:**
+- `env_file: Path | str | None`
+- `secrets_dir: Path`
+- `encoding: str`
+- `prefix: str`
+- `override_existing: bool`
+- `auto_cast: bool`
+- `cache_secrets: bool`
+- `strict_mode: bool`
+- `warn_on_missing: bool`
+
+### Exceções
+
+#### `SecretNotFoundError`
+Levantada quando um secret obrigatório não é encontrado.
+
+**Atributos:**
+- `key: str` - Nome da variável
+- `searched_locations: list[str]` - Locais onde foi buscada
+
+#### `ValidationError`
+Levantada quando a validação de uma variável falha.
+
+**Atributos:**
+- `key: str` - Nome da variável
+- `value: Any` - Valor que falhou na validação
+- `reason: str` - Motivo da falha
+
+---
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor:
+
+1. Faça um fork do projeto
+2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
+3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
+4. Push para a branch (`git push origin feature/AmazingFeature`)
+5. Abra um Pull Request
+
+### Diretrizes de Desenvolvimento
+
+- Escreva testes para novas funcionalidades
+- Mantenha cobertura de testes > 95%
+- Use type hints em todo o código
+- Siga o guia de estilo PEP 8
+- Atualize a documentação
+
+---
+
+## 📝 Changelog
+
+Veja o arquivo [CHANGELOG](CHANGELOG.md) para histórico de mudanças.
+
+---
+
+## 📄 Licença
+
+Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
+
+---
+
+## 📬 Suporte
+
+- **Issues**: [GitHub Issues](https://github.com/felipeabreu86/django-env-loader/issues)
+- **Discussões**: [GitHub Discussions](https://github.com/felipeabreu86/django-env-loader/discussions)
+
+---
+
+## 🔗 Links Úteis
+
+- [PyPI](https://pypi.org/project/django-env-loader/)
+- [Código fonte](https://github.com/felipeabreu86/django-env-loader)
+- [Exemplos](https://github.com/felipeabreu86/django-env-loader/tree/main/examples)
+

django_env_loader-1.0.3.dist-info/RECORD

@@ -0,0 +1,8 @@
+django_env_loader/__init__.py,sha256=F6T6o86XwoJmrokaiBxul2howm0iIUvmLqxFFbqPE3U,578
+django_env_loader/exceptions.py,sha256=ewHeViHT7dKR4fe7MXx6pytsJyOFSY4WyhLrDUECybI,1117
+django_env_loader/loader.py,sha256=SPkCbLL-yDn5oQ08vyvGsWgMv9S2d1KeF7YzS-3wA9o,17517
+django_env_loader/py.typed,sha256=-VPOUwqsDZdR7p-C4JfqXoX-f-VI-cz8NL4iSwj0FQ4,111
+django_env_loader-1.0.3.dist-info/licenses/LICENSE,sha256=jD4BZSgz5L_C_XAhg2Ny7GlWVv8D7__c1qSQxq12eeo,1068
+django_env_loader-1.0.3.dist-info/METADATA,sha256=PULvqQxh_7iaOh-Uvw1yEeQYk0OcAoUvd9bwBzOyP5w,17711
+django_env_loader-1.0.3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+django_env_loader-1.0.3.dist-info/RECORD,,

django_env_loader-1.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

django_env_loader-1.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Felipe Abreu
+
+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.