A lens library for python
Project description
[![Build Status](https://travis-ci.org/ingolemo/python-lenses.svg?branch=master)](https://travis-ci.org/ingolemo/python-lenses)
[![codecov](https://codecov.io/gh/ingolemo/python-lenses/branch/master/graph/badge.svg)](https://codecov.io/gh/ingolemo/python-lenses)
# 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`](examples) folder and a tutorial
is available in the [`tutorial`](tutorial/index.md) folder.
Here's a simple example:
```python
>>> 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:
```python
def format_scores(data):
result = {}
for key, value in data.items():
if key == 'scores':
new_value = []
for letter in value:
if is_instance(maybe_letter, str):
new_value.append(maybe_letter.upper())
else:
new_value.append(maybe_letter)
result[key] = new_value
else:
result[key] = value
return result
```
## 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/.
[![codecov](https://codecov.io/gh/ingolemo/python-lenses/branch/master/graph/badge.svg)](https://codecov.io/gh/ingolemo/python-lenses)
# 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`](examples) folder and a tutorial
is available in the [`tutorial`](tutorial/index.md) folder.
Here's a simple example:
```python
>>> 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:
```python
def format_scores(data):
result = {}
for key, value in data.items():
if key == 'scores':
new_value = []
for letter in value:
if is_instance(maybe_letter, str):
new_value.append(maybe_letter.upper())
else:
new_value.append(maybe_letter)
result[key] = new_value
else:
result[key] = value
return result
```
## 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/.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
lenses-0.3.0.tar.gz
(27.9 kB
view hashes)
Built Distribution
lenses-0.3.0-py2.py3-none-any.whl
(36.7 kB
view hashes)
Close
Hashes for lenses-0.3.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7505331cd8c828c5b251371c503497c4bbfac321dd5bcd895d503739312635f0 |
|
MD5 | bb1550a62ef4f79a6d7ab89c13a091ac |
|
BLAKE2b-256 | 692401168e274677a9cdaf15cddf8f091851cd319aaf5115efa77f6754478076 |