blackant-sdk 1.0.2__py3-none-any.whl

calculation/impl/my_calculation.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+MyCalculation - Default calculation implementation for BlackAnt SDK.
+
+This class provides a production-ready wrapper around the simple_calc module,
+implementing the CalculationBase interface required by the BlackAnt task system.
+"""
+
+from typing import Dict, Any, Optional
+import logging
+
+from calculation.base import CalculationBase
+from calculation.impl.simple_calc import calculate
+
+
+class MyCalculation(CalculationBase):
+    """
+    Default calculation implementation using simple_calc logic.
+
+    This class implements the CalculationBase interface and provides
+    state machine compatibility (set_up → run → tear_down).
+
+    Attributes:
+        _logger: Logger instance for calculation events
+        _kwargs: Keyword arguments passed to calculation
+        _result: Calculation result (None until run() completes)
+        _is_running: Flag indicating calculation is in progress
+    """
+
+    def __init__(self, logger: logging.Logger, **kwargs: Any) -> None:
+        """
+        Initialize MyCalculation with logger and configuration.
+
+        Args:
+            logger: Logger instance for calculation events
+            **kwargs: Additional keyword arguments for calculation configuration
+                     Expected keys:
+                     - data: Dict with calculation input (default: kwargs itself)
+                     - numbers: List of numbers to calculate (fallback)
+        """
+        super().__init__(logger)
+        self._kwargs = kwargs
+        self._result: Optional[Dict[str, Any]] = None
+        self._is_running = False
+
+        self._logger.info("MyCalculation instance created")
+        self._logger.debug(f"Configuration: {kwargs}")
+
+    def set_up(self) -> None:
+        """
+        Prepare calculation resources (state machine: idle → set_up).
+
+        This method is called by the task system before run().
+        Performs validation and resource initialization.
+        """
+        self._logger.info("MyCalculation setup started")
+
+        # Validate input data structure
+        data = self._kwargs.get('data', self._kwargs)
+        if not isinstance(data, dict):
+            self._logger.warning(f"Expected dict data, got {type(data).__name__}")
+
+        self._logger.info("MyCalculation setup completed successfully")
+
+    def run(self) -> None:
+        """
+        Execute the calculation (state machine: set_up → running).
+
+        This method performs the actual calculation using simple_calc.calculate().
+        Results are stored in self._result and accessible via the result property.
+        """
+        self._logger.info("MyCalculation execution started")
+        self._is_running = True
+
+        try:
+            # Extract data from kwargs (task sends data in 'data' key or root level)
+            data = self._kwargs.get('data', self._kwargs)
+
+            # Execute calculation using simple_calc function
+            self._logger.debug(f"Calling calculate() with data: {data}")
+            self._result = calculate(data)
+
+            self._logger.info(f"Calculation completed successfully: {self._result}")
+
+        except Exception as exc:
+            self._logger.error(f"Calculation failed: {exc}", exc_info=True)
+            self._result = {
+                'error': str(exc),
+                'status': 'failed'
+            }
+            raise
+
+        finally:
+            self._is_running = False
+
+    def tear_down(self) -> None:
+        """
+        Clean up calculation resources (state machine: running → tear_down).
+
+        This method is called by the task system after run() completes.
+        Performs cleanup and resource release.
+        """
+        self._logger.info("MyCalculation teardown started")
+
+        # Release resources (if any)
+        self._is_running = False
+
+        self._logger.info("MyCalculation teardown completed")
+
+    def stop(self) -> None:
+        """
+        Stop calculation execution (manual interrupt).
+
+        This method is called when the task is manually stopped.
+        Sets the running flag to False to signal interruption.
+        """
+        self._logger.warning("MyCalculation stop requested")
+        self._is_running = False
+
+        if self._result is None:
+            self._result = {
+                'status': 'stopped',
+                'message': 'Calculation was stopped before completion'
+            }
+
+        self._logger.info("MyCalculation stopped")
+
+    @property
+    def result(self) -> Optional[Dict[str, Any]]:
+        """
+        Get calculation result.
+
+        Returns:
+            Optional[Dict[str, Any]]: Calculation result or None if not yet executed
+                Expected structure:
+                {
+                    'result': int/float,      # Sum of numbers
+                    'count': int,             # Number count
+                    'average': float,         # Average value
+                    'timestamp': str,         # ISO format timestamp
+                    'service_name': str       # Service identifier
+                }
+        """
+        return self._result

calculation/impl/simple_calc.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Simple calculation implementation for BlackAnt SDK build_service testing."""
+
+import json
+import time
+import os
+from datetime import datetime
+
+
+def calculate(data):
+    """Simple calculation function.
+
+    Args:
+        data: Input data dictionary with 'numbers' list
+
+    Returns:
+        dict: Calculation result
+    """
+    numbers = data.get('numbers', [])
+
+    # Simple calculation: sum of numbers
+    result = sum(numbers)
+
+    # Add some processing time to simulate real calculation
+    time.sleep(0.5)
+
+    return {
+        'result': result,
+        'count': len(numbers),
+        'average': result / len(numbers) if numbers else 0,
+        'timestamp': datetime.now().isoformat(),
+        'service_name': os.getenv('SERVICE_NAME', 'simple-calc')
+    }
+
+
+def main():
+    """Main function for standalone execution."""
+    # Test data
+    test_data = {
+        'numbers': [1, 2, 3, 4, 5, 10, 15, 20]
+    }
+
+    print("🧮 BlackAnt Calculation Service Starting...")
+    print(f"📊 Input data: {test_data}")
+
+    result = calculate(test_data)
+
+    print(f"✅ Calculation completed: {json.dumps(result, indent=2)}")
+    print("🎯 Service ready for BlackAnt deployment!")
+
+
+if __name__ == '__main__':
+    main()

