lenses

library1.2.0pypypi✓ verified 85d ago

Lenses is a Python library inspired by functional programming concepts, providing a fluent API for immutable data manipulation. It allows for safe and concise modification, retrieval, and transformation of nested data structures (like dictionaries and lists) without mutating the original object. The current version is 1.2.0, with a moderate release cadence.

data serialization

pip install lenses

github ↗package ↗

INSTALL

IMPORT

SIG · LENSES

lenses

datapythonv1.2.0

Install

1.6s avg

Import

51ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.054s · 18.2MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.048s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

lens

✓ from lenses import lens

Demonstrates basic `get()`, `set()`, and `modify()` operations for navigating and transforming nested immutable data structures.

from lenses import lens data = { 'user': { 'id': 123, 'name': 'Alice', 'settings': { 'theme': 'dark', 'notifications': True } }, 'products': [{'id': 'A', 'price': 100}, {'id': 'B', 'price': 200}] } # Get a value user_name = lens(data).user.name.get() print(f"User name: {user_name}") # Set a new value (returns a new data structure) updated_data = lens(data).user.settings.theme.set('light') print(f"Original theme: {data['user']['settings']['theme']}") print(f"New theme: {updated_data['user']['settings']['theme']}") # Modify a value (returns a new data structure) increased_price_data = lens(data).products[0].price.modify(lambda p: p * 1.1) print(f"Original product A price: {data['products'][0]['price']}") print(f"Increased product A price: {increased_price_data['products'][0]['price']}")

Debug

Known issues

gotchaLenses operations are immutable. They *always* return a new modified copy of the data structure, leaving the original unchanged. Expecting in-place modification will lead to silent failures where the original data remains unaltered.

fix

Always assign the result of a `set()` or `modify()` operation to a new variable or overwrite the original if desired, e.g., `data = lens(data).path.set(new_value)`.

affects: All versions

gotchaWhen navigating nested data, be mindful of using attribute access (`.key`) vs. item access (`['key']` or `[index]`). Attribute access assumes dictionary keys can be accessed like attributes, which is convenient but can lead to `AttributeError` if the underlying dictionary type doesn't support it directly.

fix

Use `lens(data)['key']` for dictionaries to ensure robust key access. Attribute access `lens(data).key` is syntactic sugar that might rely on custom `__getattr__` implementations or `dict` subclasses.

affects: All versions

gotchaLenses throw `KeyError` or `IndexError` by default if a path component does not exist during a `get()` operation. This can lead to unexpected crashes if data structures vary.

fix

To handle missing keys gracefully, use methods like `lens(data).path.get_set(default_value)` which provides a fallback value if the path is not found, or `lens(data).path.get_0(default_value)` for an optional value.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'dict' object has no attribute 'foo'

Attempting to access a dictionary key using attribute notation (`.foo`) when the underlying `dict` object does not support attribute access for its keys.

fix

Use item access `lens(data)['foo']` instead of `lens(data).foo`. While `lens` itself enables the `.foo` syntax, the error often originates when the underlying data is being accessed through a plain `dict`.

KeyError: 'some_key' or IndexError: list index out of range

The path specified by the lens (e.g., `some_key` or `list_index`) does not exist in the data structure during a `get()` operation or when modifying.

fix

Before `get()`, `set()`, or `modify()`, ensure the path exists, or use methods like `lens(data).path.get_set(default_value)` to provide a fallback value if the path is not found.

TypeError: 'lens' object is not callable

Trying to use a lens object or one of its methods without calling the terminal operation (e.g., `get`, `set`, `modify`) with parentheses.

fix

Ensure all terminal operations are called with parentheses, even if they take no arguments, e.g., `lens(data).foo.get()` instead of `lens(data).foo.get`.

Upgrade

Version history

1.2.0latest on PyPI · released Oct 24, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/ingolemo/python-lenses ↗

packagehttps://pypi.org/project/lenses/ ↗