API Reference

Activity workout steps sub-module.

This module provides CRUD operations and data models for activity workout step records, including step duration, targets, intensity, and exercise details.

Exports

• CRUD: get_activity_workout_steps, get_activities_workout_steps, get_public_activity_workout_steps, create_activity_workout_steps
• Schemas: ActivityWorkoutSteps
• Models: ActivityWorkoutSteps (ORM model)

ActivityWorkoutSteps

Bases: BaseModel

Activity workout step schema.

Attributes:

Name	Type	Description
id	StrictInt | None	Primary key.
activity_id	StrictInt | None	FK to activities table.
message_index	StrictInt	Workout step message index.
duration_type	StrictStr	Workout step duration type.
duration_value	StrictFloat | None	Workout step duration value.
target_type	StrictStr | None	Workout step target type.
target_value	StrictInt | None	Workout step target value.
intensity	StrictStr | None	Workout step intensity type.
notes	StrictStr | None	Workout step notes.
exercise_category	StrictInt | None	Workout step exercise category.
exercise_name	StrictInt | None	Exercise name ID.
exercise_weight	StrictFloat | None	Workout step exercise weight.
weight_display_unit	StrictStr | None	Workout step weight display unit.
secondary_target_value	StrictStr | None	Workout step secondary target value.

Source code in backend/app/activities/activity_workout_steps/schema.py

class ActivityWorkoutSteps(BaseModel):
    """
    Activity workout step schema.

    Attributes:
        id: Primary key.
        activity_id: FK to activities table.
        message_index: Workout step message index.
        duration_type: Workout step duration type.
        duration_value: Workout step duration value.
        target_type: Workout step target type.
        target_value: Workout step target value.
        intensity: Workout step intensity type.
        notes: Workout step notes.
        exercise_category: Workout step exercise
            category.
        exercise_name: Exercise name ID.
        exercise_weight: Workout step exercise weight.
        weight_display_unit: Workout step weight
            display unit.
        secondary_target_value: Workout step secondary
            target value.
    """

    id: StrictInt | None = None
    activity_id: StrictInt | None = None
    message_index: StrictInt
    duration_type: StrictStr
    duration_value: StrictFloat | None = None
    target_type: StrictStr | None = None
    target_value: StrictInt | None = None
    intensity: StrictStr | None = None
    notes: StrictStr | None = None
    exercise_category: StrictInt | None = None
    exercise_name: StrictInt | None = None
    exercise_weight: StrictFloat | None = None
    weight_display_unit: StrictStr | None = None
    secondary_target_value: StrictStr | None = None

    model_config = ConfigDict(
        from_attributes=True,
    )

ActivityWorkoutStepsModel

Bases: Base

Activity workout step records.

Attributes:

Name	Type	Description
id	Mapped[int]	Primary key.
activity_id	Mapped[int]	FK to activities table.
message_index	Mapped[int]	Workout step message index.
duration_type	Mapped[str]	Workout step duration type.
duration_value	Mapped[Decimal | None]	Workout step duration value.
target_type	Mapped[str | None]	Workout step target type.
target_value	Mapped[int | None]	Workout step target value.
intensity	Mapped[str | None]	Workout step intensity type.
notes	Mapped[str | None]	Workout step notes.
exercise_category	Mapped[int | None]	Workout step exercise category.
exercise_name	Mapped[int | None]	Exercise name ID.
exercise_weight	Mapped[Decimal | None]	Workout step exercise weight.
weight_display_unit	Mapped[str | None]	Workout step weight display unit.
secondary_target_value	Mapped[str | None]	Workout step secondary target value.
activity	Mapped[Activity]	Relationship to Activity model.

Source code in backend/app/activities/activity_workout_steps/models.py

