diff options
Diffstat (limited to 'docs/release-2.6.txt')
| -rw-r--r-- | docs/release-2.6.txt | 263 |
1 files changed, 0 insertions, 263 deletions
diff --git a/docs/release-2.6.txt b/docs/release-2.6.txt deleted file mode 100644 index e450162..0000000 --- a/docs/release-2.6.txt +++ /dev/null @@ -1,263 +0,0 @@ -title: Release Notes for v2.6 -prev_title: Change Log -prev_url: change_log.html -next_title: Release Notes for v2.5 -next_url: release-2.5.html - -Python-Markdown 2.6 Release Notes -================================= - -We are pleased to release Python-Markdown 2.6 which adds a few new features -and fixes various bugs. See the list of changes below for details. - -Python-Markdown version 2.6 supports Python versions 2.7, 3.2, 3.3, and 3.4 as well as PyPy. - -Backwards-incompatible Changes ------------------------------- - -### `safe_mode` Deprecated - -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. - -If your code previously looked like this: - - html = markdown.markdown(text, safe_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 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']) - -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 - -Similarly, if you have used a third party extension (for example `mdx_math`), previously -you might have called it like this: - - markdown.markdown(text, extensions=['math']) - -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): - - markdown.markdown(text, extensions=['mdx_math']) - -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. - -### Extension Configuration as Part of Extension Name Deprecated - -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 - -### The `configs` Keyword is 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 - -What's New in Python-Markdown 2.6 ---------------------------------- - -### 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/ - -### 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. - -<del>Alternatively, if the `yaml` option is set, then the data is parsed as YAML.</del> -<ins>As the `yaml` option was buggy, it was removed in 2.6.1. It is suggested that a third -party extension be used if you want true YAML support. See [Issue #390][#390] for a full -explanation.</ins> - -[MultiMarkdown]: http://fletcherpenney.net/MultiMarkdown_Syntax_Guide#metadata -[Meta-Data]: extensions/meta_data.html -[YAML]: http://yaml.org/ -[#390]: https://github.com/Python-Markdown/markdown/issues/390 - -### Table of Contents 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 - -### 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 - -### 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]: https://flake8.readthedocs.io/en/latest/ - -Various bug fixes have been made. See the -[commit log](https://github.com/Python-Markdown/markdown/commits/master) -for a complete history of the changes. |