API

Helpers

invalidate(*keys)

Delete one or more exact cache keys.

Source code in backend/backend/api.py

def invalidate(*keys):
    """Delete one or more exact cache keys."""
    cache.delete_many(keys)

invalidate_pattern(*patterns)

Delete all cache keys matching the given patterns.

Uses django-redis delete_pattern when available. Falls back to cache.clear() for non-Redis backends (e.g. LocMemCache).

Source code in backend/backend/api.py

def invalidate_pattern(*patterns):
    """Delete all cache keys matching the given patterns.

    Uses django-redis ``delete_pattern`` when available. Falls back to
    ``cache.clear()`` for non-Redis backends (e.g. LocMemCache).
    """
    for pattern in patterns:
        if hasattr(cache, "delete_pattern"):
            cache.delete_pattern(pattern)
        else:
            cache.clear()

CustomUser

Views

list_users(request)

The function list_users retrieves a list of CustomUser objects.

Endpoint

• Path: /api/v2/users
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required

Returns:

Type	Description
List[CustomUserSchema]	List of CustomUser objects.

Source code in backend/backend/api.py

@api.get("/users", response=List[CustomUserSchema])
def list_users(request):
    """
    The function `list_users` retrieves a list of CustomUser objects.

    Endpoint:
        - **Path**: `/api/v2/users`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.

    Returns:
        (List[CustomUserSchema]): List of CustomUser objects.
    """
    cached = cache.get("users")
    if cached is not None:
        return cached
    qs = list(CustomUser.objects.all())
    cache.set("users", qs, CACHE_TTL)
    return qs

me(request)

The function me retrieves the CustomUser object of the logged in user.

Endpoint

• Path: /api/v2/me
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required

Returns:

Type	Description
CustomUserSchema	The CustomUser object of the logged in user.

Source code in backend/backend/api.py

@api.get("/me", response=CustomUserSchema)
def me(request):
    """
    The function `me` retrieves the CustomUser object of the logged in user.

    Endpoint:
        - **Path**: `/api/v2/me`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.

    Returns:
        (CustomUserSchema): The CustomUser object of the logged in user.
    """
    if not request.user.is_authenticated:
        raise HttpError(401, "Not authenticated")
    return request.user

Schemas

LoginUserSchema

Schema to represent a LoginUserSchema.

Attributes:

Name	Type	Description
email	str	User email.
profile_picture	str	Path to user picutre. Default=None.
male	bool	Toggle if male or not.
user_color	str	Hex value of a user color.
first_name	str	User first name.
last_name	str	User last name.
fullname	str	Full name of user.
is_superuser	bool	Toggle if user is superuser.
is_staff	bool	Toggle if user is staff.
is_active	bool	Toggle if user is active.
groups	List[int]	List of group ids user belongs to.

Source code in backend/backend/api.py

class LoginUserSchema(Schema):
    """
    Schema to represent a LoginUserSchema.

    Attributes:
        email (str): User email.
        profile_picture (str): Path to user picutre. Default=None.
        male (bool): Toggle if male or not.
        user_color (str): Hex value of a user color.
        first_name (str): User first name.
        last_name (str): User last name.
        fullname (str): Full name of user.
        is_superuser (bool): Toggle if user is superuser.
        is_staff (bool): Toggle if user is staff.
        is_active (bool): Toggle if user is active.
        groups (List[int]): List of group ids user belongs to.
    """

    email: str
    profile_picture: Optional[str] = None
    male: bool
    user_color: str
    first_name: str
    last_name: str
    fullname: str
    is_superuser: bool
    is_staff: bool
    is_active: bool
    groups: List[int]

CustomUserSchema

Schema to represent a CustomUserSchema.

Attributes:

Name	Type	Description
id	int	ID of the user.
email	str	Email of the user.
profile_picture	str	Path to the user profile picture. Default=None.
male	bool	Toggle if user is male.
user_color	str	Hex value of a user color.
first_name	str	User first name.
last_name	str	User last name.
fullname	str	Full name of user.
is_superuser	bool	Toggle if user is superuser.
is_staff	bool	Toggle if user is staff.
is_active	bool	Toggle if user is active.

Source code in backend/backend/api.py

class CustomUserSchema(Schema):
    """
    Schema to represent a CustomUserSchema.

    Attributes:
        id (int): ID of the user.
        email (str): Email of the user.
        profile_picture (str): Path to the user profile picture. Default=None.
        male (bool): Toggle if user is male.
        user_color (str): Hex value of a user color.
        first_name (str): User first name.
        last_name (str): User last name.
        fullname (str): Full name of user.
        is_superuser (bool): Toggle if user is superuser.
        is_staff (bool): Toggle if user is staff.
        is_active (bool): Toggle if user is active.
    """

    id: int
    email: str
    profile_picture: Optional[str] = None
    male: bool
    user_color: str
    first_name: str
    last_name: str
    fullname: str
    is_superuser: bool
    is_staff: bool
    is_active: bool
    groups: List[int]
    notify_enabled: bool
    notify_time: time

    @staticmethod
    def resolve_groups(obj):
        """
        Resolve the groups field to a list of group IDs.

        Handles both a CustomUser model (groups is a related manager) and an
        already-serialized value (a list of ids), so the schema survives
        re-validation when used as a nested field (e.g. ChoreOut.assignee).

        Args:
            obj (CustomUser): The user instance being serialized.

        Returns:
            List[int]: List of group IDs the user belongs to.
        """
        groups = getattr(obj, "groups", None)
        if groups is None:
            return []
        if hasattr(groups, "all"):
            return [group.id for group in groups.all()]
        return list(groups)

AreaGroup

Views

create_areagroup(request, payload)

The function create_areagroup creates an AreaGroup object.

Endpoint

• Path: /api/v2/areagroups
• Method: POST

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
payload	AreaGroupIn	An AreaGroup object to create.	required

Returns:

Type	Description
int	The ID of the newly created AreaGroup object.

Source code in backend/backend/api.py

@api.post("/areagroups")
def create_areagroup(request, payload: AreaGroupIn):
    """
    The function `create_areagroup` creates an AreaGroup object.

    Endpoint:
        - **Path**: `/api/v2/areagroups`
        - **Method**: `POST`

    Args:
        request (HttpRequest): The HTTP request object.
        payload (AreaGroupIn): An AreaGroup object to create.

    Returns:
        (int): The ID of the newly created AreaGroup object.
    """
    data = payload.model_dump()
    # A new group goes to the end unless the caller asks for a position. The
    # frontend used to send a hardcoded 1 for every group, so ordering was a
    # twelve-way tie broken by whatever the database felt like.
    if not data.get("group_order"):
        highest = AreaGroup.objects.aggregate(Max("group_order"))["group_order__max"]
        data["group_order"] = (highest or 0) + 1
    areagroup = AreaGroup.objects.create(**data)
    invalidate("areagroups")
    notify("areagroups")
    return {"id": areagroup.id}

get_areagroup(request, areagroup_id)

The function get_areagroup retrieves an AreaGroup object.

Endpoint

• Path: /api/v2/areagroups/{areagroup_id}
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
areagroup_id	int	ID of the AreaGroup object to retreive.	required

Returns:

Type	Description
AreaGroupOut	The AreaGroup object.

Source code in backend/backend/api.py

@api.get("/areagroups/{areagroup_id}", response=AreaGroupOut)
def get_areagroup(request, areagroup_id: int):
    """
    The function `get_areagroup` retrieves an AreaGroup object.

    Endpoint:
        - **Path**: `/api/v2/areagroups/{areagroup_id}`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        areagroup_id (int): ID of the AreaGroup object to retreive.

    Returns:
        (AreaGroupOut): The AreaGroup object.
    """
    areagroup = get_object_or_404(AreaGroup, id=areagroup_id)
    return areagroup

list_areagroups(request)

The function list_areagroups retrieves a list of AreaGroup objects.

Endpoint

• Path: /api/v2/areagroups
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required

Returns:

