API Reference

User goals module for managing user fitness goals.

This module provides CRUD operations and data models for user goal tracking including activity type goals, intervals, and progress calculation.

Exports

• CRUD: get_user_goals_by_user_id, get_user_goal_by_user_and_goal_id, create_user_goal, update_user_goal, delete_user_goal
• Schemas: UsersGoalBase, UsersGoalCreate, UsersGoalUpdate, UsersGoalRead, UsersGoalProgress
• Enums: Interval, ActivityType, GoalType
• Utils: calculate_user_goals

ActivityType

Bases: StrEnum

Supported activity types for user goals.

Attributes:

Name	Type	Description
RUN		Running activities.
BIKE		Cycling activities.
SWIM		Swimming activities.
WALK		Walking or hiking activities.
STRENGTH		Strength or resistance training.
CARDIO		Cardiovascular training.

Source code in backend/app/users/users_goals/schema.py

class ActivityType(StrEnum):
    """
    Supported activity types for user goals.

    Attributes:
        RUN: Running activities.
        BIKE: Cycling activities.
        SWIM: Swimming activities.
        WALK: Walking or hiking activities.
        STRENGTH: Strength or resistance training.
        CARDIO: Cardiovascular training.
    """

    RUN = "run"
    BIKE = "bike"
    SWIM = "swim"
    WALK = "walk"
    STRENGTH = "strength"
    CARDIO = "cardio"

GoalType

Bases: StrEnum

Types of measurable user goals.

Attributes:

Name	Type	Description
CALORIES		Target calories burned.
ACTIVITIES		Target count of completed activities.
DISTANCE		Target distance traveled.
ELEVATION		Target elevation gain.
DURATION		Target total duration.

Source code in backend/app/users/users_goals/schema.py

class GoalType(StrEnum):
    """
    Types of measurable user goals.

    Attributes:
        CALORIES: Target calories burned.
        ACTIVITIES: Target count of completed activities.
        DISTANCE: Target distance traveled.
        ELEVATION: Target elevation gain.
        DURATION: Target total duration.
    """

    CALORIES = "calories"
    ACTIVITIES = "activities"
    DISTANCE = "distance"
    ELEVATION = "elevation"
    DURATION = "duration"

Interval

Bases: StrEnum

Recurrence intervals for user goals.

Attributes:

Name	Type	Description
DAILY		Daily recurrence interval.
WEEKLY		Weekly recurrence interval.
MONTHLY		Monthly recurrence interval.
YEARLY		Yearly recurrence interval.

Source code in backend/app/users/users_goals/schema.py

class Interval(StrEnum):
    """
    Recurrence intervals for user goals.

    Attributes:
        DAILY: Daily recurrence interval.
        WEEKLY: Weekly recurrence interval.
        MONTHLY: Monthly recurrence interval.
        YEARLY: Yearly recurrence interval.
    """

    DAILY = "daily"
    WEEKLY = "weekly"
    MONTHLY = "monthly"
    YEARLY = "yearly"

UsersGoalBase

Bases: BaseModel

Base schema for users fitness goals.

Attributes:

Name	Type	Description
interval	Interval	Goal time interval (daily, weekly, monthly, yearly).
activity_type	ActivityType	Type of activity for the goal.
goal_type	GoalType	Type of goal metric being tracked.
goal_calories	StrictInt | None	Target calories in kcal.
goal_activities_number	StrictInt | None	Target number of activities.
goal_distance	StrictInt | None	Target distance in meters.
goal_elevation	StrictInt | None	Target elevation gain in meters.
goal_duration	StrictInt | None	Target duration in seconds.

Source code in backend/app/users/users_goals/schema.py

