Vytváříme Python projekt

Komentáře

Zdroj

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.

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
├── requirements.txt
├── setup.py
└── 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
├── requirements.txt
└── setup.py

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

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.

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

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.

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.

Dokumentace pomocí Sphinx

Sphinx je nástroj pro vytváření přehledné a vizuálně atraktivní dokumentace. Sphinx převádí reStructuredText na HTML, LaTeX aj. Navíc dokáže z dokumentace (docstrings) ve zdrojového kódu vytvořit přehlednou dokumentaci v reStructuredText. Výsledkem je např. vlastní dokumentace Pythonu a mnoho dalších.

Základní postup

  1. V adresáři doc spustíme sphinx-quickstart. Odpovíme na otázky, z rozšíření budeme potřebovat autodoc, případně viewcode.
  2. Podíváme se, co Sphinx vytvořil. Především to jsou soubory conf.py a index.rst.
  3. V conf.py téměř na začátku odkomentujeme sys.path.insert řádek a přidáme adresář '..'.
  4. Vytvoříme API dokumentaci pomocí sphinx-apidoc -f -o . ../project (project nahradíme vlastním názvem).
  5. Vytvoříme html pomocí make html.

Jak software publikovat

Publikace softwaru je spíše pokročilejší téma a nebudeme se mu příliš věnovat. Základní postup je popsán např. na https://packaging.python.org/tutorials/packaging-projects/.

Základem je vytvořit soubor setup.py (pro setuptools, který může vypadat zhruba takto:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="example-pkg-YOUR-USERNAME-HERE", # Replace with your own username
    version="0.0.1",
    author="Example Author",
    author_email="author@example.com",
    description="A small example package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/pypa/sampleproject",
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

Pokud to s produkcí a distribucí Python knihoven a aplikací myslíte vážně, podívejte se na https://poetry.eustace.io/.

Komentáře

Comments powered by Disqus