2021-11-22: Tools
=================

.. sectnum::

Development tools:

- pipx: installeer commandline Python programma's
- black: formateer Python broncode
- isort: sorteer imports
- flake8: "linter"
- pylint: "linter"
- poetry: vergemakkelijk gebruik van virtual environments en packaging


Intro
-----
We gebruiken bestanden in de prog4-exercises repository om de tools te leren gebruiken.

Opgave
^^^^^^
Update je GIT-fork van prog4-exercises.


pipx
----
:program:`pipx` laat toe om Python commandline programma's makkelijk te gebruiken vanuit
een commandoprompt venster.


Opgave
^^^^^^
Installeer pipx met::

  python3 -m pip install --user pipx
  python3 -m pipx ensurepath

Zie de pipx website op https://pypa.github.io/pipx/.


:abbr:`PEP8 (Python Enhancement Proposal 8)` (style guide)
------------------
Voor vele programmeertalen bestaan er documenten die aangeven hoe je je code best formateert. Zulke documenten noemt men 'style guides'. Deze hebben geen betrekking op de werking van de code, maar op het uitzicht ervan (en dus de leesbaarheid).

:pep:`8`: is de styleguide voor Python. In dit document wordt bijvoorbeeld aangegeven dat je:

- best spaties gebruikt om indentatie aan te geven
- dat je per 4 spaties dient te werken
- dat je best maximaal 79 letter op 1 regel gebruikt
- hoe je whitespace best gebruikt
- dat je best de volgende namen voor variabelen vermijdt: l, O, I (anekdote)

Er bestaan een aantal tools die je hiermee helpen.
:program:`flake8` is een tool die je mogelijke problemen aangeeft.
:program:`black` is een tool die zorgt dat je source code automatisch aan PEP8 voldoet.

De volledige PEP8 style guide vind je op: https://www.python.org/dev/peps/pep-0008/

flake8
------

Gegeven een bestand :file:`main.py`:

.. literalinclude:: ./examples/example_flake8.py
  :language: python
  :linenos:

Geeft :program:`flake8` volgende waarschuwingen::

    main.py:6:1: E303 too many blank lines (4)
    main.py:6:4: E271 multiple spaces after keyword
    main.py:6:16: E201 whitespace after '('
    main.py:6:18: E202 whitespace before ')'
    main.py:6:20: E203 whitespace before ':'
    main.py:7:5: F841 local variable 'y' is assigned to but never used
    main.py:7:6: E221 multiple spaces before operator
    main.py:8:13: E225 missing whitespace around operator


Opgave
^^^^^^
Installeer :program:`flake8` met behulp van :program:`pipx`.
Analyseer de code van :file:`part_style.py` in prog4-exercises met :program:`flake8`.

.. tip:: This is a note admonition.

  Als je het flake8 commando niet kan opstarten vanuit je commandoprompt, controlleer
  dan of het pad naar je %USERPROFILE%/.local/bin in je Windows PATH variabele zit.
  Je kan je Windows PATH variabele bekijken via het volgende commando in een commandoprompt venster::

    echo %PATH%


  Om de PATH variabele aan te passen kan je volgende instructies volgen:
  https://www.java.com/en/download/help/path.html


black
-----

Gegeven volgende code:

.. literalinclude:: ./examples/example_black.py
  :language: python
  

    
Na het commando::

  black mijncode.py


Herformatteert :program:`black` dit zodat het resultaat er als volgt uitziet:

.. literalinclude:: ./examples/example_black_after.py
  :language: python
  

Opgave
^^^^^^
Installeer :program:`black` met behulp van :program:`pipx`.
Formateer de broncode van :file:`part_style.py` met :program:`black`.

isort
-----

Gegeven de volgende code:

.. literalinclude:: ./examples/example_isort.py
  :language: python
  

Maakt :program:`isort` hier het volgende van:

.. literalinclude:: ./examples/example_isort_after.py
  :language: python
  
De imports worden gegroepeerd en vervolgens alfabetisch gesorteerd:
Eerst komen alle imports van modules die in de standaardbibliotheek van Python
zitten. Vervolgens een wit-regel en dan de andere imports.

Opgave
^^^^^^
Installeer :program:`black` met behulp van :program:`pipx`.
Sorteer de imports van :file:`part_style.py` met :program:`isort`.


poetry
------

Het installeren en up-to-date houden van Python packages, en het beheren
van virtual environments wordt door velen als onpraktisch gezien.

Er werden dan ook een aantal systemen ontwikkeld om deze handelingen te vereenvoudigen:

- pipenv
- poetry
- pyflow
- PDM

:program:`pipenv` en :program:`poetry` zijn de populairste hiervan.


Installeer :program:`poetry` met behulp van :program:`pipx`.


Maak een nieuw project aan met :program:`poetry`::

  poetry new mijnproject

  poetry add pygame
  poetry add -D pytest





Documentatie
------------
Commentaar kan je in Python ingeven door de tekst vooraf te laten gaan
door het "#" teken::

  # Dit is commentaar
  v = "hello world"

  
Dit is o.a. bijzonder nuttig om aan te geven wat er in de code gedaan wordt::

  # Gebruik stelling van Pythagoras om schuine zijde te berekenen
  c = math.sqrt(a**2 + b**2)


Docstrings
----------
Een docstring is een string die als eerste regel in een module, functie, klasse
of methode geschreven wordt. Deze string wordt dan als de omschrijving voor
die module, functie, klasse of methode gebruikt. Bijvoorbeeld::

    def kwadraat(x):
        """Geef het kwadraat van x terug"""
        return x**2

    def bmi(g, l):
        """Geef het BMI voor een gewicht g in kilogram en lengte l in meter"""
        return g/l**2