Modernize lessons on exceptions, modules and tests

#13

Author: encukou

courses/pyladies.yml

@@ -74,17 +74,23 @@ sessions:
   - lesson: beginners/nested-traceback
   - lesson: beginners/local-variables
 
-- title: Testování
-  slug: tests
+- title: Chyby a moduly
+  slug: exc
   materials:
   - lesson: beginners/exceptions
   - lesson: beginners/modules
-  - lesson: beginners/testing
-  - lesson: beginners/circular-imports
+  # XXX when homework is added, include lesson: beginners/circular-imports
   - title: Výjimkový tahák
     url: https://pyvec.github.io/cheatsheets/exceptions/exceptions-cs.pdf
     type: cheatsheet
 
+- title: Rozhraní a testy
+  slug: tests
+  materials:
+  - lesson: beginners/interfaces
+  - lesson: beginners/testing
+  - lesson: beginners/main-module
+
 - title: Spolupráce a Open-Source
   slug: foss
   materials:

lessons/beginners/circular-imports/index.md

@@ -1,7 +1,10 @@
 ## Cyklické importy
 
-V domácích projektech budeš rozdělovat 1D Piškvorky na několik modulů.
-Výsledek bude vypadat třeba nějak takhle:
+V domácích úkolech budeš rozdělovat piškvorkový projekt na několik modulů.
+Tento text si doporučuju číst až když narazíš na příslušný úkol,
+abys věděl{{a}} o čem tu je řeč.
+
+Po rozdělení bude projekt vypadat třeba nějak takhle:
 (Šipky mezi moduly znázorňují importování.)
 
 ```plain
@@ -15,16 +18,6 @@ Výsledek bude vypadat třeba nějak takhle:
 └──────────────────┘  │ def tah_hrace │  └──────────────────┘
                       │               │
                       └───────────────┘
-                          ▲
-                          │
-                          │ ┌───────────────────╮
-                          │ │ test_piskvorky.py │
-                          │ ├───────────────────┤
-                          └─│ import piskvorky  │
-                            ├───────────────────┤
-                            │ def test_...      │
-                            │                   │
-                            └───────────────────┘
 ```
 
 Jenže funkce `tah_pocitace`
@@ -47,7 +40,7 @@ Můžeš importovat `ai` z `piskvorky` a zároveň
                       └───────────────┘  
 ```
 
-Můžeme se na to podívat z hlediska Pythonu,
+Můžeš se na to podívat z pohledu Pythonu,
 který příkazy v souborech vykonává.
 Když má importovat soubor `piskvorky.py`, začne ho
 zpracovávat řádek po řádku,
@@ -59,7 +52,7 @@ Brzy narazí na příkaz `import piskvorky`. Co teď?
 Aby nenastala situace podobná nekonečné smyčce –
 jeden soubor by importoval druhý, druhý zase první,
 a tak stále dokola –
-udělá Python taková malý „podvod“:
+udělá Python takový malý „podvod“:
 když zjistí, že soubor `piskvorky.py`
 už importuje, zpřístupní v modulu `ai`
 modul `piskvorky` tak, jak ho

lessons/beginners/exceptions/index.md

@@ -3,21 +3,22 @@
 Pojďme si prohloubit znalosti o chybách, neboli odborně o *výjimkách*
 (angl. *exceptions*).
 
-Vezmi následující funkci:
+Podívej se na následující funkci:
 
 ```python
 def nacti_cislo():
+    """Získá od uživatele celé číslo a vrátí ho"""
     odpoved = input('Zadej číslo: ')
     return int(odpoved)
 ```
 
 Když uživatel nezadá číslice, ale třeba text `cokolada`,
 nastane výjimka jménem `ValueError` (chyba hodnoty) a Python vypíše
-odpovídající chybovou hlášku.
+odpovídající chybovou hlášku:
 
 ```pycon
 Traceback (most recent call last):
-  File "ukazka.py", line 3, in nacti_cislo
+  File "ukazka.py", line 4, in nacti_cislo
     cislo = int(odpoved)
 ValueError: invalid literal for int() with base 10: 'cokolada'
 ```
@@ -27,14 +28,15 @@ Co s tím má chudák funkce `int` dělat?
 Není žádná rozumná hodnota, kterou by mohla vrátit.
 Převádění tohoto textu na celé číslo nedává smysl.
 
-Až funkce `nacti_cislo` nejlíp „ví“, co se má stát, když uživatel nezadá
+Až funkce `nacti_cislo` nejlíp „ví“, co se má stát když uživatel nezadá
 číslice.
 Stačí se uživatele zeptat znovu!
 Kdybys měl{{a}} funkci, která zjistí jestli jsou v řetězci jen číslice,
 mohlo by to fungovat nějak takhle:
 
 ```python
 def nacti_cislo():
+    """Získá od uživatele celé číslo a vrátí ho"""
     while True:
         odpoved = input('Zadej číslo: ')
         if obsahuje_jen_cislice(odpoved):
@@ -47,20 +49,20 @@ def nacti_cislo():
 Kde ale vzít funkci `obsahuje_jen_cislice`?
 Nemá smysl ji psát znovu – funkce `int` sama nejlíp pozná, co se dá převést na
 číslo a co ne.
