Metadata-Version: 1.1
Name: dontasq
Version: 0.1
Summary: Extend built-in Python collections with LINQ-for-objects style methods
Home-page: https://github.com/borzunov/dontasq
Author: Alexander Borzunov
Author-email: borzunov.alexander@gmail.com
License: MIT
Description: =======
        dontasq
        =======
        
        Extend built-in Python collections with LINQ-for-objects style methods
        
        Description
        -----------
        
        The library extends built-in Python collections with methods from `Robert Smallshire`_'s asq_. Adding methods to built-ins isn't officially allowed, but it's possible to do this in CPython (both 2.x and 3.x) using a hack described in the corresponding section below.
        
        .. _Robert Smallshire: https://github.com/rob-smallshire
        .. _asq: https://github.com/rob-smallshire/asq
        
        For example:
        
        .. code:: python
        
            >>> import dontasq
            >>>
            >>> [1, 2, 3].select_many(lambda x: (x, x ** 2)).to_tuple()
            (1, 1, 2, 4, 3, 9)
            >>> 'oh brave new world'.split() \
            ...                     .where(lambda word: len(word) >= 5) \
            ...                     .select(str.capitalize) \
            ...                     .to_list()
            ['Brave', 'World']
        
        In some cases, this style helps to write functional-esque code that is more clear than code with ``map``, ``filter`` and generator expressions: there's no confusion with brackets, and methods are applied in the natural order.
        
        **Warning!** ``dontasq`` uses undocumented CPython features. It's not guaranteed that this features will be maintained in the future Python versions.
        
        Details
        -------
        
        During import, ``dontasq`` looks for classes in the built-ins namespace, ``collections`` and ``itertools`` modules. If a class is an iterable and isn't a metaclass, the library will append all public methods of ``asq.queryables.Queryable`` to it in such a way that a method call:
        
        .. code:: python
        
            >>> instance.select(lambda x: x * 2)
        
        Will be equal to:
        
        .. code:: python
        
            >>> Queryable(instance).select(lambda x: x * 2)
        
        So the methods will be added to classes such as ``list``, ``str``, ``collections.OrderedDict``, or ``itertools.count``. You can find a list of all ``Queryable`` methods and their description in `asq documentation`_.
        
        .. _asq documentation: http://docs.asq.googlecode.com/hg/1.0/html/reference/queryables.html#asq-queryables-queryable
        
        If a class already contains an attribute with a coinciding name (e.g. ``str.join`` and ``list.count``), this attribute won't be replaced.
        
        Of course, you're able to import other ``asq`` modules when using ``dontasq``:
        
        .. code:: python
        
            >>> import dontasq
            >>> from asq.predicates import *
            >>>
            >>> words = ['banana', 'receive', 'believe', 'ticket', 'deceive']
            >>> words.where(contains_('ei')).to_list()
            ['receive', 'deceive']
        
        If you want to patch classes from another library, you can use methods ``dontasq.patch_type`` and ``dontasq.patch_module``:
        
        .. code:: python
        
            >>> import bintrees
            >>> import dontasq
            >>>
            >>> dontasq.patch_type(bintrees.AVLTree)
            >>>
            >>> dictionary = {1: 'Anton', 2: 'James', 3: 'Olivia'}
            >>> bintrees.AVLTree(dictionary).select(lambda x: x * 2).to_list()
            [2, 4, 6]
        
        You can find other examples in `"tests" directory`_.
        
        .. _"tests" directory: https://github.com/borzunov/dontasq/tree/master/tests
        
        Adding methods to built-ins
        ---------------------------
        
        The following approach is found in `this question`_ on StackOverflow.
        
        .. _this question: https://stackoverflow.com/questions/25440694/whats-the-purpose-of-dictproxy
        
        Officially, you can get only a protected (read-only) instance of built-ins' ``__dict__``. The trick is that in CPython this instance contains a reference to an original (modifiable) dictionary that can be tracked with `gc.get_referents`_ function.
        
        .. _gc.get_referents: https://docs.python.org/3/library/gc.html#gc.get_referents
        
        For example, we can add ``select`` method to built-in ``list`` (unlike ``dontasq``, it's non-lazy in this example):
        
        .. code:: python
        
          >>> import gc
          >>> gc.get_referents(vars(list))[0]['select'] = lambda self, func: list(map(func, self))
          >>>
          >>> [1, 2, 3].select(lambda x: x * 2)
          [2, 4, 6]
        
        Another possible way is to use forbiddenfruit_ library that interacts with ``ctypes.pythonapi`` module. The both approaches stably work on both Python 2 and 3, but restricted to CPython only.
        
        .. _forbiddenfruit: https://github.com/clarete/forbiddenfruit
        
        Installation
        ------------
        
        You can install the library using pip::
        
            sudo pip install dontasq
        
        Or install a previously downloaded and extracted package::
        
            sudo python setup.py install
        
        Authors
        -------
        
        Copyright (c) 2015 Alexander Borzunov
        
        The library name suggested by `Robert Smallshire`_ (an author of `asq`_).
        
Keywords: LINQ
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
