Skip to content

Commit e6b1d26

Browse files
The-CompilerThe-Compiler
committed
Document modules/classes/functions
1 parent cd8fc38 commit e6b1d26

File tree

1 file changed

+188
-9
lines changed

1 file changed

+188
-9
lines changed

‎doc/main.tex‎

Lines changed: 188 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1250,6 +1250,7 @@ \section{qutebrowser tab API}
12501250
\end{tikzpicture}
12511251
\end{center}
12521252
\caption{Inheritance tree of tab API classes}
1253+
\label{fig:tabapi-inherit}
12531254
\end{figure}
12541255

12551256
The API exposed by those objects is quite long, so it's not included in full in
@@ -1973,22 +1974,200 @@ \subsection{Adding annotations}
19731974
19741975
\begin{itemize}
19751976
\item \verb|browser.browsertab| (``tab API'')
1977+
\item \verb|browser.webelem|, \verb|browser.webkit.webkitelem|,
1978+
\verb|browser.webengine.webenginelem| (``web element API'')
19761979
\item \verb|misc.objects|
19771980
\item \verb|commands.cmdutils| (registering commands)
1978-
\item Most config-related modules: \verb|config|, \verb|configcache|,
1981+
\item All modules in the \verb|qutebrowser.config| package (\verb|config|, \verb|configcache|,
19791982
\verb|configcommands|, \verb|configdata|, \verb|configdiff|,
1980-
\verb|configexc|, \verb|configfiles|, \verb|configinit|, \verb|configutils|
1983+
\verb|configexc|, \verb|configfiles|, \verb|configinit|, \verb|configtypes|,
1984+
\verb|configutils|, \verb|websettings|).
1985+
\item All modules in the \verb|qutebrowser.api| package (see section \ref{sec:important})
1986+
\item All modules in the \verb|qutebrowser.components| package (see section \ref{sec:important})
1987+
\item All modules in the \verb|qutebrowser.extension| package (see section \ref{sec:important})
19811988
\end{itemize}
19821989
19831990
19841991
% Implementation: Erläuterungen wichtiger konkreter Klassen
1985-
\section{Important Classes}
1986-
% tab API
1987-
% apitypes
1988-
% cmdutils
1989-
% config
1990-
% message
1991-
% requestfilter (?)
1992+
\section{Important packages, modules and classes}
1993+
\label{sec:important}
1994+
The modules added for qutebrowser's extension API are spread across three
1995+
packages:
1996+
1997+
\begin{itemize}
1998+
\item The \verb|qutebrowser.api| package contains the API exposed to
1999+
extensions (in other words, any code which is part of the extension API).
2000+
\item The \verb|qutebrowser.extensions| package contains supporting infrastructure and
2001+
internal code for handling extensions.
2002+
\item The \verb|qutebrowser.components| package contains modules which formerly
2003+
was part of qutebrowser's core and only uses the extension API -- that is, it
2004+
only imports code from the \verb|qutebrowser.api| package, but not from any
2005+
other \verb|qutebrowser.*| packages.
2006+
\end{itemize}
2007+
2008+
\subsection[The qutebrowser.api package]{The qutebrowser.api package: Public extension API}
2009+
2010+
\begin{table}[H]
2011+
\centering
2012+
\begin{tabulary}{\linewidth}{lL}
2013+
\toprule
2014+
Module & Description \\
2015+
\midrule
2016+
\verb|apitypes.py| & Various basic types which can be used by extensions.
2017+
Those are either used as type annotations (such as
2018+
\verb|Tab|, which is an \verb|AbstractTab| from figure
2019+
\ref{fig:tabapi-inherit}) or as enumerations (such as
2020+
\verb|ClickTarget| which is used to specify how to open
2021+
a clicked link). \\
2022+
\verb|cmdutils.py| & Utilities related to registering command handlers from
2023+
extensions, such as the \py{@cmdutils.register()}
2024+
decorator. \\
2025+
\verb|config.py| & Access to the config from extensions, by either using a
2026+
shorthand like
2027+
\verb|config.val.content.javascript.enabled|, or the
2028+
\verb|get()| function like
2029+
\py{config.get('content.javascript.enabled')}. \\
2030+
\verb|downloads.py| & Used to trigger download of temporary files (such as
2031+
adblock filter lists) from extensions. In the future,
2032+
this module could be extended to allow interacting
2033+
with existing downloads triggered by the user. \\
2034+
\verb|hook.py| & Allows extensions to register hooks for certain events via
2035+
decorators, such as \py{@hook.init()} or
2036+
\py{@hook.config_changed()} \\
2037+
\verb|interceptor.py| & Can by used by extensions to register a
2038+
\emph{request interceptor}, which then gets called
2039+
for every network request made by qutebrowser. Based
2040+
on the URL of the page and the URL being requested,
2041+
the extension may decide to block the request. \\
2042+
\verb|message.py| & Used to show messages to the user via functions like
2043+
\py{message.info("...")} or \py{message.error("...")}. \\
2044+
\bottomrule
2045+
\end{tabulary}
2046+
\caption{Modules in the qutebrowser.api package.}
2047+
\label{tab:apimodule}
2048+
\end{table}
2049+
2050+
The \verb|qutebrowser.api| package is described in more detail in the developer
2051+
documentation in appendix \ref{ch:sphinx}.
2052+
2053+
\subsection[The qutebrowser.extensions package]{The qutebrowser.extensions package: Internal extension machinery}
2054+
2055+
The \verb|qutebrowser.extensions| package consists of two modules, which are
2056+
explained in further detail below.
2057+
2058+
\subsubsection{extensions.interceptors module}
2059+
This module implements the internal logic so extensions can intercept and
2060+
optionally block network requests made by qutebrowser.
2061+
2062+
\begin{table}[H]
2063+
\centering
2064+
\begin{tabulary}{\linewidth}{lL}
2065+
\toprule
2066+
Class / Function & Description \\
2067+
\midrule
2068+
\verb|Request| & A class representing a network request, containing
2069+
information such as \verb|first_party_url| (the page being
2070+
visited) or \verb|request_url| (the URL of the resource
2071+
being requested). The request can be blocked by calling its
2072+
\verb|block()| method. \\
2073+
\verb|InterceptorType| & The type of an interceptor function, intended to be
2074+
used in type annotations (exposed to extensions as
2075+
\verb|qutebrowser.api.interceptor.InterceptorType|). \\
2076+
\verb|register()| & Register a new request interceptor (exposed to
2077+
extensions as \verb|qutebrowser.api.interceptor.register()|) \\
2078+
\verb|run()| & Used internally by qutebrowser to run all registered
2079+
interceptors over a request. \\
2080+
\bottomrule
2081+
\end{tabulary}
2082+
\caption{Classes and functions in the qutebrowser.extensions.interceptors package.}
2083+
\end{table}
2084+
2085+
\subsubsection{extensions.loader module}
2086+
This module implements the internal loading and initializing of
2087+
extensions/components. It is responsible for dynamically finding all modules
2088+
in the \verb|qutebrowser.components| package, loading them, and calling their
2089+
registered hooks correctly.
2090+
2091+
\begin{table}[H]
2092+
\centering
2093+
\begin{tabulary}{\linewidth}{lL}
2094+
\toprule
2095+
Class / Function & Description \\
2096+
\midrule
2097+
\verb|InitContext| & Information passed to an extension when it gets
2098+
initialized (if it declares a function decorated with
2099+
\py{@hook.init()}, see \verb|hook.py| in table
2100+
\ref{tab:apimodule}). Contains information such as the
2101+
commandline arguments passed to qutebrowser, or the
2102+
data/config directories used. Used via a
2103+
\verb|_get_init_context()| factory method.\\
2104+
\verb|ModuleInfo| & Information attached to a Python module object. It is
2105+
used to record internal information by decorators like
2106+
\py{@hook.init()} (see \verb|hook.py| in table
2107+
\ref{tab:apimodule}). \\
2108+
\verb|ExtensionInfo| & Meta-information about an extension. Currently only
2109+
contains the name of an extension, but could be
2110+
extended in the future to record additional
2111+
information such as version numbers or the author of
2112+
a third-party extension. \\
2113+
\verb|add_module_info()| & Used internally to add a \verb|ModuleInfo|
2114+
instance to a Python module object. \\
2115+
\verb|load_components()| & Finds and loads all modules in the
2116+
\verb|qutebrowser.components| package (see
2117+
section \ref{sec:components}). Uses a
2118+
\verb|_load_component()| utility function
2119+
internally which loads a single component. \\
2120+
\verb|walk_components()| & Find all available components. Used by
2121+
\verb|load_components()| and by qutebrowser's
2122+
packaging infrastructure so all component modules
2123+
are added to Windows/macOS builds (via
2124+
PyInstaller). Uses two different implementations
2125+
internally: \verb|_walk_normal()| and
2126+
\verb|_walk_pyinstaller()|. The latter needs to
2127+
be used because the simpler approach doesn't work
2128+
in builds built via
2129+
PyInstaller
2130+
\footnote{\url{https://github.com/pyinstaller/pyinstaller/issues/1905}}. \\
2131+
\verb|_on_config_changed()| & Triggered on a configuration change, takes
2132+
care of finding and calling all extension
2133+
methods decorated with
2134+
\py{@hook.config_changed()} (see
2135+
\verb|hook.py| in table \ref{tab:apimodule}). \\
2136+
\bottomrule
2137+
\end{tabulary}
2138+
\caption[Important classes and functions in the qutebrowser.extensions.loader
2139+
package.]{Important classes and functions in the qutebrowser.extensions.loader package.
2140+
Some private functions were redacted for brevity.}
2141+
\end{table}
2142+
2143+
\subsection[The qutebrowser.components package]{The qutebrowser.components
2144+
package: Code moved out of the core}
2145+
\label{sec:components}
2146+
2147+
\begin{table}[H]
2148+
\centering
2149+
\begin{tabulary}{\linewidth}{lL}
2150+
\toprule
2151+
Module & Description \\
2152+
\midrule
2153+
\verb|adblock.py| & qutebrowser's adblocker implementation, blocking
2154+
advertisements in websites. \\
2155+
\verb|caretcommands.py| & Commands related to moving the caret
2156+
(cursor) around via keybindings, such as
2157+
\verb|:move-to-end-of-document| or
2158+
\verb|:toggle-selection| (18 commands total). \\
2159+
\verb|misccommands.py| & Miscellaneous qutebrowser commands, such as
2160+
\verb|:home|, \verb|:reload| or \verb|:print| (15
2161+
commands total) \\
2162+
\verb|scrollcommands.py| & Commands related to scrolling (\verb|:scroll|,
2163+
\verb|:scroll-px|, \verb|:scroll-to-perc|,
2164+
\verb|:scroll-to-anchor|) \\
2165+
\verb|zoomcommands.py| & Commands related to zooming (\verb|:zoom-in|,
2166+
\verb|:zoom-out|, \verb|:zoom|) \\
2167+
\bottomrule
2168+
\end{tabulary}
2169+
\caption{Modules in the qutebrowser.components package.}
2170+
\end{table}
19922171
19932172
% Automatische Testverfahren
19942173
\section{Automated Testing}

0 commit comments

Comments
 (0)