\PassOptionsToPackage{unicode=true}{hyperref} % options for packages loaded elsewhere
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[]{article}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage{fixltx2e} % provides \textsubscript
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage{textcomp} % provides euro and other symbols
\else % if luatex or xelatex
  \usepackage{unicode-math}
  \defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase}
\fi
% use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
% use microtype if available
\IfFileExists{microtype.sty}{%
\usepackage[]{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\IfFileExists{parskip.sty}{%
\usepackage{parskip}
}{% else
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
}
\usepackage{hyperref}
\hypersetup{
            pdftitle={CSci 658-01: Software Language Engineering Python 3 Reflexive Metaprogramming Chapter 3},
            pdfauthor={H. Conrad Cunningham},
            pdfborder={0 0 0},
            breaklinks=true}
\urlstyle{same}  % don't use monospace font for urls
\usepackage{color}
\usepackage{fancyvrb}
\newcommand{\VerbBar}{|}
\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
% Add ',fontsize=\small' for more characters per line
\newenvironment{Shaded}{}{}
\newcommand{\AlertTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}}
\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.49,0.56,0.16}{#1}}
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}}
\newcommand{\BuiltInTok}[1]{#1}
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{#1}}}
\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.53,0.00,0.00}{#1}}
\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.56,0.13,0.00}{#1}}
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}}
\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.73,0.13,0.13}{\textit{#1}}}
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{#1}}}
\newcommand{\ExtensionTok}[1]{#1}
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{#1}}
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{#1}}
\newcommand{\ImportTok}[1]{#1}
\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{#1}}}
\newcommand{\NormalTok}[1]{#1}
\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}}
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{#1}}
\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.74,0.48,0.00}{#1}}
\newcommand{\RegionMarkerTok}[1]{#1}
\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.73,0.40,0.53}{#1}}
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.10,0.09,0.49}{#1}}
\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{#1}}
\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textbf{\textit{#1}}}}
\setlength{\emergencystretch}{3em}  % prevent overfull lines
\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{5}
% Redefines (sub)paragraphs to behave more like sections
\ifx\paragraph\undefined\else
\let\oldparagraph\paragraph
\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
\fi
\ifx\subparagraph\undefined\else
\let\oldsubparagraph\subparagraph
\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
\fi

% set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother

\usepackage{caption}
\DeclareCaptionLabelFormat{nolabel}{}
\captionsetup{labelformat=nolabel}

\title{CSci 658-01: Software Language Engineering\\
Python 3 Reflexive Metaprogramming\\
Chapter 3}
\author{\textbf{H. Conrad Cunningham}}
\date{\textbf{4 May 2018}}

\begin{document}
\maketitle

{
\setcounter{tocdepth}{5}
\tableofcontents
}
Copyright (C) 2018, \href{http://www.cs.olemiss.edu/~hcc}{H. Conrad
Cunningham}\\
Professor of \href{https://www.cs.olemiss.edu}{Computer and Information
Science}\\
\href{http://www.olemiss.edu}{University of Mississippi}\\
211 Weir Hall\\
P.O. Box 1848\\
University, MS 38677\\
(662) 915-5358

\textbf{Note}: This chapter adapts David Beazley's \texttt{debugly}
example presentation from his
\href{http://www.dabeaz.com/py3meta}{Python 3 Metaprogramming tutorial}
at PyCon'2013 {[}Beazley 2013a{]}.

\textbf{Advisory}: The HTML version of this document requires use of a
browser that supports the display of MathML. A good choice as of May
2018 is a recent version of Firefox from Mozilla.

\setcounter{section}{2}
\newpage

\hypertarget{decorators-and-metaclasses}{%
\section{Decorators and Metaclasses}\label{decorators-and-metaclasses}}

In this chapter, we look at metaprogramming using Python decorators and
metaclasses. To do so, we consider a simple tracing debugger case study,
adapted from David Beazley's \texttt{debugly} example from his
metaprogramming tutorial {[}Beazley 2013a{]}.

\hypertarget{basic-function-level-debugging}{%
\subsection{Basic Function-Level
Debugging}\label{basic-function-level-debugging}}

\hypertarget{motivating-example}{%
\subsubsection{Motivating example}\label{motivating-example}}

Suppose we have a Python function \texttt{add}:

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

A simple way we can approach debugging is to insert a \texttt{print}
statement into the function to trace execution, as follows:

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'add'}\NormalTok{)}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

However, suppose we need to debug several similar functions
simultaneously. Following the above approach, we might have code similar
to that in the example below.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'add'}\NormalTok{)}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}

    \KeywordTok{def}\NormalTok{ sub(x, y):}
        \CommentTok{'Subtract y from x'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'sub'}\NormalTok{)}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{-}\NormalTok{ y}

    \KeywordTok{def}\NormalTok{ mul(x, y):}
        \CommentTok{'Multiply x and y'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'mul'}\NormalTok{)}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{*}\NormalTok{ y}

    \KeywordTok{def}\NormalTok{ div(x, y):}
        \CommentTok{'Divide x by y'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'div'}\NormalTok{)}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{/}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

We insert basically the same code into every function.

This code is unpleasant because it violates the Abstraction Principle.

\hypertarget{abstraction-principle-staying-dry}{%
\subsubsection{Abstraction Principle, staying
DRY}\label{abstraction-principle-staying-dry}}

The \emph{Abstraction Principle} states, ``Each significant piece of
functionality in a program should be implemented in just one place in
the source code.'' {[}Pierce 2002, p.~339{]}. If similar functionality
is needed in several places, then the common parts of the functionality
should be separated from the variable parts.

The common parts become a new programming abstraction (e.g.~a function,
class, abstract data type, design pattern, etc.) and the variable parts
become different ways in which the abstraction can be customized
(e.g.~its parameters).

The approach encourages reuse of both design and code. Perhaps more
importantly, it can make it easier to keep the similar parts consistent
as the program evolves.

Andy Hunt and Dave Thomas {[}Hunt 2000, pp.~26-33{]} articulate a more
general software development principle \emph{Don't Repeat Yourself},
known by the acronym \emph{DRY}.

In an interview {[}Venners 2003{]}, Thomas states, ``DRY says that every
piece of system knowledge should have one authoritative, unambiguous
representation. \ldots{} A system's knowledge is far broader than just
its code. It refers to database schemas, test plans, the build system,
even documentation.''

Our goal is to keep our Python 3 code DRY, not let it get WET (``Write
Everything Twice'' or ``Wasting Everyone's Time'' or ``We Enjoy Typing''
{[}Wikipedia 2018a{]}.)

\hypertarget{function-decorators}{%
\subsubsection{Function decorators}\label{function-decorators}}

To introduce an appropriate abstraction into the previous set of
functions, we can use a Python 3 function decorator.

A \emph{function decorator} is a higher-order function that takes a
function as its argument, wraps another function around the argument,
and returns the wrapper function.

The wrapper function has the same parameters and same return value as
the function it wraps, except it does extra processing when it is
called. That is, it ``decorates'' the original function.

Remember that Python 3 functions are objects. Python's decorator
function concept is thus a special case of the
\href{https://en.wikipedia.org/wiki/Decorator_pattern}{Decorator design
pattern}, one of the classic Gang of Four patterns for object-oriented
programming {[}Gamma 1995{]}. The idea of this pattern is to wrap one
object with another object, the decorator, that has the same interface
but enhanced behavior. The decoration is usually done at runtime even in
a statically typed language like Java.

TODO: Perhaps expand on the Decorator design pattern and give a diagram.

\hypertarget{constructing-a-debug-decorator}{%
\subsubsection{Constructing a debug
decorator}\label{constructing-a-debug-decorator}}

In the motivating example above, we want to decorate a function like
\texttt{add(x,y)} by wrapping it with another function that prints the
function name \texttt{add} before doing the addition operation. The
wrapped function can then take the place of the original \texttt{add} in
the program.

Let's construct an appropriate decorator in steps.

In general, suppose we want to decorate a function named \texttt{func}
that takes some number of positional and/or keyword arguments. That is,
the function has the general signature:

\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{    func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
\end{Highlighting}
\end{Shaded}

Note: For more information on the above function calling syntax, see the
discussion on
\href{Py3RefMeta02.html\#function-calling-conventions}{Function Calling
Conventions} in Chapter 2.

In addition, suppose we want to print the content of the variable
\texttt{msg} before we execute \texttt{func}.

As our first step, we define function \texttt{wrapper} as follows:

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ wrapper(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs): }
        \BuiltInTok{print}\NormalTok{(msg) }
        \ControlFlowTok{return}\NormalTok{ func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
\end{Highlighting}
\end{Shaded}

As our second step, we define a decorator function \texttt{debug} that
takes a function \texttt{func} as its argument, sets local variable
\texttt{msg} to \texttt{func}'s name, and then creates and returns the
function \texttt{wrapper}.

Function \texttt{debug} can retrieve the function name by accessing the
\texttt{\_\_qualname\_\_} attribute of the \texttt{func} object.
Attribute \texttt{\_\_qualname\_\_} holds the fully qualified name.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ debug(func): }
\NormalTok{        msg }\OperatorTok{=}\NormalTok{ func.__qualname__ }
        \KeywordTok{def}\NormalTok{ wrapper(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs): }
            \BuiltInTok{print}\NormalTok{(msg) }
            \ControlFlowTok{return}\NormalTok{ func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
        \ControlFlowTok{return}\NormalTok{ wrapper }
\end{Highlighting}
\end{Shaded}

Function \texttt{debug} returns a closure that consists of the function
\texttt{wrapper} plus the the local environment in which
\texttt{wrapper} is defined. The local environment includes the argument
\texttt{func} and the variable \texttt{msg} and their values.

Note: For more information about the concepts and techniques used above,
see the discussion of
\href{Py3RefMeta02.html\#nested-function-definitions}{Nested Function
Definitions}, \href{Py3RefMeta02.html\#lexical-scope}{Lexical Scope},
and \href{Py3RefMeta02.html\#closures}{Closures} in Chapter 2.

It seems sufficient to assign the closure returned by \texttt{debug} to
the name of \texttt{func} as shown below for \texttt{add}.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'} \CommentTok{# docstring (documentation) }
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}
\NormalTok{    add }\OperatorTok{=}\NormalTok{ debug(add)}
\end{Highlighting}
\end{Shaded}

But this does not work as expected as shown in the following REPL
session.

\begin{Shaded}
\begin{Highlighting}[]
    \OperatorTok{>>>}\NormalTok{ add(}\DecValTok{2}\NormalTok{,}\DecValTok{5}\NormalTok{)}
\NormalTok{    add}
    \DecValTok{7}
    \OperatorTok{>>>}\NormalTok{ add.__qualname__}
\NormalTok{    debug.}\OperatorTok{<}\BuiltInTok{locals}\OperatorTok{>}\NormalTok{.wrapper}
    \OperatorTok{>>>}\NormalTok{ add.__doc__}
    \VariableTok{None}
\end{Highlighting}
\end{Shaded}

The closure returned by \texttt{debug} computes the correct result.
However, it does not have the correct metadata, as illustrated above by
the display of the name (\texttt{\_\_qualname\_\_}) and the docstring
(\texttt{\_\_doc\_\_}) metadata.

To make the use of the decorator \texttt{debug} transparent to the user,
we can apply the function decorator \texttt{@wraps} defined in the
standard module \texttt{functools} as follows.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ debug(func): }
\NormalTok{        msg }\OperatorTok{=}\NormalTok{ func.__qualname__ }
        \AttributeTok{@wraps}\NormalTok{(func) }
        \KeywordTok{def}\NormalTok{ wrapper(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs): }
            \BuiltInTok{print}\NormalTok{(msg) }
            \ControlFlowTok{return}\NormalTok{ func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
        \ControlFlowTok{return}\NormalTok{ wrapper}

    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'} \CommentTok{# docstring (documentation) }
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}
\NormalTok{    add }\OperatorTok{=}\NormalTok{ debug(add)}
\end{Highlighting}
\end{Shaded}

The \texttt{@wraps(func)} decorator call above sets function
\texttt{wrapper}'s metadata --- it's attributes \texttt{\_\_module\_\_},
\texttt{\_\_name\_\_}, \texttt{\_\_qualname\_\_},
\texttt{\_\_annotations\_\_}, and \texttt{\_\_doc\_\_} --- to the same
values as \texttt{func}'s metadata.

With this new version of the \texttt{debug} decorator, the decoration of
\texttt{add} now works transparently.

\begin{Shaded}
\begin{Highlighting}[]
    \OperatorTok{>>>}\NormalTok{ add(}\DecValTok{2}\NormalTok{,}\DecValTok{5}\NormalTok{)}
\NormalTok{    add}
    \DecValTok{7}
    \OperatorTok{>>>}\NormalTok{ add.__qualname__    add}
    \OperatorTok{>>>}\NormalTok{ add.__doc__}
\NormalTok{    Add x }\KeywordTok{and}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

Finally, because the definition of a function like \texttt{add} and the
application of the \texttt{debug} decorator function usually occur
together, we can use the decorator \emph{syntactic sugar}
\texttt{@debug} to conveniently designate the definition of a decorated
function. The \texttt{debug} decorator function can be defined in a
separate module.

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@debug}
    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

\hypertarget{using-the-debug-decorator}{%
\subsubsection{Using the debug
decorator}\label{using-the-debug-decorator}}

Given the \texttt{debug} decorator as defined in the previous
subsection, we can now simplify the motivating example.

We decorate each function with \texttt{@debug} but give no other details
of the implementation here. The debug facility is implemented in one
place but used in many places. The implementation supports the DRY
principle.

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@debug} 
    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}

    \AttributeTok{@debug} 
    \KeywordTok{def}\NormalTok{ sub(x, y):}
        \CommentTok{'Subtract y from x'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{-}\NormalTok{ y}

    \AttributeTok{@debug} 
    \KeywordTok{def}\NormalTok{ mul(x, y):}
        \CommentTok{'Multiply x and y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{*}\NormalTok{ y}

    \AttributeTok{@debug}
    \KeywordTok{def}\NormalTok{ div(x, y):}
        \CommentTok{'Divide x by y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{/}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of
\texttt{debug} is available at \href{code/debug4.py}{this link}.

\hypertarget{case-study-review}{%
\subsubsection{Case study review}\label{case-study-review}}

So far in this case study, we have implemented a simple debugging
facility that:

\begin{itemize}
\item
  is implemented once in a place separate from its use
\item
  is thus easy to modify or disable totally
\item
  can be used without knowing its implementation details
\end{itemize}

\hypertarget{variations}{%
\subsubsection{Variations}\label{variations}}

Now let's consider a couple of variations of the debugging decorator
implementation.

\hypertarget{logging}{%
\paragraph{Logging}\label{logging}}

One variation would be to use the Python logging module to log the
messages instead of just printing them {[}Beazley 2013a{]}.

The details of logging are not important here, but note that we only
need to make three changes to the \texttt{debug} implementation. We do
not need to change the user code.

\begin{Shaded}
\begin{Highlighting}[]
      \ImportTok{from}\NormalTok{ functools }\ImportTok{import}\NormalTok{ wraps}
      \ImportTok{import}\NormalTok{ logging  }\CommentTok{# (1) logging module}

      \KeywordTok{def}\NormalTok{ debug(func):}
          \CommentTok{# (2) get the Logger for func's module}
\NormalTok{          log }\OperatorTok{=}\NormalTok{ logging.getLogger(func.__module__)}
\NormalTok{          msg }\OperatorTok{=}\NormalTok{ func.__qualname__}
          \AttributeTok{@wraps}\NormalTok{(func)}
          \KeywordTok{def}\NormalTok{ wrapper(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs):}
\NormalTok{              log.debug(msg)  }\CommentTok{# (3) log msg}
              \ControlFlowTok{return}\NormalTok{ func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
          \ControlFlowTok{return}\NormalTok{ wrapper}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of
\texttt{debug} is available at \href{code/debuglog1.py}{this link}.

\hypertarget{optional-disable}{%
\paragraph{Optional disable}\label{optional-disable}}

Another variation of the debugging decorator would be to only enable
debugging when a particular environment variable is set {[}Beazley
2013a{]}. In this variation, we only need to make two changes to the
\texttt{debug} implementation.

\begin{Shaded}
\begin{Highlighting}[]
    \ImportTok{from}\NormalTok{ functools }\ImportTok{import}\NormalTok{ wraps}
    \ImportTok{import}\NormalTok{ os  }\CommentTok{# (1) import os interface}
    
    \KeywordTok{def}\NormalTok{ debug(func):}
        \CommentTok{# (2) debug only if environment variable set}
        \ControlFlowTok{if} \StringTok{'DEBUG'} \KeywordTok{not} \KeywordTok{in}\NormalTok{ os.environ:}
            \ControlFlowTok{return}\NormalTok{ func}
\NormalTok{        msg }\OperatorTok{=}\NormalTok{ func.__qualname__}
        \AttributeTok{@wraps}\NormalTok{(func)}
        \KeywordTok{def}\NormalTok{ wrapper(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs):}
            \BuiltInTok{print}\NormalTok{(msg)}
            \ControlFlowTok{return}\NormalTok{ func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
        \ControlFlowTok{return}\NormalTok{ wrapper}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of
\texttt{debug} is available at \href{code/debugopt1.py}{this link}.

\hypertarget{extended-function-level-debugging}{%
\subsection{Extended Function-Level
Debugging}\label{extended-function-level-debugging}}

Now we can extend the capability of our simple tracing debugger
{[}Beazley 2013a{]}.

\hypertarget{motivating-example-1}{%
\subsubsection{Motivating example}\label{motivating-example-1}}

Suppose, for whatever reason, we want to add a prefix string to the
debugging message that may differ from one use of \texttt{@debug} to
another. Again consider the set of arithmetic functions.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ add(x, y):}
        \CommentTok{'Add x and y'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'***add'}\NormalTok{)}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{+}\NormalTok{ y}

    \KeywordTok{def}\NormalTok{ sub(x, y):}
        \CommentTok{'Subtract y from x'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'@@@sub'}\NormalTok{) }
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{-}\NormalTok{ y}

    \KeywordTok{def}\NormalTok{ mul(x, y):}
        \CommentTok{'Multiply x and y'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'***sub'}\NormalTok{) }
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{*}\NormalTok{ y}

    \KeywordTok{def}\NormalTok{ div(x, y):}
        \CommentTok{'Divide x by y'} 
        \BuiltInTok{print}\NormalTok{(}\StringTok{'div'}\NormalTok{)}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{/}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

We implement the needed capability by using function decorators with
arguments.

\hypertarget{decorators-with-arguments}{%
\subsubsection{Decorators with
arguments}\label{decorators-with-arguments}}

We can construct decorators that take arguments other than the function
to be decorated.

Consider the following use of decorator \texttt{deco}:

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@deco}\NormalTok{(args)}
    \KeywordTok{def}\NormalTok{ func():}
        \CommentTok{# some body code}
\end{Highlighting}
\end{Shaded}

The above translates into the following decorator call and assignment:

\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{    func }\OperatorTok{=}\NormalTok{ deco(args)(func)}
\end{Highlighting}
\end{Shaded}

The right-hand side denotes the chaining of two function calls. The
system first calls function \texttt{deco} passing it the first argument
list \texttt{(args)}. This call returns a function, which is in turn
called with the second argument list, variable \texttt{(func)}.

The outer function call establishes a local environment in which the
variables in \texttt{args} are defined. In this environment, we define a
normal decorator as we did before.

\hypertarget{prefix-decorator}{%
\subsubsection{Prefix decorator}\label{prefix-decorator}}

We can thus define the outer layer of a prefix decorator with a function
with parameter \texttt{prefix} that defaults to the empty string.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ debug(prefix}\OperatorTok{=}\StringTok{''}\NormalTok{):}
        \KeywordTok{def}\NormalTok{ deco(func):}
            \CommentTok{# normal debug decorator body}
        \ControlFlowTok{return}\NormalTok{ deco}
\end{Highlighting}
\end{Shaded}

The full definition of the prefix decorator is shown below. If no
argument is given to \texttt{debug}, the behavior is (almost) the same
as the previous \texttt{debug} decorator function.

\begin{Shaded}
\begin{Highlighting}[]
    \ImportTok{from}\NormalTok{ functools }\ImportTok{import}\NormalTok{ wraps}

    \KeywordTok{def}\NormalTok{ debug(prefix}\OperatorTok{=}\StringTok{''}\NormalTok{):}
        \KeywordTok{def}\NormalTok{ deco(func):}
\NormalTok{            msg }\OperatorTok{=}\NormalTok{ prefix }\OperatorTok{+}\NormalTok{ func.__qualname__}
            \AttributeTok{@wraps}\NormalTok{(func)}
            \KeywordTok{def}\NormalTok{ wrapper(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs):}
                \BuiltInTok{print}\NormalTok{(msg)}
                \ControlFlowTok{return}\NormalTok{ func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
            \ControlFlowTok{return}\NormalTok{ wrapper}
        \ControlFlowTok{return}\NormalTok{ deco}
\end{Highlighting}
\end{Shaded}

In this formulation, \texttt{prefix} can be given as either a positional
or keyword argument.

We can apply the new prefix debug decorator to our motivating example
functions as follows. Note that the \texttt{prefix} strings vary among
the different occurrences.

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@debug}\NormalTok{(prefix}\OperatorTok{=}\StringTok{'***'}\NormalTok{) }
    \KeywordTok{def}\NormalTok{ add(x,y):}
        \CommentTok{'Add x and y'} 
        \ControlFlowTok{return}\NormalTok{ x}\OperatorTok{+}\NormalTok{y}

    \AttributeTok{@debug}\NormalTok{(prefix}\OperatorTok{=}\StringTok{'@@@'}\NormalTok{) }
    \KeywordTok{def}\NormalTok{ sub(x, y):}
        \CommentTok{'Subtract y from x'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{-}\NormalTok{ y}

    \AttributeTok{@debug}\NormalTok{(}\StringTok{'***'}\NormalTok{) }
    \KeywordTok{def}\NormalTok{ mul(x, y):}
        \CommentTok{'Multiply x and y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{*}\NormalTok{ y}

    \AttributeTok{@debug}\NormalTok{()  }\CommentTok{# parentheses needed!}
    \KeywordTok{def}\NormalTok{ div(x, y):}
        \CommentTok{'Divide x by y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{/}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of
\texttt{debugprefix} is available at \href{code/debugprefix1.py}{this
link}.

\hypertarget{reformulated-prefix-decorator}{%
\subsubsection{Reformulated prefix
decorator}\label{reformulated-prefix-decorator}}

By a clever use of default arguments and partial application of a
function to its arguments, we can transform the definition of the prefix
decorator above to one that does not involve a nested definition.

\begin{Shaded}
\begin{Highlighting}[]
    \ImportTok{from}\NormalTok{ functools }\ImportTok{import}\NormalTok{ wraps, partial}

    \KeywordTok{def}\NormalTok{ debug(func }\OperatorTok{=} \VariableTok{None}\NormalTok{, }\OperatorTok{*}\NormalTok{, prefix }\OperatorTok{=} \StringTok{''}\NormalTok{): }
        \ControlFlowTok{if}\NormalTok{ func }\KeywordTok{is} \VariableTok{None}\NormalTok{:}
            \ControlFlowTok{return}\NormalTok{ partial(debug, prefix}\OperatorTok{=}\NormalTok{prefix)}
\NormalTok{        msg }\OperatorTok{=}\NormalTok{ prefix }\OperatorTok{+}\NormalTok{ func.__qualname__}
        \AttributeTok{@wraps}\NormalTok{(func)}
        \KeywordTok{def}\NormalTok{ wrapper(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs):}
            \BuiltInTok{print}\NormalTok{(msg)}
            \ControlFlowTok{return}\NormalTok{ func(}\OperatorTok{*}\NormalTok{args, }\OperatorTok{**}\NormalTok{kwargs)}
        \ControlFlowTok{return}\NormalTok{ wrapper}
\end{Highlighting}
\end{Shaded}

If we call the \texttt{debug} decorator function with the single keyword
argument \texttt{prefix}, then the \texttt{func} argument defaults to
\texttt{None}. In this case, the \texttt{if} statement causes
\texttt{debug} to call itself with that \texttt{prefix} argument and the
decorated function (that follows the \texttt{@debug} annotation in the
user-level code or occurs in a second argument list) as the
\texttt{func} argument.

Note: The \texttt{functools.partial} function takes a function (object)
and a group of positional and/or keyword arguments, \emph{partially
applies} the function to those arguments, then returns the resulting
function (object). The returned function behaves like the original
function except that it has the argument values supplied to
\texttt{partial} as its default parameter values.

If we call the \texttt{debug} decorator function with no keyword
arguments, then parameter \texttt{prefix} defaults to the empty string
and \texttt{func} is the decorated function (e.g.~that follows the
\texttt{@debug} annotation).

If we call \texttt{debug} with both \texttt{func} and \texttt{prefix}
arguments, then it works as we expect. This case is not used with the
\texttt{@debug} annotation.

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@debug}\NormalTok{(prefix}\OperatorTok{=}\StringTok{'***'}\NormalTok{)}
    \KeywordTok{def}\NormalTok{ add(x,y):}
        \CommentTok{'Add x and y'} 
        \ControlFlowTok{return}\NormalTok{ x}\OperatorTok{+}\NormalTok{y}

    \AttributeTok{@debug}\NormalTok{(prefix}\OperatorTok{=}\StringTok{'@@@'}\NormalTok{) }
    \KeywordTok{def}\NormalTok{ sub(x, y):}
        \CommentTok{'Subtract y from x'}
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{-}\NormalTok{ y}

    \AttributeTok{@debug}\NormalTok{(prefix}\OperatorTok{=}\StringTok{'***'}\NormalTok{) }
    \KeywordTok{def}\NormalTok{ mul(x, y):}
        \CommentTok{'Multiply x and y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{*}\NormalTok{ y}

    \AttributeTok{@debug}  \CommentTok{# no parentheses required, but okay if given}
    \KeywordTok{def}\NormalTok{ div(x, y):}
        \CommentTok{'Divide x by y'} 
        \ControlFlowTok{return}\NormalTok{ x }\OperatorTok{/}\NormalTok{ y}
\end{Highlighting}
\end{Shaded}

Unlike the previous formulation of the prefix decorator, the
\texttt{prefix} string must be supplied as a prefix argument.

Note: The Python 3.6+ source code for the above version of
\texttt{debugprefix} is available at \href{code/debugprefix2.py}{this
link}.

\hypertarget{class-level-debugging}{%
\subsection{Class-Level Debugging}\label{class-level-debugging}}

\hypertarget{motivating-example-2}{%
\subsubsection{Motivating example}\label{motivating-example-2}}

Consider the class \texttt{Account} below for a simple bank account.

Suppose we want to debug all the methods using the simple debugging
package we developed above.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ Account:}
        \KeywordTok{def} \FunctionTok{__init__}\NormalTok{(}\VariableTok{self}\NormalTok{):}
            \VariableTok{self}\NormalTok{._bal }\OperatorTok{=} \DecValTok{0}

        \AttributeTok{@debug} 
        \KeywordTok{def}\NormalTok{ deposit(}\VariableTok{self}\NormalTok{,amt):}
            \VariableTok{self}\NormalTok{._bal }\OperatorTok{+=}\NormalTok{ amt}

        \AttributeTok{@debug} 
        \KeywordTok{def}\NormalTok{ withdraw(}\VariableTok{self}\NormalTok{,amt):}
            \ControlFlowTok{if}\NormalTok{ amt }\OperatorTok{<=} \VariableTok{self}\NormalTok{._bal:}
                \VariableTok{self}\NormalTok{._bal }\OperatorTok{-=}\NormalTok{ amt}
            \ControlFlowTok{else}\NormalTok{:}
                \BuiltInTok{print}\NormalTok{(}\SpecialStringTok{f'Insufficient funds for withdrawal of }\SpecialCharTok{\{}\NormalTok{amt}\SpecialCharTok{\}}\SpecialStringTok{'}\NormalTok{)}

        \AttributeTok{@debug} 
        \KeywordTok{def}\NormalTok{ get_balance(}\VariableTok{self}\NormalTok{):}
            \ControlFlowTok{return} \VariableTok{self}\NormalTok{._bal}

        \KeywordTok{def} \FunctionTok{__str__}\NormalTok{(}\VariableTok{self}\NormalTok{):}
            \ControlFlowTok{return} \SpecialStringTok{f'Account with balance }\SpecialCharTok{\{}\VariableTok{self}\SpecialCharTok{.}\NormalTok{_bal}\SpecialCharTok{\}}\SpecialStringTok{'}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of
\texttt{Account} is available at \href{code/account2.py}{this link}.

\hypertarget{class-level-debugger}{%
\subsubsection{Class-level debugger}\label{class-level-debugger}}

The \texttt{Account} example above is repetitive (not DRY). Can we do
the decoration all at once?

Yes, we can define a class decorator \texttt{debugmethods} as shown
below (where \texttt{debug} is the function-level prefix decorator
defined above). A \emph{class decorator} is a higher-order function that
takes a class as its argument, modifies the class in some way, and then
returns the modified class.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ debugmethods(cls):                     }\CommentTok{# Notes}
        \ControlFlowTok{for}\NormalTok{ name, val }\KeywordTok{in} \BuiltInTok{vars}\NormalTok{(cls).items():    }\CommentTok{# (1) (2) (3)}
            \ControlFlowTok{if} \BuiltInTok{callable}\NormalTok{(val):                  }\CommentTok{# (4)}
                \BuiltInTok{setattr}\NormalTok{(cls, name, debug(val)) }\CommentTok{# (5) (6)}
        \ControlFlowTok{return}\NormalTok{ cls                             }\CommentTok{# (7)}
\end{Highlighting}
\end{Shaded}

The idea here is that the program walks through the class dictionary,
identifies callable objects (e.g.~methods), and wraps each with a
function decorator.

Consider the numbered comments in the above code.

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  The built-in function call \texttt{vars(cls)} returns the dictionary
  (i.e. \texttt{\_\_dict\_\_}) associated with the (class) object
  \texttt{cls}.
\item
  The dictionary method call \texttt{items()} returns the list of
  key-value pairs in the dictionary.
\item
  The ``\texttt{for\ name,\ val\ in}'' statement loops through the pairs
  in the list, successively binding each key to \texttt{name} and value
  to \texttt{val}.
\item
  The built-in function call \texttt{callable(val)} returns
  \texttt{True} if \texttt{val} appears callable, \texttt{False} if not.
  (These are likely instance methods.)
\item
  The call \texttt{debug(val)} applies the function-level prefix
  debugger we defined above to the method \texttt{val}. That is, it
  wraps the method with function decorator \texttt{debug}.
\item
  The built-in function call \texttt{setattr(cls,\ name,\ debug(val))}
  sets the \texttt{name} attribute of object \texttt{cls} to the value
  \texttt{debug(val)}.
\item
  The decorator function \texttt{debugmethods} returns the modified
  class object \texttt{cls} in place of the original class.
\end{enumerate}

The code below shows the application of this new decorator to the
\texttt{Account} class.

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@debugmethods}
    \KeywordTok{class}\NormalTok{ Account:}
        \KeywordTok{def} \FunctionTok{__init__}\NormalTok{(}\VariableTok{self}\NormalTok{):}
            \VariableTok{self}\NormalTok{._bal }\OperatorTok{=} \DecValTok{0}

        \KeywordTok{def}\NormalTok{ deposit(}\VariableTok{self}\NormalTok{,amt):}
            \VariableTok{self}\NormalTok{._bal }\OperatorTok{+=}\NormalTok{ amt}

        \KeywordTok{def}\NormalTok{ withdraw(}\VariableTok{self}\NormalTok{,amt):}
            \ControlFlowTok{if}\NormalTok{ amt }\OperatorTok{<=} \VariableTok{self}\NormalTok{._bal:}
                \VariableTok{self}\NormalTok{._bal }\OperatorTok{-=}\NormalTok{ amt}
            \ControlFlowTok{else}\NormalTok{:}
                \BuiltInTok{print}\NormalTok{(}\SpecialStringTok{f'Insufficient funds for withdrawal of }\SpecialCharTok{\{}\NormalTok{amt}\SpecialCharTok{\}}\SpecialStringTok{'}\NormalTok{)}

        \KeywordTok{def}\NormalTok{ get_balance(}\VariableTok{self}\NormalTok{):}
            \ControlFlowTok{return} \VariableTok{self}\NormalTok{._bal}

        \KeywordTok{def} \FunctionTok{__str__}\NormalTok{(}\VariableTok{self}\NormalTok{):}
            \ControlFlowTok{return} \SpecialStringTok{f'Account with balance }\SpecialCharTok{\{}\VariableTok{self}\SpecialCharTok{.}\NormalTok{_bal}\SpecialCharTok{\}}\SpecialStringTok{'}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of
\texttt{Account} is available at \href{code/account3.py}{this link}.

A single decorator application handles all the method definitions within
the class.

Well, not quite!

It does not decorate class or static methods, such as the following
which can be added to class \texttt{Account}.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ Account:}
\NormalTok{    ... }
        \AttributeTok{@classmethod}
        \KeywordTok{def}\NormalTok{ classname(cls):}
            \ControlFlowTok{return}\NormalTok{ cls.}\VariableTok{__name__}

        \AttributeTok{@staticmethod}
        \KeywordTok{def}\NormalTok{ warn(msg):}
            \BuiltInTok{print}\NormalTok{(}\SpecialStringTok{f'Warning: }\SpecialCharTok{\{}\NormalTok{msg}\SpecialCharTok{\}}\SpecialStringTok{'}\NormalTok{)}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the extended version of
\texttt{Account} is available at \href{code/account4.py}{this link}.

TODO: Explain why this does not work.

\hypertarget{variation-attribute-access-debugging}{%
\subsubsection{Variation: Attribute access
debugging}\label{variation-attribute-access-debugging}}

Suppose instead of printing a message on every call of a method, we do
so for each access to an attribute.

We can do this by rewriting part of the class as shown below. In
particular, we give a new implementation for the special method
\texttt{\_\_getattribute\_\_}.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{def}\NormalTok{ debugattr(cls):}
\NormalTok{        orig_getattribute }\OperatorTok{=}\NormalTok{ cls.}\FunctionTok{__getattribute__}

        \KeywordTok{def} \FunctionTok{__getattribute__}\NormalTok{(}\VariableTok{self}\NormalTok{, name):}
            \BuiltInTok{print}\NormalTok{(}\SpecialStringTok{f'Get: }\SpecialCharTok{\{}\NormalTok{name}\SpecialCharTok{\}}\SpecialStringTok{'}\NormalTok{)}
            \ControlFlowTok{return}\NormalTok{ orig_getattribute(}\VariableTok{self}\NormalTok{, name)}

\NormalTok{        cls.}\FunctionTok{__getattribute__} \OperatorTok{=} \FunctionTok{__getattribute__}
        \ControlFlowTok{return}\NormalTok{ cls}
\end{Highlighting}
\end{Shaded}

The special method \texttt{\_\_getattribute\_\_} is called to implement
accesses to ``regular'' attributes of the class. It is not called on
accesses to other special methods such as \texttt{\_\_init\_\_} and
\texttt{\_\_str\_\_}.

In the above, we save the original implementation of the method and then
call it to complete the access once we have printed an appropriate
debugging message.

In the example below, we decorate the \texttt{Account} class with
\texttt{@debugattr}.

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@debugattr}
    \KeywordTok{class}\NormalTok{ Account:}
        \KeywordTok{def} \FunctionTok{__init__}\NormalTok{(}\VariableTok{self}\NormalTok{):}
            \VariableTok{self}\NormalTok{._bal }\OperatorTok{=} \DecValTok{0}

        \KeywordTok{def}\NormalTok{ deposit(}\VariableTok{self}\NormalTok{,amt):}
            \VariableTok{self}\NormalTok{._bal }\OperatorTok{+=}\NormalTok{ amt}

        \KeywordTok{def}\NormalTok{ withdraw(}\VariableTok{self}\NormalTok{,amt):}
            \ControlFlowTok{if}\NormalTok{ amt }\OperatorTok{<=} \VariableTok{self}\NormalTok{._bal:}
                \VariableTok{self}\NormalTok{._bal }\OperatorTok{-=}\NormalTok{ amt}
            \ControlFlowTok{else}\NormalTok{:}
                \BuiltInTok{print}\NormalTok{(}\SpecialStringTok{f'Insufficient funds for withdrawal of }\SpecialCharTok{\{}\NormalTok{amt}\SpecialCharTok{\}}\SpecialStringTok{'}\NormalTok{)}

        \KeywordTok{def}\NormalTok{ get_balance(}\VariableTok{self}\NormalTok{):}
            \ControlFlowTok{return} \VariableTok{self}\NormalTok{._bal}

        \KeywordTok{def} \FunctionTok{__str__}\NormalTok{(}\VariableTok{self}\NormalTok{):}
            \ControlFlowTok{return} \SpecialStringTok{f'Account with balance }\SpecialCharTok{\{}\VariableTok{self}\SpecialCharTok{.}\NormalTok{_bal}\SpecialCharTok{\}}\SpecialStringTok{'}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of
\texttt{Account} is available at \href{code/account5.py}{this link}.

We can see the effects of the decorator in the following REPL session.

\begin{Shaded}
\begin{Highlighting}[]
    \OperatorTok{>>>}\NormalTok{ acct }\OperatorTok{=}\NormalTok{ Account()}
    \OperatorTok{>>>} \BuiltInTok{str}\NormalTok{(acct)}
\NormalTok{    Get: _bal}
    \CommentTok{'Account with balance 0'} 
    \OperatorTok{>>>}\NormalTok{ acct.deposit(}\DecValTok{100}\NormalTok{)}
\NormalTok{    Get: deposit}
\NormalTok{    Get: _bal }
    \OperatorTok{>>>} \BuiltInTok{str}\NormalTok{(acct)   }
\NormalTok{    Get: _bal }
    \CommentTok{'Account with balance 100'} 
    \OperatorTok{>>>}\NormalTok{ acct.withdraw(}\DecValTok{60}\NormalTok{)}
\NormalTok{    Get: withdraw}
\NormalTok{    Get: _bal}
\NormalTok{    Get: _bal}
    \OperatorTok{>>>} \BuiltInTok{str}\NormalTok{(acct)   }
\NormalTok{    Get: _bal }
    \CommentTok{'Account with balance 40'} 
    \OperatorTok{>>>}\NormalTok{ acct.get_balance()}
\NormalTok{    Get: get_balance}
\NormalTok{    Get: _bal}
    \DecValTok{40}
    \OperatorTok{>>>} \BuiltInTok{str}\NormalTok{(acct)}
    \CommentTok{'Account with balance 40'} 
\end{Highlighting}
\end{Shaded}

Note that both calls to the methods and the accesses to the ``private''
data attribute \texttt{\_bal} are shown. (If we want to exclude accesses
to the private instance variables, we can modify \texttt{debugattr} to
exclude attributes whose names begin with a single underscore.)

\hypertarget{class-hierarchy-debugging}{%
\subsection{Class Hierarchy Debugging}\label{class-hierarchy-debugging}}

\hypertarget{motivating-example-3}{%
\subsubsection{Motivating example}\label{motivating-example-3}}

Now let's set up class-level debugging on the inheritance hierarchy
\texttt{P} example from Chapter 2.

\begin{Shaded}
\begin{Highlighting}[]
    \AttributeTok{@debugmethods} 
    \KeywordTok{class}\NormalTok{ P: }
        \KeywordTok{def} \FunctionTok{__init__}\NormalTok{(}\VariableTok{self}\NormalTok{,name}\OperatorTok{=}\VariableTok{None}\NormalTok{): }
            \VariableTok{self}\NormalTok{.name }\OperatorTok{=}\NormalTok{ name }
        \KeywordTok{def}\NormalTok{ process(}\VariableTok{self}\NormalTok{): }
            \ControlFlowTok{return} \SpecialStringTok{f'Process at parent P level'} 

    \AttributeTok{@debugmethods} 
    \KeywordTok{class}\NormalTok{ C(P):   }\CommentTok{# class C inherits from class P}
        \KeywordTok{def}\NormalTok{ process(}\VariableTok{self}\NormalTok{):}
\NormalTok{            result }\OperatorTok{=} \SpecialStringTok{f'Process at child C level'}
            \CommentTok{# Call method in parent class}
            \ControlFlowTok{return} \SpecialStringTok{f'}\SpecialCharTok{\{}\NormalTok{result}\SpecialCharTok{\}}\SpecialStringTok{ }\CharTok{\textbackslash{}n}\SpecialStringTok{  }\SpecialCharTok{\{}\BuiltInTok{super}\NormalTok{()}\SpecialCharTok{.}\NormalTok{process()}\SpecialCharTok{\}}\SpecialStringTok{'}
            
    \AttributeTok{@debugmethods} 
    \KeywordTok{class}\NormalTok{ D(P):   }\CommentTok{# class D inherits from class P}
        \ControlFlowTok{pass}

    \AttributeTok{@debugmethods} 
    \KeywordTok{class}\NormalTok{ G(C):   }\CommentTok{# class G inherits from class C}
        \KeywordTok{def}\NormalTok{ process(}\VariableTok{self}\NormalTok{): }
            \ControlFlowTok{return} \SpecialStringTok{f'Process at grandchild G level'}
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of the
\texttt{P} class hierarchy is available at \href{code/inherit2.py}{this
link}.

So, we have another occurrence of code redundancy that we saw at the
class level in the previous section. Let's see if we can DRY out the
code more.

To do this, the program needs to process the whole class hierarchy
rooted at class \texttt{P}. Let's review the nature of the Python 3
object model to see how to do this.

\hypertarget{review-of-objects-and-types}{%
\subsubsection{Review of objects and
types}\label{review-of-objects-and-types}}

In \href{Py3RefMeta02.html}{Chapter 2} of these notes, we learned:

\begin{itemize}
\item
  All Python 3 values are objects.
\item
  All objects have types.
\item
  A class defines a new type.
\item
  A class is a callable (i.e.~function) that creates instances; the
  class is the type of the instances it creates. Hence, in some sense, a
  class \emph{is a type} consisting of its potential instances and the
  operations it defines.
\item
  A class itself is an object. It is an instance of other classes. Thus
  it \emph{has a type}.
\item
  The built-in class \texttt{type} is the root class (i.e.~top-level
  metaclass) for all other classes (i.e.~types). When a program invokes
  \texttt{type} as a constructor, it creates a new type (i.e.~class)
  object.
\item
  Classes may inherit (i.e.~be a subclass of) other classes.
\item
  The built-in class \texttt{object} is the root class for all other
  top-level user-defined and built-in classes.
\end{itemize}

Note: See the diagram in
\href{Py3RefMeta02.html\#understanding-relationships-among-classes}{Figure
1} from Chapter 2.

The following Python 3 REPL session illustrates these concepts.

\begin{Shaded}
\begin{Highlighting}[]
    \OperatorTok{>>>} \KeywordTok{class}\NormalTok{ PP:}
\NormalTok{    ...     }\ControlFlowTok{pass}
\NormalTok{    ... }
    \OperatorTok{>>>} \KeywordTok{class}\NormalTok{ CC(PP):}
\NormalTok{    ...     }\ControlFlowTok{pass}
\NormalTok{    ...}
    \OperatorTok{>>>}\NormalTok{ PP}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'__main__.PP'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(PP) }
    \OperatorTok{<}\KeywordTok{class} \StringTok{'type'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{issubclass}\NormalTok{(P,}\BuiltInTok{object}\NormalTok{) }
    \VariableTok{True} 
    \OperatorTok{>>>}\NormalTok{ CC}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'__main__.CC'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(CC) }
    \OperatorTok{<}\KeywordTok{class} \StringTok{'type'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{issubclass}\NormalTok{(CC,PP)}
    \VariableTok{True}
    \OperatorTok{>>>}\NormalTok{ x }\OperatorTok{=}\NormalTok{ PP()}
    \OperatorTok{>>>}\NormalTok{ x}
    \OperatorTok{<}\NormalTok{__main__.PP }\BuiltInTok{object}\NormalTok{ at }\BaseNTok{0x10cd3d048}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{isinstance}\NormalTok{(x,PP)}
    \VariableTok{True}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(x)}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'__main__.PP'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{type}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'type'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(}\BuiltInTok{type}\NormalTok{)}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'type'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{issubclass}\NormalTok{(}\BuiltInTok{type}\NormalTok{,}\BuiltInTok{object}\NormalTok{) }
    \VariableTok{True} 
    \OperatorTok{>>>} \BuiltInTok{object}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'object'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(}\BuiltInTok{object}\NormalTok{) }
    \OperatorTok{<}\KeywordTok{class} \StringTok{'type'}\OperatorTok{>}
\end{Highlighting}
\end{Shaded}

\hypertarget{class-definition-process}{%
\subsubsection{Class definition
process}\label{class-definition-process}}

Now let's examine how the Python 3 interpreter elaborates class
definitions at runtime. Consider the class \texttt{MyClass} defined as
follows:

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ MyClass(Parent):}
        \KeywordTok{def} \FunctionTok{__init__}\NormalTok{(}\VariableTok{self}\NormalTok{, }\BuiltInTok{id}\NormalTok{): }
            \VariableTok{self}\NormalTok{.}\BuiltInTok{id} \OperatorTok{=} \BuiltInTok{id} 
        \KeywordTok{def}\NormalTok{ hello(}\VariableTok{self}\NormalTok{): }
            \BuiltInTok{print}\NormalTok{(}\SpecialStringTok{f'Hello from MyClass.hello, id = }\SpecialCharTok{\{}\VariableTok{self}\SpecialCharTok{.}\BuiltInTok{id}\SpecialCharTok{\}}\SpecialStringTok{'}\NormalTok{)}\StringTok{"}
\end{Highlighting}
\end{Shaded}

This class definition has three components.

\begin{itemize}
\item
  Name: \texttt{"MyClass"}
\item
  Base classes: \texttt{(Parent,)}
\item
  Functions: \texttt{(\_\_\_init\_\_\_,\ hello)}
\end{itemize}

The interpreter takes the following steps during class definition.

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  It isolates the body of the class.

\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{    body }\OperatorTok{=} \StringTok{'''}
\StringTok{    def __init__(self, myid): }
\StringTok{        self.myid = myid }
\StringTok{    def hello(self): }
\StringTok{        print(f'Hello from MyClass.hello, myid = }\SpecialCharTok{\{self.myid\}}\StringTok{')}
\StringTok{    '''}
\end{Highlighting}
\end{Shaded}
\item
  It creates the class dictionary.

\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{    clsdict }\OperatorTok{=} \BuiltInTok{type}\NormalTok{.__prepare__(}\StringTok{'MyClass'}\NormalTok{, (Parent,))}
\end{Highlighting}
\end{Shaded}

  Method \texttt{type.\_\_prepare\_\_} is a class method on the root
  metaclass \texttt{type}. In the process of creating the new class
  object for a class, the interpreter calls the \texttt{\_\_prepare\_\_}
  method before it calls the \texttt{\_\_new\_\_} method on
  \texttt{type} {[}Ramalho 2015, pp.~701-3{]}.

  In addition to metaclass argument (i.e. \texttt{type}), the
  \texttt{\_\_prepare\_\_} class method takes two additional arguments:

  \begin{itemize}
  \item
    the name of the class being created
    (e.g.\texttt{\textquotesingle{}MyClass\textquotesingle{}} above)
  \item
    a tuple of the one or more base classes (e.g. \texttt{(Parent,)}
    above)
  \end{itemize}

  Method \texttt{\_\_prepare\_\_} returns a dictionary that can be
  subsequently passed to the \texttt{\_\_new\_\_} and
  \texttt{\_\_init\_\_} methods. This dictionary serves as the local
  namespace for the statements in the class body.
\item
  It executes the body using in the local namespace defined by the class
  dictionary.

\begin{Shaded}
\begin{Highlighting}[]
    \BuiltInTok{exec}\NormalTok{(body, }\BuiltInTok{globals}\NormalTok{(), clsdict)}
\end{Highlighting}
\end{Shaded}

  This step populates \texttt{clsdict}.

\begin{Shaded}
\begin{Highlighting}[]
    \OperatorTok{>>>}\NormalTok{ clsdict}
\NormalTok{    \{}\StringTok{'__init__'}\NormalTok{: }\OperatorTok{<}\NormalTok{function }\FunctionTok{__init__}\NormalTok{ at }\BaseNTok{0x10cc21ea0}\OperatorTok{>}\NormalTok{, }
     \StringTok{'hello'}\NormalTok{: }\OperatorTok{<}\NormalTok{function hello at }\BaseNTok{0x10d2b9bf8}\OperatorTok{>}\NormalTok{\}}
\end{Highlighting}
\end{Shaded}
\item
  It constructs the class from its name, its base classes, and the
  dictionary populated in the previous step.

\begin{Shaded}
\begin{Highlighting}[]
    \OperatorTok{>>>}\NormalTok{ MyClass }\OperatorTok{=} \BuiltInTok{type}\NormalTok{(}\StringTok{'MyClass'}\NormalTok{, (Parent,), clsdict)}
    \OperatorTok{>>>}\NormalTok{ MyClass}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'__main__.MyClass'}\OperatorTok{>}
    \OperatorTok{>>>}\NormalTok{ mc }\OperatorTok{=}\NormalTok{ MyClass(}\StringTok{'Conrad'}\NormalTok{)}
    \OperatorTok{<}\NormalTok{__main__.MyClass }\BuiltInTok{object}\NormalTok{ at }\BaseNTok{0x100f96c50}\OperatorTok{>}
    \OperatorTok{>>>}\NormalTok{ mc.myid}
\NormalTok{    Conrad}
    \OperatorTok{>>>}\NormalTok{ mc.hello()}
\NormalTok{    Hello }\ImportTok{from}\NormalTok{ MyClass.hello, myid }\OperatorTok{=}\NormalTok{ Conrad}
\end{Highlighting}
\end{Shaded}

  The call
  \texttt{type(\textquotesingle{}MyClass\textquotesingle{},\ (Parent,),\ clsdict)}
  constructs an instance of metaclass \texttt{type} with name
  \texttt{MyClass}, superclass \texttt{Parent}, and object dictionary
  \texttt{clsdict}. This is the class object for \texttt{MyClass}.
\end{enumerate}

Note: The Python 3.6+ source code for the above creation of class
\texttt{MyClass} is available at \href{code/MyClass1.py}{this link}.

\hypertarget{changing-the-metaclass}{%
\subsubsection{Changing the metaclass}\label{changing-the-metaclass}}

A Python 3 class definition has a keyword parameter named
\texttt{metaclass} whose default value is \texttt{type}. So the parent
class \texttt{P} from the motivating example for this section is
equivalent to the following.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ P(metaclass}\OperatorTok{=}\BuiltInTok{type}\NormalTok{):}
        \KeywordTok{def} \FunctionTok{__init__}\NormalTok{(}\VariableTok{self}\NormalTok{,name}\OperatorTok{=}\VariableTok{None}\NormalTok{): }
            \VariableTok{self}\NormalTok{.name }\OperatorTok{=}\NormalTok{ name }
        \KeywordTok{def}\NormalTok{ process(}\VariableTok{self}\NormalTok{): }
            \ControlFlowTok{return} \SpecialStringTok{f'Process at parent P level'} 
\end{Highlighting}
\end{Shaded}

This keyword parameter sets the class for creating the new type for the
class. Although the default is \texttt{type}, we can change it to some
other metaclass.

To define a new metaclass, we typically define a type that inherits from
\texttt{type} and gives a new definition for one or both of the special
methods \texttt{\_\_new\_\_} and \texttt{\_\_init\_\_}.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ mytype(}\BuiltInTok{type}\NormalTok{):}
        \KeywordTok{def} \FunctionTok{__new__}\NormalTok{(cls, name, bases, clsdict):}
            \CommentTok{# possible preprocessing of arguments}
\NormalTok{            clsobj }\OperatorTok{=} \BuiltInTok{super}\NormalTok{().}\FunctionTok{__new__}\NormalTok{(cls, name, bases, clsdict)}
            \CommentTok{# possible postprocessing of object}
            \ControlFlowTok{return}\NormalTok{ clsobj}
\end{Highlighting}
\end{Shaded}

The special method \texttt{\_\_new\_\_} allocates memory, constructs a
new instance (i.e.~object), and then returns it. The interpreter passes
this new instance to special method \texttt{\_\_init\_\_}, which
initializes the new instance variables.

We do not normally override \texttt{\_\_new\_\_}, but in a metaclass we
may want to do some additional work either before or after the basic
construction processing.

A metaclass can access information about a class definition at the time
the class is defined. It can inspect the data and, if needed, modify the
data.

Given the above definition, we can use the new metaclass as follows:

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ P(metaclass}\OperatorTok{=}\NormalTok{mytype):}
\NormalTok{        ...}
\end{Highlighting}
\end{Shaded}

\hypertarget{debugging-using-a-metaclass}{%
\subsubsection{Debugging using a
metaclass}\label{debugging-using-a-metaclass}}

Now we have the tools we need to remove the code redundancy from the
motivating example. We can introduce the \emph{metaclass} shown in the
example below.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ debugmeta(}\BuiltInTok{type}\NormalTok{):}
        \KeywordTok{def} \FunctionTok{__new__}\NormalTok{(cls, clsname, bases, clsdict):}
\NormalTok{            clsobj }\OperatorTok{=} \BuiltInTok{super}\NormalTok{().}\FunctionTok{__new__}\NormalTok{(cls,clsname,bases,clsdict)  }\CommentTok{#1}
\NormalTok{            clsobj }\OperatorTok{=}\NormalTok{ debugmethods(clsobj)                        }\CommentTok{#2}
            \ControlFlowTok{return}\NormalTok{ clsobj                                        }\CommentTok{#3}
\end{Highlighting}
\end{Shaded}

The approach above:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  creates the class normally (using \texttt{\_\_new\_\_})
\item
  immediately wraps it with the class-level debug decorator
  \texttt{debugmethods} we developed previously
\item
  then returns the wrapped class object
\end{enumerate}

Given the above metaclass definition, we can apply it to the inheritance
example as sketched below.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ P(metaclass }\OperatorTok{=}\NormalTok{ debugmeta):}
\NormalTok{        ...}
    \KeywordTok{class}\NormalTok{ C(P):}
\NormalTok{        ...}
    \KeywordTok{class}\NormalTok{ D(P): }
\NormalTok{        ... }
    \KeywordTok{class}\NormalTok{ G(C):}
\NormalTok{        ... }
\end{Highlighting}
\end{Shaded}

Note: The Python 3.6+ source code for the above version of the
\texttt{P} class hierarchy is available at \href{code/inherit3.py}{this
link}.

Now consider a Python 3 REPL session using the above code with the
custom metaclass.

\begin{Shaded}
\begin{Highlighting}[]
    \OperatorTok{>>>} \ImportTok{from}\NormalTok{ inherit3 }\ImportTok{import} \OperatorTok{*}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(P) }
    \OperatorTok{<}\KeywordTok{class} \StringTok{'inherit3.debugmeta'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{issubclass}\NormalTok{(P,}\BuiltInTok{object}\NormalTok{) }
    \VariableTok{True} 
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(C)}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'inherit3.debugmeta'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{issubclass}\NormalTok{(C,P) }
    \VariableTok{True} 
    \OperatorTok{>>} \BuiltInTok{type}\NormalTok{(G) }
    \OperatorTok{<}\KeywordTok{class} \StringTok{'inherit3.debugmeta'}\OperatorTok{>}
    \OperatorTok{>>>} \BuiltInTok{issubclass}\NormalTok{(G,C) }
    \VariableTok{True} 
    \OperatorTok{>>>} \BuiltInTok{issubclass}\NormalTok{(G,P) }
    \VariableTok{True} 
    \OperatorTok{>>>}\NormalTok{ p1 }\OperatorTok{=}\NormalTok{ P()}
\NormalTok{    P.}\FunctionTok{__init__}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(p1) }
    \OperatorTok{<}\KeywordTok{class} \StringTok{'inherit3.P'}\OperatorTok{>}
    \OperatorTok{>>>}\NormalTok{ c1 }\OperatorTok{=}\NormalTok{ C() }
\NormalTok{    P.}\FunctionTok{__init__}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(c1)}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'inherit3.C'}\OperatorTok{>}
    \OperatorTok{>>>}\NormalTok{ g1 }\OperatorTok{=}\NormalTok{ G()}
\NormalTok{    P.}\FunctionTok{__init__}
    \OperatorTok{>>>} \BuiltInTok{type}\NormalTok{(g1)}
    \OperatorTok{<}\KeywordTok{class} \StringTok{'inherit3.C'}\OperatorTok{>}
    \OperatorTok{>>>}\NormalTok{ p1.process()}
\NormalTok{    P.process}
    \CommentTok{'Process at parent P level'}
    \OperatorTok{>>>}\NormalTok{ c1.process()}
\NormalTok{    C.process}
\NormalTok{    P.process}
    \CommentTok{'Process at child C level \textbackslash{}n  Process at parent P level'}
    \OperatorTok{>>>}\NormalTok{ g1.process()}
\NormalTok{    G.process}
    \CommentTok{'Process at grandchild G level'}
\end{Highlighting}
\end{Shaded}

\hypertarget{why-metaclasses}{%
\subsubsection{Why metaclasses?}\label{why-metaclasses}}

As we have seen, we can transform a class in similar ways using either a
class decorator or a metaclass.

Given that a class decorator is easier to set up and apply, when and why
should we use a metaclass?

One advantage to metaclasses is that they can propagate down class
hierarchies. Consider our motivating example again.

\begin{Shaded}
\begin{Highlighting}[]
    \KeywordTok{class}\NormalTok{ P(metaclass }\OperatorTok{=}\NormalTok{ debugmeta):}
\NormalTok{        ...}
    \KeywordTok{class}\NormalTok{ C(P):   }\CommentTok{# metaclass = debugmeta}
\NormalTok{        ...}
    \KeywordTok{class}\NormalTok{ D(P):   }\CommentTok{# metaclass = debugmeta}
\NormalTok{        ... }
    \KeywordTok{class}\NormalTok{ G(C):   }\CommentTok{# metaclass = debugmeta}
\NormalTok{        ... }
\end{Highlighting}
\end{Shaded}

As we can see in the REPL session output in the previous subsection, use
of the metaclass in parent class \texttt{P} is passed down automatically
to all its descendants. No changes are needed to the descendant classes.

In some sense, the metaclass mutates the DNA of the parent class and
that mutation is passed on to the children. In this example, debugging
is applied across the entire hierarchy. The code is kept DRY.

\hypertarget{chapter-summary}{%
\subsection{Chapter Summary}\label{chapter-summary}}

In this case study, we used Python metaprogramming facilities to debug
successively larger program units. But regardless of the level, the
method mostly involved wrapping and rewriting the program units.

\begin{itemize}
\item
  We used function decorators to wrap and rewrite functions.
\item
  We used class decorators to wrap and rewrite classes.
\item
  We used metaclasses to wrap and rewrite class hierarchies.
\end{itemize}

So far, we have mostly used ``classic'' metaprogramming techniques that
were available in Python 2 with only a few Python 3 features.

In the coming chapters, we use more advanced features of Python 3.
(These chapters are planned but not yet drafted.)

\hypertarget{exercises}{%
\subsection{Exercises}\label{exercises}}

TODO

\hypertarget{acknowledgements}{%
\subsection{Acknowledgements}\label{acknowledgements}}

I developed these notes in Spring 2018 for use in CSci 658 Software
Language Engineering. The Spring 2018 version used Python 3.6.

The overall set of notes on Python 3 Reflexive Metaprogramming is
inspired by David Beazley's \href{http://www.dabeaz.com/py3meta}{Python
3 Metaprogramming tutorial} from PyCon'2013 {[}Beazley 2013a{]}. In
particular, some chapters adapt Beazley's examples. Beazley's tutorial
draws on material from his and Brian K. Jones' book \emph{Python
Cookbook} {[}Beazley 2013b{]}.

In particular, this chapter adapts David Beazley's \texttt{debugly}
example presentation from his
\href{http://www.dabeaz.com/py3meta}{Python 3 Metaprogramming tutorial}
at PyCon'2013 {[}Beazley 2013a{]}.

I maintain these notes as text in Pandoc's dialect of Markdown using
embedded LaTeX markup for the mathematical formulas and then translate
the notes to HTML, PDF, and other forms as needed.

\hypertarget{references}{%
\subsection{References}\label{references}}

\begin{description}
\tightlist
\item[{[}Beazley 2013a{]}:]
David Beazley. \href{http://www.dabeaz.com/py3meta/}{Python 3
Metaprogramming (Tutorial)}, \emph{PyCon'2013}, 14 March 2013.
\item[{[}Beazley 2013b{]}:]
David Beazley and Brian K. Jones. \emph{Python Cookbook, 3rd Edition},
O'Reilly Media, May 2013.
\item[{[}Gamma 1995{]}]
Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides.
\emph{Design Patterns: Elements of Reusable Object-Oriented Software},
Addison Wesley, 1995.
\item[{[}Hunt 2000{]}:]
Andrew Hunt and David Thomas. \emph{The Pragmatic Programmer}, Addison
Wesley, 2000.
\item[{[}Pierce 2002{]}:]
Benjamin C. Pierce, \emph{Types and Programming Languages}, MIT Press,
2002.
\item[{[}Ramalho 2015{]}:]
Luciano Ramalho. \emph{Fluent Python: Clear, Concise, and Effective
Programming}, O'Reilly Media, May 2015.
\item[{[}Venners 2003{]}:]
Bill Venners, \href{https://www.artima.com/intv/dry.html}{Orthogonality
and the DRY Principle}, Interview of Dave Thomas, Artima, Inc., March
2003, Retrieved 27 April 2018.
\item[{[}Wikipedia 2018a{]}:]
Wikipedia,
\href{https://en.wikipedia.org/wiki/Don\%27t_repeat_yourself}{Don't
Repeat Yourself}, accessed 27 April 2018.
\end{description}

\hypertarget{terms-and-concepts}{%
\subsection{Terms and Concepts}\label{terms-and-concepts}}

TODO

\end{document}