Instruction:
Can you create a Python 3 function that
sets the order of the elements in the order of the elements in the SplitPiece a and b.

Response:
def set_order_by_clip(self, a, b):
        '''
        Determine which SplitPiece is the leftmost based
        on the side of the longest clipping operation
        '''
        if self.is_left_clip(a.cigar):
            self.query_left = b
            self.query_right = a
        else:
            self.query_left = a
            self.query_right = b


Instruction:
Can you tell what is the following Python 3 function doing
def is_left_clip(self, cigar):
        '''
        whether the left side of the read (w/ respect to reference) is clipped.
        Clipping side is determined as the side with the longest clip.
        Adjacent clipping operations are not considered
        '''
        left_tuple = cigar[0]
        right_tuple = cigar[-1]
        left_clipped = self.is_clip_op(left_tuple[0])
        right_clipped = self.is_clip_op(right_tuple[0])

        return (left_clipped and not right_clipped) or (left_clipped and right_clipped and left_tuple[1] > right_tuple[1])

Response: Return True if the left side of the read is clipped.


Instruction:
Write a Python 3 script to
check request is streaming request or not

Response:
def _is_streaming_request(self):
        """check request is stream request or not"""
        arg2 = self.argstreams[1]
        arg3 = self.argstreams[2]
        return not (isinstance(arg2, InMemStream) and
                    isinstance(arg3, InMemStream) and
                    ((arg2.auto_close and arg3.auto_close) or (
                        arg2.state == StreamState.completed and
                        arg3.state == StreamState.completed)))


Instruction:
Write a Python 3 script for
returning True if we should retry on an error

Response:
def should_retry_on_error(self, error):
        """rules for retry

        :param error:
            ProtocolException that returns from Server
        """

        if self.is_streaming_request:
            # not retry for streaming request
            return False

        retry_flag = self.headers.get('re', retry.DEFAULT)

        if retry_flag == retry.NEVER:
            return False

        if isinstance(error, StreamClosedError):
            return True

        if error.code in [ErrorCode.bad_request, ErrorCode.cancelled,
                          ErrorCode.unhealthy]:
            return False
        elif error.code in [ErrorCode.busy, ErrorCode.declined]:
            return True
        elif error.code is ErrorCode.timeout:
            return retry_flag is not retry.CONNECTION_ERROR
        elif error.code in [ErrorCode.network_error,
                            ErrorCode.fatal,
                            ErrorCode.unexpected]:
            return retry_flag is not retry.TIMEOUT
        else:
            return False


Instruction:
Explain what the following Python 3 code does
def client_for(service, service_module, thrift_service_name=None):
    assert service_module, 'service_module is required'

    service = service or ''  # may be blank for non-hyperbahn use cases

    if not thrift_service_name:
        thrift_service_name = service_module.__name__.rsplit('.', 1)[-1]

    method_names = get_service_methods(service_module.Iface)

    def init(
        self,
        tchannel,
        hostport=None,
        trace=False,
        protocol_headers=None,
    ):
        self.async_thrift = self.__async_client_class__(
            tchannel=tchannel,
            hostport=hostport,
            trace=trace,
            protocol_headers=protocol_headers,
        )
        self.threadloop = tchannel._threadloop

    init.__name__ = '__init__'

    methods = {
        '__init__': init,
        '__async_client_class__': async_client_for(
            service=service,
            service_module=service_module,
            thrift_service_name=thrift_service_name,
        )
    }

    methods.update({
        method_name: generate_method(method_name)
        for method_name in method_names
    })

    return type(thrift_service_name + 'Client', (object,), methods)

Response: Build a synchronous client class for the given Thrift service.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def generate_method(method_name):

    def call(self, *args, **kwargs):
        """Forward RPC call to TChannelSyncClient

        :return concurrent.futures.Future:
        """
        if not self.threadloop.is_ready():
            self.threadloop.start()

        return self.threadloop.submit(
            getattr(self.async_thrift, method_name), *args, **kwargs
        )

    return call

Response: Generates a method that invokes the given method using the provided Thrift service.


Instruction:
Can you generate the documentation for the following Python 3 function
def read_full(stream):
    assert stream, "stream is required"

    chunks = []
    chunk = yield stream.read()

    while chunk:
        chunks.append(chunk)
        chunk = yield stream.read()

    raise tornado.gen.Return(b''.join(chunks))

Response: Read the full contents of the given stream into memory.


Instruction:
Given the following Python 3 function, write the documentation
def maybe_stream(s):
    if isinstance(s, Stream):
        return s

    if s is None:
        stream = InMemStream()
        stream.close()  # we don't intend to write anything
        return stream

    if isinstance(s, unicode):
        s = s.encode('utf-8')
    if isinstance(s, bytearray):
        s = bytes(s)

    if isinstance(s, bytes):
        stream = InMemStream(s)
        stream.close()  # we don't intend to write anything
        return stream

    # s may still conform to the Stream interface. Yay duck typing.
    return s

Response: Ensure that the given argument is a stream.


Instruction:
Can you generate the documentation for the following Python 3 function
def build_raw_error_message(protocol_exception):
    message = ErrorMessage(
        id=protocol_exception.id,
        code=protocol_exception.code,
        tracing=protocol_exception.tracing,
        description=protocol_exception.description,
    )

    return message

Response: build a raw error message based on an error object


Instruction:
Implement a Python 3 function for
building protocol level message based on request and args.

Response:
def build_raw_request_message(self, request, args, is_completed=False):
        """build protocol level message based on request and args.

        request object contains meta information about outgoing request.
        args are the currently chunk data from argstreams
        is_completed tells the flags of the message

        :param request: Request
        :param args: array of arg streams
        :param is_completed: message flags
        :return: CallRequestMessage/CallRequestContinueMessage
        """
        request.flags = FlagsType.none if is_completed else FlagsType.fragment

        # TODO decide what need to pass from request
        if request.state == StreamState.init:
            message = CallRequestMessage(
                flags=request.flags,
                ttl=request.ttl * 1000,
                tracing=request.tracing,
                service=request.service,
                headers=request.headers,
                checksum=request.checksum,
                args=args
            )
            request.state = (StreamState.completed if is_completed
                             else StreamState.streaming)
        elif request.state == StreamState.streaming:
            message = CallRequestContinueMessage(
                flags=request.flags,
                checksum=request.checksum,
                args=args
            )
            request.state = (StreamState.completed if is_completed
                             else StreamState.streaming)

        message.id = request.id
        return message


Instruction:
Create a Python 3 function for
building protocol level message based on response and args.

Response:
def build_raw_response_message(self, response, args, is_completed=False):
        """build protocol level message based on response and args.

        response object contains meta information about outgoing response.
        args are the currently chunk data from argstreams
        is_completed tells the flags of the message

        :param response: Response
        :param args: array of arg streams
        :param is_completed: message flags
        :return: CallResponseMessage/CallResponseContinueMessage
        """
        response.flags = FlagsType.none if is_completed else FlagsType.fragment

        # TODO decide what need to pass from request
        if response.state == StreamState.init:
            message = CallResponseMessage(
                flags=response.flags,
                code=response.code,
                tracing=response.tracing,
                headers=response.headers,
                checksum=response.checksum,
                args=args
            )
            response.state = (StreamState.completed if is_completed
                              else StreamState.streaming)
        elif response.state == StreamState.streaming:
            message = CallResponseContinueMessage(
                flags=response.flags,
                checksum=response.checksum,
                args=args
            )
            response.state = (StreamState.completed if is_completed
                              else StreamState.streaming)

        message.id = response.id
        return message


Instruction:
Write a Python 3 function for
building inbound request object from protocol level message info.

Response:
def build_request(self, message):
        """Build inbound request object from protocol level message info.

        It is allowed to take incompleted CallRequestMessage. Therefore the
        created request may not contain whole three arguments.

        :param message: CallRequestMessage
        :return: request object
        """

        args = self.prepare_args(message)

        # TODO decide what to pass to Request from message
        req = Request(
            flags=message.flags,
            ttl=message.ttl / 1000.0,
            tracing=message.tracing,
            service=message.service,
            headers=message.headers,
            checksum=message.checksum,
            argstreams=args,
            id=message.id,
        )
        return req


Instruction:
Write a Python 3 function for
building a Response object from a protocol level message info .

Response:
def build_response(self, message):
        """Build response object from protocol level message info

        It is allowed to take incompleted CallResponseMessage. Therefore the
        created request may not contain whole three arguments.

        :param message: CallResponseMessage
        :return: response object
        """

        args = self.prepare_args(message)

        # TODO decide what to pass to Response from message
        res = Response(
            flags=message.flags,
            code=message.code,
            headers=message.headers,
            checksum=message.checksum,
            argstreams=args,
            id=message.id,
        )
        return res


Instruction:
How would you implement a function in Python 3 that
builds the next complete message based on the incoming message.

Response:
def build(self, message):
        """buffer all the streaming messages based on the
        message id. Reconstruct all fragments together.

        :param message:
            incoming message
        :return: next complete message or None if streaming
            is not done
        """
        context = None

        if message.message_type in [Types.CALL_REQ,
                                    Types.CALL_RES]:
            self.verify_message(message)

            context = self.build_context(message)
            # streaming message
            if message.flags == common.FlagsType.fragment:
                self.message_buffer[message.id] = context

            # find the incompleted stream
            num = 0
            for i, arg in enumerate(context.argstreams):
                if arg.state != StreamState.completed:
                    num = i
                    break

            self.close_argstream(context, num)
            return context

        elif message.message_type in [Types.CALL_REQ_CONTINUE,
                                      Types.CALL_RES_CONTINUE]:
            context = self.message_buffer.get(message.id)
            if context is None:
                # missing call msg before continue msg
                raise FatalProtocolError(
                    "missing call message after receiving continue message",
                    message.id,
                )

            # find the incompleted stream
            dst = 0
            for i, arg in enumerate(context.argstreams):
                if arg.state != StreamState.completed:
                    dst = i
                    break

            try:
                self.verify_message(message)
            except InvalidChecksumError as e:
                context.argstreams[dst].set_exception(e)
                raise

            src = 0
            while src < len(message.args):
                context.argstreams[dst].write(message.args[src])
                dst += 1
                src += 1

            if message.flags != FlagsType.fragment:
                # get last fragment. mark it as completed
                assert (len(context.argstreams) ==
                        CallContinueMessage.max_args_num)
                self.message_buffer.pop(message.id, None)
                context.flags = FlagsType.none

            self.close_argstream(context, dst - 1)
            return None
        elif message.message_type == Types.ERROR:
            context = self.message_buffer.pop(message.id, None)
            if context is None:
                log.info('Unconsumed error %s', message)
                return None
            else:
                error = TChannelError.from_code(
                    message.code,
                    description=message.description,
                    tracing=context.tracing,
                )

                context.set_exception(error)
                return error
        else:
            return message


