Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes14kdownloads
code_overview.html343 linesDownload Raw Back to html
1
2
3<!DOCTYPE html>
4
5<html lang="en" data-content_root="./">
6  <head>
7    <meta charset="utf-8" />
8    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
9
10    <title>Code Overview &#8212; pgAdmin 4 8.6 documentation</title>
11    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
12    <link rel="stylesheet" type="text/css" href="_static/style.css?v=d36593c3" />
13    
14    <script src="_static/documentation_options.js?v=d4c83366"></script>
15    <script src="_static/doctools.js?v=9a2dae69"></script>
16    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
17    
18    <script src="_static/sidebar.js"></script>
19    
20    <link rel="index" title="Index" href="genindex.html" />
21    <link rel="search" title="Search" href="search.html" />
22    <link rel="next" title="Coding Standards" href="coding_standards.html" />
23    <link rel="prev" title="Submitting Pull Requests" href="submitting_pull_requests.html" /> 
24  </head><body>
25    <div class="related" role="navigation" aria-label="related navigation">
26      <h3>Navigation</h3>
27      <ul>
28        <li class="right" style="margin-right: 10px">
29          <a href="genindex.html" title="General Index"
30             accesskey="I">index</a></li>
31        <li class="right" >
32          <a href="coding_standards.html" title="Coding Standards"
33             accesskey="N">next</a> |</li>
34        <li class="right" >
35          <a href="submitting_pull_requests.html" title="Submitting Pull Requests"
36             accesskey="P">previous</a> |</li>
37        <li class="nav-item nav-item-0"><a href="index.html">pgAdmin 4 8.6 documentation</a> &#187;</li>
38          <li class="nav-item nav-item-1"><a href="contributions.html" accesskey="U">pgAdmin Project Contributions</a> &#187;</li>
39        <li class="nav-item nav-item-this"><a href="">Code Overview</a></li> 
40      </ul>
41    </div>  
42
43    <div class="document">
44      <div class="documentwrapper">
45        <div class="bodywrapper">
46          <div class="body" role="main">
47            
48  <section id="code-overview">
49<span id="id1"></span><h1><span class="target" id="index-0"></span>Code Overview<a class="headerlink" href="#code-overview" title="Link to this heading">¶</a></h1>
50<p>The bulk of pgAdmin is a Python web application written using the Flask framework
51on the backend, and HTML5 with CSS3,ReactJS on the front end. A
52desktop runtime is also included for users that prefer a desktop application to
53a web application, which is written using NWjs (Node Webkit).</p>
54<section id="runtime">
55<h2>Runtime<a class="headerlink" href="#runtime" title="Link to this heading">¶</a></h2>
56<p>The runtime is based on NWjs which integrates a browser and the Python server
57creating a standalone application. The source code can be found in the
58<strong>/runtime</strong> directory in the source tree.</p>
59</section>
60<section id="web-application">
61<h2>Web Application<a class="headerlink" href="#web-application" title="Link to this heading">¶</a></h2>
62<p>The web application forms the bulk of pgAdmin and can be found in the <strong>/web</strong>
63directory in the source tree. The main file is <strong>pgAdmin4.py</strong> which can be used
64to run the built-in standalone web server, or as a WSGI application for production
65use.</p>
66<section id="configuration">
67<h3>Configuration<a class="headerlink" href="#configuration" title="Link to this heading">¶</a></h3>
68<p>The core application configuration is found in <strong>config.py</strong>. This file includes
69all configurable settings for the application, along with descriptions of their
70use. It is essential that various settings are configured prior to deployment on
71a web server; these can be overridden in <strong>config_local.py</strong> or
72<strong>config_system.py</strong> (see the <a class="reference internal" href="config_py.html#config-py"><span class="std std-ref">config.py</span></a> documentation) to
73avoid modifying the main configuration file.</p>
74</section>
75<section id="user-settings">
76<h3>User Settings<a class="headerlink" href="#user-settings" title="Link to this heading">¶</a></h3>
77<p>When running in desktop mode, pgAdmin has a single, default user account that is
78used for the desktop user. When running in server mode, there may be unlimited
79users who are required to login prior to using the application. pgAdmin utilised
80the <strong>Flask-Security</strong> module to manage application security and users, and
81provides options for self-service password reset and password changes etc.</p>
82<p>Whether in desktop or server mode, each user’s settings are stored in a SQLite
83OR external database which is also used to store the user accounts. This is initially
84created using the <strong>setup.py</strong> script which will create the database file and
85schema within it, and add the first user account (with administrative
86privileges) and a default server group for them. A <strong>settings</strong> table is also
87used to store user configuration settings in a key-value fashion. Although not
88required, setting keys (or names) are typically formatted using forward slashes
89to artificially namespace values, much like the pgAdmin 3 settings files on Linux
90or Mac.</p>
91<p>Note that the local configuration must be setup prior to <strong>setup.py</strong> being run.
92The local configuration will determine how the script sets up the database,
93particularly with regard to desktop vs. server mode.</p>
94</section>
95</section>
96<section id="pgadmin-core">
97<h2>pgAdmin Core<a class="headerlink" href="#pgadmin-core" title="Link to this heading">¶</a></h2>
98<p>The heart of pgAdmin is the <strong>pgadmin</strong> package. This contains the globally
99available HTML templates used by the Jinja engine, as well as any global static
100files such as images, Javascript and CSS files that are used in multiple modules.</p>
101<p>The work of the package is handled in it’s constructor, <strong>__init__.py</strong>. This
102is responsible for setting up logging and authentication, dynamically loading
103other modules, and a few other tasks.</p>
104</section>
105<section id="modules">
106<h2>Modules<a class="headerlink" href="#modules" title="Link to this heading">¶</a></h2>
107<p>Units of functionality are added to pgAdmin through the addition of modules.
108Theses are Python object instance of classes, inherits the
109PgAdminModule class (a Flask Blueprint implementation), found in
110<strong>web/pgadmin/utils.py</strong>. It provide various hook points for other modules
111to utilise (primarily the default module - the browser).</p>
112<p>To be recognised as a module, a Python package must be created. This must:</p>
113<ol class="arabic simple">
114<li><p>Be placed within the <strong>web/pgadmin/</strong> directory, and</p></li>
115<li><p>Implements pgadmin.utils.PgAdminModule class</p></li>
116<li><p>An instance variable (generally - named <strong>blueprint</strong>) representing that
117particular class in that package.</p></li>
118</ol>
119<p>Each module may define a <strong>template</strong> and <strong>static</strong> directory for the Blueprint
120that it implements. To avoid name collisions, templates should be stored under
121a directory within the specified template directory, named after the module itself.
122For example, the <strong>browser</strong> module stores it’s templates in
123<strong>web/pgadmin/browser/templates/browser/</strong>. This does not apply to static files
124which may omit the second module name.</p>
125<p>In addition to defining the Blueprint, the <strong>views</strong> module is typically
126responsible for defining all the views that will be rendered in response to
127client requests, we must provide a REST API url(s) for these views. These must
128include appropriate route and security decorators. Take a look at the NodeView
129class, which uses the same approach as Flask’s MethodView, it can be found in
130<strong>web/pgadmin/browser/utils.py</strong>. This specific class is used by browser nodes
131for creating REST API url(s) for different operation on them. i.e. list, create,
132update, delete, fetch children, get
133statistics/reversed SQL/dependencies/dependents list for that node, etc. We can
134use the same class for other purpose too. You just need to inherit that class,
135and overload the member variables operations, parent_ids, ids, node_type, and
136then register it as node view with PgAdminModule instance.</p>
137<p>Most pgAdmin modules will also implement the <strong>hooks</strong> provided by the
138PgAdminModule class. This is responsible for providing hook points to integrate
139the module into the rest of the application - for example, a hook might tell
140the caller what CSS files need to be included on the rendered page, or what menu
141options to include and what they should do. Hook points need not exist if they
142are not required. It is the responsibility of the caller to ensure they are
143present before attempting to utilise them.</p>
144<p>Hooks currently implemented are:</p>
145<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyModule</span><span class="p">(</span><span class="n">PgAdminModule</span><span class="p">):</span>
146<span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
147<span class="sd">    This is class implements the pgadmin.utils.PgAdminModule, and</span>
148<span class="sd">    implements the hooks</span>
149<span class="sd">    &quot;&quot;&quot;</span>
150
151    <span class="o">...</span>
152
153    <span class="k">def</span> <span class="nf">get_own_stylesheets</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
154<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
155<span class="sd">        Returns:</span>
156<span class="sd">            list: the stylesheets used by this module, not including any</span>
157<span class="sd">                  stylesheet needed by the submodules.</span>
158<span class="sd">        &quot;&quot;&quot;</span>
159        <span class="k">return</span> <span class="p">[</span><span class="n">url_for</span><span class="p">(</span><span class="s1">&#39;static&#39;</span><span class="p">,</span> <span class="s1">&#39;css/mymodule.css&#39;</span><span class="p">)]</span>
160
161    <span class="k">def</span> <span class="nf">get_own_javascripts</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
162<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
163<span class="sd">        Returns:</span>
164<span class="sd">            list of dict:</span>
165<span class="sd">            - contains the name (representation for this javascript</span>
166<span class="sd">              module), path (url for it without .js suffix), deps (array of</span>
167<span class="sd">              dependents), exports window object by the javascript module,</span>
168<span class="sd">              and when (would you like to load this javascript), etc</span>
169<span class="sd">              information for this module, not including any script needed</span>
170<span class="sd">              by submodules.</span>
171<span class="sd">        &quot;&quot;&quot;</span>
172        <span class="k">return</span> <span class="p">[</span>
173            <span class="p">{</span>
174                <span class="s1">&#39;name&#39;</span><span class="p">:</span> <span class="s1">&#39;pgadmin.extension.mymodule&#39;</span><span class="p">,</span>
175                <span class="s1">&#39;path&#39;</span><span class="p">:</span> <span class="n">url_for</span><span class="p">(</span><span class="s1">&#39;static&#39;</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s1">&#39;js/mymodule&#39;</span><span class="p">),</span>
176                <span class="s1">&#39;exports&#39;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
177                <span class="s1">&#39;when&#39;</span><span class="p">:</span> <span class="s1">&#39;server&#39;</span>
178                <span class="p">}</span>
179            <span class="p">]</span>
180
181    <span class="k">def</span> <span class="nf">get_own_menuitems</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
182<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
183<span class="sd">        Returns:</span>
184<span class="sd">            dict: the menuitems for this module, not including</span>
185<span class="sd">                  any needed from the submodules.</span>
186<span class="sd">        &quot;&quot;&quot;</span>
187        <span class="k">return</span> <span class="p">{</span>
188            <span class="s1">&#39;help_items&#39;</span><span class="p">:</span> <span class="p">[</span>
189                <span class="n">MenuItem</span><span class="p">(</span>
190                    <span class="n">name</span><span class="o">=</span><span class="s1">&#39;mnu_mymodule_help&#39;</span><span class="p">,</span>
191                    <span class="n">priority</span><span class="o">=</span><span class="mi">999</span><span class="p">,</span>
192                    <span class="c1"># We need to create javascript, which registers itself</span>
193                    <span class="c1"># as module</span>
194                    <span class="n">module</span><span class="o">=</span><span class="s2">&quot;pgAdmin.MyModule&quot;</span><span class="p">,</span>
195                    <span class="n">callback</span><span class="o">=</span><span class="s1">&#39;about_show&#39;</span><span class="p">,</span>
196                    <span class="n">icon</span><span class="o">=</span><span class="s1">&#39;fa fa-info-circle&#39;</span><span class="p">,</span>
197                    <span class="n">label</span><span class="o">=</span><span class="n">gettext</span><span class="p">(</span><span class="s1">&#39;About MyModule&#39;</span>
198                    <span class="p">)</span>
199                <span class="p">]</span>
200            <span class="p">}</span>
201    <span class="k">def</span> <span class="nf">get_panels</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
202<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
203<span class="sd">        Returns:</span>
204<span class="sd">            list: a list of panel objects to add implemented in javascript</span>
205<span class="sd">                  module</span>
206<span class="sd">        &quot;&quot;&quot;</span>
207        <span class="k">return</span> <span class="p">[]</span>
208    <span class="o">...</span>
209
210
211
212<span class="n">blueprint</span> <span class="o">=</span> <span class="n">MyModule</span><span class="p">(</span><span class="s1">&#39;mymodule&#39;</span><span class="p">,</span> <span class="vm">__name__</span><span class="p">,</span> <span class="n">static_url_path</span><span class="o">=</span><span class="s1">&#39;/static&#39;</span><span class="p">)</span>
213</pre></div>
214</div>
215<p>pgAdmin Modules may include any additional Python modules that are required to
216fulfill their purpose, as required. They may also reference other dynamically
217loaded modules, but must use the defined hook points and fail gracefully in the
218event that a particular module is not present.</p>
219</section>
220<section id="nodes">
221<h2>Nodes<a class="headerlink" href="#nodes" title="Link to this heading">¶</a></h2>
222<p>Nodes are very similar to modules, it represents an individual node or,
223collection object on the object explorer treeview. To recognised as a node module, a
224Python package (along with javascript modules) must be created. This must:</p>
225<ol class="arabic simple">
226<li><p>Be placed within the <strong>web/pgadmin/browser/</strong> directory, and</p></li>
227<li><p>Implements the BrowserPluginModule, and registers the node view, which
228exposes required the REST APIs</p></li>
229<li><p>An instance of the class object</p></li>
230</ol>
231</section>
232<section id="front-end">
233<h2>Front End<a class="headerlink" href="#front-end" title="Link to this heading">¶</a></h2>
234<p>pgAdmin uses javascript extensively for the front-end implementation. It uses
235require.js to allow the lazy loading (or, say load only when required),
236ReactJS with CSS and MaterialUI for UI look and feel. We have
237divided each module in small chunks as much as possible. Not all javascript
238modules are required to be loaded (i.e. loading a javascript module for
239database will make sense only when a server node is loaded completely.) Please
240look at the javascript files node.js, browser.js, menu.js, panel.js, etc for
241better understanding of the code.</p>
242</section>
243</section>
244
245
246            <div class="clearer"></div>
247          </div>
248        </div>
249      </div>
250      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
251        <div class="sphinxsidebarwrapper">
252  <div>
253    <h3><a href="index.html">Table of Contents</a></h3>
254    <ul>
255<li><a class="reference internal" href="#">Code Overview</a><ul>
256<li><a class="reference internal" href="#runtime">Runtime</a></li>
257<li><a class="reference internal" href="#web-application">Web Application</a><ul>
258<li><a class="reference internal" href="#configuration">Configuration</a></li>
259<li><a class="reference internal" href="#user-settings">User Settings</a></li>
260</ul>
261</li>
262<li><a class="reference internal" href="#pgadmin-core">pgAdmin Core</a></li>
263<li><a class="reference internal" href="#modules">Modules</a></li>
264<li><a class="reference internal" href="#nodes">Nodes</a></li>
265<li><a class="reference internal" href="#front-end">Front End</a></li>
266</ul>
267</li>
268</ul>
269
270  </div>
271<h3><a href="index.html">Table of Contents</a></h3>
272<ul class="current">
273<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting Started</a></li>
274<li class="toctree-l1"><a class="reference internal" href="external_database.html">External database for pgAdmin user settings</a></li>
275<li class="toctree-l1"><a class="reference internal" href="connecting.html">Connecting To A Server</a></li>
276<li class="toctree-l1"><a class="reference internal" href="managing_cluster_objects.html">Managing Cluster Objects</a></li>
277<li class="toctree-l1"><a class="reference internal" href="managing_database_objects.html">Managing Database Objects</a></li>
278<li class="toctree-l1"><a class="reference internal" href="modifying_tables.html">Creating or Modifying a Table</a></li>
279<li class="toctree-l1"><a class="reference internal" href="management_basics.html">Management Basics</a></li>
280<li class="toctree-l1"><a class="reference internal" href="backup_and_restore.html">Backup and Restore</a></li>
281<li class="toctree-l1"><a class="reference internal" href="developer_tools.html">Developer Tools</a></li>
282<li class="toctree-l1"><a class="reference internal" href="processes.html">Processes</a></li>
283<li class="toctree-l1"><a class="reference internal" href="pgagent.html">pgAgent</a></li>
284<li class="toctree-l1 current"><a class="reference internal" href="contributions.html">pgAdmin Project Contributions</a><ul class="current">
285<li class="toctree-l2"><a class="reference internal" href="submitting_pull_requests.html">Submitting Pull Requests</a></li>
286<li class="toctree-l2 current"><a class="current reference internal" href="#">Code Overview</a></li>
287<li class="toctree-l2"><a class="reference internal" href="coding_standards.html">Coding Standards</a></li>
288<li class="toctree-l2"><a class="reference internal" href="code_snippets.html">Code Snippets</a></li>
289<li class="toctree-l2"><a class="reference internal" href="code_review.html">Code Review Notes</a></li>
290<li class="toctree-l2"><a class="reference internal" href="translations.html">Translations</a></li>
291</ul>
292</li>
293<li class="toctree-l1"><a class="reference internal" href="release_notes.html">Release Notes</a></li>
294<li class="toctree-l1"><a class="reference internal" href="licence.html">Licence</a></li>
295</ul>
296
297<search id="searchbox" style="display: none" role="search">
298  <h3 id="searchlabel">Quick search</h3>
299    <div class="searchformwrapper">
300    <form class="search" action="search.html" method="get">
301      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
302      <input type="submit" value="Go" />
303    </form>
304    </div>
305</search>
306<script>document.getElementById('searchbox').style.display = "block"</script>
307        </div>
308<div id="sidebarbutton" title="Collapse sidebar">
309<span>«</span>
310</div>
311
312      </div>
313      <div class="clearer"></div>
314    </div>
315    <div class="related" role="navigation" aria-label="related navigation">
316      <h3>Navigation</h3>
317      <ul>
318        <li class="right" style="margin-right: 10px">
319          <a href="genindex.html" title="General Index"
320             >index</a></li>
321        <li class="right" >
322          <a href="coding_standards.html" title="Coding Standards"
323             >next</a> |</li>
324        <li class="right" >
325          <a href="submitting_pull_requests.html" title="Submitting Pull Requests"
326             >previous</a> |</li>
327        <li class="nav-item nav-item-0"><a href="index.html">pgAdmin 4 8.6 documentation</a> &#187;</li>
328          <li class="nav-item nav-item-1"><a href="contributions.html" >pgAdmin Project Contributions</a> &#187;</li>
329        <li class="nav-item nav-item-this"><a href="">Code Overview</a></li> 
330      </ul>
331    </div>
332    <div class="footer" role="contentinfo">
333        <div class="related" role="navigation" aria-label="related navigation">
334          <ul>
335              <li class="left" style="margin-left: 10px">&#169; Copyright (C) 2013 - 2024, The pgAdmin Development Team.</li>
336            <li class="right" style="margin-right: 10px"><a href="genindex.html" title="General Index" accesskey="I">index</a></li>
337            <li class="right" ><a href="coding_standards.html" title="Coding Standards" accesskey="N">next</a> |</li>
338            <li class="right" ><a href="submitting_pull_requests.html" title="Submitting Pull Requests" accesskey="P">previous</a> |</li>
339          </ul>
340        </div>
341    </div>
342  </body>
343</html>
codekingpro/portable-devtools · Team Ai