aiida_restapi.jsonapi package

Submodules

aiida_restapi.jsonapi.adapters module

JSON:API adapters module.

class aiida_restapi.jsonapi.adapters.JsonApiAdapter

Bases: object

JSON:API adapter to convert AiiDA models to JSON:API compliant documents.

HOOKS = {'computers': <class 'aiida_restapi.jsonapi.hooks.ComputerHook'>, 'groups': <class 'aiida_restapi.jsonapi.hooks.GroupHook'>, 'links': <class 'aiida_restapi.jsonapi.hooks.LinkHook'>, 'nodes': <class 'aiida_restapi.jsonapi.hooks.NodeHook'>, 'users': <class 'aiida_restapi.jsonapi.hooks.ResourceHook'>}

RESOURCE_TYPES = {<class 'aiida.orm.computers.Computer'>: 'computers', <class 'aiida.orm.groups.Group'>: 'groups', <class 'aiida.orm.nodes.node.Node'>: 'nodes', <class 'aiida.orm.users.User'>: 'users'}

__annotations__ = {'HOOKS': 'dict[str, type[hooks.BaseHook]]', 'RESOURCE_TYPES': 'dict[type[orm.Entity], str]'}

__dict__ = mappingproxy({'__module__': 'aiida_restapi.jsonapi.adapters', '__annotations__': {'RESOURCE_TYPES': 'dict[type[orm.Entity], str]', 'HOOKS': 'dict[str, type[hooks.BaseHook]]'}, '__doc__': 'JSON:API adapter to convert AiiDA models to JSON:API compliant documents.', 'RESOURCE_TYPES': {<class 'aiida.orm.users.User'>: 'users', <class 'aiida.orm.computers.Computer'>: 'computers', <class 'aiida.orm.groups.Group'>: 'groups', <class 'aiida.orm.nodes.node.Node'>: 'nodes'}, 'HOOKS': {'users': <class 'aiida_restapi.jsonapi.hooks.ResourceHook'>, 'computers': <class 'aiida_restapi.jsonapi.hooks.ComputerHook'>, 'groups': <class 'aiida_restapi.jsonapi.hooks.GroupHook'>, 'nodes': <class 'aiida_restapi.jsonapi.hooks.NodeHook'>, 'links': <class 'aiida_restapi.jsonapi.hooks.LinkHook'>}, 'register_hooks': <classmethod(<function JsonApiAdapter.register_hooks>)>, 'resource': <classmethod(<function JsonApiAdapter.resource>)>, 'child_resource': <classmethod(<function JsonApiAdapter.child_resource>)>, 'collection': <classmethod(<function JsonApiAdapter.collection>)>, '_build_resource': <classmethod(<function JsonApiAdapter._build_resource>)>, '_hook_for': <classmethod(<function JsonApiAdapter._hook_for>)>, '_to_resource': <classmethod(<function JsonApiAdapter._to_resource>)>, '_to_child_resource': <classmethod(<function JsonApiAdapter._to_child_resource>)>, '_build_toplevel_links': <classmethod(<function JsonApiAdapter._build_toplevel_links>)>, '_build_link': <staticmethod(<function JsonApiAdapter._build_link>)>, '__dict__': <attribute '__dict__' of 'JsonApiAdapter' objects>, '__weakref__': <attribute '__weakref__' of 'JsonApiAdapter' objects>})

__module__ = 'aiida_restapi.jsonapi.adapters'

__weakref__

list of weak references to the object

static _build_link(request, page=None, page_size=None)

Return a relative URL with updated query parameters.

Parameters:

• request (Request) – The incoming request.

• page (int | None) – The current page.

• page_size (int | None) – The page size.

Returns:

The updated URL relative to the base URL.

Return type:

str

classmethod _build_resource(request, result, resource_identity, resource_type, include=None, cache=None)

Build a JSON:API resource and its included related resources.

Parameters:

• request (Request) – The incoming request.

• result (dict[str, t.Any]) – The result to convert.

• resource_identity (str) – The identity field to use for the resource.

• resource_type (str) – The resource type to use for the resource.

• include (list[str] | None) – A list of related resource types to include.

• cache (IncludedItemParamsCache | None) – An optional cache for included resources.

Returns:

The JSON:API resource and included resources.

Return type:

tuple[dict[str, t.Any], list[dict[str, t.Any]]]

Raises:

JsonApiException – If the resource identity or type are missing.

classmethod _build_toplevel_links(request, total, page, page_size)

Return dict suitable for JSON:API top-level links (self/next/prev/first/last).

Parameters:

• request (Request) – The incoming request.

• total (int) – The total number of items.

• page (int) – The current page.

• page_size (int) – The page size.

Returns:

The top-level links.

Return type:

dict[str, str]

classmethod _hook_for(resource_type)

Return the Hook class for the given resource type.

Parameters:

resource_type (str) – The resource type.

Returns:

The hook class.

Return type:

type[Hook]

classmethod _to_child_resource(request, result, pid, parent_type, child_type)

Convert a dependent quantity to a single resource JSON:API document.

Parameters:

• request (Request) – The incoming request.

• result (dict[str, t.Any]) – The result dictionary to convert.

• pid (str | int) – The parent resource identifier.

• parent_type (str) – The parent resource type.

• child_type (str) – The child resource type.

Returns:

The JSON:API resource object.

Return type:

dict[str, t.Any]

classmethod _to_resource(request, identifier, attributes, foreign_fields, resource_type)

Convert an AiiDA quantity to a JSON:API resource.

Parameters:

• request (Request) – The incoming request.

• resource_identity (str) – The identity field to use for the resource.

• resource_type (str) – The resource type to use for the resource.

Returns:

The JSON:API resource object.

Return type:

dict[str, t.Any]

classmethod child_resource(request, result, *, pid, parent_type, child_type, include=None, meta=None)

Return a JSON:API document for a child resource derived from an AiiDA object’s child quantity.

Parameters:

• request (Request) – The incoming request.

• result (dict[str, t.Any]) – The result dictionary to convert.

• pid (str | int) – The parent resource identifier.

• child_type (str) – The child resource type.

• parent_type (str | None) – The parent resource type.

• include (list[str] | None) – A list of related resource types to include.

• meta (dict[str, t.Any] | None) – Optional meta information to include in the document.

Returns:

The JSON:API document.

Return type:

JsonApiResponse

classmethod collection(request, results, *, resource_identity, resource_type, query_params=CollectionQueryParams(include=[], page_size=10, page=1, offset=0, order_by=None, filters={}), meta=None)

Return a JSON:API document with a collection of resources derived from AiiDA objects.

Parameters:

• request (Request) – The incoming request.

• results (PaginatedResults) – The paginated results to convert.

• resource_identity (str) – The identity field to use for the resources.

• resource_type (str) – The resource type to use for the resources.

• query_params (CollectionQueryParams) – The collection query parameters.

• meta (dict[str, t.Any] | None) – Optional meta information to include in the document.

Returns:

The JSON:API document.

Return type:

JsonApiResponse

classmethod register_hooks(new_hooks)

Update the hook mapping with new hooks.

Parameters:

new_hooks (dict[str, type[Hook]]) – A dictionary of resource type to Hook class mappings.

classmethod resource(request, result, *, resource_identity, resource_type, include=None, meta=None)

Return a JSON:API document for a single resource derived from an AiiDA object.

Parameters:

• request (Request) – The incoming request.

• result (dict[str, t.Any]) – The result model to convert.

• resource_identity (str) – The identity field to use for the resource.

• resource_type (str) – The resource type to use for the resource.

• include (list[str] | None) – A list of related resource types to include.

• meta (dict[str, t.Any] | None) – Optional meta information to include in the document.

Returns:

The JSON:API document.

Return type:

JsonApiResponse

aiida_restapi.jsonapi.errors module

aiida_restapi.jsonapi.errors.jsonapi_error(request, exception, status_code)

Generate a JSON:API compliant error response.

Parameters:

• request (Request) – The incoming request.

• exception (Exception) – The exception that was raised.

• status_code (int) – The HTTP status code for the response.

Returns:

A JSON response containing the error in JSON:API format.

Return type:

JsonApiResponse

aiida_restapi.jsonapi.hooks module

class aiida_restapi.jsonapi.hooks.BaseHook

Bases: object

The base hook for JSON:API document customization.

FOREIGN_FIELDS = []

INCLUDED_TYPE_MAP = {}

TYPE_MAP = {}

__annotations__ = {'FOREIGN_FIELDS': 'list[str]', 'INCLUDED_TYPE_MAP': 'dict[str, tuple[str, type[orm.Entity]]]', 'TYPE_MAP': 'dict[str, str]'}

