Subscriptions#

Define API Subscriptions.

class google.cloud.pubsub.subscription.Subscription(name, topic=None, ack_deadline=None, push_endpoint=None, retain_acked_messages=None, message_retention_duration=None, client=None)[source]#

Bases: object

Subscriptions receive messages published to their topics.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions

Parameters:
  • name (str) – the name of the subscription.
  • topic (google.cloud.pubsub.topic.Topic) – (Optional) the topic to which the subscription belongs; if None, the subscription’s topic has been deleted.
  • ack_deadline (int) – the deadline (in seconds) by which messages pulled from the back-end must be acknowledged.
  • push_endpoint (str) – (Optional) URL to which messages will be pushed by the back-end. If not set, the application must pull messages.
  • retain_acked_messages (bool) – (Optional) Whether to retain acked messages. If set, acked messages are retained in the subscription’s backlog for a duration indicated by message_retention_duration.
  • message_retention_duration (datetime.timedelta) – (Optional) Whether to retain acked messages. If set, acked messages are retained in the subscription’s backlog for a duration indicated by message_retention_duration. If unset, defaults to 7 days.
  • client (Client) – (Optional) The client to use. If not passed, falls back to the client stored on the topic.
classmethod from_api_repr(resource, client, topics=None)[source]#

Factory: construct a topic given its API representation

Parameters:
  • resource (dict) – topic resource representation returned from the API.
  • client (google.cloud.pubsub.client.Client) – Client which holds credentials and project configuration for a topic.
  • topics (dict) – (Optional) A mapping of topic names -> topics. If not passed, the subscription will have a newly-created topic.
Return type:

google.cloud.pubsub.subscription.Subscription

Returns:

Subscription parsed from resource.

project#

Project bound to the subscription.

full_name#

Fully-qualified name used in subscription APIs

path#

URL path for the subscription’s APIs

auto_ack(return_immediately=False, max_messages=1, client=None)[source]#

AutoAck factory

Parameters:
Return type:

AutoAck

Returns:

the instance created for the given ack_id and message

create(client=None)[source]#

API call: create the subscription via a PUT request

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create

Example:

    subscription = topic.subscription(SUB_NAME)
    subscription.create()                               # API request
Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
exists(client=None)[source]#

API call: test existence of the subscription via a GET request

See https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/get

Example:

    assert subscription.exists()                        # API request
Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
Return type:bool
Returns:Boolean indicating existence of the subscription.
reload(client=None)[source]#

API call: sync local subscription configuration via a GET request

See https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/get

ack_deadline and push_endpoint might never have been set locally, or might have been updated by another client. This method fetches their values from the server.

Example:

    subscription.reload()                               # API request
Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
delete(client=None)[source]#

API call: delete the subscription via a DELETE request.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/delete

Example:

    subscription.delete()                               # API request
Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
modify_push_configuration(push_endpoint, client=None)[source]#

API call: update the push endpoint for the subscription.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/modifyPushConfig

Example:

    subscription.modify_push_configuration(push_endpoint=None)  # API request
    subscription.modify_push_configuration(
        push_endpoint=PUSH_URL)                                 # API request
Parameters:
  • push_endpoint (str) – URL to which messages will be pushed by the back-end. If None, the application must pull messages.
  • client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
pull(return_immediately=False, max_messages=1, client=None)[source]#

API call: retrieve messages for the subscription.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/pull

Example:

    pulled = subscription.pull(max_messages=2)
Parameters:
  • return_immediately (bool) – if True, the back-end returns even if no messages are available; if False, the API call blocks until one or more messages are available.
  • max_messages (int) – the maximum number of messages to return.
  • client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
Return type:

list of (ack_id, message) tuples

Returns:

sequence of tuples: ack_id is the ID to be used in a subsequent call to acknowledge(), and message is an instance of Message.

acknowledge(ack_ids, client=None)[source]#

API call: acknowledge retrieved messages for the subscription.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/acknowledge

Example:

    for ack_id, message in pulled:
        try:
            do_something_with(message)
        except ApplicationException as e:
            log_exception(e)
        else:
            subscription.acknowledge([ack_id])
Parameters:
  • ack_ids (list of string) – ack IDs of messages being acknowledged
  • client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
modify_ack_deadline(ack_ids, ack_deadline, client=None)[source]#

API call: update acknowledgement deadline for a retrieved message.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/modifyAckDeadline

Parameters:
  • ack_ids (list of string) – ack IDs of messages being updated
  • ack_deadline (int) – new deadline for the message, in seconds
  • client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
snapshot(name, client=None)[source]#

Creates a snapshot of this subscription.

Parameters:name (str) – the name of the subscription
Return type:Snapshot
Returns:The snapshot created with the passed in arguments.
seek_snapshot(snapshot, client=None)[source]#

API call: seek a subscription to a given snapshot

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/seek

Parameters:snapshot (Snapshot) – The snapshot to seek to.
seek_timestamp(timestamp, client=None)[source]#

API call: seek a subscription to a given point in time

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/seek

Parameters:time (datetime.datetime) – The time to seek to.
get_iam_policy(client=None)[source]#

Fetch the IAM policy for the subscription.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/getIamPolicy

Example:

    policy = subscription.get_iam_policy()             # API request
Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
Return type:google.cloud.pubsub.iam.Policy
Returns:policy created from the resource returned by the getIamPolicy API request.
set_iam_policy(policy, client=None)[source]#

Update the IAM policy for the subscription.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/setIamPolicy

Example:

    ALL_USERS = policy.all_users()
    policy.viewers = [ALL_USERS]
    LOGS_GROUP = policy.group('cloud-logs@google.com')
    policy.editors = [LOGS_GROUP]
    new_policy = subscription.set_iam_policy(policy)   # API request
Parameters:
Return type:

google.cloud.pubsub.iam.Policy

Returns:

updated policy created from the resource returned by the setIamPolicy API request.

check_iam_permissions(permissions, client=None)[source]#

Verify permissions allowed for the current user.

See: https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/testIamPermissions

Example:

    from google.cloud.pubsub.iam import OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE
    TO_CHECK = [OWNER_ROLE, EDITOR_ROLE, VIEWER_ROLE]
    ALLOWED = subscription.check_iam_permissions(TO_CHECK)
    assert set(ALLOWED) == set(TO_CHECK)
Parameters:
  • permissions (list of string) – list of permissions to be tested
  • client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current subscription’s topic.
Return type:

sequence of string

Returns:

subset of permissions allowed by current IAM policy.

class google.cloud.pubsub.subscription.AutoAck(subscription, return_immediately=False, max_messages=1, client=None)[source]#

Bases: dict

Wrapper for Subscription.pull() results.

Mapping, tracks messages still-to-be-acknowledged.

When used as a context manager, acknowledges all messages still in the mapping on __exit__. When processing the pulled messages, application code MUST delete messages from the AutoAck mapping which are not successfully processed, e.g.:

Parameters: