Skip to content

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_component_by_id, 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 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
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 
169
170
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 
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
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 
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
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 
210
211
212
213
214
215
216
217
218
219
220
221
class GearComponentUpdate(GearComponentBase):
    """
    Schema for updating a gear component.

    Attributes:
        id: Unique identifier.
    """

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

GearComponents

Bases: Base

Gear component data model.

Attributes:

Name Type Description
id Mapped[int]

Primary key.
user_id Mapped[int]

Foreign key to users table.
gear_id Mapped[int]

Foreign key to gear table.
type Mapped[str]

Type of gear component.
brand Mapped[str]

Gear component brand.
model Mapped[str]

Gear component model.
purchase_date Mapped[datetime]

Purchase date.
retired_date Mapped[datetime | None]

Retired date.
active Mapped[bool]

Whether component is active.
expected_kms Mapped[int | None]

Expected kilometers.
purchase_value Mapped[Decimal | None]

Purchase value.
users Mapped[Users]

Relationship to Users model.
gear Mapped[Gear]

Relationship to Gear model.
Source code in backend/app/gears/gear_components/models.py 
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class GearComponents(Base):
    """
    Gear component data model.

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

    __tablename__ = "gear_components"

    id: Mapped[int] = mapped_column(
        primary_key=True,
        autoincrement=True,
    )
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"),
        nullable=False,
        comment=(
            "User ID that the gear"
            " component belongs to"
        ),
    )
    gear_id: Mapped[int] = mapped_column(
        ForeignKey("gear.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
        comment=(
            "Gear ID associated with"
            " this component"
        ),
    )
    type: Mapped[str] = mapped_column(
        String(250),
        nullable=False,
        comment="Type of gear component",
    )
    brand: Mapped[str] = mapped_column(
        String(250),
        nullable=False,
        comment=(
            "Gear component brand"
            " (May include spaces)"
        ),
    )
    model: Mapped[str] = mapped_column(
        String(250),
        nullable=False,
        comment=(
            "Gear component model"
            " (May include spaces)"
        ),
    )
    purchase_date: Mapped[datetime_type] = mapped_column(
        DateTime(timezone=True),
        nullable=False,
        default=func.now(),
        comment=(
            "Gear component purchase"
            " date (DateTime)"
        ),
    )
    retired_date: Mapped[datetime_type | None] = (
        mapped_column(
            DateTime(timezone=True),
            nullable=True,
            comment=(
                "Gear component retired"
                " date (DateTime)"
            ),
        )
    )
    active: Mapped[bool] = mapped_column(
        nullable=False,
        default=False,
        comment=(
            "Whether the gear component"
            " is active"
            " (true - yes, false - no)"
        ),
    )
    expected_kms: Mapped[int | None] = mapped_column(
        nullable=True,
        comment=(
            "Expected kilometers of"
            " the gear component"
        ),
    )
    purchase_value: Mapped[Decimal | None] = (
        mapped_column(
            Numeric(precision=11, scale=2),
            nullable=True,
            comment=(
                "Purchase value of"
                " the gear component"
            ),
        )
    )

    users: Mapped["Users"] = relationship(
        back_populates="gear_components",
    )
    gear: Mapped["Gear"] = relationship(
        back_populates="gear_components",
    )

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
GearComponents

Created ORM gear component.

Raises:

Type Description
HTTPException

On database error (500).
Source code in backend/app/gears/gear_components/crud.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@core_decorators.handle_db_errors
def create_gear_component(
    gear_component: (
        gear_components_schema.GearComponentCreate
    ),
    user_id: int,
    db: Session,
) -> gear_components_models.GearComponents:
    """
    Create a new gear component.

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

    Returns:
        Created ORM gear component.

    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 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 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
@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).
    """
    stmt = delete(
        gear_components_models.GearComponents,
    ).where(
        gear_components_models.GearComponents
        .user_id
        == user_id,
        gear_components_models.GearComponents.id
        == gear_component_id,
    )
    result = db.execute(stmt)

    if result.rowcount == 0:
        raise HTTPException(
            status_code=(
                status.HTTP_404_NOT_FOUND
            ),
            detail=(
                f"Gear component with ID "
                f"{gear_component_id} not found"
            ),
        )

    db.commit()

edit_gear_component 

edit_gear_component(gear_component, db)

Edit an existing gear component by ID.

Parameters:

Name Type Description Default
gear_component GearComponentUpdate

Update schema data.

 required
db Session

Database session.

 required

Returns:

Type Description
GearComponents

Updated ORM gear component.

Raises:

Type Description
HTTPException

If not found (404) or database error (500).
Source code in backend/app/gears/gear_components/crud.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
@core_decorators.handle_db_errors
def edit_gear_component(
    gear_component: (
        gear_components_schema.GearComponentUpdate
    ),
    db: Session,
) -> gear_components_models.GearComponents:
    """
    Edit an existing gear component by ID.

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

    Returns:
        Updated ORM gear component.

    Raises:
        HTTPException: If not found (404) or
            database error (500).
    """
    stmt = select(
        gear_components_models.GearComponents,
    ).where(
        gear_components_models.GearComponents.id
        == gear_component.id,
    )
    db_gear_component = (
        db.execute(stmt).scalar_one_or_none()
    )

    if db_gear_component is None:
        raise HTTPException(
            status_code=(
                status.HTTP_404_NOT_FOUND
            ),
            detail="Gear component not found",
        )

    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 retired_date / active invariant.
    if db_gear_component.retired_date is not None:
        db_gear_component.active = False
    elif "retired_date" in gear_component_data:
        # retired_date explicitly cleared.
        db_gear_component.active = True

    db.commit()
    db.refresh(db_gear_component)

    return db_gear_component

get_gear_component_by_id 

get_gear_component_by_id(gear_component_id, db)

Retrieve a gear component by its ID.

Parameters:

Name Type Description Default
gear_component_id int

Primary key.

 required
db Session

Database session.

 required

Returns:

Type Description
GearComponents | None

ORM gear component or None.

Raises:

Type Description
HTTPException

On database error (500).
Source code in backend/app/gears/gear_components/crud.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@core_decorators.handle_db_errors
def get_gear_component_by_id(
    gear_component_id: int,
    db: Session,
) -> gear_components_models.GearComponents | None:
    """
    Retrieve a gear component by its ID.

    Args:
        gear_component_id: Primary key.
        db: Database session.

    Returns:
        ORM gear component or None.

    Raises:
        HTTPException: On database error (500).
    """
    stmt = select(
        gear_components_models.GearComponents,
    ).where(
        gear_components_models.GearComponents.id
        == gear_component_id,
    )
    return (
        db.execute(stmt).scalar_one_or_none()
    )

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[GearComponents]

List of ORM gear components.

Raises:

Type Description
HTTPException

On database error (500).
Source code in backend/app/gears/gear_components/crud.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
@core_decorators.handle_db_errors
def get_gear_components_user(
    user_id: int,
    db: Session,
) -> list[gear_components_models.GearComponents]:
    """
    Retrieve all gear components for a user.

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

    Returns:
        List of ORM gear components.

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

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[GearComponents]

List of ORM gear components.

Raises:

Type Description
HTTPException

On database error (500).
Source code in backend/app/gears/gear_components/crud.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
@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_models.GearComponents]:
    """
    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 ORM gear components.

    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,
        )
    return db.execute(stmt).scalars().all()