551 lines
37 KiB
HTML
551 lines
37 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>formatter — Generic output formatting — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 documentation"
|
|||
|
|
href="../_static/opensearch.xml"/>
|
|||
|
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
|
<link rel="next" title="MS Windows Specific Services" href="windows.html" />
|
|||
|
|
<link rel="prev" title="Miscellaneous Services" href="misc.html" />
|
|||
|
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/library/formatter.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="windows.html" title="MS Windows Specific Services"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="misc.html" title="Miscellaneous Services"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="misc.html" accesskey="U">Miscellaneous Services</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="module-formatter">
|
|||
|
|
<span id="formatter-generic-output-formatting"></span><h1><a class="reference internal" href="#module-formatter" title="formatter: Generic output formatter and device interface. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">formatter</span></code></a> — Generic output formatting<a class="headerlink" href="#module-formatter" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<div class="deprecated">
|
|||
|
|
<p><span class="versionmodified deprecated">Deprecated since version 3.4: </span>Due to lack of usage, the formatter module has been deprecated.</p>
|
|||
|
|
</div>
|
|||
|
|
<hr class="docutils" />
|
|||
|
|
<p>This module supports two interface definitions, each with multiple
|
|||
|
|
implementations: The <em>formatter</em> interface, and the <em>writer</em> interface which is
|
|||
|
|
required by the formatter interface.</p>
|
|||
|
|
<p>Formatter objects transform an abstract flow of formatting events into specific
|
|||
|
|
output events on writer objects. Formatters manage several stack structures to
|
|||
|
|
allow various properties of a writer object to be changed and restored; writers
|
|||
|
|
need not be able to handle relative changes nor any sort of “change back”
|
|||
|
|
operation. Specific writer properties which may be controlled via formatter
|
|||
|
|
objects are horizontal alignment, font, and left margin indentations. A
|
|||
|
|
mechanism is provided which supports providing arbitrary, non-exclusive style
|
|||
|
|
settings to a writer as well. Additional interfaces facilitate formatting
|
|||
|
|
events which are not reversible, such as paragraph separation.</p>
|
|||
|
|
<p>Writer objects encapsulate device interfaces. Abstract devices, such as file
|
|||
|
|
formats, are supported as well as physical devices. The provided
|
|||
|
|
implementations all work with abstract devices. The interface makes available
|
|||
|
|
mechanisms for setting the properties which formatter objects manage and
|
|||
|
|
inserting data into the output.</p>
|
|||
|
|
<div class="section" id="the-formatter-interface">
|
|||
|
|
<span id="formatter-interface"></span><h2>The Formatter Interface<a class="headerlink" href="#the-formatter-interface" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Interfaces to create formatters are dependent on the specific formatter class
|
|||
|
|
being instantiated. The interfaces described below are the required interfaces
|
|||
|
|
which all formatters must support once initialized.</p>
|
|||
|
|
<p>One data element is defined at the module level:</p>
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="formatter.AS_IS">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">AS_IS</code><a class="headerlink" href="#formatter.AS_IS" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Value which can be used in the font specification passed to the <code class="docutils literal notranslate"><span class="pre">push_font()</span></code>
|
|||
|
|
method described below, or as the new value to any other <code class="docutils literal notranslate"><span class="pre">push_property()</span></code>
|
|||
|
|
method. Pushing the <code class="docutils literal notranslate"><span class="pre">AS_IS</span></code> value allows the corresponding <code class="docutils literal notranslate"><span class="pre">pop_property()</span></code>
|
|||
|
|
method to be called without having to track whether the property was changed.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>The following attributes are defined for formatter instance objects:</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="formatter.formatter.writer">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">writer</code><a class="headerlink" href="#formatter.formatter.writer" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The writer instance with which the formatter interacts.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.end_paragraph">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">end_paragraph</code><span class="sig-paren">(</span><em>blanklines</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.end_paragraph" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Close any open paragraphs and insert at least <em>blanklines</em> before the next
|
|||
|
|
paragraph.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.add_line_break">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">add_line_break</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.add_line_break" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Add a hard line break if one does not already exist. This does not break the
|
|||
|
|
logical paragraph.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.add_hor_rule">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">add_hor_rule</code><span class="sig-paren">(</span><em>*args</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.add_hor_rule" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Insert a horizontal rule in the output. A hard break is inserted if there is
|
|||
|
|
data in the current paragraph, but the logical paragraph is not broken. The
|
|||
|
|
arguments and keywords are passed on to the writer’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">send_line_break()</span></code>
|
|||
|
|
method.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.add_flowing_data">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">add_flowing_data</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.add_flowing_data" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Provide data which should be formatted with collapsed whitespace. Whitespace
|
|||
|
|
from preceding and successive calls to <a class="reference internal" href="#formatter.formatter.add_flowing_data" title="formatter.formatter.add_flowing_data"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_flowing_data()</span></code></a> is considered as
|
|||
|
|
well when the whitespace collapse is performed. The data which is passed to
|
|||
|
|
this method is expected to be word-wrapped by the output device. Note that any
|
|||
|
|
word-wrapping still must be performed by the writer object due to the need to
|
|||
|
|
rely on device and font information.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.add_literal_data">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">add_literal_data</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.add_literal_data" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Provide data which should be passed to the writer unchanged. Whitespace,
|
|||
|
|
including newline and tab characters, are considered legal in the value of
|
|||
|
|
<em>data</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.add_label_data">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">add_label_data</code><span class="sig-paren">(</span><em>format</em>, <em>counter</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.add_label_data" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Insert a label which should be placed to the left of the current left margin.
|
|||
|
|
This should be used for constructing bulleted or numbered lists. If the
|
|||
|
|
<em>format</em> value is a string, it is interpreted as a format specification for
|
|||
|
|
<em>counter</em>, which should be an integer. The result of this formatting becomes the
|
|||
|
|
value of the label; if <em>format</em> is not a string it is used as the label value
|
|||
|
|
directly. The label value is passed as the only argument to the writer’s
|
|||
|
|
<code class="xref py py-meth docutils literal notranslate"><span class="pre">send_label_data()</span></code> method. Interpretation of non-string label values is
|
|||
|
|
dependent on the associated writer.</p>
|
|||
|
|
<p>Format specifications are strings which, in combination with a counter value,
|
|||
|
|
are used to compute label values. Each character in the format string is copied
|
|||
|
|
to the label value, with some characters recognized to indicate a transform on
|
|||
|
|
the counter value. Specifically, the character <code class="docutils literal notranslate"><span class="pre">'1'</span></code> represents the counter
|
|||
|
|
value formatter as an Arabic number, the characters <code class="docutils literal notranslate"><span class="pre">'A'</span></code> and <code class="docutils literal notranslate"><span class="pre">'a'</span></code>
|
|||
|
|
represent alphabetic representations of the counter value in upper and lower
|
|||
|
|
case, respectively, and <code class="docutils literal notranslate"><span class="pre">'I'</span></code> and <code class="docutils literal notranslate"><span class="pre">'i'</span></code> represent the counter value in Roman
|
|||
|
|
numerals, in upper and lower case. Note that the alphabetic and roman
|
|||
|
|
transforms require that the counter value be greater than zero.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.flush_softspace">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">flush_softspace</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.flush_softspace" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Send any pending whitespace buffered from a previous call to
|
|||
|
|
<a class="reference internal" href="#formatter.formatter.add_flowing_data" title="formatter.formatter.add_flowing_data"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_flowing_data()</span></code></a> to the associated writer object. This should be called
|
|||
|
|
before any direct manipulation of the writer object.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.push_alignment">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">push_alignment</code><span class="sig-paren">(</span><em>align</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.push_alignment" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Push a new alignment setting onto the alignment stack. This may be
|
|||
|
|
<a class="reference internal" href="#formatter.AS_IS" title="formatter.AS_IS"><code class="xref py py-const docutils literal notranslate"><span class="pre">AS_IS</span></code></a> if no change is desired. If the alignment value is changed from
|
|||
|
|
the previous setting, the writer’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">new_alignment()</span></code> method is called with
|
|||
|
|
the <em>align</em> value.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.pop_alignment">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">pop_alignment</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.pop_alignment" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Restore the previous alignment.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.push_font">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">push_font</code><span class="sig-paren">(</span><em>(size</em>, <em>italic</em>, <em>bold</em>, <em>teletype)</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.push_font" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Change some or all font properties of the writer object. Properties which are
|
|||
|
|
not set to <a class="reference internal" href="#formatter.AS_IS" title="formatter.AS_IS"><code class="xref py py-const docutils literal notranslate"><span class="pre">AS_IS</span></code></a> are set to the values passed in while others are
|
|||
|
|
maintained at their current settings. The writer’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">new_font()</span></code> method is
|
|||
|
|
called with the fully resolved font specification.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.pop_font">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">pop_font</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.pop_font" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Restore the previous font.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.push_margin">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">push_margin</code><span class="sig-paren">(</span><em>margin</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.push_margin" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Increase the number of left margin indentations by one, associating the logical
|
|||
|
|
tag <em>margin</em> with the new indentation. The initial margin level is <code class="docutils literal notranslate"><span class="pre">0</span></code>.
|
|||
|
|
Changed values of the logical tag must be true values; false values other than
|
|||
|
|
<a class="reference internal" href="#formatter.AS_IS" title="formatter.AS_IS"><code class="xref py py-const docutils literal notranslate"><span class="pre">AS_IS</span></code></a> are not sufficient to change the margin.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.pop_margin">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">pop_margin</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.pop_margin" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Restore the previous margin.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.push_style">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">push_style</code><span class="sig-paren">(</span><em>*styles</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.push_style" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Push any number of arbitrary style specifications. All styles are pushed onto
|
|||
|
|
the styles stack in order. A tuple representing the entire stack, including
|
|||
|
|
<a class="reference internal" href="#formatter.AS_IS" title="formatter.AS_IS"><code class="xref py py-const docutils literal notranslate"><span class="pre">AS_IS</span></code></a> values, is passed to the writer’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">new_styles()</span></code> method.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.pop_style">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">pop_style</code><span class="sig-paren">(</span><em>n=1</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.pop_style" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Pop the last <em>n</em> style specifications passed to <a class="reference internal" href="#formatter.formatter.push_style" title="formatter.formatter.push_style"><code class="xref py py-meth docutils literal notranslate"><span class="pre">push_style()</span></code></a>. A tuple
|
|||
|
|
representing the revised stack, including <a class="reference internal" href="#formatter.AS_IS" title="formatter.AS_IS"><code class="xref py py-const docutils literal notranslate"><span class="pre">AS_IS</span></code></a> values, is passed to
|
|||
|
|
the writer’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">new_styles()</span></code> method.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.set_spacing">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">set_spacing</code><span class="sig-paren">(</span><em>spacing</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.set_spacing" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the spacing style for the writer.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.formatter.assert_line_data">
|
|||
|
|
<code class="descclassname">formatter.</code><code class="descname">assert_line_data</code><span class="sig-paren">(</span><em>flag=1</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.formatter.assert_line_data" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Inform the formatter that data has been added to the current paragraph
|
|||
|
|
out-of-band. This should be used when the writer has been manipulated
|
|||
|
|
directly. The optional <em>flag</em> argument can be set to false if the writer
|
|||
|
|
manipulations produced a hard line break at the end of the output.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="formatter-implementations">
|
|||
|
|
<span id="formatter-impls"></span><h2>Formatter Implementations<a class="headerlink" href="#formatter-implementations" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Two implementations of formatter objects are provided by this module. Most
|
|||
|
|
applications may use one of these classes without modification or subclassing.</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="formatter.NullFormatter">
|
|||
|
|
<em class="property">class </em><code class="descclassname">formatter.</code><code class="descname">NullFormatter</code><span class="sig-paren">(</span><em>writer=None</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.NullFormatter" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A formatter which does nothing. If <em>writer</em> is omitted, a <a class="reference internal" href="#formatter.NullWriter" title="formatter.NullWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">NullWriter</span></code></a>
|
|||
|
|
instance is created. No methods of the writer are called by
|
|||
|
|
<a class="reference internal" href="#formatter.NullFormatter" title="formatter.NullFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">NullFormatter</span></code></a> instances. Implementations should inherit from this
|
|||
|
|
class if implementing a writer interface but don’t need to inherit any
|
|||
|
|
implementation.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="formatter.AbstractFormatter">
|
|||
|
|
<em class="property">class </em><code class="descclassname">formatter.</code><code class="descname">AbstractFormatter</code><span class="sig-paren">(</span><em>writer</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.AbstractFormatter" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The standard formatter. This implementation has demonstrated wide applicability
|
|||
|
|
to many writers, and may be used directly in most circumstances. It has been
|
|||
|
|
used to implement a full-featured World Wide Web browser.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="the-writer-interface">
|
|||
|
|
<span id="writer-interface"></span><h2>The Writer Interface<a class="headerlink" href="#the-writer-interface" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Interfaces to create writers are dependent on the specific writer class being
|
|||
|
|
instantiated. The interfaces described below are the required interfaces which
|
|||
|
|
all writers must support once initialized. Note that while most applications can
|
|||
|
|
use the <a class="reference internal" href="#formatter.AbstractFormatter" title="formatter.AbstractFormatter"><code class="xref py py-class docutils literal notranslate"><span class="pre">AbstractFormatter</span></code></a> class as a formatter, the writer must
|
|||
|
|
typically be provided by the application.</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.flush">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.flush" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Flush any buffered output or device control events.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.new_alignment">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">new_alignment</code><span class="sig-paren">(</span><em>align</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.new_alignment" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the alignment style. The <em>align</em> value can be any object, but by convention
|
|||
|
|
is a string or <code class="docutils literal notranslate"><span class="pre">None</span></code>, where <code class="docutils literal notranslate"><span class="pre">None</span></code> indicates that the writer’s “preferred”
|
|||
|
|
alignment should be used. Conventional <em>align</em> values are <code class="docutils literal notranslate"><span class="pre">'left'</span></code>,
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">'center'</span></code>, <code class="docutils literal notranslate"><span class="pre">'right'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'justify'</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.new_font">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">new_font</code><span class="sig-paren">(</span><em>font</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.new_font" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the font style. The value of <em>font</em> will be <code class="docutils literal notranslate"><span class="pre">None</span></code>, indicating that the
|
|||
|
|
device’s default font should be used, or a tuple of the form <code class="docutils literal notranslate"><span class="pre">(size,</span>
|
|||
|
|
<span class="pre">italic,</span> <span class="pre">bold,</span> <span class="pre">teletype)</span></code>. Size will be a string indicating the size of
|
|||
|
|
font that should be used; specific strings and their interpretation must be
|
|||
|
|
defined by the application. The <em>italic</em>, <em>bold</em>, and <em>teletype</em> values are
|
|||
|
|
Boolean values specifying which of those font attributes should be used.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.new_margin">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">new_margin</code><span class="sig-paren">(</span><em>margin</em>, <em>level</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.new_margin" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the margin level to the integer <em>level</em> and the logical tag to <em>margin</em>.
|
|||
|
|
Interpretation of the logical tag is at the writer’s discretion; the only
|
|||
|
|
restriction on the value of the logical tag is that it not be a false value for
|
|||
|
|
non-zero values of <em>level</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.new_spacing">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">new_spacing</code><span class="sig-paren">(</span><em>spacing</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.new_spacing" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the spacing style to <em>spacing</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.new_styles">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">new_styles</code><span class="sig-paren">(</span><em>styles</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.new_styles" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set additional styles. The <em>styles</em> value is a tuple of arbitrary values; the
|
|||
|
|
value <a class="reference internal" href="#formatter.AS_IS" title="formatter.AS_IS"><code class="xref py py-const docutils literal notranslate"><span class="pre">AS_IS</span></code></a> should be ignored. The <em>styles</em> tuple may be interpreted
|
|||
|
|
either as a set or as a stack depending on the requirements of the application
|
|||
|
|
and writer implementation.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.send_line_break">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">send_line_break</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.send_line_break" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Break the current line.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.send_paragraph">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">send_paragraph</code><span class="sig-paren">(</span><em>blankline</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.send_paragraph" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Produce a paragraph separation of at least <em>blankline</em> blank lines, or the
|
|||
|
|
equivalent. The <em>blankline</em> value will be an integer. Note that the
|
|||
|
|
implementation will receive a call to <a class="reference internal" href="#formatter.writer.send_line_break" title="formatter.writer.send_line_break"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send_line_break()</span></code></a> before this call
|
|||
|
|
if a line break is needed; this method should not include ending the last line
|
|||
|
|
of the paragraph. It is only responsible for vertical spacing between
|
|||
|
|
paragraphs.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.send_hor_rule">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">send_hor_rule</code><span class="sig-paren">(</span><em>*args</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.send_hor_rule" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Display a horizontal rule on the output device. The arguments to this method
|
|||
|
|
are entirely application- and writer-specific, and should be interpreted with
|
|||
|
|
care. The method implementation may assume that a line break has already been
|
|||
|
|
issued via <a class="reference internal" href="#formatter.writer.send_line_break" title="formatter.writer.send_line_break"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send_line_break()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.send_flowing_data">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">send_flowing_data</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.send_flowing_data" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Output character data which may be word-wrapped and re-flowed as needed. Within
|
|||
|
|
any sequence of calls to this method, the writer may assume that spans of
|
|||
|
|
multiple whitespace characters have been collapsed to single space characters.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.send_literal_data">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">send_literal_data</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.send_literal_data" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Output character data which has already been formatted for display. Generally,
|
|||
|
|
this should be interpreted to mean that line breaks indicated by newline
|
|||
|
|
characters should be preserved and no new line breaks should be introduced. The
|
|||
|
|
data may contain embedded newline and tab characters, unlike data provided to
|
|||
|
|
the <code class="xref py py-meth docutils literal notranslate"><span class="pre">send_formatted_data()</span></code> interface.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="formatter.writer.send_label_data">
|
|||
|
|
<code class="descclassname">writer.</code><code class="descname">send_label_data</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.writer.send_label_data" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set <em>data</em> to the left of the current left margin, if possible. The value of
|
|||
|
|
<em>data</em> is not restricted; treatment of non-string values is entirely
|
|||
|
|
application- and writer-dependent. This method will only be called at the
|
|||
|
|
beginning of a line.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="writer-implementations">
|
|||
|
|
<span id="writer-impls"></span><h2>Writer Implementations<a class="headerlink" href="#writer-implementations" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Three implementations of the writer object interface are provided as examples by
|
|||
|
|
this module. Most applications will need to derive new writer classes from the
|
|||
|
|
<a class="reference internal" href="#formatter.NullWriter" title="formatter.NullWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">NullWriter</span></code></a> class.</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="formatter.NullWriter">
|
|||
|
|
<em class="property">class </em><code class="descclassname">formatter.</code><code class="descname">NullWriter</code><a class="headerlink" href="#formatter.NullWriter" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A writer which only provides the interface definition; no actions are taken on
|
|||
|
|
any methods. This should be the base class for all writers which do not need to
|
|||
|
|
inherit any implementation methods.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="formatter.AbstractWriter">
|
|||
|
|
<em class="property">class </em><code class="descclassname">formatter.</code><code class="descname">AbstractWriter</code><a class="headerlink" href="#formatter.AbstractWriter" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A writer which can be used in debugging formatters, but not much else. Each
|
|||
|
|
method simply announces itself by printing its name and arguments on standard
|
|||
|
|
output.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="formatter.DumbWriter">
|
|||
|
|
<em class="property">class </em><code class="descclassname">formatter.</code><code class="descname">DumbWriter</code><span class="sig-paren">(</span><em>file=None</em>, <em>maxcol=72</em><span class="sig-paren">)</span><a class="headerlink" href="#formatter.DumbWriter" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Simple writer class which writes output on the <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> passed
|
|||
|
|
in as <em>file</em> or, if <em>file</em> is omitted, on standard output. The output is
|
|||
|
|
simply word-wrapped to the number of columns specified by <em>maxcol</em>. This
|
|||
|
|
class is suitable for reflowing a sequence of paragraphs.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<h3><a href="../contents.html">Table of Contents</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">formatter</span></code> — Generic output formatting</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#the-formatter-interface">The Formatter Interface</a></li>
|
|||
|
|
<li><a class="reference internal" href="#formatter-implementations">Formatter Implementations</a></li>
|
|||
|
|
<li><a class="reference internal" href="#the-writer-interface">The Writer Interface</a></li>
|
|||
|
|
<li><a class="reference internal" href="#writer-implementations">Writer Implementations</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="misc.html"
|
|||
|
|
title="previous chapter">Miscellaneous Services</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="windows.html"
|
|||
|
|
title="next chapter">MS Windows Specific Services</a></p>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<h3>This Page</h3>
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/formatter.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="windows.html" title="MS Windows Specific Services"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="misc.html" title="Miscellaneous Services"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="misc.html" >Miscellaneous Services</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|