Label module

Queries

Set of Label queries.

Source code in kili/queries/label/__init__.py

class QueriesLabel:
    """Set of Label queries."""

    # pylint: disable=too-many-arguments,too-many-locals

    def __init__(self, auth):
        """Initialize the subclass.

        Args:
            auth: KiliAuth object
        """
        self.auth = auth

    # pylint: disable=dangerous-default-value
    @Compatible(['v1', 'v2'])
    @typechecked
    def labels(self,
               asset_id: Optional[str] = None,
               asset_status_in: Optional[List[str]] = None,
               asset_external_id_in: Optional[List[str]] = None,
               author_in: Optional[List[str]] = None,
               created_at: Optional[str] = None,
               created_at_gte: Optional[str] = None,
               created_at_lte: Optional[str] = None,
               fields: List[str] = ['author.email', 'author.id', 'id',
                                    'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'],
               first: Optional[int] = None,
               honeypot_mark_gte: Optional[float] = None,
               honeypot_mark_lte: Optional[float] = None,
               id_contains: Optional[List[str]] = None,
               json_response_contains: Optional[List[str]] = None,
               label_id: Optional[str] = None,
               project_id: Optional[str] = None,
               skip: int = 0,
               skipped: Optional[bool] = None,
               type_in: Optional[List[str]] = None,
               user_id: Optional[str] = None,
               disable_tqdm: bool = False,
               as_generator: bool = False,
               ) -> Union[List[dict], Generator[dict, None, None]]:
        # pylint: disable=line-too-long
        """Get a label list or a label generator from a project based on a set of criteria.

        Args:
            asset_id: Identifier of the asset.
            asset_status_in: Returned labels should have a status that belongs to that list, if given.
                Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
            asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
            author_in: Returned labels should have a label whose status belongs to that list, if given.
            created_at: Returned labels should have a label whose creation date is equal to this date.
            created_at_gte: Returned labels should have a label whose creation date is greater than this date.
            created_at_lte: Returned labels should have a label whose creation date is lower than this date.
            fields: All the fields to request among the possible fields for the labels.
                See [the documentation](https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#label) for all possible fields.
            first: Maximum number of labels to return.
            honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
            honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
            id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
            json_response_contains: Returned labels should have a substring of the jsonResponse that belongs
                to that list, if given.
            label_id: Identifier of the label.
            project_id: Identifier of the project.
            skip: Number of labels to skip (they are ordered by their date of creation, first to last).
            skipped: Returned labels should have a label which is skipped
            type_in: Returned labels should have a label whose type belongs to that list, if given.
            user_id: Identifier of the user.
            disable_tqdm: If `True`, the progress bar will be disabled
            as_generator: If `True`, a generator on the labels is returned.

        !!! info "Dates format"
            Date strings should have format: "YYYY-MM-DD"

        Returns:
            A result object which contains the query if it was successful, else an error message.

        Examples:
            >>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
            >>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project
        """

        saved_args = locals()
        count_args = {
            k: v
            for (k, v) in saved_args.items()
            if k
            not in [
                'as_generator',
                'disable_tqdm',
                'fields',
                'first',
                'id_contains',
                'self',
                'skip',
            ]
        }

        # using tqdm with a generator is messy, so it is always disabled
        disable_tqdm = disable_tqdm or as_generator

        payload_query = {
            'where': {
                'id': label_id,
                'asset': {
                    'id': asset_id,
                    'externalIdIn': asset_external_id_in,
                    'statusIn': asset_status_in,
                },
                'project': {
                    'id': project_id,
                },
                'user': {
                    'id': user_id,
                },
                'createdAt': created_at,
                'createdAtGte': created_at_gte,
                'createdAtLte': created_at_lte,
                'authorIn': author_in,
                'honeypotMarkGte': honeypot_mark_gte,
                'honeypotMarkLte': honeypot_mark_lte,
                'idIn': id_contains,
                'jsonResponseContains': json_response_contains,
                'skipped': skipped,
                'typeIn': type_in,
            },
        }

        labels_generator = row_generator_from_paginated_calls(
            skip,
            first,
            self.count_labels,
            count_args,
            self._query_labels,
            payload_query,
            fields,
            disable_tqdm
        )

        if as_generator:
            return labels_generator
        return list(labels_generator)

    def _query_labels(self,
                      skip: int,
                      first: int,
                      payload: dict,
                      fields: List[str]):

        payload.update({'skip': skip, 'first': first})
        _gql_labels = gql_labels(fragment_builder(fields, LabelType))
        result = self.auth.client.execute(_gql_labels, payload)
        return format_result('data', result, Label)

    # pylint: disable=dangerous-default-value
    @typechecked
    def export_labels_as_df(self,
                            project_id: str,
                            fields: List[str] = [
                                'author.email',
                                'author.id',
                                'createdAt',
                                'id',
                                'labelType',
                                'skipped'
                            ],
                            asset_fields: List[str] = [
                                'externalId'
                            ]) -> pd.DataFrame:
        # pylint: disable=line-too-long
        """Get the labels of a project as a pandas DataFrame.

        Args:
            project_id: Identifier of the project
            fields: All the fields to request among the possible fields for the labels.
                See [the documentation](https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#label) for all possible fields.
            asset_fields: All the fields to request among the possible fields for the assets.
                See [the documentation](https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#asset) for all possible fields.

        Returns:
            pandas DataFrame containing the labels.
        """
        projects = QueriesProject(self.auth).projects(project_id)
        assert len(projects) == 1, NO_ACCESS_RIGHT
        assets = QueriesAsset(self.auth).assets(
            project_id=project_id,
            fields=asset_fields + ['labels.' + field for field in fields])
        labels = [dict(label, **dict((f'asset_{key}', asset[key]) for key in asset if key != 'labels'))
                  for asset in assets for label in asset['labels']]
        labels_df = pd.DataFrame(labels)
        return labels_df

    @Compatible(['v1', 'v2'])
    @typechecked
    def count_labels(self,
                     asset_id: Optional[str] = None,
                     asset_status_in: Optional[List[str]] = None,
                     asset_external_id_in: Optional[List[str]] = None,
                     author_in: Optional[List[str]] = None,
                     created_at: Optional[str] = None,
                     created_at_gte: Optional[str] = None,
                     created_at_lte: Optional[str] = None,
                     honeypot_mark_gte: Optional[float] = None,
                     honeypot_mark_lte: Optional[float] = None,
                     json_response_contains: Optional[List[str]] = None,
                     label_id: Optional[str] = None,
                     project_id: Optional[str] = None,
                     skipped: Optional[bool] = None,
                     type_in: Optional[List[str]] = None,
                     user_id: Optional[str] = None) -> int:
        # pylint: disable=line-too-long
        """Get the number of labels for the given parameters.

        Args:
            asset_id: Identifier of the asset.
            asset_status_in: Returned labels should have a status that belongs to that list, if given.
                Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
            asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
            author_in: Returned labels should have a label whose status belongs to that list, if given.
            created_at: Returned labels should have a label whose creation date is equal to this date.
            created_at_gte: Returned labels should have a label whose creation date is greater than this date.
            created_at_lte: Returned labels should have a label whose creation date is lower than this date.
            honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
            honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
            json_response_contains: Returned labels should have a substring of the jsonResponse that
                belongs to that list, if given.
            label_id: Identifier of the label.
            project_id: Identifier of the project.
            skipped: Returned labels should have a label which is skipped
            type_in: Returned labels should have a label whose type belongs to that list, if given.
            user_id: Identifier of the user.

        !!! info "Dates format"
            Date strings should have format: "YYYY-MM-DD"

        Returns:
            The number of labels with the parameters provided
        """
        variables = {
            'where': {
                'id': label_id,
                'asset': {
                    'id': asset_id,
                    'externalIdIn': asset_external_id_in,
                    'statusIn': asset_status_in,
                },
                'project': {
                    'id': project_id,
                },
                'user': {
                    'id': user_id,
                },
                'createdAt': created_at,
                'createdAtGte': created_at_gte,
                'createdAtLte': created_at_lte,
                'authorIn': author_in,
                'honeypotMarkGte': honeypot_mark_gte,
                'honeypotMarkLte': honeypot_mark_lte,
                'jsonResponseContains': json_response_contains,
                'skipped': skipped,
                'typeIn': type_in,
            }
        }
        result = self.auth.client.execute(GQL_LABELS_COUNT, variables)
        count = format_result('data', result)
        return count

