> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orm.label set

Wire shapes of the label set routes under `/v2/public/label-sets`.

Identifiers are `*_id` in Python and `*Uuid` on the wire.

## LabelSetOrigin Objects

```python theme={"dark"}
class LabelSetOrigin(CamelStrEnum)
```

Where the labels of a label set come from.

**Values:**

* **WORKFLOW:** Labels made in the project's own workflow.
* **IMPORT:** Labels written to the branch from outside the project, such as model predictions. An imported label
  set has no scheduled versions.
* **UNKNOWN:** An origin this SDK version does not recognize.

#### \_missing\_

```python theme={"dark"}
@classmethod
def _missing_(cls, value: Any) -> LabelSetOrigin
```

Return UNKNOWN for any origin added to the platform after this SDK version.

## LabelSetVersionStatus Objects

```python theme={"dark"}
class LabelSetVersionStatus(CamelStrEnum)
```

Lifecycle of a label set version.

**Values:**

* **BUILDING:** The version is being captured.
* **READY:** The version holds its labels and can be exported.
* **FAILED:** The capture failed; the version holds no labels.
* **UNKNOWN:** A status this SDK version does not recognize.

#### \_missing\_

```python theme={"dark"}
@classmethod
def _missing_(cls, value: Any) -> LabelSetVersionStatus
```

Return UNKNOWN for any status added to the platform after this SDK version.

## LabelSetJobStatus Objects

```python theme={"dark"}
class LabelSetJobStatus(CamelStrEnum)
```

Status of a label set job: creating a version or exporting one.

**Values:**

* **PENDING:** The job is queued or running.
* **DONE:** The job finished and its result is available.
* **FAILED:** The job failed.
* **UNKNOWN:** A status this SDK version does not recognize.

#### \_missing\_

```python theme={"dark"}
@classmethod
def _missing_(cls, value: Any) -> LabelSetJobStatus
```

Return UNKNOWN for any status added to the platform after this SDK version.

## ExportFormat Objects

```python theme={"dark"}
class ExportFormat(CamelStrEnum)
```

Format of a label set version export.

**Values:**

* **JSON:** Encord's label JSON, one file per label row.
* **COCO:** COCO format.

## WorkflowStageSelection Objects

```python theme={"dark"}
class WorkflowStageSelection(BaseDTO)
```

A selection of the labels of the data units whose workflow task is at one of the listed stages.

The stages are read when a version is created, so each version captures the tasks at those stages at that time.
Workflow tasks exist on the `main` branch only, so the platform refuses this selection on any other branch.

**Example**:

```python theme={"dark"}
complete = project.workflow.get_stage(name="Complete")
selection = WorkflowStageSelection(workflow_stage_ids=[complete.uuid])
source = ProjectSource(project_id=project_id, label_selection=selection)
```

**Arguments**:

* `workflow_stage_ids` - The stages whose tasks a version captures. An empty list captures every label on the
  branch.

## AllSelection Objects

```python theme={"dark"}
class AllSelection(BaseDTO)
```

Every label on the branch. The explicit form of no selection; a selection is never `None`.

**Example**:

```python theme={"dark"}
label_set.set_label_selection(source.id, AllSelection())
```

## UnknownSelection Objects

```python theme={"dark"}
class UnknownSelection(BaseDTOWithExtra)
```

A selection this SDK version cannot set, kept as the platform sent it.

The selection was set through the platform's web app or its API with a shape this SDK does not expose, such as
a list of data units or a data title filter.

**Arguments**:

* `tag` - The shape's name. The other fields are available as attributes.

#### LabelSelection

A selection the SDK can set.

#### StoredLabelSelection

A selection as the platform returns it, which may be a shape this SDK version cannot set.

## ProjectSource Objects

```python theme={"dark"}
class ProjectSource(BaseDTO)
```

A project branch that feeds a label set, and which of its labels a version captures.

**Arguments**:

