API Reference

Health steps module for managing user step count data.

This module provides CRUD operations and data models for user step tracking including daily step counts and data sources.

Exports

• CRUD: get_health_steps_number_by_user_id, get_health_steps_by_id_and_user_id, get_health_steps_by_user_id, get_health_steps_by_date_and_user_id, create_health_steps, edit_health_steps, delete_health_steps
• Schemas: HealthStepsBase, HealthStepsCreate, HealthStepsUpdate, HealthStepsRead, HealthStepsListResponse
• Enums: Source
• Models: HealthSteps (ORM model)

HealthStepsBase

Bases: BaseModel

Base model for health steps data.

Represents the core attributes of a user's step count record, including the user reference, date of the record, number of steps taken, and the source of the data.

Attributes:

Name	Type	Description
date	date | None	Calendar date of the steps record. Optional field.
steps	StrictInt | None	Number of steps taken. Must be a non-negative integer. Optional field.
source	Source | None	Source of the steps data (e.g., device, API, manual entry). Optional field.

Configuration

• from_attributes: Allows model to be populated from ORM objects.
• extra: Forbids any extra fields not defined in the model.
• validate_assignment: Validates field values when assigned after model creation.
• use_enum_values: Uses enum values instead of enum objects in serialization.

Source code in backend/app/health/health_steps/schema.py

class HealthStepsBase(BaseModel):
    """
    Base model for health steps data.

    Represents the core attributes of a user's step count record, including the user reference,
    date of the record, number of steps taken, and the source of the data.

    Attributes:
        date (datetime_date | None): Calendar date of the steps record. Optional field.
        steps (StrictInt | None): Number of steps taken. Must be a non-negative integer. Optional field.
        source (Source | None): Source of the steps data (e.g., device, API, manual entry). Optional field.

    Configuration:
        - from_attributes: Allows model to be populated from ORM objects.
        - extra: Forbids any extra fields not defined in the model.
        - validate_assignment: Validates field values when assigned after model creation.
        - use_enum_values: Uses enum values instead of enum objects in serialization.
    """

    date: datetime_date | None = Field(
        default=None, description="Calendar date of the steps"
    )
    steps: StrictInt | None = Field(
        default=None, ge=0, description="Number of steps taken"
    )
    source: Source | None = Field(default=None, description="Source of the steps data")

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

HealthStepsCreate

Bases: HealthStepsBase

Validator for HealthStepsCreate model that automatically sets the date field.

This validator runs after model initialization to ensure that if no date is provided, it defaults to today's date.

Source code in backend/app/health/health_steps/schema.py

class HealthStepsCreate(HealthStepsBase):
    """
    Validator for HealthStepsCreate model that automatically sets the date field.

    This validator runs after model initialization to ensure that if no date
    is provided, it defaults to today's date.
    """

    @model_validator(mode="after")
    def set_default_date(self) -> "HealthStepsCreate":
        """
        Set date to today if not provided.

        Returns:
            The validated model instance with date set.
        """
        if self.date is None:
            self.date = datetime_date.today()
        return self

set_default_date

set_default_date()

Set date to today if not provided.

Returns:

Type	Description
HealthStepsCreate	The validated model instance with date set.

Source code in backend/app/health/health_steps/schema.py

@model_validator(mode="after")
def set_default_date(self) -> "HealthStepsCreate":
    """
    Set date to today if not provided.

    Returns:
        The validated model instance with date set.
    """
    if self.date is None:
        self.date = datetime_date.today()
    return self

HealthStepsListResponse

Bases: HealthListResponse

Response model for listing health steps records.

Extends the base HealthListResponse to provide a typed response containing a list of steps records. This model is used when returning multiple steps entries from API endpoints.

Attributes:

Name	Type	Description
records	list[HealthStepsRead]	A list of HealthStepsRead objects representing individual steps records.

Source code in backend/app/health/health_steps/schema.py

class HealthStepsListResponse(health_schema.HealthListResponse):
    """
    Response model for listing health steps records.

    Extends the base HealthListResponse to provide a typed response containing
    a list of steps records. This model is used when returning multiple steps
    entries from API endpoints.

    Attributes:
        records: A list of HealthStepsRead objects representing individual
            steps records.
    """

    records: list[HealthStepsRead] = Field(
        ..., description="List of health steps records"
    )

HealthStepsModel

Bases: Base

SQLAlchemy model representing daily step count data for users.

This model stores health and fitness tracking data related to the number of steps taken by a user on a specific date. It includes information about the data source and maintains a relationship with the Users model.

Attributes:

