jec-api 0.0.1__tar.gz

jec_api-0.0.1/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

jec_api-0.0.1/.gitignore

@@ -0,0 +1,29 @@
+# Byte-compiled
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db

jec_api-0.0.1/LICENSE

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

jec_api-0.0.1/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: jec-api
+Version: 0.0.1
+Summary: Beta version of JEC API
+Project-URL: Homepage, https://github.com/alpheay/jec
+Project-URL: Repository, https://github.com/alpheay/jec
+Author: Nik
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,class-based,fastapi,routes,web
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.100.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# JEC-API
+
+## Features
+
+- **Class-Based Routes**: Group related endpoints (e.g., CRUD operations) into a single class.
+- **Auto-Discovery**: Automatically find and register route classes from your project packages.
+- **Smart Method Naming**: API paths and HTTP methods are inferred from your method names (e.g., `get_by_id` becomes `GET /{id}`).
+- **FastAPI Native**: Fully compatible with FastAPI dependencies, models, and OpenAPI generation.
+
+## Installation
+
+```bash
+pip install jec-api
+```
+
+## Quick Start
+
+1. **Define a Route Class**
+
+```python
+# routes.py
+from jec_api import Route
+
+class Users(Route):
+    # Optional: explicitly set path, otherwise defaults to /users
+    # path = "/my-users"
+
+    async def get(self):
+        """List all users"""
+        return [{"id": 1, "name": "Alice"}]
+
+    async def get_by_id(self, id: int):
+        """Get user by ID"""
+        return {"id": id, "name": "Alice"}
+
+    async def post(self, name: str):
+        """Create a user"""
+        return {"id": 2, "name": name}
+```
+
+2. **Create the App**
+
+```python
+# main.py
+from jec_api import Core
+
+core = Core(title="My API")
+
+# Auto-discover routes from a module/package
+core.discover("routes")
+
+# Or register manually
+from routes import Users
+core.register(Users)
+```
+
+3. **Run it**
+
+```bash
+uvicorn main:core --reload
+```
+
+## Usage Guide
+
+### Defining Routes
+
+Inherit from `jec_api.Route` to create a route group. The class name is automatically converted to kebab-case to form the base path (e.g., `UserProfiles` -> `/user-profiles`), unless you override it with the `path` attribute.
+
+### Method Naming Convention
+
+JEC-API parses your method names to determine the HTTP verb and path parameters:
+
+| Method Name | HTTP Verb | Generated Path |
+|-------------|-----------|----------------|
+| `get()` | GET | `/` |
+| `post()` | POST | `/` |
+| `get_by_id(id)` | GET | `/{id}` |
+| `delete_by_id(id)` | DELETE | `/{id}` |
+| `get_users()` | GET | `/users` |
+| `post_batch_update()` | POST | `/batch-update` |
+
+### Path Parameters
+
+To define path parameters, use the `_by_{param}` pattern in your method name.
+For example, `get_by_user_id` will generate a path `/{user_id}`.
+
+### Manual Registration
+
+You can register routes manually if you prefer not to use auto-discovery:
+
+```python
+from my_routes import MyRoute
+app.register(MyRoute, tags=["Custom Tag"])
+```
+
+### Auto-Discovery
+
+The `discover()` method recursively searches the specified package for any classes inheriting from `Route` and registers them.
+
+```python
+app.discover("src.routes")
+```
+
+## License
+
+MIT License

jec_api-0.0.1/README.md

