fivcglue 0.1.0__tar.gz

fivcglue-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Charlie Zhang
+
+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.
+

fivcglue-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: fivcglue
+Version: 0.1.0
+Summary: A Domain-Driven Design (DDD) programming package for Python, similar to zope.interface
+Author-email: Charlie ZHANG <sunnypig2002@gmail.com>
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/5C-Plus/fivcglue#readme
+Project-URL: Issues, https://github.com/5C-Plus/fivcglue/issues
+Project-URL: Source, https://github.com/5C-Plus/fivcglue
+Keywords: ddd,domain-driven-design,interface,architecture
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Object Brokering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=6.0.1; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# FivcGlue
+
+A Domain-Driven Design (DDD) programming package for Python, similar to `zope.interface`.
+
+## 🎯 Overview
+
+FivcGlue provides a clean and intuitive way to implement Domain-Driven Design patterns in Python applications. It offers interfaces and implementations for common DDD building blocks, helping you structure your code following DDD principles.
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10 or higher
+- UV package manager (recommended) or pip
+
+### Installation
+
+**With UV (recommended):**
+```bash
+# Install with development dependencies
+make install
+
+# Or minimal installation
+make install-min
+
+# With YAML support
+uv sync --extra yaml
+```
+
+**With pip:**
+```bash
+# Basic installation
+pip install -e .
+
+# With YAML support
+pip install -e ".[yaml]"
+
+# With development dependencies
+pip install -e ".[dev,yaml]"
+```
+
+## 📦 Features
+
+FivcGlue provides core DDD building blocks:
+
+- **Interfaces**: Define contracts for your domain components
+- **Configurations**: Flexible configuration management (JSON, YAML)
+- **Caching**: In-memory and Redis-based caching implementations
+- **Logging**: Built-in logging utilities
+- **Mutexes**: Distributed locking with Redis support
+
+## 💻 Usage
+
+### Basic Example
+
+```python
+from fivcglue.interfaces import IConfig
+from fivcglue.implements import YAMLFileConfig
+
+# Load configuration from YAML file
+config = YAMLFileConfig("config.yml")
+value = config.get("key", default="default_value")
+```
+
+### Configuration Management
+
+```python
+from fivcglue.implements import JSONFileConfig, YAMLFileConfig
+
+# JSON configuration
+json_config = JSONFileConfig("settings.json")
+
+# YAML configuration (requires PyYAML)
+yaml_config = YAMLFileConfig("settings.yml")
+```
+
+### Caching
+
+```python
+from fivcglue.implements import MemoryCache, RedisCache
+
+# In-memory cache
+cache = MemoryCache()
+cache.set("key", "value", ttl=3600)
+value = cache.get("key")
+
+# Redis cache
+redis_cache = RedisCache(host="localhost", port=6379)
+redis_cache.set("key", "value", ttl=3600)
+```
+
+## 📁 Project Structure
+
+```
+src/fivcglue/
+├── interfaces/      # Interface definitions
+│   ├── configs.py   # Configuration interfaces
+│   ├── caches.py    # Cache interfaces
+│   ├── loggers.py   # Logger interfaces
+│   └── mutexes.py   # Mutex interfaces
+├── implements/      # Concrete implementations
+│   ├── configs_jsonfile.py
+│   ├── configs_yamlfile.py
+│   ├── caches_mem.py
+│   ├── caches_redis.py
+│   ├── loggers_builtin.py
+│   └── mutexes_redis.py
+└── fixtures/        # Test fixtures
+```
+
+## 🛠️ Development
+
+### Available Make Commands
+
+```bash
+make help        # Show all available commands
+make install     # Install with dev dependencies
+make install-min # Install minimal dependencies
+make dev         # Install development dependencies
+make lint        # Run code linting
+make format      # Format code
+make test        # Run tests
+make test-cov    # Run tests with coverage
+make clean       # Clean temporary files
+make build       # Build distribution packages
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make test-cov
+
+# Run specific test file
+uv run pytest tests/test_configs.py -v
+```
+
+### Code Quality
+
+```bash
+# Lint code
+make lint
+
+# Format code
+make format
+```
+
+## 📚 Documentation
+
+For more detailed documentation, see the [docs/](docs/) directory:
+
+- [Architecture](docs/ARCHITECTURE.md) - System architecture and design
+- [Dependencies](docs/DEPENDENCIES.md) - Dependency management guide
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `make install`
+3. Run tests: `make test`
+4. Format code: `make format`
+5. Run linting: `make lint`
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+## 🔗 Links
+
+- **Documentation**: [GitHub README](https://github.com/5C-Plus/fivcglue#readme)
+- **Issues**: [GitHub Issues](https://github.com/5C-Plus/fivcglue/issues)
+- **Source**: [GitHub Repository](https://github.com/5C-Plus/fivcglue)

fivcglue-0.1.0/README.md

@@ -0,0 +1,177 @@
+# FivcGlue
+
+A Domain-Driven Design (DDD) programming package for Python, similar to `zope.interface`.
+
+## 🎯 Overview
+
+FivcGlue provides a clean and intuitive way to implement Domain-Driven Design patterns in Python applications. It offers interfaces and implementations for common DDD building blocks, helping you structure your code following DDD principles.
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10 or higher
+- UV package manager (recommended) or pip
+
+### Installation
+
+**With UV (recommended):**
+```bash
+# Install with development dependencies
+make install
+
+# Or minimal installation
+make install-min
+
+# With YAML support
+uv sync --extra yaml
+```
+
+**With pip:**
+```bash
+# Basic installation
+pip install -e .
+
+# With YAML support
+pip install -e ".[yaml]"
+
+# With development dependencies
+pip install -e ".[dev,yaml]"
+```
+
+## 📦 Features
+
+FivcGlue provides core DDD building blocks:
+
+- **Interfaces**: Define contracts for your domain components
+- **Configurations**: Flexible configuration management (JSON, YAML)
+- **Caching**: In-memory and Redis-based caching implementations
+- **Logging**: Built-in logging utilities
+- **Mutexes**: Distributed locking with Redis support
+
+## 💻 Usage
+
+### Basic Example
+
+```python
+from fivcglue.interfaces import IConfig
+from fivcglue.implements import YAMLFileConfig
+
+# Load configuration from YAML file
+config = YAMLFileConfig("config.yml")
+value = config.get("key", default="default_value")
+```
+
+### Configuration Management
+
+```python
+from fivcglue.implements import JSONFileConfig, YAMLFileConfig
+
+# JSON configuration
+json_config = JSONFileConfig("settings.json")
+
+# YAML configuration (requires PyYAML)
+yaml_config = YAMLFileConfig("settings.yml")
+```
+
+### Caching
+
+```python
+from fivcglue.implements import MemoryCache, RedisCache
+
+# In-memory cache
+cache = MemoryCache()
+cache.set("key", "value", ttl=3600)
+value = cache.get("key")
+
+# Redis cache
+redis_cache = RedisCache(host="localhost", port=6379)
+redis_cache.set("key", "value", ttl=3600)
+```
+
+## 📁 Project Structure
+
+```
+src/fivcglue/
+├── interfaces/      # Interface definitions
+│   ├── configs.py   # Configuration interfaces
+│   ├── caches.py    # Cache interfaces
+│   ├── loggers.py   # Logger interfaces
+│   └── mutexes.py   # Mutex interfaces
+├── implements/      # Concrete implementations
+│   ├── configs_jsonfile.py
+│   ├── configs_yamlfile.py
+│   ├── caches_mem.py
+│   ├── caches_redis.py
+│   ├── loggers_builtin.py
+│   └── mutexes_redis.py
+└── fixtures/        # Test fixtures
+```
+
+## 🛠️ Development
+
+### Available Make Commands
+
+```bash
+make help        # Show all available commands
+make install     # Install with dev dependencies
+make install-min # Install minimal dependencies
+make dev         # Install development dependencies
+make lint        # Run code linting
+make format      # Format code
+make test        # Run tests
+make test-cov    # Run tests with coverage
+make clean       # Clean temporary files
+make build       # Build distribution packages
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with coverage
+make test-cov
+
+# Run specific test file
+uv run pytest tests/test_configs.py -v
+```
+
+### Code Quality
+
+```bash
+# Lint code
+make lint
+
+# Format code
+make format
+```
+
+## 📚 Documentation
+
+For more detailed documentation, see the [docs/](docs/) directory:
+
+- [Architecture](docs/ARCHITECTURE.md) - System architecture and design
+- [Dependencies](docs/DEPENDENCIES.md) - Dependency management guide
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies: `make install`
+3. Run tests: `make test`
+4. Format code: `make format`
+5. Run linting: `make lint`
+
+## 📄 License
+
+MIT License - see LICENSE file for details
+
+## 🔗 Links
+
+- **Documentation**: [GitHub README](https://github.com/5C-Plus/fivcglue#readme)
+- **Issues**: [GitHub Issues](https://github.com/5C-Plus/fivcglue/issues)
+- **Source**: [GitHub Repository](https://github.com/5C-Plus/fivcglue)

fivcglue-0.1.0/pyproject.toml

@@ -0,0 +1,114 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fivcglue"
+version = "0.1.0"
+description = "A Domain-Driven Design (DDD) programming package for Python, similar to zope.interface"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["ddd", "domain-driven-design", "interface", "architecture"]
+authors = [
+  { name = "Charlie ZHANG", email = "sunnypig2002@gmail.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Software Development :: Object Brokering",
+]
+dependencies = []
+
+[project.optional-dependencies]
+yaml = ["PyYAML>=6.0.1"]
+dev = [
+  "pytest>=8.2.0",
+  "pytest-asyncio>=0.21.0",
+  "pytest-cov>=4.1.0",
+  "ruff>=0.4.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/5C-Plus/fivcglue#readme"
+Issues = "https://github.com/5C-Plus/fivcglue/issues"
+Source = "https://github.com/5C-Plus/fivcglue"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.run]
+source_pkgs = ["fivcglue", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/fivcglue/__about__.py",
+]
+
+[tool.coverage.paths]
+fivcglue = ["src/fivcglue", "*/fivcglue/src/fivcglue"]
+tests = ["tests", "*/fivcglue/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[tool.pytest.ini_options]
+# Test discovery settings
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+# Additional pytest options
+addopts = [
+  "--strict-markers",
+  "--strict-config",
+  "--verbose",
+]
+
+# Markers for test categorization
+markers = [
+  "asyncio: marks tests as async (deselect with '-m \"not asyncio\"')",
+  "integration: marks tests as integration tests (deselect with '-m \"not integration\"')",
+]
+
+# Suppress warnings for cleaner output
+filterwarnings = [
+  "ignore::DeprecationWarning",
+  "ignore::PendingDeprecationWarning",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+  "E",   # pycodestyle errors
+  "W",   # pycodestyle warnings
+  "F",   # pyflakes
+  "I",   # isort
+  "B",   # flake8-bugbear
+  "C4",  # flake8-comprehensions
+  "UP",  # pyupgrade
+]
+ignore = [
+  "E501",  # line too long (handled by formatter)
+  "B008",  # do not perform function calls in argument defaults
+  "C901",  # too complex
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

fivcglue-0.1.0/setup.cfg

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

fivcglue-0.1.0/src/fivcglue/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

fivcglue-0.1.0/src/fivcglue/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    "IComponent",
+    "IComponentSite",
+    "IComponentSiteBuilder",
+    "utils",
+]
+
+from .interfaces import (  # noqa
+    IComponent,
+    IComponentSite,
+    IComponentSiteBuilder,
+    utils,
+)

fivcglue-0.1.0/src/fivcglue/implements/__init__.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import TextIO
+
+from fivcglue import (
+    IComponent,
+    IComponentSite,
+    IComponentSiteBuilder,
+)
+from fivcglue import (
+    utils as i_utils,
+)
+
+
+class ComponentSite(IComponentSite):
+    """
+    default implementation of IComponentSite
+    """
+
+    def __init__(self):
+        self.service_mapping: dict[type, dict[str, IComponent]] = {}
+
+    def get_component(
+        self,
+        interface: type,
+        name: str = "",
+    ) -> IComponent:
+        component = self.query_component(interface, name=name)
+        if not component:
+            err_msg = "component not found"
+            raise LookupError(err_msg)
+        return component
+
+    def query_component(
+        self,
+        interface: type,
+        name: str = "",
+    ) -> IComponent | None:
+        component = self.service_mapping.get(interface)
+        return component and component.get(name)
+
+    def register_component(
+        self,
+        interface: type,
+        implement: IComponent,
+        name: str = "",
+    ) -> IComponent:
+        if not issubclass(implement.__class__, interface):
+            err_msg = "incorrect implementation for component interface"
+            raise TypeError(err_msg)
+
+        mapping = self.service_mapping.setdefault(interface, {})
+        mapping.update({name: implement})
+        return implement
+
+
+class ComponentSiteBuilder(IComponentSiteBuilder):
+    """
+    default implementation of ServiceBuilder
+    """
+
+    @staticmethod
+    def _loads(component_site: IComponentSite, configs: tuple | list):
+        if not isinstance(configs, (tuple, list)):
+            err_msg = "invalid component configuration file"
+            raise TypeError(err_msg)
+
+        for config_item in configs:
+            service_class_name = config_item.pop("class", "")
+            service_entries_name = config_item.pop("entries", [])
+            if not isinstance(service_entries_name, (tuple, list)):
+                err_msg = "invalid component entries in configuration file"
+                raise TypeError(err_msg)
+            try:
+                service_class = i_utils.import_string(service_class_name)
+            except ImportError as e:
+                err_msg = f"invalid component class {service_class_name}"
+                raise LookupError(err_msg) from e
+
+            service_instance = service_class(component_site, **config_item)
+            for e in service_entries_name:
+                if not isinstance(e, dict):
+                    err_msg = "invalid component entry in configuration file"
+                    raise TypeError(err_msg)
+
+                service_name = e.get("name", "")
+                service_interface_name = e.get("interface", "")
+                try:
+                    service_interface = i_utils.import_string(service_interface_name)
+                except ImportError as e:
+                    err_msg = f"invalid component interface {service_interface_name}"
+                    raise LookupError(err_msg) from e
+
+                component_site.register_component(
+                    service_interface, service_instance, name=service_name
+                )
+
+    def _parse(self, configs: TextIO, fmt: str = "json"):
+        if fmt == "json":
+            import json
+
+            return json.loads(configs.read())
+
+        if fmt in ["yaml", "yml"]:
+            import yaml
+
+            return yaml.safe_load(configs.read())
+
+        err_msg = f"Unknown file format {fmt}"
+        raise NotImplementedError(err_msg)
+
+    def loads(
+        self,
+        component_site: IComponentSite,
+        configs: TextIO,
+        fmt: str = "json",
+    ):
+        self._loads(component_site, self._parse(configs, fmt))
+
+    def dumps(
+        self,
+        component_site: IComponentSite,
+        configs: TextIO,
+        fmt: str = "json",
+    ):
+        raise NotImplementedError