API Reference

Gear components sub-module.

Provides CRUD operations, schemas, and models for gear component tracking (e.g., chains, tires, pedals, strings).

Exports

• CRUD: get_gear_components_user, get_gear_components_user_by_gear_id, create_gear_component, edit_gear_component, delete_gear_component
• Schemas: GearComponentBase, GearComponentCreate, GearComponentRead, GearComponentUpdate, GearComponentTypesRead
• Models: GearComponents (ORM model)

GearComponentBase

Bases: BaseModel

Base model for gear component data.

Attributes:

Name	Type	Description
gear_id	StrictInt	Foreign key to gear table.
type	StrictStr	Type of gear component.
brand	StrictStr	Gear component brand.
model	StrictStr	Gear component model name.
purchase_date	datetime | None	Purchase date.
retired_date	datetime | None	Retired date.
active	StrictBool | None	Whether component is active.
expected_kms	StrictInt | None	Expected kilometers.
purchase_value	StrictFloat | None	Purchase value.

Source code in backend/app/gears/gear_components/schema.py

class GearComponentBase(BaseModel):
    """
    Base model for gear component data.

    Attributes:
        gear_id: Foreign key to gear table.
        type: Type of gear component.
        brand: Gear component brand.
        model: Gear component model name.
        purchase_date: Purchase date.
        retired_date: Retired date.
        active: Whether component is active.
        expected_kms: Expected kilometers.
        purchase_value: Purchase value.
    """

    gear_id: StrictInt = Field(
        ...,
        description="Foreign key to gear",
    )
    type: StrictStr = Field(
        ...,
        max_length=250,
        description="Type of gear component",
    )
    brand: StrictStr = Field(
        ...,
        max_length=250,
        description="Gear component brand",
    )
    model: StrictStr = Field(
        ...,
        max_length=250,
        description="Gear component model",
    )
    purchase_date: datetime_type | None = Field(
        default=None,
        description="Purchase date",
    )
    retired_date: datetime_type | None = Field(
        default=None,
        description="Retired date",
    )
    active: StrictBool | None = Field(
        default=None,
        description=("Whether the component is active"),
    )
    expected_kms: StrictInt | None = Field(
        default=None,
        ge=0,
        description=("Expected kilometers"),
    )
    purchase_value: StrictFloat | None = Field(
        default=None,
        ge=0,
        description="Purchase value",
    )

    model_config = ConfigDict(
        from_attributes=True,
        extra="forbid",
        validate_assignment=True,
    )

GearComponentCreate

Bases: GearComponentBase

Schema for creating a gear component.

Source code in backend/app/gears/gear_components/schema.py

class GearComponentCreate(GearComponentBase):
    """Schema for creating a gear component."""

GearComponentRead

Bases: GearComponentBase

Schema for reading a gear component.

Attributes:

Name	Type	Description
id	StrictInt	Unique identifier.
user_id	StrictInt	Foreign key to user.
current_distance	StrictFloat	Accumulated distance.
current_time	StrictFloat	Accumulated time.

Source code in backend/app/gears/gear_components/schema.py

class GearComponentRead(GearComponentBase):
    """
    Schema for reading a gear component.

    Attributes:
        id: Unique identifier.
        user_id: Foreign key to user.
        current_distance: Accumulated distance.
        current_time: Accumulated time.
    """

    id: StrictInt = Field(
        ...,
        description="Unique identifier",
    )
    user_id: StrictInt = Field(
        ...,
        description="Foreign key to user",
    )
    current_distance: StrictFloat = Field(
        default=0,
        ge=0,
        description=("Accumulated activity distance in meters"),
    )
    current_time: StrictFloat = Field(
        default=0,
        ge=0,
        description=("Accumulated activity time in seconds"),
    )

GearComponentTypesRead

Bases: BaseModel

Schema for reading component type lists.

Attributes:

Name	Type	Description
bike	list[str]	Valid bike component types.
shoes	list[str]	Valid shoes component types.
racquet	list[str]	Valid racquet component types.
windsurf	list[str]	Valid windsurf component types.

Source code in backend/app/gears/gear_components/schema.py