class UsersGoalBase(BaseModel):
    """
    Base schema for users fitness goals.

    Attributes:
        interval: Goal time interval (daily, weekly, monthly,
            yearly).
        activity_type: Type of activity for the goal.
        goal_type: Type of goal metric being tracked.
        goal_calories: Target calories in kcal.
        goal_activities_number: Target number of activities.
        goal_distance: Target distance in meters.
        goal_elevation: Target elevation gain in meters.
        goal_duration: Target duration in seconds.
    """

    interval: Interval = Field(..., description="Goal time interval")
    activity_type: ActivityType = Field(..., description="Type of activity for the goal")
    goal_type: GoalType = Field(..., description="Type of goal metric being tracked")
    goal_calories: StrictInt | None = Field(default=None, ge=0, description="Target calories in kcal")
    goal_activities_number: StrictInt | None = Field(default=None, ge=0, description="Target number of activities")
    goal_distance: StrictInt | None = Field(default=None, ge=0, description="Target distance in meters")
    goal_elevation: StrictInt | None = Field(default=None, ge=0, description="Target elevation gain in meters")
    goal_duration: StrictInt | None = Field(default=None, ge=0, description="Target duration in seconds")

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

    @model_validator(mode="after")
    def ensure_correct_goal_field(self) -> "UsersGoalBase":
        """
        Validate exactly one goal field matches goal_type.

        Returns:
            Self with validated goal field.

        Raises:
            PydanticCustomError: If required field missing or
                extra fields set.
        """
        goal_type_value = self.goal_type if isinstance(self.goal_type, str) else self.goal_type.value

        required_field = TYPE_TO_FIELD.get(goal_type_value)
        if required_field is None:
            return self

        if getattr(self, required_field) is None:
            raise PydanticCustomError(
                "missing_goal_value",
                "{field} is required when goal_type={goal_type}",
                {
                    "field": required_field,
                    "goal_type": goal_type_value,
                },
            )

        for name in TYPE_TO_FIELD.values():
            if name != required_field and getattr(self, name) is not None:
                raise PydanticCustomError(
                    "exclusive_goal_value",
                    "Only {field} may be set when goal_type={goal_type}",
                    {
                        "field": required_field,
                        "goal_type": goal_type_value,
                    },
                )
        return self

ensure_correct_goal_field

ensure_correct_goal_field()

Validate exactly one goal field matches goal_type.

Returns:

Type	Description
UsersGoalBase	Self with validated goal field.

Raises:

Type	Description
PydanticCustomError	If required field missing or extra fields set.

Source code in backend/app/users/users_goals/schema.py

@model_validator(mode="after")
def ensure_correct_goal_field(self) -> "UsersGoalBase":
    """
    Validate exactly one goal field matches goal_type.

    Returns:
        Self with validated goal field.

    Raises:
        PydanticCustomError: If required field missing or
            extra fields set.
    """
    goal_type_value = self.goal_type if isinstance(self.goal_type, str) else self.goal_type.value

    required_field = TYPE_TO_FIELD.get(goal_type_value)
    if required_field is None:
        return self

    if getattr(self, required_field) is None:
        raise PydanticCustomError(
            "missing_goal_value",
            "{field} is required when goal_type={goal_type}",
            {
                "field": required_field,
                "goal_type": goal_type_value,
            },
        )

    for name in TYPE_TO_FIELD.values():
        if name != required_field and getattr(self, name) is not None:
            raise PydanticCustomError(
                "exclusive_goal_value",
                "Only {field} may be set when goal_type={goal_type}",
                {
                    "field": required_field,
                    "goal_type": goal_type_value,
                },
            )
    return self

UsersGoalCreate

Bases: UsersGoalBase

Schema for creating a new users goal.

Inherits all validation from UsersGoalBase.

Source code in backend/app/users/users_goals/schema.py

class UsersGoalCreate(UsersGoalBase):
    """
    Schema for creating a new users goal.

    Inherits all validation from UsersGoalBase.
    """

UsersGoalProgress

Bases: BaseModel

Schema for user goal progress tracking.

Attributes:

Name	Type	Description
goal_id	StrictInt	Goal identifier.
interval	Interval	Goal time interval.
activity_type	ActivityType	Activity type for this goal.
goal_type	GoalType	Type of goal metric.
start_date	StrictStr	Period start date.
end_date	StrictStr	Period end date.
percentage_completed	StrictInt | None	Completion percentage.
total_calories	StrictInt | None	Total calories achieved.
total_activities_number	StrictInt | None	Total activities completed.
total_distance	StrictInt | None	Total distance achieved.
total_elevation	StrictInt | None	Total elevation gained.
total_duration	StrictInt | None	Total duration achieved.
goal_calories	StrictInt | None	Target calories.
goal_activities_number	StrictInt | None	Target activities count.
goal_distance	StrictInt | None	Target distance.
goal_elevation	StrictInt | None	Target elevation.
goal_duration	StrictInt | None	Target duration.

