A Python package for creating python modules.
I was using the same code snippets over and over, so decided to put them in one place.
-
cached: A module to cache class attributes and methods. Right now, this uses a standard python dictionary for storage. Future versions will hopefully integrate with something like cachetools. -
docfiller: A module to share documentation. This is addapted from the pandasdocdecorator. There are some convenience functions and classes for sharing documentation. -
docinhert: An interface to docstring-inheritance module. This can be combined withdocfillerto make creating related function/class documentation easy.
This package is actively used by the author. Please feel free to create a pull request for wanted features and suggestions!
Use one of the following
pip install module-utilitiesor
conda install -c conda-forge module-utilitiesOptionally, you can install docstring-inheritance to use the docinherit
module:
pip install docstring-inheritance
# or
conda install -c conda-forge docstring-inheritance
Simple example of using cached module.
>>> from module_utilities import cached
>>>
>>> class Example:
... @cached.prop
... def aprop(self):
... print("setting prop")
... return ["aprop"]
... @cached.meth
... def ameth(self, x=1):
... print("setting ameth")
... return [x]
... @cached.clear
... def method_that_clears(self):
... pass
...
>>> x = Example()
>>> x.aprop
setting prop
['aprop']
>>> x.aprop
['aprop']
>>> x.ameth(1)
setting ameth
[1]
>>> x.ameth(x=1)
[1]
>>> x.method_that_clears()
>>> x.aprop
setting prop
['aprop']
>>> x.ameth(1)
setting ameth
[1]
Simple example of using DocFiller.
>>> from module_utilities.docfiller import DocFiller, indent_docstring
>>> d = DocFiller.from_docstring(
... """
... Parameters
... ----------
... x : int
... x param
... y : int
... y param
... z0 | z : int
... z int param
... z1 | z : float
... z float param
...
... Returns
... -------
... output0 | output : int
... Integer output.
... output1 | output : float
... Float output
... """,
... combine_keys='parameters'
... )
...
>>> @d.decorate
... def func(x, y, z):
... """
... Parameters
... ----------
... {x}
... {y}
... {z0}
... Returns
... --------
... {returns.output0}
... """
... return x + y + z
...
>>> print(indent_docstring(func))
+ Parameters
+ ----------
+ x : int
+ x param
+ y : int
+ y param
+ z : int
+ z int param
+ Returns
+ --------
+ output : int
+ Integer output.
# Note that for python version <= 3.8 that method chaining
# in decorators doesn't work, so have to do the following.
# For newer python, you can inline this.
>>> dd = d.assign_keys(z='z0', out='returns.output0')
>>> @dd.decorate
... def func1(x, y, z):
... """
... Parameters
... ----------
... {x}
... {y}
... {z}
... Returns
... -------
... {out}
... """
... pass
...
>>> print(indent_docstring(func1))
+ Parameters
+ ----------
+ x : int
+ x param
+ y : int
+ y param
+ z : int
+ z int param
+ Returns
+ -------
+ output : int
+ Integer output.
>>> dd = d.assign_keys(z='z1', out='returns.output1')
>>> @dd(func1)
... def func2(x, y, z):
... pass
>>> print(indent_docstring(func2))
+ Parameters
+ ----------
+ x : int
+ x param
+ y : int
+ y param
+ z : float
+ z float param
+ Returns
+ -------
+ output : float
+ Float output
See the documentation for a look at module-utilities in action.
This is free software. See LICENSE.
module-utilities is used in the following packages
The author can be reached at wpk@nist.gov.
This package was created with Cookiecutter and the wpk-nist-gov/cookiecutter-pypackage Project template forked from audreyr/cookiecutter-pypackage.