Skip to content

Commit 375ebac

Browse files
waylanwaylan
committed
Reformatted Release Notes for 2.6.
This format (using subheading rather than lists), allows for easy linking to each individual section of the release notes. I think we should sue this format going forward. Also added an additional example to clarify the deprecation of the special treatment of the 'mdx_' prefix for third party extensions.
1 parent cdb9ccb commit 375ebac

File tree

1 file changed

+188
-154
lines changed

1 file changed

+188
-154
lines changed

‎docs/release-2.6.txt‎

Lines changed: 188 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -15,211 +15,245 @@ Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as w
1515
Backwards-incompatible Changes
1616
------------------------------
1717

18-
* Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated
19-
in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and
20-
`html_replacement_text` keywords will be ignored in version 2.7. The so-called
21-
"safe mode" was never actually "safe" which has resulted in many people having a false
22-
sense of security when using it. As an alternative, the developers of Python-Markdown
23-
recommend that any untrusted content be passed through an HTML sanitizer (like [Bleach])
24-
after being converted to HTML by markdown.
18+
### `safe_mode` Deprecated
2519

26-
If your code previously looked like this:
20+
Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated
21+
in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and
22+
`html_replacement_text` keywords will be ignored in version 2.7. The so-called
23+
"safe mode" was never actually "safe" which has resulted in many people having a false
24+
sense of security when using it. As an alternative, the developers of Python-Markdown
25+
recommend that any untrusted content be passed through an HTML sanitizer (like [Bleach])
26+
after being converted to HTML by markdown.
2727

28-
html = markdown.markdown(text, safe_mode=True)
28+
If your code previously looked like this:
2929

30-
Then it is recommended that you change your code to read something like this:
30+
html = markdown.markdown(text, safe_mode=True)
3131

32-
import bleach
33-
html = bleach.clean(markdown.markdown(text))
32+
Then it is recommended that you change your code to read something like this:
3433

35-
If you are not interested in sanitizing untrusted text, but simply desire to escape
36-
raw HTML, then that can be accomplished through an extension which removes HTML parsing:
34+
import bleach
35+
html = bleach.clean(markdown.markdown(text))
3736

38-
from markdown.extensions import Extension
37+
If you are not interested in sanitizing untrusted text, but simply desire to escape
38+
raw HTML, then that can be accomplished through an extension which removes HTML parsing:
3939

40-
class EscapeHtml(Extension):
41-
def extendMarkdown(self, md, md_globals):
42-
del md.preprocessors['html_block']
43-
del md.inlinePatterns['html']
40+
from markdown.extensions import Extension
4441

45-
html = markdown.markdown(text, extensions=[EscapeHtml()])
42+
class EscapeHtml(Extension):
43+
def extendMarkdown(self, md, md_globals):
44+
del md.preprocessors['html_block']
45+
del md.inlinePatterns['html']
4646

47-
As the HTML would not be parsed with the above Extension, then the serializer will
48-
escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
47+
html = markdown.markdown(text, extensions=[EscapeHtml()])
48+
49+
As the HTML would not be parsed with the above Extension, then the serializer will
50+
escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.
4951

5052
[Bleach]: http://bleach.readthedocs.org/
5153

52-
* Positional arguments on the `markdown.Markdown()` class are deprecated as are
53-
all except the `text` argument on the `markdown.markdown()` wrapper function.
54-
Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an error
55-
in version 2.7. Only keyword arguments should be used. For example, if your code
56-
previously looked like this:
54+
### Positional Arguments Deprecated
55+
56+
Positional arguments on the `markdown.Markdown()` class are deprecated as are
57+
all except the `text` argument on the `markdown.markdown()` wrapper function.
58+
Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an error
59+
in version 2.7. Only keyword arguments should be used. For example, if your code
60+
previously looked like this:
61+
62+
html = markdown.markdown(text, [SomeExtension()])
63+
64+
Then it is recommended that you change it to read something like this:
65+
66+
html = markdown.markdown(text, extensions=[SomeExtension()])
67+
68+
!!! Note
69+
This change is being made as a result of deprecating `"safe_mode"` as the
70+
`safe_mode` argument was one of the positional arguments. When that argument
71+
is removed, the two arguments following it will no longer be at the correct
72+
position. It is recommended that you always use keywords when they are supported
73+
for this reason.
74+
75+
### "Shortened" Extension Names Deprecated
76+
77+
In previous versions of Python-Markdown, the built-in extensions received
78+
special status and did not require the full path to be provided. Additionally,
79+
third party extensions whose name started with `"mdx_"` received the same
80+
special treatment. This behavior is deprecated and will raise a
81+
**`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you
82+
always use the full path to your extensions. For example, if you previously
83+
did the following:
84+
85+
markdown.markdown(text, extensions=['extra'])
5786

58-
html = markdown.markdown(text, [SomeExtension()])
59-
60-
Then it is recommended that you change it to read something like this:
87+
You should change your code to the following:
6188

62-
html = markdown.markdown(text, extensions=[SomeExtension()])
89+
markdown.markdown(text, extensions=['markdown.extensions.extra'])
6390

64-
!!! Note
65-
This change is being made as a result of deprecating `"safe_mode"` as the
66-
`safe_mode` argument was one of the positional arguments. When that argument
67-
is removed, the two arguments following it will no longer be at the correct
68-
position. It is recommended that you always use keywords when they are supported
69-
for this reason.
91+
The same applies to the command line:
7092

71-
* In previous versions of Python-Markdown, the built-in extensions received
72-
special status and did not require the full path to be provided. Additionally,
73-
third party extensions whose name started with `"mdx_"` received the same
74-
special treatment. This behavior is deprecated and will raise a
75-
**`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you
76-
always use the full path to your extensions. For example, if you previously
77-
did the following:
93+
$ python -m markdown -x markdown.extensions.extra input.txt
7894