class ActivityWorkoutSteps(Base):
    """
    Activity workout step records.

    Attributes:
        id: Primary key.
        activity_id: FK to activities table.
        message_index: Workout step message index.
        duration_type: Workout step duration type.
        duration_value: Workout step duration value.
        target_type: Workout step target type.
        target_value: Workout step target value.
        intensity: Workout step intensity type.
        notes: Workout step notes.
        exercise_category: Workout step exercise
            category.
        exercise_name: Exercise name ID.
        exercise_weight: Workout step exercise weight.
        weight_display_unit: Workout step weight display
            unit.
        secondary_target_value: Workout step secondary
            target value.
        activity: Relationship to Activity model.
    """

    __tablename__ = "activity_workout_steps"

    id: Mapped[int] = mapped_column(
        primary_key=True,
        autoincrement=True,
    )
    activity_id: Mapped[int] = mapped_column(
        ForeignKey(
            "activities.id",
            ondelete="CASCADE",
        ),
        nullable=False,
        index=True,
        comment=(
            "Activity ID that the activity"
            " workout steps belongs"
        ),
    )
    message_index: Mapped[int] = mapped_column(
        nullable=False,
        comment="Workout step message index",
    )
    duration_type: Mapped[str] = mapped_column(
        String(250),
        nullable=False,
        comment="Workout step duration type",
    )
    duration_value: Mapped[Decimal | None] = (
        mapped_column(
            Numeric(precision=20, scale=10),
            nullable=True,
            comment="Workout step duration value",
        )
    )
    target_type: Mapped[str | None] = mapped_column(
        String(250),
        nullable=True,
        comment="Workout step target type",
    )
    target_value: Mapped[int | None] = mapped_column(
        nullable=True,
        comment="Workout step target value",
    )
    intensity: Mapped[str | None] = mapped_column(
        String(250),
        nullable=True,
        comment="Workout step intensity type",
    )
    notes: Mapped[str | None] = mapped_column(
        String(250),
        nullable=True,
        comment="Workout step notes",
    )
    exercise_category: Mapped[int | None] = (
        mapped_column(
            nullable=True,
            comment=(
                "Workout step exercise category"
            ),
        )
    )
    exercise_name: Mapped[int | None] = mapped_column(
        nullable=True,
        comment="Exercise name ID",
    )
    exercise_weight: Mapped[Decimal | None] = (
        mapped_column(
            Numeric(precision=20, scale=10),
            nullable=True,
            comment=(
                "Workout step exercise weight"
            ),
        )
    )
    weight_display_unit: Mapped[str | None] = (
        mapped_column(
            String(250),
            nullable=True,
            comment=(
                "Workout step weight display unit"
            ),
        )
    )
    secondary_target_value: Mapped[str | None] = (
        mapped_column(
            String(250),
            nullable=True,
            comment=(
                "Workout step secondary"
                " target value"
            ),
        )
    )

    # Define a relationship to the Activity model
    activity: Mapped["Activity"] = relationship(
        back_populates="activity_workout_steps",
    )

create_activity_workout_steps

create_activity_workout_steps(activity_workout_steps, activity_id, db)

Bulk create workout steps for an activity.

Parameters:

Name	Type	Description	Default
activity_workout_steps	list[ActivityWorkoutSteps]	List of workout step schemas to persist.	required
activity_id	int	Activity ID to associate with.	required
db	Session	Database session.	required

Returns:

Type	Description
None	None.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/activities/activity_workout_steps/crud.py

@core_decorators.handle_db_errors
def create_activity_workout_steps(
    activity_workout_steps: list[
        activity_workout_steps_schema
        .ActivityWorkoutSteps
    ],
    activity_id: int,
    db: Session,
) -> None:
    """
    Bulk create workout steps for an activity.

    Args:
        activity_workout_steps: List of workout step
            schemas to persist.
        activity_id: Activity ID to associate with.
        db: Database session.

    Returns:
        None.

    Raises:
        HTTPException: If database error occurs.
    """
    workout_steps = [
        activity_workout_steps_models
        .ActivityWorkoutSteps(
            activity_id=activity_id,
            message_index=step.message_index,
            duration_type=step.duration_type,
            duration_value=step.duration_value,
            target_type=step.target_type,
            target_value=step.target_value,
            intensity=step.intensity,
            notes=step.notes,
            exercise_category=(
                step.exercise_category
            ),
            exercise_name=step.exercise_name,
            exercise_weight=(
                step.exercise_weight
            ),
            weight_display_unit=(
                step.weight_display_unit
            ),
            secondary_target_value=(
                step.secondary_target_value
            ),
        )
        for step in activity_workout_steps
    ]

    db.add_all(workout_steps)
    db.commit()

get_activities_workout_steps

get_activities_workout_steps(activity_ids, token_user_id, db, activities=None)

Get workout steps for multiple activities.

Parameters:

Name	Type	Description	Default
activity_ids	list[int]	List of activity IDs.	required
token_user_id	int	Authenticated user ID.	required
db	Session	Database session.	required
activities	list[Activity] | None	Pre-fetched Activity ORM instances (optional).	None

Returns:

Type	Description
list[ActivityWorkoutSteps]	List of workout steps (may be empty).

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/activities/activity_workout_steps/crud.py

