django-email-sender 1.0.0__tar.gz

django_email_sender-1.0.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Egbie Uku
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_email_sender-1.0.0/MANIFEST.in

@@ -0,0 +1,12 @@
+# Include the README files
+include README.md
+include usage.md
+
+# Include the email templates folder
+recursive-include email_templates *
+
+# Include all Python files
+recursive-include emailsender *.py
+
+# Include any other necessary files (e.g., LICENSE, etc.)
+include LICENSE

django_email_sender-1.0.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: django-email-sender
+Version: 1.0.0
+Summary: A chainable Django email sender utility.
+Home-page: https://github.com/EgbieAndersonUku1/django-email-sender
+Author: Egbie Uku
+Author-email: egbieuku@hotmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 5.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: Django<6.0,>=3.2
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 📧 Django Email Sender Utility
+
+A clean, reusable, lightweight and chainable utility class for sending emails in Django using templates. It supports both HTML and plain text templates, context injection, and flexible usage — either directly, via subclassing, or abstracted into functions.
+
+
+🧠 Why Use This?
+
+While Django already provides a way to send emails, it can become verbose and repetitive. EmailSender abstracts the boilerplate and lets you send templated emails fluently.
+
+
+## ✨ Features
+
+- Chainable API (`.to()`, `.from_address()`, etc.)
+- Supports HTML and plain text templates
+- Uses Django's template system for dynamic content
+- Easy to integrate and override
+- Encourages clean code and reusability
+- Supports subclassing or functional abstractions
+
+---
+
+
+---
+
+🛠 Available Methods
+
+Method	Description
+```
+
+ - create()	                # Class factory method to instantiate the EmailSender.
+ - from_address(email)	    # Sets the sender’s email address.
+ - to(recipients)	        # Accepts a string or list of recipient email addresses.
+ - with_subject(subject)	# Sets the email subject.
+ - with_context(context)	# Context dictionary used in the templates.
+ - with_text_template(path)	# Path to the plain text email template.
+ - with_html_template(path)	# Path to the HTML email template.
+ - with_headers(headers)	# Optional custom headers as a dictionary.
+ - send()	                # Sends the email. Returns the number of successfully delivered messages.
+```
+
+
+🚨 Error Handling
+
+```
+ - Raises ValueError if required fields are missing.
+ - Raises TypeError if headers are not provided as a dictionary.
+
+```
+
+## 🚀 Installation
+
+This is a standalone utility. Copy the file into your Django project, or install it as a package using PyPI.
+
+---
+
+## 🧩 Requirements
+
+- Python 3.8+
+- Django >= 3.2
+
+---
+
+## 🧪 Basic Usage
+
+Here's a simple example of how to send an email using `EmailSender`:
+
+```python
+from email_sender import EmailSender
+
+EmailSender.create()\
+    .from_address("no-reply@example.com")\
+    .to(["recipient@example.com"])\  
+    .with_subject("Welcome!")\
+    .with_context({"username": "John"})\
+    .with_text_template("welcome.txt", folder_name="emails")\
+    .with_html_template("welcome.html", folder_name="emails")\
+    .send()
+```
+
+### Explanation:
+
+- `.from_address("no-reply@example.com")`: Specifies the sender's email address.
+- `.to(["recipient@example.com"])`: Specifies the recipient's email address.
+- `.with_subject("Welcome!")`: The subject of the email.
+- `.with_context({"username": "John"})`: Context for the email templates, allowing dynamic insertion of values (e.g., the recipient's name).
+- `.with_text_template("welcome.txt", folder_name="emails")`: The path to the text-based email template. Here, we specify the folder name (`emails`) where the template is stored. If no folder name is provided, it defaults to `email_templates/`.
+- `.with_html_template("welcome.html", folder_name="emails")`: The path to the HTML-based email template. Similarly, you can specify the folder name (`emails`) for this template.
+- `.send()`: Sends the email.
+
+---
+
+## 🧱 Subclassing
+
+You can also subclass the `EmailSender` class to create more specific types of emails.
+
+### Example: Password Reset Email
+
+```python
+class PasswordResetEmail(EmailSender):
+    def __init__(self, user):
+        super().__init__()
+        self.user = user
+
+    def build(self):
+        return self\
+            .from_address("no-reply@example.com")\
+            .to([self.user.email])\
+            .with_subject("Reset Your Password")\
+            .with_context({"username": self.user.username, "reset_link": generate_reset_link(self.user)})\
+            .with_text_template("reset_password.txt", folder_name="emails")\
+            .with_html_template("reset_password.html", folder_name="emails")
+```
+
+### Usage:
+
+```python
+PasswordResetEmail(user).build().send()
+```
+
+Here, the `PasswordResetEmail` class uses `reset_password.txt` and `reset_password.html` templates from the `emails` folder.
+
+---
+
+## 🛠️ Function-Based Abstractions
+
+For a functional approach, you can also wrap `EmailSender` in specific functions to handle common email use cases.
+
+### Example: Sending a Verification Email
+
+```python
+
+def send_verification_email(user):
+    html_verification_path = "verification/verification.html"
+    text_verification_path = "verification/verification.txt"
+    subject = "Verify Your Email"
+    from_email = "no-reply@example.com"
+
+    return EmailSender.create()\
+        .from_address(from_email)\
+        .to([user.email])\
+        .with_subject(subject)\
+        .with_context({
+            "username": user.username,
+            "verification_link": generate_verification_link(user)
+        })\
+        .with_text_template(text_verification_path, folder_name="emails")\
+        .with_html_template(html_verification_path, folder_name="emails")\
+        .send()
+```
+
+### Example: Sending a Registration Email
+
+```python
+def send_registration_email(user):
+    html_registration_path = "registration/registration.html"
+    text_registration_path = "registration/registration.txt"
+    
+    subject = "Welcome to the Platform!"
+    from_email = "no-reply@example.com"
+
+    return EmailSender.create()\
+        .from_address(from_email)\
+        .to([user.email])\
+        .with_subject(subject)\
+        .with_context({"username": user.username})\
+        .with_text_template(text_registration_path, folder_name="emails")\
+        .with_html_template(html_registration_path, folder_name="emails")\
+        .send()
+```
+
+### Advantages of this Approach:
+
+- **Keeps your logic functional and simple**: It's straightforward to use and easy to test.
+- **Keeps your email templates modular and easy to override**: Templates are organized in subfolders (e.g., `registration`, `verification`), making them easier to manage.
+- **Clean and maintainable codebase**: You don’t have to subclass `EmailSender` each time, reducing complexity.
+
+---
+
+
+---
+
+## 📁 Templates
+
+Templates must reside inside a dedicated `email_templates/` directory, which should exist inside your Django template directory.
+
+This folder can contain your own structure to help organise different types of emails. For example:
+
+```
+Example
+
+project/
+├── templates/
+│   └── email_templates/
+│       └── registration/
+│           ├── registration.html
+│           └── registration.txt
+```
+
+When calling `with_html_template()` or `with_text_template()`, you can provide the subfolder and filename like so:
+
+```python
+EmailSender.create()
+    .with_html_template("registration.html", folder_name="registration")
+    .with_text_template("registration.txt", folder_name="registration")
+```
+
+You **must** have both an `.html` and `.txt` version of the email template. These are required for rich content and email client compatibility.
+
+---
+
+
+## 💡 Tips
+
+- You can subclass `EmailSender` for different email types or simply wrap it in functions.
+- Organise your templates by email type (`registration/`, `verification/`, etc.)
+- Subject and context are fully customisable.
+
+---
+

django_email_sender-1.0.0/README.md

@@ -0,0 +1,219 @@
+# 📧 Django Email Sender Utility
+
+A clean, reusable, lightweight and chainable utility class for sending emails in Django using templates. It supports both HTML and plain text templates, context injection, and flexible usage — either directly, via subclassing, or abstracted into functions.
+
+
+🧠 Why Use This?
+
+While Django already provides a way to send emails, it can become verbose and repetitive. EmailSender abstracts the boilerplate and lets you send templated emails fluently.
+
+
+## ✨ Features
+
+- Chainable API (`.to()`, `.from_address()`, etc.)
+- Supports HTML and plain text templates
+- Uses Django's template system for dynamic content
+- Easy to integrate and override
+- Encourages clean code and reusability
+- Supports subclassing or functional abstractions
+
+---
+
+
+---
+
+🛠 Available Methods
+
+Method	Description
+```
+
+ - create()	                # Class factory method to instantiate the EmailSender.
+ - from_address(email)	    # Sets the sender’s email address.
+ - to(recipients)	        # Accepts a string or list of recipient email addresses.
+ - with_subject(subject)	# Sets the email subject.
+ - with_context(context)	# Context dictionary used in the templates.
+ - with_text_template(path)	# Path to the plain text email template.
+ - with_html_template(path)	# Path to the HTML email template.
+ - with_headers(headers)	# Optional custom headers as a dictionary.
+ - send()	                # Sends the email. Returns the number of successfully delivered messages.
+```
+
+
+🚨 Error Handling
+
+```
+ - Raises ValueError if required fields are missing.
+ - Raises TypeError if headers are not provided as a dictionary.
+
+```
+
+## 🚀 Installation
+
+This is a standalone utility. Copy the file into your Django project, or install it as a package using PyPI.
+
+---
+
+## 🧩 Requirements
+
+- Python 3.8+
+- Django >= 3.2
+
+---
+
+## 🧪 Basic Usage
+
+Here's a simple example of how to send an email using `EmailSender`:
+
+```python
+from email_sender import EmailSender
+
+EmailSender.create()\
+    .from_address("no-reply@example.com")\
+    .to(["recipient@example.com"])\  
+    .with_subject("Welcome!")\
+    .with_context({"username": "John"})\
+    .with_text_template("welcome.txt", folder_name="emails")\
+    .with_html_template("welcome.html", folder_name="emails")\
+    .send()
+```
+
+### Explanation:
+
+- `.from_address("no-reply@example.com")`: Specifies the sender's email address.
+- `.to(["recipient@example.com"])`: Specifies the recipient's email address.
+- `.with_subject("Welcome!")`: The subject of the email.
+- `.with_context({"username": "John"})`: Context for the email templates, allowing dynamic insertion of values (e.g., the recipient's name).
+- `.with_text_template("welcome.txt", folder_name="emails")`: The path to the text-based email template. Here, we specify the folder name (`emails`) where the template is stored. If no folder name is provided, it defaults to `email_templates/`.
+- `.with_html_template("welcome.html", folder_name="emails")`: The path to the HTML-based email template. Similarly, you can specify the folder name (`emails`) for this template.
+- `.send()`: Sends the email.
+
+---
+
+## 🧱 Subclassing
+
+You can also subclass the `EmailSender` class to create more specific types of emails.
+
+### Example: Password Reset Email
+
+```python
+class PasswordResetEmail(EmailSender):
+    def __init__(self, user):
+        super().__init__()
+        self.user = user
+
+    def build(self):
+        return self\
+            .from_address("no-reply@example.com")\
+            .to([self.user.email])\
+            .with_subject("Reset Your Password")\
+            .with_context({"username": self.user.username, "reset_link": generate_reset_link(self.user)})\
+            .with_text_template("reset_password.txt", folder_name="emails")\
+            .with_html_template("reset_password.html", folder_name="emails")
+```
+
+### Usage:
+
+```python
+PasswordResetEmail(user).build().send()
+```
+
+Here, the `PasswordResetEmail` class uses `reset_password.txt` and `reset_password.html` templates from the `emails` folder.
+
+---
+
+## 🛠️ Function-Based Abstractions
+
+For a functional approach, you can also wrap `EmailSender` in specific functions to handle common email use cases.
+
+### Example: Sending a Verification Email
+
+```python
+
+def send_verification_email(user):
+    html_verification_path = "verification/verification.html"
+    text_verification_path = "verification/verification.txt"
+    subject = "Verify Your Email"
+    from_email = "no-reply@example.com"
+
+    return EmailSender.create()\
+        .from_address(from_email)\
+        .to([user.email])\
+        .with_subject(subject)\
+        .with_context({
+            "username": user.username,
+            "verification_link": generate_verification_link(user)
+        })\
+        .with_text_template(text_verification_path, folder_name="emails")\
+        .with_html_template(html_verification_path, folder_name="emails")\
+        .send()
+```
+
+### Example: Sending a Registration Email
+
+```python
+def send_registration_email(user):
+    html_registration_path = "registration/registration.html"
+    text_registration_path = "registration/registration.txt"
+    
+    subject = "Welcome to the Platform!"
+    from_email = "no-reply@example.com"
+
+    return EmailSender.create()\
+        .from_address(from_email)\
+        .to([user.email])\
+        .with_subject(subject)\
+        .with_context({"username": user.username})\
+        .with_text_template(text_registration_path, folder_name="emails")\
+        .with_html_template(html_registration_path, folder_name="emails")\
+        .send()
+```
+
+### Advantages of this Approach:
+
+- **Keeps your logic functional and simple**: It's straightforward to use and easy to test.
+- **Keeps your email templates modular and easy to override**: Templates are organized in subfolders (e.g., `registration`, `verification`), making them easier to manage.
+- **Clean and maintainable codebase**: You don’t have to subclass `EmailSender` each time, reducing complexity.
+
+---
+
+
+---
+
+## 📁 Templates
+
+Templates must reside inside a dedicated `email_templates/` directory, which should exist inside your Django template directory.
+
+This folder can contain your own structure to help organise different types of emails. For example:
+
+```
+Example
+
+project/
+├── templates/
+│   └── email_templates/
+│       └── registration/
+│           ├── registration.html
+│           └── registration.txt
+```
+
+When calling `with_html_template()` or `with_text_template()`, you can provide the subfolder and filename like so:
+
+```python
+EmailSender.create()
+    .with_html_template("registration.html", folder_name="registration")
+    .with_text_template("registration.txt", folder_name="registration")
+```
+
+You **must** have both an `.html` and `.txt` version of the email template. These are required for rich content and email client compatibility.
+
+---
+
+
+## 💡 Tips
+
+- You can subclass `EmailSender` for different email types or simply wrap it in functions.
+- Organise your templates by email type (`registration/`, `verification/`, etc.)
+- Subject and context are fully customisable.
+
+---
+

django_email_sender-1.0.0/django_email_sender/email_sender.py

@@ -0,0 +1,301 @@
+from typing import Optional, List, Dict, Union
+from django.core.mail import EmailMultiAlternatives
+from django.template.loader import render_to_string
+from pathlib import Path
+from os.path import join
+
+from os import getenv
+
+from django_email_sender.exceptions import EmailTemplateDirNotFound, EmailTemplateNotFound, TemplateDirNotFound, EmailSenderError
+
+
+# Build paths inside the project like this: BASE_DIR / 'subdir'.
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+
+TEMPLATES_DIR        = join(BASE_DIR, "templates")
+EMAIL_TEMPLATES_DIR  = join(TEMPLATES_DIR, "emails_templates")
+
+from os.path import exists
+
+
+class EmailSender:
+    """
+    An email sender that allows you to send emails by
+    using a chaining method. This is mostly to be used in
+    the Django eco-system.
+
+    To use it in a Django eco-system, the following settings must be configured:
+
+    settings.py:
+    EMAIL_USE_TLS = True  
+    EMAIL_HOST = 'smtp.gmail.com'  
+    EMAIL_PORT = 587  
+    EMAIL_HOST_USER = 'some@emailhere.com'  
+    EMAIL_HOST_PASSWORD = 'password'
+
+    templates:
+        - Specify paths to your email templates.
+
+    Example usages:
+        You can easily abstract the `EmailSender` class into specific methods for sending different types of emails.
+        
+        For example, to send a verification email:
+        
+        def send_verification_email(user):
+        
+            subject = "Verify Your Email"
+            from_email = "no-reply@example.com"
+
+            return EmailSender.create()\
+                .from_address(from_email)\
+                .to([user.email])\
+                .with_subject(subject)\
+                .with_context({
+                    "username": user.username, 
+                    "verification_link": generate_verification_link(user)
+                })\
+                .with_text_template(folder_name="email", template_name="verification.txt")\
+                .with_html_template(folder_name="email", template_name="verification.html")\
+                .send()
+
+        Similarly, you can create other email methods such as:
+        
+        def send_registration_email(user):
+          
+            subject    = "Welcome to the Platform!"
+            from_email = "no-reply@example.com"
+
+            return EmailSender.create()\
+                .from_address(from_email)\
+                .to([user.email])\
+                .with_subject(subject)\
+                .with_context({"username": user.username})\
+                .with_text_template(folder_name='emails', template_name='registration.html')\
+                .with_html_template(folder_name='emails', template_name='registeration.txt')\
+                .send()
+                
+        This approach allows you to abstract email sending into different functions for 
+        various use cases (e.g., registration, verification, password reset), 
+        but at the same time allows the email sender class to be a single source of truth while allowing the
+        sending logic clean, consistent, and reusable.
+    """
+
+    def __init__(self):
+        """
+        Initialize an empty email configuration.
+        """
+        self.from_email: Optional[str]    = None
+        self.to_email: List[str]          = []
+        self.subject: Optional[str]       = None
+        self.html_template: Optional[str] = None
+        self.text_template: Optional[str] = None
+        self.context: Dict                = {}
+        self.headers: Dict                = {}
+
+    @classmethod
+    def create(cls) -> "EmailSender":
+        """
+        Class factory method to initialize the EmailSender for method chaining.
+
+        Returns:
+            EmailSender: A new instance of EmailSender.
+        """
+        return cls()
+
+    def from_address(self, email: str) -> "EmailSender":
+        """
+        Set the sender's email address.
+
+        Args:
+            email (str): The sender's email address.
+
+        Returns:
+            EmailSender: The current instance for chaining.
+        """
+        self.from_email = email
+        return self
+
+    def to(self, recipients: Union[str, List[str]]) -> "EmailSender":
+        """
+        Set the recipient(s) of the email.
+
+        If a single email is provided as a string, it converts it into a list.
+        Otherwise, it assumes a list of email addresses.
+        
+        Args:
+            recipients (Union[str, List[str]]): A single email address or a list of email addresses.
+            
+
+        Returns:
+            EmailSender: The current instance for chaining.
+        """
+        self.to_email = [recipients] if isinstance(recipients, str) else recipients
+        return self
+
+    def with_subject(self, subject: str) -> "EmailSender":
+        """
+        Set the subject of the email.
+
+        Args:
+            subject (str): The subject line.
+
+        Returns:
+            EmailSender: The current instance for chaining.
+        """
+        self.subject = subject
+        return self
+
+    def with_context(self, context: Dict) -> "EmailSender":
+        """
+        Set the context dictionary for rendering templates.
+
+        Args:
+            context (Dict): Context variables for use in templates.
+
+        Returns:
+            EmailSender: The current instance for chaining.
+        """
+        self.context = context
+        return self
+
+    def with_html_template(self, template_name: str, folder_name: str = None) -> "EmailSender":
+        """
+        Set the HTML template path.
+
+        Args:
+            template_name (str): The name of the plain text template file (e.g. 'welcome.html').
+            folder_name (str, optional): The name of the subfolder inside the 'email_templates' directory
+                                        where this template is located. If None, template is assumed to
+                                        reside directly in the 'email_templates' folder.
+
+        Returns:
+            EmailSender: The current instance for chaining.
+        """
+        self.html_template = self._create_path(folder_name, template_name)
+        return self
+
+    def with_text_template(self, template_name: str, folder_name: str = None) -> "EmailSender":
+        """
+        Set the plain text template path for the email.
+
+        Args:
+            template_name (str): The name of the plain text template file (e.g. 'welcome.txt').
+            folder_name (str, optional): The name of the subfolder inside the 'email_templates' directory
+                                        where this template is located. If None, template is assumed to
+                                        reside directly in the 'email_templates' folder.
+
+        Returns:
+            EmailSender: The current instance for method chaining.
+        """
+        self.text_template = self._create_path(template_name, folder_name)
+        return self
+
+    def _does_template_path_exists(email_path):
+        """
+        Checks whether a given template path exists within the email templates directory.
+
+        This method performs the following checks:
+        - Ensures the base template directory exists (e.g., TEMPLATES_DIR).
+        - Ensures the 'email_templates' folder exists within the base directory.
+        - Confirms the specific template file exists at the given path.
+
+        Args:
+            email_path (str): The full relative path to the template file to check.
+
+        Raises:
+            TemplateDirNotFound: If the base template directory is missing.
+            EmailTemplateDirNotFound: If the 'email_templates' folder is missing.
+            TemplateNotFound: If the given email template file does not exist.
+        """
+        
+        if not exists(TEMPLATES_DIR):
+           raise TemplateDirNotFound("The template directory wasn't found")
+        if not exists(EMAIL_TEMPLATES_DIR):
+           raise EmailTemplateDirNotFound("The emails_templates folder wasn't found")
+        if not exists(email_path):
+            raise EmailTemplateNotFound("The email template wasn't found")
+    
+    def _create_path(self, template_name: str, folder_name: str = None):
+        """
+        Constructs the full path to an email template file inside the 'email_templates' directory.
+
+        Allows for an optional subfolder to help organise templates by category (e.g., registration, password_reset).
+
+        Args:
+            template_name (str): Name of the template file (e.g., 'welcome.html').
+            folder_name (str, optional): Name of the subfolder inside 'email_templates'. Defaults to None.
+
+        Returns:
+            str: The combined relative path to the desired template.
+
+        Raises:
+            ValueError: If template_name is not a string, or folder_name is not a string or None.
+        """
+
+        if folder_name != None and not isinstance(folder_name, str):
+            raise ValueError("The folder name must be a string or None")
+        if not isinstance(template_name, str):
+            raise ValueError("The template name must be a string or None")
+        
+        if folder_name is None:
+            return join(EMAIL_TEMPLATES_DIR, template_name)
+        return join(EMAIL_TEMPLATES_DIR, folder_name, template_name)
+            
+
+    def with_headers(self, headers: Optional[Dict] = None) -> "EmailSender":
+        """
+        Set custom headers for the email.
+
+        Args:
+            headers (Optional[Dict], optional): A dictionary of headers to include in the email. Default is an empty dictionary.
+
+        Raises:
+            TypeError: If headers is not a dictionary.
+
+        Returns:
+            EmailSender: The current instance for chaining.
+        """
+        if headers is None:
+            headers = {}
+        if not isinstance(headers, dict):
+            raise TypeError(f"Headers must be a dictionary, got {type(headers)} instead.")
+        self.headers = headers
+        return self
+
+    def send(self) -> int:
+        """
+        Send the email using Django's email backend.
+
+        This will render the text and HTML templates, attach the HTML alternative, and send the email.
+
+        Raises:
+            ValueError: If any required fields are missing before sending.
+            EmailSendError: Raises an EmailSendError if an error occurs while sending an email.
+
+        Returns:
+            int: The number of successfully delivered messages (typically 1 if successful).
+        """
+        if not all([self.from_email, self.to_email, self.subject, self.html_template, self.text_template]):
+            raise ValueError("All email components (from, to, subject, html, text) must be set before sending.")
+
+        self._does_template_path_exists(self.text_template)
+        self._does_template_path_exists(self.html_template)
+        
+        text_content = render_to_string(self.text_template, context=self.context)
+        html_content = render_to_string(self.html_template, context=self.context)
+
+        msg = EmailMultiAlternatives(
+            subject=self.subject,
+            body=text_content,
+            from_email=self.from_email,
+            to=self.to_email,
+            headers=self.headers or None
+        )
+
+        msg.attach_alternative(html_content, "text/html")
+        
+        try:
+            return msg.send()
+        except EmailSenderError as e:
+            raise EmailSenderError(str(e))

django_email_sender-1.0.0/django_email_sender/exceptions.py

@@ -0,0 +1,18 @@
+class EmailSenderError(Exception):
+    """Base exception for all email sender errors."""
+    pass
+
+
+class EmailTemplateDirNotFound(EmailSenderError):
+    """Raised when the email_templates directory is not found."""
+    pass
+
+
+class EmailTemplateNotFound(EmailSenderError):
+    """Raised when a specific email template file is missing."""
+    pass
+
+
+class TemplateDirNotFound(EmailSenderError):
+    """Raised when a template directory does not exist."""
+    pass

django_email_sender-1.0.0/django_email_sender.egg-info/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: django-email-sender
+Version: 1.0.0
+Summary: A chainable Django email sender utility.
+Home-page: https://github.com/EgbieAndersonUku1/django-email-sender
+Author: Egbie Uku
+Author-email: egbieuku@hotmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 5.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: Django<6.0,>=3.2
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 📧 Django Email Sender Utility
+
+A clean, reusable, lightweight and chainable utility class for sending emails in Django using templates. It supports both HTML and plain text templates, context injection, and flexible usage — either directly, via subclassing, or abstracted into functions.
+
+
+🧠 Why Use This?
+
+While Django already provides a way to send emails, it can become verbose and repetitive. EmailSender abstracts the boilerplate and lets you send templated emails fluently.
+
+
+## ✨ Features
+
+- Chainable API (`.to()`, `.from_address()`, etc.)
+- Supports HTML and plain text templates
+- Uses Django's template system for dynamic content
+- Easy to integrate and override
+- Encourages clean code and reusability
+- Supports subclassing or functional abstractions
+
+---
+
+
+---
+
+🛠 Available Methods
+
+Method	Description
+```
+
+ - create()	                # Class factory method to instantiate the EmailSender.
+ - from_address(email)	    # Sets the sender’s email address.
+ - to(recipients)	        # Accepts a string or list of recipient email addresses.
+ - with_subject(subject)	# Sets the email subject.
+ - with_context(context)	# Context dictionary used in the templates.
+ - with_text_template(path)	# Path to the plain text email template.
+ - with_html_template(path)	# Path to the HTML email template.
+ - with_headers(headers)	# Optional custom headers as a dictionary.
+ - send()	                # Sends the email. Returns the number of successfully delivered messages.
+```
+
+
+🚨 Error Handling
+
+```
+ - Raises ValueError if required fields are missing.
+ - Raises TypeError if headers are not provided as a dictionary.
+
+```
+
+## 🚀 Installation
+
+This is a standalone utility. Copy the file into your Django project, or install it as a package using PyPI.
+
+---
+
+## 🧩 Requirements
+
+- Python 3.8+
+- Django >= 3.2
+
+---
+
+## 🧪 Basic Usage
+
+Here's a simple example of how to send an email using `EmailSender`:
+
+```python
+from email_sender import EmailSender
+
+EmailSender.create()\
+    .from_address("no-reply@example.com")\
+    .to(["recipient@example.com"])\  
+    .with_subject("Welcome!")\
+    .with_context({"username": "John"})\
+    .with_text_template("welcome.txt", folder_name="emails")\
+    .with_html_template("welcome.html", folder_name="emails")\
+    .send()
+```
+
+### Explanation:
+
+- `.from_address("no-reply@example.com")`: Specifies the sender's email address.
+- `.to(["recipient@example.com"])`: Specifies the recipient's email address.
+- `.with_subject("Welcome!")`: The subject of the email.
+- `.with_context({"username": "John"})`: Context for the email templates, allowing dynamic insertion of values (e.g., the recipient's name).
+- `.with_text_template("welcome.txt", folder_name="emails")`: The path to the text-based email template. Here, we specify the folder name (`emails`) where the template is stored. If no folder name is provided, it defaults to `email_templates/`.
+- `.with_html_template("welcome.html", folder_name="emails")`: The path to the HTML-based email template. Similarly, you can specify the folder name (`emails`) for this template.
+- `.send()`: Sends the email.
+
+---
+
+## 🧱 Subclassing
+
+You can also subclass the `EmailSender` class to create more specific types of emails.
+
+### Example: Password Reset Email
+
+```python
+class PasswordResetEmail(EmailSender):
+    def __init__(self, user):
+        super().__init__()
+        self.user = user
+
+    def build(self):
+        return self\
+            .from_address("no-reply@example.com")\
+            .to([self.user.email])\
+            .with_subject("Reset Your Password")\
+            .with_context({"username": self.user.username, "reset_link": generate_reset_link(self.user)})\
+            .with_text_template("reset_password.txt", folder_name="emails")\
+            .with_html_template("reset_password.html", folder_name="emails")
+```
+
+### Usage:
+
+```python
+PasswordResetEmail(user).build().send()
+```
+
+Here, the `PasswordResetEmail` class uses `reset_password.txt` and `reset_password.html` templates from the `emails` folder.
+
+---
+
+## 🛠️ Function-Based Abstractions
+
+For a functional approach, you can also wrap `EmailSender` in specific functions to handle common email use cases.
+
+### Example: Sending a Verification Email
+
+```python
+
+def send_verification_email(user):
+    html_verification_path = "verification/verification.html"
+    text_verification_path = "verification/verification.txt"
+    subject = "Verify Your Email"
+    from_email = "no-reply@example.com"
+
+    return EmailSender.create()\
+        .from_address(from_email)\
+        .to([user.email])\
+        .with_subject(subject)\
+        .with_context({
+            "username": user.username,
+            "verification_link": generate_verification_link(user)
+        })\
+        .with_text_template(text_verification_path, folder_name="emails")\
+        .with_html_template(html_verification_path, folder_name="emails")\
+        .send()
+```
+
+### Example: Sending a Registration Email
+
+```python
+def send_registration_email(user):
+    html_registration_path = "registration/registration.html"
+    text_registration_path = "registration/registration.txt"
+    
+    subject = "Welcome to the Platform!"
+    from_email = "no-reply@example.com"
+
+    return EmailSender.create()\
+        .from_address(from_email)\
+        .to([user.email])\
+        .with_subject(subject)\
+        .with_context({"username": user.username})\
+        .with_text_template(text_registration_path, folder_name="emails")\
+        .with_html_template(html_registration_path, folder_name="emails")\
+        .send()
+```
+
+### Advantages of this Approach:
+
+- **Keeps your logic functional and simple**: It's straightforward to use and easy to test.
+- **Keeps your email templates modular and easy to override**: Templates are organized in subfolders (e.g., `registration`, `verification`), making them easier to manage.
+- **Clean and maintainable codebase**: You don’t have to subclass `EmailSender` each time, reducing complexity.
+
+---
+
+
+---
+
+## 📁 Templates
+
+Templates must reside inside a dedicated `email_templates/` directory, which should exist inside your Django template directory.
+
+This folder can contain your own structure to help organise different types of emails. For example:
+
+```
+Example
+
+project/
+├── templates/
+│   └── email_templates/
+│       └── registration/
+│           ├── registration.html
+│           └── registration.txt
+```
+
+When calling `with_html_template()` or `with_text_template()`, you can provide the subfolder and filename like so:
+
+```python
+EmailSender.create()
+    .with_html_template("registration.html", folder_name="registration")
+    .with_text_template("registration.txt", folder_name="registration")
+```
+
+You **must** have both an `.html` and `.txt` version of the email template. These are required for rich content and email client compatibility.
+
+---
+
+
+## 💡 Tips
+
+- You can subclass `EmailSender` for different email types or simply wrap it in functions.
+- Organise your templates by email type (`registration/`, `verification/`, etc.)
+- Subject and context are fully customisable.
+
+---
+

django_email_sender-1.0.0/django_email_sender.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENCE
+MANIFEST.in
+README.md
+setup.py
+django_email_sender/__init__.py
+django_email_sender/email_sender.py
+django_email_sender/exceptions.py
+django_email_sender.egg-info/PKG-INFO
+django_email_sender.egg-info/SOURCES.txt
+django_email_sender.egg-info/dependency_links.txt
+django_email_sender.egg-info/requires.txt
+django_email_sender.egg-info/top_level.txt
+tests/test_email_sender.py

django_email_sender-1.0.0/django_email_sender.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

django_email_sender-1.0.0/django_email_sender.egg-info/requires.txt

@@ -0,0 +1 @@
+Django<6.0,>=3.2

django_email_sender-1.0.0/django_email_sender.egg-info/top_level.txt

@@ -0,0 +1 @@
+django_email_sender

django_email_sender-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_email_sender-1.0.0/setup.py

@@ -0,0 +1,26 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="django-email-sender",
+    version="1.0.0",
+    packages=find_packages(),
+    install_requires=[
+        "Django>=3.2,<6.0",
+    ],
+    author="Egbie Uku",
+    author_email="egbieuku@hotmail.com",
+    description="A chainable Django email sender utility.",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/EgbieAndersonUku1/django-email-sender",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Framework :: Django",
+        "Framework :: Django :: 3.2",
+        "Framework :: Django :: 4.0",
+        "Framework :: Django :: 5.0",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires='>=3.7',
+)

django_email_sender-1.0.0/tests/test_email_sender.py

@@ -0,0 +1,23 @@
+from django.test import TestCase
+from email_sender.email_sender import EmailSender
+
+
+class TestEmailSender(TestCase):
+    def test_email_sender_creates_and_sends_email(self):
+        
+        # Example test for email sending logic
+        email_sender = EmailSender.create()\
+            .from_address("no-reply@example.com")\
+            .to(["test@example.com"])\
+            .with_subject("Test Email")\
+            .with_context({"username": "testuser"})\
+            .with_text_template("emails/test.txt")\
+            .with_html_template("emails/test.html")
+        
+        # Test if the sender was set correctly
+        self.assertEqual(email_sender.from_address, "no-reply@example.com")
+        self.assertEqual(email_sender.subject, "Test Email")
+
+        # Here, you can mock `send_mail` to ensure it gets called
+        with self.assertRaises("SomeMockException"):
+            email_sender.send()