79-
markdown.markdown(text, extensions=['extra'])
95+
Similarly, if you have used a third party extension (eg: `mdx_math`), previously
96+
you might have called it like this:
8097

81-
You should change your code to the following:
98+
markdown.markdown(text, extensions=['math'])
8299

83-
markdown.markdown(text, extensions=['markdown.extensions.extra'])
100+
As the `"mdx"` prefix will no longer be appended, you will need to change your code
101+
as follows (assuming the file `mdx_math.py` is installed at the root of your PYTHONPATH):
84102

85-
The same applies to the command line:
103+
markdown.markdown(text, extensions=['mdx_math'])
86104

87-
$ python -m markdown -x markdown.extensions.extra input.txt
105+
Extension authors will want to update their documentation to reflect the new behavior.
88106

89-
See the [documentation](reference.html#extensions) for a full explanation
90-
of the current behavior.
107+
See the [documentation](reference.html#extensions) for a full explanation
108+
of the current behavior.
91109

92-
* The previously documented method of appending the extension configuration options as
93-
a string to the extension name is deprecated and will raise a
94-
**`DeprecationWarning`** in version 2.6 and an error in 2.7.
95-
The [`extension_configs`](reference.html#extension_configs) keyword should
96-
be used instead. See the [documentation](reference.html#extension-configs)
97-
for a full explanation of the current behavior.
110+
### Extension Configs as Part of Extension Name Deprecated
98111

99-
* The [HeaderId][hid] Extension is pending deprecation and will raise a
100-
**`PendingDeprecationWarning`** in version 2.6. The extension will be
101-
deprecated in version 2.7 and raise an error in version 2.8. Use the
102-
[Table of Contents][TOC] Extension instead, which offers most of the
103-
features of the HeaderId Extension and more (support for meta data is missing).
104-
105-
Extension authors who have been using the `slugify` and `unique` functions
106-
defined in the HeaderId Extension should note that those functions are now
107-
defined in the Table of Contents extension and should adjust their import
108-
statements accordingly (`from markdown.extensions.toc import slugify, unique`).
112+
The previously documented method of appending the extension configuration options as
113+
a string to the extension name is deprecated and will raise a
114+
**`DeprecationWarning`** in version 2.6 and an error in 2.7.
115+
The [`extension_configs`](reference.html#extension_configs) keyword should
116+
be used instead. See the [documentation](reference.html#extension-configs)
117+
for a full explanation of the current behavior.
118+
119+
### HeaderId Extension Pending Deprecation
120+
121+
The [HeaderId][hid] Extension is pending deprecation and will raise a
122+
**`PendingDeprecationWarning`** in version 2.6. The extension will be
123+
deprecated in version 2.7 and raise an error in version 2.8. Use the
124+
[Table of Contents][TOC] Extension instead, which offers most of the
125+
features of the HeaderId Extension and more (support for meta data is missing).
126+
127+
Extension authors who have been using the `slugify` and `unique` functions
128+
defined in the HeaderId Extension should note that those functions are now
129+
defined in the Table of Contents extension and should adjust their import
130+
statements accordingly (`from markdown.extensions.toc import slugify, unique`).
109131

110132
[hid]: extensions/header_id.html
111133

112-
* Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class
113-
(and its subclasses) are deprecated. Each individual configuration option should be passed
114-
to the class as a keyword/value pair. For example. one might have previously initiated
115-
an extension subclass like this:
116-
117-
ext = SomeExtension(configs={'somekey': 'somevalue'})
118-
119-
That code should be updated to pass in the options directly:
120-
121-
ext = SomeExtension(somekey='somevalue')
122-
123-
Extension authors will want to note that this affects the `makeExtension` function as well.
124-
Previously it was common for the function to be defined as follows:
125-
126-
def makeExtension(configs=None):
127-
return SomeExtension(configs=configs)
128-
129-
Extension authors will want to update their code to the following instead:
130-
131-
def makeExtension(**kwargs):
132-
return SomeExtension(**kwargs)
133-
134-
Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next
135-
release. See the [Extension API][mext] documentation for more information.
136-
137-
In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method
138-
and implements its own configuration handling, then the above may not apply. However, it is
139-
recommended that the subclass still calls the parent `__init__` method to handle configuration
140-
options like so:
141-
142-
class SomeExtension(markdown.extension.Extension):
143-
def __init__(**kwargs):
144-
# Do pre-config stuff here
145-
# Set config defaults
146-
self.config = {
147-
'option1' : ['value1', 'description1'],
148-
'option2' : ['value2', 'description2']
149-
}
150-
# Set user defined configs
151-
super(MyExtension, self).__init__(**kwargs)
152-
# Do post-config stuff here
153-
154-
Note the call to `super` to get the benefits of configuration handling from the parent class.
155-
See the [documentation][config] for more information.
134+
### `configs` Keyword Deprecated
135+
136+
Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class
137+
(and its subclasses) are deprecated. Each individual configuration option should be passed
138+
to the class as a keyword/value pair. For example. one might have previously initiated
139+
an extension subclass like this:
140+
141+
ext = SomeExtension(configs={'somekey': 'somevalue'})
142+
143+
That code should be updated to pass in the options directly:
144+
145+
ext = SomeExtension(somekey='somevalue')
146+
147+
Extension authors will want to note that this affects the `makeExtension` function as well.
148+
Previously it was common for the function to be defined as follows:
149+
150+
def makeExtension(configs=None):
151+
return SomeExtension(configs=configs)
152+
153+
Extension authors will want to update their code to the following instead:
154+
155+
def makeExtension(**kwargs):
156+
return SomeExtension(**kwargs)
157+
158+
Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next
159+
release. See the [Extension API][mext] documentation for more information.
160+
161+
In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method
162+
and implements its own configuration handling, then the above may not apply. However, it is
163+
recommended that the subclass still calls the parent `__init__` method to handle configuration
164+
options like so:
165+
166+
class SomeExtension(markdown.extension.Extension):
167+
def __init__(**kwargs):
168+
# Do pre-config stuff here
169+
# Set config defaults
170+
self.config = {
171+
'option1' : ['value1', 'description1'],
172+
'option2' : ['value2', 'description2']
173+
}
174+
# Set user defined configs
175+
super(MyExtension, self).__init__(**kwargs)
176+
# Do post-config stuff here
177+
178+
Note the call to `super` to get the benefits of configuration handling from the parent class.
179+
See the [documentation][config] for more information.
156180

157181
[config]: extensions/api.html#configsettings
158182
[mext]: extensions/api.html#makeextension
159183

160184
What's New in Python-Markdown 2.6
161185
---------------------------------
162186

163-
* Official support for [PyPy] has been added. While Python-Markdown has most likely
187+
### Official Support for PyPy
188+
189+
Official support for [PyPy] has been added. While Python-Markdown has most likely
164190
worked on PyPy for some time, it is now officially supported and tested on PyPy.
165191

166192
[PyPy]: http://pypy.org/
167193

168-
* The [Meta-Data] Extension now includes optional support for [YAML] style
169-
meta-data. By default, the YAML deliminators are recognized, however, the
170-
actual data is parsed as previously. This follows the syntax of
171-
[MultiMarkdown], which inspired this extension.
194+
### YAML Style Meta-Data
195+
196+
The [Meta-Data] Extension now includes optional support for [YAML] style
197+
meta-data. By default, the YAML deliminators are recognized, however, the
198+
actual data is parsed as previously. This follows the syntax of
199+
[MultiMarkdown], which inspired this extension.
172200

173-
Alternatively, if the `yaml` option is set, then the data is parsed as YAML.
201+
Alternatively, if the `yaml` option is set, then the data is parsed as YAML.
174202

175203
[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata
176204
[Meta-Data]: extensions/meta_data.html
177205
[YAML]: http://yaml.org/
178206

179-
* The [Table of Contents][TOC] Extension has been refactored and some new features
180-
have been added. See the documentation for a full explanation of each feature
181-
listed below:
182-
183-
* The extension now assigns the Table of Contents to the `toc` attribute of
184-
the Markdown class regardless of whether a "marker" was found in the document.
185-
Third party frameworks no longer need to insert a "marker," run the document
186-
through Markdown, then extract the Table of Contents from the document.
187-
188-
* The Table of Contents Extension is now a "registered extension." Therefore, when the `reset`
189-
method of the Markdown class is called, the `toc` attribute on the Markdown
190-
class is cleared (set to an empty string).
191-
192-
* When the `marker` configuration option is set to an empty string, the parser completely
193-
skips the process of searching the document for markers. This should save parsing
194-
time when the Table of Contents Extension is being used only to assign ids to headers.
195-
196-
* A `separator` configuration option has been added allowing users to override the
197-
separator character used by the slugify function.
198-
199-
* A `baselevel` configuration option has been added allowing users to set the base level
200-
of headers in their documents (h1-h6). This allows the header levels to be
201-
automatically adjusted to fit within the hierarchy of an HTML template.
207+
### TOC Extension Refactored
208+
209+
The [Table of Contents][TOC] Extension has been refactored and some new features
210+
have been added. See the documentation for a full explanation of each feature
211+
listed below:
212+
213+
* The extension now assigns the Table of Contents to the `toc` attribute of
214+
the Markdown class regardless of whether a "marker" was found in the document.
215+
Third party frameworks no longer need to insert a "marker," run the document
216+
through Markdown, then extract the Table of Contents from the document.
217+
218+
* The Table of Contents Extension is now a "registered extension." Therefore, when the `reset`
219+
method of the Markdown class is called, the `toc` attribute on the Markdown
220+
class is cleared (set to an empty string).
221+
222+
* When the `marker` configuration option is set to an empty string, the parser completely
223+
skips the process of searching the document for markers. This should save parsing
224+
time when the Table of Contents Extension is being used only to assign ids to headers.
225+
226+
* A `separator` configuration option has been added allowing users to override the
227+
separator character used by the slugify function.
228+
229+
* A `baselevel` configuration option has been added allowing users to set the base level
230+
of headers in their documents (h1-h6). This allows the header levels to be
231+
automatically adjusted to fit within the hierarchy of an HTML template.
202232

203233
[TOC]: extensions/toc.html
204234

205-
* The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`.
206-
The option is `True` by default, however, it allows one to turn off Pygments code
207-
highlighting (set to `False`) while preserving the language detection features of
208-
the extension. Note that Pygments language guessing is not used as that would 'use
209-
Pygments'. If a language is defined for a code block, it will be assigned to the
210-
`<code>` tag as a class in the manner suggested by the [HTML5 spec][spec]
211-
(alternate output will not be entertained) and could potentially be used by a JavaScript
212-
library in the browser to highlight the code block.
235+
### Pygments can now be disabled
236+
237+
The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`.
238+
The option is `True` by default, however, it allows one to turn off Pygments code
239+
highlighting (set to `False`) while preserving the language detection features of
240+
the extension. Note that Pygments language guessing is not used as that would 'use
241+
Pygments'. If a language is defined for a code block, it will be assigned to the
242+
`<code>` tag as a class in the manner suggested by the [HTML5 spec][spec]
243+
(alternate output will not be entertained) and could potentially be used by a JavaScript
244+
library in the browser to highlight the code block.
213245

214246
[ch]: extensions/code_hilite.html
215247
[spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element
216248

217-
* Test coverage has been improved including running [flake8]. While those changes
218-
will not directly effect end users, the code is being better tested which will
219-
benefit everyone.
249+
### Miscellaneous
250+
251+
Test coverage has been improved including running [flake8]. While those changes
252+
will not directly effect end users, the code is being better tested which will
253+
benefit everyone.
220254

221255
[flake8]: http://flake8.readthedocs.org/en/latest/
222256

223-
* Various bug fixes have been made. See the
224-
[commit log](https://github.com/waylan/Python-Markdown/commits/master)
225-
for a complete history of the changes.
257+
Various bug fixes have been made. See the
258+
[commit log](https://github.com/waylan/Python-Markdown/commits/master)
259+
for a complete history of the changes.

0 commit comments

Comments
 (0)