django-bananas 3.1

Compatibility

Currently tested only for

• Django 4.2 under Python 3.8-3.12

• Django 5.0 under Python 3.10-3.13

• Django 5.1 under Python 3.10-3.13

• Django 5.2 under Python 3.10-3.14

• Django 6.0 under Python 3.12-3.14

Pull requests welcome!

Models

from bananas.models import TimeStampedModel


class Book(TimeStampedModel):
    pass

>>> book.date_created
>>> book.date_modified

from bananas.models import UUIDModel


class User(UUIDModel):
    display_name = models.CharField(max_length=255)
    email = models.EmailField()

>>> user.id
UUID('70cf1f46-2c79-4fc9-8cc8-523d67484182')

>>> user.pk
UUID('70cf1f46-2c79-4fc9-8cc8-523d67484182')

from bananas.models import SecretField


class User(models.Model):
    # Ask for 32 bytes and require 24 bytes from urandom
    token = SecretField(num_bytes=32, min_bytes=24)

>>> User.objects.create()  # Token is generated automatically
>>> user.token
'3076f884da827809e80ced236e8da20fa36d0c27dd036bdd4afbac34807e5cf1'

from bananas.models import URLSecretField


class User(models.Model):
    # Generates an URL-safe base64 representation of the random value
    token = URLSecretField(num_bytes=32, min_bytes=24)

>>> user.token
'WOgrNwqFKOF_LsHorJy_hGpPepjvVH7Uar-4Z_K6DzU-'

ORM

New queryset.dicts() with field renaming through kwargs, and dot-dict style results:

from bananas.query import ExtendedQuerySet


class Book(TimeStampedModel):
    author = ForeignKey(Author)
    objects = Manager.from_queryset(ExtendedQuerySet)()

>>> book = Book.objects.dicts("id", author="author__name").first()
{'id': 1, 'author': 'Jonas'}
>>> book.author
'Jonas'

Admin

Custom django admin stylesheet.

# settings.py
INSTALLED_APPS = (
    "bananas",  # Needs to be before "django.contrib.admin"
    "django.contrib.admin",
    ...,
)

ADMIN = {
    "SITE_HEADER": "Bananas",
    "SITE_TITLE": "Bananas Admin",
    "INDEX_TITLE": "Admin Panel",
    # 'BACKGROUND_COLOR': '#363c3f',
}

# your main urls.py
from bananas import admin

urlpatterns = [
    # ...
    url(r"^admin/", include(admin.site.urls)),
]

# app/admin.py or something
from django.conf.urls import url
from bananas import admin


@admin.register
class MyAdminView(admin.AdminView):
    def get_urls(self):
        return [
            url(r"^custom/$", self.admin_view(self.custom_view)),
            # ^^ Note that the view is wrapped in self.admin_view.
            # Needed for permissions and to prevent any
            # threading issues.
        ]

    def get(self, request):
        return self.render("admin/template.html", {})

    def custom_view(self, request):
        return self.render("admin/custom.html", {})

Admin API

Django admin API for use with django-bananas.js (react admin site). This feature requires installation with the drf extra.

# app/admin.py or something
from bananas.admin.api.mixins import BananasAPI
from bananas.admin.api.schemas import schema
from bananas.admin.api.views import BananasAdminAPI
from bananas.lazy import lazy_title
from django.utils.translation import gettext_lazy as _
from rest_framework import viewsets


class CustomAdminAPI(BananasAdminAPI):
    name = lazy_title(_("custom"))

    @schema(query_serializer=SomeSerializer, responses={200: SomeSerializer})
    def list(self, request):
        return ...


class SomeModelAdminAPI(BananasAPI, viewsets.ModelViewSet):
    serializer_class = SomeModelSerializer

    def list(self, request):
        return ...

# app/urls.py or something
from bananas.admin import api
from django.conf.urls import include, path

from .admin import CustomAdminAPI, SomeModelAdminAPI

api.register(CustomAdminAPI)
api.register(SomeModelAdminAPI)

urlpatterns = [
    path(r"^api/", include("bananas.admin.api.urls")),
]

# setting.py
ADMIN = {
    "API": {
        # Optional: override the default OpenAPI schemes
        "SCHEMES": ["https"],
    }
}

Database URLs

