summaryrefslogtreecommitdiff
path: root/docs/release-2.5.txt
blob: 6f3812269bd9aaa9204cd1f9fd059a7f94201d56 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
title:      Release Notes for v2.5
prev_title: Release Notes for v2.6
prev_url:   release-2.6.html
next_title: Release Notes for v2.4
next_url:   release-2.4.html

Python-Markdown 2.5 Release Notes
=================================

We are pleased to release Python-Markdown 2.5 which adds a few new features
and fixes various bugs. See the list of changes below for details.

Python-Markdown version 2.5 supports Python versions 2.7, 3.2, 3.3, and 3.4.

Backwards-incompatible Changes
------------------------------

* Python-Markdown no longer supports Python version 2.6. You must be using Python 
  versions 2.7, 3.2, 3.3, or 3.4.

[importlib]: https://pypi.python.org/pypi/importlib

* The `force_linenos` configuration key on the [CodeHilite Extension] has been **deprecated**
  and will raise a `KeyError` if provided. In the previous release (2.4), it was 
  issuing a `DeprecationWarning`. The [`linenums`][linenums] keyword should be used 
  instead, which provides more control of the output.

[CodeHilite Extension]: extensions/code_hilite.html
[linenums]: extensions/code_hilite.html#usage

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

    If your code previously looked like this:

	    html = markdown.markdown(text, same_mode=True)

	Then it is recommended that you change your code to read something like this:

	    import bleach
        html = bleach.clean(markdown.markdown(text))

	If you are not interested in sanitizing untrusted text, but simply desire to escape
	raw HTML, then that can be accomplished through an extension which removes HTML parsing:

		from markdown.extensions import Extension

		class EscapeHtml(Extension):
			def extendMarkdown(self, md, md_globals):
				del md.preprocessors['html_block']
				del md.inlinePatterns['html']

		html = markdown.markdown(text, extensions=[EscapeHtml()])

	As the HTML would not be parsed with the above Extension, then the serializer will
	escape the raw HTML, which is exactly what happens now when `safe_mode="escape"`.

[Bleach]: https://bleach.readthedocs.io/

* Positional arguments on the `markdown.Markdown()` are pending deprecation as are
  all except the `text` argument on the `markdown.markdown()` wrapper function.
  Only keyword arguments should be used. For example, if your code previously
  looked like this:

         html = markdown.markdown(text, ['extra'])
    
	Then it is recommended that you change it to read something like this:

	    html = markdown.markdown(text, extensions=['extra'])

	!!! Note
	    This change is being made as a result of deprecating `"safe_mode"` as the 
		`safe_mode` argument was one of the positional arguments. When that argument 
		is removed, the two arguments following it will no longer be at the correct 
		position. It is recommended that you always use keywords when they are supported
		for this reason.

* In previous versions of Python-Markdown, the built-in extensions received
  special status and did not require the full path to be provided. Additionally,
  third party extensions whose name started with `"mdx_"` received the same 
  special treatment. This behavior will be deprecated in version 2.6 and will
  raise a **`PendingDeprecationWarning`** in 2.5. Ensure that you always use the full 
  path to your extensions. For example, if you previously did the following:

        markdown.markdown(text, extensions=['extra'])

    You should change your code to the following:

	    markdown.markdown(text, extensions=['markdown.extensions.extra'])

    The same applies to the command line:

        $ python -m markdown -x markdown.extensions.extra input.txt

    See the [documentation](reference.html#extensions) for a full explanation
    of the current behavior.

* The previously documented method of appending the extension configuration as 
  a string to the extension name will be deprecated in Python-Markdown 
  version 2.6 and will raise a **`PendingDeprecationWarning`** in 2.5. The 
  [`extension_configs`](reference.html#extension_configs) keyword should 
  be used instead. See the [documentation](reference.html#extension-configs) 
  for a full explanation of the current behavior.

What's New in Python-Markdown 2.5
---------------------------------

*   The [Smarty Extension] has had a number of additional configuration settings
    added, which allows one to define their own substitutions to better support
    languages other than English. Thanks to [Martin Altmayer] for implementing this 
	feature.

[Smarty Extension]: extensions/smarty.html
[Martin Altmayer]:https://github.com/MartinAltmayer

*   Named Extensions (strings passed to the [`extensions`][ex] keyword of 
    `markdown.Markdown`) can now point to any module and/or Class on your PYTHONPATH. 
	While dot notation was previously supported, a module could not be at the root of 
	your PYTHONPATH. The name had to contain at least one dot (requiring it to be a 
	sub-module). This restriction no longer exists. 

	Additionally, a Class may be specified in the name. The class must be at the end of 
	the name (which uses dot notation from PYTHONPATH) and be separated by a colon from 
	the module. 

	Therefore, if you were to import the class like this:
	
		from path.to.module import SomeExtensionClass

	Then the named extension would comprise this string:

		"path.to.module:SomeExtensionClass"
	
	This allows multiple extensions to be implemented within the same module and still 
	accessible when the user is not able to import the extension directly (perhaps from 
	a template filter or the command line).

	This also means that extension modules are no longer required to include the 
	`makeExtension`	function which returns an instance of the extension class. However, 
	if the user does not specify the class name (she only provides `"path.to.module"`)
	the extension will fail to load without the `makeExtension` function included in
	the module. Extension authors will want to document carefully what is required to
	load their extensions.

[ex]: reference.html#extensions

*   The Extension Configuration code has been refactored to make it a little easier 
    for extension authors to work with configuration settings. As a result, the 
    [`extension_configs`][ec] keyword now accepts a dictionary rather than requiring 
    a list of tuples. A list of tuples is still supported so no one needs to change 
    their existing code. This should also simplify the learning curve for new users.

	Extension authors are encouraged to review the new methods available on the 
	`markdown.extnesions.Extension` class for handling configuration and adjust their
	code going forward. The included extensions provide a model for best practices.
	See the [API] documentation for a full explanation.

[ec]: reference.html#extension_configs
[API]: extensions/api.html#configsettings

*   The [Command Line Interface][cli] now accepts a `--extensions_config` (or `-c`) 
    option which accepts a file name and passes the parsed content of a [YAML] or 
	[JSON]   file to the [`extension_configs`][ec] keyword of the `markdown.Markdown`
	class. The contents of the YAML or JSON must map to a Python Dictionary which 
	matches the format required by the `extension_configs` keyword. Note that 
	[PyYAML] is required to parse YAML files.

[cli]: cli.html#using-extensions
[YAML]: http://yaml.org/
[JSON]: http://json.org/
[PyYAML]: http://pyyaml.org/

*   The [admonition extension][ae] is no longer considered "experimental."

[ae]: extensions/admonition.html

*   There have been various refactors of the testing framework. While those changes
    will not directly effect end users, the code is being better tested which will 
    benefit everyone.

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