91 lines
3.4 KiB
Python
91 lines
3.4 KiB
Python
# Copyright (c) 2013 Red Hat, Inc.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
# implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
"""
|
|
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=1.1)
|
|
|
|
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=1.1, 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.
|
|
|
|
A simple example for accessing an existing queue through a client
|
|
instance - based on the API v1.1 - would look like::
|
|
|
|
from zaqarclient.queues import client
|
|
|
|
cli = client.Client(\'http://zaqar.example.com:8888/\', version=1.1)
|
|
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=1.1)
|
|
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.
|
|
"""
|
|
from zaqarclient import errors
|
|
from zaqarclient.queues.v1 import client as cv1
|
|
from zaqarclient.queues.v2 import client as cv2
|
|
|
|
_CLIENTS = {1: cv1.Client,
|
|
1.1: cv1.Client,
|
|
2: cv2.Client}
|
|
|
|
|
|
def Client(url=None, version=None, conf=None, session=None):
|
|
# NOTE: Please don't mix use the Client object with different version at
|
|
# the same time. Because the cache mechanism of queue's metadata will lead
|
|
# to unexpected response value.
|
|
# Please see zaqarclient.queues.v1.queues.Queue.metadata and
|
|
# zaqarclient.queues.v2.queues.Queue.metadata for more detail.
|
|
try:
|
|
return _CLIENTS[version](url=url, version=version, conf=conf,
|
|
session=session)
|
|
except KeyError:
|
|
raise errors.ZaqarError('Unknown client version')
|