Metadata-Version: 2.3
Name: pidalu-core
Version: 0.1.0
Summary: Pidalu Tech - Resusable core models, serializers and middlewares
License: MIT
Author: Pidalu Tech
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: django (>=5.2.1,<6.0.0)
Requires-Dist: djangorestframework (>=3.16.0,<4.0.0)
Description-Content-Type: text/markdown

# pidalu-core

Reusable Django core utilities and base components for Django and Django REST Framework projects.

> Includes model mixins, serializer tools, queryset managers, admin helpers, and middleware.  
> Designed to work out of the box with `settings.py` overrides.

---

## 🚀 Features

### ✅ Models & Mixins
- `TimeStampedModel` – auto `created_at`, `updated_at`
- `UserTrackerModel` – auto `created_by`, `updated_by`
- `TrackedModel` – combo of the above
- `SlugFieldModel` – auto slug from any source field
- `UUIDPrimaryKeyModel` – use UUIDs as primary keys
- `SoftDeleteModel` – soft deletion with manager/queryset support
- `AuditModel` – tracks and logs field-level changes

### 🔁 QuerySet & Manager Extensions
- `SoftDeleteManager` – `.only_deleted()`, `.with_deleted()`, `.active()`
- `SoftDeleteQuerySet` – compatible with manager above

### 📦 Serializers
- `DynamicFieldsModelSerializer` – limit output via `fields=[...]`
- `DynamicSerializer` – same for plain serializers
- `DummySerializer` – no-op placeholder
- *(All located in `pidalu_core.serializers`)*

### 🛠 Admin Helpers
- `ReadOnlyAdminFieldsMixin` – make selected fields readonly
- `AutoSlugAdminMixin` – auto-prepopulate `slug` in admin from any field

### 🧠 Middleware
- `RequestMiddleware` – stores current request in thread-local
  > Used to track `created_by`/`updated_by` automatically in models

---

## ⚙️ Installation

```bash
pip install pidalu-core
```

Or using Poetry:

```bash
poetry add pidalu-core
```

---

## 🧩 Setup

### 1. Add Middleware

```python
# settings.py
MIDDLEWARE = [
    "pidalu_core.middleware.request.RequestMiddleware",  # ✅ Add near top
    ...
]
```

### 2. Optional Settings

```python
# settings.py

PIDALU_CORE_TRACK_USER = True  # enable tracking created_by/updated_by
PIDALU_CORE_AUTO_SLUG_FIELD = "name"  # default source field for slug generation
```

---

## 🧱 Usage Examples

### `TrackedModel` (timestamps + user)

```python
from pidalu_core.models import TrackedModel

class Post(TrackedModel):
    title = models.CharField(max_length=100)
```

### `SlugFieldModel` with custom source

```python
class Article(SlugFieldModel):
    title = models.CharField(max_length=255)
    slug_source_field = "title"
```

### `SoftDeleteModel` with manager

```python
class Project(SoftDeleteModel):
    name = models.CharField(max_length=255)

# Usage:
Project.objects.all()  # active only
Project.objects.only_deleted()
Project.objects.with_deleted()
```

### `DynamicFieldsModelSerializer`

```python
class UserSerializer(DynamicFieldsModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username", "email"]

# usage: UserSerializer(user, fields=["id", "email"])
```

---

## 🧪 Testing

Use `Makefile`> `test`.

### Setup
```bash
make test
```
Or directly with Poetry, uses pytest and pytest-django under the hood:
```bash
PYTHONPATH=. poetry run pytest -vv
```

We use in-memory SQLite + dynamic schema creation.

---

## 📦 Packaging & Publishing

Coming soon:
- Versioned releases
- PyPI support
- Docs site

---

## 👤 Author

Built and maintained by [Pidalu].

---

## 🪪 License

MIT License — free to use, modify, and distribute.