class GearComponentTypesRead(BaseModel):
    """
    Schema for reading component type lists.

    Attributes:
        bike: Valid bike component types.
        shoes: Valid shoes component types.
        racquet: Valid racquet component types.
        windsurf: Valid windsurf component types.
    """

    bike: list[str] = Field(
        ...,
        description=("Valid bike component types"),
    )
    shoes: list[str] = Field(
        ...,
        description=("Valid shoes component types"),
    )
    racquet: list[str] = Field(
        ...,
        description=("Valid racquet component types"),
    )
    windsurf: list[str] = Field(
        ...,
        description=("Valid windsurf component types"),
    )

    model_config = ConfigDict(
        extra="forbid",
    )

GearComponentUpdate

Bases: GearComponentBase

Schema for updating a gear component.

Attributes:

Name	Type	Description
id	StrictInt	Unique identifier.

Source code in backend/app/gears/gear_components/schema.py

class GearComponentUpdate(GearComponentBase):
    """
    Schema for updating a gear component.

    Attributes:
        id: Unique identifier.
    """

    id: StrictInt = Field(
        ...,
        description="Unique identifier",
    )

create_gear_component

create_gear_component(gear_component, user_id, db)

Create a new gear component.

Parameters:

Name	Type	Description	Default
gear_component	GearComponentCreate	Create schema data.	required
user_id	int	Authenticated user ID (token).	required
db	Session	Database session.	required

Returns:

Type	Description
GearComponentRead	Created GearComponentRead schema.

Raises:

Type	Description
HTTPException	On database error (500).

Source code in backend/app/gears/gear_components/crud.py

@core_decorators.handle_db_errors
def create_gear_component(
    gear_component: (gear_components_schema.GearComponentCreate),
    user_id: int,
    db: Session,
) -> gear_components_schema.GearComponentRead:
    """
    Create a new gear component.

    Args:
        gear_component: Create schema data.
        user_id: Authenticated user ID (token).
        db: Database session.

    Returns:
        Created GearComponentRead schema.

    Raises:
        HTTPException: On database error (500).
    """
    new_gear_component = gear_components_models.GearComponents(
        user_id=user_id,
        gear_id=gear_component.gear_id,
        type=gear_component.type,
        brand=gear_component.brand,
        model=gear_component.model,
        purchase_date=(gear_component.purchase_date),
        active=True,
        expected_kms=(gear_component.expected_kms),
        purchase_value=(gear_component.purchase_value),
    )

    db.add(new_gear_component)
    db.commit()
    db.refresh(new_gear_component)

    return _transform_gear_components(new_gear_component)

delete_gear_component

delete_gear_component(user_id, gear_component_id, db)

Delete a gear component by user and ID.

Parameters:

Name	Type	Description	Default
user_id	int	Owner user ID.	required
gear_component_id	int	Component ID to delete.	required
db	Session	Database session.	required

Returns:

Type	Description
None	None.

Raises:

Type	Description
HTTPException	If not found (404) or database error (500).

Source code in backend/app/gears/gear_components/crud.py

@core_decorators.handle_db_errors
def delete_gear_component(
    user_id: int,
    gear_component_id: int,
    db: Session,
) -> None:
    """
    Delete a gear component by user and ID.

    Args:
        user_id: Owner user ID.
        gear_component_id: Component ID to delete.
        db: Database session.

    Returns:
        None.

    Raises:
        HTTPException: If not found (404) or
            database error (500).
    """
    db_gear_component = _get_gear_component_model_by_id_and_user_id_or_404(gear_component_id, user_id, db)

    db.delete(db_gear_component)
    db.commit()

edit_gear_component

edit_gear_component(gear_component, user_id, db)

Edit an existing gear component by ID.

Applies a partial update (only fields present in the payload are changed) and enforces the retired/active invariant: a retired component (retired_date set) is always inactive, while an un-retired component keeps the client-supplied active value.

Parameters:

Name	Type	Description	Default
gear_component	GearComponentUpdate	Update schema data.	required
db	Session	Database session.	required

Returns:

Type	Description
GearComponentRead	Updated GearComponentRead schema.

Raises:

Type	Description
HTTPException	If not found (404) or database error (500).