Name	Type	Description
id	Mapped[int]	Primary key, auto-incremented unique identifier.
user_id	Mapped[int]	Foreign key referencing users.id.
date	Mapped[date]	Calendar date for which the step count is recorded.
steps	Mapped[int]	Total number of steps taken on the date.
source	Mapped[str | None]	Source of the step data (e.g., fitness device, app).
user	Mapped[str | None]	Relationship to the Users model.

Table

health_steps

Relationships

• Many-to-One with Users model through user_id

Source code in backend/app/health/health_steps/models.py

class HealthSteps(Base):
    """
    SQLAlchemy model representing daily step count data for users.

    This model stores health and fitness tracking data related to the number of steps
    taken by a user on a specific date. It includes information about the data source
    and maintains a relationship with the Users model.

    Attributes:
        id: Primary key, auto-incremented unique identifier.
        user_id: Foreign key referencing users.id.
        date: Calendar date for which the step count is recorded.
        steps: Total number of steps taken on the date.
        source: Source of the step data (e.g., fitness device, app).
        user: Relationship to the Users model.

    Table:
        health_steps

    Relationships:
        - Many-to-One with Users model through user_id
    """

    __tablename__ = "health_steps"

    id: Mapped[int] = mapped_column(
        primary_key=True,
        autoincrement=True,
    )
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
        comment="User ID that the health_steps belongs",
    )
    date: Mapped[date_type] = mapped_column(
        nullable=False,
        index=True,
        comment="Health steps date (date)",
    )
    steps: Mapped[int] = mapped_column(
        nullable=False,
        comment="Number of steps taken",
    )
    source: Mapped[str | None] = mapped_column(
        String(250),
        nullable=True,
        comment="Source of the health steps data",
    )

    # Define a relationship to the Users model
    users: Mapped["Users"] = relationship(back_populates="health_steps")

HealthStepsRead

Bases: HealthStepsBase

Schema for reading health steps records.

Extends the base health steps schema with an identifier field for retrieving or referencing existing steps records in the database.

Attributes:

Name	Type	Description
id	StrictInt	Unique identifier for the steps record to update. Required field.
user_id	StrictInt	Foreign key reference to the user. Required field.

Source code in backend/app/health/health_steps/schema.py

class HealthStepsRead(HealthStepsBase):
    """
    Schema for reading health steps records.

    Extends the base health steps schema with an identifier field for retrieving
    or referencing existing steps records in the database.

    Attributes:
        id (StrictInt): Unique identifier for the steps record to update. Required field.
        user_id (StrictInt): Foreign key reference to the user. Required field.
    """

    id: StrictInt = Field(
        ..., description="Unique identifier for the steps record to update"
    )
    user_id: StrictInt = Field(..., description="Foreign key reference to the user")

HealthStepsUpdate

Bases: HealthStepsRead

Schema for updating health steps records.

Inherits from HealthStepsRead to maintain consistency with read operations while allowing modifications to health steps data. This schema is used for PUT/PATCH requests to update existing health steps entries.

Source code in backend/app/health/health_steps/schema.py

class HealthStepsUpdate(HealthStepsRead):
    """
    Schema for updating health steps records.

    Inherits from HealthStepsRead to maintain consistency with read operations
    while allowing modifications to health steps data. This schema is used for
    PUT/PATCH requests to update existing health steps entries.
    """

Source

Bases: Enum

An enumeration representing supported sources for the application.

Members

GARMIN: Garmin health data source

Source code in backend/app/health/health_steps/schema.py

class Source(Enum):
    """
    An enumeration representing supported sources for the application.

    Members:
        GARMIN: Garmin health data source
    """

    GARMIN = "garmin"

create_health_steps

create_health_steps(user_id, health_steps, db)

Create a new health steps record for a user.

Parameters:

Name	Type	Description	Default
user_id	int	User ID for the record owner.	required
health_steps	HealthStepsCreate	Health steps data to create.	required
db	Session	Database session.	required

Returns:

Type	Description
HealthSteps	Created health steps record.

Raises:

Type	Description
HTTPException	If duplicate entry or database error.

Source code in backend/app/health/health_steps/crud.py

@core_decorators.handle_db_errors
def create_health_steps(
    user_id: int,
    health_steps: health_steps_schema.HealthStepsCreate,
    db: Session,
) -> health_steps_models.HealthSteps:
    """
    Create a new health steps record for a user.

    Args:
        user_id: User ID for the record owner.
        health_steps: Health steps data to create.
        db: Database session.

    Returns:
        Created health steps record.

    Raises:
        HTTPException: If duplicate entry or database error.
    """
    try:
        # Create a new health_steps
        db_health_steps = health_steps_models.HealthSteps(
            **health_steps.model_dump(exclude_none=False),
            user_id=user_id,
        )

        # Add the health_steps to the database
        db.add(db_health_steps)
        db.commit()
        db.refresh(db_health_steps)

        # Return the health_steps
        return db_health_steps
    except IntegrityError as integrity_error:
        # Rollback the transaction
        db.rollback()

        # Raise an HTTPException with a 409 Conflict status code
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=(
                f"Duplicate entry error. Check if there is already "
                f"a entry created for {health_steps.date}"
            ),
        ) from integrity_error

