Skip to content

API Reference

neodb.core.NeoDB

An in-memory database that manages named collections.

Attributes:

Name Type Description
dbname

The name of the database.
collections

A dictionary of collection names to NeoCollection instances.
Source code in neodb/core.py 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
class NeoDB:
    """An in-memory database that manages named collections.

    Attributes:
        dbname: The name of the database.
        collections: A dictionary of collection names to NeoCollection instances.
    """

    def __init__(self, dbname="neodb"):
        """Initializes NeoDB with the given database name.

        Args:
            dbname: The name of the database. Defaults to "neodb".
        """
        self.dbname = dbname
        self.collections = {}
        self._collection_number = 0

    def collection(self, collection_name=None):
        """Gets or creates a collection by name.

        If no name is provided, an auto-generated name is used
        (e.g., "Collection_1", "Collection_2"). If a collection with the
        given name already exists, the existing instance is returned.

        Args:
            collection_name: The name of the collection. Defaults to None,
                which triggers auto-naming.

        Returns:
            The NeoCollection instance for the given name.
        """
        if collection_name is None:
            self._collection_number += 1
            collection_name = f"Collection_{self._collection_number}"
        if collection_name not in self.collections:
            collection = NeoCollection(collection_name)
            self.collections[collection_name] = collection
            return collection
        return self.collections[collection_name]

    def list_collections(self) -> list:
        """Lists all collection names in the database.

        Returns:
            A list of collection name strings.
        """
        return list(self.collections.keys())

    def drop_collection(self, collection_name: str) -> bool:
        """Drops a collection by name.

        Args:
            collection_name: The name of the collection to drop.

        Returns:
            True if the collection existed and was dropped, False otherwise.
        """
        if collection_name in self.collections:
            del self.collections[collection_name]
            return True
        return False

__init__(dbname='neodb')

Initializes NeoDB with the given database name.

Parameters:

Name Type Description Default
dbname

The name of the database. Defaults to "neodb".

 'neodb'
Source code in neodb/core.py 
 9
10
11
12
13
14
15
16
17
def __init__(self, dbname="neodb"):
    """Initializes NeoDB with the given database name.

    Args:
        dbname: The name of the database. Defaults to "neodb".
    """
    self.dbname = dbname
    self.collections = {}
    self._collection_number = 0

collection(collection_name=None)

Gets or creates a collection by name.

If no name is provided, an auto-generated name is used (e.g., "Collection_1", "Collection_2"). If a collection with the given name already exists, the existing instance is returned.

Parameters:

Name Type Description Default
collection_name

The name of the collection. Defaults to None, which triggers auto-naming.

 None

Returns:

Type Description

The NeoCollection instance for the given name.
Source code in neodb/core.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def collection(self, collection_name=None):
    """Gets or creates a collection by name.

    If no name is provided, an auto-generated name is used
    (e.g., "Collection_1", "Collection_2"). If a collection with the
    given name already exists, the existing instance is returned.

    Args:
        collection_name: The name of the collection. Defaults to None,
            which triggers auto-naming.

    Returns:
        The NeoCollection instance for the given name.
    """
    if collection_name is None:
        self._collection_number += 1
        collection_name = f"Collection_{self._collection_number}"
    if collection_name not in self.collections:
        collection = NeoCollection(collection_name)
        self.collections[collection_name] = collection
        return collection
    return self.collections[collection_name]

drop_collection(collection_name)

Drops a collection by name.

Parameters:

Name Type Description Default
collection_name str

The name of the collection to drop.

 required

Returns:

Type Description
bool

True if the collection existed and was dropped, False otherwise.
Source code in neodb/core.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
def drop_collection(self, collection_name: str) -> bool:
    """Drops a collection by name.

    Args:
        collection_name: The name of the collection to drop.

    Returns:
        True if the collection existed and was dropped, False otherwise.
    """
    if collection_name in self.collections:
        del self.collections[collection_name]
        return True
    return False

list_collections()

Lists all collection names in the database.

Returns:

Type Description
list

A list of collection name strings.
Source code in neodb/core.py 
42
43
44
45
46
47
48
def list_collections(self) -> list:
    """Lists all collection names in the database.

    Returns:
        A list of collection name strings.
    """
    return list(self.collections.keys())

neodb.core.NeoCollection

A key-value store with optional indexing support.

Records are stored as simple key-value pairs. Optional indexes allow fast lookups by index name and value. A reverse index is maintained for efficient cleanup on delete or update.

Attributes:

Name Type Description
name

The name of the collection.
records

A dictionary mapping keys to their values.
indexes

A forward index mapping {index_name: {index_value: {keys}}}.
reverse_indexes