Source code in backend/app/gears/gear_components/crud.py

@core_decorators.handle_db_errors
def edit_gear_component(
    gear_component: (gear_components_schema.GearComponentUpdate),
    user_id: int,
    db: Session,
) -> gear_components_schema.GearComponentRead:
    """
    Edit an existing gear component by ID.

    Applies a partial update (only fields present in the payload are
    changed) and enforces the retired/active invariant: a retired
    component (``retired_date`` set) is always inactive, while an
    un-retired component keeps the client-supplied ``active`` value.

    Args:
        gear_component: Update schema data.
        db: Database session.

    Returns:
        Updated GearComponentRead schema.

    Raises:
        HTTPException: If not found (404) or
            database error (500).
    """
    db_gear_component = _get_gear_component_model_by_id_and_user_id_or_404(gear_component.id, user_id, db)

    gear_component_data = gear_component.model_dump(
        exclude_unset=True,
    )
    for key, value in gear_component_data.items():
        if key not in _IMMUTABLE_FIELDS:
            setattr(db_gear_component, key, value)

    # Enforce the retired/active invariant: a retired component is always
    # inactive. When the component is not retired, the client-supplied
    # ``active`` value (already applied above) is honoured as-is. The
    # server never infers reactivation from field presence, so behaviour
    # is deterministic across every client; reactivating a retired
    # component is an explicit client action (clear ``retired_date`` and
    # set ``active`` to True in the same request).
    if db_gear_component.retired_date is not None:
        db_gear_component.active = False

    db.commit()
    db.refresh(db_gear_component)

    return _transform_gear_components(db_gear_component)

get_gear_components_user

get_gear_components_user(user_id, db)

Retrieve all gear components for a user.

Parameters:

Name	Type	Description	Default
user_id	int	Owner user ID.	required
db	Session	Database session.	required

Returns:

Type	Description
list[GearComponentRead]	List of GearComponentRead schema.

Raises:

Type	Description
HTTPException	On database error (500).

Source code in backend/app/gears/gear_components/crud.py

@core_decorators.handle_db_errors
def get_gear_components_user(
    user_id: int,
    db: Session,
) -> list[gear_components_schema.GearComponentRead]:
    """
    Retrieve all gear components for a user.

    Args:
        user_id: Owner user ID.
        db: Database session.

    Returns:
        List of GearComponentRead schema.

    Raises:
        HTTPException: On database error (500).
    """
    stmt = select(
        gear_components_models.GearComponents,
    ).where(
        gear_components_models.GearComponents.user_id == user_id,
    )
    db_gear_components = db.execute(stmt).scalars().all()
    return _transform_gear_components(list(db_gear_components))

get_gear_components_user_by_gear_id

get_gear_components_user_by_gear_id(user_id, gear_id, db, active=None)

Retrieve gear components by user and gear.

Parameters:

Name	Type	Description	Default
user_id	int	Owner user ID.	required
gear_id	int	Gear ID to filter by.	required
db	Session	Database session.	required
active	bool | None	Optional active-status filter.	None

Returns:

Type	Description
list[GearComponentRead]	List of GearComponentRead schema.

Raises:

Type	Description
HTTPException	On database error (500).

Source code in backend/app/gears/gear_components/crud.py

@core_decorators.handle_db_errors
def get_gear_components_user_by_gear_id(
    user_id: int,
    gear_id: int,
    db: Session,
    active: bool | None = None,
) -> list[gear_components_schema.GearComponentRead]:
    """
    Retrieve gear components by user and gear.

    Args:
        user_id: Owner user ID.
        gear_id: Gear ID to filter by.
        db: Database session.
        active: Optional active-status filter.

    Returns:
        List of GearComponentRead schema.

    Raises:
        HTTPException: On database error (500).
    """
    stmt = select(
        gear_components_models.GearComponents,
    ).where(
        gear_components_models.GearComponents.user_id == user_id,
        gear_components_models.GearComponents.gear_id == gear_id,
    )
    if active is not None:
        stmt = stmt.where(
            gear_components_models.GearComponents.active == active,
        )
    db_gear_components = db.execute(stmt).scalars().all()
    return _transform_gear_components(list(db_gear_components))