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

Python API Reference

License

The license state of this device, or of this program under a Developer 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. There are two kinds: the Standard license of this device and user, and the Developer license that a program activates for itself. Every engine call checks the license first, and a call the license refuses fails with a license Status; the error’s message is written to show the user as it is, such as “Standard trial ended — Buy license” or “Trial limit: this would simulate 3,000 tetrahedrons; the trial allows 2,500”.

license.activate takes both kinds of key. A Standard key is activated online once and stays on the device; the library keeps one Standard state per device and user, shared by every program that loads it: the plugins and the SDKs. A Developer key holds a “.”, 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 Standard license is one person’s on one computer. It and its free trial belong to this device and user, and every program that loads the library shares them; refresh(), activate() and deactivate() start, renew, activate and deactivate it with our licensing service.
  • The Developer license is a company’s, for one app it ships. Its key is checked offline and licenses the program that activates it, on any computer, 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 a Developer key.

Engine calls raise LicenseError when the trial or license does not allow them: LicenseRequiredError once a trial ended or the Standard license was removed, TrialLimitExceededError for a Standard trial scene past its tetrahedron limit, and LicenseError itself when one online check is needed.

LicenseState

Enum · deformable.LicenseState

python
class LicenseState(enum.IntEnum):
    NOT_STARTED = 0
    STANDARD_TRIAL = 1
    STANDARD_TRIAL_ENDED = 2
    STANDARD_LICENSE = 3
    NEEDS_ONLINE = 4
    DEVELOPMENT = 5
    DEVELOPER_TRIAL = 6
    DEVELOPER_TRIAL_ENDED = 7
    DEVELOPER_LICENSE = 8

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

Values

  • NOT_STARTED (0)No Standard trial or license yet: the next refresh(), or the first engine call, starts the Standard trial online.
  • STANDARD_TRIAL (1)The Standard trial runs: every feature, at most LicenseStatus.tetrahedron_limit (2,500) tetrahedrons per scene.
  • STANDARD_TRIAL_ENDED (2)The Standard trial ended, or this device cannot have one; engine calls raise LicenseRequiredError until a license is activated.
  • STANDARD_LICENSE (3)A Standard license is active on this device; no limit.
  • NEEDS_ONLINE (4)A Standard license (or the Standard 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. It is not the Developer license.
  • DEVELOPER_TRIAL (6)A Developer trial key runs in this program: every feature and no limit, until the key ends.
  • DEVELOPER_TRIAL_ENDED (7)The Developer trial key of this program ended; engine calls raise LicenseRequiredError.
  • DEVELOPER_LICENSE (8)A Developer license key runs in this program; no limit and no end.

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
    usable: bool
    needs_online: bool
    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)The whole days left counting the current day: in STANDARD_TRIAL 7 down to 1, in DEVELOPER_TRIAL the days until the trial key ends, 30 down to 1 for a 30-day key; 0 in any other state.
  • tetrahedron_limit (int or None)The most tetrahedrons one scene may hold: 2,500 in STANDARD_TRIAL; None when there is no limit.
  • usable (bool)Engine calls work (STANDARD_TRIAL, STANDARD_LICENSE, DEVELOPER_TRIAL, DEVELOPER_LICENSE, DEVELOPMENT).
  • needs_online (bool)The state changes only after an online check (NOT_STARTED, NEEDS_ONLINE).
  • has_license_key (bool)A Standard license key is stored on this device, so a host offers Deactivate rather than Activate; never under a Developer license.
  • message (str)The status line: “Standard trial: 7 days left”, “Standard license”, “Developer trial: 30 days left”, “Developer license: Acme Inc.”, … The company of a Developer 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 Developer license, or else the Standard license 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 describe.

Example

python
status = deformable.license.status()
if not status.usable:
    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

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. Under a Developer license nothing is ever sent and it gives the Developer state.

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: 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, refused this copy of the library, or gave an answer that did not verify, or set_online_access() forbade every contact.
  • LICENSE_KEY_REJECTEDThe 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_FAILEDThe 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 · 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 Standard or a Developer license key: only a Developer key holds a ..

A Standard key is activated on this device with the licensing service, waiting at most timeout seconds; the state is then STANDARD_LICENSE. 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.

A Developer 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 DEVELOPER_LICENSE, or DEVELOPER_TRIAL for a trial key. The same key again changes nothing. The plugins refuse a Developer 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: a Standard key such as "TGDF-XXXX-XXXX-XXXX", where letter case, spaces and dashes do not matter, or a Developer key as it was sent, spaces around it aside.
  • 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. A Developer 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 a Developer key that does not verify; another Standard key is stored on this device: deactivate it first; another Developer key is already set in this program; or it is a Standard key in a program on a Developer license. Nothing changes then.
  • LICENSE_KEY_REJECTEDThe service refused the Standard 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. Or the Developer key was revoked, is a trial key that ended, or was given inside a plugin host, where only a Standard license works.
  • LICENSE_SERVICE_UNAVAILABLEThe service could not be reached, refused this copy of the library, or gave an answer that did not verify, or set_online_access() forbade every contact.
  • LICENSE_STORAGE_FAILEDThe 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)
# An app on a Developer license activates its key, as it was
# sent, first thing at every start. This one is a stand-in,
# refused as not valid.
developer_key = "TGDF-eyJ2ZXJzaW9uIjoxfQ.c2lnbmF0dXJl"
try:
    status = deformable.license.activate(developer_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

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, or under a Developer 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(), activate() and deactivate() raise LicenseError with 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. A Developer key is checked offline and is not affected, and under a Developer license refresh() and deactivate() contact nothing and succeed. 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