smartasync 0.2.0__tar.gz

smartasync-0.2.0/LICENSE

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

smartasync-0.2.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: smartasync
+Version: 0.2.0
+Summary: Unified sync/async API decorator with automatic context detection
+Author-email: Giovanni Porcari <softwell@softwell.it>
+License: MIT
+Project-URL: Homepage, https://github.com/genropy/smartasync
+Project-URL: Documentation, https://smartasync.readthedocs.io
+Project-URL: Repository, https://github.com/genropy/smartasync
+Project-URL: Bug Tracker, https://github.com/genropy/smartasync/issues
+Keywords: async,sync,decorator,asyncio,context-detection,unified-api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == "docs"
+Requires-Dist: myst-parser>=4.0.0; extra == "docs"
+Requires-Dist: sphinxcontrib-mermaid>=1.0.0; extra == "docs"
+Provides-Extra: all
+Requires-Dist: pytest>=7.0.0; extra == "all"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "all"
+Requires-Dist: pytest-cov>=4.0.0; extra == "all"
+Requires-Dist: black>=23.0.0; extra == "all"
+Requires-Dist: ruff>=0.1.0; extra == "all"
+Requires-Dist: mypy>=1.0.0; extra == "all"
+Requires-Dist: sphinx>=8.0.0; extra == "all"
+Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "all"
+Requires-Dist: sphinx-autodoc-typehints>=3.0.0; extra == "all"
+Requires-Dist: myst-parser>=4.0.0; extra == "all"
+Requires-Dist: sphinxcontrib-mermaid>=1.0.0; extra == "all"
+Dynamic: license-file
+
+# SmartAsync
+
+**Unified sync/async API decorator with automatic context detection**
+
+[![PyPI version](https://img.shields.io/pypi/v/smartasync.svg)](https://pypi.org/project/smartasync/)
+[![Tests](https://github.com/genropy/smartasync/actions/workflows/test.yml/badge.svg)](https://github.com/genropy/smartasync/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/genropy/smartasync/branch/main/graph/badge.svg)](https://codecov.io/gh/genropy/smartasync)
+[![Documentation Status](https://readthedocs.org/projects/smartasync/badge/?version=latest)](https://smartasync.readthedocs.io/en/latest/?badge=latest)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Part of Genro-Libs](https://img.shields.io/badge/Part%20of-Genro--Libs-blue)](https://github.com/softwell/genro-libs)
+[![LLM Docs](https://img.shields.io/badge/LLM-Docs-purple)](llm-docs/)
+
+SmartAsync allows you to write async methods once and call them in both sync and async contexts without modification. It automatically detects the execution context and adapts accordingly.
+
+## Features
+
+- ✅ **Automatic context detection**: Detects sync vs async execution context at runtime
+- ✅ **Zero configuration**: Just apply the `@smartasync` decorator
+- ✅ **Asymmetric caching**: Smart caching strategy for optimal performance
+- ✅ **Compatible with `__slots__`**: Works with memory-optimized classes
+- ✅ **Pure Python**: No dependencies beyond standard library
+
+## Installation
+
+```bash
+pip install smartasync
+```
+
+## Quick Start
+
+```python
+from smartasync import smartasync
+import asyncio
+
+class DataManager:
+    @smartasync
+    async def fetch_data(self, url: str):
+        """Fetch data - works in both sync and async contexts!"""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url)
+            return response.json()
+
+# Sync context - no await needed
+manager = DataManager()
+data = manager.fetch_data("https://api.example.com/data")
+
+# Async context - use await
+async def main():
+    manager = DataManager()
+    data = await manager.fetch_data("https://api.example.com/data")
+
+asyncio.run(main())
+```
+
+## How It Works
+
+SmartAsync uses `asyncio.get_running_loop()` to detect the execution context:
+
+- **Sync context** (no event loop): Executes with `asyncio.run()`
+- **Async context** (event loop running): Returns coroutine to be awaited
+
+### Asymmetric Caching
+
+SmartAsync uses an intelligent caching strategy:
+- ✅ **Async context detected**: Cached forever (can't transition from async to sync)
+- ⚠️ **Sync context**: Always rechecked (can transition from sync to async)
+
+This ensures correct behavior while optimizing for the most common case (async contexts in web frameworks).
+
+## Use Cases
+
+### 1. CLI + HTTP API
+
+```python
+from smartasync import smartasync
+from smpub import PublishedClass, ApiSwitcher
+
+class DataHandler(PublishedClass):
+    api = ApiSwitcher()
+
+    @api
+    @smartasync
+    async def process_data(self, input_file: str):
+        """Process data file."""
+        async with aiofiles.open(input_file) as f:
+            data = await f.read()
+        return process(data)
+
+# CLI usage (sync)
+handler = DataHandler()
+result = handler.process_data("data.csv")
+
+# HTTP usage (async via FastAPI)
+# Automatically works without modification!
+```
+
+### 2. Testing
+
+```python
+@smartasync
+async def database_query(query: str):
+    async with database.connect() as conn:
+        return await conn.execute(query)
+
+# Sync tests
+def test_query():
+    result = database_query("SELECT * FROM users")
+    assert len(result) > 0
+
+# Async tests
+async def test_query_async():
+    result = await database_query("SELECT * FROM users")
+    assert len(result) > 0
+```
+
+### 3. Mixed Codebases
+
+Perfect for gradually migrating sync code to async without breaking existing callers.
+
+## Performance
+
+- **Decoration time**: ~3-4 microseconds (one-time cost)
+- **Sync context**: ~102 microseconds (dominated by `asyncio.run()` overhead)
+- **Async context (first call)**: ~2.3 microseconds
+- **Async context (cached)**: ~1.3 microseconds
+
+For typical CLI tools and web APIs, this overhead is negligible compared to network latency (10-200ms).
+
+## Advanced Usage
+
+### With `__slots__`
+
+SmartAsync works seamlessly with `__slots__` classes:
+
+```python
+from smartasync import smartasync
+
+class OptimizedManager:
+    __slots__ = ('data',)
+
+    def __init__(self):
+        self.data = []
+
+    @smartasync
+    async def add_item(self, item):
+        await asyncio.sleep(0.01)  # Simulate I/O
+        self.data.append(item)
+```
+
+### Cache Reset for Testing
+
+```python
+@smartasync
+async def my_method():
+    pass
+
+# Reset cache between tests
+my_method._smartasync_reset_cache()
+```
+
+## Limitations
+
+- ⚠️ **Cannot transition from async to sync**: Once in async context, cannot move back to sync (this is correct behavior)
+- ⚠️ **Sync overhead**: Always rechecks context in sync mode (~2 microseconds per call)
+
+## Thread Safety
+
+SmartAsync is **safe for all common use cases**:
+
+✅ **Safe scenarios** (covers 99% of real-world usage):
+- Single-threaded applications (CLI tools, scripts)
+- Async event loops (inherently single-threaded)
+- Web servers with request isolation (new instance per request)
+- Thread pools with instance-per-thread pattern
+
+⚠️ **Theoretical concern** (anti-pattern, not recommended):
+- Sharing a single instance across multiple threads in a thread pool
+
+**Why this isn't a real issue:**
+The anti-pattern scenario defeats SmartAsync's purpose. If you're using thread pools with shared instances, you should use async workers instead for better performance and natural concurrency.
+
+**Recommendation:** Create instances per thread/request, or better yet, use async patterns natively.
+
+## Related Projects
+
+SmartAsync is part of the **Genro-Libs toolkit**:
+
+- [smartswitch](https://github.com/genropy/smartswitch) - Rule-based function dispatch
+- [smpub](https://github.com/genropy/smpub) - CLI/API framework (uses SmartAsync for async handlers)
+- [gtext](https://github.com/genropy/gtext) - Text transformation and templates
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Credits
+
+**Author**: Giovanni Porcari (Genropy Team)
+**Part of**: [Genro-Libs](https://github.com/softwell/genro-libs) developer toolkit

smartasync-0.2.0/README.md

@@ -0,0 +1,204 @@
+# SmartAsync
+
+**Unified sync/async API decorator with automatic context detection**
+
+[![PyPI version](https://img.shields.io/pypi/v/smartasync.svg)](https://pypi.org/project/smartasync/)
+[![Tests](https://github.com/genropy/smartasync/actions/workflows/test.yml/badge.svg)](https://github.com/genropy/smartasync/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/genropy/smartasync/branch/main/graph/badge.svg)](https://codecov.io/gh/genropy/smartasync)
+[![Documentation Status](https://readthedocs.org/projects/smartasync/badge/?version=latest)](https://smartasync.readthedocs.io/en/latest/?badge=latest)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Part of Genro-Libs](https://img.shields.io/badge/Part%20of-Genro--Libs-blue)](https://github.com/softwell/genro-libs)
+[![LLM Docs](https://img.shields.io/badge/LLM-Docs-purple)](llm-docs/)
+
+SmartAsync allows you to write async methods once and call them in both sync and async contexts without modification. It automatically detects the execution context and adapts accordingly.
+
+## Features
+
+- ✅ **Automatic context detection**: Detects sync vs async execution context at runtime
+- ✅ **Zero configuration**: Just apply the `@smartasync` decorator
+- ✅ **Asymmetric caching**: Smart caching strategy for optimal performance
+- ✅ **Compatible with `__slots__`**: Works with memory-optimized classes
+- ✅ **Pure Python**: No dependencies beyond standard library
+
+## Installation
+
+```bash
+pip install smartasync
+```
+
+## Quick Start
+
+```python
+from smartasync import smartasync
+import asyncio
+
+class DataManager:
+    @smartasync
+    async def fetch_data(self, url: str):
+        """Fetch data - works in both sync and async contexts!"""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url)
+            return response.json()
+
+# Sync context - no await needed
+manager = DataManager()
+data = manager.fetch_data("https://api.example.com/data")
+
+# Async context - use await
+async def main():
+    manager = DataManager()
+    data = await manager.fetch_data("https://api.example.com/data")
+
+asyncio.run(main())
+```
+
+## How It Works
+
+SmartAsync uses `asyncio.get_running_loop()` to detect the execution context:
+
+- **Sync context** (no event loop): Executes with `asyncio.run()`
+- **Async context** (event loop running): Returns coroutine to be awaited
+
+### Asymmetric Caching
+
+SmartAsync uses an intelligent caching strategy:
+- ✅ **Async context detected**: Cached forever (can't transition from async to sync)
+- ⚠️ **Sync context**: Always rechecked (can transition from sync to async)
+
+This ensures correct behavior while optimizing for the most common case (async contexts in web frameworks).
+
+## Use Cases
+
+### 1. CLI + HTTP API
+
+```python
+from smartasync import smartasync
+from smpub import PublishedClass, ApiSwitcher
+
+class DataHandler(PublishedClass):
+    api = ApiSwitcher()
+
+    @api
+    @smartasync
+    async def process_data(self, input_file: str):
+        """Process data file."""
+        async with aiofiles.open(input_file) as f:
+            data = await f.read()
+        return process(data)
+
+# CLI usage (sync)
+handler = DataHandler()
+result = handler.process_data("data.csv")
+
+# HTTP usage (async via FastAPI)
+# Automatically works without modification!
+```
+
+### 2. Testing
+
+```python
+@smartasync
+async def database_query(query: str):
+    async with database.connect() as conn:
+        return await conn.execute(query)
+
+# Sync tests
+def test_query():
+    result = database_query("SELECT * FROM users")
+    assert len(result) > 0
+
+# Async tests
+async def test_query_async():
+    result = await database_query("SELECT * FROM users")
+    assert len(result) > 0
+```
+
+### 3. Mixed Codebases
+
+Perfect for gradually migrating sync code to async without breaking existing callers.
+
+## Performance
+
+- **Decoration time**: ~3-4 microseconds (one-time cost)
+- **Sync context**: ~102 microseconds (dominated by `asyncio.run()` overhead)
+- **Async context (first call)**: ~2.3 microseconds
+- **Async context (cached)**: ~1.3 microseconds
+
+For typical CLI tools and web APIs, this overhead is negligible compared to network latency (10-200ms).
+
+## Advanced Usage
+
+### With `__slots__`
+
+SmartAsync works seamlessly with `__slots__` classes:
+
+```python
+from smartasync import smartasync
+
+class OptimizedManager:
+    __slots__ = ('data',)
+
+    def __init__(self):
+        self.data = []
+
+    @smartasync
+    async def add_item(self, item):
+        await asyncio.sleep(0.01)  # Simulate I/O
+        self.data.append(item)
+```
+
+### Cache Reset for Testing
+
+```python
+@smartasync
+async def my_method():
+    pass
+
+# Reset cache between tests
+my_method._smartasync_reset_cache()
+```
+
+## Limitations
+
+- ⚠️ **Cannot transition from async to sync**: Once in async context, cannot move back to sync (this is correct behavior)
+- ⚠️ **Sync overhead**: Always rechecks context in sync mode (~2 microseconds per call)
+
+## Thread Safety
+
+SmartAsync is **safe for all common use cases**:
+
+✅ **Safe scenarios** (covers 99% of real-world usage):
+- Single-threaded applications (CLI tools, scripts)
+- Async event loops (inherently single-threaded)
+- Web servers with request isolation (new instance per request)
+- Thread pools with instance-per-thread pattern
+
+⚠️ **Theoretical concern** (anti-pattern, not recommended):
+- Sharing a single instance across multiple threads in a thread pool
+
+**Why this isn't a real issue:**
+The anti-pattern scenario defeats SmartAsync's purpose. If you're using thread pools with shared instances, you should use async workers instead for better performance and natural concurrency.
+
+**Recommendation:** Create instances per thread/request, or better yet, use async patterns natively.
+
+## Related Projects
+
+SmartAsync is part of the **Genro-Libs toolkit**:
+
+- [smartswitch](https://github.com/genropy/smartswitch) - Rule-based function dispatch
+- [smpub](https://github.com/genropy/smpub) - CLI/API framework (uses SmartAsync for async handlers)
+- [gtext](https://github.com/genropy/gtext) - Text transformation and templates
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Credits
+
+**Author**: Giovanni Porcari (Genropy Team)
+**Part of**: [Genro-Libs](https://github.com/softwell/genro-libs) developer toolkit

smartasync-0.2.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smartasync"
+version = "0.2.0"
+description = "Unified sync/async API decorator with automatic context detection"
+authors = [
+    {name = "Giovanni Porcari", email = "softwell@softwell.it"},
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+keywords = ["async", "sync", "decorator", "asyncio", "context-detection", "unified-api"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+docs = [
+    "sphinx>=8.0.0",
+    "sphinx-rtd-theme>=3.0.0",
+    "sphinx-autodoc-typehints>=3.0.0",
+    "myst-parser>=4.0.0",
+    "sphinxcontrib-mermaid>=1.0.0",
+]
+all = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "sphinx>=8.0.0",
+    "sphinx-rtd-theme>=3.0.0",
+    "sphinx-autodoc-typehints>=3.0.0",
+    "myst-parser>=4.0.0",
+    "sphinxcontrib-mermaid>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/genropy/smartasync"
+Documentation = "https://smartasync.readthedocs.io"
+Repository = "https://github.com/genropy/smartasync"
+"Bug Tracker" = "https://github.com/genropy/smartasync/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["smartasync*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --cov=smartasync --cov-report=term-missing --cov-report=html --cov-report=xml"
+asyncio_mode = "auto"
+
+[tool.black]
+line-length = 100
+target-version = ['py310', 'py311', 'py312']
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+files = ["src/smartasync"]

smartasync-0.2.0/setup.cfg

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

smartasync-0.2.0/src/smartasync/__init__.py

@@ -0,0 +1,9 @@
+"""SmartAsync - Unified sync/async API decorator.
+
+Provides transparent sync/async method calling with automatic context detection.
+"""
+
+from .core import smartasync
+
+__version__ = "0.1.0"
+__all__ = ["smartasync"]