API Reference

Health water intake module for managing user hydration data.

This module provides CRUD operations and data models for user water intake tracking including daily consumption amounts and data sources.

Exports

• CRUD: get_health_water_number_by_user_id, get_health_water_by_id_and_user_id, get_health_water_by_user_id, get_health_water_by_date_and_user_id, create_health_water, edit_health_water, delete_health_water
• Schemas: HealthWaterBase, HealthWaterCreate, HealthWaterUpdate, HealthWaterRead, HealthWaterListResponse
• Enums: Source

HealthWaterBase

Bases: BaseModel

Base model for health water intake data.

Attributes:

Name	Type	Description
date	date | None	Calendar date of the water intake record.
amount_ml	StrictFloat | None	Water consumed in milliliters.
source	Source | None	Source of the water intake data.

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

class HealthWaterBase(BaseModel):
    """
    Base model for health water intake data.

    Attributes:
        date: Calendar date of the water intake record.
        amount_ml: Water consumed in milliliters.
        source: Source of the water intake data.
    """

    date: datetime_date | None = Field(
        default=None,
        description="Calendar date of the water intake",
    )
    amount_ml: StrictFloat | None = Field(
        default=None,
        ge=0,
        le=20000,
        description="Water consumed in milliliters",
    )
    source: Source | None = Field(
        default=None,
        description="Source of the water intake data",
    )

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

HealthWaterCreate

Bases: HealthWaterBase

Schema for creating a new water intake record.

Automatically sets the date to today if not provided.

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

class HealthWaterCreate(HealthWaterBase):
    """
    Schema for creating a new water intake record.

    Automatically sets the date to today if not provided.
    """

    @model_validator(mode="after")
    def set_default_date(self) -> "HealthWaterCreate":
        """
        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
HealthWaterCreate	The validated model instance with date set.

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

@model_validator(mode="after")
def set_default_date(self) -> "HealthWaterCreate":
    """
    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

HealthWaterListResponse

Bases: HealthListResponse

Response model for listing health water intake records.

Attributes:

Name	Type	Description
records	list[HealthWaterRead]	A list of HealthWaterRead objects representing individual water intake records.

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

class HealthWaterListResponse(health_schema.HealthListResponse):
    """
    Response model for listing health water intake records.

    Attributes:
        records: A list of HealthWaterRead objects representing
            individual water intake records.
    """

    records: list[HealthWaterRead] = Field(
        ...,
        description="List of health water intake records",
    )

HealthWaterRead

Bases: HealthWaterBase

Schema for reading a water intake record.

Attributes:

Name	Type	Description
id	StrictInt	Unique identifier for the water intake record.
user_id	StrictInt	Foreign key reference to the user.

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

class HealthWaterRead(HealthWaterBase):
    """
    Schema for reading a water intake record.

    Attributes:
        id: Unique identifier for the water intake record.
        user_id: Foreign key reference to the user.
    """

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

HealthWaterUpdate

Bases: HealthWaterRead

Schema for updating a water intake record.

Inherits from HealthWaterRead for consistency with read operations while allowing modifications to water intake data.

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

class HealthWaterUpdate(HealthWaterRead):
    """
    Schema for updating a water intake record.

    Inherits from HealthWaterRead for consistency with read
    operations while allowing modifications to water intake data.
    """

Source

Bases: Enum

Enumeration of data sources for water intake records.

Attributes:

Name	Type	Description
MANUAL		Manually entered water intake data.
GARMIN		Garmin fitness tracking platform as a data source.

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

class Source(Enum):
    """
    Enumeration of data sources for water intake records.

    Attributes:
        MANUAL: Manually entered water intake data.
        GARMIN: Garmin fitness tracking platform as a data source.
    """

    MANUAL = "manual"
    GARMIN = "garmin"

create_health_water

create_health_water(user_id, health_water, db)

Create a new water intake record for a user.

Parameters:

Name	Type	Description	Default
user_id	int	User ID for the record owner.	required
health_water	HealthWaterCreate	Water intake data to create.	required
db	Session	Database session.	required

Returns:

Type	Description
HealthWaterRead	Created water intake record.

Raises:

Type	Description
HTTPException	If duplicate entry or database error.

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

@core_decorators.handle_db_errors
def create_health_water(
    user_id: int,
    health_water: health_water_schema.HealthWaterCreate,
    db: Session,
) -> health_water_schema.HealthWaterRead:
    """
    Create a new water intake record for a user.

    Args:
        user_id: User ID for the record owner.
        health_water: Water intake data to create.
        db: Database session.

    Returns:
        Created water intake record.

    Raises:
        HTTPException: If duplicate entry or database error.
    """
    try:
        db_health_water = health_water_models.HealthWater(
            **health_water.model_dump(exclude_none=False),
            user_id=user_id,
        )

        db.add(db_health_water)
        db.commit()
        db.refresh(db_health_water)

        return _transform_health_water(db_health_water)
    except IntegrityError as integrity_error:
        db.rollback()

        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=(f"Duplicate entry error. Check if there is already an entry created for {health_water.date}"),
        ) from integrity_error

delete_health_water

delete_health_water(user_id, health_water_id, db)

Delete a water intake record for a user.

Parameters:

Name	Type	Description	Default
user_id	int	User ID who owns the record.	required
health_water_id	int	Water intake 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_water/crud.py

@core_decorators.handle_db_errors
def delete_health_water(user_id: int, health_water_id: int, db: Session) -> None:
    """
    Delete a water intake record for a user.

    Args:
        user_id: User ID who owns the record.
        health_water_id: Water intake record ID to delete.
        db: Database session.

    Returns:
        None

    Raises:
        HTTPException: If record not found or database error.
    """
    db_health_water = _get_health_water_model_by_id_and_user_id_or_404(health_water_id, user_id, db)

    db.delete(db_health_water)
    db.commit()

