Improve docstring comments (#1453)

* Improve docstring comments

Half the project was using proper format and the other half a "too many
newlines" format, so normalize the too-many-newlines to standard
formatting.

* Update src/dispatch/event/service.py

* Update src/dispatch/event/service.py

* Update src/dispatch/incident_cost/service.py

* Update src/dispatch/incident_cost/service.py

* Update src/dispatch/incident_cost/views.py

* Update src/dispatch/participant/service.py

* Update src/dispatch/tag/views.py

* Update src/dispatch/tag/views.py

* Update src/dispatch/term/views.py

* Update src/dispatch/term/views.py

* Update src/dispatch/incident_cost/views.py

* Update src/dispatch/incident_cost_type/views.py

* Update src/dispatch/incident_cost_type/views.py

* Update src/dispatch/individual/views.py

* Update src/dispatch/individual/views.py

* Update src/dispatch/individual/views.py

* Update src/dispatch/organization/views.py

* Update src/dispatch/notification/views.py

* Update src/dispatch/notification/views.py

* Update src/dispatch/organization/views.py

Co-authored-by: Marc Vilanova <39573146+mvilanova@users.noreply.github.com>

src/dispatch/auth/views.py

@@ -41,9 +41,7 @@
     response_model=UserPagination,
 )
 def get_users(*, organization: str, common: dict = Depends(common_parameters)):
-    """
-    Get all users.
-    """
+    """Get all users."""
     common["filter_spec"] = {
         "and": [{"model": "Organization", "op": "==", "field": "name", "value": organization}]
     }
@@ -66,9 +64,7 @@ def get_users(*, organization: str, common: dict = Depends(common_parameters)):
 
 @user_router.get("/{user_id}", response_model=UserRead)
 def get_user(*, db_session: Session = Depends(get_db), user_id: int):
-    """
-    Get a user.
-    """
+    """Get a user."""
     user = get(db_session=db_session, user_id=user_id)
     if not user:
         raise HTTPException(status_code=404, detail="The user with this id does not exist.")
@@ -96,9 +92,7 @@ def update_user(
     organization: str,
     user_in: UserUpdate,
 ):
-    """
-    Update a user.
-    """
+    """Update a user."""
     user = get(db_session=db_session, user_id=user_id)
     if not user:
         raise HTTPException(status_code=404, detail="The user with this id does not exist.")

src/dispatch/definition/views.py

@@ -17,17 +17,13 @@
 
 @router.get("", response_model=DefinitionPagination)
 def get_definitions(*, common: dict = Depends(common_parameters)):
-    """
-    Get all definitions.
-    """
+    """Get all definitions."""
     return search_filter_sort_paginate(model="Definition", **common)
 
 
 @router.get("/{definition_id}", response_model=DefinitionRead)
 def get_definition(*, db_session: Session = Depends(get_db), definition_id: int):
-    """
-    Update a definition.
-    """
+    """Update a definition."""
     definition = get(db_session=db_session, definition_id=definition_id)
     if not definition:
         raise HTTPException(status_code=404, detail="The definition with this id does not exist.")
@@ -36,9 +32,7 @@ def get_definition(*, db_session: Session = Depends(get_db), definition_id: int)
 
 @router.post("", response_model=DefinitionRead)
 def create_definition(*, db_session: Session = Depends(get_db), definition_in: DefinitionCreate):