count_labels(self, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, honeypot_mark_gte=None, honeypot_mark_lte=None, json_response_contains=None, label_id=None, project_id=None, skipped=None, type_in=None, user_id=None)

Get the number of labels for the given parameters.

Parameters:

Name	Type	Description	Default
asset_id	Optional[str]	Identifier of the asset.	None
asset_status_in	Optional[List[str]]	Returned labels should have a status that belongs to that list, if given. Possible choices : TODO, ONGOING, LABELED or REVIEWED	None
asset_external_id_in	Optional[List[str]]	Returned labels should have an external id that belongs to that list, if given.	None
author_in	Optional[List[str]]	Returned labels should have a label whose status belongs to that list, if given.	None
created_at	Optional[str]	Returned labels should have a label whose creation date is equal to this date.	None
created_at_gte	Optional[str]	Returned labels should have a label whose creation date is greater than this date.	None
created_at_lte	Optional[str]	Returned labels should have a label whose creation date is lower than this date.	None
honeypot_mark_gte	Optional[float]	Returned labels should have a label whose honeypot is greater than this number.	None
honeypot_mark_lte	Optional[float]	Returned labels should have a label whose honeypot is lower than this number.	None
json_response_contains	Optional[List[str]]	Returned labels should have a substring of the jsonResponse that belongs to that list, if given.	None
label_id	Optional[str]	Identifier of the label.	None
project_id	Optional[str]	Identifier of the project.	None
skipped	Optional[bool]	Returned labels should have a label which is skipped	None
type_in	Optional[List[str]]	Returned labels should have a label whose type belongs to that list, if given.	None
user_id	Optional[str]	Identifier of the user.	None