Source code in backend/app/users/users_goals/schema.py

class UsersGoalProgress(BaseModel):
    """
    Schema for user goal progress tracking.

    Attributes:
        goal_id: Goal identifier.
        interval: Goal time interval.
        activity_type: Activity type for this goal.
        goal_type: Type of goal metric.
        start_date: Period start date.
        end_date: Period end date.
        percentage_completed: Completion percentage.
        total_calories: Total calories achieved.
        total_activities_number: Total activities completed.
        total_distance: Total distance achieved.
        total_elevation: Total elevation gained.
        total_duration: Total duration achieved.
        goal_calories: Target calories.
        goal_activities_number: Target activities count.
        goal_distance: Target distance.
        goal_elevation: Target elevation.
        goal_duration: Target duration.
    """

    goal_id: StrictInt = Field(..., ge=1, description="Goal identifier")
    interval: Interval = Field(..., description="Goal time interval")
    activity_type: ActivityType = Field(..., description="Activity type for this goal")
    goal_type: GoalType
    start_date: StrictStr = Field(..., description="Period start date")
    end_date: StrictStr = Field(..., description="Period end date")
    percentage_completed: StrictInt | None = Field(default=None, ge=0, le=100, description="Completion percentage")
    # total
    total_calories: StrictInt | None = Field(default=None, ge=0, description="Total calories achieved")
    total_activities_number: StrictInt | None = Field(default=None, ge=0, description="Total activities completed")
    total_distance: StrictInt | None = Field(default=None, ge=0, description="Total distance achieved")
    total_elevation: StrictInt | None = Field(default=None, ge=0, description="Total elevation gained")
    total_duration: StrictInt | None = Field(default=None, ge=0, description="Total duration achieved")
    # goal
    goal_calories: StrictInt | None = Field(default=None, ge=0, description="Target calories")
    goal_activities_number: StrictInt | None = Field(default=None, ge=0, description="Target activities count")
    goal_distance: StrictInt | None = Field(default=None, ge=0, description="Target distance")
    goal_elevation: StrictInt | None = Field(default=None, ge=0, description="Target elevation")
    goal_duration: StrictInt | None = Field(default=None, ge=0, description="Target duration")

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

UsersGoalRead

Bases: UsersGoalBase

Schema for reading a user goal.

Attributes:

Name	Type	Description
id	StrictInt	Unique identifier for the goal.
user_id	StrictInt	User who owns this goal.

Source code in backend/app/users/users_goals/schema.py

class UsersGoalRead(UsersGoalBase):
    """
    Schema for reading a user goal.

    Attributes:
        id: Unique identifier for the goal.
        user_id: User who owns this goal.
    """

    id: StrictInt = Field(..., ge=1, description="Unique identifier for the goal")
    user_id: StrictInt = Field(..., ge=1, description="User who owns this goal")

UsersGoalUpdate

Bases: UsersGoalRead

Schema for updating an existing users goal.

Supports partial updates. Omitted fields remain unchanged.

Source code in backend/app/users/users_goals/schema.py

class UsersGoalUpdate(UsersGoalRead):
    """
    Schema for updating an existing users goal.

    Supports partial updates. Omitted fields remain unchanged.
    """

calculate_user_goals

calculate_user_goals(user_id, date, db)

Calculate progress for all user goals on a specified date.

Parameters:

Name	Type	Description	Default
user_id	int	The ID of the user.	required
date	str | None	Date in YYYY-MM-DD format. If None, uses current date.	required
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
list[UsersGoalProgress] | None	List of UsersGoalProgress objects, or None if no goals found.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/users/users_goals/utils.py

