|
| 1 | +\hsection{Interlude:~Searching in the Python Documentation}% |
| 2 | +\label{sec:pythonDocumentation}% |
| 3 | +\let\oldinterludepythonglslink\glslink% |
| 4 | +\protected\gdef\glslink#1#2{#2}% |
| 5 | +% |
| 6 | +\begin{figure}% |
| 7 | +\centering% |
| 8 | +% |
| 9 | +\subfloat[][% |
| 10 | +We open a browser and visit the \citetitle{PSF:P3D}~\cite{PSF:P3D} at~\citeurl{PSF:P3D}.% |
| 11 | +\label{fig:pythondoc01website}% |
| 12 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondoc01website}}}% |
| 13 | +% |
| 14 | +\floatSep% |
| 15 | +% |
| 16 | +\subfloat[][% |
| 17 | +If you click the \menu{\threeBarButton} at on the top-left corner of the website, you can get to a menu where you can change the language and, e.g., select simplified Chinese~(简体中文) if that is your preferred language.~% |
| 18 | +(I will not do so and instead continue in English.)% |
| 19 | +\label{fig:pythondoc02language}% |
| 20 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondoc02language}}}% |
| 21 | +% |
| 22 | +\floatRowSep% |
| 23 | +% |
| 24 | +\subfloat[][% |
| 25 | +We are looking for information on the \pythonilIdx{ceil} function and therefore type \pythonilIdx{ceil} into the search bar \emph{of the website} and click on~\menu{Go}.% |
| 26 | +\label{fig:pythondoc03searchCeil}% |
| 27 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondoc03searchCeil}}}% |
| 28 | +% |
| 29 | +\floatSep% |
| 30 | +% |
| 31 | +\subfloat[][% |
| 32 | +Especially if you visit the website for the first time in your current web browser session, it may take some time until results show up. % |
| 33 | +We wait patiently.% |
| 34 | +\label{fig:pythondoc04wait}% |
| 35 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondoc04wait}}}% |
| 36 | +% |
| 37 | +\floatRowSep% |
| 38 | +% |
| 39 | +\subfloat[][% |
| 40 | +A list of documentation articles about the \pythonilIdx{ceil} function appears. % |
| 41 | +We click on the link to~\pythonil{math.ceil}.% |
| 42 | +\label{fig:pythondoc05results}% |
| 43 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondoc05results}}}% |
| 44 | +% |
| 45 | +\floatSep% |
| 46 | +% |
| 47 | +\subfloat[][% |
| 48 | +It takes us to the \pythonilIdx{ceil}~entry of the \citetitle{PSF:P3D:TPSL:MMF} page~\cite{PSF:P3D:TPSL:MMF} at \citeurl{PSF:P3D:TPSL:MMF}. % |
| 49 | +Indeed, we find a brief explanation about the \pythonilIdx{ceil} function.~% |
| 50 | +(Also, we find a link to further reading about the \dunder{ceil} method, which we will discuss much later in~\cref{fig:pythonDunder:2}.) |
| 51 | +\label{fig:pythondoc06mathceil}% |
| 52 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondoc06mathceil}}}% |
| 53 | +% |
| 54 | +% |
| 55 | +\caption{Searching the \citetitle{PSF:P3D}~\cite{PSF:P3D} for information about the function~\pythonilIdx{ceil}.}% |
| 56 | +\label{fig:pythondoc:A}% |
| 57 | +\end{figure}% |
| 58 | +% |
| 59 | +\begin{figure}% |
| 60 | +\centering% |
| 61 | +% |
| 62 | +\subfloat[][% |
| 63 | +We try searching for information about \inQuotes{round towards positive infinity} in the~\citetitle{PSF:P3D}~\cite{PSF:P3D} at~\citeurl{PSF:P3D}.% |
| 64 | +\label{fig:rounding01searchInDocumentation}% |
| 65 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/rounding01searchInDocumentation}}}% |
| 66 | +% |
| 67 | +\floatSep% |
| 68 | +% |
| 69 | +\subfloat[][% |
| 70 | +The results are not too useful. % |
| 71 | +The first result is unrelated to floating point numbers. % |
| 72 | +The second one is a complete list of all functions in the module~\pythonilIdx{math}. % |
| 73 | +However, without knowing that the right function is called~\pythonilIdx{ceil}, finding it in this list could be hard.% |
| 74 | +\label{fig:rounding02foundNothingUseful}% |
| 75 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/rounding02foundNothingUseful}}}% |
| 76 | +% |
| 77 | +\floatRowSep% |
| 78 | +% |
| 79 | +\subfloat[][% |
| 80 | +We enter \inQuotes{round towards positive infinity} into an internet search engine, here Microsoft Bing at~\url{https://bing.com}, but any search engine should do just as well. % |
| 81 | +The result looks promising.% |
| 82 | +\label{fig:rounding03searchEngine}% |
| 83 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/rounding03searchEngine}}}% |
| 84 | +% |
| 85 | +\floatSep% |
| 86 | +% |
| 87 | +\subfloat[][% |
| 88 | +Clicking on the first result, we visit the page~\citetitle{D2021RPT:A2024HTRNIP}~\cite{D2021RPT:A2024HTRNIP} at \citeurl{D2021RPT:A2024HTRNIP}.% |
| 89 | +\label{fig:rounding04realPython}% |
| 90 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/rounding04realPython}}}% |
| 91 | +% |
| 92 | +\floatRowSep% |
| 93 | +% |
| 94 | +\subfloat[][% |
| 95 | +After scrolling down a bit, we indeed find the information we want: % |
| 96 | +For rounding up, the function~\pythonilIdx{ceil} is suitable. % |
| 97 | +It is even presented as hyperlink.% |
| 98 | +\label{fig:rounding05realPythonScrolledToCeil}% |
| 99 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/rounding05realPythonScrolledToCeil}}}% |
| 100 | +% |
| 101 | +\floatSep% |
| 102 | +% |
| 103 | +\subfloat[][% |
| 104 | +If we click on the hyperlink, it takes us to the \pythonilIdx{ceil}~entry in the \citetitle{PSF:P3D:TPSL:MMF} page~\cite{PSF:P3D:TPSL:MMF} at \citeurl{PSF:P3D:TPSL:MMF}.% |
| 105 | +\label{fig:rounding06foundCeilInPythonDoc}% |
| 106 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/rounding06foundCeilInPythonDoc}}}% |
| 107 | +% |
| 108 | +% |
| 109 | +\caption{Searching for a \python\ function for \inQuotes{rounding up} if we do not know its name.}% |
| 110 | +\label{fig:pythondoc:B}% |
| 111 | +% |
| 112 | +\end{figure}% |
| 113 | +% |
| 114 | +\begin{figure}% |
| 115 | +\centering% |
| 116 | +% |
| 117 | +\subfloat[][% |
| 118 | +The \citetitle{PSF:P3D:PSAU} page~\cite{PSF:P3D:PSAU} at~\citeurl{PSF:P3D:PSAU}.% |
| 119 | +\label{fig:pythondocOther01setupAndUsage}% |
| 120 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondocOther01setupAndUsage}}}% |
| 121 | +% |
| 122 | +\floatSep% |
| 123 | +% |
| 124 | +\subfloat[][% |
| 125 | +The \citetitle{PSF:P3D:TPT} page~\cite{PSF:P3D:TPT} page at~\citeurl{PSF:P3D:TPT}.% |
| 126 | +\label{fig:pythondocOther02tutorial}% |
| 127 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondocOther02tutorial}}}% |
| 128 | +% |
| 129 | +\floatRowSep% |
| 130 | +% |
| 131 | +\subfloat[][% |
| 132 | +The \citetitle{PSF:P3D:TPSL} page~\cite{PSF:P3D:TPSL} at~\citeurl{PSF:P3D:TPSL}.% |
| 133 | +\label{fig:pythondocOther03standardLibrary}% |
| 134 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondocOther03standardLibrary}}}% |
| 135 | +% |
| 136 | +\floatSep% |
| 137 | +% |
| 138 | +\subfloat[][% |
| 139 | +The \citetitle{PEP0} page~\cite{PEP0} at~\citeurl{PEP0}.% |
| 140 | +\label{fig:pythondocOther04pep0}% |
| 141 | +]{\tightbox{\includegraphics[width=0.47\linewidth]{\currentDir/pythondocOther04pep0}}}% |
| 142 | +% |
| 143 | +\caption{Several important authoritative online resources on \python.}% |
| 144 | +\label{fig:pythondoc:C}% |
| 145 | +\end{figure}% |
| 146 | +% |
| 147 | +In the previous section, we discussed lots of functions, \pythonilIdx{sin}, \pythonilIdx{cos}, \pythonilIdx{tan}, \pythonilIdx{atan}, \pythonilIdx{exp}, \pythonilIdx{log}, \pythonilIdx{round}, \pythonilIdx{floor}, \pythonilIdx{trunc}, and~\pythonilIdx{ceil}, to name just a few. |
| 148 | +You could read about and explore what these functions do in this book. |
| 149 | +However, there are two issues with this: |
| 150 | + |
| 151 | +First, this book can only provide brief introductions into these functions from a didactic perspective. |
| 152 | +It does not make any sense to here discuss their exact specifications and relationships to other functions in the \python\ ecosystem. |
| 153 | +So what do you do if you need exact, authoritative information about full specification of a function? |
| 154 | +Second, you only learn about the functions that we \emph{do} list. |
| 155 | +What do you do if you want to learn about a function that we do not discuss here? |
| 156 | + |
| 157 | +The answer to the first question is rather simple: |
| 158 | +There is a complete online help catalog available for \python:~the \citetitle{PSF:P3D}~\cite{PSF:P3D} at~\url{https://docs.python.org/3}. |
| 159 | +This should be your primary destination if you want to learn anything about \python. |
| 160 | +Also, it is available in Chinese. |
| 161 | + |
| 162 | +As example, let us imagine that you want to learn more about the function~\pythonilIdx{ceil}. |
| 163 | +In \cref{fig:pythondoc01website}, we open a browser and visit the \citetitle{PSF:P3D}~\cite{PSF:P3D} at~\url{https://docs.python.org/3}. |
| 164 | +On this page, you will either directly see a drop-down box where you can choose your favorite language or you can find it by clicking the \menu{\threeBarButton} at on the top-left corner of the website. |
| 165 | +In the menu that opens in \cref{fig:pythondoc02language}, you can change the language and, e.g., select simplified Chinese~(简体中文) if that is your preferred language. |
| 166 | +I will not do so and instead continue here in English. |
| 167 | + |
| 168 | +Regardless of which language you chose, we still want to find information about the \pythonilIdx{ceil}~function. |
| 169 | +Therefore, we locate the search bar \emph{in the website}~(not the one where you type in the \pglspl{URL} in the web browser). |
| 170 | +Into this search bar, we type \pythonilIdx{ceil} and click on~\menu{Go} in \cref{fig:pythondoc03searchCeil}. |
| 171 | + |
| 172 | +Depending on your internet connection and your location on the globe, it may take a bit of time until results are displaced. |
| 173 | +Especially when visiting the page for the first time during a browsing session. |
| 174 | +We wait patiently in \cref{fig:pythondoc04wait}. |
| 175 | +And indeed, a list of documentation articles about the \pythonilIdx{ceil} function appears after a brief wait in \cref{fig:pythondoc05results}. |
| 176 | +We decide that the link to \pythonil{math.ceil} looks most promising and click on it. |
| 177 | + |
| 178 | +It takes us to the \pythonilIdx{ceil}~entry of the \citetitle{PSF:P3D:TPSL:MMF} page~\cite{PSF:P3D:TPSL:MMF} at \citeurl{PSF:P3D:TPSL:MMF}. |
| 179 | +There, we find a brief explanation about the \pythonilIdx{ceil} function, as shown in \cref{fig:pythondoc06mathceil}. |
| 180 | +The explanation also provides further reading, e.g., a link to the \dunder{ceil} method. |
| 181 | +This is not important here, we will discuss it much later in~\cref{fig:pythonDunder:2}, but if we were interested, we could continue exploring and find more information about~\pythonilIdx{ceil}. |
| 182 | +Also, we see that the information about the \pythonilIdx{ceil}~function is part of a longer list of mathematical functions. |
| 183 | +Being curious, we would scroll a bit through this list. |
| 184 | +Maybe we could learn about one or two other functions that we did not know about yet.% |
| 185 | +% |
| 186 | +\usefulTool{pythonDoc}{% |
| 187 | +The first place to look for information about \python\ is the official \citetitle{PSF:P3D} at \citeurl{PSF:P3D}. % |
| 188 | +This is the \emph{authoritative} source about \python: % |
| 189 | +Everything what is written there is \emph{true} and \emph{exact} regarding~\python. % |
| 190 | +All other sources may contain errors, be imprecise, ambiguous, or outdated. % |
| 191 | +Therefore, always first consult the official \python\ documentation when being in doubt or looking for information.% |
| 192 | +}% |
| 193 | +% |
| 194 | +Of course, in many cases, we do not know the name of the function we are looking for. |
| 195 | +Assume that you did not know that the function~\pythonilIdx{ceil} exists. |
| 196 | +You were looking for a way to round floating point numbers \inQuotes{upwards.} |
| 197 | + |
| 198 | +You want to do something that you know should somehow be possible. |
| 199 | +You think that \python\ should probably offer some out-of-the-box function for doing that. |
| 200 | +If not, there should at least be some \inQuotes{standard \python way} to do that. |
| 201 | +Anyway, the point is: |
| 202 | +You do not have a function name to look for. |
| 203 | + |
| 204 | +Let's again start at the search mask of the \citetitle{PSF:P3D} at~\citeurl{PSF:P3D}. |
| 205 | +In \cref{fig:rounding01searchInDocumentation}, we try to describe what we want to do as clearly as possible. |
| 206 | +\inQuotes{Rounding up} is maybe not very precise. |
| 207 | +Let's enter \inQuotes{round towards positive infinity} into the search mask. |
| 208 | + |
| 209 | +Sadly, the results shown in \cref{fig:rounding02foundNothingUseful} are not too useful. |
| 210 | +This can happen. |
| 211 | +The first result is unrelated to floating point numbers. |
| 212 | +It offers us some discussion about objects implementing fractional arithmetics in a different way. |
| 213 | +While we could find some hints in this text, it is not useful. |
| 214 | + |
| 215 | +The second search result takes us to the a complete list of all functions in the module~\pythonilIdx{math}~\cite{PSF:P3D:TPSL:MMF}, but \emph{not} to the \pythonilIdx{ceil} function. |
| 216 | +This means that we would need to go through the whole list of functions, read all of their descriptions, until we arrive at one that matches our goals. |
| 217 | +This is a feasible method. |
| 218 | +The list is not too long. |
| 219 | +We could indeed spot the right answer here. |
| 220 | +And we would probably learn more about \python\ on the way. |
| 221 | +So directly working our way through the documentation here is a good idea. |
| 222 | + |
| 223 | +But let's say that we did not find anything useful and gave up using the \python\ documentation directly. |
| 224 | +The second thing that we could try is to enter the description of what we want to do into a common search engine. |
| 225 | +In \cref{fig:rounding03searchEngine}, we use Microsoft Bing at~\url{https://bing.com}, but any other search engine would probably be as same as good. |
| 226 | +We enter \inQuotes{round towards positive infinity} into the search mask and hit~\menu{Search}. |
| 227 | + |
| 228 | +The first result looks promising right way. |
| 229 | +\inQuotes{\cite{D2021RPT:A2024HTRNIP}} {\dots} while it does not say \inQuotes{round towards infinity,} if it summarizes all information about rounding numbers, that topic is bound to come up somewhere. |
| 230 | +So we click the link. |
| 231 | + |
| 232 | +It takes us visit to the page~\citetitle{D2021RPT:A2024HTRNIP}~\cite{D2021RPT:A2024HTRNIP} at \citeurl{D2021RPT:A2024HTRNIP} in \cref{fig:rounding04realPython}. |
| 233 | +A summary page on all about rounding of numbers. |
| 234 | +Nice. |
| 235 | + |
| 236 | +We begin to read the text. |
| 237 | +Reading is an important skill, as reading texts and tutorials can significantly expand our knowledge. |
| 238 | +After reading for a while, we indeed find the information we want: |
| 239 | +For rounding up, the function~\pythonilIdx{ceil} is suitable. |
| 240 | +It is even presented as a hyperlink in \cref{fig:rounding05realPythonScrolledToCeil}. |
| 241 | +If we click on the hyperlink in \cref{fig:rounding06foundCeilInPythonDoc}, it takes us to the \pythonilIdx{ceil}~entry in the \citetitle{PSF:P3D:TPSL:MMF} page~\cite{PSF:P3D:TPSL:MMF} at \citeurl{PSF:P3D:TPSL:MMF}. |
| 242 | +So we went round trip: |
| 243 | +Even if we do not know how to do a given thing or what its name is, we can still find our way to the \python\ documentation.% |
| 244 | +% |
| 245 | +\usefulTool{searchEngines}{% |
| 246 | +Search engines are useful tools to find information about certain functionality. % |
| 247 | +Writing a precise description of the problem or functionality into the search bar of a search engine can lead to pages that describe answers or take us to the official \python\ documentation. % |
| 248 | +However, search engines can also lead us to pages containing wrong, incomplete, ambiguous, outdated, or otherwise useless information. % |
| 249 | +It is important to compare whatever information we found with the official \python\ documentation~\cite{PSF:P3D}.% |
| 250 | +}% |
| 251 | +% |
| 252 | +Let us also note: |
| 253 | +Besides being a source of authoritative information about \python, the official website also offers a variety of other useful information. |
| 254 | +You may have already used the \citetitle{PSF:P3D:PSAU} page~\cite{PSF:P3D:PSAU} at~\citeurl{PSF:P3D:PSAU}, screenshotted in \cref{fig:pythondocOther01setupAndUsage}, when installing \python\ on your system. |
| 255 | + |
| 256 | +The \citetitle{PSF:P3D:TPT} page~\cite{PSF:P3D:TPT} page at~\citeurl{PSF:P3D:TPT} and shown in \cref{fig:pythondocOther02tutorial} offers several useful tutorials. |
| 257 | +Actually, it describes many of the techniques that we discuss in this book in much depth and very nicely, probably even better than this book. |
| 258 | +I very strongly urge you to also read this website. |
| 259 | + |
| 260 | +The \citetitle{PSF:P3D:TPSL} page~\cite{PSF:P3D:TPSL} at~\citeurl{PSF:P3D:TPSL} depicted in \cref{fig:pythondocOther03standardLibrary} contains the specification of all the standard functions that ship with \python. |
| 261 | +It is therefore a very useful tool when checking what a function \emph{actually} does, to complement our learned knowledge. |
| 262 | + |
| 263 | +Finally, the \citetitle{PEP0} page~\cite{PEP0} at~\citeurl{PEP0} shown in \cref{fig:pythondocOther04pep0} contains all changes and additions to the \python\ language since roughly the year~2000. |
| 264 | +We can find many of the language utilities that we are using in this book defined in a so-called~\emph{Python Enhancement Proposal~(PEP)}.% |
| 265 | +% |
| 266 | +\FloatBarrier% |
| 267 | +\global\let\glslink\oldinterludepythonglslink% |
| 268 | +\endhsection% |
| 269 | +% |
0 commit comments