Dates format

Date strings should have format: "YYYY-MM-DD"

Returns:

Type	Description
int	The number of labels with the parameters provided

Source code in kili/queries/label/__init__.py

@Compatible(['v1', 'v2'])
@typechecked
def count_labels(self,
                 asset_id: Optional[str] = None,
                 asset_status_in: Optional[List[str]] = None,
                 asset_external_id_in: Optional[List[str]] = None,
                 author_in: Optional[List[str]] = None,
                 created_at: Optional[str] = None,
                 created_at_gte: Optional[str] = None,
                 created_at_lte: Optional[str] = None,
                 honeypot_mark_gte: Optional[float] = None,
                 honeypot_mark_lte: Optional[float] = None,
                 json_response_contains: Optional[List[str]] = None,
                 label_id: Optional[str] = None,
                 project_id: Optional[str] = None,
                 skipped: Optional[bool] = None,
                 type_in: Optional[List[str]] = None,
                 user_id: Optional[str] = None) -> int:
    # pylint: disable=line-too-long
    """Get the number of labels for the given parameters.

    Args:
        asset_id: Identifier of the asset.
        asset_status_in: Returned labels should have a status that belongs to that list, if given.
            Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
        asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
        author_in: Returned labels should have a label whose status belongs to that list, if given.
        created_at: Returned labels should have a label whose creation date is equal to this date.
        created_at_gte: Returned labels should have a label whose creation date is greater than this date.
        created_at_lte: Returned labels should have a label whose creation date is lower than this date.
        honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
        honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
        json_response_contains: Returned labels should have a substring of the jsonResponse that
            belongs to that list, if given.
        label_id: Identifier of the label.
        project_id: Identifier of the project.
        skipped: Returned labels should have a label which is skipped
        type_in: Returned labels should have a label whose type belongs to that list, if given.
        user_id: Identifier of the user.

    !!! info "Dates format"
        Date strings should have format: "YYYY-MM-DD"

    Returns:
        The number of labels with the parameters provided
    """
    variables = {
        'where': {
            'id': label_id,
            'asset': {
                'id': asset_id,
                'externalIdIn': asset_external_id_in,
                'statusIn': asset_status_in,
            },
            'project': {
                'id': project_id,
            },
            'user': {
                'id': user_id,
            },
            'createdAt': created_at,
            'createdAtGte': created_at_gte,
            'createdAtLte': created_at_lte,
            'authorIn': author_in,
            'honeypotMarkGte': honeypot_mark_gte,
            'honeypotMarkLte': honeypot_mark_lte,
            'jsonResponseContains': json_response_contains,
            'skipped': skipped,
            'typeIn': type_in,
        }
    }
    result = self.auth.client.execute(GQL_LABELS_COUNT, variables)
    count = format_result('data', result)
    return count

export_labels_as_df(self, project_id, fields=['author.email', 'author.id', 'createdAt', 'id', 'labelType', 'skipped'], asset_fields=['externalId'])

Get the labels of a project as a pandas DataFrame.

Parameters:

Name	Type	Description	Default
project_id	str	Identifier of the project	required
fields	List[str]	All the fields to request among the possible fields for the labels. See the documentation for all possible fields.	['author.email', 'author.id', 'createdAt', 'id', 'labelType', 'skipped']
asset_fields	List[str]	All the fields to request among the possible fields for the assets. See the documentation for all possible fields.	['externalId']

Returns:

Type	Description
DataFrame	pandas DataFrame containing the labels.

Source code in kili/queries/label/__init__.py

@typechecked
def export_labels_as_df(self,
                        project_id: str,
                        fields: List[str] = [
                            'author.email',
                            'author.id',
                            'createdAt',
                            'id',
                            'labelType',
                            'skipped'
                        ],
                        asset_fields: List[str] = [
                            'externalId'
                        ]) -> pd.DataFrame:
    # pylint: disable=line-too-long
    """Get the labels of a project as a pandas DataFrame.

    Args:
        project_id: Identifier of the project
        fields: All the fields to request among the possible fields for the labels.
            See [the documentation](https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#label) for all possible fields.
        asset_fields: All the fields to request among the possible fields for the assets.
            See [the documentation](https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#asset) for all possible fields.

    Returns:
        pandas DataFrame containing the labels.
    """
    projects = QueriesProject(self.auth).projects(project_id)
    assert len(projects) == 1, NO_ACCESS_RIGHT
    assets = QueriesAsset(self.auth).assets(
        project_id=project_id,
        fields=asset_fields + ['labels.' + field for field in fields])
    labels = [dict(label, **dict((f'asset_{key}', asset[key]) for key in asset if key != 'labels'))
              for asset in assets for label in asset['labels']]
    labels_df = pd.DataFrame(labels)
    return labels_df

