isik

Everyday Python utilities, and a set of Django and Django REST Framework building blocks: base models with history tracking, per-host feedback and tag models attached without hand-written migrations, scoped permissions, serializer and viewset mixins, and HTTP exceptions you can raise from anywhere.

Install

pip install isik              # isik.common only - no dependencies
pip install isik[django]      # isik.django.apps, isik.django.http_exceptions
pip install isik[drf]         # isik.django.drf - brings the django extra with it
pip install isik[celery]      # isik.django.celery - brings the django extra with it
pip install isik[cli]         # isik.cli - click and questionary
pip install isik[all]         # everything, sentry/tiptap/templated_fields/cli included

Requires Python 3.11+. The django and drf extras assume PostgreSQL: BaseModel's timestamps and history tracking run on database triggers (django-pgtrigger, django-pghistory), so add pgtrigger and pghistory to INSTALLED_APPS. Bring your own database driver (psycopg or psycopg2); isik doesn't choose one for you.

Documentation

The full index is docs/INDEX.md.

• isik.common - caching, concurrency, error handling, functional helpers, typed settings from environment variables
• isik.cli - settings declared once as class attributes, given by option, environment variable or answer to a question, checked to be reachable all three ways
• isik.django.apps - BaseModel, history tracking, and the votes()/comments()/notes()/bookmarks()/tags() makers
• Idempotency keys - Idempotency-Key on DRF views: a retry replays the first response instead of doing the work twice
• Preconditions - ETag / If-Match on DRF views: a write made against an older version is refused instead of overwriting the newer one
• isik.django.drf - permissions (guarding, django_permission, ...), request policies on any view, serializer and viewset mixins, filters, pagination
• isik.django.celery - a task base whose history rows name whoever caused the task, not nobody
• isik.django.http_exceptions - raise an HTTP status directly instead of threading responses back up the call stack
• isik.sentry - Sentry-reporting exception suppression
• Translations - every user-facing string is translatable, through Django's catalogs or stdlib gettext

Plain Python, and worth knowing about in a Django project

A Django project's imports all start with isik.django, so isik.common.utils is easy to never see. It needs no Django and these come up in Django code constantly:

• first_of(iterable, default=None, pred=None) / not_none - the first item, or the first one matching a predicate, without a next(...) and a StopIteration to handle.
• with_attrs(**attrs) - set attributes on a function as a decorator (short_description, boolean on an admin method).
• returns(value) / raises(exception) / noop / identity - small callables for defaults and hooks.
• Exemption - an opt-out that names the rule it skips and says why, held to a minimum length and listed by rule (manage.py exemptions): NoHelpText(reason="why").
• TransformExceptions / SuppressAndRun - turn one exception into another, or run something when one is swallowed.

See isik.common for all of it.

What changed in each release: CHANGELOG.md.

License

MIT