django-fast-modeladmin 1.0.0__py3-none-any.whl

django_fast_modeladmin-1.0.0.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: django-fast-modeladmin
+Version: 1.0.0
+Summary: Faster Admin model control via a settings dictionary
+Author: SimplePythonCoder
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SimplePythonCoder/django-fast-modeladmin
+Project-URL: Source, https://github.com/SimplePythonCoder/django-fast-modeladmin
+Project-URL: Changelog, https://github.com/SimplePythonCoder/django-fast-modeladmin/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/SimplePythonCoder/django-fast-modeladmin/wiki
+Project-URL: Issues, https://github.com/SimplePythonCoder/django-fast-modeladmin/issues
+Keywords: django,django-admin
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django
+Dynamic: license-file
+
+# django-fast-modeladmin
+
+[![downloads](https://static.pepy.tech/badge/django-fast-modeladmin)](https://www.pepy.tech/projects/django-fast-modeladmin) [![changelog](https://raw.githubusercontent.com/SimplePythonCoder/zipmanager/main/images/Changelog.svg)](https://github.com/SimplePythonCoder/django-fast-modeladmin/blob/main/CHANGELOG.md) [![wiki](https://raw.githubusercontent.com/SimplePythonCoder/zipmanager/main/images/Wiki.svg)](https://github.com/SimplePythonCoder/django-fast-modeladmin/wiki)
+
+
+A fast way to customize your django admin site.
+
+### Installation & Usage
+
+```
+pip install django-fast-modeladmin
+```
+
+Add fast_modeladmin to INSTALLED_APPS:
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...,
+    'fast_modeladmin'
+]
+
+...
+
+FAST_MODELADMIN = (...)
+```
+
+## Features
+
+Allows you to control many of the Django admin sited functionalities with a dict for each model instead of creating many classes.
+
+Including:
+- edit columns shown in the model table page
+- a search box for specific fields (including foreign keys)
+- select which fields are editable or not
+
+and many more.
+
+The package also include an error system for easier readability.
+
+more info at the [wiki](https://github.com/SimplePythonCoder/django-fast-modeladmin/wiki).

django_fast_modeladmin-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+django_fast_modeladmin-1.0.0.dist-info/licenses/LICENSE,sha256=kAeeE4HF_j5MduozghXRLfWDe7sHW43rUjhG41SDKtA,1074
+fast_modeladmin/__init__.py,sha256=w7J8kHoWbaPZlLHAcYE81OlFjMak5FdeLiTRGuxE6_Q,82
+fast_modeladmin/apps.py,sha256=H-CekTvM_mSWNKTQOWUXe0NjKJmHbGcxBse5aTv2MAg,980
+fast_modeladmin/exceptions.py,sha256=-qeNqNRXXo3gZdbPgxZenvsMqdvZgMvvBhNrEKJRewg,2275
+fast_modeladmin/form.py,sha256=00UYmnuggCfQhPyp3kdd8y7sac_teuP9fQ5vUlEAfJY,318
+fast_modeladmin/main.py,sha256=9GXLwZoVWA1_4lSBuRxrjjf3jFvAyYVM8DxukyYnPCU,16545
+django_fast_modeladmin-1.0.0.dist-info/METADATA,sha256=Eeq2lPkYTgFPWOBFCbj4PaZFYRd67xwukgoAquBFuss,2288
+django_fast_modeladmin-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+django_fast_modeladmin-1.0.0.dist-info/top_level.txt,sha256=0Z1fxrA9AhYaNIDz4ln6wD_KqKF8458gFRcNS8DmFak,16
+django_fast_modeladmin-1.0.0.dist-info/RECORD,,

django_fast_modeladmin-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_fast_modeladmin-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SimplePythonCoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_fast_modeladmin-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fast_modeladmin

fast_modeladmin/__init__.py

@@ -0,0 +1,2 @@
+from .main import _register_models, get_dict
+from .form import template_model_form

fast_modeladmin/apps.py

@@ -0,0 +1,28 @@
+from django.apps import AppConfig
+from django.conf import settings
+from django.core.checks import Warning, register, Tags
+
+from .main import _register_models
+
+
+def check_my_custom_setting(**kwargs):
+    errors = []
+    if not hasattr(settings, 'FAST_MODELADMIN'):
+        errors.append(
+            Warning(
+                'FAST_MODELADMIN setting is missing.',
+                hint='Add "FAST_MODELADMIN = ()" to settings.py',
+                obj='fast_modeladmin'
+            )
+        )
+    return errors
+
+
+class CustomAdminAppConfig(AppConfig):
+    name = 'fast_modeladmin'
+
+    def ready(self):
+        register(check_my_custom_setting, Tags.compatibility)
+        _register_models(admin_model=getattr(settings, 'FAST_MODELADMIN', None),
+                                         register_all=getattr(settings, 'FAST_MODELADMIN_REGISTER_ALL', None),
+                                         files=getattr(settings, 'FAST_MODELADMIN_MODULES', {}))

fast_modeladmin/exceptions.py

@@ -0,0 +1,75 @@
+class BaseFastAdminException(Exception):
+    def __init__(self, message):
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+
+class ImproperlyConfigured(BaseFastAdminException):
+    pass
+
+
+class CustomSyntaxError(BaseFastAdminException):
+    def __init__(self, message, model=None):
+        if model:
+            message = f'{model.__name__} Model: {message}'
+        super().__init__(message)
+
+
+class ModuleError(CustomSyntaxError):
+    pass
+
+
+class ClassError(CustomSyntaxError):
+    pass
+
+
+class DecoratorError(CustomSyntaxError):
+    def __init__(self, function, decorator, model=None):
+        super().__init__(message=f'action "{function}" does not use the "{decorator}" decorator', model=model)
+
+
+class ValueTypeError(CustomSyntaxError):
+    @staticmethod
+    def get_str_type(types):
+        match types:
+            case list():
+                return ' or '.join([t.__name__ if t is not None else "None" for t in types])
+            case type():
+                return types.__name__
+            case None:
+                return 'None'
+            case _:
+                return type(types).__name__
+
+    def __init__(self, value, types, kind, model=None):
+        if type(value) is str:
+            value = f'"{value}"'
+        super().__init__(model=model,
+                         message=f'{kind} type is {self.get_str_type(value)} instead of '
+                                 f'{self.get_str_type(types)}' +
+                                 (f' [{kind}: {value}]' if model else '')
+                         )
+
+
+class OptionError(CustomSyntaxError):
+    pass
+
+
+class ModelNotFound(BaseFastAdminException):
+    def __init__(self, model):
+        if hasattr(model, '__name__'):
+            model = model.__name__
+        super().__init__(f'Model "{model}" not found')
+
+
+class ModelFieldError(BaseFastAdminException):
+    def __init__(self, model, field=None, message=None):
+        if type(field) is str:
+            super().__init__(f'field "{field}" not found in {model.__name__} model')
+        elif type(message) is str:
+            super().__init__(message)
+
+def _raise(error_type, *args, **kwargs):
+    raise error_type(*args, **kwargs) from None

fast_modeladmin/form.py

@@ -0,0 +1,9 @@
+from django import forms
+
+def template_model_form(model_to_render, fields_to_render: list | None = None):
+    class GenericModelForm(forms.ModelForm):
+        class Meta:
+            model = model_to_render
+            fields = fields_to_render if fields_to_render else '__all__'
+
+    return GenericModelForm

fast_modeladmin/main.py

@@ -0,0 +1,296 @@
+from typing import cast
+
+from django.apps import apps
+from django.contrib import admin
+import re
+from importlib import import_module
+from django.contrib.admin import ShowFacets
+from django.db import models
+
+from .exceptions import (ModelFieldError, OptionError, ModelNotFound, ValueTypeError,
+                         CustomSyntaxError, ModuleError, ClassError,
+                         _raise)
+
+from .form import template_model_form
+
+
+def _get_import(model, field_list: list, index=0):
+    if index < len(field_list):
+        if getattr(model, field_list[index], None) is not None:
+            match getattr(model, field_list[index]).__class__.__name__:
+                case 'ForwardManyToOneDescriptor' | 'ForwardOneToOneDescriptor':
+                    return _get_import(getattr(model, field_list[index]).field.remote_field.model, field_list,
+                                            index + 1)
+                case 'DeferredAttribute':
+                    if getattr(getattr(model, field_list[index]), 'field', None) is not None:
+                        return _get_import(getattr(getattr(model, field_list[index]), 'field'), field_list,
+                                                index + 1)
+                    else:
+                        _raise(model=model.__name__, error_type=ModelFieldError, field=field_list[index])
+        else:
+            _raise(model=model.__name__, error_type=ModelFieldError, message=f'field "{field_list[index]}" in {"__".join(field_list)} '
+                                                       f'cannot be found')
+    return model
+
+
+def get_dict(model=None, columns=None, parts=None,
+             actions=None, form=None, read_only_fields=None,
+             sort=None, search=None, editables=None, links=None,
+             filters=None):
+    """
+    This function builds a dictionary to be used in the FAST_MODELADMIN setting
+
+    :param model:                   app and model name (app_name.ModelName)
+    :type model:                    str
+    :param columns:                 list of fields to be columns of list page
+    :type columns:                  list[str]
+    :param parts:                   parts and fields to render on entry page
+    :type parts:                    dict [(str, str), (str, list)]
+    :param actions:                 list of function names in the admin module
+    :type actions:                  list[str]
+    :param form:                    list of class names in the forms module
+    :type form:                     str
+    :param read_only_fields:        list of fields to be non-editables in the form page
+    :type read_only_fields:         list[str]
+    :param sort:                    name of field to sort by
+    :type sort:                     list[str]
+    :param search:                  list of fields and sub-fields to search in
+    :type search:                   list[str]
+    :param editables:               list of column fields to be editable on the list page
+    :type editables:                list[str]
+    :param links:                   list of column fields to be clickable on the list page
+    :type links:                    list[str]
+    :param filters:                 dict with list of fields in 'fields' and 'show_count' that is either 'show',
+                                    'hide' or 'disable'.
+    :type filters:                  dict[str, list] | dict[str, str]
+    :return:                        dict to be used in settings for CUSTOM_MODELADMIN variable
+    :rtype:                         dict
+    """
+    return {'model': model,
+            'columns': columns,
+            'parts': parts,
+            'actions': actions,
+            'form': form,
+            'read_only_fields': read_only_fields,
+            'sort': sort,
+            'search': search,
+            'editables': editables,
+            'links': links,
+            'filters': filters}
+
+
+def _part_creator(**kwargs):
+    match kwargs.get('classes'):
+        case None:
+            return kwargs['label'], {'fields': kwargs['fields']}
+        case list() | tuple():
+            return kwargs['label'], {'fields': kwargs['fields'], 'classes': kwargs['classes']}
+
+    return None
+
+def _get_app(app_model):
+    if type(app_model) is str:
+        if not re.match(pattern=r'.+\..+', string=app_model):
+            _raise(error_type=OptionError, message='model pattern must be app_label.ModelName')
+        app_model = {'app_label': app_model.split('.')[0], 'model_name': app_model.split('.')[1]}
+    try:
+        return apps.get_model(**app_model)
+    except LookupError:
+        _raise(model=f'{app_model["app_label"]}.{app_model["model_name"]}', error_type=ModelNotFound)
+
+
+def _is_type(model, value, types, kind):
+    match types:
+        case list():
+            if type(value) not in types:
+                _raise(model=model, error_type=ValueTypeError, kind=kind, value=value, types=types)
+        case type():
+            if type(value) is not types:
+                _raise(model=model, error_type=ValueTypeError, kind=kind, value=value, types=types)
+
+
+def _interpreter(values, files, model):
+    model_fields = [field for field in model.__dict__.keys() if not field.startswith('_')]
+    non_editable_fields = [field.name for field in getattr(model, '_meta').fields if not field.editable]
+
+    if values.get('columns') is not None:
+        _is_type(model, value=values['columns'], types=[list, tuple], kind='columns')
+        for field in values['columns']:
+            _is_type(model, value=field, types=str, kind='columns field')
+            if field not in model_fields and field != 'pk':
+                _raise(model=model, error_type=ModelFieldError, field=field)
+    if values.get('read_only_fields') is not None:
+        _is_type(model, value=values['read_only_fields'], types=[list, tuple], kind='read only fields')
+        for field in values['read_only_fields']:
+            _is_type(model, value=field, types=str, kind='read only field')
+            if field not in model_fields and field != 'pk':
+                _raise(model=model, error_type=ModelFieldError, field=field)
+    if values.get('parts') is not None:
+        _is_type(model, value=values.get('parts'), types=[list, tuple], kind='parts')
+        field_list = []
+        for index, part in enumerate(values['parts']):
+            _is_type(model, value=part, types=dict, kind='parts')
+            if part.get('label') is None:
+                _raise(model=model, error_type=OptionError, message=f'missing label in parts[{index}]')
+            _is_type(model, value=part.get('label'), types=str, kind='label')
+            if part.get('fields') is None:
+                _raise(model=model, error_type=OptionError, message=f'missing fields in parts[{index}]')
+            _is_type(model, value=part.get('fields'), types=[list, tuple], kind='part fields')
+            _is_type(model, value=part.get('classes'), types=[list, tuple, type(None)], kind='classes')
+            for field in part['fields']:
+                _is_type(model, value=field, types=str, kind='field')
+                if field not in model_fields:
+                    _raise(model=model, error_type=ModelFieldError, field=field)
+                if field in non_editable_fields and field not in values.get('read_only_fields'):
+                    _raise(model=model, error_type=OptionError,
+                           message=f'cannot use non-editable field "{field}" in parts.'
+                                   f'\nHINT: you can add it to the "read_only_fields" to avoid this error.')
+                if field in field_list:
+                    _raise(model=model, error_type=OptionError,
+                           message=f'cannot use field "{field}" more than once in "parts"')
+                field_list.append(field)
+            values['parts'][index] = _part_creator(**part)
+        del field_list
+    if values.get('sort') is not None:
+        _is_type(model, value=values['sort'], types=[list, tuple], kind='sort')
+        for sort in values['sort']:
+            _is_type(model, value=sort, types=str, kind='sort field')
+            if not re.match(pattern=r'-?\w+', string=sort):
+                _raise(model=model, error_type=CustomSyntaxError,
+                          message=f'sort pattern must be "field_name" or "-field_name"')
+            _get_import(model, sort[1:].split('__') if sort[0] == '-' else sort.split('__'))
+    if values.get('actions') is not None:
+        _is_type(model, value=values['actions'], types=[list, tuple], kind='actions')
+        try:
+            admin_module = import_module(values['model'].split('.')[0] + '.' +
+                                         (files['ADMIN'].replace('.py', '') if files.get('ADMIN') else 'admin'))
+        except ModuleNotFoundError:
+            _raise(model=model, error_type=CustomSyntaxError,
+                      message=f'could not find "{files.get("ADMIN")}" admin module')
+            return None
+        for index, action in enumerate(values['actions']):
+            _is_type(model, value=action, types=str, kind='action')
+            values['actions'][index] = getattr(admin_module, action, None)
+            if not callable(values['actions'][index]):
+                _raise(model=model, error_type=ModuleError,
+                          message=f'action "{action}" was not found in {values["model"].split(".")[0]}.admin')
+    if values.get('form') is not None:
+        _is_type(model, value=values['form'], types=str, kind='form')
+        try:
+            values['form'] = getattr(import_module(values['model'].split('.')[0] + '.' +
+                                                   (files['FORMS'].replace('.py', '')
+                                                    if files.get('FORMS') else 'forms')),
+                                     values['form'])
+        except ModuleNotFoundError:
+            _raise(model=model, error_type=CustomSyntaxError, message=f'could not find "{files.get("FORMS")}" forms module')
+        except AttributeError:
+            _raise(model=model, error_type=ModuleError,
+                   message=f'form "{values["form"]}" not found in {values["model"].split(".")[0]}.forms')
+        if not callable(values['form']):
+            _is_type(model=model, value=values['form'], types=str, kind='form')
+        if values['form'].__class__.__name__ != 'ModelFormMetaclass':
+            _raise(model=model, error_type=ClassError,
+                      message='form must inherit from forms.ModelForm (including multilevel inheritance)')
+    if values.get('search') is not None:
+        _is_type(model, value=values['search'], types=[list, tuple], kind='search')
+        for field in values['search']:
+            _is_type(model, value=field, types=str, kind='search field')
+            if (error_field:=field.split('__')[0]) not in model_fields:
+                _raise(model=model, error_type=ModelFieldError, field=error_field)
+            del error_field
+            _get_import(model, field.split('__'))
+    if values.get('editables') is not None:
+        _is_type(model, value=values['editables'], types=[list, tuple], kind='editables')
+        if not values.get('columns'):
+            _raise(model=model, error_type=CustomSyntaxError,
+                      message='cannot use editables without columns')
+        for editable in values['editables']:
+            if editable not in model_fields:
+                _raise(model=model, error_type=ModelFieldError,
+                          field=editable)
+            if editable not in values['columns']:
+                _raise(model=model, error_type=ModelFieldError,
+                          message=f'editable field "{editable}" must be one of the columns')
+            if editable in values['columns'][0]:
+                _raise(model=model, error_type=ModelFieldError,
+                          message=f'editable field "{editable}" cannot be the first column')
+            if values.get('links') and editable in values['links']:
+                _raise(model=model, error_type=ModelFieldError,
+                          message=f'field "{editable}" cannot be in both editables and links')
+    if values.get('filters') is not None:
+        _is_type(model, value=values['filters'], types=dict, kind='filter')
+        _is_type(model, value=values['filters'].get('fields'), types=[list, tuple], kind='filter fields')
+        for filter_name in values['filters']['fields']:
+            _is_type(model, value=filter_name, types=str, kind='filter field')
+            _get_import(model=model, field_list=filter_name.split('__'))
+        if values['filters'].get('show_count'):
+            _is_type(model, value=values['filters']['show_count'], types=str, kind='filter show count')
+            match values['filters']['show_count']:
+                case 'show':
+                    values['filters']['show_count'] = ShowFacets.ALWAYS
+                case 'hide':
+                    values['filters']['show_count'] = ShowFacets.ALLOW
+                case 'disable':
+                    values['filters']['show_count'] = ShowFacets.NEVER
+                case _:
+                    _raise(model=model, error_type=CustomSyntaxError,
+                           message='show_count must be "show", "hide" or "disable"')
+    if values.get('search_text') is not None:
+        if not values.get('search'):
+            _raise(model=model, error_type=CustomSyntaxError,
+                      message='cannot use search text without search')
+        _is_type(model, value=values['search text'], types=str, kind='search text')
+    if values.get('links') is not None:
+        if not values.get('columns'):
+            _raise(model=model, error_type=CustomSyntaxError,
+                      message='cannot use links without columns')
+        _is_type(model, value=values['links'], types=[list, tuple], kind='links')
+        for link in values['links']:
+            _is_type(model, value=link, types=str, kind='link')
+            if link not in values['columns']:
+                _raise(model=model, error_type=ModelFieldError,
+                          message=f'link "{link}" must be one of {values["model"]}\'s current columns')
+
+    return values
+
+
+def _create_modeladmin(**kwargs: dict):
+    class FastModelAdminClass(admin.ModelAdmin):
+        list_display = kwargs.get('columns', ['__str__'])
+        fieldsets = kwargs.get('parts', [])
+        form = kwargs.get('form', template_model_form(_get_app(kwargs['model'])))
+        actions = kwargs.get('actions', [])
+        search_fields = kwargs.get('search', [])
+        readonly_fields = kwargs.get('read_only_fields', [])
+        list_filter = kwargs.get('filters', {}).get('fields', [])
+        show_facets = kwargs.get('filters', {}).get('show_count', ShowFacets.NEVER)
+        list_editable = kwargs.get('editables', [])
+        ordering = kwargs.get('sort', [])
+        search_help_text = kwargs.get('search_text')
+        list_display_links = kwargs.get('links', [])
+
+    return FastModelAdminClass
+
+
+def _register_models(admin_model, register_all, files=None):
+    if type(files) is not dict:
+        _raise(error_type=ValueTypeError, kind='FAST_MODELADMIN_MODULES', value=files, types=dict)
+    match admin_model:
+        case list() | tuple():
+            for values in admin_model:
+                if type(values) is not dict:
+                    _raise(error_type=OptionError, message='FAST_MODELADMIN elements must be dict')
+                if type(values.get('model')) is not str:
+                    _raise(error_type=ValueTypeError, kind='model', value=values.get('model'), types=str)
+                model = cast(type[models.Model], _get_app(values['model']))
+                if admin.site.is_registered(model):
+                    _raise(error_type=OptionError, message=f'Model {values["model"]} cannot be registered again.')
+                admin.site.register(model, _create_modeladmin(**_interpreter(values, files, model=model) or {}))
+        case None:
+            pass
+        case _:
+            _raise(error_type=ValueTypeError, kind='FAST_MODELADMIN', value=type(admin_model), types=[list, tuple])
+    if register_all:
+        for model in apps.get_models():
+            if not admin.site.is_registered(model) and 'django' not in model.__module__:
+                admin.site.register(model)