lib/PyAMF-0.6.1/pyamf/remoting/__init__.py - external/googleappengine/python - Git at Google

 # Copyright (c) The PyAMF Project.
 # See LICENSE.txt for details.

 """
 AMF Remoting support.

 A Remoting request from the client consists of a short preamble, headers, and
 bodies. The preamble contains basic information about the nature of the
 request. Headers can be used to request debugging information, send
 authentication info, tag transactions, etc. Bodies contain actual Remoting
 requests and responses. A single Remoting envelope can contain several
 requests; Remoting supports batching out of the box.

 Client headers and bodies need not be responded to in a one-to-one manner.
 That is, a body or header may not require a response. Debug information is
 requested by a header but sent back as a body object. The response index is
 essential for the Adobe Flash Player to understand the response therefore.

 @see: U{Remoting Envelope on OSFlash
     <http://osflash.org/documentation/amf/envelopes/remoting>}
 @see: U{Remoting Headers on OSFlash
     <http://osflash.org/amf/envelopes/remoting/headers>}
 @see: U{Remoting Debug Headers on OSFlash
     <http://osflash.org/documentation/amf/envelopes/remoting/debuginfo>}

 @since: 0.1
 """

 import pyamf
 from pyamf import util


 __all__ = ['Envelope', 'Request', 'Response', 'decode', 'encode']

 #: Succesful call.
 STATUS_OK = 0
 #: Reserved for runtime errors.
 STATUS_ERROR = 1
 #: Debug information.
 STATUS_DEBUG = 2

 #: List of available status response codes.
 STATUS_CODES = {
     STATUS_OK:    '/onResult',
     STATUS_ERROR: '/onStatus',
     STATUS_DEBUG: '/onDebugEvents'
 }

 #: AMF mimetype.
 CONTENT_TYPE = 'application/x-amf'

 ERROR_CALL_FAILED, = range(1)
 ERROR_CODES = {
     ERROR_CALL_FAILED: 'Server.Call.Failed'
 }

 APPEND_TO_GATEWAY_URL = 'AppendToGatewayUrl'
 REPLACE_GATEWAY_URL = 'ReplaceGatewayUrl'
 REQUEST_PERSISTENT_HEADER = 'RequestPersistentHeader'


 class RemotingError(pyamf.BaseError):
     """
     Generic remoting error class.
     """


 class RemotingCallFailed(RemotingError):
     """
     Raised if B{Server.Call.Failed} received.
     """

 pyamf.add_error_class(RemotingCallFailed, ERROR_CODES[ERROR_CALL_FAILED])


 class HeaderCollection(dict):
     """
     Collection of AMF message headers.
     """

     def __init__(self, raw_headers={}):
         self.required = []

         for (k, ig, v) in raw_headers:
             self[k] = v
             if ig:
                 self.required.append(k)

     def is_required(self, idx):
         """
         @raise KeyError: Unknown header found.
         """
         if not idx in self:
             raise KeyError("Unknown header %s" % str(idx))

         return idx in self.required

     def set_required(self, idx, value=True):
         """
         @raise KeyError: Unknown header found.
         """
         if not idx in self:
             raise KeyError("Unknown header %s" % str(idx))

         if not idx in self.required:
             self.required.append(idx)

     def __len__(self):
         return len(self.keys())


 class Envelope(object):
     """
     I wrap an entire request, encapsulating headers and bodies.

     There can be more than one request in a single transaction.

     @ivar amfVersion: AMF encoding version. See L{pyamf.ENCODING_TYPES}
     @type amfVersion: C{int} or C{None}
     @ivar headers: AMF headers, a list of name, value pairs. Global to each
         request.
     @type headers: L{HeaderCollection}
     @ivar bodies: A list of requests/response messages
     @type bodies: C{list} containing tuples of the key of the request and the
         L{Message}.
     """

     def __init__(self, amfVersion=None):
         self.amfVersion = amfVersion
         self.headers = HeaderCollection()
         self.bodies = []

     def __repr__(self):
         r = "<Envelope amfVersion=%r>\n" % (self.amfVersion,)

         for h in self.headers:
             r += " " + repr(h) + "\n"

         for request in iter(self):
             r += " " + repr(request) + "\n"

         r += "</Envelope>"

         return r

     def __setitem__(self, name, value):
         if not isinstance(value, Message):
             raise TypeError("Message instance expected")

         idx = 0
         found = False

         for body in self.bodies:
             if name == body[0]:
                 self.bodies[idx] = (name, value)
                 found = True

             idx = idx + 1

         if not found:
             self.bodies.append((name, value))

         value.envelope = self

     def __getitem__(self, name):
         for body in self.bodies:
             if name == body[0]:
                 return body[1]

         raise KeyError("'%r'" % (name,))

     def __nonzero__(self):
         return len(self.bodies) != 0 or len(self.headers) != 0

     def __iter__(self):
         for body in self.bodies:
             yield body[0], body[1]

         raise StopIteration

     def __len__(self):
         return len(self.bodies)

     def iteritems(self):
         for body in self.bodies:
             yield body

         raise StopIteration

     def keys(self):
         return [body[0] for body in self.bodies]

     def items(self):
         return self.bodies

     def __contains__(self, name):
         for body in self.bodies:
             if name == body[0]:
                 return True

         return False

     def __eq__(self, other):
         if isinstance(other, Envelope):
             return (self.amfVersion == other.amfVersion and
                 self.headers == other.headers and
                 self.bodies == other.bodies)

         if hasattr(other, 'keys') and hasattr(other, 'items'):
             keys, o_keys = self.keys(), other.keys()

             if len(o_keys) != len(keys):
                 return False

             for k in o_keys:
                 if k not in keys:
                     return False

                 keys.remove(k)

             for k, v in other.items():
                 if self[k] != v:
                     return False

             return True


 class Message(object):
     """
     I represent a singular request/response, containing a collection of
     headers and one body of data.

     I am used to iterate over all requests in the :class:`Envelope`.

     @ivar envelope: The parent L{envelope<Envelope>} of this AMF Message.
     @ivar body: The body of the message.
     @ivar headers: The message headers. Dict like in behaviour.
     """

     def __init__(self, envelope, body):
         self.envelope = envelope
         self.body = body

     def _get_headers(self):
         return self.envelope.headers

     headers = property(_get_headers)


 class Request(Message):
     """
     An AMF Request payload.

     @ivar target: The C{string} target of the request
     """

     def __init__(self, target, body=[], envelope=None):
         Message.__init__(self, envelope, body)

         self.target = target

     def __repr__(self):
         return "<%s target=%s>%s</%s>" % (
             type(self).__name__, repr(self.target), repr(self.body), type(self).__name__)


 class Response(Message):
     """
     An AMF Response.

     @ivar status: The status of the message. Default is L{STATUS_OK}.
     @type status: Member of L{STATUS_CODES}.
     """

     def __init__(self, body, status=STATUS_OK, envelope=None):
         Message.__init__(self, envelope, body)

         self.status = status

     def __repr__(self):
         return "<%s status=%s>%s</%s>" % (
             type(self).__name__, _get_status(self.status), repr(self.body),
             type(self).__name__
         )


 class BaseFault(object):
     """
     I represent a fault message (C{mx.rpc.Fault}).

     @ivar level: The level of the fault.
     @ivar code: A simple code describing the fault.
     @ivar details: Any extra details of the fault.
     @ivar description: A longer description of the fault.

     @see: U{mx.rpc.Fault on Livedocs
           <http://livedocs.adobe.com/flex/201/langref/mx/rpc/Fault.html>}
     """

     level = None

     class __amf__:
         static = ('level', 'code', 'type', 'details', 'description')

     def __init__(self, *args, **kwargs):
         self.code = kwargs.get('code', '')
         self.type = kwargs.get('type', '')
         self.details = kwargs.get('details', '')
         self.description = kwargs.get('description', '')

     def __repr__(self):
         x = '%s level=%s' % (self.__class__.__name__, self.level)

         if self.code not in ('', None):
             x += ' code=%s' % repr(self.code)
         if self.type not in ('', None):
             x += ' type=%s' % repr(self.type)
         if self.description not in ('', None):
             x += ' description=%s' % repr(self.description)

         if self.details not in ('', None):
             x += '\nTraceback:\n%s' % (repr(self.details),)

         return x

     def raiseException(self):
         """
         Raises an exception based on the fault object. There is no traceback
         available.
         """
         raise get_exception_from_fault(self), self.description, None


 class ErrorFault(BaseFault):
     """
     I represent an error level fault.
     """

     level = 'error'


 def _read_header(stream, decoder, strict=False):
     """
     Read AMF L{Message} header from the stream.

     @type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
     @param decoder: An AMF0 decoder.
     @param strict: Use strict decoding policy. Default is C{False}. Will raise a
         L{pyamf.DecodeError} if the data that was read from the stream does not
         match the header length.
     @return: A C{tuple} containing the name of the header, a C{bool}
         determining if understanding this header is required and the decoded
         data.
     @note: Quite what understanding required headers actually means is unknown.
     """
     name_len = stream.read_ushort()
     name = stream.read_utf8_string(name_len)

     required = bool(stream.read_uchar())

     data_len = stream.read_ulong()
     pos = stream.tell()

     data = decoder.readElement()

     if strict and pos + data_len != stream.tell():
         raise pyamf.DecodeError(
             "Data read from stream does not match header length")

     return (name, required, data)


 def _write_header(name, header, required, stream, encoder, strict=False):
     """
     Write AMF message header.

     @param name: Name of the header.
     @param header: Header value.
     @param required: Whether understanding this header is required (?).
     @param stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>} that
         will receive the encoded header.
     @param encoder: An encoder capable of encoding C{AMF0}.
     @param strict: Use strict encoding policy. Default is C{False}. Will write
         the correct header length after writing the header.
     """
     stream.write_ushort(len(name))
     stream.write_utf8_string(name)

     stream.write_uchar(required)
     write_pos = stream.tell()

     stream.write_ulong(0)
     old_pos = stream.tell()
     encoder.writeElement(header)
     new_pos = stream.tell()

     if strict:
         stream.seek(write_pos)
         stream.write_ulong(new_pos - old_pos)
         stream.seek(new_pos)


 def _read_body(stream, decoder, strict=False, logger=None):
     """
     Read an AMF message body from the stream.

     @type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
     @param decoder: An AMF0 decoder.
     @param strict: Use strict decoding policy. Default is `False`.
     @param logger: Used to log interesting events whilst reading a remoting
         body.
     @type logger: A C{logging.Logger} instance or C{None}.
     @return: A C{tuple} containing the C{id} of the request and the L{Request}
         or L{Response}
     """
     def _read_args():
         # we have to go through this insanity because it seems that amf0
         # does not keep the array of args in the object references lookup
         type_byte = stream.peek(1)

         if type_byte == '\x11':
             if not decoder.use_amf3:
                 raise pyamf.DecodeError(
                     "Unexpected AMF3 type with incorrect message type")

             return decoder.readElement()

         if type_byte != '\x0a':
             raise pyamf.DecodeError("Array type required for request body")

         stream.read(1)
         x = stream.read_ulong()

         return [decoder.readElement() for i in xrange(x)]

     target = stream.read_utf8_string(stream.read_ushort())
     response = stream.read_utf8_string(stream.read_ushort())

     status = STATUS_OK
     is_request = True

     for code, s in STATUS_CODES.iteritems():
         if not target.endswith(s):
             continue

         is_request = False
         status = code
         target = target[:0 - len(s)]

     if logger:
         logger.debug('Remoting target: %r' % (target,))

     data_len = stream.read_ulong()
     pos = stream.tell()

     if is_request:
         data = _read_args()
     else:
         data = decoder.readElement()

     if strict and pos + data_len != stream.tell():
         raise pyamf.DecodeError("Data read from stream does not match body "
             "length (%d != %d)" % (pos + data_len, stream.tell(),))

     if is_request:
         return response, Request(target, body=data)

     if status == STATUS_ERROR and isinstance(data, pyamf.ASObject):
         data = get_fault(data)

     return target, Response(data, status)


 def _write_body(name, message, stream, encoder, strict=False):
     """
     Write AMF message body.

     @param name: The name of the request.
     @param message: The AMF L{Message}
     @type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
     @param encoder: An AMF0 encoder.
     @param strict: Use strict encoding policy. Default is `False`.
     """
     def _encode_body(message):
         if isinstance(message, Response):
             encoder.writeElement(message.body)

             return

         stream.write('\x0a')
         stream.write_ulong(len(message.body))
         for x in message.body:
             encoder.writeElement(x)

     if not isinstance(message, (Request, Response)):
         raise TypeError("Unknown message type")

     target = None

     if isinstance(message, Request):
         target = unicode(message.target)
     else:
         target = u"%s%s" % (name, _get_status(message.status))

     target = target.encode('utf8')

     stream.write_ushort(len(target))
     stream.write_utf8_string(target)

     response = 'null'

     if isinstance(message, Request):
         response = name

     stream.write_ushort(len(response))
     stream.write_utf8_string(response)

     if not strict:
         stream.write_ulong(0)
         _encode_body(message)

         return

     write_pos = stream.tell()
     stream.write_ulong(0)
     old_pos = stream.tell()

     _encode_body(message)
     new_pos = stream.tell()

     stream.seek(write_pos)
     stream.write_ulong(new_pos - old_pos)
     stream.seek(new_pos)


 def _get_status(status):
     """
     Get status code.

     @see: L{STATUS_CODES}
     """
     if status not in STATUS_CODES:
         # TODO print that status code..
         raise ValueError("Unknown status code")

     return STATUS_CODES[status]


 def get_fault_class(level, **kwargs):
     if level == 'error':
         return ErrorFault

     return BaseFault


 def get_fault(data):
     try:
         level = data['level']
         del data['level']
     except KeyError:
         level = 'error'

     e = {}

     for x, y in data.iteritems():
         if isinstance(x, unicode):
             e[str(x)] = y
         else:
             e[x] = y

     return get_fault_class(level, **e)(**e)


 def decode(stream, strict=False, logger=None, timezone_offset=None):
     """
     Decodes the incoming stream as a remoting message.

     @type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
     @param strict: Enforce strict decoding. Default is `False`.
     @param logger: Used to log interesting events whilst decoding a remoting
         message.
     @type logger: U{logging.Logger<http://
         docs.python.org/library/logging.html#loggers>}
     @param timezone_offset: The difference between the current timezone and
         UTC. Date/times should always be handled in UTC to avoid confusion but
         this is required for legacy systems.
     @type timezone_offset: U{datetime.datetime.timedelta<http://
         docs.python.org/library/datetime.html#datetime.timedelta}

     @return: Message L{envelope<Envelope>}.
     """
     if not isinstance(stream, util.BufferedByteStream):
         stream = util.BufferedByteStream(stream)

     if logger:
         logger.debug('remoting.decode start')

     msg = Envelope()
     msg.amfVersion = stream.read_ushort()

     # see http://osflash.org/documentation/amf/envelopes/remoting#preamble
     # why we are doing this...
     if msg.amfVersion > 0x09:
         raise pyamf.DecodeError("Malformed stream (amfVersion=%d)" %
             msg.amfVersion)

     decoder = pyamf.get_decoder(pyamf.AMF0, stream, strict=strict,
         timezone_offset=timezone_offset)
     context = decoder.context

     decoder.use_amf3 = msg.amfVersion == pyamf.AMF3
     header_count = stream.read_ushort()

     for i in xrange(header_count):
         name, required, data = _read_header(stream, decoder, strict)
         msg.headers[name] = data

         if required:
             msg.headers.set_required(name)

     body_count = stream.read_short()

     for i in xrange(body_count):
         context.clear()

         target, payload = _read_body(stream, decoder, strict, logger)
         msg[target] = payload

     if strict and stream.remaining() > 0:
         raise RuntimeError("Unable to fully consume the buffer")

     if logger:
         logger.debug('remoting.decode end')

     return msg


 def encode(msg, strict=False, logger=None, timezone_offset=None):
     """
     Encodes and returns the L{msg<Envelope>} as an AMF stream.

     @param strict: Enforce strict encoding. Default is C{False}. Specifically
         header/body lengths will be written correctly, instead of the default 0.
         Default is `False`. Introduced in 0.4.
     @param logger: Used to log interesting events whilst decoding a remoting
         message.
     @type logger: U{logging.Logger<http://
         docs.python.org/library/logging.html#loggers>}
     @param timezone_offset: The difference between the current timezone and
         UTC. Date/times should always be handled in UTC to avoid confusion but
         this is required for legacy systems.
     @type timezone_offset: U{datetime.datetime.timedelta<http://
         docs.python.org/library/datetime.html#datetime.timedelta}
     @rtype: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
     """
     stream = util.BufferedByteStream()

     encoder = pyamf.get_encoder(pyamf.AMF0, stream, strict=strict,
         timezone_offset=timezone_offset)

     if msg.amfVersion == pyamf.AMF3:
         encoder.use_amf3 = True

     stream.write_ushort(msg.amfVersion)
     stream.write_ushort(len(msg.headers))

     for name, header in msg.headers.iteritems():
         _write_header(name, header, int(msg.headers.is_required(name)),
             stream, encoder, strict)

     stream.write_short(len(msg))

     for name, message in msg.iteritems():
         encoder.context.clear()

         _write_body(name, message, stream, encoder, strict)

     stream.seek(0)

     return stream


 def get_exception_from_fault(fault):
     """
     """
     return pyamf.ERROR_CLASS_MAP.get(fault.code, RemotingError)


 pyamf.register_class(ErrorFault)
	# Copyright (c) The PyAMF Project.
	# See LICENSE.txt for details.

	"""
	AMF Remoting support.

	A Remoting request from the client consists of a short preamble, headers, and
	bodies. The preamble contains basic information about the nature of the
	request. Headers can be used to request debugging information, send
	authentication info, tag transactions, etc. Bodies contain actual Remoting
	requests and responses. A single Remoting envelope can contain several
	requests; Remoting supports batching out of the box.

	Client headers and bodies need not be responded to in a one-to-one manner.
	That is, a body or header may not require a response. Debug information is
	requested by a header but sent back as a body object. The response index is
	essential for the Adobe Flash Player to understand the response therefore.

	@see: U{Remoting Envelope on OSFlash
	<http://osflash.org/documentation/amf/envelopes/remoting>}
	@see: U{Remoting Headers on OSFlash
	<http://osflash.org/amf/envelopes/remoting/headers>}
	@see: U{Remoting Debug Headers on OSFlash
	<http://osflash.org/documentation/amf/envelopes/remoting/debuginfo>}

	@since: 0.1
	"""

	import pyamf
	from pyamf import util


	__all__ = ['Envelope', 'Request', 'Response', 'decode', 'encode']

	#: Succesful call.
	STATUS_OK = 0
	#: Reserved for runtime errors.
	STATUS_ERROR = 1
	#: Debug information.
	STATUS_DEBUG = 2

	#: List of available status response codes.
	STATUS_CODES = {
	STATUS_OK: '/onResult',
	STATUS_ERROR: '/onStatus',
	STATUS_DEBUG: '/onDebugEvents'
	}

	#: AMF mimetype.
	CONTENT_TYPE = 'application/x-amf'

	ERROR_CALL_FAILED, = range(1)
	ERROR_CODES = {
	ERROR_CALL_FAILED: 'Server.Call.Failed'
	}

	APPEND_TO_GATEWAY_URL = 'AppendToGatewayUrl'
	REPLACE_GATEWAY_URL = 'ReplaceGatewayUrl'
	REQUEST_PERSISTENT_HEADER = 'RequestPersistentHeader'


	class RemotingError(pyamf.BaseError):
	"""
	Generic remoting error class.
	"""


	class RemotingCallFailed(RemotingError):
	"""
	Raised if B{Server.Call.Failed} received.
	"""

	pyamf.add_error_class(RemotingCallFailed, ERROR_CODES[ERROR_CALL_FAILED])


	class HeaderCollection(dict):
	"""
	Collection of AMF message headers.
	"""

	def __init__(self, raw_headers={}):
	self.required = []

	for (k, ig, v) in raw_headers:
	self[k] = v
	if ig:
	self.required.append(k)

	def is_required(self, idx):
	"""
	@raise KeyError: Unknown header found.
	"""
	if not idx in self:
	raise KeyError("Unknown header %s" % str(idx))

	return idx in self.required

	def set_required(self, idx, value=True):
	"""
	@raise KeyError: Unknown header found.
	"""
	if not idx in self:
	raise KeyError("Unknown header %s" % str(idx))

	if not idx in self.required:
	self.required.append(idx)

	def __len__(self):
	return len(self.keys())


	class Envelope(object):
	"""
	I wrap an entire request, encapsulating headers and bodies.

	There can be more than one request in a single transaction.

	@ivar amfVersion: AMF encoding version. See L{pyamf.ENCODING_TYPES}
	@type amfVersion: C{int} or C{None}
	@ivar headers: AMF headers, a list of name, value pairs. Global to each
	request.
	@type headers: L{HeaderCollection}
	@ivar bodies: A list of requests/response messages
	@type bodies: C{list} containing tuples of the key of the request and the
	L{Message}.
	"""

	def __init__(self, amfVersion=None):
	self.amfVersion = amfVersion
	self.headers = HeaderCollection()
	self.bodies = []

	def __repr__(self):
	r = "<Envelope amfVersion=%r>\n" % (self.amfVersion,)

	for h in self.headers:
	r += " " + repr(h) + "\n"

	for request in iter(self):
	r += " " + repr(request) + "\n"

	r += "</Envelope>"

	return r

	def __setitem__(self, name, value):
	if not isinstance(value, Message):
	raise TypeError("Message instance expected")

	idx = 0
	found = False

	for body in self.bodies:
	if name == body[0]:
	self.bodies[idx] = (name, value)
	found = True

	idx = idx + 1

	if not found:
	self.bodies.append((name, value))

	value.envelope = self

	def __getitem__(self, name):
	for body in self.bodies:
	if name == body[0]:
	return body[1]

	raise KeyError("'%r'" % (name,))

	def __nonzero__(self):
	return len(self.bodies) != 0 or len(self.headers) != 0

	def __iter__(self):
	for body in self.bodies:
	yield body[0], body[1]

	raise StopIteration

	def __len__(self):
	return len(self.bodies)

	def iteritems(self):
	for body in self.bodies:
	yield body

	raise StopIteration

	def keys(self):
	return [body[0] for body in self.bodies]

	def items(self):
	return self.bodies

	def __contains__(self, name):
	for body in self.bodies:
	if name == body[0]:
	return True

	return False

	def __eq__(self, other):
	if isinstance(other, Envelope):
	return (self.amfVersion == other.amfVersion and
	self.headers == other.headers and
	self.bodies == other.bodies)

	if hasattr(other, 'keys') and hasattr(other, 'items'):
	keys, o_keys = self.keys(), other.keys()

	if len(o_keys) != len(keys):
	return False

	for k in o_keys:
	if k not in keys:
	return False

	keys.remove(k)

	for k, v in other.items():
	if self[k] != v:
	return False

	return True


	class Message(object):
	"""
	I represent a singular request/response, containing a collection of
	headers and one body of data.

	I am used to iterate over all requests in the :class:`Envelope`.

	@ivar envelope: The parent L{envelope<Envelope>} of this AMF Message.
	@ivar body: The body of the message.
	@ivar headers: The message headers. Dict like in behaviour.
	"""

	def __init__(self, envelope, body):
	self.envelope = envelope
	self.body = body

	def _get_headers(self):
	return self.envelope.headers

	headers = property(_get_headers)


	class Request(Message):
	"""
	An AMF Request payload.

	@ivar target: The C{string} target of the request
	"""

	def __init__(self, target, body=[], envelope=None):
	Message.__init__(self, envelope, body)

	self.target = target

	def __repr__(self):
	return "<%s target=%s>%s</%s>" % (
	type(self).__name__, repr(self.target), repr(self.body), type(self).__name__)


	class Response(Message):
	"""
	An AMF Response.

	@ivar status: The status of the message. Default is L{STATUS_OK}.
	@type status: Member of L{STATUS_CODES}.
	"""

	def __init__(self, body, status=STATUS_OK, envelope=None):
	Message.__init__(self, envelope, body)

	self.status = status

	def __repr__(self):
	return "<%s status=%s>%s</%s>" % (
	type(self).__name__, _get_status(self.status), repr(self.body),
	type(self).__name__
	)


	class BaseFault(object):
	"""
	I represent a fault message (C{mx.rpc.Fault}).

	@ivar level: The level of the fault.
	@ivar code: A simple code describing the fault.
	@ivar details: Any extra details of the fault.
	@ivar description: A longer description of the fault.

	@see: U{mx.rpc.Fault on Livedocs
	<http://livedocs.adobe.com/flex/201/langref/mx/rpc/Fault.html>}
	"""

	level = None

	class __amf__:
	static = ('level', 'code', 'type', 'details', 'description')

	def __init__(self, args, *kwargs):
	self.code = kwargs.get('code', '')
	self.type = kwargs.get('type', '')
	self.details = kwargs.get('details', '')
	self.description = kwargs.get('description', '')

	def __repr__(self):
	x = '%s level=%s' % (self.__class__.__name__, self.level)

	if self.code not in ('', None):
	x += ' code=%s' % repr(self.code)
	if self.type not in ('', None):
	x += ' type=%s' % repr(self.type)
	if self.description not in ('', None):
	x += ' description=%s' % repr(self.description)

	if self.details not in ('', None):
	x += '\nTraceback:\n%s' % (repr(self.details),)

	return x

	def raiseException(self):
	"""
	Raises an exception based on the fault object. There is no traceback
	available.
	"""
	raise get_exception_from_fault(self), self.description, None


	class ErrorFault(BaseFault):
	"""
	I represent an error level fault.
	"""

	level = 'error'


	def _read_header(stream, decoder, strict=False):
	"""
	Read AMF L{Message} header from the stream.

	@type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
	@param decoder: An AMF0 decoder.
	@param strict: Use strict decoding policy. Default is C{False}. Will raise a
	L{pyamf.DecodeError} if the data that was read from the stream does not
	match the header length.
	@return: A C{tuple} containing the name of the header, a C{bool}
	determining if understanding this header is required and the decoded
	data.
	@note: Quite what understanding required headers actually means is unknown.
	"""
	name_len = stream.read_ushort()
	name = stream.read_utf8_string(name_len)

	required = bool(stream.read_uchar())

	data_len = stream.read_ulong()
	pos = stream.tell()

	data = decoder.readElement()

	if strict and pos + data_len != stream.tell():
	raise pyamf.DecodeError(
	"Data read from stream does not match header length")

	return (name, required, data)


	def _write_header(name, header, required, stream, encoder, strict=False):
	"""
	Write AMF message header.

	@param name: Name of the header.
	@param header: Header value.
	@param required: Whether understanding this header is required (?).
	@param stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>} that
	will receive the encoded header.
	@param encoder: An encoder capable of encoding C{AMF0}.
	@param strict: Use strict encoding policy. Default is C{False}. Will write
	the correct header length after writing the header.
	"""
	stream.write_ushort(len(name))
	stream.write_utf8_string(name)

	stream.write_uchar(required)
	write_pos = stream.tell()

	stream.write_ulong(0)
	old_pos = stream.tell()
	encoder.writeElement(header)
	new_pos = stream.tell()

	if strict:
	stream.seek(write_pos)
	stream.write_ulong(new_pos - old_pos)
	stream.seek(new_pos)


	def _read_body(stream, decoder, strict=False, logger=None):
	"""
	Read an AMF message body from the stream.

	@type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
	@param decoder: An AMF0 decoder.
	@param strict: Use strict decoding policy. Default is `False`.
	@param logger: Used to log interesting events whilst reading a remoting
	body.
	@type logger: A C{logging.Logger} instance or C{None}.
	@return: A C{tuple} containing the C{id} of the request and the L{Request}
	or L{Response}
	"""
	def _read_args():
	# we have to go through this insanity because it seems that amf0
	# does not keep the array of args in the object references lookup
	type_byte = stream.peek(1)

	if type_byte == '\x11':
	if not decoder.use_amf3:
	raise pyamf.DecodeError(
	"Unexpected AMF3 type with incorrect message type")

	return decoder.readElement()

	if type_byte != '\x0a':
	raise pyamf.DecodeError("Array type required for request body")

	stream.read(1)
	x = stream.read_ulong()

	return [decoder.readElement() for i in xrange(x)]

	target = stream.read_utf8_string(stream.read_ushort())
	response = stream.read_utf8_string(stream.read_ushort())

	status = STATUS_OK
	is_request = True

	for code, s in STATUS_CODES.iteritems():
	if not target.endswith(s):
	continue

	is_request = False
	status = code
	target = target[:0 - len(s)]

	if logger:
	logger.debug('Remoting target: %r' % (target,))

	data_len = stream.read_ulong()
	pos = stream.tell()

	if is_request:
	data = _read_args()
	else:
	data = decoder.readElement()

	if strict and pos + data_len != stream.tell():
	raise pyamf.DecodeError("Data read from stream does not match body "
	"length (%d != %d)" % (pos + data_len, stream.tell(),))

	if is_request:
	return response, Request(target, body=data)

	if status == STATUS_ERROR and isinstance(data, pyamf.ASObject):
	data = get_fault(data)

	return target, Response(data, status)


	def _write_body(name, message, stream, encoder, strict=False):
	"""
	Write AMF message body.

	@param name: The name of the request.
	@param message: The AMF L{Message}
	@type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
	@param encoder: An AMF0 encoder.
	@param strict: Use strict encoding policy. Default is `False`.
	"""
	def _encode_body(message):
	if isinstance(message, Response):
	encoder.writeElement(message.body)

	return

	stream.write('\x0a')
	stream.write_ulong(len(message.body))
	for x in message.body:
	encoder.writeElement(x)

	if not isinstance(message, (Request, Response)):
	raise TypeError("Unknown message type")

	target = None

	if isinstance(message, Request):
	target = unicode(message.target)
	else:
	target = u"%s%s" % (name, _get_status(message.status))

	target = target.encode('utf8')

	stream.write_ushort(len(target))
	stream.write_utf8_string(target)

	response = 'null'

	if isinstance(message, Request):
	response = name

	stream.write_ushort(len(response))
	stream.write_utf8_string(response)

	if not strict:
	stream.write_ulong(0)
	_encode_body(message)

	return

	write_pos = stream.tell()
	stream.write_ulong(0)
	old_pos = stream.tell()

	_encode_body(message)
	new_pos = stream.tell()

	stream.seek(write_pos)
	stream.write_ulong(new_pos - old_pos)
	stream.seek(new_pos)


	def _get_status(status):
	"""
	Get status code.

	@see: L{STATUS_CODES}
	"""
	if status not in STATUS_CODES:
	# TODO print that status code..
	raise ValueError("Unknown status code")

	return STATUS_CODES[status]


	def get_fault_class(level, **kwargs):
	if level == 'error':
	return ErrorFault

	return BaseFault


	def get_fault(data):
	try:
	level = data['level']
	del data['level']
	except KeyError:
	level = 'error'

	e = {}

	for x, y in data.iteritems():
	if isinstance(x, unicode):
	e[str(x)] = y
	else:
	e[x] = y

	return get_fault_class(level, e)(e)


	def decode(stream, strict=False, logger=None, timezone_offset=None):
	"""
	Decodes the incoming stream as a remoting message.

	@type stream: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
	@param strict: Enforce strict decoding. Default is `False`.
	@param logger: Used to log interesting events whilst decoding a remoting
	message.
	@type logger: U{logging.Logger<http://
	docs.python.org/library/logging.html#loggers>}
	@param timezone_offset: The difference between the current timezone and
	UTC. Date/times should always be handled in UTC to avoid confusion but
	this is required for legacy systems.
	@type timezone_offset: U{datetime.datetime.timedelta<http://
	docs.python.org/library/datetime.html#datetime.timedelta}

	@return: Message L{envelope<Envelope>}.
	"""
	if not isinstance(stream, util.BufferedByteStream):
	stream = util.BufferedByteStream(stream)

	if logger:
	logger.debug('remoting.decode start')

	msg = Envelope()
	msg.amfVersion = stream.read_ushort()

	# see http://osflash.org/documentation/amf/envelopes/remoting#preamble
	# why we are doing this...
	if msg.amfVersion > 0x09:
	raise pyamf.DecodeError("Malformed stream (amfVersion=%d)" %
	msg.amfVersion)

	decoder = pyamf.get_decoder(pyamf.AMF0, stream, strict=strict,
	timezone_offset=timezone_offset)
	context = decoder.context

	decoder.use_amf3 = msg.amfVersion == pyamf.AMF3
	header_count = stream.read_ushort()

	for i in xrange(header_count):
	name, required, data = _read_header(stream, decoder, strict)
	msg.headers[name] = data

	if required:
	msg.headers.set_required(name)

	body_count = stream.read_short()

	for i in xrange(body_count):
	context.clear()

	target, payload = _read_body(stream, decoder, strict, logger)
	msg[target] = payload

	if strict and stream.remaining() > 0:
	raise RuntimeError("Unable to fully consume the buffer")

	if logger:
	logger.debug('remoting.decode end')

	return msg


	def encode(msg, strict=False, logger=None, timezone_offset=None):
	"""
	Encodes and returns the L{msg<Envelope>} as an AMF stream.

	@param strict: Enforce strict encoding. Default is C{False}. Specifically
	header/body lengths will be written correctly, instead of the default 0.
	Default is `False`. Introduced in 0.4.
	@param logger: Used to log interesting events whilst decoding a remoting
	message.
	@type logger: U{logging.Logger<http://
	docs.python.org/library/logging.html#loggers>}
	@param timezone_offset: The difference between the current timezone and
	UTC. Date/times should always be handled in UTC to avoid confusion but
	this is required for legacy systems.
	@type timezone_offset: U{datetime.datetime.timedelta<http://
	docs.python.org/library/datetime.html#datetime.timedelta}
	@rtype: L{BufferedByteStream<pyamf.util.BufferedByteStream>}
	"""
	stream = util.BufferedByteStream()

	encoder = pyamf.get_encoder(pyamf.AMF0, stream, strict=strict,
	timezone_offset=timezone_offset)

	if msg.amfVersion == pyamf.AMF3:
	encoder.use_amf3 = True

	stream.write_ushort(msg.amfVersion)
	stream.write_ushort(len(msg.headers))

	for name, header in msg.headers.iteritems():
	_write_header(name, header, int(msg.headers.is_required(name)),
	stream, encoder, strict)

	stream.write_short(len(msg))

	for name, message in msg.iteritems():
	encoder.context.clear()

	_write_body(name, message, stream, encoder, strict)

	stream.seek(0)

	return stream


	def get_exception_from_fault(fault):
	"""
	"""
	return pyamf.ERROR_CLASS_MAP.get(fault.code, RemotingError)


	pyamf.register_class(ErrorFault)