| Server IP : 127.0.0.2 / Your IP : 18.222.48.95 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/docutils-doc/docs/api/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" /> <title>Docutils Runtime Settings</title> <meta name="author" content="David Goodger" /> <meta name="date" content="2012-01-03" /> <meta name="copyright" content="This document has been placed in the public domain." /> <link rel="stylesheet" href="../../css/html4css1.css" type="text/css" /> </head> <body> <div class="document" id="docutils-runtime-settings"> <h1 class="title">Docutils Runtime Settings</h1> <table class="docinfo" frame="void" rules="none"> <col class="docinfo-name" /> <col class="docinfo-content" /> <tbody valign="top"> <tr><th class="docinfo-name">Author:</th> <td>David Goodger</td></tr> <tr><th class="docinfo-name">Contact:</th> <td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr> <tr><th class="docinfo-name">Date:</th> <td>2012-01-03</td></tr> <tr><th class="docinfo-name">Revision:</th> <td>7302</td></tr> <tr><th class="docinfo-name">Copyright:</th> <td>This document has been placed in the public domain.</td></tr> </tbody> </table> <div class="contents topic" id="contents"> <p class="topic-title first">Contents</p> <ul class="simple"> <li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li> <li><a class="reference internal" href="#runtime-settings-processing-for-command-line-tools" id="id2">Runtime Settings Processing for Command-Line Tools</a></li> <li><a class="reference internal" href="#runtime-settings-processing-from-applications" id="id3">Runtime Settings Processing From Applications</a></li> </ul> </div> <div class="section" id="introduction"> <h1><a class="toc-backref" href="#id1">Introduction</a></h1> <p>Docutils runtime settings are assembled from several sources: component settings specifications, application settings specifications, configuration files, and command-line options. Docutils overlays default and explicitly specified values from these sources such that settings behave the way we want and expect them to behave.</p> <p>To understand how Docutils deals with runtime settings, the attributes and parameters involved must first be understood. Begin with the the docstrings of the attributes of the <tt class="docutils literal">docutils.SettingsSpec</tt> base class (in the <tt class="docutils literal">docutils/__init__.py</tt> module):</p> <ul class="simple"> <li><tt class="docutils literal">settings_spec</tt></li> <li><tt class="docutils literal">settings_defaults</tt></li> <li><tt class="docutils literal">settings_default_overrides</tt></li> <li><tt class="docutils literal">relative_path_settings</tt></li> <li><tt class="docutils literal">config_section</tt></li> <li><tt class="docutils literal">config_section_dependencies</tt></li> </ul> <p>Next, several <span class="target" id="convenience-function-parameters">convenience function parameters</span> are also significant (described in the <tt class="docutils literal">docutils.core.publish_programmatically</tt> function docstring):</p> <ul class="simple"> <li>The <tt class="docutils literal">settings</tt> parameter is a runtime settings (<tt class="docutils literal">docutils.frontend.Values</tt>) object which, if present, is assumed to be complete (it must include all runtime settings). Also, if the <tt class="docutils literal">settings</tt> parameter is present, no further runtime settings processing is done. In other words, the other parameters, described below, will have no effect.</li> <li><tt class="docutils literal">settings_spec</tt>, a <span class="incremental">docutils.SettingsSpec</span> subclass or object, is treated like a fourth component (after the Parser, Reader, and Writer). In other words, it's the settings specification for the "Application" itself.</li> <li><tt class="docutils literal">settings_overrides</tt> is a dictionary which will override the defaults of the components (from their settings specs).</li> <li><tt class="docutils literal">config_section</tt> specifies the name of an application-specific configuration file section.</li> </ul> </div> <div class="section" id="runtime-settings-processing-for-command-line-tools"> <span id="command-line-tools"></span><h1><a class="toc-backref" href="#id2">Runtime Settings Processing for Command-Line Tools</a></h1> <p>Following along with the actual code is recommended. The <tt class="docutils literal">docutils/__init__.py</tt>, <tt class="docutils literal">docutils/core.py</tt>, and <tt class="docutils literal">docutils.frontend.py</tt> modules are described.</p> <ol class="arabic"> <li><p class="first">A command-line front-end tool imports and calls <tt class="docutils literal">docutils.core.publish_cmdline</tt>. The relevant <a class="reference internal" href="#convenience-function-parameters">convenience function parameters</a> are described above.</p> </li> <li><p class="first"><tt class="docutils literal">docutils.core.publish_cmdline</tt> initializes a <tt class="docutils literal">docutils.core.Publisher</tt> object, then calls its <tt class="docutils literal">publish</tt> method.</p> </li> <li><p class="first">The <tt class="docutils literal">docutils.core.Publisher</tt> object's <tt class="docutils literal">publish</tt> method checks its <tt class="docutils literal">settings</tt> attribute to see if it's defined. If it is, no further runtime settings processing is done.</p> <p>If <tt class="docutils literal">settings</tt> is not defined, <tt class="docutils literal">self.process_command_line</tt> is called with the following relevant arguments:</p> <ul class="simple"> <li><tt class="docutils literal">settings_spec</tt></li> <li><tt class="docutils literal">config_section</tt></li> <li><tt class="docutils literal">settings_overrides</tt> (in the form of excess keyword arguments, collected in the <tt class="docutils literal">defaults</tt> parameter)</li> </ul> </li> <li><p class="first"><tt class="docutils literal">self.process_command_line</tt> calls <tt class="docutils literal">self.setup_option_parser</tt>, passing <tt class="docutils literal">settings_spec</tt>, <tt class="docutils literal">config_section</tt>, and <tt class="docutils literal">defaults</tt>.</p> </li> <li><p class="first"><tt class="docutils literal">self.setup_option_parser</tt> checks its <tt class="docutils literal">config_section</tt> parameter; if defined, it adds that config file section to <tt class="docutils literal">settings_spec</tt> (or to a new, empty <tt class="docutils literal">docutils.SettingsSpec</tt> object), replacing anything defined earlier. (See <a class="reference external" href="../user/config.html">Docutils Configuration Files</a> for details.) Then it instantiates a new <tt class="docutils literal">docutils.frontend.OptionParser</tt> object, passing the following relevant arguments:</p> <ul class="simple"> <li><tt class="docutils literal">components</tt>: A tuple of <tt class="docutils literal">docutils.SettingsSpec</tt> objects, <tt class="docutils literal">(self.parser, self.reader, self.writer, settings_spec)</tt></li> <li><tt class="docutils literal">defaults</tt> (originally from <tt class="docutils literal">settings_overrides</tt>)</li> </ul> </li> <li><p class="first">The <tt class="docutils literal">docutils.frontend.OptionParser</tt> object's <tt class="docutils literal">__init__</tt> method calls <tt class="docutils literal">self.populate_from_components</tt> with <tt class="docutils literal">self.components</tt>, which consists of <tt class="docutils literal">self</tt> prepended to the <tt class="docutils literal">components</tt> tuple it received. <tt class="docutils literal">self</tt> (<tt class="docutils literal">docutils.frontend.OptionParser</tt>) defines general Docutils settings.</p> </li> <li><p class="first">In <tt class="docutils literal">self.populate_from_components</tt>, for each component passed, <tt class="docutils literal">component.settings_spec</tt> is processed and <tt class="docutils literal">component.settings_defaults</tt> is applied. Then, for each component, <tt class="docutils literal">component.settings_default_overrides</tt> is applied. This two-loop process ensures that <tt class="docutils literal">component.settings_default_overrides</tt> can override the default settings of any other component.</p> </li> <li><p class="first">Back in <tt class="docutils literal">docutils.frontend.OptionParser.__init__</tt>, the <tt class="docutils literal">defaults</tt> parameter (derived from the <tt class="docutils literal">settings_overrides</tt> parameter of <tt class="docutils literal">docutils.core.Publisher.publish</tt>) is overlaid over <tt class="docutils literal">self.defaults</tt>. So <tt class="docutils literal">settings_overrides</tt> has priority over all <tt class="docutils literal">SettingsSpec</tt> data.</p> </li> <li><p class="first">Next, <tt class="docutils literal">docutils.frontend.OptionParser.__init__</tt> checks if configuration files are enabled (its <tt class="docutils literal">read_config_files</tt> parameter is true, and <tt class="docutils literal"><span class="pre">self.defaults['_disable_config']</span></tt> is false). If they are enabled (and normally, they are), <tt class="docutils literal">self.get_standard_config_settings</tt> is called. This reads the <a class="reference external" href="../user/config.html">docutils configuration files</a>, and returns a dictionary of settings. This is then overlaid on <tt class="docutils literal">self.defaults</tt>. So configuration file settings have priority over all software-defined defaults.</p> </li> <li><p class="first">Back in the <tt class="docutils literal">docutils.core.Publisher</tt> object, <tt class="docutils literal">self.setup_option_parser</tt> returns the <tt class="docutils literal">option_parser</tt> object to its caller, <tt class="docutils literal">self.process_command_line</tt>.</p> </li> <li><p class="first"><tt class="docutils literal">self.process_command_line</tt> calls <tt class="docutils literal">option_parser.parse_args</tt>, which parses all command line options and returns a <tt class="docutils literal">docutils.frontend.Values</tt> object. This is assigned to the <tt class="docutils literal">docutils.core.Publisher</tt> object's <tt class="docutils literal">self.settings</tt>. So command-line options have priority over configuration file settings.</p> <p>When <tt class="docutils literal">option_parser.parse_args</tt> is called, the source and destination command-line arguments are also parsed, and assigned to the <tt class="docutils literal">_source</tt> and <tt class="docutils literal">_destination</tt> attributes of what becomes the <tt class="docutils literal">docutils.core.Publisher</tt> object's <tt class="docutils literal">self.settings</tt>.</p> </li> <li><p class="first">From <tt class="docutils literal">docutils.core.Publisher.publish</tt>, <tt class="docutils literal">self.set_io</tt> is called with no arguments. If either <tt class="docutils literal">self.source</tt> or <tt class="docutils literal">self.destination</tt> are not set, the corresponding <tt class="docutils literal">self.set_source</tt> and <tt class="docutils literal">self.set_destination</tt> are called, effectively with no arguments.</p> </li> <li><p class="first"><tt class="docutils literal">self.set_source</tt> checks for a <tt class="docutils literal">source_path</tt> parameter, and if there is none (which is the case for command-line use), it is taken from <tt class="docutils literal">self.settings._source</tt>. <tt class="docutils literal">self.source</tt> is set by instantiating a <tt class="docutils literal">self.source_class</tt> object. For command-line front-end tools, the default <tt class="docutils literal">self.source_class</tt> is used, <tt class="docutils literal">docutils.io.FileInput</tt>.</p> </li> <li><p class="first"><tt class="docutils literal">self.set_destination</tt> does the same job for the destination that <tt class="docutils literal">self.set_source</tt> does for the source (the default <tt class="docutils literal">self.destination_class</tt> is <tt class="docutils literal">docutils.io.FileOutput</tt>).</p> </li> </ol> </div> <div class="section" id="runtime-settings-processing-from-applications"> <h1><a class="toc-backref" href="#id3">Runtime Settings Processing From Applications</a></h1> <p>Applications process runtime settings in a different way than <a class="reference internal" href="#command-line-tools">command-line tools</a> do. Instead of calling <tt class="docutils literal">publish_cmdline</tt>, the application calls one of <tt class="docutils literal">publish_file</tt>, <tt class="docutils literal">publish_string</tt>, or <tt class="docutils literal">publish_parts</tt>. These in turn call <tt class="docutils literal">publish_programmatically</tt>, which implements a generic programmatic interface. Although an application may also call <tt class="docutils literal">publish_programmatically</tt> directly, it is not recommended (if it does seem to be necessary, please write to the <a class="reference external" href="../user/mailing-lists.html#docutils-develop">Docutils-develop</a> mailing list).</p> <p><tt class="docutils literal">publish_programmatically</tt> accepts the same <a class="reference internal" href="#convenience-function-parameters">convenience function parameters</a> as <tt class="docutils literal">publish_cmdline</tt>. Where things differ is that programmatic use does no command-line processing. Instead of calling <tt class="docutils literal">docutils.Publisher.process_command_line</tt> (as <tt class="docutils literal">publish_cmdline</tt> does, via <tt class="docutils literal">docutils.Publisher.publish</tt>), <tt class="docutils literal">docutils.Publisher.process_programmatic_settings</tt> is called to set up the runtime settings.</p> <!-- copy & modify the list from command-line tools? --> </div> </div> </body> </html>