PYTHON-ZAQARCLIENT(1)
β¨ python-zaqarclient β PYTHON-ZAQARCLIENT(1) β¨
okay bestie, you opened the manual page for python-zaqarclient and honestly? iconic. This is the 4.7.0 era of the client, and we're gonna walk through it together like we're sharing earbuds on the bus. π§π¦
πΈ NAME πΈ
python-zaqarclient β python-zaqarclient 4.7.0
Zaqar (https://wiki.openstack.org/wiki/Zaqar) is a multi-tenant cloud messaging and notification service for web and mobile developers. π
The service features a ReST API, which developers can use to send messages between various components of their SaaS and mobile applications, by using a variety of communication patterns. Underlying this API is an efficient messaging engine designed with scalability and security in mind. no cap, that's the whole vibe. π₯
Other OpenStack components can integrate with Zaqar to surface events to end users and to communicate with guest agents that run in the "over-cloud" layer.
Note: This documentation is generated by the Sphinx toolkit and lives in the Zaqar project source tree. Additional draft and project documentation regarding Zaqar and other components of OpenStack can be found on the OpenStack Wiki (https://wiki.openstack.org/wiki/Main_Page), as well as in the user guides found on docs.openstack.org (https://docs.openstack.org). π«Ά
π CONTENTS π
- Client
- Client Object Reference
- Command-line
- Queue
π§Έ Client π§Έ
A Client is a high-level abstraction on top of Zaqar features. It exposes the server features with an object-oriented interface, which encourages dot notation and automatic, but lazy, resources allocation. A Client allows you to control everything, from public interfaces to admin endpoints. π
To create a Client instance, you supply an url pointing to the server and a version number:
from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/', version=2)
which will load the appropriate client based on the specified version. Optionally, you can also supply a config dictionary:
from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/',
version=2, conf={})
The arguments passed to this function will be passed to the client instances as well.
It's recommended to use Client instances instead of accessing the lower level API as it has been designed to ease the interaction with the server and it gives enough control for the most common cases. like, she's literally built for this. π
A simple example for accessing an existing queue through a client instance - based on the API v2 - would look like:
from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/', version=2)
queue = cli.queue('my_queue')
Through the queue instance will be then possible to access all the features associated with the queue itself like posting messages, getting message and deleting messages. π
As mentioned previously in this documentation, a client instance allows you to also access admin endpoints, for example:
from zaqarclient.queues import client
cli = client.Client('http://zaqar.example.com:8888/', version=2)
flavor = cli.flavor('tasty',
pool='my-pool-group',
auto_create=True)
flavor.delete()
Client uses the lower-level API to access the server, which means anything you can do with this client instance can be done by accessing the underlying API, although not recommended. π
π Client Object Reference π
This is the reference documentation for all API version. yes, all of it, bestie. π
π API v2.0 π
class Client(url=None, version=2, conf=None, session=None)
Client base class
- Parameters
url(str) β Zaqar's instance base url.version(int) β API Version pointing to.conf(oslo_config.cfg.CONF) β CONF object.
flavor(ref, **kwargs)β Returns a flavor instance.- Parameters:
ref(str) β Flavor's reference name. - Returns: A flavor instance.
- Return type:
flavor.Flavor
- Parameters:
flavors(**params)β Gets a list of flavors from the server.- Parameters:
params(dict.) β Filters to use for getting flavors. - Returns: A list of flavors.
- Return type:
list
- Parameters:
follow(ref)β Followsref. This method instanciates a new request instance and requestsref. It is intended to be used to follow a reference href gotten from links sections in responses like queues' lists.- Params
ref: The reference path.
- Params
health()β Gets the detailed health status of Zaqar server.homedoc()β Get the detailed resource doc of Zaqar server.ping()β Gets the health status of Zaqar server.pool(ref, **kwargs)β Returns a pool instance.- Parameters:
ref(str) β Pool's reference name. - Returns: A pool instance.
- Return type:
pool.Pool
- Parameters:
pools(**params)β Gets a list of pools from the server.- Parameters:
params(dict.) β Filters to use for getting pools. - Returns: A list of pools.
- Return type:
list
- Parameters:
queue(ref, **kwargs)β Returns a queue instance.- Parameters:
ref(str) β Queue's reference id. - Returns: A queue instance.
- Return type:
queues.Queue
- Parameters:
queues(**params)β Gets a list of queues from the server.- Returns: A list of queues.
- Return type:
list
subscription(queue_name, **kwargs)β Returns a subscription instance.- Parameters:
queue_name(str) β Name of the queue to subscribe to. - Returns: A subscription instance.
- Return type:
subscription.Subscription
- Parameters:
subscriptions(queue_name, **params)β Gets a list of subscriptions from the server.- Parameters:
params(dict.) β Filters to use for getting subscriptions. - Returns: A list of subscriptions.
- Return type:
list
- Parameters:
transport()β Gets a transport based the api url and version.- Return type:
zaqarclient.transport.base.Transport
- Return type:
π₯οΈ Command-line π₯οΈ
This chapter documents the usage of Zaqar Client Command Line with API v2.0.
Zaqar client now support some kinds of resources or actions: queue, message, claim, subscription, pool, flavor, ping, health.
Click the Link below for the details. π«Ά
π Queue π
For help on a specific openstack messaging queue command, enter:
$ openstack messaging queue COMMAND -h/--help
The fourteen commands:
messaging queue create
messaging queue delete
messaging queue get metadata
messaging queue list
messaging queue set metadata
messaging queue signed url
messaging queue stats
π οΈ openstack messaging queue create π οΈ
usage: openstack messaging queue create [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>] [--noindent]
[--prefix PREFIX]
<queue_name>
Create a queue. β¨
Positional arguments:
<queue_name>β Name of the queue.
ποΈ openstack messaging queue delete ποΈ
usage: openstack messaging queue delete [-h] <queue_name>
Delete a queue.
Positional arguments:
<queue_name>β Name of the queue.
π openstack messaging queue get metadata π
usage: openstack messaging queue get metadata [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
<queue_name>
Get queue metadata.
Positional arguments:
<queue_name>β Name of the queue.
π openstack messaging queue list π
usage: openstack messaging queue list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
[--max-width <integer>] [--noindent]
[--quote {all,minimal,none,nonnumeric}]
[--marker <queue_id>] [--limit <limit>]
[--detailed]
List available queues.
Optional arguments:
--marker <queue_id>β Queue's paging marker.--limit <limit>β Page size limit.--detailedβ If show detailed information of queue.
βοΈ openstack messaging queue set metadata βοΈ
usage: openstack messaging queue set metadata [-h] <queue_name> <queue_metadata>
Set queue metadata. All the metadata of the queue will be replaced by queue_metadata. like, full glow-up replacement, no leftovers. π
Positional arguments:
<queue_name>β Name of the queue.<queue_metadata>β Queue metadata. It should be json like. For example:'{"age": 18}'
π openstack messaging queue signed url π
usage: openstack messaging queue signed url [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
[--paths <paths>]
[--ttl-seconds <ttl_seconds>]
[--methods <methods>]
<queue_name>
Create a pre-signed url for the queue.
Positional arguments:
<queue_name>β Name of the queue.
Optional arguments:
--paths <paths>β Allowed paths in a comma-separated list. Options:messages,subscriptions,claims.--ttl-seconds <ttl_seconds>β Length of time (in seconds) until the signature expires.--methods <methods>β HTTP methods to allow as a comma-separated list. Options:GET,HEAD,OPTIONS,POST,PUT,DELETE.
openstack messaging queue stats
usage: openstack messaging queue stats [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>] [--noindent]
[--prefix PREFIX]
<queue_name>
Okay so this one gets you the queue stats, bestie. That's the whole vibe.
Positional arguments:
<queue_name>β name of the queue π
openstack messaging queue purge
usage: openstack messaging queue purge [-h] [--resource_types <resource_types>]
<queue_name>
Purge a queue. Important: all the metadata of the queue will be kept β so it's not a full delete situation, it's a "clear the stuff inside" situation. Use --resource_types to specify which resource should be purged (the page says "pured", love that for it). If --resource_types is not specified, all the messages and subscriptions in the queue will be purged by default. That's the default, no cap.
Positional arguments:
<queue_name>β name of the queue πΈ
Optional arguments:
--resource_types <resource_types>β resource types you want to be purged. It supports messages and subscriptions. π«Ά
π©Ί Health
For help on a specific openstack messaging message command, enter:
$ openstack messaging message COMMAND -h/--help
The one command:
messaging message list
messaging message post
(Yes, it says "the one command" and then lists two. We're not gonna fight the manpage about it. π)
openstack messaging message list
usage: openstack messaging message list [-h] [-f {csv,json,table,value,yaml}]
[-c COLUMN]
[--quote {all,minimal,none,nonnumeric}]
[--noindent] [--max-width <integer>]
[--fit-width] [--print-empty]
[--sort-column SORT_COLUMN]
[--message-ids <message_ids>]
[--limit <limit>] [--echo]
[--include-claimed]
[--include-delayed]
[--client-id <client_id>]
<queue_name>
List all of the messages in a queue. That's it, that's the job. The usage line above is where all the flag energy lives β formatting, sorting, filtering, all of it. β¨
Positional arguments:
<queue_name>β name of the queue π
openstack messaging message post
usage: openstack messaging message post [-h] [--client-id <client_id>]
<queue_name> <messages>
Post the messages to a queue. Very demure, very mindful.
Positional arguments:
<queue_name>β name of the queue π¦<messages>β messages. It should be json like. For example:'[{"body": "msg", "ttl": 60}]'β yes, keep the JSON exactly like that. π₯
π― Claim
For help on a specific openstack messaging claim command, enter:
$ openstack messaging claim COMMAND -h/--help
The eight commands:
messaging claim create
messaging claim query
messaging claim release
messaging claim renew
(The page says eight, the list shows four. Iconic inconsistency. We move. π)
openstack messaging claim create
usage: openstack messaging claim create [-h] [-f {csv,json,table,value,yaml}]
[-c COLUMN] [--max-width <integer>] [--noindent]
[--quote {all,minimal,none,nonnumeric}]
[--ttl <ttl>] [--grace <grace>]
[--limit <limit>]
<queue_name>
Create claim and return a list of claimed messages. Claiming messages, but make it cute. π
Positional arguments:
<queue_name>β name of the queue to be claim. (The page says "to be claim" β we're keeping the lore.) π
Optional arguments:
--ttl <ttl>β time to live in seconds for claim β--grace <grace>β the message grace period in seconds π--limit <limit>β claims a set of messages, up to limit π
openstack messaging claim query
usage: openstack messaging claim query [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
[--max-width <integer>] [--noindent]
[--quote {all,minimal,none,nonnumeric}]
<queue_name> <claim_id>
Display claim details. Detective mode: activated. π
Positional arguments:
<queue_name>β name of the claimed queue π<claim_id>β ID of the claim π
openstack messaging claim release
usage: openstack messaging claim release [-h] <queue_name> <claim_id>
Delete a claim. Let it go, bestie. π¦
Positional arguments:
<queue_name>β name of the claimed queue πΈ<claim_id>β claim ID to delete π
openstack messaging claim renew
usage: openstack messaging claim renew [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
[--max-width <integer>] [--noindent]
[--quote {all,minimal,none,nonnumeric}]
[--ttl <ttl>] [--grace <grace>]
<queue_name> <claim_id>
Renew a claim. Giving that claim a little extension, main character energy. β¨
Positional arguments:
<queue_name>β name of the claimed queue π«Ά<claim_id>β claim ID π
Optional arguments:
--ttl <ttl>β time to live in seconds for claim β--grace <grace>β the message grace period in seconds π
π Pool
For help on a specific openstack messaging pool command, enter:
$ openstack messaging pool COMMAND -h/--help
The ten commands:
messaging pool create
messaging pool delete
messaging pool list
messaging pool show
messaging pool update
(Again: says ten, lists five. The math is not mathing, but we're still slaying. π)
openstack messaging pool create
usage: openstack messaging pool create [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>] [--noindent]
[--prefix PREFIX] [--pool_group <pool_group>]
[--pool_options <pool_options>]
<pool_name> <pool_uri> <pool_weight>
Create a pool. Pool girl summer. π©·
Positional arguments:
<pool_name>β name of the pool π<pool_uri>β storage engine URI πΈ<pool_weight>β weight of the pool β
Optional arguments:
--pool_group <pool_group>β group of the pool π--pool_options <pool_options>β an optional request component related to storage-specific options π¦
openstack messaging pool delete
usage: openstack messaging pool delete [-h] <pool_name>
Delete a pool. Bye bestie. π
Positional arguments:
<pool_name>β name of the pool π
openstack messaging pool list
usage: openstack messaging pool list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
[--max-width <integer>] [--noindent]
[--quote {all,minimal,none,nonnumeric}]
[--marker <pool_name>] [--limit <limit>]
[--detailed <detailed>]
List available Pools. Capital P, because it's that serious. π₯
Optional arguments:
--marker <pool_name>β pool's paging marker π«Ά--limit <limit>β page size limit π--detailed <detailed>β detailed output β¨
openstack messaging pool show
usage: openstack messaging pool show [-h] [-f {json,shell,table,value,yaml}] [-c COLUMN]
[--max-width <integer>] [--noindent]
[--prefix PREFIX]
<pool_name>
Display pool details. Show me everything. π
Positional arguments:
<pool_name>β pool to display (name) π
openstack messaging pool update
usage: openstack messaging pool update [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>] [--noindent]
[--prefix PREFIX] [--pool_uri <pool_uri>]
[--pool_weight <pool_weight>]
[--pool_group <pool_group>]
[--pool_options <pool_options>]
<pool_name>
Update a pool attribute. Glow-up era. π
Positional arguments:
<pool_name>β name of the pool π
Optional arguments:
--pool_uri <pool_uri>β storage engine URI πΈ--pool_weight <pool_weight>β weight of the pool β--pool_group <pool_group>β group of the pool π--pool_options <pool_options>β an optional request component related to storage-specific options π¦
π Flavor
For help on a specific openstack messaging flavor command, enter:
$ openstack messaging flavor COMMAND -h/--help
The five commands:
messaging flavor create
messaging flavor delete
messaging flavor list
messaging flavor show
messaging flavor update
openstack messaging flavor create
usage: openstack messaging flavor create [-h]
[-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
[--capabilities <capabilities>]
<flavor_name> <pool_group>
Create a pool flavor. Yes, flavor. Not the edible kind, unfortunately. π
Positional arguments:
<flavor_name>β name of the flavor π<pool_group>β pool group for flavor π
Optional arguments:
--capabilities <capabilities>β describes flavor-specific capabilities. This option is only available in client api version < 2. π«Ά
openstack messaging flavor delete
usage: openstack messaging flavor delete [-h] <flavor_name>
Delete a pool flavor. No more flavor. π
Positional arguments:
<flavor_name>β name of the flavor πΈ
openstack messaging flavor list
usage: openstack messaging flavor list [-h] [-f {csv,json,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent]
[--quote {all,minimal,none,nonnumeric}]
[--marker <flavor_name>]
[--limit <limit>]
[--detailed <detailed>]
List available pool flavors. A little flavor lineup. β¨
Optional arguments:
--marker <flavor_name>β flavor's paging marker π¦--limit <limit>β page size limit π--detailed <detailed>β if show detailed capabilities of flavor π
openstack messaging flavor show
usage: openstack messaging flavor show [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
<flavor_name>
Okay so this one just displays flavor details β like, the whole vibe of one flavor, front to back. π
Positional arguments:
<flavor_name>β the flavor you wanna display, by name.
Optional arguments:
-hβ help, bestie. always there for u π«Ά-f {json,shell,table,value,yaml}β pick your output format β¨-c COLUMNβ only show these column(s)--max-width <integer>β cap the width of the output--noindentβ no indenting forjson/yamlπ--prefix PREFIXβ prefix to slap on all the output names
openstack messaging flavor update
usage: openstack messaging flavor update [-h]
[-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
[--pool_group <pool_group>]
[--capabilities <capabilities>]
<flavor_name>
Update a pool flavor's attributes. β¨ little glow-up for your flavor, no biggie.
Positional arguments:
<flavor_name>β name of the flavor, obvs.
Optional arguments:
-hβ help π-f {json,shell,table,value,yaml}β output format, ur choice bestie-c COLUMNβ columns to show--max-width <integer>β max width of the output--noindentβ don't indentjson/yaml--prefix PREFIXβ prefix for all output names--pool_group <pool_group>β the pool group the flavor sits on πͺ--capabilities <capabilities>β describes flavor-specific capabilities π₯
π« PING π«
Wanna help on a specific openstack messaging ping command? Just type:
$ openstack messaging ping COMMAND -h/--help
And there is exactly one command here, main character energy only:
messaging ping
openstack messaging ping
usage: openstack messaging ping [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
Check if the Zaqar server is alive or not. π«Ά like a little "u up?" text for your server. if it answers, it's alive, slay.
-hβ help-f {json,shell,table,value,yaml}β output format-c COLUMNβ columns--max-width <integer>β max width--noindentβ no indent forjson/yaml--prefix PREFIXβ output name prefix
Heads up: this one has no positional arguments β you literally just run it and it vibes. π
π©Ί HEALTH π©Ί
Help for a specific openstack messaging health command:
$ openstack messaging health COMMAND -h/--help
Again, just the one:
messaging health
openstack messaging health
usage: openstack messaging health [-h]
Display detailed health status of Zaqar server. π the full checkup, not just "are u alive" β the detailed tea.
-hβ help
Not me pointing out this one doesn't even take-for-cπ it's literally just-h. minimal queen.
πΈ SUBSCRIPTION πΈ
Help for a specific openstack messaging subscription command:
$ openstack messaging subscription COMMAND -h/--help
The ten commands:
messaging subscription create
messaging subscription delete
messaging subscription list
messaging subscription show
messaging subscription update
She says ten and then lists five and honestly? We're not gonna fact-check her π the page says ten, the list says five, that's the lore. π
openstack messaging subscription create
usage: openstack messaging subscription create [-h]
[-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
[--options <options>]
<queue_name> <subscriber> <ttl>
Create a subscription. π new sub, who dis.
Positional arguments:
<queue_name>β name of the queue<subscriber>β the subscriber that will be notified π<ttl>β time to live of the subscription, in seconds β³
Optional arguments:
-hβ help-f {json,shell,table,value,yaml}β output format-c COLUMNβ columns--max-width <integer>β max width--noindentβ no indent forjson/yaml--prefix PREFIXβ output name prefix--options <options>β options for the subscription
openstack messaging subscription delete
usage: openstack messaging subscription delete [-h] <queue_name> <subscription_id>
Delete a subscription. π bye bestie, unfollowed.
Positional arguments:
<queue_name>β name of the queue<subscription_id>β ID of the subscription
Notice: no format flags here. It just takes -h and goes. efficient icon β¨
openstack messaging subscription list
usage: openstack messaging subscription list [-h] [-f {csv,json,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent]
[--quote {all,minimal,none,nonnumeric}]
[--marker <subscription_id>]
[--limit <limit>]
<queue_name>
Get list of subscriptions. π¦ the whole roster.
Positional arguments:
<queue_name>β name of the queue
Optional arguments:
-hβ help π«Ά-f {csv,json,table,value,yaml}β output format (yes,csvis in this one's list π)-c COLUMNβ columns--max-width <integer>β max width--noindentβ no indent forjson/yaml--quote {all,minimal,none,nonnumeric}β when to quote stuff incsvπ--marker <subscription_id>β the marker, a subscription ID--limit <limit>β how many to return, max
openstack messaging subscription show
usage: openstack messaging subscription show [-h] [-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
<queue_name> <subscription_id>
Query a subscription details. π the full scoop on one sub.
Positional arguments:
<queue_name>β name of the queue<subscription_id>β ID of the subscription
Optional arguments:
-hβ help-f {json,shell,table,value,yaml}β output format-c COLUMNβ columns--max-width <integer>β max width--noindentβ no indent forjson/yaml--prefix PREFIXβ output name prefix
openstack messaging subscription update
usage: openstack messaging subscription update [-h]
[-f {json,shell,table,value,yaml}]
[-c COLUMN] [--max-width <integer>]
[--noindent] [--prefix PREFIX]
[--subscriber <subscriber>] [--ttl <ttl>]
[--options <options>]
<queue_name> <subscription_id>
Update a subscription. π glow-up szn.
Positional arguments:
<queue_name>β name of the queue<subscription_id>β ID of the subscription
Optional arguments:
-hβ help-f {json,shell,table,value,yaml}β output format-c COLUMNβ columns--max-width <integer>β max width--noindentβ no indent forjson/yaml--prefix PREFIXβ output name prefix--subscriber <subscriber>β subscriber that will be notified π--ttl <ttl>β time to live of the subscription, in seconds β³--options <options>β metadata of the subscription, in JSON format π
π RELEASE NOTES π
New Release Note
We use reno to publish the release note now. Please see Release Page https://docs.openstack.org/releasenotes/python-zaqarclient for more detail. π¦
0.2.0
1934a98Updated from global requirements863371bAllow for authentication in functional testsb35689dDon't pass options to pool creation8104ff4Don't reuse request and transport instancesbf841b5Pass group in pool's functional tests2490ed4Send claims limit as a query parambaf6fa7v1.1 and v2 claims return document not list0d80728Make sure the API version is passed down407925cMake v1.1 the default CLI version895aad2Updated from global requirements8a81c44Updated from global requirements705ee75Implement CLI support for flavor32a847eImplements CLI for pool964443dRaises an error if the queue name is emptye9a8d01Added support to pools and flavorsf46979bRemoved deprecated 'shard' methods1a85f83Update README to work with release tools
0.1.1
- Fix handling of 1.1 API
- Gets 'flavor' data if the resource exists
- Gets 'pool' data if the resource exists
- Handling exception on 504 Error
- Added i18n support
- Makes health return True or False
- Add reference docs for latest recommended client
- Add docs for Client instances
- Add a read-only property for Queues
π Indices and tables
- Index
<> - Module Index
<> - Search Page
<>
π Author
Author name not set π (yes, really β that's literally what it says, no cap)
Β©οΈ Copyright
2010-present, OpenStack Foundation β iconic, timeless, mother. π
And that's the whole page bestie!! πβ¨ It's from python-zaqarclient, version 4.7.0, dated Jan 02, 1980 β yes, 1980, she's vintage ππ¦ β and it's all officially brought to you by the OpenStack Foundation. slay, go message some queues, ily, bye!! πππ«Ά
π¦ where this page comes from
- nixpkgs unstable: python3.13-python-zaqarclient 4.7.0
- nixpkgs unstable: python3.14-python-zaqarclient 4.7.0
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms