Metadata-Version: 2.4
Name: django-essentials-kit
Version: 0.1.6
Summary: Essential utilities for Django
Home-page: https://github.com/alex-deus/django-essentials-kit
Author: Alex Deus
License: MIT
Project-URL: Homepage, https://github.com/alex-deus/django-essentials-kit
Project-URL: Repository, https://github.com/alex-deus/django-essentials-kit
Project-URL: Issues, https://github.com/alex-deus/django-essentials-kit/issues
Keywords: django,utilities,django-admin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: json-log-formatter<2.0.0,>=1.1.1
Requires-Dist: django-ipware<8.0.0,>=7.0.1
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Django Essentials

Essential utilities for Django that make common tasks easier and more efficient.

## Features

- **Admin Utilities**: Enhanced admin interface components including FancyBox image display
- **Model Utilities**: Helper functions for common model operations

## Installation

```bash
pip install django-essentials-kit
```

## Quick Start

### Admin Utilities

The library provides `MediaFancybox` class and `get_fancybox_image` function for enhanced image display in Django admin:

```python
from django.contrib import admin
from django_essentials_kit.admin import MediaFancybox, get_fancybox_image
from .models import YourModel

@admin.register(YourModel)
class YourModelAdmin(admin.ModelAdmin):
    list_display = ['name', 'image_preview']

    class Media(MediaFancybox):
        ...

    def image_preview(self, obj) -> SafeString:
        return get_fancybox_image(obj, 'image_field', w=60, h=60)
```

### Model Utilities

Use `get_object_or_none` for safe object retrieval:

```python
from django_essentials_kit.utils import get_object_or_none

from .models import YourModel

# Instead of try/except blocks
obj = get_object_or_none(YourModel, pk=1)
if obj:
    ...  # Do something with obj
```

### JSON Logger Formatter

Add to `settings.py`:
```python
LOGGING = {
    "version": 1,
    "disable_existing_loggers": True,
    "root": {"level": "INFO", "handlers": ["console"]},
    "formatters": {
        "json": {
            "format": "[%(levelname)s][%(asctime)s] %(module)s.%(funcName)s:%(lineno)d: %(message)s",
            "()": "django_essentials_kit.logger_formatter.JSONFormatter",
        },
    },
    "handlers": {
        "console": {"level": "INFO", "class": "logging.StreamHandler", "formatter": "json"},
    },
    "loggers": {
        "django": {"level": "DEBUG", "handlers": ["console"], "propagate": False},
        # ...
    },
}
```

### Logging HTTP request-response

Add to `settings.py`:
```python
MIDDLEWARE = [
    "django_essentials_kit.middlewares.DjangoLoggingMiddleware",
    # ...
]
```

It will be added to the logs:
- **real_client_ip** if it is routable
- **is_succeeded** (200 <= status < 300 - true else false)
- request details:
  - **status_code**
  - **method**
  - **path**
- **user_id** if a user is signed in
- **real_client_ip** (if routable)

## Requirements

- Python 3.8+
- Django 3.2+

## License

MIT License - see LICENSE file for details.
