Differences

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

--- courses:mldl:lab1 [2025/09/10 10:04] – admin
+++ courses:mldl:lab1 [2025/10/08 09:01] (current) – [PyPi (Python Package Index)] drobiu
@@ Line 117: / Line 117: @@
 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**
@@ Line 127: / Line 128: @@
   - 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]]