Instruction:
How would you code a function in Python 3 to
fragment a message based on max payload size

Response:
def fragment(self, message):
        """Fragment message based on max payload size

        note: if the message doesn't need to fragment,
        it will return a list which only contains original
        message itself.

        :param message: raw message
        :return: list of messages whose sizes <= max
            payload size
        """
        if message.message_type in [Types.CALL_RES,
                                    Types.CALL_REQ,
                                    Types.CALL_REQ_CONTINUE,
                                    Types.CALL_RES_CONTINUE]:
            rw = RW[message.message_type]
            payload_space = (common.MAX_PAYLOAD_SIZE -
                             rw.length_no_args(message))
            # split a call/request message into an array
            # with a call/request message and {0~n} continue
            # message
            fragment_msg = message.fragment(payload_space)
            self.generate_checksum(message)

            yield message
            while fragment_msg is not None:
                message = fragment_msg
                rw = RW[message.message_type]
                payload_space = (common.MAX_PAYLOAD_SIZE -
                                 rw.length_no_args(message))
                fragment_msg = message.fragment(payload_space)
                self.generate_checksum(message)
                yield message
        else:
            yield message


Instruction:
Can you generate a brief explanation for the following Python 3 code
def verify_message(self, message):
        if verify_checksum(
                message,
                self.in_checksum.get(message.id, 0),
        ):
            self.in_checksum[message.id] = message.checksum[1]

            if message.flags == FlagsType.none:
                self.in_checksum.pop(message.id)
        else:
            self.in_checksum.pop(message.id, None)
            raise InvalidChecksumError(
                description="Checksum does not match!",
                id=message.id,
            )

Response: Verify the checksum of the message.


Instruction:
Create a Python 3 function to
build a ReadWriter from a list of ReadWriters in - order.

Response:
def chain(*rws):
    """Build a ReadWriter from the given list of ReadWriters.

    .. code-block:: python

        chain(
            number(1),
            number(8),
            len_prefixed_string(number(2)),
        )  # == n1:1 n2:8 s~2

    Reads/writes from the given ReadWriters in-order. Returns lists of values
    in the same order as the ReadWriters.

    :param rws:
        One or more ReadWriters
    """
    assert rws is not None
    if len(rws) == 1 and isinstance(rws[0], list):
        # In case someone does chain([l0, l1, ...])
        rws = rws[0]
    return ChainReadWriter(rws)


Instruction:
Write a Python 3 function that can
read the given number of bytes from the given stream.

Response:
def take(self, stream, num):
        """Read the given number of bytes from the stream.

        :param stream:
            stream to read from
        :param num:
            number of bytes to read
        :raises ReadError:
            if the stream did not yield the exact number of bytes expected
        """
        s = stream.read(num)
        slen = len(s)
        if slen != num:
            raise ReadError(
                "Expected %d bytes but got %d bytes." % (num, slen)
            )
        return s


Instruction:
Given the following Python 3 function, write the documentation
def get_service_methods(iface):
    methods = inspect.getmembers(iface, predicate=inspect.ismethod)

    return set(
        name for (name, method) in methods if not name.startswith('__')
    )

Response: Get a list of methods defined in the Thrift - generated interface for a Thrift service.


Instruction:
Write a Python 3 function that can
warn every time a fn is called.

Response:
def deprecated(message):
    """Warn every time a fn is called."""
    def decorator(fn):
        @functools.wraps(fn)
        def new_fn(*args, **kwargs):
            deprecate(message)
            return fn(*args, **kwargs)
        return new_fn
    return decorator


Instruction:
Explain what the following Python 3 code does
def load(path, service=None, hostport=None, module_name=None):
    # TODO replace with more specific exceptions
    # assert service, 'service is required'
    # assert path, 'path is required'

    # Backwards compatibility for callers passing in service name as first arg.
    if not path.endswith('.thrift'):
        service, path = path, service

    module = thriftrw.load(path=path, name=module_name)
    return TChannelThriftModule(service, module, hostport)

Response: Loads the Thrift file at the specified path and returns a Python module containing the result of the load.


Instruction:
Make a summary of the following Python 3 code
def register(dispatcher, service, handler=None, method=None):

    def decorator(method, handler):
        if not method:
            method = handler.__name__

        function = getattr(service, method, None)
        assert function, (
            'Service "%s" does not define method "%s"' % (service.name, method)
        )
        assert not function.oneway

        dispatcher.register(
            function.endpoint,
            build_handler(function, handler),
            ThriftRWSerializer(service._module, function._request_cls),
            ThriftRWSerializer(service._module, function._response_cls),
        )
        return handler

    if handler is None:
        return partial(decorator, method)
    else:
        return decorator(method, handler)

Response: Decorator for registering a Thrift function.


Instruction:
Make a summary of the following Python 3 code
def interface_ip(interface):
    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    return socket.inet_ntoa(
        fcntl.ioctl(
            sock.fileno(), 0x8915, struct.pack('256s', interface[:15])
        )[20:24]
    )

Response: Determine the IP assigned to us by the given network interface.


Instruction:
Create a Python 3 function for
getting the local network IP of this machine

Response:
def local_ip():
    """Get the local network IP of this machine"""
    ip = socket.gethostbyname(socket.gethostname())
    if ip.startswith('127.'):
        # Check eth0, eth1, eth2, en0, ...
        interfaces = [
            i + str(n) for i in ("eth", "en", "wlan") for n in xrange(3)
        ]  # :(
        for interface in interfaces:
            try:
                ip = interface_ip(interface)
                break
            except IOError:
                pass
    return ip


Instruction:
Can you write a function in Python 3 where it
builds a client class for the given Thrift service.

Response:
def client_for(service, service_module, thrift_service_name=None):
    """Build a client class for the given Thrift service.

    The generated class accepts a TChannel and an optional hostport as
    initialization arguments.

    Given ``CommentService`` defined in ``comment.thrift`` and registered with
    Hyperbahn under the name "comment", here's how this may be used:

    .. code-block:: python

        from comment import CommentService

        CommentServiceClient = client_for("comment", CommentService)

        @gen.coroutine
        def post_comment(articleId, msg, hostport=None):
            client = CommentServiceClient(tchannel, hostport)
            yield client.postComment(articleId, CommentService.Comment(msg))

    :param service:
        Name of the Hyperbahn service being called. This is the name with
        which the service registered with Hyperbahn.
    :param service_module:
        The Thrift-generated module for that service. This usually has the
        same name as defined for the service in the IDL.
    :param thrift_service_name:
        If the Thrift service has a different name than its module, use this
        parameter to specify it.
    :returns:
        An object with the same interface as the service that uses the given
        TChannel to call the service.
    """
    assert service_module, 'service_module is required'
    service = service or ''  # may be blank for non-hyperbahn use cases
    if not thrift_service_name:
        thrift_service_name = service_module.__name__.rsplit('.', 1)[-1]

    method_names = get_service_methods(service_module.Iface)

    def new(cls, tchannel, hostport=None, trace=False, protocol_headers=None):
        """
        :param tchannel:
            TChannel through which the requests will be sent.
        :param hostport:
            Address of the machine to which the requests will be sent, or None
            if the TChannel will do peer selection on a per-request basis.
        :param trace:
            Whether tracing is enabled.
        :param protocol_headers:
            Protocol-level headers to send with the request.
        """
        protocol_headers = protocol_headers or {}
        protocol_headers['as'] = 'thrift'
        return _ClientBase.__new__(
            cls, tchannel, hostport, service, trace, protocol_headers
        )

    new.__name__ = '__new__'
    methods = {'__new__': new}

    for method_name in method_names:
        methods[method_name] = generate_method(
            service_module, thrift_service_name, method_name
        )

    return type(thrift_service_name + 'Client', (_ClientBase,), methods)


Instruction:
How would you implement a function in Python 3 that
generates a method for the given Thrift service.

