julien-python-toolkit 0.2.2__tar.gz → 0.2.5__tar.gz

julien_python_toolkit-0.2.5/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: julien-python-toolkit
+Version: 0.2.5
+Summary: Important code that I reuse through multiple projects. Please see license for allowed use.
+Home-page: https://github.com/JulienPython/JulienPythonToolkit-V001
+Author: Julien Python
+Author-email: python.julien@hotmail.com
+License: Custom Non-Commercial License
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: certifi==2024.8.30
+Requires-Dist: google-api-core==2.19.1
+Requires-Dist: google-api-python-client==2.139.0
+Requires-Dist: google-auth==2.32.0
+Requires-Dist: google-auth-httplib2==0.2.0
+Requires-Dist: google-auth-oauthlib==1.2.1
+Requires-Dist: googleapis-common-protos==1.63.2
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# JulienPythonToolkit-V001
+
+Important code that I reuse through multiple projects. Please see license for allowed use.
+
+## 🚀 Release & Publishing Guide (GitHub → PyPI)
+
+This repository uses GitHub Actions to automatically build and publish the package to PyPI when a new version tag is created.
+
+---
+
+### How GitHub Actions Works in This Repository
+
+The publishing workflow is defined in:
+
+.github/workflows/publish.yml
+
+The workflow is triggered **only when a new tag starting with `v` is pushed**.
+
+Trigger condition:
+
+on:
+  push:
+    tags:
+      - "v*"
+
+This means:
+
+- Normal commits to `main` do NOT publish.
+- Editing a GitHub release does NOT publish.
+- Reusing an existing tag does NOT publish.
+- Only a brand-new tag push triggers the workflow.
+
+When triggered, the workflow:
+
+1. Verifies the tag points to a commit on `main`
+2. Builds the package using `python -m build`
+3. Publishes to PyPI using Trusted Publishing
+
+---
+
+### PyPI Trusted Publishing
+
+This project uses **PyPI Trusted Publishing (OIDC)**.
+
+This means:
+
+- No PyPI API token is stored in GitHub secrets.
+- GitHub securely authenticates directly with PyPI.
+- The workflow requires `id-token: write` permission.
+
+If Trusted Publishing is not configured in the PyPI project settings, publishing will fail.
+
+---
+
+### Correct Release Workflow
+
+Follow this process exactly.
+
+1. Create a feature branch  
+2. Make your changes  
+3. Bump the version in `setup.py`  
+   Example:  
+   version='0.2.4'
+
+4. Commit and push the branch  
+5. Merge the branch into `main`  
+6. On GitHub:
+   - Go to **Releases**
+   - Click **Draft a new release**
+   - Create a new tag (e.g. `v0.2.4`)
+   - Target branch must be `main`
+   - Publish release
+
+Creating the release creates and pushes the tag.
+
+This triggers the GitHub Action.
+
+To monitor progress:
+
+Repository → Actions
+
+Green check = success  
+Red X = failure  
+
+After success, the new version appears on PyPI.
+
+---
+
+### Important Rules
+
+1. The tag must be new  
+   Reusing the same tag will NOT trigger the workflow again.
+
+2. The package version must be new  
+   PyPI does not allow re-uploading the same version number, even if the previous upload failed.
+
+3. The version inside the package must match the tag  
+   Tag: v0.2.4  
+   setup.py version: 0.2.4  
+
+4. Always bump the version before merging to `main`.
+
+5. Always tag after the change is merged to `main`.  
+   Do not tag on feature branches.
+
+6. Test the build locally before releasing:
+
+   python -m pip install build  
+   python -m build  
+
+   If it fails locally, CI will fail.
+
+---
+
+### If Publishing Does Not Trigger
+
+Check:
+
+- Is the workflow file merged into `main`?
+- Does the tag start with `v`?
+- Is it a new tag?
+- Does the tag target `main`?
+- Is Trusted Publishing configured in PyPI?
+
+---
+
+### Release Summary
+
+Branch → Implement changes → Bump version → Merge to main → Create GitHub release (new tag) → Workflow runs → Check Actions → Version appears on PyPI.
+
+This ensures secure, reproducible, and clean releases.

