full documentation

Author: HMohammad2520

README.md

@@ -6,14 +6,15 @@
 
 All features are well documented and use a high level of `type_hints` for easy understanding and usage.
 
-## Features
+## Features 
 
-* `ConstantAttrib`: A descriptor that acts like a constant. Once set, the value cannot be changed. Raises `AttributeError` on change detection.
-* `RemoteAttrib`: A descriptor that acts as a remote attribute. You can modify the mapped value on-the-fly.
-* `ENVMod`: The main API class for managing `.env` variables. Supports manual and decorator-based registration of environment items, type-safe value loading, and `.env_example` generation.
-* `MethodMonitor`: A class to monitor method calls of a target class, triggering a handler function after the method is called.
-* `logwrap`: A dynamic decorator to log function calls. Uses the `logging` module with your current project configurations.
-* `suppress_errors`: A decorator that suppresses exceptions raised by the wrapped function and returns a fallback value instead.
+>(***Click names for more information***)
+* [`ConstantAttrib`](docs\constant_attrib.md): A descriptor that acts like a constant. Once set, the value cannot be changed. Raises `AttributeError` on change detection.
+* [`RemoteAttrib`](docs\remote_attrib.md): A descriptor that acts as a remote attribute. You can modify the mapped value on-the-fly.
+* [`ENVMod`](docs\env_mod.md): The main API class for managing `.env` variables. Supports manual and decorator-based registration of environment items, type-safe value loading, and `.env_example` generation.
+* [`MethodMonitor`](docs\method_monitor.md): A class to monitor method calls of a target class, triggering a handler function after the method is called.
+* [`logwrap`](docs\logwrap.md): A dynamic decorator to log function calls. Uses the `logging` module with your current project configurations.
+* [`suppress_errors`](docs\supress_errors.md): A decorator that suppresses exceptions raised by the wrapped function and returns a fallback value instead.
 
 ## Installation
 
@@ -29,150 +30,6 @@ pip install classmods
 pip install git+https://github.com/hmohammad2520-org/classmods
 ```
 
-## Examples
-
-### Constant Attribute
-
-```python
-from classmods import ConstantAttrib
-
-class Config:
-    app_name = ConstantAttrib[str]()
-
-    def __init__(self, app_name):
-        self.app_name = app_name
-
-config = Config('new app')
-config.app_name = 'my app'  # This will raise AttributeError
-```
-
-### Remote Attribute
-
-```python
-import requests
-from classmods import RemoteAttrib
-
-class Config:
-    token = RemoteAttrib[str](
-        get=lambda: requests.get("https://api.example.com/auth").json()["token"],
-        cache_timeout=10,  # keeps result for 10 seconds
-    )
-
-config = Config()
-token = config.token  # This will send a request and return the result
-```
-
-### ENVMod
-
-```python
-from os import PathLike
-from requests import Session
-from classmods import ENVMod
-
-class Config:
-    ENVMod.register(exclude=['session'], cast={'log_path': str})
-    def __init__(
-        self,
-        app_name: str,
-        session: Session,  # Excluded non-parsable object
-        log_path: PathLike,
-        log_level: Optional[str] = None,
-        port: int = 10,
-    ):
-        '''
-        Args:
-            app_name (str): Application name.
-            session (Session): Requests session.
-            log_path (PathLike): Path of log file.
-            log_level (Optional[str]): Log level, e.g., info.
-            port (int): Session port, defaults to 10.
-        '''
-
-ENVMod.save_example('.my_example_path')
-ENVMod.load_dotenv('.my_env')
-ENVMod.sync_env_file('.my_env')
-```
-
-#### Recommended (Type-safe, IDE-friendly) Argument Loading
-
-```python
-config = Config(**ENVMod.load_args(Config.__init__), session=Session())
-```
-
-**Why this is recommended:**
-
-* Full IDE autocompletion
-* No static type checker errors
-* Explicit and predictable behavior
-* Best for libraries, frameworks, production code
-
----
-
-#### Convenience Mode (Runtime Magic) Argument Loading
-
-```python
-config = Config(envmod_loader, session=Session()) #type: ignore
-```
-
-**What this does:**
-
-* Automatically loads environment variables
-* Injects them into `__init__`
-* Overrides missing arguments
-
-**Why `# type: ignore` is required:**
-
-* Static analyzers cannot infer runtime argument injection
-* This is intentional and documented behavior
-
-
-### Method Monitor
-
-```python
-from classmods import MethodMonitor
-
-class MyClass:
-    def my_method(self):
-        pass
-
-def my_handler(instance):
-    print(f"Monitor triggered on {instance}")
-
-monitor = MethodMonitor(MyClass, my_handler, target_method='my_method')
-obj = MyClass()
-obj.my_method()
-```
-
-### logwrap
-
-```python
-from classmods import logwrap
-
-@logwrap(before=('INFO', '{func} starting, args={args} kwargs={kwargs}'), after=('INFO', '{func} ended'))
-def my_func(my_arg, my_kwarg=None):
-    ...
-
-my_func('hello', my_kwarg=123)  # Check logs to see the output
-```
-
-### Suppress Errors
-
-```python
-from classmods import suppress_errors
-
-@suppress_errors(Exception)
-def risky_op() -> int:
-    return 1 / 0
-
-result = risky_op()  # result = ZeroDivisionError
-
-@suppress_errors(False)
-def safe_op() -> bool:
-    raise ValueError("error")
-
-result = safe_op()  # result = False
-```
-
 ## License
 
 MIT License