labels(self, asset_id=None, asset_status_in=None, asset_external_id_in=None, author_in=None, created_at=None, created_at_gte=None, created_at_lte=None, fields=['author.email', 'author.id', 'id', 'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'], first=None, honeypot_mark_gte=None, honeypot_mark_lte=None, id_contains=None, json_response_contains=None, label_id=None, project_id=None, skip=0, skipped=None, type_in=None, user_id=None, disable_tqdm=False, as_generator=False)

Get a label list or a label generator from a project based on a set of criteria.

Parameters:

Name	Type	Description	Default
asset_id	Optional[str]	Identifier of the asset.	None
asset_status_in	Optional[List[str]]	Returned labels should have a status that belongs to that list, if given. Possible choices : TODO, ONGOING, LABELED or REVIEWED	None
asset_external_id_in	Optional[List[str]]	Returned labels should have an external id that belongs to that list, if given.	None
author_in	Optional[List[str]]	Returned labels should have a label whose status belongs to that list, if given.	None
created_at	Optional[str]	Returned labels should have a label whose creation date is equal to this date.	None
created_at_gte	Optional[str]	Returned labels should have a label whose creation date is greater than this date.	None
created_at_lte	Optional[str]	Returned labels should have a label whose creation date is lower than this date.	None
fields	List[str]	All the fields to request among the possible fields for the labels. See the documentation for all possible fields.	['author.email', 'author.id', 'id', 'jsonResponse', 'labelType', 'secondsToLabel', 'skipped']
first	Optional[int]	Maximum number of labels to return.	None
honeypot_mark_gte	Optional[float]	Returned labels should have a label whose honeypot is greater than this number.	None
honeypot_mark_lte	Optional[float]	Returned labels should have a label whose honeypot is lower than this number.	None
id_contains	Optional[List[str]]	Filters out labels not belonging to that list. If empty, no filtering is applied.	None
json_response_contains	Optional[List[str]]	Returned labels should have a substring of the jsonResponse that belongs to that list, if given.	None
label_id	Optional[str]	Identifier of the label.	None
project_id	Optional[str]	Identifier of the project.	None
skip	int	Number of labels to skip (they are ordered by their date of creation, first to last).	0
skipped	Optional[bool]	Returned labels should have a label which is skipped	None
type_in	Optional[List[str]]	Returned labels should have a label whose type belongs to that list, if given.	None
user_id	Optional[str]	Identifier of the user.	None
disable_tqdm	bool	If True, the progress bar will be disabled	False
as_generator	bool	If True, a generator on the labels is returned.	False

Dates format

Date strings should have format: "YYYY-MM-DD"

Returns:

Type	Description
Union[List[dict], Generator[dict, NoneType]]	A result object which contains the query if it was successful, else an error message.

Examples:

>>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
>>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project

Source code in kili/queries/label/__init__.py