@core_decorators.handle_db_errors
def get_activities_workout_steps(
    activity_ids: list[int],
    token_user_id: int,
    db: Session,
    activities: (
        list[activity_models.Activity] | None
    ) = None,
) -> list[
    activity_workout_steps_models
    .ActivityWorkoutSteps
]:
    """
    Get workout steps for multiple activities.

    Args:
        activity_ids: List of activity IDs.
        token_user_id: Authenticated user ID.
        db: Database session.
        activities: Pre-fetched Activity ORM
            instances (optional).

    Returns:
        List of workout steps (may be empty).

    Raises:
        HTTPException: If database error occurs.
    """
    if not activity_ids:
        return []

    if not activities:
        stmt = select(
            activity_models.Activity
        ).where(
            activity_models.Activity.id.in_(
                activity_ids
            )
        )
        activities = db.scalars(stmt).all()

    if not activities:
        return []

    allowed_ids = [
        activity.id
        for activity in activities
        if (
            activity.user_id == token_user_id
            or not activity.hide_workout_sets_steps
        )
    ]

    if not allowed_ids:
        return []

    stmt = select(
        activity_workout_steps_models
        .ActivityWorkoutSteps
    ).where(
        activity_workout_steps_models
        .ActivityWorkoutSteps.activity_id.in_(
            allowed_ids
        )
    )
    workout_steps = db.scalars(stmt).all()

    if not workout_steps:
        return []

    return workout_steps

get_activity_workout_steps

get_activity_workout_steps(activity_id, token_user_id, db)

Get workout steps for a single activity.

Parameters:

Name	Type	Description	Default
activity_id	int	Activity ID to fetch steps for.	required
token_user_id	int	Authenticated user ID.	required
db	Session	Database session.	required

Returns:

Type	Description
list[ActivityWorkoutSteps] | None	List of workout steps or None if not found
list[ActivityWorkoutSteps] | None	or access denied.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/activities/activity_workout_steps/crud.py

@core_decorators.handle_db_errors
def get_activity_workout_steps(
    activity_id: int,
    token_user_id: int,
    db: Session,
) -> (
    list[
        activity_workout_steps_models
        .ActivityWorkoutSteps
    ]
    | None
):
    """
    Get workout steps for a single activity.

    Args:
        activity_id: Activity ID to fetch steps for.
        token_user_id: Authenticated user ID.
        db: Database session.

    Returns:
        List of workout steps or None if not found
        or access denied.

    Raises:
        HTTPException: If database error occurs.
    """
    activity = activity_crud.get_activity_by_id(
        activity_id, db
    )

    if not activity:
        return None

    if (
        token_user_id != activity.user_id
        and activity.hide_workout_sets_steps
    ):
        return None

    stmt = select(
        activity_workout_steps_models
        .ActivityWorkoutSteps
    ).where(
        activity_workout_steps_models
        .ActivityWorkoutSteps.activity_id
        == activity_id,
    )
    workout_steps = db.scalars(stmt).all()

    if not workout_steps:
        return None

    return workout_steps

get_public_activity_workout_steps

get_public_activity_workout_steps(activity_id, db)

Get workout steps for a public activity.

Parameters:

Name	Type	Description	Default
activity_id	int	Activity ID to fetch steps for.	required
db	Session	Database session.	required

Returns:

Type	Description
list[ActivityWorkoutSteps] | None	List of workout steps or None if not found,
list[ActivityWorkoutSteps] | None	hidden, not public, or feature disabled.

Raises:

Type	Description
HTTPException	If database error occurs.

Source code in backend/app/activities/activity_workout_steps/crud.py

@core_decorators.handle_db_errors
def get_public_activity_workout_steps(
    activity_id: int,
    db: Session,
) -> (
    list[
        activity_workout_steps_models
        .ActivityWorkoutSteps
    ]
    | None
):
    """
    Get workout steps for a public activity.

    Args:
        activity_id: Activity ID to fetch steps for.
        db: Database session.

    Returns:
        List of workout steps or None if not found,
        hidden, not public, or feature disabled.

    Raises:
        HTTPException: If database error occurs.
    """
    activity = activity_crud.get_activity_by_id(
        activity_id, db
    )

    if not activity:
        return None

    if activity.hide_workout_sets_steps:
        return None

    server_settings = (
        server_settings_utils
        .get_server_settings_or_404(db)
    )

    if not server_settings.public_shareable_links:
        return None

    if activity.visibility != 0:
        return None

    stmt = select(
        activity_workout_steps_models
        .ActivityWorkoutSteps
    ).where(
        activity_workout_steps_models
        .ActivityWorkoutSteps.activity_id
        == activity_id,
    )
    workout_steps = db.scalars(stmt).all()

    if not workout_steps:
        return None

    return workout_steps