Was ist die beste Projektstruktur für eine Python-Anwendung? [geschlossen]

Question

Stellen Sie sich vor, dass Sie einen nicht-trivialen Endbenutzer-Desktop (nicht Web-) Anwendung in Python entwickeln wollen. Was ist der beste Weg, die Projektordnerhierarchie zu strukturieren?

Erwünschte Merkmale sind einfache Wartung, IDE Freundlichkeit, Eignung für die Quellcodeverwaltung Verzweigung / Zusammenführung und einfache Erstellung von Paketen installieren.

Im Einzelnen:

1. Haben Sie eine Quelle setzen?
2. Wo sehen Sie die Anwendungsstartskripts setzen?
3. Haben Sie ein IDE-Projekt cruft setzen?
4. Wo Sie das Gerät / Abnahmen setzen Sie?
5. Wo sehen Sie nicht-Python-Daten, wie Konfigurationsdateien setzen?
6. Wo sehen Sie nicht-Python-Quellen wie C ++ setzen für pyd / so binäre Erweiterungsmodule?

Answer 1

nicht zu viel Materie. Was auch immer Sie glücklich macht arbeiten. Es gibt nicht viele dumme Regeln, weil Python Projekte einfach sein kann.

• /scripts oder /bin für diese Art von Kommandozeilen-Schnittstelle Sachen
• /tests für Ihre Tests
• /lib für Ihre C-Sprachbibliotheken
• /doc für die meisten Dokumentation
• /apidoc für die Epydoc generierte API-Dokumentation.

Und das Top-Level-Verzeichnis kann enthalten README des, Config und so weiter.

Die harte Wahl ist, ob ein /src Baum zu verwenden. Python hat keinen Unterschied zwischen /src, /lib und /bin wie Java oder C hat.

Da ein Top-Level-/src Verzeichnis von einigen als bedeutungslos zu sehen ist, Ihr Top-Level-Verzeichnis die Top-Level-Architektur der Anwendung sein kann.

• /foo
• /bar
• /baz

Ich empfehle all dies unter dem "name-of-my-Produkt" Verzeichnis setzen. Also, wenn Sie eine Anwendung namens quux schreiben, das Verzeichnis, das all dieses Zeug enthält heißt /quux.

Ein weiteres Projekt des PYTHONPATH, dann können, umfassen /path/to/quux/foo das QUUX.foo Modul wieder zu verwenden.

In meinem Fall, da ich Komodo Edit, mein IDE cuft ist eine einzige .KPF Datei. Ich habe eigentlich, dass in der obersten Ebene /quux Verzeichnis, und lassen es zu SVN hinzugefügt wird.

Answer 2

Nach Jean-Paul Calderone Dateisystem-Struktur eines Python-Projekt :

Project/
|-- bin/
|   |-- project
|
|-- project/
|   |-- test/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |   
|   |-- __init__.py
|   |-- main.py
|
|-- setup.py
|-- README

Answer 3

Der Blog-Eintrag von Jean-Paul Calderone wird allgemein als Antwort in #python auf Freenode gegeben.

  

Dateisystem-Struktur eines Python-Projekt

     

Sie:

     

  
• benennen das Verzeichnis etwas zu Ihrem Projekt. Zum Beispiel, wenn Ihr Projekt „Twisted“ genannt wird, nennen Sie das Top-Level-Verzeichnis für die Quelldateien Twisted. Wenn Sie Meldungen tun, sollten Sie eine Versionsnummer Suffix enthalten. Twisted-2.5
  
• ein Verzeichnis Twisted/bin erstellen und ausführbare Dateien dort setzen, wenn Sie welche haben. Sie sie nicht eine .py Erweiterung geben, auch wenn sie Python-Source-Dateien sind. Stellen Sie keinen Code in ihnen außer einem Import von und zu einer Hauptfunktion irgendwo anders definiert in Ihren Projekten nennen. (Leichte Falten:.. Da unter Windows, der Interpreter durch die Dateierweiterung ausgewählt ist, Windows-Benutzer tatsächlich die Endung .py wollen Also, wenn Sie für Windows-Paket, können Sie es hinzufügen möchten Leider gibt es keine einfache distutils Trick, ich kenne diesen Prozess zu automatisieren. Bedenkt man, dass auf POSIX die Py-Erweiterung ist eine nur eine Warze, während unter Windows das Fehlen wirklich ein Bug ist, wenn Ihr totzukriegen Windows-Benutzer enthält, können Sie entscheiden, nur die .py haben Erweiterung überall.)
  
• Wenn Ihr Projekt ausdrückbar als eine einzelne Python-Quelldatei ist, es dann in das Verzeichnis setzen und es etwas zu Ihrem Projekt nennen. Zum Beispiel Twisted/twisted.py. Wenn Sie mehrere Quelldateien benötigen, erstellen Sie ein Paket statt (Twisted/twisted/, mit einem leeren Twisted/twisted/__init__.py) und platzieren Sie Ihre Quelldateien in ihm. Zum Beispiel Twisted/twisted/internet.py.
  