@@ -0,0 +1,106 @@
+# JEC-API
+
+## Features
+
+- **Class-Based Routes**: Group related endpoints (e.g., CRUD operations) into a single class.
+- **Auto-Discovery**: Automatically find and register route classes from your project packages.
+- **Smart Method Naming**: API paths and HTTP methods are inferred from your method names (e.g., `get_by_id` becomes `GET /{id}`).
+- **FastAPI Native**: Fully compatible with FastAPI dependencies, models, and OpenAPI generation.
+
+## Installation
+
+```bash
+pip install jec-api
+```
+
+## Quick Start
+
+1. **Define a Route Class**
+
+```python
+# routes.py
+from jec_api import Route
+
+class Users(Route):
+    # Optional: explicitly set path, otherwise defaults to /users
+    # path = "/my-users"
+
+    async def get(self):
+        """List all users"""
+        return [{"id": 1, "name": "Alice"}]
+
+    async def get_by_id(self, id: int):
+        """Get user by ID"""
+        return {"id": id, "name": "Alice"}
+
+    async def post(self, name: str):
+        """Create a user"""
+        return {"id": 2, "name": name}
+```
+
+2. **Create the App**
+
+```python
+# main.py
+from jec_api import Core
+
+core = Core(title="My API")
+
+# Auto-discover routes from a module/package
+core.discover("routes")
+
+# Or register manually
+from routes import Users
+core.register(Users)
+```
+
+3. **Run it**
+
+```bash
+uvicorn main:core --reload
+```
+
+## Usage Guide
+
+### Defining Routes
+
+Inherit from `jec_api.Route` to create a route group. The class name is automatically converted to kebab-case to form the base path (e.g., `UserProfiles` -> `/user-profiles`), unless you override it with the `path` attribute.
+
+### Method Naming Convention
+
+JEC-API parses your method names to determine the HTTP verb and path parameters:
+
+| Method Name | HTTP Verb | Generated Path |
+|-------------|-----------|----------------|
+| `get()` | GET | `/` |
+| `post()` | POST | `/` |
+| `get_by_id(id)` | GET | `/{id}` |
+| `delete_by_id(id)` | DELETE | `/{id}` |
+| `get_users()` | GET | `/users` |
+| `post_batch_update()` | POST | `/batch-update` |
+
+### Path Parameters
+
+To define path parameters, use the `_by_{param}` pattern in your method name.
+For example, `get_by_user_id` will generate a path `/{user_id}`.
+
+### Manual Registration
+
+You can register routes manually if you prefer not to use auto-discovery:
+
+```python
+from my_routes import MyRoute
+app.register(MyRoute, tags=["Custom Tag"])
+```
+
+### Auto-Discovery
+
+The `discover()` method recursively searches the specified package for any classes inheriting from `Route` and registers them.
+
+```python
+app.discover("src.routes")
+```
+
+## License
+
+MIT License

