> built 2026-09-22 14:47 UTC from 9a3e4aa (master) · chromadol 0.1.7. Details: build_info.json

# index.html.md

<!-- generated by epythet -->

# chromadol

Data Object Layer for ChromaDB

To install:	`pip install chromadol`

[Documentation](https://i2mint.github.io/chromadol/)

# Example usage

To make a `ChromaClient` DOL, you can specify a `chromadb` `Client`, `PersistentClient` (etc.)
instance, or specify a string (which will be interpreted as a path to a directory to
save the data to in a `PersistentClient` instance).

```none
>>> from chromadol import ChromaClient
>>> import tempfile, os 
>>> with tempfile.TemporaryDirectory() as temp_dir:
...     tempdir = os.path.join(temp_dir, "chromadol_test")
...     os.makedirs(tempdir)
>>> client = ChromaClient(tempdir)
```

Removing all contents of client to be able to run a test on a clean slate

```none
>>> for k in client:
...     del client[k]
```

There’s nothing yet:

```none
>>> list(client)
[]
```

Now let’s “get” a collection.

```none
>>> collection = client['chromadol_test']
```

Note that just accessing the collection creates it (by default)

```none
>>> list(client)
['chromadol_test']
```

Here’s nothing in the collection yet:

```none
>>> list(collection)
[]
```

So let’s write something.
Note that `chromadb` is designed to operate on multiple documents at once,
so the “chromadb-natural” way of specifying it’s keys and contents (and any extras)
would be like this:

```none
>>> collection[['piece', 'of']] = {
...     'documents': ['contents for piece', 'contents for of'],
...     'metadatas': [{'author': 'me'}, {'author': 'you'}],
... }
```

Now we have two documents in the collection:

```none
>>> len(collection)
2
```

Note, though, that the order of the documents is not guaranteed.

```none
>>> sorted(collection)
['of', 'piece']

>>> assert collection['piece'] == {
...     'ids': ['piece'],
...     'embeddings': None,
...     'metadatas': [{'author': 'me'}],
...     'documents': ['contents for piece'],
...     'uris': None,
...     'data': None
... }

>>> assert collection['of'] == {
...     'ids': ['of'],
...     'embeddings': None,
...     'metadatas': [{'author': 'you'}],
...     'documents': ['contents for of'],
...     'uris': None,
...     'data': None
... }
```

You can also read multiple documents at once.
But note that the order of the documents is not guaranteed.

```none
>>> collection[['piece', 'of']] == collection[['of', 'piece']]
True
```

You can read or write one document at a time too.

```none
>>> collection['cake'] = {
...     "documents": "contents for cake",
... }
>>> sorted(collection)  # sorting because order is not guaranteed
['cake', 'of', 'piece']
>>> assert collection['cake'] == {
...     'ids': ['cake'],
...     'embeddings': None,
...     'metadatas': [None],
...     'documents': ['contents for cake'],
...     'uris': None,
...     'data': None,
... }
```

In fact, see that if you only want to specify the “documents” part of the information,
you can just write a string instead of a dictionary:

```none
>>> collection['cake'] = 'a different cake'
>>> assert collection['cake'] == {
...     'ids': ['cake'],
...     'embeddings': None,
...     'metadatas': [None],
...     'documents': ['a different cake'],
...     'uris': None,
...     'data': None,
... }
```

<p class="epythet-aggregates">This documentation as a single file: <a href="chromadol.md">chromadol.md</a> (Markdown, for agents).</p>


# _autosummary/chromadol.base.html.md

# chromadol.base

Base objects for chromadol.

### Functions

| `get_collection`(collection, \*[, codec, client])   |    |
|-----------------------------------------------------|----|
| `identity`(x)                                       |    |

### Classes

| [`AppendableChromaCollection`](_autosummary/chromadol.base.html.md#chromadol.base.AppendableChromaCollection)(collection)         | ChromaCollection with `append` and `extend`, auto-generating uuid keys.   |
|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| [`ChromaClient`](_autosummary/chromadol.base.html.md#chromadol.base.ChromaClient)([client, decoder, get_or_create]) |                                                                           |
| [`ChromaCollection`](_autosummary/chromadol.base.html.md#chromadol.base.ChromaCollection)(collection)                   |                                                                           |
| [`ChromaDocuments`](_autosummary/chromadol.base.html.md#chromadol.base.ChromaDocuments)(collection)                    | ChromaCollection but reading and writing only the 'documents' field.      |
| [`ChromaMetadatas`](_autosummary/chromadol.base.html.md#chromadol.base.ChromaMetadatas)(collection)                    | ChromaCollection but reading and writing only the 'metadatas' field.      |
| [`ChromaUris`](_autosummary/chromadol.base.html.md#chromadol.base.ChromaUris)(collection)                         | ChromaCollection but reading and writing only the 'uris' field.           |

### *class* chromadol.base.AppendableChromaCollection(collection)

Bases: [`AppendableChromaCollection`](_autosummary/chromadol.base.html.md#chromadol.base.AppendableChromaCollection)

ChromaCollection with `append` and `extend`, auto-generating uuid keys.

Items are the raw `chromadb` kwargs mappings that
`ChromaCollection.__setitem__()` accepts (e.g.
`{"documents": ..., "metadatas": ...}`) – use this when you need to append
more than the single field the codec-ed stores below expose.

### *class* chromadol.base.ChromaClient(client=None, \*, decoder=<class 'chromadol.base.ChromaCollection'>, get_or_create=True, \*\*create_collection_kwargs)

Bases: [`MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping)

#### clear()

This method is here, in fact, to disable the clear method, that would
otherwise be inherited from MutableMapping.
It’s existence is too dangerous, as it would delete all collections in the
client.
If you want to actually delete all collections in the client, do so explicitly
by iterating over the client and deleting each collection, as such:

```pycon
>>> for k in chroma_client_instance:
...     del chroma_client_instance[k]
```

### *class* chromadol.base.ChromaCollection(collection)

Bases: [`MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping)

#### get_include *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None*

The `include` that reads pass to `collection.get`. `None` keeps
chromadb’s default (documents and metadatas); a single-field store whose
field is not in that default (e.g. `uris`) names it here.

### *class* chromadol.base.ChromaDocuments(collection)

Bases: [`ChromaDocuments`](_autosummary/chromadol.base.html.md#chromadol.base.ChromaDocuments)

ChromaCollection but reading and writing only the ‘documents’ field.

`append` and `extend` take the same values `__setitem__` takes (that is,
the ‘documents’ field’s value), generating uuid keys for them. To write raw
`chromadb` kwargs instead, use `AppendableChromaCollection`.

### *class* chromadol.base.ChromaMetadatas(collection)

Bases: `Store`

ChromaCollection but reading and writing only the ‘metadatas’ field.

Mainly a read view: `chromadb` refuses an `upsert` that carries neither
documents nor images, so writing metadata alone raises (that is also why this
one has no `append`). Write metadata with the documents, through
`ChromaCollection` or `AppendableChromaCollection`.

### *class* chromadol.base.ChromaUris(collection)

Bases: [`ChromaUris`](_autosummary/chromadol.base.html.md#chromadol.base.ChromaUris)

ChromaCollection but reading and writing only the ‘uris’ field.

Writing uris needs a collection created with a `data_loader` (see
`chromadol.data_loaders`): the record is embedded from the data it loads.
`chromadb` only does that in `add` (`upsert` and `update` embed only
documents or images), so a new key is added and an existing key is replaced
(delete, then add, keeping its metadata), and restored if the add fails.


# _autosummary/chromadol.data_loaders.html.md

# chromadol.data_loaders

Data loaders for ChromaDB.

### Functions

| `load_bytes`(filepath)                              |    |
|-----------------------------------------------------|----|
| `load_text`(filepath)                               |    |
| `pdf_file_text`(filepath, \*[, page_break_delim])   |    |
| `test_file_loader`()                                |    |
| `url_to_contents`(url[, content_extractor, params]) |    |

### Classes

| [`FileLoader`](_autosummary/chromadol.data_loaders.html.md#chromadol.data_loaders.FileLoader)([loader, prefix, suffix, max_workers])   | A DataLoader that loads a list of text files from a list of URIs.   |
|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| [`MappingLoader`](_autosummary/chromadol.data_loaders.html.md#chromadol.data_loaders.MappingLoader)(mapping, \*[, key_type, ...])         |                                                                     |

### *class* chromadol.data_loaders.FileLoader(loader=<function load_text>, \*, prefix='', suffix='', max_workers=4)

Bases: `DataLoader`[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) | [`None`](https://docs.python.org/3/builtins/constants.html#None)]]

A DataLoader that loads a list of text files from a list of URIs.

By default, it loads text files from local files, given URIs that are full file paths.
You can specify a prefix thought (usually used to specify a root directory),
or a suffix (usually used to specify a file extension).

Further, you can specify a different `loader`, e.g. to load files from a remote URL,
or to load binary files, or to load text from pdf files, or from S3, or a database, etc.

### Example

```pycon
>>> import chromadb
>>> rootdir = chromadb.__path__[0] + '/'
>>> file_loader_1 = FileLoader(prefix=rootdir)
>>> file_contents_1 = file_loader_1(['__init__.py', 'types.py'])
>>> len(file_contents_1)
2
>>> 'Embeddings' in file_contents_1[0]  # i.e. __init__.py contains the word 'Embeddings'
True
>>> 'from typing import' in file_contents_1[1]  # i.e. types.py contains the phrase 'from typing import'
True
```

### *class* chromadol.data_loaders.MappingLoader(mapping, \*, key_type=<class 'str'>, ingress=<function identity>, egress=<function identity>, max_workers=None)

Bases: `DataLoader`


# _autosummary/chromadol.html.md

# chromadol

Data Object Layer (DOL) for ChromaDB

Example usage:

To make a `ChromaClient` DOL, you can specify a `chromadb` `Client`, `PersistentClient` (etc.)
instance, or specify a string (which will be interpreted as a path to a directory to
save the data to in a `PersistentClient` instance).

```pycon
>>> from chromadol import ChromaClient
>>> import tempfile, os
>>> with tempfile.TemporaryDirectory() as temp_dir:
...     tempdir = os.path.join(temp_dir, "chromadol_test")
...     os.makedirs(tempdir)
>>> client = ChromaClient(tempdir)
```

Removing all contents of client to be able to run a test on a clean slate

```pycon
>>> for k in client:
...     del client[k]
...
```

There’s nothing yet:

```pycon
>>> list(client)
[]
```

Now let’s “get” a collection.

```pycon
>>> collection = client['chromadol_test']
```

Note that just accessing the collection creates it (by default)

```pycon
>>> list(client)
['chromadol_test']
```

Here’s nothing in the collection yet:

```pycon
>>> list(collection)
[]
```

So let’s write something.
Note that `chromadb` is designed to operate on multiple documents at once,
so the “chromadb-natural” way of specifying it’s keys and contents (and any extras)
would be like this:

```pycon
>>> collection[['piece', 'of']] = {
...     'documents': ['contents for piece', 'contents for of'],
...     'metadatas': [{'author': 'me'}, {'author': 'you'}],
... }
```

Now we have two documents in the collection:

```pycon
>>> len(collection)
2
```

Note, though, that the order of the documents is not guaranteed.

```pycon
>>> sorted(collection)
['of', 'piece']
```

Reading a key back returns a `chromadb` record. Its meaningful fields are
`ids`, `documents` and `metadatas` (`chromadb` also manages
`embeddings`/`uris`/`data`/`included`, whose presence and defaults
vary by version), so we check the meaningful fields:

```pycon
>>> piece = collection['piece']
>>> piece['ids'], piece['documents'], piece['metadatas']
(['piece'], ['contents for piece'], [{'author': 'me'}])
>>> of = collection['of']
>>> of['ids'], of['documents'], of['metadatas']
(['of'], ['contents for of'], [{'author': 'you'}])
```

You can also read multiple documents at once.
But note that the order of the documents is not guaranteed.

```pycon
>>> collection[['piece', 'of']] == collection[['of', 'piece']]
True
```

You can read or write one document at a time too.

```pycon
>>> collection['cake'] = {
...     "documents": "contents for cake",
... }
>>> sorted(collection)  # sorting because order is not guaranteed
['cake', 'of', 'piece']
>>> cake = collection['cake']
>>> cake['ids'], cake['documents'], cake['metadatas']
(['cake'], ['contents for cake'], [None])
```

# In fact, see that if you only want to specify the “documents” part of the information,
# you can just write a string instead of a dictionary:

# >>> collection[‘cake’] = ‘a different cake’
# >>> assert collection[‘cake’] == {
# …     ‘ids’: [‘cake’],
# …     ‘embeddings’: None,
# …     ‘metadatas’: [None],
# …     ‘documents’: [‘a different cake’],
# …     ‘uris’: None,
# …     ‘data’: None,
# … }

# The `collection` instance is not only dict-like, but also list-like in the
# sense that it has an `.append` and an `.extend` method.

# >>> len(collection)
# 3
# >>> collection.extend([‘two documents’, ‘specified without keys’])
# >>> len(collection)
# 5

# See that the two documents were added to the collection, and that they were assigned
# keys automatically:

# >>> list(collection)  # doctest: +SKIP
# [‘piece’, ‘of’, ‘cake’, ‘1704294539590875904’, ‘1704294539631522048’]

### Modules

| [`base`](_autosummary/chromadol.base.html.md#module-chromadol.base)                 | Base objects for chromadol.   |
|---------------------------------------------------------------------------------------------|-------------------------------|
| [`data_loaders`](_autosummary/chromadol.data_loaders.html.md#module-chromadol.data_loaders) | Data loaders for ChromaDB.    |
| [`util`](_autosummary/chromadol.util.html.md#module-chromadol.util)                 | Utils for chromadol.          |


# _autosummary/chromadol.util.html.md

# chromadol.util

Utils for chromadol.

### Functions

| [`add_if_missing`](_autosummary/chromadol.util.html.md#chromadol.util.add_if_missing)(collection, ids[, ...])           | Add to collection if not already there.                                                                                                |
|---------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| [`argument_value`](_autosummary/chromadol.util.html.md#chromadol.util.argument_value)(argname, func, args, kwargs)      | Extract the argument value from a function call, or the default if not given.                                                          |
| [`identity`](_autosummary/chromadol.util.html.md#chromadol.util.identity)(x)                                      | The identity function.                                                                                                                 |
| `ids_not_in_collection`(collection, ids)                                                          |                                                                                                                                        |
| `indices_of_id_not_in_collection`(collection, ids)                                                |                                                                                                                                        |
| [`keep_only_include_keys`](_autosummary/chromadol.util.html.md#chromadol.util.keep_only_include_keys)(method)                   | Return wrapped method that only subdicts it's outputs to only `include` keys.                                                          |
| [`map_arguments`](_autosummary/chromadol.util.html.md#chromadol.util.map_arguments)(func, args, kwargs)                | Get a `{argname: argval, ...}` dict from the args and kwargs of a function call.                                                       |
| [`mapped_list`](_autosummary/chromadol.util.html.md#chromadol.util.mapped_list)(func[, iterable, max_workers])       | Like builtin map, but returns a list, and if iterable is None, returns a partial function that can directly be applied to an iterable. |
| [`subdict`](_autosummary/chromadol.util.html.md#chromadol.util.subdict)(d, keys)                                 | return a subdict with only the given keys                                                                                              |
| [`transform_methods_to_keep_only_include_keys`](_autosummary/chromadol.util.html.md#chromadol.util.transform_methods_to_keep_only_include_keys)(...) | Wraps all methods that contain an `include` argument so they filter their output accordingly.                                          |

### Classes

| [`Delegator`](_autosummary/chromadol.util.html.md#chromadol.util.Delegator)(wrapped_obj)   | Delegates all attributes to the wrapped object   |
|---------------------------------------------------------------------------|--------------------------------------------------|

### *class* chromadol.util.Delegator(wrapped_obj)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Delegates all attributes to the wrapped object

### chromadol.util.add_if_missing(collection, ids, embeddings=None, metadatas=None, documents=None, images=None, uris=None)

Add to collection if not already there.

### chromadol.util.argument_value(argname, func, args, kwargs)

Extract the argument value from a function call, or the default if not given.

Note that this

```pycon
>>> func = lambda x, y, z=42: None
>>> argument_value('z', func, [1, 2], {})  # z not given, so use default
42
>>> argument_value('z', func, [1, 2], {'z': 4})  # z given, so use that
4
>>> argument_value('z', func, [1, 2, 3], {})  # y given as positional, so use that
3
```

### chromadol.util.identity(x)

The identity function. Returns what it is given.

* **Return type:**
  [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)(`T`)

### chromadol.util.keep_only_include_keys(method)

Return wrapped method that only subdicts it’s outputs to only `include` keys.

### chromadol.util.map_arguments(func, args, kwargs)

Get a `{argname: argval, ...}` dict from the args and kwargs of a function call.

```pycon
>>> func = lambda x, y, z=42: None
>>> map_arguments(func, [1], {'y': 2})  # x as positional, y as keyword, z not given
{'x': 1, 'y': 2, 'z': 42}
>>> map_arguments(func, [1, 2], {'z': 4})  # z given, so use that
{'x': 1, 'y': 2, 'z': 4}
>>> map_arguments(func, [1, 2, 3], {})  # y given as positional, so use that
{'x': 1, 'y': 2, 'z': 3}
```

### chromadol.util.mapped_list(func, iterable=None, , max_workers=1)

Like builtin map, but returns a list,
and if iterable is None, returns a partial function that can directly be applied
to an iterable.
This is useful, for instance, for making a data loader from any single-uri loader.

### Example

```pycon
>>> mapped_list(lambda x: x**2, [1,2,3])
[1, 4, 9]
>>> squares = mapped_list(lambda x: x**2)  # iterable=None -> partial
>>> squares([1,2,3])
[1, 4, 9]
```

### chromadol.util.subdict(d, keys)

return a subdict with only the given keys

* **Return type:**
  [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)

```pycon
>>> subdict(dict(a=1, b=2, c=3), ['a', 'c'])
{'a': 1, 'c': 3}
```

### chromadol.util.transform_methods_to_keep_only_include_keys(instance, method_names=('get', 'query'))

Wraps all methods that contain an `include` argument so they filter their output
accordingly.


# about-this-build.html.md

<!-- generated by epythet -->

# About this build

This documentation was built on **2026-09-22 14:47 UTC** from commit <a href="https://github.com/i2mint/chromadol/commit/9a3e4aafa42e6d9d238a5414efe0339a11c08cdb"><code>9a3e4aa</code></a> on branch <code>master</code>, for **chromadol 0.1.7** (from <code>pyproject.toml</code>).

#### NOTE
Nothing suggests a mismatch: the tree was clean at the commit above, and the documented version is the one on PyPI.

## Source

|                     |                                                                                                                                                         |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| Commit              | <a href="https://github.com/i2mint/chromadol/commit/9a3e4aafa42e6d9d238a5414efe0339a11c08cdb"><code>9a3e4aafa42e6d9d238a5414efe0339a11c08cdb</code></a> |
| Branch              | <code>master</code>                                                                                                                                     |
| Tags at this commit | <code>0.1.7</code>                                                                                                                                      |
| Working tree        | clean                                                                                                                                                   |
| Remote              | <code>https://github.com/i2mint/chromadol</code>                                                                                                        |

## Continuous integration

|              |                                                                                            |
|--------------|--------------------------------------------------------------------------------------------|
| Repository   | <code>i2mint/chromadol</code>                                                              |
| Run          | <a href="https://github.com/i2mint/chromadol/actions/runs/35742467001">35742467001</a>     |
| Ref          | <code>refs/heads/master</code>                                                             |
| Event commit | <code>ddc30a4741b8a5b49d7f9b45d2b824884cc1d4b2</code> (in the history of the built commit) |

## Tools

|          |         |
|----------|---------|
| epythet  | 0.2.12  |
| Sphinx   | 9.1.0   |
| docutils | 0.22.4  |
| Python   | 3.12.14 |

## Configuration as resolved

|               |                                                                   |
|---------------|-------------------------------------------------------------------|
| theme         | <code>auto</code> (Sphinx theme <code>sphinxawesome_theme</code>) |
| accent        | <code>#006c35</code>                                              |
| api_generator | <code>autosummary</code>                                          |
| ignore        | <code>tests/</code>, <code>scrap/</code>, <code>examples/</code>  |
| agent_outputs | <code>true</code>                                                 |
| aggregates    | <code>md</code>                                                   |
| ai_artifacts  | <code>true</code>                                                 |

## Package on PyPI

Latest release: <a href="https://pypi.org/project/chromadol/0.1.7/">0.1.7</a>, the same as the documented version.

## Reproduce

```bash
git clone https://github.com/i2mint/chromadol && cd chromadol
git checkout 9a3e4aafa42e6d9d238a5414efe0339a11c08cdb
pip install "epythet==0.2.12"
epythet quickstart . --ignore tests/ scrap/ examples/
```

The same data, for machines: <a href="build_info.json"><code>build_info.json</code></a> (schema version 1).


# api.html.md

# API reference

| [`chromadol`](_autosummary/chromadol.html.md#module-chromadol)   | Data Object Layer (DOL) for ChromaDB   |
|-------------------------------------------------------------------------------|----------------------------------------|