fluidkit 0.1.0__py3-none-any.whl

fluidkit/__init__.py

@@ -0,0 +1,47 @@
+"""
+FluidKit - Automatic TypeScript client code generation for FastAPI
+"""
+
+__version__ = "2.0.0"
+
+def _check_dependencies():
+    """Check for required dependencies and provide helpful error messages"""
+    missing = []
+    
+    try:
+        import fastapi
+    except ImportError:
+        missing.append("fastapi")
+    
+    try:
+        import pydantic
+    except ImportError:
+        missing.append("pydantic")
+    
+    if missing:
+        deps = " and ".join(missing)
+        raise ImportError(
+            f"FluidKit requires {deps} to be installed.\n"
+            f"Install with: pip install {' '.join(missing)}\n"
+            f"FluidKit works with your existing {deps} versions."
+        )
+
+# Check dependencies on import
+_check_dependencies()
+
+# Import main API only after dependency check
+from .core.schema import LanguageType
+from .core.integrator import integrate, introspect_only, generate_only
+
+__all__ = [
+    # Main functions
+    'integrate',
+    'introspect_only', 
+    'generate_only',
+    
+    # Enums
+    'LanguageType',
+    
+    # Version
+    '__version__'
+]

fluidkit/core/__init__.py

@@ -0,0 +1,35 @@
+"""
+Core FluidKit components - for advanced users and plugin developers
+"""
+
+# Main data structures
+from .schema import (
+    FluidKitApp,
+    RouteNode, 
+    ModelNode,
+    Field,
+    FieldAnnotation,
+    FieldConstraints,
+    ModuleLocation,
+    
+    # Enums
+    BaseType,
+    LanguageType,
+    ContainerType, 
+    ParameterType,
+)
+
+# Main integration function
+from .integrator import integrate, introspect_only, generate_only
+
+__all__ = [
+    # Functions
+    'integrate', 'introspect_only', 'generate_only',
+
+    # Data structures
+    'FluidKitApp', 'RouteNode', 'ModelNode', 'Field', 
+    'FieldAnnotation', 'FieldConstraints', 'ModuleLocation',
+
+    # Enums
+    'LanguageType', 'BaseType', 'ContainerType', 'ParameterType',
+]

fluidkit/core/constants.py

@@ -0,0 +1,32 @@
+"""
+FluidKit constants for runtime imports and code generation
+"""
+
+class FluidKitRuntime:
+    """FluidKit runtime function and type names"""
+    
+    # TypeScript runtime exports
+    API_RESULT_TYPE = "ApiResult"
+    GET_BASE_URL_FN = "getBaseUrl"
+    HANDLE_RESPONSE_FN = "handleResponse"
+    
+    # Runtime file locations
+    RUNTIME_DIR = ".fluidkit"
+    RUNTIME_FILE = "runtime.ts"
+    
+    @classmethod
+    def get_all_imports(cls) -> list[str]:
+        """Get all runtime imports for TypeScript"""
+        return [cls.API_RESULT_TYPE, cls.GET_BASE_URL_FN, cls.HANDLE_RESPONSE_FN]
+
+
+class GenerationPaths:
+    """Standard paths for code generation"""
+    
+    FLUIDKIT_DIR = ".fluidkit"
+    TYPESCRIPT_RUNTIME = "runtime.ts"
+    
+    # Future language runtimes
+    PYTHON_RUNTIME = "runtime.py"
+    JAVASCRIPT_RUNTIME = "runtime.js"
+

fluidkit/core/integrator.py

