/usr/share/doc/python-cement-doc/html/dev/configuration.html is in python-cement-doc 2.10.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 | <!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Configuration Handling — Cement 2.10.0 documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="top" title="Cement 2.10.0 documentation" href="../index.html"/>
<link rel="up" title="Developer Documentation" href="index.html"/>
<link rel="next" title="Argument and Option Handling" href="arguments.html"/>
<link rel="prev" title="Interfaces and Handlers" href="interfaces_and_handlers.html"/>
<script src="../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="../index.html" class="icon icon-home"> Cement
</a>
<div class="version">
2.10
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../changes.html">ChangeLog</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributors.html">Contributors</a></li>
<li class="toctree-l1"><a class="reference internal" href="../upgrading.html">Upgrading</a></li>
<li class="toctree-l1"><a class="reference internal" href="../whats_new.html">What’s New</a></li>
<li class="toctree-l1"><a class="reference internal" href="../projects_built_on_cement.html">Projects Built on Cement™</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq.html">Frequenty Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../api/index.html">API Reference</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="quickstart.html">Quick Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="interfaces_and_handlers.html">Interfaces and Handlers</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Configuration Handling</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#configuration-ordering">Configuration Ordering</a></li>
<li class="toctree-l3"><a class="reference internal" href="#application-default-settings">Application Default Settings</a></li>
<li class="toctree-l3"><a class="reference internal" href="#built-in-defaults">Built-in Defaults</a></li>
<li class="toctree-l3"><a class="reference internal" href="#application-configuration-defaults-vs-handler-configuration-defaults">Application Configuration Defaults vs Handler Configuration Defaults</a></li>
<li class="toctree-l3"><a class="reference internal" href="#accessing-configuration-settings">Accessing Configuration Settings</a></li>
<li class="toctree-l3"><a class="reference internal" href="#parsing-config-files">Parsing Config Files</a></li>
<li class="toctree-l3"><a class="reference internal" href="#overriding-configurations-with-command-line-options">Overriding Configurations with Command Line Options</a></li>
<li class="toctree-l3"><a class="reference internal" href="#configuration-options-versus-meta-options">Configuration Options Versus Meta Options</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="arguments.html">Argument and Option Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="logging.html">Log Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="output.html">Output Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="controllers.html">Application Controllers</a></li>
<li class="toctree-l2"><a class="reference internal" href="extensions.html">Framework Extensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="plugins.html">Application Plugins</a></li>
<li class="toctree-l2"><a class="reference internal" href="hooks.html">Framework and Application Hooks</a></li>
<li class="toctree-l2"><a class="reference internal" href="extending_cementapp.html">Extending CementApp</a></li>
<li class="toctree-l2"><a class="reference internal" href="signal_handling.html">Signal Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="cleanup.html">Application Cleanup</a></li>
<li class="toctree-l2"><a class="reference internal" href="caching.html">Caching</a></li>
<li class="toctree-l2"><a class="reference internal" href="mail.html">Sending Email Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="testing.html">Unit Testing Your Application</a></li>
<li class="toctree-l2"><a class="reference internal" href="application_design.html">Application Design</a></li>
<li class="toctree-l2"><a class="reference internal" href="boss_templates.html">Starting Projects from Boss Templates</a></li>
<li class="toctree-l2"><a class="reference internal" href="contributing.html">Contributing</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../examples/index.html">Examples</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Cement</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li><a href="index.html">Developer Documentation</a> »</li>
<li>Configuration Handling</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/dev/configuration.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="configuration-handling">
<h1>Configuration Handling<a class="headerlink" href="#configuration-handling" title="Permalink to this headline">¶</a></h1>
<p>Cement defines a configuration interface called
<a class="reference internal" href="../api/core/config.html#cement-core-config"><span class="std std-ref">IConfig</span></a>, as well as the default
<a class="reference internal" href="../api/ext/ext_configparser.html#cement-ext-ext-configparser"><span class="std std-ref">ConfigParserConfigHandler</span></a> that implements
the interface. This handler is built on top of <a class="reference external" href="http://docs.python.org/library/configparser.html">ConfigParser</a> which is included in the
Python standard library. Therefor, this class will work much like
ConfigParser but with any added functions necessary to meet the requirements
of the <code class="docutils literal"><span class="pre">IConfig</span></code> interface.</p>
<p>Please note that there are other handlers that implement the <code class="docutils literal"><span class="pre">IConfig</span></code>
interface. The documentation below only references usage based on the
interface and not the full capabilities of the implementation.</p>
<p>The following config handlers are included and maintained with Cement:</p>
<blockquote>
<div><ul class="simple">
<li><a class="reference internal" href="../api/ext/ext_configparser.html#cement-ext-ext-configparser"><span class="std std-ref">ConfigParserConfigHandler</span></a> (default)</li>
<li><a class="reference internal" href="../api/ext/ext_configobj.html#cement-ext-ext-configobj"><span class="std std-ref">ConfigObjConfigHandler</span></a></li>
<li><a class="reference internal" href="../api/ext/ext_json.html#cement-ext-ext-json"><span class="std std-ref">JsonConfigHandler</span></a></li>
<li><a class="reference internal" href="../api/ext/ext_json_configobj.html#cement-ext-ext-json-configobj"><span class="std std-ref">JsonConfigObjConfigHandler</span></a></li>
<li><a class="reference internal" href="../api/ext/ext_yaml.html#cement-ext-ext-yaml"><span class="std std-ref">YamlConfigHandler</span></a></li>
<li><a class="reference internal" href="../api/ext/ext_yaml_configobj.html#cement-ext-ext-yaml-configobj"><span class="std std-ref">YamlConfigObjHandler</span></a></li>
</ul>
</div></blockquote>
<p>Please reference the <a class="reference internal" href="../api/core/config.html#cement-core-config"><span class="std std-ref">IConfig</span></a> interface
documentation for writing your own config handler.</p>
<div class="section" id="configuration-ordering">
<h2>Configuration Ordering<a class="headerlink" href="#configuration-ordering" title="Permalink to this headline">¶</a></h2>
<p>An applications configuration is made up of a number of things, including
default settings, handler defaults, config file settings, etc. The following
is the order in which configurations are discovered and loaded:</p>
<blockquote>
<div><ul class="simple">
<li>Defaults defined in <code class="docutils literal"><span class="pre">CementApp.Meta.config_defaults</span></code> or passed as
<code class="docutils literal"><span class="pre">config_defaults</span></code> keyword to <code class="docutils literal"><span class="pre">CementApp</span></code></li>
<li>Extended by <code class="docutils literal"><span class="pre">CementBaseHandler.Meta.config_defaults</span></code> (not overridden)</li>
<li>Overridden by configuration files defined in
<code class="docutils literal"><span class="pre">CementApp.Meta.config_files</span></code> in the order they are listed/loaded
(last has precedence)</li>
<li>Overridden by command line options that match the same key name (only
if <code class="docutils literal"><span class="pre">CementApp.Meta.arguments_override_config</span> <span class="pre">==</span> <span class="pre">True</span></code> or if the
argument name is listed in <code class="docutils literal"><span class="pre">CementApp.Meta.override_arguments</span></code>)</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="application-default-settings">
<h2>Application Default Settings<a class="headerlink" href="#application-default-settings" title="Permalink to this headline">¶</a></h2>
<p>Cement does not require default config settings in order to operate. That
said, these settings are found under the <code class="docutils literal"><span class="pre">app_label</span></code> application section
of the configuration, and overridden by a <code class="docutils literal"><span class="pre">[<app_label>]</span></code> block from a
configuration file.</p>
<p>A default dictionary is used if no other defaults are passed when creating an
application. For example, the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cement.core</span> <span class="kn">import</span> <span class="n">foundation</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">foundation</span><span class="o">.</span><span class="n">CementApp</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">)</span>
</pre></div>
</div>
<p>Is equivalent to:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cement.core</span> <span class="kn">import</span> <span class="n">foundation</span>
<span class="kn">from</span> <span class="nn">cement.utils.misc</span> <span class="kn">import</span> <span class="n">init_defaults</span>
<span class="n">defaults</span> <span class="o">=</span> <span class="n">init_defaults</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">)</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">foundation</span><span class="o">.</span><span class="n">CementApp</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">,</span> <span class="n">config_defaults</span><span class="o">=</span><span class="n">defaults</span><span class="p">)</span>
</pre></div>
</div>
<p>That said, you can override default settings or add your own defaults like
so:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cement.core</span> <span class="kn">import</span> <span class="n">foundation</span>
<span class="kn">from</span> <span class="nn">cement.utils.misc</span> <span class="kn">import</span> <span class="n">init_defaults</span>
<span class="n">defaults</span> <span class="o">=</span> <span class="n">init_defaults</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">,</span> <span class="s1">'section1'</span><span class="p">,</span><span class="s1">'section2'</span><span class="p">)</span>
<span class="n">defaults</span><span class="p">[</span><span class="s1">'section1'</span><span class="p">][</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'bar'</span>
<span class="n">defaults</span><span class="p">[</span><span class="s1">'section2'</span><span class="p">][</span><span class="s1">'foo2'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'bar2'</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">foundation</span><span class="o">.</span><span class="n">CementApp</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">,</span> <span class="n">config_defaults</span><span class="o">=</span><span class="n">defaults</span><span class="p">)</span>
</pre></div>
</div>
<p>It is important to note that the default settings, which is a dict, is parsed
by the config handler and loaded into it’s own configuration mechanism.
Meaning, though some config handlers (i.e. <code class="docutils literal"><span class="pre">ConfigObjConfigHandler</span></code>) might
also be accessible like a dict, not all do (i.e.
<code class="docutils literal"><span class="pre">ConfigParserConfigHandler</span></code>). Please see the documentation for the config
handler you use for their full usage when accessing the <code class="docutils literal"><span class="pre">app.config</span></code> object.</p>
</div>
<div class="section" id="built-in-defaults">
<h2>Built-in Defaults<a class="headerlink" href="#built-in-defaults" title="Permalink to this headline">¶</a></h2>
<p>The following are not required to exist in the config defaults, however if
they do, Cement will honor them (overriding or appending to built-in
defaults).</p>
<blockquote>
<div><dl class="docutils">
<dt>debug = <code class="docutils literal"><span class="pre">False</span></code></dt>
<dd>Toggles debug output. By default, this setting is also overridden
by the <code class="docutils literal"><span class="pre">[<app_label>]</span> <span class="pre">-></span> <span class="pre">debug</span></code> config setting parsed in any
of the application configuration files.</dd>
<dt>ignore_deprecation_warnings = <code class="docutils literal"><span class="pre">False</span></code></dt>
<dd>Disable deprecation warnings from being logged by Cement.</dd>
<dt>extensions = <code class="docutils literal"><span class="pre">None</span></code></dt>
<dd>List of additional framework extensions to load. Any extensions
defined here will be appended to the application’s defined extensions.</dd>
<dt>plugin_config_dir = <code class="docutils literal"><span class="pre">None</span></code></dt>
<dd><p class="first">A directory path where plugin config files can be found. Files
must end in <code class="docutils literal"><span class="pre">.conf</span></code>. By default, this setting is also overridden
by the <code class="docutils literal"><span class="pre">[<app_label>]</span> <span class="pre">-></span> <span class="pre">plugin_config_dir</span></code> config setting parsed in
any of the application configuration files.</p>
<p>If set, this item will be <strong>appended</strong> to
<code class="docutils literal"><span class="pre">CementApp.Meta.plugin_config_dirs</span></code> so that it’s settings will have
presedence over other config files.</p>
<p class="last">In general, this setting should not be defined by the developer, as it
is primarily used to allow the end-user to define a
<code class="docutils literal"><span class="pre">plugin_config_dir</span></code> without completely trumping the hard-coded list
of default <code class="docutils literal"><span class="pre">plugin_config_dirs</span></code> defined by the app/developer.</p>
</dd>
<dt>plugin_dir = <code class="docutils literal"><span class="pre">None</span></code></dt>
<dd><p class="first">A directory path where plugin code (modules) can be loaded from.
By default, this setting is also overridden by the
<code class="docutils literal"><span class="pre">[<app_label>]</span> <span class="pre">-></span> <span class="pre">plugin_dir</span></code> config setting parsed in any of the
application configuration files.</p>
<p>If set, this item will be <strong>prepended</strong> to
<code class="docutils literal"><span class="pre">CementApp.Meta.plugin_dirs</span></code> so that a user’s defined <code class="docutils literal"><span class="pre">plugin_dir</span></code>
has precedence over other <code class="docutils literal"><span class="pre">plugin_dirs</span></code>.</p>
<p class="last">In general, this setting should not be defined by the developer, as it
is primarily used to allow the end-user to define a
<code class="docutils literal"><span class="pre">plugin_dir</span></code> without completely trumping the hard-coded list
of default <code class="docutils literal"><span class="pre">plugin_dirs</span></code> defined by the app/developer.</p>
</dd>
<dt>template_dir = <code class="docutils literal"><span class="pre">None</span></code></dt>
<dd><p class="first">A directory path where template files can be loaded from. By default,
this setting is also overridden by the
<code class="docutils literal"><span class="pre">[<app_label>]</span> <span class="pre">-></span> <span class="pre">template_dir</span></code> config setting parsed in any of the
application configuration files.</p>
<p>If set, this item will be appended to
<code class="docutils literal"><span class="pre">CementApp.Meta.template_dirs</span></code>.</p>
<p class="last">In general, this setting should not be defined by the developer, as it
is primarily used to allow the end-user to define a <code class="docutils literal"><span class="pre">template_dir</span></code>
without completely trumping the hard-coded list of default
<code class="docutils literal"><span class="pre">template_dirs</span></code> defined by the app/developer.</p>
</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="application-configuration-defaults-vs-handler-configuration-defaults">
<h2>Application Configuration Defaults vs Handler Configuration Defaults<a class="headerlink" href="#application-configuration-defaults-vs-handler-configuration-defaults" title="Permalink to this headline">¶</a></h2>
<p>There may be slight confusion between the <code class="docutils literal"><span class="pre">CementApp.Meta.config_defaults</span></code>
and the <code class="docutils literal"><span class="pre">CementBaseHandler.Meta.config_defaults</span></code> options. They both are
very similar, however the application level configuration defaults are
intended to be used to set defaults for multiple sections. Therefore, the
<code class="docutils literal"><span class="pre">CementApp.Meta.config_defaults</span></code> option is a <code class="docutils literal"><span class="pre">dict</span></code> with nested
<code class="docutils literal"><span class="pre">dict</span></code>‘s under it. Each key of the top level <code class="docutils literal"><span class="pre">dict</span></code> relates to a config
<code class="docutils literal"><span class="pre">[section]</span></code> and the nested <code class="docutils literal"><span class="pre">dict</span></code> are the settings for that <code class="docutils literal"><span class="pre">[section]</span></code>.</p>
<p>The <code class="docutils literal"><span class="pre">CementBaseHandler.Meta.config_defaults</span></code> only partain to a single
<code class="docutils literal"><span class="pre">[section]</span></code> and therefor is only a single level <code class="docutils literal"><span class="pre">dict</span></code>, whose settings are
applied to the <code class="docutils literal"><span class="pre">CementBaseHandler.Meta.config_section</span></code> of the application’s
configuration.</p>
</div>
<div class="section" id="accessing-configuration-settings">
<h2>Accessing Configuration Settings<a class="headerlink" href="#accessing-configuration-settings" title="Permalink to this headline">¶</a></h2>
<p>After application creation and setup, you can access the config handler via
the <code class="docutils literal"><span class="pre">app.config</span></code> object. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cement.core</span> <span class="kn">import</span> <span class="n">foundation</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">foundation</span><span class="o">.</span><span class="n">CementApp</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">)</span>
<span class="c1"># First setup the application</span>
<span class="n">app</span><span class="o">.</span><span class="n">setup</span><span class="p">()</span>
<span class="c1"># Get settings</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">,</span> <span class="s1">'debug'</span><span class="p">)</span>
<span class="c1"># Set settings</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">,</span> <span class="s1">'debug'</span><span class="p">,</span> <span class="bp">True</span><span class="p">)</span>
<span class="c1"># Get sections (configuration [blocks])</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">get_sections</span><span class="p">()</span>
<span class="c1"># Add a section</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">add_section</span><span class="p">(</span><span class="s1">'my_config_section'</span><span class="p">)</span>
<span class="c1"># Test if a section exists</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">has_section</span><span class="p">(</span><span class="s1">'my_config_section'</span><span class="p">)</span>
<span class="c1"># Get configuration keys for the 'myapp' section</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">keys</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">)</span>
<span class="c1"># Test if a key exist</span>
<span class="k">if</span> <span class="s1">'debug'</span> <span class="ow">in</span> <span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">keys</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">)</span>
<span class="c1"># Merge a dict of settings into the config</span>
<span class="n">other_config</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">()</span>
<span class="n">other_config</span><span class="p">[</span><span class="s1">'myapp'</span><span class="p">]</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">()</span>
<span class="n">other_config</span><span class="p">[</span><span class="s1">'myapp'</span><span class="p">][</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'not bar'</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">other_config</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="parsing-config-files">
<h2>Parsing Config Files<a class="headerlink" href="#parsing-config-files" title="Permalink to this headline">¶</a></h2>
<p>Most applications benefit from allowing their users to customize runtime via
a configuration file. This can be done by:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cement.core</span> <span class="kn">import</span> <span class="n">foundation</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">foundation</span><span class="o">.</span><span class="n">CementApp</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">)</span>
<span class="c1"># First setup the application</span>
<span class="n">app</span><span class="o">.</span><span class="n">setup</span><span class="p">()</span>
<span class="c1"># Parse a configuration file</span>
<span class="n">app</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">parse_file</span><span class="p">(</span><span class="s1">'/path/to/some/file.conf'</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that Cement automatically parses any config files listed in the
<code class="docutils literal"><span class="pre">CementApp.Meta.config_files</span></code> list. For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cement.core</span> <span class="kn">import</span> <span class="n">foundation</span><span class="p">,</span> <span class="n">backend</span>
<span class="n">app</span> <span class="o">=</span> <span class="n">foundation</span><span class="o">.</span><span class="n">CementApp</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">,</span>
<span class="n">config_files</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">'/path/to/config1'</span><span class="p">,</span>
<span class="s1">'/path/to/config2'</span>
<span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>If no <code class="docutils literal"><span class="pre">config_files</span></code> meta is provided, Cement will set the defaults to the
following common and sane defaults:</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal"><span class="pre">/etc/<app_label>/<app_label>.conf</span></code></li>
<li><code class="docutils literal"><span class="pre">~/.<app_label>.conf</span></code></li>
<li><code class="docutils literal"><span class="pre">~/.<app_label>/config</span></code></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="overriding-configurations-with-command-line-options">
<h2>Overriding Configurations with Command Line Options<a class="headerlink" href="#overriding-configurations-with-command-line-options" title="Permalink to this headline">¶</a></h2>
<p>Config settings can <strong>optionally</strong> overridden by a passed command line
option if the option name matches a configuration key. Note that this will
happen in <em>all</em> config sections if enabled:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">cement.core.foundation</span> <span class="kn">import</span> <span class="n">CementApp</span>
<span class="kn">from</span> <span class="nn">cement.utils.misc</span> <span class="kn">import</span> <span class="n">init_defaults</span>
<span class="n">defaults</span> <span class="o">=</span> <span class="n">init_defaults</span><span class="p">(</span><span class="s1">'myapp'</span><span class="p">)</span>
<span class="n">defaults</span><span class="p">[</span><span class="s1">'myapp'</span><span class="p">][</span><span class="s1">'foo'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'bar'</span>
<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">CementApp</span><span class="p">):</span>
<span class="k">class</span> <span class="nc">Meta</span><span class="p">:</span>
<span class="n">label</span> <span class="o">=</span> <span class="s1">'myapp'</span>
<span class="n">config_defaults</span> <span class="o">=</span> <span class="n">defaults</span>
<span class="n">arguments_override_config</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">with</span> <span class="n">MyApp</span><span class="p">()</span> <span class="k">as</span> <span class="n">app</span><span class="p">:</span>
<span class="n">app</span><span class="o">.</span><span class="n">args</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'--foo'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">)</span>
<span class="n">app</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>With <code class="docutils literal"><span class="pre">arguments_override_config</span></code> enabled, running the above application and
passing the <code class="docutils literal"><span class="pre">--foo=some_value</span></code> option will override the <code class="docutils literal"><span class="pre">foo</span></code> setting
under a <code class="docutils literal"><span class="pre">[myapp]</span></code> configuration section as well as any other section that
has a matching <code class="docutils literal"><span class="pre">foo</span></code> key.</p>
</div>
<div class="section" id="configuration-options-versus-meta-options">
<h2>Configuration Options Versus Meta Options<a class="headerlink" href="#configuration-options-versus-meta-options" title="Permalink to this headline">¶</a></h2>
<p>As you will see extensively throughout the Cement code is the use of Meta
options. There can be some confusion between the use of Meta options, and
application configuration options. The following explains the two:</p>
<p><strong>Configuration Options</strong></p>
<p>Configuration options are application specific. There are config defaults
defined by the application developer, that can be (and are intended to be)
overridden by user defined settings in a configuration file.</p>
<p>Cement does not rely on the application configuration, though it can honor
configuration settings. For example, <code class="docutils literal"><span class="pre">CementApp</span></code> honors the <code class="docutils literal"><span class="pre">debug</span></code>
config option which is documented, but it doesn’t rely on it existing either.</p>
<p>The key things to note about configuration options are:</p>
<blockquote>
<div><ul class="simple">
<li>They give the end user flexibility in how the application operates.</li>
<li>Anything that you want users to be able to customize via a config file.
For example, the path to a log file or the location of a database
server. These are things that you do not want hard-coded into your
app, but rather might want sane defaults for.</li>
</ul>
</div></blockquote>
<p><strong>Meta Options</strong></p>
<p>Meta options are used on the backend by developers to alter how classes
operate. For example, the <code class="docutils literal"><span class="pre">CementApp</span></code> class has a meta option of
<code class="docutils literal"><span class="pre">log_handler</span></code>. The default log handler is <code class="docutils literal"><span class="pre">LoggingLogHandler</span></code>, however
because this is built on an interface definition, Cement can use any other log
handler the same way without issue as long as that log handler abides by the
interface definition. Meta options make this change seamless and allows the
handler to alter functionality, rather than having to change code in the top
level class itself.</p>
<p>The key thing to note about Meta options are:</p>
<blockquote>
<div><ul class="simple">
<li>They give the developer flexibility in how the code operates.</li>
<li>End users should not have access to modify Meta options via a config
file or similar ‘dynamic’ configuration (unless those specific options
are listed in <code class="docutils literal"><span class="pre">CementApp.Meta.core_meta_override</span></code> or
<code class="docutils literal"><span class="pre">CementApp.Meta.meta_override</span></code> (for example, the <code class="docutils literal"><span class="pre">debug</span></code> setting
under <code class="docutils literal"><span class="pre">[<app_label>]</span></code> overrides <code class="docutils literal"><span class="pre">CementApp.Meta.debug</span></code> by default.</li>
<li>Meta options are used to alter how classes work, however are considered
‘hard-coded’ settings. If the developer chooses to alter a Meta option,
it is for the life of that release.</li>
<li>Meta options should have a sane default, and be clearly documented.</li>
</ul>
</div></blockquote>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="arguments.html" class="btn btn-neutral float-right" title="Argument and Option Handling" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="interfaces_and_handlers.html" class="btn btn-neutral" title="Interfaces and Handlers" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2009-2016, Data Folk Labs, LLC.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2.10.0',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
|