Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

🍌 Django Bananas - Django extensions the monkey way


django-bananas is on PyPI, so just run:

python3 -m pip install django-bananas

Using DRF specific features like Bananas Admin and fencing requires djangorestframework and drf-yasg and it's recommended to install django-bananas with the drf extra to keep those in sync:

python3 -m pip install django-bananas[drf]


Currently tested only for

  • Django 2.2 under Python 3.7-3.9
  • Django 3.2 under Python 3.7-3.9
  • Django 4.0 under Python 3.8-3.10

Pull requests welcome!




Abstract TimeStampedModel with date created/modified fields:

Use TimeStampedModel as base class for your model

from bananas.models import TimeStampedModel

class Book(TimeStampedModel):

the timestamps can be accessed on the model as

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


Abstract model that uses a Django 1.8 UUID field as the primary key.

from bananas.models import UUIDModel

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



Can be used to generate and store "safe" random bytes for authentication.

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


An implementation of SecretField that generates an URL-safe base64 string instead of a hex representation of the random bytes.

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


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'}


Custom django admin stylesheet.


Work in progress. Only a few views styled completely as of now.

    "bananas",  # Needs to be before "django.contrib.admin"

    "SITE_HEADER": "Bananas",
    "SITE_TITLE": "Bananas Admin",
    "INDEX_TITLE": "Admin Panel",
    # 'BACKGROUND_COLOR': '#363c3f',
# your main
from bananas import admin

urlpatterns = [
    # ...
    url(r"^admin/", include(,
# app/ or something
from django.conf.urls import url
from bananas import admin

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/ 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/ or something
from bananas.admin import api
from django.conf.urls import include, path

from .admin import CustomAdminAPI, SomeModelAdminAPI


urlpatterns = [
    path(r"^api/", include("bananas.admin.api.urls")),
    "API": {
        # Optional: override the default OpenAPI schemes
        "SCHEMES": ["https"],

Database URLs

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


Currently supported engines are:

URI scheme Engine
pgsql, postgres, postgresql django.db.backends.postgresql_psycopg2
mysql django.db.backends.mysql
sqlite, sqlite3 django.db.backends.sqlite3
mysqlgis django.contrib.gis.db.backends.mysql
postgis django.contrib.gis.db.backends.postgis
spatialite django.contrib.gis.db.backends.spatialite

You can add your own by running register(scheme, module_name) before parsing.


Return a django-style database configuration based on url.

param url:Database URL
return:Django-style database configuration dict


>>> from bananas.url import database_conf_from_url
>>> conf = database_conf_from_url(
...     "pgsql://"
... )
>>> sorted(conf.items())  # doctest: +NORMALIZE_WHITESPACE
[('ENGINE', 'django.db.backends.postgresql_psycopg2'),
 ('HOST', ''),
 ('NAME', 'tweets'),
 ('PARAMS', {'hello': 'world'}),
 ('PASSWORD', 'hunter2'),
 ('PORT', 4242),
 ('SCHEMA', 'tweetschema'),
 ('USER', 'joar')]

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
>>> # env ONE=1
>>> env.get_int("ONE")
>>> env.get_int("TWO")  # Not set
>>> env.get_int("TWO", -1)  # Not set, default to -1

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.


>>> # env CAN_DO=1 NO_THANKS=false NO_HABLA=f4lse
>>> env.get_bool("CAN_DO")
>>> env.get_bool("NO_THANKS")
>>> env.get_bool("NO_HABLA")  # Set, but not valid
>>> env.get_bool("NO_HABLA", True)  # Set, but not valid, with default
>>> env.get_bool("IS_NONE")  # Not set
>>> env.get_bool("IS_NONE", False)  # Not set, default provided
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")

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.


Make a view-set for a TimeStampedModel only accept updates when If-Unmodified-Since specifies a date before the date_modified of the updated instance.

Due to comparing datetime instances, using allow_if_unmodified_since requires running Django with timezone support enabled, USE_TZ = TRUE.

from bananas.drf.fencing import FencedUpdateModelMixin, allow_if_unmodified_since

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


Make a view-set that requires passing a version string in If-Match and rejects requests when the given version does not match the version attribute of the updated instance.

from bananas.drf.fencing import FencedUpdateModelMixin, allow_if_match

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


Example implementing a fence for If-Modified-Since:

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(
            "Time of last edit of the client's representation of the resource in "
            "RFC7231 format."
    rejection=NotModified("The resource is unmodified"),


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.


Testing and development requirements can be installed using package extras test and dev respectively. You'll most likely always want to install the drf extra when installing dev.

To get started, setup a virtualenv and then install test requirements and run tests and checks on Python 3.9/Django 3.1 with:

python3 -m pip install -e .[test]
TOXENV=py39-django31,checks python3 -m tox

You can install development requirements into your virtualenv. Linting and formatting uses pre-commit which you could also install on a system level.

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

After installing pre-commit, you can enable hooks to have it run before you publish pull requests.

pre-commit install -t pre-push

After installing dev you can also run tests without tox for rapid iteration and select specific tests with the test argument to make test:

make test test='tests.test_admin.APITest.test_logout'