half-orm-gen 1.0.0a1__py3-none-any.whl

half_orm_gen/__init__.py

@@ -0,0 +1,16 @@
+"""
+half-orm-gen — API and frontend generation for halfORM projects.
+
+Decorate halfORM relation methods with ``@tools.api_*`` and run
+``half_orm gen`` to produce a ready-to-run application.
+
+Quick start::
+
+    from half_orm_gen import tools
+
+    class MyTable(MODEL.get_relation_class('schema.my_table')):
+
+        @tools.api_get('/items/{id: uuid}', guards=['connected'])
+        async def get_item(self, request: "Request"):
+            ...
+"""

half_orm_gen/api_routes.py

@@ -0,0 +1,224 @@
+"""
+Generation of Litestar route handlers from @api_* decorated halfORM methods.
+"""
+
+import importlib
+import inspect
+import re
+from typing import Iterable, Tuple, Type
+
+from half_orm.relation import Relation
+
+from half_orm_gen import templates as T
+
+_RE_PATH_VAR = re.compile(r'\{([^:]*):([^\}]*)\}')
+
+_LITESTAR_INTERNAL_PARAMS = {
+    'operation_class', 'operation_id', 'tags', 'summary',
+    'response_description', 'responses', 'deprecated',
+    'cache', 'etag', 'return_dto', 'dto', 'type_encoders',
+    'sync_to_thread', 'opt', 'signature_namespace',
+    'include_in_schema', 'security', 'middleware',
+}
+
+_LITESTAR_DEFAULT_VALUES = {
+    'cache': False,
+    'deprecated': False,
+    'sync_to_thread': True,
+    'include_in_schema': True,
+}
+
+
+def _path_params(api_path: str) -> str:
+    parts = [f'{var}: Any' for var, _ in re.findall(_RE_PATH_VAR, api_path)]
+    return ', '.join(parts)
+
+
+def _annotation_str(annotation) -> str:
+    """Return a valid Python expression string for a type annotation."""
+    if hasattr(annotation, '__name__'):
+        mod = getattr(annotation, '__module__', None)
+        if mod and mod != 'builtins':
+            return f'{mod}.{annotation.__name__}'
+        return annotation.__name__
+    if hasattr(annotation, '__qualname__'):
+        mod = getattr(annotation, '__module__', None)
+        if mod and mod != 'builtins':
+            return f'{mod}.{annotation.__qualname__}'
+        return annotation.__qualname__
+    return str(annotation)
+
+
+def _query_params(signature: inspect.Signature):
+    params_decl = []
+    params_call = []
+    for name, param in signature.parameters.items():
+        if name == 'self':
+            continue
+        params_call.append(name)
+        decl = name
+        if param.annotation is not inspect.Parameter.empty:
+            decl = f'{decl}: {_annotation_str(param.annotation)}'
+        if param.default is not inspect.Parameter.empty:
+            decl = f'{decl}={param.default!r}'
+        params_decl.append(decl)
+    return ', '.join(params_decl), ', '.join(params_call)
+
+
+def _extract_guards(litestar_params: dict) -> list:
+    guards = litestar_params.get('guards') or []
+    result = []
+    for g in guards:
+        if hasattr(g, '__name__'):
+            result.append(g.__name__)
+        elif isinstance(g, str):
+            result.append(g)
+        else:
+            result.append(str(g))
+    return result
+
+
+def _format_litestar_args(
+    litestar_params: dict, guards_list: list, method_doc: str, api_version
+) -> str:
+    args = []
+
+    if 'path' in litestar_params:
+        version_prefix = f'/v{api_version}' if api_version is not None else ''
+        full_path = f"{version_prefix}{litestar_params['path']}"
+        args.append(f'"{full_path}"')
+
+    kwargs = []
+
+    if guards_list:
+        guards_str = ', '.join(f'guards.{g}' for g in guards_list)
+        kwargs.append(f'guards=[{guards_str}]')
+
+    if litestar_params.get('name'):
+        kwargs.append(f'name="{litestar_params["name"]}"')
+
+    desc_parts = [p for p in [method_doc, f"Guards: {', '.join(guards_list)}" if guards_list else ''] if p]
+    if desc_parts:
+        kwargs.append(f'description="""{chr(10).join(desc_parts)}"""')
+    elif litestar_params.get('description'):
+        kwargs.append(f'description="""{litestar_params["description"]}"""')
+
+    for key, value in litestar_params.items():
+        if key in ('path', 'guards', 'name', 'description'):
+            continue
+        if key in _LITESTAR_INTERNAL_PARAMS:
+            continue
+        if key in _LITESTAR_DEFAULT_VALUES and value == _LITESTAR_DEFAULT_VALUES[key]:
+            continue
+        if hasattr(value, '__class__'):
+            cls = value.__class__
+            if 'Empty' in str(cls) or 'enum' in str(cls).lower():
+                continue
+            if cls.__module__ not in ('builtins', '__builtin__'):
+                continue
+        if isinstance(value, str):
+            kwargs.append(f'{key}="{value}"')
+        elif isinstance(value, bool):
+            kwargs.append(f'{key}={value}')
+        elif isinstance(value, (int, float)):
+            kwargs.append(f'{key}={value}')
+        elif value is not None:
+            kwargs.append(f'{key}={value!r}')
+
+    return ', '.join(args + kwargs)
+
+
+def generate_api_routes(
+    classes: Iterable[Tuple[Type[Relation], str]],
+    api_version,
+) -> Tuple[list, list]:
+    """Scan @api_* decorated methods and return (blocks, route_handler_names).
+
+    Also returns the set of (module_str, verb) pairs already covered, so the
+    CRUD generator can skip them.
+    """
+    blocks: list[str] = []
+    route_handlers: list[str] = []
+    covered: set[tuple] = set()   # (module_str, verb) covered by @api_*
+
+    for relation, _relation_type in classes:
+        module_str   = relation.__module__
+        schema       = '.'.join(module_str.split('.')[:-1])
+        module_name  = module_str.split('.')[-1]
+        module_alias = module_str.replace('.', '_')
+
+        schema_cap   = ''.join(p.capitalize() for p in relation._schemaname.split('.'))
+
+        api_methods = [
+            (name, method)
+            for name, method in inspect.getmembers(relation, predicate=inspect.isfunction)
+            if getattr(method, 'is_api_route', False) and name in relation.__dict__
+        ]
+
+        if not api_methods:
+            mod = importlib.import_module(module_str)
+            if hasattr(mod, 'API'):
+                for func in mod.API:
+                    alias = str(func).replace('.', '_')
+                    fname = str(func).split('.')[-1]
+                    blocks.append(T.DIRECT_API.format(
+                        module_str=module_str,
+                        function=fname,
+                        function_alias=alias,
+                    ))
+                    route_handlers.append(alias)
+            continue
+
+        blocks.append(T.IMPORT.format(
+            schema=schema,
+            module_name=module_name,
+            module_alias=module_alias,
+        ))
+
+        for name, method in api_methods:
+            litestar_params = method.litestar_params
+            metadata        = method.metadata
+            verb            = method.http_method
+            guards_list     = _extract_guards(litestar_params)
+            sig             = metadata.get('signature', inspect.signature(method))
+            query_params, call_params = _query_params(sig)
+            litestar_args = _format_litestar_args(
+                litestar_params, guards_list, metadata.get('documentation', ''),
+                api_version,
+            )
+
+            full_name = f'{module_alias}_{name}'
+            template  = T.HTTP.get(verb)
+            if template is None:
+                print(f'  warning: no template for HTTP method {verb} ({module_str}.{name})')
+                continue
+
+            print(f'  {verb:6s} {litestar_params.get("path", "")} → {full_name}')
+
+            blocks.append(template.format(
+                full_name    = full_name,
+                litestar_args= litestar_args,
+                dc_name      = relation._ho_dataclass_name(),
+                module_alias = module_alias,
+                class_name   = relation.__name__,
+                path_params  = _path_params(litestar_params.get('path', '')),
+                query_params = query_params,
+                params       = call_params,
+                name         = name,
+            ))
+            route_handlers.append(full_name)
+            covered.add((module_str, verb))
+
+        mod = importlib.import_module(module_str)
+        if hasattr(mod, 'API'):
+            for func in mod.API:
+                alias = str(func).replace('.', '_')
+                fname = str(func).split('.')[-1]
+                blocks.append(T.DIRECT_API.format(
+                    module_str=module_str,
+                    function=fname,
+                    function_alias=alias,
+                ))
+                route_handlers.append(alias)
+
+    return blocks, route_handlers, covered

