djresttoolkit 0.7.0__tar.gz → 0.8.0__tar.gz

{djresttoolkit-0.7.0 → djresttoolkit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.7.0
+Version: 0.8.0
 Summary: A collection of Django and DRF utilities to simplify API development.
 Project-URL: Homepage, https://github.com/shaileshpandit141/djresttoolkit
 Project-URL: Documentation, https://shaileshpandit141.github.io/djresttoolkit
@@ -47,7 +47,9 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
 Requires-Dist: faker>=37.5.3
+Requires-Dist: pydantic-settings>=2.10.1
 Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyyaml>=6.0.2
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
@@ -201,7 +203,72 @@ or
 Flushed 120 records from all models and reset IDs.
 ```
 
-### 3. EmailSender
+### 3. EnvBaseSettings
+
+```python
+from djresttoolkit.envconfig import EnvBaseSettings
+```
+
+#### `EnvBaseSettings`
+
+A **base settings class** for managing application configuration using:
+
+- YAML files (default `.environ.yaml`)
+- Environment variables (default `.env`)
+
+Supports **nested configuration** using double underscores (`__`) in environment variable names.
+
+#### Class Attributes
+
+| Attribute      | Type                 | Default         | Description                                                        |
+| -------------- | -------------------- | --------------- | ------------------------------------------------------------------ |
+| `env_file`     | `str`                | `.env`          | Environment variable file path.                                    |
+| `yaml_file`    | `str`                | `.environ.yaml` | YAML configuration file path.                                      |
+| `model_config` | `SettingsConfigDict` | —               | Pydantic settings configuration (file encoding, nested delimiter). |
+
+#### Methods
+
+#### `load(cls, *, env_file: str | None = None, ymal_file: str | None = None, warning: bool = True) -> EnvBaseSettings`
+
+Loads configuration from **YAML first**, then overrides with **environment variables**.
+
+#### Parameters
+
+- `env_file` — Optional custom `.env` file path.
+- `ymal_file` — Optional custom YAML file path.
+- `warning` — Emit a warning if YAML file is missing (default `True`).
+
+#### Returns
+
+- Instance of `EnvBaseSettings` (or subclass) with loaded configuration.
+
+#### Raises
+
+- `UserWarning` if YAML file not found and `warning=True`.
+
+### Usage Example
+
+```python
+from djresttoolkit.envconfig import EnvBaseSettings
+
+class EnvSettings(EnvBaseSettings):
+    debug: bool = False
+    database_url: str
+
+# Load settings
+settings = EnvSettings.load(warning=False)
+
+print(settings.debug)
+print(settings.database_url)
+```
+
+#### Features
+
+- Prioritizes `.env` variables over YAML.
+- Supports nested keys: `DATABASE__HOST` → `settings.database.host`.
+- Designed to be subclassed for project-specific settings.
+
+### 4. EmailSender
 
 ```python
 from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate
@@ -217,7 +284,7 @@ Send templated emails.
 EmailSender(email_content: EmailContent | EmailContentDict)
 ```
 
-#### Methods
+#### EmailSender Methods
 
 ```python
 send(to: list[str], exceptions: bool = False) -> bool
@@ -250,7 +317,7 @@ EmailSender(content).send(to=["user@example.com"])
 
 - `text`, `html` — template file paths
 
-### 4. Custom DRF Exception Handler
+### 5. Custom DRF Exception Handler
 
 ```python
 from djresttoolkit.views import exception_handler
@@ -264,12 +331,12 @@ A DRF exception handler that:
 - Adds throttling support (defaults to `AnonRateThrottle`).
 - Returns **429 Too Many Requests** with `retry_after` if throttle limit is exceeded.
 
-#### Parameters
+#### Exception Handler Parameters
 
 - `exc`: Exception object.
 - `context`: DRF context dictionary containing `"request"` and `"view"`.
 
-#### Returns
+#### Returns Type of Exception Handler
 
 - `Response` — DRF Response object (with throttling info if applicable), or `None`.
 
@@ -290,7 +357,7 @@ REST_FRAMEWORK = {
 - Tracks requests in cache and calculates `retry_after`.
 - Cleans expired timestamps automatically.
 
-### 5. Response Time Middleware
+### 6. Response Time Middleware
 
 ```python
 from djresttoolkit.middlewares import ResponseTimeMiddleware
@@ -337,7 +404,7 @@ X-Response-Time: 0.01234 seconds
 INFO: Request processed in 0.01234 seconds
 ```
 
-### 6. Throttle Utilities
+### 7. Throttle Utilities
 
 #### `ThrottleInfoJSONRenderer`
 

{djresttoolkit-0.7.0 → djresttoolkit-0.8.0}/README.md

@@ -145,7 +145,72 @@ or
 Flushed 120 records from all models and reset IDs.
 ```
 
-### 3. EmailSender
+### 3. EnvBaseSettings
+
+```python
+from djresttoolkit.envconfig import EnvBaseSettings
+```
+
+#### `EnvBaseSettings`
+
+A **base settings class** for managing application configuration using:
+
+- YAML files (default `.environ.yaml`)
+- Environment variables (default `.env`)
+
+Supports **nested configuration** using double underscores (`__`) in environment variable names.
+
+#### Class Attributes
+
+| Attribute      | Type                 | Default         | Description                                                        |
+| -------------- | -------------------- | --------------- | ------------------------------------------------------------------ |
+| `env_file`     | `str`                | `.env`          | Environment variable file path.                                    |
+| `yaml_file`    | `str`                | `.environ.yaml` | YAML configuration file path.                                      |
+| `model_config` | `SettingsConfigDict` | —               | Pydantic settings configuration (file encoding, nested delimiter). |
+
+#### Methods
+
+#### `load(cls, *, env_file: str | None = None, ymal_file: str | None = None, warning: bool = True) -> EnvBaseSettings`
+
+Loads configuration from **YAML first**, then overrides with **environment variables**.
+
+#### Parameters
+
+- `env_file` — Optional custom `.env` file path.
+- `ymal_file` — Optional custom YAML file path.
+- `warning` — Emit a warning if YAML file is missing (default `True`).
+
+#### Returns
+
+- Instance of `EnvBaseSettings` (or subclass) with loaded configuration.
+
+#### Raises
+
+- `UserWarning` if YAML file not found and `warning=True`.
+
+### Usage Example
+
+```python
+from djresttoolkit.envconfig import EnvBaseSettings
+
+class EnvSettings(EnvBaseSettings):
+    debug: bool = False
+    database_url: str
+
+# Load settings
+settings = EnvSettings.load(warning=False)
+
+print(settings.debug)
+print(settings.database_url)
+```
+
+#### Features
+
+- Prioritizes `.env` variables over YAML.
+- Supports nested keys: `DATABASE__HOST` → `settings.database.host`.
+- Designed to be subclassed for project-specific settings.
+
+### 4. EmailSender
 
 ```python
 from djresttoolkit.mail import EmailSender, EmailContent, EmailTemplate
@@ -161,7 +226,7 @@ Send templated emails.
 EmailSender(email_content: EmailContent | EmailContentDict)
 ```
 
-#### Methods
+#### EmailSender Methods
 
 ```python
 send(to: list[str], exceptions: bool = False) -> bool
@@ -194,7 +259,7 @@ EmailSender(content).send(to=["user@example.com"])
 
 - `text`, `html` — template file paths
 
-### 4. Custom DRF Exception Handler
+### 5. Custom DRF Exception Handler
 
 ```python
 from djresttoolkit.views import exception_handler
@@ -208,12 +273,12 @@ A DRF exception handler that:
 - Adds throttling support (defaults to `AnonRateThrottle`).
 - Returns **429 Too Many Requests** with `retry_after` if throttle limit is exceeded.
 
-#### Parameters
+#### Exception Handler Parameters
 
 - `exc`: Exception object.
 - `context`: DRF context dictionary containing `"request"` and `"view"`.
 
-#### Returns
+#### Returns Type of Exception Handler
 
 - `Response` — DRF Response object (with throttling info if applicable), or `None`.
 
@@ -234,7 +299,7 @@ REST_FRAMEWORK = {
 - Tracks requests in cache and calculates `retry_after`.
 - Cleans expired timestamps automatically.
 
-### 5. Response Time Middleware
+### 6. Response Time Middleware
 
 ```python
 from djresttoolkit.middlewares import ResponseTimeMiddleware
@@ -281,7 +346,7 @@ X-Response-Time: 0.01234 seconds
 INFO: Request processed in 0.01234 seconds
 ```
 
-### 6. Throttle Utilities
+### 7. Throttle Utilities
 
 #### `ThrottleInfoJSONRenderer`
 

{djresttoolkit-0.7.0 → djresttoolkit-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "djresttoolkit"
-version = "0.7.0"
+version = "0.8.0"
 description = "A collection of Django and DRF utilities to simplify API development."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }
@@ -48,6 +48,8 @@ requires-python = ">=3.13"
 dependencies = [
     "faker>=37.5.3",
     "pydantic>=2.11.7",
+    "pydantic-settings>=2.10.1",
+    "pyyaml>=6.0.2",
 ]
 
 # CLI scripts entry point configuration

djresttoolkit-0.8.0/src/djresttoolkit/envconfig/__init__.py

@@ -0,0 +1,3 @@
+from ._env_settings import EnvBaseSettings
+
+__all__ = ["EnvBaseSettings"]

djresttoolkit-0.8.0/src/djresttoolkit/envconfig/_env_settings.py

@@ -0,0 +1,84 @@
+import warnings
+from pathlib import Path
+from typing import Any, ClassVar
+
+import yaml
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class EnvBaseSettings(BaseSettings):
+    """ "
+    EnvBaseSettings is a base settings class for managing application configuration
+    using both YAML files and environment variables.
+    This class is designed to load configuration values from a YAML file first,
+    and then override those values with environment variables if present. It supports
+    nested configuration using a double underscore (`__`) as the delimiter in
+    environment variable names, allowing for hierarchical settings.
+
+    Class Attributes:
+        env_file (str): The default filename for the environment variables file (default: ".env").
+        yaml_file (str): The default filename for the YAML configuration file (default: ".environ.yaml").
+        model_config (SettingsConfigDict): Configuration for environment variable parsing, including file encoding and nested delimiter.
+
+    Methods:
+        load(cls, *, env_file: str | None = None, ymal_file: str | None = None, warning: bool = True) -> "EnvBaseSettings":
+            Loads configuration from a YAML file (if it exists), then overrides with environment variables.
+            - env_file: Optional custom path to the .env file.
+            - ymal_file: Optional custom path to the YAML file.
+            - warning: If True, emits a warning if the YAML file is not found.
+            Returns an instance of EnvBaseSettings with the loaded configuration.
+
+    Usage:
+        - Define your settings as subclasses of EnvBaseSettings.
+        - Call `YourSettingsClass.load()` to load configuration from files and environment variables.
+        - Supports nested configuration via double underscore in environment variable names (e.g., `DATABASE__HOST`).
+
+    Raises:
+        - UserWarning: If the YAML file is not found and `warning` is True.
+
+    Example:
+    ```python
+        from djresttoolkit.envconfig import EnvBaseSettings
+        
+        class EnvSettings(EnvBaseSettings):
+            debug: bool = False
+            database_url: str
+            
+        settings = EnvSettings.load(warning=False)
+    ```
+
+    """
+
+    env_file: ClassVar[str] = ".env"
+    yaml_file: ClassVar[str] = ".environ.yaml"
+
+    model_config = SettingsConfigDict(
+        env_file=env_file,
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+    )
+
+    @classmethod
+    def load(
+        cls,
+        *,
+        env_file: str | None = None,
+        ymal_file: str | None = None,
+        warning: bool = True,
+    ) -> "EnvBaseSettings":
+        """Load from YAML first, then override with .env."""
+        if env_file:
+            cls.env_file = env_file
+        if ymal_file:
+            cls.yaml_file = ymal_file
+
+        config_file = Path(cls.yaml_file)
+        yaml_data: dict[str, Any] = {}
+        if config_file.exists():
+            with config_file.open("r") as f:
+                yaml_data = yaml.safe_load(f) or {}
+        elif warning:
+            msg: str = f"Config file {config_file} not found, using only env vars."
+            warnings.warn(msg, UserWarning, stacklevel=1)
+
+        return cls(**yaml_data)