Type	Description
List[AreaGroupOut]	List of AreaGroup objects.

Source code in backend/backend/api.py

@api.get("/areagroups", response=List[AreaGroupOut])
def list_areagroups(request):
    """
    The function `list_areagroups` retrieves a list of AreaGroup objects.

    Endpoint:
        - **Path**: `/api/v2/areagroups`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.

    Returns:
        (List[AreaGroupOut]): List of AreaGroup objects.
    """
    cached = cache.get("areagroups")
    if cached is not None:
        return cached
    # group_order exists precisely to order this list, and nothing was using it:
    # a bare .all() returns database order, so every group picker in the app was
    # in arbitrary order. group_name breaks ties left over from the era when the
    # frontend hardcoded group_order=1 on every group it created.
    qs = list(AreaGroup.objects.all().order_by("group_order", "group_name"))
    cache.set("areagroups", qs, CACHE_TTL)
    return qs

update_areagroup(request, areagroup_id, payload)

The function update_areagroup updates a given AreaGroup object.

Endpoint

• Path: /api/v2/areagroups/{areagroup_id}
• Method: PUT

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
areagroup_id	int	ID of the AreaGroup object to update.	required
payload	AreaGroupIn	AreaGroup object with updates to apply.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.put("/areagroups/{areagroup_id}")
def update_areagroup(request, areagroup_id: int, payload: AreaGroupIn):
    """
    The function `update_areagroup` updates a given AreaGroup object.

    Endpoint:
        - **Path**: `/api/v2/areagroups/{areagroup_id}`
        - **Method**: `PUT`

    Args:
        request (HttpRequest): The HTTP request object.
        areagroup_id (int): ID of the AreaGroup object to update.
        payload (AreaGroupIn): AreaGroup object with updates to apply.

    Returns:
        (str): Returns `success` if successful.
    """
    areagroup = get_object_or_404(AreaGroup, id=areagroup_id)
    areagroup.group_name = payload.group_name
    # group_order is optional on the way in (see AreaGroupIn), but the column is
    # a non-null IntegerField -- assigning None unconditionally would turn a
    # rename that omits the order into a 500. Omitting it means "leave it".
    if payload.group_order is not None:
        areagroup.group_order = payload.group_order
    areagroup.group_color = payload.group_color
    areagroup.save()
    invalidate("areagroups")
    notify("areagroups")
    return {"success": True}

delete_areagroup(request, areagroup_id, reassign_to=None)

The function delete_areagroup deletes a given AreaGroup object, moving any areas that belong to it into another group first.

Area.group is null=True, on_delete=SET_DEFAULT, default=1, which made the unguarded delete this replaces unsafe in three separate ways:

1. Deleting an ordinary group silently moved its areas to group 1 -- no warning, no say in the destination.
2. Deleting group 1 set its own areas' group_id to 1, the row being deleted, violating the foreign key.
3. Any area left group-less returned 500 from /areas and /chores, because AreaOut.group was non-Optional. (That schema is fixed too, but an area silently losing its group is still wrong.)

The reassignment is therefore explicit and happens before the delete, so SET_DEFAULT never fires at all.

Endpoint

• Path: /api/v2/areagroups/{areagroup_id}
• Method: DELETE

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
areagroup_id	int	ID of the AreaGroup object to delete.	required
reassign_to	int	ID of the group to move this group's areas into. Defaults to the lowest-ordered remaining group.	None

Returns:

Type	Description
dict	success, the destination group id, and how many areas moved.

Source code in backend/backend/api.py

@api.delete("/areagroups/{areagroup_id}")
def delete_areagroup(request, areagroup_id: int, reassign_to: Optional[int] = None):
    """
    The function `delete_areagroup` deletes a given AreaGroup object, moving any
    areas that belong to it into another group first.

    Area.group is `null=True, on_delete=SET_DEFAULT, default=1`, which made the
    unguarded delete this replaces unsafe in three separate ways:

    1. Deleting an ordinary group silently moved its areas to group 1 -- no
       warning, no say in the destination.
    2. Deleting group 1 set its own areas' group_id to 1, the row being deleted,
       violating the foreign key.
    3. Any area left group-less returned 500 from /areas and /chores, because
       AreaOut.group was non-Optional. (That schema is fixed too, but an area
       silently losing its group is still wrong.)

    The reassignment is therefore explicit and happens before the delete, so
    SET_DEFAULT never fires at all.

    Endpoint:
        - **Path**: `/api/v2/areagroups/{areagroup_id}`
        - **Method**: `DELETE`

    Args:
        request (HttpRequest): The HTTP request object.
        areagroup_id (int): ID of the AreaGroup object to delete.
        reassign_to (int): ID of the group to move this group's areas into.
            Defaults to the lowest-ordered remaining group.

    Returns:
        (dict): `success`, the destination group id, and how many areas moved.
    """
    areagroup = get_object_or_404(AreaGroup, id=areagroup_id)

    remaining = AreaGroup.objects.exclude(id=areagroup_id).order_by(
        "group_order", "group_name"
    )

    # Areas have to land somewhere, so the last group cannot go.
    if not remaining.exists():
        raise HttpError(
            400,
            "This is the only area group. Create another one before deleting it.",
        )

    if reassign_to is None:
        destination = remaining.first()
    else:
        if reassign_to == areagroup_id:
            raise HttpError(400, "Cannot reassign areas to the group being deleted.")
        destination = get_object_or_404(AreaGroup, id=reassign_to)

    moved = Area.objects.filter(group_id=areagroup_id).update(group=destination)
    areagroup.delete()

    # Reassigning areas changes what /areas and /chores return, so those caches
    # have to go too -- the old version invalidated "areagroups" alone and left
    # every area still reporting its deleted group.
    invalidate("areas", "areagroups")
    invalidate_chores()
    notify("areagroups")
    notify("areas")
    return {"success": True, "reassigned_to": destination.id, "areas_moved": moved}

Schemas

AreaGroupIn

Schema to represent an AreaGroupIn.

Attributes:

Name	Type	Description
group_name	str	Area group name.
group_order	int	Area group order index. Optional; on create, a group with no order given is appended to the end of the list.
group_color	str	Hex value of area group color.

Source code in backend/backend/api.py

class AreaGroupIn(Schema):
    """
    Schema to represent an AreaGroupIn.

    Attributes:
        group_name (str): Area group name.
        group_order (int): Area group order index. Optional; on create, a group
            with no order given is appended to the end of the list.
        group_color (str): Hex value of area group color.
    """

    group_name: str
    group_order: Optional[int] = None
    group_color: str

AreaGroupOut

Schema to represent an AreaGroupOut.

Attributes:

Name	Type	Description
id	int	ID of area group.
group_name	str	Area group name.
group_order	int	Area group order index.
group_color	str	Hex value of area group color.

Source code in backend/backend/api.py

class AreaGroupOut(Schema):
    """
    Schema to represent an AreaGroupOut.

    Attributes:
        id (int): ID of area group.
        group_name (str): Area group name.
        group_order (int): Area group order index.
        group_color (str): Hex value of area group color.
    """

    id: int
    group_name: str
    group_order: int
    group_color: str

Area

Views

create_area(request, payload)

The function create_area creates an Area object.

Endpoint

• Path: /api/v2/areas
• Method: POST

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
payload	AreaIn	Area Object to create.	required

Returns:

Type	Description
int	ID of the newly created Area object.

Source code in backend/backend/api.py

@api.post("/areas")
def create_area(request, payload: AreaIn):
    """
    The function `create_area` creates an Area object.

    Endpoint:
        - **Path**: `/api/v2/areas`
        - **Method**: `POST`

    Args:
        request (HttpRequest): The HTTP request object.
        payload (AreaIn): Area Object to create.

    Returns:
        (int): ID of the newly created Area object.
    """
    area = Area.objects.create(**payload.model_dump())
    invalidate("areas", "areagroups")
    notify("areas")
    return {"id": area.id}

get_area(request, area_id)

The function get_area retrieves an Area object.

Endpoint