calculation/impl/test.py

@@ -0,0 +1 @@
+print('test')

calculation/impl/test_calc.py

@@ -0,0 +1,36 @@
+"""Test calculation module for BlackAnt SDK live test."""
+
+from calculation.base import BaseCalculation
+
+
+class TestCalculation(BaseCalculation):
+    """Simple test calculation for SDK verification."""
+
+    def calculate(self, input_data: dict) -> dict:
+        """
+        Simple calculation that processes a list of numbers.
+
+        Args:
+            input_data: dict with 'numbers' key containing list of numbers
+
+        Returns:
+            dict with sum, average, min, max
+        """
+        numbers = input_data.get('numbers', [])
+
+        if not numbers:
+            return {
+                'error': 'No numbers provided',
+                'status': 'failed'
+            }
+
+        result = {
+            'sum': sum(numbers),
+            'average': sum(numbers) / len(numbers),
+            'min': min(numbers),
+            'max': max(numbers),
+            'count': len(numbers),
+            'status': 'success'
+        }
+
+        return result

calculation/loader.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""
+CalculationLoader - Dynamic calculation loading system for BlackAnt SDK.
+
+This module provides thread-safe, singleton-based dynamic loading of calculation
+implementations. Supports environment variable configuration and automatic fallback.
+
+Designed for production use with Gunicorn multi-worker environments (8 workers).
+"""
+
+import os
+import threading
+import importlib
+from typing import Type, Dict, Optional
+
+from calculation.base import CalculationBase
+from blackant.utils.logging import get_logger
+
+
+class CalculationLoader:
+    """
+    Thread-safe singleton loader for dynamic calculation instantiation.
+
+    This loader supports:
+    - Environment variable configuration (CALCULATION_MODULE, CALCULATION_CLASS)
+    - Thread-safe caching for multi-worker environments
+    - Automatic fallback to MyCalculation
+    - Type validation (must inherit from CalculationBase)
+
+    Thread Safety:
+        Designed for Gunicorn with --workers=8 configuration.
+        Uses threading.Lock for cache synchronization across threads.
+
+    Usage:
+        >>> loader = CalculationLoader()
+        >>> CalculationClass = loader.get_calculation()
+        >>> calc = CalculationClass(logger, **kwargs)
+    """
+
+    # Class-level singleton instance
+    _instance: Optional['CalculationLoader'] = None
+    _instance_lock = threading.Lock()
+
+    def __new__(cls) -> 'CalculationLoader':
+        """
+        Create or return singleton instance (thread-safe).
+
+        Returns:
+            CalculationLoader: Singleton instance
+        """
+        if not cls._instance:
+            with cls._instance_lock:
+                # Double-check locking pattern for thread safety
+                if not cls._instance:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialize()
+        return cls._instance
+
+    def _initialize(self) -> None:
+        """Initialize loader state (called once by __new__)."""
+        self._cache: Dict[str, Type[CalculationBase]] = {}
+        self._cache_lock = threading.Lock()
+        self._logger = get_logger("CalculationLoader")
+
+        self._logger.info("CalculationLoader singleton initialized")
+
+    def get_calculation(self) -> Type[CalculationBase]:
+        """
+        Get calculation class based on environment configuration.
+
+        Environment Variables:
+            CALCULATION_MODULE: Python module path (default: calculation.impl.my_calculation)
+            CALCULATION_CLASS: Class name (default: MyCalculation)
+
+        Returns:
+            Type[CalculationBase]: Calculation class ready for instantiation
+
+        Raises:
+            TypeError: If loaded class does not inherit from CalculationBase
+
+        Example:
+            >>> os.environ['CALCULATION_MODULE'] = 'calculation.impl.simple_calc'
+            >>> os.environ['CALCULATION_CLASS'] = 'SimpleCalculation'
+            >>> loader = CalculationLoader()
+            >>> CalcClass = loader.get_calculation()
+            >>> calc = CalcClass(logger)
+        """
+        # Get configuration from environment
+        module_path = os.getenv('CALCULATION_MODULE', 'calculation.impl.my_calculation')
+        class_name = os.getenv('CALCULATION_CLASS', 'MyCalculation')
+
+        cache_key = f"{module_path}.{class_name}"
+
+        # Check cache first (thread-safe read)
+        with self._cache_lock:
+            if cache_key in self._cache:
+                self._logger.debug(f"Cache hit: {cache_key}")
+                return self._cache[cache_key]
+
+        # Cache miss - load calculation
+        self._logger.info(f"Loading calculation: {module_path}.{class_name}")
+
+        try:
+            calc_class = self._load_calculation(module_path, class_name)
+
+            # Cache the result (thread-safe write)
+            with self._cache_lock:
+                self._cache[cache_key] = calc_class
+
+            self._logger.info(f"Successfully loaded and cached: {cache_key}")
+            return calc_class
+
+        except Exception as exc:
+            self._logger.error(f"Failed to load {cache_key}: {exc}")
+            self._logger.warning("Falling back to default MyCalculation")
+
+            # Fallback to default MyCalculation
+            return self._load_fallback()
+
+    def _load_calculation(self, module_path: str, class_name: str) -> Type[CalculationBase]:
+        """
+        Load calculation class from module path.
+
+        Args:
+            module_path: Python module path (e.g., 'calculation.impl.my_calculation')
+            class_name: Class name (e.g., 'MyCalculation')
+
+        Returns:
+            Type[CalculationBase]: Loaded calculation class
+
+        Raises:
+            ImportError: If module cannot be imported
+            AttributeError: If class does not exist in module
+            TypeError: If class is not a CalculationBase subclass
+        """
+        # Import module
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as exc:
+            self._logger.error(f"Cannot import module '{module_path}': {exc}")
+            raise
+
+        # Get class from module
+        try:
+            calc_class = getattr(module, class_name)
+        except AttributeError as exc:
+            self._logger.error(f"Class '{class_name}' not found in '{module_path}': {exc}")
+            raise
+
+        # Validate it's a CalculationBase subclass
+        if not isinstance(calc_class, type):
+            raise TypeError(f"{class_name} is not a class (got {type(calc_class).__name__})")
+
+        if not issubclass(calc_class, CalculationBase):
+            raise TypeError(
+                f"{class_name} must inherit from CalculationBase "
+                f"(current bases: {[b.__name__ for b in calc_class.__bases__]})"
+            )
+
+        self._logger.debug(f"Validated: {class_name} is a valid CalculationBase subclass")
+        return calc_class
+
+    def _load_fallback(self) -> Type[CalculationBase]:
+        """
+        Load fallback calculation (MyCalculation).
+
+        Returns:
+            Type[CalculationBase]: MyCalculation class
+
+        Raises:
+            ImportError: If even fallback cannot be loaded (critical error)
+        """
+        fallback_module = 'calculation.impl.my_calculation'
+        fallback_class = 'MyCalculation'
+
+        cache_key = f"{fallback_module}.{fallback_class}"
+
+        # Check if fallback is already cached
+        with self._cache_lock:
+            if cache_key in self._cache:
+                return self._cache[cache_key]
+
+        try:
+            from calculation.impl.my_calculation import MyCalculation
+
+            # Cache fallback
+            with self._cache_lock:
+                self._cache[cache_key] = MyCalculation
+
+            self._logger.info("Fallback MyCalculation loaded successfully")
+            return MyCalculation
+
+        except ImportError as exc:
+            self._logger.critical(f"CRITICAL: Cannot load fallback MyCalculation: {exc}")
+            raise ImportError(
+                "CalculationLoader failed: cannot load configured calculation "
+                "and fallback MyCalculation is also unavailable. "
+                "Ensure calculation/impl/my_calculation.py exists."
+            ) from exc
+
+    def clear_cache(self) -> None:
+        """
+        Clear calculation cache (useful for testing or hot-reload).
+
+        Thread-safe operation.
+        """
+        with self._cache_lock:
+            cache_size = len(self._cache)
+            self._cache.clear()
+            self._logger.info(f"Cache cleared ({cache_size} entries removed)")
+
+    def get_cache_info(self) -> Dict[str, int]:
+        """
+        Get cache statistics.
+
+        Returns:
+            Dict[str, int]: Cache information
+                {
+                    'size': Number of cached calculations,
+                    'entries': List of cached keys
+                }
+        """
+        with self._cache_lock:
+            return {
+                'size': len(self._cache),
+                'entries': list(self._cache.keys())
+            }

notifinations/__init__.py

@@ -0,0 +1,8 @@
+"""Notifications module for BlackAnt SDK.
+
+This module provides email sending functionality.
+"""
+
+from notifinations.mail_sender import EmailSender
+
+__all__ = ["EmailSender"]

notifinations/mail_sender.py

@@ -0,0 +1,212 @@
+"""Email sender module.
+
+Module for sending email messages via SMTP.
+
+Example usage:
+    from mail_sender import EmailSender
+    mail_sender_inst = EmailSender()
+    mail_sender_inst.send_mail(
+        subject="My subject",
+        mail_body="My body",
+        addr_to="who_get_mail@mail.com",
+        addr_from="no_reply@blackant.app",
+        addr_cc="get_copy_mail@mail.com",
+        attachments=["file1.txt", "file2.json"],
+        reply_to="personal_mail@mail.com"
+    )
+"""
+
+import os
+import re
+import smtplib
+from email.mime.application import MIMEApplication
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from logging import Logger
+from typing import List, Optional, Union
+
+from blackant.utils.logging import get_logger
+
+
+class EmailSender:  # pylint: disable=too-few-public-methods
+    """Email sender class for SMTP operations.
+
+    This class handles email sending operations with support for
+    attachments, CC recipients, and reply-to addresses.
+
+    The init method creates an SMTP client and handles authentication.
+    Emails are constructed using the email.mime module and sent to recipients.
+    """
+
+    def __init__(self, logger: Optional[Logger] = None) -> None:
+        """Initialize the logger object and SMTP client.
+
+        Args:
+            logger: External logger to use. If None, creates default logger.
+
+        Environment variables:
+            SMTP_HOST: SMTP server hostname (default: mail.blackant.app)
+            SMTP_PORT: SMTP server port (default: 26)
+            SMTP_USER: SMTP username (required)
+            SMTP_PASSWORD: SMTP password (required)
+        """
+        self.__logger = logger or get_logger("email_sender")
+
+        # Get SMTP configuration from environment
+        smtp_host = os.getenv("SMTP_HOST", "mail.blackant.app")
+        smtp_port = int(os.getenv("SMTP_PORT", "26"))
+        smtp_user = os.getenv("SMTP_USER")
+        smtp_password = os.getenv("SMTP_PASSWORD")
+
+        if not smtp_user or not smtp_password:
+            raise ValueError(
+                "SMTP_USER and SMTP_PASSWORD environment variables are required. "
+                "Please set them before using EmailSender."
+            )
+
+        self.__logger.info("Initialize the SMTP client")
+        try:
+            self.__smtp_client = smtplib.SMTP(host=smtp_host, port=smtp_port)
+        except Exception:
+            self.__logger.exception("Cannot create the SMTP client")
+            raise
+        self.__logger.info("The SMTP client has been initialized")
+        try:
+            self.__smtp_client.login(user=smtp_user, password=smtp_password)
+        except Exception:
+            self.__logger.exception("Cannot login to SMTP server")
+            raise
+        self.__logger.info("Login to SMTP server has been successful")
+
+    def __string_to_list(self, string_param: Union[str, List, tuple, None]) -> List[str]:
+        """Convert input to list type.
+
+        Attempts to convert the input argument to list type.
+        Handles most built-in types that can be cast to list.
+
+        Args:
+            string_param: The object to convert, typically a string.
+                Can also handle other types (e.g., Tuple).
+
+        Returns:
+            list: The converted list.
+        """
+
+        list_to_return: list = []
+        if not string_param:
+            return list_to_return
+        if isinstance(string_param, str):
+            list_to_return.extend(re.split(r"[,;]", string_param))
+            return list_to_return
+        try:
+            return list(string_param)
+        except TypeError as type_error:
+            self.__logger.exception("Cannot convert the string to list.")
+            raise type_error
+
+    def send_mail(  # pylint: disable=too-many-arguments
+        self,
+        subject: str,
+        mail_body: str,
+        addr_to: Union[str, List[str]],
+        addr_from: str = "no-reply@blackant.app",
+        addr_cc: Optional[Union[str, List[str]]] = None,
+        attachments: Optional[List[str]] = None,
+        reply_to: Optional[str] = None,
+    ) -> None:
+        """Send an email message.
+
+        Constructs and sends an email based on the provided arguments.
+
+        Args:
+            subject: Email subject line.
+            mail_body: Email content (Text/HTML).
+            addr_to: Recipient email address.
+            addr_from: Sender email address. Defaults to no-reply@blackant.app.
+            addr_cc: Carbon copy recipient email address.
+            attachments: List of file paths to attach.
+            reply_to: Email address to use for replies.
+        """
+
+        addr_to = self.__string_to_list(addr_to)
+        addr_cc = self.__string_to_list(addr_cc)
+
+        if attachments:
+            if not isinstance(attachments, list):
+                raise TypeError("Attachments has to be list type.")
+            if all(single_attachment is None for single_attachment in attachments):
+                self.__logger.warning(
+                    "All elements of attachment list are None. Nothing will be attached to mail."
+                )
+                attachments = []
+        try:
+            self.__logger.info("E-mail will be sent to {}".format(addr_to))
+            if addr_cc:
+                self.__logger.info("Copy will be sent to {}".format(addr_cc))
+            message = self.__get_message_body(
+                subject=subject,
+                mail_body=mail_body,
+                addr_to=addr_to,
+                addr_from=addr_from,
+                addr_cc=addr_cc,
+                attachments=attachments,
+                reply_to=reply_to,
+            )
+
+            self.__logger.debug("The created message: {}".format(message.as_string()))
+
+            addr_to.extend(addr_cc)
+            self.__logger.info("Starting to send out the E-mail.")
+            self.__smtp_client.sendmail(addr_from, addr_to, message.as_string())
+            self.__logger.info("The E-mail has been sent out successfully.")
+        except smtplib.SMTPConnectError:
+            self.__logger.exception("Cannot connect to SMTP server.")
+        except smtplib.SMTPDataError:
+            self.__logger.exception("Data error in mail sending.")
+        finally:
+            self.__logger.info("Closing the SMTP connection.")
+            self.__smtp_client.quit()
+
+    @staticmethod
+    def __get_message_body(  # pylint: disable=too-many-arguments
+        subject: str,
+        mail_body: str,
+        addr_to: List[str],
+        addr_from: str,
+        addr_cc: List[str],
+        attachments: Optional[List[str]] = None,
+        reply_to: Optional[str] = None
+    ) -> MIMEMultipart:
+        """Construct the email message body.
+
+        Creates the email content based on the provided arguments.
+
+        Args:
+            subject: Email subject line.
+            mail_body: Email content (Text/HTML).
+            addr_to: Recipient email address.
+            addr_from: Sender email address. Defaults to no-reply@blackant.app.
+            addr_cc: Carbon copy recipient email address.
+            attachments: List of file paths to attach.
+            reply_to: Email address to use for replies.
+
+        Returns:
+            MIMEMultipart: The constructed email message.
+        """
+
+        msg = MIMEMultipart("alternative")
+        msg["To"] = ", ".join(addr_to) if addr_to else ""
+        msg["CC"] = ", ".join(addr_cc) if addr_cc else ""
+        msg["From"] = addr_from
+        msg["Subject"] = subject
+        msg.attach(MIMEText(mail_body, "html"))
+        if reply_to:
+            msg.add_header("reply-to", reply_to)
+        for single_file in attachments or []:
+            with open(single_file, "rb") as opened_file:
+                part = MIMEApplication(opened_file.read(), Name=os.path.basename(single_file))
+                part["Content-Disposition"] = 'attachment; filename="{}"'.format(
+                    os.path.basename(single_file)
+                )
+                msg.attach(part)
+        return msg