API reference¶

Connecting to a database¶

wurm.setup_connection(conn)¶

Call this once in each OS thread with a sqlite3.Connection, before accessing the database via wurm.

This records the connection and ensures all tables are created.

Defining tables¶

class wurm.Table¶

Baseclass for your own tables. Tables must be dataclasses.

Use the keyword argument name in the class definition to set the table name:

@dataclass
class MyTable(Table, name='mytable'):
    ...

If not given, wurm uses the class name to automatically derive a suitable table name.

classmethod query(**kwargs)¶

Create a query object.

The names of keywords passed should be rowid or any of the fields defined on the table.

The values can either be Python values matching the types of the relevant fields, or the same wrapped in one of lt(), gt(), le(), ge(), eq() or ne(). When unwrapped, the behavior matches that of values wrapped in eq().

Merely creating a query does not access the database.

Returns: A query for this table.
Return type: Query

classmethod __len__()¶: The total number of rows in this table. A shortcut for len(table.query()).

Note

This method accesses the connected database.

classmethod __iter__()¶: Iterate over all the objects in the table. A shortcut for iter(table.query())

Note

This method accesses the connected database.

commit()¶: Commits any changes to the object to the database.

Note

This method accesses the connected database.

delete()¶

Deletes this object from the database.

Note

This method accesses the connected database.

Raises: ValueError – if called twice on the same instance, or called on a fresh instance that has not been inserted yèt.

insert()¶: Insert a new object into the database.

Note

This method accesses the connected database.

wurm.Unique¶

Using Unique[T] as a type annotation in a table definition is equivalent to using T, except that a UNIQUE index is created for the field. Note that SQL considers None values to be different from other None values for this purpose.

If you attempt to call Table.insert() or Table.commit() in a way that would violate such a constraint, the operation is rolled back, and a WurmError is raised.

Queries¶

Query objects¶

Most advanced queries will be done through Query objects, that can be created either explicitly through their constructor, or by calling Table.query().

class wurm.Query(table: type, filters: dict)¶

Represents one or more queries on a specified table.

Query(table, filters) is equivalent to table.query(**filters)`

__iter__()¶

Iterate over the results of this query.

Note

This method accesses the connected database.

Equivalent to select_with_limit() without specifying limit.

__len__()¶

Returns the number of rows matching this query.

Note

This method accesses the connected database.

Returns: number of matches
Return type: int

delete()¶

Delete the objects matching this query.

Warning

Calling this on an empty query deletes all rows in the database

Note

This method accesses the connected database.

Returns: the number of rows deleted
Return type: int

first()¶

Return the first result of this query.

Note

This method accesses the connected database.

Raises: WurmError – if this query returns zero results

one()¶

Return the only result of this query.

Note

This method accesses the connected database.

Raises: WurmError – if this query returns zero results or more than one

select_with_limit(limit=None)¶

Create an iterator over the results of this query.

This accesses the database.

Parameters: limit (int or None) – The number of results to limit this query to.
Returns: an iterator over the objects matching this query.

Comparators¶

wurm.lt(value)¶

wurm.le(value)¶

wurm.eq(value)¶

wurm.ne(value)¶

wurm.ge(value)¶

wurm.gt(value)¶

Used to wrap values in queries. These functions correspond to the special names for the Python comparison operators.

The expression

MyTable.query(a=le(1), b=gt(2), c=3, d=ne(4))

is roughly equivalent to

SELECT * FROM MyTable WHERE a <= 1 AND b > 2 AND c = 3 AND d != 4

Replacing c=3 with c=eq(3) is optional.

Exceptions¶

exception wurm.WurmError¶

General error for a database operation failing.

Its __cause__ attribute refers to the relevant sqlite3.Error when that exists.