Best Practices: Datei- und Ordnernamen in Django-Projekten und Apps
Wenn man Applikationen mit Django entwickelt gibt es einige Konventionen für die benennung von Dateien und Ordnern aber gleichzeitig auch viel Freiheit, denn Django arbeitet mit normalen Python-Modulen.
Um den Überblick nicht zu verlieren und auch in Projekten mit mehreren Entwicklern eine einheitliche Struktur zu verwenden sind hier sowohl die Dateinamen dokumentiert, die eine spezielle Bedeutung haben als auch diejenigen, welche sinnvoll für einen bestimmten Zweck sind.
Django Projekte
Ein Django-Projekt, angelegt mit django-admin.py startproject myproject enthällt am Anfang genau vier Dateien:
__init__.py
Diese Datei ist leer, hat aber eine spezielle Bedeutung für den Python-Interpreter. Nur wenn ein Ordner eine Datei namens __init__.py enthällt ist er ein Python-Modul und der Ordner bzw. sein Inhalt kann importiert werden. Diese Funktionalität gibt es seit Python 1.5 und hier kann man mehr darüber erfahren. Für den Moment reicht es zu wissen, dass diese Datei eine spezielle Bedeutung hat und einen Ordner zu einem Python-Modul bzw. Package erklärt.
manage.py
Diese Datei dient dazu administrative Kommandos im Kontext des aktuellen Django-Projekts auszuführen. Also z.B. das syncdb Kommando zum Einrichten der Datenbanktabellen. Die Datei manage.py erwartet, dass die Projekt-Konfigurationsdatei settings.py heißt und im selben Ordner liegt. Heißt die Konfigurationsdatei anders kann man alle Funktionen von manage.py auch mit django-admin.py unter expliziter Angabe einer Konfigurationsdatei (oder genauer gesagt eines Python-Moduls) ausführen.
settings.py
Diese Datei ist die Konfigurationsdatei des Projekts, der Name ist allerdings nur Konvention, kein Zwang. Wie schon zu manage.py beschrieben, kann die Datei anders heißen, man muss dann allerdings django-admin.py zum Verwalten des Projekts benutzen und sollte die Umgebungsvariable DJANGO_SETTINGS_MODULE auf den Python-Pfad der Datei setzen, z.B. myproject.mysettings, wenn die Datei mysettings.py heißt.
urls.py
In dieser Datei befindet sich die Root-URL-Konfiguration. Der Name ist auch hier nur Konvention und kein Zwang. Wo die Root-URL-Konfiguration zu finden ist, weiß Django an Hand der Einstellung ROOT_URLCONF, zu finden in der settings.py bzw. in dem Python-Modul, welches in DJANGO_SETTINGS_MODULE festgelegt ist.
Die Standard Projektstruktur die mit django-admin.py erzeugt wird entspricht schon den Best Practices für Django Projekte, allerdings ist es kein starres Korsett, man kann im Prinzip jede dieser Dateien auch anders nennen oder an einen anderen Ort legen.
Django Apps
Anders als bei Django-Projekten sieht es bei Django Apps aus, hier gibt es durchaus ein paar feste Regeln für Dateinamen damit auch alles so funktioniert wie man es erwartet. Im folgenden werden zuerst die Dateien besprochen, die mit manage.py startapp myapp angelegt werden, danach alle Dateien die eine feste Bedeutung haben und zum Schluß dann noch alle Dateinamen, die man benutzen sollte um es sich und anderen Entwicklern leichter zu machen den Überblick zu behalten.
Note
Datei oder Ordner: In Django funktionert so gut wie alles auf Basis von Python-Modulen, d.h. es macht keinen Unterschied, ob ein Stück Code (z.B. eine View-Funktion) in der Datei views.py oder in der Datei views/__init__.py liegt. Wächst ein Projekt will man lange Dateien der Übersichtlichkeit halber oftmals gerne aufteilen. In diesem Fall kann man einfach einen Ordner mit dem Namen der Datei anlegen, den bestehenden Code in die __init__.py Datei verschieben und beginnen weitere Dateien in dem Ordner anzulegen. Dann kann man Stück für Stück Code in die neuen Dateien migrieren (oder komplett neu hinzufügen) und muss ggf. an einigen Stellen im Code ein paar Import-Pfade anpassen. Dort wo diese Methode nicht möglich ist, wird es im Folgenden erwähnt werden und teilweise wird es Vorschläge für Best Practices geben, aber da dieses Vorgehen prinzipiell immer Möglich ist, wird es nicht jedesmal erwähnt und nur von den Dateinamen ausgegangen.
models.py
In der models.py werden die Django-Modelle erstellt. Dieser Name ist nicht beliebig, da Django beim Einrichten der Datenbank und beim Laden der Models genau hier nachschaut und alle Klassen, die von django.db.models.Model erben als Models behandelt. Will man die Datei models.py in einen Ordner umwandeln um den Code auf mehrere Dateien zu verteilen, so muss man beachten dass app_label in der Meta Klasse des Models von Hand zu setzen, sonst kommt Django durcheinander. Außerem sollte man alle Models in der Datei models/__init__.py importieren, damit sie beim Einrichten der Datenbank auch berücksichtig werden. Beim Laden eines Django-Projekts wird Code in der models.py ausgeführt, das heißt hier ist z.B. ein Punkt wo man Callbacks im Django-Dispatcher registrieren kann (der einzige andere Ort wäre die Datei __init__.py im App-Order).
views.py
Diese Datei hat keine spezielle Bedeutung, sondern heißt nur aus Konvention so. Django Views werden in den URL-Konfigurationen immer direkt oder als String, der den Python-Import-Pfad enthällt angegeben. Da man also z.B. einen View als 'myproject.myapp.views.my_view_function' angibt, wird schnell klar, dass der Name view hier beliebig austauschbar ist. Hat man in einer App sehr viele Views macht es Sinn einen Ordner views anzulegen und darin z.B. die Datei ajax.py, in die man spezielle Views, die nur per XML-HTTP-Request angesprochen werden auszulagern, dies hällt den Code übersichtlicher.
admin.py
Die Datei admin.py hat seit dem Merge der Newforms-Admin Branch von Django eine spezielle Bedeutung. Benutzt man in der URL-Konfiguration den Autodiscover-Modus des Admin-Interfaces:
from django.contrib import admin
admin.autodiscover()
So wird für jedes App, die in der Einstellung INSTALLED_APPS gelistet ist versucht die Datei admin.py zu importieren und damit die Models im Admin-Interface zu registrieren. Benutzt man den Autodiscover-Modus nicht so muss man die Modelle, in der models.py oder in der __init__.py Datei registrieren. Best Practice wäre es hier in der __init__.py folgenden Code zu haben:
import admin
Und den Code zum registrieren der Models trotzdem in der Datei admin.py zu belassen. Somit fällt nicht nur ein Wechsel zwischen Autodiscover oder nicht leichter, sondern der Code bleibt auch sauber strukturiert.
management.py
Die Datei mangement.py bzw. der Ordner management in einer Django-App wird immer dann importiert, wenn man mit manage.py oder django-admin.py administrative Kommandos in einem Projekt ausführt. Hat man z.B. eine App, die spezielle Aktionen ausführen muss, wenn Django die Datenbank einrichtet (manage.py syncdb), so ist der korrekte Ort hierfür die Datei management.py, hier kann man z.B. eine Funktion für das post_syncdb-Signal registrieren und so seine Aktion ausführen lassen.
Hat man eine App, die ein eigenes Management-Kommando, also eins, was man mit manage.py ausführen kann, mitliefert, so ist der korrekte Ort dafür der Ordner management/commands, mehr dazu gibt es in der Dokumenation der Management-Commands.
tests.py
Die Datei tests.py hat eine spezielle Bedeutung in Django-Apps. In diese Datei gehören die Unittests für die App. Führt man manage.py test aus, so wird pro App diese Datei importiert und die angelegten Tests werden ausgeführt.
templates/
Der Ordner templates in einer Django-App, hat insofern eine spezielle Bedeutung, als dass der app_directories-Template-Loader hier standardmäßig nach Templates sucht. In den Settings eines Projekts ist dieser Loader in der Einstellung TEMPLATE_LOADERS voreingestellt, d.h. man kann diesen Ordner für App-spezifische Templates benutzen, ohne etwas konfigurieren zu müssen.
templatetags/
Dieser Ordner hat ebenfalls eine spezielle Bedeutung, benutzt man in einem Template spezielle Templates-Tags oder -Filter, die man mit {% load my_stuff %} lädt, so sucht Django in allen Apps in den Ordnern templatetags nach einer Datei my_stuff.py um von dort Template-Tags und -Filter zu laden. Mehr dazu in der offiziellen Dokumentation.
fixtures/
Die Management-Kommandos syncdb und loaddata wissen beide, wie über sog. Fixtures Daten in die Datenbank eingefügt werden. syncdb wird dabei immer automatisch die Fixtures in der Datei initial_data (mit der jeweiligen Endung je nach Datenformat, z.B. .json, .xml etc) laden und das loaddata Kommando wird immer die jeweils angegeben Fixtures laden. Der Ordner fixtures/ kommt hier insofern ins Spiel, als dass beide Kommandos an drei Orten nach Fixtures suchen:
- Im Ordner fixtures
- In allen Ordnern aus settings.FIXTURE_DIRS
- Im absoluten Pfad, falls einer angegeben wurde (trifft nur auf loaddata zu)
forms.py
Diese Datei ist ein sinnvoller Ort für sämtliche in einer App verwendeten Formular-Klassen, hat aber keine spezielle Bedeutung für Django.
fields.py
Benutzt eine App spezielle Model-Fields, so macht es Sinn diese in der Datei fields.py zu definieren, für Django hat diese Datei keine spezielle Bedeutung.
widgets.py
Benutzt ein Formular-Feld ein spezielles Widget, so macht es Sinn dieses in der Datei widgets.py zu definieren, für Django hat diese Datei keine spezielle Bedeutung.
urls.py
In der Root-URL-Konfiguration (spezifiziert über settings.ROOT_URLCONF, siehe oben) kann man mit include() an bestimmten Stellen weitere URL-Konfigurationen laden. Eine App-spezifische URL-Konfiguration ist in der Datei urls.py gut aufgehoben, auch wenn der Name für Django keine spezielle Bedeutung hat.
middleware.py
Benötigt eine App spezielle Middlewares, so macht es Sinn die Middleware-Klasse(n) in der Datei middleware.py abzulegen. Django lädt alle Middlewares, die in settings.MIDDLEWARE_CLASSES angegeben sind, der Dateiname hat also keine spezielle Bedeutung, ist aber der sinnvollste Ort.
utils.py
Die Datei utils.py (oder oft auch ein Ordner utils mit einer __init__.py und mehreren Dateien darin) macht Sinn, wenn man mit einer App Code ausliefert, der eher Helfer-Charakter hat und und/oder keinem anderen Ort wirklich sinnvoll zugeordnet werden kann.
context_processors.py
Bringt eine App eigene Context-Processors mit, welche über settings.TEMPLATE_CONTEXT_PROCESSORS geladen werden, so macht es Sinn diese in der Datei context_processors.py abzulegen, der Name an sich hat jedoch keine spezielle Bedeutung für Django.
managers.py
Gibts es in einer App spezielle Manager für ein oder mehrere Models so kann man überlegen, ob die Manager direkt in der models.py liegen sollen, oder ob es übersichtlicher wird, wenn diese in einer extra Datei liegen. Sinnvoll wäre die Datei managers.py, wenn die Manager ausgelagert werden sollen. Für Django hat der Dateinamen keine spezielle Bedeutung.
feeds.py
Die Datei feeds.py ist ein sinnvoller Ort um alle Feeds, die eine App bereitstellt (meist über django.contrib.syndication) zu definieren. Für Django hat diese Datei keine spezielle Bedeutung.
signals.py
Gibt es in einer App eigene Signale die zusammen mit django.dispatch verwendet werden, wäre ein sinnvoller Ort zum definieren der Signale die Datei signals.py. Für Django hat diese Datei keine spezielle Bedeutung.
admin_views.py / views/admin.py
Bringt eine App eigenes Views mit, die das Admin-Interface (django.contrib.admin) erweitern oder verändern und welche nicht in admin.py passen, so macht es wahrscheinlich am meisten Sinn diese entweder in die Datei admin_views.py oder views/admin.py zu speichern. Letzteres macht natürlich nur dann Sinn, wenn man die views.py sowieso schon in einen Ordner umgewandelt hat um den Code besser aufzuteilen. Ist dies nicht der Fall wäre admin_views.py wohl besser geeignet.