• Path: /api/v2/areas/{area_id}
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
area_id	int	ID of the Area object to retreive.	required

Returns:

Type	Description
AreaOut	The Area object.

Source code in backend/backend/api.py

@api.get("/areas/{area_id}", response=AreaOut)
def get_area(request, area_id: int):
    """
    The function `get_area` retrieves an Area object.

    Endpoint:
        - **Path**: `/api/v2/areas/{area_id}`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        area_id (int): ID of the Area object to retreive.

    Returns:
        (AreaOut): The Area object.
    """
    area = get_object_or_404(Area, id=area_id)
    return area

list_areas(request)

The function list_areas retrieves a list of Area objects.

Endpoint

• Path: /api/v2/areas
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required

Returns:

Type	Description
List[AreaOut]	List of Area objects.

Source code in backend/backend/api.py

@api.get("/areas", response=List[AreaOut])
def list_areas(request):
    """
    The function `list_areas` retrieves a list of Area objects.

    Endpoint:
        - **Path**: `/api/v2/areas`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.

    Returns:
        (List[AreaOut]): List of Area objects.
    """
    cached = cache.get("areas")
    if cached is not None:
        return cached
    qs = list(Area.objects.all().order_by("group__group_order", "area_name"))
    cache.set("areas", qs, CACHE_TTL)
    return qs

update_area(request, area_id, payload)

The function update_area updates a given Area object.

Endpoint

• Path: /api/v2/areas/{area_id}
• Method: PUT

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
area_id	int	ID of the Area object to update.	required
payload	AreaIn	Area object with updates to apply.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.put("/areas/{area_id}")
def update_area(request, area_id: int, payload: AreaIn):
    """
    The function `update_area` updates a given Area object.

    Endpoint:
        - **Path**: `/api/v2/areas/{area_id}`
        - **Method**: `PUT`

    Args:
        request (HttpRequest): The HTTP request object.
        area_id (int): ID of the Area object to update.
        payload (AreaIn): Area object with updates to apply.

    Returns:
        (str): Returns `success` if successful.
    """
    area = get_object_or_404(Area, id=area_id)
    area.area_name = payload.area_name
    area.area_icon = payload.area_icon
    area.group_id = payload.group_id
    area.save()
    invalidate("areas", "areagroups")
    notify("areas")
    return {"success": True}

delete_area(request, area_id)

The function delete_area deletes a given Area object.

Endpoint

• Path: /api/v2/areas/{area_id}
• Method: DELETE

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
area_id	int	ID of the Area object to delete.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.delete("/areas/{area_id}")
def delete_area(request, area_id: int):
    """
    The function `delete_area` deletes a given Area object.

    Endpoint:
        - **Path**: `/api/v2/areas/{area_id}`
        - **Method**: `DELETE`

    Args:
        request (HttpRequest): The HTTP request object.
        area_id (int): ID of the Area object to delete.

    Returns:
        (str): Returns `success` if successful.
    """
    area = get_object_or_404(Area, id=area_id)
    area.delete()
    invalidate("areas", "areagroups")
    notify("areas")
    return {"success": True}

Schemas

AreaIn

Schema to represent an AreaIn.

Attributes:

Name	Type	Description
area_name	str	Area name.
area_icon	str	Name of area icon.
group_id	int	ID of group object area belongs to.

Source code in backend/backend/api.py

class AreaIn(Schema):
    """
    Schema to represent an AreaIn.

    Attributes:
        area_name (str): Area name.
        area_icon (str): Name of area icon.
        group_id (int): ID of group object area belongs to.
    """

    area_name: str
    area_icon: str
    group_id: int

AreaOut

Schema to represent an AreaOut.

Attributes:

Name	Type	Description
id	int	ID of an area.
area_name	str	Area name.
area_icon	str	Name of area icon.
group_id	int	ID of group object area belongs to.
group	AreaGroupOut	Group object area belongs to.
dirtiness	int	Percentage of dirtiness for the area.
dueCount	int	Number of chores due for the area.
overdueCount	int	Number of chores already past their due date.
totalCount	int	Total number of chores for the area.
total_dirtiness	int	Total dirtiness of the area.

Source code in backend/backend/api.py

class AreaOut(Schema):
    """
    Schema to represent an AreaOut.

    Attributes:
        id (int): ID of an area.
        area_name (str): Area name.
        area_icon (str): Name of area icon.
        group_id (int): ID of group object area belongs to.
        group (AreaGroupOut): Group object area belongs to.
        dirtiness (int): Percentage of dirtiness for the area.
        dueCount (int): Number of chores due for the area.
        overdueCount (int): Number of chores already past their due date.
        totalCount (int): Total number of chores for the area.
        total_dirtiness (int): Total dirtiness of the area.
    """

    id: int
    area_name: str
    area_icon: str
    # Area.group is null=True with on_delete=SET_DEFAULT, so both of these can
    # legitimately be None. They were declared non-Optional, which meant a single
    # group-less area returned 500 from BOTH /areas and /chores -- the same shape
    # as the two Pydantic-v2 bugs that needed the v1.4.1 hotfix.
    group_id: Optional[int] = None
    group: Optional[AreaGroupOut] = None
    dirtiness: int
    dueCount: int
    overdueCount: int
    totalCount: int
    total_dirtiness: int

Month

Views

Schemas

MonthOut

Schema to represent a Month.

Attributes:

Name	Type	Description
id	int	ID of the month.
name	str	Name of the month.

Source code in backend/backend/api.py

class MonthOut(Schema):
    """
    Schema to represent a Month.

    Attributes:
        id (int): ID of the month.
        name (str): Name of the month.
    """

    id: int
    name: str

Chore

Views

create_chore(request, payload)

The function create_chore creates a new Chore object.

Endpoint

• Path: /api/v2/chores
• Method: POST

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
payload	ChoreIn	Chore object to create.	required

Returns:

Type	Description
int	ID of the newly created Chore object.

Source code in backend/backend/api.py

@api.post("/chores")
def create_chore(request, payload: ChoreIn):
    """
    The function `create_chore` creates a new Chore object.

    Endpoint:
        - **Path**: `/api/v2/chores`
        - **Method**: `POST`

    Args:
        request (HttpRequest): The HTTP request object.
        payload (ChoreIn): Chore object to create.

    Returns:
        (int): ID of the newly created Chore object.
    """
    # Convert active_months IDs into Month instances
    active_months = Month.objects.filter(id__in=payload.active_months)

    # Create the Chore object
    chore = Chore.objects.create(
        chore_name=payload.chore_name,
        area_id=payload.area_id,
        intervalNumber=payload.intervalNumber,
        unit=payload.unit,
        effort=payload.effort,
    )

    # Set the active_months field
    chore.active_months.set(active_months)

    invalidate_chores()
    invalidate("areas")
    notify("chores")
    return {"id": chore.id}

get_chore(request, chore_id)

The function get_chore retrieves an Chore object.

Endpoint

• Path: /api/v2/chores/{chore_id}
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
chore_id	int	ID of the Chore object to retreive.	required

Returns:

Type	Description
ChoreOut	The Chore object.

Source code in backend/backend/api.py

@api.get("/chores/{chore_id}", response=ChoreOut)
def get_chore(request, chore_id: int):
    """
    The function `get_chore` retrieves an Chore object.

    Endpoint:
        - **Path**: `/api/v2/chores/{chore_id}`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        chore_id (int): ID of the Chore object to retreive.

    Returns:
        (ChoreOut): The Chore object.
    """
    chore = get_object_or_404(Chore, id=chore_id)
    return chore

list_chores(request, inactive=False, timeframe=None, assignee_id=None, area_id=None, group_id=None, chore_name=None, overdue=False, sort='due')

The function list_chores retrieves a list of Chore objects.

Endpoint

