def presence_stanza_handler(stanza_type = None, payload_class = None,<EOL>payload_key = None, usage_restriction = "<STR_LIT>"):

return _stanza_handler("<STR_LIT>", stanza_type, payload_class, payload_key,<EOL>usage_restriction)<EOL>

Method decorator generator for decorating <presence/>
    stanza handler methods in `XMPPFeatureHandler` subclasses.

    :Parameters:
        - `payload_class`: payload class expected
        - `stanza_type`: expected value of the 'type' attribute of the stanza.
        - `payload_key`: payload class specific filtering key
        - `usage_restriction`: optional usage restriction: "pre-auth" or
          "post-auth"
    :Types:
        - `payload_class`: subclass of `StanzaPayload`
        - `stanza_type`: `unicode`
        - `usage_restriction`: `unicode`


def decorator(klass):<EOL><INDENT>"""<STR_LIT>"""<EOL>from .stanzapayload import STANZA_PAYLOAD_CLASSES<EOL>from .stanzapayload import STANZA_PAYLOAD_ELEMENTS<EOL>if hasattr(klass, "<STR_LIT>"):<EOL><INDENT>klass._pyxmpp_payload_element_name.append(element_name)<EOL><DEDENT>else:<EOL><INDENT>klass._pyxmpp_payload_element_name = [element_name]<EOL><DEDENT>if element_name in STANZA_PAYLOAD_CLASSES:<EOL><INDENT>logger = logging.getLogger('<STR_LIT>')<EOL>logger.warning("<STR_LIT>".format(<EOL>element_name))<EOL><DEDENT>STANZA_PAYLOAD_CLASSES[element_name] = klass<EOL>STANZA_PAYLOAD_ELEMENTS[klass].append(element_name)<EOL>return klass<EOL><DEDENT>return decorator<EOL>

Class decorator generator for decorationg
    `StanzaPayload` subclasses.

    :Parameters:
        - `element_name`: XML element qname handled by the class
    :Types:
        - `element_name`: `unicode`


pass<EOL>


def make_stream_features(self, stream, features):

<EOL>return False<EOL>

Update the features element announced by the stream.

        [receiver only]

        :Parameters:
            - `stream`: the stream
            - `features`: the features element about to be sent
        :Types:
            - `stream`: `StreamBase`
            - `features`: :etree:`ElementTree.Element`


def handle_stream_features(self, stream, features):

<EOL>return False<EOL>

Handle features announced by the stream peer.

        [initiator only]

        :Parameters:
            - `stream`: the stream
            - `features`: the features element just received
        :Types:
            - `stream`: `StreamBase`
            - `features`: :etree:`ElementTree.Element`

        :Return:
            - `StreamFeatureHandled` instance if a feature was recognized and
              handled
            - `StreamFeatureNotHandled` instance if a feature was recognized
              but not handled
            - `None` if no feature was recognized


def _stanza_handler(element_name, stanza_type, payload_class, payload_key,<EOL>usage_restriction):

def decorator(func):<EOL><INDENT>"""<STR_LIT>"""<EOL>func._pyxmpp_stanza_handled = (element_name, stanza_type)<EOL>func._pyxmpp_payload_class_handled = payload_class<EOL>func._pyxmpp_payload_key = payload_key<EOL>func._pyxmpp_usage_restriction = usage_restriction<EOL>return func<EOL><DEDENT>return decorator<EOL>

Method decorator generator for decorating <message/> or <presence/>
    stanza handler methods in `XMPPFeatureHandler` subclasses.

    :Parameters:
        - `element_name`: "message" or "presence"
        - `stanza_type`: expected value of the 'type' attribute of the stanza
        - `payload_class`: payload class expected
        - `payload_key`: payload class specific filtering key
        - `usage_restriction`: optional usage restriction: "pre-auth" or
          "post-auth"
    :Types:
        - `element_name`: `unicode`
        - `stanza_type`: `unicode`
        - `payload_class`: subclass of `StanzaPayload`
        - `usage_restriction`: `unicode`


return {}<EOL>

Channel properties for authentication and authorization.


<EOL>raise NotImplementedError<EOL>

Create a `cls` instance from an XML element.

        :Parameters:
            - `element`: the XML element
        :Types:
            - `element`: :etree:`ElementTree.Element`


def _iq_handler(iq_type, payload_class, payload_key, usage_restriction):

def decorator(func):<EOL><INDENT>"""<STR_LIT>"""<EOL>func._pyxmpp_stanza_handled = ("<STR_LIT>", iq_type)<EOL>func._pyxmpp_payload_class_handled = payload_class<EOL>func._pyxmpp_payload_key = payload_key<EOL>func._pyxmpp_usage_restriction = usage_restriction<EOL>return func<EOL><DEDENT>return decorator<EOL>

Method decorator generator for decorating <iq type='get'/> stanza
    handler methods in `XMPPFeatureHandler` subclasses.

    :Parameters:
        - `payload_class`: payload class expected
        - `payload_key`: payload class specific filtering key
        - `usage_restriction`: optional usage restriction: "pre-auth" or
          "post-auth"
    :Types:
        - `payload_class`: subclass of `StanzaPayload`
        - `usage_restriction`: `unicode`


def iq_set_stanza_handler(payload_class, payload_key = None,<EOL>usage_restriction = "<STR_LIT>"):

return _iq_handler("<STR_LIT>", payload_class, payload_key, usage_restriction)<EOL>

Method decorator generator for decorating <iq type='set'/> stanza
    handler methods in `XMPPFeatureHandler` subclasses.

    :Parameters:
        - `payload_class`: payload class expected
        - `payload_key`: payload class specific filtering key
        - `usage_restriction`: optional usage restriction: "pre-auth" or
          "post-auth"
    :Types:
        - `payload_class`: subclass of `StanzaPayload`
        - `usage_restriction`: `unicode`


return deepcopy(self)<EOL>


return RosterClient(self.settings)<EOL>

Creates the `RosterClient` instance for the `roster_client`
        attribute.

        Subclasses can provide different behaviour by overriding this. The
        overriding method can return `None` if no roster client is needed.

        :Return: `RosterClient`


with self.lock:<EOL><INDENT>if self.stream:<EOL><INDENT>if self.settings[u"<STR_LIT>"]:<EOL><INDENT>self.send(Presence(stanza_type = "<STR_LIT>"))<EOL><DEDENT>self.stream.disconnect()<EOL><DEDENT><DEDENT>


tls_handler = StreamTLSHandler(self.settings)<EOL>sasl_handler = StreamSASLHandler(self.settings)<EOL>session_handler = SessionHandler()<EOL>binding_handler = ResourceBindingHandler(self.settings)<EOL>return [tls_handler, sasl_handler, binding_handler, session_handler]<EOL>

Default base client handlers factory.

        Subclasses can provide different behaviour by overriding this.

        :Return: list of handlers


if self.uplink:<EOL><INDENT>self.uplink.send(stanza)<EOL><DEDENT>else:<EOL><INDENT>raise NoRouteError("<STR_LIT>")<EOL><DEDENT>

Send a stanza somwhere.

        The default implementation sends it via the `uplink` if it is defined
        or raises the `NoRouteError`.

        :Parameters:
            - `stanza`: the stanza to send.
        :Types:
            - `stanza`: `pyxmpp.stanza.Stanza`


stanza_type = stanza.stanza_type<EOL>return self.__try_handlers(self._presence_handlers, stanza, stanza_type)<EOL>

Process presence stanza.

        Pass it to a handler of the stanza's type and payload namespace.

        :Parameters:
            - `stanza`: presence stanza to be handled


def __try_handlers(self, handler_list, stanza, stanza_type = None):

<EOL>if stanza_type is None:<EOL><INDENT>stanza_type = stanza.stanza_type<EOL><DEDENT>payload = stanza.get_all_payload()<EOL>classes = [p.__class__ for p in payload]<EOL>keys = [(p.__class__, p.handler_key) for p in payload]<EOL>for handler in handler_list:<EOL><INDENT>type_filter = handler._pyxmpp_stanza_handled[<NUM_LIT:1>]<EOL>class_filter = handler._pyxmpp_payload_class_handled<EOL>extra_filter = handler._pyxmpp_payload_key<EOL>if type_filter != stanza_type:<EOL><INDENT>continue<EOL><DEDENT>if class_filter:<EOL><INDENT>if extra_filter is None and class_filter not in classes:<EOL><INDENT>continue<EOL><DEDENT>if extra_filter and (class_filter, extra_filter) not in keys:<EOL><INDENT>continue<EOL><DEDENT><DEDENT>response = handler(stanza)<EOL>if self._process_handler_result(response):<EOL><INDENT>return True<EOL><DEDENT><DEDENT>return False<EOL>

Search the handler list for handlers matching
        given stanza type and payload namespace. Run the
        handlers found ordering them by priority until
        the first one which returns `True`.

        :Parameters:
            - `handler_list`: list of available handlers
            - `stanza`: the stanza to handle
            - `stanza_type`: stanza type override (value of its "type"
              attribute)

        :return: result of the last handler or `False` if no
            handler was found.


def setup_stanza_handlers(self, handler_objects, usage_restriction):

<EOL>iq_handlers = {"<STR_LIT>": {}, "<STR_LIT>": {}}<EOL>message_handlers = []<EOL>presence_handlers = []<EOL>for obj in handler_objects:<EOL><INDENT>if not isinstance(obj, XMPPFeatureHandler):<EOL><INDENT>continue<EOL><DEDENT>obj.stanza_processor = self<EOL>for dummy, handler in inspect.getmembers(obj, callable):<EOL><INDENT>if not hasattr(handler, "<STR_LIT>"):<EOL><INDENT>continue<EOL><DEDENT>element_name, stanza_type = handler._pyxmpp_stanza_handled<EOL>restr = handler._pyxmpp_usage_restriction<EOL>if restr and restr != usage_restriction:<EOL><INDENT>continue<EOL><DEDENT>if element_name == "<STR_LIT>":<EOL><INDENT>payload_class = handler._pyxmpp_payload_class_handled<EOL>payload_key = handler._pyxmpp_payload_key<EOL>if (payload_class, payload_key) in iq_handlers[stanza_type]:<EOL><INDENT>continue<EOL><DEDENT>iq_handlers[stanza_type][(payload_class, payload_key)] =handler<EOL>continue<EOL><DEDENT>elif element_name == "<STR_LIT:message>":<EOL><INDENT>handler_list = message_handlers<EOL><DEDENT>elif element_name == "<STR_LIT>":<EOL><INDENT>handler_list = presence_handlers<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>handler_list.append(handler)<EOL><DEDENT><DEDENT>with self.lock:<EOL><INDENT>self._iq_handlers = iq_handlers<EOL>self._presence_handlers = presence_handlers<EOL>self._message_handlers = message_handlers<EOL><DEDENT>

Install stanza handlers provided by `handler_objects`


pass<EOL>

Modify outgoing stanza before sending into the stream.

        This implementation does nothig. It should be overriden in derived
        classes if needed.


self.fix_in_stanza(stanza)<EOL>to_jid = stanza.to_jid<EOL>if not self.process_all_stanzas and to_jid and (<EOL>to_jid != self.me and to_jid.bare() != self.me.bare()):<EOL><INDENT>return self.route_stanza(stanza)<EOL><DEDENT>try:<EOL><INDENT>if isinstance(stanza, Iq):<EOL><INDENT>if self.process_iq(stanza):<EOL><INDENT>return True<EOL><DEDENT><DEDENT>elif isinstance(stanza, Message):<EOL><INDENT>if self.process_message(stanza):<EOL><INDENT>return True<EOL><DEDENT><DEDENT>elif isinstance(stanza, Presence):<EOL><INDENT>if self.process_presence(stanza):<EOL><INDENT>return True<EOL><DEDENT><DEDENT><DEDENT>except ProtocolError as err:<EOL><INDENT>typ = stanza.stanza_type<EOL>if typ != '<STR_LIT:error>' and (typ != '<STR_LIT:result>'<EOL>or stanza.stanza_type != '<STR_LIT>'):<EOL><INDENT>response = stanza.make_error_response(err.xmpp_name)<EOL>self.send(response)<EOL>err.log_reported()<EOL><DEDENT>else:<EOL><INDENT>err.log_ignored()<EOL><DEDENT>return<EOL><DEDENT>logger.debug("<STR_LIT>" % (stanza.stanza_type,<EOL>stanza.serialize()))<EOL>return False<EOL>

Process stanza received from the stream.

        First "fix" the stanza with `self.fix_in_stanza()`,
        then pass it to `self.route_stanza()` if it is not directed
        to `self.me` and `self.process_all_stanzas` is not True. Otherwise
        stanza is passwd to `self.process_iq()`, `self.process_message()`
        or `self.process_presence()` appropriately.

        :Parameters:
            - `stanza`: the stanza received.

        :returns: `True` when stanza was handled


def stanza_factory(element, return_path = None, language = None):

tag = element.tag<EOL>if tag.endswith("<STR_LIT>") or tag == "<STR_LIT>":<EOL><INDENT>return Iq(element, return_path = return_path, language = language)<EOL><DEDENT>if tag.endswith("<STR_LIT>") or tag == "<STR_LIT:message>":<EOL><INDENT>return Message(element, return_path = return_path, language = language)<EOL><DEDENT>if tag.endswith("<STR_LIT>") or tag == "<STR_LIT>":<EOL><INDENT>return Presence(element, return_path = return_path, language = language)<EOL><DEDENT>else:<EOL><INDENT>return Stanza(element, return_path = return_path, language = language)<EOL><DEDENT>

Creates Iq, Message or Presence object for XML stanza `element`

    :Parameters:
        - `element`: the stanza XML element
        - `return_path`: object through which responses to this stanza should
          be sent (will be weakly referenced by the stanza object).
        - `language`: default language for the stanza
    :Types:
        - `element`: :etree:`ElementTree.Element`
        - `return_path`: `StanzaRoute`
        - `language`: `unicode`


