syntax examples now also in code repository

Author: thomasWeise

bookbase

@@ -48,21 +48,7 @@
 In this chapter, we discuss \pythoniles{class} in \python.
 Syntactly, \pythoniles{classes} follow the general blueprint below:%
 %
-\begin{pythonSyntax}
-class MyClass:   # or `class MyClass(MyBaseClass)`
-    """Docstring of the class."""
-
-    def __init__(self) -> None:
-        """Docstring of the initializer __init__."""
-        # initialize all attributes
-        #: Meaning of attribute 1
-        self.attribute_1: type hint = initial value
-        # ...
-
-    def my_method(self, param1, param2) -> result:
-        """Docstring of my_method."""
-        # compute something using the attributes
-\end{pythonSyntax}
+\pythonSyntax{syntax/class_init_method.py}%
 %
 \bestPractice{className}{\sloppy%
 Class names should follow the CapWords convention (often also called camel case), i.e., look like \pythonil{MyClass} or \pythonil{UniversityDepartment} (not \pythonil{my_class} or \pythonil{university_department})~\cite{PEP8}.}%

text/main/classes/basics/basics.tex

@@ -10,16 +10,7 @@
 The condition is provided as the kind of Boolean expressions that we already discussed back in \cref{sec:bool}.
 The syntax for this in \python\ is very simple:%
 %
-\begin{pythonSyntax}
-if booleanExpression:
-    conditional statement 1
-    conditional statement 2
-    # ...
-
-normal statement 1
-normal statement 2
-# ...
-\end{pythonSyntax}
+\pythonSyntax{syntax/if.py}%
 %
 \FloatBarrier%
 %
@@ -82,20 +73,7 @@
 This seems to be quite verbose and verbosity leads to confusion.
 So we are offered a better alternative: the \pythonil{if ... else}\pythonIdx{if{\idxdots}else} statement, which looks like this:%
 %
-\begin{pythonSyntax}
-if booleanExpression:
-    conditional statement 1
-    conditional statement 2
-    # ...
-else:
-    alternative statement 1
-    alternative statement 2
-    # ...
-
-normal statement 1
-normal statement 2
-# ...
-\end{pythonSyntax}
+\pythonSyntax{syntax/if_else.py}%
 %
 The statement begins like a normal \pythonilIdx{if}~statement:
 \pythonil{if}, followed by a Boolean expression, followed by a colon~(\pythonilIdx{:}) marks the condition.
@@ -157,24 +135,7 @@
 Therefore, the \pythonilIdx{elif} statement has been developed, which can replace an \pythonil{else} containing just another \pythonil{if}.
 The syntax of a combined \pythonil{if ... elif} looks like this:%
 %
-\begin{pythonSyntax}
-if booleanExpression 1:
-    conditional 1 statement 1
-    conditional 1 statement 2
-    # ...
-elif booleanExpression 2:  # such block can be placed arbitrarily often
-    conditional 2 statement 1
-    conditional 2 statement 2
-    # ...
-else:  # this, too, is optional
-    alternative statement 1
-    alternative statement 2
-    # ...
-
-normal statement 1
-normal statement 2
-# ...
-\end{pythonSyntax}
+\pythonSyntax{syntax/if_elif_else.py}%
 %
 Notice that we can use arbitrarily many \pythonils{elif}\pythonIdx{elif} and, optionally, one~\pythonilIdx{else}.
 Only if the condition of the \pythonilIdx{if} evaluates to~\pythonilIdx{False}, the condition of the first~\pythonilIdx{elif} is checked.
@@ -254,11 +215,7 @@
 \python\ offers us a more compact syntax for this, and \ruff\ can again give us some idea about that in \cref{exec:conditionals:if_else_could_be_inline:ruff}:
 The inline \pythonil{if...then...else} statement, which has the following syntax:%
 %
-\begin{pythonSyntax}[false]
-variable = valueA if conditionForUsingValueA else valueB
-
-variable = valueA if conditionForUsingValueA else (valueB if conditionForUsingValueB else valueC)
-\end{pythonSyntax}
+\pythonSyntax{syntax/if_else_inline.py}%
 %
 In the first variant, the value \pythonil{valueA} will be assigned to \pythonil{variable} if \pythonil{conditionForUsingValueA} evaluates to \pythonil{True}.
 Otherwise, \pythonil{valueB} is assigned.

text/main/controlFlow/conditionals/conditionals.tex

@@ -235,18 +235,7 @@
 Of course, multiple different types of \pythonilsIdx{Exception} may be raised, so we can have multiple \pythonilIdx{except} blocks.
 This looks like this:%
 %
-\begin{pythonSyntax}
-try:  # Begin the try-except block.
-    # Code that may raise an exception or that
-    # calls a function that may rise one.
-except ExceptionType1 as ex1:  # One exception type that can be caught.
-    # Code the handles exceptions of type ExceptionType1.
-except ExceptionType2 as ex2:  # Another exception type (optional).
-    # Code the handles exceptions of type ExceptionType2 that are not
-    # instances of ExceptionType1.
-
-next statement  # Executed only if there are no uncaught Exceptions.
-\end{pythonSyntax}
+\pythonSyntax{syntax/try_except.py}%
 \FloatBarrier%
 %
 \gitLoadAndExecPython{exceptions:try_except_str_index}{}{exceptions}{try_except_str_index.py}{}%
@@ -378,18 +367,7 @@
 One possible solution in such a situation is the \pythonilIdx{try}-\pythonilIdx{except}-\pythonilIdx{else} block.
 The difference to the \pythonilIdx{try}-\pythonilIdx{except} block is only that an \pythonilIdx{else} block follows, which is executed if and only if no exception occurred.%
 %
-\begin{pythonSyntax}
-try:  # Begin the try-except block.
-    # Code that may raise an exception or that
-    # calls a function that may rise one.
-except ExceptionType1 as ex1:  # One exception type that can be caught.
-    # Code the handles exceptions of type ExceptionType1.
-# ... maybe more `except` blocks
-else:
-    # Code executed if and only if no Exception occurred.
-
-next statement  # Executed only if there are no uncaught Exceptions.
-\end{pythonSyntax}
+\pythonSyntax{syntax/try_except_else.py}%
 %
 \gitLoadAndExecPython{exceptions:try_except_else}{}{exceptions}{try_except_else.py}{}%
 \listingPythonAndOutput{exceptions:try_except_else}{%
@@ -433,20 +411,7 @@
 Basically, we can add a \pythonilIdx{finally} block that contains the code that should always be executed.
 While we definitely need a \pythonilIdx{try} block that contains that code that may cause an error, we can optionally add \pythonilIdx{except} blocks to handle certain \pythonilsIdx{Exception} and an \pythonilIdx{else} block to be executed if no error occurs.%
 %
-\begin{pythonSyntax}
-try:  # Begin the try-except block.
-    # Code that may raise an exception or that
-    # calls a function that may rise one.
-except ExceptionType1 as ex1:  # The **optional** except blocks.
-    # Code the handles exceptions of type ExceptionType1.
-# ... maybe more `except` blocks
-else:  # The **optional** else block.
-    # Code executed if and only if no Exception occurred.
-finally:  # The **optional** finally block.
-    # Code will always be executed, even if exceptions are uncaught.
-
-next statement  # Executed only if there are no uncaught Exceptions.
-\end{pythonSyntax}
+\pythonSyntax{syntax/try_except_else_finally.py}%
 %
 \gitLoadAndExecPythonAndErrors{exceptions:try_except_else_finally}{}{exceptions}{try_except_else_finally.py}{}%
 \listingPythonAndError{exceptions:try_except_else_finally}{%
@@ -599,15 +564,7 @@
 %
 The \pythonilIdx{with} statement has the following syntax, where the \pythonil{expression} is supposed to return a context manager~\cite{PSF:P3D:TPLR:WSCM,PSF:P3D:TPSL:CUFWSC,PSF:P3D:TPLR:TWS,PEP343}.%
 %
-\begin{pythonSyntax}
-with expression as variable:
-    # block of code that works with variable
-
-# or
-
-with expression:
-    # block of code
-\end{pythonSyntax}
+\pythonSyntax{syntax/with.py}%
 %
 Right now, we are still lacking some background knowledge needed to discuss what a context manager exactly is or how it works.
 We will therefore do this later in \cref{sec:dunder:contextManager}.

text/main/controlFlow/exceptions/exceptions.tex

@@ -10,29 +10,7 @@
 \pythonIdx{def}\pythonIdx{function!def}%
 The syntax for defining our own functions in \python\ is as follows:%
 %
-\begin{pythonSyntax}
-def my_function(param_1: type, param_2: type, ...) -> result_type:
-    """
-    Short sentence describing the function.
-
-    The title of the so-called docstring is a short sentence stating
-    what the function does. It can be followed by several paragraphs of
-    text describing it in more detail. Then follows the list of
-    parameters, return values, and raised exceptions (if any).
-
-    :param param_1: the description of the first parameter (if any)
-    :param param_2: the description of the second parameter (if any)
-    :returns: the description of the return value (unless `-> None`).
-    """
-    body of function 1
-    body of function 2
-    return result  # if result_type is not None we return something
-
-
-normal statement 1
-normal statement 2
-my_function(argument_1, argument_2)  # we can call the function like this
-\end{pythonSyntax}
+\pythonSyntax{syntax/function.py}%
 %
 \pythonIdx{function!def}A function in \python\ is created by using the \pythonilIdx{def}\pythonIdx{function!def} keyword, followed by the name of the function.%
 %
@@ -354,9 +332,7 @@
 
 Tests are often defined in the form of several assertions assertions:\pythonIdx{assert}%
 %
-\begin{pythonSyntax}
-assert booleanExpr  # raises AssertionError if not booleanExpr
-\end{pythonSyntax}
+\pythonSyntax{syntax/assert.py}%
 %
 An assertion is defined by the keyword \pythonilIdx{assert} followed by an arbitrary Boolean expression.
 If the Boolean expression evaluates to \pythonil{True}, then nothing happens.
@@ -711,9 +687,7 @@
 \pythonilIdx{Callable} is the \pgls{typeHint} for anything that can be called, i.e., functions~\cite{PSF:P3D:TPSL:ACO}.
 Like the \pgls{typeHint} for lists and tuples, it can be parameterized following the scheme~\cite{PEP612}:%
 %
-\begin{pythonSyntax}
-Callable[[parameterType1, parameterType2, ...], resultType]
-\end{pythonSyntax}
+\pythonSyntax{syntax/callable.py}%
 %
 In other words, inside the \pythonil{Callable[...]}, we first provide the list of parameter types, then a comma~\pythonil{,} followed by the return type.
 \pythonil{f: Callable[[float], float | int]} thus states that our function expects, as first parameter, \emph{another function}~\pythonil{f}.
@@ -735,35 +709,21 @@
 For this purpose, we need to pass the function~$f(x)=1$ as the~\pythonil{f} parameter of~\pythonil{integrate}.
 We could do this by writing:%
 %
-\begin{pythonSyntax}
-def const_1(x: float) -> float:
-    return 1.0
-\end{pythonSyntax}
-%
-or%
-%
-\begin{pythonSyntax}
-def const_1(_: float) -> float:
-    return 1.0
-\end{pythonSyntax}
+\pythonSyntax{syntax/const_unary_function.py}%
 %
 where the \pythonil{_}\pythonIdx{\_} indicates that we are actually going to ignore this parameter~(see~\cref{bp:underscore}).
 We could then invoke~\pythonil{integrate(const_1)}.
 
 However, there also is a more compact way to specify functions that we are only going to use once:
 The so-called \pythonilsIdx{lambda}~\cite{PSF:P3D:TPLR:L}, which have the structure%
 %
-\begin{pythonSyntax}
-lambda param1, param2, ...: return value
-\end{pythonSyntax}
+\pythonSyntax{syntax/lambda.py}%
 %
 Due to the \pythonilIdx{:} in the notation, we cannot annotate \pythonilsIdx{lambda} with \pglspl{typeHint}.
 As a \pythonil{lambda} expression is very small and only used once, this does not pose a serious problem.
 Either way, since we need one parameter for our 1-returning-function and since we do not care about the value of this parameter, we can simply write:%
 %
-\begin{pythonSyntax}
-integrate(lambda _: 1.0)
-\end{pythonSyntax}
+\pythonSyntax{syntax/lambda_as_arg.py}%
 %
 \pythonilsIdx{lambda} are functions that we only want use in a single place.
 This is clearly the case for a function that ignores its parameter and always returns~\pythonil{1.0}.

text/main/controlFlow/functions/functions.tex

@@ -107,10 +107,7 @@
 If we want to create a list with the logarithms of first five natural numbers, writing \pythonil{[log(1), log(2), log(3), log(4), log(5)]}\pythonIdx{log} looks clunky as well.
 Luckily, \python\ offers the much more convenient syntax of list comprehension\pythonIdx{list!comprehension}\pythonIdx{comprehension!list}~\cite{PEP202}:%
 %
-\begin{pythonSyntax}
-# Create a list from the items in a sequence; the condition is optional
-[expression for item in sequence if condition]
-\end{pythonSyntax}
+\pythonSyntax{syntax/list_comprehension.py}%
 %
 \gitLoadAndExecPython{iteration:simple_list_comprehension}{}{iteration}{simple_list_comprehension.py}{}%
 \listingPythonAndOutput{iteration:simple_list_comprehension}{%
@@ -343,10 +340,7 @@
 Set comprehension works very much the same as list comprehension.
 The corresponding syntax is as follows:%
 %
-\begin{pythonSyntax}
-# Create a set from the items in a sequence; the condition is optional
-{expression for item in sequence if condition}
-\end{pythonSyntax}
+\pythonSyntax{syntax/set_comprehension.py}%
 %
 \gitLoadAndExecPython{iteration:simple_set_comprehension}{}{iteration}{simple_set_comprehension.py}{}%
 \listingPythonAndOutput{iteration:simple_set_comprehension}{%
@@ -399,10 +393,7 @@
 Both of them use curly braces, but in dictionary comprehension\pythonIdx{dict!comprehension}\pythonIdx{comprehension!dict}, keys and values are separated by~\pythonilIdx{:}, whereas in a set comprehension, only single values are given.
 Dictionary comprehension has the following syntax:%
 %
-\begin{pythonSyntax}
-# Create a dict from the items in a sequence; the condition is optional
-{expression1: expression2 for item in sequence if condition}
-\end{pythonSyntax}
+\pythonSyntax{syntax/dict_comprehension.py}%
 %
 \gitLoadAndExecPython{iteration:simple_dict_comprehension}{}{iteration}{simple_dict_comprehension.py}{}%
 \listingPythonAndOutput{iteration:simple_dict_comprehension}{%
@@ -472,14 +463,7 @@
 To allow us to create \inQuotes{lazy} sequences that return their elements as needed (instead of keeping them all in memory all the time), generator expressions exist~\cite{PEP289}.
 The syntax for generator expressions is basically the same as for list expressions, except that we use parenthesis instead of square brackets:%
 %
-\begin{pythonSyntax}
-# A generator with the items in a sequence; the condition is optional
-(expression for item in sequence if condition)
-
-# If generator expressions are single function parameters, then the
-# parentheses are unnecessary.
-function(expression for item in sequence if condition)
-\end{pythonSyntax}
+\pythonSyntax{syntax/generator_comprehension.py}%
 %
 \gitLoadAndExecPython{iteration:generator_expressions_next_1}{}{iteration}{generator_expressions_next_1.py}{}%
 \listingPythonAndOutput{iteration:generator_expressions_next_1}{%

text/main/controlFlow/iteration/iteration.tex

@@ -10,17 +10,7 @@
 \pythonIdx{loop!for}%
 The most basic such sequence in \python\ may be the \pythonilIdx{for}~loop, which has the following pattern:%
 %
-\begin{pythonSyntax}
-for loopVariable in sequence:
-    loop body statement 1
-    loop body statement 2
-    # ...
-
-normal statement 1
-normal statement 2
-# ...
-\end{pythonSyntax}
-%
+\pythonSyntax{syntax/for_loop.py}%
 %
 \gitLoadAndExecPython{loops:for_loop_range}{}{loops}{for_loop_range.py}{}%
 \listingPythonAndOutput{loops:for_loop_range}{%
@@ -392,16 +382,7 @@
 Of course, we could try to pick a very very huge number and then \pythonil{break} the loop when the guesses converg {\dots} but that is just ugly.
 The \pythonilIdx{while} comes to rescue:%
 %
-\begin{pythonSyntax}
-while booleanExpression:
-    loop body statement 1
-    loop body statement 2
-    # ...
-
-normal statement 1
-normal statement 2
-# ...
-\end{pythonSyntax}
+\pythonSyntax{syntax/while_loop.py}%
 \FloatBarrier%
 %
 \gitLoadAndExecPython{loops:while_loop_sqrt}{}{loops}{while_loop_sqrt.py}{}%
@@ -454,31 +435,8 @@
 This is totally fine, but \python\ offers us a much less verbose method:
 Using the \pythonilIdx{else} statement at the bottom of the loop, which works for both \pythonilIdx{for} and \pythonilIdx{while} loops:%
 %
-\begin{pythonSyntax}
-for loopVariable in sequence:
-    loop body statement 1
-    loop body statement 2
-    # ...
-else:
-    code executed if break not invoked 1
-    # ...
-normal statement 1
-normal statement 2
-# ...
-\end{pythonSyntax}
-%
-\begin{pythonSyntax}
-while booleanExpression:
-    loop body statement 1
-    loop body statement 2
-    # ...
-else:
-    code executed if break not invoked 1
-    # ...
-normal statement 1
-normal statement 2
-# ...
-\end{pythonSyntax}
+\pythonSyntax{syntax/for_loop_else.py}%
+\pythonSyntax{syntax/while_loop_else.py}%
 %
 \gitLoadAndExecPython{loops:while_loop_search}{}{loops}{while_loop_search.py}{}%
 \listingPythonAndOutput{loops:while_loop_search}{%