Dom new (#148)

* updating docstrings

Author: terazus

ptmd/database/models/file.py

@@ -198,11 +198,11 @@ def __validate_time(self, at: str | None, field: str) -> datetime:
         """ Validate the time of the shipment or reception of the file to make sure it is after the start and end date
         of the collection steps.
 
-        :@param at: the date the samples were shipped
-        :@param field: the field to be validated
-        :@return: the date the samples were shipped
+        :param at: the date the samples were shipped
+        :param field: the field to be validated
+        :return: the date the samples were shipped
 
-        :@raise ValueError: if the date is before the start or end date of the collection steps
+        :raise ValueError: if the date is before the start or end date of the collection steps
         """
         start_date: datetime = datetime.strptime(self.start_date.strftime('%Y-%m-%d'), '%Y-%m-%d')
         end_date: datetime = datetime.strptime(self.end_date.strftime('%Y-%m-%d'), '%Y-%m-%d')

ptmd/database/models/token_blocklist.py

@@ -20,9 +20,9 @@ def __init__(self, jti: str):
 
 @jwt.token_in_blocklist_loader
 def check_if_token_revoked(jwt_header: dict, jwt_payload: dict) -> bool:
-    """ Check if a JWT exists in the database blocklist
+    """Check if a JWT exists in the database blocklist
 
-    @param jwt_header: JWT header
-    @param jwt_payload: JWT payload
+    :param jwt_header: JWT header
+    :param jwt_payload: JWT payload
     """
     return session.query(TokenBlocklist.id).filter_by(jti=jwt_payload["jti"]).scalar() is not None  # type: ignore

ptmd/database/queries/files.py

@@ -83,7 +83,7 @@ def get_shipped_file(species: str, batch: str) -> File | None:  # pragma: no cov
     :param batch: the batch of the file
     :return: the first received file with the given batch and species if it exists or None
 
-    @note: This function is excluded from coverage report because it is just a wrapper around a database query
+    :note: This function is excluded from coverage report because it is just a wrapper around a database query
     """
     return File.query.join(Organism).filter(
             Organism.ptox_biosystem_name == species,

ptmd/database/queries/users.py

@@ -14,9 +14,9 @@
 def login_user(username: str, password: str) -> tuple[Response, int]:
     """ Login a user and return a JWT token. The username and password are retrieved from the request body.
 
-    @param username
-    @param password
-    @return: Response, int: the response message and the response code
+    :param username
+    :param password
+    :return: Response, int: the response message and the response code
     """
     raw_user = User.query.filter(User.username == username).first()
     user = dict(raw_user) if raw_user and raw_user.validate_password(password) else None

ptmd/lib/creator/__init__.py

@@ -1,6 +1,6 @@
 """ This module contains the Model class and functions that, given a list of fields, will generate the dataframe and
 ISA objects.
 
-@author: Terazus (D. Batista)
+:author: Terazus (D. Batista)
 """
 from .core import DataframeCreator

ptmd/lib/email/core.py

@@ -22,10 +22,10 @@
 def send_confirmation_mail(username: str, email: str, token: str) -> str:
     """ Send the account activation email to the user.
 
-    @param username: the name of the user
-    @param email: the email of the user
-    @param token: the token to be used to activate the account
-    @return: the message sent to the user
+    :param username: the name of the user
+    :param email: the email of the user
+    :param token: the token to be used to activate the account
+    :return: the message sent to the user
     """
     service: Any = build('gmail', 'v1', credentials=Credentials.from_authorized_user_file(get_config()))
     message: MIMEMultipart = build_email_core(title='PTMD - Account activation', email=email)
@@ -36,9 +36,9 @@ def send_confirmation_mail(username: str, email: str, token: str) -> str:
 def send_validated_account_mail(username: str, email: str) -> str:
     """ Send the notification to the user that the account is now active.
 
-    @param username: the name of the user
-    @param email: the email of the user
-    @return: the message sent to the user
+    :param username: the name of the user
+    :param email: the email of the user
+    :return: the message sent to the user
     """
     service: Any = build('gmail', 'v1', credentials=Credentials.from_authorized_user_file(get_config()))
     message: MIMEMultipart = build_email_core(title='PTMD - Your account is now active', email=email)
@@ -49,8 +49,8 @@ def send_validated_account_mail(username: str, email: str) -> str:
 def send_validation_mail(user: object) -> str:
     """ Send the notification to the admin that a user account needs activation.
 
-    @param user: the User class to be used to get the user information
-    @return: the message sent to the user
+    :param user: the User class to be used to get the user information
+    :return: the message sent to the user
     """
     service: Any = build('gmail', 'v1', credentials=Credentials.from_authorized_user_file(get_config()))
     message: MIMEMultipart = build_email_core(title='PTMD - An account needs to be activated', email=ADMIN_EMAIL)
@@ -61,9 +61,9 @@ def send_validation_mail(user: object) -> str:
 def build_email_core(title: str, email: str) -> MIMEMultipart:
     """ Build the core of the email and return a MIMEMultipart object.
 
-    @param title: the title of the email
-    @param email: the email of the user
-    @return: the core of the email
+    :param title: the title of the email
+    :param email: the email of the user
+    :return: the core of the email
     """
     message: MIMEMultipart = MIMEMultipart()
     message['Subject'] = title
@@ -75,9 +75,9 @@ def build_email_core(title: str, email: str) -> MIMEMultipart:
 def send_email(message: MIMEMultipart, service: Any, body: str) -> str:
     """ Send the email to the user.
 
-    @param message: the MIMEMultipart object to be used to send the email
-    @param service: the service to be used to send the email
-    @param body: the body of the email
+    :param message: the MIMEMultipart object to be used to send the email
+    :param service: the service to be used to send the email
+    :param body: the body of the email
     """
     message.attach(MIMEText(body, 'html'))
     create_message = {'raw': urlsafe_b64encode(message.as_bytes()).decode()}
@@ -88,10 +88,10 @@ def send_email(message: MIMEMultipart, service: Any, body: str) -> str:
 def send_reset_pwd_email(username: str, email: str, token: str) -> str:
     """ Send the reset password token to the user.
 
-    @param username: the name of the user
-    @param email: the email of the user
-    @param token: the token to be used to reset the account password
-    @return: the message sent to the user
+    :param username: the name of the user
+    :param email: the email of the user
+    :param token: the token to be used to reset the account password
+    :return: the message sent to the user
     """
     service: Any = build('gmail', 'v1', credentials=Credentials.from_authorized_user_file(get_config()))
     message: MIMEMultipart = build_email_core(title='PTMD -Reset Password', email=email)

ptmd/lib/email/load_templates.py

@@ -12,9 +12,9 @@
 def create_confirmation_email_content(username: str, token: str) -> str:
     """ Create the content of the confirmation email to be sent to the user.
 
-    @param username: the name of the user
-    @param token: the token to be used to activate the account
-    @return: the content of the email
+    :param username: the name of the user
+    :param token: the token to be used to activate the account
+    :return: the content of the email
     """
     with open(path.join(TEMPLATES_PATH, 'enable_account.html'), 'r') as template_data:
         template: Template = Template(template_data.read())
@@ -24,8 +24,8 @@ def create_confirmation_email_content(username: str, token: str) -> str:
 def create_validated_email_content(username: str) -> str:
     """ Create the content of the email to be sent to the user when his account has been validated by an admin.
 
-    @param username: the name of the user
-    @return: the content of the email
+    :param username: the name of the user
+    :return: the content of the email
     """
     with open(path.join(TEMPLATES_PATH, 'activated_account.html'), 'r') as template_data:
         template: Template = Template(template_data.read())
@@ -35,8 +35,8 @@ def create_validated_email_content(username: str) -> str:
 def create_validation_mail_content(user: Any) -> str:
     """ Create the content of the email to be sent to the user.
 
-    @param user: the user account to activate
-    @return: the content of the email
+    :param user: the user account to activate
+    :return: the content of the email
     """
     with open(path.join(TEMPLATES_PATH, 'activate_account.html'), 'r') as template_data:
         template: Template = Template(template_data.read())
@@ -46,9 +46,9 @@ def create_validation_mail_content(user: Any) -> str:
 def create_reset_pwd_mail_content(username: str, token: str) -> str:
     """ Create the content of the email to be sent to the user.
 
-    @param username: the name of the user
-    @param token: the token to be used to activate the account
-    @return: the content of the email
+    :param username: the name of the user
+    :param token: the token to be used to activate the account
+    :return: the content of the email
     """
     with open(path.join(TEMPLATES_PATH, 'reset_password.html'), 'r') as template_data:
         template: Template = Template(template_data.read())

ptmd/lib/email/utils.py

@@ -9,7 +9,7 @@
 def get_config() -> str:
     """ Get the configuration file for the Google Drive API.
 
-    @return: the path to the credentials file
+    :return: the path to the credentials file
     """
     with open(GOOGLE_DRIVE_SETTINGS_FILE_PATH, 'r') as settings_file:
         settings = safe_load(settings_file)