• setzen Sie Ihre Unit-Tests in einem Unterpaket des Pakets (Anmerkung - dies bedeutet, dass die einzelne Datei Option Python Quelle über einen Trick war - Sie immer mindestens eine andere Datei für Ihr Gerät benötigen Tests). Zum Beispiel Twisted/twisted/test/. Natürlich macht ein Paket mit Twisted/twisted/test/__init__.py es. Die Prüfungen in Dateien wie Twisted/twisted/test/test_internet.py.
  
• hinzufügen Twisted/README und Twisted/setup.py, um Ihre Software zu erklären und zu installieren, bzw. wenn Sie schön fühlen.
  

     

Sie nicht:

     

  
• setzen Sie Ihre Quelle in einem Verzeichnis namens src oder lib. Dies macht es schwer zu laufen, ohne zu installieren.
  
• setzen Sie Ihre Tests außerhalb Ihrer Python-Paket. Dies macht es schwierig, die Tests gegen eine installierte Version ausgeführt werden.
  
• ein Paket erstellen, dass nur ein __init__.py hat und dann den Code alle in __init__.py setzen. Nur ein Modul macht anstatt ein Paket, es ist einfacher.
  
• versuchen, mit magischen Hacks zu entwickeln, um Python Lage zu machen Ihr Modul oder ein Paket zu importieren, ohne dass der Benutzer das Verzeichnis es um ihre Importpfade hinzufügen zu müssen (entweder über PYTHONPATH oder einen anderen Mechanismus) enthält. Sie werden nicht korrekt verarbeiten alle Fälle und Benutzer werden dich wütend, wenn die Software nicht in ihrer Umgebung funktioniert.
  

Answer 4

Sehen Sie sich Open Sourcing eine Python Projekt der richtige Weg .

Lassen Sie mich Auszug mit dem Projekt-Layout Teil dieses ausgezeichneten Artikel:

  

Wenn Sie ein Projekt einrichten, das Layout (oder Verzeichnisstruktur) ist wichtig, richtig zu machen. Ein vernünftiges Layout bedeutet, dass potenzieller Beitrag muß immer nicht ausgeben für ein Stück Code Jagd; Dateispeicherorte sind intuitiv. Da wir mit einem bestehenden Projekt zu tun hat, bedeutet dies, werden Sie wahrscheinlich um ein paar Sachen bewegen müssen.

     

Lassen Sie uns am Anfang beginnen. Die meisten Projekte haben eine Reihe von Top-Level-Dateien (wie setup.py, README.md, requirements.txt, etc). Es gibt dann drei Verzeichnisse, dass jedes Projekt haben sollte:

     

  
• Ein Verzeichnis docs enthält Projektdokumentation
  
• Ein Verzeichnis mit den Projektnamen benannt, die das eigentliche Python-Paket speichert
  
• Ein Testverzeichnis in einem von zwei Orten   
    
  • Unter dem Paketverzeichnis mit Testcode und Ressourcen
    
  • Als Stand-alone-Top-Level-Verzeichnis   Um einen besseren Eindruck davon, wie Sie Ihre Dateien organisiert werden sollen, ist hier eine vereinfachte Momentaufnahme des Layouts für eine meiner Projekte, sandman:
    
  

$ pwd
~/code/sandman
$ tree
.
|- LICENSE
|- README.md
|- TODO.md
|- docs
|   |-- conf.py
|   |-- generated
|   |-- index.rst
|   |-- installation.rst
|   |-- modules.rst
|   |-- quickstart.rst
|   |-- sandman.rst
|- requirements.txt
|- sandman
|   |-- __init__.py
|   |-- exception.py
|   |-- model.py
|   |-- sandman.py
|   |-- test
|       |-- models.py
|       |-- test_sandman.py
|- setup.py

  

Wie Sie sehen können, gibt es einige Top-Level-Dateien, ein Verzeichnis docs (erzeugt ein leeres Verzeichnis, in dem Sphinx die generierte Dokumentation gestellt werden), ein Sandmännchen Verzeichnis und ein Testverzeichnis unter Sandmännchen.

Answer 5

Der "Python Verpackungs Authority" hat eine Sample:

https://github.com/pypa/sampleproject

Es ist ein Beispielprojekt, das auf die Python Verpackung Benutzerhandbuch Tutorial über Verpackungen und Distributing Projekte als Hilfe vorhanden ist.

Answer 6

Versuchen Sie das Projekt startet mit der python_boilerplate Vorlage. Es folgt weitgehend die besten Praktiken (zB diejenigen hier ), aber es ist besser geeignet für den Fall, finden Sie sich bereit, Ihr Projekt in mehr als ein Ei an einem gewissen Punkt zu teilen (und glauben Sie mir, mit etwas, aber die einfachsten Projekte, werden Sie. eine übliche Situation ist, wo Sie haben eine lokal modifizierte Version der Bibliothek jemand anderes verwenden).

• Wo setzen Sie die Quelle?

  • Für anständig große Projekte ist es sinnvoll, die Quelle in mehrere Eier zu spalten. Jedes Ei würde als separates Setuptools-Layout unter PROJECT_ROOT/src/<egg_name>.

