Jaka jest najlepsza struktura projektu dla aplikacji Pythona? [zamknięte]

Według Jean-Paula Calderone ' a struktura systemu plików projektu Pythona :

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

Ten post na blogu Jean-Paul Calderone jest powszechnie podawany jako odpowiedź w #python na Freenode.

Struktura systemu plików projektu Pythona

Do:

• nazwij katalog coś związanego z Twoim projektem. Na przykład, jeśli twój projekt ma nazwę "Twisted", nazwij katalog najwyższego poziomu dla jego plików źródłowych Twisted. Kiedy robisz wydania, powinieneś dodać przyrostek numeru wersji: Twisted-2.5.
• utwórz katalog Twisted/bin i umieść tam swoje pliki wykonywalne, jeśli je masz. Nie podawaj im rozszerzenia .py, nawet jeśli są to pliki źródłowe Pythona. Nie umieszczaj w nich żadnego kodu poza importem i wywołaniem do głównej funkcji zdefiniowanej gdzieś indziej w twoich projektach. (Niewielkie zmarszczki: ponieważ w systemie Windows interpreter jest wybierany przez rozszerzenie pliku, użytkownicy systemu Windows rzeczywiście chcą rozszerzenia. py. Tak więc, gdy pakiet dla systemu Windows, może chcesz go dodać. Niestety nie ma łatwej sztuczki, którą znam do zautomatyzuj ten proces. Biorąc pod uwagę, że w POSIX rozszerzenie. py jest tylko brodawką, podczas gdy w Windows brak jest faktycznym błędem, jeśli twoja baza użytkowników Zawiera użytkowników Windows, możesz chcieć po prostu mieć rozszerzenie .py wszędzie.)
• jeśli twój projekt jest wyrażalny jako pojedynczy plik źródłowy Pythona, umieść go w katalogu i nazwij coś związanego z Twoim projektem. Na przykład Twisted/twisted.py. Jeśli potrzebujesz wielu plików źródłowych, Utwórz zamiast tego pakiet (Twisted/twisted/, z pustym Twisted/twisted/__init__.py) i umieść w nim swoje pliki źródłowe. Na przykład Twisted/twisted/internet.py.
• umieść swoje testy jednostkowe w podpakiecie swojego pakietu (Uwaga - oznacza to, że opcja pojedynczego pliku źródłowego Pythona powyżej była sztuczką - ty zawsze potrzebujesz co najmniej jednego innego pliku do testów jednostkowych). Na przykład Twisted/twisted/test/. Oczywiście, niech to będzie paczka z Twisted/twisted/test/__init__.py. Umieść testy w plikach typu Twisted/twisted/test/test_internet.py.
• dodaj Twisted/README i Twisted/setup.py, aby wyjaśnić i zainstalować oprogramowanie, odpowiednio, jeśli czujesz się dobrze.

Nie:

• umieść swoje źródło w katalogu o nazwie src lub lib. To sprawia, że trudno jest uruchomić bez instalacji.
• umieść swoje testy poza pakietem Pythona. Utrudnia to Uruchamianie testów na zainstalowanej wersji.
• Utwórz pakiet, który tylko mA __init__.py, a następnie umieść cały kod w __init__.py. Wystarczy zrobić moduł zamiast pakietu, to jest prostsze.
• spróbuj wymyślić magiczne hacki, aby zrobić Pythona możliwość zaimportowania modułu lub pakietu bez konieczności dodawania katalogu zawierającego go do ścieżki importu (poprzez PYTHONPATH lub inny mechanizm). Będziesz nie poprawnie obsługiwać wszystkie przypadki, a użytkownicy będą się na Ciebie złościć, gdy twoje oprogramowanie nie działa w ich środowisku.

Sprawdź Open Sourcing projektu Pythona we właściwy sposób .

Pozwól mi fragment układ projektu część tego wspaniałego artykułu:

Podczas konfigurowania projektu, układ (lub struktura katalogów) jest ważny, aby uzyskać prawo. Rozsądny układ oznacza, że potencjalni współpracownicy nie muszą spędzać wieczności na szukaniu kawałka kodu; Lokalizacje plików są intuicyjne. Ponieważ mamy do czynienia z istniejącym projektem, oznacza to, że prawdopodobnie będziesz musiał przenieść niektóre rzeczy wokół.

Zacznijmy od początku. Większość projektów ma wiele plików najwyższego poziomu (takich jak setup.py, README.md, wymagania.txt itp.). Istnieją trzy katalogi, które każdy projekt powinien mieć:

• katalog dokumentów zawierający dokumentację projektową
• katalog o nazwie projektu, który przechowuje rzeczywisty pakiet Pythona
• katalog testowy w jednym z dwóch miejsc
  • pod katalogiem pakietów zawierającym test kod i zasoby
  • jako samodzielny katalog najwyższego poziomu Aby lepiej zrozumieć, jak powinny być zorganizowane pliki, oto uproszczona migawka układu dla jednego z moich projektów, 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

Jak widzisz, istnieją pliki najwyższego poziomu, katalog docs (generowany jest pustym katalogiem, w którym sphinx umieści wygenerowaną dokumentację), katalog sandman i katalog testowy pod sandman.

The "Python Packaging Authority" has a sampleproject:

Https://github.com/pypa/sampleproject