@Compatible(['v1', 'v2'])
@typechecked
def labels(self,
           asset_id: Optional[str] = None,
           asset_status_in: Optional[List[str]] = None,
           asset_external_id_in: Optional[List[str]] = None,
           author_in: Optional[List[str]] = None,
           created_at: Optional[str] = None,
           created_at_gte: Optional[str] = None,
           created_at_lte: Optional[str] = None,
           fields: List[str] = ['author.email', 'author.id', 'id',
                                'jsonResponse', 'labelType', 'secondsToLabel', 'skipped'],
           first: Optional[int] = None,
           honeypot_mark_gte: Optional[float] = None,
           honeypot_mark_lte: Optional[float] = None,
           id_contains: Optional[List[str]] = None,
           json_response_contains: Optional[List[str]] = None,
           label_id: Optional[str] = None,
           project_id: Optional[str] = None,
           skip: int = 0,
           skipped: Optional[bool] = None,
           type_in: Optional[List[str]] = None,
           user_id: Optional[str] = None,
           disable_tqdm: bool = False,
           as_generator: bool = False,
           ) -> Union[List[dict], Generator[dict, None, None]]:
    # pylint: disable=line-too-long
    """Get a label list or a label generator from a project based on a set of criteria.

    Args:
        asset_id: Identifier of the asset.
        asset_status_in: Returned labels should have a status that belongs to that list, if given.
            Possible choices : `TODO`, `ONGOING`, `LABELED` or `REVIEWED`
        asset_external_id_in: Returned labels should have an external id that belongs to that list, if given.
        author_in: Returned labels should have a label whose status belongs to that list, if given.
        created_at: Returned labels should have a label whose creation date is equal to this date.
        created_at_gte: Returned labels should have a label whose creation date is greater than this date.
        created_at_lte: Returned labels should have a label whose creation date is lower than this date.
        fields: All the fields to request among the possible fields for the labels.
            See [the documentation](https://cloud.kili-technology.com/docs/python-graphql-api/graphql-api/#label) for all possible fields.
        first: Maximum number of labels to return.
        honeypot_mark_gte: Returned labels should have a label whose honeypot is greater than this number.
        honeypot_mark_lte: Returned labels should have a label whose honeypot is lower than this number.
        id_contains: Filters out labels not belonging to that list. If empty, no filtering is applied.
        json_response_contains: Returned labels should have a substring of the jsonResponse that belongs
            to that list, if given.
        label_id: Identifier of the label.
        project_id: Identifier of the project.
        skip: Number of labels to skip (they are ordered by their date of creation, first to last).
        skipped: Returned labels should have a label which is skipped
        type_in: Returned labels should have a label whose type belongs to that list, if given.
        user_id: Identifier of the user.
        disable_tqdm: If `True`, the progress bar will be disabled
        as_generator: If `True`, a generator on the labels is returned.

    !!! info "Dates format"
        Date strings should have format: "YYYY-MM-DD"

    Returns:
        A result object which contains the query if it was successful, else an error message.

    Examples:
        >>> kili.labels(project_id=project_id, fields=['jsonResponse', 'labelOf.externalId']) # returns a list of all labels of a project and their assets external ID
        >>> kili.labels(project_id=project_id, fields=['jsonResponse'], as_generator=True) # returns a generator of all labels of a project
    """

    saved_args = locals()
    count_args = {
        k: v
        for (k, v) in saved_args.items()
        if k
        not in [
            'as_generator',
            'disable_tqdm',
            'fields',
            'first',
            'id_contains',
            'self',
            'skip',
        ]
    }

    # using tqdm with a generator is messy, so it is always disabled
    disable_tqdm = disable_tqdm or as_generator

    payload_query = {
        'where': {
            'id': label_id,
            'asset': {
                'id': asset_id,
                'externalIdIn': asset_external_id_in,
                'statusIn': asset_status_in,
            },
            'project': {
                'id': project_id,
            },
            'user': {
                'id': user_id,
            },
            'createdAt': created_at,
            'createdAtGte': created_at_gte,
            'createdAtLte': created_at_lte,
            'authorIn': author_in,
            'honeypotMarkGte': honeypot_mark_gte,
            'honeypotMarkLte': honeypot_mark_lte,
            'idIn': id_contains,
            'jsonResponseContains': json_response_contains,
            'skipped': skipped,
            'typeIn': type_in,
        },
    }

    labels_generator = row_generator_from_paginated_calls(
        skip,
        first,
        self.count_labels,
        count_args,
        self._query_labels,
        payload_query,
        fields,
        disable_tqdm
    )

    if as_generator:
        return labels_generator
    return list(labels_generator)

Mutations

Set of Label mutations.

Source code in kili/mutations/label/__init__.py