__dict__ = mappingproxy({'__module__': 'aiida_restapi.jsonapi.hooks', '__annotations__': {'TYPE_MAP': 'dict[str, str]', 'FOREIGN_FIELDS': 'list[str]', 'INCLUDED_TYPE_MAP': 'dict[str, tuple[str, type[orm.Entity]]]'}, '__doc__': 'The base hook for JSON:API document customization.', 'TYPE_MAP': {}, 'FOREIGN_FIELDS': [], 'INCLUDED_TYPE_MAP': {}, 'split_resource': <classmethod(<function BaseHook.split_resource>)>, 'links': <classmethod(<function BaseHook.links>)>, 'relationships': <classmethod(<function BaseHook.relationships>)>, 'include': <classmethod(<function BaseHook.include>)>, '_build_included_item': <classmethod(<function BaseHook._build_included_item>)>, '__dict__': <attribute '__dict__' of 'BaseHook' objects>, '__weakref__': <attribute '__weakref__' of 'BaseHook' objects>})

__module__ = 'aiida_restapi.jsonapi.hooks'

__weakref__

list of weak references to the object

classmethod _build_included_item(resource_id, resource_type, orm_class, cache=None)

Build an included item parameters tuple.

Parameters:

• resource_id (str | int) – The identifier of the resource.

• resource_type (str) – The type of the resource.

• orm_class (type[orm.Entity]) – The ORM class of the resource.

• cache (IncludedItemParamsCache | None) – An optional cache for included resources.

Returns:

A tuple containing identifier, type, attributes, and foreign fields of the included resource, or None if resource_id is None.

Return type:

IncludedItemParams | None

classmethod include(*, foreign_fields, include, cache=None)

classmethod links(request, resource_type, url_id)

Return link dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of links.

Return type:

dict[str, str | dict[str, t.Any]]

classmethod relationships(request, *, foreign_fields, resource_type, url_id)

Return relationships dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• foreign_fields (dict[str, t.Any]) – The foreign fields of the resource.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of relationships.

Return type:

dict[str, dict[str, t.Any]]

classmethod split_resource(result, resource_identity, resource_type)

Split the result into identifier, attributes, and foreign fields.

Parameters:

• result (dict[str, t.Any]) – The raw result of the resource.

• resource_identity (str) – The identity field of the resource.

• resource_type (str) – The type of the resource.

Returns:

A tuple containing the identifier, attributes, and foreign fields.

Return type:

tuple[str, dict[str, t.Any], dict[str, t.Any]]

class aiida_restapi.jsonapi.hooks.ComputerHook

Bases: EntityHook

A hook for computer-specific JSON:API customization.

__annotations__ = {}

__module__ = 'aiida_restapi.jsonapi.hooks'

classmethod relationships(request, *, foreign_fields, resource_type, url_id)

Return relationships dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• foreign_fields (dict[str, t.Any]) – The foreign fields of the resource.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of relationships.

Return type:

dict[str, dict[str, t.Any]]

class aiida_restapi.jsonapi.hooks.EntityHook

Bases: ResourceHook

A hook for entity-specific JSON:API customization.

INCLUDED_TYPE_MAP = {'computer': ('computers', <class 'aiida.orm.computers.Computer'>), 'group': ('groups', <class 'aiida.orm.groups.Group'>), 'node': ('nodes', <class 'aiida.orm.nodes.node.Node'>), 'user': ('users', <class 'aiida.orm.users.User'>)}

TYPE_MAP = {'computers': 'computer', 'groups': 'group', 'nodes': 'node', 'users': 'user'}

__annotations__ = {'INCLUDED_TYPE_MAP': 'dict[str, tuple[str, type[orm.Entity]]]', 'TYPE_MAP': 'dict[str, str]'}

__module__ = 'aiida_restapi.jsonapi.hooks'

class aiida_restapi.jsonapi.hooks.GroupHook

Bases: EntityHook

A hook for group-specific JSON:API customization.

FOREIGN_FIELDS = ['user']

__annotations__ = {'FOREIGN_FIELDS': 'list[str]'}

__module__ = 'aiida_restapi.jsonapi.hooks'

classmethod relationships(request, *, foreign_fields, resource_type, url_id)

Return relationships dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• foreign_fields (dict[str, t.Any]) – The foreign fields of the resource.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of relationships.

Return type:

dict[str, dict[str, t.Any]]

class aiida_restapi.jsonapi.hooks.LinkHook

Bases: BaseHook

A hook for link-specific JSON:API customization.

FOREIGN_FIELDS = ['source', 'target']