• Path: /api/v2/chores
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
inactive	bool	Toggle retreiving inactive chores. Default=False.	False
timeframe	int	Days from today to retrieve. Retreives all if None. Default=None.	None
assignee_id	int	Filter chores by assigned CustomUser ID. Retreives all if None. Default=None.	None
area_id	int	Filter chores by Area ID. Retreives all if None. Default=None.	None
group_id	int	Filter chores by the AreaGroup their area belongs to. Default=None.	None
chore_name	str	Only chores with this name, case-insensitively. Lets one task -- dusting, say -- be worked through every area it exists in.	None
overdue	bool	Only chores whose due date has already passed. Default=False.	False
sort	str	One of due, name, effort, dirtiest. Default=due.	'due'

Returns:

Type	Description
List[ChoreOut]	List of Chore objects.

Source code in backend/backend/api.py

@api.get("/chores", response=List[ChoreOut])
def list_chores(
    request,
    inactive: bool = False,
    timeframe: Optional[int] = None,
    assignee_id: Optional[int] = None,
    area_id: Optional[int] = None,
    group_id: Optional[int] = None,
    chore_name: Optional[str] = None,
    overdue: bool = False,
    sort: str = "due",
):
    """
    The function `list_chores` retrieves a list of Chore objects.

    Endpoint:
        - **Path**: `/api/v2/chores`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        inactive (bool): Toggle retreiving inactive chores. Default=False.
        timeframe (int): Days from today to retrieve. Retreives all if None. Default=None.
        assignee_id (int): Filter chores by assigned CustomUser ID. Retreives all if None. Default=None.
        area_id (int): Filter chores by Area ID. Retreives all if None. Default=None.
        group_id (int): Filter chores by the AreaGroup their area belongs to. Default=None.
        chore_name (str): Only chores with this name, case-insensitively. Lets one
            task -- dusting, say -- be worked through every area it exists in.
        overdue (bool): Only chores whose due date has already passed. Default=False.
        sort (str): One of `due`, `name`, `effort`, `dirtiest`. Default=`due`.

    Returns:
        (List[ChoreOut]): List of Chore objects.
    """
    if sort not in CHORE_SORTS:
        allowed = ", ".join(sorted(CHORE_SORTS))
        raise HttpError(422, f"Unknown sort '{sort}'. Expected one of: {allowed}")

    # Every parameter has to be in the key. Adding a filter or a sort without
    # extending it serves one request's results to a differently-filtered one.
    cache_key = (
        f"chores:{inactive}:{timeframe}:{assignee_id}:{area_id}"
        f":{group_id}:{chore_name}:{overdue}:{sort}"
    )
    cached = cache.get(cache_key)
    if cached is not None:
        return cached

    # "dirtiest" still needs a stable base ordering, so ties after the Python
    # sort below fall back to something deterministic rather than to whatever
    # the database returns.
    ordering = CHORE_SORTS[sort] or CHORE_SORTS["due"]
    qs = Chore.objects.all().order_by(*ordering)

    if not inactive:
        qs = qs.filter(status=0)
    if timeframe is not None:
        today = timezone.localdate()
        target_date = today
        if timeframe > 0:
            target_date = today + timedelta(days=timeframe)
        qs = qs.filter(nextDue__lte=target_date)
    if overdue:
        # Strictly before today: something due today is not yet overdue, which
        # is also how ChoreCard's "Due today" vs "N days overdue" reads.
        #
        # localdate(), NOT now().date(). USE_TZ is on and TIME_ZONE is
        # America/New_York, so now().date() is the UTC date -- already tomorrow
        # from about 8pm Eastern. The pre-existing `timeframe` filter above had
        # the same bug: for those hours every evening it matched a day too far,
        # while Chore.duedays and Chore.dirtiness use date.today() and did not.
        qs = qs.filter(nextDue__lt=timezone.localdate())
    if assignee_id is not None:
        qs = qs.filter(assignee_id=assignee_id)
    if area_id is not None:
        qs = qs.filter(area_id=area_id)
    if group_id is not None:
        # Chores reach a group through their area.
        qs = qs.filter(area__group_id=group_id)
    if chore_name:
        # iexact rather than exact: the name is picked from a list the API
        # itself produced, but a filter that silently returns nothing over a
        # capitalisation difference is a bad way to find that out.
        qs = qs.filter(chore_name__iexact=chore_name)
    chore_list = []

    for chore in qs:
        active_months = list(chore.active_months.all())
        active_month_ids = [month.id for month in active_months]
        last_three_query = HistoryItem.objects.filter(chore=chore).order_by(
            "-completed_date"
        )[:3]
        last_three = []
        for item in last_three_query:
            display_name = ""
            if item.completed_by is None:
                # completed_by is SET_NULL on user delete; don't crash on it.
                display_name = "Unknown"
            elif item.completed_by.fullname == " ":
                display_name = item.completed_by.email
            else:
                display_name = item.completed_by.fullname
            last_three_object = LastHistoryItem(
                completed_date=item.completed_date,
                completed_by=display_name,
            )
            last_three.append(last_three_object)
        chore_data = ChoreOut(
            id=chore.id,
            chore_name=chore.chore_name,
            area_id=chore.area_id,
            area=chore.area,  # Assuming AreaOut is a valid representation
            nextDue=chore.nextDue,
            lastCompleted=chore.lastCompleted,
            intervalNumber=chore.intervalNumber,
            unit=chore.unit,
            active_months=active_month_ids,  # Set active_months to the list of IDs
            assignee_id=chore.assignee_id,
            assignee=chore.assignee,
            effort=chore.effort,
            vacationPause=chore.vacationPause,
            expand=chore.expand,
            dirtiness=chore.dirtiness,
            duedays=chore.duedays,
            last_three_history_items=last_three,
            status=chore.status,
        )
        chore_list.append(chore_data)

    if sort == "dirtiest":
        # Chore.dirtiness is computed per chore in Python, so this cannot be an
        # order_by. Sorted here on the built objects, which already carry the
        # value, rather than recomputing it.
        chore_list.sort(key=lambda c: c.dirtiness, reverse=True)

    cache.set(cache_key, chore_list, CACHE_TTL)
    return chore_list

update_chore(request, chore_id, payload)

The function update_chore updates a given Chore object.

Endpoint

• Path: /api/v2/chores/{chore_id}
• Method: PUT

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
chore_id	int	ID of the Chore object to update.	required
payload	ChoreIn	Chore object with updates to apply.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.put("/chores/{chore_id}")
def update_chore(request, chore_id: int, payload: ChoreIn):
    """
    The function `update_chore` updates a given Chore object.

    Endpoint:
        - **Path**: `/api/v2/chores/{chore_id}`
        - **Method**: `PUT`

    Args:
        request (HttpRequest): The HTTP request object.
        chore_id (int): ID of the Chore object to update.
        payload (ChoreIn): Chore object with updates to apply.

    Returns:
        (str): Returns `success` if successful.
    """
    chore = get_object_or_404(Chore, id=chore_id)
    chore.chore_name = payload.chore_name
    chore.area_id = payload.area_id
    chore.status = payload.status
    chore.nextDue = payload.nextDue
    chore.lastCompleted = payload.lastCompleted
    chore.intervalNumber = payload.intervalNumber
    chore.unit = payload.unit
    chore.active_months.set(payload.active_months)
    chore.assignee_id = payload.assignee_id
    chore.effort = payload.effort
    chore.save()
    invalidate_chores()
    invalidate("areas")
    notify("chores")
    return {"success": True}

delete_chore(request, chore_id)

The function delete_chore deletes a given Chore object.

Endpoint

• Path: /api/v2/chores/{chore_id}
• Method: DELETE

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
chore_id	int	ID of the Chore object to delete.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.delete("/chores/{chore_id}")
def delete_chore(request, chore_id: int):
    """
    The function `delete_chore` deletes a given Chore object.

    Endpoint:
        - **Path**: `/api/v2/chores/{chore_id}`
        - **Method**: `DELETE`

    Args:
        request (HttpRequest): The HTTP request object.
        chore_id (int): ID of the Chore object to delete.

    Returns:
        (str): Returns `success` if successful.
    """
    chore = get_object_or_404(Chore, id=chore_id)
    chore.delete()
    invalidate_chores()
    invalidate("areas")
    notify("chores")
    return {"success": True}