Response:
def generate_method(service_module, service_name, method_name):
    """Generate a method for the given Thrift service.

    :param service_module:
        Thrift-generated service module
    :param service_name:
        Name of the Thrift service
    :param method_name:
        Method being called
    """
    assert service_module
    assert service_name
    assert method_name

    args_type = getattr(service_module, method_name + '_args')
    result_type = getattr(service_module, method_name + '_result', None)
    serializer = ThriftSerializer(result_type)
    # oneway not currently supported
    # TODO - write test for this
    if result_type is None:
        def not_supported(self, *args, **kwags):
            raise OneWayNotSupportedError(
                'TChannel+Thrift does not currently support oneway procedues'
            )
        return not_supported

    result_spec = result_type.thrift_spec
    # result_spec is a tuple of tuples in the form:
    #
    #   (fieldId, fieldType, fieldName, ...)
    #
    # Where "..." is other information we don't care about right now.
    #
    # result_spec will be empty if there is no return value or exception for
    # the method.
    #
    # Its first element, with field ID 0, contains the spec for the return
    # value. It is None if the result type is void but the method may still
    # throw exceptions.
    #
    # Elements after the first one are specs for the exceptions.

    endpoint = '%s::%s' % (service_name, method_name)

    @gen.coroutine
    def send(self, *args, **kwargs):
        params = inspect.getcallargs(
            getattr(service_module.Iface, method_name), self, *args, **kwargs
        )
        params.pop('self')  # self is already known

        # $methodName_args is the implicit struct containing the various
        # method parameters.
        call_args = args_type()
        for name, value in params.items():
            setattr(call_args, name, value)

        tracer = tracing.ClientTracer(channel=self.tchannel)
        span, headers = tracer.start_span(
            service=service_name, endpoint=method_name, headers={}
        )

        body = serializer.serialize_body(call_args)
        header = serializer.serialize_header(headers)

        # Glue for old API.
        if hasattr(self.tchannel, 'request'):
            tracing.apply_trace_flag(span, self.trace, True)
            with span:
                response = yield self.tchannel.request(
                    hostport=self.hostport, service=self.service
                ).send(
                    arg1=endpoint,
                    arg2=header,
                    arg3=body,  # body
                    headers=self.protocol_headers,
                )
                body = yield response.get_body()
        else:
            with span:
                response = yield self.tchannel.call(
                    scheme=schemes.THRIFT,
                    service=self.service,
                    arg1=endpoint,
                    arg2=header,
                    arg3=body,
                    hostport=self.hostport,
                    trace=self.trace,
                    tracing_span=span
                    # TODO: Need to handle these!
                    # headers=self.protocol_headers,
                )
                body = response.body

        call_result = serializer.deserialize_body(body)

        if not result_spec:
            # void return type and no exceptions allowed
            raise gen.Return(None)

        for exc_spec in result_spec[1:]:
            # May have failed with an exception
            exc = getattr(call_result, exc_spec[2])
            if exc is not None:
                raise exc

        if result_spec[0]:
            # Non-void return type. Return the result.
            success = getattr(call_result, result_spec[0][2])
            if success is not None:
                raise gen.Return(success)
        else:
            # No return type specified and no exceptions raised.
            raise gen.Return(None)

        # Expected a result but nothing was present in the object. Something
        # went wrong.
        from thrift import Thrift
        raise Thrift.TApplicationException(
            Thrift.TApplicationException.MISSING_RESULT,
            '%s failed: did not receive a result as expected' % method_name
        )
        # TODO: We should probably throw a custom exception instead.

    send.__name__ = method_name
    return send


Instruction:
Write a Python 3 function for
connecting to this peer.

Response:
def connect(self):
        """Get a connection to this peer.

        If an connection to the peer already exists (either incoming or
        outgoing), that's returned. Otherwise, a new outgoing connection to
        this peer is created.

        :return:
            A future containing a connection to this host.
        """
        # Prefer incoming connections over outgoing connections.
        if self.connections:
            # First value is an incoming connection
            future = gen.Future()
            future.set_result(self.connections[0])
            return future

        if self._connecting:
            # If we're in the process of connecting to the peer, just wait
            # and re-use that connection.
            return self._connecting

        conn_future = self._connecting = self.connection_class.outgoing(
            hostport=self.hostport,
            process_name=self.tchannel.process_name,
            serve_hostport=self.tchannel.hostport,
            handler=self.tchannel.receive_call,
            tchannel=self.tchannel,
        )

        def on_connect(_):
            if not conn_future.exception():
                # We don't actually need to handle the exception. That's on
                # the caller.
                connection = conn_future.result()
                self.register_outgoing_conn(connection)
            self._connecting = None

        conn_future.add_done_callback(on_connect)
        return conn_future


Instruction:
Given the following Python 3 function, write the documentation
def register_outgoing_conn(self, conn):
        assert conn, "conn is required"
        conn.set_outbound_pending_change_callback(self._on_conn_change)
        self.connections.append(conn)
        self._set_on_close_cb(conn)
        self._on_conn_change()

Response: Add an outgoing connection into the heap.


Instruction:
How would you explain what the following Python 3 function does
def register_incoming_conn(self, conn):
        assert conn, "conn is required"
        conn.set_outbound_pending_change_callback(self._on_conn_change)
        self.connections.appendleft(conn)
        self._set_on_close_cb(conn)
        self._on_conn_change()

Response: Add incoming connection into the heap.


Instruction:
Here you have a function in Python 3, explain what it does
def outgoing_connections(self):

        # Outgoing connections are on the right
        return list(
            dropwhile(lambda c: c.direction != OUTGOING, self.connections)
        )

Response: Returns a list of all outgoing connections for this peer.


Instruction:
How would you code a function in Python 3 to
return a list of all incoming connections for this peer.

Response:
def incoming_connections(self):
        """Returns a list of all incoming connections for this peer."""

        # Incoming connections are on the left.
        return list(
            takewhile(lambda c: c.direction == INCOMING, self.connections)
        )


Instruction:
Can you create a Python 3 function that
finds a peer and connect to it.

Response:
def _get_peer_connection(self, blacklist=None):
        """Find a peer and connect to it.

        Returns a ``(peer, connection)`` tuple.

        Raises ``NoAvailablePeerError`` if no healthy peers are found.

        :param blacklist:
            If given, a set of hostports for peers that we must not try.
        """

        blacklist = blacklist or set()

        peer = None
        connection = None

        while connection is None:
            peer = self._choose(blacklist)

            if not peer:
                raise NoAvailablePeerError(
                    "Can't find an available peer for '%s'" % self.service
                )

            try:
                connection = yield peer.connect()
            except NetworkError as e:
                log.info(
                    'Failed to connect to %s. Trying a different host.',
                    peer.hostport,
                    exc_info=e,
                )
                connection = None
                blacklist.add(peer.hostport)

        raise gen.Return((peer, connection))


Instruction:
Write a Python 3 script to
send a message to the peer.

Response:
def send(
        self, arg1, arg2, arg3,
        headers=None,
        retry_limit=None,
        ttl=None,
    ):
        """Make a request to the Peer.

        :param arg1:
            String or Stream containing the contents of arg1. If None, an empty
            stream is used.
        :param arg2:
            String or Stream containing the contents of arg2. If None, an empty
            stream is used.
        :param arg3:
            String or Stream containing the contents of arg3. If None, an empty
            stream is used.
        :param headers:
            Headers will be put in the message as protocol header.
        :param retry_limit:
           Maximum number of retries will perform on the message. If the number
           is 0, it means no retry.
        :param ttl:
            Timeout for each request (second).
        :return:
            Future that contains the response from the peer.
        """

        # find a peer connection
        # If we can't find available peer at the first time, we throw
        # NoAvailablePeerError. Later during retry, if we can't find available
        # peer, we throw exceptions from retry not NoAvailablePeerError.
        peer, connection = yield self._get_peer_connection()

        arg1, arg2, arg3 = (
            maybe_stream(arg1), maybe_stream(arg2), maybe_stream(arg3)
        )

        if retry_limit is None:
            retry_limit = DEFAULT_RETRY_LIMIT

        ttl = ttl or DEFAULT_TIMEOUT
        # hack to get endpoint from arg_1 for trace name
        arg1.close()
        endpoint = yield read_full(arg1)

        # set default transport headers
        headers = headers or {}
        for k, v in self.headers.iteritems():
            headers.setdefault(k, v)

        if self.tracing_span is None:
            tracer = ClientTracer(channel=self.tchannel)
            self.tracing_span, _ = tracer.start_span(
                service=self.service, endpoint=endpoint,
                hostport=self._hostport, encoding=self.headers.get('as')
            )

        request = Request(
            service=self.service,
            argstreams=[InMemStream(endpoint), arg2, arg3],
            id=connection.writer.next_message_id(),
            headers=headers,
            endpoint=endpoint,
            ttl=ttl,
            tracing=tracing.span_to_tracing_field(self.tracing_span)
        )

        # only retry on non-stream request
        if request.is_streaming_request or self._hostport:
            retry_limit = 0

        if request.is_streaming_request:
            request.ttl = 0

        try:
            with self.tracing_span:  # to ensure span is finished
                response = yield self.send_with_retry(
                    request, peer, retry_limit, connection
                )
        except Exception as e:
            # event: on_exception
            exc_info = sys.exc_info()
            yield self.tchannel.event_emitter.fire(
                EventType.on_exception, request, e,
            )
            six.reraise(*exc_info)

        log.debug("Got response %s", response)

        raise gen.Return(response)


Instruction:
Can you tell what is the following Python 3 function doing
def clear(self):
        try:
            for peer in self._peers.values():
                peer.close()
        finally:
            self._peers = {}
            self._resetting = False

Response:
Reset this PeerGroup.

        This closes all connections to all known peers and forgets about
        these peers.

        :returns:
            A Future that resolves with a value of None when the operation
            has finished


Instruction:
Here you have a function in Python 3, explain what it does
def remove(self, hostport):
        assert hostport, "hostport is required"
        peer = self._peers.pop(hostport, None)
        peer_in_heap = peer and peer.index != -1
        if peer_in_heap:
            self.peer_heap.remove_peer(peer)
        return peer

Response: Removes the Peer for the given host port. Does nothing if a matching Peer does not exist. Returns None if no matching Peer is found.


Instruction:
Can you create a Python 3 function that
gets a Peer for the given destination.

Response:
def get(self, hostport):
        """Get a Peer for the given destination.

        A new Peer is added to the peer heap and returned if one does
        not already exist for the given host-port. Otherwise, the
        existing Peer is returned.
        """
        assert hostport, "hostport is required"
        assert isinstance(hostport, basestring), "hostport must be a string"

        if hostport not in self._peers:
            self._add(hostport)

        return self._peers[hostport]


Instruction:
Given the following Python 3 function, write the documentation
def _add(self, hostport):
        peer = self.peer_class(
            tchannel=self.tchannel,
            hostport=hostport,
            on_conn_change=self._update_heap,
        )
        peer.rank = self.rank_calculator.get_rank(peer)
        self._peers[peer.hostport] = peer

        self.peer_heap.add_and_shuffle(peer)

