courses:mldl:lab1 [IIS Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Środowiska Wirtualne ======
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**.

===== Środowiska Anacondy =====
Anaconda dostarcza bardzo zaawansowany system zarządzania pakietami, środowiskami wirtualnymi, ale też całymi środowiskami. Można ją pobrać z [[https://www.anaconda.com|Anaconda]].

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

==== Tworzenie i aktywowanie środowiska ====
  * Utworzenie nowego środowiska:
    <code bash>
    conda create --name <nazwa_srodowiska>
    </code>

  * Utworzenie środowiska z konkretną wersją Pythona:
    <code bash>
    conda create --name <nazwa_srodowiska> python=3.8
    </code>

  * Aktywacja środowiska:
    <code bash>
    conda activate <nazwa_srodowiska>
    </code>

==== Instalacja pakietów w środowisku ====
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:
<code bash>
conda install <nazwa_pakietu>
</code>

Instalacja z użyciem pip:
  - Zainstaluj pip z wykorzystaniem condy:
    <code bash>
    conda install pip
    </code>

  - Używaj pip jak zawsze:
    <code bash>
    pip install <nazwa_pakietu>
    </code>

==== Usuwanie i migracja środowiska ====
  * Usunięcie środowiska:
    <code bash>
    conda remove --name <nazwa_srodowiska> --all
    </code>

  * Eksport konfiguracji środowiska:
    - Do pliku requirements.txt:
      <code bash>
      pip list --format=freeze > requirements.txt
      pip install -r requirements.txt
      </code>

    - Do pliku YAML:
      <code bash>
      conda env export > environment.yaml
      conda env create -f environment.yaml
      </code>

===== Środowiska venv =====

==== Tworzenie i aktywowanie środowiska ====
  * Tworzenie nowego środowiska:
    <code bash>
    python -m venv nazwa_katalogu
    </code>

  * Tworzenie środowiska z konkretną wersją Pythona:
    <code bash>
    python3.8 -m venv nazwa_katalogu
    </code>

  * Aktywacja środowiska (Unix/Linux):
    <code bash>
    source nazwa_katalogu/bin/activate
    </code>

  * Aktywacja środowiska (Windows):
    <code bash>
    nazwa_katalogu\Scripts\activate.bat
    </code>

  * Dezaktywacja środowiska:
    <code bash>
    deactivate
    </code>

==== Instalacja pakietów w środowisku ====
  * Aktywuj środowisko
  * Instaluj pakiety z wykorzystaniem pip, np.:
    <code bash>
    pip install numpy
    </code>

==== Usuwanie i migracja środowiska ====
  * Usunięcie środowiska: dezaktywuj je, a następnie usuń katalog, w którym było utworzone
  * Eksport konfiguracji środowiska:
    <code bash>
    pip list --format=freeze > requirements.txt
    </code>

  * Odtworzenie środowiska:
    <code bash>
    pip install -r requirements.txt
    </code>

==== Podłączenie PyCharm ====
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.
{{:courses:mldl:conda-pycharm.png?600|}}

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


====== Środowisko developerskie ======
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.

===== Tworzenie oprogramowania, dokumentacji i pakietu "klasycznie" =====
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**.

===== GitHub =====
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:  
[[https://github.com/sbobek/wpdm|Repozytorium WPDM]]

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

{{:courses:mldl:welcome-pycharm.png?600|}}

{{:courses:mldl:vcs-pycharm.png?600|}}

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

{{:courses:mldl:working-pycharm.png?600|}}
===== Ćwiczenia =====
  - Dopisz kilka funkcji do modułu **utils** i sprawdź, czy działa ich import – przetestuj działanie.  
  - 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?  

===== PyPi (Python Package Index) =====
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 [[https://pypi.org/|PyPi]] oraz [[https://test.pypi.org/|Test PyPi]]
  * Stwórz plik **.pypirc** w katalogu domowym:

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

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

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

<code>
[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"
</code>

  * Zbuduj projekt lokalnie i przetestuj jego działanie:
<code bash>
python -m pip install --upgrade build
python -m build
</code>

  * Opublikuj projekt w TestPyPi:
<code bash>
python3 -m pip install --upgrade twine
python3 -m twine upload --repository testpypi dist/*
</code>

  * Przetestuj instalację:
<code bash>
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps wpdm
</code>

  * Upload na produkcyjny PyPi:
<code bash>
twine upload dist/*
</code>

Po tej operacji możliwa jest instalacja z wykorzystaniem:
<code bash>
pip install wpdm
</code>

===== Ćwiczenia =====
  - Wykonaj operacje powyżej i sprawdź, czy uda Ci się wyeksportować pakiet do PyPi.  
  - Co daje wykonanie:
<code bash>
pip install wpdm[gpu]
</code>

===== ReadTheDocs =====
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 [[https://readthedocs.org/|ReadTheDocs]].

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

Kroki:

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

{{:courses:mldl:readthedocs.png?600|}}

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

===== Ćwiczenia =====
  - Dodaj nową funkcję/klasę do kodu, zrób push i zobacz, czy dokumentacja poprawnie się zbudowała  
  - Dodaj nową stronę w dokumentacji (np. przykłady użycia)  
  - Posiłkuj się dokumentacją: [[https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html|Sphinx Autosummary]]  





===== Tworzenie oprogramowania z użyciem nbdev =====
**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:  
[[https://nbdev.fast.ai/tutorials/tutorial.html|nbdev Tutorial]]