Metadata-Version: 2.4
Name: nanotable
Version: 0.1.0
Summary: More than a collection, less than a database
Project-URL: Documentation, https://github.com/abel1502/nanotable#readme
Project-URL: Issues, https://github.com/abel1502/nanotable/issues
Project-URL: Source, https://github.com/abel1502/nanotable
Author: abel1502
License-Expression: MIT
License-File: LICENSE.txt
Keywords: collection,database,storage,table
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: typing-extensions>=4.15.0
Provides-Extra: sorted
Requires-Dist: sortedcontainers-stubs>=2.4.3; extra == 'sorted'
Requires-Dist: sortedcontainers>=2.4.0; extra == 'sorted'
Description-Content-Type: text/markdown

# nanotable

[![PyPI - Version](https://img.shields.io/pypi/v/nanotable.svg)](https://pypi.org/project/nanotable)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/nanotable.svg)](https://pypi.org/project/nanotable)
[![codecov](https://codecov.io/gh/abel1502/nanotable/graph/badge.svg?token=ZVUHGZZMKZ)](https://codecov.io/gh/abel1502/nanotable)

Nanotable is meant to bridge the gap between simple collections, such as `list` and `dict`,
and full-on database tables. It lets you store a set of objects, index it by
several keys, and more! It's fast, memory-efficient, and well-tested.
The project draws inspiration from [littletable](https://github.com/ptmcg/littletable),
but is a completely original implementation. Its goal is to avoid feature bloat
and maintain performance on par with built-in collections.

There are several situations where you might want to use Nanotable:

- When you'd otherwise use a `dict` from an object's field to the object itself.
  Nanotable does that for you, and also provides additional features, such
  as checking for the existence of an element with a simple `in` check;
  hanging the value of the key field with `Table.rekey`, or catching
  accidental changes to the key field automatically.

- When you'd otherwise use a `bidict`. That's a great library in its own right,
  but Nanotable provides some additional functionality such as storing extra
  non-hashable metadata along your objects (also see the previous point).

- When you'd otherwise use a database. Nanotable spares you the computational
  and mental overhead. You probably have already written your own domain-specific
  version of Nanotable at some point in your life -- now you can use a well-tested
  library instead.

## Installation

```console
pip install nanotable
```

## Usage

A basic usage example is given below:

```python
from nanotable import Table

table = Table(of_dicts=True)\
    .primary_index_on("name")\
    .index_on("phone")

table.add({"name": "John Doe", "phone": "123-456-7890", "age": 25})
table.add({"name": "Jane Doe", "phone": "987-654-3210", "age": 26})
table.add({"name": "Barrack Obama", "age": "idk"})

table.at["Jane Doe"]  # {"name": "Jane Doe", "phone": "987-654-3210", "age": 26}
table.by.name["John Doe"]  # Same as above
table.by.phone["987-654-3210"]  # {"name": "Jane Doe", "phone": "987-654-3210", "age": 26}

table.remove(table.by.name["Barrack Obama"])
```

You can store any kind of object in the table. Specify `of_dicts=True` or `getfield=getfield_item`
to use mappings (`dict` or anything with `obj[key]` item access); `of_objects=True` or
`getfield=getfield_attr` to use objects with attributes (`obj.key` access); or
any function with the signature `(obj, key: str) -> Any | MISSING` as `getfield`.
You can also specify `of=MyType` to have the table infer either `of_objects` or `of_dicts`
based on the anticipated element type.

### Typing

The library is fully type-annotated. To make use of this, at the bare minimum
you can specify the type of the objects you want to store in the table:

```python
table = Table[Person](of_objects=True)
# or
table = Table[dict[str, Any]](of_dicts=True)
```

To add static typing to your indexes, you need to define a type with all of them:

```python
class MyIndexes(Protocol):
    name: UniqueIndex[Person, str]
    phone: UniqueIndex[Person, str]

# The first template parameter is the object type;
# The second template parameter is protocol for `by`;
# The third template parameter is the primary index type.
table = Table[Person, MyIndexes, UniqueIndex[Person, str]](of_objects=True)
table.primary_index_on("name", required=True)
table.index_on("phone")
```

### Indexes

TODO: UniqueIndex, MultiIndex

TODO: `[sorted]` extra and SortedUniqueIndex, SortedMultiIndex

### Storage

TODO

### Caveats

Indexed fields must be hashable, like with the built-in `dict`. This already
imposes the restriction that they must be immutable (which is why you can't
use, for example, a `list` as a `dict` key -- see [here](https://docs.python.org/3/faq/design.html#why-must-dictionary-keys-be-immutable) to learn why).
With Nanotable, however, comes the additional restriction that the value of the
indexed field itself **mustn't be changed**. For a `dict` this obviously isn't
a concern since it stores keys and values separately, inaccessible to the user.
Nanotable will try to detect this happening and warn you, but this unfortunately cannot be done reliably.
If you wish to change an indexed field, the correct way to do that is to
remove it from the table, change the field and re-add it. Nanotable provides
a helper that does this for you:

```python
with table.rekey(obj):
    obj.field = new_value
```

If a field is not indexed, this is unnecessary.

If you are certain that your code never modifies an indexed field of an object
in a `Table`, you can disable the checks that issue the warning by setting
`nanotable.safety.disable_safety_checks` to `False`. This provides a small
performance improvement, with the downside that any potential bugs will be
almost impossible to catch and will show up as subtly wrong results. It is
recommended that you keep the safety checks on unless you know what you're
doing.

Nanotable is also not thread-safe. When using a `Table` from multiple threads
at once, use a synchronization primitive such as a `threading.Lock` to ensure
that only one thread can interact with the table at a time. Multithreaded
read-only access should theoretically be fine.

## License

Nanotable is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
See the [LICENSE.txt](LICENSE.txt) for details.

© 2026 abel1502