julien_python_toolkit-0.2.5/README.md

@@ -0,0 +1,131 @@
+# JulienPythonToolkit-V001
+
+Important code that I reuse through multiple projects. Please see license for allowed use.
+
+## 🚀 Release & Publishing Guide (GitHub → PyPI)
+
+This repository uses GitHub Actions to automatically build and publish the package to PyPI when a new version tag is created.
+
+---
+
+### How GitHub Actions Works in This Repository
+
+The publishing workflow is defined in:
+
+.github/workflows/publish.yml
+
+The workflow is triggered **only when a new tag starting with `v` is pushed**.
+
+Trigger condition:
+
+on:
+  push:
+    tags:
+      - "v*"
+
+This means:
+
+- Normal commits to `main` do NOT publish.
+- Editing a GitHub release does NOT publish.
+- Reusing an existing tag does NOT publish.
+- Only a brand-new tag push triggers the workflow.
+
+When triggered, the workflow:
+
+1. Verifies the tag points to a commit on `main`
+2. Builds the package using `python -m build`
+3. Publishes to PyPI using Trusted Publishing
+
+---
+
+### PyPI Trusted Publishing
+
+This project uses **PyPI Trusted Publishing (OIDC)**.
+
+This means:
+
+- No PyPI API token is stored in GitHub secrets.
+- GitHub securely authenticates directly with PyPI.
+- The workflow requires `id-token: write` permission.
+
+If Trusted Publishing is not configured in the PyPI project settings, publishing will fail.
+
+---
+
+### Correct Release Workflow
+
+Follow this process exactly.
+
+1. Create a feature branch  
+2. Make your changes  
+3. Bump the version in `setup.py`  
+   Example:  
+   version='0.2.4'
+
+4. Commit and push the branch  
+5. Merge the branch into `main`  
+6. On GitHub:
+   - Go to **Releases**
+   - Click **Draft a new release**
+   - Create a new tag (e.g. `v0.2.4`)
+   - Target branch must be `main`
+   - Publish release
+
+Creating the release creates and pushes the tag.
+
+This triggers the GitHub Action.
+
+To monitor progress:
+
+Repository → Actions
+
+Green check = success  
+Red X = failure  
+
+After success, the new version appears on PyPI.
+
+---
+
+### Important Rules
+
+1. The tag must be new  
+   Reusing the same tag will NOT trigger the workflow again.
+
+2. The package version must be new  
+   PyPI does not allow re-uploading the same version number, even if the previous upload failed.
+
+3. The version inside the package must match the tag  
+   Tag: v0.2.4  
+   setup.py version: 0.2.4  
+
+4. Always bump the version before merging to `main`.
+
+5. Always tag after the change is merged to `main`.  
+   Do not tag on feature branches.
+
+6. Test the build locally before releasing:
+
+   python -m pip install build  
+   python -m build  
+
+   If it fails locally, CI will fail.
+
+---
+
+### If Publishing Does Not Trigger
+
+Check:
+
+- Is the workflow file merged into `main`?
+- Does the tag start with `v`?
+- Is it a new tag?
+- Does the tag target `main`?
+- Is Trusted Publishing configured in PyPI?
+
+---
+
+### Release Summary
+
+Branch → Implement changes → Bump version → Merge to main → Create GitHub release (new tag) → Workflow runs → Check Actions → Version appears on PyPI.
+
+This ensures secure, reproducible, and clean releases.

{julien_python_toolkit-0.2.2 → julien_python_toolkit-0.2.5}/setup.py

@@ -5,16 +5,21 @@ from pathlib import Path
 this_directory = Path(__file__).parent
 long_description = (this_directory / "README.md").read_text()
 
