Jaka jest najlepsza struktura projektu dla aplikacji Python? [Zamknięte]

Wyobraź sobie, że chcesz opracować w Pythonie nietrywialną aplikację komputerową dla użytkowników końcowych (nie WWW). Jaki jest najlepszy sposób na uporządkowanie hierarchii folderów projektu?

Pożądanymi cechami są łatwość konserwacji, łatwość obsługi IDE, przydatność do rozgałęziania / łączenia kontroli źródła oraz łatwe generowanie pakietów instalacyjnych.

W szczególności:

1. Gdzie umieszczasz źródło?
2. Gdzie umieszczasz skrypty uruchamiania aplikacji?
3. Gdzie kładziesz cruft projektu IDE?
4. Gdzie umieszczasz testy jednostkowe / akceptacyjne?
5. Gdzie umieszczasz dane inne niż Python, takie jak pliki konfiguracyjne?
6. Gdzie umieszczasz źródła inne niż Python, takie jak C ++ dla binarnych modułów rozszerzeń pyd / so?

To nie ma większego znaczenia. Cokolwiek cię uszczęśliwia, będzie działać. Nie ma wielu głupich reguł, ponieważ projekty w języku Python mogą być proste.

• /scriptslub /bindla tego rodzaju interfejsu wiersza poleceń
• /tests do twoich testów
• /lib dla twoich bibliotek języka C.
• /doc dla większości dokumentacji
• /apidoc dla dokumentów API generowanych przez Epydoc.

A katalog najwyższego poziomu może zawierać pliki README, Config i tak dalej.

Trudnym wyborem jest to, czy użyć /srcdrzewa. Python nie ma rozróżnienia pomiędzy /src, /libi /binjak Java lub C ma.

Ponieważ /srckatalog najwyższego poziomu jest przez niektórych postrzegany jako nieistotny, katalog najwyższego poziomu może być architekturą najwyższego poziomu aplikacji.

• /foo
• /bar
• /baz

Zalecam umieszczenie tego wszystkiego w katalogu „name-of-my-product”. Jeśli więc piszesz aplikację o nazwie quux, katalog, który zawiera wszystkie te rzeczy, nazywa się /quux.

Kolejny projekt PYTHONPATHmoże zatem obejmować /path/to/quux/fooponowne użycie QUUX.foomodułu.

W moim przypadku, ponieważ korzystam z Edycji Komodo, mój kufel IDE to pojedynczy plik .KPF. Właściwie umieszczam to w katalogu najwyższego poziomu /quuxi pomijam dodawanie go do SVN.

Według struktury systemu plików Jeana-Paula Calderone'a projektu Python :

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

Ten post na blogu autorstwa Jeana-Paula Calderone'a jest często podawany jako odpowiedź w #python na Freenode.

Struktura systemu plików projektu Python

Zrobić:

• nazwij katalog coś związanego z twoim projektem. Na przykład, jeśli projekt ma nazwę „Twisted”, nazwij katalog najwyższego poziomu dla plików źródłowych Twisted. Kiedy robisz komunikaty, należy zawierać numer wersji przyrostka: Twisted-2.5.
• utwórz katalog Twisted/bini umieść tam pliki wykonywalne, jeśli takie masz. Nie podawaj im .pyrozszerzenia, nawet jeśli są to pliki źródłowe Pythona. Nie umieszczaj w nich żadnego kodu oprócz importu i wywołania funkcji głównej zdefiniowanej gdzie indziej w twoich projektach. (Nieznaczne zmarszczki: ponieważ w systemie Windows interpreter jest wybierany przez rozszerzenie pliku, Twoi użytkownicy systemu Windows naprawdę chcą rozszerzenia .py. Więc, kiedy pakujesz dla systemu Windows, możesz chcieć je dodać. Niestety nie ma łatwego distutils sztuczki, że Wiem, że mogę zautomatyzować ten proces. Biorąc pod uwagę, że w POSIX rozszerzenie .py jest tylko brodawką, podczas gdy w systemie Windows brak jest prawdziwym błędem, jeśli twoja baza użytkowników obejmuje użytkowników systemu Windows, możesz zdecydować się na posiadanie .py rozszerzenie wszędzie.)
• Jeśli twój projekt można wyrazić jako pojedynczy plik źródłowy Pythona, to umieść go w katalogu i nazwij coś związanego z 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 pliki źródłowe. Na przykład Twisted/twisted/internet.py.
• umieść testy jednostkowe w sub-pakiecie pakietu (uwaga - oznacza to, że powyższa opcja pojedynczego pliku źródłowego Pythona była podstępem - zawsze potrzebujesz przynajmniej jednego innego pliku do testów jednostkowych). Na przykład Twisted/twisted/test/. Oczywiście, zrób z tego pakiet Twisted/twisted/test/__init__.py. Umieść testy w plikach takich jak Twisted/twisted/test/test_internet.py.
• dodaj Twisted/READMEi Twisted/setup.pywyjaśnij i zainstaluj odpowiednio swoje oprogramowanie, jeśli czujesz się dobrze.

