From 43cb7e700dc1c79a3f47ba2ffa2f514f07c015d7 Mon Sep 17 00:00:00 2001
From: luxferre <chris@sr2.uk>
Date: Thu, 28 May 2026 14:55:44 +0100
Subject: [PATCH] docs: user docstrings

Issue: #13
---
 src/user/config.py       |  6 +-----
 src/user/constants.py    |  6 +-----
 src/user/dependencies.py | 13 +++++--------
 src/user/exceptions.py   |  5 ++---
 src/user/models.py       |  7 ++++++-
 src/user/router.py       | 14 +++++---------
 src/user/schemas.py      |  6 +-----
 src/user/service.py      |  5 +----
 src/user/utils.py        | 10 +---------
 9 files changed, 23 insertions(+), 49 deletions(-)

diff --git a/src/user/config.py b/src/user/config.py
index 1b9a778..9bbcbc4 100644
--- a/src/user/config.py
+++ b/src/user/config.py
@@ -1,7 +1,3 @@
 """
-Configurations for user module
-
-Configurations:
- - List: Description
- - Configs: Description
+Configurations for the user module
 """
\ No newline at end of file
diff --git a/src/user/constants.py b/src/user/constants.py
index 940b259..fc6a780 100644
--- a/src/user/constants.py
+++ b/src/user/constants.py
@@ -1,7 +1,3 @@
 """
-Constants and error codes for user module
-
-Constants:
- - List: Description
- - Consts: Description
+Constants for the user module
 """
\ No newline at end of file
diff --git a/src/user/dependencies.py b/src/user/dependencies.py
index c5314d0..dc22429 100644
--- a/src/user/dependencies.py
+++ b/src/user/dependencies.py
@@ -1,13 +1,10 @@
 """
-Router dependencies for user module
+Dependencies related to the user module
 
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Exports:
+ - user_model_claims_dependency: user_model: Gets user model from db, if it exists. Uses db_id from user claims.
+ - user_model_query_dependency: user_model: Gets user model from db, if it exists. Uses user_id from query param
+ - user_model_body_dependency: user_model: Gets user model from db, if it exists. Uses user_id from request body.
 """
 from typing import Annotated
 from fastapi import Depends, Query
diff --git a/src/user/exceptions.py b/src/user/exceptions.py
index 6f2a669..2e03b05 100644
--- a/src/user/exceptions.py
+++ b/src/user/exceptions.py
@@ -1,9 +1,8 @@
 """
-Module specific exceptions for user module
+Exceptions related to the user module
 
 Exceptions:
- - List: Description
- - Exceptions: Description
+ - UserNotFoundException: Takes an optional user_id int
 """
 from typing import Optional
 
diff --git a/src/user/models.py b/src/user/models.py
index 964bed6..92350ed 100644
--- a/src/user/models.py
+++ b/src/user/models.py
@@ -2,7 +2,12 @@
 Database models for user module
 
 Models:
- - User - id[pk], email, first_name, last_name, oidc_id
+ - User:
+  - id[PK], email, first_name, last_name, oidc_id
+  - organisation_rel: ORM relationship to Organisation via OrgUsers table
+  - group_rel: ORM relationship to Group via UserGroups table
+  - organisations: Calc property list of organisation_rel.name
+  - groups: Calc property dict of {group_rel.org_rel.name: group_rel.name}
 """
 from collections import defaultdict
 
diff --git a/src/user/router.py b/src/user/router.py
index c7dbb12..90c133f 100644
--- a/src/user/router.py
+++ b/src/user/router.py
@@ -1,15 +1,11 @@
 """
-Router endpoints for user module
+Router endpoints for the user module
 
 Endpoints:
- - [get]/self/claims - Retrieves user's OIDC claims
- - [get]/self/db - Retrieves the user data from the db that corresponds to the current OIDC user
- - [get]/self/orgs - Retrieves all organisations associated with the current user
- - [get]/self/orgs/admin - Retrieves only admin organisations for the current user
- - [get]/{user_id} - Retrieves a specific user by their ID
- - [get]/{user_id}/orgs - Retrieves all organisations associated with a specific user
- - [get]/{user_id}/orgs/admin - Retrieves only admin organisations for a specific user
- - [delete]/{user_id} - Deletes a user from the db by their db ID
+ - [GET](/user/self/claims): [OIDC claims]: Returns all OIDC claims associated with the currently logged-in user.
+ - [GET](/user/self/db): [OIDC claims]: Returns details about the currently logged-in user from the hub db.
+ - [GET](/user/): [super admin]: Returns user(id) details.
+ - [DELETE](/user/): [super admin]: Removes a User(id) from the hub database.
 """
 from fastapi import APIRouter
 from starlette import status
diff --git a/src/user/schemas.py b/src/user/schemas.py
index 285f510..27d455e 100644
--- a/src/user/schemas.py
+++ b/src/user/schemas.py
@@ -1,9 +1,5 @@
 """
-Pydantic models for user module
-
-Models:
- - List: Description
- - Models: Description
+Pydantic models for the user module
 """
 from typing import Optional
 from src.schemas import CustomBaseModel
diff --git a/src/user/service.py b/src/user/service.py
index 378d837..f65e045 100644
--- a/src/user/service.py
+++ b/src/user/service.py
@@ -1,11 +1,8 @@
 """
 Module specific business logic for user module
 
-Functions:
- - add_user_to_db
-
 Exports:
- - add_user_to_db
+ - add_user_to_db: Creates a User record from OIDC claims, or updates user details
 """
 from typing import Any
 
diff --git a/src/user/utils.py b/src/user/utils.py
index 658daa1..35fcc1a 100644
--- a/src/user/utils.py
+++ b/src/user/utils.py
@@ -1,11 +1,3 @@
 """
-Non-business logic reusable functions and classes for user module
-
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Non-business logic reusable functions and classes for the user module
 """
\ No newline at end of file