API Reference
dict

dbzero.dict(*args, **kwargs)

The dbzero.dict() method creates a persistent, mutable mapping object. It's designed to be a drop-in replacement for Python's built-in dict, offering the same familiar API but with the added benefit of being automatically managed and persisted by the dbzero engine.

Signature

db0.dict([initial_data], **kwargs)

Parameters

The constructor accepts the same arguments as the standard Python dict() constructor:

  • initial_data (optional): Can be a mapping object (like another dict), an iterable of key-value pairs (like a list of tuples), or a zip object.
  • **kwargs (optional): You can also initialize the dictionary with keyword arguments.

Returns

A dbzero.dict object. This object behaves like a standard Python dict, supporting key-based access, iteration, and standard dictionary methods.

Side Effects

  • All changes to a dbzero.dict instance (adding, updating, or removing items) are tracked by dbzero.
  • The dictionary's state is saved to the database upon dbzero.commit().
  • When items are removed (e.g., via pop(), clear(), or del), or when a dbzero.dict is deleted, dbzero will automatically garbage collect any underlying dbzero objects that are no longer referenced, freeing up memory and disk space.

Usage and Examples

Creating a Dictionary

You can create a dbzero.dict in several ways, just like a regular dict.

# Create an empty dictionary
d1 = db0.dict()
 
# Create from keyword arguments
d2 = db0.dict(name="Alice", age=30)
print(d2["name"]) # Outputs: Alice
 
# Create from a list of tuples
d3 = db0.dict([("name", "Bob"), ("age", 25)])
print(d3["age"]) # Outputs: 25
 
# Create from another dictionary
d4 = db0.dict({"name": "Charlie", "age": 35})
print(d4) # Outputs: {'name': 'Charlie', 'age': 35}

Basic Operations

dbzero.dict supports all the fundamental dictionary operations.

data = db0.dict(name="Alice", age=30)
 
# Access an item
print(data["name"]) # Outputs: Alice
 
# Add or update an item
data["city"] = "New York"
data["age"] = 31
 
# Check for a key's existence
if "city" in data:
    print("City is present.")
 
# Delete an item
del data["age"]
assert "age" not in data
 
# Get the number of items
print(len(data)) # Outputs: 2

Keys and Values

Keys must be hashable, just like in a standard Python dict. This includes types like strings, numbers, tuples (if their elements are hashable), and even dbzero objects. Values can be of any type, including other dbzero collections.

# Using a tuple with a dbzero object as a key
UserProfile = db0.class("UserProfile", "user_id", "email")
user = UserProfile(123, "test@example.com")
stats = db0.dict()
 
stats[(user, "logins")] = 15
print(stats[(user, "logins")]) # Outputs: 15
 
# Nesting dictionaries
complex_data = db0.dict()
complex_data["user_a"] = {"permissions": ["read", "write"]}
 
print(complex_data["user_a"]["permissions"]) # Outputs: ['read', 'write']

Methods

dbzero.dict implements the full dict API. Here are some of the most common methods:

  • .clear(): Removes all items from the dictionary.
  • .copy(): Returns a shallow copy of the dictionary.
  • .get(key[, default]): Returns the value for key if it's in the dictionary, otherwise returns default. If default isn't given, it defaults to None.
  • .items(): Returns a view object that displays a list of a given dictionary's key-value tuple pairs.
  • .keys(): Returns a view object that displays a list of all the keys.
  • .values(): Returns a view object that displays a list of all the values.
  • .pop(key[, default]): Removes the specified key and returns the corresponding value. If the key is not found, default is returned if given, otherwise a KeyError is raised.
  • .setdefault(key[, default]): If key is in the dictionary, returns its value. If not, inserts key with a value of default and returns default. default defaults to None.
  • .update([other]): Updates the dictionary with the key/value pairs from other, overwriting existing keys.
deserializeenum