diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/release-2.6.txt | 342 |
1 files changed, 188 insertions, 154 deletions
diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt index 0a95780..f222d6c 100644 --- a/docs/release-2.6.txt +++ b/docs/release-2.6.txt @@ -15,144 +15,168 @@ Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as w Backwards-incompatible Changes ------------------------------ -* Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated - in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and - `html_replacement_text` keywords will be ignored in version 2.7. 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. +### `safe_mode` Deprecated - If your code previously looked like this: +Both `safe_mode` and the associated `html_replacement_text` keywords are deprecated +in version 2.6 and will raise a **`DeprecationWarning`**. The `safe_mode` and +`html_replacement_text` keywords will be ignored in version 2.7. 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. - html = markdown.markdown(text, safe_mode=True) +If your code previously looked like this: - Then it is recommended that you change your code to read something like this: + html = markdown.markdown(text, safe_mode=True) - import bleach - html = bleach.clean(markdown.markdown(text)) +Then it is recommended that you change your code to read something like this: - 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: + import bleach + html = bleach.clean(markdown.markdown(text)) - from markdown.extensions import Extension +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: - class EscapeHtml(Extension): - def extendMarkdown(self, md, md_globals): - del md.preprocessors['html_block'] - del md.inlinePatterns['html'] + from markdown.extensions import Extension - html = markdown.markdown(text, extensions=[EscapeHtml()]) + class EscapeHtml(Extension): + def extendMarkdown(self, md, md_globals): + del md.preprocessors['html_block'] + del md.inlinePatterns['html'] - 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"`. + 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]: http://bleach.readthedocs.org/ -* Positional arguments on the `markdown.Markdown()` class are deprecated as are - all except the `text` argument on the `markdown.markdown()` wrapper function. - Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an error - in version 2.7. Only keyword arguments should be used. For example, if your code - previously looked like this: +### Positional Arguments Deprecated + +Positional arguments on the `markdown.Markdown()` class are deprecated as are +all except the `text` argument on the `markdown.markdown()` wrapper function. +Using positional arguments will raise a **`DeprecationWarning`** in 2.6 and an error +in version 2.7. Only keyword arguments should be used. For example, if your code +previously looked like this: + + html = markdown.markdown(text, [SomeExtension()]) + +Then it is recommended that you change it to read something like this: + + html = markdown.markdown(text, extensions=[SomeExtension()]) + +!!! 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. + +### "Shortened" Extension Names Deprecated + +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 is deprecated and will raise a +**`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you +always use the full path to your extensions. For example, if you previously +did the following: + + markdown.markdown(text, extensions=['extra']) - html = markdown.markdown(text, [SomeExtension()]) - - Then it is recommended that you change it to read something like this: +You should change your code to the following: - html = markdown.markdown(text, extensions=[SomeExtension()]) + markdown.markdown(text, extensions=['markdown.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. +The same applies to the command line: -* 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 is deprecated and will raise a - **`DeprecationWarning`** in version 2.6 and an error in 2.7. Ensure that you - always use the full path to your extensions. For example, if you previously - did the following: + $ python -m markdown -x markdown.extensions.extra input.txt - markdown.markdown(text, extensions=['extra']) +Similarly, if you have used a third party extension (eg: `mdx_math`), previously +you might have called it like this: - You should change your code to the following: + markdown.markdown(text, extensions=['math']) - markdown.markdown(text, extensions=['markdown.extensions.extra']) +As the `"mdx"` prefix will no longer be appended, you will need to change your code +as follows (assuming the file `mdx_math.py` is installed at the root of your PYTHONPATH): - The same applies to the command line: + markdown.markdown(text, extensions=['mdx_math']) - $ python -m markdown -x markdown.extensions.extra input.txt +Extension authors will want to update their documentation to reflect the new behavior. - See the [documentation](reference.html#extensions) for a full explanation - of the current behavior. +See the [documentation](reference.html#extensions) for a full explanation +of the current behavior. -* The previously documented method of appending the extension configuration options as - a string to the extension name is deprecated and will raise a - **`DeprecationWarning`** in version 2.6 and an error in 2.7. - 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. +### Extension Configs as Part of Extension Name Deprecated -* The [HeaderId][hid] Extension is pending deprecation and will raise a - **`PendingDeprecationWarning`** in version 2.6. The extension will be - deprecated in version 2.7 and raise an error in version 2.8. Use the - [Table of Contents][TOC] Extension instead, which offers most of the - features of the HeaderId Extension and more (support for meta data is missing). - - Extension authors who have been using the `slugify` and `unique` functions - defined in the HeaderId Extension should note that those functions are now - defined in the Table of Contents extension and should adjust their import - statements accordingly (`from markdown.extensions.toc import slugify, unique`). +The previously documented method of appending the extension configuration options as +a string to the extension name is deprecated and will raise a +**`DeprecationWarning`** in version 2.6 and an error in 2.7. +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. + +### HeaderId Extension Pending Deprecation + +The [HeaderId][hid] Extension is pending deprecation and will raise a +**`PendingDeprecationWarning`** in version 2.6. The extension will be +deprecated in version 2.7 and raise an error in version 2.8. Use the +[Table of Contents][TOC] Extension instead, which offers most of the +features of the HeaderId Extension and more (support for meta data is missing). + +Extension authors who have been using the `slugify` and `unique` functions +defined in the HeaderId Extension should note that those functions are now +defined in the Table of Contents extension and should adjust their import +statements accordingly (`from markdown.extensions.toc import slugify, unique`). [hid]: extensions/header_id.html -* Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class - (and its subclasses) are deprecated. Each individual configuration option should be passed - to the class as a keyword/value pair. For example. one might have previously initiated - an extension subclass like this: - - ext = SomeExtension(configs={'somekey': 'somevalue'}) - - That code should be updated to pass in the options directly: - - ext = SomeExtension(somekey='somevalue') - - Extension authors will want to note that this affects the `makeExtension` function as well. - Previously it was common for the function to be defined as follows: - - def makeExtension(configs=None): - return SomeExtension(configs=configs) - - Extension authors will want to update their code to the following instead: - - def makeExtension(**kwargs): - return SomeExtension(**kwargs) - - Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next - release. See the [Extension API][mext] documentation for more information. - - In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method - and implements its own configuration handling, then the above may not apply. However, it is - recommended that the subclass still calls the parent `__init__` method to handle configuration - options like so: - - class SomeExtension(markdown.extension.Extension): - def __init__(**kwargs): - # Do pre-config stuff here - # Set config defaults - self.config = { - 'option1' : ['value1', 'description1'], - 'option2' : ['value2', 'description2'] - } - # Set user defined configs - super(MyExtension, self).__init__(**kwargs) - # Do post-config stuff here - - Note the call to `super` to get the benefits of configuration handling from the parent class. - See the [documentation][config] for more information. +### `configs` Keyword Deprecated + +Positional arguments and the `configs` keyword on the `markdown.extension.Extension` class +(and its subclasses) are deprecated. Each individual configuration option should be passed +to the class as a keyword/value pair. For example. one might have previously initiated +an extension subclass like this: + + ext = SomeExtension(configs={'somekey': 'somevalue'}) + +That code should be updated to pass in the options directly: + + ext = SomeExtension(somekey='somevalue') + +Extension authors will want to note that this affects the `makeExtension` function as well. +Previously it was common for the function to be defined as follows: + + def makeExtension(configs=None): + return SomeExtension(configs=configs) + +Extension authors will want to update their code to the following instead: + + def makeExtension(**kwargs): + return SomeExtension(**kwargs) + +Failing to do so will result in a **`DeprecationWarning`** and will raise an error in the next +release. See the [Extension API][mext] documentation for more information. + +In the event that an `markdown.extension.Extension` subclass overrides the `__init__` method +and implements its own configuration handling, then the above may not apply. However, it is +recommended that the subclass still calls the parent `__init__` method to handle configuration +options like so: + + class SomeExtension(markdown.extension.Extension): + def __init__(**kwargs): + # Do pre-config stuff here + # Set config defaults + self.config = { + 'option1' : ['value1', 'description1'], + 'option2' : ['value2', 'description2'] + } + # Set user defined configs + super(MyExtension, self).__init__(**kwargs) + # Do post-config stuff here + +Note the call to `super` to get the benefits of configuration handling from the parent class. +See the [documentation][config] for more information. [config]: extensions/api.html#configsettings [mext]: extensions/api.html#makeextension @@ -160,66 +184,76 @@ Backwards-incompatible Changes What's New in Python-Markdown 2.6 --------------------------------- -* Official support for [PyPy] has been added. While Python-Markdown has most likely +### Official Support for PyPy + +Official support for [PyPy] has been added. While Python-Markdown has most likely worked on PyPy for some time, it is now officially supported and tested on PyPy. [PyPy]: http://pypy.org/ -* The [Meta-Data] Extension now includes optional support for [YAML] style - meta-data. By default, the YAML deliminators are recognized, however, the - actual data is parsed as previously. This follows the syntax of - [MultiMarkdown], which inspired this extension. +### YAML Style Meta-Data + +The [Meta-Data] Extension now includes optional support for [YAML] style +meta-data. By default, the YAML deliminators are recognized, however, the +actual data is parsed as previously. This follows the syntax of +[MultiMarkdown], which inspired this extension. - Alternatively, if the `yaml` option is set, then the data is parsed as YAML. +Alternatively, if the `yaml` option is set, then the data is parsed as YAML. [MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata [Meta-Data]: extensions/meta_data.html [YAML]: http://yaml.org/ -* The [Table of Contents][TOC] Extension has been refactored and some new features - have been added. See the documentation for a full explanation of each feature - listed below: - - * The extension now assigns the Table of Contents to the `toc` attribute of - the Markdown class regardless of whether a "marker" was found in the document. - Third party frameworks no longer need to insert a "marker," run the document - through Markdown, then extract the Table of Contents from the document. - - * The Table of Contents Extension is now a "registered extension." Therefore, when the `reset` - method of the Markdown class is called, the `toc` attribute on the Markdown - class is cleared (set to an empty string). - - * When the `marker` configuration option is set to an empty string, the parser completely - skips the process of searching the document for markers. This should save parsing - time when the Table of Contents Extension is being used only to assign ids to headers. - - * A `separator` configuration option has been added allowing users to override the - separator character used by the slugify function. - - * A `baselevel` configuration option has been added allowing users to set the base level - of headers in their documents (h1-h6). This allows the header levels to be - automatically adjusted to fit within the hierarchy of an HTML template. +### TOC Extension Refactored + +The [Table of Contents][TOC] Extension has been refactored and some new features +have been added. See the documentation for a full explanation of each feature +listed below: + +* The extension now assigns the Table of Contents to the `toc` attribute of + the Markdown class regardless of whether a "marker" was found in the document. + Third party frameworks no longer need to insert a "marker," run the document + through Markdown, then extract the Table of Contents from the document. + +* The Table of Contents Extension is now a "registered extension." Therefore, when the `reset` + method of the Markdown class is called, the `toc` attribute on the Markdown + class is cleared (set to an empty string). + +* When the `marker` configuration option is set to an empty string, the parser completely + skips the process of searching the document for markers. This should save parsing + time when the Table of Contents Extension is being used only to assign ids to headers. + +* A `separator` configuration option has been added allowing users to override the + separator character used by the slugify function. + +* A `baselevel` configuration option has been added allowing users to set the base level + of headers in their documents (h1-h6). This allows the header levels to be + automatically adjusted to fit within the hierarchy of an HTML template. [TOC]: extensions/toc.html -* The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`. - The option is `True` by default, however, it allows one to turn off Pygments code - highlighting (set to `False`) while preserving the language detection features of - the extension. Note that Pygments language guessing is not used as that would 'use - Pygments'. If a language is defined for a code block, it will be assigned to the - `<code>` tag as a class in the manner suggested by the [HTML5 spec][spec] - (alternate output will not be entertained) and could potentially be used by a JavaScript - library in the browser to highlight the code block. +### Pygments can now be disabled + +The [CodeHilite][ch] Extension has gained a new configuration option: `use_pygments`. +The option is `True` by default, however, it allows one to turn off Pygments code +highlighting (set to `False`) while preserving the language detection features of +the extension. Note that Pygments language guessing is not used as that would 'use +Pygments'. If a language is defined for a code block, it will be assigned to the +`<code>` tag as a class in the manner suggested by the [HTML5 spec][spec] +(alternate output will not be entertained) and could potentially be used by a JavaScript +library in the browser to highlight the code block. [ch]: extensions/code_hilite.html [spec]: http://www.w3.org/TR/html5/text-level-semantics.html#the-code-element -* Test coverage has been improved including running [flake8]. While those changes - will not directly effect end users, the code is being better tested which will - benefit everyone. +### Miscellaneous + +Test coverage has been improved including running [flake8]. While those changes +will not directly effect end users, the code is being better tested which will +benefit everyone. [flake8]: http://flake8.readthedocs.org/en/latest/ -* 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. +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. |