Revision: 7496
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7496&view=rev
Author: efiring
Date: 2009-08-15 23:51:39 +0000 (Sat, 15 Aug 2009)
Log Message:
-----------
Add docstring.py; I forgot to add it when committing the Coombs patch
Added Paths:
-----------
trunk/matplotlib/lib/matplotlib/docstring.py
Added: trunk/matplotlib/lib/matplotlib/docstring.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/docstring.py
(rev 0)
+++ trunk/matplotlib/lib/matplotlib/docstring.py 2009-08-15 23:51:39 UTC
(rev 7496)
@@ -0,0 +1,112 @@
+from matplotlib import cbook
+
+class Substitution(object):
+ """
+ A decorator to take a function's docstring and perform string
+ substitution on it.
+
+ This decorator should be robust even if func.__doc__ is None
+ (for example, if -OO was passed to the interpreter)
+
+ Usage: construct a docstring.Substitution with a sequence or
+ dictionary suitable for performing substitution; then
+ decorate a suitable function with the constructed object. e.g.
+
+ sub_author_name = Substitution(author='Jason')
+
+ @sub_author_name
+ def some_function(x):
+ "%(author)s wrote this function"
+
+ # note that some_function.__doc__ is now "Jason wrote this function"
+
+ One can also use positional arguments.
+
+ sub_first_last_names = Substitution('Edgar Allen', 'Poe')
+
+ @sub_first_last_names
+ def some_function(x):
+ "%s %s wrote the Raven"
+ """
+ def __init__(self, *args, **kwargs):
+ assert not (args and kwargs), "Only positional or keyword args are
allowed"
+ self.params = args or kwargs
+
+ def __call__(self, func):
+ func.__doc__ = func.__doc__ and func.__doc__ % self.params
+ return func
+
+ def update(self, *args, **kwargs):
+ "Assume self.params is a dict and update it with supplied args"
+ self.params.update(*args, **kwargs)
+
+ @classmethod
+ def from_params(cls, params):
+ """
+ In the case where the params is a mutable sequence (list or dictionary)
+ and it may change before this class is called, one may explicitly use
+ a reference to the params rather than using *args or **kwargs which
will
+ copy the values and not reference them.
+ """
+ result = cls()
+ result.params = params
+ return result
+
+class Appender(object):
+ """
+ A function decorator that will append an addendum to the docstring
+ of the target function.
+
+ This decorator should be robust even if func.__doc__ is None
+ (for example, if -OO was passed to the interpreter).
+
+ Usage: construct a docstring.Appender with a string to be joined to
+ the original docstring. An optional 'join' parameter may be supplied
+ which will be used to join the docstring and addendum. e.g.
+
+ add_copyright = Appender("Copyright (c) 2009", join='\n')
+
+ @add_copyright
+ def my_dog(has='fleas'):
+ "This docstring will have a copyright below"
+ pass
+ """
+ def __init__(self, addendum, join=''):
+ self.addendum = addendum
+ self.join = join
+
+ def __call__(self, func):
+ docitems = [func.__doc__, self.addendum]
+ func.__doc__ = func.__doc__ and ''.join(docitems)
+ return func
+
+def dedent(func):
+ "Dedent a docstring (if present)"
+ func.__doc__ = func.__doc__ and cbook.dedent(func.__doc__)
+ return func
+
+def copy(source):
+ "Copy a docstring from another source function (if present)"
+ def do_copy(target):
+ if source.__doc__:
+ target.__doc__ = source.__doc__
+ return target
+ return do_copy
+
+# create a decorator that will house the various documentation that
+# is reused throughout matplotlib
+interpd = Substitution()
+
+def dedent_interpd(func):
+ """A special case of the interpd that first performs a dedent on
+ the incoming docstring"""
+ return interpd(dedent(func))
+
+def copy_dedent(source):
+ """A decorator that will copy the docstring from the source and
+ then dedent it"""
+ # note the following is ugly because "Python is not a functional
+ # language" - GVR. Perhaps one day, functools.compose will exist.
+ # or perhaps not.
+ # http://mail.python.org/pipermail/patches/2007-February/021687.html
+ return lambda target: dedent(copy(source)(target))
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day
trial. Simplify your report design, integration and deployment - and focus on
what you do best, core application coding. Discover what's new with
Crystal Reports now. http://p.sf.net/sfu/bobj-july
_______________________________________________
Matplotlib-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/matplotlib-checkins