Jest to przykładowy projekt, który istnieje jako pomoc w samouczku Python Packaging User Guide na temat pakowania i dystrybucji projektów.

Spróbuj uruchomić projekt używając szablonu python_boilerplate . W dużej mierze jest to zgodne z najlepszymi praktykami (np. te tutaj ), ale lepiej nadaje się na wypadek, gdybyś chciał podzielić swój projekt na więcej niż jedno jajko w pewnym momencie (i uwierz mi, przy czymkolwiek, oprócz najprostszych projektów, zrobisz to. Często zdarza się, że trzeba użyć lokalnie zmodyfikowanej wersji czyjejś biblioteki).

• Gdzie umieścić źródło?

  • W przypadku przyzwoicie dużych projektów sensowne jest podzielenie źródła na kilka jaj. Każde jajko będzie miało osobny układ setuptools pod PROJECT_ROOT/src/<egg_name>.

• Gdzie umieścić skrypty startowe aplikacji?

  • idealną opcją jest zarejestrowanie skryptu startowego aplikacji jako entry_point w jednym z jaj.

• Gdzie umieścić projekt IDE cruft?

  • zależy od IDE. Wielu z nich trzyma swoje rzeczy w korzeniu projektu, a to jest w porządku.

• Gdzie umieszczasz testy jednostkowe / akceptacyjne?

  • każde jajo ma oddzielny zestaw testów, przechowywany w katalogu PROJECT_ROOT/src/<egg_name>/tests. Osobiście wolę używać py.test do ich uruchamiania.

• Gdzie umieszczasz dane inne niż Python, takie jak pliki konfiguracyjne?

  To zależy. Tam mogą to być różne typy danych innych niż Python.
  • "zasoby" , czyli dane, które muszą być zapakowane w jajko. Dane te trafiają do odpowiedniego katalogu egg, gdzieś w przestrzeni nazw pakietów. Można go używać za pośrednictwem pakietu pkg_resources.
  • "config-files" , tzn. pliki inne niż Python, które mają być traktowane jako zewnętrzne pliki źródłowe projektu, ale muszą być zainicjalizowane pewnymi wartościami, gdy aplikacja zacznie działać. Podczas rozwoju wolę zachować takie pliki w PROJECT_ROOT/config. Do wdrożenia mogą być różne opcje. W systemie Windows Można używać %APP_DATA%/<app-name>/config, w Linuksie, /etc/<app-name> lub /opt/<app-name>/config.
  • generowane pliki , czyli pliki, które mogą być tworzone lub modyfikowane przez aplikację podczas wykonywania. Wolałbym trzymać je w PROJECT_ROOT/var podczas programowania i pod /var podczas wdrażania Linuksa.

Dokumentacja zazwyczaj trafia do PROJECT_ROOT/doc lub PROJECT_ROOT/src/<egg_name>/doc (zależy to od tego, czy uważasz niektóre jaja za oddzielne duże projekty). Niektóre dodatkowe konfiguracje będą w plikach takich jak PROJECT_ROOT/buildout.cfg i PROJECT_ROOT/setup.cfg.

Z mojego doświadczenia wynika, że to tylko kwestia iteracji. Umieść swoje dane i Kod, gdziekolwiek myślisz, że idą. Są szanse, że i tak się mylisz. Ale kiedy już masz lepszy pomysł, jak dokładnie rzeczy będą kształtować się, jesteś w znacznie lepszej sytuacji, aby tego rodzaju domysły.

Jeśli chodzi o źródła rozszerzeń, mamy katalog kodu w trunku, który zawiera katalog dla Pythona i katalog dla różnych innych języków. Osobiście jestem bardziej skłonny spróbować umieścić jakiekolwiek następnym razem rozszerz kod do własnego repozytorium.

Z tym powiedziane, wracam do mojego punktu początkowego: nie rób z tego zbyt wielkiej sprawy. Umieść go w miejscu, które Ci odpowiada. Jeśli znajdziesz coś, co nie działa, można (i powinno) zostać zmienione.

Dane inne niż python są najlepiej spakowane wewnątrz modułów Pythona przy użyciu package_data wsparcia w setuptools . Jedną z rzeczy, którą zdecydowanie zalecam, jest używanie pakietów przestrzeni nazw do tworzenia wspólnych przestrzeni nazw, których może używać wiele projektów - podobnie jak Konwencja Java polegająca na umieszczaniu pakietów w com.yourcompany.yourproject (i możliwość posiadania wspólnej przestrzeni nazw com.yourcompany.utils).

Ponowne rozgałęzianie i scalanie, jeśli użyjesz wystarczająco dobrego systemu kontroli źródeł, obsłuży on scalanie nawet poprzez zmianę nazw; Bazaar jest szczególnie dobry w tym.

W przeciwieństwie do innych odpowiedzi tutaj, jestem +1 na posiadanie {[3] } katalogu najwyższego poziomu(z katalogami doc i test obok). Specyficzne konwencje dla drzew katalogów dokumentacji będą się różnić w zależności od tego, czego używasz; na przykład Sphinx ma swoje własne konwencje, które obsługuje narzędzie quickstart.

Proszę, skorzystaj z setuptools i pkg_resources; to znacznie ułatwia innym projektom poleganie na określonych wersjach Twojego kodu (i dla wielu wersji, które mogą być instalowane jednocześnie z różnymi plikami bez kodu, jeśli używasz package_data).