aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/cli.txt13
-rw-r--r--docs/reference.txt42
-rw-r--r--docs/release-2.5.txt27
-rw-r--r--markdown/__init__.py33
-rw-r--r--markdown/extensions/__init__.py15
-rw-r--r--tests/test_apis.py20
-rw-r--r--tests/test_extensions.py16
7 files changed, 111 insertions, 55 deletions
diff --git a/docs/cli.txt b/docs/cli.txt
index acad4ff..7741d34 100644
--- a/docs/cli.txt
+++ b/docs/cli.txt
@@ -147,17 +147,14 @@ The `--extension_configs` option will only support YAML config files if [PyYaml]
installed on your system. JSON should work with no additional dependencies. The format
of your config file is automatically detected.
-As an alternative, you may append the extension configs as a string to the extension name
-that is provided to the `-x-` option in the following format:
-
- $ python -m markdown -x "markdown.extensions.footnotes(PLACE_MARKER=~~~~~~~~,UNIQUE_IDS=1)" input.txt
-
-Note that there are no quotes or whitespace in the above format, which severely limits
-how it can be used. For more complex settings, it is suggested that the
-`--extension_configs` option be used.
+!!!warning
+ The previously documented method of appending the extension configs as a string to the
+ extension name will be deprecated in Python-Markdown version 2.6. The `--extension_configs`
+ option should be used instead. See the [2.5 release notes] for more information.
[ec]: reference.html#extension_configs
[YAML]: http://yaml.org/
[JSON]: http://json.org/
[PyYAML]: http://pyyaml.org/
+[2.5 release notes]: release-2.5.txt
diff --git a/docs/reference.txt b/docs/reference.txt
index 033b658..afc3b05 100644
--- a/docs/reference.txt
+++ b/docs/reference.txt
@@ -66,11 +66,12 @@ The following options are available on the `markdown.markdown` function:
The list of extensions may contain instances of extensions and/or strings
of extension names.
- extensions=[MyExtension(), 'path.to.my.ext', 'extra']
+ extensions=[MyExtension(), 'path.to.my.ext']
!!! warning
- The prefered method is to pass in an instance of an extension. The other
- methods may be removed in a future version of Python-Markdown.
+ The prefered method is to pass in an instance of an extension. Strings
+ should only be used when it is impossable to import the Extension Class
+ directly (from the command line or in a template).
When passing in extension instances, each class instance must be a subclass
of `markdown.extensions.Extension` and any configuration options should be
@@ -86,24 +87,27 @@ The following options are available on the `markdown.markdown` function:
If an extension name is provided as a string, the extension must be
importable as a python module on your PYTHONPATH. Python's dot notation is
supported. Therefore, to import the 'extra' extension, one could do
- `extensions=['markdown.extensions.extra']` However, if no dots are provided
- in the string (`extensions=['extra']`) Markdown will first look for the
- module `markdown.extensions.extra` (the built-in extension), then a module
- named `mdx_extra` ('mdx_' will be appended to the beginning of the string)
- at the root of your PYTHONPATH.
+ `extensions=['markdown.extensions.extra']`
- When loading an extension by name (as a string), you may either pass in
- configuration settings to the extension using the
- [extension_configs](#extension_configs) keyword or by appending the
- settings to the name in the following format:
+ Additionaly, a Class may be specified in the name. The class must be at the end of
+ the name and be seperated by a colon from the module.
- extensions=['name(option1=value,option2=value)']
-
- Note that there are no quotes or whitespace in the above format, which
- severely limits how it can be used. For more complex settings, it is
- suggested that an instance of a class be passed in or, if that's not
- possible, the [extension_configs](#extension_configs) keyword
- be used.
+ 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"
+
+ !!! note
+ You should only need to specify the class name if more than one extension is defined
+ within the same module. The extensions that come with Python-Markdown do *not*
+ need to have the class name specified.
+
+ When loading an extension by name (as a string), you may pass in
+ configuration settings to the extension using the
+ [extension_configs](#extension_configs) keyword.
!!! seealso "See Also"
See the documentation of the [Extension API](extensions/api.html) for
diff --git a/docs/release-2.5.txt b/docs/release-2.5.txt
index a81acfd..d45fe24 100644
--- a/docs/release-2.5.txt
+++ b/docs/release-2.5.txt
@@ -31,6 +31,33 @@ Backwards-incompatible Changes
[CodeHilite Extension]: extensions/code_hilite.html
[linenumes]: extensions/code_hilite.html#usage
+* In previous versions of Python-Markdown, the builtin extensions received
+ special status and did not require the full path to be provided. Additionaly,
+ 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 explaination
+ of the current behavior.
+
+* The previously documented method of appending the extension configs 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 explaination of the current behavior.
+
What's New in Python-Markdown 2.5
---------------------------------
diff --git a/markdown/__init__.py b/markdown/__init__.py
index 0fdcd97..6bf84d0 100644
--- a/markdown/__init__.py
+++ b/markdown/__init__.py
@@ -36,6 +36,7 @@ from .__version__ import version, version_info
import codecs
import sys
import logging
+import warnings
import importlib
from . import util
from .preprocessors import build_preprocessors
@@ -161,7 +162,7 @@ class Markdown(object):
"""
for ext in extensions:
if isinstance(ext, util.string_type):
- ext = self.build_extension(ext, configs.get(ext, []))
+ ext = self.build_extension(ext, configs.get(ext, {}))
if isinstance(ext, Extension):
ext.extendMarkdown(self, globals())
logger.info('Successfully loaded extension "%s.%s".'
@@ -173,22 +174,29 @@ class Markdown(object):
return self
- def build_extension(self, ext_name, configs = []):
+ def build_extension(self, ext_name, configs):
"""Build extension by name, then return the module.
The extension name may contain arguments as part of the string in the
following format: "extname(key1=value1,key2=value2)"
"""
-
- # Parse extensions config params (ignore the order)
+
configs = dict(configs)
+
+ # Parse extensions config params (ignore the order)
pos = ext_name.find("(") # find the first "("
if pos > 0:
ext_args = ext_name[pos+1:-1]
ext_name = ext_name[:pos]
pairs = [x.split("=") for x in ext_args.split(",")]
configs.update([(x.strip(), y.strip()) for (x, y) in pairs])
+ warnings.warn('Setting configs in the Named Extension string is pending deprecation. '
+ 'It is recommended that you pass an instance of the extension class to '
+ 'Markdown or use the "extension_configs" keyword. The current behavior '
+ 'will be deprecated in version 2.6 and raise an error in version 2.7. '
+ 'See the Release Notes for Python-Markdown version 2.5 for more info.',
+ PendingDeprecationWarning)
# Get class name (if provided): `path.to.module:ClassName`
ext_name, class_name = ext_name.split(':', 1) if ':' in ext_name else (ext_name, '')
@@ -204,12 +212,25 @@ class Markdown(object):
try:
module = importlib.import_module(module_name)
logger.debug('Successfuly imported extension module "%s".' % module_name)
+ warnings.warn('Using short names for Markdown\'s builtin extensions is pending deprecation. '
+ 'Use the full path to the extension with Python\'s dot notation '
+ '(eg: "%s" instead of "%s"). The current behavior will be deprecated in '
+ 'version 2.6 and raise an error in version 2.7. See the Release Notes for '
+ 'Python-Markdown version 2.5 for more info.' % (module_name, ext_name),
+ PendingDeprecationWarning)
except ImportError:
# Preppend `mdx_` to name
module_name_old_style = '_'.join(['mdx', ext_name])
try:
module = importlib.import_module(module_name_old_style)
logger.debug('Successfuly imported extension module "%s".' % module_name_old_style)
+ warnings.warn('Markdown\'s behavuor of appending "mdx_" to an extension name '
+ 'is pending deprecation. Use the full path to the extension with '
+ 'Python\'s dot notation (eg: "%s" instead of "%s"). The '
+ 'current behavior will be deprecated in version 2.6 and raise an '
+ 'error in version 2.7. See the Release Notes for Python-Markdown '
+ 'version 2.5 for more info.' % (module_name_old_style, ext_name),
+ PendingDeprecationWarning)
except ImportError as e:
message = "Failed loading extension '%s' from '%s', '%s' or '%s'" \
% (ext_name, ext_name, module_name, module_name_old_style)
@@ -218,11 +239,11 @@ class Markdown(object):
if class_name:
# Load given class name from module.
- return getattr(module, class_name)(configs=configs)
+ return getattr(module, class_name)(**configs)
else:
# Expect makeExtension() function to return a class.
try:
- return module.makeExtension(configs=configs)
+ return module.makeExtension(**configs)
except AttributeError as e:
message = e.args[0]
message = "Failed to initiate extension " \
diff --git a/markdown/extensions/__init__.py b/markdown/extensions/__init__.py
index 2751eef..03b2a4c 100644
--- a/markdown/extensions/__init__.py
+++ b/markdown/extensions/__init__.py
@@ -5,6 +5,7 @@ Extensions
from __future__ import unicode_literals
from ..util import parseBoolValue
+import warnings
class Extension(object):
""" Base class for extensions to subclass. """
@@ -25,8 +26,20 @@ class Extension(object):
# (there only ever used to be one so we use arg[0])
if len(args):
self.setConfigs(args[0])
+ warnings.warn('Extension classes accepting positional args is pending Deprecation. '
+ 'Each setting should be passed into the Class as a keyword. Positional '
+ 'args will be deprecated in version 2.6 and raise an error in version '
+ '2.7. See the Release Notes for Python-Markdown version 2.5 for more info.',
+ PendingDeprecationWarning)
# check for configs kwarg for backward compat.
- self.setConfigs(kwargs.pop('configs', {}))
+ if 'configs' in kwargs.keys():
+ self.setConfigs(kwargs.pop('configs', {}))
+ warnings.warn('Extension classes accepting a dict on the single keyword "config" is '
+ 'pending Deprecation. Each setting should be passed into the Class as '
+ 'a keyword directly. The "config" keyword will be deprecated in version '
+ '2.6 and raise an error in version 2.7. See the Release Notes for '
+ 'Python-Markdown version 2.5 for more info.',
+ PendingDeprecationWarning)
# finally, use kwargs
self.setConfigs(kwargs)
diff --git a/tests/test_apis.py b/tests/test_apis.py
index 010bf70..b19db62 100644
--- a/tests/test_apis.py
+++ b/tests/test_apis.py
@@ -303,14 +303,24 @@ class TestErrors(unittest.TestCase):
self.assertRaises(NotImplementedError,
markdown.Markdown, extensions=['fake_c'])
- def testDotSyntaxExtention(self):
- """ Test that dot syntax imports properly (not using mdx_). """
- _create_fake_extension(name='fake_d', use_old_style=False)
- self.assertRaises(NotImplementedError,
+ def testMdxExtention(self):
+ """ Test that appending mdx_ raises a PendingDeprecationWarning. """
+ _create_fake_extension(name='fake_d', use_old_style=True)
+ self.assertRaises(PendingDeprecationWarning,
markdown.Markdown, extensions=['fake_d'])
+ def testShortNameExtention(self):
+ """ Test that using a short name raises a PendingDeprecationWarning. """
+ self.assertRaises(PendingDeprecationWarning,
+ markdown.Markdown, extensions=['footnotes'])
+
+ def testStringConfigExtention(self):
+ """ Test that passing configs to an Extension in the name raises a PendingDeprecationWarning. """
+ self.assertRaises(PendingDeprecationWarning,
+ markdown.Markdown, extensions=['markdown.extension.footnotes(PLACE_MARKER=FOO)'])
+
-def _create_fake_extension(name, has_factory_func=True, is_wrong_type=False, use_old_style=True):
+def _create_fake_extension(name, has_factory_func=True, is_wrong_type=False, use_old_style=False):
""" Create a fake extension module for testing. """
if use_old_style:
mod_name = '_'.join(['mdx', name])
diff --git a/tests/test_extensions.py b/tests/test_extensions.py
index a7be627..a21fd94 100644
--- a/tests/test_extensions.py
+++ b/tests/test_extensions.py
@@ -47,22 +47,6 @@ class TestExtensionClass(unittest.TestCase):
# self.ext.setConfig('bad', 'baz) ==> KeyError
self.assertRaises(KeyError, self.ext.setConfig, 'bad', 'baz')
- def testConfigAsArgListOnInit(self):
- ext = self.ExtKlass([('foo', 'baz'), ('bar', 'blah')])
- self.assertEqual(ext.getConfigs(), {'foo': 'baz', 'bar': 'blah'})
-
- def testConfigAsArgDictOnInit(self):
- ext = self.ExtKlass({'foo': 'baz', 'bar': 'blah', 'bar': 'blah'})
- self.assertEqual(ext.getConfigs(), {'foo': 'baz', 'bar': 'blah'})
-
- def testConfigAsKwargListOnInit(self):
- ext = self.ExtKlass(configs=[('foo', 'baz'), ('bar', 'blah')])
- self.assertEqual(ext.getConfigs(), {'foo': 'baz', 'bar': 'blah'})
-
- def testConfigAsKwargDictOnInit(self):
- ext = self.ExtKlass(configs={'foo': 'baz', 'bar': 'blah'})
- self.assertEqual(ext.getConfigs(), {'foo': 'baz', 'bar': 'blah'})
-
def testConfigAsKwargsOnInit(self):
ext = self.ExtKlass(foo='baz', bar='blah')
self.assertEqual(ext.getConfigs(), {'foo': 'baz', 'bar': 'blah'})