INCLUDED_TYPE_MAP = {'source': ('nodes', <class 'aiida.orm.nodes.node.Node'>), 'target': ('nodes', <class 'aiida.orm.nodes.node.Node'>)}

__annotations__ = {'FOREIGN_FIELDS': 'list[str]', 'INCLUDED_TYPE_MAP': 'dict[str, tuple[str, type[orm.Entity]]]'}

__module__ = 'aiida_restapi.jsonapi.hooks'

classmethod relationships(request, *, foreign_fields, resource_type, url_id)

Return relationships dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• foreign_fields (dict[str, t.Any]) – The foreign fields of the resource.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of relationships.

Return type:

dict[str, dict[str, t.Any]]

class aiida_restapi.jsonapi.hooks.NodeHook

Bases: EntityHook

A hook for node-specific JSON:API customization.

FOREIGN_FIELDS = ['user', 'computer']

__annotations__ = {'FOREIGN_FIELDS': 'list[str]'}

__module__ = 'aiida_restapi.jsonapi.hooks'

classmethod relationships(request, *, foreign_fields, resource_type, url_id)

Return relationships dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• foreign_fields (dict[str, t.Any]) – The foreign fields of the resource.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of relationships.

Return type:

dict[str, dict[str, t.Any]]

class aiida_restapi.jsonapi.hooks.ResourceHook

Bases: BaseHook

A hook for JSON:API resource customization.

__annotations__ = {}

__module__ = 'aiida_restapi.jsonapi.hooks'

classmethod links(request, resource_type, url_id)

Return link dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of links.

Return type:

dict[str, str | dict[str, t.Any]]

classmethod relationships(request, *, foreign_fields, resource_type, url_id)

Return relationships dictionary for the resource.

Parameters:

• request (Request) – The incoming request.

• foreign_fields (dict[str, t.Any]) – The foreign fields of the resource.

• resource_type (str) – The type of the resource.

• url_id (str) – The URL identifier of the resource.

Returns:

A dictionary of relationships.

Return type:

dict[str, dict[str, t.Any]]

aiida_restapi.jsonapi.utils module

JSON:API utilities.

class aiida_restapi.jsonapi.utils.IncludedItemParamsCache(buckets=<factory>)

Bases: object

Per-request cache for the parameter of an included resources.

The cache is used to avoid recomputing the parameters of shared included resources (user, computer, etc.). The cache is organized in buckets per resource type and maps to id: (id, type, attributes, foreign fields).

__annotations__ = {'buckets': 'dict[str, CacheBucket]'}

__dataclass_fields__ = {'buckets': Field(name='buckets',type='dict[str, CacheBucket]',default=<dataclasses._MISSING_TYPE object>,default_factory=<class 'dict'>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}

__dataclass_params__ = _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False)

__dict__ = mappingproxy({'__module__': 'aiida_restapi.jsonapi.utils', '__annotations__': {'buckets': 'dict[str, CacheBucket]'}, '__doc__': 'Per-request cache for the parameter of an included resources.\n\n    The cache is used to avoid recomputing the parameters of shared included resources (user, computer, etc.).\n    The cache is organized in buckets per resource type and maps to id: (id, type, attributes, foreign fields).\n    ', 'bucket': <function IncludedItemParamsCache.bucket>, '__dict__': <attribute '__dict__' of 'IncludedItemParamsCache' objects>, '__weakref__': <attribute '__weakref__' of 'IncludedItemParamsCache' objects>, '__dataclass_params__': _DataclassParams(init=True,repr=True,eq=True,order=False,unsafe_hash=False,frozen=False), '__dataclass_fields__': {'buckets': Field(name='buckets',type='dict[str, CacheBucket]',default=<dataclasses._MISSING_TYPE object>,default_factory=<class 'dict'>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),kw_only=False,_field_type=_FIELD)}, '__init__': <function IncludedItemParamsCache.__init__>, '__repr__': <function IncludedItemParamsCache.__repr__>, '__eq__': <function IncludedItemParamsCache.__eq__>, '__hash__': None, '__match_args__': ('buckets',)})

__eq__(other)

Return self==value.

__hash__ = None

__init__(buckets=<factory>)

__match_args__ = ('buckets',)

__module__ = 'aiida_restapi.jsonapi.utils'

__repr__()

Return repr(self).

__weakref__

list of weak references to the object

bucket(resource_type)

Get the cache bucket for a given resource type.

Parameters:

resource_type (str) – The resource type.

Returns:

The cache bucket for the resource type.

Return type:

CacheBucket

buckets

Module contents