feat(helpers): add custom exceptions and logging

Introduced `SwgohComlinkValueError` for better exception handling and replaced generic `ValueError` instances with it across helpers.py.

Author: MarTrepodi

.github/workflows/release.yml

@@ -37,23 +37,54 @@ jobs:
           ref: ${{ github.ref_name }}
           fetch-depth: 0
 
-      - name: Action | Semantic Version Release
-        id: release
-        uses: python-semantic-release/python-semantic-release@v9.21.0
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          git_committer_name: "github-actions"
-          git_committer_email: "actions@users.noreply.github.com"
+      # Install dependencies
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install hatch
 
-      - name: Publish | Upload to GitHub Release Assets
-        uses: python-semantic-release/publish-action@v9.21.0
-        if: steps.release.outputs.released == 'true'
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          tag: ${{ steps.release.outputs.tag }}
+      # Build the package using python3 -m build
+      - name: Build the package
+        run: |
+          python3 -m pip install --upgrade setuptools wheel build uv
+          python3 -m build
+
+      # Tag the release in GitHub
+      - name: Tag the release
+        run: |
+          VERSION=$(hatch version)
+          git config user.name "$(git log -n 1 --pretty=format:%an)"
+          git config user.email "$(git log -n 1 --pretty=format:%ae)"
+          git tag -a "v$VERSION" -m "Release version $VERSION"
+          git push origin "v$VERSION"
+          uv run hatch version "$VERSION"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Update CHANGELOG.md
+      - name: Update CHANGELOG.md
+        run: |
+          python3 install git-changelog
+          git-changelog -B auto -Tio CHANGELOG.md -c angular -s build,deps,fix,feat,refactor -n semver 
+
+    # Publish the package to PyPI
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+      contents: write
 
+    environment:
+      name: pypi
+      url: https://pypi.org/project/swgoh-comlink/
+
+    steps:
       - name: Retrieve release distributions
         uses: actions/download-artifact@v4
 
-      - name: Publish | Upload package to PyPI
+      - name: Publish release distributions to PyPI
         uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc

README.md

@@ -70,6 +70,11 @@ player_name = player_data['name']
 - **_access_key_**: The "public" portion of the shared key used in HMAC request signing. Defaults to `None` which disables HMAC signing of requests. Can also be read from the ACCESS_KEY environment variable.
 - **_secret_key_**: The "private" portion of the key used in HMAC request signing. Defaults to `None` which disables HMAC signing of requests. Can also be read from the SECRET_KEY environment variable.
 
+# Logging
+
+Logging is handled by the [python logging module](https://docs.python.org/3/library/logging.html). For details on the
+logging implementation for this package, go [here](docs/logging.md).
+
 See the online [wiki](https://github.com/swgoh-utils/swgoh-comlink/wiki) for more information.
 
 ## Support

docs/logging.md

@@ -0,0 +1,51 @@
+# SwgohComlink Logging
+
+The `swgoh_comlink` package includes some basic logging functionality. By default, the package will create a logger
+instance with the name 'swgoh_comlink' and use the built-in logging functionality.
+
+The default log level is set to `DEBUG`. If you would like to use the built-in logging but at a lower logging level or
+specialized output formatting, you can create your own logging instance with the name 'swgoh_comlink' and implement the
+custom logging setting appropriate for your needs.
+
+For example:
+
+```python
+import logging
+from swgoh_comlink import SwgohComlink
+
+comlink_logger = logging.getLogger('swgoh_comlink')
+comlink_logger.setLevel(logging.CRITICAL)
+console_handler = logging.StreamHandler()
+log_format = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+console_handler.setFormatter(log_format)
+comlink_logger.addHandler(console_handler)
+
+comlink = SwgohComlink()
+```
+
+The configuration above would capture all `CRITICAL` events and higher and display them on the console terminal.
+
+If you wanted to capture events to a rotating log file, you could add a handler to the logger instance
+defined above.
+
+```python
+import logging
+from logging.handlers import RotatingFileHandler
+from swgoh_comlink import SwgohComlink
+
+comlink_logger = logging.getLogger('swgoh_comlink')
+comlink_logger.setLevel(logging.CRITICAL)
+console_handler = logging.StreamHandler()
+log_format = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+console_handler.setFormatter(log_format)
+comlink_logger.addHandler(console_handler)
+
+file_handler = RotatingFileHandler(filename="./comlink.log", encoding="utf-8", maxBytes=2500000, backupCount=5)
+file_handler.setFormatter(log_format)
+file_handler.setLevel(logging.DEBUG)
+comlink_logger.addHandler(file_handler)
+
+comlink = SwgohComlink()
+
+
+```

src/swgoh_comlink/exceptions.py

@@ -0,0 +1,22 @@
+# coding=utf-8
+"""
+Custom exceptions for logging
+"""
+
+from __future__ import annotations
+
+from .globals import get_logger
+
+logger = get_logger(__name__)
+
+
+class SwgohComlinkException(Exception):
+    """Base class for exceptions in this module."""
+
+    def __init__(self, message) -> None:
+        super().__init__(message)
+        logger.exception(f"SwgohComlinkException: {message}", exc_info=True)
+
+
+class SwgohComlinkValueError(SwgohComlinkException, ValueError):
+    ...

src/swgoh_comlink/globals.py

@@ -0,0 +1,29 @@
+# coding=utf-8
+"""
+Global entities
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+class LoggingFormatter(logging.Formatter):
+    """Custom logging formatter class"""
+
+    def format(self, record):
+        log_message_format = \
+            '{asctime} | {levelname:<9} | {name:15} | {module:<14} : {funcName:>30}() [{lineno:_>5}] | {message}'
+        formatter = logging.Formatter(log_message_format, "%Y-%m-%d %H:%M:%S", style="{")
+        return formatter.format(record)
+
+
+def get_logger(logger_name: str = __name__, log_level: str = "INFO") -> logging.Logger:
+    """Return the configured logger"""
+    logger = logging.getLogger(logger_name)
+    log_lvl = logging.getLevelName(log_level.upper())
+    logger.setLevel(log_lvl)
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(LoggingFormatter())
+    logger.addHandler(console_handler)
+    return logger