<!DOCTYPE html>
<html>
<head>
<meta charset=utf-8>
<title>Library Reference — Python Markdown</title>
<link rel="stylesheet" href="default.css" type="text/css">
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="siteindex.html" title="General Index">index</a></li>
<li class="right">
<a href="cli.html" title="Command Line"
accesskey="N">next</a> |</li>
<li class="right">
<a href="install.html" title="Installation"
accesskey="P">previous</a> |</li>
<li><img src="py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="index.html">Python Markdown v2.4.1 documentation</a> »</li>
<li><a href="reference.html">Library Reference</a> »</li>
</ul>
</div> <!-- .related -->
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<h1 id="using-markdown-as-a-python-library">Using Markdown as a Python Library<a class="headerlink" href="#using-markdown-as-a-python-library" title="Permanent link">¶</a></h1>
<p>First and foremost, Python-Markdown is intended to be a python library module
used by various projects to convert Markdown syntax into HTML.</p>
<h2 id="the-basics">The Basics<a class="headerlink" href="#the-basics" title="Permanent link">¶</a></h2>
<p>To use markdown as a module:</p>
<pre><code>import markdown
html = markdown.markdown(your_text_string)
</code></pre>
<h2 id="the-details">The Details<a class="headerlink" href="#the-details" title="Permanent link">¶</a></h2>
<p>Python-Markdown provides two public functions (<a href="#markdown"><code>markdown.markdown</code></a>
and <a href="#markdownFromFile"><code>markdown.markdownFromFile</code></a>) both of which wrap the
public class <a href="#Markdown"><code>markdown.Markdown</code></a>. If you’re processing one
document at a time, these functions will serve your needs. However, if you need
to process multiple documents, it may be advantageous to create a single
instance of the <code>markdown.Markdown</code> class and pass multiple documents through
it. If you do use a single instance though, make sure to call the <code>reset</code>
method appropriately (<a href="#convert">see below</a>).</p>
<h3 id="markdown"><code>markdown.markdown (text [, **kwargs])</code><a class="headerlink" href="#markdown" title="Permanent link">¶</a></h3>
<p>The following options are available on the <code>markdown.markdown</code> function:</p>
<ul>
<li>
<p><strong id="text"><code>text</code></strong> (required): The source unicode string.</p>
<div class="admonition note">
<p class="admonition-title">Important</p>
<p>Python-Markdown expects <strong>Unicode</strong> as input (although
some simple ASCII strings <em>may</em> work) and returns output as Unicode.
Do not pass encoded strings to it! If your input is encoded, (e.g. as
UTF-8), it is your responsibility to decode it. For example:</p>
<pre><code>input_file = codecs.open("some_file.txt", mode="r", encoding="utf-8")
text = input_file.read()
html = markdown.markdown(text)
</code></pre>
<p>If you want to write the output to disk, you <em>must</em> encode it yourself:</p>
<pre><code>output_file = codecs.open("some_file.html", "w",
encoding="utf-8",
errors="xmlcharrefreplace"
)
output_file.write(html)
</code></pre>
</div>
</li>
<li>
<p><strong id="extensions"><code>extensions</code></strong>: A list of extensions.</p>
<p>Python-Markdown provides an <a href="extensions/api.html">API</a> for third parties to
write extensions to the parser adding their own additions or changes to the
syntax. A few commonly used extensions are shipped with the markdown
library. See the <a href="extensions/index.html">extension documentation</a> for a
list of available extensions.</p>
<p>The list of extensions may contain instances of extensions and/or strings
of extension names. </p>
<pre><code>extensions=[MyExtension(), 'path.to.my.ext', 'extra']
</code></pre>
<p>When passing in extension instances, each class instance must be a subclass
of <code>markdown.extensions.Extension</code> and any configuration options should be
defined when initiating the class instance rather than using the
<a href="#extension_configs">extension_configs</a> keyword. For example:</p>
<pre><code>from markdown.extensions import Extension
class MyExtension(Extension):
# define your extension here...
markdown.markdown(text, extensions=[MyExtension(configs={'option': 'value'}))
</code></pre>
<p>If an extension name is provided as a string, the extension must be
importable as a python module on your PYTHONPATH. Python’s dot notation is
supported. Therefore, to import the ‘extra’ extension, one could do
<code>extensions=['markdown.extensions.extra']</code> However, if no dots are provided
in the string (<code>extensions=['extra']</code>) Markdown will first look for the
module <code>markdown.extensions.extra</code> (the built-in extension), then a module
named <code>mdx_extra</code> (‘mdx_’ will be appended to the beginning of the string)
at the root of your PYTHONPATH. </p>
<p>When loading an extension by name (as a string), you may either pass in
configuration settings to the extension using the
<a href="#extension_configs">extension_configs</a> keyword or by appending the
settings to the name in the following format:</p>
<pre><code>extensions=['name(option1=value,option2=value)']
</code></pre>
<p>Note that there are no quotes or whitespace in the above format, which
severely limits how it can be used. For more complex settings, it is
suggested that the <a href="#extension_configs">extension_configs</a> keyword
be used or an instance of a class be passed in.</p>
<div class="admonition seealso">
<p class="admonition-title">See Also</p>
<p>See the documentation of the <a href="extensions/api.html">Extension API</a> for
assistance in creating extensions.</p>
</div>
</li>
<li>
<p><strong id="extension_configs"><code>extension_configs</code></strong>: A dictionary of
configuration settings for extensions.</p>
<p>Any configuration settings will only be passed to extensions loaded by name
(as a string). When loading extensions as class instances, pass the
configuration settings directly to the class when initializing it. </p>
<p>The dictionary of configuration settings must be in the following format:</p>
<pre><code>extension_configs = {'extension_name_1':
[
('option_1', 'value_1'),
('option_2', 'value_2')
],
'extension_name_2':
[
('option_1', 'value_1')
]
}
</code></pre>
<p>See the documentation specific to the extension you are using for help in
specifying configuration settings for that extension.</p>
</li>
<li>
<p><strong id="output_format"><code>output_format</code></strong>: Format of output. </p>
<p>Supported formats are:</p>
<ul>
<li><code>"xhtml1"</code>: Outputs XHTML 1.x. <strong>Default</strong>.</li>
<li><code>"xhtml5"</code>: Outputs XHTML style tags of HTML 5</li>
<li><code>"xhtml"</code>: Outputs latest supported version of XHTML (currently XHTML 1.1).</li>
<li><code>"html4"</code>: Outputs HTML 4</li>
<li><code>"html5"</code>: Outputs HTML style tags of HTML 5</li>
<li><code>"html"</code>: Outputs latest supported version of HTML (currently HTML 4).</li>
</ul>
<p>The values can be in either lowercase or uppercase.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>It is suggested that the more specific formats (“xhtml1”, “html5”, &
“html4”) be used as the more general formats (“xhtml” or “html”) may
change in the future if it makes sense at that time. </p>
</div>
</li>
<li>
<p><strong id="safe_mode"><code>safe_mode</code></strong>: Disallow raw html.</p>
<p>If you are using Markdown on a web system which will transform text
provided by untrusted users, you may want to use the “safe_mode”
option which ensures that the user’s HTML tags are either replaced,
removed or escaped. (They can still create links using Markdown syntax.)</p>
<p>The following values are accepted:</p>
<ul>
<li>
<p><code>False</code> (Default): Raw HTML is passed through unaltered.</p>
</li>
<li>
<p><code>replace</code>: Replace all HTML blocks with the text assigned to
<code>html_replacement_text</code> To maintain backward compatibility, setting
<code>safe_mode=True</code> will have the same effect as <code>safe_mode='replace'</code>. </p>
<p>To replace raw HTML with something other than the default, do:</p>
<pre><code>md = markdown.Markdown(safe_mode='replace',
html_replacement_text='--RAW HTML NOT ALLOWED--')
</code></pre>
</li>
<li>
<p><code>remove</code>: All raw HTML will be completely stripped from the text with
no warning to the author.</p>
</li>
<li>
<p><code>escape</code>: All raw HTML will be escaped and included in the document.</p>
<p>For example, the following source:</p>
<pre><code>Foo <b>bar</b>.
</code></pre>
<p>Will result in the following HTML:</p>
<pre><code><p>Foo &lt;b&gt;bar&lt;/b&gt;.</p>
</code></pre>
</li>
</ul>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>“safe_mode” also alters the default value for the
<a href="#enable_attributes"><code>enable_attributes</code></a> option.</p>
</div>
<div class="admonition seealso">
<p class="admonition-title">See Also</p>
<p>HTML sanitizers (like <a href="https://github.com/jsocol/bleach">Bleach</a>) may provide a better solution for
dealing with markdown text submitted by untrusted users. That way,
both the HTML generated by Markdown and user submited raw HTML are
fully sanitized.</p>
<pre><code>import markdown
import bleach
html = bleach.clean(markdown.markdown(evil_text))
</code></pre>
</div>
</li>
<li>
<p><strong id="html_replacement_text"><code>html_replacement_text</code></strong>: Text used when
safe_mode is set to <code>replace</code>. Defaults to <code>[HTML_REMOVED]</code>.</p>
</li>
<li>
<p><strong id="tab_length"><code>tab_length</code></strong>: Length of tabs in the source. Default: 4</p>
</li>
<li>
<p><strong id="enable_attributes"><code>enable_attributes</code></strong>: Enable the conversion of
attributes. Defaults to <code>True</code>, unless <a href="#safe_mode"><code>safe_mode</code></a> is enabled,
in which case the default is <code>False</code>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p><code>safe_mode</code> only overrides the default. If <code>enable_attributes</code>
is explicitly set, the explicit value is used regardless of <code>safe_mode</code>.
However, this could potentially allow an untrusted user to inject
JavaScript into your documents.</p>
</div>
</li>
<li>
<p><strong id="smart_emphasis"><code>smart_emphasis</code></strong>: Treat <code>_connected_words_</code>
intelligently Default: True</p>
</li>
<li>
<p><strong id="lazy_ol"><code>lazy_ol</code></strong>: Ignore number of first item of ordered lists.
Default: True</p>
<p>Given the following list:</p>
<pre><code>4. Apples
5. Oranges
6. Pears
</code></pre>
<p>By default markdown will ignore the fact the the first line started
with item number “4” and the HTML list will start with a number “1”.
If <code>lazy_ol</code> is set to <code>False</code>, then markdown will output the following
HTML:</p>
<pre><code><ol>
<li start="4">Apples</li>
<li>Oranges</li>
<li>Pears</li>
</ol>
</code></pre>
</li>
</ul>
<h3 id="markdownFromFile"><code>markdown.markdownFromFile (**kwargs)</code><a class="headerlink" href="#markdownFromFile" title="Permanent link">¶</a></h3>
<p>With a few exceptions, <code>markdown.markdownFromFile</code> accepts the same options as
<code>markdown.markdown</code>. It does <strong>not</strong> accept a <code>text</code> (or Unicode) string.
Instead, it accepts the following required options:</p>
<ul>
<li>
<p><strong id="input"><code>input</code></strong> (required): The source text file.</p>
<p><code>input</code> may be set to one of three options:</p>
<ul>
<li>a string which contains a path to a readable file on the file system,</li>
<li>a readable file-like object,</li>
<li>or <code>None</code> (default) which will read from <code>stdin</code>.</li>
</ul>
</li>
<li>
<p><strong id="output"><code>output</code></strong>: The target which output is written to.</p>
<p><code>output</code> may be set to one of three options:</p>
<ul>
<li>a string which contains a path to a writable file on the file system,</li>
<li>a writable file-like object,</li>
<li>or <code>None</code> (default) which will write to <code>stdout</code>.</li>
</ul>
</li>
<li>
<p><strong id="encoding"><code>encoding</code></strong>: The encoding of the source text file. Defaults
to “utf-8”. The same encoding will always be used for input and output.
The ‘xmlcharrefreplace’ error handler is used when encoding the output.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is the only place that decoding and encoding of unicode
takes place in Python-Markdown. If this rather naive solution does not
meet your specific needs, it is suggested that you write your own code
to handle your encoding/decoding needs.</p>
</div>
</li>
</ul>
<h3 id="Markdown"><code>markdown.Markdown ([**kwargs])</code><a class="headerlink" href="#Markdown" title="Permanent link">¶</a></h3>
<p>The same options are available when initializing the <code>markdown.Markdown</code> class
as on the <a href="#markdown"><code>markdown.markdown</code></a> function, except that the class does
<strong>not</strong> accept a source text string on initialization. Rather, the source text
string must be passed to one of two instance methods:</p>
<ul>
<li>
<p><code id="convert">Markdown.convert(source)</code></p>
<p>The <code>source</code> text must meet the same requirements as the <a href="#text"><code>text</code></a>
argument of the <a href="#markdown"><code>markdown.markdown</code></a> function.</p>
<p>You should also use this method if you want to process multiple strings
without creating a new instance of the class for each string.</p>
<pre><code>md = markdown.Markdown()
html1 = md.convert(text1)
html2 = md.convert(text2)
</code></pre>
<p>Depending on which options and/or extensions are being used, the parser may
need its state reset between each call to <code>convert</code>, otherwise performance
can degrade drastically:</p>
<pre><code>html1 = md.convert(text1)
md.reset()
html2 = md.convert(text2)
</code></pre>
<p>To make this easier, you can also chain calls to <code>reset</code> together:</p>
<pre><code>html3 = md.reset().convert(text3)
</code></pre>
</li>
<li>
<p><code id="convertFile">Markdown.convertFile(**kwargs)</code></p>
<p>The arguments of this method are identical to the arguments of the same
name on the <code>markdown.markdownFromFile</code> function (<a href="#input"><code>input</code></a>,
<a href="#output"><code>output</code></a>, and <a href="#encoding"><code>encoding</code></a>). As with the
<a href="#convert"><code>convert</code></a> method, this method should be used to
process multiple files without creating a new instance of the class for
each document. State may need to be <code>reset</code> between each call to
<code>convertFile</code> as is the case with <code>convert</code>.</p>
</li>
</ul>
</div> <!-- .body -->
</div> <!-- .bodywrapper -->
</div> <!-- .documentwrapper -->
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3>Table Of Contents</h3>
<div class="toc">
<ul>
<li><a href="#using-markdown-as-a-python-library">Using Markdown as a Python Library</a><ul>
<li><a href="#the-basics">The Basics</a></li>
<li><a href="#the-details">The Details</a><ul>
<li><a href="#markdown">markdown.markdown (text [, **kwargs])</a></li>
<li><a href="#markdownFromFile">markdown.markdownFromFile (**kwargs)</a></li>
<li><a href="#Markdown">markdown.Markdown ([**kwargs])</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<h4>Previous topic</h4>
<p class="topless"><a href="install.html"
title="previous chapter">Installation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="cli.html"
title="next chapter">Command Line</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="https://github.com/waylan/Python-Markdown/issues"
>Report a Bug</a></li>
<li><a href="reference.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div> <!-- .sphinxsidebarwrapper -->
</div> <!-- .sphinxsidebar -->
<div class="clearer"></div>
</div> <!-- .document -->
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="siteindex.html" title="General Index">index</a></li>
<li class="right">
<a href="cli.html" title="Command Line"
accesskey="N">next</a> |</li>
<li class="right">
<a href="install.html" title="Installation"
accesskey="P">previous</a> |</li>
<li><img src="py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="index.html">Python Markdown v2.4.1 documentation</a> »</li>
<li><a href="reference.html">Library Reference</a> »</li>
</ul>
</div> <!-- .related -->
<div class="footer">© 2010-2012 Python Markdown Project</div>
</body>
</html>
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-release
>
by-pkgid
>
475047415fcf83c129d0834cea9418c4
>
files
>
150
