Terminology

• Modular Programming - Python Modules
  • Modules allow code-reuse between programs (functions allow re-use in a program)
  • Separating functionality into independent, interchangeable modules
  • Modules generally contain code related to one desired functionality
  • They provide an interface usable by other modules
  • Input, UI and the computations of your program generally should not overlap
  • Makes code easier to maintain and test
  • Allows specialization and division of labor
• Packages
  • Mechanism for organizing related modules/ classes
  • Provide a way of structuring multiple modules into a program or library
  • Python programs and library are delivered as packages
• Comments vs. docstring
  • Comments stay inside the code
  • Documentation strings (docstrings) are used to generate designated documentation
  • It is too easy to forget updating external documentation
  • See example in ipython
• Doctest
• Test-driven development (TDD)
• Magic constants
  • Bad for code maintenance and readability

  • # ...
    profit = round(profit, 2)
    effort = round(effort, 2)
    
    postal_code = data.get("postal_code", 8010)
    

  • PRECISION = 2  # use given precision throughout the program
    DEFAULT_POSTAL_CODE = 8010
    # ...
    profit = round(profit, PRECISION)
    effort = round(effort, PRECISION)
    
    postal_code = data.get("postal_code", DEFAULT_POSTAL_CODE)
    

• Maintenance
  • Copy and paste of functions used in different programs would lead to maintenance nightmares
  • Code without tests (aka. legacy code) is extremely difficult to work with

Python Modules

• Every *.py file is a module
  • A program can contain many modules
  • If a program consists of a single file, the file is a module as well as a program
  • Programs are designed to be executed, modules are designed to be used (imported) by programs
• Code in one module can be accessed from other modules

  import name
  from name import object
  

• Modules are executed whenever they are imported
  • Use the ifmain pattern when appropriate

  • if __name__=="__main__":  # not executed when imported as a module
        sys.exit(main())
    

    or

    if __name__=="__main__":  # not executed when imported as a module
        import doctest
        doctest.testmod()
    

• Avoid name clashes (particularly with the standard library)
• How are modules found?
  • PYTHONPATH
  • sys.path

• Independent functionality should reside in different modules

• solver.py  

  """
  Solver for different equations.
  """
  
  import cmath
  import math
  
  def quadratic(a, b, c):
      """
      Compute the solution to a quadratic equation.
      """
      root = b ** 2 - 4 * a * c
      if root >= 0:
          sqrt = math.sqrt
      else:
          sqrt = cmath.sqrt
      x1 = (-b + sqrt(root)) / (2 * a)
      x2 = (-b - sqrt(root)) / (2 * a)
      return x1, x2
    

• ui.pyw  

  #!/usr/bin/env python3
  
  import tkinter as tk
  from solver import quadratic
  
  
  def click_solve():
      x1, x2 = quadratic(float(a.get()), float(b.get()), float(c.get()))
      print('x1:', x1, 'x2:', x2)
  
  app = tk.Tk()
  a = tk.StringVar()
  b = tk.StringVar()
  c = tk.StringVar()
  app.title('Solver for Quadratic Equations')
  tk.Entry(app, width=3, textvariable=a).pack(side=tk.LEFT, pady=10)
  tk.Label(text=' x^2 + ').pack(side=tk.LEFT, pady=10)
  tk.Entry(app, width=3, textvariable=b).pack(side=tk.LEFT, pady=10)
  tk.Label(text=' x + ').pack(side=tk.LEFT, pady=10)
  tk.Entry(app, width=3, textvariable=c).pack(side=tk.LEFT, pady=10)
  tk.Label(text=' = 0').pack(side=tk.LEFT, pady=10)
  tk.Button(app, text='solve', command=click_solve).pack(side=tk.LEFT, padx=10)
  app.mainloop()
    

Creating + Installing Packages

• Every code directory needs a __init__.py
• setup.py file is at the heart of a Python project
• Find Python packages at PyPI
• Upload your own Python packages to PyPI
• Pip Installs Python (pip)
  • Standard Python package manager
  • Formerly, easy_install was the main installer
  • sudo pip3 install ${PACKAGE_NAME}
• Alternatively, use your distribution's installer
  • Debian-based: sudo apt install python3-${PACKAGE_NAME}
  • emerge, yum, ...
• How To Package Your Python Code

Documentation

• Every package/ module/ class/ function should have a one-liner stating what its purpose is
• Use docstrings if available in your language
• Source code represents primary knowledge
  • Secondary knowledge takes the form of more human-readable documentation
• Given the source code - is there a need for secondary documentation?
  • Yes!
  • Representing a model/ thoughts in code is easier than deducting that model/ these thoughts from code
  • Document the high level
  • Document reasoning behind decisions
• What should be documented?
  • Everything that should be explained, but can't be said in code
  • High level documentation
  • Reasoning behind design decisions
  • Installation and usage instructions
  • ...

Docstrings

• Use triple-quoted strings: """ or '''
• From within Python, __doc__ gives access to an object's docstring
• To access the documentation, you can use the help function

• doc.py  

  """
  This module provides basic mathematical functions.
  """
  
  def add(first, second):
      """
      Return the sum of the parameters.
  
      Arguments:
      first -- an integer or floating point number
      second -- an integer or floating point number
      """
      return first + second
  
  print(__doc__)
  print(add.__doc__)
  help(add)
    

Doctests

• Key purpose is tutorial documentation
  • Explain what a function/ class/ module/ package does with examples
  • Show how a function/ class is to be used
• Syntax
  • Derived from the standard Python interpreter shell
  • Primary prompt: >>> followed by new commands
  • Secondary prompt: ... when continuing commands on multiple lines
  • Results are displayed without indentation
  • Blank line or lines starting with the primary prompt mark the end of the output
  • Use the regular python3 interpreter or set %doctest_mode in ipython3
• Example

  doctest_sample.py  

  def add(first, second):
      """
      Return the sum of the parameters.
  
      All arguments need to have the same type (string or number).
  
      Arguments:
      first -- an integer, floating point number or string
      second -- an integer, floating point number or string
  
      >>> add(1,3)
      4
      >>> add("spam", " eggs")
      'spam eggs'
      >>> add(7, -3.0)
      4.0
      >>> add("foo", 42)
      Traceback (most recent call last):
          ...
      TypeError: can only concatenate str (not "int") to str
      """
      return first + second
    

• Dangers
  • Doctests should be an addition to unit tests - not a replacement
  • Avoid cluttering your code
• No output to be shown when tests pass
• Execution

  $ python3 -m doctest doctest_sample.py
  $ python3 -m doctest -v doctest_sample.py  # detailed output
  

  • Running executable scripts with -m doctest doesn't work (-m doctest would be an argument to the script and not to the Python interpreter)
• Doctests can also be written in textual documentation files

  $ python3 -m doctest -v example.txt