Metadata-Version: 1.0
Name: pluck
Version: 0.2
Summary: Plucks values from an iterable.
Home-page: http://github.com/nvie/pluck/
Author: Vincent Driessen
Author-email: vincent@3rdcloud.com
License: BSD
Description: pluck: Quickly pluck "fields" from a list of values
        ===================================================
        
        .. image:: https://travis-ci.org/nvie/pluck.png
           :target: https://travis-ci.org/nvie/pluck
        
        
        pluck is the simplest way of plucking "fields" from an iterable of values.
        "Fields" are either ``item.field`` or ``item[field]``.  Pluck tries both,
        in that order.  If nothing is found, and no default value is specified, it
        throws an exception.
        
        
        Usage
        =====
        
        The package consists of one module consisting of two functions::
        
           from pluck import pluck, ipluck
        
        ``ipluck`` is just the iterable version of ``pluck``.  Use it like this::
        
           pluck(iterable, key)
        
        or::
        
           pluck(iterable, *keys)
        
        
        Examples
        ========
        
        A simple example first.  Say you have a list of datetimes::
        
           >>> from pluck import pluck
           >>> dates = [
           ...     datetime(2012, 10, 22, 12, 00),
           ...     datetime(2012, 10, 22, 15, 14),
           ...     datetime(2012, 10, 22, 21, 44),
           ... ]
           >>> pluck(dates, 'day')
           [22, 22, 22]
           >>> pluck(dates, 'hour')
           [12, 15, 21]
        
        It also works on dictionary-like access (``__getitem__``)::
        
            >>> objects = [
            ...      {'id': 282, 'name': 'Alice', 'age': 30, 'sex': 'female'},
            ...      {'id': 217, 'name': 'Bob', 'age': 56},
            ...      {'id': 328, 'name': 'Charlie', 'age': 56, 'sex': 'male'},
            ... ]
            >>> pluck(objects, 'name')
            ['Alice', 'Bob', 'Charlie']
            >>> pluck(objects, 'age')
            [30, 56, 56]
        
        You can also combine these into a single pluck::
        
           >>> pluck(objects, 'name', 'age')
           [('Alice', 30), ('Bob', 56), ('Charlie', 56)]
        
        
        Defaults
        ========
        
        You can specify default values, too.  By default, ``pluck`` will throw an
        exception when a "field" does not exist::
        
           >>> pluck(objects, 'sex')
           Traceback (most recent call last):
             File "<stdin>", line 1, in <module>
             File "pluck.py", line 104, in pluck
                 return list(ipluck(iterable, *keys, **kwargs))
             File "pluck.py", line 49, in getter
                 raise ValueError('Item %r has no attr or key for %r' % (item, key))
             ValueError: Item {'age': 56, 'id': 217, 'name': 'Bob'} has no attr or key for 'sex'
        
        To instead fill these places with a default value, use this::
        
           >>> pluck(objects, 'sex', default='unknown')
           ['female', 'unknown', 'male']
        
        When you specify multiple keys, you need to use the ``defaults`` (plural!)
        keyword argument instead::
        
           >>> pluck(objects, 'name', 'sex', defaults={'sex': 'unknown'})
           [('Alice', 'female'), ('Bob', 'unknown'), ('Charlie', 'male')]
        
        
        Iterator, rather?
        =================
        
        Use ``ipluck`` if you'd rather wanna have an iterator::
        
            >>> from pluck import ipluck
            >>> ipluck(large_stream_of_items, 'name')
            <itertools.imap object at 0x10c7515d0>
        
        ``pluck`` is equivalent to ``list(ipluck(...))``.
        
        
        History
        =======
        
        0.2 (2012-10-22)
        ------------------
           - Add Python 3 compatibility
           - Improve documentation
        
        0.1 (2012-10-22)
        ------------------
           - Initial release.
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