def calculate_user_goals(
    user_id: int, date: str | None, db: Session
) -> list[user_goals_schema.UsersGoalProgress] | None:
    """
    Calculate progress for all user goals on a specified date.

    Args:
        user_id: The ID of the user.
        date: Date in YYYY-MM-DD format. If None, uses
            current date.
        db: SQLAlchemy database session.

    Returns:
        List of UsersGoalProgress objects, or None if no
            goals found.

    Raises:
        HTTPException: If database error occurs.
    """
    if not date:
        date = datetime.now(UTC).strftime("%Y-%m-%d")
    try:
        goals: list[user_goals_schema.UsersGoalRead] = user_goals_crud.get_user_goals_by_user_id(user_id, db)

        if not goals:
            return None

        return [calculate_goal_progress_by_activity_type(goal, date, db) for goal in goals]
    except HTTPException as http_err:
        raise http_err
    except (ValueError, TypeError) as err:
        # Log the exception
        core_logger.print_to_log(
            f"Error in calculate_user_goals: {err}",
            "error",
            exc=err,
        )
        # Raise an HTTPException with a 400 status code
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Invalid data provided",
        ) from err
    except Exception as err:
        # Log unexpected exceptions
        core_logger.print_to_log(
            f"Unexpected error in calculate_user_goals: {err}",
            "error",
            exc=err,
        )
        # Raise an HTTPException with a 500 status code
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail="Internal Server Error",
        ) from err

create_user_goal

create_user_goal(user_id, user_goal, db)

Create a new user goal.

Parameters:

Name	Type	Description	Default
user_id	int	The ID of the user.	required
user_goal	UsersGoalCreate	Goal data to create.	required
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
UsersGoalRead	The created UsersGoal schema.

Raises:

Type	Description
HTTPException	If goal already exists (409) or database error occurs (500).

Source code in backend/app/users/users_goals/crud.py

@core_decorators.handle_db_errors
def create_user_goal(
    user_id: int,
    user_goal: user_goals_schema.UsersGoalCreate,
    db: Session,
) -> user_goals_schema.UsersGoalRead:
    """
    Create a new user goal.

    Args:
        user_id: The ID of the user.
        user_goal: Goal data to create.
        db: SQLAlchemy database session.

    Returns:
        The created UsersGoal schema.

    Raises:
        HTTPException: If goal already exists (409) or database
            error occurs (500).
    """
    try:
        # Check if goal already exists
        stmt = select(user_goals_models.UsersGoal).where(
            user_goals_models.UsersGoal.user_id == user_id,
            user_goals_models.UsersGoal.interval == user_goal.interval,
            user_goals_models.UsersGoal.activity_type == user_goal.activity_type,
            user_goals_models.UsersGoal.goal_type == user_goal.goal_type,
        )
        existing_goal = db.execute(stmt).scalar_one_or_none()

        if existing_goal:
            raise HTTPException(
                status_code=status.HTTP_409_CONFLICT,
                detail=("User already has a goal for this activity type, interval, and goal type."),
            )

        db_users_goal = user_goals_models.UsersGoal(
            user_id=user_id,
            interval=user_goal.interval,
            activity_type=user_goal.activity_type,
            goal_type=user_goal.goal_type,
            goal_calories=user_goal.goal_calories,
            goal_activities_number=user_goal.goal_activities_number,
            goal_distance=user_goal.goal_distance,
            goal_elevation=user_goal.goal_elevation,
            goal_duration=user_goal.goal_duration,
        )
        db.add(db_users_goal)
        db.commit()
        db.refresh(db_users_goal)
        return _transform_users_goals(db_users_goal)
    except HTTPException:
        raise

delete_user_goal

delete_user_goal(user_id, goal_id, db)

Delete a user's goal from the database.

Parameters:

Name	Type	Description	Default
user_id	int	ID of the user who owns the goal.	required
goal_id	int	ID of the goal to delete.	required
db	Session	SQLAlchemy database session.	required

Raises:

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

Source code in backend/app/users/users_goals/crud.py

@core_decorators.handle_db_errors
def delete_user_goal(user_id: int, goal_id: int, db: Session) -> None:
    """
    Delete a user's goal from the database.

    Args:
        user_id: ID of the user who owns the goal.
        goal_id: ID of the goal to delete.
        db: SQLAlchemy database session.

    Raises:
        HTTPException: If goal not found (404) or database
            error occurs (500).
    """
    db_users_goal = _get_user_goal_model_by_user_and_goal_id_or_404(user_id, goal_id, db)

    db.delete(db_users_goal)
    db.commit()

get_user_goal_by_user_and_goal_id

get_user_goal_by_user_and_goal_id(user_id, goal_id, db)

Retrieve a specific goal by user ID and goal ID.

Parameters:

