aboutsummaryrefslogtreecommitdiffstats
path: root/docs/extensions/api.txt
diff options
context:
space:
mode:
authorWaylan Limberg <waylan.limberg@icloud.com>2014-08-01 21:43:53 -0400
committerWaylan Limberg <waylan.limberg@icloud.com>2014-08-01 21:43:53 -0400
commitcc3405c29c975bc4a056fde274df6d08e58e43e4 (patch)
tree34c2ba1e7cac27a20d03b0321fa656987a018ef0 /docs/extensions/api.txt
parent2649f81cc23cf9c6f3c597adf2807e60ee6fd9ff (diff)
downloadmarkdown-cc3405c29c975bc4a056fde274df6d08e58e43e4.tar.gz
markdown-cc3405c29c975bc4a056fde274df6d08e58e43e4.tar.bz2
markdown-cc3405c29c975bc4a056fde274df6d08e58e43e4.zip
Updated extension API docs for Extension.__init__ refactor
Relates to #325.
Diffstat (limited to 'docs/extensions/api.txt')
-rw-r--r--docs/extensions/api.txt27
1 files changed, 18 insertions, 9 deletions
diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt
index 715df6d..d11c534 100644
--- a/docs/extensions/api.txt
+++ b/docs/extensions/api.txt
@@ -550,10 +550,13 @@ If an extension uses any parameters that the user may want to change,
those parameters should be stored in ``self.config`` of your
``markdown.Extension`` class in the following format:
- self.config = {parameter_1_name : [value1, description1],
- parameter_2_name : [value2, description2] }
+ class MyExtension(markdown.extensions.Extension):
+ def __init__(self, *args, **kwargs):
+ self.config = {parameter_1_name : [value1, description1],
+ parameter_2_name : [value2, description2] }
+ super(MyExtension, self).__init__(*args, **kwargs)
-When stored this way the config parameters can be over-ridden from the
+When implemented this way the config parameters can be over-ridden from the
command line or at the time Markdown is initiated:
markdown.py -x myextension(SOME_PARAM=2) inputfile.txt > output.txt
@@ -573,8 +576,7 @@ For example:
import markdown
import myextension
- configs = {...}
- myext = myextension.MyExtension(configs=configs)
+ myext = myextension.MyExtension(option='value')
md = markdown.Markdown(extensions=[myext])
This is especially useful if you need to implement a large number of extensions
@@ -583,14 +585,21 @@ with more than one residing in a module.
However, for historical reasons, Markdown also accepts "named" third party
extensions. In that case, only one extension can be defined per module
and that extension must define a module-level function called
-`makeExtension` that takes an optional parameter consisting of a dictionary
-of configuration over-rides and returns an instance of the extension. For example:
+`makeExtension` that takes `*args` and `**kwargs`. For example:
class MyExtension(markdown.extensions.Extension)
# Define extension here...
- def makeExtension(configs=None):
- return MyExtension(configs=configs)
+ def makeExtension(*args, **kwargs):
+ return MyExtension(*args, **kwargs)
+
+!!! warning
+ Previous versions of Python-Markdown expected a `config` keyword which contained
+ a dictionary (or list of tuples) of options. To maintain backward compatability,
+ the `config` keyword is given special treatment and you should avoid using "config"
+ as an option name. Additionaly, in some past situations, the `config` dict may have
+ been passed in as a positional argument. Therefore, it is sugegsted that positional
+ arguments be avoided for any othe purpose.
When Markdown is passed the "name" of your extension as a string, it will import
the module and call the `makeExtension` function to initiate your extension.