# 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.admin import MediaFancybox, get_fancybox_image
from .models import YourModel
@admin.register(YourModel)
class YourModelAdmin(admin.ModelAdmin):
image_preview.short_description = 'Image Preview'
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.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
```
## Requirements
- Python 3.8+
- Django 3.2+
## Contributing
We welcome contributions! Here's how you can help improve Django Toolkit Essentials:
### Getting Started
1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
```bash
git clone https://github.com/alex-deus/django-toolkit-essentials.git
cd django-toolkit-essentials
```
3. **Create a virtual environment**:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
4. **Install development dependencies and setup pre-commit**:
```bash
make install-dev
# Or manually:
pip install -e .
pip install -r requirements-dev.txt
pre-commit install
```
### Development Workflow
1. **Create a feature branch**:
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes** following our coding standards:
- Follow PEP 8 style guidelines
- Add type hints where appropriate
- Write docstrings for new functions and classes
- Keep functions focused and well-named
3. **Test your changes**:
```bash
make check # Run all checks (tests, linting, formatting)
# Or run individual commands:
make test # Run tests
make lint # Run linters
make format # Format code
pre-commit run --all-files # Run pre-commit hooks
```
4. **Commit your changes**:
```bash
git add .
git commit -m "Add: brief description of your changes"
```
5. **Push and create a Pull Request**:
```bash
git push origin feature/your-feature-name
```
### What We're Looking For
- **Bug fixes** - Help us squash those pesky bugs
- **New utilities** - Add helpful Django utilities that follow our patterns
- **Documentation improvements** - Better docs help everyone
- **Performance optimizations** - Make things faster and more efficient
- **Test coverage** - Help us maintain high code quality
### Code Style Guidelines
- Use type hints for all function parameters and return values
- Follow Django conventions and best practices
- Write clear, descriptive variable and function names
- Add docstrings to public functions and classes
- Keep imports organized (standard library, third-party, local)
**Automated Code Quality:**
- Pre-commit hooks automatically run on every commit to ensure code quality
- Code is automatically formatted with Black and isort
- Linting with flake8, mypy, and bandit catches issues early
- Use `make format` to format code manually
- Use `make lint` to run all linters manually
### Reporting Issues
Found a bug or have a feature request? Please:
1. Check existing issues first to avoid duplicates
2. Use our issue templates when available
3. Provide clear reproduction steps for bugs
4. Include relevant system information (Python/Django versions)
### Questions?
Feel free to open an issue for questions or join discussions in existing issues.
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/alex-deus/django-essentials-kit",
"name": "django-essentials-kit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django, utilities, django-admin",
"author": "Alex Deus",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# Django Essentials\n\nEssential utilities for Django that make common tasks easier and more efficient.\n\n## Features\n\n- **Admin Utilities**: Enhanced admin interface components including FancyBox image display\n- **Model Utilities**: Helper functions for common model operations\n\n## Installation\n\n```bash\npip install django-essentials-kit\n```\n\n## Quick Start\n\n### Admin Utilities\n\nThe library provides `MediaFancybox` class and `get_fancybox_image` function for enhanced image display in Django admin:\n\n```python\nfrom django.contrib import admin\nfrom django_essentials.admin import MediaFancybox, get_fancybox_image\nfrom .models import YourModel\n\n@admin.register(YourModel)\nclass YourModelAdmin(admin.ModelAdmin):\n image_preview.short_description = 'Image Preview'\n list_display = ['name', 'image_preview']\n\n class Media(MediaFancybox):\n ...\n\n def image_preview(self, obj) -> SafeString:\n return get_fancybox_image(obj, 'image_field', w=60, h=60)\n```\n\n### Model Utilities\n\nUse `get_object_or_none` for safe object retrieval:\n\n```python\nfrom django_essentials.utils import get_object_or_none\n\nfrom .models import YourModel\n\n# Instead of try/except blocks\nobj = get_object_or_none(YourModel, pk=1)\nif obj:\n ... # Do something with obj\n```\n\n## Requirements\n\n- Python 3.8+\n- Django 3.2+\n\n## Contributing\n\nWe welcome contributions! Here's how you can help improve Django Toolkit Essentials:\n\n### Getting Started\n\n1. **Fork the repository** on GitHub\n2. **Clone your fork** locally:\n ```bash\n git clone https://github.com/alex-deus/django-toolkit-essentials.git\n cd django-toolkit-essentials\n ```\n\n3. **Create a virtual environment**:\n ```bash\n python -m venv venv\n source venv/bin/activate # On Windows: venv\\Scripts\\activate\n ```\n\n4. **Install development dependencies and setup pre-commit**:\n ```bash\n make install-dev\n # Or manually:\n pip install -e .\n pip install -r requirements-dev.txt\n pre-commit install\n ```\n\n### Development Workflow\n\n1. **Create a feature branch**:\n ```bash\n git checkout -b feature/your-feature-name\n ```\n\n2. **Make your changes** following our coding standards:\n - Follow PEP 8 style guidelines\n - Add type hints where appropriate\n - Write docstrings for new functions and classes\n - Keep functions focused and well-named\n\n3. **Test your changes**:\n ```bash\n make check # Run all checks (tests, linting, formatting)\n # Or run individual commands:\n make test # Run tests\n make lint # Run linters\n make format # Format code\n pre-commit run --all-files # Run pre-commit hooks\n ```\n\n4. **Commit your changes**:\n ```bash\n git add .\n git commit -m \"Add: brief description of your changes\"\n ```\n\n5. **Push and create a Pull Request**:\n ```bash\n git push origin feature/your-feature-name\n ```\n\n### What We're Looking For\n\n- **Bug fixes** - Help us squash those pesky bugs\n- **New utilities** - Add helpful Django utilities that follow our patterns\n- **Documentation improvements** - Better docs help everyone\n- **Performance optimizations** - Make things faster and more efficient\n- **Test coverage** - Help us maintain high code quality\n\n### Code Style Guidelines\n\n- Use type hints for all function parameters and return values\n- Follow Django conventions and best practices\n- Write clear, descriptive variable and function names\n- Add docstrings to public functions and classes\n- Keep imports organized (standard library, third-party, local)\n\n**Automated Code Quality:**\n- Pre-commit hooks automatically run on every commit to ensure code quality\n- Code is automatically formatted with Black and isort\n- Linting with flake8, mypy, and bandit catches issues early\n- Use `make format` to format code manually\n- Use `make lint` to run all linters manually\n\n### Reporting Issues\n\nFound a bug or have a feature request? Please:\n\n1. Check existing issues first to avoid duplicates\n2. Use our issue templates when available\n3. Provide clear reproduction steps for bugs\n4. Include relevant system information (Python/Django versions)\n\n### Questions?\n\nFeel free to open an issue for questions or join discussions in existing issues.\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Essential utilities for Django",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/alex-deus/django-essentials-kit",
"Issues": "https://github.com/alex-deus/django-essentials-kit/issues",
"Repository": "https://github.com/alex-deus/django-essentials-kit"
},
"split_keywords": [
"django",
" utilities",
" django-admin"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "18cbd65a50de2ae6d87aad3644bb56d961de0d4678a6bd94173221816ed9d630",
"md5": "70b0c69f574f62f8b06ca4788d879106",
"sha256": "fe22e430ba8e8feb7f83540b0bda7ce0dbca276ffc898db25886049c714b2f61"
},
"downloads": -1,
"filename": "django_essentials_kit-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70b0c69f574f62f8b06ca4788d879106",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5736,
"upload_time": "2025-10-26T16:01:53",
"upload_time_iso_8601": "2025-10-26T16:01:53.426734Z",
"url": "https://files.pythonhosted.org/packages/18/cb/d65a50de2ae6d87aad3644bb56d961de0d4678a6bd94173221816ed9d630/django_essentials_kit-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 16:01:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alex-deus",
"github_project": "django-essentials-kit",
"github_not_found": true,
"lcname": "django-essentials-kit"
}
JSON
