You are viewing the documentation for Deformable v0.5.0, an older version. Read the latest, v0.9.0

Python API Reference

License

The license state of this device, or of this program under an Application license, and the calls that refresh, activate and deactivate it.

On this page

The license: its state, and the calls that refresh, activate and deactivate it. Nothing ever refuses to run: without a license the Free license runs, and a scene simulates at most 2,500 tetrahedrons. Two licenses lift the limit: the Standalone license of this device and user, and the Application license that a program activates for itself. A license failure’s message is written to show the user as it is, such as “Free license: this would simulate 3,000 tetrahedrons; the limit is 2,500 per scene”.

license.activate takes both kinds of key. A Standalone key is activated online once and stays on the device; the library keeps one Standalone state per device and user, shared by every program that loads it: the plugins and the SDKs. An Application key is checked offline and holds for the process only, so a program activates it at every start, before any other engine call; with it, the other calls contact nothing, and a plugin host refuses it. license.status never contacts the licensing service and is cheap enough to call on every redraw. license.refresh, license.activate and 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 keeps a process off the network when its user asked for that.

  • The Standalone license runs on 1 device per seat. Its key and the lease our licensing service signs for this device belong to this device and user, and every program that loads the library shares them; activate(), refresh() and deactivate() activate, renew and deactivate it. The lease renews on its own while the engine runs, and a device may stay offline up to 7 days.
  • The Application license is a company’s, for one app it ships. Its key is checked offline and licenses the program that activates it, on any device, for as long as it runs: nothing is stored or sent, so the app activates its key at every start, as its first Deformable call, before status and refresh, and its users need nothing. The plugins refuse an Application key.

LicenseState

Enum · deformable.LicenseState

python
class LicenseState(enum.IntEnum):
    FREE_LICENSE = 0
    STANDALONE_LICENSE = 1
    NEEDS_ONLINE = 2
    DEVELOPMENT = 3
    APPLICATION_TRIAL = 4
    APPLICATION_TRIAL_ENDED = 5
    APPLICATION_LICENSE = 6

The license state of this program, as LicenseStatus.state reports it: its Application license, or else the Free or Standalone license of this device and user, which every program that loads the library shares.

Values

  • FREE_LICENSE (0)No license key: the Free license, at most LicenseStatus.tetrahedron_limit (2,500) tetrahedrons per scene.
  • STANDALONE_LICENSE (1)A Standalone license key with a lease that licenses this device; no limit.
  • NEEDS_ONLINE (2)A Standalone license key whose lease ran out, or that this device’s clock leaves untrusted: the Free license runs until the next renewal online.
  • DEVELOPMENT (3)A development build of the library: licensing is off, no limit, and nothing contacts the licensing service. It is not the Application license.
  • APPLICATION_TRIAL (4)An Application trial key runs in this program: no limit, until the key ends.
  • APPLICATION_TRIAL_ENDED (5)The Application trial key of this program ended: the Free license runs.
  • APPLICATION_LICENSE (6)A full Application license key runs in this program; no limit.

See also Guide: License · C DeformableLicenseState · Rust LicenseState

LicenseStatus

Data class · deformable.LicenseStatus

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

The license state as a status line shows it.

Fields

  • state (LicenseState or int)Which license state the program 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 APPLICATION_TRIAL, the whole days until the trial key ends counting the current day, 30 down to 1 for a 30-day key; 0 in any other state.
  • tetrahedron_limit (int or None)The most tetrahedrons one scene simulates: 2,500 under the Free license and every state that falls back to it; None when there is no limit.
  • has_license_key (bool)A Standalone license key is stored on this device, so a host offers Deactivate rather than Activate; never under an Application license.
  • message (str)The status line: “Free license: up to 2,500 tetrahedrons per scene — Buy license”, “Standalone license”, “Application trial: 30 days left”, “Application license: Acme Inc.”, … The company of an Application license is cut to fit.

See also Guide: License · C DeformableLicenseStatus · Rust LicenseStatus

license.status

Function · deformable.license.status

python
def status() -> LicenseStatus

The license state of this program: its Application license, or else the Free or Standalone license of this device and user. It never contacts the licensing service and never waits on the network: it reads the per-user license store 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 describe.

Example

python
status = deformable.license.status()
if status.tetrahedron_limit is not None:
    print(status.message)

See also Guide: License · C deformable_license_status · Rust status

license.DEFAULT_TIMEOUT

Constant · deformable.license.DEFAULT_TIMEOUT

python
DEFAULT_TIMEOUT = 15.0