docs/constant_attrib.md

@@ -0,0 +1,151 @@
+## `ConstantAttrib` Descriptor
+
+### Overview
+
+`ConstantAttrib` is a **data descriptor** that enforces **write-once (constant) attributes at the instance level**.
+
+Once a value is assigned:
+
+* It **cannot be reassigned**
+* It **cannot be deleted**
+* Access before assignment raises an error
+
+This is useful when you want:
+
+* Immutable instance configuration
+* Late initialization with safety
+* Explicit, self-documenting constants without `@property` boilerplate
+
+---
+
+## Key Characteristics
+
+* Enforced **per instance**
+* Allows **exactly one assignment**
+* Read-only after initialization
+* Works cleanly with static type checkers (Pylance, MyPy)
+* Does **not** allow class-level assignment
+
+---
+
+## Basic Usage
+
+```python
+class MyClass:
+    VALUE = ConstantAttrib()
+
+obj = MyClass()
+obj.VALUE = 42       # OK
+print(obj.VALUE)     # 42
+
+obj.VALUE = 10       # AttributeError
+del obj.VALUE        # AttributeError
+```
+
+---
+
+## Behavior Summary
+
+| Operation                | Result             |
+| ------------------------ | ------------------ |
+| First assignment         | Allowed            |
+| Second assignment        | ❌ `AttributeError` |
+| Access before assignment | ❌ `AttributeError` |
+| Deletion                 | ❌ `AttributeError` |
+| Class-level access       | Returns descriptor |
+
+---
+
+## Typing & Static Analysis
+
+Because `ConstantAttrib` is generic:
+
+```python
+class Config:
+    PORT = ConstantAttrib[int]()
+```
+
+Type checkers infer:
+
+```python
+config.PORT  # int
+```
+
+This works without casts or `# type: ignore`.
+
+---
+
+## Advanced Example: Late Initialization
+
+```python
+class Service:
+    token = ConstantAttrib[str]()
+
+    def initialize(self, token: str) -> None:
+        self.token = token
+```
+
+```python
+svc = Service()
+svc.initialize("abc123")
+svc.token = "xyz"   # AttributeError
+```
+
+---
+
+## Comparison With Alternatives
+
+### vs `@property`
+
+| Feature     | ConstantAttrib | property     |
+| ----------- | -------------- | ------------ |
+| Write-once  | Yes            | Manual       |
+| Boilerplate | Minimal        | High         |
+| Typing      | Excellent      | Often tricky |
+| Storage     | Automatic      | Manual       |
+
+---
+
+### vs `frozen=True` dataclass
+
+| Feature               | ConstantAttrib | Frozen dataclass |
+| --------------------- | -------------- | ---------------- |
+| Late init             | Yes            | No               |
+| Partial immutability  | Yes            | No               |
+| Per-attribute control | Yes            | No               |
+
+---
+
+## Design Philosophy
+
+`ConstantAttrib` is:
+
+* **Explicit**
+* **Predictable**
+* **Minimal**
+* **Safe for public APIs**
+
+It avoids:
+
+* Metaclasses
+* Magic mutation
+* Runtime patching
+* Silent behavior
+
+This makes it ideal for **library code**, **configuration objects**, and **framework internals**.
+
+---
+
+## When to Use
+
+Recommended for:
+
+* Configuration values
+* Identifiers
+* Runtime-initialized constants
+* Public API invariants
+
+Avoid using when:
+
+* Values must change
+* Full immutability is required (use frozen dataclasses instead)