Implement logging and additional exception handling

MANIFEST.in

@@ -1,8 +1,13 @@
 include README.md
 include LICENSE
-include setup.cfg
+include pyproject.toml
 
-recursive-include johnnyfive/config *
+include johnnyfive/config/README.md
+include johnnyfive/config/email.conf-TEMPLATE
+include johnnyfive/config/emailFooter.txt
+include johnnyfive/config/gmail_credentials.json-TEMPLATE
+include johnnyfive/config/gmail_token.json-TEMPLATE
+include johnnyfive/config/johnnyfive.conf-TEMPLATE
 recursive-include johnnyfive/images *
 
 global-exclude *.pyc *.o *.so *.DS_Store

README.md

@@ -15,7 +15,7 @@ import johnnyfive
 page = johnnyfive.ConfluencePage(space, page_title, instance=None, use_oauth=False)
 
 # Gmail API
-message = johnnyfive.GmailMessage(toaddr, subject, message_text, fromname=None fromaddr=None, interactive=False)
+message = johnnyfive.GmailMessage(toaddr, subject, message_text, fromname=None, fromaddr=None, interactive=False)
 message_list = johnnyfive.GetMessages(label=None, after=None, before=None, interactive=False)
 
 # Slack API
@@ -33,12 +33,13 @@ slack_channel = johnnyfive.SlackChannel(channel_name)
 - google-api-python-client
 - google-auth-httplib2
 - google-auth-oauthlib
+- httplib2
 - lxml
-- pyjwt
-- python-twitter
 - requests
 - slack_sdk
-- ligmos @ https://github.com/LowellObservatory/ligmos
+
+JohnnyFive parses its own INI-style configuration file and does not require
+`ligmos`.
 
 ## Installation
 
@@ -52,6 +53,8 @@ Installable either as a standalone library:
 
 Or as a dependancy for other software:
 
-- In your package's `setup.cfg` file, add:
+- In your package's `pyproject.toml` file, add:
 
-    ```install_requires = JohnnyFive @ git+https://github.com/LowellObservatory/JohnnyFive```
+    ```toml
+    dependencies = ["JohnnyFive @ git+https://github.com/LowellObservatory/JohnnyFive"]
+    ```

johnnyfive/old_email.py → ToyModels/old_email.py

@@ -1,8 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-#  This Source Code Form is subject to the terms of the Mozilla Public
-#  License, v. 2.0. If a copy of the MPL was not distributed with this
-#  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
 #
 #  Created on 25 Feb 2020
 #
@@ -19,11 +17,35 @@
 import socket
 import smtplib
 from email.message import EmailMessage
-
-
-def sendMail(message, smtploc='localhost', port=25, user=None, passw=None):
-    """
-    This assumes that 'message' is an instance of EmailMessage
+from typing import Any
+
+
+def sendMail(
+    message: EmailMessage,
+    smtploc: str = "localhost",
+    port: int | str = 25,
+    user: str | None = None,
+    passw: str | None = None,
+) -> bool:
+    """Send an email message via an unencrypted or SSL SMTP connection.
+
+    Parameters
+    ----------
+    message : EmailMessage
+        Message to send.
+    smtploc : str, optional
+        SMTP host name.
+    port : int | str, optional
+        SMTP port number.
+    user : str | None, optional
+        User name for SSL authentication.
+    passw : str | None, optional
+        Password for SSL authentication.
+
+    Returns
+    -------
+    bool
+        Whether the message was sent successfully.
     """
     # Ultimate return value to know whether we need to try again later
     success = False
@@ -77,8 +99,32 @@ def sendMail(message, smtploc='localhost', port=25, user=None, passw=None):
     return success
 
 
-def constructMail(subject, body, fromaddr, toaddr, fromname=None):
-    """
+def constructMail(
+    subject: str,
+    body: str,
+    fromaddr: str,
+    toaddr: str,
+    fromname: str | None = None,
+) -> EmailMessage:
+    """Construct a plain-text email message.
+
+    Parameters
+    ----------
+    subject : str
+        Email subject.
+    body : str
+        Plain-text message body.
+    fromaddr : str
+        Sender address.
+    toaddr : str
+        Recipient address.
+    fromname : str | None, optional
+        Sender display name.
+
+    Returns
+    -------
+    EmailMessage
+        Configured email message.
     """
     msg = EmailMessage()
     if fromname is None:

ToyModels/tweetTester.py

@@ -1,8 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-#  This Source Code Form is subject to the terms of the Mozilla Public
-#  License, v. 2.0. If a copy of the MPL was not distributed with this
-#  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
 #
 #  Created on 7 Feb 2020
 #
@@ -15,13 +13,27 @@
 
 from __future__ import division, print_function, absolute_import
 
