API reference

The API for the items project.

This module provides classes and functions to interact with the items database programmatically.

items.api.Item class

class items.api.Item(summary: str = None, owner: str = None, state: str = 'todo', id: int = None)

Defines the items type with the attributes summary, owner and state.

Parameters:

• summary (str) – Summary of an item. Defaults to None.

• owner (str) – The person working on an item. Defaults to None.

• state (str) – The status of a task. Defaults to ‘todo’.

• id (int) – The unique identifier for the item. Defaults to None.

classmethod from_dict(d)

Return an item instance from a dict.

Parameters:

d (dict) – Dictionary containing item attributes.

Returns:

Item instance created from dictionary values.

Return type:

Item

to_dict()

Return a dict from an item instance.

Returns:

Dictionary containing the item’s attributes.

Return type:

dict

items.api.ItemsDB class

class items.api.ItemsDB(db_path)

Database class to access the items_db file.

Parameters:

db_path (str or pathlib.Path) – Path to the database file.

add_item(item: Item)

Add an item to the database.

Parameters:

item (Item) – The Item instance to add to the database.

Returns:

The item id of the newly added item.

Return type:

int

Raises:

MissingSummaryError – If the item has no summary.

close()

Close the database connection.

count()

Return the number of items in the database.

Returns:

The number of items in the database.

Return type:

int

delete_all()

Remove all items from the database.

delete_item(item_id: int)

Remove an item from the database.

Parameters:

item_id (int) – The ID of the item to delete.

Raises:

InvalidItemIdError – If no item with the given ID exists.

finish(item_id: int)

Set an item state to ‘done’.

Parameters:

item_id (int) – The ID of the item to update.

Raises:

InvalidItemIdError – If no item with the given ID exists.

get_item(item_id: int)

Return an item for the corresponding id.

Parameters:

item_id (int) – ID of the item to retrieve.

Returns:

Item instance from the database.

Return type:

Item

Raises:

InvalidItemIdError – If no item with the given ID exists.

list_items(owner=None, state=None)

Return a list of items filtered by owner and/or state.

Parameters:

• owner (str, optional) – Filter items by this owner. Defaults to

• None.

• state (str, optional) – Filter items by this state. Defaults to

• None.

Returns:

List of Item instances matching the filters. If no filters are specified, returns all items.

Return type:

list[Item]

path()

Return the path to the database.

Returns:

Path to the database file.

Return type:

str or pathlib.Path

start(item_id: int)

Set an item state to ‘in progress’.

Parameters:

item_id (int) – The ID of the item to update.

Raises:

InvalidItemIdError – If no item with the given ID exists.

update_item(item_id: int, item_mods: Item)

Update an item with modifications.

Parameters:

• item_id (int) – The ID of the item to update.

• item_mods (Item) – Item instance containing the modifications to

• apply.

Raises:

InvalidItemIdError – If no item with the given ID exists.

Exceptions

exception items.api.ItemsError

Base exception class for the items module.

Parent class for MissingSummaryError and InvalidItemIdError exceptions.

exception items.api.MissingSummaryError

Exception raised when an item is added without a summary.

Raised when items.api.ItemsDB.add_item is called with an item that has no summary.

exception items.api.InvalidItemIdError

Exception raised when an operation is performed with an invalid item ID.

Raised when trying to access or modify an item that doesn’t exist.