Response: Adds a new peer to the peer heap


Instruction:
Implement a function in Python 3 to
get a Peer for the given destination for a request.

Response:
def _get_isolated(self, hostport):
        """Get a Peer for the given destination for a request.

        A new Peer is added and returned if one does not already exist for the
        given host-port. Otherwise, the existing Peer is returned.

        **NOTE** new peers will not be added to the peer heap.
        """
        assert hostport, "hostport is required"
        if hostport not in self._peers:
            # Add a peer directly from a hostport, do NOT add it to the peer
            # heap
            peer = self.peer_class(
                tchannel=self.tchannel,
                hostport=hostport,
            )
            self._peers[peer.hostport] = peer

        return self._peers[hostport]


Instruction:
Can you implement a function in Python 3 that
initiates a new request through this PeerGroup.

Response:
def request(self, service, hostport=None, **kwargs):
        """Initiate a new request through this PeerGroup.

        :param hostport:
            If specified, requests will be sent to the specific host.
            Otherwise, a known peer will be picked at random.
        :param service:
            Name of the service being called. Defaults to an empty string.
        """
        return PeerClientOperation(
            peer_group=self,
            service=service,
            hostport=hostport,
            **kwargs)


Instruction:
Implement a function in Python 3 to
return a Peer that matches the given criteria.

Response:
def choose(self, hostport=None, blacklist=None):
        """Choose a Peer that matches the given criteria.

        :param hostport:
            Specifies that the returned Peer must be for the given host-port.
            Without this, all peers managed by this PeerGroup are
            candidates.
        :param blacklist:
            Peers on the blacklist won't be chosen.
        :returns:
            A Peer that matches all the requested criteria or None if no such
            Peer was found.
        """

        blacklist = blacklist or set()
        if hostport:
            return self._get_isolated(hostport)

        return self.peer_heap.smallest_peer(
            (lambda p: p.hostport not in blacklist and not p.is_ephemeral),
        )


Instruction:
Given the following Python 3 function, write the documentation
def get_arg(context, index):
    if index < len(context.argstreams):
        arg = ""
        chunk = yield context.argstreams[index].read()
        while chunk:
            arg += chunk
            chunk = yield context.argstreams[index].read()

        raise tornado.gen.Return(arg)
    else:
        raise TChannelError()

Response: get value from arg stream in async way


Instruction:
Write a Python 3 script for
putting an item into the queue. Returns a Future that resolves to None when the value has been successfully put into the queue.

Response:
def put(self, value):
        """Puts an item into the queue.

        Returns a Future that resolves to None once the value has been
        accepted by the queue.
        """
        io_loop = IOLoop.current()
        new_hole = Future()

        new_put = Future()
        new_put.set_result(new_hole)

        with self._lock:
            self._put, put = new_put, self._put

        answer = Future()

        def _on_put(future):
            if future.exception():  # pragma: no cover (never happens)
                return answer.set_exc_info(future.exc_info())

            old_hole = put.result()
            old_hole.set_result(Node(value, new_hole))
            answer.set_result(None)

        io_loop.add_future(put, _on_put)
        return answer


Instruction:
Create a Python 3 function to
return a value from the queue without waiting. Raises QueueEmpty if no values are available right now.

Response:
def get_nowait(self):
        """Returns a value from the queue without waiting.

        Raises ``QueueEmpty`` if no values are available right now.
        """
        new_get = Future()

        with self._lock:
            if not self._get.done():
                raise QueueEmpty
            get, self._get = self._get, new_get

        hole = get.result()
        if not hole.done():
            # Restore the unfinished hole.
            new_get.set_result(hole)
            raise QueueEmpty

        node = hole.result()
        value = node.value
        new_hole, node.next = node.next, None
        new_get.set_result(new_hole)
        return value


Instruction:
Explain what the following Python 3 code does
def get(self):
        io_loop = IOLoop.current()
        new_get = Future()

        with self._lock:
            get, self._get = self._get, new_get

        answer = Future()

        def _on_node(future):
            if future.exception():  # pragma: no cover (never happens)
                return answer.set_exc_info(future.exc_info())

            node = future.result()
            value = node.value
            new_hole, node.next = node.next, None
            new_get.set_result(new_hole)
            answer.set_result(value)

        def _on_get(future):
            if future.exception():  # pragma: no cover (never happens)
                return answer.set_exc_info(future.exc_info())

            hole = future.result()
            io_loop.add_future(hole, _on_node)

        io_loop.add_future(get, _on_get)
        return answer

Response: Gets the next item from the queue.


Instruction:
Write a Python 3 script to
stream Message got fragmented based on payload size. All the data within space_left will be kept. All the rest will be shifted to next fragment message. :param space_left: space left for current frame :param fragment_msg: the type is either CallRequestMessage or CallResponseMessage :return: None if there is space left or next fragment message

Response:
def fragment(self, space_left, fragment_msg):
        """Streaming Message got fragmented based on
        payload size. All the data within space_left
        will be kept. All the rest will be shifted to
        next fragment message.

        :param space_left:
            space left for current frame
        :param fragment_msg:
            the type is either CallRequestMessage or
            CallResponseMessage
        :return: None if there is space left
            or next fragment message
        """
        new_args = []
        key_length = 2  # 2bytes for size
        for i, arg in enumerate(self.args):
            if space_left >= key_length:
                space_left -= key_length

                if arg is not None:
                    arg_length = len(arg)
                    if space_left < arg_length:
                        fragment_msg.args.append(arg[space_left:])
                        new_args.append(arg[:space_left])
                        space_left = 0
                    else:
                        new_args.append(arg)
                        space_left -= arg_length
                        if space_left <= key_length:
                            # boundary for arg
                            fragment_msg.args.append("")
                else:
                    new_args.append("")
            else:
                for l in range(i, len(self.args)):
                    fragment_msg.args.append(self.args[l])
                break

        self.args = new_args
        if space_left >= 0 and len(fragment_msg.args) == 0:
            # don't need to fragment any more
            return None
        else:
            self.flags = FlagsType.fragment
            fragment_msg.id = self.id
            return fragment_msg


Instruction:
Here you have a function in Python 3, explain what it does
def response_from_mixed(mixed):

    # if none then give empty Response
    if mixed is None:
        return Response()

    # if not Response, then treat like body
    if not isinstance(mixed, Response):
        return Response(mixed)

    # it's already a Response
    return mixed

Response: Create Response from mixed input.


Instruction:
Write a Python 3 script for
registering a hook to be called when an event is fired.

Response:
def register_hook(self, hook, event_type=None):
        """
        If ``event_type`` is provided, then ``hook`` will be called whenever
        that event is fired.

        If no ``event_type`` is specifid, but ``hook`` implements any methods
        with names matching an event hook, then those will be registered with
        their corresponding events. This allows for more stateful, class-based
        event handlers.
        """
        if event_type is not None:
            assert type(event_type) is int, "register hooks with int values"
            return self.hooks[event_type].append(hook)

        for event_type in EventType._fields:
            func = getattr(hook, event_type, None)
            if callable(func):
                event_value = getattr(EventType, event_type)
                self.register_hook(func, event_value)


Instruction:
Write a Python 3 function for
initializing existing object into the heap.

Response:
def init(h):
    """Initialize existing object into the heap."""
    # heapify
    n = h.size()
    for i in six.moves.range(int(math.floor(n/2)) - 1, -1, -1):
        down(h, i, n)


Instruction:
Can you write a function in Python 3 where it
pushes a new value into heap.

Response:
def push(h, x):
    """Push a new value into heap."""
    h.push(x)
    up(h, h.size()-1)


Instruction:
Create a Python 3 function to
pop the value from the heap.

Response:
def pop(h):
    """Pop the heap value from the heap."""
    n = h.size() - 1
    h.swap(0, n)
    down(h, 0, n)
    return h.pop()


Instruction:
Can you implement a function in Python 3 that
removes the item at position i from the heap.

Response:
def remove(h, i):
    """Remove the item at position i of the heap."""
    n = h.size() - 1
    if n != i:
        h.swap(i, n)
        down(h, i, n)
        up(h, i)

    return h.pop()


Instruction:
How would you explain what the following Python 3 function does
def fix(h, i):
    down(h, i, h.size())
    up(h, i)

Response: Rearrange the heap after the item at position i got updated.


Instruction:
Can you create a Python 3 function that
finds the index of the smallest item in the given heap that matches the given predicate.

Response:
def smallest(heap, predicate):
    """Finds the index of the smallest item in the heap that matches the given
    predicate.

    :param heap:
        Heap on which this search is being performed.
    :param predicate:
        Function that accepts an item from the heap and returns true or false.
    :returns:
        Index of the first item for which ``predicate`` returned true.
    :raises NoMatchError:
        If no matching items were found.
    """
    n = heap.size()

    # items contains indexes of items yet to be checked.
    items = deque([0])
    while items:
        current = items.popleft()
        if current >= n:
            continue

        if predicate(heap.peek(current)):
            return current

        child1 = 2 * current + 1
        child2 = child1 + 1

        if child1 < n and child2 < n and heap.lt(child2, child1):
            # make sure we check the smaller child first.
            child1, child2 = child2, child1

        if child1 < n:
            items.append(child1)

        if child2 < n:
            items.append(child2)

    raise NoMatchError()


Instruction:
Implement a function in Python 3 to
inject the span into the Trace field

Response:
def span_to_tracing_field(span):
    """
    Inject the span into Trace field, if Zipkin format is supported
    :param span: OpenTracing Span
    """
    if span is None:
        return common.random_tracing()
    # noinspection PyBroadException
    try:
        carrier = {}
        span.tracer.inject(span, ZIPKIN_SPAN_FORMAT, carrier)
        tracing = Tracing(span_id=carrier['span_id'],
                          trace_id=carrier['trace_id'],
                          parent_id=carrier['parent_id'] or 0L,
                          traceflags=carrier['traceflags'])
        return tracing
    except opentracing.UnsupportedFormatException:
        pass  # tracer might not support Zipkin format
    except:
        log.exception('Failed to inject tracing span into headers')
    return common.random_tracing()