class MutationsLabel:
    """Set of Label mutations."""
    # pylint: disable=too-many-arguments,too-many-locals

    def __init__(self, auth):
        """Initializes the subclass.

        Args:
            auth: KiliAuth object
        """
        self.auth = auth

    @Compatible(['v1', 'v2'])
    @typechecked
    def create_predictions(
            self,
            project_id: str,
            external_id_array: List[str],
            model_name_array: List[str],
            json_response_array: List[dict]):
        # pylint: disable=line-too-long
        """Create predictions for specific assets.

        Args:
            project_id: Identifier of the project
            external_id_array: The external identifiers of the assets for which we want to add predictions
            model_name_array: In case you want to precise from which model the label originated
            json_response_array: The predictions are given here. For examples,
                see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).

        Returns:
            A result object which indicates if the mutation was successful, or an error message.

        !!! example "Recipe"
            For more detailed examples on how to create predictions, see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).
        """
        assert len(external_id_array) == len(
            json_response_array), "IDs list and predictions list should have the same length"
        assert len(external_id_array) == len(
            model_name_array), "IDs list and model names list should have the same length"
        if len(external_id_array) == 0:
            warnings.warn("Empty IDs and prediction list")

        properties_to_batch = {'external_id_array': external_id_array,
                               'model_name_array': model_name_array,
                               'json_response_array': json_response_array}

        def generate_variables(batch):
            return {
                'data': {'modelNameArray': batch['model_name_array'],
                         'jsonResponseArray': [dumps(elem) for elem in batch['json_response_array']]},
                'where': {'externalIdStrictlyIn': batch['external_id_array'], 'project': {'id': project_id}}
            }

        results = _mutate_from_paginated_call(
            self, properties_to_batch, generate_variables, GQL_CREATE_PREDICTIONS)
        return format_result('data', results[0], Label)

    @Compatible(['v1', 'v2'])
    @typechecked
    def append_to_labels(self, json_response: dict, author_id: Optional[str] = None,
                         label_asset_external_id: Optional[str] = None,
                         label_asset_id: Optional[str] = None, label_type: str = 'DEFAULT',
                         project_id: Optional[str] = None, seconds_to_label: Optional[int] = 0,
                         skipped: Optional[bool] = False):
        """Append a label to an asset.

        Args:
            json_response: Label is given here
            author_id: ID of the author of the label
            label_asset_external_id: External identifier of the asset
            label_asset_id: Identifier of the asset
            project_id: Identifier of the project
            label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION` or `REVIEW`
            seconds_to_label: Time to create the label
            skipped: Describe if the label is skipped or not

        !!! warning
            Either provide `label_asset_id` or `label_asset_external_id` and `project_id`

        Returns:
            A result object which indicates if the mutation was successful,
                or an error message.

        Examples:
            >>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})

        """

        if author_id is None:
            author_id = self.auth.user_id
        label_asset_id = infer_id_from_external_id(
            self, label_asset_id, label_asset_external_id, project_id)
        variables = {
            'data': {'authorID': author_id,
                     'jsonResponse': dumps(json_response),
                     'labelType': label_type,
                     'secondsToLabel': seconds_to_label,
                     'skipped': skipped},
            'where': {'id': label_asset_id}
        }
        result = self.auth.client.execute(GQL_APPEND_TO_LABELS, variables)
        return format_result('data', result, Label)

    @Compatible(['v1', 'v2'])
    @typechecked
    def update_properties_in_label(self,
                                   label_id: str,
                                   seconds_to_label: Optional[int] = None,
                                   model_name: Optional[str] = None,
                                   json_response: Optional[dict] = None):
        """Update properties of a label.

        Args:
            label_id: Identifier of the label
            seconds_to_label: Time to create the label
            model_name: Name of the model
            json_response: The label is given here

        Returns:
            A result object which indicates if the mutation was successful,
                or an error message.

        Examples:
            >>> kili.update_properties_in_label(label_id=label_id, json_response={...})
        """
        formatted_json_response = None if json_response is None else dumps(
            json_response)
        variables = {
            'labelID': label_id,
            'secondsToLabel': seconds_to_label,
            'modelName': model_name,
            'jsonResponse': formatted_json_response
        }
        result = self.auth.client.execute(
            GQL_UPDATE_PROPERTIES_IN_LABEL, variables)
        return format_result('data', result, Label)

    @Compatible(['v1', 'v2'])
    @typechecked
    def create_honeypot(self, json_response: dict, asset_external_id: Optional[str] = None,
                        asset_id: Optional[str] = None, project_id: Optional[str] = None):
        """Create honeypot for an asset.

        !!! info
            Uses the given `json_response` to create a `REVIEW` label.
            This enables Kili to compute a`honeypotMark`,
            which measures the similarity between this label and other labels.

        Args:
            json_response: The JSON response of the honeypot label of the asset
            asset_id: Identifier of the asset
                Either provide asset_id or asset_external_id and project_id
            asset_external_id: External identifier of the asset
                Either provide asset_id or asset_external_id and project_id
            project_id: Identifier of the project
                Either provide asset_id or asset_external_id and project_id

        Returns:
            A result object which indicates if the mutation was successful,
                or an error message.
        """
        asset_id = infer_id_from_external_id(
            self, asset_id, asset_external_id, project_id)

        variables = {
            'data': {'jsonResponse': dumps(json_response)},
            'where': {'id': asset_id}
        }
        result = self.auth.client.execute(GQL_CREATE_HONEYPOT, variables)
        return format_result('data', result, Label)

append_to_labels(self, json_response, author_id=None, label_asset_external_id=None, label_asset_id=None, label_type='DEFAULT', project_id=None, seconds_to_label=0, skipped=False)

Append a label to an asset.

Parameters:

Name	Type	Description	Default
json_response	dict	Label is given here	required
author_id	Optional[str]	ID of the author of the label	None
label_asset_external_id	Optional[str]	External identifier of the asset	None
label_asset_id	Optional[str]	Identifier of the asset	None
project_id	Optional[str]	Identifier of the project	None
label_type	str	Can be one of AUTOSAVE, DEFAULT, PREDICTION or REVIEW	'DEFAULT'
seconds_to_label	Optional[int]	Time to create the label	0
skipped	Optional[bool]	Describe if the label is skipped or not	False

Warning

Either provide label_asset_id or label_asset_external_id and project_id

Returns:

Type	Description
	A result object which indicates if the mutation was successful, or an error message.

Examples:

>>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})

Source code in kili/mutations/label/__init__.py