How long refresh(), activate() and deactivate() wait for the licensing service by default, in seconds. The library counts anything above 60 seconds as 60 seconds.

See also Guide: License · Rust DEFAULT_TIMEOUT

license.refresh

Function · deformable.license.refresh

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

Renews the stored Standalone key’s lease when it no longer licenses this device, or when it is 6 hours old or ends within a day and no contact ran in the last 5 minutes, waiting at most timeout seconds. Without a key, and under an Application license, nothing is sent and it gives the state as it is. The library renews the lease on its own while the engine runs, so a host calls this when the program starts and when its user asks.

It waits on the network with the global interpreter lock released, so a host with an interface runs it off its main thread. 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: The license state after the call. After a failure, status() gives the state to show.

Raises

LicenseError with one of these statuses:

  • LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not answer, its answer did not verify or this device’s clock contradicts it, or set_online_access() forbade every contact. The lease is kept until it runs out.
  • LICENSE_KEY_REJECTEDThe service no longer accepts the key: it was revoked or refunded, or this device was removed. The license is then forgotten at once and the Free license runs.
  • LICENSE_STORAGE_FAILEDThe per-user license store 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 · C deformable_license_refresh · Rust refresh

license.activate

Function · deformable.license.activate

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

Activates license_key, a Standalone or an Application license key, told apart by their shape: a Standalone key is tgdfp-xxxxx-xxxxx-xxxxx-xxxxx, an Application key tgdfp-<payload hex>-<signature hex>.

A Standalone key is activated on this device with the licensing service, waiting at most timeout seconds; the state is then STANDALONE_LICENSE. The key already stored here renews its lease instead. It waits on the network with the global interpreter lock released, so a host with an interface runs it off its main thread.

An Application key is checked offline, without waiting, and licenses this program for as long as it runs: nothing is stored or sent, so the program calls this at every start, as its first Deformable call, before status and refresh. The state is then APPLICATION_LICENSE, or APPLICATION_TRIAL for a trial key. The same key again changes nothing. A full key covers the versions of the library released until its updates end, and keeps working in them forever. The plugins refuse an Application key. A development build of the library checks the key the same way but stays DEVELOPMENT.

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, where letter case does not matter and spaces and line breaks are removed.
  • 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. An Application key never waits.

Returns

LicenseStatus: The license state after the activation. After a license failure, status() gives the state to show.

Raises

DeformableError with one of these statuses; the license ones raise its subclass LicenseError:

  • INVALID_ARGUMENTlicense_key is no license key or an Application key that does not verify; another Standalone key is stored on this device: deactivate it first; another Application key is already set in this program; or it is a Standalone key in a program on an Application license. Nothing changes then.
  • LICENSE_KEY_REJECTEDThe service refused the Standalone key: it does not exist, was revoked or refunded, is not for Deformable, or every seat of the license is in use. Or the Application key was revoked, is a trial key that ended, covers only versions released before this one, or was given inside a plugin host.
  • LICENSE_SERVICE_UNAVAILABLEThe service could not be reached or did not answer, its answer did not verify or this device’s clock contradicts it, or set_online_access() forbade every contact.
  • LICENSE_STORAGE_FAILEDThe per-user license store 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
key = "tgdfp-xxxxx-xxxxx-xxxxx-xxxxx"
try:
    status = deformable.license.activate(key)
except deformable.DeformableError as error:
    print(error.message)
# An app on an Application license activates its key, exactly as
# copied from the Licenses page, first thing at every start.
# This one is shaped like an Application key but signed by
# nobody, so it is refused.
application_key = "tgdfp-7b2276657273696f6e223a317d-" + "0" * 128
try:
    status = deformable.license.activate(application_key)
except deformable.DeformableError as error:
    print(error.message)
# This license key is not valid

See also Guide: License · C deformable_license_activate · Rust activate

license.deactivate

Function · deformable.license.deactivate

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

Forgets the Standalone license on this device at once, even offline, so the Free license runs; then frees its seat with the licensing service, waiting at most timeout seconds, so the key can be activated on another device. When the seat cannot be freed, the customer removes this device on the Licenses page. With no key stored, or under an Application license, 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: The license state after the deactivation. After a failure, status() gives the state to show.

Raises

LicenseError with one of these statuses:

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 · C deformable_license_deactivate · Rust 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() and activate() raise LicenseError with LICENSE_SERVICE_UNAVAILABLE and change nothing, deactivate() forgets the license without freeing its seat, and the library never renews the lease on its own, so it runs out as it would offline. An Application key is checked offline and is not affected. 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 describe.

Example

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

See also Guide: License · C deformable_license_set_online_access · Rust set_online_access