half_orm_gen/cli_extension.py

@@ -0,0 +1,170 @@
+"""
+CLI extension for half-orm-gen.
+
+Registers the ``gen`` sub-command group under the ``half_orm`` CLI::
+
+    half_orm gen api
+    half_orm gen frontend
+"""
+
+import sys
+from pathlib import Path
+import click
+from half_orm.cli_utils import create_and_register_extension
+
+_VERSION_FILE = Path('api') / '.api_version'
+
+
+def _read_api_version() -> int:
+    try:
+        return int(_VERSION_FILE.read_text().strip())
+    except (FileNotFoundError, ValueError):
+        return 0
+
+
+def _write_api_version(version: int) -> None:
+    _VERSION_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _VERSION_FILE.write_text(str(version) + '\n')
+
+
+def add_commands(main_group):
+    """Required entry point for halfORM extensions."""
+
+    @create_and_register_extension(main_group, sys.modules[__name__])
+    def gen():
+        """Generate a Litestar API and frontend backoffice from a halfORM project."""
+        pass
+
+    @gen.command('api')
+    @click.option(
+        '--dry-run', is_flag=True, default=False,
+        help='Print what would be generated without writing any file.',
+    )
+    @click.option(
+        '--bump', is_flag=True, default=False,
+        help='Bump the API version to N+1 (asks for confirmation).',
+    )
+    @click.option('--litestar', 'framework', flag_value='litestar',
+                  help='Generate a Litestar app.')
+    @click.option('--fastapi', 'framework', flag_value='fastapi',
+                  help='Generate a FastAPI app (no @api_* support).')
+    def api(dry_run, bump, framework):
+        """Generate api/app.py from CRUD_ACCESS and @api_* decorated methods.
+
+        The API version is read from api/.api_version (default: 0).
+        Use --bump to move to N+1; the new value is saved for future runs.
+        To revert a mistaken bump: git checkout api/.api_version.
+
+        Must be run from inside a half-orm-dev project directory.
+        On first run, missing scaffolding files (guards.py, custom/) are
+        created automatically and are never overwritten on subsequent runs.
+        """
+        try:
+            from half_orm_dev.repo import Repo
+        except ImportError:
+            click.echo(
+                'Error: half_orm_dev is not installed. '
+                'Install it with: pip install half-orm-dev',
+                err=True,
+            )
+            sys.exit(1)
+
+        try:
+            repo = Repo()
+        except Exception as exc:
+            click.echo(
+                f'Error: could not load the halfORM project ({exc}).\n'
+                'Make sure you are inside a half-orm-dev project directory.',
+                err=True,
+            )
+            sys.exit(1)
+
+        if not framework:
+            click.echo('Error: specify --litestar or --fastapi.', err=True)
+            sys.exit(1)
+
+        api_version = _read_api_version()
+
+        if bump:
+            next_version = api_version + 1
+            click.confirm(
+                f'Bump API version from v{api_version} to v{next_version}?',
+                abort=True,
+            )
+            _write_api_version(next_version)
+            api_version = next_version
+
+        if dry_run:
+            click.echo(
+                f'[dry-run] would generate api/app.py ({framework}) for project: {repo.name}'
+                f' (v{api_version})'
+            )
+            return
+
+        from half_orm_gen.generate import GenApi
+        click.echo(f'Generating {framework} API for project: {repo.name} (v{api_version})')
+        GenApi(repo, api_version=api_version, framework=framework)
+        if framework == 'litestar':
+            click.echo('\nTo run:  litestar --app api.app:application run --reload')
+        else:
+            click.echo('\nTo run:  uvicorn api.app:application --reload')
+
+    @gen.command('frontend')
+    @click.option('--svelte',   'framework', flag_value='svelte',
+                  help='Generate a SvelteKit 5 application.')
+    @click.option('--angular',  'framework', flag_value='angular',
+                  help='Generate an Angular 22 application (signal-based).')
+    @click.option('--output', default=None,
+                  help='Output directory (default: frontend/<framework>).')
+    def frontend(framework, output):
+        """Generate a frontend backoffice from CRUD_ACCESS introspection.
+
+        Produces a complete SvelteKit or Angular application with Tailwind CSS,
+        per-resource List/CreateForm/DetailView components in generated/,
+        admin-only route pages, and a minimal JWT login.
+
+        Must be run from inside a half-orm-dev project directory.
+        """
+        try:
+            from half_orm_dev.repo import Repo
+        except ImportError:
+            click.echo(
+                'Error: half_orm_dev is not installed. '
+                'Install it with: pip install half-orm-dev',
+                err=True,
+            )
+            sys.exit(1)
+
+        try:
+            repo = Repo()
+        except Exception as exc:
+            click.echo(
+                f'Error: could not load the halfORM project ({exc}).\n'
+                'Make sure you are inside a half-orm-dev project directory.',
+                err=True,
+            )
+            sys.exit(1)
+
+        api_version = _read_api_version()
+        output_dir = Path(output) if output else Path('frontend') / framework
+
+        if not framework:
+            click.echo('Error: specify --svelte or --angular.', err=True)
+            sys.exit(1)
+        if framework == 'svelte':
+            from half_orm_gen.gen_app.svelte import SvelteAppGenerator
+            generator = SvelteAppGenerator()
+        elif framework == 'angular':
+            from half_orm_gen.gen_app.angular import AngularAppGenerator
+            generator = AngularAppGenerator()
+        else:
+            click.echo(f'Error: unknown framework "{framework}".', err=True)
+            sys.exit(1)
+
+        from half_orm_gen.gen_app import GenApp
+        click.echo(f'Generating {framework} application → {output_dir}')
+        GenApp(repo, generator=generator, output_dir=output_dir, api_version=api_version)
+        if framework == 'svelte':
+            click.echo(f'\nTo run:  cd {output_dir} && npm install && npm run dev')
+        elif framework == 'angular':
+            click.echo(f'\nTo run:  cd {output_dir} && npm install && npm start')