Dobry sposób na ustrukturyzowanie projektu w Pythonie

Niezależnie od tego, czy pracujesz nad projektem samodzielnie, czy współpracujesz z innymi, istnieją 5 prostych kroków, które pomogą Ci być bardziej zorganizowanym.

1. Utwórz środowisko wirtualne
2. Utwórz osobny katalog dla testów
3. Utwórz różne katalogi na content
4. Dokumentuj swój kod
5. Użyj GitHuba do kontroli wersji

Niektóre sekcje są związane z PyCharmem. Możesz je pominąć, jeśli używasz innego IDE.

1. Utwórz środowisko wirtualne

Aby utrzymać przestrzeń projektową, warto stworzyć środowisko wirtualne i odizolować swoje zależności.

Możesz użyć modułu venv z Pythona i określić wersję Pythona oraz nazwę środowiska. W poniższym przykładzie używam Python3 i wywołuję środowisko venv. Po utworzeniu katalogu należy uruchomić znajdujący się w nim skrypt activate.

Podsumowanie poleceń:

1. python3 -m venv venv→ tworzy wirtualne środowisko
2. source venv/bin/activate→ aktywuje środowisko
3. deactivate→ dezaktywuje środowisko

Wgląd w PyCharm

Jeśli używasz PyCharm, zobaczysz katalog venv wyskakujący w katalogu projektu po lewej stronie. Automatycznie instaluje się w nim mnóstwo rzeczy. Najprawdopodobniej zależy ci tylko na skrypcie activate - jak mogliśmy zauważyć powyżej.

Co ważne, w PyCharm powinieneś wykonać dodatkowy krok, aby Twoje programy mogły działać w środowisku wirtualnym.

Przejdź do prawego dolnego rogu. Powinieneś zobaczyć, którego interpretera używa PyCharm.

Kliknij na „Add Interpreter” i wybierz opcję „Existing environment”.

Następnie przejdź do folderu, w którym utworzyłeś środowisko i wybierz Python z katalogu bin.

Jeśli wszystko działa poprawnie, powinieneś zobaczyć, w prawym dolnym rogu, wersję Pythona, która istnieje w twoim środowisku wirtualnym. Faajnie! 

W dużym skrócie, środowiska wirtualne pozwalają na:

1. Utrzymanie zależności w izolacji. Pozwala to uniknąć sytuacji, w której Twoje projekty używają różnych wersji pakietów i globalnie odinstalowujesz/ponownie instalujesz to, czego potrzebujesz za każdym razem, gdy musisz uruchomić projekt.
2. Dzielenie się zależnościami z innymi ludźmi.

Po zainstalowaniu wszystkich pakietów, których potrzebuje twój projekt, możesz uruchomić:

pip freeze > requirements.txt

pip freeze „zamraża” wszystkie aktualnie używane pakiety/wersje. Następnie zapisujesz wyjście pip freeze przez plik txt.

Inne osoby korzystające z Twojego programu będą wtedy uruchamiać:

pip install -r requirements.txt

i być w stanie zainstalować wszystkie pakiety i poprawne wersje za jednym zamachem. Niesamowite, prawda? 

2. Utwórz osobny katalog dla testów

Na pewno słyszałeś, że tworzenie testów dla swojego kodu to całkiem niezły pomysł. Piszesz więc kod Pythona i próbujesz go przetestować za pomocą Pytest.

Przykład: Powiedzmy, że tworzysz plik o nazwie greetings.py i inny, aby napisać kilka testów o nazwie test_greetings.py.

W tym przykładzie użyję Pytest jako pakietu do testowania. Pytest ma wiele konwencji nazewnictwa. Rozpoczęcie nazwy pliku od test_ jest jedną z nich. Jeśli się do tego zastosujesz, Pytest automatycznie poszuka w bieżącym katalogu i podkatalogach tych plików, które zaczynają się od test_  i je uruchomi.

Aby utworzyć nowe pliki, możesz użyć w swoim terminalu polecenia touch:

W prawej górnej części PyCharm powinieneś zobaczyć coś takiego:

Otwórz greetings.py i napisz prostą funkcję:

def say_hello(name: str) -> str:
  return f'Hello {name}!'

W swoim terminalu możesz uruchomić pip install pytest, aby zainstalować moduł pytest, a następnie po prostu pytest. Ponieważ nie zdefiniowałeś jeszcze żadnego testu, pytest zostanie uruchomiony, ale zbierze 0 elementów.

Otwórz plik test_greetings.py i napisz funkcję testową:

from greetings import say_hello

def test_say_hello():
  output = say_hello('panda')
  assert output == 'Hello panda!'

Zauważ również, że nazwa funkcji musi zaczynać się od test_, np. test_say_hello. Jest to kolejna konwencja nazewnictwa w Pytest.

Jak usunąć błąd ModuleNotFound

Innym dobrym pomysłem jest zebranie wszystkich swoich testów w jednym katalogu.

Gdybyście jednak po prostu tak zrobili, to gdy teraz uruchomicie pytest, zobaczycie, że żaden z waszych testów nie działa. Jeśli przyjrzysz się bliżej, prawdopodobnie otrzymasz ModuleNotFoundError.

Zobaczmy, co się stało i jak to naprawić.

Pytest próbuje zaimportować moduł greetings, ale kończy się niepowodzeniem.

Najprostszym sposobem na naprawienie tego jest udawanie, że katalog test jest pakietem (tj. kolekcją modułów). W katalogu utwórz plik o nazwie __init__.py.

Jest to całkiem pusty plik:

Jednak sam fakt istnienia sprawia, że twój test znów działa.

3. Utwórz różne katalogi na content

Teraz, gdy poznałeś już ideę tworzenia pliku __init__.py, możesz stworzyć tyle katalogów, ile tylko chcesz.

Na przykład:

# if you have something like this:
another_directory/__init__.py
another_directory/module.py

# you can import the code in module.py as
from another_directory import module

# or
import another_directory.module

Zasadniczo:

__init__.py jest używany do oznaczania katalogów jako katalogów pakietów Pythona

Jeśli usuniesz plik __init__.py, Python nie będzie już szukał sub modułów wewnątrz tego katalogu. Tak więc, jeśli spróbujesz zaimportować moduł w innym miejscu, skończy się to niepowodzeniem.

4. Dokumentuj swój kod

Dokumentacja kodu jest bardzo ważna zarówno dla „przyszłego” ciebie, jak i innych osób czytających twój projekt. Niektórzy programiści mówią nawet:

Jeśli trudno jest udokumentować swój kod, rozważ zmianę projektu.

Warto tutaj pamiętać o 3 krytycznych kwestiach:

1. Dodaj docstring z opisem na początku każdego pliku

2. Dodaj docstring do każdej funkcji i klasy

3. Używaj podpowiedzi typu zawsze, gdy definiujesz funkcję lub klasę

Podpowiedzi typów sprawiają, że funkcje i klasy są bardziej czytelne, pozwalają ominąć określanie typu parametrów w dokumentacji oraz można ich użyć do automatycznego sprawdzania kodu za pomocą mypy. 

Istnieje wiele przewodników po stylach dotyczących pisania dobrej dokumentacji. Ja osobiście bardzo lubię Google Style Python Docstring.

5. Użyj GitHuba do kontroli wersji

Jeśli pracujesz z kimś innym, Git + GitHub są niezbędne, jeśli chcesz zrobić code review i uniknąć konfliktów scalania.

Jeśli pracujesz samodzielnie, to nadal są one pomocne, jeśli zapisujemy swoją pracę i chcemy przywrócić zmiany i „cofnąć się w czasie”.

Pierwsze podejście do Gita nie jest usłane różami, ale mogę Ci obiecać, że opłaci się to w przyszłości. Też byliśmy w tym miejscu.

Mam nadzieję, że te wskazówki były dla Ciebie przydatne! 

Oryginał tekstu w jezyku angielskim przeczytasz tutaj.