-# Load requirements from a file
-with open('requirements.txt') as f:
-    required = f.read().splitlines()
-
 setup(
     name='julien-python-toolkit',
-    version='0.2.2',
-    packages=find_packages(),
+    version='0.2.5',
+    package_dir={"": "src"},
+    packages=find_packages(where="src"),
     license='Custom Non-Commercial License',  # Reference your custom license
-    install_requires=required,  # Use the list from requirements.txt
+    install_requires=[
+        "certifi==2024.8.30",
+        "google-api-core==2.19.1",
+        "google-api-python-client==2.139.0",
+        "google-auth==2.32.0",
+        "google-auth-httplib2==0.2.0",
+        "google-auth-oauthlib==1.2.1",
+        "googleapis-common-protos==1.63.2",
+    ],
     description='Important code that I reuse through multiple projects. Please see license for allowed use.',
     long_description=long_description,  # Include long description here
     long_description_content_type='text/markdown',  # Set to 'text/markdown' for Markdown files

julien_python_toolkit-0.2.5/src/julien_python_toolkit/email_logger.py

@@ -0,0 +1,150 @@
+# This file is part of the "your-package-name" project.
+# It is licensed under the "Custom Non-Commercial License".
+# You may not use this file for commercial purposes without
+# explicit permission from the author.
+
+
+import datetime
+import time
+from typing import Protocol
+
+
+class _SupportsEmailSend(Protocol):
+    def send_emails(self, subject: str, body: str) -> None:
+        """Send an email payload to one or many recipients.
+
+        Args:
+            subject: Subject line used for the outgoing email.
+            body: Message body that should be sent.
+        """
+
+
+class EmailLogger:
+    """Collect log lines and send them by email in one batch."""
+
+    def __init__(
+        self,
+        email_sender: _SupportsEmailSend,
+        logger_name: str,
+        subject: str,
+        timestamp: bool = True,
+    ) -> None:
+        """Create a logger that stores messages until ``send`` is called.
+
+        Args:
+            email_sender: Object that can send emails.
+            logger_name: Name to show inside each formatted log line.
+            subject: Subject line to use when sending buffered logs.
+            timestamp: If ``True``, prepend timestamps to buffered log lines.
+        """
+
+        self.email_sender = email_sender
+        self.logger_name = logger_name
+        self.subject = subject
+        self.timestamp = timestamp
+        self.buffer: list[str] = []
+
+    def critical(self, message: str) -> None:
+        """Add a CRITICAL log message to the email buffer.
+
+        Args:
+            message: Log message text to store.
+        """
+
+        self._log_message(message, "CRITICAL")
+
+    def error(self, message: str) -> None:
+        """Add an ERROR log message to the email buffer.
+
+        Args:
+            message: Log message text to store.
+        """
+
+        self._log_message(message, "ERROR")
+
+    def warning(self, message: str) -> None:
+        """Add a WARNING log message to the email buffer.
+
+        Args:
+            message: Log message text to store.
+        """
+
+        self._log_message(message, "WARNING")
+
+    def info(self, message: str) -> None:
+        """Add an INFO log message to the email buffer.
+
+        Args:
+            message: Log message text to store.
+        """
+
+        self._log_message(message, "INFO")
+
+    def debug(self, message: str) -> None:
+        """Add a DEBUG log message to the email buffer.
+
+        Args:
+            message: Log message text to store.
+        """
+
+        self._log_message(message, "DEBUG")
+
+    def _log_message(self, message: str, log_level: str = "INFO") -> None:
+        """Format one message and append it to the internal buffer."""
+
+        formatted_message = ""
+
+        if self.timestamp:
+            formatted_message += f"{datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')} - "
+
+        formatted_message += f"{log_level} - {self.logger_name} - {message}"
+
+        self.buffer.append(formatted_message)
+
+    def send(self) -> None:
+        """Send all buffered log lines as one email and clear the buffer.
+
+        This method does nothing when the buffer is empty.
+        """
+
+        if self.buffer:
+            log_message = "\n".join(self.buffer)
+            self.email_sender.send_emails(self.subject, log_message)
+            self.buffer = []
+
+
+class TimedEmailLogger(EmailLogger):
+    """Email logger that auto-sends buffered logs on a time interval."""
+
+    def __init__(
+        self,
+        email_sender: _SupportsEmailSend,
+        logger_name: str,
+        subject: str,
+        timestamp: bool = True,
+        interval: int = 60,
+    ) -> None:
+        """Create a timed logger with an interval in seconds.
+
+        Args:
+            email_sender: Object that can send emails.
+            logger_name: Name to show inside each formatted log line.
+            subject: Subject line to use when sending buffered logs.
+            timestamp: If ``True``, prepend timestamps to buffered log lines.
+            interval: Number of seconds to wait between automatic sends.
+        """
+
+        super().__init__(email_sender, logger_name, subject, timestamp=timestamp)
+        self.interval = interval
+        self.last_email_time = time.time()
+
+    def _log_message(self, message: str, log_level: str = "INFO") -> None:
+        """Append a message and send if the interval has elapsed."""
+
+        super()._log_message(message, log_level)
+
+        current_time = time.time()
+
+        if current_time - self.last_email_time >= self.interval:
+            self.send()
+            self.last_email_time = current_time

{julien_python_toolkit-0.2.2 → julien_python_toolkit-0.2.5/src}/julien_python_toolkit/email_sender.py

@@ -4,12 +4,13 @@
 # explicit permission from the author.
 
 
-import ssl
 import smtplib
+import socket
+import ssl
 import time
 from email.message import EmailMessage
+
 import certifi
-import socket
 
 from . import log_utilities
 
@@ -22,19 +23,38 @@ from . import log_utilities
 
 
 # Setup Logger
-logger = log_utilities.Logger("EmailGroup", "email_group.log", stream_log_level = log_utilities.INFO, file_log_level = log_utilities.DEBUG)
+logger = log_utilities.Logger(
+    "EmailGroup",
+    "email_group.log",
+    stream_log_level=log_utilities.INFO,
+    file_log_level=log_utilities.DEBUG,
+)
+
+
+class EmailSender:
+    """Send emails to a configured list of recipients."""
 
-class EmailSender():
+    def __init__(self, sender_email: str, sender_password: str, receiver_emails: list[str]) -> None:
+        """Create SMTP client and connect immediately.
 
-    def __init__(self, sender_email, sender_password, receiver_emails):
+        Args:
+            sender_email: Email address used to send emails.
+            sender_password: App password used to authenticate with SMTP.
+            receiver_emails: List of destination email addresses.
+        """
 
         self._sender_email = sender_email
         self._sender_password = sender_password
         self._receiver_emails = receiver_emails
-        self._smtp = None
-        self._connect_and_login()  # Establish connection and login
+        self._smtp: smtplib.SMTP_SSL | None = None
 
-    def __del__(self):
+        self._connect_and_login()
+
+    def __del__(self) -> None:
+        """Close SMTP connection when object is destroyed.
+
+        This method is best-effort and suppresses expected shutdown errors.
+        """
 
         if self._smtp and self._smtp.sock is not None:
             try:
@@ -42,72 +62,79 @@ class EmailSender():
                 logger.info("SMTP connection closed.")
             except smtplib.SMTPServerDisconnected:
                 logger.info("SMTP connection was already closed.")
-            except Exception as e:
-                logger.error(f"Error closing SMTP connection: {e}")
+            except Exception as error:
+                logger.error(f"Error closing SMTP connection: {error}")
 
-    def _connect_and_login_with_retry(self):
+    def _connect_and_login_with_retry(self) -> None:
+        """Retry SMTP login for common transient network failures."""
 
         retries = 0
 
         while retries < 8:
-
             try:
                 self._connect_and_login()
-            
             except Exception as error:
-
                 logger.warn(f"Error connecting and logging in: {error.__class__.__name__}({error}).")
 
-                if isinstance(error, socket.timeout) or isinstance(error, socket.gaierror) or isinstance(error, ssl.SSLError):
-
-                    logger.warn(f"Function '{self._connect_and_login.__name__}' timed out. Retrying. Retry count: {retries + 1}/8. Curent delay: {2 ** (retries + 1)} seconds.")
+                if (
+                    isinstance(error, socket.timeout)
+                    or isinstance(error, socket.gaierror)
+                    or isinstance(error, ssl.SSLError)
+                ):
+                    logger.warn(
+                        f"Function '{self._connect_and_login.__name__}' timed out. "
+                        f"Retrying. Retry count: {retries + 1}/8. Curent delay: {2 ** (retries + 1)} seconds."
+                    )
 
                     retries += 1
-                    delay = 2 ** retries
+                    delay = 2**retries
                     time.sleep(delay)
-
                 else:
                     raise error from error
 
             raise TimeoutError("Exceeded maximum retries.")
 
-    def _connect_and_login(self):
+    def _connect_and_login(self) -> None:
+        """Connect to Gmail SMTP over SSL and authenticate."""
 
         try:
-
             context = ssl.create_default_context()
             context.load_verify_locations(certifi.where())
+
             self._smtp = smtplib.SMTP_SSL("smtp.gmail.com", 465, context=context)
             self._smtp.login(self._sender_email, self._sender_password)
-            logger.info("Connected and logged in to SMTP server.")
 
-        except Exception as e:
-
-            logger.error(f"Failed to connect and login: {e}")
-            raise e
-
-    def _reconnect_if_needed(self):
+            logger.info("Connected and logged in to SMTP server.")
+        except Exception as error:
+            logger.error(f"Failed to connect and login: {error}")
+            raise error
 
-        # Reconnect to the SMTP server if the connection is lost.
+    def _reconnect_if_needed(self) -> None:
+        """Reconnect to SMTP server if current connection is not healthy."""
 
         try:
+            status = self._smtp.noop() if self._smtp else None
 
-            status = self._smtp.noop()
-
-            if status[0] != 250:
+            if not status or status[0] != 250:
                 raise smtplib.SMTPException("SMTP connection is not healthy")
 
         except (smtplib.SMTPException, AttributeError):
-
             logger.warning("SMTP connection lost, reconnecting...")
             self._connect_and_login()
-    
-    def send_emails(self, subject, body):
+
+    def send_emails(self, subject: str, body: str) -> None:
+        """Send one message to every configured receiver.
+
+        Args:
+            subject: Subject line for the outgoing message.
+            body: Body text for the outgoing message.
+        """
 
         for receiver_email in self._receiver_emails:
             self._send_email(receiver_email, subject, body)
 
-    def _send_email(self, receiver_email, subject, body):
+    def _send_email(self, receiver_email: str, subject: str, body: str) -> None:
+        """Send one email to one recipient."""
 
         em = EmailMessage()
         em["From"] = self._sender_email
@@ -115,12 +142,16 @@ class EmailSender():
         em["Subject"] = subject
         em.set_content(body)
 
-        self._reconnect_if_needed() # Ensure connection is active before sending
+        self._reconnect_if_needed()
 
         try:
+            if self._smtp is None:
+                raise smtplib.SMTPException("SMTP connection is not initialized")
+
             start_time = time.time()
             self._smtp.send_message(em)
             seconds_elapsed = time.time() - start_time
+
             logger.info(f"Sent email to '{receiver_email}' in {seconds_elapsed:.2f} seconds.")
-        except Exception as e:
-            logger.error(f"Failed to send email to '{receiver_email}': {e}")  
+        except Exception as error:
+            logger.error(f"Failed to send email to '{receiver_email}': {error}")

julien_python_toolkit-0.2.5/src/julien_python_toolkit/file_utilities.py

@@ -0,0 +1,35 @@
+# This file is part of the "your-package-name" project.
+# It is licensed under the "Custom Non-Commercial License".
+# You may not use this file for commercial purposes without
+# explicit permission from the author.
+
+
+import os
+
+
+def path_to_this_file(file: str) -> str:
+    """Return the absolute parent directory path for a file path.
+
+    Args:
+        file: File path that should be converted to an absolute directory path.
+
+    Returns:
+        The absolute directory path that contains ``file``.
+    """
+
+    absolute_file_path = os.path.abspath(file)
+
+    return os.path.dirname(absolute_file_path)
+
+
+def join(*args: str) -> str:
+    """Join path parts into a single normalized path string.
+
+    Args:
+        *args: One or many path segments to join.
+
+    Returns:
+        A single path string built from all provided segments.
+    """
+
+    return os.path.join(*args)