* `project_id` - The project.
* `branch_name` - The label branch a version captures.
* `label_selection` - Which of the branch's labels a version captures. [AllSelection](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#allselection-objects), the default, is
  every label on the branch. A [WorkflowStageSelection](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#workflowstageselection-objects) applies to the `main` branch only.

## StoredProjectSource Objects

```python theme={"dark"}
class StoredProjectSource(BaseDTO)
```

A source already attached to a label set.

**Arguments**:

* `id` - The source identifier, used when changing its selection.
* `project_id` - The project.
* `branch_name` - The label branch a version captures.
* `label_selection_mode` - The selection as the platform returned it, or `None` when a list response omitted
  it. Read it through `label_selection`, which refuses an omitted selection rather than reporting one.

#### label\_selection

```python theme={"dark"}
@property
def label_selection() -> StoredLabelSelection
```

The source's selection. [AllSelection](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#allselection-objects) is every label on the branch.

**Raises**:

* [`EncordException`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#encordexception-objects) - The selection was omitted from a list response. Call the
  label set's `refetch_data()` and read its sources again.

## UnknownSource Objects

```python theme={"dark"}
class UnknownSource(BaseDTOWithExtra)
```

A source of a kind this SDK version does not recognize, kept as the platform sent it.

**Arguments**:

* `tag` - The kind's name. The other fields are available as attributes.

#### StoredSource

A source as the platform returns it, which may be a kind this SDK version does not recognize.

## LabelSet Objects

```python theme={"dark"}
class LabelSet(BaseDTO)
```

A label set as the platform returns it.

**Arguments**:

* `id` - Unique identifier of the label set.
* `sources` - The project branches that feed the set. One source today. List results name each source without
  its selection; a single set carries them.
* `name` - Name of the label set.
* `description` - Description of the label set.
* `origin` - Where the set's labels come from.
* `created_by_email` - Email of the user who created the set.
* `created_at` - When the set was created.

## \_SelectionPayload Objects

```python theme={"dark"}
class _SelectionPayload(BaseDTO)
```

Keep nulls so a selection is sent whole: the platform requires every filter of a stage selection, including
the ones this SDK leaves unset.

#### to\_dict

```python theme={"dark"}
def to_dict(by_alias: bool = True,
            exclude_none: bool = False) -> Dict[str, Any]
```

Keep `None` by default so a stage selection's unset filters are sent as null.

## CreateLabelSetPayload Objects

```python theme={"dark"}
class CreateLabelSetPayload(_SelectionPayload)
```

Payload for creating a label set.

**Arguments**:

* `sources` - The project branches that feed the set, each with its selection. The platform accepts one today.
* `name` - Name of the label set.
* `description` - Description of the label set.
* `origin` - Where the branch's labels come from.

## UpdateLabelSetPayload Objects

```python theme={"dark"}
class UpdateLabelSetPayload(BaseDTO)
```

Payload for changing a label set's name or description. A field left as `None` is unchanged.

**Arguments**:

* `name` - New name.
* `description` - New description. An empty string clears it.

## SetLabelSelectionPayload Objects

```python theme={"dark"}
class SetLabelSelectionPayload(_SelectionPayload)
```

Payload for replacing one source's selection.

**Arguments**:

* `label_selection` - New selection; [AllSelection](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#allselection-objects) captures every label on the branch.

## LabelSetPageParams Objects

```python theme={"dark"}
class LabelSetPageParams(BaseDTO)
```

Query parameters for a paged list under a label set.

**Arguments**:

* `page_size` - Maximum number of results per page.
* `page_token` - Token for the next page, from the previous page.

## ListLabelSetsParams Objects

```python theme={"dark"}
class ListLabelSetsParams(LabelSetPageParams)
```

Query parameters for listing label sets.

**Arguments**:

* `project_id` - Only the sets this project feeds.
* `page_size` - Maximum number of sets per page.
* `page_token` - Token for the next page, from the previous page.

## CapturedSource Objects

```python theme={"dark"}
class CapturedSource(BaseDTO)
```

A project branch as a version captured it, with the ontology its labels were made against at the time.

**Arguments**:

* `project_id` - The project.
* `branch_name` - The label branch that was captured.
* `ontology_id` - The ontology the labels were made against.
* `ontology_version_id` - The ontology revision in force when the version was created. `None` for an ontology with no revision
  history.

#### StoredCapturedSource

A captured source as the platform returns it, which may be a kind this SDK version does not recognize.

## VersionOntology Objects

```python theme={"dark"}
class VersionOntology(BaseDTO)
```

The ontology definition a version's labels were made against, frozen when the version was created.

The ontology and revision ids are on the version's `sources`. The definition is served separately because a
shared class can be edited without a new revision, so the ids alone cannot tell two definitions apart.

**Arguments**:

* `editor` - The ontology definition, in the shape the ontology routes return.

## LabelSetVersion Objects

```python theme={"dark"}
class LabelSetVersion(BaseDTO)
```

A version of a label set: a frozen record of the labels captured when it was created.

**Arguments**:

* `id` - Unique identifier of the version.
* `label_set_id` - The label set the version belongs to.
* `sources` - What the version captured: each project branch and the ontology it used. One source today.
* `version_number` - Position of the version in the set, from 1.
* `name` - Name of the version.
* `status` - Lifecycle of the version.
* `created_by_email` - Email of the user who created the version.
* `capture_started_at` - When the capture started.
* `capture_finished_at` - When the capture finished, or `None` while it is building.
* `label_count` - How many labels the version holds. Set once the version is READY.

## LabelSetVersionMember Objects

```python theme={"dark"}
class LabelSetVersionMember(BaseDTO)
```

One label as a version holds it.

**Arguments**:

* `label_id` - The label row.
* `label_version` - The revision of the label row that was captured.
* `backing_item_id` - The storage item the label was on when captured.
* `data_title` - Title of the data unit.

## CreateVersionPayload Objects

```python theme={"dark"}
class CreateVersionPayload(BaseDTO)
```

Payload for creating a version.

**Arguments**:

* `name` - A label for the version, shown with its number. `None` means the number alone.

## LabelSetJob Objects

```python theme={"dark"}
class LabelSetJob(BaseDTO)
```

A queued label set job.

**Arguments**:

* `job_id` - The job, to poll for its result.

## LabelSetJobPending Objects

```python theme={"dark"}
class LabelSetJobPending(BaseDTO)
```

The job is queued or running. Poll again.

**Arguments**:

* `status` - Always PENDING.

## LabelSetJobUnknown Objects

```python theme={"dark"}
class LabelSetJobUnknown(BaseDTO)
```

A job state this SDK version does not recognize. Treat it as not done.

**Arguments**:

* `status` - UNKNOWN.

## VersionJobDone Objects

```python theme={"dark"}
class VersionJobDone(BaseDTO)
```

The version job finished.

**Arguments**:

* `status` - Always DONE.
* `version_id` - The version the job created.

## VersionJobFailed Objects

```python theme={"dark"}
class VersionJobFailed(BaseDTO)
```

The version job failed. No version was created.

**Arguments**:

* `status` - Always FAILED.
* `error` - Why the job failed.

#### VersionJob

The state of a version job: one of pending, done, failed, or a state this SDK version does not recognize.

## VersionJobResponse Objects

```python theme={"dark"}
class VersionJobResponse(RootModelDTO[VersionJob])
```

Wire envelope of a version job read; `root` is the state.

## CreateVersionExportPayload Objects

```python theme={"dark"}
class CreateVersionExportPayload(BaseDTO)
```

Payload for exporting a version.

**Arguments**:

* `format` - Format of the export.

## VersionExportJobDone Objects

```python theme={"dark"}
class VersionExportJobDone(BaseDTO)
```

The export finished.

**Arguments**:

* `status` - Always DONE.
* `signed_url` - A link to the archive, signed freshly on every read.

## VersionExportJobFailed Objects

```python theme={"dark"}
class VersionExportJobFailed(BaseDTO)
```

The export failed. Queue it again; a repeat failure is one for support.

**Arguments**:

* `status` - Always FAILED.

#### VersionExportJob

The state of an export job: one of pending, done, failed, or a state this SDK version does not recognize.

## VersionExportJobResponse Objects

```python theme={"dark"}
class VersionExportJobResponse(RootModelDTO[VersionExportJob])
```

Wire envelope of an export job read; `root` is the state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.