openstack/debtcollector
Code Issues Proposed changes

Add doctested examples into the documentation

Browse Source 
To make it more easy for those to see how to use
this library, start adding some basic examples that
show the common usage patterns.

Change-Id: Ieda04d0c3402cb3d9d7e55ecfd737571520ffbcb
This commit is contained in:
Joshua Harlow 2015-02-06 18:32:45 -08:00
parent b078a94a5b
commit 7e3f6d41d7
3 changed files with 175 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/conf.py
View File

@ -24,6 +24,7 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.doctest',
'oslosphinx',
]

173
doc/source/examples.rst Normal file
View File

@ -0,0 +1,173 @@
========
Examples
========
Moving a method
---------------
To move a *instance* method from an existing one to a new one
the :py:func:`~debtcollector.moves.moved_method` function/decorator can be
used to achieve this in a non-destructive manner.
A basic example to do just this:
.. doctest::
>>> from debtcollector import moves
>>> import warnings
>>> warnings.simplefilter('always')
>>> class Cat(object):
... @moves.moved_method('meow')
... def mewow(self):
... return self.meow()
... def meow(self):
... return 'kitty'
...
>>> c = Cat()
>>> c.mewow()
__main__:1: DeprecationWarning: Method 'Cat.mewow()' has moved to 'Cat.meow()'
'kitty'
>>> c.meow()
'kitty'
Moving a property
-----------------
To move a *instance* property from an existing one to a new one
the :py:func:`~debtcollector.moves.moved_property` function/decorator can be
used to achieve this in a non-destructive manner.
A basic example to do just this:
.. doctest::
>>> from debtcollector import moves
>>> import warnings
>>> warnings.simplefilter('always')
>>> class Dog(object):
... @property
... @moves.moved_property('bark')
... def burk(self):
... return self.bark
... @property
... def bark(self):
... return 'woof'
...
>>> d = Dog()
>>> d.burk
__main__:1: DeprecationWarning: Property 'Dog.burk' has moved to 'Dog.bark'
'woof'
>>> d.bark
'woof'
Moving a class
--------------
To move a *class* from an existing one to a new one
the :py:func:`~debtcollector.moves.moved_class` type generator function can
be used to achieve this in a non-destructive manner.
A basic example to do just this:
.. doctest::
>>> from debtcollector import moves
>>> import warnings
>>> warnings.simplefilter('always')
>>> class WizBang(object):
... pass
...
>>> OldWizBang = moves.moved_class(WizBang, 'OldWizBang', __name__)
>>> a = OldWizBang()
__main__:1: DeprecationWarning: Class '__main__.OldWizBang' has moved to '__main__.WizBang'
>>> b = WizBang()
Renaming a keyword argument
---------------------------
To notify the user when a keyword argument has been replaced with a new and
improved keyword argument and the user is still using the old keyword argument
the :py:func:`~debtcollector.renames.renamed_kwarg` function/decorator
can be used to achieve this in a non-destructive manner.
A basic example to do just this:
.. doctest::
>>> from debtcollector import renames
>>> import warnings
>>> warnings.simplefilter('always')
>>> @renames.renamed_kwarg('snizzle', 'nizzle')
... def do_the_deed(snizzle=True, nizzle=True):
... print(snizzle)
... print(nizzle)
...
>>> do_the_deed()
True
True
>>> do_the_deed(snizzle=False)
__main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated, please use the 'nizzle' argument instead
False
True
>>> do_the_deed(nizzle=False)
True
False
Further customizing the emitted messages
----------------------------------------
It is typically useful to tell the user when a deprecation has started and
when the deprecated item will be offically removed (deleted or other). To
enable this all the currently provided functions this library provides
take a ``message``, ``version`` and ``removal_version`` keyword arguments.
These are used in forming the message that is shown to the user when they
trigger the deprecated activity.
A basic example to do just this:
.. doctest::
>>> from debtcollector import renames
>>> import warnings
>>> warnings.simplefilter('always')
>>> @renames.renamed_kwarg('snizzle', 'nizzle', version="0.5", removal_version="0.7")
... def do_the_deed(snizzle=True, nizzle=True):
... pass
...
>>> do_the_deed(snizzle=False)
__main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated in version '0.5' and will be removed in version '0.7', please use the 'nizzle' argument instead
If the ``removal_version`` is unknown the special character ``?`` can be used
instead (to denote that the deprecated activity will be removed sometime in
the future).
A basic example to do just this:
.. doctest::
>>> from debtcollector import renames
>>> import warnings
>>> warnings.simplefilter('always')
>>> @renames.renamed_kwarg('snizzle', 'nizzle', version="0.5", removal_version="?")
... def do_the_deed(snizzle=True, nizzle=True):
... pass
...
>>> do_the_deed(snizzle=False)
__main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated in version '0.5' and will be removed in a future version, please use the 'nizzle' argument instead
To further customize the message (with a special postfix) the ``message``
keyword argument can be provided.
A basic example to do just this:
.. doctest::
>>> from debtcollector import renames
>>> import warnings
>>> warnings.simplefilter('always')
>>> @renames.renamed_kwarg('snizzle', 'nizzle', message="Pretty please stop using it")
... def do_the_deed(snizzle=True, nizzle=True):
... pass
...
>>> do_the_deed(snizzle=False)
__main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated, please use the 'nizzle' argument instead: Pretty please stop using it

1
doc/source/index.rst
View File

@ -18,6 +18,7 @@ Contents
installation
api
examples
contributing
Indices and tables