Tworzenie oddzielnych środowisk wirtualnych dla każdego projektu pozwala na pracę z oprogramowaniem które wymaga różnych wersji pakietów Pythona lub zależności. Dzięki temu rozwiązaniu można uniknąć konfliktów między różnymi wersjami pakietów, co pozwala na sprawniejszą pracę nad różnymi projektami.

Zasadniczo są dwa najpopularniejsze rozwiązania do tworzenia środowisk wirtualnych: conda i venv.

Anaconda dostarcza bardzo zaawansowany system zarządzania pakietami, środowiskami wirtualnymi, ale też całymi środowiskami. Można ją pobrać z Anaconda.

Zarządzanie środowiskami i pakietami możliwe jest z poziomu graficznego interfejsu użytkownika, jednak tutaj skupimy się na korzystaniu z CLI.

• Utworzenie nowego środowiska:

    conda create --name <nazwa_srodowiska>
 

• Utworzenie środowiska z konkretną wersją Pythona:

    conda create --name <nazwa_srodowiska> python=3.8
 

• Aktywacja środowiska:

    conda activate <nazwa_srodowiska>
 

Instalacja pakietów jest możliwa na dwa sposoby:

• przy użyciu pip
• przy użyciu natywnego systemu zarządzania pakietami condy

Instalacja z użyciem condy:

conda install <nazwa_pakietu>

Instalacja z użyciem pip:

1. Zainstaluj pip z wykorzystaniem condy:

    conda install pip
 

1. Używaj pip jak zawsze:

    pip install <nazwa_pakietu>
 

• Usunięcie środowiska:

    conda remove --name <nazwa_srodowiska> --all
 

• Eksport konfiguracji środowiska:
  1. Do pliku requirements.txt:

      pip list --format=freeze > requirements.txt
      pip install -r requirements.txt
 

1. Do pliku YAML:

      conda env export > environment.yaml
      conda env create -f environment.yaml
 

• Tworzenie nowego środowiska:

    python -m venv nazwa_katalogu
 

• Tworzenie środowiska z konkretną wersją Pythona:

    python3.8 -m venv nazwa_katalogu
 

• Aktywacja środowiska (Unix/Linux):

    source nazwa_katalogu/bin/activate
 

• Aktywacja środowiska (Windows):

    nazwa_katalogu\Scripts\activate.bat
 

• Dezaktywacja środowiska:

    deactivate
 

• Aktywuj środowisko
• Instaluj pakiety z wykorzystaniem pip, np.:

    pip install numpy
 

• Usunięcie środowiska: dezaktywuj je, a następnie usuń katalog, w którym było utworzone
• Eksport konfiguracji środowiska:

    pip list --format=freeze > requirements.txt
 

• Odtworzenie środowiska:

    pip install -r requirements.txt
 

Zarówno środowisko Anacondy jak i środowisko venv można podłączyć do PyCharma.

Można również w momencie tworzenia nowego projektu nakazać stworzenie nowego środowiska wirtualnego.

1. Utwórz środowisko condy z Pythonem w wersji 3.8 o nazwie wpdm
2. Zainstaluj w nim pakiety (za pomocą pip):
   • pandas==1.4.3
   • numpy==1.22.4
   • scikit-learn==1.1.1
   • numdifftools==0.9.41
3. Wyeksportuj konfigurację środowiska do pliku yaml
4. Usuń środowisko wpdm
5. Odtwórz je z pliku yaml i sprawdź, czy wszystkie pakiety są zainstalowane.

Zazwyczaj w pracy z danymi mamy dużo prototypowania, eksperymentowania, ale finalnie chcemy żeby nasz kod mógł być używany przez innych. Przećwiczymy dwie ścieżki tworzenia takiego oprogramowania.

Dla każdego z poniższych konieczne będzie stworzenie środowiska wirtualnego.

Poniżej specyfikacja dla środowiska:

• pandas>=1.4.3
• numpy>=1.22.4
• scikit-learn>=1.1.1
• matplotlib>=3.5.2
• matplotlib-inline>=0.1.3
• seaborn>=0.11.2
• jupyterlab==4.0.11

Utwórz środowisko korzystając z venv lub condy.

Utwórz repozytorium na GitHub, lub zrób forka repozytorium z już wstępnie przygotowaną hierarchią i strukturą katalogów, która będzie nam potrzebna potem: Repozytorium WPDM

