stackmate 0.1.0__py3-none-any.whl

stackmate/__init__.py

@@ -0,0 +1,24 @@
+"""
+StackMate: A Full-Stack Development Toolkit for Python.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Sudhakar K"
+
+from stackmate.auth import AuthManager
+from stackmate.db_helper import DBHelper
+from stackmate.error_handler import APIResponse, ErrorCode
+from stackmate.logger import AppLogger
+from stackmate.utils import generate_uuid, get_timestamp
+from stackmate.validator import PayloadValidator
+
+__all__ = [
+    "AuthManager",
+    "DBHelper",
+    "APIResponse",
+    "ErrorCode",
+    "AppLogger",
+    "generate_uuid",
+    "get_timestamp",
+    "PayloadValidator",
+]

stackmate/auth.py

@@ -0,0 +1,82 @@
+"""
+JWT and token management utilities for StackMate.
+"""
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional, Union
+
+import jwt
+
+
+class AuthManager:
+    """
+    Manager for creating and verifying JWT tokens.
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        algorithm: str = "HS256",
+        expires_delta: int = 60,
+    ):
+        """
+        Initializes the Auth Manager.
+
+        Args:
+            secret_key (str): Secret key for encoding/decoding.
+            algorithm (str): JWT algorithm. Defaults to HS256.
+            expires_delta (int): Expiry time in minutes. Defaults to 60.
+        """
+        self.secret_key = secret_key
+        self.algorithm = algorithm
+        self.expires_delta = expires_delta
+
+    def create_token(self, data: Dict[str, Any]) -> str:
+        """
+        Creates a JWT token.
+
+        Args:
+            data (Dict): The payload to include.
+
+        Returns:
+            str: Encoded JWT token.
+        """
+        to_encode = data.copy()
+        expire = datetime.now(timezone.utc) + timedelta(minutes=self.expires_delta)
+        to_encode.update({"exp": expire})
+        return jwt.encode(to_encode, self.secret_key, algorithm=self.algorithm)
+
+    def verify_token(self, token: str) -> Optional[Dict[str, Any]]:
+        """
+        Verifies and decodes a JWT token.
+
+        Args:
+            token (str): The JWT string.
+
+        Returns:
+            Optional[Dict]: The decoded payload if valid, None otherwise.
+        """
+        try:
+            return jwt.decode(token, self.secret_key, algorithms=[self.algorithm])
+        except (jwt.ExpiredSignatureError, jwt.InvalidTokenError):
+            return None
+
+    def decode_token(self, token: str) -> Optional[Dict[str, Any]]:
+        """
+        Decodes a token without verifying expiry (for debug/extraction).
+
+        Args:
+            token (str): The JWT string.
+
+        Returns:
+            Optional[Dict]: The decoded payload.
+        """
+        try:
+            return jwt.decode(
+                token,
+                self.secret_key,
+                algorithms=[self.algorithm],
+                options={"verify_exp": False},
+            )
+        except Exception:
+            return None

stackmate/db_helper.py

