﻿---
title: License
description: The license state of this device, and the calls that refresh, activate and deactivate it.
url: https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/
---

# License – Python API Reference – Deformable v0.1.0

The license of this device and user: its state, and the calls that refresh, activate and deactivate it. Every engine call checks the license first, and a call the license refuses fails with a license [`Status`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status); the error's message is written to show the user as it is, such as "Trial ended — Buy license" or "Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500".

The library keeps one license state per device and user, shared by every program that loads it: the plugins and the SDKs. [`license.status`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-status) never contacts the licensing service and is cheap enough to call on every redraw. [`license.refresh`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-refresh), [`license.activate`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-activate) and [`license.deactivate`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-deactivate) wait on the network for at most their timeout, so a host with an interface calls them off its interface thread. [`license.set_online_access`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-set_online_access) keeps a process off the network when its user asked for that.

Engine calls raise [`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror) when the trial or license does not allow them: [`LicenseRequiredError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenserequirederror) once the trial ended or the license was removed, [`TrialLimitExceededError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#triallimitexceedederror) for a trial scene past its tetrahedron limit, and [`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror) itself when one online check is needed.

## LicenseState

**Enum** · `deformable.LicenseState`

```python
class LicenseState(enum.IntEnum):
    NOT_STARTED = 0
    TRIAL = 1
    TRIAL_ENDED = 2
    LICENSED = 3
    NEEDS_ONLINE = 4
    DEVELOPMENT = 5
```

The license state of this device and user, as [`LicenseStatus.state`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestatus) reports it. Every program that loads the library shares it.

**Values**

