Debian Codegraph @

docs/change_log/release-2.6.md

raw
1 title: Release Notes for v2.6
2
3 # Python-Markdown 2.6 Release Notes
4
5 We are pleased to release Python-Markdown 2.6 which adds a few new features
6 and fixes various bugs. See the list of changes below for details.
7
8 Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as
9 well as PyPy.
10
11 ## Backwards-incompatible Changes
12
13 ### `safe_mode` Deprecated
14
15 Both `safe_mode` and the associated `html_replacement_text` keywords are
16 deprecated in version 2.6 and will raise a **`DeprecationWarning`**. The
17 `safe_mode` and `html_replacement_text` keywords will be ignored in the next
18 release. The so-called "safe mode" was never actually "safe" which has resulted
19 in many people having a false sense of security when using it. As an
20 alternative, the developers of Python-Markdown recommend that any untrusted
21 content be passed through an HTML sanitizer (like [Bleach]) after being
22 converted to HTML by markdown. In fact, [Bleach Whitelist] provides a curated
23 list of tags, attributes, and styles suitable for filtering user-provided HTML
24 using bleach.
25
26 If your code previously looked like this:
27
28 ```python
29 html = markdown.markdown(text, safe_mode=True)
30 ```
31
32 Then it is recommended that you change your code to read something like this:
33
34 ```python
35 import bleach
36 from bleach_whitelist import markdown_tags, markdown_attrs
37 html = bleach.clean(markdown.markdown(text), markdown_tags, markdown_attrs)
38 ```
39
40 If you are not interested in sanitizing untrusted text, but simply desire to
41 escape raw HTML, then that can be accomplished through an extension which
42 removes HTML parsing:
43
44 ```python
45 from markdown.extensions import Extension
46
47 class EscapeHtml(Extension):
48 def extendMarkdown(self, md, md_globals):
49 del md.preprocessors['html_block']
50 del md.inlinePatterns['html']
51
52 html = markdown.markdown(text, extensions=[EscapeHtml()])
53 ```
54
55 As the HTML would not be parsed with the above Extension, then the serializer
56 will escape the raw HTML, which is exactly what happens now when
57 `safe_mode="escape"`.
58
59 [Bleach]: https://bleach.readthedocs.io/
60 [Bleach Whitelist]: https://github.com/yourcelf/bleach-whitelist
61
62 ### Positional Arguments Deprecated
63
64 Positional arguments on the `markdown.Markdown()` class are deprecated as are
65 all except the `text` argument on the `markdown.markdown()` wrapper function.
66 Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an
67 error in the next release. Only keyword arguments should be used. For example,
68 if your code previously looked like this:
69
70 ```python
71 html = markdown.markdown(text, [SomeExtension()])
72 ```
73
74 Then it is recommended that you change it to read something like this:
75
76 ```python
77 html = markdown.markdown(text, extensions=[SomeExtension()])
78 ```
79
80 !!! Note
81 This change is being made as a result of deprecating `"safe_mode"` as the
82 `safe_mode` argument was one of the positional arguments. When that argument
83 is removed, the two arguments following it will no longer be at the correct
84 position. It is recommended that you always use keywords when they are
85 supported for this reason.
86
87 ### "Shortened" Extension Names Deprecated
88
89 In previous versions of Python-Markdown, the built-in extensions received
90 special status and did not require the full path to be provided. Additionally,
91 third party extensions whose name started with `"mdx_"` received the same
92 special treatment. This behavior is deprecated and will raise a
93 **`DeprecationWarning`** in version 2.6 and an error in the next release. Ensure
94 that you always use the full path to your extensions. For example, if you
95 previously did the following:
96
97 ```python
98 markdown.markdown(text, extensions=['extra'])
99 ```
100
101 You should change your code to the following:
102
103 ```python
104 markdown.markdown(text, extensions=['markdown.extensions.extra'])
105 ```
106
107 The same applies to the command line:
108
109 ```python
110 python -m markdown -x markdown.extensions.extra input.txt
111 ```
112
113 Similarly, if you have used a third party extension (for example `mdx_math`),
114 previously you might have called it like this:
115
116 ```python
117 markdown.markdown(text, extensions=['math'])
118 ```
119
120 As the `"mdx"` prefix will no longer be appended, you will need to change your
121 code as follows (assuming the file `mdx_math.py` is installed at the root of
122 your PYTHONPATH):
123
124 ```python
125 markdown.markdown(text, extensions=['mdx_math'])
126 ```
127
128 Extension authors will want to update their documentation to reflect the new
129 behavior.
130
131 See the [documentation](../reference.md#extensions) for a full explanation
132 of the current behavior.
133
134 ### Extension Configuration as Part of Extension Name Deprecated
135
136 The previously documented method of appending the extension configuration
137 options as a string to the extension name is deprecated and will raise a
138 **`DeprecationWarning`** in version 2.6 and an error in 2.7. The
139 [`extension_configs`](../reference.md#extension_configs) keyword should be used
140 instead. See the [documentation](../reference.md#extension_configs) for a full
141 explanation of the current behavior.
142
143 ### HeaderId Extension Pending Deprecation
144
145 The HeaderId Extension is pending deprecation and will raise a
146 **`PendingDeprecationWarning`** in version 2.6. The extension will be deprecated
147 in the next release and raise an error in the release after that. Use the [Table
148 of Contents][TOC] Extension instead, which offers most of the features of the
149 HeaderId Extension and more (support for meta data is missing).
150
151 Extension authors who have been using the `slugify` and `unique` functions
152 defined in the HeaderId Extension should note that those functions are now
153 defined in the Table of Contents extension and should adjust their import
154 statements accordingly (`from markdown.extensions.toc import slugify, unique`).
155
156 ### The `configs` Keyword is Deprecated
157
158 Positional arguments and the `configs` keyword on the
159 `markdown.extension.Extension` class (and its subclasses) are deprecated. Each
160 individual configuration option should be passed to the class as a keyword/value
161 pair. For example. one might have previously initiated an extension subclass
162 like this:
163
164 ```python
165 ext = SomeExtension(configs={'somekey': 'somevalue'})
166 ```
167
168 That code should be updated to pass in the options directly:
169
170 ```python
171 ext = SomeExtension(somekey='somevalue')
172 ```
173
174 Extension authors will want to note that this affects the `makeExtension`
175 function as well. Previously it was common for the function to be defined as
176 follows:
177
178 ```python
179 def makeExtension(configs=None):
180 return SomeExtension(configs=configs)
181 ```
182
183 Extension authors will want to update their code to the following instead:
184
185 ```python
186 def makeExtension(**kwargs):
187 return SomeExtension(**kwargs)
188 ```
189
190 Failing to do so will result in a **`DeprecationWarning`** and will raise an
191 error in the next release. See the [Extension API][mext] documentation for more
192 information.
193
194 In the event that an `markdown.extension.Extension` subclass overrides the
195 `__init__` method and implements its own configuration handling, then the above
196 may not apply. However, it is recommended that the subclass still calls the
197 parent `__init__` method to handle configuration options like so:
198
199 ```python
200 class SomeExtension(markdown.extension.Extension):
201 def __init__(**kwargs):
202 # Do pre-config stuff here
203 # Set config defaults
204 self.config = {
205 'option1' : ['value1', 'description1'],
206 'option2' : ['value2', 'description2']
207 }
208 # Set user defined configs
209 super(MyExtension, self).__init__(**kwargs)
210 # Do post-config stuff here
211 ```
212
213 Note the call to `super` to get the benefits of configuration handling from the
214 parent class. See the [documentation][config] for more information.
215
216 [config]: ../extensions/api.md#configsettings
217 [mext]: ../extensions/api.md#dot_notation
218
219 ## What's New in Python-Markdown 2.6
220
221 ### Official Support for PyPy
222
223 Official support for [PyPy] has been added. While Python-Markdown has most
224 likely worked on PyPy for some time, it is now officially supported and tested
225 on PyPy.
226
227 [PyPy]: https://pypy.org/
228
229 ### YAML Style Meta-Data
230
231 <del>The [Meta-Data] Extension now includes optional support for [YAML] style
232 meta-data.</del> By default, the YAML deliminators are recognized, however, the
233 actual data is parsed as previously. This follows the syntax of [MultiMarkdown],
234 which inspired this extension.
235
236 <del>Alternatively, if the `yaml` option is set, then the data is parsed as
237 YAML.</del> <ins>As the `yaml` option was buggy, it was removed in 2.6.1. It is
238 suggested that a preprocessor (like [docdata]) or a third party extension be
239 used if you want true YAML support. See [Issue #390][#390] for a full
240 explanation.</ins>
241
242 [MultiMarkdown]: https://fletcherpenney.net/multimarkdown/#metadata
243 [Meta-Data]: ../extensions/meta_data.md
244 [YAML]: https://yaml.org/
245 [#390]: https://github.com/Python-Markdown/markdown/issues/390
246 [docdata]: https://github.com/waylan/docdata
247
248 ### Table of Contents Extension Refactored
249
250 The [Table of Contents][TOC] Extension has been refactored and some new features
251 have been added. See the documentation for a full explanation of each feature
252 listed below:
253
254 * The extension now assigns the Table of Contents to the `toc` attribute of
255 the Markdown class regardless of whether a "marker" was found in the
256 document. Third party frameworks no longer need to insert a "marker," run
257 the document through Markdown, then extract the Table of Contents from the
258 document.
259
260 * The Table of Contents Extension is now a "registered extension." Therefore,
261 when the `reset` method of the Markdown class is called, the `toc` attribute
262 on the Markdown class is cleared (set to an empty string).
263
264 * When the `marker` configuration option is set to an empty string, the parser
265 completely skips the process of searching the document for markers. This
266 should save parsing time when the Table of Contents Extension is being used
267 only to assign ids to headers.
268
269 * A `separator` configuration option has been added allowing users to override
270 the separator character used by the slugify function.
271
272 * A `baselevel` configuration option has been added allowing users to set the
273 base level of headers in their documents (h1-h6). This allows the header
274 levels to be automatically adjusted to fit within the hierarchy of an HTML
275 template.
276
277 [TOC]: ../extensions/toc.md
278
279 ### Pygments can now be disabled
280
281 The [CodeHilite][ch] Extension has gained a new configuration option:
282 `use_pygments`. The option is `True` by default, however, it allows one to turn
283 off Pygments code highlighting (set to `False`) while preserving the language
284 detection features of the extension. Note that Pygments language guessing is not
285 used as that would 'use Pygments'. If a language is defined for a code block, it
286 will be assigned to the `<code>` tag as a class in the manner suggested by the
287 [HTML5 spec][spec] (alternate output will not be entertained) and could
288 potentially be used by a JavaScript library in the browser to highlight the code
289 block.
290
291 [ch]: ../extensions/code_hilite.md
292 [spec]: https://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
293
294 ### Miscellaneous
295
296 Test coverage has been improved including running [flake8]. While those changes
297 will not directly effect end users, the code is being better tested which will
298 benefit everyone.
299
300 [flake8]: https://flake8.readthedocs.io/en/latest/
301
302 Various bug fixes have been made. See the
303 [commit log](https://github.com/Python-Markdown/markdown/commits/master)
304 for a complete history of the changes.