Sklonuj repozytorium z wykorzystaniem CLI lub bezpośrednio z PyCharm i skonfiguruj, aby PyCharm korzystał z wcześniej utworzonego środowiska wirtualnego.

Pracuj nad kodem, rozdzielając część Jupyter Notebooka od części, która potem będzie paczką.

1. Dopisz kilka funkcji do modułu utils i sprawdź, czy działa ich import – przetestuj działanie.
2. Zmień działanie funkcji foo z dodawania na odejmowanie:
   • czy modyfikacja jest automatycznie widoczna w JupyterLab?
   • co się stanie, jeśli wykomentujesz pierwsze dwie linie i zresetujesz kernel?

Korzystanie z lokalnie importowanych plików jest wygodne, ale nie sprawdzi się, kiedy będziecie chcieli udostępnić swój kod szerzej publiczności lub wypuścić go jako część otwartego oprogramowania.

Wtedy warto wiedzieć, jak zapakować kod do pakietu instalowanego przez pip.

Minimalne kroki:

• Zarejestruj się na PyPi oraz Test PyPi
• Stwórz plik .pypirc w katalogu domowym:

[pypi]
  username = __token__
  password = pypi-<twoj_token_z_pypi>

[testpypi]
  username = __token__
  password = pypi-<twoj_token_z_testpypi>

• Stwórz plik pyproject.toml (zastępuje dawny setup.py):

[build-system]
requires      = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "wpdm"
version = "0.1.0"
description = "Warsztat Praktyka Data Mining"
readme = "README.md"
authors = [{ name = "Szymon Bobek", email = "szymon.bobek@gmail.com" }]
license = { file = "LICENSE" }
classifiers = [
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
]
keywords = ["xai", "time-series","explainability", "model-agnostic", "rule-based"]
dependencies = ["pandas>=1.4.3",
    "numpy>=1.22.4",
    "scikit-learn>=1.1.1",
    "matplotlib>=3.5.2",
    "matplotlib-inline>=0.1.3",
    "seaborn>=0.11.2"
    ]
requires-python = ">=3.8"

[project.optional-dependencies]
gpu = ["torch>=2.0.1"]

[project.urls]
Homepage = "https://github.com/sbobek/wpdm"
Documentation = "https://wpdm.readthedocs.org"
Issues = "https://github.com/sbobek/wpdm/issues"

• Zbuduj projekt lokalnie i przetestuj jego działanie:

python -m pip install --upgrade build
python -m build

• Opublikuj projekt w TestPyPi:

python3 -m pip install --upgrade twine==6.0.1
python3 -m twine upload --repository testpypi dist/*

• Przetestuj instalację:

python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps wpdm

• Upload na produkcyjny PyPi:

twine upload dist/*

Po tej operacji możliwa jest instalacja z wykorzystaniem:

pip install wpdm

1. Wykonaj operacje powyżej i sprawdź, czy uda Ci się wyeksportować pakiet do PyPi.
2. Co daje wykonanie:

pip install wpdm[gpu]

Dokumentacja to część kodu równie ważna jak sam kod. Bez niej najczęściej oprogramowanie jest na dłuższą metę nieużywalne.

Jednym z najpopularniejszych serwisów udostępniających dokumentację kodu Python jest ReadTheDocs.

System ten pozwala na automatyczne generowanie dokumentacji i jej hostowanie wprost z repozytorium GitHub.

Kroki:

• Zarejestruj się w ReadTheDocs
• Stwórz plik .readthedocs.yaml w katalogu głównym projektu (określa konfigurację Sphinx-a i środowisko)
• Stwórz katalog docs zawierający:
  1. conf.py (konfiguracja Sphinx-a)
  2. index.rst (strona główna dokumentacji)
  3. make.bat i Makefile (opcjonalne)
• Na stronie ReadTheDocs kliknij “Import Project” i wybierz swój projekt z GitHub

System po każdym pushu automatycznie wygeneruje i opublikuje dokumentację.

1. Dodaj nową funkcję/klasę do kodu, zrób push i zobacz, czy dokumentacja poprawnie się zbudowała
2. Dodaj nową stronę w dokumentacji (np. przykłady użycia)
3. Posiłkuj się dokumentacją: Sphinx Autosummary

nbdev to narzędzie od fast.ai, które pozwala na wykonywanie wszystkich powyższych czynności bez konieczności pamiętania o strukturze i poleceniach.

Spróbuj przejść tutorial nbdev i wykonać analogiczną pracę jak powyżej: nbdev Tutorial