Vytváříme Python projekt

16. Vytváříme Python projekt#

Ukážeme si, jak vytvořit kompletní projekt v Pythonu. Navrhneme vhodnou adresářovou strukturu. Ukážeme si některé nástroje, které je možné použít, včetně verzovacího systému Git. A řekneme si něco málo o distribuci ve světě Pythonu.

16.1. Vhodná adresářová struktura#

Python nevyžaduje žádnou speciální strukturu adresářů, existují pouze zvyklosti. Přehled takových zvyklostí najdeme např. v https://realpython.com/python-application-layouts/.

Úplně jednoduchý projekt (script):

helloworld/
│
├── .gitignore
├── helloworld.py
├── LICENSE
├── README.md
├── pyproject.toml
└── tests.py

Typický projekt - instalovatelná knihovna:

helloworld/
│
├── helloworld/
│   ├── __init__.py
│   ├── helloworld.py
│   └── helpers.py
│
├── tests/
│   ├── helloworld_tests.py
│   └── helpers_tests.py
│
├── .gitignore
├── LICENSE
├── README.md
└── pyproject.toml

V první řadě vytvoříme adresář, kam dáváme všechny soubory týkající se projektu.

16.2. PEP 8#

O PEP 8 jsme se již zmínili. Tento dokument ovšem obsahuje natolik důležité konvence, že je dobré ho znovu připomenout. Jeho znalost a dodržování výrazně zlepšuje čitelnost kódů od ostatních / ostatními programátory. Vhodné je, aby přímo editor kontroloval PEP 8, případně alespoň použít samostatný pep8 příkaz.

Několik důležitých bodů:

  • Use 4 spaces per indentation level. Spaces are the preferred indentation method.

  • Limit all lines to a maximum of 79 characters. The preferred way of wrapping long lines is by using Python’s implied line continuation inside parentheses, brackets and braces.

  • Avoid extraneous whitespace in the following situations:

    • Immediately inside parentheses, brackets or braces.

    • Immediately before a comma, semicolon, or colon:

    • Immediately before the open parenthesis that starts the argument list of a function call:

    • Immediately before the open parenthesis that starts an indexing or slicing:

    • More than one space around an assignment (or other) operator to align it with another.

  • Modules should have short, all-lowercase names.

  • Almost without exception, class names use the CapWords convention.

  • Function names should be lowercase, with words separated by underscores as necessary to improve readability.

16.3. Cvičný projekt: načítání csv souboru#

Na ukázku si zkusíme načíst csv soubor. To není příliš složité, navíc si specifikaci ještě trochu zjednodušíme. Co budeme od projektu chtít:

  1. Načíst csv (specifikace např. na wikipedii (pro jednoduchost nebudeme uvažovat uvozovky) soubor do seznamu řádků.

  2. Zvolit si oddělovač řádků

  3. Každý řádek bude reprezentován seznamem.

  4. Každá položka bude převedena na int, float nebo str podle obsahu.

  5. Napíšeme unit testy pro nose.

  6. Vytvoříme dokumentaci pomocí Sphinx.

Co se může hodit#

  • Práce se soubory (open + iterace)

  • str metody split, strip

  • Převod na float a int

  • Generátorova notace

16.4. Verzovací systém Git#

Vhodné je používat nějaký nástroj na správu verzí. V současnosti je nejrozšířenější Git. Základní kroky jsou:

  1. Vytvořit adresář projektu.

  2. Inicializovat pomocí git init.

  3. Přidat nebo změnit soubory.

  4. Změněné / nové soubory přidat pomocí git add <jména souborů>.

  5. Vytvořit revizi pomocí git commit.

  6. … zpět na 3.

16.5. Testování pomocí pytest#

pytest umožňuje jednoduše spravovat a spouštět unit testy.

  1. V adresáři tests vytvoříme soubor(y)s testy, např. tests_main.py.

  2. V tomto souboru implementujeme funkce, které začínají test_ (např. test_int). Typicky v těchto funkcích používáme pro testování assert.

  3. Testy spustíme pomocí python -m pytest.

16.6. Dokumentace pomocí MkDocs#

MkDocs je moderní nástroj pro vytváření dokumentace, který používá Markdown místo reStructuredText. Je jednodušší na používání než Sphinx a vytváří krásnou, moderně vypadající dokumentaci. Výsledkem je například dokumentace Material for MkDocs.

Základní postup#

  1. Nainstalujeme potřebné balíčky:

    pip install mkdocs mkdocstrings[python] mkdocs-material

  2. Vytvoříme nový projekt:

    mkdocs new .

  3. Upravíme konfigurační soubor mkdocs.yml:

    site_name: Název projektu
theme:
  name: material
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          paths: [.]  # cesta k Python modulům
          options:
            show_source: true

  4. Vytvoříme dokumentaci v Markdown souborech v adresáři docs/

  5. Spustíme lokální server pro náhled:

    mkdocs serve

  6. Vygenerujeme finální dokumentaci:

    mkdocs build

16.7. Jak software publikovat#

Publikace softwaru je spíše pokročilejší téma a nebudeme se mu příliš věnovat. Jedním z možných a doporučených postupů je použít uv, viz https://docs.astral.sh/uv/guides/package/.