@@ -0,0 +1,299 @@
+"""
+FluidKit V2 App Integration
+
+Main integration API for FluidKit with FastAPI applications with multi-language support.
+Orchestrates route collection, model discovery, and optional code generation.
+"""
+
+import logging
+from enum import Enum
+from pathlib import Path
+from fastapi import FastAPI
+from typing import List, Dict, Tuple
+from fastapi.routing import APIRoute
+
+from fluidkit.introspection.routes import route_to_node
+from fluidkit.introspection.models import discover_models_from_routes
+from fluidkit.core.schema import FluidKitApp, RouteNode, LanguageType
+
+
+logger = logging.getLogger(__name__)
+
+
+def integrate(
+    app: FastAPI, 
+    lang: str = "typescript",
+    strategy: str = "mirror",
+    verbose: bool = False,
+    **options
+) -> Tuple[FluidKitApp, Dict[str, str]]:
+    """
+    Integrate FluidKit with FastAPI app using runtime introspection.
+    
+    Args:
+        app: FastAPI application instance
+        lang: Target language for code generation ("ts"/"typescript" default)
+        strategy: Generation strategy ("co-locate" or "mirror")
+        verbose: Enable detailed logging
+        **options: Additional options (project_root, runtime config, etc.)
+        
+    Returns:
+        (FluidKitApp, generated_files_dict)
+    """
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG, format='%(levelname)s: %(message)s')
+    
+    project_root = options.get('project_root') or str(Path.cwd().resolve())
+    
+    if verbose:
+        logger.info("Starting FluidKit integration with FastAPI app")
+        logger.debug(f"Project root: {project_root}")
+    
+    # Collect and convert routes
+    api_routes = _collect_fastapi_routes(app)
+    route_nodes = _convert_routes_to_nodes(api_routes)
+    
+    # Discover models (project types only)
+    model_nodes = discover_models_from_routes(route_nodes, project_root)
+    
+    # Build FluidKitApp
+    fluid_app = FluidKitApp(
+        models=model_nodes,
+        routes=route_nodes,
+        app_instance=app,
+        metadata={'project_root': project_root, **options}
+    )
+    
+    if verbose:
+        logger.info(f"Introspection complete: {len(route_nodes)} routes, {len(model_nodes)} models")
+    
+    # Generate TypeScript files
+    normalized_lang = _normalize_language(lang)
+    
+    if normalized_lang == LanguageType.TYPESCRIPT:
+        generated_files = _generate_and_write_typescript(fluid_app, strategy, verbose, **options)
+        
+        if not verbose:
+            print(f"FluidKit: Generated {len(generated_files)} TypeScript files ({strategy} strategy)")
+        
+        return fluid_app, generated_files
+    
+    else:
+        raise NotImplementedError(f"Language '{lang}' not yet supported. Currently supported: ts, typescript")
+    
+
+def _generate_and_write_typescript(
+    fluid_app: FluidKitApp, 
+    strategy: str, 
+    verbose: bool,
+    **options
+) -> Dict[str, str]:
+    """Generate TypeScript files and write them to disk."""
+    from fluidkit.generators.typescript.pipeline import generate_typescript_files
+    
+    generated_files = generate_typescript_files(
+        fluid_app=fluid_app,
+        strategy=strategy,
+        **options
+    )
+    
+    _write_generated_files(generated_files, verbose)
+    return generated_files
+
+
+def _write_generated_files(generated_files: Dict[str, str], verbose: bool):
+    """Write generated files to disk with auto-generated headers."""
+    for file_path, content in generated_files.items():
+        try:
+            file_path_obj = Path(file_path)
+            file_path_obj.parent.mkdir(parents=True, exist_ok=True)
+            
+            header = _get_file_header(file_path_obj.suffix)
+            final_content = header + content
+            
+            with open(file_path_obj, 'w', encoding='utf-8') as f:
+                f.write(final_content)
+            
+            if verbose:
+                logger.debug(f"Generated: {file_path}")
+            
+        except Exception as e:
+            error_msg = f"Failed to write {file_path}: {e}"
+            if verbose:
+                logger.error(error_msg)
+            else:
+                print(f"❌ {error_msg}")
+
+
+def _get_file_header(file_extension: str) -> str:
+    """Get auto-generated file header based on file type."""
+    if file_extension == '.ts':
+        return '''/**
+ * Auto-generated by FluidKit from FastAPI routes and models - DO NOT EDIT
+ * Changes will be overwritten on regeneration.
+ */
+
+'''
+    elif file_extension == '.py':
+        return '''"""
+Auto-generated by FluidKit from FastAPI routes and models - DO NOT EDIT
+Changes will be overwritten on regeneration.
+"""
+
+'''
+    else:
+        return '''/**
+ * Auto-generated by FluidKit from FastAPI routes and models - DO NOT EDIT
+ * Changes will be overwritten on regeneration.
+ */
+
+ '''
+
+
+def _normalize_language(lang: str) -> LanguageType:
+    """Normalize language string to LanguageType enum."""
+    lang_lower = lang.lower()
+    
+    if lang_lower in ["ts", "typescript"]:
+        return LanguageType.TYPESCRIPT
+    
+    else:
+        valid_langs = ["ts", "typescript"]
+        raise ValueError(f"Unsupported language '{lang}'. Supported: {', '.join(valid_langs)}")
+    
+
+def _collect_fastapi_routes(app: FastAPI) -> List[APIRoute]:
+    """Collect user-defined API routes from FastAPI app."""
+    user_routes = []
+    
+    for route in app.routes:
+        if isinstance(route, APIRoute) and _is_user_defined_route(route):
+            user_routes.append(route)
+    
+    return user_routes
+
+
+def _convert_routes_to_nodes(api_routes: List[APIRoute]) -> List[RouteNode]:
+    """Convert FastAPI APIRoute objects to RouteNode objects."""
+    route_nodes = []
+    
+    for route in api_routes:
+        try:
+            route_node = route_to_node(route)
+            if route_node:
+                route_nodes.append(route_node)
+        except Exception as e:
+            logger.warning(f"Failed to convert route {route.path}: {e}")
+            continue
+    
+    return route_nodes
+
+
+def _is_user_defined_route(route: APIRoute) -> bool:
+    """Determine if route is user-defined using module-based filtering."""
+    endpoint = route.endpoint
+    
+    if (not endpoint or not callable(endpoint) or 
+        not hasattr(endpoint, '__name__') or endpoint.__name__ == '<lambda>' or
+        not hasattr(endpoint, '__module__') or not route.methods):
+        return False
+    
+    endpoint_module = endpoint.__module__
+    system_prefixes = ('fastapi.', 'starlette.')
+    
+    if any(endpoint_module.startswith(prefix) for prefix in system_prefixes):
+        return False
+    
+    valid_methods = {'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE'}
+    if not any(method in valid_methods for method in route.methods):
+        return False
+    
+    if hasattr(endpoint, 'app') and hasattr(endpoint, '__call__'):
+        return False
+    
+    return True
+
+
+def introspect_only(app: FastAPI, **options) -> FluidKitApp:
+    """Convenience function for introspection only (no code generation)."""
+    project_root = options.get('project_root') or str(Path.cwd().resolve())
+    
+    api_routes = _collect_fastapi_routes(app)
+    route_nodes = _convert_routes_to_nodes(api_routes)
+    model_nodes = discover_models_from_routes(route_nodes, project_root)
+    
+    fluid_app = FluidKitApp(
+        models=model_nodes,
+        routes=route_nodes,
+        app_instance=app,
+        metadata={'project_root': project_root, **options}
+    )
+    
+    print(f"FluidKit: Introspected {len(route_nodes)} routes, {len(model_nodes)} models")
+    return fluid_app
+
+
+def generate_only(app: FastAPI, strategy: str = "mirror", **options) -> Dict[str, str]:
+    """Convenience function to generate files without writing to disk."""
+    from fluidkit.generators.typescript.pipeline import generate_typescript_files
+    
+    project_root = options.get('project_root') or str(Path.cwd().resolve())
+    
+    api_routes = _collect_fastapi_routes(app)
+    route_nodes = _convert_routes_to_nodes(api_routes)
+    model_nodes = discover_models_from_routes(route_nodes, project_root)
+    
+    fluid_app = FluidKitApp(
+        models=model_nodes,
+        routes=route_nodes,
+        app_instance=app,
+        metadata={'project_root': project_root, **options}
+    )
+    
+    generated_files = generate_typescript_files(
+        fluid_app=fluid_app,
+        strategy=strategy,
+        **options
+    )
+    
+    print(f"FluidKit: Generated {len(generated_files)} TypeScript files ({strategy} strategy) - not written to disk")
+    return generated_files
+
+
+# === TESTING FUNCTION === #
+
+def test_integration():
+    """Test the integration with file writing."""
+    try:
+        from tests.sample.app import app
+        
+        print("=== FLUIDKIT V2 INTEGRATION TEST ===")
+        
+        # Test 1: Default integration (generates and writes files)
+        print("\n1. Default integration (mirror strategy):")
+        fluid_app, files = integrate(app)
+        
+        # Test 2: Co-locate strategy
+        print("\n2. Co-locate strategy:")
+        fluid_app, files = integrate(app, strategy="co-locate")
+        
+        # Test 3: Introspection only
+        print("\n3. Introspection only:")
+        fluid_app = introspect_only(app)
+        
+        # Test 4: Generate only (don't write)
+        print("\n4. Generate only (no file writing):")
+        files = generate_only(app)
+        
+        print("\n✅ All tests passed!")
+        
+    except ImportError:
+        print("❌ Could not import v2.examples.test - ensure example files exist")
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    test_integration()