Metadata-Version: 2.1
Name: attrsx
Version: 0.0.1
Summary: A lightweight extension of attrs that adds extras like logging.
Home-page: https://kiril-mordan.github.io/reusables/attrsx/
Author: Kyrylo Mordan
Author-email: parachute.repo@gmail.com
License: mit
Keywords: aa-paa-tool
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: attrs>=22.2.0

# Attrsx

**`attrsx` – A Lightweight, Playful Extension to `attrs`**  

🔧 **What is `attrsx`?**  
`attrsx` is a minimal, lightweight extension of the popular `attrs` library, designed to seamlessly add logging capabilities to your `attrs` classes.  

---

### **✨ What It Does:**  
- 🛠️ **Extends `attrs.define`** – Behaves exactly like `attrs.define`, but with automatic logger initialization.  
- 🎛️ **Built-in Logging Fields** – Adds fields for logger name, level, and format – all customizable per class or instance.  
- 🔍 **Non-Intrusive** – If you don’t need logging, `attrsx` functions just like plain old `attrs`.  

---

### **🎯 Why `attrsx`?**  
- 🚀 You sometimes just want **simple logging** without writing the same boilerplate over and over.  
- 😌 `attrsx` lets you keep things clean – adding just a little "magic" to `attrs`-based classes.  
- 🌱 It’s `attrs`, but with room for playful future extensions.  

---

### **🚧 Features at a Glance:**  
- ✅ **Fully compatible** with `attrs` 22.2.0 and later.  
- 🧩 Supports **all `attrs.define` parameters** – like `slots`, `frozen`, and more.  
- 🔧 Logger defaults to the class name but can be **overridden effortlessly**.  

---

✨ It’s `attrs`, but with just a little... **extra**. 😄

```python
import attrsx
import attrs
```

## Usage

### 1. Built-in logger

One of the primary extensions in `attrsx` is `automatic logging`. It can be accessed via `self.logger` in any `attrsx`-decorated class.

#### Example: Basic Logger Usage


```python
@attrsx.define
class ProcessData:
    data: str = attrs.field(default=None)

    def run(self):
        self.logger.info("Running data processing...")
        self.logger.debug(f"Processing data: {self.data}")
        return f"Processed: {self.data}"

```


```python
ProcessData(data = "data").run()
```

    INFO:ProcessData:Running data processing...





    'Processed: data'



#### Logger Configuration

The logging behavior can be customized using the following optional attributes:

- `loggerLvl` : Sets the log level (from `logging`), defaults to `logging.INFO`.
- `logger_name` : Specifies the logger name; defaults to the class name.
- `logger_format` : Sets the logging message format; defaults to `%(levelname)s:%(name)s:%(message)s`.

`self.logger` becomes available starting from `__attrs_post_init__`.


```python
import logging

@attrsx.define
class ProcessData2:
    data: str = attrs.field(default=None)
    
    # optional attributes
    loggerLvl: int = attrs.field(default=logging.DEBUG) 
    logger_name : str = attrs.field(default="ProcessData")
    logger_format : str = attrs.field(default="%(asctime)s - %(name)s - %(levelname)s - %(message)s")

    def __attrs_post_init__(self):
        self.logger.info("Custom post-init logic running!")
        self.data = "DATA"

    def run(self):
        self.logger.info("Running data processing...")
        self.logger.debug(f"Processing data: {self.data}")
        return f"Processed: {self.data}"
```


```python
ProcessData2(data = "data").run()
```

    2025-01-02 23:26:02,710 - ProcessData - INFO - Custom post-init logic running!
    2025-01-02 23:26:02,711 - ProcessData - INFO - Running data processing...
    2025-01-02 23:26:02,711 - ProcessData - DEBUG - Processing data: DATA





    'Processed: DATA'



#### Using External Loggers

An external, pre-initialized logger can also be provided to the class using the `logger` attribute.


```python
ProcessData2(
    data = "data",
    logger = ProcessData().logger
).run()
```

    INFO:ProcessData:Custom post-init logic running!
    INFO:ProcessData:Running data processing...





    'Processed: DATA'


