Debian Codegraph @

docs/change_log/release-2.5.md

raw
1 title: Release Notes for v2.5
2
3 Python-Markdown 2.5 Release Notes
4 =================================
5
6 We are pleased to release Python-Markdown 2.5 which adds a few new features
7 and fixes various bugs. See the list of changes below for details.
8
9 Python-Markdown version 2.5 supports Python versions 2.7, 3.2, 3.3, and 3.4.
10
11 Backwards-incompatible Changes
12 ------------------------------
13
14 * Python-Markdown no longer supports Python version 2.6. You must be using Python
15 versions 2.7, 3.2, 3.3, or 3.4.
16
17 [importlib]: https://pypi.org/project/importlib/
18
19 * The `force_linenos` configuration key on the [CodeHilite Extension] has been **deprecated**
20 and will raise a `KeyError` if provided. In the previous release (2.4), it was
21 issuing a `DeprecationWarning`. The [`linenums`][linenums] keyword should be used
22 instead, which provides more control of the output.
23
24 [CodeHilite Extension]: ../extensions/code_hilite.md
25 [linenums]: ../extensions/code_hilite.md#usage
26
27 * Both `safe_mode` and the associated `html_replacement_text` keywords will be
28 deprecated in version 2.6 and will raise a **`PendingDeprecationWarning`** in
29 2.5. The so-called "safe mode" was never actually "safe" which has resulted in
30 many people having a false sense of security when using it. As an alternative,
31 the developers of Python-Markdown recommend that any untrusted content be
32 passed through an HTML sanitizer (like [Bleach]) after being converted to HTML
33 by markdown.
34
35 If your code previously looked like this:
36
37 html = markdown.markdown(text, same_mode=True)
38
39 Then it is recommended that you change your code to read something like this:
40
41 import bleach
42 html = bleach.clean(markdown.markdown(text))
43
44 If you are not interested in sanitizing untrusted text, but simply desire to
45 escape raw HTML, then that can be accomplished through an extension which
46 removes HTML parsing:
47
48 from markdown.extensions import Extension
49
50 class EscapeHtml(Extension):
51 def extendMarkdown(self, md, md_globals):
52 del md.preprocessors['html_block']
53 del md.inlinePatterns['html']
54
55 html = markdown.markdown(text, extensions=[EscapeHtml()])
56
57 As the HTML would not be parsed with the above Extension, then the
58 serializer will escape the raw HTML, which is exactly what happens now when
59 `safe_mode="escape"`.
60
61 [Bleach]: https://bleach.readthedocs.io/
62
63 * Positional arguments on the `markdown.Markdown()` are pending deprecation as are
64 all except the `text` argument on the `markdown.markdown()` wrapper function.
65 Only keyword arguments should be used. For example, if your code previously
66 looked like this:
67
68 html = markdown.markdown(text, ['extra'])
69
70 Then it is recommended that you change it to read something like this:
71
72 html = markdown.markdown(text, extensions=['extra'])
73
74 !!! Note
75 This change is being made as a result of deprecating `"safe_mode"` as the
76 `safe_mode` argument was one of the positional arguments. When that argument
77 is removed, the two arguments following it will no longer be at the correct
78 position. It is recommended that you always use keywords when they are supported
79 for this reason.
80
81 * In previous versions of Python-Markdown, the built-in extensions received
82 special status and did not require the full path to be provided. Additionally,
83 third party extensions whose name started with `"mdx_"` received the same
84 special treatment. This behavior will be deprecated in version 2.6 and will
85 raise a **`PendingDeprecationWarning`** in 2.5. Ensure that you always use the
86 full path to your extensions. For example, if you previously did the
87 following:
88
89 markdown.markdown(text, extensions=['extra'])
90
91 You should change your code to the following:
92
93 markdown.markdown(text, extensions=['markdown.extensions.extra'])
94
95 The same applies to the command line:
96
97 $ python -m markdown -x markdown.extensions.extra input.txt
98
99 See the [documentation](../reference.md#extensions) for a full explanation
100 of the current behavior.
101
102 * The previously documented method of appending the extension configuration as
103 a string to the extension name will be deprecated in Python-Markdown
104 version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. The
105 [`extension_configs`](../reference.md#extension_configs) keyword should
106 be used instead. See the [documentation](../reference.md#extension_configs)
107 for a full explanation of the current behavior.
108
109 What's New in Python-Markdown 2.5
110 ---------------------------------
111
112 * The [Smarty Extension] has had a number of additional configuration settings
113 added, which allows one to define their own substitutions to better support
114 languages other than English. Thanks to [Martin Altmayer] for implementing this
115 feature.
116
117 [Smarty Extension]: ../extensions/smarty.md
118 [Martin Altmayer]:https://github.com/MartinAltmayer
119
120 * Named Extensions (strings passed to the [`extensions`][ex] keyword of
121 `markdown.Markdown`) can now point to any module and/or Class on your
122 PYTHONPATH. While dot notation was previously supported, a module could not
123 be at the root of your PYTHONPATH. The name had to contain at least one dot
124 (requiring it to be a sub-module). This restriction no longer exists.
125
126 Additionally, a Class may be specified in the name. The class must be at the
127 end of the name (which uses dot notation from PYTHONPATH) and be separated
128 by a colon from the module.
129
130 Therefore, if you were to import the class like this:
131
132 from path.to.module import SomeExtensionClass
133
134 Then the named extension would comprise this string:
135
136 "path.to.module:SomeExtensionClass"
137
138 This allows multiple extensions to be implemented within the same module and
139 still accessible when the user is not able to import the extension directly
140 (perhaps from a template filter or the command line).
141
142 This also means that extension modules are no longer required to include the
143 `makeExtension` function which returns an instance of the extension class.
144 However, if the user does not specify the class name (she only provides
145 `"path.to.module"`) the extension will fail to load without the
146 `makeExtension` function included in the module. Extension authors will want
147 to document carefully what is required to load their extensions.
148
149 [ex]: ../reference.md#extensions
150
151 * The Extension Configuration code has been refactored to make it a little
152 easier for extension authors to work with configuration settings. As a
153 result, the [`extension_configs`][ec] keyword now accepts a dictionary
154 rather than requiring a list of tuples. A list of tuples is still supported
155 so no one needs to change their existing code. This should also simplify the
156 learning curve for new users.
157
158 Extension authors are encouraged to review the new methods available on the
159 `markdown.extnesions.Extension` class for handling configuration and adjust
160 their code going forward. The included extensions provide a model for best
161 practices. See the [API] documentation for a full explanation.
162
163 [ec]: ../reference.md#extension_configs
164 [API]: ../extensions/api.md#configsettings
165
166 * The [Command Line Interface][cli] now accepts a `--extensions_config` (or
167 `-c`) option which accepts a file name and passes the parsed content of a
168 [YAML] or [JSON] file to the [`extension_configs`][ec] keyword of the
169 `markdown.Markdown` class. The contents of the YAML or JSON must map to a
170 Python Dictionary which matches the format required by the
171 `extension_configs` keyword. Note that [PyYAML] is required to parse YAML
172 files.
173
174 [cli]: ../cli.md#using-extensions
175 [YAML]: https://yaml.org/
176 [JSON]: https://json.org/
177 [PyYAML]: https://pyyaml.org/
178
179 * The [Admonition Extension][ae] is no longer considered "experimental."
180
181 [ae]: ../extensions/admonition.md
182
183 * There have been various refactors of the testing framework. While those
184 changes will not directly effect end users, the code is being better tested
185 which will benefit everyone.
186
187 * Various bug fixes have been made. See the [commit
188 log](https://github.com/Python-Markdown/markdown/commits/master) for a
189 complete history of the changes.