You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by rh...@apache.org on 2012/09/28 18:41:52 UTC
svn commit: r1391538 - /qpid/proton/trunk/proton-c/bindings/python/proton.py
Author: rhs
Date: Fri Sep 28 16:41:52 2012
New Revision: 1391538
URL: http://svn.apache.org/viewvc?rev=1391538&view=rev
Log:
added API-doc to the proton module
Modified:
qpid/proton/trunk/proton-c/bindings/python/proton.py
Modified: qpid/proton/trunk/proton-c/bindings/python/proton.py
URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/bindings/python/proton.py?rev=1391538&r1=1391537&r2=1391538&view=diff
==============================================================================
--- qpid/proton/trunk/proton-c/bindings/python/proton.py (original)
+++ qpid/proton/trunk/proton-c/bindings/python/proton.py Fri Sep 28 16:41:52 2012
@@ -1,15 +1,64 @@
+#
+ # Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you 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.
+#
+
+"""
+The proton module defines a suite of APIs that implement the AMQP 1.0
+protocol.
+
+The proton APIs consist of the following classes:
+
+ - L{Messenger} -- A messaging endpoint.
+ - L{Message} -- A class for creating and/or accessing AMQP message content.
+ - L{Data} -- A class for creating and/or accessing arbitrary AMQP encoded
+ data.
+
+"""
+
from xproton import *
class ProtonException(Exception):
+ """
+ The root of the proton exception hierarchy. All proton exception
+ classes derive from this exception.
+ """
pass
class Timeout(ProtonException):
+ """
+ A timeout exception indicates that a blocking operation has timed
+ out.
+ """
pass
class MessengerException(ProtonException):
+ """
+ The root of the messenger exception hierarchy. All exceptions
+ generated by the messenger class derive from this exception.
+ """
pass
class MessageException(ProtonException):
+ """
+ The MessageException class is the root of the message exception
+ hierarhcy. All exceptions generated by the Message class derive from
+ this exception.
+ """
pass
EXCEPTIONS = {
@@ -17,8 +66,75 @@ EXCEPTIONS = {
}
class Messenger(object):
+ """
+ The L{Messenger} class defines a high level interface for sending
+ and receiving L{Messages<Message>}. Every L{Messenger} contains a
+ single logical queue of incoming messages and a single logical queue
+ of outgoing messages. These messages in these queues may be destined
+ for, or originate from, a variety of addresses.
+
+ Address Syntax
+ ==============
+
+ An address has the following form::
+
+ [ amqp[s]:// ] [user[:password]@] domain [/[name]]
+
+ Where domain can be one of::
+
+ host | host:port | ip | ip:port | name
+
+ The following are valid examples of addresses:
+
+ - example.org
+ - example.org:1234
+ - amqp://example.org
+ - amqps://example.org
+ - example.org/incoming
+ - amqps://example.org/outgoing
+ - amqps://fred:trustno1@example.org
+ - 127.0.0.1:1234
+ - amqps://127.0.0.1:1234
+
+ Sending & Receiving Messages
+ ============================
+
+ The L{Messenger} class works in conjuction with the L{Message}
+ class. The L{Message} class is a mutable holder of message content.
+ The L{put} method will encode the content in a given L{Message}
+ object into the outgoing message queue leaving that L{Message}
+ object free to be modified or discarded without having any impact on
+ the content in the outgoing queue.
+
+ >>> message = Message()
+ >>> for i in range(3):
+ ... message.address = "amqp://host/queue"
+ ... message.subject = "Hello World %i" % i
+ ... messenger.put(message)
+ >>> messenger.send()
+
+ Similarly, the L{get} method will decode the content in the incoming
+ message queue into the supplied L{Message} object.
+
+ >>> message = Message()
+ >>> messenger.recv(10):
+ >>> while messenger.incoming > 0:
+ ... messenger.get(message)
+ ... print message.subject
+ Hello World 0
+ Hello World 1
+ Hello World 2
+ """
def __init__(self, name=None):
+ """
+ Construct a new L{Messenger} with the given name. The name has
+ global scope. If a NULL name is supplied, a L{uuid.UUID} based
+ name will be chosen.
+
+ @type name: string
+ @param name: the name of the messenger or None
+ """
self._mng = pn_messenger(name)
def __del__(self):
@@ -35,78 +151,177 @@ class Messenger(object):
@property
def name(self):
+ """
+ The name of the L{Messenger}.
+ """
return pn_messenger_name(self._mng)
- def get_certificate(self):
+ def _get_certificate(self):
return pn_messenger_get_certificate(self._mng)
- def set_certificate(self, value):
+ def _set_certificate(self, value):
self._check(pn_messenger_set_certificate(self._mng, value))
- certificate = property(get_certificate, set_certificate)
+ certificate = property(_get_certificate, _set_certificate,
+ doc="""
+Path to a certificate file for the L{Messenger}. This certificate is
+used when the L{Messenger} accepts or establishes SSL/TLS connections.
+This property must be specified for the L{Messenger} to accept
+incoming SSL/TLS connections and to establish client authenticated
+outgoing SSL/TLS connection. Non client authenticated outgoing SSL/TLS
+connections do not require this property.
+""")
- def get_private_key(self):
+ def _get_private_key(self):
return pn_messenger_get_private_key(self._mng)
- def set_private_key(self, value):
+ def _set_private_key(self, value):
self._check(pn_messenger_set_private_key(self._mng, value))
- private_key = property(get_private_key, set_private_key)
+ private_key = property(_get_private_key, _set_private_key,
+ doc="""
+Path to a private key file for the L{Messenger's<Messenger>}
+certificate. This property must be specified for the L{Messenger} to
+accept incoming SSL/TLS connections and to establish client
+authenticated outgoing SSL/TLS connection. Non client authenticated
+SSL/TLS connections do not require this property.
+""")
- def get_password(self):
+ def _get_password(self):
return pn_messenger_get_password(self._mng)
- def set_password(self, value):
+ def _set_password(self, value):
self._check(pn_messenger_set_password(self._mng, value))
- password = property(get_password, set_password)
+ password = property(_get_password, _set_password,
+ doc="""
+This property contains the password for the L{Messenger.private_key}
+file, or None if the file is not encrypted.
+""")
- def get_trusted_certificates(self):
+ def _get_trusted_certificates(self):
return pn_messenger_get_trusted_certificates(self._mng)
- def set_trusted_certificates(self, value):
+ def _set_trusted_certificates(self, value):
self._check(pn_messenger_set_trusted_certificates(self._mng, value))
- trusted_certificates = property(get_trusted_certificates, set_trusted_certificates)
+ trusted_certificates = property(_get_trusted_certificates,
+ _set_trusted_certificates,
+ doc="""
+A path do a database of trusted certificates for use in verifying the
+peer on an SSL/TLS connection. If this property is None, then the peer
+will not be verified.
+""")
- def get_timeout(self):
+ def _get_timeout(self):
return pn_messenger_get_timeout(self._mng)
- def set_timeout(self, value):
+ def _set_timeout(self, value):
self._check(pn_messenger_set_timeout(self._mng, value))
- timeout = property(get_timeout, set_timeout)
+ timeout = property(_get_timeout, _set_timeout,
+ doc="""
+The timeout property contains the default timeout for blocking
+operations performed by the L{Messenger}.
+""")
def start(self):
+ """
+ Transitions the L{Messenger} to an active state. A L{Messenger} is
+ initially created in an inactive state. When inactive a
+ L{Messenger} will not send or receive messages from its internal
+ queues. A L{Messenger} must be started before calling L{send} or
+ L{recv}.
+ """
self._check(pn_messenger_start(self._mng))
def stop(self):
+ """
+ Transitions the L{Messenger} to an inactive state. An inactive
+ L{Messenger} will not send or receive messages from its internal
+ queues. A L{Messenger} should be stopped before being discarded to
+ ensure a clean shutdown handshake occurs on any internally managed
+ connections.
+ """
self._check(pn_messenger_stop(self._mng))
def subscribe(self, source):
+ """
+ Subscribes the L{Messenger} to messages originating from the
+ specified source. The source is an address as specified in the
+ L{Messenger} introduction with the following addition. If the
+ domain portion of the address begins with the '~' character, the
+ L{Messenger} will interpret the domain as host/port, bind to it,
+ and listen for incoming messages. For example "~0.0.0.0",
+ "amqp://~0.0.0.0", and "amqps://~0.0.0.0" will all bind to any
+ local interface and listen for incoming messages with the last
+ variant only permitting incoming SSL connections.
+
+ @type source: string
+ @param source: the source of messages to subscribe to
+ """
self._check(pn_messenger_subscribe(self._mng, source))
- def put(self, msg):
- self._check(pn_messenger_put(self._mng, msg._msg))
+ def put(self, message):
+ """
+ Places the content contained in the message onto the outgoing
+ queue of the L{Messenger}. This method will never block, however
+ it will send any unblocked L{Messages<Message>} in the outgoing
+ queue immediately and leave any blocked L{Messages<Message>}
+ remaining in the outgoing queue. The L{send} call may be used to
+ block until the outgoing queue is empty. The L{outgoing} property
+ may be used to check the depth of the outgoing queue.
+
+ @type message: Message
+ @param message: the message to place in the outgoing queue
+ """
+ self._check(pn_messenger_put(self._mng, message._msg))
def send(self):
+ """
+ Blocks until the outgoing queue is empty or the operation times
+ out. The L{timeout} property controls how long a L{Messenger} will
+ block before timing out.
+ """
self._check(pn_messenger_send(self._mng))
def recv(self, n):
+ """
+ Receives up to I{n} messages into the incoming queue of the
+ L{Messenger}. This method will block until at least one message is
+ available or the operation times out.
+ """
self._check(pn_messenger_recv(self._mng, n))
- def get(self, msg):
- self._check(pn_messenger_get(self._mng, msg._msg))
+ def get(self, message):
+ """
+ Moves the message from the head of the incoming message queue into
+ the supplied message object. Any content in the message will be
+ overwritten.
+
+ @type message: Message
+ @param message: the destination message object
+ """
+ self._check(pn_messenger_get(self._mng, message._msg))
@property
def outgoing(self):
+ """
+ The outgoing queue depth.
+ """
return pn_messenger_outgoing(self._mng)
@property
def incoming(self):
+ """
+ The incoming queue depth.
+ """
return pn_messenger_incoming(self._mng)
class Message(object):
+ """
+ The L{Message} class is a mutable holder of message content.
+ """
DATA = PN_DATA
TEXT = PN_TEXT
@@ -129,162 +344,225 @@ class Message(object):
return err
def clear(self):
+ """
+ Clears the contents of the L{Message}. All fields will be reset to
+ their default values.
+ """
pn_message_clear(self._msg)
- def is_durable(self):
+ def _is_durable(self):
return pn_message_is_durable(self._msg)
- def set_durable(self, value):
+ def _set_durable(self, value):
self._check(pn_message_set_durable(self._msg, bool(value)))
- durable = property(is_durable, set_durable)
+ durable = property(_is_durable, _set_durable,
+ doc="""
+The durable property indicates that the message should be held durably
+by any intermediaries taking responsibility for the message.
+""")
- def get_priority(self):
+ def _get_priority(self):
return pn_message_get_priority(self._msg)
- def set_priority(self, value):
+ def _set_priority(self, value):
self._check(pn_message_set_priority(self._msg, value))
- priority = property(get_priority, set_priority)
+ priority = property(_get_priority, _set_priority,
+ doc="""
+The priority of the message.
+""")
- def get_ttl(self):
+ def _get_ttl(self):
return pn_message_get_ttl(self._msg)
- def set_ttl(self, value):
+ def _set_ttl(self, value):
self._check(pn_message_set_ttl(self._msg, value))
- ttl = property(get_ttl, set_ttl)
+ ttl = property(_get_ttl, _set_ttl,
+ doc="""
+The time to live of the message measured in milliseconds. Expired
+messages may be dropped.
+""")
- def is_first_acquirer(self):
+ def _is_first_acquirer(self):
return pn_message_is_first_acquirer(self._msg)
- def set_first_acquirer(self, value):
+ def _set_first_acquirer(self, value):
self._check(pn_message_set_first_acquirer(self._msg, bool(value)))
- first_acquirer = property(is_first_acquirer, set_first_acquirer)
+ first_acquirer = property(_is_first_acquirer, _set_first_acquirer,
+ doc="""
+True iff the recipient is the first to acquire the message.
+""")
- def get_delivery_count(self):
+ def _get_delivery_count(self):
return pn_message_get_delivery_count(self._msg)
- def set_delivery_count(self, value):
+ def _set_delivery_count(self, value):
self._check(pn_message_set_delivery_count(self._msg, value))
- delivery_count = property(get_delivery_count, set_delivery_count)
+ delivery_count = property(_get_delivery_count, _set_delivery_count,
+ doc="""
+The number of delivery attempts made for this message.
+""")
# XXX
- def get_id(self):
+ def _get_id(self):
return pn_message_get_id(self._msg)
- def set_id(self, value):
+ def _set_id(self, value):
self._check(pn_message_set_id(self._msg, value))
- id = property(get_id, set_id)
+ id = property(_get_id, _set_id,
+ doc="""
+The id of the message.
+""")
- def get_user_id(self):
+ def _get_user_id(self):
return pn_message_get_user_id(self._msg)
- def set_user_id(self, value):
+ def _set_user_id(self, value):
self._check(pn_message_set_user_id(self._msg, value))
- user_id = property(get_user_id, set_user_id)
+ user_id = property(_get_user_id, _set_user_id,
+ doc="""
+The user id of the message creator.
+""")
- def get_address(self):
+ def _get_address(self):
return pn_message_get_address(self._msg)
- def set_address(self, value):
+ def _set_address(self, value):
self._check(pn_message_set_address(self._msg, value))
- address = property(get_address, set_address)
+ address = property(_get_address, _set_address,
+ doc="""
+The address of the message.
+""")
- def get_subject(self):
+ def _get_subject(self):
return pn_message_get_subject(self._msg)
- def set_subject(self, value):
+ def _set_subject(self, value):
self._check(pn_message_set_subject(self._msg, value))
- subject = property(get_subject, set_subject)
+ subject = property(_get_subject, _set_subject,
+ doc="""
+The subject of the message.
+""")
- def get_reply_to(self):
+ def _get_reply_to(self):
return pn_message_get_reply_to(self._msg)
- def set_reply_to(self, value):
+ def _set_reply_to(self, value):
self._check(pn_message_set_reply_to(self._msg, value))
- reply_to = property(get_reply_to, set_reply_to)
+ reply_to = property(_get_reply_to, _set_reply_to,
+ doc="""
+The reply-to address for the message.
+""")
# XXX
- def get_correlation_id(self):
+ def _get_correlation_id(self):
return pn_message_get_correlation_id(self._msg)
- def set_correlation_id(self, value):
+ def _set_correlation_id(self, value):
self._check(pn_message_set_correlation_id(self._msg, value))
- correlation_id = property(get_correlation_id, set_correlation_id)
+ correlation_id = property(_get_correlation_id, _set_correlation_id,
+ doc="""
+The correlation-id for the message.
+""")
- def get_content_type(self):
+ def _get_content_type(self):
return pn_message_get_content_type(self._msg)
- def set_content_type(self, value):
+ def _set_content_type(self, value):
self._check(pn_message_set_content_type(self._msg, value))
- content_type = property(get_content_type, set_content_type)
+ content_type = property(_get_content_type, _set_content_type,
+ doc="""
+The content-type of the message.
+""")
- def get_content_encoding(self):
+ def _get_content_encoding(self):
return pn_message_get_content_encoding(self._msg)
- def set_content_encoding(self, value):
+ def _set_content_encoding(self, value):
self._check(pn_message_set_content_encoding(self._msg, value))
- content_encoding = property(get_content_encoding, set_content_encoding)
+ content_encoding = property(_get_content_encoding, _set_content_encoding,
+ doc="""
+The content-encoding of the message.
+""")
- def get_expiry_time(self):
+ def _get_expiry_time(self):
return pn_message_get_expiry_time(self._msg)
- def set_expiry_time(self, value):
+ def _set_expiry_time(self, value):
self._check(pn_message_set_expiry_time(self._msg, value))
- expiry_time = property(get_expiry_time, set_expiry_time)
+ expiry_time = property(_get_expiry_time, _set_expiry_time,
+ doc="""
+The expiry time of the message.
+""")
- def get_creation_time(self):
+ def _get_creation_time(self):
return pn_message_get_creation_time(self._msg)
- def set_creation_time(self, value):
+ def _set_creation_time(self, value):
self._check(pn_message_set_creation_time(self._msg, value))
- creation_time = property(get_creation_time, set_creation_time)
+ creation_time = property(_get_creation_time, _set_creation_time,
+ doc="""
+The creation time of the message.
+""")
- def get_group_id(self):
+ def _get_group_id(self):
return pn_message_get_group_id(self._msg)
- def set_group_id(self, value):
+ def _set_group_id(self, value):
self._check(pn_message_set_group_id(self._msg, value))
- group_id = property(get_group_id, set_group_id)
+ group_id = property(_get_group_id, _set_group_id,
+ doc="""
+The group id of the message.
+""")
- def get_group_sequence(self):
+ def _get_group_sequence(self):
return pn_message_get_group_sequence(self._msg)
- def set_group_sequence(self, value):
+ def _set_group_sequence(self, value):
self._check(pn_message_set_group_sequence(self._msg, value))
- group_sequence = property(get_group_sequence, set_group_sequence)
+ group_sequence = property(_get_group_sequence, _set_group_sequence,
+ doc="""
+The sequence of the message within its group.
+""")
- def get_reply_to_group_id(self):
+ def _get_reply_to_group_id(self):
return pn_message_get_reply_to_group_id(self._msg)
- def set_reply_to_group_id(self, value):
+ def _set_reply_to_group_id(self, value):
self._check(pn_message_set_reply_to_group_id(self._msg, value))
- reply_to_group_id = property(get_reply_to_group_id, set_reply_to_group_id)
+ reply_to_group_id = property(_get_reply_to_group_id, _set_reply_to_group_id,
+ doc="""
+The group-id for any replies.
+""")
# XXX
- def get_format(self):
+ def _get_format(self):
return pn_message_get_format(self._msg)
- def set_format(self, value):
+ def _set_format(self, value):
self._check(pn_message_set_format(self._msg, value))
- format = property(get_format, set_format)
+ format = property(_get_format, _set_format,
+ doc="""
+The format of the message.
+""")
def load(self, data):
self._check(pn_message_load(self._msg, data))
@@ -301,29 +579,83 @@ class Message(object):
return data
class DataException(ProtonException):
+ """
+ The DataException class is the root of the Data exception hierarchy.
+ All exceptions raised by the Data class extend this exception.
+ """
pass
class Data:
-
- NULL = PN_NULL
- BOOL = PN_BOOL
- UBYTE = PN_UBYTE
- BYTE = PN_BYTE
- USHORT = PN_USHORT
- SHORT = PN_SHORT
- UINT = PN_UINT
- INT = PN_INT
- ULONG = PN_ULONG
- LONG = PN_LONG
- FLOAT = PN_FLOAT
- DOUBLE = PN_DOUBLE
- BINARY = PN_BINARY
- STRING = PN_STRING
- SYMBOL = PN_SYMBOL
- DESCRIBED = PN_DESCRIPTOR
- ARRAY = PN_ARRAY
- LIST = PN_LIST
- MAP = PN_MAP
+ """
+ The L{Data} class provides an interface for decoding, extracting,
+ creating, and encoding arbitrary AMQP data. A L{Data} object
+ contains a tree of AMQP values. Leaf nodes in this tree correspond
+ to scalars in the AMQP type system such as L{ints<INT>} or
+ L{strings<STRING>}. Non-leaf nodes in this tree correspond to
+ compound values in the AMQP type system such as L{lists<LIST>},
+ L{maps<MAP>}, L{arrays<ARRAY>}, or L{described values<DESCRIBED>}.
+ The root node of the tree is the L{Data} object itself and can have
+ an arbitrary number of children.
+
+ A L{Data} object maintains the notion of the current sibling node
+ and a current parent node. Siblings are ordered within their parent.
+ Values are accessed and/or added by using the L{next}, L{prev},
+ L{enter}, and L{exit} methods to navigate to the desired location in
+ the tree and using the supplied variety of put_*/get_* methods to
+ access or add a value of the desired type.
+
+ The put_* methods will always add a value I{after} the current node
+ in the tree. If the current node has a next sibling the put_* method
+ will overwrite the value on this node. If there is no current node
+ or the current node has no next sibling then one will be added. The
+ put_* methods always set the added/modified node to the current
+ node. The get_* methods read the value of the current node and do
+ not change which node is current.
+
+ The following types of scalar values are supported:
+
+ - L{NULL}
+ - L{BOOL}
+ - L{UBYTE}
+ - L{USHORT}
+ - L{SHORT}
+ - L{UINT}
+ - L{INT}
+ - L{ULONG}
+ - L{LONG}
+ - L{FLOAT}
+ - L{DOUBLE}
+ - L{BINARY}
+ - L{STRING}
+ - L{SYMBOL}
+
+ The following types of compound values are supported:
+
+ - L{DESCRIBED}
+ - L{ARRAY}
+ - L{LIST}
+ - L{MAP}
+ """
+
+ NULL = PN_NULL; "A null value."
+ BOOL = PN_BOOL; "A boolean value."
+ UBYTE = PN_UBYTE; "An unsigned byte value."
+ BYTE = PN_BYTE; "A signed byte value."
+ USHORT = PN_USHORT; "An unsigned short value."
+ SHORT = PN_SHORT; "A short value."
+ UINT = PN_UINT; "An unsigned int value."
+ INT = PN_INT; "A signed int value."
+ ULONG = PN_ULONG; "An unsigned long value."
+ LONG = PN_LONG; "A signed long value."
+ FLOAT = PN_FLOAT; "A float value."
+ DOUBLE = PN_DOUBLE; "A double value."
+ BINARY = PN_BINARY; "A binary string."
+ STRING = PN_STRING; "A unicode string."
+ SYMBOL = PN_SYMBOL; "A symbolic string."
+ DESCRIBED = PN_DESCRIPTOR; "A described value."
+ ARRAY = PN_ARRAY; "An array value."
+ LIST = PN_LIST; "A list value."
+ MAP = PN_MAP; "A map value."
def __init__(self, capacity=16):
self._data = pn_data(capacity)
@@ -341,9 +673,17 @@ class Data:
return err
def rewind(self):
+ """
+ Clears current node and sets the parent to the root node.
+ """
pn_data_rewind(self._data)
def next(self):
+ """
+ Advances the current node to its next sibling and returns its
+ type. If there is no next sibling the current node remains
+ unchanged and None is returned.
+ """
found, dtype = pn_data_next(self._data)
if found:
return dtype
@@ -351,6 +691,11 @@ class Data:
return None
def prev(self):
+ """
+ Advances the current node to its previous sibling and returns its
+ type. If there is no previous sibling the current node remains
+ unchanged and None is returned.
+ """
found, dtype = pn_data_prev(self._data)
if found:
return dtype
@@ -358,12 +703,22 @@ class Data:
return None
def enter(self):
+ """
+ Sets the parent node to the current node and clears the current node.
+ """
return pn_data_enter(self._data)
def exit(self):
+ """
+ Sets the current node to the parent node and the parent node to
+ its own parent.
+ """
return pn_data_exit(self._data)
def encode(self):
+ """
+ Returns a representation of the data encoded in AMQP format.
+ """
size = 1024
while True:
cd, enc = pn_data_encode(self._data, size)
@@ -375,152 +730,418 @@ class Data:
self._check(cd)
def decode(self, encoded):
+ """
+ Decodes the first value from supplied AMQP data and returns the
+ number of bytes consumed.
+
+ @type encoded: binary
+ @param encoded: AMQP encoded binary data
+ """
return self._check(pn_data_decode(self._data, encoded))
def put_list(self):
+ """
+ Puts a list value. Elements may be filled by entering the list
+ node and putting element values.
+
+ >>> data = Data()
+ >>> data.put_list()
+ >>> data.enter()
+ >>> data.put_int(1)
+ >>> data.put_int(2)
+ >>> data.put_int(3)
+ >>> data.exit()
+ """
self._check(pn_data_put_list(self._data))
def put_map(self):
+ """
+ Puts a map value. Elements may be filled by entering the map node
+ and putting alternating key value pairs.
+
+ >>> data = Data()
+ >>> data.put_map()
+ >>> data.enter()
+ >>> data.put_string("key")
+ >>> data.put_string("value")
+ >>> data.exit()
+ """
self._check(pn_data_put_map(self._data))
- def put_array(self, described, etype):
- self._check(pn_data_put_array(self._data, described, etype))
+ def put_array(self, described, element_type):
+ """
+ Puts an array value. Elements may be filled by entering the array
+ node and putting the element values. The values must all be of the
+ specified array element type. If an array is described then the
+ first child value of the array is the descriptor and may be of any
+ type.
+
+ >>> data = Data()
+ >>>
+ >>> data.put_array(False, Data.INT)
+ >>> data.enter()
+ >>> data.put_int(1)
+ >>> data.put_int(2)
+ >>> data.put_int(3)
+ >>> data.exit()
+ >>>
+ >>> data.put_array(True, Data.DOUBLE)
+ >>> data.enter()
+ >>> data.put_symbol("array-descriptor")
+ >>> data.enter()
+ >>> data.put_double(1.1)
+ >>> data.put_double(1.2)
+ >>> data.put_double(1.3)
+ >>> data.exit()
+
+ @type described: bool
+ @param described: specifies whether the array is described
+ @type element_type: int
+ @param element_type: the type of the array elements
+ """
+ self._check(pn_data_put_array(self._data, described, element_type))
def put_described(self):
+ """
+ Puts a described value. A described node has two children, the
+ descriptor and the value. These are specified by entering the node
+ and putting the desired values.
+
+ >>> data = Data()
+ >>> data.put_described()
+ >>> data.enter()
+ >>> data.put_symbol("value-descriptor")
+ >>> data.put_string("the value")
+ >>> data.exit()
+ """
self._check(pn_data_put_described(self._data))
def put_null(self):
+ """
+ Puts a null value.
+ """
self._check(pn_data_put_null(self._data))
def put_bool(self, b):
+ """
+ Puts a boolean value.
+
+ @param b: a boolean value
+ """
self._check(pn_data_put_bool(self._data, b))
def put_ubyte(self, ub):
+ """
+ Puts an unsigned byte value.
+
+ @param ub: an integral value
+ """
self._check(pn_data_put_ubyte(self._data, ub))
def put_byte(self, b):
+ """
+ Puts a signed byte value.
+
+ @param b: an integral value
+ """
self._check(pn_data_put_byte(self._data, b))
def put_ushort(self, us):
+ """
+ Puts an unsigned short value.
+
+ @param us: an integral value.
+ """
self._check(pn_data_put_ushort(self._data, us))
def put_short(self, s):
+ """
+ Puts a signed short value.
+
+ @param s: an integral value
+ """
self._check(pn_data_put_short(self._data, s))
def put_uint(self, ui):
+ """
+ Puts an unsigned int value.
+
+ @param ui: an integral value
+ """
self._check(pn_data_put_uint(self._data, ui))
def put_int(self, i):
+ """
+ Puts a signed int value.
+
+ @param i: an integral value
+ """
self._check(pn_data_put_int(self._data, i))
def put_ulong(self, ul):
+ """
+ Puts an unsigned long value.
+
+ @param ul: an integral value
+ """
self._check(pn_data_put_ulong(self._data, ul))
def put_long(self, l):
+ """
+ Puts a signed long value.
+
+ @param l: an integral value
+ """
self._check(pn_data_put_long(self._data, l))
def put_float(self, f):
+ """
+ Puts a float value.
+
+ @param f: a floating point value
+ """
self._check(pn_data_put_float(self._data, f))
def put_double(self, d):
+ """
+ Puts a double value.
+
+ @param d: a floating point value.
+ """
self._check(pn_data_put_double(self._data, d))
def put_binary(self, b):
+ """
+ Puts a binary value.
+
+ @type b: binary
+ @param b: a binary value
+ """
self._check(pn_data_put_binary(self._data, b))
def put_string(self, s):
+ """
+ Puts a unicode value.
+
+ @type s: unicode
+ @param s: a unicode value
+ """
self._check(pn_data_put_string(self._data, s))
def put_symbol(self, s):
+ """
+ Puts a symbolic value.
+
+ @type s: string
+ @param s: the symbol name
+ """
self._check(pn_data_put_symbol(self._data, s))
def get_list(self):
+ """
+ If the current node is a list, return the number of elements,
+ otherwise raise an error. List elements can be accessed by
+ entering the list.
+
+ >>> count = data.get_list()
+ >>> data.enter()
+ >>> for i in range(count):
+ ... type = data.next()
+ ... if type == Data.STRING:
+ ... print data.get_string()
+ ... elif type == ...:
+ ... ...
+ >>> data.exit()
+ """
err, count = pn_data_get_list(self._data)
self._check(err)
return count
def get_map(self):
+ """
+ If the current node is a map, return the number of child elements,
+ otherwise raise an error. Key value pairs can be accessed by
+ entering the map.
+
+ >>> count = data.get_map()
+ >>> data.enter()
+ >>> for i in range(count/2):
+ ... type = data.next()
+ ... if type == Data.STRING:
+ ... print data.get_string()
+ ... elif type == ...:
+ ... ...
+ >>> data.exit()
+ """
err, count = pn_data_get_map(self._data)
self._check(err)
return count
def get_array(self):
+ """
+ If the current node is an array, return a tuple of the element
+ count, a boolean indicating whether the array is described, and
+ the type of each element. Array data can be accessed by entering
+ the array.
+
+ >>> # read an array of strings with a symbolic descriptor
+ >>> count, described, type = data.get_array()
+ >>> data.enter()
+ >>> data.next()
+ >>> print "Descriptor:", data.get_symbol()
+ >>> for i in range(count):
+ ... data.next()
+ ... print "Element:", data.get_string()
+ >>> data.exit()
+ """
err, count, described, type = pn_data_get_array(self._data)
self._check(err)
return count, described, type
def get_described(self):
+ """
+ Checks if the current node is a described value, raises an
+ exception otherwise. The descriptor and value may be accessed by
+ entering the described value.
+
+ >>> # read a symbolically described string
+ >>> data.get_described() # will error if the current node is not described
+ >>> data.enter()
+ >>> print data.get_symbol()
+ >>> print data.get_string()
+ >>> data.exit()
+ """
self._check(pn_data_get_described(self._data))
def get_null(self):
+ """
+ Checks if the current node is a null, raises an exception
+ otherwise.
+ """
self._check(pn_data_get_null(self._data))
def get_bool(self):
+ """
+ If the current node is a boolean, returns its value, raises an
+ exception otherwise.
+ """
err, b = pn_data_get_bool(self._data)
self._check(err)
return b
def get_ubyte(self):
+ """
+ If the current node is an unsigned byte, returns its value, raises
+ an exception otherwise.
+ """
err, value = pn_data_get_ubyte(self._data)
self._check(err)
return value
def get_byte(self):
+ """
+ If the current node is a signed byte, returns its value, raises an
+ exception otherwise.
+ """
err, value = pn_data_get_byte(self._data)
self._check(err)
return value
def get_ushort(self):
+ """
+ If the current node is an unsigned short, returns its value,
+ raises an exception otherwise.
+ """
err, value = pn_data_get_ushort(self._data)
self._check(err)
return value
def get_short(self):
+ """
+ If the current node is a signed short, returns its value, raises
+ an exception otherwise.
+ """
err, value = pn_data_get_short(self._data)
self._check(err)
return value
def get_uint(self):
+ """
+ If the current node is an unsigned int, returns its value, raises
+ an exception otherwise.
+ """
err, value = pn_data_get_uint(self._data)
self._check(err)
return value
def get_int(self):
+ """
+ If the current node is a signed int, returns its value, raises an
+ exception otherwise.
+ """
err, value = pn_data_get_int(self._data)
self._check(err)
return value
def get_ulong(self):
+ """
+ If the current node is an unsigned long, returns its value, raises
+ an exception otherwise.
+ """
err, value = pn_data_get_ulong(self._data)
self._check(err)
return value
def get_long(self):
+ """
+ If the current node is an signed long, returns its value, raises
+ an exception otherwise.
+ """
err, value = pn_data_get_long(self._data)
self._check(err)
return value
def get_float(self):
+ """
+ If the current node is a float, returns its value, raises an
+ exception otherwise.
+ """
err, value = pn_data_get_float(self._data)
self._check(err)
return value
def get_double(self):
+ """
+ If the current node is a double, returns its value, raises an
+ exception otherwise.
+ """
err, value = pn_data_get_double(self._data)
self._check(err)
return value
def get_binary(self):
+ """
+ If the current node is binary, returns its value, raises an
+ exception otherwise.
+ """
err, value = pn_data_get_binary(self._data)
self._check(err)
return value
def get_string(self):
+ """
+ If the current node is a string, returns its value, raises an
+ exception otherwise.
+ """
err, value = pn_data_get_string(self._data)
self._check(err)
return value
def get_symbol(self):
+ """
+ If the current node is a symbol, returns its value, raises an
+ exception otherwise.
+ """
err, value = pn_data_get_symbol(self._data)
self._check(err)
return value
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org