Instruction:
Make a summary of the following Python 3 code
def apply_trace_flag(span, trace, default_trace):
    if trace is None:
        trace = default_trace
    trace = trace() if callable(trace) else trace
    if trace is False and span:
        span.set_tag(tags.SAMPLING_PRIORITY, 0)

Response: Apply tracing flag to a node.


Instruction:
Make a summary of the following Python 3 code
def start_basic_span(self, request):
        # noinspection PyBroadException
        try:
            # Currently Java does not populate Tracing field, so do not
            # mistaken it for a real trace ID.
            if request.tracing.trace_id:
                context = self.tracer.extract(
                    format=ZIPKIN_SPAN_FORMAT,
                    carrier=request.tracing)
                self.span = self.tracer.start_span(
                    operation_name=request.endpoint,
                    child_of=context,
                    tags={tags.SPAN_KIND: tags.SPAN_KIND_RPC_SERVER},
                )
        except opentracing.UnsupportedFormatException:
            pass  # tracer might not support Zipkin format
        except:
            log.exception('Cannot extract tracing span from Trace field')

Response: Start tracing span from the protocol s tracing fields.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def start_span(self, request, headers, peer_host, peer_port):
        parent_context = None
        # noinspection PyBroadException
        try:
            if headers and hasattr(headers, 'iteritems'):
                tracing_headers = {
                    k[len(TRACING_KEY_PREFIX):]: v
                    for k, v in headers.iteritems()
                    if k.startswith(TRACING_KEY_PREFIX)
                }
                parent_context = self.tracer.extract(
                    format=opentracing.Format.TEXT_MAP,
                    carrier=tracing_headers
                )
                if self.span and parent_context:
                    # we already started a span from Tracing fields,
                    # so only copy baggage from the headers.
                    for k, v in parent_context.baggage.iteritems():
                        self.span.set_baggage_item(k, v)
        except:
            log.exception('Cannot extract tracing span from headers')
        if self.span is None:
            self.span = self.tracer.start_span(
                operation_name=request.endpoint,
                child_of=parent_context,
                tags={tags.SPAN_KIND: tags.SPAN_KIND_RPC_SERVER},
            )
        if 'cn' in request.headers:
            self.span.set_tag(tags.PEER_SERVICE, request.headers['cn'])
        if peer_host:
            self.span.set_tag(tags.PEER_HOST_IPV4, peer_host)
        if peer_port:
            self.span.set_tag(tags.PEER_PORT, peer_port)
        if 'as' in request.headers:
            self.span.set_tag('as', request.headers['as'])
        return self.span

Response: Start a new server - side span.


Instruction:
Can you write a function in Python 3 where it
constructs a TChannelError instance from an error code.

Response:
def from_code(cls, code, **kw):
        """Construct a ``TChannelError`` instance from an error code.

        This will return the appropriate class type for the given code.
        """
        return {
            TIMEOUT: TimeoutError,
            CANCELED: CanceledError,
            BUSY: BusyError,
            DECLINED: DeclinedError,
            UNEXPECTED_ERROR: UnexpectedError,
            BAD_REQUEST: BadRequestError,
            NETWORK_ERROR: NetworkError,
            UNHEALTHY: UnhealthyError,
            FATAL: FatalProtocolError,
        }[code](**kw)


Instruction:
Can you generate the documentation for the following Python 3 function
def register(dispatcher, service_module, handler, method=None, service=None):
    if not service:
        service = service_module.__name__.rsplit('.', 1)[-1]
    if not method:
        method = handler.__name__
    assert service, 'A service name could not be determined'
    assert method, 'A method name could not be determined'

    assert hasattr(service_module.Iface, method), (
        "Service %s doesn't define method %s" % (service, method)
    )
    assert hasattr(service_module, method + '_result'), (
        "oneway methods are not yet supported"
    )

    endpoint = '%s::%s' % (service, method)
    args_type = getattr(service_module, method + '_args')
    result_type = getattr(service_module, method + '_result')

    # if the dispatcher is set to deal with handlers that
    # return responses, then use new api, else use deprecated
    if dispatcher._handler_returns_response:
        new_handler = build_handler(result_type, handler)
    else:
        new_handler = deprecated_build_handler(result_type, handler)

    dispatcher.register(
        endpoint,
        new_handler,
        ThriftSerializer(args_type),
        ThriftSerializer(result_type)
    )
    return handler

Response: Registers a Thrift service method with the given RequestDispatcher.


Instruction:
How would you implement a function in Python 3 that
sends back the result of this call. Only one of this and write_exc_info may be called.

Response:
def write_result(self, result):
        """Send back the result of this call.

        Only one of this and `write_exc_info` may be called.

        :param result:
            Return value of the call
        """
        assert not self.finished, "Already sent a response"

        if not self.result.thrift_spec:
            self.finished = True
            return

        spec = self.result.thrift_spec[0]
        if result is not None:
            assert spec, "Tried to return a result for a void method."
            setattr(self.result, spec[2], result)

        self.finished = True


Instruction:
Implement a Python 3 function for
writing exception information to the response.

Response:
def write_exc_info(self, exc_info=None):
        """Write exception information to the response.

        Only one of this and ``write_result`` may be called.

        :param exc_info:
            3-tuple of exception information. If omitted, the last exception
            will be retrieved using ``sys.exc_info()``.
        """
        exc_info = exc_info or sys.exc_info()
        exc = exc_info[1]
        self.code = StatusCode.error
        for spec in self.result.thrift_spec[1:]:
            if spec and isinstance(exc, spec[3][0]):
                assert not self.finished, "Already sent a response"

                setattr(self.result, spec[2], exc)
                self.finished = True
                return

        # Re-raise the exception (with the same traceback) if it didn't match.
        raise exc_info[0], exc_info[1], exc_info[2]


Instruction:
Make a summary of the following Python 3 code
def call(
        self,
        scheme,
        service,
        arg1,
        arg2=None,
        arg3=None,
        timeout=None,
        retry_on=None,
        retry_limit=None,
        routing_delegate=None,
        hostport=None,
        shard_key=None,
        tracing_span=None,
        trace=None,  # to trace or not, defaults to self._dep_tchannel.trace
        caller_name=None,
    ):
        """Make low-level requests to TChannel services.

        **Note:** Usually you would interact with a higher-level arg scheme
        like :py:class:`tchannel.schemes.JsonArgScheme` or
        :py:class:`tchannel.schemes.ThriftArgScheme`.
        """

        # TODO - don't use asserts for public API
        assert format, "format is required"
        assert service, "service is required"
        assert arg1, "arg1 is required"

        # default args
        if arg2 is None:
            arg2 = ""
        if arg3 is None:
            arg3 = ""
        if timeout is None:
            timeout = DEFAULT_TIMEOUT
        if retry_on is None:
            retry_on = retry.DEFAULT
        if retry_limit is None:
            retry_limit = retry.DEFAULT_RETRY_LIMIT

        # TODO - allow filters/steps for serialization, tracing, etc...

        tracing.apply_trace_flag(tracing_span, trace, self._dep_tchannel.trace)

        # calls tchannel.tornado.peer.PeerClientOperation.__init__
        operation = self._dep_tchannel.request(
            service=service,
            hostport=hostport,
            arg_scheme=scheme,
            retry=retry_on,
            tracing_span=tracing_span
        )

        # fire operation
        transport_headers = {
            transport.SCHEME: scheme,
            transport.CALLER_NAME: caller_name or self.name,
        }
        if shard_key:
            transport_headers[transport.SHARD_KEY] = shard_key
        if routing_delegate:
            transport_headers[transport.ROUTING_DELEGATE] = routing_delegate

        response = yield operation.send(
            arg1=arg1,
            arg2=arg2,
            arg3=arg3,
            headers=transport_headers,
            retry_limit=retry_limit,
            ttl=timeout,
        )

        # unwrap response
        body = yield response.get_body()
        headers = yield response.get_header()
        t = TransportHeaders.from_dict(response.headers)
        result = Response(
            body=body,
            headers=headers,
            transport=t,
            status=response.code,
        )

        raise gen.Return(result)

Response: Make low - level requests to TChannel services.


Instruction:
Make a summary of the following Python 3 code
def advertise(self, routers=None, name=None, timeout=None,
                  router_file=None, jitter=None):
        """Advertise with Hyperbahn.

        After a successful advertisement, Hyperbahn will establish long-lived
        connections with your application. These connections are used to load
        balance inbound and outbound requests to other applications on the
        Hyperbahn network.

        Re-advertisement happens periodically after calling this method (every
        minute). Hyperbahn will eject us from the network if it doesn't get a
        re-advertise from us after 5 minutes.

        This function may be called multiple times if it fails. If it
        succeeds, all consecutive calls are ignored.

        :param list routers:
            A seed list of known Hyperbahn addresses to attempt contact with.
            Entries should be of the form ``"host:port"``.

        :param string name:
            The name your application identifies itself as. This is usually
            unneeded because in the common case it will match the ``name`` you
            initialized the ``TChannel`` instance with. This is the identifier
            other services will use to make contact with you.

        :param timeout:
            The timeout (in sec) for the initial advertise attempt.
            Defaults to 30 seconds.

        :param jitter:
            Variance allowed in the interval per request. Defaults to 5
            seconds.  The jitter applies to the initial advertise request as
            well.

        :param router_file:
            The host file that contains the routers information. The file
            should contain a JSON stringified format of the routers parameter.
            Either routers or router_file should be provided. If both provided,
            a ValueError will be raised.

        :returns:
            A future that resolves to the remote server's response after the
            first advertise finishes.

        :raises TimeoutError:
            When unable to make our first advertise request to Hyperbahn.
            Subsequent requests may fail but will be ignored.
        """
        if routers is not None and router_file is not None:
            raise ValueError(
                'Only one of routers and router_file can be provided.')

        if routers is None and router_file is not None:
            # should just let the exceptions fly
            try:
                with open(router_file, 'r') as json_data:
                    routers = json.load(json_data)
            except (IOError, OSError, ValueError):
                log.exception('Failed to read seed routers list.')
                raise

        @gen.coroutine
        def _advertise():
            result = yield self._dep_tchannel.advertise(
                routers=routers,
                name=name,
                timeout=timeout,
            )
            body = yield result.get_body()
            headers = yield result.get_header()
            response = Response(json.loads(body), headers or {})
            raise gen.Return(response)

        def _on_advertise(future):
            if not future.exception():
                return

            # If the request failed, clear the response so that we can try
            # again.
            with self._advertise_lock:
                # `is` comparison to ensure we're not deleting another Future.
                if self._advertise_response is future:
                    self._advertise_response = None

        with self._advertise_lock:
            if self._advertise_response is not None:
                return self._advertise_response
            future = self._advertise_response = _advertise()

        # We call add_done_callback here rather than when we call _advertise()
        # because if the future has already resolved by the time we call
        # add_done_callback, the callback will immediately be executed. The
        # callback will try to acquire the advertise_lock which we already
        # hold and end up in a deadlock.
        future.add_done_callback(_on_advertise)
        return future

