refactoring of python references

Author: thomasWeise

bookbase

@@ -4,7 +4,7 @@
 We already learned about simple datatypes, like integer and floating point numbers, strings, and Boolean values.
 We also learned how we can use variables to store instances (objects) of such datatypes.
 However, in many cases, we do not just want to store a single object.
-Often, we want to store and process \emph{collections} of objects~\cite{PSF2024BIT,PSF2024DM,PSF2024CAABCFC}.
+Often, we want to store and process \emph{collections} of objects~\cite{PSF:P3D:TPSL:BIT,PSF:P3D:TPLR:DM,PSF:P3D:TPSL:CAABCFC}.
 \python\ offers us four basic types of collections:
 
 The first one, \emph{lists}, are mutable sequences of objects.

text/main/basics/collections/collections.tex

@@ -35,7 +35,7 @@
 You may notice that all of these sequences have the same order of elements that was used when we created the dictionary.
 They key-value pair \pythonil{2: "two"} comes before \pythonil{1: "one"}.
 This is because dictionaries, different from sets, are ordered datastructures.
-Their elements appear in all sequenced versions always in the same order in which they were originally inserted into the dictionary~\cite{PSF2024D}.%
+Their elements appear in all sequenced versions always in the same order in which they were originally inserted into the dictionary~\cite{PSF:P3D:TPLR:D}.%
 \end{sloppypar}%
 %
 \begin{sloppypar}%

text/main/basics/collections/dictionaries/dictionaries.tex

@@ -1,7 +1,7 @@
 \hsection{Lists}%
 \label{sec:lists}%
 %
-A \pythonilIdx{list} is a mutable sequence of objects which can be accessed via their index~\cite{PSF2024S}.
+A \pythonilIdx{list} is a mutable sequence of objects which can be accessed via their index~\cite{PSF:P3D:TPLR:S}.
 They work very similar to the strings we already discussed in \cref{sec:str}, but instead of characters, they can contain any kind of objects and they can be modified.%
 %
 \hsection{Basic Functionality and Examples}%
@@ -104,7 +104,7 @@
 \pythonil{[5, 6, 7] * 3}\pythonIdx{*!list}\pythonIdx{list!*} therefore yields \pythonil{[5, 6, 7, 5, 6, 7, 5, 6, 7]}.
 
 In \cref{sec:strBasicOperations}, we discussed string slicing.
-Lists can be sliced in pretty much the same way\pythonIdx{list!slicing}\pythonIdx{slicing}\pythonIdx{slice}~\cite{PSF2024S}.
+Lists can be sliced in pretty much the same way\pythonIdx{list!slicing}\pythonIdx{slicing}\pythonIdx{slice}~\cite{PSF:P3D:TPLR:S}.
 When slicing a list~\pythonil{l} or a string, you can provide either two or three values in the square brackets\pythonIdx{[\idxdots]}\pythonIdx{[i:j:k]}, i.e., either do~\pythonil{l[i:j]}\pythonIdx{[i:j]}\pythonIdx{slicing} or \pythonil{l[i:j:k]}.
 If \pythonil{j < 0}, then it is replaced with~\pythonil{len(l) - j}.
 In both the two and three indices case, \pythonil{i} is the inclusive start index and \pythonil{j} is the exclusive end index, i.e., all elements with index~\pythonil{m} such that \pythonil{i <= m < j}.

text/main/basics/collections/lists/lists.tex

@@ -29,7 +29,7 @@
 }%
 %
 Different from tuples, sets themselves are not immutable.
-Furthermore, sets are \emph{unordered} collections~\cite{PSF2024STSF}.
+Furthermore, sets are \emph{unordered} collections~\cite{PSF:P3D:TPSL:STSF}.
 Therefore, also different from tuples and lists, they cannot be indexed, i.e., the square-bracket notation does not work with sets.%
 %
 \bestPractice{setsUnordered}{%
@@ -82,7 +82,7 @@
 
 We can also convert the set \pythonil{letters} to a list or tuple.
 \pythonil{list(letters)}\pythonIdx{list} will achieve the former, \pythonil{tuple(letters)}\pythonil{tuple} the latter.
-However, since sets are unordered~\cite{PSF2024STSF,PSF2024ST} and the order in which the elements would appear in the created list or tuple is not defined.
+However, since sets are unordered~\cite{PSF:P3D:TPSL:STSF,PSF:P3D:TPLR:ST} and the order in which the elements would appear in the created list or tuple is not defined.
 They may appear in a strange or unexpected order.
 Here we therefore use the function \pythonilIdx{sorted}, which accepts an arbitrary collection of objects as input and returns a sorted list.
 \pythonil{sorted(letters)} therefore creates a list where all the elements of letters appear in a sorted fashion.

text/main/basics/collections/sets/sets.tex

@@ -8,7 +8,7 @@
 More help can be found at the following resources:%
 %
 \begin{itemize}%
-\item the official \python\ setup and usage page~\url{https://docs.python.org/3/using}~\cite{PSF2024PSAU},%
+\item the official \python\ setup and usage page~\url{https://docs.python.org/3/using}~\cite{PSF:P3D:PSAU},%
 \item the \python\ Downloads at~\url{https://www.python.org/downloads}, and%
 \item the \python~3 Installation \& Setup Guide at~\url{https://realpython.com/installing-python}%
 \end{itemize}%

text/main/basics/gettingStarted/installingPython/installingPython.tex

@@ -28,7 +28,7 @@
 But how does it work in \python?
 How can we deal with the fact that we cannot dynamically represent fractional numbers exactly even in typical everyday cases?
 With \pythonilIdx{float}, \python\ offers us one type for fractional numbers.
-This datatype represents numbers usually in the same internal structure as \pythonils{double} in the \pgls{C}~programming language~\cite{PSF2024NTIFC}, which, in turn, internally have a 64~bit IEEE~Standard 754 floating point number layout~\cite{IEEE2019ISFFPA,H1997IS7FPN}.
+This datatype represents numbers usually in the same internal structure as \pythonils{double} in the \pgls{C}~programming language~\cite{PSF:P3D:TPSL:NTIFC}, which, in turn, internally have a 64~bit IEEE~Standard 754 floating point number layout~\cite{IEEE2019ISFFPA,H1997IS7FPN}.
 The idea behind this standard is to represent both very large numbers, like~$10^{300}$ and very small numbers, like~$10^{-300}$.
 In order to achieve this, the 64~bits are divided into three pieces, as illustrated in \cref{fig:floatIEEEStructure}.
 %
@@ -65,7 +65,7 @@
 However, their accuracy is always limited to about 15~digits.
 In other words, regardless whether your \pythonilIdx{float} stores a very large or a very small number, you can have at most 15~digits of precision.
 For example, adding~1 to~$10^{16}$ would still yield~$10^{16}$, because only 15~digits are \inQuotes{stored} and the~1 will just \inQuotes{fall off.}
-You cannot represent numbers arbitrarily precisely~\cite{PSF2024FPAIAL}.%
+You cannot represent numbers arbitrarily precisely~\cite{PSF:P3D:TPT:FPAIAL}.%
 %
 \endhsection%
 %
@@ -124,7 +124,7 @@
 There is no way to write down all the digits of fractions like~$\frac{1}{7}$ as decimals.
 We always need to cut off somewhere, e.g., we could write~$0.14285714285714285$, but that is not exactly the same as~$\frac{1}{7}$.
 As we discussed before, floating point numbers are stored in a binary format, i.e., represented by bits.
-In the binary system, we encounter this problem already for fractions like~$\frac{1}{10}=0.1$~\cite{PSF2024FPAIAL}.
+In the binary system, we encounter this problem already for fractions like~$\frac{1}{10}=0.1$~\cite{PSF:P3D:TPT:FPAIAL}.
 Essentially, we could write $\frac{1}{10}\approx\frac{1}{2^4}+\frac{1}{2^5}+\frac{1}{2^8}+\frac{1}{2^9}+\frac{1}{2^{12}}+\frac{1}{2^{13}}+\frac{1}{2^{16}}+\dots$, but we would never quite get there.
 This means that $0.1$~cannot be exactly represented as \pythonil{float}.
 Therefore, adding it up ten times also does not exactly equal~$1$.

text/main/basics/simpleDataTypesAndOperations/float/float.tex

@@ -141,7 +141,7 @@
 \pythonil{"Hello World!".endswith("Hello")} is \pythonilIdx{False}, too, but \pythonil{"Hello World!".endswith("World!")} is \pythonilIdx{True}.
 
 Of course, these were just a small selection of the many string operations available in \python.
-You can find more in the \href{https://docs.python.org/3/library/stdtypes.html\#textseq}{official documentation}~\cite{PSF2024TSTS}.%
+You can find more in the \href{https://docs.python.org/3/library/stdtypes.html\#textseq}{official documentation}~\cite{PSF:P3D:TPSL:TSTS}.%
 \endhsection%
 %
 \hsection{The str Function and f-strings}%
@@ -174,7 +174,7 @@
 \label{fig:fstrings}%
 \end{figure}
 
-\pythonIdx{str!f}\pythonIdx{f-string}Let us therefore discuss a very powerful and much more convenient gadget in \python's string processing toolbox: format strings, or \pglspl{fstring}\pythonIdx{f-string}\pythonIdx{str!f} for short~\cite{PSF2024FSL,PEP498,M2017WAFSIPAHCIUT,B2023PFS}.
+\pythonIdx{str!f}\pythonIdx{f-string}Let us therefore discuss a very powerful and much more convenient gadget in \python's string processing toolbox: format strings, or \pglspl{fstring}\pythonIdx{f-string}\pythonIdx{str!f} for short~\cite{PSF:P3D:TPT:FSL,PEP498,M2017WAFSIPAHCIUT,B2023PFS}.
 An \pgls{fstring} is like a normal string, except that it starts with \pythonil{f"}\pythonIdx{f\textquotedbl\idxdots\textquotedbl} instead of \pythonil{"}.
 And, most importantly, it can contain other data and even complete expressions inside curly braces~(\pythonil{\{...\}}\pythonIdx{\textbraceleft\idxdots\textbraceright!f-string}) which are then embedded into the string.%
 %
@@ -279,7 +279,7 @@
 \pythonil{f"Single braces without expression: \{\{ and \}\}."} simply becomes \pythonil{"Single braces without expression: \{ and \}."}
 
 As final example, let us look at a very cool ability of \pglspl{fstring}\pythonIdx{f-string!=}.
-Often, we want to print an expression together with its result~\cite{PSF2024WNIP38FSFSDEAD}.
+Often, we want to print an expression together with its result~\cite{PSF:P3D:WNIP:WNIP38FSFSDEAD}.
 Earlier, we wrote \pythonil{f"\{5\}\ + \{4\}\ = \{5 + 4\}"} is evaluated to \pythonil{"5 + 4 = 9"}.
 What we actually wanted to print was the expression \pythonil{5 + 4} together with its result.
 This can be done much easier:

text/main/basics/simpleDataTypesAndOperations/str/str.tex

@@ -296,7 +296,7 @@
 This is illustrated in \cref{fig:addingFloatsError}:
 If we add~\pythonil{1} to~$10^{15}=\pythonil{1e15}$, the correct result is~\pythonil{1000000000000001.0}.
 However, if we add~\pythonil{1} to~$10^{16}=\pythonil{1e16}$, the result is still~\pythonil{1e16}.
-It is not possible to represent the number~$1+10^{16}$ correctly with the 64~bit double precision floating point numbers that \python\ offers~\cite{PSF2024FPAIAL}.
+It is not possible to represent the number~$1+10^{16}$ correctly with the 64~bit double precision floating point numbers that \python\ offers~\cite{PSF:P3D:TPT:FPAIAL}.
 Usually, that itself is totally fine:
 There are few application in \inQuotes{everyday programming} where we really need more than fifteen digits of precision.
 

text/main/classes/basics/basics.tex

@@ -1,6 +1,6 @@
 \hsection{Dunder Methods}%
 %
-In \python, \emph{everything is an object}~\cite{PSF2024OVAT,J2022PPEIAOSCD}.
+In \python, \emph{everything is an object}~\cite{PSF:P3D:TPLR:OVAT,J2022PPEIAOSCD}.
 Functions, modules, classes, datatypes, values of simple datatypes, and so on -- all are objects.
 Many of these objects have special functionality.
 For example, we can add, multiply, and divide numerical objects.
@@ -143,7 +143,7 @@
 If so, it will return \pythonil{True} if and only if the \pythonil{x} and \pythonil{y} coordinate of the \pythonil{other} point are the same as of the point \pythonil{self}.
 Otherwise, it will return the constant \pythonilIdx{NotImplemented}:%
 %
-\cquotation{PSF2024BIC}{%
+\cquotation{PSF:P3D:TPSL:BIC}{%
 A special value which should be returned by the binary special methods [\dots] to indicate that the operation is not implemented with respect to the other type\dots\medskip\\\strut\hspace{1cm}\strut%
 \emph{Note:}~When a binary (or in-place) method returns \pythonilIdx{NotImplemented} the interpreter will try the reflected operation on the other type (or some other fallback, depending on the operator). %
 If all attempts return \pythonilIdx{NotImplemented}, the interpreter will raise an appropriate exception. %
@@ -186,14 +186,14 @@
 %
 \end{itemize}%
 %
-For these two methods, it must hold that~\cite{PSF2024OH}%
+For these two methods, it must hold that~\cite{PSF:P3D:TPLR:OH}%
 %
 \begin{equation}%
 \pythonil{a.\_\_eq\_\_(b)} \Rightarrow \pythonil{a.\_\_hash\_\_()} = \pythonil{b.\_\_hash\_\_()}%
 \label{eq:eqAndHash1}%
 \end{equation}%
 %
-This is equivalent~\cite{PSF2024BIE,PSF2024OH} to:%
+This is equivalent~\cite{PSF:P3D:TPSL:BIE,PSF:P3D:TPLR:OH} to:%
 %
 \begin{equation}%
 \pythonil{a == b} \Rightarrow \pythonil{hash(a)} = \pythonil{hash(b)}%
@@ -253,12 +253,12 @@
 In \cref{lst:dunder:point_with_hash}, we modify the \pythonil{Point} class from \cref{lst:dunder:point_with_dunder}.
 We retain the implementation of~\dunder{eq} and add the method~\dunder{hash}.%
 %
-\cquotation{PSF2024OH}{{\dots}The \pythonil{\_\_hash\_\_()}\pythonIdx{\_\_hash\_\_}\pythonIdx{dunder!\_\_hash\_\_} method should return an integer. %
+\cquotation{PSF:P3D:TPLR:OH}{{\dots}The \pythonil{\_\_hash\_\_()}\pythonIdx{\_\_hash\_\_}\pythonIdx{dunder!\_\_hash\_\_} method should return an integer. %
 The only required property is that objects which compare equal have the same hash value; %
 it is advised to mix together the hash values of the components of the object that also play a part in comparison of objects by packing them into a \pythonil{tuple} and hashing the tuple.}%
 %
 \bestPractice{hash}{%
-For implementing \dunder{eq} and \dunder{hash}, the following rules hold~\cite{PSF2024OH}:%
+For implementing \dunder{eq} and \dunder{hash}, the following rules hold~\cite{PSF:P3D:TPLR:OH}:%
 \sloppy%
 \begin{itemize}\sloppy%
 %
@@ -301,7 +301,7 @@
 Actually, I secretly planned to use this as a very tricky example for learning how to use the debugger{\dots}
 Alas, the developers of \python\ have already solved this:%
 %
-\cquotation{PSF2024BIF}{Numeric values that compare equal have the same \pythonilIdx{hash} value (even if they are of different types, as is the case for~\pythonil{1} and~\pythonil{1.0}).}%
+\cquotation{PSF:P3D:TPSL:BIF}{Numeric values that compare equal have the same \pythonilIdx{hash} value (even if they are of different types, as is the case for~\pythonil{1} and~\pythonil{1.0}).}%
 %
 Therefore, we can indeed implement \dunder{hash} with a single line of code in~\cref{sec:hashDunder}.
 And I will later find another example on how the debugger can be used to spot errors in code.%
@@ -340,7 +340,7 @@
 We implement the basic arithmetic operations for a class~\pythonil{Fraction} that represents fractions~$q\in\rationalNumbers$, i.e., it holds that~$q=\frac{a}{b}$ with~$a,b\in\integerNumbers$ and~$b\neq0$.\footnote{
 \python\ already has such a type built-in. %
 Our goal here is to explore dunder methods, so we make our own class instead. %
-In any actual application, you would use the more efficient class \pythonilIdx{Fraction} from the module~\pythonilIdx{fractions}~\cite{PSF2024FRN}.%
+In any actual application, you would use the more efficient class \pythonilIdx{Fraction} from the module~\pythonilIdx{fractions}~\cite{PSF:P3D:TPSL:FRN}.%
 }
 In other words, we want to pour primary school mathematics into a new numerical type.
 To refresh our memory, $a$~is called the \pgls{numerator} and $b$~is called the \pgls{denominator} of the fraction~$\frac{a}{b}$.
@@ -1385,7 +1385,7 @@
 The \pythonilIdx{\_\_exit\_\_}\pythonIdx{dunder!\_\_exit\_\_} method looks a bit different from \pythonilIdx{\_\_enter\_\_}\pythonIdx{dunder!\_\_enter\_\_}.
 First, it also gets three parameters: the exception type~\pythonil{exc_type}, the exception value~\pythonil{exc_value}, and the stack~\pythonil{traceback}.
 These parameters are filled with the information about any \pythonilIdx{Exception} raised within the \pythonilIdx{with}~body.
-Otherwise, they will be~\pythonil{None}~\cite{PSF2024WSCM}.
+Otherwise, they will be~\pythonil{None}~\cite{PSF:P3D:TPLR:WSCM}.
 We here just define a single parameter~\pythonil{*exc}.
 This syntax tells \python\ to capture all positional arguments into a single tuple.
 Since we do not care about exceptions here, we just write this to safe space, honestly, because I do not want to write three lines of \pgls{docstring} where one suffices.

text/main/classes/dunder/dunder.tex

@@ -579,13 +579,13 @@
 \pylint\ suggests to go with a \pythonilIdx{with}~statement instead.
 They both mean the same.
 
-\cquotation{PSF2024WSCM}{%
+\cquotation{PSF:P3D:TPLR:WSCM}{%
 A context manager is an object that defines the runtime context to be established when executing a \pythonilIdx{with} statement. %
 The context manager handles the entry into, and the exit from, the desired runtime context for the execution of the block of code. %
 [\dots] %
 Typical uses of context managers include saving and restoring various kinds of global state, locking and unlocking resources, closing opened files, etc.}%
 %
-The \pythonilIdx{with} statement has the following syntax, where the \pythonil{expression} is supposed to return a context manager~\cite{PSF2024WSCM,PSF2024CUFWSC,PSF2024TWS,PEP343}.%
+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:
@@ -646,7 +646,7 @@
 Luckily, \pytest\ offers us a device for this.
 
 Let us expand our \cref{lst:functions:test_my_math_2} for testing the \pythonil{sqrt} function to now also test for \pythonilsIdx{ArithmeticError}.
-The \pythonilIdx{pytest} module offers a so-called context manager~\cite{PSF2024CUFWSC} named \pythonilIdx{raises}.
+The \pythonilIdx{pytest} module offers a so-called context manager~\cite{PSF:P3D:TPSL:CUFWSC} named \pythonilIdx{raises}.
 If we want to check whether a function indeed raises a certain exception of type \pythonil{ExpectedExceptionType} for a given input, then we can wrap the corresponding function call into \pythonil{with raises(ExpectedExceptionType):}.
 This is block tells the \pytest\ system that, in the following, indented, block, we expect that a certain exception must be raised.
 If such an exception is not raised, the test fails.
@@ -802,7 +802,7 @@
 .2 \pythonilIdx{SystemExit}\DTcomment{raised by \pythonilIdx{exit}; not an error}.
 }%
 %
-\caption{An overview of the hierarchy of \pythonilsIdx{Exception} in \python~\cite{PSF2024BIE}.}%
+\caption{An overview of the hierarchy of \pythonilsIdx{Exception} in \python~\cite{PSF:P3D:TPSL:BIE}.}%
 \label{fig:pythonExceptions}%
 \end{figure}%
 %
@@ -815,7 +815,7 @@
 Running out of memory is a completely different situation than trying to read from a non-existing file.
 Therefore, different types of exceptions are raised:
 The former problem causes a \pythonilIdx{MemoryError} while the later raises an \pythonilIdx{FileNotFoundError}.
-The hierarchy of the different problem types is illustrated in \cref{fig:pythonExceptions}~\cite{PSF2024BIE}.
+The hierarchy of the different problem types is illustrated in \cref{fig:pythonExceptions}~\cite{PSF:P3D:TPSL:BIE}.
 There, you can also see why an \pythonilIdx{except} block catching \pythonilsIdx{ArithmeticError} would also catch an \pythonilsIdx{OverflowError}, because the latter is a special case of the former.
 
 Depending on the operations that your code tries to perform, you would wrap it into \pythonilIdx{except} blocks for the errors from this list that you could reasonably expect to be able to recover from.