calculate_duedays(next_due)

The function calculate_duedays calculates the days until due based on a given date.

Parameters:

Name	Type	Description	Default
next_due	date	The chore next due date.	required

Returns:

Type	Description
int	The number of days until due date.

Source code in backend/backend/api.py

def calculate_duedays(next_due):
    """
    The function `calculate_duedays` calculates the days until due based on a given date.

    Args:
        next_due (date): The chore next due date.

    Returns:
        (int): The number of days until due date.
    """
    delta = next_due - date.today()
    return delta.days

toggle_chore(request, chore_id, payload)

The function toggle_chore toggles wether a Chore is active/inactive.

Endpoint

• Path: /api/v2/chores/togglechore/{chore_id}
• Method: PATCH

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
chore_id	int	ID of the Chore object to update.	required
payload	ToggleActive	ToggleActive schema with status to set for the Chore.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.patch("/chores/togglechore/{chore_id}")
def toggle_chore(request, chore_id: int, payload: TogglActive):
    """
    The function `toggle_chore` toggles wether a Chore is active/inactive.

    Endpoint:
        - **Path**: `/api/v2/chores/togglechore/{chore_id}`
        - **Method**: `PATCH`

    Args:
        request (HttpRequest): The HTTP request object.
        chore_id (int): ID of the Chore object to update.
        payload (ToggleActive): ToggleActive schema with status to set for the Chore.

    Returns:
        (str): Returns `success` if successful.
    """
    chore = get_object_or_404(Chore, id=chore_id)
    chore.status = payload.status
    chore.save()
    invalidate_chores()
    invalidate("areas")
    notify("chores")
    return {"success": True}

snooze_chore(request, chore_id, payload)

The function snooze_chore updates a given Chore object's next due date.

Endpoint

• Path: /api/v2/chores/snoozechore/{chore_id}
• Method: PATCH

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
chore_id	int	ID of the Chore object to update.	required
payload	SnoozeChore	SnoozeChore schema with nextDue date to update chore with.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.patch("/chores/snoozechore/{chore_id}")
def snooze_chore(request, chore_id: int, payload: SnoozeChore):
    """
    The function `snooze_chore` updates a given Chore object's next due date.

    Endpoint:
        - **Path**: `/api/v2/chores/snoozechore/{chore_id}`
        - **Method**: `PATCH`

    Args:
        request (HttpRequest): The HTTP request object.
        chore_id (int): ID of the Chore object to update.
        payload (SnoozeChore): SnoozeChore schema with nextDue date to update chore with.

    Returns:
        (str): Returns `success` if successful.
    """
    chore = get_object_or_404(Chore, id=chore_id)
    chore.nextDue = payload.nextDue
    chore.save()
    invalidate_chores()
    invalidate("areas")
    notify("chores")
    return {"success": True}

claim_chore(request, chore_id, payload)

The function claim_chore assigns a given Chore object to a user.

Endpoint

• Path: /api/v2/chores/claimchore/{chore_id}
• Method: PATCH

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
chore_id	int	ID of the Chore object to update.	required
payload	ClaimChore	ClaimChore schema with a CustomUser ID to assign to chore.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.patch("/chores/claimchore/{chore_id}")
def claim_chore(request, chore_id: int, payload: ClaimChore):
    """
    The function `claim_chore` assigns a given Chore object to a user.

    Endpoint:
        - **Path**: `/api/v2/chores/claimchore/{chore_id}`
        - **Method**: `PATCH`

    Args:
        request (HttpRequest): The HTTP request object.
        chore_id (int): ID of the Chore object to update.
        payload (ClaimChore): ClaimChore schema with a CustomUser ID to assign to chore.

    Returns:
        (str): Returns `success` if successful.
    """
    chore = get_object_or_404(Chore, id=chore_id)
    chore.assignee_id = payload.assignee_id
    chore.save()
    invalidate_chores()
    notify("chores")
    return {"success": True}

complete_chore(request, chore_id, payload)

The function complete_chore completes a given Chore object.

Endpoint

• Path: /api/v2/chores/completechore/{chore_id}
• Method: PATCH

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
chore_id	int	ID of the Chore object to update.	required
payload	CompleteChore	CompleteChore schema to update Chore with.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.patch("/chores/completechore/{chore_id}")
def complete_chore(request, chore_id: int, payload: CompleteChore):
    """
    The function `complete_chore` completes a given Chore object.

    Endpoint:
        - **Path**: `/api/v2/chores/completechore/{chore_id}`
        - **Method**: `PATCH`

    Args:
        request (HttpRequest): The HTTP request object.
        chore_id (int): ID of the Chore object to update.
        payload (CompleteChore): CompleteChore schema to update Chore with.

    Returns:
        (str): Returns `success` if successful.
    """
    chore = get_object_or_404(Chore, id=chore_id)
    _apply_completion(chore, payload.lastCompleted, payload.completed_by_id)
    invalidate_chores("weeklytotals:*")
    invalidate("areas")
    notify("chores")
    notify("history")
    return {"success": True}

Schemas

ChoreIn

Schema to represent a Chore.

Attributes:

Name	Type	Description
chore_name	str	Name of the chore. Optional.
area_id	int	ID of the area. Optional.
intervalNumber	int	The repeat interval of the chore. Optional.
unit	str	The repeat unit of the chore. Optional.
active_months	List[int]	A list of month ids this chore is active. Optional.
effort	int	The effort required for this chore. Optional.
nextDue	date	The date chore is next due. Optional.
lastCompleted	date	The date chore was last completed. Optional.
assignee_id	int	ID of the assigned user. Optional.
status	int	ID of the status. Optional.

Source code in backend/backend/api.py

class ChoreIn(Schema):
    """
    Schema to represent a Chore.

    Attributes:
        chore_name (str): Name of the chore. Optional.
        area_id (int): ID of the area. Optional.
        intervalNumber (int): The repeat interval of the chore. Optional.
        unit (str): The repeat unit of the chore. Optional.
        active_months (List[int]): A list of month ids this chore is active. Optional.
        effort (int): The effort required for this chore. Optional.
        nextDue (date): The date chore is next due. Optional.
        lastCompleted (date): The date chore was last completed. Optional.
        assignee_id (int): ID of the assigned user. Optional.
        status (int): ID of the status. Optional.
    """

    chore_name: Optional[str] = None
    area_id: Optional[int] = None
    intervalNumber: Optional[int] = None
    unit: Optional[str] = None
    active_months: Optional[List[int]] = None
    effort: Optional[int] = None
    nextDue: Optional[date] = None
    lastCompleted: Optional[date] = None
    assignee_id: Optional[int] = None
    status: Optional[int] = None

ChoreOut

Schema to represent a Chore.

Attributes:

Name	Type	Description
id	int	ID of the chore.
chore_name	str	Name of the chore.
area_id	int	ID of an Area object assigned to the chore.
area	AreaOut	Area object assigned to the chore.
nextDue	date	Date chore is next due.
lastCompleted	date	Date chore was last completed.
intervalNumber	int	Repeat interval for the chore.
unit	str	Repeat unit for the chore.
active_months	List[int]	List of Month ids chode is active.
assignee_id	int	ID of a user assigned to the chore. Default=None.
effort	int	Effort required for the chore.
vacationPause	bool	Due days when paused for vacation.
expand	bool	Toggle expand menu in UI.
dirtiness	int	Percentage dirty of the chore.
duedays	int	Days until chore is due.
last_three_history_items	List[LastHistoryItem]	List of 3 last history items of the chore.
status	int	Status ID of the chore.

Source code in backend/backend/api.py