Response: Advertise a new TChannel instance to Hyperbahn.


Instruction:
Here you have a function in Python 3, explain what it does
def thrift_request_builder(service, thrift_module, hostport=None,
                           thrift_class_name=None):
    """Provide TChannel compatibility with Thrift-generated modules.

    The service this creates is meant to be used with TChannel like so:

    .. code-block:: python

        from tchannel import TChannel, thrift_request_builder
        from some_other_service_thrift import some_other_service

        tchannel = TChannel('my-service')

        some_service = thrift_request_builder(
            service='some-other-service',
            thrift_module=some_other_service
        )

        resp = tchannel.thrift(
            some_service.fetchPotatoes()
        )

    .. deprecated:: 0.18.0

        Please switch to :py:func:`tchannel.thrift.load`.

    .. warning::

        This API is deprecated and will be removed in a future version.

    :param string service:
        Name of Thrift service to call. This is used internally for
        grouping and stats, but also to route requests over Hyperbahn.

    :param thrift_module:
        The top-level module of the Apache Thrift generated code for
        the service that will be called.

    :param string hostport:
        When calling the Thrift service directly, and not over Hyperbahn,
        this 'host:port' value should be provided.

    :param string thrift_class_name:
        When the Apache Thrift generated Iface class name does not match
        thrift_module, then this should be provided.
    """

    # start with a request maker instance
    maker = ThriftRequestMaker(
        service=service,
        thrift_module=thrift_module,
        hostport=hostport,
        thrift_class_name=thrift_class_name
    )

    # create methods that mirror thrift client
    # and each return ThriftRequest
    methods = _create_methods(thrift_module)

    # then attach to instane
    for name, method in methods.iteritems():
        method = types.MethodType(method, maker, ThriftRequestMaker)
        setattr(maker, name, method)

    return maker

Response: This function creates a Thrift - compatible client for a given service.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def read_body(self, body):
        result_spec = self.result_type.thrift_spec

        # raise application exception, if present
        for exc_spec in result_spec[1:]:
            exc = getattr(body, exc_spec[2])
            if exc is not None:
                raise exc

        # success - non-void
        if len(result_spec) >= 1 and result_spec[0] is not None:

            # value expected, but got none
            # TODO - server side should use this same logic
            if body.success is None:
                raise ValueExpectedError(
                    'Expected a value to be returned for %s, '
                    'but recieved None - only void procedures can '
                    'return None.' % self.endpoint
                )

            return body.success

        # success - void
        else:
            return None

Response:
Handles the response body for this request. Returns the result unwrapped
        from the response union.


Instruction:
Here you have a function in Python 3, explain what it does
def get_rank(self, peer):
        if not peer.connections:
            return self.TIERS[0]

        if not peer.has_incoming_connections:
            return self.TIERS[1] + peer.total_outbound_pendings

        return self.TIERS[2] + peer.total_outbound_pendings

Response: Calculate the rank of the peer based on the connections.


Instruction:
Can you tell what is the following Python 3 function doing
def prepare(cls, *args, **kwargs):
        cls.args = args
        cls.kwargs = kwargs
        cls.prepared = True

Response: Set the arguments to be used when instantiating a TChannel instance.


Instruction:
Write a Python 3 function for
undoing call to prepare useful for testing.

Response:
def reset(cls, *args, **kwargs):
        """Undo call to prepare, useful for testing."""
        cls.local.tchannel = None
        cls.args = None
        cls.kwargs = None
        cls.prepared = False


Instruction:
Here you have a function in Python 3, explain what it does
def get_instance(cls):
        if not cls.prepared:
            raise SingletonNotPreparedError(
                "prepare must be called before get_instance"
            )

        if hasattr(cls.local, 'tchannel') and cls.local.tchannel is not None:
            return cls.local.tchannel

        cls.local.tchannel = cls.tchannel_cls(*cls.args, **cls.kwargs)

        return cls.local.tchannel

Response: Get a configured thread - safe singleton TChannel instance.


Instruction:
Create a Python 3 function for
handling incoming request message including CallRequestMessage and CallRequestContinueMessage.

Response:
def handle_pre_call(self, message, connection):
        """Handle incoming request message including CallRequestMessage and
        CallRequestContinueMessage

        This method will build the User friendly request object based on the
        incoming messages.

        It passes all the messages into the message_factory to build the init
        request object. Only when it get a CallRequestMessage and a completed
        arg_1=argstream[0], the message_factory will return a request object.
        Then it will trigger the async handle_call method.

        :param message: CallRequestMessage or CallRequestContinueMessage
        :param connection: tornado connection
        """
        req = None
        try:
            req = connection.request_message_factory.build(message)
            # message_factory will create Request only when it receives
            # CallRequestMessage. It will return None, if it receives
            # CallRequestContinueMessage.
            if req:
                self.handle_call(req, connection)

        except TChannelError as e:
            log.warn('Received a bad request.', exc_info=True)
            if req:
                e.tracing = req.tracing
            connection.send_error(e)


Instruction:
Can you generate the documentation for the following Python 3 function
def register(
            self,
            rule,
            handler,
            req_serializer=None,
            resp_serializer=None
    ):
        """Register a new endpoint with the given name.

        .. code-block:: python

            @dispatcher.register('is_healthy')
            def check_health(request, response):
                # ...

        :param rule:
            Name of the endpoint. Incoming Call Requests must have this as
            ``arg1`` to dispatch to this handler.

            If ``RequestHandler.FALLBACK`` is specified as a rule, the given
            handler will be used as the 'fallback' handler when requests don't
            match any registered rules.

        :param handler:
            A function that gets called with ``Request`` and ``Response``.

        :param req_serializer:
            Arg scheme serializer of this endpoint. It should be
            ``RawSerializer``, ``JsonSerializer``, and ``ThriftSerializer``.

        :param resp_serializer:
            Arg scheme serializer of this endpoint. It should be
            ``RawSerializer``, ``JsonSerializer``, and ``ThriftSerializer``.
        """

        assert handler, "handler must not be None"
        req_serializer = req_serializer or RawSerializer()
        resp_serializer = resp_serializer or RawSerializer()
        self.handlers[rule] = Handler(handler, req_serializer, resp_serializer)

Response: Register a new endpoint with the given name.


Instruction:
How would you code a function in Python 3 to
create a new Tracing with random IDs.

Response:
def random_tracing():
    """
    Create new Tracing() tuple with random IDs.
    """
    new_id = _uniq_id()
    return Tracing(
        span_id=new_id,
        parent_id=0,
        trace_id=new_id,
        traceflags=0)


Instruction:
Can you implement a function in Python 3 that
generates checksum for messages with the given message.

Response:
def generate_checksum(message, previous_csum=0):
    """Generate checksum for messages with
        CALL_REQ, CALL_REQ_CONTINUE,
        CALL_RES,CALL_RES_CONTINUE types.

    :param message: outgoing message
    :param previous_csum: accumulated checksum value
    """
    if message.message_type in CHECKSUM_MSG_TYPES:
        csum = compute_checksum(
            message.checksum[0],
            message.args,
            previous_csum,
        )

        message.checksum = (message.checksum[0], csum)


Instruction:
How would you code a function in Python 3 to
verify checksum for incoming message.

Response:
def verify_checksum(message, previous_csum=0):
    """Verify checksum for incoming message.

    :param message: incoming message
    :param previous_csum: accumulated checksum value

    :return return True if message checksum type is None
    or checksum is correct
    """
    if message.message_type in CHECKSUM_MSG_TYPES:
        csum = compute_checksum(
            message.checksum[0],
            message.args,
            previous_csum,
        )

        if csum == message.checksum[1]:
            return True
        else:
            return False
    else:
        return True


Instruction:
Write a Python 3 function for
advertising with Hyperbahn. See :py:class:`tchannel.TChannel.advertise`.

Response:
def advertise(tchannel, service, routers=None, timeout=None, router_file=None,
              jitter=None):
    """Advertise with Hyperbahn.

    See :py:class:`tchannel.TChannel.advertise`.
    """
    timeout = timeout or FIRST_ADVERTISE_TIME
    if routers is not None and router_file is not None:
        raise ValueError(
            'Only one of routers and router_file can be provided.')

    if routers is None and router_file is not None:
        # should just let the exceptions fly
        try:
            with open(router_file, 'r') as json_data:
                routers = json.load(json_data)
        except (IOError, OSError, ValueError):
            log.exception('Failed to read seed routers list.')
            raise

    for router in routers:
        # We use .get here instead of .add because we don't want to fail if a
        # TChannel already knows about some of the routers.
        tchannel.peers.get(router)

    adv = Advertiser(service, tchannel, ttl_secs=timeout,
                     interval_max_jitter_secs=jitter)
    return adv.start()