stanza_type = stanza.stanza_type<EOL>if stanza_type is None:<EOL><INDENT>stanza_type = "<STR_LIT>"<EOL><DEDENT>if self.__try_handlers(self._message_handlers, stanza,<EOL>stanza_type = stanza_type):<EOL><INDENT>return True<EOL><DEDENT>if stanza_type not in ("<STR_LIT:error>", "<STR_LIT>"):<EOL><INDENT>return self.__try_handlers(self._message_handlers, stanza,<EOL>stanza_type = "<STR_LIT>")<EOL><DEDENT>return False<EOL>

Process message stanza.

        Pass it to a handler of the stanza's type and payload namespace.
        If no handler for the actual stanza type succeeds then hadlers
        for type "normal" are used.

        :Parameters:
            - `stanza`: message stanza to be handled


def __init__(self, default_timeout = <NUM_LIT>):

self.me = None<EOL>self.peer = None<EOL>self.uplink = None<EOL>self.process_all_stanzas = True<EOL>self._iq_response_handlers = ExpiringDictionary(default_timeout)<EOL>self._iq_handlers = defaultdict(dict)<EOL>self._message_handlers = []<EOL>self._presence_handlers = []<EOL>self.lock = threading.RLock()<EOL>

Initialize a `StanzaProcessor` object.

        :Parameters:
            - `default_timeout`: default timeout for IQ response handlers


typ = stanza.stanza_type<EOL>if typ in ("<STR_LIT:result>", "<STR_LIT:error>"):<EOL><INDENT>return self._process_iq_response(stanza)<EOL><DEDENT>if typ not in ("<STR_LIT>", "<STR_LIT>"):<EOL><INDENT>raise BadRequestProtocolError("<STR_LIT>")<EOL><DEDENT>logger.debug("<STR_LIT>".format(<EOL>stanza, typ))<EOL>payload = stanza.get_payload(None)<EOL>logger.debug("<STR_LIT>".format(payload))<EOL>if not payload:<EOL><INDENT>raise BadRequestProtocolError("<STR_LIT>")<EOL><DEDENT>handler = self._get_iq_handler(typ, payload)<EOL>if not handler:<EOL><INDENT>payload = stanza.get_payload(None, specialize = True)<EOL>logger.debug("<STR_LIT>".format(payload))<EOL>if not isinstance(payload, XMLPayload):<EOL><INDENT>handler = self._get_iq_handler(typ, payload)<EOL><DEDENT><DEDENT>if handler:<EOL><INDENT>response = handler(stanza)<EOL>self._process_handler_result(response)<EOL>return True<EOL><DEDENT>else:<EOL><INDENT>raise ServiceUnavailableProtocolError("<STR_LIT>")<EOL><DEDENT>

Process IQ stanza received.

        :Parameters:
            - `stanza`: the stanza received
        :Types:
            - `stanza`: `Iq`

        If a matching handler is available pass the stanza to it.  Otherwise
        ignore it if it is "error" or "result" stanza or return
        "feature-not-implemented" error if it is "get" or "set".


result = Iq(None, self.from_jid, self.to_jid,<EOL>self.stanza_type, self.stanza_id, self.error,<EOL>self._return_path())<EOL>if self._payload is None:<EOL><INDENT>self.decode_payload()<EOL><DEDENT>for payload in self._payload:<EOL><INDENT>Stanza.add_payload(result, payload)<EOL><DEDENT>return result<EOL>

Create a deep copy of the stanza.

        :returntype: `Iq`


<EOL>from pyxmpp2.mainloop.glib import GLibMainLoop<EOL>self.loop = GLibMainLoop(None, handlers)<EOL>

Return a main loop object for use with this test suite.


logger.debug("<STR_LIT>")<EOL>while True:<EOL><INDENT>try:<EOL><INDENT>self.sock.do_handshake()<EOL>break<EOL><DEDENT>except ssl.SSLError as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] == ssl.SSL_ERROR_WANT_READ:<EOL><INDENT>select.select([self.sock], [], [])<EOL><DEDENT>elif err.args[<NUM_LIT:0>] == ssl.SSL_ERROR_WANT_WRITE:<EOL><INDENT>select.select([], [self.sock], [])<EOL><DEDENT>else:<EOL><INDENT>raise<EOL><DEDENT><DEDENT><DEDENT>logger.debug("<STR_LIT>")<EOL>self.extra_on_read = None<EOL>self.write_enabled = True<EOL>self.write_cond.notify()<EOL>

Do the TLS handshake. Called from the reader thread
        after `starttls` is called.


if self.server:<EOL><INDENT>self.server.close()<EOL><DEDENT>if self.client:<EOL><INDENT>self.client.close()<EOL><DEDENT>XMPPSettings._defs['<STR_LIT>'].default = None<EOL>

Stop the server and client connections started.


with self.lock:<EOL><INDENT>data, self.rdata = self.rdata, "<STR_LIT>"<EOL><DEDENT>return data<EOL>

Read data from input buffer (received by the reader thread).


<EOL>self.loop = PollMainLoop(None, handlers)<EOL>


def wait_short(self, timeout = <NUM_LIT:0.1>):


reader_thread = threading.Thread(target = self.reader_run,<EOL>name = "<STR_LIT>")<EOL>reader_thread.daemon = True<EOL>writter_thread = threading.Thread(target = self.writter_run,<EOL>name = "<STR_LIT>")<EOL>writter_thread.daemon = True<EOL>reader_thread.start()<EOL>writter_thread.start()<EOL>


self.transport = TCPTransport()<EOL>self.make_loop(handlers + [self.transport])<EOL>

Initialize a transport and a main loop with the provided handlers


addr, port = self.start_server()<EOL>self.transport.connect(addr, port)<EOL>

Start a test server and connect the transport to it.


with self.write_cond:<EOL><INDENT>while self.sock is not None:<EOL><INDENT>while self.ready and self.wdata and self.write_enabled:<EOL><INDENT>sent = self.sock.send(self.wdata)<EOL>logger.debug("<STR_LIT>" + repr(self.wdata[:sent]))<EOL>self.wdata = self.wdata[sent:]<EOL>self.write_cond.notify()<EOL><DEDENT>if self._disconnect and not self.wdata:<EOL><INDENT>self.sock.shutdown(socket.SHUT_WR)<EOL>logger.debug("<STR_LIT>")<EOL>break<EOL><DEDENT>self.write_cond.wait()<EOL><DEDENT><DEDENT>


self.loop = SelectMainLoop(None, handlers)<EOL>


if "<STR_LIT>" not in _support.RESOURCES:<EOL><INDENT>raise unittest.SkipTest("<STR_LIT>")<EOL><DEDENT>try:<EOL><INDENT>sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)<EOL>sock.close()<EOL>cls.can_do_ipv4 = True<EOL><DEDENT>except socket.error as err:<EOL><INDENT>logger.debug("<STR_LIT>".format(err))<EOL>pass<EOL><DEDENT>if socket.has_ipv6:<EOL><INDENT>try:<EOL><INDENT>sock = socket.socket(socket.AF_INET6, socket.SOCK_STREAM)<EOL>sock.close()<EOL>cls.can_do_ipv6 = True<EOL><DEDENT>except socket.error as err:<EOL><INDENT>logger.debug("<STR_LIT>".format(err))<EOL>pass<EOL><DEDENT><DEDENT>

Check if loopback networking is enabled and IPv4 and IPv6 sockets
        available.


super(ReceiverThreadedTestMixIn, self).start_transport(handlers)<EOL>self.loop.start()<EOL>

Create a listening socket for the tested stream,
        a transport a main loop and create a client connectiong to the
        socket.


<EOL>self.loop = ThreadPool(XMPPSettings({"<STR_LIT>": <NUM_LIT:0.1>}), handlers)<EOL>


kwargs['<STR_LIT>'] = False<EOL>with self.lock:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>while self.wdata:<EOL><INDENT>self.write_cond.wait()<EOL><DEDENT>self.write_enabled = False<EOL>self.write_cond.notify()<EOL>logger.debug("<STR_LIT>")<EOL>self.sock = ssl.wrap_socket(*args, **kwargs)<EOL>self.extra_on_read = self._do_tls_handshake<EOL>self.rdata = b"<STR_LIT>"<EOL><DEDENT>

Request switching to TLS.

        First waits untill all currently buffered data is sent.

        :Parameters:
            - `args`: positional arguments to :std:`ssl.wrap_socket`
            - `kwargs`: keyword arguments to :std:`ssl.wrap_socket`


self.events_received.append(event)<EOL>return False<EOL>

Handle any event: store it in `events_received`.


suite = unittest.TestSuite()<EOL>for mod in unittest.defaultTestLoader.discover("<STR_LIT>", "<STR_LIT>"):<EOL><INDENT>suite.addTest(mod)<EOL><DEDENT>return suite<EOL>

Discover all the test suites in pyxmpp2.test.


return SelectMainLoop(None, handlers)<EOL>


from pyxmpp2.mainloop.glib import GLibMainLoop<EOL>return GLibMainLoop(None, handlers)<EOL>


return PollMainLoop(None, handlers)<EOL>


def __init__(self, family, address, target):

self._socket = None<EOL>self._lock = threading.RLock()<EOL>self._target = target<EOL>sock = socket.socket(family, socket.SOCK_STREAM)<EOL>try:<EOL><INDENT>sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, <NUM_LIT:1>)<EOL>sock.bind(address)<EOL><DEDENT>except:<EOL><INDENT>sock.close()<EOL>raise<EOL><DEDENT>self._socket = sock<EOL>

Initialize the `TCPListener` object and create the socket.

        :Parameters:
            - `family`: address family (:std:`socket.AF_INET` or
              :std:`socket.AF_INET6`)
            - `address`: address to listen on (address, port)
            - `target`: function to call on an accepted connection


with self._lock:<EOL><INDENT>if self._socket:<EOL><INDENT>return self._socket.fileno()<EOL><DEDENT><DEDENT>

Return file descriptor to poll or select.


with self._lock:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>if self._socket is None:<EOL><INDENT>return<EOL><DEDENT>while True:<EOL><INDENT>try:<EOL><INDENT>sock, address = self._socket.accept()<EOL><DEDENT>except socket.error as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] in BLOCKING_ERRORS:<EOL><INDENT>break<EOL><DEDENT>else:<EOL><INDENT>raise<EOL><DEDENT><DEDENT>logger.debug("<STR_LIT>".format(address))<EOL>self._target(sock, address)<EOL><DEDENT><DEDENT>


return payload_class_for_element_name(element.tag).from_xml(element)<EOL>

Return a specialized `StanzaPayload` object for given element.


logger.debug("<STR_LIT>".format(<EOL>element_name))<EOL>logger.debug("<STR_LIT>".format(STANZA_PAYLOAD_CLASSES))<EOL>if element_name in STANZA_PAYLOAD_CLASSES:<EOL><INDENT>return STANZA_PAYLOAD_CLASSES[element_name]<EOL><DEDENT>else:<EOL><INDENT>return XMLPayload<EOL><DEDENT>

Return a payload class for given element name.


logger.error("<STR_LIT>".format(element))<EOL>

Called when the start tag of root element is encountered
        in the stream.

        :Parameters:
            - `element`: the root element
        :Types:
            - `element`: :etree:`ElementTree.Element`


self._handler = handler<EOL>self._head = "<STR_LIT>"<EOL>self._tail = "<STR_LIT>"<EOL>self._builder = None<EOL>self._level = <NUM_LIT:0><EOL>self._root = None<EOL>

Initialize the SAX handler.

        :Parameters:
            - `handler`: Object to handle stream start, end and stanzas.
        :Types:
            - `handler`: `XMLStreamHandler`


self.handler = handler<EOL>self.parser = ElementTree.XMLParser(target = ParserTarget(handler))<EOL>self.lock = threading.RLock()<EOL>self.in_use = False<EOL>self._started = False<EOL>

Initialize the reader.

        :Parameters:
            - `handler`: Object to handle stream start, end and stanzas.
        :Types:
            - `handler`: `XMLStreamHandler`


for char in data:<EOL><INDENT>for lookup in self.prohibited:<EOL><INDENT>if lookup(char):<EOL><INDENT>raise StringprepError("<STR_LIT>"<EOL>.format(char))<EOL><DEDENT><DEDENT><DEDENT>return data<EOL>


result = []<EOL>for char in data:<EOL><INDENT>ret = None<EOL>for lookup in self.mapping:<EOL><INDENT>ret = lookup(char)<EOL>if ret is not None:<EOL><INDENT>break<EOL><DEDENT><DEDENT>if ret is not None:<EOL><INDENT>result.append(ret)<EOL><DEDENT>else:<EOL><INDENT>result.append(char)<EOL><DEDENT><DEDENT>return result<EOL>


<EOL>global _stringprep_cache_size<EOL>_stringprep_cache_size = size<EOL>if len(Profile.cache_items) > size:<EOL><INDENT>remove = Profile.cache_items[:-size]<EOL>for profile, key in remove:<EOL><INDENT>try:<EOL><INDENT>del profile.cache[key]<EOL><DEDENT>except KeyError:<EOL><INDENT>pass<EOL><DEDENT><DEDENT>Profile.cache_items = Profile.cache_items[-size:]<EOL><DEDENT>

Modify stringprep cache size.

    :Parameters:
        - `size`: new cache size


logger.debug("<STR_LIT>".format(event))<EOL>if self._stream:<EOL><INDENT>event.stream = self._stream<EOL><DEDENT>self._event_queue.put(event)<EOL>

Pass an event to the target stream or just log it.


logger.debug("<STR_LIT>".format(state))<EOL>self._state = state<EOL>self._state_cond.notify()<EOL>

Set `_state` and notify any threads waiting for the change.


with self.lock:<EOL><INDENT>if self._eof or self._socket is None or not self._serializer:<EOL><INDENT>logger.debug("<STR_LIT>".format(<EOL>element_to_unicode(element)))<EOL>return<EOL><DEDENT>data = self._serializer.emit_stanza(element)<EOL>self._write(data.encode("<STR_LIT:utf-8>"))<EOL><DEDENT>


def send_stream_head(self, stanza_namespace, stream_from, stream_to,<EOL>stream_id = None, version = '<STR_LIT:1.0>', language = None):

