From 48c1716ddfe66d43bd171eeaf018935fe6c54426 Mon Sep 17 00:00:00 2001 From: Ese <17943860+dlpbc@users.noreply.github.com> Date: Tue, 29 Aug 2023 21:56:25 +0100 Subject: [PATCH 1/5] Updated docstring to google format. Updated two scripts from non-google style docstring to google style docstring. --- rctab/daily_routine_tasks.py | 21 ++---- rctab/routers/accounting/send_emails.py | 86 +++++++++---------------- 2 files changed, 37 insertions(+), 70 deletions(-) diff --git a/rctab/daily_routine_tasks.py b/rctab/daily_routine_tasks.py index 78ebd1c..82e2cb4 100644 --- a/rctab/daily_routine_tasks.py +++ b/rctab/daily_routine_tasks.py @@ -59,10 +59,8 @@ def __exit__( def datetime_utcnow() -> datetime: """Returns the current date and time in the UTC timezone. - Returns - ------- - datetime - current UTC date and time + Returns: + the current UTC date and time """ # This can be patched for testing more easily than datetime @@ -105,12 +103,9 @@ async def send_summary_email( Items in the jinja2 template are replaced with those in template_data. - Parameters - ---------- - recipients : List[str] - list of email addresses of recipients - since_this_datetime : Optional[datetime], optional - include information since this date and time, by default None + Args: + recipients : list of email addresses of recipients. + since_this_datetime : include information since this date and time, by default None. """ # pylint: disable=invalid-name template_name = "daily_summary.html" @@ -229,10 +224,8 @@ async def routine_tasks() -> None: async def get_timestamp_last_summary_email() -> Optional[datetime]: """Returns timestamp of the last summary email that has been sent. - Returns - ------- - datetime - timestamp of last summary email record in emails table + Returns: + The timestamp of last summary email record in emails table. """ query = ( select([emails]) diff --git a/rctab/routers/accounting/send_emails.py b/rctab/routers/accounting/send_emails.py index 6bfa7da..88c86ef 100644 --- a/rctab/routers/accounting/send_emails.py +++ b/rctab/routers/accounting/send_emails.py @@ -49,17 +49,12 @@ async def get_sub_email_recipients( ) -> List[str]: """Returns the users we should email about this subscription. - Parameters - ---------- - database : Database - a database to keep a record of a subscription and its users - subscription_id : UUID - a subscription ID + Args: + database : a database to keep a record of a subscription and its users. + subscription_id : a subscription ID. - Returns - ------- - List[str] - contains email addresses of the users that should receive the email + Returns: + A string that contains email addresses of the users that should receive the email. """ query = get_subscription_details(subscription_id, execute=False) results = await database.fetch_one(query) @@ -99,27 +94,17 @@ def send_with_sendgrid( Items in the jinja2 template are replaced with those in template_data. - Parameters - ---------- - subject : str - subject of the email - template_name : str - name of jinja2 template used to render the email - template_data : Dict[str, Any] - data passed to the template - to_list : List[str] - contains the email addresses of the recipients + Args: + subject : The subject of the email. + template_name : The name of jinja2 template used to render the email. + template_data : The data passed to the template. + to_list : A string that contains the email addresses of the recipients. - Returns - ------- - int - status code that indicates whether or not email was sent sucessfully - - Raises - ------ - MissingEmailParamsError - raises an error if the api key or the "from" email address - is missing + Returns: + The status code that indicates whether or not email was sent sucessfully + + Raises: + MissingEmailParamsError: raises an error if the api key or the "from" email address is missing """ # pylint: disable=invalid-name try: @@ -254,12 +239,10 @@ async def send_expiry_looming_emails( ) -> None: """If needed, sends emails to say that subscription is nearing its expiry date. - Parameters - ---------- - database : Database - a database to keep record of subscriptions and of sent emails - subscription_expiry_dates : List[Tuple[UUID, date, SubscriptionState]] - subscription ids and expiry dates of subscriptions nearing expiry + Args: + database: a database to keep record of subscriptions and of sent emails. + subscription_expiry_dates: a list of subscription ids and expiry dates of + subscriptions nearing expiry. """ # pylint: disable=use-dict-literal email_query = sub_time_based_emails() @@ -293,12 +276,10 @@ async def send_overbudget_emails( ) -> None: """If needed, sends emails to say that subscription is overbudget. - Parameters - ---------- - database : Database - a database to keep record of subscriptions and of sent emails - overbudget_subs : List[Tuple[UUID, float]] - subscription ids and percentage of budget used for subscriptions that exceeded their budget + Args: + database: a database to keep record of subscriptions and of sent emails. + overbudget_subs: a list of subscription ids and percentage of budget used for + subscriptions that exceeded their budget. """ # pylint: disable=use-dict-literal email_query = sub_usage_emails() @@ -328,10 +309,8 @@ async def send_overbudget_emails( def sub_time_based_emails() -> Select: """Builds a query to get the most recent time-based email for each subscription. - Returns - ------- - Select - SELECT statement for database query + Returns: + SELECT statement for database query. """ most_recent = ( select([func.max_(emails.c.id).label("max_id")]) @@ -440,10 +419,8 @@ async def check_for_subs_nearing_expiry(database: Database) -> None: async def check_for_overbudget_subs(database: Database) -> None: """Check for subscriptions that should trigger an email as they are overbudget. - Parameters - ---------- - database : Database - holds a record of the subscription, including budget information + Args: + database: a database that holds a record of the subscription, including budget information. """ overbudget_subs = [] @@ -949,12 +926,9 @@ async def get_approvals_since( def render_template(template_name: str, template_data: Dict[str, Any]) -> str: """Renders html based on provided template and data. - Parameters - ---------- - template_name : str - name of template - template_data : Dict[str, Any] - data used to render template + Args: + template_name : The name of template. + template_data : The data used to render template Returns ------- From 82c0070ccf9b7e00407458246ff0a3ef784dd3bf Mon Sep 17 00:00:00 2001 From: Ese <17943860+dlpbc@users.noreply.github.com> Date: Thu, 31 Aug 2023 12:54:31 +0100 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Joe Palmer <22678593+joseph-palmer@users.noreply.github.com> --- rctab/daily_routine_tasks.py | 10 ++++----- rctab/routers/accounting/send_emails.py | 30 ++++++++++++------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/rctab/daily_routine_tasks.py b/rctab/daily_routine_tasks.py index 82e2cb4..8cebb9e 100644 --- a/rctab/daily_routine_tasks.py +++ b/rctab/daily_routine_tasks.py @@ -60,7 +60,7 @@ def datetime_utcnow() -> datetime: """Returns the current date and time in the UTC timezone. Returns: - the current UTC date and time + The current UTC date and time. """ # This can be patched for testing more easily than datetime @@ -104,8 +104,8 @@ async def send_summary_email( Items in the jinja2 template are replaced with those in template_data. Args: - recipients : list of email addresses of recipients. - since_this_datetime : include information since this date and time, by default None. + recipients : The email addresses to send summary emails to. + since_this_datetime : Include information since this date and time, by default None. """ # pylint: disable=invalid-name template_name = "daily_summary.html" @@ -222,10 +222,10 @@ async def routine_tasks() -> None: async def get_timestamp_last_summary_email() -> Optional[datetime]: - """Returns timestamp of the last summary email that has been sent. + """Retrieve the timestamp from the emails table of the most recent summary email sent. Returns: - The timestamp of last summary email record in emails table. + The timestamp of the last summary email sent. """ query = ( select([emails]) diff --git a/rctab/routers/accounting/send_emails.py b/rctab/routers/accounting/send_emails.py index 88c86ef..8b798a0 100644 --- a/rctab/routers/accounting/send_emails.py +++ b/rctab/routers/accounting/send_emails.py @@ -50,11 +50,11 @@ async def get_sub_email_recipients( """Returns the users we should email about this subscription. Args: - database : a database to keep a record of a subscription and its users. - subscription_id : a subscription ID. + database : The database recording the subscription and its users. + subscription_id : The ID of the subscription to get user emails for. Returns: - A string that contains email addresses of the users that should receive the email. + The email addresses of the users that should receive the email. """ query = get_subscription_details(subscription_id, execute=False) results = await database.fetch_one(query) @@ -101,10 +101,10 @@ def send_with_sendgrid( to_list : A string that contains the email addresses of the recipients. Returns: - The status code that indicates whether or not email was sent sucessfully + The status code that indicates whether or not email was sent sucessfully. Raises: - MissingEmailParamsError: raises an error if the api key or the "from" email address is missing + MissingEmailParamsError: raises an error if the api key or the "from" email address is missing. """ # pylint: disable=invalid-name try: @@ -237,11 +237,11 @@ async def send_expiry_looming_emails( database: Database, subscription_expiry_dates: List[Tuple[UUID, date, SubscriptionState]], ) -> None: - """If needed, sends emails to say that subscription is nearing its expiry date. + """Send an email to notify users that a subscription is nearing its expiry date. Args: - database: a database to keep record of subscriptions and of sent emails. - subscription_expiry_dates: a list of subscription ids and expiry dates of + database: A database to keep record of subscriptions and of sent emails. + subscription_expiry_dates: A list of subscription ids and expiry dates for subscriptions nearing expiry. """ # pylint: disable=use-dict-literal @@ -274,11 +274,11 @@ async def send_overbudget_emails( database: Database, overbudget_subs: List[Tuple[UUID, float]], ) -> None: - """If needed, sends emails to say that subscription is overbudget. + """Send an email to notify users that subscription is overbudget. Args: - database: a database to keep record of subscriptions and of sent emails. - overbudget_subs: a list of subscription ids and percentage of budget used for + database: The database recording subscriptions and sent emails. + overbudget_subs: A list of subscription ids and the percentage of budget used for subscriptions that exceeded their budget. """ # pylint: disable=use-dict-literal @@ -417,10 +417,10 @@ async def check_for_subs_nearing_expiry(database: Database) -> None: async def check_for_overbudget_subs(database: Database) -> None: - """Check for subscriptions that should trigger an email as they are overbudget. + """Check for subscriptions that are overbudget and should trigger an email. Args: - database: a database that holds a record of the subscription, including budget information. + database: The database containing a record of the subscription, including budget information. """ overbudget_subs = [] @@ -924,11 +924,11 @@ async def get_approvals_since( def render_template(template_name: str, template_data: Dict[str, Any]) -> str: - """Renders html based on provided template and data. + """Renders html based on the provided template and data. Args: template_name : The name of template. - template_data : The data used to render template + template_data : The data used to render the template. Returns ------- From abc0769783198582fb5ad64334aa94d319b905f7 Mon Sep 17 00:00:00 2001 From: Ese <17943860+dlpbc@users.noreply.github.com> Date: Thu, 31 Aug 2023 13:04:10 +0100 Subject: [PATCH 3/5] Update rctab/routers/accounting/send_emails.py Co-authored-by: Joe Palmer <22678593+joseph-palmer@users.noreply.github.com> --- rctab/routers/accounting/send_emails.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rctab/routers/accounting/send_emails.py b/rctab/routers/accounting/send_emails.py index 8b798a0..f723da8 100644 --- a/rctab/routers/accounting/send_emails.py +++ b/rctab/routers/accounting/send_emails.py @@ -47,7 +47,7 @@ async def get_sub_email_recipients( database: Database, subscription_id: UUID ) -> List[str]: - """Returns the users we should email about this subscription. + """Get the email adresses of users that should be emailed about this subscription. Args: database : The database recording the subscription and its users. From dc0bed5f48621b1d896df7936f360fb9a099b048 Mon Sep 17 00:00:00 2001 From: Ese <17943860+dlpbc@users.noreply.github.com> Date: Thu, 31 Aug 2023 13:08:37 +0100 Subject: [PATCH 4/5] UPDATED rctab/routers/accounting/send_email.py --- rctab/routers/accounting/send_emails.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/rctab/routers/accounting/send_emails.py b/rctab/routers/accounting/send_emails.py index f723da8..2f9b8e9 100644 --- a/rctab/routers/accounting/send_emails.py +++ b/rctab/routers/accounting/send_emails.py @@ -930,9 +930,7 @@ def render_template(template_name: str, template_data: Dict[str, Any]) -> str: template_name : The name of template. template_data : The data used to render the template. - Returns - ------- - str + Returns: The rendered template as a string. """ env = Environment(loader=PackageLoader("rctab", "templates/emails")) From fed3ffb9623c30030e87b845709ed51f5bd69e53 Mon Sep 17 00:00:00 2001 From: Ese <17943860+dlpbc@users.noreply.github.com> Date: Thu, 31 Aug 2023 13:24:11 +0100 Subject: [PATCH 5/5] UPDATED rctab/daily_routine_task.py trimmed trailing whitespace --- rctab/daily_routine_tasks.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rctab/daily_routine_tasks.py b/rctab/daily_routine_tasks.py index 8cebb9e..3ea72d2 100644 --- a/rctab/daily_routine_tasks.py +++ b/rctab/daily_routine_tasks.py @@ -222,7 +222,7 @@ async def routine_tasks() -> None: async def get_timestamp_last_summary_email() -> Optional[datetime]: - """Retrieve the timestamp from the emails table of the most recent summary email sent. + """Retrieve the timestamp from the emails table of the most recent summary email sent. Returns: The timestamp of the last summary email sent.