-A dokonce nám to dá vědět – chybou, kterou můžeš *zachytit*.
+A dokonce nám to dá vědět – výjimkou, kterou můžeš *zachytit*.
 
 > [note]
 > Ono „obsahuje_jen_cislice“ v Pythonu existuje. Dokonce několikrát.
 > Místo řešení problému to ale spíš ilustruje, v čem problém spočívá:
 > * Řetězcová metoda `isnumeric` vrací `True` pokud řetězec obsahuje číslice:
 >   `'123'.isnumeric()` je pravda; `'abc'.isnumeric()` nepravda.
->   Problém je, že funkci `int` potřebuje jeden konkrétní druh číslic:
->   pro řetězce jako `'½'` nebo `'௩三๓໓`' (trojka v tamilském, japonském,
->   thajském nebo laoském písmu) platí `isnumeric`, ale `int` si na nich
+>   Problém je, že funkce `int` potřebuje jeden konkrétní druh číslic:
+>   pro řetězce jako `'½'` nebo `'௩三๓໓`' (trojky v tamilském, japonském,
+>   thajském a laoském písmu) platí `isnumeric`, ale `int` si na nich
 >   vyláme zuby stejně jako na `'abc'`.
 > * Řetězcová metoda `isdecimal` vrací `True` pokud řetězec obsahuje arabské
 >   číslice 0-9. To už je lepší, ale stejně to úplně nesedí: `int` si poradí
->   s mezerou na začátku, např. s `' 3'`, ale funkce `isdecimal` takový řetězec
+>   s mezerou na začátku, např. s `' 3'`. Funkce `isdecimal` ale takový řetězec
 >   odmítne.
 >
 > Chceš-li zjistit jestli funkce `int` umí daný řetězec převést na číslo,
@@ -73,17 +75,19 @@ Pro zachycení chyby má Python příkaz `try`/`except`.
 
 ```python
 def nacti_cislo():
+    """Získá od uživatele celé číslo a vrátí ho"""
     while True:
         odpoved = input('Zadej číslo: ')
         try:
             return int(odpoved)
         except ValueError:
             print('To nebylo číslo!')
+            # ... a zeptáme se znovu -- cyklus `while` pokračuje
 ```
 
 Jak to funguje?
 Příkazy v bloku uvozeném příkazem `try` se normálně provádějí, ale když
-nastane uvedená výjimka, Python přeskočí zbytek bloku `try` a provede všechno 
+nastane uvedená výjimka, Python přeskočí zbytek bloku `try` a provede všechno
 v bloku `except`.
 Pokud výjimka nenastala, přeskočí se celý blok `except`.
 
@@ -141,10 +145,10 @@ V našem příkladu to platí pro `ValueError` z funkce `int`: víš že uživ
 nemusí vždy zadat číslo ve správném formátu a víš že správná
 reakce na tuhle situaci je problém vysvětlit a zeptat se znovu.
 
-Co ale dělat, kdyš uživatel chce ukončit program a zmáčkne
+Co ale dělat, když uživatel chce ukončit program a zmáčkne
 <kbd>Ctrl</kbd>+<kbd>C</kbd>?
 Nebo když se mu porouchá klávesnice a selže funkce `input`?
-Nejlepší reakce na takovou nečekanou situaci ukončit program a informovat
+Nejlepší reakce na takovou nečekanou situaci je ukončit program a informovat
 uživatele (nebo lépe, programátora), že (a kde) je něco špatně.
 Neboli vypsat chybovou hlášku.
 A to se stane normálně, bez `try`.
@@ -204,22 +208,23 @@ funkce mohla vrátit.
 Místo vrácení výsledku musí tato funkce *signalizovat chybu*.
 S tou se pak může program, který `obsah_ctverce(-5)` zavolal,
 vypořádat – vynadat uživateli, zkalibrovat měřák, nebo, pokud na chybu není
-připravený, sám skončit s chybou (a upozornit tak programátora, že je něco
-špatně).
+připravený, sám skončit s chybou a upozornit tak programátora, že je něco
+špatně.
 
 Jak na to prakticky?
 Chybu můžeš vyvolat pomocí příkazu `raise`.
 Za příkaz dáš druh výjimky a pak do závorek nějaký popis toho, co je špatně.
 
 ```python
 def obsah_ctverce(strana):
+    """Vrátí obsah čtverce s danou délkou strany"""
     if strana > 0:
         return strana ** 2
     else:
         raise ValueError(f'Strana musí být kladná, číslo {strana} kladné není!')
 ```
 
-Podobně jako `return`, i příkaz `raise` ukončí funkci.
+Podobně jako `return` i příkaz `raise` ukončí funkci.
 A nejen tu – pokud na tuhle konkrétní chybu není program předem připravený,
 ukončí se celý program.
 

lessons/beginners/interfaces/index.md