class ChoreOut(Schema):
    """
    Schema to represent a Chore.

    Attributes:
        id (int): ID of the chore.
        chore_name (str): Name of the chore.
        area_id (int): ID of an Area object assigned to the chore.
        area (AreaOut): Area object assigned to the chore.
        nextDue (date): Date chore is next due.
        lastCompleted (date): Date chore was last completed.
        intervalNumber (int): Repeat interval for the chore.
        unit (str): Repeat unit for the chore.
        active_months (List[int]): List of Month ids chode is active.
        assignee_id (int): ID of a user assigned to the chore. Default=None.
        effort (int): Effort required for the chore.
        vacationPause (bool): Due days when paused for vacation.
        expand (bool): Toggle expand menu in UI.
        dirtiness (int): Percentage dirty of the chore.
        duedays (int): Days until chore is due.
        last_three_history_items (List[LastHistoryItem]): List of 3 last history items of the chore.
        status (int): Status ID of the chore.
    """

    id: int
    chore_name: str
    area_id: int
    area: AreaOut
    nextDue: date
    lastCompleted: date
    intervalNumber: int
    unit: str
    active_months: List[int]
    assignee_id: Optional[int] = None
    assignee: Optional[CustomUserSchema] = None
    effort: int
    vacationPause: int
    expand: bool
    dirtiness: int
    duedays: int
    last_three_history_items: List[LastHistoryItem]
    status: int

ChoreOutFull

Schema to represent a Chore with full Assigned User and no History.

Attributes:

Name	Type	Description
id	int	ID of the chore.
chore_name	str	Name of the chore.
area_id	int	ID of an Area object assigned to the chore.
area	AreaOut	Area object assigned to the chore.
nextDue	date	Date chore is next due.
lastCompleted	date	Date chore was last completed.
intervalNumber	int	Repeat interval for the chore.
unit	str	Repeat unit for the chore.
active_months	List[int]	List of Month ids chode is active.
assignee_id	int	ID of a user assigned to the chore. Default=None.
assignee	CustomUserSchema	CustomUser object of the assigned user. Default=None.
effort	int	Effort required for the chore.
vacationPause	bool	Due days when paused for vacation.
expand	bool	Toggle expand menu in UI.
dirtiness	int	Percentage dirty of the chore.
duedays	int	Days until chore is due.
status	int	Status ID of the chore.

Source code in backend/backend/api.py

class ChoreOutFull(Schema):
    """
    Schema to represent a Chore with full Assigned User and no History.

    Attributes:
        id (int): ID of the chore.
        chore_name (str): Name of the chore.
        area_id (int): ID of an Area object assigned to the chore.
        area (AreaOut): Area object assigned to the chore.
        nextDue (date): Date chore is next due.
        lastCompleted (date): Date chore was last completed.
        intervalNumber (int): Repeat interval for the chore.
        unit (str): Repeat unit for the chore.
        active_months (List[int]): List of Month ids chode is active.
        assignee_id (int): ID of a user assigned to the chore. Default=None.
        assignee (CustomUserSchema): CustomUser object of the assigned user. Default=None.
        effort (int): Effort required for the chore.
        vacationPause (bool): Due days when paused for vacation.
        expand (bool): Toggle expand menu in UI.
        dirtiness (int): Percentage dirty of the chore.
        duedays (int): Days until chore is due.
        status (int): Status ID of the chore.
    """

    id: int
    chore_name: str
    area_id: int
    area: AreaOut
    nextDue: date
    lastCompleted: date
    intervalNumber: int
    unit: str
    active_months: List[MonthOut]
    assignee_id: Optional[int] = None
    assignee: Optional[CustomUserSchema] = None
    effort: int
    vacationPause: int
    expand: bool
    dirtiness: int
    duedays: int
    status: int

TogglActive

Schema to toggle a Chore status.

Attributes:

Name	Type	Description
status	int	ID of a status object.

Source code in backend/backend/api.py

class TogglActive(Schema):
    """
    Schema to toggle a Chore status.

    Attributes:
        status (int): ID of a status object.
    """

    status: int

CompleteChore

Schema to complete a Chore object.

Attributes:

Name	Type	Description
lastCompleted	date	Date chore was completed.
completed_by_id	int	ID of the user who completed chore.

Source code in backend/backend/api.py

class CompleteChore(Schema):
    """
    Schema to complete a Chore object.

    Attributes:
        lastCompleted (date): Date chore was completed.
        completed_by_id (int): ID of the user who completed chore.
    """

    lastCompleted: date
    completed_by_id: int

SnoozeChore

Schema to snooze a chore object.

Attributes:

Name	Type	Description
nextDue	date	Date to set nextDue to.

Source code in backend/backend/api.py

class SnoozeChore(Schema):
    """
    Schema to snooze a chore object.

    Attributes:
        nextDue (date): Date to set nextDue to.
    """

    nextDue: date

ClaimChore

Schema to claim a Chore.

Attributes:

Name	Type	Description
assignee_id	int	ID of a user to assign to chore. Optional.

Source code in backend/backend/api.py

class ClaimChore(Schema):
    """
    Schema to claim a Chore.

    Attributes:
        assignee_id (int): ID of a user to assign to chore. Optional.
    """

    assignee_id: Optional[int] = None

HistoryItem

Views

create_historyitem(request, payload)

The function create_historyitem creates a new HistoryItem object.

Endpoint

• Path: /api/v2/historyitems
• Method: POST

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
payload	HistoryItemIn	HistoryItem object to create.	required

Returns:

Type	Description
int	ID of the newly created HistoryItem object.

Source code in backend/backend/api.py

@api.post("/historyitems")
def create_historyitem(request, payload: HistoryItemIn):
    """
    The function `create_historyitem` creates a new HistoryItem object.

    Endpoint:
        - **Path**: `/api/v2/historyitems`
        - **Method**: `POST`

    Args:
        request (HttpRequest): The HTTP request object.
        payload (HistoryItemIn): HistoryItem object to create.

    Returns:
        (int): ID of the newly created HistoryItem object.
    """
    completed_by_id = payload.completed_by
    completed_by_object = get_object_or_404(CustomUser, id=completed_by_id)
    historyitem = HistoryItem.objects.create(
        completed_date=payload.completed_date,
        completed_by=completed_by_object,
        chore_id=payload.chore_id,
    )
    invalidate_chores("weeklytotals:*")
    notify("chores")
    notify("history")
    return {"id": historyitem.id}

get_historyitem(request, historyitem_id)

The function get_historyitem retrieves an HistoryItem object.

Endpoint

• Path: /api/v2/historyitems/{historyitem_id}
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
historyitem_id	int	ID of the HistoryItem object to retreive.	required

Returns:

Type	Description
HistoryItemOut	The HistoryItem object.

Source code in backend/backend/api.py

@api.get("/historyitems/{historyitem_id}", response=HistoryItemOut)
def get_historyitem(request, historyitem_id: int):
    """
    The function `get_historyitem` retrieves an HistoryItem object.

    Endpoint:
        - **Path**: `/api/v2/historyitems/{historyitem_id}`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        historyitem_id (int): ID of the HistoryItem object to retreive.

    Returns:
        (HistoryItemOut): The HistoryItem object.
    """
    historyitem = get_object_or_404(HistoryItem, id=historyitem_id)
    return historyitem

list_historyitems(request, page=1, page_size=60)

The function list_historyitems retrieves a list of HistoryItem objects.

Endpoint

• Path: /api/v2/historyitems
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
page	int	The page of the paginated History Items to return. Default=1. Optional.	1
page_size	int	The page size of paginated History Items. Default=60. Optional.	60

Returns:

Type	Description
PaginatedHistoryItems	Paginated List of HistoryItem objects.

Source code in backend/backend/api.py

@api.get("/historyitems", response=PaginatedHistoryItems)
def list_historyitems(
    request,
    page: int = 1,
    page_size: int = 60,
):
    """
    The function `list_historyitems` retrieves a list of HistoryItem objects.

    Endpoint:
        - **Path**: `/api/v2/historyitems`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        page (int): The page of the paginated History Items to return. Default=1. Optional.
        page_size (int): The page size of paginated History Items. Default=60. Optional.

    Returns:
        (PaginatedHistoryItems): Paginated List of HistoryItem objects.
    """
    qs = HistoryItem.objects.all().order_by("-completed_date", "-id")
    total_pages = 0
    item_list = []
    if len(qs) > 0:
        paginator = Paginator(qs, page_size)
        page_obj = paginator.page(page)
        item_list = list(page_obj.object_list)
        total_pages = paginator.num_pages
    total_records = len(qs)
    paginated_items = PaginatedHistoryItems(
        items=item_list,
        current_page=page,
        total_pages=total_pages,
        total_records=total_records,
    )
    return paginated_items

