`fairdm.api.viewsets`#

API viewsets.

This module provides:

:class:BaseViewSet — the base class for all FairDM API viewsets.
:class:ProjectViewSet, :class:DatasetViewSet — full CRUD viewsets for core models.
:class:PersonViewSet, :class:OrganizationViewSet — read-only viewsets for the people and the organizations a portal holds.
:func:generate_viewset — factory that creates a ModelViewSet subclass from a registry :class:~fairdm.registry.ModelConfiguration.

Module Contents#

Classes#

`BaseViewSet`	Internal base class — see generated subclasses for API documentation.
`ProjectViewSet`	Research projects registered in the portal.
`DatasetViewSet`	Datasets within research projects.
`PersonViewSet`	People credited on the portal’s projects, datasets, samples and measurements.
`OrganizationViewSet`	Organizations credited on the portal’s records, or that people are affiliated with.

Functions#

`under_heading`	Group a viewset’s operations under one heading of the generated documentation.
`sortable_fields`	List the fields a list may be sorted on: the model’s own columns the serializer returns.
`load_relations`	Load the relations a serializer returns, so a list reads no query per record.
`generate_viewset`	Generate a :class:`ModelViewSet` subclass from a registry config.

Data#

ACTIONS

API#

ACTIONS#: (‘list’, ‘retrieve’, ‘create’, ‘update’, ‘partial_update’, ‘destroy’)

under_heading(heading: str, actions: tuple[str, ...] = ACTIONS)#

Group a viewset’s operations under one heading of the generated documentation.

Args: heading: The tag every operation carries. actions: The actions the viewset serves.

Returns: A class decorator.

exception DeleteRefused(detail=None, code=None)#

Bases: rest_framework.exceptions.APIException

A delete the portal refuses for the state the record is in, answered 409 with a reason.

Initialization

Initialize self. See help(type(self)) for accurate signature.

status_code#: None

default_detail#: ‘_(…)’

default_code#: ‘delete_refused’

class BaseViewSet(**kwargs)#

Bases: rest_framework.viewsets.ModelViewSet

Internal base class — see generated subclasses for API documentation.

Portal developers: use :func:generate_viewset or subclass the per-model viewsets that appear in the browsable API at /api/v1/.

Initialization

Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

lookup_field#: ‘uuid’

perform_create(serializer: rest_framework.serializers.BaseSerializer) → None#: Require an authenticated user before saving.

perform_update(serializer: rest_framework.serializers.BaseSerializer) → None#: Require an authenticated user before saving.

perform_destroy(instance) → None#

Require an authenticated user before deleting, and refuse what the portal refuses.

Raises: PermissionDenied: When the caller is not signed in. DeleteRefused: When the record has public datasets or other records depend on it. The reason is written here and names no other record, which the caller may not be allowed to see.

class ProjectViewSet(**kwargs)#

Bases: fairdm.api.viewsets.BaseViewSet

Research projects registered in the portal.

Projects are the top-level organizational unit containing datasets, samples, and measurements. Use this endpoint to browse, create, and manage projects you have permission to access.

Initialization

Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

serializer_class#: None

filterset_class#: None

ordering_fields#: (‘name’, ‘added’, ‘modified’, ‘status’, ‘uuid’)

get_queryset()#: Return all projects, with what the serializer reads loaded.

perform_create(serializer: rest_framework.serializers.BaseSerializer) → None#: Save a new project, recording the request user as its creator.

class DatasetViewSet(**kwargs)#

Bases: fairdm.api.viewsets.BaseViewSet

Datasets within research projects.

Each dataset contains samples and associated measurements. Use this endpoint to query, add, and manage datasets you have permission to access.

Initialization

Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

serializer_class#: None

filterset_class#: None

ordering_fields#: (‘name’, ‘added’, ‘modified’, ‘uuid’)

get_queryset()#: Return all datasets, including private ones the visibility filter admits.

perform_create(serializer: rest_framework.serializers.BaseSerializer) → None#: Save a new dataset, recording the request user as its creator.

class PersonViewSet(**kwargs)#

Bases: rest_framework.viewsets.ReadOnlyModelViewSet

People credited on the portal’s projects, datasets, samples and measurements.

A person’s profile is publicly accessible (read-only). Use this endpoint to look up the individuals associated with portal data.

Initialization

Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

lookup_field#: ‘uuid’

permission_classes#: ()

serializer_class#: None

filterset_class#: None

ordering_fields#: (‘name’, ‘last_name’, ‘added’, ‘modified’, ‘uuid’)

get_serializer_class()#: Serve a list entry for the list, and the whole person for one record.

get_queryset()#

Return the people the portal’s own lists show, with what the serializer reads.

Leaves out superusers and the anonymous account, as Person.objects.real() does.

class OrganizationViewSet(**kwargs)#

Bases: rest_framework.viewsets.ReadOnlyModelViewSet

Organizations credited on the portal’s records, or that people are affiliated with.

An organization’s profile is publicly accessible (read-only). Use this endpoint to look up the institutions associated with portal data.

Initialization

Constructor. Called in the URLconf; can contain helpful extra keyword arguments, and other things.

lookup_field#: ‘uuid’

permission_classes#: ()

serializer_class#: None

filterset_class#: None

ordering_fields#: (‘name’, ‘added’, ‘modified’, ‘uuid’)

get_serializer_class()#: Serve a list entry for the list, and the whole organization for one record.

get_queryset()#

Return all organizations, with what the serializer reads.

A single record also loads its parent, its sub-organizations and its current verified affiliations with their people, which the list does not show.

sortable_fields(model, serializer_cls) → list[str]#

List the fields a list may be sorted on: the model’s own columns the serializer returns.

Args: model: The model the list serves. serializer_cls: The serializer the list uses.

Returns: The names of the stored, non-relational fields among the serializer’s fields.

load_relations(queryset, serializer_cls)#

Load the relations a serializer returns, so a list reads no query per record.

Args: queryset: The records about to be serialized, with the serializer’s parents loaded. serializer_cls: The serializer the list uses.

Returns: The queryset with each foreign key and one-to-one among the serializer’s fields selected and each many-to-many prefetched, apart from the parents it already loads.

generate_viewset(config: Any, base_class: type = BaseViewSet) → type#

Generate a :class:ModelViewSet subclass from a registry config.

The serializer is whatever config.get_serializer_class() returns: the class named in the registration, or one the registry builds from the configured fields. A sample or measurement serializer must build on the base serializer of its kind.

Args: config: A :class:~fairdm.registry.ModelConfiguration instance from the FairDM registry. base_class: Base viewset class (default: :class:BaseViewSet).

Returns: A ModelViewSet subclass configured for config.model.

Raises: ImproperlyConfigured: When the serializer of a sample or measurement type does not build on the base serializer of its kind.

fairdm.api.viewsets#

Module Contents#

Classes#

Functions#

Data#

API#

`fairdm.api.viewsets`#