- `NOT_STARTED` (`0`): No trial or license yet: the next [`refresh()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-refresh), or the first engine call, starts the trial online.
- `TRIAL` (`1`): The trial runs: every feature, at most [`LicenseStatus.tetrahedron_limit`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestatus) (2,500) tetrahedrons per scene.
- `TRIAL_ENDED` (`2`): The trial ended, or this device cannot have one; engine calls raise [`LicenseRequiredError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenserequirederror) until a license is activated.
- `LICENSED` (`3`): A license is active on this device; no limit.
- `NEEDS_ONLINE` (`4`): A license (or the trial) needs one online check before engine calls work again.
- `DEVELOPMENT` (`5`): A development build of the library: licensing is off, engine calls always work and nothing contacts the licensing service.

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [C `DeformableLicenseState`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/license/#deformablelicensestate) · [Rust `LicenseState`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#licensestate)

## LicenseStatus

**Data class** · `deformable.LicenseStatus`

```python
@dataclasses.dataclass(frozen=True)
class LicenseStatus:
    state: LicenseState | int
    days_left: int
    tetrahedron_limit: int | None
    usable: bool
    needs_online: bool
    has_license_key: bool
    message: str
```

The license state as a status line shows it.

**Fields**

- `state` ([`LicenseState`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate) or `int`): Which license state the device is in, which the other fields detail; a plain int for a state a newer library reports that this package does not know yet.
- `days_left` (`int`): In [`TRIAL`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-trial), the whole days left, 7 down to 1, counting the current day; 0 in any other state.
- `tetrahedron_limit` (`int` or `None`): The most tetrahedrons one scene may hold: 2,500 in [`TRIAL`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-trial); None when there is no limit.
- `usable` (`bool`): Engine calls work ([`TRIAL`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-trial), [`LICENSED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-licensed), [`DEVELOPMENT`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-development)).
- `needs_online` (`bool`): The state changes only after an online check ([`NOT_STARTED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-not_started), [`NEEDS_ONLINE`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-needs_online)).
- `has_license_key` (`bool`): A license key is stored on this device, so a host offers Deactivate rather than Activate.
- `message` (`str`): The status line: "Trial: 7 days left", "Trial ended — Buy license", "Licensed", ...

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [C `DeformableLicenseStatus`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/license/#deformablelicensestatus) · [Rust `LicenseStatus`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#licensestatus)

## license.status

**Function** · `deformable.license.status`

```python
def status() -> LicenseStatus
```

The license state of this device and user. It never contacts the licensing service and never waits on the network: it reads the per-user license state at most once every 2 seconds, so it is cheap enough to call on every redraw.

**Raises**

Only the errors every call can raise, which the [conventions](https://help.tangerina.io/deformable/v0.1.0/api-references/python/overview/#conventions) describe.

**Example**

```python
status = deformable.license.status()
if not status.usable:
    print(status.message)
```

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [C `deformable_license_status`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/license/#deformable_license_status) · [Rust `status`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#status)

## license.DEFAULT_TIMEOUT

**Constant** · `deformable.license.DEFAULT_TIMEOUT`

```python
DEFAULT_TIMEOUT = 15.0
```

How long [`refresh()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-refresh), [`activate()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-activate) and [`deactivate()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-deactivate) wait for the licensing service by default, in seconds. The library counts anything above 60 seconds as 60 seconds.

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [Rust `DEFAULT_TIMEOUT`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#default_timeout)

## license.refresh

**Function** · `deformable.license.refresh`

```python
def refresh(timeout: float = DEFAULT_TIMEOUT) -> LicenseStatus
```

Brings the license up to date with the licensing service when a contact is due, waiting at most `timeout` seconds. A device that never started its trial starts it; a trial reports itself once a day and keeps the earliest start the service remembers for this device, so a reinstall does not restart it; a stored license renews when its last renewal is 6 hours old or it needs online. Otherwise nothing is sent.

It waits on the network with the global interpreter lock released, so a host with an interface runs it off its main thread, such as when the program starts. Contacts run one at a time per process: a second caller waits for the first.

**Parameters**

- `timeout` (`float`): How long to wait for the service, in seconds, rounded up to whole milliseconds. The library counts anything above 60 seconds as 60 seconds.

**Returns**

[`LicenseStatus`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestatus): The license state after the call. After a failure, [`status()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-status) gives the state to show.

**Raises**

[`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror) with one of these statuses:

- [`LICENSE_SERVICE_UNAVAILABLE`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_service_unavailable): The service could not be reached, refused this copy of the library, or gave an answer that did not verify, or [`set_online_access()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-set_online_access) forbade every contact.
- [`LICENSE_KEY_REJECTED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_key_rejected): The service no longer accepts the stored license: it was revoked, this device was removed, or it is not a Deformable license. The license is then forgotten.
- [`LICENSE_STORAGE_FAILED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_storage_failed): The per-user license state could not be written; the message names its folder.

`TypeError` when `timeout` is a bool, or neither an int nor a float.

`ValueError` when `timeout` is NaN, 0 or less.

**Example**

```python
try:
    status = deformable.license.refresh()
except deformable.LicenseError as error:
    print(error.message)
```

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [C `deformable_license_refresh`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/license/#deformable_license_refresh) · [Rust `refresh`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#refresh)

## license.activate

**Function** · `deformable.license.activate`

```python
def activate(
    license_key: str,
    timeout: float = DEFAULT_TIMEOUT,
) -> LicenseStatus
```

Activates `license_key` on this device with the licensing service, waiting at most `timeout` seconds; the state is then [`LICENSED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestate-licensed). A key already active here is renewed instead. It waits on the network with the global interpreter lock released, so a host with an interface runs it off its main thread.

The error's message says why the key was not activated, written to show the user as it is.

**Parameters**

- `license_key` (`str`): The license key, such as `"TGDF-XXXX-XXXX-XXXX"`; letter case, spaces and dashes do not matter.
- `timeout` (`float`): How long to wait for the service, in seconds, rounded up to whole milliseconds. The library counts anything above 60 seconds as 60 seconds.

**Returns**

[`LicenseStatus`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestatus): The license state after the activation. After a license failure, [`status()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-status) gives the state to show.

**Raises**

[`DeformableError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#deformableerror) with one of these statuses; the license ones raise its subclass [`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror):

- [`INVALID_ARGUMENT`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-invalid_argument): `license_key` is no license key, or another key is stored on this device: deactivate it first. Nothing changes then.
- [`LICENSE_KEY_REJECTED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_key_rejected): The service refused the key: it does not exist, was revoked or expired, is not a Deformable license, or its seat is in use on another device; or the service takes no more devices.
- [`LICENSE_SERVICE_UNAVAILABLE`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_service_unavailable): The service could not be reached, refused this copy of the library, or gave an answer that did not verify, or [`set_online_access()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-set_online_access) forbade every contact.
- [`LICENSE_STORAGE_FAILED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_storage_failed): The per-user license state could not be written; the message names its folder.

`ValueError` when `license_key` is not a string, is empty or blank, or holds a NUL character, or when `timeout` is NaN, 0 or less.

`TypeError` when `timeout` is a bool, or neither an int nor a float.

**Example**

```python
try:
    status = deformable.license.activate("TGDF-XXXX-XXXX-XXXX")
except deformable.DeformableError as error:
    print(error.message)
```

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [C `deformable_license_activate`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/license/#deformable_license_activate) · [Rust `activate`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#activate)

## license.deactivate

**Function** · `deformable.license.deactivate`

```python
def deactivate(timeout: float = DEFAULT_TIMEOUT) -> LicenseStatus
```

Frees this device's seat with the licensing service, then forgets the key, waiting at most `timeout` seconds, so the license can be activated on another computer. The key is forgotten only once the service confirms, or says the seat is already gone. With no key stored it does nothing and succeeds. It waits on the network with the global interpreter lock released, so a host with an interface runs it off its main thread.

**Parameters**

- `timeout` (`float`): How long to wait for the service, in seconds, rounded up to whole milliseconds. The library counts anything above 60 seconds as 60 seconds.

**Returns**

[`LicenseStatus`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#licensestatus): The license state after the deactivation. After a failure, [`status()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-status) gives the state to show.

**Raises**

[`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror) with one of these statuses:

- [`LICENSE_SERVICE_UNAVAILABLE`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_service_unavailable): The service could not be reached or did not confirm, or [`set_online_access()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-set_online_access) forbade every contact. Nothing changes then; the device can also be removed in the license portal.
- [`LICENSE_STORAGE_FAILED`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_storage_failed): The per-user license state could not be written; the message names its folder.

`TypeError` when `timeout` is a bool, or neither an int nor a float.

`ValueError` when `timeout` is NaN, 0 or less.

**Example**

```python
status = deformable.license.deactivate()
status.has_license_key
# False
```

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [C `deformable_license_deactivate`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/license/#deformable_license_deactivate) · [Rust `deactivate`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#deactivate)

## license.set_online_access

**Function** · `deformable.license.set_online_access`

```python
def set_online_access(allowed: bool) -> None
```

Allows (the default) or forbids every contact with the licensing service from this process, for a host whose user turned online access off. Forbidden, nothing is sent: [`refresh()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-refresh), [`activate()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-activate) and [`deactivate()`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/license/#license-deactivate) raise [`LicenseError`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#licenseerror) with [`LICENSE_SERVICE_UNAVAILABLE`](https://help.tangerina.io/deformable/v0.1.0/api-references/python/errors/#status-license_service_unavailable) and change nothing, and engine calls neither start the trial nor renew the license on their own, so a state that needs the service stays as it is and a lease runs out as it would offline. It grants nothing, and it fails only when the library fails inside.

**Parameters**

- `allowed` (`bool`): True allows every contact, False forbids them.

**Raises**

Only the errors every call can raise, which the [conventions](https://help.tangerina.io/deformable/v0.1.0/api-references/python/overview/#conventions) describe.

**Example**

```python
# The user turned online access off in the host's settings.
deformable.license.set_online_access(False)
```

**See also** [Guide: License](https://help.tangerina.io/deformable/v0.1.0/user-guides/python/getting-started/#license) · [C `deformable_license_set_online_access`](https://help.tangerina.io/deformable/v0.1.0/api-references/c/license/#deformable_license_set_online_access) · [Rust `set_online_access`](https://help.tangerina.io/deformable/v0.1.0/api-references/rust/license/#set_online_access)