@@ -0,0 +1,107 @@
+# Rozhraní
+
+Už víš že funkce ti umožňují kousek kódu:
+
+* použít (zavolat) na více místech v programu, i když definice je jen jedna,
+* vyčlenit, aby detail (jako načtení čísla od uživatele) „nezavazel“ ve větším
+  programu, který tak může být přehlednější, a
+* pojmenovat, aby bylo jasné co kód dělá i bez toho, abys musel{{a}} číst
+  samotné tělo funkce.
+
+Další výhoda funkce je, že ji můžeš jednoduše vyměnit za jinou,
+lepší funkci – pokud má ta lepší funkce stejné *rozhraní* (angl. *interface*).
+
+Aby se ti líp představovalo, o čem budeme povídat, představ si elektrickou
+zásuvku ve zdi.
+Do takové zásuvky můžeš zapojit počítač, lampu, nabíječku na mobil, vysavač,
+nebo rádio.
+Zásuvka poskytuje elektrický proud; je jedno, jak ho použiješ.
+Stejně tak je jedno jestli je „druhý konec“ zásuvky připojený k solárnímu
+panelu nebo k atomové elektrárně.
+Zásuvka poskytuje elektrický proud, a jsou u ní důležité určité parametry
+(tvar, napětí, frekvence, maximální proud) na kterých se obě strany,
+poskytovatel proudu i spotřebič, shodly.
+Tyhle parametry tvoří *rozhraní*, které umožňuje připojit jakýkoli spotřebič
+k jakékoli elektrárně.
+
+
+## Rozhraní funkce
+
+Podívej se na tuhle hlavičku funkce.
+Je z ní poznat, co ta funkce dělá a jak ji použít?
+
+```python
+def ano_nebo_ne(otazka):
+    """Zeptá se uživatele na otázku a vrátí True nebo False dle odpovědi"""
+    ...
+```
+
+Podobnou funkci už jsi napsal{{a}}.
+Když zavoláš `ano_nebo_ne('Chutná ti čokoláda?')`, otázka se objeví
+na příkazové řádce.
+Když uživatel odpoví, funkce vrátí True nebo False.
+
+Co kdybys ale měl{{a}} následující funkci?
+
+```python
+def ano_nebo_ne(otazka):
+    """Ukáže tlačítka "Ano" a "Ne" a až uživatel jedno zmáčkne, vrátí True
+    nebo False dle stisknutého tlačítka."""
+    ...
+```
+
+<img src="{{ static('yn.png') }}" alt="Screenshot s tlačítky Ano a Ne" style="display:block;float:right;">
+
+Když zavoláš tuhle funkci, `ano_nebo_ne('Chutná ti čokoláda?')`, ukáže se
+okýnko se dvěma tlačítky.
+Když uživatel jedno zmáčkne, funkce vrátí True nebo False.
+
+Z hlediska programu se nic nemění: jediné co se změní je *definice funkce*;
+volání a práce s návratovou hodnotou je pak stejné jako dřív.
+
+
+### Vyzkoušej si to!
+
+Najdi nějaký svůj program, který používá `ano_nebo_ne`, případně jen `print`
+a `input`.
+
+Stáhni si modul <a href="{{ static('tkui.py') }}"><code>tkui.py</code></a>
+do adresáře se svým programem.
+Naimportuj z něho funkce, které potřebuješ.
+Jsou k dispozici čtyři:
+
+```python
+from tkui import input, nacti_cislo, ano_nebo_ne, print
+```
+
+Tento import *přepíše* vestavěné funkce `input` a `print` variantami,
+které mají (téměř) stejné rozhraní – jen dělají něco trochu jinak.
+
+Případné vlastní definice funkcí `nacti_cislo` a `ano_nebo_ne` pak z programu
+vyndej, aby se použily ty naimportované.
+
+> [note]
+> Funkce `tkui.nacti_cislo` potřebuje Python verze 3.7 nebo vyšší.
+> Používáš-li Python 3.6, `nacti_cislo` nenahrazuj.
+
+Program by měl fungovat stejně jako dřív!
+
+Je to tím, že tyto funkce mají stejné *rozhraní* jako jejich dřívější protějšky.
+Rozhraní funkce tvoří všechno, co potřebuje kód který funkce volá:
+
+* jméno, kterým se funkce volá,
+* argumenty, které bere (např. `input` bere otázku jako řetězec; `print`
+  může brát více argumentů k vypsání), a
+* návratová hodnota, se kterou program pracuje dál (např. `input` vrací
+  řetězec; `print` nevrací nic smysluplného).
+
+Nékteré z těchto informací musíš do hlavičky funkce napsat vždy.
+Ty ostatní je dobré popsat v dokumentačním řetězci, aby ten, kdo chce funkci
+použít, věděl jak na to.
+
+
+> [note]
+> Modul `tkui` je jen ilustrační. Je udělaný tak, aby se dobře “instaloval”
+> spíš než aby ti pomohl psát reálné programy.
+> V tomto kurzu se vrátíme zpět k příkazové řádce, která je dělaná tak
+> aby byla užitečná pro programátory.

lessons/beginners/interfaces/info.yml

@@ -0,0 +1,4 @@
+title: Rozhraní
+style: md
+attribution: Pro PyLadies Brno napsal Petr Viktorin, 2020.
+license: cc-by-sa-40