docs: org docstrings

issue: #13

src/organisation/config.py

@@ -1,7 +1,3 @@
 """
-Configurations for organisation module
-
-Configurations:
- - List: Description
- - Configs: Description
+Configurations for the organisation module
 """

src/organisation/constants.py

@@ -1,5 +1,5 @@
 """
-Constants and error codes for organisation module
+Constants for the organisation module
 
 Classes:
  - Status(StrEnum): PARTIAL, SUBMITTED, REMEDIATION, APPROVED, REJECTED, REMOVED

src/organisation/dependencies.py

@@ -1,13 +1,9 @@
 """
-Router dependencies for organisation module
+Dependencies related to the organisation module
 
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Exports:
+ - org_model_query_dependency: org_model: Gets org model from db, if it exists. Uses org_id from query param. Also verifies if the org has been approved.
+ - org_model_body_dependency: org_model: Gets org model from db, if it exists. Uses org_id from request body. Also verifies if the org has been approved.
 """
 from typing import Annotated, Optional
 

src/organisation/exceptions.py

@@ -1,9 +1,9 @@
 """
-Module specific exceptions for organisation module
+Exceptions related to the organisation module
 
 Exceptions:
- - List: Description
- - Exceptions: Description
+ - OrgNotFoundException: Takes an optional org_id int
+ - AwaitingApprovalException: Takes an optional org_id int
 """
 from typing import Optional
 

src/organisation/models.py

@@ -2,9 +2,16 @@
 Database models for organisation module
 
 Models:
- - Organisation: id[pk], name, status, intake_questionnaire,
-                billing_contact_id[fk], security_contact_id[fk], owner_contact_id[fk]
- - OrgUsers: org_id[fk][cpk], user_id[fk][cpk], is_admin
+ - Organisation:
+  - id[PK], name, status, intake_questionnaire, root_user_id[FK], billing_contact_id[FK], security_contact_id[FK], owner_contact_id[FK]
+  - user_rel: ORM relationship to User via OrgUsers relationship table
+  - group_rel: ORM relationship to Group, backprops Group.org_rel
+  - root_user_rel: ORM relationship to User with root_user_id FK
+  - root_user_email: Calc property root_user_rel.email
+  - billing_contact_rel: ORM relationship to Contact with billing_contact FK
+  - security_contact_rel: ORM relationship to Contact with security_contact FK
+  - owner_contact_rel: ORM relationship to Contact with owner_contact FK
+ - OrgUsers: org_id[FK][PK], user_id[FK][PK]
 """
 from sqlalchemy import Column, Integer, String, ForeignKey, JSON
 from sqlalchemy.orm import relationship

src/organisation/router.py

@@ -2,15 +2,18 @@
 Router endpoints for organisation module
 
 Endpoints:
- - [get]/id/{org_id} - Retrieves an organisation by its ID
- - [post]/ - Creates a new organisation
- - [patch]/{org_id}/questionnaire - Updates the questionnaire data for an organisation (can be partial or final submission)
- - [patch]/{org_id}/status - Updates the status of an organisation
- - [patch]/{org_id}/contact - Assigns a contact to an organisation (as billing, security, or owner)
- - [get]/{org_id}/users - Retrieves all users associated with an organisation
- - [post]/{org_id}/users - Adds a new user to an organisation
- - [delete]/{org_id} - Deletes an organisation by ID
- - [get]/{org_id}/contact/{contact_type} - Retrieves the contact of a specific type (owner, billing, security) for an organisation
+ - [GET](/org/id): [root user]: Get details about an organisation(id)
+ - [POST](/org/): [oidc claim]: Creates an organisation, adds the current user as a user and sets them to be the root user
+ - [PATCH](/org/questionnaire): [root user]: Updates the org's intake questionnaire and optionally be submitted for review
+ - [PATCH](/org/status): [super admin]: Allows a super admin to update an org(id) status(Status enum)
+ - [GET](/org/users): [root user]: Gets a list of the org(id) users(email)
+ - [POST](/org/users): [root user]: Adds a new user(id) to the org(id)
+ - [DELETE](/org/): [super admin]: Deletes an organisation(id)
+ - [PATCH](/org/root_user): [super admin]: Updates an org(id) root user(id)
+ - [GET](/org/groups): [root user]: Gets a list of the org(id) groups(name)
+ - [DELETE](/org/user): [root user]: Removes a user(id) from an org(id)
+ - [GET](/org/contact): [root user]: Gets the (contact_type) contact for an org(id)
+ - [PATCH](/org/contact): [root user]: Updates the (contact_type) contact for an org(id). Any number of details can be changed.
 """
 from typing import Annotated, Optional
 

src/organisation/schemas.py

@@ -1,9 +1,10 @@
 """
 Pydantic models for organisation module
 
-Models:
- - List: Description
- - Models: Description
+Models follow the nomenclature of:
+- Sub-models: "<Resource><Opt:>Schema"
+- Mixins: "<Attribute>Mixin"
+- Models: "<Module><Method><Resource><Opt:Resource><Direction>" ie "OrgPostOrgRequest"
 """
 from typing import Optional
 

src/organisation/service.py

@@ -1,11 +1,3 @@
 """
-Module specific business logic for organisation module
-
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Reusable business logic functions for the organisation module
 """

src/organisation/utils.py

@@ -1,11 +1,3 @@
 """
-Non-business logic reusable functions and classes for organisation module
-
-Classes:
- - List: Description
- - Classes: Description
-
-Functions:
- - List: Description
- - Functions: Description
+Non-business logic reusable functions and classes for the organisation module
 """