check_arg 0.1.3

wrapping decorator to enhance the documentation

• source: https://github.com/jul/check_arg

• ticketing: https://github.com/jul/check_arg/issues

Usage

Checking optional/positional arguments and auto documenting at the same time

Warning

The documentation relies on your talent for naming your functions, and having sensible names.

Example by using some currying, the purpose is to achieve auto documentation and validation so that:

>>> @set_default_kw_value(port=1026,nawak=123)
>>> @must_have_key("name")
>>> @min_positional(2)
>>> @validate(name = naming_convention(), port = in_range(1024,1030 ))
>>> def toto(*a,**kw):
...    """useless fonction"""
...    print a
...    print kw
...    print "done"
...        return 1

gives this results:

>>> help(toto)
... Help on function toto in module __main__:
...
... toto(*a, **kw)
...     useless fonction
...
...     **kewords must validate the following rules**:
...
...     * key: <port> must belong to [ 1024, 1030 [,
...     * key: <name> must begin with underscore
...
...     **at_least_n_positional** :2
...
...
...     **keyword_must_contain_key** :name
...
...
...     **default_kw_value** :
...
...     * params: port is 1026,
...     * params: nawak is 123

Use

To create a decorator that will be called before the called functions and which names and arguments will enhance the documentation as in the following example just do:

>>> set_default_kw_value = valid_and_doc(default_kw_value)
>>> min_positional = valid_and_doc(at_least_n_positional)

You can provide a default template for the documention as a second argument::

>>> def in_range(low,high):
...      def _in_range(_int):
...          return high >= _int > low
...      _in_range.__doc__ = """belong to [ %s, %s [""" % (low, high)
...      return _in_range

>>> def _validate(**validator):
...      def wrap(**validator):
...          def rewrapped(*a,**kw):
...              for key,valid in validator.items():
...                  if key in kw and not valid(kw[key]):
...                      raise Exception(
...                          "Key <%s> does not match rule %s" % (
...                              key,default_doc_maker(
...                                  valid,**{ key: kw[key]}
...                      ) ) )
...          return rewrapped
...
>>>      def validate_doc(_validate,  **validator):
...         return """
...
...  **kewords must validate the following rules**:
...
...  %s
...  """ % ( ",\n".join(
...          "* key: <%s> must %s" % (
...                  key, valid.__doc__ is not None and valid.__doc__ or valid.__name__
...                  ) for key, valid in validator.items()
...              ) )
...      return [ wrap, validate_doc ]
...
>>> validate = valid_and_doc(*_validate())

Changelog

• 0.1.0 initial release

• 0.1.(1|2|3) trying to have README.txt being seen as Rst