+import configparser
+from pathlib import Path
+from typing import Mapping
+
 import twitter
 
-import ligmos
 
+def sendMessage(twit: Mapping[str, str], message: str) -> None:
+    """Post a message to Twitter using configured API credentials.
 
-def sendMessage(twit, message):
-    """
+    Parameters
+    ----------
+    twit : Mapping[str, str]
+        Twitter API credential mapping.
+    message : str
+        Message to post.
+
+    Returns
+    -------
+    None
+        The API response is printed for this prototype script.
     """
     api = twitter.Api(consumer_key=twit['apiKey'],
                       consumer_secret=twit['apiSecret'],
@@ -41,10 +53,11 @@ def sendMessage(twit, message):
 
 
 if __name__ == "__main__":
-    confFile = '../config/johnnyfive.conf'
-    conf = ligmos.utils.confparsers.rawParser(confFile)
+    conf_file = Path(__file__).parents[1] / "johnnyfive" / "config" / "johnnyfive.conf"
+    conf = configparser.ConfigParser()
+    conf.read(conf_file)
 
     # Quick and dirty for prototyping, will set up classes later
-    twit = conf['twitterSetup']
+    twit = conf["twitterSetup"]
 
     sendMessage(twit)

examples/gmail_example.py

@@ -1,13 +1,17 @@
-""" Example for using the Gmail module
-
-_extended_summary_
-"""
+"""Demonstrate the Gmail message API."""
 
 from johnnyfive import gmail as j5g
 from johnnyfive import utils
 
 
-def main(interactive=False):
+def main(interactive: bool = False) -> None:
+    """Demonstrate sending a Gmail message with an attachment.
+
+    Parameters
+    ----------
+    interactive : bool, optional
+        Whether OAuth authentication may open a browser.
+    """
     """main Main Testing Driver
    """
 

examples/slack_example.py

@@ -1,15 +1,13 @@
-""" Example for using the Slack module
-
-_extended_summary_
-"""
+"""Demonstrate the Slack channel API."""
 
 import os
 
 from johnnyfive import slack as j5s
 from johnnyfive import utils
 
 # Main Testing Driver ========================================================#
-def main():
+def main() -> None:
+    """Demonstrate sending a Slack message and uploading a file."""
     """main Main Testing Driver
     """
     slack_object = j5s.SlackChannel('bot_test')

johnnyfive/__init__.py

@@ -1,19 +1,18 @@
 # -*- coding: utf-8 -*-
 #
-#  This Source Code Form is subject to the terms of the Mozilla Public
-#  License, v. 2.0. If a copy of the MPL was not distributed with this
-#  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
 #
 #  Created on 07-Mar-2022
 #
 #  @author: tbowers
 
-"""Init File
-"""
+"""Init File"""
 
 
 # Imports for signal and log handling
 import os
+from types import TracebackType
+from typing import IO, Type
 import warnings
 
 __all__ = ["ConfluencePage", "GmailMessage", "GetMessages", "SlackChannel"]
@@ -25,9 +24,35 @@
 from .utils import *  # noqa
 
 
-def short_warning(message, category, filename, lineno, file=None, line=None):
-    """
-    Return the format for a short warning message.
+def short_warning(
+    message: Warning | str,
+    category: Type[Warning],
+    filename: str,
+    lineno: int,
+    file: IO[str] | None = None,
+    line: str | None = None,
+) -> str:
+    """Format a warning as a concise single line.
+
+    Parameters
+    ----------
+    message : Warning | str
+        Warning text or warning instance.
+    category : type[Warning]
+        Warning category.
+    filename : str
+        Source filename.
+    lineno : int
+        Source line number.
+    file : IO[str] | None, optional
+        Unused output stream accepted for the warnings hook protocol.
+    line : str | None, optional
+        Unused source line accepted for the warnings hook protocol.
+
+    Returns
+    -------
+    str
+        Formatted warning line.
     """
     return f" {category.__name__}: {message} ({os.path.split(filename)[1]}:{lineno})\n"
 

johnnyfive/classes.py

@@ -1,8 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-#  This Source Code Form is subject to the terms of the Mozilla Public
-#  License, v. 2.0. If a copy of the MPL was not distributed with this
-#  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
 #
 #  Created on 25 Feb 2020
 #
@@ -16,8 +14,19 @@
 from __future__ import division, print_function, absolute_import
 
 
-class emailSNMP(object):
-    def __init__(self):
+class emailSNMP:
+    """Store SMTP connection and message configuration.
+
+    Attributes
+    ----------
+    host : str | None
+        SMTP server host name.
+    port : int
+        SMTP server port.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an SMTP configuration with safe defaults."""
         self.host = None
         self.port = 465
         self.user = None