<EOL>with self.lock:<EOL><INDENT>self._serializer = XMPPSerializer(stanza_namespace,<EOL>self.settings["<STR_LIT>"])<EOL>head = self._serializer.emit_head(stream_from, stream_to,<EOL>stream_id, version, language)<EOL>self._write(head.encode("<STR_LIT:utf-8>"))<EOL><DEDENT>

Send stream head via the transport.

:Parameters:
    - `stanza_namespace`: namespace of stream stanzas (e.g.
      'jabber:client')
    - `stream_from`: the 'from' attribute of the stream. May be `None`.
    - `stream_to`: the 'to' attribute of the stream. May be `None`.
    - `version`: the 'version' of the stream.
    - `language`: the 'xml:lang' of the stream
:Types:
    - `stanza_namespace`: `unicode`
    - `stream_from`: `unicode`
    - `stream_to`: `unicode`
    - `version`: `unicode`
    - `language`: `unicode`


self._set_state("<STR_LIT>")<EOL>resolver = self.settings["<STR_LIT>"] <EOL>logger.debug("<STR_LIT>".format(self._dst_nameports))<EOL>name, port = self._dst_nameports.pop(<NUM_LIT:0>)<EOL>self._dst_hostname = name<EOL>resolver.resolve_address(name, callback = partial(<EOL>self._got_addresses, name, port),<EOL>allow_cname = self._dst_service is None)<EOL>self.event(ResolvingAddressEvent(name))<EOL>

Start hostname resolution for the next name to try.

        [called with `lock` acquired]


with self.lock:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>if self._eof or self._socket is None:<EOL><INDENT>return<EOL><DEDENT>if self._state == "<STR_LIT>":<EOL><INDENT>while True:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>self._continue_tls_handshake()<EOL>logger.debug("<STR_LIT>".format(self._tls_state))<EOL>if self._tls_state != "<STR_LIT>":<EOL><INDENT>break<EOL><DEDENT><DEDENT><DEDENT>elif self._tls_state == "<STR_LIT>":<EOL><INDENT>while self._socket and not self._eof:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>try:<EOL><INDENT>data = self._socket.read(<NUM_LIT>)<EOL><DEDENT>except ssl.SSLError as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] == ssl.SSL_ERROR_WANT_READ:<EOL><INDENT>break<EOL><DEDENT>elif err.args[<NUM_LIT:0>] == ssl.SSL_ERROR_WANT_WRITE:<EOL><INDENT>break<EOL><DEDENT>else:<EOL><INDENT>raise<EOL><DEDENT><DEDENT>except socket.error as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] == errno.EINTR:<EOL><INDENT>continue<EOL><DEDENT>elif err.args[<NUM_LIT:0>] in BLOCKING_ERRORS:<EOL><INDENT>break<EOL><DEDENT>elif err.args[<NUM_LIT:0>] == errno.ECONNRESET:<EOL><INDENT>logger.warning("<STR_LIT>")<EOL>data = None<EOL><DEDENT>else:<EOL><INDENT>raise<EOL><DEDENT><DEDENT>self._feed_reader(data)<EOL><DEDENT><DEDENT>else:<EOL><INDENT>while self._socket and not self._eof:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>try:<EOL><INDENT>data = self._socket.recv(<NUM_LIT>)<EOL><DEDENT>except socket.error as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] == errno.EINTR:<EOL><INDENT>continue<EOL><DEDENT>elif err.args[<NUM_LIT:0>] in BLOCKING_ERRORS:<EOL><INDENT>break<EOL><DEDENT>elif err.args[<NUM_LIT:0>] == errno.ECONNRESET:<EOL><INDENT>logger.warning("<STR_LIT>")<EOL>data = None<EOL><DEDENT>else:<EOL><INDENT>raise<EOL><DEDENT><DEDENT>self._feed_reader(data)<EOL><DEDENT><DEDENT><DEDENT>

Handle the 'channel readable' state. E.g. read from a socket.


self._auth_properties['<STR_LIT>'] = self._dst_addr[<NUM_LIT:0>]<EOL>if self._dst_service:<EOL><INDENT>self._auth_properties['<STR_LIT>'] = self._dst_name<EOL><DEDENT>if self._dst_hostname is not None:<EOL><INDENT>self._auth_properties['<STR_LIT>'] = self._dst_hostname<EOL><DEDENT>else:<EOL><INDENT>self._auth_properties['<STR_LIT>'] = self._dst_addr[<NUM_LIT:0>]<EOL><DEDENT>self._auth_properties['<STR_LIT>'] = None<EOL>self.event(ConnectedEvent(self._dst_addr))<EOL>self._set_state("<STR_LIT>")<EOL>self._stream.transport_connected()<EOL>


OUT_LOGGER.debug("<STR_LIT>", data)<EOL>if self._hup or not self._socket:<EOL><INDENT>raise PyXMPPIOError("<STR_LIT>")<EOL><DEDENT>try:<EOL><INDENT>while data:<EOL><INDENT>try:<EOL><INDENT>sent = self._socket.send(data)<EOL><DEDENT>except ssl.SSLError as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] == ssl.SSL_ERROR_WANT_WRITE:<EOL><INDENT>continue<EOL><DEDENT>else:<EOL><INDENT>raise<EOL><DEDENT><DEDENT>except socket.error as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] == errno.EINTR:<EOL><INDENT>continue<EOL><DEDENT>if err.args[<NUM_LIT:0>] in BLOCKING_ERRORS:<EOL><INDENT>wait_for_write(self._socket)<EOL>continue<EOL><DEDENT>raise<EOL><DEDENT>data = data[sent:]<EOL><DEDENT><DEDENT>except (IOError, OSError, socket.error) as err:<EOL><INDENT>raise PyXMPPIOError("<STR_LIT>".format(err))<EOL><DEDENT>

Write raw data to the socket.

        :Parameters:
            - `data`: data to send
        :Types:
            - `data`: `bytes`


with self.lock:<EOL><INDENT>if self._stream:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>self._stream = stream<EOL>self._reader = StreamReader(stream)<EOL><DEDENT>

Make the `stream` the target for this transport instance.

        The 'stream_start', 'stream_end' and 'stream_element' methods
        of the target will be called when appropriate content is received.

        :Parameters:
            - `stream`: the stream handler to receive stream content
              from the transport
        :Types:
            - `stream`: `StreamBase`


logger.debug("<STR_LIT>")<EOL>with self.lock:<EOL><INDENT>if self._socket is None:<EOL><INDENT>if self._state != "<STR_LIT>":<EOL><INDENT>self.event(DisconnectedEvent(self._dst_addr))<EOL>self._set_state("<STR_LIT>")<EOL><DEDENT>return<EOL><DEDENT>if self._hup or not self._serializer:<EOL><INDENT>self._close()<EOL><DEDENT>else:<EOL><INDENT>self.send_stream_tail()<EOL><DEDENT><DEDENT>


with self.lock:<EOL><INDENT>return self._socket and bool(self._write_queue)<EOL><DEDENT>

:Return: `False` as currently the data is always written synchronously


try:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>self._socket.do_handshake()<EOL><DEDENT>except ssl.SSLError as err:<EOL><INDENT>if err.args[<NUM_LIT:0>] == ssl.SSL_ERROR_WANT_READ:<EOL><INDENT>self._tls_state = "<STR_LIT>"<EOL>logger.debug("<STR_LIT>")<EOL>self._state_cond.notify()<EOL>return<EOL><DEDENT>elif err.args[<NUM_LIT:0>] == ssl.SSL_ERROR_WANT_WRITE:<EOL><INDENT>self._tls_state = "<STR_LIT>"<EOL>logger.debug("<STR_LIT>")<EOL>self._write_queue.appendleft(TLSHandshake)<EOL>return<EOL><DEDENT>else:<EOL><INDENT>raise<EOL><DEDENT><DEDENT>self._tls_state = "<STR_LIT>"<EOL>self._set_state("<STR_LIT>")<EOL>self._auth_properties['<STR_LIT>'] = "<STR_LIT>"<EOL>if "<STR_LIT>" in CHANNEL_BINDING_TYPES:<EOL><INDENT>try:<EOL><INDENT>tls_unique = self._socket.get_channel_binding("<STR_LIT>")<EOL><DEDENT>except ValueError:<EOL><INDENT>pass<EOL><DEDENT>else:<EOL><INDENT>self._auth_properties['<STR_LIT>'] = {<EOL>"<STR_LIT>": tls_unique}<EOL><DEDENT><DEDENT>try:<EOL><INDENT>cipher = self._socket.cipher()<EOL><DEDENT>except AttributeError:<EOL><INDENT>cipher = "<STR_LIT>"<EOL><DEDENT>cert = get_certificate_from_ssl_socket(self._socket)<EOL>self.event(TLSConnectedEvent(cipher, cert))<EOL>


with self.lock:<EOL><INDENT>if self._state == '<STR_LIT>' and self._dst_addrs:<EOL><INDENT>self._hup = False<EOL>self._set_state("<STR_LIT>")<EOL>return<EOL><DEDENT><DEDENT>self._hup = True<EOL>

Handle the 'channel hungup' state. The handler should not be writable
after this.


if self._socket is None:<EOL><INDENT>return<EOL><DEDENT>self._set_state("<STR_LIT>")<EOL>raise PyXMPPIOError("<STR_LIT>")<EOL>


with self.lock:<EOL><INDENT>if self._state == '<STR_LIT>' and self._dst_addrs:<EOL><INDENT>self._hup = False<EOL>self._set_state("<STR_LIT>")<EOL>return<EOL><DEDENT>self._socket.close()<EOL>self._socket = None<EOL>self._set_state("<STR_LIT>")<EOL>self._write_queue.clear()<EOL>self._write_queue_cond.notify()<EOL><DEDENT>raise PyXMPPIOError("<STR_LIT>")<EOL>


def connect(self, addr, port = None, service = None):

with self.lock:<EOL><INDENT>self._connect(addr, port, service)<EOL><DEDENT>

Start establishing TCP connection with given address.

        One of: `port` or `service` must be provided and `addr` must be
        a domain name and not an IP address if `port` is not given.

        When `service` is given try an SRV lookup for that service
        at domain `addr`. If `service` is not given or `addr` is an IP address,
        or the SRV lookup fails, connect to `port` at host `addr` directly.

        [initiating entity only]

        :Parameters:
            - `addr`: peer name or IP address
            - `port`: port number to connect to
            - `service`: service name (to be resolved using SRV DNS records)


with self.lock:<EOL><INDENT>if not self._socket or self._hup:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>return<EOL><DEDENT>data = self._serializer.emit_tail()<EOL>try:<EOL><INDENT>self._write(data.encode("<STR_LIT:utf-8>"))<EOL><DEDENT>except (IOError, SystemError, socket.error) as err:<EOL><INDENT>logger.debug("<STR_LIT>"<EOL>.format(err))<EOL><DEDENT>self._serializer = None<EOL>self._hup = True<EOL>if self._tls_state is None:<EOL><INDENT>try:<EOL><INDENT>self._socket.shutdown(socket.SHUT_WR)<EOL><DEDENT>except socket.error:<EOL><INDENT>pass<EOL><DEDENT><DEDENT>self._set_state("<STR_LIT>")<EOL>self._write_queue.clear()<EOL>self._write_queue_cond.notify()<EOL><DEDENT>


with self.lock:<EOL><INDENT>self.event(TLSConnectingEvent())<EOL>self._write_queue.append(StartTLS(**kwargs))<EOL>self._write_queue_cond.notify()<EOL><DEDENT>

Request a TLS handshake on the socket ans switch
        to encrypted output.
        The handshake will start after any currently buffered data is sent.

        :Parameters:
            - `kwargs`: arguments for :std:`ssl.wrap_socket`


def __init__(self, settings = None, sock = None):

if settings:<EOL><INDENT>self.settings = settings<EOL><DEDENT>else:<EOL><INDENT>self.settings = XMPPSettings()<EOL><DEDENT>self.lock = threading.RLock()<EOL>self._write_queue = deque()<EOL>self._write_queue_cond = threading.Condition(self.lock)<EOL>self._eof = False<EOL>self._hup = False<EOL>self._stream = None<EOL>self._serializer = None<EOL>self._reader = None<EOL>self._dst_name = None<EOL>self._dst_port = None<EOL>self._dst_service = None<EOL>self._dst_nameports = None<EOL>self._dst_hostname = None<EOL>self._dst_addrs = None<EOL>self._tls_state = None<EOL>self._state_cond = threading.Condition(self.lock)<EOL>if sock is None:<EOL><INDENT>self._socket = None<EOL>self._dst_addr = None<EOL>self._family = None<EOL>self._state = None<EOL><DEDENT>else:<EOL><INDENT>self._socket = sock<EOL>self._family = sock.family<EOL>self._dst_addr = sock.getpeername()<EOL>self._state = "<STR_LIT>"<EOL>self._socket.setblocking(False)<EOL><DEDENT>self._event_queue = self.settings["<STR_LIT>"]<EOL>self._auth_properties = {}<EOL>

Initialize the `TCPTransport` object.

        :Parameters:
            - `settings`: XMPP settings to use
            - `sock`: existing socket, e.g. for accepted incoming connection.


def __init__(self, jid, stanza_route, handlers, settings = None):

if handlers is None:<EOL><INDENT>handlers = []<EOL><DEDENT>if settings is None:<EOL><INDENT>settings = XMPPSettings()<EOL><DEDENT>if "<STR_LIT>" not in settings:<EOL><INDENT>settings["<STR_LIT>"] = jid.resource<EOL><DEDENT>StreamBase.__init__(self, STANZA_CLIENT_NS, stanza_route,<EOL>handlers, settings)<EOL>self.me = JID(jid.local, jid.domain)<EOL>

Initialize the ClientStream object.

        :Parameters:
            - `jid`: local JID.
            - `handlers`: XMPP feature and event handlers
            - `settings`: PyXMPP settings for the stream
        :Types:
            - `jid`: `JID`
            - `settings`: `XMPPSettings`


def receive(self, transport, myname = None):

if myname is None:<EOL><INDENT>myname = JID(self.me.domain)<EOL><DEDENT>return StreamBase.receive(self, transport, myname)<EOL>

Receive an XMPP connection over the `transport`.

        :Parameters:
            - `transport`: an XMPP transport instance
            - `myname`: local stream endpoint name (defaults to own jid domain
              part).