update_historyitem(request, historyitem_id, payload)

The function update_historyitem updates a given HistoryItem object.

Endpoint

• Path: /api/v2/historyitems/{historyitem_id}
• Method: PUT

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
historyitem_id	int	ID of the HistoryItem object to update.	required
payload	HistoryItemIn	HistoryItem object with updates to apply.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.put("/historyitems/{historyitem_id}")
def update_historyitem(request, historyitem_id: int, payload: HistoryItemIn):
    """
    The function `update_historyitem` updates a given HistoryItem object.

    Endpoint:
        - **Path**: `/api/v2/historyitems/{historyitem_id}`
        - **Method**: `PUT`

    Args:
        request (HttpRequest): The HTTP request object.
        historyitem_id (int): ID of the HistoryItem object to update.
        payload (HistoryItemIn): HistoryItem object with updates to apply.

    Returns:
        (str): Returns `success` if successful.
    """
    historyitem = get_object_or_404(HistoryItem, id=historyitem_id)
    historyitem.completed_date = payload.completed_date
    historyitem.completed_by = payload.completed_by
    historyitem.chore_id = payload.chore_id
    historyitem.save()
    invalidate_chores("weeklytotals:*")
    notify("chores")
    notify("history")
    return {"success": True}

delete_historyitem(request, historyitem_id)

The function delete_historyitem deletes a given HistoryItem object.

Endpoint

• Path: /api/v2/historyitems/{historyitem_id}
• Method: DELETE

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
historyitem_id	int	ID of the HistoryItem object to delete.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.delete("/historyitems/{historyitem_id}")
def delete_historyitem(request, historyitem_id: int):
    """
    The function `delete_historyitem` deletes a given HistoryItem object.

    Endpoint:
        - **Path**: `/api/v2/historyitems/{historyitem_id}`
        - **Method**: `DELETE`

    Args:
        request (HttpRequest): The HTTP request object.
        historyitem_id (int): ID of the HistoryItem object to delete.

    Returns:
        (str): Returns `success` if successful.
    """
    historyitem = get_object_or_404(HistoryItem, id=historyitem_id)
    historyitem.delete()
    invalidate_chores("weeklytotals:*")
    notify("chores")
    notify("history")
    return {"success": True}

Schemas

HistoryItemIn

Schema to represent a HistoryItem.

Attributes:

Name	Type	Description
completed_date	date	The date the chore was completed.
completed_by	str	A name of the user who completed the chore.
chore_id	int	ID of the chore completed.

Source code in backend/backend/api.py

class HistoryItemIn(Schema):
    """
    Schema to represent a HistoryItem.

    Attributes:
        completed_date (date): The date the chore was completed.
        completed_by (str): A name of the user who completed the chore.
        chore_id (int): ID of the chore completed.
    """

    completed_date: date
    completed_by: int
    chore_id: int

HistoryItemOut

Schema to represent a HistoryItem.

Attributes:

Name	Type	Description
id	int	ID of the HistoryItem.
completed_date	date	The date the chore was completed.
completed_by	CustomUserSchema	Object of the user who completed chore.
chore	ChoreOutFull	Object of the chore completed.

Source code in backend/backend/api.py

class HistoryItemOut(Schema):
    """
    Schema to represent a HistoryItem.

    Attributes:
        id (int): ID of the HistoryItem.
        completed_date (date): The date the chore was completed.
        completed_by (CustomUserSchema): Object of the user who completed chore.
        chore (ChoreOutFull): Object of the chore completed.
    """

    id: int
    completed_date: date
    completed_by: Optional[CustomUserSchema] = None
    chore: ChoreOutFull

LastHistoryItem

Schema to represent the last History Item for a chore.

Attributes:

Name	Type	Description
completed_date	date	The date the chore was completed.
completed_by	str	A name of the user who completed the chore.

Source code in backend/backend/api.py

class LastHistoryItem(Schema):
    """
    Schema to represent the last History Item for a chore.

    Attributes:
        completed_date (date): The date the chore was completed.
        completed_by (str): A name of the user who completed the chore.
    """

    completed_date: date
    completed_by: str

PaginatedHistoryItems

Schema to represent a paginated list of HistoryItems.

Attributes:

Name	Type	Description
items	List[HistoryItemOut]	List of HistoryItem objects.
current_page	int	Page number of current record set.
total_pages	int	Total number of pages.
total_records	int	Total numboer of HistoryItems.

Source code in backend/backend/api.py

class PaginatedHistoryItems(Schema):
    """
    Schema to represent a paginated list of HistoryItems.

    Attributes:
        items (List[HistoryItemOut]): List of HistoryItem objects.
        current_page (int): Page number of current record set.
        total_pages (int): Total number of pages.
        total_records (int): Total numboer of HistoryItems.
    """

    items: List[HistoryItemOut]
    current_page: int
    total_pages: int
    total_records: int

Option

Views

get_option(request, option_id)

The function get_option retrieves an Option object.

Endpoint

• Path: /api/v2/options/{option_id}
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
option_id	int	ID of the Option object to retreive.	required

Returns:

Type	Description
OptionOut	The Option object.

Source code in backend/backend/api.py

@api.get("/options/{option_id}", response=OptionOut)
def get_option(request, option_id: int):
    """
    The function `get_option` retrieves an Option object.

    Endpoint:
        - **Path**: `/api/v2/options/{option_id}`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        option_id (int): ID of the Option object to retreive.

    Returns:
        (OptionOut): The Option object.
    """
    option = get_object_or_404(Option, id=option_id)
    return option

list_options(request)

The function list_options retrieves a list of Option objects.

Endpoint

• Path: /api/v2/options
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required

Returns:

Type	Description
List[OptionOut]	List of Option objects.

Source code in backend/backend/api.py

@api.get("/options", response=List[OptionOut])
def list_options(request):
    """
    The function `list_options` retrieves a list of Option objects.

    Endpoint:
        - **Path**: `/api/v2/options`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.

    Returns:
        (List[OptionOut]): List of Option objects.
    """
    cached = cache.get("options")
    if cached is not None:
        return cached
    qs = list(Option.objects.all())
    cache.set("options", qs, CACHE_TTL)
    return qs

update_option(request, option_id, payload)

The function update_option updates a given Option object.

Endpoint

• Path: /api/v2/options/{option_id}
• Method: PUT

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
option_id	int	ID of the Option object to update.	required
payload	OptionIn	Option object with updates to apply.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.put("/options/{option_id}")
def update_option(request, option_id: int, payload: OptionIn):
    """
    The function `update_option` updates a given Option object.

    Endpoint:
        - **Path**: `/api/v2/options/{option_id}`
        - **Method**: `PUT`

    Args:
        request (HttpRequest): The HTTP request object.
        option_id (int): ID of the Option object to update.
        payload (OptionIn): Option object with updates to apply.

    Returns:
        (str): Returns `success` if successful.
    """
    option = get_object_or_404(Option, id=option_id)
    option.vacation_mode = payload.vacation_mode
    option.med_thresh = payload.med_thresh
    option.high_thresh = payload.high_thresh
    option.save()
    invalidate("options")
    notify("options")
    return {"success": True}

toggle_vacation(request)

The function toggle_vacation toggles vacation mode.

Endpoint

• Path: /api/v2/toggle_vacation
• Method: POST

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required

Returns:

Type	Description
str	Returns success if successful.

Source code in backend/backend/api.py