delete_health_steps

delete_health_steps(user_id, health_steps_id, db)

Delete a health steps record for a user.

Parameters:

Name	Type	Description	Default
user_id	int	User ID who owns the record.	required
health_steps_id	int	Health steps record ID to delete.	required
db	Session	Database session.	required

Returns:

Type	Description
None	None

Raises:

Type	Description
HTTPException	If record not found or database error.

Source code in backend/app/health/health_steps/crud.py

@core_decorators.handle_db_errors
def delete_health_steps(user_id: int, health_steps_id: int, db: Session) -> None:
    """
    Delete a health steps record for a user.

    Args:
        user_id: User ID who owns the record.
        health_steps_id: Health steps record ID to delete.
        db: Database session.

    Returns:
        None

    Raises:
        HTTPException: If record not found or database error.
    """
    # Get the record first to ensure it exists
    db_health_steps = get_health_steps_by_id_and_user_id(health_steps_id, user_id, db)

    # Check if the health_steps was found
    if db_health_steps is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Health steps not found",
        ) from None

    # Delete the health_steps
    db.delete(db_health_steps)
    # Commit the transaction
    db.commit()

edit_health_steps

edit_health_steps(user_id, health_steps, db)

Edit health steps record for a user.

Parameters:

Name	Type	Description	Default
user_id	int	User ID who owns the record.	required
health_steps	HealthStepsUpdate	Health steps data to update.	required
db	Session	Database session.	required

Returns:

Type	Description
HealthSteps	Updated HealthSteps model.

Raises:

Type	Description
HTTPException	403 if trying to edit other user record, 404 if not found, 500 if database error.

Source code in backend/app/health/health_steps/crud.py

@core_decorators.handle_db_errors
def edit_health_steps(
    user_id: int,
    health_steps: health_steps_schema.HealthStepsUpdate,
    db: Session,
) -> health_steps_models.HealthSteps:
    """
    Edit health steps record for a user.

    Args:
        user_id: User ID who owns the record.
        health_steps: Health steps data to update.
        db: Database session.

    Returns:
        Updated HealthSteps model.

    Raises:
        HTTPException: 403 if trying to edit other user record, 404 if not
            found, 500 if database error.
    """
    # Ensure the health_steps belongs to the user
    if health_steps.user_id != user_id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Cannot edit health steps for another user.",
        )

    # Get the health_steps from the database
    db_health_steps = get_health_steps_by_id_and_user_id(health_steps.id, user_id, db)

    if db_health_steps is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Health steps not found",
        ) from None

    # Dictionary of the fields to update if they are not None
    health_steps_data = health_steps.model_dump(exclude_unset=True)
    # Iterate over the fields and update the db_health_steps dynamically
    for key, value in health_steps_data.items():
        setattr(db_health_steps, key, value)

    # Commit the transaction
    db.commit()
    # Refresh the object to ensure it reflects database state
    db.refresh(db_health_steps)

    return db_health_steps

get_health_steps_by_date_and_user_id

get_health_steps_by_date_and_user_id(user_id, date, db)

Retrieve health steps record for a user on a specific date.

Parameters:

Name	Type	Description	Default
user_id	int	User ID.	required
date	str	Date string for the steps record.	required
db	Session	Database session.	required

Returns:

Type	Description
HealthSteps | None	HealthSteps model if found, None otherwise.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/health/health_steps/crud.py

@core_decorators.handle_db_errors
def get_health_steps_by_date_and_user_id(
    user_id: int, date: str, db: Session
) -> health_steps_models.HealthSteps | None:
    """
    Retrieve health steps record for a user on a specific date.

    Args:
        user_id: User ID.
        date: Date string for the steps record.
        db: Database session.

    Returns:
        HealthSteps model if found, None otherwise.

    Raises:
        HTTPException: If database error occurs.
    """
    # Get the health_steps from the database
    stmt = select(health_steps_models.HealthSteps).where(
        health_steps_models.HealthSteps.date == func.date(date),
        health_steps_models.HealthSteps.user_id == user_id,
    )
    return db.execute(stmt).scalar_one_or_none()

get_health_steps_by_id_and_user_id

get_health_steps_by_id_and_user_id(health_steps_id, user_id, db)

Retrieve health steps record by ID and user ID. Args: health_steps_id: Health steps record ID to fetch. user_id: User ID to fetch record for. db: Database session.

Returns:

Type	Description
HealthSteps | None	HealthSteps model if found, None otherwise.

