Cleanup: docstrings, models, endpoint params, tests, etc.

aiida_restapi/__init__.py

@@ -1,5 +1,3 @@
-"""AiiDA REST API for data queries and workflow managment."""
+"""AiiDA REST API for data queries and workflow management."""
 
 __version__ = '0.1.0a1'
-
-from .main import app  # noqa: F401

aiida_restapi/cli/main.py

@@ -0,0 +1,31 @@
+import os
+
+import click
+import uvicorn
+
+
+@click.group()
+def cli() -> None:
+    """AiiDA REST API management CLI."""
+
+
+@cli.command()
+@click.option('--host', default='127.0.0.1', show_default=True)
+@click.option('--port', default=8000, show_default=True, type=int)
+@click.option('--read-only', is_flag=True)
+@click.option('--watch', is_flag=True)
+def start(read_only: bool, watch: bool, host: str, port: int) -> None:
+    """Start the AiiDA REST API service."""
+
+    os.environ['AIIDA_RESTAPI_READ_ONLY'] = '1' if read_only else '0'
+
+    click.echo(f'Starting REST API (read_only={read_only}, watch={watch}) on {host}:{port}')
+
+    uvicorn.run(
+        'aiida_restapi.main:create_app',
+        host=host,
+        port=port,
+        reload=watch,
+        reload_dirs=['aiida_restapi'],
+        factory=True,
+    )

aiida_restapi/common/errors.py

@@ -0,0 +1,87 @@
+"""Common error models.
+
+These are used in ReDoc and OpenAPI documentation to describe error responses.
+"""
+
+import pydantic as pdt
+
+
+class JsonDecodingError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='The provided JSON input is invalid.',
+        examples=['Malformed JSON string'],
+    )
+
+
+class NonExistentError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='The requested resource does not exist.',
+        examples=['No result was found'],
+    )
+
+
+class MultipleObjectsError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='Multiple resources were found when exactly one was expected.',
+        examples=['Multiple results were found'],
+    )
+
+
+class StoringNotAllowedError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='Attempt to store the new resource was rejected.',
+        examples=['Resource cannot be stored'],
+    )
+
+
+class InvalidInputError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='The input provided was invalid.',
+        examples=['Input value out of range'],
+    )
+
+
+class InvalidNodeTypeError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='The node type does not exist.',
+        examples=['Unknown node type: "data.nonexistent.NonExistentNode"'],
+    )
+
+
+class InvalidLicenseError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='The operation is not permitted due to licensing restrictions.',
+        examples=['Operation not permitted under current license'],
+    )
+
+
+class DaemonError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='An error occurred while interacting with the AiiDA daemon.',
+        examples=[
+            'The daemon is not running',
+            'Failed to start daemon',
+            'The daemon is already running',
+        ],
+    )
+
+
+class InvalidOperationError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='The requested operation is invalid.',
+        examples=['Cannot submit a process with `store_provenance=False`'],
+    )
+
+
+class RequestValidationError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='The request parameters failed validation.',
+        examples=['Invalid query parameter: "sort"'],
+    )
+
+
+class QueryBuilderError(pdt.BaseModel):
+    detail: str = pdt.Field(
+        description='An error occurred while processing the QueryBuilder request.',
+        examples=['Invalid QueryBuilder query structure'],
+    )

aiida_restapi/common/exceptions.py

@@ -0,0 +1,5 @@
+"""Common exception classes."""
+
+
+class QueryBuilderException(Exception):
+    """Exception raised for errors during QueryBuilder execution."""

aiida_restapi/common/pagination.py

@@ -0,0 +1,20 @@
+"""Pagination utilities."""
+
+from __future__ import annotations
+
+import typing as t
+
+import pydantic as pdt
+
+ResultType = t.TypeVar('ResultType')
+
+__all__ = [
+    'PaginatedResults',
+]
+
+
+class PaginatedResults(pdt.BaseModel, t.Generic[ResultType]):
+    total: int
+    page: int
+    page_size: int
+    data: list[ResultType]

aiida_restapi/common/query.py

@@ -0,0 +1,78 @@
+"""REST API query utilities."""
+
+from __future__ import annotations
+
+import json
+import typing as t
+
+import pydantic as pdt
+from fastapi import Query
+
+
+class QueryParams(pdt.BaseModel):
+    filters: dict[str, t.Any] = pdt.Field(
+        default_factory=dict,
+        description='AiiDA QueryBuilder filters',
+        examples=[
+            {'node_type': {'==': 'data.core.int.Int.'}},
+            {'attributes.value': {'>': 42}},
+        ],
+    )
+    order_by: str | list[str] | dict[str, t.Any] | None = pdt.Field(
+        None,
+        description='Fields to sort by',
+        examples=[
+            {'attributes.value': 'desc'},
+        ],
+    )
+    page_size: pdt.PositiveInt = pdt.Field(
+        10,
+        description='Number of results per page',
+        examples=[10],
+    )
+    page: pdt.PositiveInt = pdt.Field(
+        1,
+        description='Page number',
+        examples=[1],
+    )
+
+
+def query_params(
+    filters: str | None = Query(
+        None,
+        description='AiiDA QueryBuilder filters as JSON string',
+    ),
+    order_by: str | None = Query(
+        None,
+        description='Comma-separated list of fields to sort by',
+    ),
+    page_size: pdt.PositiveInt = Query(
+        10,
+        description='Number of results per page',
+    ),
+    page: pdt.PositiveInt = Query(
+        1,
+        description='Page number',
+    ),
+) -> QueryParams:
+    """Parse query parameters into a structured object.
+
+    :param filters: AiiDA QueryBuilder filters as JSON string.
+    :param order_by: Comma-separated string of fields to sort by.
+    :param page_size: Number of results per page.
+    :param page: Page number.
+    :return: Structured query parameters.
+    :raises HTTPException: If filters cannot be parsed as JSON.
+    """
+    query_filters: dict[str, t.Any] = {}
+    query_order_by: str | list[str] | dict[str, t.Any] | None = None
+    if filters:
+        query_filters = json.loads(filters)
+    if order_by:
+        query_order_by = json.loads(order_by)
+    return QueryParams(
+        filters=query_filters,
+        order_by=query_order_by,
+        page_size=page_size,
+        page=page,
+    )