-    """
-    Create a new definition.
-    """
+    """Create a new definition."""
     definition = get_by_text(db_session=db_session, text=definition_in.text)
     if definition:
         raise HTTPException(
@@ -53,9 +47,7 @@ def create_definition(*, db_session: Session = Depends(get_db), definition_in: D
 def update_definition(
     *, db_session: Session = Depends(get_db), definition_id: int, definition_in: DefinitionUpdate
 ):
-    """
-    Update a definition.
-    """
+    """Update a definition."""
     definition = get(db_session=db_session, definition_id=definition_id)
     if not definition:
         raise HTTPException(status_code=404, detail="The definition with this id does not exist.")
@@ -65,9 +57,7 @@ def update_definition(
 
 @router.delete("/{definition_id}")
 def delete_definition(*, db_session: Session = Depends(get_db), definition_id: int):
-    """
-    Delete a definition.
-    """
+    """Delete a definition."""
     definition = get(db_session=db_session, definition_id=definition_id)
     if not definition:
         raise HTTPException(status_code=404, detail="The definition with this id does not exist.")

src/dispatch/document/views.py

@@ -12,17 +12,13 @@
 
 @router.get("", response_model=DocumentPagination)
 def get_documents(*, common: dict = Depends(common_parameters)):
-    """
-    Get all documents.
-    """
+    """Get all documents."""
     return search_filter_sort_paginate(model="Document", **common)
 
 
 @router.get("/{document_id}", response_model=DocumentRead)
 def get_document(*, db_session: Session = Depends(get_db), document_id: int):
-    """
-    Update a document.
-    """
+    """Update a document."""
     document = get(db_session=db_session, document_id=document_id)
     if not document:
         raise HTTPException(status_code=404, detail="The document with this id does not exist.")
@@ -31,9 +27,7 @@ def get_document(*, db_session: Session = Depends(get_db), document_id: int):
 
 @router.post("", response_model=DocumentCreate)
 def create_document(*, db_session: Session = Depends(get_db), document_in: DocumentCreate):
-    """
-    Create a new document.
-    """
+    """Create a new document."""
     document = create(db_session=db_session, document_in=document_in)
     return document
 
@@ -42,9 +36,7 @@ def create_document(*, db_session: Session = Depends(get_db), document_in: Docum
 def update_document(
     *, db_session: Session = Depends(get_db), document_id: int, document_in: DocumentUpdate
 ):
-    """
-    Update a document.
-    """
+    """Update a document."""
     document = get(db_session=db_session, document_id=document_id)
     if not document:
         raise HTTPException(status_code=404, detail="The document with this id does not exist.")
@@ -54,9 +46,7 @@ def update_document(
 
 @router.delete("/{document_id}")
 def delete_document(*, db_session: Session = Depends(get_db), document_id: int):
-    """
-    Delete a document.
-    """
+    """Delete a document."""
     document = get(db_session=db_session, document_id=document_id)
     if not document:
         raise HTTPException(status_code=404, detail="The document with this id does not exist.")

src/dispatch/event/service.py

@@ -15,40 +15,30 @@
 
 
 def get(*, db_session, event_id: int) -> Optional[Event]:
-    """
-    Get an event by id.
-    """
+    """Get an event by id."""
     return db_session.query(Event).filter(Event.id == event_id).one_or_none()
 
 
 def get_by_incident_id(*, db_session, incident_id: int) -> List[Optional[Event]]:
-    """
-    Get events by incident id.
-    """
+    """Get events by incident id."""
     return db_session.query(Event).filter(Event.incident_id == incident_id)
 
 
 def get_all(*, db_session) -> List[Optional[Event]]:
-    """
-    Get all events.
-    """
+    """Get all events."""
     return db_session.query(Event)
 
 
 def create(*, db_session, event_in: EventCreate) -> Event:
-    """
-    Create a new event.
-    """
+    """Create a new event."""
     event = Event(**event_in.dict())
     db_session.add(event)
     db_session.commit()
     return event
 
 
 def update(*, db_session, event: Event, event_in: EventUpdate) -> Event:
-    """
-    Updates an event.
-    """
+    """Updates an event."""
     event_data = jsonable_encoder(event)
     update_data = event_in.dict(skip_defaults=True)
 
@@ -62,9 +52,7 @@ def update(*, db_session, event: Event, event_in: EventUpdate) -> Event:
 
 
 def delete(*, db_session, event_id: int):
-    """
-    Deletes an event
-    """
+    """Deletes an event."""
     event = db_session.query(Event).filter(Event.id == event_id).first()
     db_session.delete(event)
     db_session.commit()
@@ -80,9 +68,7 @@ def log(
     ended_at: datetime = None,
     details: dict = None,
 ) -> Event:
-    """
-    Logs an event
-    """
+    """Logs an event."""
     uuid = uuid4()
 
     if not started_at:

src/dispatch/feedback/messaging.py

@@ -18,9 +18,7 @@
 def send_incident_feedback_daily_report(
     commander_email: str, feedback: List[Feedback], project_id: int, db_session: SessionLocal
 ):
-    """
-    Sends an incident feedback daily report to all incident commanders who received feedback.
-    """
+    """Sends an incident feedback daily report to all incident commanders who received feedback."""
     plugin = plugin_service.get_active_instance(
         db_session=db_session, project_id=project_id, plugin_type="email"
     )

src/dispatch/feedback/views.py

@@ -19,17 +19,13 @@
 
 @router.get("", response_model=FeedbackPagination)
 def get_feedback_entries(*, commons: dict = Depends(common_parameters)):
-    """
-    Get all feedback entries, or only those matching a given search term.
-    """
+    """Get all feedback entries, or only those matching a given search term."""
     return search_filter_sort_paginate(model="Feedback", **commons)
 
 
 @router.get("/{feedback_id}", response_model=FeedbackRead)
 def get_feedback(*, db_session: Session = Depends(get_db), feedback_id: int):
-    """
-    Get a feedback entry by its id.
-    """
+    """Get a feedback entry by its id."""
     feedback = get(db_session=db_session, feedback_id=feedback_id)
     if not feedback:
         raise HTTPException(status_code=404, detail="A feedback entry with this id does not exist.")
@@ -38,9 +34,7 @@ def get_feedback(*, db_session: Session = Depends(get_db), feedback_id: int):
 
 @router.post("", response_model=FeedbackRead)
 def create_feedback(*, db_session: Session = Depends(get_db), feedback_in: FeedbackCreate):
-    """
-    Create a new feedback entry.
-    """
+    """Create a new feedback entry."""
     feedback = create(db_session=db_session, feedback_in=feedback_in)
     return feedback
 
@@ -49,9 +43,7 @@ def create_feedback(*, db_session: Session = Depends(get_db), feedback_in: Feedb
 def update_feedback(
     *, db_session: Session = Depends(get_db), feedback_id: int, feedback_in: FeedbackUpdate
 ):
-    """
-    Updates a feeback entry by its id.
-    """
+    """Updates a feeback entry by its id."""
     feedback = get(db_session=db_session, feedback_id=feedback_id)
     if not feedback:
         raise HTTPException(status_code=404, detail="A feedback entry with this id does not exist.")
@@ -61,9 +53,7 @@ def update_feedback(
 
 @router.delete("/{feedback_id}")
 def delete_feedback(*, db_session: Session = Depends(get_db), feedback_id: int):
-    """
-    Delete a feedback entry, returning only an HTTP 200 OK if successful.
-    """
+    """Delete a feedback entry, returning only an HTTP 200 OK if successful."""
     feedback = get(db_session=db_session, feedback_id=feedback_id)
     if not feedback:
         raise HTTPException(status_code=404, detail="A feedback entry with this id does not exist.")

src/dispatch/incident/scheduled.py

@@ -87,9 +87,7 @@ def auto_tagger(db_session: SessionLocal, project: Project):
 @scheduler.add(every(1).day.at("18:00"), name="incident-daily-report")
 @scheduled_project_task
 def daily_report(db_session: SessionLocal, project: Project):
-    """
-    Creates and sends incident daily reports based on notifications.
-    """
+    """Creates and sends incident daily reports based on notifications."""
     # we fetch all active, stable and closed incidents
     active_incidents = get_all_by_status(
         db_session=db_session, project_id=project.id, status=IncidentStatus.active

src/dispatch/incident/views.py

@@ -60,9 +60,7 @@ def get_incidents(
     common: dict = Depends(common_parameters),
     include: List[str] = Query([], alias="include[]"),
 ):
-    """
-    Retrieve a list of all incidents.
-    """
+    """Retrieve a list of all incidents."""
     pagination = search_filter_sort_paginate(model="Incident", **common)
 
     if include:
@@ -90,9 +88,7 @@ def get_incident(
     db_session: Session = Depends(get_db),
     current_incident: Incident = Depends(get_current_incident),
 ):
-    """
-    Retrieve details about a specific incident.
-    """
+    """Retrieve details about a specific incident."""
     return current_incident
 
 
@@ -105,9 +101,7 @@ def create_incident(
     current_user: DispatchUser = Depends(get_current_user),
     background_tasks: BackgroundTasks,
 ):
-    """
-    Create a new incident.
-    """
+    """Create a new incident."""
     if not incident_in.reporter:
         incident_in.reporter = ParticipantUpdate(
             individual=IndividualReadNested(email=current_user.email)
@@ -149,9 +143,7 @@ def update_incident(
     current_user: DispatchUser = Depends(get_current_user),
     background_tasks: BackgroundTasks,
 ):
-    """
-    Update an individual incident.
-    """
+    """Update an individual incident."""
     previous_incident = IncidentRead.from_orm(current_incident)
 
     # NOTE: Order matters we have to get the previous state for change detection
@@ -205,9 +197,7 @@ def join_incident(
     current_user: DispatchUser = Depends(get_current_user),
     background_tasks: BackgroundTasks,
 ):
-    """
-    Join an individual incident.
-    """
+    """Join an individual incident."""
     background_tasks.add_task(
         incident_add_or_reactivate_participant_flow,
         current_user.email,
@@ -230,9 +220,7 @@ def create_tactical_report(
     current_incident: Incident = Depends(get_current_incident),
     background_tasks: BackgroundTasks,
 ):
-    """
-    Creates a new tactical report.
-    """
+    """Creates a new tactical report."""
     background_tasks.add_task(
         report_flows.create_tactical_report,
         user_email=current_user.email,
@@ -256,9 +244,7 @@ def create_executive_report(
     current_user: DispatchUser = Depends(get_current_user),
     background_tasks: BackgroundTasks,
 ):
-    """
-    Creates a new executive report.
-    """
+    """Creates a new executive report."""
     background_tasks.add_task(
         report_flows.create_executive_report,
         user_email=current_user.email,
@@ -279,9 +265,7 @@ def delete_incident(
     db_session: Session = Depends(get_db),
     current_incident: Incident = Depends(get_current_incident),
 ):
-    """
-    Delete an individual incident.
-    """
+    """Delete an individual incident."""
     delete(db_session=db_session, incident_id=current_incident.id)
 
 
@@ -300,9 +284,7 @@ def get_incident_forecast(
     db_session: Session = Depends(get_db),
     filter_spec: str = Query(None, alias="filter"),
 ):
-    """
-    Get incident forecast data.
-    """
+    """Get incident forecast data."""
     categories = []
     predicted = []
     actual = []

src/dispatch/incident_cost/scheduled.py

@@ -24,9 +24,7 @@
 @scheduler.add(every(5).minutes, name="calculate-incidents-response-cost")
 @scheduled_project_task
 def calculate_incidents_response_cost(db_session: SessionLocal, project: Project):
-    """
-    Calculates and saves the response cost for all incidents.
-    """
+    """Calculates and saves the response cost for all incidents."""
     response_cost_type = incident_cost_type_service.get_default(
         db_session=db_session, project_id=project.id
     )