Nie:

• umieść swoje źródło w katalogu o nazwie srclub lib. Utrudnia to uruchomienie bez instalacji.
• umieść swoje testy poza pakietem Python. Utrudnia to uruchomienie testów dla zainstalowanej wersji.
• stwórz pakiet, który ma tylko__init__.py a następnie włóż cały swój kod __init__.py. Po prostu stwórz moduł zamiast pakietu, to jest prostsze.
• spróbuj wymyślić magiczne hacki, aby Python mógł zaimportować moduł lub pakiet bez konieczności dodawania katalogu zawierającego go do ścieżki importu (za pomocą PYTHONPATH lub innego mechanizmu). Będziesz nie prawidłowo obsłużyć wszystkie przypadki, a użytkownicy będą się gniewać na ciebie, gdy oprogramowanie nie działa w ich otoczeniu.

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

Pozwólcie mi wyciągnąć część dotyczącą układu tego znakomitego artykułu:

Podczas konfigurowania projektu ważny jest układ (lub struktura katalogów). Rozsądny układ oznacza, że ​​potencjalni współpracownicy nie muszą spędzać wiecznie na poszukiwaniu kodu; lokalizacje plików są intuicyjne. Ponieważ mamy do czynienia z istniejącym projektem, oznacza to, że prawdopodobnie będziesz musiał coś poruszyć.

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

• Katalog docs zawierający dokumentację projektu
• Katalog o nazwie z nazwą projektu, który przechowuje rzeczywisty pakiet Python
• Katalog testowy w jednym z dwóch miejsc
  • W katalogu pakietu zawierającym kod testowy i zasoby
  • Jako samodzielny katalog najwyższego poziomu Aby lepiej zrozumieć, w jaki sposób należy uporządkować 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 widać, istnieją pewne pliki najwyższego poziomu, katalog docs (wygenerowany jest pusty katalog, w którym sfinks umieści wygenerowaną dokumentację), katalog sandman i katalog testowy pod sandman.

„Python Packaging Authority” ma sampleproject:

https://github.com/pypa/sampleproject

Jest to przykładowy projekt, który stanowi pomoc dla samouczka Python Packaging User Guide na temat pakowania i dystrybucji projektów.

Spróbuj uruchomić projekt przy użyciu szablonu python_boilerplate . W dużej mierze postępuje zgodnie z najlepszymi praktykami (np. Tymi tutaj ), ale lepiej nadaje się w przypadku, gdy w pewnym momencie okaże się, że chcesz podzielić swój projekt na więcej niż jedno jajko (i wierz mi, jeśli chodzi o coś innego niż najprostsze projekty, zrobisz to. często zdarza się, że musisz użyć lokalnie zmodyfikowanej wersji biblioteki innej osoby).

• Gdzie umieszczasz źródło?

  • W przypadku dość dużych projektów sensowne jest podzielenie źródła na kilka jaj. Każde jajko przejdzie jako osobny układ setuptools PROJECT_ROOT/src/<egg_name>.

• Gdzie umieszczasz skrypty uruchamiania aplikacji?

  • Idealną opcją jest zarejestrowanie skryptu uruchamiania aplikacji jako entry_pointjednego z jaj.

• Gdzie kładziesz cruft projektu IDE?

  • Zależy od IDE. Wielu z nich trzyma swoje rzeczy w PROJECT_ROOT/.<something>katalogu głównym projektu i jest w porządku.