Parse database information from a URL, kind of like SQLAlchemy.

bananas.environment - Helpers to get setting values from environment variables

bananas.environment.env is a wrapper around os.environ, it provides the standard .get(key, value), method to get a value for a key, or a default if the key is not set - by default that default is None as you would expect. What is more useful is the additional type-parsing .get_* methods it provides:

• get_bool

• get_int

• get_list, get_set, get_tuple

get_int:

>>> # env ONE=1
>>> env.get_int("ONE")
1
>>> env.get_int("TWO")  # Not set
None
>>> env.get_int("TWO", -1)  # Not set, default to -1
-1

get_bool:

returns True if the environment variable value is any of, case-insensitive:

• "true"

• "yes"

• "on"

• "1"

returns False if the environment variable value is any of, case-insensitive:

• "false"

• "no"

• "off"

• "0"

if the value is set to anything other than above, the default value will be returned instead.

e.g.:

>>> # env CAN_DO=1 NO_THANKS=false NO_HABLA=f4lse
>>> env.get_bool("CAN_DO")
True
>>> env.get_bool("NO_THANKS")
False
>>> env.get_bool("NO_HABLA")  # Set, but not valid
None
>>> env.get_bool("NO_HABLA", True)  # Set, but not valid, with default
True
>>> env.get_bool("IS_NONE")  # Not set
None
>>> env.get_bool("IS_NONE", False)  # Not set, default provided
False

get_tuple, get_list, get_set:

Returns a tuple, list or set of the environment variable string, split by the ascii comma character. e.g.:

>>> # env FOOS=foo,foo,bar
>>> get_list("FOO")
['foo', 'foo', 'bar']
>>> get_set("FOO")
set(['foo', 'bar'])

bananas.secrets - Helpers for getting secrets from files

Is useful for getting the content of secrets stored in files. One usecase is docker secrets.

BANANAS_SECRETS_DIR can be used to configure the directory that secrets live in. Defaults to /run/secrets/.

>>> from bananas import secrets

>>> secrets.get_secret("hemlis")
"topsecret"

bananas.drf.fencing - Fence DRF views with HTTP conditional headers

Building blocks for composing HTTP conditionals to guard DRF views. Built to work well in conjunction with BananasAdminAPI and TimeStampedModel. This feature requires installation with the drf extra.

Fences add a header parameter to the exposed OpenAPI schema if you’re using drf-yasg.

from bananas.drf.fencing import FencedUpdateModelMixin, allow_if_unmodified_since


class ItemAPI(FencedUpdateModelMixin, GenericViewSet):
    fence = allow_if_unmodified_since()
    serializer_class = ItemSerializer

from bananas.drf.fencing import FencedUpdateModelMixin, allow_if_match


class ItemAPI(FencedUpdateModelMixin, GenericViewSet):
    fence = allow_if_match(operator.attrgetter("version"))
    serializer_class = ItemSerializer

import operator
from drf_yasg import openapi
from rest_framework import status
from rest_framework.exceptions import APIException
from bananas.drf.fencing import Fence, header_date_parser, parse_date_modified


class NotModified(APIException):
    status_code = status.HTTP_304_NOT_MODIFIED
    default_detail = "An HTTP precondition failed"
    default_code = "not_modified"


allow_if_not_modified_since = Fence(
    get_token=header_date_parser("If-Modified-Since"),
    compare=operator.gt,
    get_version=parse_date_modified,
    openapi_parameter=openapi.Parameter(
        in_=openapi.IN_HEADER,
        name="If-Modified-Since",
        type=openapi.TYPE_STRING,
        required=True,
        description=(
            "Time of last edit of the client's representation of the resource in "
            "RFC7231 format."
        ),
    ),
    rejection=NotModified("The resource is unmodified"),
)

Contributing

Contributing is welcome in the form of PRs and issues. If you want to add a bigger feature or contribute with a large change in current behaviour it’s always a good idea to start a discussion with an issue before getting started.

New additions will be expected to have 100% test coverage as well as type hints and documentation to be considered to be merged.

python3 -m pip install -e .[test]
TOXENV=py314-django60,type-check python3 -m tox

python3 -m pip install -e .[dev,drf]
make type-check
pre-commit run --all-files

pre-commit install -t pre-push

make test test='-k test_logout'