aiida_restapi/common/types.py

@@ -0,0 +1,13 @@
+"""Common type variables."""
+
+from __future__ import annotations
+
+import typing as t
+
+from aiida import orm
+
+EntityType = t.TypeVar('EntityType', bound='orm.Entity')
+EntityModelType = t.TypeVar('EntityModelType', bound='orm.Entity.Model')
+
+NodeType = t.TypeVar('NodeType', bound='orm.Node')
+NodeModelType = t.TypeVar('NodeModelType', bound='orm.Node.Model')

aiida_restapi/config.py

@@ -1,5 +1,7 @@
 """Configuration of API"""
 
+from aiida_restapi import __version__
+
 # to get a string like this run:
 # openssl rand -hex 32
 SECRET_KEY = '09d25e094faa6ca2556c818166b7a9563b93f7099f6f0f4caa6cf63b88e8d3e7'
@@ -18,3 +20,8 @@
         'disabled': False,
     }
 }
+
+API_CONFIG = {
+    'PREFIX': '/api/v0',
+    'VERSION': __version__,
+}

aiida_restapi/graphql/comments.py

@@ -6,7 +6,7 @@
 import graphene as gr
 from aiida.orm import Comment
 
-from aiida_restapi.filter_syntax import parse_filter_str
+from aiida_restapi.graphql.filter_syntax import parse_filter_str
 
 from .orm_factories import (
     ENTITY_DICT_TYPE,

aiida_restapi/graphql/computers.py

@@ -6,7 +6,7 @@
 import graphene as gr
 from aiida.orm import Computer
 
-from aiida_restapi.filter_syntax import parse_filter_str
+from aiida_restapi.graphql.filter_syntax import parse_filter_str
 from aiida_restapi.graphql.plugins import QueryPlugin
 
 from .nodes import NodesQuery

aiida_restapi/filter_syntax.py → aiida_restapi/graphql/filter_syntax.py

@@ -13,8 +13,8 @@
 
 from lark import Lark, Token, Tree
 
-from . import static
-from .utils import parse_date
+from .. import static
+from ..utils import parse_date
 
 FILTER_GRAMMAR = resources.open_text(static, 'filter_grammar.lark')
 

aiida_restapi/graphql/groups.py

@@ -6,7 +6,7 @@
 import graphene as gr
 from aiida.orm import Group
 
-from aiida_restapi.filter_syntax import parse_filter_str
+from aiida_restapi.graphql.filter_syntax import parse_filter_str
 from aiida_restapi.graphql.nodes import NodesQuery
 from aiida_restapi.graphql.plugins import QueryPlugin
 

aiida_restapi/graphql/logs.py

@@ -6,7 +6,7 @@
 import graphene as gr
 from aiida.orm import Log
 
-from aiida_restapi.filter_syntax import parse_filter_str
+from aiida_restapi.graphql.filter_syntax import parse_filter_str
 
 from .orm_factories import (
     ENTITY_DICT_TYPE,

aiida_restapi/graphql/nodes.py

@@ -6,7 +6,7 @@
 import graphene as gr
 from aiida import orm
 
-from aiida_restapi.filter_syntax import parse_filter_str
+from aiida_restapi.graphql.filter_syntax import parse_filter_str
 from aiida_restapi.graphql.plugins import QueryPlugin
 
 from .comments import CommentsQuery

aiida_restapi/graphql/orm_factories.py

@@ -12,7 +12,7 @@
 from graphql import GraphQLError
 from pydantic import Json
 
-from aiida_restapi.aiida_db_mappings import ORM_MAPPING, get_model_from_orm
+from aiida_restapi.graphql.aiida_db_mappings import ORM_MAPPING, get_model_from_orm
 
 from .config import ENTITY_LIMIT
 from .utils import JSON, selected_field_names_naive

aiida_restapi/graphql/users.py

@@ -6,7 +6,7 @@
 import graphene as gr
 from aiida.orm import User
 
-from aiida_restapi.filter_syntax import parse_filter_str
+from aiida_restapi.graphql.filter_syntax import parse_filter_str
 
 from .nodes import NodesQuery
 from .orm_factories import (