Debian Codegraph @

docs/change_log/release-2.1.md

raw
1 title: Release Notes for v2.1
2
3 Python-Markdown 2.1 Release Notes
4 =================================
5
6 We are pleased to release Python-Markdown 2.1 which makes many
7 improvements on 2.0. In fact, we consider 2.1 to be what 2.0 should have been.
8 While 2.1 consists mostly of bug fixes, bringing Python-Markdown more inline
9 with other implementations, some internal improvements were made to the parser,
10 a few new built-in extensions were added, and HTML5 support was added.
11
12 Python-Markdown supports Python versions 2.4, 2.5, 2.6, 2.7, 3.1, and 3.2 out
13 of the box. In fact, the same code base installs on Python 3.1 and 3.2 with no
14 extra work by the end user.
15
16 Backwards-incompatible Changes
17 ------------------------------
18
19 While Python-Markdown has received only minor internal changes since the last
20 release, there are a few backward-incompatible changes to note:
21
22 * Support had been dropped for Python 2.3. No guarantees are made that the
23 library will work in any version of Python lower than 2.4. Additionally, while
24 the library had been tested with Python 2.4, consider Python 2.4 support to be
25 depreciated. It is not likely that any future versions will continue to
26 support any version of Python less than 2.5. Note that Python 3.0 is not
27 supported due to a bug in its 2to3 tool. If you must use Python-Markdown with
28 Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to do a
29 conversion.
30
31 * Python-Markdown previously accepted positional arguments on its class and
32 wrapper methods. It now expects keyword arguments. Currently, the positional
33 arguments should continue to work, but the solution feels hacky and may be
34 removed in a future version. All users are encouraged to use keyword arguments
35 as documented in the [Library Reference](../reference.md).
36
37 * Past versions of Python-Markdown provided module level Global variables which
38 controlled the behavior of a few different aspects of the parser. Those global
39 variables have been replaced with attributes on the Markdown class.
40 Additionally, those attributes are settable as keyword arguments when
41 initializing a class instance. Therefore, if you were editing the global
42 variables (either by editing the source or by overriding them in your code),
43 you should now set them on the class. See the [Library
44 Reference](../reference.md) for the options available.
45
46 * If you have been using the HeaderId extension to
47 define custom ids on headers, you will want to switch to using the new
48 [Attribute List](../extensions/attr_list.md) extension. The HeaderId extension
49 now only auto-generates ids on headers which have not already had ids defined.
50 Note that the [Extra](../extensions/extra.md) extension has been switched to
51 use Attribute Lists instead of HeaderId as it did previously.
52
53 * Some code was moved into the `markdown.util` namespace which was previously in
54 the `markdown` namespace. Extension authors may need to adjust a few import
55 statements in their extensions to work with the changes.
56
57 * The command line script name was changed to `markdown_py`. The previous name
58 (`markdown`) was conflicting with people (and Linux package systems) who also
59 had markdown.pl installed on there system as markdown.pl's command line script
60 was also named `markdown`. Be aware that installing Python-Markdown 2.1 will
61 not remove the old versions of the script with different names. You may want
62 to remove them yourself as they are unlikely to work properly.
63
64 What's New in Python-Markdown 2.1
65 ---------------------------------
66
67 Three new extensions were added. [Attribute Lists](../extensions/attr_list.md),
68 which was inspired by Maruku's feature of the same name, [Newline to
69 Break](../extensions/nl2br.md), which was inspired by GitHub Flavored Markdown,
70 and Smart Strong, which fills a hole in the Extra extension.
71
72 HTML5 is now supported. All this really means is that new block level elements
73 introduced in the HTML5 spec are now properly recognized as raw HTML. As
74 valid HTML5 can consist of either HTML4 or XHTML1, there is no need to add a
75 new HTML5 serializers. That said, `html5` and `xhtml5` have been added as
76 aliases of the `html4` and `xhtml1` serializers respectively.
77
78 An XHTML serializer has been added. Previously, ElementTree's XML serializer
79 was being used for XHTML output. With the new serializer we are able to avoid
80 more invalid output like empty elements (i.e., `<p />`) which can choke
81 browsers.
82
83 Improved support for Python 3.x. Now when running `setupy.py install` in
84 Python 3.1 or greater the 2to3 tool is run automatically. Note that Python 3.0
85 is not supported due to a bug in its 2to3 tool. If you must use Python-Markdown
86 with Python 3.0, it is suggested you manually use Python 3.1's 2to3 tool to
87 do a conversion.
88
89 Methods on instances of the Markdown class that do not return results can now
90 be changed allowing one to do `md.reset().convert(moretext)`.
91
92 The Markdown class was refactored so that a subclass could define its own
93 `build_parser` method which would build a completely different parser. In
94 other words, one could use the basic machinery in the markdown library to
95 build a parser of a different markup language without the overhead of building
96 the markdown parser and throwing it away.
97
98 Import statements within markdown have been improved so that third party
99 libraries can embed the markdown library if they desire (licensing permitting).
100
101 Added support for Python's `-m` command line option. You can run the markdown
102 package as a command line script. Do `python -m markdown [options] [args]`.
103 Note that this is only fully supported in Python 2.7+. Python 2.5 & 2.6
104 require you to call the module directly (`markdown.__main__`) rather than
105 the package (`markdown`). This does not work in Python 2.4.
106
107 The command line script has been renamed to `markdown_py` which avoids all the
108 various problems we had with previous names. Also improved the command line
109 script to accept input on `stdin`.
110
111 The testing framework has been completely rebuilt using the Nose testing
112 framework. This provides a number of benefits including the ability to better
113 test the built-in extensions and other options available to change the parsing
114 behavior. See the Test Suite documentation for details.
115
116 Various bug fixes have been made, which are too numerous to list here. See the
117 [commit log](https://github.com/Python-Markdown/markdown/commits/master) for a
118 complete history of the changes.