{"id":22622400,"url":"https://github.com/sageteamorg/django-sage-tools","last_synced_at":"2025-04-11T16:40:52.396Z","repository":{"id":250204977,"uuid":"833787107","full_name":"sageteamorg/django-sage-tools","owner":"sageteamorg","description":"Reusable, generic mixins for Django","archived":false,"fork":false,"pushed_at":"2024-11-11T09:00:15.000Z","size":242,"stargazers_count":7,"open_issues_count":14,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T12:51:11.458Z","etag":null,"topics":["django","django-https","django-mixin","django-packages","sageteam","views"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sageteamorg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-25T18:41:53.000Z","updated_at":"2025-01-30T20:40:29.000Z","dependencies_parsed_at":"2024-08-25T07:34:16.230Z","dependency_job_id":null,"html_url":"https://github.com/sageteamorg/django-sage-tools","commit_stats":null,"previous_names":["sageteamorg/django-sage-tools"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sageteamorg%2Fdjango-sage-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sageteamorg%2Fdjango-sage-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sageteamorg%2Fdjango-sage-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sageteamorg%2Fdjango-sage-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sageteamorg","download_url":"https://codeload.github.com/sageteamorg/django-sage-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248442037,"owners_count":21104121,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["django","django-https","django-mixin","django-packages","sageteam","views"],"created_at":"2024-12-08T23:14:57.459Z","updated_at":"2025-04-11T16:40:52.377Z","avatar_url":"https://github.com/sageteamorg.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# django-sage-tools\n\n`django-sage-tools` is a Django package providing an extensive suite of tools, mixins, utilities, and validators tailored for class-based views, model handling, form processing, and various other enhancements. This library simplifies common development patterns in Django, offering robust solutions for request handling, data validation, model management, caching, and more.\n\n## Features\n\nSome of the key features include:\n\n- **Mixins for Class-Based Views**: Enhancements for handling permissions, cache control, access restrictions, HTTP headers, and more.\n- **Admin Tools**: Mixins to enforce singleton instances, make models read-only, and prioritize admin app lists.\n- **Form Utilities**: Facilitates form processing by automatically injecting request user and message handling.\n- **Model Mixins**: Simplifies model handling with timestamp, UUID, address, and singleton pattern support.\n- **Encryption and Security**: Offers encryption utilities for session data, CSRF handling, and file size validation.\n- **Utility Functions and Validators**: Tools for handling unit conversions, TOML configuration reading, foreign key linking in Django admin, and more.\n\n## Installation\n\n### Using pip\n\n1. **Create a Virtual Environment**:\n   ```bash\n   python -m venv .venv\n   ```\n2. **Activate the Virtual Environment**:\n   - On Windows:\n      ```bash\n      .venv\\Scripts\\activate\n      ```\n   - On macOS and Linux:\n      ```bash\n      source .venv/bin/activate\n      ```\n3. **Install the Package**:\n   ```bash\n   pip install django-sage-tools\n   ```\n\n### Using Poetry\n\n1. **Install Poetry**: Follow the official installation instructions at the [Poetry website](https://python-poetry.org/docs/#installation).\n2. **Create a New Project (Optional)**:\n   ```bash\n   poetry new myproject\n   cd myproject\n   ```\n3. **Add the Package as a Dependency**:\n   ```bash\n   poetry add django-sage-tools\n   ```\n4. **Activate the Virtual Environment**:\n   ```bash\n   poetry shell\n   ```\n\n## Usage\n\nHere are some examples of the capabilities provided by `django-sage-tools`:\n\n### 1. Mixins for Views\n\n- **`AccessMixin`**: Base class for view access control, handling unauthenticated redirects and permission handling.\n- **`LoginRequiredMixin`**, **`AnonymousRequiredMixin`**: Require or restrict user authentication for accessing views.\n- **`CacheControlMixin`** and **`NeverCacheMixin`**: Control caching behavior with cache-control headers or prevent caching entirely.\n- **`FormMessagesMixin`**: Adds success and failure messages on form validation.\n  \n**Example**:\n```python\nfrom sage_tools.mixins.views.access import LoginRequiredMixin\nfrom django.views.generic import ListView\n\nclass MyListView(LoginRequiredMixin, ListView):\n    model = MyModel\n    template_name = \"my_template.html\"\n```\n\n### 2. Model Mixins\n\n- **`TimeStampMixin`**: Automatically manages `created_at` and `modified_at` fields.\n- **`UUIDBaseModel`**: Adds a UUID primary key to the model.\n- **`BaseTitleSlugMixin`**: Provides a title and auto-generated unique slug field.\n\n**Example**:\n```python\nfrom django.db import models\nfrom sage_tools.mixins.models.base import TimeStampMixin, UUIDBaseModel\n\nclass Product(TimeStampMixin, UUIDBaseModel):\n    name = models.CharField(max_length=255)\n```\n\n### 3. Validators\n\n- **`FileSizeValidator`**: Validates the file size against a specified maximum.\n- **`HalfPointIncrementValidator`**: Ensures a rating is in half-point increments between 1 and 5.\n- **`NameValidator`**: Validates names to contain only letters, spaces, hyphens, and apostrophes.\n\n**Example**:\n```python\nfrom django.db import models\nfrom sage_tools.validators.file import FileSizeValidator\n\nclass Document(models.Model):\n    file = models.FileField(upload_to='documents/', validators=[FileSizeValidator(max_size=5 * 1024 * 1024)])\n```\n\n### 4. Admin Tools\n\n- **`LimitOneInstanceAdminMixin`**: Enforces a singleton pattern in the Django admin.\n- **`ReadOnlyAdmin`**: Makes a model read-only in the admin.\n\n**Example**:\n```python\nfrom django.contrib import admin\nfrom sage_tools.mixins.admins.limits import LimitOneInstanceAdminMixin\nfrom .models import SingletonModel\n\n@admin.register(SingletonModel)\nclass SingletonModelAdmin(LimitOneInstanceAdminMixin, admin.ModelAdmin):\n    pass\n```\n\n### 5. Utilities\n\n- **Unit Conversion**: `UnitConvertor` class for converting bytes to megabytes, days to seconds, etc.\n- **Admin Prioritization**: Customizes the display order of models in the Django admin.\n- **Data Generation**: `BaseDataGenerator` for creating placeholder images, random text, colors, prices, and more.\n- **TOML Reader**: Reads and parses TOML files.\n\n**Example**:\n```python\nfrom sage_tools.utils.converters import UnitConvertor\n\nbytes_value = 1024\nmegabytes = UnitConvertor.convert_byte_to_megabyte(bytes_value)\n```\n\n## Configuration\n\nSome features rely on Django settings:\n- **`FERNET_SECRET_KEY`**: Required for session encryption with `FernetEncryptor`.\n- **`CLEANUP_DELETE_FILES`**: Enables/disables automatic file deletion on model instance updates.\n- **`AUTO_SLUGIFY_ENABLED`**: Controls whether slugs are automatically generated in `SlugService`.\n\nAdd these in your Django `settings.py` file as needed:\n```python\nFERNET_SECRET_KEY = \"your_fernet_key_here\"\nCLEANUP_DELETE_FILES = True\nAUTO_SLUGIFY_ENABLED = True\n```\n\n## Contribution Guidelines\n\nThank you for your interest in contributing to our package! This document outlines the tools and steps to follow to ensure a smooth and consistent workflow. [CODE OF CONDUCT](CODE_OF_CONDUCT.md)\n\n\n## License\n\n`django-sage-tools` is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsageteamorg%2Fdjango-sage-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsageteamorg%2Fdjango-sage-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsageteamorg%2Fdjango-sage-tools/lists"}