jec_api-0.0.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jec-api"
+version = "0.0.1"
+description = "Beta version of JEC API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Nik" }
+]
+keywords = ["fastapi", "api", "routes", "class-based", "web"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+    "fastapi>=0.100.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "httpx>=0.24.0",
+    "uvicorn>=0.20.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/alpheay/jec"
+Repository = "https://github.com/alpheay/jec"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jec_api"]

jec_api-0.0.1/src/jec_api/__init__.py

@@ -0,0 +1,7 @@
+"""JEC-API: Define FastAPI routes as classes."""
+
+from .route import Route
+from .router import Core
+ 
+__all__ = ["Route", "Core"]
+__version__ = "0.1.0"

jec_api-0.0.1/src/jec_api/discovery.py

@@ -0,0 +1,145 @@
+"""Auto-discovery of Route classes from packages and directories."""
+
+import importlib
+import importlib.util
+import pkgutil
+import sys
+from pathlib import Path
+from typing import List, Type
+
+from .route import Route
+
+
+def discover_routes(package: str, *, recursive: bool = True) -> List[Type[Route]]:
+    """
+    Discover all Route subclasses in a package or directory.
+    
+    Args:
+        package: Package name (e.g., "routes") or path to directory
+        recursive: Whether to search subdirectories
+    
+    Returns:
+        List of Route subclasses found
+    """
+    route_classes: List[Type[Route]] = []
+    
+    # Check if it's a path or a package name
+    package_path = Path(package)
+    
+    if package_path.is_dir():
+        # It's a directory path
+        route_classes.extend(_discover_from_directory(package_path, recursive))
+    else:
+        # Try as a package name
+        try:
+            route_classes.extend(_discover_from_package(package, recursive))
+        except ModuleNotFoundError:
+            # Maybe it's a relative path from cwd
+            cwd_path = Path.cwd() / package
+            if cwd_path.is_dir():
+                route_classes.extend(_discover_from_directory(cwd_path, recursive))
+            else:
+                raise ValueError(f"Could not find package or directory: {package}")
+    
+    return route_classes
+
+
+def _discover_from_package(package_name: str, recursive: bool) -> List[Type[Route]]:
+    """Discover routes from an installed package."""
+    route_classes: List[Type[Route]] = []
+    
+    package = importlib.import_module(package_name)
+    
+    if not hasattr(package, "__path__"):
+        # Single module, not a package
+        route_classes.extend(_extract_routes_from_module(package))
+        return route_classes
+    
+    # Walk through the package
+    prefix = package_name + "."
+    
+    for importer, modname, ispkg in pkgutil.walk_packages(
+        package.__path__,
+        prefix=prefix,
+    ):
+        if not recursive and ispkg:
+            continue
+        
+        try:
+            module = importlib.import_module(modname)
+            route_classes.extend(_extract_routes_from_module(module))
+        except Exception:
+            # Skip modules that fail to import
+            continue
+    
+    return route_classes
+
+
+def _discover_from_directory(directory: Path, recursive: bool) -> List[Type[Route]]:
+    """Discover routes from a directory of Python files."""
+    route_classes: List[Type[Route]] = []
+    
+    # Add directory to sys.path temporarily if needed
+    dir_str = str(directory.parent.resolve())
+    added_to_path = False
+    
+    if dir_str not in sys.path:
+        sys.path.insert(0, dir_str)
+        added_to_path = True
+    
+    try:
+        pattern = "**/*.py" if recursive else "*.py"
+        
+        for py_file in directory.glob(pattern):
+            if py_file.name.startswith("_"):
+                continue
+            
+            try:
+                module = _load_module_from_file(py_file)
+                if module:
+                    route_classes.extend(_extract_routes_from_module(module))
+            except Exception:
+                # Skip files that fail to import
+                continue
+    finally:
+        if added_to_path:
+            sys.path.remove(dir_str)
+    
+    return route_classes
+
+
+def _load_module_from_file(file_path: Path):
+    """Load a Python module from a file path."""
+    module_name = file_path.stem
+    
+    spec = importlib.util.spec_from_file_location(module_name, file_path)
+    if spec is None or spec.loader is None:
+        return None
+    
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    
+    return module
+
+
+def _extract_routes_from_module(module) -> List[Type[Route]]:
+    """Extract all Route subclasses from a module."""
+    route_classes: List[Type[Route]] = []
+    
+    for name in dir(module):
+        if name.startswith("_"):
+            continue
+        
+        obj = getattr(module, name)
+        
+        # Check if it's a class that inherits from Route (but not Route itself)
+        if (
+            isinstance(obj, type)
+            and issubclass(obj, Route)
+            and obj is not Route
+            and obj.__module__ == module.__name__
+        ):
+            route_classes.append(obj)
+    
+    return route_classes

jec_api-0.0.1/src/jec_api/route.py

@@ -0,0 +1,118 @@
+"""Route base class for defining API endpoints."""
+
+import re
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type
+import inspect
+
+
+# HTTP methods that can be used as method prefixes
+HTTP_METHODS = {"get", "post", "put", "delete", "patch", "options", "head"}
+
+
+class RouteMeta(type):
+    """Metaclass that collects route information from class methods."""
+    
+    def __new__(mcs, name: str, bases: Tuple[type, ...], namespace: Dict[str, Any]) -> type:
+        cls = super().__new__(mcs, name, bases, namespace)
+        
+        # Skip processing for the base Route class itself
+        if name == "Route" and not bases:
+            return cls
+        
+        # Collect endpoint methods
+        cls._endpoints: List[Tuple[str, str, Callable]] = []
+        
+        for attr_name, attr_value in namespace.items():
+            if attr_name.startswith("_"):
+                continue
+            if not callable(attr_value):
+                continue
+            
+            parsed = mcs._parse_method_name(attr_name)
+            if parsed:
+                http_method, sub_path = parsed
+                cls._endpoints.append((http_method, sub_path, attr_value))
+        
+        return cls
+    
+    @staticmethod
+    def _parse_method_name(name: str) -> Optional[Tuple[str, str]]:
+        """
+        Parse method name to extract HTTP method and sub-path.
+        
+        Examples:
+            get -> (GET, /)
+            post -> (POST, /)
+            get_by_id -> (GET, /{id})
+            get_users -> (GET, /users)
+            post_batch -> (POST, /batch)
+            get_user_by_id -> (GET, /user/{id})
+        """
+        parts = name.lower().split("_")
+        
+        if not parts or parts[0] not in HTTP_METHODS:
+            return None
+        
+        http_method = parts[0].upper()
+        
+        if len(parts) == 1:
+            # Just the HTTP method: get, post, etc.
+            return (http_method, "/")
+        
+        # Check for "by_" pattern indicating path parameter
+        path_parts = []
+        i = 1
+        while i < len(parts):
+            if parts[i] == "by" and i + 1 < len(parts):
+                # Convert "by_id" to "{id}"
+                param_name = parts[i + 1]
+                path_parts.append(f"{{{param_name}}}")
+                i += 2
+            else:
+                # Convert to kebab-case path segment
+                path_parts.append(parts[i])
+                i += 1
+        
+        if not path_parts:
+            return (http_method, "/")
+        
+        sub_path = "/" + "/".join(path_parts)
+        return (http_method, sub_path)
+
+
+class Route(metaclass=RouteMeta):
+    """
+    Base class for defining API route endpoints.
+    
+    Inherit from this class and define methods with HTTP method prefixes:
+    - get(), post(), put(), delete(), patch(), options(), head()
+    - get_by_id(id: int) -> GET /{id}
+    - get_users() -> GET /users
+    - post_batch() -> POST /batch
+    
+    Optionally set `path` class attribute to override the auto-generated path.
+    """
+    
+    # Override this to set a custom path instead of deriving from class name
+    path: Optional[str] = None
+    
+    # Set by metaclass
+    _endpoints: List[Tuple[str, str, Callable]] = []
+    
+    @classmethod
+    def get_path(cls) -> str:
+        """Get the base path for this route class."""
+        if cls.path is not None:
+            return cls.path if cls.path.startswith("/") else f"/{cls.path}"
+        
+        # Convert class name to kebab-case path
+        # UserProfiles -> user-profiles
+        name = cls.__name__
+        # Insert hyphens before uppercase letters and lowercase everything
+        kebab = re.sub(r"(?<!^)(?=[A-Z])", "-", name).lower()
+        return f"/{kebab}"
+    
+    @classmethod
+    def get_endpoints(cls) -> List[Tuple[str, str, Callable]]:
+        """Get all endpoint definitions for this route class."""
+        return cls._endpoints

jec_api-0.0.1/src/jec_api/router.py

@@ -0,0 +1,105 @@
+"""Core - FastAPI wrapper with class-based route registration."""
+
+from typing import Any, Callable, List, Type, Optional
+from fastapi import FastAPI, APIRouter
+from fastapi.routing import APIRoute
+
+from .route import Route
+from .discovery import discover_routes
+
+
+class Core(FastAPI):
+    """
+    FastAPI application with class-based route registration.
+    
+    Usage:
+        app = Core()
+        app.discover("routes")  # Auto-discover from package
+        app.register(MyRoute)   # Or register manually
+    """
+    
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._registered_routes: List[Type[Route]] = []
+    
+    def register(self, route_class: Type[Route], **router_kwargs) -> "Core":
+        """
+        Register a Route subclass with the application.
+        
+        Args:
+            route_class: A class that inherits from Route
+            **router_kwargs: Additional kwargs passed to APIRouter (tags, etc.)
+        
+        Returns:
+            Self for method chaining
+        """
+        if not isinstance(route_class, type) or not issubclass(route_class, Route):
+            raise TypeError(f"{route_class} must be a subclass of Route")
+        
+        if route_class is Route:
+            raise ValueError("Cannot register the base Route class directly")
+        
+        base_path = route_class.get_path()
+        endpoints = route_class.get_endpoints()
+        
+        if not endpoints:
+            return self  # No endpoints to register
+        
+        # Create an instance of the route class
+        instance = route_class()
+        
+        # Determine tags from class name if not provided
+        if "tags" not in router_kwargs:
+            router_kwargs["tags"] = [route_class.__name__]
+        
+        # Register each endpoint
+        for http_method, sub_path, method_func in endpoints:
+            # Build full path
+            if sub_path == "/":
+                full_path = base_path
+            else:
+                full_path = base_path.rstrip("/") + sub_path
+            
+            # Bind the method to the instance
+            bound_method = getattr(instance, method_func.__name__)
+            
+            # Get the appropriate router method (get, post, etc.)
+            router_method = getattr(self, http_method.lower())
+            
+            # Register the route
+            router_method(
+                full_path,
+                **router_kwargs,
+            )(bound_method)
+        
+        self._registered_routes.append(route_class)
+        return self
+    
+    def discover(
+        self,
+        package: str,
+        *,
+        recursive: bool = True,
+        **router_kwargs
+    ) -> "Core":
+        """
+        Auto-discover and register Route subclasses from a package.
+        
+        Args:
+            package: Package name or path to discover routes from
+            recursive: Whether to search subdirectories
+            **router_kwargs: Additional kwargs passed to each route's registration
+        
+        Returns:
+            Self for method chaining
+        """
+        route_classes = discover_routes(package, recursive=recursive)
+        
+        for route_class in route_classes:
+            self.register(route_class, **router_kwargs)
+        
+        return self
+    
+    def get_registered_routes(self) -> List[Type[Route]]:
+        """Get a list of all registered Route classes."""
+        return self._registered_routes.copy()