edit_health_water

edit_health_water(user_id, health_water, db)

Edit water intake record for a user.

Parameters:

Name	Type	Description	Default
user_id	int	User ID who owns the record.	required
health_water	HealthWaterUpdate	Water intake data to update.	required
db	Session	Database session.	required

Returns:

Type	Description
HealthWaterRead	Updated HealthWaterRead schema.

Raises:

Type	Description
HTTPException	403 if editing another user's record, 404 if not found, 500 if database error.

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

@core_decorators.handle_db_errors
def edit_health_water(
    user_id: int,
    health_water: health_water_schema.HealthWaterUpdate,
    db: Session,
) -> health_water_schema.HealthWaterRead:
    """
    Edit water intake record for a user.

    Args:
        user_id: User ID who owns the record.
        health_water: Water intake data to update.
        db: Database session.

    Returns:
        Updated HealthWaterRead schema.

    Raises:
        HTTPException: 403 if editing another user's record,
            404 if not found, 500 if database error.
    """
    if health_water.user_id != user_id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail=("Cannot edit health water intake for another user."),
        )

    db_health_water = _get_health_water_model_by_id_and_user_id_or_404(health_water.id, user_id, db)

    health_water_data = health_water.model_dump(exclude_unset=True)
    for key, value in health_water_data.items():
        setattr(db_health_water, key, value)

    db.commit()
    db.refresh(db_health_water)

    return _transform_health_water(db_health_water)

get_health_water_by_date_and_user_id

get_health_water_by_date_and_user_id(user_id, date, db)

Retrieve water intake 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 water intake record.	required
db	Session	Database session.	required

Returns:

Type	Description
HealthWaterRead | None	HealthWaterRead schema if found, None otherwise.

Raises:

Type	Description
HTTPException	If database error occurs.

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

@core_decorators.handle_db_errors
def get_health_water_by_date_and_user_id(
    user_id: int, date: str, db: Session
) -> health_water_schema.HealthWaterRead | None:
    """
    Retrieve water intake record for a user on a specific date.

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

    Returns:
        HealthWaterRead schema if found, None otherwise.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = select(health_water_models.HealthWater).where(
        health_water_models.HealthWater.date == func.date(date),
        health_water_models.HealthWater.user_id == user_id,
    )
    db_health_water = db.execute(stmt).scalar_one_or_none()

    return _transform_health_water(db_health_water) if db_health_water else None

get_health_water_by_id_and_user_id

get_health_water_by_id_and_user_id(health_water_id, user_id, db)

Retrieve water intake record by ID and user ID.

Parameters:

Name	Type	Description	Default
health_water_id	int	Water intake record ID to fetch.	required
user_id	int	User ID to fetch record for.	required
db	Session	Database session.	required

Returns:

Type	Description
HealthWaterRead | None	HealthWaterRead schema if found, None otherwise.

Raises:

Type	Description
HTTPException	If database error occurs.

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

@core_decorators.handle_db_errors
def get_health_water_by_id_and_user_id(
    health_water_id: int, user_id: int, db: Session
) -> health_water_schema.HealthWaterRead | None:
    """
    Retrieve water intake record by ID and user ID.

    Args:
        health_water_id: Water intake record ID to fetch.
        user_id: User ID to fetch record for.
        db: Database session.

    Returns:
        HealthWaterRead schema if found, None otherwise.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = select(health_water_models.HealthWater).where(
        health_water_models.HealthWater.id == health_water_id,
        health_water_models.HealthWater.user_id == user_id,
    )
    db_health_water = db.execute(stmt).scalar_one_or_none()
    return _transform_health_water(db_health_water) if db_health_water else None

get_health_water_by_user_id

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

Retrieve water intake records for a user with optional pagination and filtering.

Parameters:

Name	Type	Description	Default
user_id	int	User ID whose records are to be retrieved.	required
db	Session	Database session used to execute the query.	required
page_number	int | None	Page number for pagination (1-indexed).	None
num_records	int | None	Number of records per page.	None
interval	Interval | None	Time interval to filter records.	None

Returns:

Type	Description
list[HealthWaterRead]	List of HealthWaterRead schema records sorted by date descending.

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

@core_decorators.handle_db_errors
def get_health_water_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_water_schema.HealthWaterRead]:
    """
    Retrieve water intake records for a user with optional
    pagination and filtering.

    Args:
        user_id: User ID whose records are to be retrieved.
        db: Database session used to execute the query.
        page_number: Page number for pagination (1-indexed).
        num_records: Number of records per page.
        interval: Time interval to filter records.

    Returns:
        List of HealthWaterRead schema records sorted by date descending.
    """
    stmt = select(health_water_models.HealthWater).where(health_water_models.HealthWater.user_id == user_id)

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

    stmt = stmt.order_by(desc(health_water_models.HealthWater.date))

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

    db_health_water = db.execute(stmt).scalars().all()

    return _transform_health_water(list(db_health_water))

get_health_water_number_by_user_id

get_health_water_number_by_user_id(user_id, db, interval=None)

Retrieve total count of water intake 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 water intake records.

Raises:

Type	Description
HTTPException	If database error occurs.

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

@core_decorators.handle_db_errors
def get_health_water_number_by_user_id(
    user_id: int,
    db: Session,
    interval: health_constants.Interval | None = None,
) -> int:
    """
    Retrieve total count of water intake 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 water intake records.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = (
        select(func.count())
        .select_from(health_water_models.HealthWater)
        .where(health_water_models.HealthWater.user_id == user_id)
    )

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

    return db.execute(stmt).scalar_one()