Metadata-Version: 1.1
Name: check-arg
Version: 0.1.3
Summary: wrapping decorator to enhance the documentation
Home-page: http://github.org/jul/check_arg
Author: Julien Tayon
Author-email: julien@tayon.net
License: License :: OSI Approved :: BSD License
Description: =======================
        check_arg documentation
        =======================
        
        * source: https://github.com/jul/check_arg
        * ticketing: https://github.com/jul/check_arg/issues
        
        .. image:: 
           https://travis-ci.org/jul/check_arg.png
        
        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
        
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
