djresttoolkit 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

README.md

@@ -46,4 +46,4 @@ MIT License — See [LICENSE](LICENSE).
 
 ## 👤 Author
 
-For questions or assistance, contact **Shailesh** at [shaileshpandit141@gmail.com](mailto:shaileshpandit141@gmail.com).
+For questions or assistance, contact **Shailesh** at [shaileshpandit141@gmail.com](mailto:shaileshpandit141@gmail.com).

{djresttoolkit-0.1.0.dist-info → djresttoolkit-0.2.0.dist-info}/METADATA

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: djresttoolkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: A collection of Django and DRF utilities to simplify API development.
 Project-URL: Homepage, https://github.com/shaileshpandit141/djresttoolkit
-Project-URL: Repository, https://github.com/shaileshpandit141/djresttoolkit
+Project-URL: Documentation, https://shaileshpandit141.github.io/djresttoolkit
+Project-URL: Source, https://github.com/shaileshpandit141/djresttoolkit
 Project-URL: Issues, https://github.com/shaileshpandit141/djresttoolkit/issues
+Project-URL: License, https://github.com/shaileshpandit141/djresttoolkit/blob/main/LICENSE
 Author-email: shaileshpandit141 <shaileshpandit141@gmail.com>
 License: # MIT License
         
@@ -31,7 +33,7 @@ License: # MIT License
         OTHER DEALINGS IN THE SOFTWARE.
 License-File: LICENSE
 Keywords: api-development,django,django-authentication,django-email,django-helpers,django-mixins,django-pagination,django-rest,django-rest-framework-utilities,django-rest-utilities,django-serializers,django-shortcuts,django-utilities,djangorestframework,drf,python-package,rest-api
-Classifier: Development Status :: 1 - Planning
+Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Django
 Classifier: Framework :: Django :: 4.0
 Classifier: Intended Audience :: Developers
@@ -44,6 +46,7 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.11.7
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
@@ -98,4 +101,4 @@ MIT License — See [LICENSE](LICENSE).
 
 ## 👤 Author
 
-For questions or assistance, contact **Shailesh** at [shaileshpandit141@gmail.com](mailto:shaileshpandit141@gmail.com).
+For questions or assistance, contact **Shailesh** at [shaileshpandit141@gmail.com](mailto:shaileshpandit141@gmail.com).

djresttoolkit-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+README.md,sha256=P0hcRXIpkEZZIiyWKsvuCkOIlqPxQ4tRkdb5R_mTARQ,1464
+src/djresttoolkit/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/admin.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/apps.py,sha256=nKb5GUIEhAB3IL3lTmEXNc5XuvvaZupH-1CCuYKFrEQ,158
+src/djresttoolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/mail/__init__.py,sha256=tB9SdMlhfWQ640q4aobZ0H1c7fTWalpDL2I-onkr2VI,268
+src/djresttoolkit/mail/_email_sender.py,sha256=vvTPZzSAfX2FXHv1IY0ST8dEsq8M4wAxkihm0JbRh1Y,3136
+src/djresttoolkit/mail/_models.py,sha256=_41pH3xC0jP8SHSty2FkxvRh2_ddKk-4peT11OHcBBE,1462
+src/djresttoolkit/mail/_types.py,sha256=est1mrN80vB_4-j-2yuAr_l_7rNzO4AJlqpq74zO5ow,682
+src/djresttoolkit/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/djresttoolkit/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djresttoolkit-0.2.0.dist-info/METADATA,sha256=Xr6JLGRsN0NlwnQ_Nu0HcdBv6Sfs7RKeIdYOq4GVoL8,4374
+djresttoolkit-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+djresttoolkit-0.2.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
+djresttoolkit-0.2.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
+djresttoolkit-0.2.0.dist-info/RECORD,,

src/djresttoolkit/__init__.py

@@ -1,2 +0,0 @@
-def main() -> None:
-    print("Hello from drutils!")

src/djresttoolkit/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class DjresttoolkitConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "djresttoolkit"

src/djresttoolkit/mail/__init__.py

@@ -0,0 +1,11 @@
+from ._email_sender import EmailSender
+from ._models import EmailContent, EmailTemplate
+from ._types import EmailContentDict, EmailTemplateDict
+
+__all__ = [
+    "EmailSender",
+    "EmailContent",
+    "EmailTemplate",
+    "EmailContentDict",
+    "EmailTemplateDict",
+]

src/djresttoolkit/mail/_email_sender.py