Instruction:
Write a Python 3 script for
starting the advertise loop.

Response:
def start(self):
        """Starts the advertise loop.

        Returns the result of the first ad request.
        """
        if self.running:
            raise Exception('Advertiser is already running')
        if self.io_loop is None:
            self.io_loop = tornado.ioloop.IOLoop.current()

        self.running = True
        answer = tornado.gen.Future()
        self._schedule_ad(0, answer)
        return answer


Instruction:
Explain what the following Python 3 code does
def _schedule_ad(self, delay=None, response_future=None):
        if not self.running:
            return

        if delay is None:
            delay = self.interval_secs

        delay += random.uniform(0, self.interval_max_jitter_secs)
        self._next_ad = self.io_loop.call_later(delay, self._ad,
                                                response_future)

Response: Schedules an ad request.


Instruction:
Can you create a Python 3 function that
adds a new request to the Cemetery that is known to have timed out.

Response:
def add(self, id, ttl_secs):
        """Adds a new request to the Cemetery that is known to have timed out.

        The request will be forgotten after ``ttl_secs + ttl_offset_secs``
        seconds.

        :param id:
            ID of the request
        :param ttl_secs:
            TTL of the request (in seconds)
        """
        ttl_secs = min(ttl_secs + self.ttl_offset_secs, self.max_ttl_secs)
        self._tombstones[id] = IOLoop.current().call_later(
            ttl_secs, self.forget, id,
        )


Instruction:
Here you have a function in Python 3, explain what it does
def clear(self):
        io_loop = IOLoop.current()
        while self._tombstones:
            _, req_timeout = self._tombstones.popitem()
            io_loop.remove_timeout(req_timeout)

Response: Forget about all requests.


Instruction:
Implement a function in Python 3 to
get the header value from the response.

Response:
def get_header(self):
        """Get the header value from the response.

        :return: a future contains the deserialized value of header
        """
        raw_header = yield get_arg(self, 1)
        if not self.serializer:
            raise tornado.gen.Return(raw_header)
        else:
            header = self.serializer.deserialize_header(raw_header)
            raise tornado.gen.Return(header)


Instruction:
Can you implement a function in Python 3 that
gets the body value from the response.

Response:
def get_body(self):
        """Get the body value from the response.

        :return: a future contains the deserialized value of body
        """

        raw_body = yield get_arg(self, 2)
        if not self.serializer:
            raise tornado.gen.Return(raw_body)
        else:
            body = self.serializer.deserialize_body(raw_body)
            raise tornado.gen.Return(body)


Instruction:
How would you implement a function in Python 3 that
sets the custom body stream for the current message.

Response:
def set_body_s(self, stream):
        """Set customized body stream.

        Note: the body stream can only be changed before the stream
        is consumed.

        :param stream: InMemStream/PipeStream for body

        :except TChannelError:
            Raise TChannelError if the stream is being sent when you try
            to change the stream.
        """
        if self.argstreams[2].state == StreamState.init:
            self.argstreams[2] = stream
        else:
            raise TChannelError(
                "Unable to change the body since the streaming has started")


Instruction:
Can you generate the documentation for the following Python 3 function
def set_header_s(self, stream):

        if self.argstreams[1].state == StreamState.init:
            self.argstreams[1] = stream
        else:
            raise TChannelError(
                "Unable to change the header since the streaming has started")

Response: Set the custom header stream for the current entry.


Instruction:
Can you implement a function in Python 3 that
writes the header to the header stream.

Response:
def write_header(self, chunk):
        """Write to header.

        Note: the header stream is only available to write before write body.

        :param chunk: content to write to header

        :except TChannelError:
            Raise TChannelError if the response's flush() has been called
        """

        if self.serializer:
            header = self.serializer.serialize_header(chunk)
        else:
            header = chunk

        if self.flushed:
            raise TChannelError("write operation invalid after flush call")

        if (self.argstreams[0].state != StreamState.completed and
                self.argstreams[0].auto_close):
            self.argstreams[0].close()

        return self.argstreams[1].write(header)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def write_body(self, chunk):

        if self.serializer:
            body = self.serializer.serialize_body(chunk)
        else:
            body = chunk

        if self.flushed:
            raise TChannelError("write operation invalid after flush call")

        if (self.argstreams[0].state != StreamState.completed and
                self.argstreams[0].auto_close):
            self.argstreams[0].close()
        if (self.argstreams[1].state != StreamState.completed and
                self.argstreams[1].auto_close):
            self.argstreams[1].close()

        return self.argstreams[2].write(body)

Response: Write the content of the message to the response.


Instruction:
Can you generate the documentation for the following Python 3 function
def read_message(stream):
    answer = tornado.gen.Future()
    io_loop = IOLoop.current()

    def on_error(future):
        log.info('Failed to read data: %s', future.exception())
        return answer.set_exc_info(future.exc_info())

    @fail_to(answer)
    def on_body(size, future):
        if future.exception():
            return on_error(future)

        body = future.result()
        f = frame.frame_rw.read(BytesIO(body), size=size)
        message_type = f.header.message_type
        message_rw = messages.RW.get(message_type)
        if not message_rw:
            exc = errors.FatalProtocolError(
                'Unknown message type %s', str(message_type)
            )
            return answer.set_exception(exc)

        message = message_rw.read(BytesIO(f.payload))
        message.id = f.header.message_id
        answer.set_result(message)

    @fail_to(answer)
    def on_read_size(future):
        if future.exception():
            return answer.set_exc_info(future.exc_info())

        size_bytes = future.result()
        size = frame.frame_rw.size_rw.read(BytesIO(size_bytes))
        io_loop.add_future(
            stream.read_bytes(size - FRAME_SIZE_WIDTH),
            lambda f: on_body(size, f)
        )

    try:
        # read_bytes may fail if the stream has already been closed
        read_size_future = stream.read_bytes(FRAME_SIZE_WIDTH)
    except Exception:
        answer.set_exc_info(sys.exc_info())
    else:
        read_size_future.add_done_callback(on_read_size)
    return answer

Response: Reads a message from the given IOStream.


Instruction:
How would you code a function in Python 3 to
specify a function to be called when this connection is closed.

Response:
def set_close_callback(self, cb):
        """Specify a function to be called when this connection is closed.

        :param cb:
            A callable that takes no arguments. This callable will be called
            when this connection is closed.
        """
        assert self._close_cb is None, (
            'A close_callback has already been set for this connection.'
        )
        self._close_cb = stack_context.wrap(cb)
        if self.closed:
            self._close_cb()


Instruction:
Create a Python 3 function to
send a message up the wire.

Response:
def send(self, message):
        """Send the given message up the wire.
        Use this for messages which have a response message.

        :param message:
            Message to send
        :returns:
            A Future containing the response for the message
        """
        assert self._handshake_performed, "Perform a handshake first."
        assert message.message_type in self.CALL_REQ_TYPES, (
            "Message '%s' can't use send" % repr(message)
        )

        message.id = message.id or self.writer.next_message_id()
        assert message.id not in self._outbound_pending_call, (
            "Message ID '%d' already being used" % message.id
        )

        future = tornado.gen.Future()
        self._outbound_pending_call[message.id] = future
        self.write(message)
        return future


Instruction:
Write a Python 3 function that can
write the given message up the wire.

Response:
def write(self, message):
        """Writes the given message up the wire.

        Does not expect a response back for the message.

        :param message:
            Message to write.
        """
        message.id = message.id or self.writer.next_message_id()

        if message.message_type in self.CALL_REQ_TYPES:
            message_factory = self.request_message_factory
        else:
            message_factory = self.response_message_factory

        fragments = message_factory.fragment(message)
        return self._write_fragments(fragments)


Instruction:
Make a summary of the following Python 3 code
def _write_fragments(self, fragments):
        answer = tornado.gen.Future()

        if not fragments:
            answer.set_result(None)
            return answer

        io_loop = IOLoop.current()

        def _write_fragment(future):
            if future and future.exception():
                return answer.set_exc_info(future.exc_info())

            try:
                fragment = fragments.next()
            except StopIteration:
                return answer.set_result(None)

            io_loop.add_future(self.writer.put(fragment), _write_fragment)

        _write_fragment(None)
        return answer

Response: Writes the given generator of messages to the cache.


Instruction:
Here you have a function in Python 3, explain what it does
def initiate_handshake(self, headers, timeout=None):
        io_loop = IOLoop.current()
        timeout = timeout or DEFAULT_INIT_TIMEOUT_SECS

        self.writer.put(messages.InitRequestMessage(
            version=PROTOCOL_VERSION,
            headers=headers
        ))

        init_res_future = self.reader.get()
        timeout_handle = io_loop.call_later(timeout, (
            lambda: init_res_future.set_exception(errors.TimeoutError(
                'Handshake with %s:%d timed out. Did not receive an INIT_RES '
                'after %s seconds' % (
                    self.remote_host, self.remote_host_port, str(timeout)
                )
            ))
        ))
        io_loop.add_future(
            init_res_future,
            (lambda _: io_loop.remove_timeout(timeout_handle)),
        )

        init_res = yield init_res_future
        if init_res.message_type != Types.INIT_RES:
            raise errors.UnexpectedError(
                "Expected handshake response, got %s" % repr(init_res)
            )
        self._extract_handshake_headers(init_res)
        self._handshake_performed = True

        # The receive loop is started only after the handshake has been
        # completed.
        self._loop()

        raise tornado.gen.Return(init_res)

Response: Initiate a handshake with the remote host.


Instruction:
Implement a function in Python 3 to
expect a handshake from the remote host.

