Skip to content

Subscription

Canonical path: o6.subscription.Subscription

Root shortcut: o6.Subscription

Subscription

A client subscription that groups monitored items.

Created by Client.createSubscription(...) rather than directly. A subscription owns its MonitoredItem objects and their common publishing schedule, so items can be enabled, retimed, and removed together.

Awaiting the subscription waits for the server to acknowledge creation, which is when its id becomes available. The subscription is falsy once deleted, and every operation on a deleted subscription raises RuntimeError.

All configuration properties are read-only and report the values the server revised, not the values requested.

See Managing subscriptions explicitly.

Attributes

client property 

client

The client that owns this subscription.

id property 

id

Server-assigned subscription id; None before creation and after deletion.

monitoredItems property 

monitoredItems

The items in this subscription, keyed by item id.

A copy, so adding or removing entries does not affect the subscription.

publishingInterval property 

publishingInterval

Publishing interval in milliseconds, as revised by the server.

lifetimeCount property 

lifetimeCount

Lifetime count in publishing intervals, as revised by the server.

maxKeepaliveCount property 

maxKeepaliveCount

Keepalive count in publishing intervals, as revised by the server.

maxNotificationsPerPublish property 

maxNotificationsPerPublish

Cap on notifications per Publish response. 0 means unlimited.

enabled property 

enabled

Whether the server is currently publishing notifications.

Functions

__init__ 

__init__(
    client,
    publishingInterval,
    lifetimeCount,
    maxKeepaliveCount,
    maxNotificationsPerPublish=10,
    publishingEnabled=True,
    onCreated=None,
    onStatusChange=None,
    onDeleted=None,
)

Request a new subscription from the server.

Prefer Client.createSubscription(...), which registers the result with the client. The CreateSubscription call is started here and completed when the subscription is awaited.

Parameters:

Name Type Description Default
client Client

The client that will own the subscription.

 required
publishingInterval float

Requested publishing interval in milliseconds.

 required
lifetimeCount int

Publishing intervals the server keeps the subscription alive without a Publish request.

 required
maxKeepaliveCount int

Publishing intervals without notifications after which the server sends a keepalive.

 required
maxNotificationsPerPublish int

Cap on notifications per Publish response. 0 means unlimited.

 10
publishingEnabled bool

Whether the server starts out publishing.

 True
onCreated Callable[['Subscription', CreateSubscriptionResponse], None] | None

Called when the server acknowledges creation, as (subscription, response). The subscription's own id is assigned after this runs, so read response.subscriptionId.

 None
onStatusChange Callable[['Subscription', StatusChangeNotification], None] | None

Called with (subscription, notification) when the server publishes a StatusChangeNotification, for example on a keepalive timeout or a session transfer.

 None
onDeleted Callable[['Subscription'], None] | None

Called with (subscription,) on explicit deletion and on session close.

 None

Raises:

Type Description
TypeError

A callback argument is not callable.

__await__ 

__await__()

Wait for the server to create this subscription, then return it.

delete 

delete()

Delete this subscription and every item in it.

The monitored items are deleted first, then the subscription itself. Deleting a subscription that is already gone logs a warning instead of raising.

Raises:

Type Description
RuntimeError

The owning client has been garbage-collected.
StatusCodeError

The DeleteSubscriptions service call failed.

modify 

modify(
    publishingInterval=None,
    lifetimeCount=None,
    maxKeepaliveCount=None,
    maxNotificationsPerPublish=None,
    publishingEnabled=None,
)

Change this subscription's publishing parameters on the server.

Omitted arguments keep their current value. The server may revise the timing values, and the revised values are stored back, so reading the properties afterwards reports what was actually granted. Changing publishingEnabled needs a second service call, which is only sent when the value actually differs.

Parameters:

Name Type Description Default
publishingInterval float | None

Requested publishing interval in milliseconds.

 None
lifetimeCount int | None

Publishing intervals the server keeps the subscription alive without a Publish request.

 None
maxKeepaliveCount int | None

Publishing intervals without notifications after which the server sends a keepalive.

 None
maxNotificationsPerPublish int | None

Cap on notifications per Publish response. 0 means unlimited.

 None
publishingEnabled bool | None

Whether the server sends notifications at all.

 None

Raises:

Type Description
RuntimeError

The subscription has been deleted.
StatusCodeError

The ModifySubscription or SetPublishingMode service call failed.