Name	Type	Description	Default
user_id	int	The ID of the user.	required
goal_id	int	The ID of the goal.	required
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
UsersGoalRead | None	UsersGoal schema if found, None otherwise.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/users/users_goals/crud.py

@core_decorators.handle_db_errors
def get_user_goal_by_user_and_goal_id(
    user_id: int, goal_id: int, db: Session
) -> user_goals_schema.UsersGoalRead | None:
    """
    Retrieve a specific goal by user ID and goal ID.

    Args:
        user_id: The ID of the user.
        goal_id: The ID of the goal.
        db: SQLAlchemy database session.

    Returns:
        UsersGoal schema if found, None otherwise.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = select(user_goals_models.UsersGoal).where(
        user_goals_models.UsersGoal.user_id == user_id,
        user_goals_models.UsersGoal.id == goal_id,
    )
    result = db.execute(stmt).scalar_one_or_none()
    return _transform_users_goals(result) if result else None

get_user_goals_by_user_id

get_user_goals_by_user_id(user_id, db, interval=None, activity_type=None, goal_type=None)

Retrieve goals for a specific user with optional filters.

Parameters:

Name	Type	Description	Default
user_id	int	The ID of the user.	required
db	Session	SQLAlchemy database session.	required
interval	Interval | None	Optional filter by goal interval.	None
activity_type	ActivityType | None	Optional filter by activity type.	None
goal_type	GoalType | None	Optional filter by goal type.	None

Returns:

Type	Description
list[UsersGoalRead]	List of UsersGoal schemas matching the filters.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/users/users_goals/crud.py

@core_decorators.handle_db_errors
def get_user_goals_by_user_id(
    user_id: int,
    db: Session,
    interval: user_goals_schema.Interval | None = None,
    activity_type: user_goals_schema.ActivityType | None = None,
    goal_type: user_goals_schema.GoalType | None = None,
) -> list[user_goals_schema.UsersGoalRead]:
    """
    Retrieve goals for a specific user with optional filters.

    Args:
        user_id: The ID of the user.
        db: SQLAlchemy database session.
        interval: Optional filter by goal interval.
        activity_type: Optional filter by activity type.
        goal_type: Optional filter by goal type.

    Returns:
        List of UsersGoal schemas matching the filters.

    Raises:
        HTTPException: If database error occurs.
    """
    stmt = select(user_goals_models.UsersGoal).where(user_goals_models.UsersGoal.user_id == user_id)

    if interval is not None:
        stmt = stmt.where(user_goals_models.UsersGoal.interval == interval.value)
    if activity_type is not None:
        stmt = stmt.where(user_goals_models.UsersGoal.activity_type == activity_type.value)
    if goal_type is not None:
        stmt = stmt.where(user_goals_models.UsersGoal.goal_type == goal_type.value)

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

update_user_goal

update_user_goal(user_id, user_goal, db)

Update a user's goal.

Parameters:

Name	Type	Description	Default
user_id	int	ID of the user.	required
user_goal	UsersGoalUpdate	Schema with fields to update.	required
db	Session	SQLAlchemy database session.	required

Returns:

Type	Description
UsersGoalRead	The updated UsersGoal schema.

Raises:

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

Source code in backend/app/users/users_goals/crud.py

@core_decorators.handle_db_errors
def update_user_goal(
    user_id: int,
    user_goal: user_goals_schema.UsersGoalUpdate,
    db: Session,
) -> user_goals_schema.UsersGoalRead:
    """
    Update a user's goal.

    Args:
        user_id: ID of the user.
        user_goal: Schema with fields to update.
        db: SQLAlchemy database session.

    Returns:
        The updated UsersGoal schema.

    Raises:
        HTTPException: If goal not found (404) or database
            error occurs (500).
    """
    if user_goal.user_id != user_id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Cannot edit user goal for another user",
        )

    db_users_goal = _get_user_goal_model_by_user_and_goal_id_or_404(user_id, user_goal.id, db)

    # Update only provided fields
    update_data = user_goal.model_dump(exclude_unset=True, exclude={"user_id", "id"})
    for field, value in update_data.items():
        setattr(db_users_goal, field, value)

    db.commit()
    db.refresh(db_users_goal)
    return _transform_users_goals(db_users_goal)