• Wo Sie die Anwendungsstartskripts setzen Sie?

  • Die ideale Option ist die Anwendung Startskript als entry_point in einem der Eier registriert haben.

• Wo setzen Sie das IDE-Projekt cruft?

  • Abhängig von der IDE. Viele von ihnen halten ihre Sachen in PROJECT_ROOT/.<something> in der Wurzel des Projektes, und das ist in Ordnung.

• Wo setzen Sie die Einheit / Abnahmen?

  • Jedes Ei einen separaten Satz von Tests hat, gehalten in seinem PROJECT_ROOT/src/<egg_name>/tests Verzeichnis. Ich persönlich bevorzuge py.test zu verwenden, um sie auszuführen.

• Wo wollen Sie nicht-Python-Daten stellen wie Konfigurationsdateien?

  • Es hängt davon ab. Es können verschiedene Arten von nicht-Python-Daten sein.
    • "Ressourcen" , das heißt Daten, die in einem Ei verpackt werden müssen. Diese Daten gehen in das entsprechenden Verzeichnis Ei, irgendwo im Paket-Namespace. Es kann über pkg_resources Paket verwendet werden.
    • „Config-Dateien“ , das heißt nicht-Python-Dateien, die als externe an die Projektquelldateien angesehen werden sollen, haben aber mit einigen Werten initialisiert werden, wenn die Anwendung zu laufen beginnt. Während der Entwicklung ziehe ich solche Dateien in PROJECT_ROOT/config zu halten. Für den Einsatz können verschiedene Optionen. Unter Windows kann man %APP_DATA%/<app-name>/config, auf Linux, /etc/<app-name> oder /opt/<app-name>/config verwenden.
    • Erzeugen Dateien , das heißt Dateien, die von der Anwendung während der Ausführung erstellt oder geändert werden können. Ich würde es vorziehen, sie in PROJECT_ROOT/var während der Entwicklung zu halten, und unter /var während der Linux-Implementierung.
• Wo wollen Sie nicht-Python-Quellen wie C ++ für pyd / so binäre Erweiterungsmodule setzen?
  • In PROJECT_ROOT/src/<egg_name>/native

Dokumentation typischerweise in PROJECT_ROOT/doc oder PROJECT_ROOT/src/<egg_name>/doc gehen würde (dies hängt davon ab, ob Sie einige der Eier betrachten ein separates großen Projekte zu sein). Einige zusätzliche Konfiguration in Dateien wie PROJECT_ROOT/buildout.cfg und PROJECT_ROOT/setup.cfg sein wird.

Answer 7

Nach meiner Erfahrung, es ist nur eine Frage der Iteration. Setzen Sie Ihre Daten und Code, wo immer Sie denken, sie gehen. Die Chancen stehen gut, werden Sie auf jeden Fall falsch sein. Aber sobald Sie eine bessere Vorstellung von genau das bekommen, wie die Dinge laufen oben zu formen, sind Sie in einer viel besseren Position, diese Art von Vermutungen zu machen.

Soweit Erweiterung Quellen haben wir ein Codeverzeichnis unter Stamm, der ein Verzeichnis für Python und ein Verzeichnis für verschiedene andere Sprachen enthält. Persönlich bin ich eher geneigt, um zu versuchen, um eine beliebige Erweiterung Code in sein eigenes Repository beim nächsten Mal setzen.

Mit diesem wird gesagt, ich gehe zurück zu meinem Ausgangspunkt: nicht allzu große Sache daraus machen. Legen Sie es irgendwo, dass für Sie zu arbeiten scheint. Wenn Sie etwas finden, das nicht funktioniert, kann es (und soll) geändert werden.

Answer 8

Nicht-Python-Daten werden in Ihrer Python-Module mit der package_data Unterstützung in Setuptool . Eine Sache, die ich sehr empfehlen ist die Namespace-Pakete mit zu gemeinsamen Namensräume erstellen, die mehr Projekte verwenden können -. Ähnlich wie die Java-Konvention von Paketen in com.yourcompany.yourproject setzen (und hat in der Lage, eine gemeinsame com.yourcompany.utils Namespace)

Re Branching und Merging, wenn Sie gut genug Quellcodeverwaltungssystem verwenden, wird es verschmilzt auch durch Umbenennungen handhaben; Bazaar ist besonders gut darin.

Im Gegensatz zu einigen anderen Antworten hier, ich bin ein eine src Verzeichnis auf oberste Ebene auf, die (mit doc und test Verzeichnissen neben). Konventionen für die Dokumentation Verzeichnisbäume variieren je nachdem, was Sie verwenden; Sphinx zum Beispiel seine eigenen Konventionen hat das seine quickstart-Tool unterstützt.

Bitte, bitte nutzen Setuptools und pkg_resources; Dies macht es viel einfacher für andere Projekte auf bestimmte Versionen des Codes verlassen (und für mehrere Versionen gleichzeitig mit verschiedenen Nicht-Code-Dateien installiert werden, wenn Sie mit package_data).