@Compatible(['v1', 'v2'])
@typechecked
def append_to_labels(self, json_response: dict, author_id: Optional[str] = None,
                     label_asset_external_id: Optional[str] = None,
                     label_asset_id: Optional[str] = None, label_type: str = 'DEFAULT',
                     project_id: Optional[str] = None, seconds_to_label: Optional[int] = 0,
                     skipped: Optional[bool] = False):
    """Append a label to an asset.

    Args:
        json_response: Label is given here
        author_id: ID of the author of the label
        label_asset_external_id: External identifier of the asset
        label_asset_id: Identifier of the asset
        project_id: Identifier of the project
        label_type: Can be one of `AUTOSAVE`, `DEFAULT`, `PREDICTION` or `REVIEW`
        seconds_to_label: Time to create the label
        skipped: Describe if the label is skipped or not

    !!! warning
        Either provide `label_asset_id` or `label_asset_external_id` and `project_id`

    Returns:
        A result object which indicates if the mutation was successful,
            or an error message.

    Examples:
        >>> kili.append_to_labels(label_asset_id=asset_id, json_response={...})

    """

    if author_id is None:
        author_id = self.auth.user_id
    label_asset_id = infer_id_from_external_id(
        self, label_asset_id, label_asset_external_id, project_id)
    variables = {
        'data': {'authorID': author_id,
                 'jsonResponse': dumps(json_response),
                 'labelType': label_type,
                 'secondsToLabel': seconds_to_label,
                 'skipped': skipped},
        'where': {'id': label_asset_id}
    }
    result = self.auth.client.execute(GQL_APPEND_TO_LABELS, variables)
    return format_result('data', result, Label)

create_honeypot(self, json_response, asset_external_id=None, asset_id=None, project_id=None)

Create honeypot for an asset.

Info

Uses the given json_response to create a REVIEW label. This enables Kili to compute ahoneypotMark, which measures the similarity between this label and other labels.

Parameters:

Name	Type	Description	Default
json_response	dict	The JSON response of the honeypot label of the asset	required
asset_id	Optional[str]	Identifier of the asset Either provide asset_id or asset_external_id and project_id	None
asset_external_id	Optional[str]	External identifier of the asset Either provide asset_id or asset_external_id and project_id	None
project_id	Optional[str]	Identifier of the project Either provide asset_id or asset_external_id and project_id	None

Returns:

Type	Description
	A result object which indicates if the mutation was successful, or an error message.

Source code in kili/mutations/label/__init__.py

@Compatible(['v1', 'v2'])
@typechecked
def create_honeypot(self, json_response: dict, asset_external_id: Optional[str] = None,
                    asset_id: Optional[str] = None, project_id: Optional[str] = None):
    """Create honeypot for an asset.

    !!! info
        Uses the given `json_response` to create a `REVIEW` label.
        This enables Kili to compute a`honeypotMark`,
        which measures the similarity between this label and other labels.

    Args:
        json_response: The JSON response of the honeypot label of the asset
        asset_id: Identifier of the asset
            Either provide asset_id or asset_external_id and project_id
        asset_external_id: External identifier of the asset
            Either provide asset_id or asset_external_id and project_id
        project_id: Identifier of the project
            Either provide asset_id or asset_external_id and project_id

    Returns:
        A result object which indicates if the mutation was successful,
            or an error message.
    """
    asset_id = infer_id_from_external_id(
        self, asset_id, asset_external_id, project_id)

    variables = {
        'data': {'jsonResponse': dumps(json_response)},
        'where': {'id': asset_id}
    }
    result = self.auth.client.execute(GQL_CREATE_HONEYPOT, variables)
    return format_result('data', result, Label)

create_predictions(self, project_id, external_id_array, model_name_array, json_response_array)

Create predictions for specific assets.

Parameters:

Name	Type	Description	Default
project_id	str	Identifier of the project	required
external_id_array	List[str]	The external identifiers of the assets for which we want to add predictions	required
model_name_array	List[str]	In case you want to precise from which model the label originated	required
json_response_array	List[dict]	The predictions are given here. For examples, see the recipe.	required

Returns:

Type	Description
	A result object which indicates if the mutation was successful, or an error message.

Recipe

For more detailed examples on how to create predictions, see the recipe.

Source code in kili/mutations/label/__init__.py

@Compatible(['v1', 'v2'])
@typechecked
def create_predictions(
        self,
        project_id: str,
        external_id_array: List[str],
        model_name_array: List[str],
        json_response_array: List[dict]):
    # pylint: disable=line-too-long
    """Create predictions for specific assets.

    Args:
        project_id: Identifier of the project
        external_id_array: The external identifiers of the assets for which we want to add predictions
        model_name_array: In case you want to precise from which model the label originated
        json_response_array: The predictions are given here. For examples,
            see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).

    Returns:
        A result object which indicates if the mutation was successful, or an error message.

    !!! example "Recipe"
        For more detailed examples on how to create predictions, see [the recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/import_predictions.ipynb).
    """
    assert len(external_id_array) == len(
        json_response_array), "IDs list and predictions list should have the same length"
    assert len(external_id_array) == len(
        model_name_array), "IDs list and model names list should have the same length"
    if len(external_id_array) == 0:
        warnings.warn("Empty IDs and prediction list")

    properties_to_batch = {'external_id_array': external_id_array,
                           'model_name_array': model_name_array,
                           'json_response_array': json_response_array}

    def generate_variables(batch):
        return {
            'data': {'modelNameArray': batch['model_name_array'],
                     'jsonResponseArray': [dumps(elem) for elem in batch['json_response_array']]},
            'where': {'externalIdStrictlyIn': batch['external_id_array'], 'project': {'id': project_id}}
        }

    results = _mutate_from_paginated_call(
        self, properties_to_batch, generate_variables, GQL_CREATE_PREDICTIONS)
    return format_result('data', results[0], Label)

