guaro 0.1.0__tar.gz

guaro-0.1.0/LICENSE

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

guaro-0.1.0/PKG-INFO

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: guaro
+Version: 0.1.0
+Summary: Guaro: Unified REST + GraphQL framework with auto-migration and multi-database support
+Author-email: Mickyas Tesfaye <alazar42@github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Alazar42/Guaro
+Project-URL: Repository, https://github.com/Alazar42/Guaro.git
+Project-URL: Documentation, https://github.com/Alazar42/Guaro/blob/main/docs/README.md
+Project-URL: Changelog, https://github.com/Alazar42/Guaro/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/Alazar42/Guaro/issues
+Keywords: framework,rest,graphql,api,starlette,strawberry,database,orm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: starlette>=0.37
+Requires-Dist: strawberry-graphql>=0.245
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.17; extra == "sqlite"
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2; extra == "mysql"
+Provides-Extra: mongodb
+Requires-Dist: motor>=3.3; extra == "mongodb"
+Provides-Extra: all-databases
+Requires-Dist: aiosqlite>=0.17; extra == "all-databases"
+Requires-Dist: asyncpg>=0.29; extra == "all-databases"
+Requires-Dist: aiomysql>=0.2; extra == "all-databases"
+Requires-Dist: motor>=3.3; extra == "all-databases"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: pylint>=3.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# Guaro - Modern Python Backend Framework
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+
+A powerful, async-first Python framework for building REST & GraphQL APIs with automatic schema management, dependency injection, and type-safe data validation.
+
+## ✨ Features
+
+- **🚀 Async-First**: Built on Starlette for high-performance async request handling
+- **🔄 Multi-Protocol**: REST and GraphQL support out of the box
+- **📊 Database Agnostic**: SQLite, PostgreSQL, MySQL, MongoDB support with intelligent schema management
+- **✅ Auto-Migrate**: Smart schema updates that preserve data (never loses existing data)
+- **🔗 Relations**: Built-in support for complex relationships and nested queries
+- **💉 Dependency Injection**: Clean dependency resolution for handlers and middleware
+- **🛡️ Type Safe**: Full type hints for better IDE support and developer experience
+- **📝 Auto Documentation**: Automatic OpenAPI/Swagger generation
+- **🔐 Middleware & Auth**: Built-in middleware support for authentication & permissions
+
+## 🚀 Quick Start
+
+### Installation
+
+Install the latest version from PyPI:
+
+```bash
+# Basic installation with SQLite support
+pip install guaro
+
+# With specific database support
+pip install "guaro[postgres]"     # PostgreSQL
+pip install "guaro[mysql]"        # MySQL
+pip install "guaro[mongodb]"      # MongoDB
+pip install "guaro[all-databases]" # All databases
+
+# Development version from source
+git clone https://github.com/Alazar42/Guaro.git
+cd Guaro
+pip install -e ".[all-databases,dev]"
+```
+
+**See [Installation & Setup Guide](docs/INSTALLATION.md) for detailed setup instructions and environment configuration.**
+
+### Basic Example
+
+```python
+from guaro import API, Model, Router, DatabaseEngine
+
+# Define your models
+class User(Model):
+    id: int
+    name: str
+    email: str
+
+class Post(Model):
+    id: int
+    title: str
+    body: str
+    author: "User"
+
+# Configure API
+api = API(database={
+    "engine": DatabaseEngine.POSTGRESQL,
+    "url": "postgresql+asyncpg://user:pass@localhost/dbname",
+    "auto_migrate": True,  # Automatic schema creation
+})
+
+# Register models
+api.register_model(User)
+api.register_model(Post)
+
+# Create routes
+router = Router(prefix="/users")
+
+@router.get("/")
+async def list_users() -> list[User]:
+    return await User.all()
+
+@router.get("/{id}")
+async def get_user(id: int) -> User | None:
+    return await User.find(id)
+
+api.register_router(router)
+
+# Run
+if __name__ == "__main__":
+    api.run(mode="hybrid")  # REST + GraphQL
+```
+
+## 📚 Documentation
+
+Full documentation available at [docs/README.md](docs/README.md) with learning paths and guides:
+
+### Getting Started
+- **[Installation & Setup](docs/INSTALLATION.md)** - Installation methods (pip, clone, Poetry)
+- **[Quick Start Tutorial](docs/INSTALLATION.md#quick-setup-walkthrough)** - Build your first API in 5 minutes
+
+### Core Concepts
+- **[Models & Data](docs/MODELS.md)** - Define models with relationships
+- **[REST Routing](docs/ROUTING.md)** - Create REST endpoints
+- **[Database Configuration](docs/DATABASE.md)** - All supported databases
+- **[GraphQL](docs/GRAPHQL.md)** - GraphQL schema and queries
+
+### Advanced Topics
+- **[Middleware & Authentication](docs/MIDDLEWARE.md)** - Security and authorization
+- **[Dependency Injection](docs/DEPENDENCY_INJECTION.md)** - Service management
+- **[Developer Guide](docs/DEVELOPMENT.md)** - Architecture and testing
+
+### Contributing & Deployment
+- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to Guaro
+- **[Development Setup](DEVELOPMENT_SETUP.md)** - Local development environment
+- **[Publishing Guide](PUBLISH.md)** - Deploying to PyPI
+- **[Changelog](CHANGELOG.md)** - Version history and roadmap
+
+## 🛠️ To Get Started
+
+1. **Users**: Follow the [Installation & Setup](docs/INSTALLATION.md) guide
+2. **Developers**: See [Development Setup](DEVELOPMENT_SETUP.md) for cloning and local setup
+3. **Contributors**: Read [Contributing Guide](CONTRIBUTING.md) and [Developer Guide](docs/DEVELOPMENT.md)/
+├── middleware/
+└── guaro/
+```
+
+## Quick start
+
+```bash
+python -m pip install -e .
+python app.py
+```
+
+## Example usage
+
+```python
+from guaro import API, Model, Router, permission, require_auth
+
+
+class User(Model):
+    id: int
+    name: str
+    email: str
+
+
+router = Router(prefix="/users")
+
+
+@router.get("/")
+@require_auth
+def get_users():
+    return User.all()
+
+
+api = API()
+api.register_model(User)
+api.register_router(router)
+api.run(mode="hybrid")
+```
+
+## Database Configuration
+
+Guaro supports fully externalized, environment-driven database configuration. Configuration is decoupled from application code and can be environment-specific (dev/staging/prod).
+
+### Configuration Patterns
+
+#### Pattern 1: Default Configuration (Automatic SQLite)
+
+Works out of the box with zero configuration:
+
+```python
+from guaro import API
+
+api = API()  # Automatically uses sqlite+aiosqlite:///guaro.db
+api.run()
+```
+
+#### Pattern 2: Inline Configuration
+
+Convenient for quick prototypes and testing:
+
+```python
+from guaro import API, DatabaseEngine
+
+api = API(
+    database={
+        "url": "sqlite+aiosqlite:///local.db",
+        "engine": DatabaseEngine.SQLITE,
+        "auto_migrate": True,
+        "pool_size": 2,
+        "echo": True,
+    }
+)
+api.run()
+```
+
+#### Pattern 3: External Configuration (Recommended)
+
+Production-grade pattern — configuration is isolated from application code:
+
+**config.py:**
+```python
+from guaro import DatabaseEngine
+
+# Development
+dev_config = {
+    "url": "sqlite+aiosqlite:///guaro_dev.db",
+    "engine": DatabaseEngine.SQLITE,
+    "auto_migrate": True,
+}
+
+# Staging
+staging_config = {
+    "url": "postgresql+asyncpg://user:pass@db-staging.internal/guaro_staging",
+    "engine": DatabaseEngine.POSTGRESQL,
+    "auto_migrate": True,
+    "pool_size": 10,
+}
+
+# Production
+prod_config = {
+    "url": "postgresql+asyncpg://user:pass@db-prod.internal/guaro_prod",
+    "engine": DatabaseEngine.POSTGRESQL,
+    "auto_migrate": False,  # Migrations run separately
+    "pool_size": 20,
+}
+
+# Load based on environment
+import os
+environment = os.getenv("ENVIRONMENT", "dev")
+database_config = locals()[f"{environment}_config"]
+```
+
+**app.py:**
+```python
+from guaro import API
+from config import database_config
+
+api = API(database=database_config)
+api.run()
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | str | `"sqlite+aiosqlite:///guaro.db"` | Database connection URL |
+| `engine` | DatabaseEngine | inferred from URL or SQLITE | Database engine type |
+| `auto_migrate` | bool | `True` | Run migrations automatically on startup |
+| `pool_size` | int | `5` | Connection pool size |
+| `pool_pre_ping` | bool | `True` | Test connections before use |
+| `echo` | bool | `False` | Log all SQL statements |
+| `timeout` | int | `30` | Connection timeout in seconds |
+| `extra` | dict | `{}` | Engine-specific options |
+
+### Supported Engines
+
+```python
+from guaro import DatabaseEngine
+
+DatabaseEngine.SQLITE      # SQLite (default)
+DatabaseEngine.POSTGRESQL # PostgreSQL
+DatabaseEngine.MYSQL      # MySQL
+DatabaseEngine.MONGODB    # MongoDB
+DatabaseEngine.MEMORY     # In-memory cache
+```
+
+### URL Format
+
+Guaro normalizes URLs into transport strings that are passed to adapters. The engine determines how the URL is interpreted:
+
+- **SQLite**: `sqlite+aiosqlite:///path/to/db.db`
+- **PostgreSQL**: `postgresql+asyncpg://user:pass@host:port/dbname`
+- **MySQL**: `mysql+aiomysql://user:pass@host:port/dbname`
+- **MongoDB**: `mongodb://user:pass@host:port/dbname`
+- **Custom**: `https://db.api.company.com/api` (engine must be specified)
+
+### Environment-Based Configuration
+
+For multi-environment deployments:
+
+```bash
+# Development (automatic SQLite)
+python app.py
+
+# Staging environment
+export ENVIRONMENT=staging
+python app.py
+
+# Production environment
+export ENVIRONMENT=prod
+python app.py
+```
+
+In `config.py`:
+```python
+import os
+
+environment = os.getenv("ENVIRONMENT", "dev")
+database_config = locals()[f"{environment}_config"]
+```
+
+### Advanced Configuration
+
+With extra options for engine-specific settings:
+
+```python
+database_config = {
+    "url": "postgresql+asyncpg://user@localhost/guaro",
+    "engine": DatabaseEngine.POSTGRESQL,
+    "pool_size": 15,
+    "pool_pre_ping": True,
+    "echo": False,
+    "timeout": 45,
+    "extra": {
+        "ssl": "require",
+        "application_name": "guaro_api",
+        "statement_cache_size": 100,
+    },
+}
+```
+
+
+
+This repository contains a production-oriented MVP architecture, not a finished distributed system. The implementation focuses on:
+
+- unified metadata registration
+- shared execution and planning
+- automatic REST and GraphQL generation
+- request-scoped batching and caching hooks
+
+## Startup modes
+
+- `rest` serves only REST routes
+- `graphql` serves only GraphQL
+- `hybrid` serves both simultaneously