A reverse index mapping {key: {index_name: index_value}}.
Source code in neodb/core.py 
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
class NeoCollection:
    """A key-value store with optional indexing support.

    Records are stored as simple key-value pairs. Optional indexes allow
    fast lookups by index name and value. A reverse index is maintained
    for efficient cleanup on delete or update.

    Attributes:
        name: The name of the collection.
        records: A dictionary mapping keys to their values.
        indexes: A forward index mapping
            ``{index_name: {index_value: {keys}}}``.
        reverse_indexes: A reverse index mapping
            ``{key: {index_name: index_value}}``.
    """

    def __init__(self, collection_name):
        """Initializes a NeoCollection with the given name.

        Args:
            collection_name: The name of the collection.
        """
        self.name = collection_name
        self.records = dict()
        self.indexes = dict()
        self.reverse_indexes = dict()

    def get(self, key):
        """Retrieves the value for a given key.

        Args:
            key: The key to look up.

        Returns:
            The stored value, or None if the key does not exist.
        """
        record_value = self.records.get(key, None)
        return record_value

    def put(self, key, value, indexes=None):
        """Stores a value under the given key with optional indexes.

        If the key already exists, the old value and its indexes are
        replaced. Index entries are automatically maintained.

        Args:
            key: The key to store the value under.
            value: The value to store.
            indexes: An optional dictionary of ``{index_name: index_value}``
                pairs for indexing the record. Defaults to None.
        """
        self._delete_indexes(key)
        self.records[key] = value
        if indexes:
            for index_name, index_value in indexes.items():
                self.indexes.setdefault(index_name, dict()).setdefault(index_value, set()).add(key)
                self.reverse_indexes.setdefault(key, dict())[index_name] = index_value

    def _delete_indexes(self, key):
        """Removes all index entries associated with a key.

        Uses the reverse index to find and clean up forward index entries.
        Empty index buckets are removed to keep the index structure clean.

        Args:
            key: The key whose index entries should be removed.
        """
        index_to_remove = self.reverse_indexes.pop(key, None)
        if index_to_remove:
            for index_name, index_value in index_to_remove.items():
                if index_name in self.indexes and index_value in self.indexes[index_name]:
                    self.indexes[index_name][index_value].discard(key)
                    if not self.indexes[index_name][index_value]:
                        del self.indexes[index_name][index_value]
                    if not self.indexes[index_name]:
                        del self.indexes[index_name]

    def delete(self, key):
        """Deletes a record and cleans up its indexes.

        Args:
            key: The key to delete.

        Returns:
            True if the key existed and was deleted, False otherwise.
        """
        self._delete_indexes(key)
        return self.records.pop(key, None) is not None

    def find_keys(self, index_name, index_value):
        """Finds all keys matching a given index name and value.

        Args:
            index_name: The name of the index to search.
            index_value: The index value to match.

        Returns:
            A set of keys matching the index, or an empty set if no
            match is found.
        """
        return self.indexes.get(index_name, {}).get(index_value, set())

__init__(collection_name)

Initializes a NeoCollection with the given name.

Parameters:

Name Type Description Default
collection_name

The name of the collection.

 required
Source code in neodb/core.py 
81
82
83
84
85
86
87
88
89
90
def __init__(self, collection_name):
    """Initializes a NeoCollection with the given name.

    Args:
        collection_name: The name of the collection.
    """
    self.name = collection_name
    self.records = dict()
    self.indexes = dict()
    self.reverse_indexes = dict()

delete(key)

Deletes a record and cleans up its indexes.

Parameters:

Name Type Description Default
key

The key to delete.

 required

Returns:

Type Description

True if the key existed and was deleted, False otherwise.
Source code in neodb/core.py 
142
143
144
145
146
147
148
149
150
151
152
def delete(self, key):
    """Deletes a record and cleans up its indexes.

    Args:
        key: The key to delete.

    Returns:
        True if the key existed and was deleted, False otherwise.
    """
    self._delete_indexes(key)
    return self.records.pop(key, None) is not None

find_keys(index_name, index_value)

Finds all keys matching a given index name and value.

Parameters:

Name Type Description Default
index_name

The name of the index to search.

 required
index_value

The index value to match.

 required

Returns:

Type Description

A set of keys matching the index, or an empty set if no

match is found.
Source code in neodb/core.py 
154
155
156
157
158
159
160
161
162
163
164
165
def find_keys(self, index_name, index_value):
    """Finds all keys matching a given index name and value.

    Args:
        index_name: The name of the index to search.
        index_value: The index value to match.

    Returns:
        A set of keys matching the index, or an empty set if no
        match is found.
    """
    return self.indexes.get(index_name, {}).get(index_value, set())

get(key)

Retrieves the value for a given key.

Parameters:

Name Type Description Default
key

The key to look up.

 required

Returns:

Type Description

The stored value, or None if the key does not exist.
Source code in neodb/core.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def get(self, key):
    """Retrieves the value for a given key.

    Args:
        key: The key to look up.

    Returns:
        The stored value, or None if the key does not exist.
    """
    record_value = self.records.get(key, None)
    return record_value

put(key, value, indexes=None)

Stores a value under the given key with optional indexes.

If the key already exists, the old value and its indexes are replaced. Index entries are automatically maintained.

Parameters:

Name Type Description Default
key

The key to store the value under.

 required
value

The value to store.

 required
indexes

An optional dictionary of {index_name: index_value} pairs for indexing the record. Defaults to None.

 None
Source code in neodb/core.py 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def put(self, key, value, indexes=None):
    """Stores a value under the given key with optional indexes.

    If the key already exists, the old value and its indexes are
    replaced. Index entries are automatically maintained.

    Args:
        key: The key to store the value under.
        value: The value to store.
        indexes: An optional dictionary of ``{index_name: index_value}``
            pairs for indexing the record. Defaults to None.
    """
    self._delete_indexes(key)
    self.records[key] = value
    if indexes:
        for index_name, index_value in indexes.items():
            self.indexes.setdefault(index_name, dict()).setdefault(index_value, set()).add(key)
            self.reverse_indexes.setdefault(key, dict())[index_name] = index_value