aiida_restapi.jsonapi package

Contents

aiida_restapi.jsonapi package#

Submodules#

aiida_restapi.jsonapi.adapters module#

JSON:API adapters module.

class aiida_restapi.jsonapi.adapters.JsonApiAdapter[source]#

Bases: object

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

BASE_API_URL = ''#
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'>}, 'BASE_API_URL': '', 'register_hooks': <classmethod(<function JsonApiAdapter.register_hooks>)>, 'resource': <classmethod(<function JsonApiAdapter.resource>)>, 'child_resource': <classmethod(<function JsonApiAdapter.child_resource>)>, 'collection': <classmethod(<function JsonApiAdapter.collection>)>, '_base_api_url': <classmethod(<function JsonApiAdapter._base_api_url>)>, '_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

classmethod _base_api_url(request)[source]#

Return the base API URL from the request.

Parameters:

request (Request) – The incoming request.

Returns:

The base API URL.

Return type:

str

Return a URL with updated query parameters.

Parameters:

  • request (Request) – The incoming request.

  • updates (dict[str, str | int | None]) – The query parameter updates.

Returns:

The updated URL.

Return type:

URL

classmethod _build_resource(result, resource_identity, resource_type, base_api, include=None, cache=None)[source]#

Build a JSON:API resource and its included related resources. :param result: The result to convert. :type result: dict[str, t.Any] :param resource_identity: The identity field to use for the resource. :type resource_identity: str :param resource_type: The resource type to use for the resource. :type resource_type: str :param base_api: The base API URL. :type base_api: str :param include: A list of related resource types to include. :type include: list[str] | None :param cache: An optional cache for included resources. :type cache: IncludedItemParamsCache | None :return: The JSON:API resource and included resources. :rtype: tuple[dict[str, t.Any], list[dict[str, t.Any]]] :raises JsonApiException: If the resource identity or type are missing.

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

Parameters:

  • request (Request) – The incoming request.

  • page_size (int) – The page size.

  • page (int) – The current page.

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

Returns:

The top-level links.

Return type:

dict[str, str]

classmethod _hook_for(resource_type)[source]#

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(result, *, pid, parent_type, child_type, base_api)[source]#

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

Parameters:

  • 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.

  • base_api (str) – The base API URL.

Returns:

The JSON:API resource object.

Return type:

dict[str, t.Any]

classmethod _to_resource(identifier, attributes, foreign_fields, resource_type, base_api)[source]#

Convert an AiiDA quantity to a JSON:API resource.

Parameters:

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

  • base_api (str) – The base API URL.

  • 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)[source]#

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)[source]#

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)[source]#

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)[source]#

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.hooks module#

class aiida_restapi.jsonapi.hooks.BaseHook[source]#

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)[source]#

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)[source]#

Return link dictionary for the resource.

Parameters:

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

  • base_api_url (str) – The base URL of the API.

  • 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(*, foreign_fields, resource_type, base_api_url, url_id)[source]#

Return relationships dictionary for the resource.

Parameters:

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

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

  • base_api_url (str) – The base URL of the API.

  • 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)[source]#

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[source]#

Bases: EntityHook

A hook for computer-specific JSON:API customization.

__annotations__ = {}#
__module__ = 'aiida_restapi.jsonapi.hooks'#
classmethod relationships(*, foreign_fields, resource_type, base_api_url, url_id)[source]#

Return relationships dictionary for the resource.

Parameters:

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

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

  • base_api_url (str) – The base URL of the API.

  • 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[source]#

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[source]#

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(*, foreign_fields, resource_type, base_api_url, url_id)[source]#

Return relationships dictionary for the resource.

Parameters:

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

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

  • base_api_url (str) – The base URL of the API.

  • 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[source]#

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(*, foreign_fields, resource_type, base_api_url, url_id)[source]#

Return relationships dictionary for the resource.

Parameters:

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

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

  • base_api_url (str) – The base URL of the API.

  • 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[source]#

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(*, foreign_fields, resource_type, base_api_url, url_id)[source]#

Return relationships dictionary for the resource.

Parameters:

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

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

  • base_api_url (str) – The base URL of the API.

  • 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[source]#

Bases: BaseHook

A hook for JSON:API resource customization.

__annotations__ = {}#
__module__ = 'aiida_restapi.jsonapi.hooks'#

Return link dictionary for the resource.

Parameters:

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

  • base_api_url (str) – The base URL of the API.

  • 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(*, foreign_fields, resource_type, base_api_url, url_id)[source]#

Return relationships dictionary for the resource.

Parameters:

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

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

  • base_api_url (str) – The base URL of the API.

  • 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.responses module#

JSON:API responses module.

class aiida_restapi.jsonapi.responses.JsonApiResponse(content, status_code=200, headers=None, media_type=None, background=None)[source]#

Bases: JSONResponse

Custom JSONResponse for JSON:API media type.

__module__ = 'aiida_restapi.jsonapi.responses'#
media_type = 'application/vnd.api+json'#
render(content)[source]#

aiida_restapi.jsonapi.utils module#

JSON:API utilities.

class aiida_restapi.jsonapi.utils.IncludedItemParamsCache(buckets=<factory>)[source]#

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)[source]#

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#
aiida_restapi.jsonapi.utils.jsonapi_error(request, exception, status_code)[source]#

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:

JSONResponse

Module contents#

Contents