@@ -0,0 +1,94 @@
+import logging
+from smtplib import SMTPException
+from typing import cast
+
+from django.core.exceptions import ValidationError
+from django.core.mail import EmailMultiAlternatives
+from django.template.loader import render_to_string
+from pydantic import EmailStr
+
+from ._models import EmailContent
+from ._types import EmailContentDict
+
+# Set up logger
+logger = logging.getLogger(__name__)
+
+
+class EmailSender:
+    """
+    Sends templated emails using Django's EmailMultiAlternatives.
+
+    Supports:
+    - Plain text and HTML templates
+    - Template rendering with context
+    - Optional silent failure handling via `exceptions`
+
+    Parameters
+    ----------
+    email_content : EmailContent | EmailContentDict
+        The email data, including subject, sender, templates, and context.
+
+    Methods
+    -------
+    send(to: list[EmailStr], exceptions: bool = False) -> bool
+        Sends the email to the given recipients.
+        - `exceptions=True` riase exceptions on failure and returns False if `exceptions=False`.
+
+    Example
+    -------
+    >>> from mypackage._models import EmailContent, EmailTemplate
+    >>> content = EmailContent(
+    ...     subject="Hello",
+    ...     from_email="noreply@example.com",
+    ...     context={"username": "Alice"},
+    ...     template=EmailTemplate(text="emails/welcome.txt", html="emails/welcome.html")
+    ... )
+    >>> sender = EmailSender(content)
+    >>> sender.send(to=["user@example.com"])  # --> True/False
+
+    """
+
+    def __init__(
+        self,
+        email_content: EmailContent | EmailContentDict,
+    ) -> None:
+        """Initialize email sender class."""
+        self._email_content = email_content
+
+    @property
+    def email_content(self) -> EmailContentDict:
+        """Convert pydantic mode to python dict."""
+        if isinstance(self.email_content, EmailContent):
+            return cast(EmailContentDict, self.email_content.model_dump())
+        return self.email_content
+
+    def send(
+        self,
+        to: list[EmailStr],
+        exceptions: bool = False,
+    ) -> bool:
+        """Send email to recipients."""
+        unique_recipients = list(set(to))
+        try:
+            logger.info("Starting email sending process.")
+            email = EmailMultiAlternatives(
+                subject=self.email_content["subject"],
+                body=render_to_string(
+                    self.email_content["template"]["text"],
+                    self.email_content["context"],
+                ),
+                from_email=self.email_content["from_email"],
+                to=unique_recipients,
+            )
+            email.attach_alternative(
+                content=self.email_content["template"]["html"],
+                mimetype="text/html",
+            )
+            email.send()
+            logger.info(f"Email sent successfully to: {', '.join(unique_recipients)}")
+            return True
+        except (SMTPException, ValidationError) as error:
+            logger.error(f"Error during sending email\nErrors: {error}")
+            if exceptions:
+                raise ValidationError("Error during sending email") from error
+            return False

src/djresttoolkit/mail/_models.py

@@ -0,0 +1,53 @@
+from typing import Any
+
+from pydantic import BaseModel, EmailStr, field_validator
+
+
+class EmailTemplate(BaseModel):
+    """Template for rendering email content."""
+
+    text: str  # plain text version
+    html: str  # HTML version
+
+    @field_validator("text")
+    @classmethod
+    def validate_text_template(cls, v: str) -> str:
+        if not v.endswith(".txt"):
+            raise ValueError("Text template must end with .txt")
+        return v
+
+    @field_validator("html")
+    @classmethod
+    def validate_html_template(cls, v: str) -> str:
+        if not v.endswith(".html"):
+            raise ValueError("HTML template must end with .html")
+        return v
+
+
+class EmailContent(BaseModel):
+    """
+    Represents the content of an email ready for rendering.
+
+    This model combines the key parts of an email, including:
+    - subject line
+    - sender email (from_email)
+    - rendering context for template variables
+    - associated text and/or HTML templates
+
+    Attributes
+    ----------
+    subject : str
+        The subject line of the email.
+    from_email : EmailStr | None
+        Sender's email address.
+    context : dict[str, Any] | None
+        Optional context data used to render templates (e.g., {"username": "Alice"}).
+    template : EmailTemplate
+        Templates for the email body (.txt and/or .html).
+
+    """
+
+    subject: str
+    from_email: EmailStr | None
+    context: dict[str, Any] | None = None
+    template: EmailTemplate

src/djresttoolkit/mail/_types.py

@@ -0,0 +1,28 @@
+from typing import Any, TypedDict
+
+from pydantic import EmailStr
+
+
+class EmailTemplateDict(TypedDict):
+    """Template for rendering email content."""
+
+    text: str  # plain text version
+    html: str  # HTML version    html: str  # HTML version
+
+
+class EmailContentDict(TypedDict):
+    """
+    Represents a fully configured email message.
+
+    This model combines the essential parts of an email, including:
+    - subject line
+    - from_email the sender email
+    - a rendering context for template variables
+    - associated text and/or HTML templates
+
+    """
+
+    subject: str
+    from_email: EmailStr | None
+    context: dict[str, Any] | None
+    template: EmailTemplateDict

djresttoolkit-0.1.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-README.md,sha256=Zk4_MIYW-Wr07HnFOANa3uQXNA08dPdQaNJhjcUH07w,1463
-src/djresttoolkit/__init__.py,sha256=ENteKzaWCshHx06bXsudOKG4J4PqQrCELdx4Gx6p7hU,53
-src/djresttoolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-djresttoolkit-0.1.0.dist-info/METADATA,sha256=yCgqJyTEOVrSvKHKRpLApPIMJh7vHSuBbUumuUOpG-A,4179
-djresttoolkit-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-djresttoolkit-0.1.0.dist-info/entry_points.txt,sha256=YMhfTF-7mYppO8QqqWnvR_hyMWvoYxD6XI94_ViFu3k,60
-djresttoolkit-0.1.0.dist-info/licenses/LICENSE,sha256=8-oZM3yuuTRjySMbVKX9YXYA7Y4M_KhQNBYXPFjeWUo,1074
-djresttoolkit-0.1.0.dist-info/RECORD,,