def initiate(self, transport, to = None):

if to is None:<EOL><INDENT>to = JID(self.me.domain)<EOL><DEDENT>return StreamBase.initiate(self, transport, to)<EOL>

Initiate an XMPP connection over the `transport`.

        :Parameters:
            - `transport`: an XMPP transport instance
            - `to`: peer name (defaults to own jid domain part)


def __init__(self, element = None, from_jid = None, to_jid = None,<EOL>stanza_type = None, stanza_id = None,<EOL>error = None, error_cond = None, return_path = None,<EOL>language = None,<EOL>subject = None, body = None, thread = None):

<EOL>self._subject = None<EOL>self._body = None<EOL>self._thread = None<EOL>if element is None:<EOL><INDENT>element = "<STR_LIT:message>"<EOL><DEDENT>elif not isinstance(element, ElementClass):<EOL><INDENT>raise TypeError("<STR_LIT>" + repr(element))<EOL><DEDENT>Stanza.__init__(self, element, from_jid = from_jid, to_jid = to_jid,<EOL>stanza_type = stanza_type, stanza_id = stanza_id,<EOL>error = error, error_cond = error_cond,<EOL>return_path = return_path, language = language)<EOL>if self.element_name != "<STR_LIT:message>":<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>self._subject_tag = self._ns_prefix + "<STR_LIT>"<EOL>self._body_tag = self._ns_prefix + "<STR_LIT:body>"<EOL>self._thread_tag = self._ns_prefix + "<STR_LIT>"<EOL>if self._element is not None:<EOL><INDENT>self._decode_subelements()<EOL><DEDENT>if subject is not None:<EOL><INDENT>self.subject = subject<EOL><DEDENT>if body is not None:<EOL><INDENT>self.body = body<EOL><DEDENT>if thread is not None:<EOL><INDENT>self.thread = thread<EOL><DEDENT>

Initialize a `Message` object.

        :Parameters:
            - `element`: XML element of this stanza.
            - `from_jid`: sender JID.
            - `to_jid`: recipient JID.
            - `stanza_type`: staza type: one of: "normal", "chat", "headline",
              "error", "groupchat"
            - `stanza_id`: stanza id -- value of stanza's "id" attribute. If
              not given, then unique for the session value is generated.
            - `error_cond`: error condition name. Ignored if `stanza_type`
              is not "error".
            - `language`: default language for the stanza content
            - `subject`: message subject,
            - `body`: message body.
            - `thread`: message thread id.
        :Types:
            - `element`: :etree:`ElementTree.Element`
            - `from_jid`: `JID`
            - `to_jid`: `JID`
            - `stanza_type`: `unicode`
            - `stanza_id`: `unicode`
            - `error`: `pyxmpp.error.StanzaErrorElement`
            - `error_cond`: `unicode`
            - `subject`: `unicode`
            - `body`: `unicode`
            - `thread`: `unicode`
            - `language`: `unicode`


return self._thread<EOL>

Thread id.

        :Returntype: `unicode`