Raises: HTTPException: If database error occurs.

Source code in backend/app/health/health_steps/crud.py

@core_decorators.handle_db_errors
def get_health_steps_by_id_and_user_id(
    health_steps_id: int, user_id: int, db: Session
) -> health_steps_models.HealthSteps | None:
    """
    Retrieve health steps record by ID and user ID.
    Args:
        health_steps_id: Health steps record ID to fetch.
        user_id: User ID to fetch record for.
        db: Database session.

    Returns:
        HealthSteps model if found, None otherwise.
    Raises:
        HTTPException: If database error occurs.
    """
    # Get the health_steps from the database
    stmt = select(health_steps_models.HealthSteps).where(
        health_steps_models.HealthSteps.id == health_steps_id,
        health_steps_models.HealthSteps.user_id == user_id,
    )
    return db.execute(stmt).scalar_one_or_none()

get_health_steps_by_user_id

get_health_steps_by_user_id(user_id, db, page_number=None, num_records=None, interval=None)

Retrieve health steps records for a specific user with optional pagination and filtering.

Parameters:

Name	Type	Description	Default
user_id	int	The ID of the user whose health steps records are to be retrieved.	required
db	Session	The database session used to execute the query.	required
page_number	int | None	The page number for pagination (1-indexed). If provided, num_records must also be provided. Defaults to None.	None
num_records	int | None	The number of records per page. If provided, page_number must also be provided. Defaults to None.	None
interval	Interval | None	The time interval to filter records. If provided, only records from the start of the interval to present are returned. Defaults to None.	None

Returns:

Type	Description
list[HealthSteps]	list[health_steps_models.HealthSteps]: A list of health steps records sorted by date in descending order, optionally paginated.

Source code in backend/app/health/health_steps/crud.py

@core_decorators.handle_db_errors
def get_health_steps_by_user_id(
    user_id: int,
    db: Session,
    page_number: int | None = None,
    num_records: int | None = None,
    interval: health_constants.Interval | None = None,
) -> list[health_steps_models.HealthSteps]:
    """
    Retrieve health steps records for a specific user with optional pagination
        and filtering.

    Args:
        user_id (int): The ID of the user whose health steps records are to be
            retrieved.
        db (Session): The database session used to execute the query.
        page_number (int | None, optional): The page number for pagination
            (1-indexed).
            If provided, num_records must also be provided. Defaults to None.
        num_records (int | None, optional): The number of records per page.
            If provided, page_number must also be provided. Defaults to None.
        interval (health_constants.Interval | None, optional): The time
            interval to filter records.
            If provided, only records from the start of the interval to present
            are returned. Defaults to None.

    Returns:
        list[health_steps_models.HealthSteps]: A list of health steps
            records sorted by date in descending order, optionally paginated.
    """
    # Get the health_steps from the database
    stmt = select(health_steps_models.HealthSteps).where(
        health_steps_models.HealthSteps.user_id == user_id
    )

    if interval is not None:
        stmt = stmt.where(
            health_steps_models.HealthSteps.date
            >= health_utils.get_start_date_for_interval(interval.value)
        )

    stmt = stmt.order_by(desc(health_steps_models.HealthSteps.date))

    if page_number is not None and num_records is not None:
        stmt = stmt.offset((page_number - 1) * num_records).limit(num_records)

    return db.execute(stmt).scalars().all()

get_health_steps_number_by_user_id

get_health_steps_number_by_user_id(user_id, db, interval=None)

Retrieve total count of health steps records for a user. If interval is provided, count only records starting from the calculated start date.

Parameters:

Name	Type	Description	Default
user_id	int	User ID to count records for.	required
db	Session	Database session.	required
interval	Interval | None	Optional filter by goal interval.	None

Returns:

Type	Description
int	Total number of health steps records.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/health/health_steps/crud.py

@core_decorators.handle_db_errors
def get_health_steps_number_by_user_id(
    user_id: int, db: Session, interval: health_constants.Interval | None = None
) -> int:
    """
    Retrieve total count of health steps records for a user. If interval is
    provided, count only records starting from the calculated start date.

    Args:
        user_id: User ID to count records for.
        db: Database session.
        interval: Optional filter by goal interval.

    Returns:
        Total number of health steps records.

    Raises:
        HTTPException: If database error occurs.
    """
    # Get the number of health_steps from the database
    stmt = (
        select(func.count())
        .select_from(health_steps_models.HealthSteps)
        .where(health_steps_models.HealthSteps.user_id == user_id)
    )

    if interval is not None:
        stmt = stmt.where(
            health_steps_models.HealthSteps.date
            >= health_utils.get_start_date_for_interval(interval.value)
        )

    return db.execute(stmt).scalar_one()