@@ -0,0 +1,94 @@
+"""
+Database utility helpers for StackMate.
+Simulates a generic CRUD interface.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+
+class DBHelper:
+    """
+    Generic Database Helper for CRUD operations.
+    Acts as an abstraction layer (Mocked for demonstration).
+    """
+
+    def __init__(self, connection_string: str = "mock://localhost"):
+        """
+        Initializes the DB helper.
+
+        Args:
+            connection_string (str): Database connection URI.
+        """
+        self.connection_string = connection_string
+        # In a real app, you'd initialize a pool or client here
+        self._mock_db: List[Dict[str, Any]] = []
+
+    def create(self, table: str, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Inserts a new record into the "table".
+
+        Args:
+            table (str): Target table/collection name.
+            data (Dict): Record content.
+
+        Returns:
+            Dict: The created record.
+        """
+        # Mock implementation
+        record = {"id": len(self._mock_db) + 1, "table": table, **data}
+        self._mock_db.append(record)
+        return record
+
+    def read(self, table: str, filters: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        """
+        Retrieves records from the "table" based on filters.
+
+        Args:
+            table (str): Target table name.
+            filters (Dict): Query filters.
+
+        Returns:
+            List[Dict]: List of matching records.
+        """
+        results = [r for r in self._mock_db if r["table"] == table]
+        if filters:
+            for key, value in filters.items():
+                results = [r for r in results if r.get(key) == value]
+        return results
+
+    def update(
+        self, table: str, record_id: int, updates: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Updates an existing record.
+
+        Args:
+            table (str): Target table name.
+            record_id (int): ID of the record to update.
+            updates (Dict): Field-value updates.
+
+        Returns:
+            Optional[Dict]: The updated record if found.
+        """
+        for record in self._mock_db:
+            if record["table"] == table and record["id"] == record_id:
+                record.update(updates)
+                return record
+        return None
+
+    def delete(self, table: str, record_id: int) -> bool:
+        """
+        Deletes a record.
+
+        Args:
+            table (str): Target table name.
+            record_id (int): ID of the record.
+
+        Returns:
+            bool: True if deleted, False if not found.
+        """
+        for i, record in enumerate(self._mock_db):
+            if record["table"] == table and record["id"] == record_id:
+                del self._mock_db[i]
+                return True
+        return False

stackmate/error_handler.py

@@ -0,0 +1,73 @@
+"""
+Unified error handling and structured API responses for StackMate.
+"""
+
+from enum import Enum
+from typing import Any, Dict, Optional, Union
+
+
+class ErrorCode(str, Enum):
+    """Enumeration of standard error codes."""
+
+    SUCCESS = "SUCCESS"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    AUTHENTICATION_ERROR = "AUTHENTICATION_ERROR"
+    NOT_FOUND = "NOT_FOUND"
+    DATABASE_ERROR = "DATABASE_ERROR"
+    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR"
+
+
+class APIResponse:
+    """Class to handle structured API responses."""
+
+    @staticmethod
+    def success(
+        data: Any = None,
+        message: str = "Operation successful",
+        status_code: int = 200,
+    ) -> Dict[str, Any]:
+        """
+        Generates a successful API response.
+
+        Args:
+            data (Any): The payload to return.
+            message (str): A message for the user.
+            status_code (int): HTTP status code.
+
+        Returns:
+            Dict[str, Any]: Structured success response.
+        """
+        return {
+            "success": True,
+            "message": message,
+            "data": data,
+            "error_code": ErrorCode.SUCCESS,
+            "status_code": status_code,
+        }
+
+    @staticmethod
+    def failure(
+        message: str,
+        error_code: ErrorCode = ErrorCode.INTERNAL_SERVER_ERROR,
+        data: Any = None,
+        status_code: int = 500,
+    ) -> Dict[str, Any]:
+        """
+        Generates a failed API response.
+
+        Args:
+            message (str): Error message.
+            error_code (ErrorCode): Standardized error code.
+            data (Any): Optional additional error context.
+            status_code (int): HTTP status code.
+
+        Returns:
+            Dict[str, Any]: Structured failure response.
+        """
+        return {
+            "success": False,
+            "message": message,
+            "data": data,
+            "error_code": error_code,
+            "status_code": status_code,
+        }

stackmate/logger.py

@@ -0,0 +1,96 @@
+"""
+Request/Response logging utilities for StackMate.
+"""
+
+import json
+import logging
+import time
+from typing import Any, Dict, Optional
+
+from stackmate.utils import get_timestamp, parse_latency
+
+
+class AppLogger:
+    """
+    Standard logger for API requests and responses.
+    """
+
+    def __init__(self, name: str = "StackMate", level: int = logging.INFO):
+        """
+        Initializes the logger.
+
+        Args:
+            name (str): Name of the logger.
+            level (int): Logging level.
+        """
+        self.logger = logging.getLogger(name)
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+        handler.setFormatter(formatter)
+        if not self.logger.handlers:
+            self.logger.addHandler(handler)
+        self.logger.setLevel(level)
+
+    def log_request(self, method: str, url: str, payload: Optional[Dict[str, Any]] = None) -> float:
+        """
+        Logs an incoming API request.
+
+        Args:
+            method (str): HTTP method (GET, POST, etc.).
+            url (str): Target URL.
+            payload (Dict): Request body.
+
+        Returns:
+            float: The start time of the request.
+        """
+        start_time = time.time()
+        log_data = {
+            "timestamp": get_timestamp(),
+            "type": "REQUEST",
+            "method": method,
+            "url": url,
+            "payload": payload,
+        }
+        self.logger.info("Request: %s", json.dumps(log_data))
+        return start_time
+
+    def log_response(
+        self,
+        method: str,
+        url: str,
+        status_code: int,
+        start_time: float,
+        response_data: Optional[Any] = None,
+    ) -> None:
+        """
+        Logs an API response with latency calculation.
+
+        Args:
+            method (str): HTTP method.
+            url (str): Target URL.
+            status_code (int): HTTP status code.
+            start_time (float): The timestamp when the request started.
+            response_data (Any): The response content.
+        """
+        end_time = time.time()
+        latency = parse_latency(start_time, end_time)
+        log_data = {
+            "timestamp": get_timestamp(),
+            "type": "RESPONSE",
+            "method": method,
+            "url": url,
+            "status": status_code,
+            "latency": latency,
+            "data": response_data,
+        }
+        self.logger.info("Response: %s", json.dumps(log_data))
+
+    def error(self, message: str, exc_info: bool = True) -> None:
+        """Logs an error message."""
+        self.logger.error(message, exc_info=exc_info)
+
+    def info(self, message: str) -> None:
+        """Logs an info message."""
+        self.logger.info(message)

stackmate/utils.py

@@ -0,0 +1,62 @@
+"""
+Miscellaneous helper functions for StackMate.
+"""
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+def generate_uuid() -> str:
+    """
+    Generates a unique UUID v4 string.
+
+    Returns:
+        str: A unique UUID.
+    """
+    return str(uuid.uuid4())
+
+
+def get_timestamp(utc: bool = True) -> str:
+    """
+    Returns the current timestamp in ISO format.
+
+    Args:
+        utc (bool): Whether to use UTC time. Defaults to True.
+
+    Returns:
+        str: ISO formatted timestamp.
+    """
+    if utc:
+        return datetime.now(timezone.utc).isoformat()
+    return datetime.now().isoformat()
+
+
+def format_response_data(data: Any) -> Dict[str, Any]:
+    """
+    Helper to ensure data is in a dictionary format for JSON responses.
+
+    Args:
+        data (Any): Input data.
+
+    Returns:
+        Dict[str, Any]: Formatted data.
+    """
+    if isinstance(data, dict):
+        return data
+    return {"result": data}
+
+
+def parse_latency(start_time: float, end_time: float) -> str:
+    """
+    Calculates latency and returns it as a formatted string.
+
+    Args:
+        start_time (float): Execution start time.
+        end_time (float): Execution end time.
+
+    Returns:
+        str: Latency in milliseconds (e.g., "120ms").
+    """
+    duration = (end_time - start_time) * 1000
+    return f"{duration:.2f}ms"

stackmate/validator.py

@@ -0,0 +1,66 @@
+"""
+API payload validation utilities for StackMate.
+"""
+
+from typing import Any, Dict, List, Optional, Type, Union
+
+
+class PayloadValidator:
+    """
+    Validates API request payloads against required fields and types.
+    """
+
+    @staticmethod
+    def validate(
+        payload: Dict[str, Any],
+        schema: Dict[str, Type],
+        required_fields: Optional[List[str]] = None,
+    ) -> List[str]:
+        """
+        Validates the payload against a schema.
+
+        Args:
+            payload (Dict): The data to validate.
+            schema (Dict): A mapping of field names to expected types.
+            required_fields (List): A list of fields that must be present.
+
+        Returns:
+            List[str]: A list of error messages. Empty if valid.
+        """
+        errors = []
+        required = required_fields or []
+
+        # Check for missing required fields
+        for field in required:
+            if field not in payload:
+                errors.append(f"Field '{field}' is required.")
+
+        # Check types for present fields
+        for field, value in payload.items():
+            if field in schema:
+                expected_type = schema[field]
+                if not isinstance(value, expected_type):
+                    errors.append(
+                        f"Field '{field}' must be of type {expected_type.__name__}, "
+                        f"got {type(value).__name__}."
+                    )
+            elif field not in schema and required_fields is not None:
+                # Optionally handle unexpected fields if schema is strict
+                # For now, we allow them unless we want strict validation
+                pass
+
+        return errors
+
+    @staticmethod
+    def is_valid(
+        payload: Dict[str, Any],
+        schema: Dict[str, Type],
+        required_fields: Optional[List[str]] = None,
+    ) -> bool:
+        """
+        Shortcut to check if a payload is valid.
+
+        Returns:
+            bool: True if valid, False otherwise.
+        """
+        return len(PayloadValidator.validate(payload, schema, required_fields)) == 0

stackmate-0.1.0.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: stackmate
+Version: 0.1.0
+Summary: A Full-Stack Development Toolkit for Python developers.
+Author-email: Sudhakar K <sudhakark4227@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# StackMate
+
+**StackMate** is a production-ready Full-Stack Development Toolkit for Python developers. It provides essential utilities for building robust APIs, managing authentication, handling errors, and simplifying database operations.
+
+## Features
+
+- **Logger**: Structured request/response logging with latency tracking.
+- **Validator**: API payload validation using type hints and schema checks.
+- **DB Helper**: Generic CRUD utilities for SQL/NoSQL databases.
+- **Auth**: Secure JWT token management (creation and verification).
+- **Error Handler**: Standardized API response formatting.
+- **Utils**: Common helper functions (UUIDs, timestamps, etc.).
+
+## Installation
+
+```bash
+pip install stackmate
+```
+
+## Quick Start
+
+```python
+from stackmate.logger import AppLogger
+from stackmate.auth import AuthManager
+
+# Initialize components
+logger = AppLogger("my-app")
+auth = AuthManager(secret_key="your-secret-key")
+
+# Use them in your application
+token = auth.create_token({"user_id": 123})
+```
+
+## Project Structure
+
+```text
+stackmate/
+├── stackmate/           # Core library files
+├── examples/            # Example usage scripts
+├── tests/               # Unit tests
+├── pyproject.toml       # Build configuration
+└── README.md            # Project documentation
+```
+
+## Author
+
+- **Sudhakar K** - [sudhakark4227@gmail.com](mailto:sudhakark4227@gmail.com)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

stackmate-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+stackmate/__init__.py,sha256=IPfrLdFHIHgHB_4V3X3Hn-TqtCk6Dwm9lzAj1s452ak,591
+stackmate/auth.py,sha256=B4tOtpXXxp1Ce017HLLgmSaRNAe03OF8FR1rG5vG384,2344
+stackmate/db_helper.py,sha256=KpCXNCxl_8iXsNcdRUcstoZUJgDwhukK4laSL3BOpaY,2912
+stackmate/error_handler.py,sha256=XYat-D9mlmUhcVCCUewsQYG2o7YOUW5zANPU2KD3w9I,2038
+stackmate/logger.py,sha256=ya3nV6KA9RfIZ3uV2pvStchirMryO_SxCd5eOycy1L4,2876
+stackmate/utils.py,sha256=COtTHEKU2t7IyBE5oB_-vC9KcM0O_gMQr5dG_UQglVo,1419
+stackmate/validator.py,sha256=HcizDceTYQJYb29fwGs6HARauHa35LMikOhgdScJ6yc,2151
+stackmate-0.1.0.dist-info/licenses/LICENSE,sha256=mpx1EG96iVtm54Ttxu_r5k9cj9Q6vjiozWO-n3UMTLM,1088
+stackmate-0.1.0.dist-info/METADATA,sha256=_wNFezIWN-Wxj48wzVsMfMDxtJtEXcPw3Kxa_RgnjUA,2421
+stackmate-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+stackmate-0.1.0.dist-info/top_level.txt,sha256=mV9VScpq-qTtrQJk9bHvvmQ-2L93_y25D4SeAB6t1CE,10
+stackmate-0.1.0.dist-info/RECORD,,

stackmate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stackmate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sudhakar K
+
+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.

stackmate-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stackmate