@api.post("/toggle_vacation")
def toggle_vacation(request):
    """
    The function `toggle_vacation` toggles vacation mode.

    Endpoint:
        - **Path**: `/api/v2/toggle_vacation`
        - **Method**: `POST`

    Args:
        request (HttpRequest): The HTTP request object.

    Returns:
        (str): Returns success if successful.
    """
    enabling = False
    option = get_object_or_404(Option, id=1)
    if option.vacation_mode:
        enabling = False
    else:
        enabling = True
    option.vacation_mode = not option.vacation_mode
    option.save()
    if enabling:
        chores = Chore.objects.filter(status=0)
        for chore in chores:
            chore.status = 3
            chore.vacationPause = chore.duedays
            chore.save()
    else:
        chores = Chore.objects.filter(status=3)
        for chore in chores:
            chore.status = 0
            chore.nextDue = date.today() + timedelta(days=chore.vacationPause)
            chore.save()
    invalidate("options")
    invalidate_chores()
    invalidate("areas")
    notify("options")
    notify("chores")
    # The state it landed in, not just that something happened. A toggle whose
    # response does not say which way it went leaves every caller guessing --
    # the frontend was about to invert its own stale copy to word a message.
    return {"success": True, "vacation_mode": option.vacation_mode}

Schemas

OptionIn

Schema to represent an Option object.

Attributes:

Name	Type	Description
vacation_mode	bool	Toggle for vacation mode.
med_thresh	int	Medium dirtiness threshold.
high_thresh	int	High dirtiness threshold.

Source code in backend/backend/api.py

class OptionIn(Schema):
    """
    Schema to represent an Option object.

    Attributes:
        vacation_mode (bool): Toggle for vacation mode.
        med_thresh (int): Medium dirtiness threshold.
        high_thresh (int): High dirtiness threshold.
    """

    vacation_mode: bool
    med_thresh: int
    high_thresh: int

OptionOut

Schema to represent an Option object.

Attributes:

Name	Type	Description
id	int	ID of the Option object.
vacation_mode	bool	Toggle for vacation mode.
med_thresh	int	Medium dirtiness threshold.
high_thresh	int	High dirtiness threshold.

Source code in backend/backend/api.py

class OptionOut(Schema):
    """
    Schema to represent an Option object.

    Attributes:
        id (int): ID of the Option object.
        vacation_mode (bool): Toggle for vacation mode.
        med_thresh (int): Medium dirtiness threshold.
        high_thresh (int): High dirtiness threshold.
    """

    id: int
    vacation_mode: bool
    med_thresh: int
    high_thresh: int

Version

Views

list_version(request)

The function list_version retrieves the app version number from the backend.

Endpoint

• Path: /api/v2/version/list
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required

Returns:

Name	Type	Description
VersionOut	VersionOut	a version object

Source code in backend/backend/api.py

@api.get("/version/list", response=VersionOut, auth=None)
def list_version(request) -> VersionOut:
    """
    The function `list_version` retrieves the app version number
    from the backend.

    Endpoint:
        - **Path**: `/api/v2/version/list`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.

    Returns:
        VersionOut: a version object
    """

    try:
        qs = get_object_or_404(Version, id=1)
        return qs
    except Exception as e:
        raise HttpError(500, f"Record retrieval error: {str(e)}")

Schemas

VersionOut

Schema to represent a Version.

Attributes:

Name	Type	Description
id	int	ID integer. Unique.
version_number	str	The version of the app.

Source code in backend/backend/api.py

class VersionOut(Schema):
    """
    Schema to represent a Version.

    Attributes:
        id (int): ID integer. Unique.
        version_number (str): The version of the app.
    """

    id: int
    version_number: str

Graphs

Views

get_weeklytotals(request, week=0)

The function get_weeklytotals retrieves the weekly totals.

Endpoint

• Path: /api/v2/weeklytotals
• Method: GET

Parameters:

Name	Type	Description	Default
request	HttpRequest	The HTTP request object.	required
week	int	Flag to indicate if the totals for last week should be retrieved. Default=0.	0

Returns:

Type	Description
GraphData	The graph data with labels and datasets.

Source code in backend/backend/api.py

@api.get("/weeklytotals", response=GraphData)
def get_weeklytotals(request, week: int = 0):
    """
    The function `get_weeklytotals` retrieves the weekly totals.

    Endpoint:
        - **Path**: `/api/v2/weeklytotals`
        - **Method**: `GET`

    Args:
        request (HttpRequest): The HTTP request object.
        week (int): Flag to indicate if the totals for last week should be retrieved. Default=0.

    Returns:
        (GraphData): The graph data with labels and datasets.
    """
    cache_key = f"weeklytotals:{week}"
    cached = cache.get(cache_key)
    if cached is not None:
        return cached

    labels = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
    # localdate(), not now().date(): see list_chores. With TIME_ZONE set to
    # America/New_York and USE_TZ on, now().date() is the UTC date, so from
    # ~8pm Eastern it is already tomorrow -- and on a Sunday evening that
    # rolled this into next week's window.
    today = timezone.localdate()
    days = week * 7
    start_of_week = (
        today - timedelta(days=today.weekday()) - timedelta(days=days)
    )
    end_of_week = start_of_week + timedelta(days=6)

    datasets = []
    users = CustomUser.objects.all()
    for user in users:
        user_name = None
        if user.first_name and user.first_name != "":
            user_name = user.first_name
        else:
            if len(user.email) > 15:
                if "@" in user.email:
                    parts = user.email.split("@")
                    if len(parts[0]) <= 9:
                        user_name = parts[0] + "@"
                    else:
                        user_name = parts[0][:8] + "*@"
                    if len(parts[1]) <= 5:
                        user_name += parts[1]
                    else:
                        user_name += parts[1][:4] + "*"
                else:
                    user_name = user.email[:14] + "*"
            else:
                user_name = user.email
        # Get records for this week or last week
        records_this_week = HistoryItem.objects.filter(
            completed_by=user,
            completed_date__gte=start_of_week,
            completed_date__lt=start_of_week + timedelta(days=7),
        )

        # Aggregate counts by date
        daily_counts = records_this_week.values("completed_date").annotate(
            count=Count("id")
        )

        # Initialize weekly counts with 0s
        weekly_counts = [0] * 7

        # Map counts to the correct day of the week
        for record in daily_counts:
            day_index = (record["completed_date"] - start_of_week).days
            weekly_counts[day_index] = record["count"]

        dataset_obj = DatasetObject(
            backgroundColor=user.user_color,
            data=weekly_counts,
            label=user_name,
        )
        datasets.append(dataset_obj)
    title = (
        start_of_week.strftime("%m/%d") + " to " + end_of_week.strftime("%m/%d")
    )
    graph = GraphData(labels=labels, datasets=datasets, title=title)
    cache.set(cache_key, graph, CACHE_TTL)
    return graph

Schemas

DatasetObject

Schema to represent a graph DataSet object.

Attributes:

Name	Type	Description
backgroundColor	str	Hex value of the graph color. Optional.
data	List(int	List of object IDs for the graph.
label	str	Label for the gaph dataset.

Source code in backend/backend/api.py

class DatasetObject(Schema):
    """
    Schema to represent a graph DataSet object.

    Attributes:
        backgroundColor (str): Hex value of the graph color. Optional.
        data (List(int)): List of object IDs for the graph.
        label (str): Label for the gaph dataset.
    """

    backgroundColor: Optional[str] = None
    data: Optional[List[int]] = None
    label: Optional[str] = None

GraphData

Schema to represent a GraphData object.

Attributes:

Name	Type	Description
labels	List[str]	List of labels for the graph data.
datasets	List[DatasetObject]	List of DataSetObject objects.
title	str	Title of the graph.

Source code in backend/backend/api.py

class GraphData(Schema):
    """
    Schema to represent a GraphData object.

    Attributes:
        labels (List[str]): List of labels for the graph data.
        datasets (List[DatasetObject]): List of DataSetObject objects.
        title (str): Title of the graph.
    """

    labels: List[str]
    datasets: List[DatasetObject]
    title: str