update_properties_in_label(self, label_id, seconds_to_label=None, model_name=None, json_response=None)

Update properties of a label.

Parameters:

Name	Type	Description	Default
label_id	str	Identifier of the label	required
seconds_to_label	Optional[int]	Time to create the label	None
model_name	Optional[str]	Name of the model	None
json_response	Optional[dict]	The label is given here	None

Returns:

Type	Description
	A result object which indicates if the mutation was successful, or an error message.

Examples:

>>> kili.update_properties_in_label(label_id=label_id, json_response={...})

Source code in kili/mutations/label/__init__.py

@Compatible(['v1', 'v2'])
@typechecked
def update_properties_in_label(self,
                               label_id: str,
                               seconds_to_label: Optional[int] = None,
                               model_name: Optional[str] = None,
                               json_response: Optional[dict] = None):
    """Update properties of a label.

    Args:
        label_id: Identifier of the label
        seconds_to_label: Time to create the label
        model_name: Name of the model
        json_response: The label is given here

    Returns:
        A result object which indicates if the mutation was successful,
            or an error message.

    Examples:
        >>> kili.update_properties_in_label(label_id=label_id, json_response={...})
    """
    formatted_json_response = None if json_response is None else dumps(
        json_response)
    variables = {
        'labelID': label_id,
        'secondsToLabel': seconds_to_label,
        'modelName': model_name,
        'jsonResponse': formatted_json_response
    }
    result = self.auth.client.execute(
        GQL_UPDATE_PROPERTIES_IN_LABEL, variables)
    return format_result('data', result, Label)

Subscriptions

Set of Label subscriptions.

Source code in kili/subscriptions/label/__init__.py

@dataclass
class SubscriptionsLabel:
    """Set of Label subscriptions."""

    # pylint: disable=too-many-arguments,too-many-locals

    def __init__(self, auth):
        """Initialize the subclass.

        Args:
            auth: KiliAuth object
        """
        self.auth = auth

    @typechecked
    def label_created_or_updated(self, project_id: str, callback: Callable[[str, str], None]):
        # pylint: disable=line-too-long
        """
        Subscribe a callback to a project, which is executed when a label is created or updated.

        Args:
            project_id: Identifier of the project
            callback: This function takes as input the id of the asset and its content.

        Returns:
            A subscription client

        !!! example "Recipe"
            For more detailed examples on how to use Webhooks,
            See [the related recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/webhooks.ipynb)
        """
        ws_endpoint = self.auth.client.endpoint.replace('http', 'ws')
        websocket = SubscriptionGraphQLClient(ws_endpoint)
        headers = {'Accept': 'application/json',
                   'Content-Type': 'application/json'}
        authorization = f'{self.auth.client.token}'
        headers['Authorization'] = authorization
        variables = {'projectID': project_id}
        websocket.subscribe(
            GQL_LABEL_CREATED_OR_UPDATED,
            variables=variables,
            callback=callback,
            headers=headers,
            authorization=authorization)
        return websocket

label_created_or_updated(self, project_id, callback)

Subscribe a callback to a project, which is executed when a label is created or updated.

Parameters:

Name	Type	Description	Default
project_id	str	Identifier of the project	required
callback	Callable[[str, str], NoneType]	This function takes as input the id of the asset and its content.	required

Returns:

Type	Description
	A subscription client

Recipe

For more detailed examples on how to use Webhooks, See the related recipe

Source code in kili/subscriptions/label/__init__.py

@typechecked
def label_created_or_updated(self, project_id: str, callback: Callable[[str, str], None]):
    # pylint: disable=line-too-long
    """
    Subscribe a callback to a project, which is executed when a label is created or updated.

    Args:
        project_id: Identifier of the project
        callback: This function takes as input the id of the asset and its content.

    Returns:
        A subscription client

    !!! example "Recipe"
        For more detailed examples on how to use Webhooks,
        See [the related recipe](https://github.com/kili-technology/kili-python-sdk/blob/master/recipes/webhooks.ipynb)
    """
    ws_endpoint = self.auth.client.endpoint.replace('http', 'ws')
    websocket = SubscriptionGraphQLClient(ws_endpoint)
    headers = {'Accept': 'application/json',
               'Content-Type': 'application/json'}
    authorization = f'{self.auth.client.token}'
    headers['Authorization'] = authorization
    variables = {'projectID': project_id}
    websocket.subscribe(
        GQL_LABEL_CREATED_OR_UPDATED,
        variables=variables,
        callback=callback,
        headers=headers,
        authorization=authorization)
    return websocket