if self.stanza_type == "<STR_LIT:error>":<EOL><INDENT>raise ValueError("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT>msg = Message(stanza_type = "<STR_LIT:error>", from_jid = self.to_jid,<EOL>to_jid = self.from_jid, stanza_id = self.stanza_id,<EOL>error_cond = cond,<EOL>subject = self._subject, body = self._body,<EOL>thread = self._thread)<EOL>if self._payload is None:<EOL><INDENT>self.decode_payload()<EOL><DEDENT>for payload in self._payload:<EOL><INDENT>msg.add_payload(payload.copy())<EOL><DEDENT>return msg<EOL>

Create error response for any non-error message stanza.

        :Parameters:
            - `cond`: error condition name, as defined in XMPP specification.

        :return: new message stanza with the same "id" as self, "from" and
            "to" attributes swapped, type="error" and containing <error />
            element plus payload of `self`.
        :returntype: `Message`


result = Stanza.as_xml(self)<EOL>if self._subject:<EOL><INDENT>child = ElementTree.SubElement(result, self._subject_tag)<EOL>child.text = self._subject<EOL><DEDENT>if self._body:<EOL><INDENT>child = ElementTree.SubElement(result, self._body_tag)<EOL>child.text = self._body<EOL><DEDENT>if self._thread:<EOL><INDENT>child = ElementTree.SubElement(result, self._thread_tag)<EOL>child.text = self._thread<EOL><DEDENT>return result<EOL>

Return the XML stanza representation.

        Always return an independent copy of the stanza XML representation,
        which can be freely modified without affecting the stanza.

        :returntype: :etree:`ElementTree.Element`


for child in self._element:<EOL><INDENT>if child.tag == self._subject_tag:<EOL><INDENT>self._subject = child.text<EOL><DEDENT>elif child.tag == self._body_tag:<EOL><INDENT>self._body = child.text<EOL><DEDENT>elif child.tag == self._thread_tag:<EOL><INDENT>self._thread = child.text<EOL><DEDENT><DEDENT>


self._settings[unicode(key)] = value<EOL>

Set a parameter value.

        :Parameters:
            - `key`: the parameter name
            - `value`: the new value
        :Types:
            - `key`: `unicode`


return self.get(key, required = True)<EOL>

Get a parameter value. Return the default if no value is set
        and the default is provided by PyXMPP.

        :Parameters:
            - `key`: the parameter name
        :Types:
            - `key`: `unicode`


return len(self._settings)<EOL>


if data is None:<EOL><INDENT>self._settings = {}<EOL><DEDENT>else:<EOL><INDENT>self._settings = dict(data)<EOL><DEDENT>

Create settings, optionally initialized with `data`.

        :Parameters:
            - `data`: initial data
        :Types:
            - `data`: any mapping, including `XMPPSettings`


def validate_int_range(value):<EOL><INDENT>"""<STR_LIT>"""<EOL>value = int(value)<EOL>if value >= start and value < stop:<EOL><INDENT>return value<EOL><DEDENT>raise ValueError("<STR_LIT>".format(start, stop))<EOL><DEDENT>return validate_int_range<EOL>

Return an integer range validator to be used with `add_setting`.

        :Parameters:
            - `start`: minimum value for the integer
            - `stop`: the upper bound (maximum value + 1)
        :Types:
            - `start`: `int`
            - `stop`: `int`

        :return: a validator function


@classmethod<EOL><INDENT>def add_setting(cls, name, type = unicode, default = None, factory = None,<EOL>cache = False, default_d = None, doc = None,<EOL>cmdline_help = None, validator = None, basic = False):<DEDENT>

<EOL>setting_def = _SettingDefinition(name, type, default, factory,<EOL>cache, default_d, doc,<EOL>cmdline_help, validator, basic)<EOL>if name not in cls._defs:<EOL><INDENT>cls._defs[name] = setting_def<EOL>return<EOL><DEDENT>duplicate = cls._defs[name]<EOL>if duplicate.type != setting_def.type:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if duplicate.default != setting_def.default:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>if duplicate.factory != setting_def.factory:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>

Add a new setting definition.

        :Parameters:
            - `name`: setting name
            - `type`: setting type object or type description
            - `default`: default value
            - `factory`: default value factory
            - `cache`: if `True` the `factory` will be called only once
              and its value stored as a constant default.
            - `default_d`: description of the default value
            - `doc`: setting documentation
            - `cmdline_help`: command line argument description. When not
              provided then the setting won't be available as a command-line
              option
            - `basic`: when `True` the option is considered a basic option -
              one of those which should usually stay configurable in
              an application.
            - `validator`: function validating command-line option value string
              and returning proper value for the settings objects. Defaults
              to `type`.
        :Types:
            - `name`: `unicode`
            - `type`: type or `unicode`
            - `factory`: a callable
            - `cache`: `bool`
            - `default_d`: `unicode`
            - `doc`: `unicode`
            - `cmdline_help`: `unicode`
            - `basic`: `bool`
            - `validator`: a callable


for key in self._settings.iterkeys():<EOL><INDENT>return self[key]<EOL><DEDENT>


try:<EOL><INDENT>if sys.version_info.major < <NUM_LIT:3>:<EOL><INDENT>from locale import getpreferredencoding<EOL>encoding = getpreferredencoding()<EOL>value = value.decode(encoding)<EOL><DEDENT>return [x.strip() for x in value.split(u"<STR_LIT:U+002C>")]<EOL><DEDENT>except (AttributeError, TypeError, UnicodeError):<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>

Validator for string lists to be used with `add_setting`.


if hasattr(ElementTree, '<STR_LIT>'):<EOL><INDENT>return ElementTree.tounicode("<STR_LIT>")<EOL><DEDENT>elif sys.version_info.major < <NUM_LIT:3>:<EOL><INDENT>return unicode(ElementTree.tostring(element))<EOL><DEDENT>else:<EOL><INDENT>return ElementTree.tostring(element, encoding = "<STR_LIT>")<EOL><DEDENT>

Serialize an XML element into a unicode string.

    This should work the same on Python2 and Python3 and with all
    :etree:`ElementTree` implementations.

    :Parameters:
        - `element`: the XML element to serialize
    :Types:
        - `element`: :etree:`ElementTree.Element`


<EOL>ts = time.time()<EOL>cur = datetime.datetime.fromtimestamp(ts)<EOL>cur_utc = datetime.datetime.utcfromtimestamp(ts)<EOL>offset = cur - cur_utc<EOL>t = utc<EOL>d = datetime.timedelta(hours = <NUM_LIT:2>)<EOL>while d > _MINUTE:<EOL><INDENT>local = t + offset<EOL>tm = local.timetuple()<EOL>tm = tm[<NUM_LIT:0>:<NUM_LIT:8>] + (<NUM_LIT:0>, )<EOL>ts = time.mktime(tm)<EOL>u = datetime.datetime.utcfromtimestamp(ts)<EOL>diff = u - utc<EOL>if diff < _MINUTE and diff > -_MINUTE:<EOL><INDENT>break<EOL><DEDENT>if diff > _NULLDELTA:<EOL><INDENT>offset -= d<EOL><DEDENT>else:<EOL><INDENT>offset += d<EOL><DEDENT>d //= <NUM_LIT:2><EOL><DEDENT>return local<EOL>

An ugly hack to convert naive :std:`datetime.datetime` object containing
UTC time to a naive :std:`datetime.datetime` object with local time.
It seems standard Python 2.3 library doesn't provide any better way to
do that.


@stream_element_handler(FAILURE_TAG, "<STR_LIT>")<EOL><INDENT>def _process_sasl_failure(self, stream, element):<DEDENT>

_unused = stream<EOL>if not self.authenticator:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>return False<EOL><DEDENT>logger.debug("<STR_LIT>".format(<EOL>element_to_unicode(element)))<EOL>raise SASLAuthenticationFailed("<STR_LIT>")<EOL>

Process incoming <sasl:failure/> element.

        [initiating entity only]


def _handle_auth_success(self, stream, success):

if not self._check_authorization(success.properties, stream):<EOL><INDENT>element = ElementTree.Element(FAILURE_TAG)<EOL>ElementTree.SubElement(element, SASL_QNP + "<STR_LIT>")<EOL>return True<EOL><DEDENT>authzid = success.properties.get("<STR_LIT>")<EOL>if authzid:<EOL><INDENT>peer = JID(success.authzid)<EOL><DEDENT>elif "<STR_LIT:username>" in success.properties:<EOL><INDENT>peer = JID(success.properties["<STR_LIT:username>"], stream.me.domain)<EOL><DEDENT>else:<EOL><INDENT>peer = None<EOL><DEDENT>stream.set_peer_authenticated(peer, True)<EOL>

Handle successful authentication.

        Send <success/> and mark the stream peer authenticated.

        [receiver only]


@stream_element_handler(CHALLENGE_TAG, "<STR_LIT>")<EOL><INDENT>def _process_sasl_challenge(self, stream, element):<DEDENT>

if not self.authenticator:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>return False<EOL><DEDENT>content = element.text.encode("<STR_LIT>")<EOL>ret = self.authenticator.challenge(a2b_base64(content))<EOL>if isinstance(ret, sasl.Response):<EOL><INDENT>element = ElementTree.Element(RESPONSE_TAG)<EOL>element.text = ret.encode()<EOL><DEDENT>else:<EOL><INDENT>element = ElementTree.Element(ABORT_TAG)<EOL><DEDENT>stream.write_element(element)<EOL>if isinstance(ret, sasl.Failure):<EOL><INDENT>stream.disconnect()<EOL>raise SASLAuthenticationFailed("<STR_LIT>")<EOL><DEDENT>return True<EOL>

Process incoming <sasl:challenge/> element.

        [initiating entity only]


def _check_authorization(self, properties, stream):

authzid = properties.get("<STR_LIT>")<EOL>if not authzid:<EOL><INDENT>return True<EOL><DEDENT>try:<EOL><INDENT>jid = JID(authzid)<EOL><DEDENT>except ValueError:<EOL><INDENT>return False<EOL><DEDENT>if "<STR_LIT:username>" not in properties:<EOL><INDENT>result = False<EOL><DEDENT>elif jid.local != properties["<STR_LIT:username>"]:<EOL><INDENT>result = False<EOL><DEDENT>elif jid.domain != stream.me.domain:<EOL><INDENT>result = False<EOL><DEDENT>elif jid.resource:<EOL><INDENT>result = False<EOL><DEDENT>else:<EOL><INDENT>result = True<EOL><DEDENT>return result<EOL>

Check authorization id and other properties returned by the
        authentication mechanism.

        [receiving entity only]

        Allow only no authzid or authzid equal to current username@domain

        FIXME: other rules in s2s

        :Parameters:
            - `properties`: data obtained during authentication
        :Types:
            - `properties`: mapping

        :return: `True` if user is authorized to use a provided authzid
        :returntype: `bool`


@stream_element_handler(AUTH_TAG, "<STR_LIT>")<EOL><INDENT>def process_sasl_auth(self, stream, element):<DEDENT>

if self.authenticator:<EOL><INDENT>logger.debug("<STR_LIT>")<EOL>return False<EOL><DEDENT>password_db = self.settings["<STR_LIT>"]<EOL>mechanism = element.get("<STR_LIT>")<EOL>if not mechanism:<EOL><INDENT>stream.send_stream_error("<STR_LIT>")<EOL>raise FatalStreamError("<STR_LIT>")<EOL><DEDENT>stream.auth_method_used = mechanism<EOL>self.authenticator = sasl.server_authenticator_factory(mechanism,<EOL>password_db)<EOL>content = element.text.encode("<STR_LIT>")<EOL>ret = self.authenticator.start(stream.auth_properties,<EOL>a2b_base64(content))<EOL>if isinstance(ret, sasl.Success):<EOL><INDENT>element = ElementTree.Element(SUCCESS_TAG)<EOL>element.text = ret.encode()<EOL><DEDENT>elif isinstance(ret, sasl.Challenge):<EOL><INDENT>element = ElementTree.Element(CHALLENGE_TAG)<EOL>element.text = ret.encode()<EOL><DEDENT>else:<EOL><INDENT>element = ElementTree.Element(FAILURE_TAG)<EOL>ElementTree.SubElement(element, SASL_QNP + ret.reason)<EOL><DEDENT>stream.write_element(element)<EOL>if isinstance(ret, sasl.Success):<EOL><INDENT>self._handle_auth_success(stream, ret)<EOL><DEDENT>elif isinstance(ret, sasl.Failure):<EOL><INDENT>raise SASLAuthenticationFailed("<STR_LIT>"<EOL>.format(ret.reason))<EOL><DEDENT>return True<EOL>

Process incoming <sasl:auth/> element.

        [receiving entity only]


return serialize(self.as_xml())<EOL>

Serialize the stanza into a Unicode XML string.

        :return: serialized element.
        :returntype: `unicode`


<EOL>if element.tag != self.error_qname:<EOL><INDENT>raise ValueError("<STR_LIT>".format(<EOL>element, self.error_qname))<EOL><DEDENT>lang = element.get(XML_LANG_QNAME, None)<EOL>if lang:<EOL><INDENT>self.language = lang<EOL><DEDENT>self.condition = None<EOL>for child in element:<EOL><INDENT>if child.tag.startswith(self.cond_qname_prefix):<EOL><INDENT>if self.condition is not None:<EOL><INDENT>logger.warning("<STR_LIT>")<EOL>continue<EOL><DEDENT>self.condition = deepcopy(child)<EOL><DEDENT>elif child.tag == self.text_qname:<EOL><INDENT>lang = child.get(XML_LANG_QNAME, None)<EOL>if lang:<EOL><INDENT>self.language = lang<EOL><DEDENT>self.text = child.text.strip()<EOL><DEDENT>else:<EOL><INDENT>bad = False<EOL>for prefix in (STREAM_QNP, STANZA_CLIENT_QNP, STANZA_SERVER_QNP,<EOL>STANZA_ERROR_QNP, STREAM_ERROR_QNP):<EOL><INDENT>if child.tag.startswith(prefix):<EOL><INDENT>logger.warning("<STR_LIT>"<EOL>"<STR_LIT>")<EOL>bad = True<EOL>break<EOL><DEDENT><DEDENT>if not bad:<EOL><INDENT>self.custom_condition.append( deepcopy(child) )<EOL><DEDENT><DEDENT><DEDENT>if self.condition is None:<EOL><INDENT>self.condition = ElementTree.Element(self.cond_qname_prefix<EOL>+ "<STR_LIT>")<EOL><DEDENT>if self.condition.tag in OBSOLETE_CONDITIONS:<EOL><INDENT>new_cond_name = OBSOLETE_CONDITIONS[self.condition.tag]<EOL>self.condition = ElementTree.Element(new_cond_name)<EOL><DEDENT>

Initialize an ErrorElement object from an XML element.

        :Parameters:
            - `element`: XML element to be decoded.
        :Types:
            - `element`: :etree:`ElementTree.Element`


ErrorElement._from_xml(self, element)<EOL>error_type = element.get("<STR_LIT:type>")<EOL>if error_type:<EOL><INDENT>self.error_type = error_type<EOL><DEDENT>


result = ElementTree.Element(self.error_qname)<EOL>result.append(deepcopy(self.condition))<EOL>if self.text:<EOL><INDENT>text = ElementTree.SubElement(result, self.text_qname)<EOL>if self.language:<EOL><INDENT>text.set(XML_LANG_QNAME, self.language)<EOL><DEDENT>text.text = self.text<EOL><DEDENT>return result<EOL>

Return the XML error representation.

        :returntype: :etree:`ElementTree.Element`


return self.condition.tag.split("<STR_LIT:}>", <NUM_LIT:1>)[<NUM_LIT:1>]<EOL>

Return the condition name (condition element name without the
        namespace).


def as_xml(self, stanza_namespace = None):

if stanza_namespace:<EOL><INDENT>self.error_qname = "<STR_LIT>".format(stanza_namespace)<EOL>self.text_qname = "<STR_LIT>".format(stanza_namespace)<EOL><DEDENT>result = ErrorElement.as_xml(self)<EOL>result.set("<STR_LIT:type>", self.error_type)<EOL>return result<EOL>

Return the XML error representation.

        :Parameters:
            - `stanza_namespace`: namespace URI of the containing stanza
        :Types:
            - `stanza_namespace`: `unicode`

        :returntype: :etree:`ElementTree.Element`


cond = self.condition_name<EOL>if cond in STREAM_ERRORS:<EOL><INDENT>return STREAM_ERRORS[cond][<NUM_LIT:0>]<EOL><DEDENT>else:<EOL><INDENT>return None<EOL><DEDENT>

Get the standard English message for the error.

        :return: the error message.
        :returntype: `unicode`


if settings is None:<EOL><INDENT>self.settings = XMPPSettings()<EOL><DEDENT>else:<EOL><INDENT>self.settings = settings<EOL><DEDENT>self.stream = None<EOL>self.requested = False<EOL>self.tls_socket = None<EOL>

Initialize the TLS handler.

        :Parameters:
          - `settings`: settings for StartTLS.
        :Types:
          - `settings`: `XMPPSettings`


self.requested = True<EOL>element = ElementTree.Element(STARTTLS_TAG)<EOL>self.stream.write_element(element)<EOL>

Request a TLS-encrypted connection.

        [initiating entity only]


@stream_element_handler(PROCEED_TAG, "<STR_LIT>")<EOL><INDENT>def _process_tls_proceed(self, stream, element):<DEDENT>

<EOL>if not self.requested:<EOL><INDENT>logger.debug("<STR_LIT>".format(element))<EOL>return False<EOL><DEDENT>logger.debug("<STR_LIT>")<EOL>self.requested = False<EOL>self._make_tls_connection()<EOL>return True<EOL>


try:<EOL><INDENT>logger.debug("<STR_LIT>".format(cert))<EOL>if not cert:<EOL><INDENT>logger.warning("<STR_LIT>")<EOL>return False<EOL><DEDENT>if not cert.validated:<EOL><INDENT>logger.warning("<STR_LIT>")<EOL>return False<EOL><DEDENT>srv_type = stream.transport._dst_service <EOL>if cert.verify_server(stream.peer, srv_type):<EOL><INDENT>logger.debug("<STR_LIT>"<EOL>.format(stream.peer))<EOL>return True<EOL><DEDENT>else:<EOL><INDENT>logger.debug("<STR_LIT>"<EOL>.format(stream.peer))<EOL>return False<EOL><DEDENT><DEDENT>except:<EOL><INDENT>logger.exception("<STR_LIT>")<EOL>raise<EOL><DEDENT>

Default certificate verification callback for TLS connections.

        :Parameters:
            - `cert`: certificate information
        :Types:
            - `cert`: `CertificateData`

        :return: computed verification result.


@stream_element_handler(STARTTLS_TAG, "<STR_LIT>")<EOL><INDENT>def _process_tls_starttls(self, stream, element):<DEDENT>

<EOL>_unused, _unused = stream, element<EOL>raise FatalStreamError("<STR_LIT>")<EOL>


@stream_element_handler(FAILURE_TAG, "<STR_LIT>")<EOL><INDENT>def _process_tls_failure(self, stream, element):<DEDENT>

<EOL>_unused, _unused = stream, element<EOL>raise TLSNegotiationFailed("<STR_LIT>")<EOL>


self.logger_ignored.debug(u"<STR_LIT>"<EOL>.format(self.message))<EOL>

Log message via the "pyxmpp.ProtocolError.ignored" logger.


self.logger_reported.debug(u"<STR_LIT>"<EOL>.format(self.message))<EOL>

Log message via the "pyxmpp.ProtocolError.reported" logger.


return self.args[<NUM_LIT:0>]<EOL>

XMPP error name which should be reported


@iq_set_stanza_handler(XMLPayload, SESSION_TAG)<EOL><INDENT>def handle_bind_iq_set(self, stanza):<DEDENT>

<EOL>logger.debug("<STR_LIT>")<EOL>return stanza.make_result_response()<EOL>

Handler <iq type="set"/> for session establishment.


return self.__data_columns.colnames<EOL>

Getter for the columns names of the DataFrame.

:return: returns a list of column names
:rtype: list(str)


self.__data_columns.cbind(**kwargs)<EOL>return self<EOL>

Bind a column to the DataFrame.

:param kwargs: named list of elements you want to add
:type kwargs: keyword tuple
:return: self
:rtype: DataFrame


cols = {}<EOL>for k in self.colnames:<EOL><INDENT>if k in args:<EOL><INDENT>cols[str(k)] =self.__data_columns[self.colnames.index(k)].values<EOL><DEDENT><DEDENT>return DataFrame(**cols)<EOL>

Subset only some of the columns of the DataFrame.

:param args: list of column names of the object that should be subsetted
:type args: tuple
:return: returns dataframe with only the columns you selected
:rtype: DataFrame


return self.__data_columns.which_colnames(*args)<EOL>

Computes the indexes of the columns in the DataFrame.

:param args: list of column names
:type args: tuple
:return: returns a list of indexes
:rtype: list(int)


def modify(self, clazz, new_col, *args):

if is_callable(clazz) and not is_none(new_col) and has_elements(*args):<EOL><INDENT>return self.__do_modify(clazz, new_col, *args)<EOL><DEDENT>

Modify some columns (i.e. apply a function) and add the
result to the table.

:param clazz: name of a class that extends class Callable
:type clazz: class
:param new_col: name of the new column
:type new_col: str
:param args: list of column names of the object that
function should be applied to
:type args: tuple
:return: returns a new dataframe object with the modiefied values,
 i.e. the new column
:rtype: DataFrame


def __init__(self, piping_method, *args):

self.__piping_method = piping_method<EOL>if args and isinstance(args[<NUM_LIT:0>], dataframe.DataFrame):<EOL><INDENT>raise PipingException("<STR_LIT>")<EOL><DEDENT>elif not args:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>else:<EOL><INDENT>self.__args = args<EOL><DEDENT>

Constructor for chainable. Takes a tuple which is either a dataframe
and column names to group by or only the column names

:param args: tuple of params


return self.__colname<EOL>

Getter for the column name.

:return: returns the column name


if args and isinstance(args[<NUM_LIT:0>], dataframe.DataFrame):<EOL><INDENT>return args[<NUM_LIT:0>].subset(*args[<NUM_LIT:1>:])<EOL><DEDENT>elif not args:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>else:<EOL><INDENT>return pipeable.Pipeable(pipeable.PipingMethod.SUBSET, *args)<EOL><DEDENT>

Pipeable subsetting method.

Takes either
 - a dataframe and a tuple of arguments required for subsetting,
 - a tuple of arguments if a dataframe has already been piped into.

:Example:

subset(dataframe, "column")

:Example:

dataframe >> subset("column")

:param args: tuple of arguments
:type args: tuple
:return: returns a dataframe object
:rtype: DataFrame


if args and isinstance(args[<NUM_LIT:0>], dataframe.DataFrame):<EOL><INDENT>return args[<NUM_LIT:0>].aggregate(args[<NUM_LIT:1>], args[<NUM_LIT:2>], *args[<NUM_LIT:3>:])<EOL><DEDENT>elif not args:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>else:<EOL><INDENT>return pipeable.Pipeable(pipeable.PipingMethod.AGGREGATE, *args)<EOL><DEDENT>

Pipeable aggregation method.

Takes either
 - a dataframe and a tuple of arguments required for aggregation,
 - a tuple of arguments if a dataframe has already been piped into.
In any case one argument has to be a class that extends callable.

:Example:

aggregate(dataframe, Function, "new_col_name", "old_col_name")

:Example:

dataframe >> aggregate(Function, "new_col_name", "old_col_name")

:param args: tuple of arguments
:type args: tuple
:return: returns a dataframe object
:rtype: DataFrame


curr_node = self.__root<EOL>return self.__traverse(curr_node, <NUM_LIT:0>,  *args)<EOL>

Find a node in the tree. If the node is not found it is added first and then returned.

:param args: a tuple
:return: returns the node


if isinstance(item, str) and item in self.__data_columns.colnames:<EOL><INDENT>return self.__data_columns[self.__data_columns.colnames.index(item)]<EOL><DEDENT>raise TypeError("<STR_LIT>" +<EOL>"<STR_LIT>")<EOL>

Getter method for DataFrame. Returns the column with name item.

:param item: the name of a column
:type item: str
:return: returns a column from the DataFrame
:rtype: DataFrameColumn


return self.__grouping_colnames<EOL>

Getter for the grouping column names.

:return: returns the grouping column names


pass<EOL>

Call method. Is used when object is called like this: object()

:param args: tuple of columns
:type args: tuple
:return: returns a list/scalar
:rtype: list(any)/scalar


return self.__grouping.groups<EOL>

Getter for all groups.

:return: returns the groups
:rtype: list(DataFrameGroup)


return self.__grouping.ungroup().colnames<EOL>

Getter for the column names of the DataFrame.

:return: returns column names
:rtype: list(str)


args = list(args)<EOL>args.extend([x for x in<EOL>self.__grouping.grouping_colnames if x not in args])<EOL>return GroupedDataFrame(self.__grouping.ungroup(), *args)<EOL>

Group the DataFrame into row-subsets.

:param args: list of column names taht should be used for grouping
:type args: tuple
:return: returns a dataframe that has grouping information
:rtype: GroupedDataFrame


return self.__grouping.ungroup()<EOL>

Undo the grouping and return the DataFrame.

:return: returns the original DataFrame
:rtype: DataFrame


if is_callable(clazz)and not is_none(new_col)and has_elements(*args)and is_disjoint(self.__grouping.grouping_colnames,<EOL>args,<EOL>__DISJOINT_SETS_ERROR__):<EOL><INDENT>return self.__do_modify(clazz, new_col, *args)<EOL><DEDENT>

Modify some columns (i.e. apply a function)
 and add the result to the table.

:param clazz: name of a class that extends class Callable
:type clazz: class
:param new_col: name of the new column
:type new_col: str
:param args: list of column names of the object that
 function should be applied to
:type args: tuple
:return: returns a new GroupedDataFrame object with the modified
  values, i.e. the new column of values
:rtype: GroupedDataFrame


def aggregate(self, clazz, new_col, *args):

if is_callable(clazz)and not is_none(new_col)and has_elements(*args)and is_disjoint(self.__grouping.grouping_colnames,<EOL>args,<EOL>__DISJOINT_SETS_ERROR__):<EOL><INDENT>return self.__do_aggregate(clazz, new_col, *args)<EOL><DEDENT>

Aggregate the rows of each group into a single value.

:param clazz: name of a class that extends class Callable
:type clazz: class
:param new_col: name of the new column
:type new_col: str
:param args: list of column names of the object that
 function should be applied to
:type args: varargs
:return: returns a new dataframe object with the aggregated value
:rtype: DataFrame


return self.__grouping.__str__()<EOL>

ToString method for GroupedDataFrame.

:return: returns the string representation
:rtype: str


if not args:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>return True<EOL>

Check if args has elements.

:param args: a tuple
:return: returns true if args has elements


for elem in set2:<EOL><INDENT>if elem in set1:<EOL><INDENT>raise ValueError(warn)<EOL><DEDENT><DEDENT>return True<EOL>

Checks if elements of set2 are in set1.

:param set1: a set of values
:param set2: a set of values
:param warn: the error message that should be thrown
 when the sets are NOT disjoint
:return: returns true no elements of set2 are in set1


for elem in set2:<EOL><INDENT>if elem not in set1:<EOL><INDENT>raise ValueError(warn)<EOL><DEDENT><DEDENT>return True<EOL>

Checks if all elements from set2 are in set1.

:param set1:  a set of values
:param set2:  a set of values
:param warn: the error message that should be thrown
 when the sets are not containd
:return: returns true if all values of set2 are in set1


if not issubclass(func, dataframe.Callable):<EOL><INDENT>raise TypeError("<STR_LIT>")<EOL><DEDENT>return True<EOL>

Check if a function extends callable.

:param func: the function to be checked
:return: returns true if the function is callable


return self.__dataframe<EOL>

Getter for the normal DataFrame object without grouping information.

:return: returns the ungrouped DataFrame
:rtype: DataFrame


return self.__groups.values()<EOL>

Getter the values of the group dictionary, i.e. the Group objects

:return: returns the groupings of the rows
:rtype: list(DataFrameGroup)


arr = []<EOL>with open(filepath, '<STR_LIT:rb>') as f:<EOL><INDENT>carr = f.read(blosc.MAX_BUFFERSIZE)<EOL>while len(carr) > <NUM_LIT:0>:<EOL><INDENT>arr.append(blosc.decompress(carr))<EOL>carr = f.read(blosc.MAX_BUFFERSIZE)<EOL><DEDENT><DEDENT>return pkl.loads(b"<STR_LIT>".join(arr))<EOL>


return {<EOL>'<STR_LIT>': ['<STR_LIT:U+0020>'.join([<EOL>'<STR_LIT>', '<STR_LIT>', BIBFILE,<EOL>'<STR_LIT>'.format(CITEULIKE_GROUP),<EOL>])],<EOL>'<STR_LIT>': [BIBFILE],<EOL>}<EOL>

Download bibliography from CiteULike group


def sample_states(<EOL>graph, spanning_cluster=True, model='<STR_LIT>', copy_result=True<EOL>):

if model != '<STR_LIT>':<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if spanning_cluster:<EOL><INDENT>auxiliary_node_attributes = nx.get_node_attributes(graph, '<STR_LIT>')<EOL>auxiliary_nodes = auxiliary_node_attributes.keys()<EOL>if not list(auxiliary_nodes):<EOL><INDENT>raise ValueError(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>'<EOL>)<EOL><DEDENT>spanning_sides = list(set(auxiliary_node_attributes.values()))<EOL>if len(spanning_sides) != <NUM_LIT:2>:<EOL><INDENT>raise ValueError(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>'<EOL>)<EOL><DEDENT>auxiliary_edge_attributes = nx.get_edge_attributes(graph, '<STR_LIT>')<EOL><DEDENT>if spanning_cluster:<EOL><INDENT>perc_graph = graph.subgraph(<EOL>[<EOL>node for node in graph.nodes_iter()<EOL>if '<STR_LIT>' not in graph.node[node]<EOL>]<EOL>)<EOL><DEDENT>else:<EOL><INDENT>perc_graph = graph<EOL><DEDENT>perc_edges = perc_graph.edges()<EOL>num_nodes = nx.number_of_nodes(perc_graph)<EOL>num_edges = nx.number_of_edges(perc_graph)<EOL>ret = dict()<EOL>ret['<STR_LIT:n>'] = <NUM_LIT:0><EOL>ret['<STR_LIT:N>'] = num_nodes<EOL>ret['<STR_LIT:M>'] = num_edges<EOL>ret['<STR_LIT>'] = <NUM_LIT:1><EOL>ret['<STR_LIT>'] = np.ones(<NUM_LIT:5>) * (num_nodes - <NUM_LIT:1>)<EOL>if spanning_cluster:<EOL><INDENT>ret['<STR_LIT>'] = False<EOL><DEDENT>if copy_result:<EOL><INDENT>yield copy.deepcopy(ret)<EOL><DEDENT>else:<EOL><INDENT>yield ret<EOL><DEDENT>perm_edges = np.random.permutation(num_edges)<EOL>ds = nx.utils.union_find.UnionFind()<EOL>if spanning_cluster:<EOL><INDENT>ds_spanning = nx.utils.union_find.UnionFind()<EOL>side_roots = dict()<EOL>for side in spanning_sides:<EOL><INDENT>nodes = [<EOL>node for (node, node_side) in auxiliary_node_attributes.items()<EOL>if node_side is side<EOL>]<EOL>ds_spanning.union(*nodes)<EOL>side_roots[side] = ds_spanning[nodes[<NUM_LIT:0>]]<EOL><DEDENT>for (edge, edge_side) in auxiliary_edge_attributes.items():<EOL><INDENT>ds_spanning.union(side_roots[edge_side], *edge)<EOL><DEDENT>side_roots = [<EOL>ds_spanning[side_root] for side_root in side_roots.values()<EOL>]<EOL><DEDENT>max_cluster_root = next(perc_graph.nodes_iter())<EOL>for n in range(num_edges):<EOL><INDENT>ret['<STR_LIT:n>'] = n + <NUM_LIT:1><EOL>edge_index = perm_edges[n]<EOL>edge = perc_edges[edge_index]<EOL>ret['<STR_LIT>'] = edge<EOL>roots = [<EOL>ds[node] for node in edge<EOL>]<EOL>weights = [<EOL>ds.weights[root] for root in roots<EOL>]<EOL>if roots[<NUM_LIT:0>] is not roots[<NUM_LIT:1>]:<EOL><INDENT>ds.union(*roots)<EOL>if spanning_cluster:<EOL><INDENT>ds_spanning.union(*roots)<EOL>ret['<STR_LIT>'] = (<EOL>ds_spanning[side_roots[<NUM_LIT:0>]] == ds_spanning[side_roots[<NUM_LIT:1>]]<EOL>)<EOL><DEDENT>root = ds[edge[<NUM_LIT:0>]]<EOL>weight = ds.weights[root]<EOL>for i in [<NUM_LIT:0>, <NUM_LIT:1>]:<EOL><INDENT>if roots[i] is max_cluster_root:<EOL><INDENT>continue<EOL><DEDENT>ret['<STR_LIT>'] -= weights[i] ** np.arange(<NUM_LIT:5>)<EOL><DEDENT>if max_cluster_root in roots:<EOL><INDENT>max_cluster_root = root<EOL>ret['<STR_LIT>'] = weight<EOL><DEDENT>else:<EOL><INDENT>if ret['<STR_LIT>'] >= weight:<EOL><INDENT>ret['<STR_LIT>'] += weight ** np.arange(<NUM_LIT:5>)<EOL><DEDENT>else:<EOL><INDENT>max_cluster_root = root<EOL>ret['<STR_LIT>'] += ret['<STR_LIT>'] ** np.arange(<NUM_LIT:5>)<EOL>ret['<STR_LIT>'] = weight<EOL><DEDENT><DEDENT><DEDENT>if copy_result:<EOL><INDENT>yield copy.deepcopy(ret)<EOL><DEDENT>else:<EOL><INDENT>yield ret<EOL><DEDENT><DEDENT>

Generate successive sample states of the percolation model

This is a :ref:`generator function <python:tut-generators>` to successively
add one edge at a time from the graph to the percolation model.
At each iteration, it calculates and returns the cluster statistics.

Parameters
----------
graph : networkx.Graph
    The substrate graph on which percolation is to take place

spanning_cluster : bool, optional
    Whether to detect a spanning cluster or not.
    Defaults to ``True``.

model : str, optional
    The percolation model (either ``'bond'`` or ``'site'``).
    Defaults to ``'bond'``.

    .. note:: Other models than ``'bond'`` are not supported yet.

copy_result : bool, optional
    Whether to return a copy or a reference to the result dictionary.
    Defaults to ``True``.

Yields
------
ret : dict
    Cluster statistics

ret['n'] : int
    Number of occupied bonds

ret['N'] : int
    Total number of sites

ret['M'] : int
    Total number of bonds

ret['has_spanning_cluster'] : bool
    ``True`` if there is a spanning cluster, ``False`` otherwise.
    Only exists if `spanning_cluster` argument is set to ``True``.

ret['max_cluster_size'] : int
    Size of the largest cluster (absolute number of sites)

ret['moments'] : 1-D :py:class:`numpy.ndarray` of int
    Array of size ``5``.
    The ``k``-th entry is the ``k``-th raw moment of the (absolute) cluster
    size distribution, with ``k`` ranging from ``0`` to ``4``.

Raises
------
ValueError
    If `model` does not equal ``'bond'``.

ValueError
    If `spanning_cluster` is ``True``, but `graph` does not contain any
    auxiliary nodes to detect spanning clusters.

See also
--------

microcanonical_averages : Evolves multiple sample states in parallel

Notes
-----
Iterating through this generator is a single run of the Newman-Ziff
algorithm. [2]_
The first iteration yields the trivial state with :math:`n = 0` occupied
bonds.

Spanning cluster

    In order to detect a spanning cluster, `graph` needs to contain
    auxiliary nodes and edges, cf. Reference [2]_, Figure 6.
    The auxiliary nodes and edges have the ``'span'`` `attribute
    <http://networkx.github.io/documentation/latest/tutorial/tutorial.html#node-attributes>`_.
    The value is either ``0`` or ``1``, distinguishing the two sides of the
    graph to span.

Raw moments of the cluster size distribution

    The :math:`k`-th raw moment of the (absolute) cluster size distribution
    is :math:`\sum_s' s^k N_s`, where :math:`s` is the cluster size and
    :math:`N_s` is the number of clusters of size :math:`s`. [3]_
    The primed sum :math:`\sum'` signifies that the largest cluster is
    excluded from the sum. [4]_

References
----------
.. [2] Newman, M. E. J. & Ziff, R. M. Fast monte carlo algorithm for site
    or bond percolation. Physical Review E 64, 016706+ (2001),
    `doi:10.1103/physreve.64.016706 <http://dx.doi.org/10.1103/physreve.64.016706>`_.

.. [3] Stauffer, D. & Aharony, A. Introduction to Percolation Theory (Taylor &
   Francis, London, 1994), second edn.

.. [4] Binder, K. & Heermann, D. W. Monte Carlo Simulation in Statistical
   Physics (Springer, Berlin, Heidelberg, 2010),
   `doi:10.1007/978-3-642-03163-2 <http://dx.doi.org/10.1007/978-3-642-03163-2>`_.


ret = dict()<EOL>ret['<STR_LIT>'] = graph<EOL>ret['<STR_LIT>'] = bool(spanning_cluster)<EOL>if spanning_cluster:<EOL><INDENT>spanning_auxiliary_node_attributes = nx.get_node_attributes(<EOL>graph, '<STR_LIT>'<EOL>)<EOL>ret['<STR_LIT>'] = spanning_auxiliary_node_attributes<EOL>auxiliary_nodes = spanning_auxiliary_node_attributes.keys()<EOL>if not list(auxiliary_nodes):<EOL><INDENT>raise ValueError(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>'<EOL>)<EOL><DEDENT>spanning_sides = list(set(spanning_auxiliary_node_attributes.values()))<EOL>if len(spanning_sides) != <NUM_LIT:2>:<EOL><INDENT>raise ValueError(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>'<EOL>)<EOL><DEDENT>ret['<STR_LIT>'] = spanning_sides<EOL>ret['<STR_LIT>'] = nx.get_edge_attributes(<EOL>graph, '<STR_LIT>'<EOL>)<EOL><DEDENT>if spanning_cluster:<EOL><INDENT>perc_graph = graph.subgraph(<EOL>[<EOL>node for node in graph.nodes_iter()<EOL>if '<STR_LIT>' not in graph.node[node]<EOL>]<EOL>)<EOL><DEDENT>else:<EOL><INDENT>perc_graph = graph<EOL><DEDENT>ret['<STR_LIT>'] = perc_graph<EOL>ret['<STR_LIT>'] = nx.number_of_nodes(perc_graph)<EOL>ret['<STR_LIT>'] = nx.number_of_edges(perc_graph)<EOL>return ret<EOL>

Prepare the (internal) percolation graph from a given graph

Helper function to prepare the given graph for spanning cluster detection
(if required).
Basically it strips off the auxiliary nodes and edges again.
It also returns fundamental graph quantitities (number of nodes and edges).

Parameters
----------
graph
spanning_cluster

Returns
-------
ret : tuple


ret = dict()<EOL>for n, microcanonical_average in enumerate(microcanonical_averages):<EOL><INDENT>assert n == microcanonical_average['<STR_LIT:n>']<EOL>if n == <NUM_LIT:0>:<EOL><INDENT>num_edges = microcanonical_average['<STR_LIT:M>']<EOL>num_sites = microcanonical_average['<STR_LIT:N>']<EOL>spanning_cluster = ('<STR_LIT>' in microcanonical_average)<EOL>ret['<STR_LIT>'] = np.empty(num_edges + <NUM_LIT:1>)<EOL>ret['<STR_LIT>'] = np.empty((num_edges + <NUM_LIT:1>, <NUM_LIT:2>))<EOL>if spanning_cluster:<EOL><INDENT>ret['<STR_LIT>'] = np.empty(num_edges + <NUM_LIT:1>)<EOL>ret['<STR_LIT>'] = np.empty((num_edges + <NUM_LIT:1>, <NUM_LIT:2>))<EOL><DEDENT>ret['<STR_LIT>'] = np.empty((<NUM_LIT:5>, num_edges + <NUM_LIT:1>))<EOL>ret['<STR_LIT>'] = np.empty((<NUM_LIT:5>, num_edges + <NUM_LIT:1>, <NUM_LIT:2>))<EOL><DEDENT>ret['<STR_LIT>'][n] = microcanonical_average['<STR_LIT>']<EOL>ret['<STR_LIT>'][n] = (<EOL>microcanonical_average['<STR_LIT>']<EOL>)<EOL>if spanning_cluster:<EOL><INDENT>ret['<STR_LIT>'][n] = (<EOL>microcanonical_average['<STR_LIT>']<EOL>)<EOL>ret['<STR_LIT>'][n] = (<EOL>microcanonical_average['<STR_LIT>']<EOL>)<EOL><DEDENT>ret['<STR_LIT>'][:, n] = microcanonical_average['<STR_LIT>']<EOL>ret['<STR_LIT>'][:, n] = microcanonical_average['<STR_LIT>']<EOL><DEDENT>for key in ret:<EOL><INDENT>if '<STR_LIT>' in key:<EOL><INDENT>continue<EOL><DEDENT>ret[key] /= num_sites<EOL><DEDENT>ret['<STR_LIT:M>'] = num_edges<EOL>ret['<STR_LIT:N>'] = num_sites<EOL>return ret<EOL>

Compile microcanonical averages over all iteration steps into single arrays

Helper function to aggregate the microcanonical averages over all iteration
steps into single arrays for further processing

Parameters
----------

microcanonical_averages : iterable
   Typically, this is the :func:`microcanonical_averages` generator

Returns
-------

ret : dict
   Aggregated cluster statistics

ret['N'] : int
    Total number of sites

ret['M'] : int
    Total number of bonds

ret['spanning_cluster'] : 1-D :py:class:`numpy.ndarray` of float
    The percolation probability:
    The normalized average number of runs that have a spanning cluster.

ret['spanning_cluster_ci'] : 2-D :py:class:`numpy.ndarray` of float, size 2
    The lower and upper bounds of the percolation probability.

ret['max_cluster_size'] : 1-D :py:class:`numpy.ndarray` of float
    The percolation strength:
    Average relative size of the largest cluster

ret['max_cluster_size_ci'] : 2-D :py:class:`numpy.ndarray` of float
    Lower and upper bounds of the normal confidence interval of the
    percolation strength.

ret['moments'] : 2-D :py:class:`numpy.ndarray` of float, shape (5, M + 1)
    Average raw moments of the (relative) cluster size distribution.

ret['moments_ci'] : 3-D :py:class:`numpy.ndarray` of float, shape (5, M + 1, 2)
    Lower and upper bounds of the normal confidence interval of the raw
    moments of the (relative) cluster size distribution.

See Also
--------

microcanonical_averages


ret = dict()<EOL>runs = has_spanning_cluster.size<EOL>k = has_spanning_cluster.sum(dtype=np.float)<EOL>ret['<STR_LIT>'] = (<EOL>(k + <NUM_LIT:1>) / (runs + <NUM_LIT:2>)<EOL>)<EOL>ret['<STR_LIT>'] = scipy.stats.beta.ppf(<EOL>[alpha / <NUM_LIT:2>, <NUM_LIT:1> - alpha / <NUM_LIT:2>], k + <NUM_LIT:1>, runs - k + <NUM_LIT:1><EOL>)<EOL>return ret<EOL>

r'''
    Compute the average number of runs that have a spanning cluster

    Helper function for :func:`microcanonical_averages`

    Parameters
    ----------

    has_spanning_cluster : 1-D :py:class:`numpy.ndarray` of bool
        Each entry is the ``has_spanning_cluster`` field of the output of
        :func:`sample_states`:
        An entry is ``True`` if there is a spanning cluster in that respective
        run, and ``False`` otherwise.

    alpha : float
        Significance level.

    Returns
    -------

    ret : dict
        Spanning cluster statistics

    ret['spanning_cluster'] : float
        The average relative number (Binomial proportion) of runs that have a
        spanning cluster.
        This is the Bayesian point estimate of the posterior mean, with a
        uniform prior.

    ret['spanning_cluster_ci'] : 1-D :py:class:`numpy.ndarray` of float, size 2
        The lower and upper bounds of the Binomial proportion confidence
        interval with uniform prior.

    See Also
    --------

    sample_states : spanning cluster detection

    microcanonical_averages : spanning cluster statistics

    Notes
    -----

    Averages and confidence intervals for Binomial proportions

    As Cameron [8]_ puts it, the normal approximation to the confidence
    interval for a Binomial proportion :math:`p` "suffers a *systematic*
    decline in performance (...) towards extreme values of :math:`p` near
    :math:`0` and :math:`1`, generating binomial [confidence intervals]
    with effective coverage far below the desired level." (see also
    References [6]_ and [7]_).

    A different approach to quantifying uncertainty is Bayesian inference.
    [5]_
    For :math:`n` independent Bernoulli trails with common success
    probability :math:`p`, the *likelihood* to have :math:`k` successes
    given :math:`p` is the binomial distribution

    .. math::

        P(k|p) = \binom{n}{k} p^k (1-p)^{n-k} \equiv B(a,b),

    where :math:`B(a, b)` is the *Beta distribution* with parameters
    :math:`a = k + 1` and :math:`b = n - k + 1`.
    Assuming a uniform prior :math:`P(p) = 1`, the *posterior* is [5]_

    .. math::

        P(p|k) = P(k|p)=B(a,b).

    A point estimate is the posterior mean

    .. math::

        \bar{p} = \frac{k+1}{n+2}

    with the :math:`1 - \alpha` credible interval :math:`(p_l, p_u)` given
    by

    .. math::

        \int_0^{p_l} dp B(a,b) = \int_{p_u}^1 dp B(a,b) = \frac{\alpha}{2}.

    References
    ----------

    .. [5] Wasserman, L. All of Statistics (Springer New York, 2004),
       `doi:10.1007/978-0-387-21736-9 <http://dx.doi.org/10.1007/978-0-387-21736-9>`_.

    .. [6] DasGupta, A., Cai, T. T. & Brown, L. D. Interval Estimation for a
       Binomial Proportion. Statistical Science 16, 101-133 (2001).
       `doi:10.1214/ss/1009213286 <http://dx.doi.org/10.1214/ss/1009213286>`_.

    .. [7] Agresti, A. & Coull, B. A. Approximate is Better than "Exact" for
       Interval Estimation of Binomial Proportions. The American Statistician
       52, 119-126 (1998),
       `doi:10.2307/2685469 <http://dx.doi.org/10.2307/2685469>`_.

    .. [8] Cameron, E. On the Estimation of Confidence Intervals for Binomial
       Population Proportions in Astronomy: The Simplicity and Superiority of
       the Bayesian Approach. Publications of the Astronomical Society of
       Australia 28, 128-139 (2011),
       `doi:10.1071/as10046 <http://dx.doi.org/10.1071/as10046>`_.


num_sites = microcanonical_averages_arrays['<STR_LIT:N>']<EOL>num_edges = microcanonical_averages_arrays['<STR_LIT:M>']<EOL>spanning_cluster = ('<STR_LIT>' in microcanonical_averages_arrays)<EOL>ret = dict()<EOL>ret['<STR_LIT>'] = ps<EOL>ret['<STR_LIT:N>'] = num_sites<EOL>ret['<STR_LIT:M>'] = num_edges<EOL>ret['<STR_LIT>'] = np.empty(ps.size)<EOL>ret['<STR_LIT>'] = np.empty((ps.size, <NUM_LIT:2>))<EOL>if spanning_cluster:<EOL><INDENT>ret['<STR_LIT>'] = np.empty(ps.size)<EOL>ret['<STR_LIT>'] = np.empty((ps.size, <NUM_LIT:2>))<EOL><DEDENT>ret['<STR_LIT>'] = np.empty((<NUM_LIT:5>, ps.size))<EOL>ret['<STR_LIT>'] = np.empty((<NUM_LIT:5>, ps.size, <NUM_LIT:2>))<EOL>for p_index, p in enumerate(ps):<EOL><INDENT>binomials = _binomial_pmf(n=num_edges, p=p)<EOL>for key, value in microcanonical_averages_arrays.items():<EOL><INDENT>if len(key) <= <NUM_LIT:1>:<EOL><INDENT>continue<EOL><DEDENT>if key in ['<STR_LIT>', '<STR_LIT>']:<EOL><INDENT>ret[key][p_index] = np.sum(binomials * value)<EOL><DEDENT>elif key in ['<STR_LIT>', '<STR_LIT>']:<EOL><INDENT>ret[key][p_index] = np.sum(<EOL>np.tile(binomials, (<NUM_LIT:2>, <NUM_LIT:1>)).T * value, axis=<NUM_LIT:0><EOL>)<EOL><DEDENT>elif key == '<STR_LIT>':<EOL><INDENT>ret[key][:, p_index] = np.sum(<EOL>np.tile(binomials, (<NUM_LIT:5>, <NUM_LIT:1>)) * value, axis=<NUM_LIT:1><EOL>)<EOL><DEDENT>elif key == '<STR_LIT>':<EOL><INDENT>ret[key][:, p_index] = np.sum(<EOL>np.rollaxis(np.tile(binomials, (<NUM_LIT:5>, <NUM_LIT:2>, <NUM_LIT:1>)), <NUM_LIT:2>, <NUM_LIT:1>) * value,<EOL>axis=<NUM_LIT:1><EOL>)<EOL><DEDENT>else:<EOL><INDENT>raise NotImplementedError(<EOL>'<STR_LIT>'.format(value.ndim)<EOL>)<EOL><DEDENT><DEDENT><DEDENT>return ret<EOL>

Compute the canonical cluster statistics from microcanonical statistics

This is according to Newman and Ziff, Equation (2).
Note that we also simply average the bounds of the confidence intervals
according to this formula.

Parameters
----------

ps : iterable of float
   Each entry is a probability for which to form the canonical ensemble
   and compute the weighted statistics from the microcanonical statistics

microcanonical_averages_arrays
   Typically the output of :func:`microcanonical_averages_arrays`

Returns
-------

ret : dict
   Canonical ensemble cluster statistics

ret['ps'] : iterable of float
    The parameter `ps`

ret['N'] : int
    Total number of sites

ret['M'] : int
    Total number of bonds

ret['spanning_cluster'] : 1-D :py:class:`numpy.ndarray` of float
    The percolation probability:
    The normalized average number of runs that have a spanning cluster.

ret['spanning_cluster_ci'] : 2-D :py:class:`numpy.ndarray` of float, size 2
    The lower and upper bounds of the percolation probability.

ret['max_cluster_size'] : 1-D :py:class:`numpy.ndarray` of float
    The percolation strength:
    Average relative size of the largest cluster

ret['max_cluster_size_ci'] : 2-D :py:class:`numpy.ndarray` of float
    Lower and upper bounds of the normal confidence interval of the
    percolation strength.

ret['moments'] : 2-D :py:class:`numpy.ndarray` of float, shape (5, M + 1)
    Average raw moments of the (relative) cluster size distribution.

ret['moments_ci'] : 3-D :py:class:`numpy.ndarray` of float, shape (5, M + 1, 2)
    Lower and upper bounds of the normal confidence interval of the raw
    moments of the (relative) cluster size distribution.

See Also
--------

microcanonical_averages

microcanonical_averages_arrays


ret = nx.grid_2d_graph(length + <NUM_LIT:2>, length)<EOL>for i in range(length):<EOL><INDENT>ret.node[(<NUM_LIT:0>, i)]['<STR_LIT>'] = <NUM_LIT:0><EOL>ret[(<NUM_LIT:0>, i)][(<NUM_LIT:1>, i)]['<STR_LIT>'] = <NUM_LIT:0><EOL>ret.node[(length + <NUM_LIT:1>, i)]['<STR_LIT>'] = <NUM_LIT:1><EOL>ret[(length + <NUM_LIT:1>, i)][(length, i)]['<STR_LIT>'] = <NUM_LIT:1><EOL><DEDENT>return ret<EOL>

Generate a square lattice with auxiliary nodes for spanning detection

Parameters
----------

length : int
   Number of nodes in one dimension, excluding the auxiliary nodes.

Returns
-------

networkx.Graph
   A square lattice graph with auxiliary nodes for spanning cluster
   detection

See Also
--------

sample_states : spanning cluster detection


def statistics(<EOL>graph, ps, spanning_cluster=True, model='<STR_LIT>', alpha=alpha_1sigma, runs=<NUM_LIT><EOL>):

my_microcanonical_averages = microcanonical_averages(<EOL>graph=graph, runs=runs, spanning_cluster=spanning_cluster, model=model,<EOL>alpha=alpha<EOL>)<EOL>my_microcanonical_averages_arrays = microcanonical_averages_arrays(<EOL>my_microcanonical_averages<EOL>)<EOL>return canonical_averages(ps, my_microcanonical_averages_arrays)<EOL>

Helper function to compute percolation statistics

See Also
--------

canonical_averages

microcanonical_averages

sample_states


ret = dict()<EOL>runs = moments.shape[<NUM_LIT:0>]<EOL>sqrt_n = np.sqrt(runs)<EOL>moments_sample_mean = moments.mean(axis=<NUM_LIT:0>)<EOL>ret['<STR_LIT>'] = moments_sample_mean<EOL>moments_sample_std = moments.std(axis=<NUM_LIT:0>, ddof=<NUM_LIT:1>)<EOL>ret['<STR_LIT>'] = np.empty((<NUM_LIT:5>, <NUM_LIT:2>))<EOL>for k in range(<NUM_LIT:5>):<EOL><INDENT>if moments_sample_std[k]:<EOL><INDENT>old_settings = np.seterr(all='<STR_LIT>')<EOL>ret['<STR_LIT>'][k] = scipy.stats.t.interval(<EOL><NUM_LIT:1> - alpha,<EOL>df=runs - <NUM_LIT:1>,<EOL>loc=moments_sample_mean[k],<EOL>scale=moments_sample_std[k] / sqrt_n<EOL>)<EOL>np.seterr(**old_settings)<EOL><DEDENT>else:<EOL><INDENT>ret['<STR_LIT>'][k] = (<EOL>moments_sample_mean[k] * np.ones(<NUM_LIT:2>)<EOL>)<EOL><DEDENT><DEDENT>return ret<EOL>

Compute the average moments of the cluster size distributions

Helper function for :func:`microcanonical_averages`

Parameters
----------

moments : 2-D :py:class:`numpy.ndarray` of int
    ``moments.shape[1] == 5`.
    Each array ``moments[r, :]`` is the ``moments`` field of the output of
    :func:`sample_states`:
    The ``k``-th entry is the ``k``-th raw moment of the (absolute) cluster
    size distribution.

alpha: float
    Significance level.

Returns
-------

ret : dict
    Moment statistics

ret['moments'] : 1-D :py:class:`numpy.ndarray` of float, size 5
    The ``k``-th entry is the average ``k``-th raw moment of the (absolute)
    cluster size distribution, with ``k`` ranging from ``0`` to ``4``.

ret['moments_ci'] : 2-D :py:class:`numpy.ndarray` of float, shape (5,2)
    ``ret['moments_ci'][k]`` are the lower and upper bounds of the normal
    confidence interval of the average ``k``-th raw moment of the
    (absolute) cluster size distribution, with ``k`` ranging from ``0`` to
    ``4``.

See Also
--------

sample_states : computation of moments

microcanonical_averages : moment statistics


ret = nx.grid_graph(dim=[int(length + <NUM_LIT:2>)])<EOL>ret.node[<NUM_LIT:0>]['<STR_LIT>'] = <NUM_LIT:0><EOL>ret[<NUM_LIT:0>][<NUM_LIT:1>]['<STR_LIT>'] = <NUM_LIT:0><EOL>ret.node[length + <NUM_LIT:1>]['<STR_LIT>'] = <NUM_LIT:1><EOL>ret[length][length + <NUM_LIT:1>]['<STR_LIT>'] = <NUM_LIT:1><EOL>return ret<EOL>

Generate a linear chain with auxiliary nodes for spanning cluster detection

Parameters
----------

length : int
   Number of nodes in the chain, excluding the auxiliary nodes.

Returns
-------

networkx.Graph
   A linear chain graph with auxiliary nodes for spanning cluster detection

See Also
--------

sample_states : spanning cluster detection


return '<STR_LIT>'.encode('<STR_LIT:utf-8>')<EOL>


@TaskGenerator<EOL>def bond_task(<EOL>perc_graph_result, seeds, ps, convolution_factors_tasks_iterator<EOL>):

Perform a number of runs

The number of runs is the number of seeds

convolution_factors_tasks_iterator needs to be an iterator

We shield the convolution factors tasks from jug value/result mechanism
by supplying an iterator to the list of tasks for lazy evaluation
http://github.com/luispedro/jug/blob/43f0d80a78f418fd3aa2b8705eaf7c4a5175fff7/jug/task.py#L100
http://github.com/luispedro/jug/blob/43f0d80a78f418fd3aa2b8705eaf7c4a5175fff7/jug/task.py#L455


def bond_run(perc_graph_result, seed, ps, convolution_factors_tasks):

microcanonical_statistics = percolate.hpc.bond_microcanonical_statistics(<EOL>seed=seed, **perc_graph_result<EOL>)<EOL>canonical_statistics = np.empty(<EOL>ps.size,<EOL>dtype=percolate.hpc.canonical_statistics_dtype(<EOL>spanning_cluster=SPANNING_CLUSTER,<EOL>)<EOL>)<EOL>for row, convolution_factors_task in zip(<EOL>np.nditer(canonical_statistics, op_flags=['<STR_LIT>']),<EOL>convolution_factors_tasks,<EOL>):<EOL><INDENT>assert not convolution_factors_task.is_loaded()<EOL>convolution_factors_task.load()<EOL>my_convolution_factors = convolution_factors_task.result<EOL>row[...] = percolate.hpc.bond_canonical_statistics(<EOL>microcanonical_statistics=microcanonical_statistics,<EOL>convolution_factors=my_convolution_factors,<EOL>spanning_cluster=SPANNING_CLUSTER,<EOL>)<EOL>convolution_factors_task.unload()<EOL><DEDENT>ret = percolate.hpc.bond_initialize_canonical_averages(<EOL>canonical_statistics=canonical_statistics,<EOL>spanning_cluster=SPANNING_CLUSTER,<EOL>)<EOL>return ret<EOL>

Perform a single run (realization) over all microstates and return the
canonical cluster statistics


fields = list()<EOL>fields.extend([<EOL>('<STR_LIT:n>', '<STR_LIT>'),<EOL>('<STR_LIT>', '<STR_LIT>'),<EOL>])<EOL>if spanning_cluster:<EOL><INDENT>fields.extend([<EOL>('<STR_LIT>', '<STR_LIT:bool>'),<EOL>])<EOL><DEDENT>fields.extend([<EOL>('<STR_LIT>', '<STR_LIT>'),<EOL>('<STR_LIT>', '<STR_LIT>'),<EOL>])<EOL>return _ndarray_dtype(fields)<EOL>

Return the numpy structured array data type for sample states

Helper function

Parameters
----------
spanning_cluster : bool, optional
    Whether to detect a spanning cluster or not.
    Defaults to ``True``.

Returns
-------
ret : list of pairs of str
    A list of tuples of field names and data types to be used as ``dtype``
    argument in numpy ndarray constructors

See Also
--------
http://docs.scipy.org/doc/numpy/user/basics.rec.html
canonical_statistics_dtype


<EOL>spanning_cluster = (<EOL>'<STR_LIT>' in canonical_statistics.dtype.names<EOL>)<EOL>ret = np.empty_like(<EOL>canonical_statistics,<EOL>dtype=canonical_averages_dtype(spanning_cluster=spanning_cluster),<EOL>)<EOL>ret['<STR_LIT>'] = <NUM_LIT:1><EOL>if spanning_cluster:<EOL><INDENT>ret['<STR_LIT>'] = (<EOL>canonical_statistics['<STR_LIT>']<EOL>)<EOL>ret['<STR_LIT>'] = <NUM_LIT:0.0><EOL><DEDENT>ret['<STR_LIT>'] = (<EOL>canonical_statistics['<STR_LIT>']<EOL>)<EOL>ret['<STR_LIT>'] = <NUM_LIT:0.0><EOL>ret['<STR_LIT>'] = canonical_statistics['<STR_LIT>']<EOL>ret['<STR_LIT>'] = <NUM_LIT:0.0><EOL>return ret<EOL>

Initialize the canonical averages from a single-run cluster statistics

Parameters
----------
canonical_statistics : 1-D structured ndarray
    Typically contains the canonical statistics for a range of values
    of the occupation probability ``p``.
    The dtype is the result of `canonical_statistics_dtype`.

Returns
-------
ret : structured ndarray
    The dype is the result of `canonical_averages_dtype`.

ret['number_of_runs'] : 1-D ndarray of int
    Equals ``1`` (initial run).

ret['percolation_probability_mean'] : 1-D array of float
    Equals ``canonical_statistics['percolation_probability']``
    (if ``percolation_probability`` is present)

ret['percolation_probability_m2'] : 1-D array of float
    Each entry is ``0.0``

ret['max_cluster_size_mean'] : 1-D array of float
    Equals ``canonical_statistics['max_cluster_size']``

ret['max_cluster_size_m2'] : 1-D array of float
    Each entry is ``0.0``

ret['moments_mean'] : 2-D array of float
    Equals ``canonical_statistics['moments']``

ret['moments_m2'] : 2-D array of float
    Each entry is ``0.0``

See Also
--------
canonical_averages_dtype
bond_canonical_statistics


def finalize_canonical_averages(<EOL>number_of_nodes, ps, canonical_averages, alpha,<EOL>):

spanning_cluster = (<EOL>(<EOL>'<STR_LIT>' in<EOL>canonical_averages.dtype.names<EOL>) and<EOL>'<STR_LIT>' in canonical_averages.dtype.names<EOL>)<EOL>ret = np.empty_like(<EOL>canonical_averages,<EOL>dtype=finalized_canonical_averages_dtype(<EOL>spanning_cluster=spanning_cluster<EOL>),<EOL>)<EOL>n = canonical_averages['<STR_LIT>']<EOL>sqrt_n = np.sqrt(canonical_averages['<STR_LIT>'])<EOL>ret['<STR_LIT>'] = n<EOL>ret['<STR_LIT:p>'] = ps<EOL>ret['<STR_LIT>'] = alpha<EOL>def _transform(<EOL>original_key, final_key=None, normalize=False, transpose=False,<EOL>):<EOL><INDENT>if final_key is None:<EOL><INDENT>final_key = original_key<EOL><DEDENT>keys_mean = [<EOL>'<STR_LIT>'.format(key)<EOL>for key in [original_key, final_key]<EOL>]<EOL>keys_std = [<EOL>'<STR_LIT>'.format(original_key),<EOL>'<STR_LIT>'.format(final_key),<EOL>]<EOL>key_ci = '<STR_LIT>'.format(final_key)<EOL>ret[keys_mean[<NUM_LIT:1>]] = canonical_averages[keys_mean[<NUM_LIT:0>]]<EOL>if normalize:<EOL><INDENT>ret[keys_mean[<NUM_LIT:1>]] /= number_of_nodes<EOL><DEDENT>array = canonical_averages[keys_std[<NUM_LIT:0>]]<EOL>result = np.sqrt(<EOL>(array.T if transpose else array) / (n - <NUM_LIT:1>)<EOL>)<EOL>ret[keys_std[<NUM_LIT:1>]] = (<EOL>result.T if transpose else result<EOL>)<EOL>if normalize:<EOL><INDENT>ret[keys_std[<NUM_LIT:1>]] /= number_of_nodes<EOL><DEDENT>array = ret[keys_std[<NUM_LIT:1>]]<EOL>scale = (array.T if transpose else array) / sqrt_n<EOL>array = ret[keys_mean[<NUM_LIT:1>]]<EOL>mean = (array.T if transpose else array)<EOL>result = scipy.stats.t.interval(<EOL><NUM_LIT:1> - alpha,<EOL>df=n - <NUM_LIT:1>,<EOL>loc=mean,<EOL>scale=scale,<EOL>)<EOL>(<EOL>ret[key_ci][..., <NUM_LIT:0>], ret[key_ci][..., <NUM_LIT:1>]<EOL>) = ([my_array.T for my_array in result] if transpose else result)<EOL><DEDENT>if spanning_cluster:<EOL><INDENT>_transform('<STR_LIT>')<EOL><DEDENT>_transform('<STR_LIT>', '<STR_LIT>', normalize=True)<EOL>_transform('<STR_LIT>', normalize=True, transpose=True)<EOL>return ret<EOL>


Evolve a single run over all microstates (bond occupation numbers)

Return the cluster statistics for each microstate

Parameters
----------
perc_graph : networkx.Graph
    The substrate graph on which percolation is to take place

num_nodes : int
    Number ``N`` of sites in the graph

num_edges : int
    Number ``M`` of bonds in the graph

seed : {None, int, array_like}
    Random seed initializing the pseudo-random number generator.
    Piped through to `numpy.random.RandomState` constructor.

spanning_cluster : bool, optional
    Whether to detect a spanning cluster or not.
    Defaults to ``True``.

auxiliary_node_attributes : optional
    Value of ``networkx.get_node_attributes(graph, 'span')``

auxiliary_edge_attributes : optional
    Value of ``networkx.get_edge_attributes(graph, 'span')``

spanning_sides : list, optional
    List of keys (attribute values) of the two sides of the auxiliary
    nodes.
    Return value of ``list(set(auxiliary_node_attributes.values()))``

Returns
-------
ret : ndarray of size ``num_edges + 1``
    Structured array with dtype ``dtype=[('has_spanning_cluster', 'bool'),
    ('max_cluster_size', 'uint32'), ('moments', 'uint64', 5)]``

ret['n'] : ndarray of int
    The number of bonds added at the particular iteration

ret['edge'] : ndarray of int
    The index of the edge added at the particular iteration.
    Note that ``ret['edge'][0]`` is undefined!

ret['has_spanning_cluster'] : ndarray of bool
    ``True`` if there is a spanning cluster, ``False`` otherwise.
    Only exists if `spanning_cluster` argument is set to ``True``.

ret['max_cluster_size'] : int
    Size of the largest cluster (absolute number of sites)

ret['moments'] : 2-D :py:class:`numpy.ndarray` of int
    Array of shape ``(num_edges + 1, 5)``.
    The ``k``-th entry is the ``k``-th raw moment of the (absolute) cluster
    size distribution, with ``k`` ranging from ``0`` to ``4``.

See also
--------

bond_sample_states
microcanonical_statistics_dtype

numpy.random.RandomState