• Gdzie umieszczasz testy jednostkowe / akceptacyjne?

  • Każde jajko ma osobny zestaw testów, przechowywany w swoim PROJECT_ROOT/src/<egg_name>/testskatalogu. Osobiście wolę używać ich py.testdo uruchamiania.

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

  • To zależy. Mogą istnieć różne typy danych spoza Pythona.
    • „Zasoby” , tj. Dane, które muszą być spakowane w jajku. Dane te trafiają do odpowiedniego katalogu jaj, gdzieś w przestrzeni nazw pakietów. Może być używany przez pkg_resourcespakiet z setuptoolslub od Pythona 3.7 przez importlib.resourcesmoduł ze standardowej biblioteki.
    • „Pliki konfiguracyjne” , tj. Pliki inne niż Python, które należy traktować jako zewnętrzne w stosunku do plików źródłowych projektu, ale należy je zainicjować z pewnymi wartościami, gdy aplikacja zacznie działać. Podczas programowania wolę przechowywać takie pliki PROJECT_ROOT/config. W przypadku wdrożenia mogą istnieć różne opcje. W systemie Windows można użyć %APP_DATA%/<app-name>/config, w systemie Linux /etc/<app-name>lub /opt/<app-name>/config.
    • Wygenerowane pliki , tj. Pliki, które mogą być tworzone lub modyfikowane przez aplikację podczas wykonywania. Wolałbym zachować je PROJECT_ROOT/varpodczas programowania i /varpodczas wdrażania systemu Linux.
• Gdzie umieszczasz źródła inne niż Python, takie jak C ++ dla binarnych modułów rozszerzeń pyd / so?
  • W PROJECT_ROOT/src/<egg_name>/native

Dokumentacja zwykle przechodzi do PROJECT_ROOT/doclub PROJECT_ROOT/src/<egg_name>/doc(zależy to od tego, czy traktujesz niektóre jajka jako osobne duże projekty). Niektóre dodatkowe konfiguracje będą w plikach takich jak PROJECT_ROOT/buildout.cfgi PROJECT_ROOT/setup.cfg.

Z mojego doświadczenia wynika, że ​​to tylko kwestia iteracji. Umieść swoje dane i kod w dowolnym miejscu. Możliwe, że i tak się pomylisz. Ale kiedy już zrozumiesz, jak dokładnie wszystko się ukształtuje, będziesz w znacznie lepszej sytuacji, aby zgadywać tego rodzaju domysły.

Jeśli chodzi o źródła rozszerzeń, pod katalogiem głównym znajduje się katalog Code zawierający katalog dla Pythona i katalog dla różnych innych języków. Osobiście jestem bardziej skłonny, aby następnym razem umieścić kod rozszerzenia we własnym repozytorium.

Powiedziawszy to, wracam do pierwotnego punktu: nie rób z tego zbyt wielkiego interesu. Połóż to w miejscu, które wydaje się działać dla Ciebie. Jeśli znajdziesz coś, co nie działa, można (i należy) to zmienić.

Dane niebędące pythonami najlepiej jest umieszczać w modułach Pythona, korzystając z package_dataobsługi setuptools . Jedną rzeczą, którą zdecydowanie polecam, jest używanie pakietów przestrzeni nazw do tworzenia wspólnych przestrzeni nazw, z których może korzystać wiele projektów - podobnie jak konwencja Java umieszczania pakietów com.yourcompany.yourproject(i możliwość posiadania wspólnej com.yourcompany.utilsprzestrzeni nazw).

Ponownie rozgałęzianie i scalanie, jeśli użyjesz wystarczająco dobrego systemu kontroli źródła, będzie on obsługiwał scalanie nawet poprzez zmianę nazw; Bazar jest w tym szczególnie dobry.

W przeciwieństwie do niektórych innych odpowiedzi tutaj, jestem na +1 o srckatalogu najwyższego poziomu (z doci testkatalogi obok). Konkretne konwencje dotyczące drzew katalogów dokumentacji będą się różnić w zależności od tego, czego używasz; Na przykład Sphinx ma własne konwencje, które obsługuje narzędzie szybkiego startu.

Proszę, skorzystaj z setuptools i pkg_resources; znacznie ułatwia to innym projektom poleganie na określonych wersjach kodu (i jednoczesne instalowanie wielu wersji z różnymi plikami innymi niż kod, jeśli używasz package_data).