Differences

This shows you the differences between two versions of the page.

--- courses:mldl:lab1 [2025/09/10 10:02] – created admin
+++ courses:mldl:lab1 [2025/10/08 09:01] (current) – [PyPi (Python Package Index)] drobiu
@@ Line 5: / Line 5: @@
 ===== Ś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].
+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.
@@ Line 11: / Line 11: @@
 ==== Tworzenie i aktywowanie środowiska ====
   * Utworzenie nowego środowiska:
-    `conda create --name <nazwa_srodowiska>`
+    <code bash>
+    conda create --name <nazwa_srodowiska>
+    </code>
   * Utworzenie środowiska z konkretną wersją Pythona:
-    `conda create --name <nazwa_srodowiska> python=3.8`
+    <code bash>
+    conda create --name <nazwa_srodowiska> python=3.8
+    </code>
   * Aktywacja środowiska:
-    `conda activate <nazwa_srodowiska>`
+    <code bash>
+    conda activate <nazwa_srodowiska>
+    </code>
 ==== Instalacja pakietów w środowisku ====
@@ Line 23: / Line 31: @@
 Instalacja z użyciem condy:
-  `conda install <nazwa_pakietu>`
+<code bash>
+conda install <nazwa_pakietu>
+</code>
 Instalacja z użyciem pip:
-  - Zainstaluj pip z wykorzystaniem condy: `conda install pip`
+  - Zainstaluj pip z wykorzystaniem condy:
-  - Używaj pip jak zawsze: `pip install <nazwa_pakietu>`
+    <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:
-    `conda remove --name <nazwa_srodowiska> --all`
+    <code bash>
+    conda remove --name <nazwa_srodowiska> --all
+    </code>
   * Eksport konfiguracji środowiska:
     - Do pliku requirements.txt:
-      `pip list --format=freeze > requirements.txt`
+      <code bash>
-      a następnie w nowym środowisku:
+      pip list --format=freeze > requirements.txt
-      `pip install -r requirements.txt`
+      pip install -r requirements.txt
-    - Do pliku YAML:
+      </code>
-      `conda env export > environment.yaml`
-      a następnie odtworzenie środowiska:
+    - Do pliku YAML:
-      `conda env create -f environment.yaml`
+      <code bash>
+      conda env export > environment.yaml
+      conda env create -f environment.yaml
+      </code>
 ===== Środowiska venv =====
 ==== Tworzenie i aktywowanie środowiska ====
   * Tworzenie nowego środowiska:
-    `python -m venv nazwa_katalogu`
+    <code bash>
-  * Tworzenie środowiska z konkretną wersją Pythona:
+    python -m venv nazwa_katalogu
-    `python3.8 -m venv nazwa_katalogu`
+    </code>
-  * Aktywacja środowiska (Unix/Linux):
-    `source nazwa_katalogu/bin/activate`
+  * Tworzenie środowiska z konkretną wersją Pythona:
-  * Aktywacja środowiska (Windows):
+    <code bash>
-    `nazwa_katalogu\Scripts\activate.bat`
+    python3.8 -m venv nazwa_katalogu
-  * Dezaktywacja środowiska:
+    </code>
-    `deactivate`
+  * 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.:
-    `pip install numpy`
+    <code bash>
+    pip install numpy
+    </code>
 ==== Usuwanie i migracja środowiska ====
-  * Usunięcie środowiska:
+  * Usunięcie środowiska: dezaktywuj je, a następnie usuń katalog, w którym było utworzone
-    dezaktywuj je, a następnie usuń katalog, w którym było utworzone
+  * Eksport konfiguracji środowiska:
-  * Eksport konfiguracji środowiska:
+    <code bash>
-    `pip list --format=freeze > requirements.txt`
+    pip list --format=freeze > requirements.txt
-  * Odtworzenie środowiska:
+    </code>
-    stwórz nowe środowisko i zainstaluj pakiety:
-    `pip install -r requirements.txt`
+  * Odtworzenie środowiska:
+    <code bash>
+    pip install -r requirements.txt
+    </code>
 ==== Podłączenie PyCharm ====
@@ Line 74: / Line 116: @@
 Można również w momencie tworzenia nowego projektu nakazać stworzenie nowego środowiska wirtualnego.
+{{:courses:mldl:conda-pycharm.png?600|}}
-{{:courses:mldl:conda-pycharm.png?400|}}
 ===== Ćwiczenia =====
-  - Utwórz środowisko condy z Pythonem w wersji 3.8 o nazwie **mldl**
+  - Utwórz środowisko condy z Pythonem w wersji 3.8 o nazwie **wpdm**
   - Zainstaluj w nim pakiety (za pomocą pip):
     * pandas==1.4.3
@@ Line 85: / Line 126: @@
     * numdifftools==0.9.41
   - Wyeksportuj konfigurację środowiska do pliku **yaml**
-  - Usuń środowisko **mldl**
+  - 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==6.0.1
+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]]