sweet_tea 0.1.28

A comprehensive Python factory pattern implementation with thread-safe operations and type-safe generics

Sweet Tea Factory System

A comprehensive, production-ready Python factory pattern implementation with advanced features for building extensible applications.

🚀 Features

• Dual Factory Patterns: Class-based factories (new instances) AND instance-based singletons (shared instances)
• Thread-Safe Registry: Concurrent operations with RLock synchronization
• Type-Safe Generics: Full TypeVar support with __class_getitem__
• Flexible Key Matching: Support for ClassName, class_name, classname variations
• Optional Dependencies: Graceful handling with custom warnings
• Auto-Registration: Classes automatically registered via package imports
• Lazy Singletons: SingletonFactory.create() for on-demand singleton instantiation
• Comprehensive Testing: 58 tests with 97% coverage
• Rich Documentation: MkDocs with Dracula theme and API reference

📦 Installation

Using uv (Recommended)

uv add sweet-tea

Using pip

pip install sweet-tea

Using Poetry

poetry add sweet-tea

🏁 Quick Start

from sweet_tea import Registry, Factory, AbstractFactory, SingletonFactory

# === CLASS-BASED FACTORY (Creates new instances each time) ===
Registry.register("database", DatabaseConnection)
db1 = Factory.create("database", configuration={"host": "server1"})
db2 = Factory.create("database", configuration={"host": "server2"})
# db1 ≠ db2 (different instances)

# === LAZY SINGLETON FACTORY (Creates and caches instances on-demand) ===
Registry.register("database", DatabaseConnection)
db3 = SingletonFactory.create("database", configuration={"host": "prod-db", "pool_size": 10})
db4 = SingletonFactory.create("database")  # Returns cached instance
# db3 === db4 (same cached instance)

# === TYPE-SAFE ABSTRACT FACTORIES ===
class DatabaseInterface:
    def connect(self) -> str: ...

db_factory = AbstractFactory[DatabaseInterface]
db = db_factory.create("postgres")  # Only classes implementing DatabaseInterface

Three Factory Patterns

1. Factory - Class registration → New instances with configuration
2. AbstractFactory - Type-constrained → New instances with type safety
3. SingletonFactory - Lazy singletons → Cached instances created on-demand

📖 Documentation

Complete documentation is available at https://snoodleboot-io.github.io/sweet_tea/

User Guides

• Getting Started - Installation and setup
• Basic Usage - Core factory patterns
• Advanced Features - Type constraints and threading

API Reference

• Registry - Global class registry
• Factory - Basic factory implementation
• AbstractFactory - Generic type-constrained factories

Development

• Contributing - Development setup and guidelines
• Testing - Testing strategy and coverage

🔧 Development

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended)

Setup

# Clone the repository
git clone https://github.com/snoodleboot-io/sweet_tea.git
cd sweet_tea

# Install development dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

# Build documentation locally
uv run mkdocs serve

Code Quality

This project uses several tools to maintain code quality:

• Black: Code formatting
• isort: Import sorting (compatible with Black)
• Ruff: Fast linting and additional formatting
• Bandit: Security scanning
• MyPy: Type checking

All tools run automatically via pre-commit hooks on git commit.

🤝 Contributing

We welcome contributions! Please see our contributing guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and ensure they pass
5. Update documentation if needed
6. Submit a pull request

📄 License

Copyright © 2025 snoodleboot, LLC. Licensed under the Apache License 2.0.

See LICENSE for the full license text.

🙏 Acknowledgments

• Built with Pydantic for data validation
• Documentation powered by MkDocs with Material theme
• Testing framework: pytest with coverage
• Code quality: Black, Ruff, MyPy

---

Sweet Tea Factory System - Production-ready factory patterns for Python applications.