Metadata-Version: 1.1
Name: positional
Version: 1.1.1
Summary: Library to enforce positional or key-word arguments
Home-page: https://github.com/morganfainberg/positional
Author: Morgan Fainberg
Author-email: morgan.fainberg@gmail.com
License: UNKNOWN
Description: ==========
        positional
        ==========
        
        A decorator which enforces only some args may be passed positionally.
        
        |PyPi|
        
        |Build Status|
        
        |Documentation Status|
        
        The Basics
        ==========
        
        `positional` provides a decorator which enforces only some args may be passed
        positionally. The idea and some of the code was taken from the oauth2 client
        of the google-api client.
        
        The decorator makes it easy to support Python 3 style key-word only
        parameters. For example, in Python 3 it is possible to write:
        
        .. code:: python
        
            >>> def fn(pos1, *, kwonly1, kwonly2=None):
            ...     ...
        
        All named parameters after `*` must be a keyword:
        
        .. code:: python
        
            >>> fn(10, 'kw1', 'kw2')  # Raises exception.
            >>> fn(10, kwonly1='kw1', kwonly2='kw2')  # Ok.
        
        To replicate this behaviour with the positional decorator you simply specify
        how many arguments may be passed positionally.
        
        First to import the decorator we typically use:
        
        .. code:: python
        
            >> from positional import positional
        
        Replicating the Example above:
        
        .. code:: python
        
            >>> @positional(1)
            ... fn(pos1, kwonly1=None, kwonly2=None):
            ...     ...
        
        If no default value is provided to a keyword argument, it becomes a required
        keyword argument:
        
        .. code:: python
        
            >>> @positional(0)
            ... def fn(required_kw):
            ...     ...
        
        This must be called with the keyword parameter:
        
        .. code:: python
        
            >>> fn() # Raises exception
            >>> fn(10) # Raises Exception
            >>> fn(required_kw=10) # OK
        
        When defining instance or class methods always remember that in python the
        first positional argument passed is the instance; you will need to account for
        `self` and `cls`:
        
        .. code:: python
        
            >>> class MyClass(object):
            ...
            ...     @positional(2)
            ...     def my_method(self, pos1, kwonly1=None):
            ...         ...
            ...
            ...     @classmethod
            ...     @positional(2)
            ...     def my_method(cls, pos1, kwonly1=None):
            ...         ...
        
        
        
        If you would prefer not to account for `self` and `cls` you can use the
        `method` and `classmethod` helpers which do not consider the initial
        positional argument. So the following class is exactly the same as the one
        above:
        
        .. code:: python
        
            >>> class MyClass(object):
            ...
            ...     @positional.method(1)
            ...     def my_method(self, pos1, kwonly1=None):
            ...         ...
            ...
            ...     @positional.classmethod(1)
            ...     def my_method(cls, pos1, kwonly1=None):
            ...         ...
        
        
        If a value isn't provided to the decorator then it will enforce that
        every variable without a default value will be required to be a kwarg:
        
        .. code:: python
        
            >>> @positional()
            ... def fn(pos1, kwonly1=None):
            ...     ...
            ...
            >>> fn(10)  # Ok.
            >>> fn(10, 20)  # Raises exception.
            >>> fn(10, kwonly1=20)  # Ok.
        
        This behaviour will work with the `positional.method` and
        `positional.classmethod` helper functions as well:
        
        .. code:: python
        
            >>> class MyClass(object):
            ...
            ...    @positional.classmethod()
            ...    def my_method(cls, pos1, kwonly1=None):
            ...        ...
            ...
            >>> MyClass.my_method(10)  # Ok.
            >>> MyClass.my_method(10, 20)  # Raises exception.
            >>> MyClass.my_method(10, kwonly1=20)  # Ok.
        
        For compatibility reasons you may wish to not always raise an exception so
        a WARN mode is available. Rather than raise an exception a warning will be
        emitted.
        
        .. code:: python
        
            >>> @positional(1, enforcement=positional.WARN):
            ... def fn(pos1, kwonly=1):
            ...     ...
        
        Available modes are:
        
        - positional.EXCEPT - the default, raise an exception.
        - positional.WARN - emit a warning.
        
        
        .. |Build Status| image:: https://travis-ci.org/morganfainberg/positional.svg?branch=master
           :target: https://travis-ci.org/morganfainberg/positional
        .. |Documentation Status| image:: https://readthedocs.org/projects/positional/badge/?version=latest
           :target: http://positional.readthedocs.org/en/latest/?badge=latest
        .. |PyPi| image:: https://badge.fury.io/py/positional.png
           :target: http://badge.fury.io/py/positional
        
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4