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 Mercurial. 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. Jedna možnost je popsána zde.

Project/
|-- bin/
|-- project/
|   |-- test/
|   |   |-- __init__.py
|   |   |-- test_main.py
|   |-- __init__.py
|   |-- main_module.py
|-- doc/
|-- setup.py
|-- README

V první řadě vytvoříme adresář, kam dáváme všechny soubory týkající se projektu. V něm pak vytvoříme adresář se jménem našeho balíku a souborem __init__.py. Do adresáře test dáme jednotkové testy. Mnoho projektů je má o úroveň výše (jako třeba zde, pak je ovšem těžší je instalovat (nebo je záměrem je neinstalovat).

Nástroje jsou také důležité

Vhodných nástrojů pro vývoj je celá řada. Zcela zásadní je zvolit vhodný editor, ať už je to klasický Vim nebo Emacs nebo námi doporučovaný Sublime Text. Případně můžeme sáhnout po nějakém IDE, např. Pydev, Spyder, IEP, Ninja, PTVS.

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 Mercurial

Vhodné je používat nějaký nástroj na správu verzí. Jedna z možností je Mercurial, který je napsaný přímo v Pythonu. Je to distribuovaný systém, podobně jako např. git (a na rozdíl od subversion). Základní kroky jsou:

  1. Vytvořit adresář projektu.
  2. Inicializovat pomocí hg init.
  3. Udělat první commit pomocí hg commit -A -m 'initial commit'.
  4. ... editace souborů ...
  5. hg add pro nové soubory.
  6. Uložit změny pomocí hg commit -m 'popis co jsem udělal'
  7. Zpět na 4.

Testování pomocí nose

nose umožňuje unit testy spouštět velice jednoduše.

  1. V adresáři project/test vytvoříme soubor(y), např. tests_main.py.
  2. V tomto souboru implementujeme funkce, které začínají test_ (např. test_int). V těchto funkcích používáme pro testování assert.
  3. Testy spustíme pomocí nosetests -vv project/test/.

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. Pokud někdo dokáže vytvořit publikovatelný projekt, bude jistě schopný s pomocí dokumentace a rad na internetu tento projekt publikovat. Základní nástroj je modul distutils. Častěji se ale používá setuptools. Za instalaci (případně kompilaci pokud je součástí projektu např. kód v C) je zodpovědný soubor setup.py.

Komentáře

Comments powered by Disqus