Resource

class activelogic.Resource

This is the parent class for all resources.

Connection instantiates all resources:

c = await conn.config()
rs = await conn.ruleset()

Each resource defines a subset of the system’s configuration and has its own set of privileges in the user database:

None - User can’t access the resource at all.
Read - User can run read-only commands on the resource.
Write - User can run all commands on the resource.

A session attached to the resource will always be in a transaction. There is also implicit locks on each resource that are taken when the first manipulative command is sent, and released when changes are committed or rolled back.

Changes to database-bound resources, such like Config and Ruleset must be committed to take effect. This either can be done using a context manager or by just calling commit():

# Alt 1.
async with await conn.config() as c:
    await c.update('DRDL_ENABLED', True)

# Alt 2.
await c.update('DRDL_ENABLED', True)
await c.commit()

Issuing commands on an outdated resource will result in that PLDBNewDataCommitted is raised.

class activelogic.Flag

Object representing a flag definition.

Parameters:: name (str) – Name of the flag definition.

class activelogic.Service

Object representing a service definition.

Parameters:: name (str) – Name of the service definition.

Resource.machineid

The machine id of the system that owns the resource.

>>> res.machineid
'001122334455'

Resource.distversion

The firmware version running on the system that owns the resource.

>>> res.distversion
'22.20.06.1'

async Resource.list(cls)

Generic list function for definitions that does not belong to any specific resource.

Parameters:

cls – Object type that determines what kind of data to get.

Returns:

A list of given dataclass type.

Raises:

ValueError – Invalid dataclass type.
PLDBNewDataCommitted – Conflict with new data committed by an other session.

Resources may override this method, but will fallback to this generic method if cls does not match any resource-specific type. Definitions listen in this method cannot be modified:

Service

Flag

List may or may not be cached, depending on if cache_enabled is set.

Transactions

Resource.set_commit_message(commit_message)

Sets the commit message of the next commit.

Parameters:: commit_message (str) –

This function is typically used for setting proper commit message in context manager-based commits:

>>> with conn.config() as c:
...     c.update("GEOLOGIC_ENABLED", True)
...     c.set_commit_message("Enable GeoLogic function")

async Resource.commit(commit_message=None)

Stores the current transaction to the database.

Parameters:: commit_message (str) – Message recorded in the commit log.

This command makes your changes visible to others.

It is usually a good practice to commit changes in batches. In particular if changes are committed to Ruleset. This will reload the ruleset and take a lot of CPU resources from the system.

async Resource.rollback()

Aborts the current transaction and discards the changes.

This also automatically happens if your connection drops or you exit the program without committing your changes.

async Resource.wait_for_commit()

Sits down and waits until another session commits changes to the resource.

>>> res.wait_for_commit()

The amount of time spent on waiting for the commit to happen, can be limited using the built-in timeout support:

try:
    await asyncio.wait_for(rs.wait_for_commit(), timeout=5)
except asyncio.TimeoutError:
    pass

Resource Cache

Resource.cache_set_enabled(enable)

Enables or disables the caching mechanism for the resource.

Parameters:: enable (bool) – True or False.

For optimal performance, caching should always be enabled. All resources have their caching enabled by default.

Resource.cache_invalidate(cache_id='')

Invalidates a specific cache, or all caches tied to the current resource.

The cache is always invalidated if the current transaction is rolled back or committed.

Parameters:: cache_id (str) – Id of the cache to invalidate, or empty if all caches should be invalidated.

Miscellaneous

async Resource.ping(data)

Sends a message to session to test if it is up.

Parameters:: data (bytes) – Data to send.
Returns:: The echo reply from remote session.

>>> res.ping(b"hello")
b'hello'