Response:
def expect_handshake(self, headers):
        """Expect a handshake from the remote host.

        :param headers:
            Headers to respond with
        :returns:
            A future that resolves (with a value of None) when the handshake
            is complete.
        """
        init_req = yield self.reader.get()
        if init_req.message_type != Types.INIT_REQ:
            raise errors.UnexpectedError(
                "You need to shake my hand first. Got %s" % repr(init_req)
            )
        self._extract_handshake_headers(init_req)
        self._handshake_performed = True

        self.writer.put(
            messages.InitResponseMessage(
                PROTOCOL_VERSION, headers, init_req.id),
        )

        # The receive loop is started only after the handshake has been
        # completed.
        self._loop()

        raise tornado.gen.Return(init_req)


Instruction:
Make a summary of the following Python 3 code
def outgoing(cls, hostport, process_name=None, serve_hostport=None,
                 handler=None, tchannel=None):
        """Initiate a new connection to the given host.

        :param hostport:
            String in the form ``$host:$port`` specifying the target host
        :param process_name:
            Process name of the entity making the connection.
        :param serve_hostport:
            String in the form ``$host:$port`` specifying an address at which
            the caller can be reached. If omitted, ``0.0.0.0:0`` is used.
        :param handler:
            If given, any calls received from this connection will be sent to
            this RequestHandler.
        """
        host, port = hostport.rsplit(":", 1)
        process_name = process_name or "%s[%s]" % (sys.argv[0], os.getpid())
        serve_hostport = serve_hostport or "0.0.0.0:0"

        # TODO: change this to tornado.tcpclient.TCPClient to do async DNS
        # lookups.
        stream = tornado.iostream.IOStream(
            socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        )

        log.debug("Connecting to %s", hostport)
        try:
            yield stream.connect((host, int(port)))

            connection = cls(stream, tchannel, direction=OUTGOING)

            log.debug("Performing handshake with %s", hostport)

            yield connection.initiate_handshake(headers={
                'host_port': serve_hostport,
                'process_name': process_name,
                'tchannel_language': TCHANNEL_LANGUAGE,
                'tchannel_language_version': TCHANNEL_LANGUAGE_VERSION,
                'tchannel_version': TCHANNEL_VERSION,
            })
        except (StreamClosedError, socket.error, errors.TimeoutError) as e:
            log.warn("Couldn't connect to %s", hostport)
            raise NetworkError(
                "Couldn't connect to %s" % hostport, e
            )

        if handler:
            connection.serve(handler)

        raise tornado.gen.Return(connection)

Response: Initiate a new connection to the given host.


Instruction:
Implement a function in Python 3 to
serve calls over this connection using the given RequestHandler.

Response:
def serve(self, handler):
        """Serve calls over this connection using the given RequestHandler.

        :param handler:
            RequestHandler to process the requests through
        :return:
            A Future that resolves (to None) once the loop is done running --
            which happens once this connection is closed.
        """
        assert handler, "handler is required"

        while not self.closed:
            message = yield self.await()

            try:
                handler(message, self)
            except Exception:
                # TODO Send error frame back
                log.exception("Failed to process %s", repr(message))


Instruction:
Can you generate the documentation for the following Python 3 function
def send_error(self, error):

        error_message = build_raw_error_message(error)
        write_future = self.writer.put(error_message)
        write_future.add_done_callback(
            lambda f: IOLoop.current().add_callback(
                self.tchannel.event_emitter.fire(
                    EventType.after_send_error,
                    error,
                )
            )
        )
        return write_future

Response: Convenience method for writing an error message up the wire.


Instruction:
Create a Python 3 function to
transform request or response into frames

Response:
def _stream(self, context, message_factory):
        """write request/response into frames

        Transform request/response into protocol level message objects based on
        types and argstreams.

        Assumption: the chunk data read from stream can fit into memory.

        If arg stream is at init or streaming state, build the message based on
        current chunk. If arg stream is at completed state, put current chunk
        into args[] array, and continue to read next arg stream in order to
        compose a larger message instead of sending multi small messages.

        Note: the message built at this stage is not guaranteed the size is
        less then 64KB.

        Possible messages created sequence:

        Take request as an example::
        CallRequestMessage(flags=fragment)
            --> CallRequestContinueMessage(flags=fragment)
            ....
            --> CallRequestContinueMessage(flags=fragment)
                --> CallRequestMessage(flags=none)

        :param context: Request or Response object
        """
        args = []
        try:
            for argstream in context.argstreams:
                chunk = yield argstream.read()
                args.append(chunk)
                chunk = yield argstream.read()
                while chunk:
                    message = (message_factory.
                               build_raw_message(context, args))
                    yield self.write(message)
                    args = [chunk]
                    chunk = yield argstream.read()

            # last piece of request/response.
            message = (message_factory.
                       build_raw_message(context, args, is_completed=True))
            yield self.write(message)
            context.state = StreamState.completed
        # Stop streamming immediately if exception occurs on the handler side
        except TChannelError:
            # raise by tchannel intentionally
            log.info("Stopped outgoing streams because of an error",
                     exc_info=sys.exc_info())


Instruction:
How would you explain what the following Python 3 function does
def stream_request(self, request, out_future):
        request.close_argstreams()

        def on_done(future):
            if future.exception() and out_future.running():
                out_future.set_exc_info(future.exc_info())
            request.close_argstreams(force=True)

        stream_future = self._stream(request, self.request_message_factory)
        stream_future.add_done_callback(on_done)
        return stream_future

Response: send the given request and response is not required


Instruction:
Write a Python 3 function for
sending the given request and return a future that will be returned.

Response:
def send_request(self, request):
        """Send the given request and response is required.

        Use this for messages which have a response message.

        :param request:
            request to send
        :returns:
            A Future containing the response for the request
        """
        assert self._handshake_performed, "Perform a handshake first."

        assert request.id not in self._outbound_pending_call, (
            "Message ID '%d' already being used" % request.id
        )

        future = tornado.gen.Future()
        self._outbound_pending_call[request.id] = future
        self.add_pending_outbound()
        self.stream_request(request, future).add_done_callback(
            lambda f: self.remove_pending_outbound()
        )

        if request.ttl:
            self._add_timeout(request, future)

        # the actual future that caller will yield
        response_future = tornado.gen.Future()
        # TODO: fire before_receive_response

        IOLoop.current().add_future(
            future,
            lambda f: self.adapt_result(f, request, response_future),
        )
        return response_future


Instruction:
How would you code a function in Python 3 to
add a timeout for the given request to the given future.

Response:
def _add_timeout(self, request, future):
        """Adds a timeout for the given request to the given future."""
        io_loop = IOLoop.current()
        t = io_loop.call_later(
            request.ttl,
            self._request_timed_out,
            request.id,
            request.service,
            request.ttl,
            future,
        )
        io_loop.add_future(future, lambda f: io_loop.remove_timeout(t))


Instruction:
Given the following Python 3 function, write the documentation
def get(self):
        if not self.filling:
            self.fill()

        answer = tornado.gen.Future()

        def _on_result(future):
            if future.exception():
                return answer.set_exc_info(future.exc_info())
            answer.set_result(future.result())

        def _on_item(future):
            if future.exception():
                return answer.set_exc_info(future.exc_info())
            future.result().add_done_callback(_on_result)

        self.queue.get().add_done_callback(_on_item)
        return answer

Response: Receive the next message off the wire.


Instruction:
Can you generate the documentation for the following Python 3 function
def put(self, message):
        if self.draining is False:
            self.drain()

        return self._enqueue(message)

Response: Enqueues the given message for writing to the wire.


Instruction:
Implement a Python 3 function for
making a service available on the Hyperbahn routing mesh. This will make contact with a Hyperbahn host from a list of known Hyperbahn routers. Additional Hyperbahn connections will be established once contact has been made with the network. :param router: A seed list of addresses of Hyperbahn routers, e.g., ``["127.0.0.1:23000"]``. :param name: The identity of this service on the Hyperbahn. This is usually unnecessary, as it defaults to the name given when initializing the :py:class:`TChannel` (which is used as your identity as a caller). :returns: A future that resolves to the remote server's response after the first advertise finishes. Advertisement will continue to happen periodically.

Response:
def advertise(
        self,
        routers=None,
        name=None,
        timeout=None,
        router_file=None,
        jitter=None,
    ):
        """Make a service available on the Hyperbahn routing mesh.

        This will make contact with a Hyperbahn host from a list of known
        Hyperbahn routers. Additional Hyperbahn connections will be established
        once contact has been made with the network.

        :param router:
            A seed list of addresses of Hyperbahn routers, e.g.,
            ``["127.0.0.1:23000"]``.

        :param name:
            The identity of this service on the Hyperbahn.

            This is usually unnecessary, as it defaults to the name given when
            initializing the :py:class:`TChannel` (which is used as your
            identity as a caller).

        :returns:
            A future that resolves to the remote server's response after
            the first advertise finishes.

            Advertisement will continue to happen periodically.
        """
        name = name or self.name

        if not self.is_listening():
            self.listen()

        return hyperbahn.advertise(
            self,
            name,
            routers,
            timeout,
            router_file,
            jitter,
        )


Instruction:
Can you tell what is the following Python 3 function doing
def request(self,
                hostport=None,
                service=None,
                arg_scheme=None,
                retry=None,
                **kwargs):
        """Initiate a new request through this TChannel.

        :param hostport:
            Host to which the request will be made. If unspecified, a random
            known peer will be picked. This is not necessary if using
            Hyperbahn.

        :param service:
            The name of a service available on Hyperbahn. Defaults to an empty
            string.

        :param arg_scheme:
            Determines the serialization scheme for the request. One of 'raw',
            'json', or 'thrift'. Defaults to 'raw'.

        :param rety:
            One of 'n' (never retry), 'c' (retry on connection errors), 't'
            (retry on timeout), 'ct' (retry on connection errors and timeouts).

            Defaults to 'c'.
        """
        # TODO disallow certain parameters or don't propagate them backwards.
        # For example, blacklist and rank threshold aren't really
        # user-configurable right now.
        return self.peers.request(hostport=hostport,
                                  service=service,
                                  arg_scheme=arg_scheme,
                                  retry=retry,
                                  **kwargs)

Response: Initiate a new request through this TChannel.