Metadata-Version: 2.1
Name: lenses
Version: 1.0.0
Summary: A lens library for python
Home-page: https://github.com/ingolemo/python-lenses
Author: Adrian Room
Author-email: ingolemo@gmail.com
License: GPLv3+
Keywords: lens lenses immutable functional optics
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.5, <4
Requires-Dist: singledispatch
Requires-Dist: typing
Provides-Extra: docs
Requires-Dist: sphinx ; extra == 'docs'
Provides-Extra: optional
Requires-Dist: pyrsistent ; extra == 'optional'
Provides-Extra: tests
Requires-Dist: pyrsistent ; extra == 'tests'
Requires-Dist: pytest ; extra == 'tests'
Requires-Dist: pytest-sugar ; extra == 'tests'
Requires-Dist: coverage ; extra == 'tests'
Requires-Dist: pytest-coverage ; extra == 'tests'
Requires-Dist: hypothesis ; extra == 'tests'
Requires-Dist: mypy ; (implementation_name == "cpython") and extra == 'tests'


Lenses
======

.. image:: https://travis-ci.org/ingolemo/python-lenses.svg
    :target: https://travis-ci.org/ingolemo/python-lenses

.. image:: https://codecov.io/gh/ingolemo/python-lenses/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/ingolemo/python-lenses

Lenses is a python library that helps you to manipulate large
data-structures without mutating them. It is inspired by the lenses in
Haskell, although it's much less principled and the api is more suitable
for python.


Installation
------------

You can install the latest version from pypi using pip like so::

    pip install lenses

You can uninstall similarly::

    pip uninstall lenses


Documentation
-------------

The lenses library makes liberal use of docstrings, which you can access
as normal with the ``pydoc`` shell command, the ``help`` function in
the repl, or by reading the source yourself.

Most users will only need the docs from ``lenses.UnboundLens``. If you
want to add hooks to allow parts of the library to work with custom
objects then you should check out the ``lenses.hooks`` module. Most of
the fancy lens code is in the ``lenses.optics`` module for those who
are curious how everything works.

Some examples are given in the `examples`_ folder and the `documentation`_
is available on ReadTheDocs.

.. _examples: examples
.. _documentation: https://python-lenses.readthedocs.io/en/latest/


Example
-------

.. code:: pycon

    >>> from pprint import pprint
    >>> from lenses import lens
    >>>
    >>> data = [{'name': 'Jane', 'scores': ['a', 'a', 'b', 'a']},
    ...         {'name': 'Richard', 'scores': ['c', None, 'd', 'c']},
    ...         {'name': 'Zoe', 'scores': ['f', 'f', None, 'f']}]
    ... 
    >>> format_scores = lens.Each()['scores'].Each().Instance(str).call_upper()
    >>> cheat = lens[2]['scores'].Each().set('a')
    >>>
    >>> corrected = format_scores(data)
    >>> pprint(corrected)
    [{'name': 'Jane', 'scores': ['A', 'A', 'B', 'A']},
     {'name': 'Richard', 'scores': ['C', None, 'D', 'C']},
     {'name': 'Zoe', 'scores': ['F', 'F', None, 'F']}]
    >>>
    >>> cheated = format_scores(cheat(data))
    >>> pprint(cheated)
    [{'name': 'Jane', 'scores': ['A', 'A', 'B', 'A']},
     {'name': 'Richard', 'scores': ['C', None, 'D', 'C']},
     {'name': 'Zoe', 'scores': ['A', 'A', 'A', 'A']}]


The definition of ``format_scores`` means "for each item in the data take
the value with the key of ``'scores'`` and then for each item in that list
that is an instance of ``str``, call its ``upper`` method on it". That one
line is the equivalent of this code:

.. code:: python

    def format_scores(data):
        results = []
        for entry in data:
            result = {}
            for key, value in entry.items():
                if key == 'scores':
                    new_value = []
                    for letter in value:
                        if isinstance(letter, str):
                            new_value.append(letter.upper())
                        else:
                            new_value.append(letter)
                    result[key] = new_value
                else:
                    result[key] = value
            results.append(result)
        return results


License
-------

python-lenses is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with this program. If not, see http://www.gnu.org/licenses/.


