if self.kind != Kind.CLIENT:<EOL><INDENT>return<EOL><DEDENT>remote_endpoint = create_endpoint(<EOL>port=port,<EOL>service_name=service_name,<EOL>host=host,<EOL>)<EOL>if not self.logging_context:<EOL><INDENT>if self.remote_endpoint is not None:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>self.remote_endpoint = remote_endpoint<EOL><DEDENT>else:<EOL><INDENT>if self.logging_context.remote_endpoint is not None:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>self.logging_context.remote_endpoint = remote_endpoint<EOL><DEDENT>

Adds a 'sa' binary annotation to the current span.

        'sa' binary annotations are useful for situations where you need to log
        where a request is going but the destination doesn't support zipkin.

        Note that the span must have 'cs'/'cr' annotations.

        :param port: The port number of the destination
        :type port: int
        :param service_name: The name of the destination service
        :type service_name: str
        :param host: Host address of the destination
        :type host: str


self.span_name = name<EOL>if self.logging_context:<EOL><INDENT>self.logging_context.span_name = name<EOL><DEDENT>

Overrides the current span name.

        This is useful if you don't know the span name yet when you create the
        zipkin_span object. i.e. pyramid_zipkin doesn't know which route the
        request matched until the function wrapped by the context manager
        completes.

        :param name: New span name
        :type name: str


_validate_args(kwargs)<EOL>kwargs['<STR_LIT>'] = Kind.CLIENT<EOL>super(zipkin_client_span, self).__init__(*args, **kwargs)<EOL>

Logs a zipkin span with client annotations.

        See :class:`zipkin_span` for arguments


_validate_args(kwargs)<EOL>kwargs['<STR_LIT>'] = Kind.SERVER<EOL>super(zipkin_server_span, self).__init__(*args, **kwargs)<EOL>

Logs a zipkin span with server annotations.

        See :class:`zipkin_span` for arguments


def create_annotation(timestamp, value, host):

return zipkin_core.Annotation(timestamp=timestamp, value=value, host=host)<EOL>

Create a zipkin annotation object

:param timestamp: timestamp of when the annotation occured in microseconds
:param value: name of the annotation, such as 'sr'
:param host: zipkin endpoint object

:returns: zipkin annotation object


def create_binary_annotation(key, value, annotation_type, host):

return zipkin_core.BinaryAnnotation(<EOL>key=key,<EOL>value=value,<EOL>annotation_type=annotation_type,<EOL>host=host,<EOL>)<EOL>

Create a zipkin binary annotation object

:param key: name of the annotation, such as 'http.uri'
:param value: value of the annotation, such as a URI
:param annotation_type: type of annotation, such as AnnotationType.I32
:param host: zipkin endpoint object

:returns: zipkin binary annotation object


def create_endpoint(port=<NUM_LIT:0>, service_name='<STR_LIT>', ipv4=None, ipv6=None):

ipv4_int = <NUM_LIT:0><EOL>ipv6_binary = None<EOL>if ipv4:<EOL><INDENT>ipv4_int = struct.unpack('<STR_LIT>', socket.inet_pton(socket.AF_INET, ipv4))[<NUM_LIT:0>]<EOL><DEDENT>if ipv6:<EOL><INDENT>ipv6_binary = socket.inet_pton(socket.AF_INET6, ipv6)<EOL><DEDENT>port = struct.unpack('<STR_LIT:h>', struct.pack('<STR_LIT:H>', port))[<NUM_LIT:0>]<EOL>return zipkin_core.Endpoint(<EOL>ipv4=ipv4_int,<EOL>ipv6=ipv6_binary,<EOL>port=port,<EOL>service_name=service_name,<EOL>)<EOL>

Create a zipkin Endpoint object.

    An Endpoint object holds information about the network context of a span.

    :param port: int value of the port. Defaults to 0
    :param service_name: service name as a str. Defaults to 'unknown'
    :param ipv4: ipv4 host address
    :param ipv6: ipv6 host address
    :returns: thrift Endpoint object


return zipkin_core.Endpoint(<EOL>ipv4=endpoint.ipv4,<EOL>port=endpoint.port,<EOL>service_name=service_name,<EOL>)<EOL>

Copies a copy of a given endpoint with a new service name.
    This should be very fast, on the order of several microseconds.

    :param endpoint: existing zipkin_core.Endpoint object
    :param service_name: str of new service name
    :returns: zipkin Endpoint object


return [<EOL>create_annotation(int(timestamp * <NUM_LIT>), key, host)<EOL>for key, timestamp in annotations.items()<EOL>]<EOL>

Reformat annotations dict to return list of corresponding zipkin_core objects.

:param annotations: dict containing key as annotation name,
                    value being timestamp in seconds(float).
:type host: :class:`zipkin_core.Endpoint`
:returns: a list of annotation zipkin_core objects
:rtype: list


<EOL>ann_type = zipkin_core.AnnotationType.STRING<EOL>return [<EOL>create_binary_annotation(key, str(value), ann_type, host)<EOL>for key, value in binary_annotations.items()<EOL>]<EOL>

Reformat binary annotations dict to return list of zipkin_core objects. The
value of the binary annotations MUST be in string format.

:param binary_annotations: dict with key, value being the name and value
                           of the binary annotation being logged.
:type host: :class:`zipkin_core.Endpoint`
:returns: a list of binary annotation zipkin_core objects
:rtype: list


<EOL>trace_id_length = len(trace_id)<EOL>trace_id_high = None<EOL>if trace_id_length > <NUM_LIT:16>:<EOL><INDENT>assert trace_id_length == <NUM_LIT:32><EOL>trace_id, trace_id_high = trace_id[<NUM_LIT:16>:], trace_id[:<NUM_LIT:16>]<EOL><DEDENT>if trace_id_high:<EOL><INDENT>trace_id_high = unsigned_hex_to_signed_int(trace_id_high)<EOL><DEDENT>span_dict = {<EOL>'<STR_LIT>': unsigned_hex_to_signed_int(trace_id),<EOL>'<STR_LIT:name>': span_name,<EOL>'<STR_LIT:id>': unsigned_hex_to_signed_int(span_id),<EOL>'<STR_LIT>': annotations,<EOL>'<STR_LIT>': binary_annotations,<EOL>'<STR_LIT>': int(timestamp_s * <NUM_LIT>) if timestamp_s else None,<EOL>'<STR_LIT>': int(duration_s * <NUM_LIT>) if duration_s else None,<EOL>'<STR_LIT>': trace_id_high,<EOL>}<EOL>if parent_span_id:<EOL><INDENT>span_dict['<STR_LIT>'] = unsigned_hex_to_signed_int(parent_span_id)<EOL><DEDENT>return zipkin_core.Span(**span_dict)<EOL>

Takes a bunch of span attributes and returns a thriftpy2 representation
    of the span. Timestamps passed in are in seconds, they're converted to
    microseconds before thrift encoding.


transport = TMemoryBuffer()<EOL>protocol = TBinaryProtocol(transport)<EOL>thrift_span.write(protocol)<EOL>return bytes(transport.getvalue())<EOL>

Returns a TBinaryProtocol encoded Thrift span.

:param thrift_span: thrift object to encode.
:returns: thrift object in TBinaryProtocol format bytes.


transport = TMemoryBuffer()<EOL>write_list_begin(transport, TType.STRUCT, len(binary_thrift_obj_list))<EOL>for thrift_bin in binary_thrift_obj_list:<EOL><INDENT>transport.write(thrift_bin)<EOL><DEDENT>return bytes(transport.getvalue())<EOL>

Returns a TBinaryProtocol encoded list of Thrift objects.

:param binary_thrift_obj_list: list of TBinaryProtocol objects to encode.
:returns: bynary object representing the encoded list.


if not hasattr(_thread_local_tracer, '<STR_LIT>'):<EOL><INDENT>_thread_local_tracer.tracer = Tracer()<EOL><DEDENT>return _thread_local_tracer.tracer<EOL>

Returns the current tracer from thread-local.

    If there's no current tracer it'll create a new one.
    :returns: current tracer.
    :rtype: Tracer


_thread_local_tracer.tracer = tracer<EOL>

Sets the current tracer in thread-local.

    :param tracer: current tracer.
    :type tracer: Tracer


try:<EOL><INDENT>return _contextvars_tracer.get()<EOL><DEDENT>except LookupError:<EOL><INDENT>_contextvars_tracer.set(Tracer())<EOL>return _contextvars_tracer.get()<EOL><DEDENT>

Returns the current tracer from contextvars.

    If there's no current tracer it'll create a new one.
    :returns: current tracer.
    :rtype: Tracer


Sets the current tracer in contextvars.

    :param tracer: current tracer.
    :type tracer: Tracer


if _contextvars_tracer:<EOL><INDENT>return _get_contextvars_tracer()<EOL><DEDENT>return _get_thread_local_tracer()<EOL>

Return the current default Tracer.

    For now it'll get it from thread-local in Python 2.7 to 3.6 and from
    contextvars since Python 3.7.

    :returns: current default tracer.
    :rtype: Tracer


if _contextvars_tracer:<EOL><INDENT>return _set_contextvars_tracer(tracer)<EOL><DEDENT>return _set_thread_local_tracer(tracer)<EOL>

Sets the current default Tracer.

    For now it'll get it from thread-local in Python 2.7 to 3.6 and from
    contextvars since Python 3.7.

    :returns: current default tracer.
    :rtype: Tracer


def create_endpoint(port=None, service_name=None, host=None, use_defaults=True):

if use_defaults:<EOL><INDENT>if port is None:<EOL><INDENT>port = <NUM_LIT:0><EOL><DEDENT>if service_name is None:<EOL><INDENT>service_name = '<STR_LIT>'<EOL><DEDENT>if host is None:<EOL><INDENT>try:<EOL><INDENT>host = socket.gethostbyname(socket.gethostname())<EOL><DEDENT>except socket.gaierror:<EOL><INDENT>host = '<STR_LIT:127.0.0.1>'<EOL><DEDENT><DEDENT><DEDENT>ipv4 = None<EOL>ipv6 = None<EOL>if host:<EOL><INDENT>try:<EOL><INDENT>socket.inet_pton(socket.AF_INET, host)<EOL>ipv4 = host<EOL><DEDENT>except socket.error:<EOL><INDENT>try:<EOL><INDENT>socket.inet_pton(socket.AF_INET6, host)<EOL>ipv6 = host<EOL><DEDENT>except socket.error:<EOL><INDENT>pass<EOL><DEDENT><DEDENT><DEDENT>return Endpoint(<EOL>ipv4=ipv4,<EOL>ipv6=ipv6,<EOL>port=port,<EOL>service_name=service_name,<EOL>)<EOL>

Creates a new Endpoint object.

    :param port: TCP/UDP port. Defaults to 0.
    :type port: int
    :param service_name: service name as a str. Defaults to 'unknown'.
    :type service_name: str
    :param host: ipv4 or ipv6 address of the host. Defaults to the
    current host ip.
    :type host: str
    :param use_defaults: whether to use defaults.
    :type use_defaults: bool
    :returns: zipkin Endpoint object


return Endpoint(<EOL>service_name=new_service_name,<EOL>ipv4=endpoint.ipv4,<EOL>ipv6=endpoint.ipv6,<EOL>port=endpoint.port,<EOL>)<EOL>

Creates a copy of a given endpoint with a new service name.

    :param endpoint: existing Endpoint object
    :type endpoint: Endpoint
    :param new_service_name: new service name
    :type new_service_name: str
    :returns: zipkin new Endpoint object


self.trace_id = trace_id<EOL>self.name = name<EOL>self.parent_id = parent_id<EOL>self.span_id = span_id<EOL>self.kind = kind<EOL>self.timestamp = timestamp<EOL>self.duration = duration<EOL>self.local_endpoint = local_endpoint<EOL>self.remote_endpoint = remote_endpoint<EOL>self.debug = debug<EOL>self.shared = shared<EOL>self.annotations = annotations or {}<EOL>self.tags = tags or {}<EOL>if not isinstance(kind, Kind):<EOL><INDENT>raise ZipkinError(<EOL>'<STR_LIT>'.format(kind))<EOL><DEDENT>if local_endpoint and not isinstance(local_endpoint, Endpoint):<EOL><INDENT>raise ZipkinError(<EOL>'<STR_LIT>')<EOL><DEDENT>if remote_endpoint and not isinstance(remote_endpoint, Endpoint):<EOL><INDENT>raise ZipkinError(<EOL>'<STR_LIT>')<EOL><DEDENT>

Creates a new Span.

        :param trace_id: Trace id.
        :type trace_id: str
        :param name: Name of the span.
        :type name: str
        :param parent_id: Parent span id.
        :type parent_id: str
        :param span_id: Span id.
        :type span_id: str
        :param kind: Span type (client, server, local, etc...)
        :type kind: Kind
        :param timestamp: start timestamp in seconds.
        :type timestamp: float
        :param duration: span duration in seconds.
        :type duration: float
        :param local_endpoint: the host that recorded this span.
        :type local_endpoint: Endpoint
        :param remote_endpoint: the remote service.
        :type remote_endpoint: Endpoint
        :param debug: True is a request to store this span even if it
            overrides sampling policy.
        :type debug: bool
        :param shared: True if we are contributing to a span started by
            another tracer (ex on a different host).
        :type shared: bool
        :param annotations: Optional dict of str -> timestamp annotations.
        :type annotations: dict
        :param tags: Optional dict of str -> str span tags.
        :type tags: dict


return self.__dict__ == other.__dict__<EOL>

Compare function to help assert span1 == span2 in py3


Compare function to help assert span1 == span2 in py2


return str(self.__dict__)<EOL>

Compare function to nicely print Span rather than just the pointer


<EOL>full_annotations = OrderedDict([<EOL>('<STR_LIT>', self.timestamp),<EOL>('<STR_LIT>', self.timestamp),<EOL>('<STR_LIT>', self.timestamp + self.duration),<EOL>('<STR_LIT>', self.timestamp + self.duration),<EOL>])<EOL>if self.kind != Kind.LOCAL:<EOL><INDENT>for ann in _DROP_ANNOTATIONS_BY_KIND[self.kind]:<EOL><INDENT>del full_annotations[ann]<EOL><DEDENT><DEDENT>full_annotations.update(self.annotations)<EOL>return _V1Span(<EOL>trace_id=self.trace_id,<EOL>name=self.name,<EOL>parent_id=self.parent_id,<EOL>id=self.span_id,<EOL>timestamp=self.timestamp if self.shared is False else None,<EOL>duration=self.duration if self.shared is False else None,<EOL>endpoint=self.local_endpoint,<EOL>annotations=full_annotations,<EOL>binary_annotations=self.tags,<EOL>remote_endpoint=self.remote_endpoint,<EOL>)<EOL>

Builds and returns a V1 Span.

        :return: newly generated _V1Span
        :rtype: _V1Span


if encoding == Encoding.V1_THRIFT:<EOL><INDENT>return _V1ThriftEncoder()<EOL><DEDENT>if encoding == Encoding.V1_JSON:<EOL><INDENT>return _V1JSONEncoder()<EOL><DEDENT>if encoding == Encoding.V2_JSON:<EOL><INDENT>return _V2JSONEncoder()<EOL><DEDENT>if encoding == Encoding.V2_PROTO3:<EOL><INDENT>return _V2ProtobufEncoder()<EOL><DEDENT>raise ZipkinError('<STR_LIT>'.format(encoding))<EOL>

Creates encoder object for the given encoding.

    :param encoding: desired output encoding protocol.
    :type encoding: Encoding
    :return: corresponding IEncoder object
    :rtype: IEncoder


def fits(self, current_count, current_size, max_size, new_span):

raise NotImplementedError()<EOL>

Returns whether the new span will fit in the list.

        :param current_count: number of spans already in the list.
        :type current_count: int
        :param current_size: sum of the sizes of all the spans already in the list.
        :type current_size: int
        :param max_size: max supported transport payload size.
        :type max_size: int
        :param new_span: encoded span object that we want to add the the list.
        :type new_span: str or bytes
        :return: True if the new span can be added to the list, False otherwise.
        :rtype: bool


raise NotImplementedError()<EOL>

Encodes a single span.

        :param span: Span object representing the span.
        :type span: Span
        :return: encoded span.
        :rtype: str or bytes


raise NotImplementedError()<EOL>

Encodes a list of pre-encoded spans.

        :param queue: list of encoded spans.
        :type queue: list
        :return: encoded list, type depends on the encoding.
        :rtype: str or bytes


return thrift.LIST_HEADER_SIZE + current_size + len(new_span) <= max_size<EOL>

Checks if the new span fits in the max payload size.

        Thrift lists have a fixed-size header and no delimiters between elements
        so it's easy to compute the list size.


return thrift.encode_bytes_list(queue)<EOL>


return <NUM_LIT:2> + current_count + current_size + len(new_span) <= max_size<EOL>

Checks if the new span fits in the max payload size.

        Json lists only have a 2 bytes overhead from '[]' plus 1 byte from
        ',' between elements


def _create_json_endpoint(self, endpoint, is_v1):

json_endpoint = {}<EOL>if endpoint.service_name:<EOL><INDENT>json_endpoint['<STR_LIT>'] = endpoint.service_name<EOL><DEDENT>elif is_v1:<EOL><INDENT>json_endpoint['<STR_LIT>'] = "<STR_LIT>"<EOL><DEDENT>if endpoint.port and endpoint.port != <NUM_LIT:0>:<EOL><INDENT>json_endpoint['<STR_LIT:port>'] = endpoint.port<EOL><DEDENT>if endpoint.ipv4 is not None:<EOL><INDENT>json_endpoint['<STR_LIT>'] = endpoint.ipv4<EOL><DEDENT>if endpoint.ipv6 is not None:<EOL><INDENT>json_endpoint['<STR_LIT>'] = endpoint.ipv6<EOL><DEDENT>return json_endpoint<EOL>

Converts an Endpoint to a JSON endpoint dict.

        :param endpoint: endpoint object to convert.
        :type endpoint: Endpoint
        :param is_v1: whether we're serializing a v1 span. This is needed since
            in v1 some fields default to an empty string rather than being
            dropped if they're not set.
        :type is_v1: bool
        :return: dict representing a JSON endpoint.
        :rtype: dict


return '<STR_LIT:[>' + '<STR_LIT:U+002C>'.join(queue) + '<STR_LIT:]>'<EOL>


span = v2_span.build_v1_span()<EOL>json_span = {<EOL>'<STR_LIT>': span.trace_id,<EOL>'<STR_LIT:name>': span.name,<EOL>'<STR_LIT:id>': span.id,<EOL>'<STR_LIT>': [],<EOL>'<STR_LIT>': [],<EOL>}<EOL>if span.parent_id:<EOL><INDENT>json_span['<STR_LIT>'] = span.parent_id<EOL><DEDENT>if span.timestamp:<EOL><INDENT>json_span['<STR_LIT>'] = int(span.timestamp * <NUM_LIT>)<EOL><DEDENT>if span.duration:<EOL><INDENT>json_span['<STR_LIT>'] = int(span.duration * <NUM_LIT>)<EOL><DEDENT>v1_endpoint = self._create_json_endpoint(span.endpoint, True)<EOL>for key, timestamp in span.annotations.items():<EOL><INDENT>json_span['<STR_LIT>'].append({<EOL>'<STR_LIT>': v1_endpoint,<EOL>'<STR_LIT>': int(timestamp * <NUM_LIT>),<EOL>'<STR_LIT:value>': key,<EOL>})<EOL><DEDENT>for key, value in span.binary_annotations.items():<EOL><INDENT>json_span['<STR_LIT>'].append({<EOL>'<STR_LIT:key>': key,<EOL>'<STR_LIT:value>': value,<EOL>'<STR_LIT>': v1_endpoint,<EOL>})<EOL><DEDENT>if v2_span.remote_endpoint:<EOL><INDENT>self.encode_remote_endpoint(<EOL>v2_span.remote_endpoint,<EOL>v2_span.kind,<EOL>json_span['<STR_LIT>'],<EOL>)<EOL><DEDENT>encoded_span = json.dumps(json_span)<EOL>return encoded_span<EOL>


json_span = {<EOL>'<STR_LIT>': span.trace_id,<EOL>'<STR_LIT:id>': span.span_id,<EOL>}<EOL>if span.name:<EOL><INDENT>json_span['<STR_LIT:name>'] = span.name<EOL><DEDENT>if span.parent_id:<EOL><INDENT>json_span['<STR_LIT>'] = span.parent_id<EOL><DEDENT>if span.timestamp:<EOL><INDENT>json_span['<STR_LIT>'] = int(span.timestamp * <NUM_LIT>)<EOL><DEDENT>if span.duration:<EOL><INDENT>json_span['<STR_LIT>'] = int(span.duration * <NUM_LIT>)<EOL><DEDENT>if span.shared is True:<EOL><INDENT>json_span['<STR_LIT>'] = True<EOL><DEDENT>if span.kind and span.kind.value is not None:<EOL><INDENT>json_span['<STR_LIT>'] = span.kind.value<EOL><DEDENT>if span.local_endpoint:<EOL><INDENT>json_span['<STR_LIT>'] = self._create_json_endpoint(<EOL>span.local_endpoint,<EOL>False,<EOL>)<EOL><DEDENT>if span.remote_endpoint:<EOL><INDENT>json_span['<STR_LIT>'] = self._create_json_endpoint(<EOL>span.remote_endpoint,<EOL>False,<EOL>)<EOL><DEDENT>if span.tags and len(span.tags) > <NUM_LIT:0>:<EOL><INDENT>json_span['<STR_LIT>'] = span.tags<EOL><DEDENT>if span.annotations:<EOL><INDENT>json_span['<STR_LIT>'] = [<EOL>{<EOL>'<STR_LIT>': int(timestamp * <NUM_LIT>),<EOL>'<STR_LIT:value>': key,<EOL>}<EOL>for key, timestamp in span.annotations.items()<EOL>]<EOL><DEDENT>encoded_span = json.dumps(json_span)<EOL>return encoded_span<EOL>


return current_size + len(new_span) <= max_size<EOL>

Checks if the new span fits in the max payload size.


if not protobuf.installed():<EOL><INDENT>raise ZipkinError(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>'<EOL>)<EOL><DEDENT>pb_span = protobuf.create_protobuf_span(span)<EOL>return protobuf.encode_pb_list([pb_span])<EOL>


return b'<STR_LIT>'.join(queue)<EOL>

Concatenates the list to a protobuf list and encodes it to bytes


<EOL>if isinstance(message, six.string_types):<EOL><INDENT>if six.PY2:<EOL><INDENT>message = six.b(message)  <EOL><DEDENT>else:<EOL><INDENT>message = message.encode('<STR_LIT:utf-8>')  <EOL><DEDENT><DEDENT>if len(message) < <NUM_LIT:2>:<EOL><INDENT>raise ZipkinError("<STR_LIT>")<EOL><DEDENT>if six.byte2int(message) <= <NUM_LIT:16>:<EOL><INDENT>if six.byte2int(message) == <NUM_LIT:10> and six.byte2int(message[<NUM_LIT:1>:<NUM_LIT:2>]) != <NUM_LIT:0>:<EOL><INDENT>return Encoding.V2_PROTO3<EOL><DEDENT>return Encoding.V1_THRIFT<EOL><DEDENT>str_msg = message.decode('<STR_LIT:utf-8>')<EOL>if str_msg[<NUM_LIT:0>] == '<STR_LIT:[>':<EOL><INDENT>span_list = json.loads(str_msg)<EOL>if len(span_list) > <NUM_LIT:0>:<EOL><INDENT>for span in span_list:<EOL><INDENT>if any(word in span for word in _V2_ATTRIBUTES):<EOL><INDENT>return Encoding.V2_JSON<EOL><DEDENT>elif (<EOL>'<STR_LIT>' in span or<EOL>(<EOL>'<STR_LIT>' in span and<EOL>'<STR_LIT>' in span['<STR_LIT>']<EOL>)<EOL>):<EOL><INDENT>return Encoding.V1_JSON<EOL><DEDENT><DEDENT>return Encoding.V2_JSON<EOL><DEDENT><DEDENT>raise ZipkinError("<STR_LIT>")<EOL>

Returns the span type and encoding for the message provided.

    The logic in this function is a Python port of
    https://github.com/openzipkin/zipkin/blob/master/zipkin/src/main/java/zipkin/internal/DetectingSpanDecoder.java

    :param message: span to perform operations on.
    :type message: byte array
    :returns: span encoding.
    :rtype: Encoding


def convert_spans(spans, output_encoding, input_encoding=None):

if not isinstance(input_encoding, Encoding):<EOL><INDENT>input_encoding = detect_span_version_and_encoding(message=spans)<EOL><DEDENT>if input_encoding == output_encoding:<EOL><INDENT>return spans<EOL><DEDENT>decoder = get_decoder(input_encoding)<EOL>encoder = get_encoder(output_encoding)<EOL>decoded_spans = decoder.decode_spans(spans)<EOL>output_spans = []<EOL>for span in decoded_spans:<EOL><INDENT>output_spans.append(encoder.encode_span(span))<EOL><DEDENT>return encoder.encode_queue(output_spans)<EOL>

Converts encoded spans to a different encoding.

    param spans: encoded input spans.
    type spans: byte array
    param output_encoding: desired output encoding.
    type output_encoding: Encoding
    param input_encoding: optional input encoding. If this is not specified, it'll
        try to understand the encoding automatically by inspecting the input spans.
    type input_encoding: Encoding
    :returns: encoded spans.
    :rtype: byte array


if encoding == Encoding.V1_THRIFT:<EOL><INDENT>return _V1ThriftDecoder()<EOL><DEDENT>if encoding == Encoding.V1_JSON:<EOL><INDENT>raise NotImplementedError(<EOL>'<STR_LIT>'.format(encoding))<EOL><DEDENT>if encoding == Encoding.V2_JSON:<EOL><INDENT>raise NotImplementedError(<EOL>'<STR_LIT>'.format(encoding))<EOL><DEDENT>raise ZipkinError('<STR_LIT>'.format(encoding))<EOL>

Creates encoder object for the given encoding.

    :param encoding: desired output encoding protocol
    :type encoding: Encoding
    :return: corresponding IEncoder object
    :rtype: IEncoder


raise NotImplementedError()<EOL>

Decodes an encoded list of spans.

        :param spans: encoded list of spans
        :type spans: bytes
        :return: list of spans
        :rtype: list of Span


decoded_spans = []<EOL>transport = TMemoryBuffer(spans)<EOL>if six.byte2int(spans) == TType.STRUCT:<EOL><INDENT>_, size = read_list_begin(transport)<EOL><DEDENT>else:<EOL><INDENT>size = <NUM_LIT:1><EOL><DEDENT>for _ in range(size):<EOL><INDENT>span = zipkin_core.Span()<EOL>span.read(TBinaryProtocol(transport))<EOL>decoded_spans.append(self._decode_thrift_span(span))<EOL><DEDENT>return decoded_spans<EOL>


ipv4 = None<EOL>ipv6 = None<EOL>port = struct.unpack('<STR_LIT:H>', struct.pack('<STR_LIT:h>', thrift_endpoint.port))[<NUM_LIT:0>]<EOL>if thrift_endpoint.ipv4 != <NUM_LIT:0>:<EOL><INDENT>ipv4 = socket.inet_ntop(<EOL>socket.AF_INET,<EOL>struct.pack('<STR_LIT>', thrift_endpoint.ipv4),<EOL>)<EOL><DEDENT>if thrift_endpoint.ipv6:<EOL><INDENT>ipv6 = socket.inet_ntop(socket.AF_INET6, thrift_endpoint.ipv6)<EOL><DEDENT>return Endpoint(<EOL>service_name=thrift_endpoint.service_name,<EOL>ipv4=ipv4,<EOL>ipv6=ipv6,<EOL>port=port,<EOL>)<EOL>

Accepts a thrift decoded endpoint and converts it to an Endpoint.

        :param thrift_endpoint: thrift encoded endpoint
        :type thrift_endpoint: thrift endpoint
        :returns: decoded endpoint
        :rtype: Encoding


local_endpoint = None<EOL>kind = Kind.LOCAL<EOL>all_annotations = {}<EOL>timestamp = None<EOL>duration = None<EOL>for thrift_annotation in thrift_annotations:<EOL><INDENT>all_annotations[thrift_annotation.value] = thrift_annotation.timestamp<EOL>if thrift_annotation.host:<EOL><INDENT>local_endpoint = self._convert_from_thrift_endpoint(<EOL>thrift_annotation.host,<EOL>)<EOL><DEDENT><DEDENT>if '<STR_LIT>' in all_annotations and '<STR_LIT>' not in all_annotations:<EOL><INDENT>kind = Kind.CLIENT<EOL>timestamp = all_annotations['<STR_LIT>']<EOL>duration = all_annotations['<STR_LIT>'] - all_annotations['<STR_LIT>']<EOL><DEDENT>elif '<STR_LIT>' not in all_annotations and '<STR_LIT>' in all_annotations:<EOL><INDENT>kind = Kind.SERVER<EOL>timestamp = all_annotations['<STR_LIT>']<EOL>duration = all_annotations['<STR_LIT>'] - all_annotations['<STR_LIT>']<EOL><DEDENT>annotations = {<EOL>name: self.seconds(ts) for name, ts in all_annotations.items()<EOL>if name not in _DROP_ANNOTATIONS<EOL>}<EOL>return annotations, local_endpoint, kind, timestamp, duration<EOL>

Accepts a thrift annotation and converts it to a v1 annotation.

        :param thrift_annotations: list of thrift annotations.
        :type thrift_annotations: list of zipkin_core.Span.Annotation
        :returns: (annotations, local_endpoint, kind)


tags = {}<EOL>local_endpoint = None<EOL>remote_endpoint = None<EOL>for binary_annotation in thrift_binary_annotations:<EOL><INDENT>if binary_annotation.key == '<STR_LIT>':<EOL><INDENT>remote_endpoint = self._convert_from_thrift_endpoint(<EOL>thrift_endpoint=binary_annotation.host,<EOL>)<EOL><DEDENT>else:<EOL><INDENT>key = binary_annotation.key<EOL>annotation_type = binary_annotation.annotation_type<EOL>value = binary_annotation.value<EOL>if annotation_type == zipkin_core.AnnotationType.BOOL:<EOL><INDENT>tags[key] = "<STR_LIT:true>" if value == <NUM_LIT:1> else "<STR_LIT:false>"<EOL><DEDENT>elif annotation_type == zipkin_core.AnnotationType.STRING:<EOL><INDENT>tags[key] = str(value)<EOL><DEDENT>else:<EOL><INDENT>log.warning('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT>if binary_annotation.host:<EOL><INDENT>local_endpoint = self._convert_from_thrift_endpoint(<EOL>thrift_endpoint=binary_annotation.host,<EOL>)<EOL><DEDENT><DEDENT><DEDENT>return tags, local_endpoint, remote_endpoint<EOL>

Accepts a thrift decoded binary annotation and converts it
        to a v1 binary annotation.


parent_id = None<EOL>local_endpoint = None<EOL>annotations = {}<EOL>tags = {}<EOL>kind = Kind.LOCAL<EOL>remote_endpoint = None<EOL>timestamp = None<EOL>duration = None<EOL>if thrift_span.parent_id:<EOL><INDENT>parent_id = self._convert_unsigned_long_to_lower_hex(<EOL>thrift_span.parent_id,<EOL>)<EOL><DEDENT>if thrift_span.annotations:<EOL><INDENT>annotations, local_endpoint, kind, timestamp, duration =self._decode_thrift_annotations(thrift_span.annotations)<EOL><DEDENT>if thrift_span.binary_annotations:<EOL><INDENT>tags, local_endpoint, remote_endpoint =self._convert_from_thrift_binary_annotations(<EOL>thrift_span.binary_annotations,<EOL>)<EOL><DEDENT>trace_id = self._convert_trace_id_to_string(<EOL>thrift_span.trace_id,<EOL>thrift_span.trace_id_high,<EOL>)<EOL>return Span(<EOL>trace_id=trace_id,<EOL>name=thrift_span.name,<EOL>parent_id=parent_id,<EOL>span_id=self._convert_unsigned_long_to_lower_hex(thrift_span.id),<EOL>kind=kind,<EOL>timestamp=self.seconds(timestamp or thrift_span.timestamp),<EOL>duration=self.seconds(duration or thrift_span.duration),<EOL>local_endpoint=local_endpoint,<EOL>remote_endpoint=remote_endpoint,<EOL>shared=(kind == Kind.SERVER and thrift_span.timestamp is None),<EOL>annotations=annotations,<EOL>tags=tags,<EOL>)<EOL>

Decodes a thrift span.

        :param thrift_span: thrift span
        :type thrift_span: thrift Span object
        :returns: span builder representing this span
        :rtype: Span


def _convert_trace_id_to_string(self, trace_id, trace_id_high=None):

if trace_id_high is not None:<EOL><INDENT>result = bytearray(<NUM_LIT:32>)<EOL>self._write_hex_long(result, <NUM_LIT:0>, trace_id_high)<EOL>self._write_hex_long(result, <NUM_LIT:16>, trace_id)<EOL>return result.decode("<STR_LIT:utf8>")<EOL><DEDENT>result = bytearray(<NUM_LIT:16>)<EOL>self._write_hex_long(result, <NUM_LIT:0>, trace_id)<EOL>return result.decode("<STR_LIT:utf8>")<EOL>

Converts the provided traceId hex value with optional high bits
to a string.

:param trace_id: the value of the trace ID
:type trace_id: int
:param trace_id_high: the high bits of the trace ID
:type trace_id: int
:returns: trace_id_high + trace_id as a string


result = bytearray(<NUM_LIT:16>)<EOL>self._write_hex_long(result, <NUM_LIT:0>, value)<EOL>return result.decode("<STR_LIT:utf8>")<EOL>

Converts the provided unsigned long value to a hex string.

:param value: the value to convert
:type value: unsigned long
:returns: value as a hex string


def _write_hex_long(self, data, pos, value):

self._write_hex_byte(data, pos + <NUM_LIT:0>, (value >> <NUM_LIT>) & <NUM_LIT>)<EOL>self._write_hex_byte(data, pos + <NUM_LIT:2>, (value >> <NUM_LIT>) & <NUM_LIT>)<EOL>self._write_hex_byte(data, pos + <NUM_LIT:4>, (value >> <NUM_LIT>) & <NUM_LIT>)<EOL>self._write_hex_byte(data, pos + <NUM_LIT:6>, (value >> <NUM_LIT:32>) & <NUM_LIT>)<EOL>self._write_hex_byte(data, pos + <NUM_LIT:8>, (value >> <NUM_LIT>) & <NUM_LIT>)<EOL>self._write_hex_byte(data, pos + <NUM_LIT:10>, (value >> <NUM_LIT:16>) & <NUM_LIT>)<EOL>self._write_hex_byte(data, pos + <NUM_LIT:12>, (value >> <NUM_LIT:8>) & <NUM_LIT>)<EOL>self._write_hex_byte(data, pos + <NUM_LIT>, (value & <NUM_LIT>))<EOL>

Writes an unsigned long value across a byte array.

:param data: the buffer to write the value to
:type data: bytearray
:param pos: the starting position
:type pos: int
:param value: the value to write
:type value: unsigned long


return zipkin_pb2 is not None<EOL>

Checks whether the protobud library is installed and can be used.

    :return: True if everything's fine, False otherwise
    :rtype: bool


pb_list = zipkin_pb2.ListOfSpans()<EOL>pb_list.spans.extend(pb_spans)<EOL>return pb_list.SerializeToString()<EOL>

Encode list of protobuf Spans to binary.

    :param pb_spans: list of protobuf Spans.
    :type pb_spans: list of zipkin_pb2.Span
    :return: encoded list.
    :rtype: bytes


<EOL>pb_kwargs = {}<EOL>pb_kwargs['<STR_LIT>'] = _hex_to_bytes(span.trace_id)<EOL>if span.parent_id:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = _hex_to_bytes(span.parent_id)<EOL><DEDENT>pb_kwargs['<STR_LIT:id>'] = _hex_to_bytes(span.span_id)<EOL>pb_kind = _get_protobuf_kind(span.kind)<EOL>if pb_kind:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = pb_kind<EOL><DEDENT>if span.name:<EOL><INDENT>pb_kwargs['<STR_LIT:name>'] = span.name<EOL><DEDENT>if span.timestamp:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = int(span.timestamp * <NUM_LIT:1000> * <NUM_LIT:1000>)<EOL><DEDENT>if span.duration:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = int(span.duration * <NUM_LIT:1000> * <NUM_LIT:1000>)<EOL><DEDENT>if span.local_endpoint:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = _convert_endpoint(span.local_endpoint)<EOL><DEDENT>if span.remote_endpoint:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = _convert_endpoint(span.remote_endpoint)<EOL><DEDENT>if len(span.annotations) > <NUM_LIT:0>:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = _convert_annotations(span.annotations)<EOL><DEDENT>if len(span.tags) > <NUM_LIT:0>:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = span.tags<EOL><DEDENT>if span.debug:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = span.debug<EOL><DEDENT>if span.shared:<EOL><INDENT>pb_kwargs['<STR_LIT>'] = span.shared<EOL><DEDENT>return zipkin_pb2.Span(**pb_kwargs)<EOL>

Converts a py_zipkin Span in a protobuf Span.

    :param span: py_zipkin Span to convert.
    :type span: py_zipkin.encoding.Span
    :return: protobuf's Span
    :rtype: zipkin_pb2.Span


if len(hex_id) <= <NUM_LIT:16>:<EOL><INDENT>int_id = unsigned_hex_to_signed_int(hex_id)<EOL>return struct.pack('<STR_LIT>', int_id)<EOL><DEDENT>else:<EOL><INDENT>high_id = unsigned_hex_to_signed_int(hex_id[:-<NUM_LIT:16>])<EOL>high_bin = struct.pack('<STR_LIT>', high_id)<EOL>low_id = unsigned_hex_to_signed_int(hex_id[-<NUM_LIT:16>:])<EOL>low_bin = struct.pack('<STR_LIT>', low_id)<EOL>return high_bin + low_bin<EOL><DEDENT>

Encodes to hexadecimal ids to big-endian binary.

    :param hex_id: hexadecimal id to encode.
    :type hex_id: str
    :return: binary representation.
    :type: bytes


if kind == Kind.CLIENT:<EOL><INDENT>return zipkin_pb2.Span.CLIENT<EOL><DEDENT>elif kind == Kind.SERVER:<EOL><INDENT>return zipkin_pb2.Span.SERVER<EOL><DEDENT>elif kind == Kind.PRODUCER:<EOL><INDENT>return zipkin_pb2.Span.PRODUCER<EOL><DEDENT>elif kind == Kind.CONSUMER:<EOL><INDENT>return zipkin_pb2.Span.CONSUMER<EOL><DEDENT>return None<EOL>

Converts py_zipkin's Kind to Protobuf's Kind.

    :param kind: py_zipkin's Kind.
    :type kind: py_zipkin.Kind
    :return: correcponding protobuf's kind value.
    :rtype: zipkin_pb2.Span.Kind


pb_endpoint = zipkin_pb2.Endpoint()<EOL>if endpoint.service_name:<EOL><INDENT>pb_endpoint.service_name = endpoint.service_name<EOL><DEDENT>if endpoint.port and endpoint.port != <NUM_LIT:0>:<EOL><INDENT>pb_endpoint.port = endpoint.port<EOL><DEDENT>if endpoint.ipv4:<EOL><INDENT>pb_endpoint.ipv4 = socket.inet_pton(socket.AF_INET, endpoint.ipv4)<EOL><DEDENT>if endpoint.ipv6:<EOL><INDENT>pb_endpoint.ipv6 = socket.inet_pton(socket.AF_INET6, endpoint.ipv6)<EOL><DEDENT>return pb_endpoint<EOL>

Converts py_zipkin's Endpoint to Protobuf's Endpoint.

    :param endpoint: py_zipkins' endpoint to convert.
    :type endpoint: py_zipkin.encoding.Endpoint
    :return: corresponding protobuf's endpoint.
    :rtype: zipkin_pb2.Endpoint


pb_annotations = []<EOL>for value, ts in annotations.items():<EOL><INDENT>pb_annotations.append(zipkin_pb2.Annotation(<EOL>timestamp=int(ts * <NUM_LIT:1000> * <NUM_LIT:1000>),<EOL>value=value,<EOL>))<EOL><DEDENT>return pb_annotations<EOL>

Converts py_zipkin's annotations dict to protobuf.

    :param annotations: annotations dict.
    :type annotations: dict
    :return: corresponding protobuf's list of annotations.
    :rtype: list


raise NotImplementedError('<STR_LIT>')<EOL>

Returns the maximum payload size for this transport.

        Most transports have a maximum packet size that can be sent. For example,
        UDP has a 65507 bytes MTU.
        py_zipkin automatically batches collected spans for performance reasons.
        The batch size is going to be the minimum between `get_max_payload_bytes`
        and `max_span_batch_size` from `zipkin_span`.

        If you don't want to enforce a max payload size, return None.

        :returns: max payload size in bytes or None.


Sends the encoded payload over the transport.

        :argument payload: encoded list of spans.


self.send(payload)<EOL>

Internal wrapper around `send`. Do not override.

        Mostly used to keep backward compatibility with older transports
        implemented as functions. However decoupling the function developers
        override and what's internally called by py_zipkin will allow us to add
        extra logic here in the future without having the users update their
        code every time.


session.install('<STR_LIT>')<EOL>session.run('<STR_LIT>',<EOL>'<STR_LIT>')<EOL>

Run flake8.
    Returns a failure if flake8 finds linting errors or sufficiently
    serious code quality issues.


session.install('<STR_LIT>', '<STR_LIT>')<EOL>_run_tests(session)<EOL>


@nox.session(python=['<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>'])<EOL>@nox.parametrize('<STR_LIT>',<EOL>['<STR_LIT>', '<STR_LIT>', '<STR_LIT>'])<EOL>def compatibility(session, install):

session.install('<STR_LIT>', '<STR_LIT>')<EOL>session.install(install)<EOL>_run_tests(session)<EOL>

Run the unit test suite with each support library and Python version.


session.install('<STR_LIT>', '<STR_LIT>')<EOL>session.install('<STR_LIT>')<EOL>session.run(<EOL>'<STR_LIT>',<EOL>'<STR_LIT>',<EOL>'<STR_LIT>',<EOL>'<STR_LIT>')<EOL>


def __init__(self, deja_vu_sans_path: str):

self._font = ImageFont.truetype(deja_vu_sans_path, <NUM_LIT>)<EOL>

Initializer for PilMeasurer.

        Args:
            deja_vu_sans_path: The path to the DejaVu Sans TrueType (.ttf) font
                file.


def text_width(self, text: str) -> float:

width, _ = self._font.getsize(text)<EOL>return width<EOL>

Returns the width, in pixels, of a string in DejaVu Sans 110pt.


def __init__(self, default_character_width: float,<EOL>char_to_width: Mapping[str, float],<EOL>pair_to_kern: Mapping[str, float]):

self._default_character_width = default_character_width<EOL>self._char_to_width = char_to_width<EOL>self._pair_to_kern = pair_to_kern<EOL>

Initializer for PrecalculatedTextMeasurer.

        Args:
            default_character_width: the average width, in pixels, of a
                character in DejaVu Sans 110pt.
            char_to_width: a mapping between a character and it's width,
                in pixels, in DejaVu Sans 110pt.
            pair_to_kern: a mapping between pairs of characters and the kerning
                distance between them e.g. text_width("IJ") =>
                    (char_to_width["I"] + char_to_width["J"]
                    - pair_to_kern.get("IJ", 0))


width = <NUM_LIT:0><EOL>for index, c in enumerate(text):<EOL><INDENT>width += self._char_to_width.get(c, self._default_character_width)<EOL>width -= self._pair_to_kern.get(text[index:index + <NUM_LIT:2>], <NUM_LIT:0>)<EOL><DEDENT>return width<EOL>


@staticmethod<EOL><INDENT>def from_json(f: TextIO) -> '<STR_LIT>':<DEDENT>

o = json.load(f)<EOL>return PrecalculatedTextMeasurer(o['<STR_LIT>'],<EOL>o['<STR_LIT>'],<EOL>o['<STR_LIT>'])<EOL>

Return a PrecalculatedTextMeasurer given a JSON stream.

        See precalculate_text.py for details on the required format.


@classmethod<EOL><INDENT>def default(cls) -> '<STR_LIT>':<DEDENT>

if cls._default_cache is not None:<EOL><INDENT>return cls._default_cache<EOL><DEDENT>if pkg_resources.resource_exists(__name__, '<STR_LIT>'):<EOL><INDENT>import lzma<EOL>with pkg_resources.resource_stream(__name__,<EOL>'<STR_LIT>') as f:<EOL><INDENT>with lzma.open(f, "<STR_LIT>") as g:<EOL><INDENT>cls._default_cache = PrecalculatedTextMeasurer.from_json(<EOL>cast(TextIO, g))<EOL>return cls._default_cache<EOL><DEDENT><DEDENT><DEDENT>elif pkg_resources.resource_exists(__name__, '<STR_LIT>'):<EOL><INDENT>with pkg_resources.resource_stream(__name__,<EOL>'<STR_LIT>') as f:<EOL><INDENT>cls._default_cache = PrecalculatedTextMeasurer.from_json(<EOL>io.TextIOWrapper(f, encoding='<STR_LIT:utf-8>'))<EOL>return cls._default_cache<EOL><DEDENT><DEDENT>else:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>

Returns a reasonable default PrecalculatedTextMeasurer.


def generate_supported_characters(deja_vu_sans_path: str) -> Iterable[str]:

font = ttLib.TTFont(deja_vu_sans_path)<EOL>for cmap in font['<STR_LIT>'].tables:<EOL><INDENT>if cmap.isUnicode():<EOL><INDENT>for code in cmap.cmap:<EOL><INDENT>yield chr(code)<EOL><DEDENT><DEDENT><DEDENT>

Generate the characters support by the font at the given path.


def generate_encodeable_characters(characters: Iterable[str],<EOL>encodings: Iterable[str]) -> Iterable[str]:

for c in characters:<EOL><INDENT>for encoding in encodings:<EOL><INDENT>try:<EOL><INDENT>c.encode(encoding)<EOL>yield c<EOL><DEDENT>except UnicodeEncodeError:<EOL><INDENT>pass<EOL><DEDENT><DEDENT><DEDENT>

Generates the subset of 'characters' that can be encoded by 'encodings'.

    Args:
        characters: The characters to check for encodeability e.g. 'abcd'.
        encodings: The encodings to check against e.g. ['cp1252', 'iso-8859-5'].

    Returns:
        The subset of 'characters' that can be encoded using one of the provided
        encodings.


def calculate_character_to_length_mapping(<EOL>measurer: text_measurer.TextMeasurer,<EOL>characters: Iterable[str]) -> Mapping[str, float]:

char_to_length = {}<EOL>for c in characters:<EOL><INDENT>char_to_length[c] = measurer.text_width(c)<EOL><DEDENT>return char_to_length<EOL>

Return a mapping between each given character and its length.

    Args:
        measurer: The TextMeasurer used to measure the width of the text in
            pixels.
        characters: The characters to measure e.g. "ml".

    Returns:
        A mapping from the given characters to their length in pixels, as
        determined by 'measurer' e.g. {'m': 5.2, 'l', 1.2}.


def calculate_pair_to_kern_mapping(<EOL>measurer: text_measurer.TextMeasurer,<EOL>char_to_length: Mapping[str, float],<EOL>characters: Iterable[str]) -> Mapping[str, float]:

pair_to_kerning = {}<EOL>for a, b in itertools.permutations(characters, <NUM_LIT:2>):<EOL><INDENT>kerned_width = measurer.text_width(a + b)<EOL>unkerned_width = char_to_length[a] + char_to_length[b]<EOL>kerning = unkerned_width - kerned_width<EOL>if abs(kerning) > <NUM_LIT>:<EOL><INDENT>pair_to_kerning[a + b] = round(kerning, <NUM_LIT:3>)<EOL><DEDENT><DEDENT>return pair_to_kerning<EOL>

Returns a mapping between each *pair* of characters and their kerning.

    Args:
        measurer: The TextMeasurer used to measure the width of each pair of
            characters.
        char_to_length: A mapping between characters and their length in pixels.
            Must contain every character in 'characters' e.g.
            {'h': 5.2, 'e': 4.0, 'l', 1.2, 'o': 5.0}.
        characters: The characters to generate the kerning mapping for e.g.
            'hel'.

    Returns:
        A mapping between each pair of given characters
        (e.g. 'hh', he', hl', 'eh', 'ee', 'el', 'lh, 'le', 'll') and the kerning
        adjustment for that pair of characters i.e. the difference between the
        length of the two characters calculated using 'char_to_length' vs.
        the length calculated by `measurer`. Positive values indicate that the
        length is less than using the sum of 'char_to_length'. Zero values are
        excluded from the map e.g. {'hl': 3.1, 'ee': -0.5}.


def write_json(f: TextIO, deja_vu_sans_path: str,<EOL>measurer: text_measurer.TextMeasurer,<EOL>encodings: Iterable[str]) -> None:

supported_characters = list(<EOL>generate_supported_characters(deja_vu_sans_path))<EOL>kerning_characters = '<STR_LIT>'.join(<EOL>generate_encodeable_characters(supported_characters, encodings))<EOL>char_to_length = calculate_character_to_length_mapping(measurer,<EOL>supported_characters)<EOL>pair_to_kerning = calculate_pair_to_kern_mapping(measurer, char_to_length,<EOL>kerning_characters)<EOL>json.dump(<EOL>{'<STR_LIT>': statistics.mean(char_to_length.values()),<EOL>'<STR_LIT>': char_to_length,<EOL>'<STR_LIT>': kerning_characters,<EOL>'<STR_LIT>': pair_to_kerning},<EOL>f, sort_keys=True, indent=<NUM_LIT:1>)<EOL>

Write the data required by PrecalculatedTextMeasurer to a stream.


def badge(left_text: str, right_text: str, left_link: Optional[str] = None,<EOL>right_link: Optional[str] = None,<EOL>whole_link: Optional[str] = None, logo: Optional[str] = None,<EOL>left_color: str = '<STR_LIT>', right_color: str = '<STR_LIT>',<EOL>measurer: Optional[text_measurer.TextMeasurer] = None,<EOL>embed_logo: bool = False) -> str:

if measurer is None:<EOL><INDENT>measurer = (<EOL>precalculated_text_measurer.PrecalculatedTextMeasurer<EOL>.default())<EOL><DEDENT>if (left_link or right_link) and whole_link:<EOL><INDENT>raise ValueError(<EOL>'<STR_LIT>')<EOL><DEDENT>template = _JINJA2_ENVIRONMENT.get_template('<STR_LIT>')<EOL>if logo and embed_logo:<EOL><INDENT>logo = _embed_image(logo)<EOL><DEDENT>svg = template.render(<EOL>left_text=left_text,<EOL>right_text=right_text,<EOL>left_text_width=measurer.text_width(left_text) / <NUM_LIT>,<EOL>right_text_width=measurer.text_width(right_text) / <NUM_LIT>,<EOL>left_link=left_link,<EOL>right_link=right_link,<EOL>whole_link=whole_link,<EOL>logo=logo,<EOL>left_color=_NAME_TO_COLOR.get(left_color, left_color),<EOL>right_color=_NAME_TO_COLOR.get(right_color, right_color),<EOL>)<EOL>xml = minidom.parseString(svg)<EOL>_remove_blanks(xml)<EOL>xml.normalize()<EOL>return xml.documentElement.toxml()<EOL>

Creates a github-style badge as an SVG image.

    >>> badge(left_text='coverage', right_text='23%', right_color='red')
    '<svg...</svg>'
    >>> badge(left_text='build', right_text='green', right_color='green',
    ...       whole_link="http://www.example.com/")
    '<svg...</svg>'

    Args:
        left_text: The text that should appear on the left-hand-side of the
            badge e.g. "coverage".
        right_text: The text that should appear on the right-hand-side of the
            badge e.g. "23%".
        left_link: The URL that should be redirected to when the left-hand text
            is selected.
        right_link: The URL that should be redirected to when the right-hand
            text is selected.
        whole_link: The link that should be redirected to when the badge is
            selected. If set then left_link and right_right may not be set.
        logo: A url representing a logo that will be displayed inside the
            badge. Can be a data URL e.g. "data:image/svg+xml;utf8,<svg..."
        left_color: The color of the part of the badge containing the left-hand
            text. Can be an valid CSS color
            (see https://developer.mozilla.org/en-US/docs/Web/CSS/color) or a
            color name defined here:
            https://github.com/badges/shields/blob/master/lib/colorscheme.json
        right_color: The color of the part of the badge containing the
            right-hand text. Can be an valid CSS color
            (see https://developer.mozilla.org/en-US/docs/Web/CSS/color) or a
            color name defined here:
            https://github.com/badges/shields/blob/master/lib/colorscheme.json
        measurer: A text_measurer.TextMeasurer that can be used to measure the
            width of left_text and right_text.
        embed_logo: If True then embed the logo image directly in the badge.
            This can prevent an HTTP request and some browsers will not render
            external image referenced. When True, `logo` must be a HTTP/HTTPS
            URI or a filesystem path. Also, the `badge` call may raise an
            exception if the logo cannot be loaded, is not an image, etc.


raise NotImplementedError('<STR_LIT>')<EOL>


with open('<STR_LIT>') as f:<EOL><INDENT>read_me = f.read()<EOL><DEDENT>def replace_relative_with_absolute(match):<EOL><INDENT>svg_path = match.group(<NUM_LIT:0>)[<NUM_LIT:1>:-<NUM_LIT:1>]<EOL>return ('<STR_LIT>'<EOL>'<STR_LIT>' % svg_path)<EOL><DEDENT>return re.sub(r'<STR_LIT>',<EOL>replace_relative_with_absolute,<EOL>read_me)<EOL>

Transform README.md into a usable long description.

    Replaces relative references to svg images to absolute https references.


def make_fake_movie(nframes, mask_shape=(<NUM_LIT:64>, <NUM_LIT:64>), mask_center=None,<EOL>bg_intensity=<NUM_LIT:0.1>, mask_sigma=<NUM_LIT:10>, dt=<NUM_LIT>, rate=<NUM_LIT:1.0>,<EOL>tau=<NUM_LIT:1.>, sigma=<NUM_LIT>, seed=None):

gen = np.random.RandomState(seed)<EOL>n = gen.poisson(rate * dt, size=nframes)<EOL>gamma = np.exp(-dt / tau)<EOL>c = signal.lfilter(np.r_[<NUM_LIT:1>], np.r_[<NUM_LIT:1>, -gamma], n, axis=<NUM_LIT:0>)<EOL>nr, nc = mask_shape<EOL>npix = nr * nc<EOL>if mask_center is None:<EOL><INDENT>mask_center = (nc // <NUM_LIT>, nr // <NUM_LIT>)<EOL><DEDENT>a, b = mask_center<EOL>y, x = np.ogrid[:nr, :nc]<EOL>xs = (x - a) ** <NUM_LIT><EOL>ys = (y - b) ** <NUM_LIT><EOL>twoss = <NUM_LIT> * mask_sigma ** <NUM_LIT><EOL>alpha = np.exp(-<NUM_LIT:1> * ((xs / twoss) + (ys / twoss))).ravel()<EOL>alpha /= alpha.sum()<EOL>beta = gen.randn(npix) * bg_intensity<EOL>lamb = rate<EOL>epsilon = gen.randn(npix, nframes) * sigma<EOL>F = c[None, :] * alpha[:, None] + beta[:, None] + epsilon<EOL>theta = (sigma, alpha, beta, lamb, gamma)<EOL>return F, c, n, theta<EOL>

Generate 2D fake fluorescence movie

Arguments:
---------------------------------------------------------------------------
    nframes:        number of timebins to simulate
    mask_shape:     tuple (nrows, ncols), shape of a single movie frame
    mask_center:    tuple (x, y), pixel coords of cell center
    bg_intensity:   scalar, amplitude of (static) baseline fluorescence
    mask_sigma:     scalar, standard deviation of Gaussian mask
    dt:             timestep (s)
    rate:           mean spike rate (Hz)
    tau:            time constant of decay in calcium concentration (s)
    sigma:          SD of additive noise on fluorescence
    seed:           Seed for RNG

Returns:
---------------------------------------------------------------------------
    F:          fluorescence [npixels, nframes]
    c:          calcium concentration [nframes,]
    n:          spike train [nframes,]
    theta:      tuple of true model parameters:
                (sigma, alpha, beta, lambda, gamma)


def trisolve(dl, d, du, b, inplace=False):

if (dl.shape[<NUM_LIT:0>] != du.shape[<NUM_LIT:0>] or (d.shape[<NUM_LIT:0>] != dl.shape[<NUM_LIT:0>] + <NUM_LIT:1>)<EOL>or d.shape[<NUM_LIT:0>] != b.shape[<NUM_LIT:0>]):<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>bshape_in = b.shape<EOL>rtype = np.result_type(dl, d, du, b)<EOL>if not inplace:<EOL><INDENT>dl = np.array(dl, dtype=rtype, copy=True, order='<STR_LIT:F>')<EOL>d = np.array(d, dtype=rtype, copy=True, order='<STR_LIT:F>')<EOL>du = np.array(du, dtype=rtype, copy=True, order='<STR_LIT:F>')<EOL>b = np.array(b, dtype=rtype, copy=True, order='<STR_LIT:F>')<EOL><DEDENT>dl, d, du, b = (np.array(v, dtype=rtype, copy=False, order='<STR_LIT:F>')<EOL>for v in (dl, d, du, b))<EOL>_lapack_trisolve(dl, d, du, b, rtype)<EOL>return b.reshape(bshape_in)<EOL>

The tridiagonal matrix (Thomas) algorithm for solving tridiagonal systems
of equations:

    a_{i}x_{i-1} + b_{i}x_{i} + c_{i}x_{i+1} = y_{i}

in matrix form:
    Mx = b

TDMA is O(n), whereas standard Gaussian elimination is O(n^3).

Arguments:
-----------
    dl: (n - 1,) vector
        the lower diagonal of M
    d: (n,) vector
        the main diagonal of M
    du: (n - 1,) vector
        the upper diagonal of M
    b: (n,) vector
        the result of Mx
    inplace:
        if True, and if d and b are both float64 vectors, they will be
        modified in place (may be faster)

Returns:
-----------
    x: (n,) vector
        the solution to Mx = b

References:
-----------
http://en.wikipedia.org/wiki/Tridiagonal_matrix_algorithm
http://www.netlib.org/lapack/explore-html/d1/db3/dgtsv_8f.html


def deconvolve(F, c0=None, theta0=((None,) * <NUM_LIT:5>), dt=<NUM_LIT>, rate=<NUM_LIT:0.5>, tau=<NUM_LIT:1.>,<EOL>learn_theta=((<NUM_LIT:0>,) * <NUM_LIT:5>), norm_alpha=True, params_tol=<NUM_LIT>,<EOL>spikes_tol=<NUM_LIT>, spikes_maxiter=<NUM_LIT:100>, params_maxiter=<NUM_LIT:20>,<EOL>decimate=<NUM_LIT:0>, verbosity=<NUM_LIT:0>):

tstart = time.time()<EOL>F = np.atleast_2d(F.astype(DTYPE))<EOL>npix, nt = F.shape<EOL>offset = F.min() - EPS<EOL>F = F - offset<EOL>theta = _init_theta(F, theta0, offset, dt=dt, rate=rate, tau=tau,<EOL>decimate=decimate)<EOL>sigma, alpha, beta, lamb, gamma = theta<EOL>if c0 is None:<EOL><INDENT>n0 = lamb * dt * np.ones(nt, dtype=DTYPE)<EOL>c0 = signal.lfilter(np.r_[<NUM_LIT:1.>], np.r_[<NUM_LIT:1.>, -gamma], n0, axis=<NUM_LIT:0>)<EOL><DEDENT>else:<EOL><INDENT>c0 = c0.copy()<EOL><DEDENT>n_hat, c_hat, LL = _get_MAP_spikes(F, c0, theta, dt, spikes_tol,<EOL>spikes_maxiter, verbosity)<EOL>if any(learn_theta):<EOL><INDENT>if verbosity >= <NUM_LIT:1>:<EOL><INDENT>print('<STR_LIT>' % (<NUM_LIT:0>, LL))<EOL><DEDENT>nloop1 = <NUM_LIT:1><EOL>done = False<EOL>while not done:<EOL><INDENT>theta1 = _update_theta(n_hat, c_hat, F, theta, dt, learn_theta,<EOL>decimate)<EOL>n1, c_hat1, LL1 = _get_MAP_spikes(F, c_hat, theta1, dt, spikes_tol,<EOL>spikes_maxiter, verbosity)<EOL>delta_LL = -((LL1 - LL) / LL)<EOL>if verbosity >= <NUM_LIT:1>:<EOL><INDENT>print('<STR_LIT>'<EOL>% (nloop1, LL1, delta_LL))<EOL><DEDENT>if delta_LL > <NUM_LIT:0>:<EOL><INDENT>n_hat, c_hat, LL, theta = n1, c_hat1, LL1, theta1<EOL>if delta_LL < params_tol:<EOL><INDENT>if verbosity >= <NUM_LIT:1>:<EOL><INDENT>print("<STR_LIT>"<EOL>"<STR_LIT>" % nloop1)<EOL><DEDENT>done = True<EOL><DEDENT>elif nloop1 == params_maxiter:<EOL><INDENT>if verbosity >= <NUM_LIT:1>:<EOL><INDENT>print('<STR_LIT>'<EOL>'<STR_LIT>' % nloop1)<EOL><DEDENT>done = True<EOL><DEDENT><DEDENT>else:<EOL><INDENT>if verbosity >= <NUM_LIT:1>:<EOL><INDENT>print('<STR_LIT>'<EOL>'<STR_LIT>' % nloop1)<EOL><DEDENT>done = True<EOL><DEDENT>if done:<EOL><INDENT>if verbosity >= <NUM_LIT:1>:<EOL><INDENT>print("<STR_LIT>" % delta_LL)<EOL>print("<STR_LIT>" % LL)<EOL><DEDENT><DEDENT>nloop1 += <NUM_LIT:1><EOL><DEDENT><DEDENT>if verbosity >= <NUM_LIT:1>:<EOL><INDENT>time_taken = time.time() - tstart<EOL>print("<STR_LIT>" % s2h(time_taken))<EOL><DEDENT>sigma, alpha, beta, lamb, gamma = theta<EOL>beta += offset<EOL>if norm_alpha:<EOL><INDENT>alpha_sum = np.sum(alpha)<EOL>if alpha_sum < <NUM_LIT:0>:<EOL><INDENT>warnings.warn('<STR_LIT>'<EOL>'<STR_LIT>')<EOL><DEDENT>alpha /= alpha_sum<EOL>c_hat *= alpha_sum<EOL>n_hat = c_hat[<NUM_LIT:1>:] - gamma * c_hat[:-<NUM_LIT:1>]<EOL><DEDENT>n_hat = np.r_[<NUM_LIT:0>, n_hat]<EOL>theta = sigma, alpha, beta, lamb, gamma<EOL>return n_hat, c_hat, LL, theta<EOL>

Fast Non-Negative Deconvolution
---------------------------------------------------------------------------
This function uses an interior point method to solve the following
optimization problem:

    n_hat = argmax_{n >= 0} P(n | F)

where n_hat_best is a maximum a posteriori estimate for the most likely
spike train, given the fluorescence signal F, and the model:

c_{t} = gamma * c_{t-1} + n_{t},            n_{t} ~ Poisson(lambda * dt)
F_{t} = alpha * c_{t} + beta + epsilon,     epsilon ~ N(0, sigma)

It is also possible to estimate the model parameters sigma, alpha, beta and
lambda from the data using pseudo-EM updates.

Arguments:
---------------------------------------------------------------------------
F: ndarray, [nt] or [npix, nt]
    measured fluorescence values

c0: ndarray, [nt]
    initial estimate of the calcium concentration for each time bin

theta0: len(5) sequence
    initial estimates of the model parameters (sigma, alpha, beta, lambda,
    gamma). any parameters in theta0 that are None will be estimated from
    F.

dt: float scalar
    duration of each time bin (s)

rate: float scalar
    estimate of mean firing rate (Hz), ignored if theta0[3] is not None

tau: float scalar
    estimate of calcium decay time constant (s), ignored if theta0[4] is
    not None

learn_theta: len(5) bool sequence
    specifies which of the model parameters to attempt learn via pseudo-EM
    iterations. currently gamma cannot be optimised.

norm_alpha: bool
    if True (default), we impose that sum(alpha) == 1 by scaling n_hat and
    c_hat

spikes_tol: float scalar
    termination condition for interior point spike train estimation:
        params_tol > abs((LL_prev - LL) / LL)

params_tol: float scalar
    as above, but for the model parameter estimation

spikes_maxiter: int scalar
    maximum number of interior point iterations to estimate MAP spike train

params_maxiter: int scalar
    maximum number of pseudo-EM iterations to estimate model parameters

decimate: int scalar
    option to decimate the input array over time when initalizing and
    updating the theta parameters, i.e. Fd = F[:, ::decimate]. this can
    be useful for very large input arrays. the default value (0) means no
    decimation is performed.

verbosity: int scalar
    0: no convergence messages (default)
    1: convergence messages for model parameters
    2: convergence messages for model parameters & MAP spike train

Returns:
---------------------------------------------------------------------------
n_hat_best: ndarray, [nt]
    MAP estimate of the most likely spike train

c_hat_best: ndarray, [nt]
    estimated intracellular calcium concentration (A.U.)

LL_best: float scalar
    posterior log-likelihood of F given n_hat_best and theta_best

theta_best: len(5) tuple
    model parameters, updated according to learn_theta

Reference:
---------------------------------------------------------------------------
Vogelstein, J. T., Packer, A. M., Machado, T. A., Sippy, T., Babadi, B.,
Yuste, R., & Paninski, L. (2010). Fast nonnegative deconvolution for spike
train inference from population calcium imaging. Journal of
Neurophysiology, 104(6), 3691-704. doi:10.1152/jn.01073.2009


def _get_MAP_spikes(F, c_hat, theta, dt, tol=<NUM_LIT>, maxiter=<NUM_LIT:100>, verbosity=<NUM_LIT:0>):

npix, nt = F.shape<EOL>sigma, alpha, beta, lamb, gamma = theta<EOL>alpha_ss = np.dot(alpha, alpha)<EOL>c = np.dot(alpha, F) - np.dot(alpha, beta)<EOL>scale_var = <NUM_LIT:1.> / (<NUM_LIT:2> * sigma * sigma)<EOL>lD = lamb * dt<EOL>grad_lnprior = np.zeros(nt, dtype=DTYPE)<EOL>grad_lnprior[<NUM_LIT:1>:] = lD<EOL>grad_lnprior[:-<NUM_LIT:1>] -= lD * gamma<EOL>z = <NUM_LIT:1.><EOL>n_hat = c_hat[<NUM_LIT:1>:] - gamma * c_hat[:-<NUM_LIT:1>]<EOL>res = c - alpha_ss * c_hat<EOL>LL_best = _post_LL(n_hat, res, scale_var, lD, z)<EOL>LL_barrier = LL_best<EOL>nloop1 = <NUM_LIT:0><EOL>terminate_interior = False<EOL>while not terminate_interior:<EOL><INDENT>nloop2 = <NUM_LIT:0><EOL>terminate_barrier = False<EOL>while not terminate_barrier:<EOL><INDENT>res = c - alpha_ss * c_hat<EOL>d = _direction(n_hat, res, alpha_ss, gamma, scale_var,<EOL>grad_lnprior, z)<EOL>terminate_linesearch = False<EOL>s_upper_bnd = -n_hat / (d[<NUM_LIT:1>:] - gamma * d[:-<NUM_LIT:1>])<EOL>feasible = (s_upper_bnd > <NUM_LIT:0>)<EOL>if np.any(feasible):<EOL><INDENT>s = min(<NUM_LIT:1.>, <NUM_LIT> * np.min(s_upper_bnd[feasible]))<EOL><DEDENT>else:<EOL><INDENT>terminate_linesearch = True<EOL>terminate_barrier = True<EOL>if verbosity >= <NUM_LIT:2>:<EOL><INDENT>print("<STR_LIT>"<EOL>"<STR_LIT>")<EOL><DEDENT><DEDENT>nloop3 = <NUM_LIT:0><EOL>while not terminate_linesearch:<EOL><INDENT>c_hat_line = c_hat + (s * d)<EOL>n_hat_line = c_hat_line[<NUM_LIT:1>:] - gamma * c_hat_line[:-<NUM_LIT:1>]<EOL>res = c - alpha_ss * c_hat_line<EOL>LL_line = _post_LL(n_hat_line, res, scale_var, lD, z)<EOL>if verbosity >= <NUM_LIT:2>:<EOL><INDENT>print('<STR_LIT>'<EOL>'<STR_LIT>'<EOL>% (nloop1, nloop2, nloop3, z, s, LL_line))<EOL><DEDENT>if s < S_TOL:<EOL><INDENT>if verbosity >= <NUM_LIT:2>:<EOL><INDENT>print('<STR_LIT>'<EOL>'<STR_LIT>' % (S_TOL, nloop3))<EOL><DEDENT>terminate_linesearch = True<EOL>terminate_barrier = True<EOL><DEDENT>if LL_line > LL_barrier:<EOL><INDENT>LL_barrier, n_hat, c_hat = LL_line, n_hat_line, c_hat_line<EOL>terminate_linesearch = True<EOL><DEDENT>else:<EOL><INDENT>s /= S_FAC<EOL><DEDENT>nloop3 += <NUM_LIT:1><EOL><DEDENT>if (np.linalg.norm(d) < D_TOL):<EOL><INDENT>terminate_barrier = True<EOL><DEDENT>nloop2 += <NUM_LIT:1><EOL><DEDENT>if nloop3:<EOL><INDENT>delta_LL = -(LL_barrier - LL_best) / LL_best<EOL>LL_best = LL_barrier<EOL>if (delta_LL < tol):<EOL><INDENT>terminate_interior = True<EOL><DEDENT><DEDENT>elif z < Z_TOL:<EOL><INDENT>if verbosity >= <NUM_LIT:2>:<EOL><INDENT>print('<STR_LIT>'<EOL>% Z_TOL)<EOL><DEDENT>terminate_interior = True<EOL><DEDENT>elif nloop1 > maxiter:<EOL><INDENT>if verbosity >= <NUM_LIT:2>:<EOL><INDENT>print('<STR_LIT>'<EOL>% maxiter)<EOL><DEDENT>terminate_interior = True<EOL><DEDENT>nloop1 += <NUM_LIT:1><EOL>z /= Z_FAC<EOL><DEDENT>return n_hat, c_hat, LL_best<EOL>

Used internally by deconvolve to compute the maximum a posteriori
spike train for a given set of fluorescence traces and model parameters.

See the documentation for deconvolve for the meaning of the
arguments

Returns:    n_hat_best, c_hat_best, LL_best


mm, ss = divmod(ss, <NUM_LIT>)<EOL>hh, mm = divmod(mm, <NUM_LIT>)<EOL>dd, hh = divmod(hh, <NUM_LIT>)<EOL>tstr = "<STR_LIT>" % (mm, ss)<EOL>if hh > <NUM_LIT:0>:<EOL><INDENT>tstr = ("<STR_LIT>" % hh) + tstr<EOL><DEDENT>if dd > <NUM_LIT:0>:<EOL><INDENT>tstr = ("<STR_LIT>" % dd) + tstr<EOL><DEDENT>return tstr<EOL>

convert seconds to a pretty "d hh:mm:ss.s" format


global _override_backends<EOL>_override_backends = backends<EOL>


global _metrics_backends<EOL>_metrics_backends = backends<EOL>


return clspath.rsplit('<STR_LIT:.>', <NUM_LIT:1>)<EOL>

Split of clspath into module and class name.

    NOTE(willkg): This is really simple. Maybe we should use something more
    sophisticated?


good_backends = []<EOL>for backend in backends:<EOL><INDENT>clspath = backend['<STR_LIT:class>']<EOL>options = backend.get('<STR_LIT>', {})<EOL>if isinstance(clspath, str):<EOL><INDENT>modpath, clsname = split_clspath(clspath)<EOL>try:<EOL><INDENT>__import__(modpath)<EOL>module = sys.modules[modpath]<EOL>cls = getattr(module, clsname)<EOL><DEDENT>except Exception:<EOL><INDENT>logger.exception('<STR_LIT>', clspath)<EOL>if raise_errors:<EOL><INDENT>raise<EOL><DEDENT>continue<EOL><DEDENT><DEDENT>else:<EOL><INDENT>cls = clspath<EOL><DEDENT>try:<EOL><INDENT>good_backends.append(cls(options))<EOL><DEDENT>except Exception:<EOL><INDENT>logger.exception(<EOL>'<STR_LIT>',<EOL>clspath,<EOL>options<EOL>)<EOL>if raise_errors:<EOL><INDENT>raise<EOL><DEDENT><DEDENT><DEDENT>_change_metrics(good_backends)<EOL>

Instantiate and configures backends.

    :arg list-of-dicts backends: the backend configuration as a list of dicts where
        each dict specifies a separate backend.

        Each backend dict consists of two things:

        1. ``class`` with a value that is either a Python class or a dotted
           Python path to one

        2. ``options`` dict with options for the backend in question to
           configure it

        See the documentation for the backends you're using to know what is
        configurable in the options dict.

    :arg raise_errors bool: whether or not to raise an exception if something
        happens in configuration; if it doesn't raise an exception, it'll log
        the exception

    For example, this sets up a
    :py:class:`markus.backends.logging.LoggingMetrics` backend::

        markus.configure([
            {
                'class': 'markus.backends.logging.LoggingMetrics',
                'options': {
                    'logger_name': 'metrics'
                }
            }
        ])

    You can set up as many backends as you like.

    .. Note::

       During application startup, Markus should get configured before the app
       starts generating metrics. Any metrics generated before Markus is
       configured will get dropped.

       However, anything can call :py:func:`markus.get_metrics` and get a
       :py:class:`markus.main.MetricsInterface` before Markus has been
       configured including at module load time.


thing = thing or '<STR_LIT>'<EOL>if not isinstance(thing, str):<EOL><INDENT>if type(thing) == type:<EOL><INDENT>thing = '<STR_LIT>' % (thing.__module__, thing.__name__)<EOL><DEDENT>else:<EOL><INDENT>thing = '<STR_LIT>' % (<EOL>thing.__class__.__module__, thing.__class__.__name__<EOL>)<EOL><DEDENT><DEDENT>if extra:<EOL><INDENT>thing = '<STR_LIT>' % (thing, extra)<EOL><DEDENT>return MetricsInterface(thing)<EOL>

Return MetricsInterface instance with specified name.

    The name is used as the prefix for all keys generated with this
    :py:class:`markus.main.MetricsInterface`.

    The :py:class:`markus.main.MetricsInterface` is not tied to metrics
    backends. The list of active backends are globally configured. This allows
    us to create :py:class:`markus.main.MetricsInterface` classes without
    having to worry about bootstrapping order of the app.

    :arg class/instance/str thing: The name to use as a key prefix.

        If this is a class, it uses the dotted Python path. If this is an
        instance, it uses the dotted Python path plus ``str(instance)``.

    :arg str extra: Any extra bits to add to the end of the name.

    :returns: a ``MetricsInterface`` instance

    Examples:

    >>> from markus import get_metrics

    Create a MetricsInterface with the name "myapp" and generate a count with
    stat "myapp.thing1" and value 1:

    >>> metrics = get_metrics('myapp')
    >>> metrics.incr('thing1', value=1)

    Create a MetricsInterface with the prefix of the Python module it's being
    called in:

    >>> metrics = get_metrics(__name__)

    Create a MetricsInterface with the prefix as the qualname of the class:

    >>> class Foo:
    ...     def __init__(self):
    ...         self.metrics = get_metrics(self)

    Create a prefix of the class path plus some identifying information:

    >>> class Foo:
    ...     def __init__(self, myname):
    ...         self.metrics = get_metrics(self, extra=myname)
    ...
    >>> foo = Foo('jim')

    Assume that ``Foo`` is defined in the ``myapp`` module. Then this will
    generate the name ``myapp.Foo.jim``.


<EOL>name = NOT_ALPHANUM_RE.sub('<STR_LIT:.>', name)<EOL>while True:<EOL><INDENT>new_name = name.replace('<STR_LIT:..>', '<STR_LIT:.>')<EOL>if new_name == name:<EOL><INDENT>break<EOL><DEDENT>name = new_name<EOL><DEDENT>self.name = name.strip('<STR_LIT:.>')<EOL>

Create a MetricsInterface.

        :arg str name: Use alphanumeric characters and underscore and period.
            Anything else gets converted to a period. Sequences of periods get
            collapsed to a single period.


def incr(self, stat, value=<NUM_LIT:1>, tags=None):

full_stat = self._full_stat(stat)<EOL>for backend in _get_metrics_backends():<EOL><INDENT>backend.incr(full_stat, value=value, tags=tags)<EOL><DEDENT>

Incr is used for counting things.

        :arg string stat: A period delimited alphanumeric key.

        :arg int value: A value to increment the count by. Usually this is 1.

        :arg list-of-strings tags: Each string in the tag consists of a key and
            a value separated by a colon. Tags can make it easier to break down
            metrics for analysis.

            For example ``['env:stage', 'compressed:yes']``.

        For example:

        >>> import markus

        >>> metrics = markus.get_metrics('foo')
        >>> def chop_vegetable(kind):
        ...     # chop chop chop
        ...     metrics.incr('vegetable', value=1)

        You can also use incr to decrement by passing a negative value.


def gauge(self, stat, value, tags=None):

full_stat = self._full_stat(stat)<EOL>for backend in _get_metrics_backends():<EOL><INDENT>backend.gauge(full_stat, value=value, tags=tags)<EOL><DEDENT>

Gauges are used for measuring things.

        :arg string stat: A period delimited alphanumeric key.

        :arg int value: The measured value of the thing being measured.

        :arg list-of-strings tags: Each string in the tag consists of a key and
            a value separated by a colon. Tags can make it easier to break down
            metrics for analysis.

            For example ``['env:stage', 'compressed:yes']``.

        For example:

        >>> import markus

        >>> metrics = markus.get_metrics('foo')
        >>> def parse_payload(payload):
        ...     metrics.gauge('payload_size', value=len(payload))
        ...     # parse parse parse


def timing(self, stat, value, tags=None):

full_stat = self._full_stat(stat)<EOL>for backend in _get_metrics_backends():<EOL><INDENT>backend.timing(full_stat, value=value, tags=tags)<EOL><DEDENT>

Record a timing value.

        Record the length of time of something to be added to a set of values from
        which a statistical distribution is derived.

        Depending on the backend, you might end up with count, average, median,
        95% and max for a set of timing values.

        This is useful for analyzing how long things take to occur. For
        example, how long it takes for a function to run, to upload files, or
        for a database query to execute.

        :arg string stat: A period delimited alphanumeric key.

        :arg int value: A timing in milliseconds.

        :arg list-of-strings tags: Each string in the tag consists of a key and
            a value separated by a colon. Tags can make it easier to break down
            metrics for analysis.

            For example ``['env:stage', 'compressed:yes']``.

        For example:

        >>> import time
        >>> import markus

        >>> metrics = markus.get_metrics('foo')
        >>> def upload_file(payload):
        ...     start_time = time.perf_counter()  # this is in seconds
        ...     # upload the file
        ...     timing = (time.perf_counter() - start_time) * 1000.0  # convert to ms
        ...     metrics.timing('upload_file_time', value=timing)

        .. Note::

           If you're timing a function or a block of code, it's probably more
           convenient to use :py:meth:`markus.main.MetricsInterface.timer` or
           :py:meth:`markus.main.MetricsInterface.timer_decorator`.


def histogram(self, stat, value, tags=None):

full_stat = self._full_stat(stat)<EOL>for backend in _get_metrics_backends():<EOL><INDENT>backend.histogram(full_stat, value=value, tags=tags)<EOL><DEDENT>

Record a histogram value.

        Record a value to be added to a set of values from which a statistical
        distribution is derived.

        Depending on the backend, you might end up with count, average, median,
        95% and max for a set of values.

        This is useful for analyzing distributions of values. For example,
        what's the median and 95% upload file size? What's the most expensive
        thing sold?

        :arg string stat: A period delimited alphanumeric key.

        :arg int value: The value of the thing.

        :arg list-of-strings tags: Each string in the tag consists of a key and
            a value separated by a colon. Tags can make it easier to break down
            metrics for analysis.

            For example ``['env:stage', 'compressed:yes']``.

        For example:

        >>> import time
        >>> import markus

        >>> metrics = markus.get_metrics('foo')
        >>> def finalize_sale(cart):
        ...     for item in cart:
        ...         metrics.histogram('item_cost', value=item.cost)
        ...     # finish finalizing

        .. Note::

           For metrics backends that don't have histogram, this will do the
           same as timing.


@contextlib.contextmanager<EOL><INDENT>def timer(self, stat, tags=None):<DEDENT>

if six.PY3:<EOL><INDENT>start_time = time.perf_counter()<EOL><DEDENT>else:<EOL><INDENT>start_time = time.time()<EOL><DEDENT>yield<EOL>if six.PY3:<EOL><INDENT>end_time = time.perf_counter()<EOL><DEDENT>else:<EOL><INDENT>end_time = time.time()<EOL><DEDENT>delta = end_time - start_time<EOL>self.timing(stat, value=delta * <NUM_LIT>, tags=tags)<EOL>

Contextmanager for easily computing timings.

        :arg string stat: A period delimited alphanumeric key.

        :arg list-of-strings tags: Each string in the tag consists of a key and
            a value separated by a colon. Tags can make it easier to break down
            metrics for analysis.

            For example ``['env:stage', 'compressed:yes']``.

        For example:

        >>> mymetrics = get_metrics(__name__)

        >>> def long_function():
        ...     with mymetrics.timer('long_function'):
        ...         # perform some thing we want to keep metrics on
        ...         pass

        .. Note::

           All timings generated with this are in milliseconds.


def timer_decorator(self, stat, tags=None):

def _inner(fun):<EOL><INDENT>@wraps(fun)<EOL>def _timer_decorator(*args, **kwargs):<EOL><INDENT>with self.timer(stat, tags):<EOL><INDENT>return fun(*args, **kwargs)<EOL><DEDENT><DEDENT>return _timer_decorator<EOL><DEDENT>return _inner<EOL>

Timer decorator for easily computing timings.

        :arg string stat: A period delimited alphanumeric key.

        :arg list-of-strings tags: Each string in the tag consists of a key and
            a value separated by a colon. Tags can make it easier to break down
            metrics for analysis.

            For example ``['env:stage', 'compressed:yes']``.

        For example:

        >>> mymetrics = get_metrics(__name__)

        >>> @mymetrics.timer_decorator('long_function')
        ... def long_function():
        ...     # perform some thing we want to keep metrics on
        ...     pass

        .. Note::

           All timings generated with this are in milliseconds.


self._add_record(INCR, stat, value, tags)<EOL>


self._add_record(GAUGE, stat, value, tags)<EOL>


self._add_record(TIMING, stat, value, tags)<EOL>

Measure a timing for statistical distribution.


self._add_record(HISTOGRAM, stat, value, tags)<EOL>

Measure a value for statistical distribution.


return self.records<EOL>

Return set of collected metrics records.


def filter_records(self, fun_name=None, stat=None, value=None, tags=None):

def match_fun_name(record_fun_name):<EOL><INDENT>return fun_name is None or fun_name == record_fun_name<EOL><DEDENT>def match_stat(record_stat):<EOL><INDENT>return stat is None or stat == record_stat<EOL><DEDENT>def match_value(record_value):<EOL><INDENT>return value is None or value == record_value<EOL><DEDENT>def match_tags(record_tags):<EOL><INDENT>return tags is None or list(sorted(tags)) == list(sorted(record_tags))<EOL><DEDENT>return [<EOL>record for record in self.get_records()<EOL>if (match_fun_name(record[<NUM_LIT:0>]) and<EOL>match_stat(record[<NUM_LIT:1>]) and<EOL>match_value(record[<NUM_LIT:2>]) and<EOL>match_tags(record[<NUM_LIT:3>]))<EOL>]<EOL>

Filter collected metircs records for ones that match specified criteria.


def has_record(self, fun_name=None, stat=None, value=None, tags=None):

return bool(<EOL>self.filter_records(<EOL>fun_name=fun_name,<EOL>stat=stat,<EOL>value=value,<EOL>tags=tags<EOL>)<EOL>)<EOL>

Return True/False regarding whether collected metrics match specified criteria.


for record in self.get_records():<EOL><INDENT>print(record)<EOL><DEDENT>


self.records = []<EOL>


self._log('<STR_LIT:count>', stat, value, tags)<EOL>


self._log('<STR_LIT>', stat, value, tags)<EOL>


Set a timing.

        Note: Does the same thing as histogram.


now = time.time()<EOL>if now < self.next_rollup:<EOL><INDENT>return<EOL><DEDENT>self.next_rollup = now + self.flush_interval<EOL>for key, values in sorted(self.incr_stats.items()):<EOL><INDENT>self.logger.info(<EOL>'<STR_LIT>',<EOL>self.leader,<EOL>key,<EOL>len(values),<EOL>sum(values),<EOL>self.flush_interval<EOL>)<EOL>self.incr_stats[key] = []<EOL><DEDENT>for key, values in sorted(self.gauge_stats.items()):<EOL><INDENT>if values:<EOL><INDENT>self.logger.info(<EOL>'<STR_LIT>',<EOL>self.leader,<EOL>key,<EOL>len(values),<EOL>values[-<NUM_LIT:1>],<EOL>min(values),<EOL>max(values),<EOL>)<EOL><DEDENT>else:<EOL><INDENT>self.logger.info('<STR_LIT>', self.leader, key)<EOL><DEDENT>self.gauge_stats[key] = []<EOL><DEDENT>for key, values in sorted(self.histogram_stats.items()):<EOL><INDENT>if values:<EOL><INDENT>self.logger.info(<EOL>(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>'<EOL>),<EOL>self.leader,<EOL>key,<EOL>len(values),<EOL>min(values),<EOL>statistics.mean(values),<EOL>statistics.median(values),<EOL>values[int(len(values) * <NUM_LIT> / <NUM_LIT:100>)],<EOL>max(values)<EOL>)<EOL><DEDENT>else:<EOL><INDENT>self.logger.info('<STR_LIT>', self.leader, key)<EOL><DEDENT>self.histogram_stats[key] = []<EOL><DEDENT>


self.rollup()<EOL>self.incr_stats.setdefault(stat, []).append(value)<EOL>


self.rollup()<EOL>self.gauge_stats.setdefault(stat, []).append(value)<EOL>


self.histogram(stat, value, tags)<EOL>

Measure a timing for statistical distribution.

        Note: timing is a special case of histogram.


self.rollup()<EOL>self.histogram_stats.setdefault(stat, []).append(value)<EOL>


self.options = options<EOL>

Implement this. The options dict is the user-specified options.


raise NotImplementedError<EOL>

Implement this. This is a counter-type metric.


raise NotImplementedError<EOL>

Implement this. This is a gauge-type metric.


raise NotImplementedError<EOL>

Implement this. This is a timing-type metric.


raise NotImplementedError<EOL>

Implement this. This is a histogram-type metric.


self.client.incr(stat=stat, count=value)<EOL>


self.client.gauge(stat=stat, value=value)<EOL>


self.client.timing(stat=stat, delta=value)<EOL>


Measure a value for statistical distribution.

        Note: Since pystatsd has no "histogram", this does the same thing
        as timing.


self.client.increment(metric=stat, value=value, tags=tags)<EOL>


self.client.gauge(metric=stat, value=value, tags=tags)<EOL>


self.client.timing(metric=stat, value=value, tags=tags)<EOL>


self.client.histogram(metric=stat, value=value, tags=tags)<EOL>


<EOL>if not isinstance(key, six.string_types):<EOL><INDENT>raise ValueError('<STR_LIT>' % key)<EOL><DEDENT>if not isinstance(value, six.string_types + (NONE_TYPE,)):<EOL><INDENT>raise ValueError('<STR_LIT>' % value)<EOL><DEDENT>key = BAD_TAG_CHAR_REGEXP.sub('<STR_LIT:_>', key).strip()<EOL>if value is None or not value.strip():<EOL><INDENT>tag = key<EOL><DEDENT>else:<EOL><INDENT>value = BAD_TAG_CHAR_REGEXP.sub('<STR_LIT:_>', value).strip()<EOL>tag = '<STR_LIT>' % (key, value)<EOL><DEDENT>if tag and not tag[<NUM_LIT:0>].isalpha():<EOL><INDENT>tag = '<STR_LIT:a>' + tag<EOL><DEDENT>tag = tag.lower()[:<NUM_LIT:200>]<EOL>if tag in ['<STR_LIT>', '<STR_LIT:host>', '<STR_LIT:source>']:<EOL><INDENT>tag = tag + '<STR_LIT:_>'<EOL><DEDENT>return tag<EOL>

Generate a tag for use with the tag backends.

    The key and value (if there is one) are sanitized according to the
    following rules:

    1. after the first character, all characters must be alphanumeric,
       underscore, minus, period, or slash--invalid characters are converted
       to "_"
    2. lowercase

    If a value is provided, the final tag is `key:value`.

    The final tag must start with a letter. If it doesn't, an "a" is prepended.

    The final tag is truncated to 200 characters.

    If the final tag is "device", "host", or "source", then a "_" will be
    appended the end.

    :arg str key: the key to use
    :arg str value: the value (if any)

    :returns: the final tag

    Examples:

    >>> generate_tag('yellow')
    'yellow'
    >>> generate_tag('rule', 'is_yellow')
    'rule:is_yellow'

    Example with ``incr``:

    >>> import markus
    >>> mymetrics = markus.get_metrics(__name__)

    >>> mymetrics.incr('somekey', value=1,
    ...                tags=[generate_tag('rule', 'is_yellow')])


loader = yaml.Loader(data)<EOL>def compose_node(parent, index):<EOL><INDENT>line = loader.line<EOL>node = Composer.compose_node(loader, parent, index)<EOL>node.__line__ = line + <NUM_LIT:1><EOL>return node<EOL><DEDENT>def construct_mapping(node, deep=False):<EOL><INDENT>mapping = dict()<EOL>errors = dict()<EOL>for key_node, value_node in node.value:<EOL><INDENT>key = key_node.value<EOL>if key in mapping:<EOL><INDENT>if key in errors:<EOL><INDENT>errors[key].append(key_node.__line__)<EOL><DEDENT>else:<EOL><INDENT>errors[key] = [mapping[key], key_node.__line__]<EOL><DEDENT><DEDENT>mapping[key] = key_node.__line__<EOL><DEDENT>return errors<EOL><DEDENT>loader.compose_node = compose_node<EOL>loader.construct_mapping = construct_mapping<EOL>data = loader.get_single_data()<EOL>return data<EOL>

Parses yaml and returns a list of repeated variables and
       the line on which they occur


with open(filename, encoding=encoding) as source:<EOL><INDENT>for line in source:<EOL><INDENT>for word in line.split():<EOL><INDENT>yield word<EOL><DEDENT><DEDENT><DEDENT>

!DEMO!
Simple file parsing generator

Args:
    filename: absolute or relative path to file on disk
    encoding: encoding string that is passed to open function


super(ObjectLikeDbfilenameShelf, self).__setattr__('<STR_LIT>', ds)<EOL>


def __init__(self, iterable, step_size):

self.iterator = iter(iterable)<EOL>self.step_size = step_size<EOL>self.buffer = (None, ) + tuple(next(self.iterator) for x in range(step_size-<NUM_LIT:1>))<EOL>

Args:
    iterable: iterable object (object that can be turned into iterator)
    step_size: number of elements returned at once


if self._start_words is not None:<EOL><INDENT>return self._start_words<EOL><DEDENT>else:<EOL><INDENT>self._start_words = list(filter(<EOL>lambda x: str.isupper(x[<NUM_LIT:0>][<NUM_LIT:0>]) and x[<NUM_LIT:0>][-<NUM_LIT:1>] not in ['<STR_LIT:.>', '<STR_LIT:?>', '<STR_LIT:!>'],<EOL>self.content.keys()<EOL>))<EOL>return self._start_words<EOL><DEDENT>

!DEMO!
Cached list of keys that can be used to generate sentence.


self._start_words = None<EOL>


self.ds = shelve.open(shelve_file, writeback=True)<EOL>self.chains = ObjectLikeDbfilenameShelf(self.ds)<EOL>

Args:
    shelve_file: path to shelve file on disk


if name not in self.chains:<EOL><INDENT>setattr(self.chains, name, MarkovChain(order=order))<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>

Add chain to current shelve file

Args:
    name: chain name
    order: markov chain order


if name in self.chains:<EOL><INDENT>delattr(self.chains, name)<EOL><DEDENT>else:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>

Remove chain from current shelve file

Args:
    name: chain name


for group in WalkByGroup(source, chain.order+<NUM_LIT:1>):<EOL><INDENT>pre = group[:-<NUM_LIT:1>]<EOL>res = group[-<NUM_LIT:1>]<EOL>if pre not in chain.content:<EOL><INDENT>chain.content[pre] = {res: <NUM_LIT:1>}<EOL><DEDENT>else:<EOL><INDENT>if res not in chain.content[pre]:<EOL><INDENT>chain.content[pre][res] = <NUM_LIT:1><EOL><DEDENT>else:<EOL><INDENT>chain.content[pre][res] += <NUM_LIT:1><EOL><DEDENT><DEDENT><DEDENT>chain.decache()<EOL>

Build markov chain from source on top of existin chain

Args:
    source: iterable which will be used to build chain
    chain: MarkovChain in currently loaded shelve file that
           will be extended by source


def weighted_choice(choices):<EOL><INDENT>total_weight = sum(weight for val, weight in choices)<EOL>rand = random.uniform(<NUM_LIT:0>, total_weight)<EOL>upto = <NUM_LIT:0><EOL>for val, weight in choices:<EOL><INDENT>if upto + weight >= rand:<EOL><INDENT>return val<EOL><DEDENT>upto += weight<EOL><DEDENT><DEDENT>sentence = list(random.choice(chain.startwords))<EOL>while not sentence[-<NUM_LIT:1>][-<NUM_LIT:1>] in ['<STR_LIT:.>', '<STR_LIT:?>', '<STR_LIT:!>']:<EOL><INDENT>sentence.append(<EOL>weighted_choice(<EOL>chain.content[tuple(sentence[-<NUM_LIT:2>:])].items()<EOL>)<EOL>)<EOL><DEDENT>return '<STR_LIT:U+0020>'.join(sentence)<EOL>

!DEMO!
Demo function that shows how to generate a simple sentence starting with
uppercase letter without lenght limit.

Args:
    chain: MarkovChain that will be used to generate sentence


self.chains.close()<EOL>


stime = date_to_timestamp(start)<EOL>etime = date_to_timestamp(end)<EOL>ptime = stime + random.random() * (etime - stime)<EOL>return datetime.date.fromtimestamp(ptime)<EOL>


languages = languages or ['<STR_LIT>']<EOL>genders = genders or (GENDER_FEMALE, GENDER_MALE)<EOL>choices = _get_titles(languages)<EOL>gender = {'<STR_LIT:m>':<NUM_LIT:0>, '<STR_LIT:f>':<NUM_LIT:1>}[random.choice(genders)]<EOL>return random.choice(choices)[gender]<EOL>

returns a random title

.. code-block:: python

    >>> d.title()
    u'Mrs.'
    >>> d.title(['es'])
    u'El Sr.'
    >>> d.title(None, [GENDER_FEMALE])
    u'Mrs.'

:param languages: list of allowed languages. ['en'] if None
:param genders: list of allowed genders. (GENDER_FEMALE, GENDER_MALE) if None


return random.choice((GENDER_FEMALE, GENDER_MALE))<EOL>


languages = languages or ['<STR_LIT>']<EOL>genders = genders or (GENDER_FEMALE, GENDER_MALE)<EOL>lang = random.choice(languages)<EOL>g = random.choice(genders)<EOL>t = title([lang], [g])<EOL>return first_name([lang], [g]), last_name([lang]), t, g<EOL>

returns a random tuple representing person information

.. code-block:: python

    >>> d.person()
    (u'Derren', u'Powell', 'm')
    >>> d.person(genders=['f'])
    (u'Marge', u'Rodriguez', u'Mrs.', 'f')
    >>> d.person(['es'],['m'])
    (u'Jacinto', u'Delgado', u'El Sr.', 'm')

:param language:
:param genders:


choices = []<EOL>languages = languages or ['<STR_LIT>']<EOL>genders = genders or [GENDER_MALE, GENDER_FEMALE]<EOL>for lang in languages:<EOL><INDENT>for gender in genders:<EOL><INDENT>samples = _get_firstnames(lang, gender)<EOL>choices.extend(samples)<EOL><DEDENT><DEDENT>return random.choice(choices).title()<EOL>

return a random first name
:return:

>>> from mock import patch
>>> with patch('%s._get_firstnamess' % __name__, lambda *args: ['aaa']):
...     first_name()
'Aaa'


choices = []<EOL>languages = languages or ['<STR_LIT>']<EOL>for lang in languages:<EOL><INDENT>samples = _get_lastnames(lang)<EOL>choices.extend(samples)<EOL><DEDENT>return random.choice(choices).title()<EOL>

return a random last name

>>> from mock import patch
>>> with patch('%s._get_lastnames' % __name__, lambda *args: ['aaa']):
...     last_name()
'Aaa'
>>> with patch('%s.get_lastnames' % __name__, lambda lang: ['%s_lastname'% lang]):
...     last_name(['it'])
'It_Lastname'


cache_filename = os.path.join(os.path.dirname(__file__), '<STR_LIT:data>', '<STR_LIT>')<EOL>data = []<EOL>for line in open(cache_filename, '<STR_LIT:r>'):<EOL><INDENT>if not line.startswith('<STR_LIT:#>'):<EOL><INDENT>data.append(line.split('<STR_LIT:\t>'))<EOL><DEDENT><DEDENT>return data<EOL>

>> get_codes()
ISO	ISO3	ISO-Numeric	fips	Country	Capital	Area(in sq km)	Population	Continent	tld	CurrencyCode	CurrencyName	Phone	Postal Code Format	Postal Code Regex	Languages	geonameid	neighbours	EquivalentFipsCode


codes = get_codes()<EOL>selection = choice(codes)<EOL>return selection[<NUM_LIT:0>:<NUM_LIT:3>] + selection[<NUM_LIT:4>:<NUM_LIT:5>] + selection[<NUM_LIT:8>:<NUM_LIT:12>]<EOL>

>> country()
['SZ', 'SWZ', '748', 'Swaziland', 'AF', '.sz', 'SZL', 'Lilangeni']

:return: (iso2,iso3,isonum,CountryName,Continent,tld,CurrencyCode,CurrencyName


def amount(min=<NUM_LIT:1>, max=sys.maxsize, decimal_places=<NUM_LIT:2>):

q = '<STR_LIT>' % '<STR_LIT:0>' * (decimal_places - <NUM_LIT:1>)<EOL>return decimal.Decimal(uniform(min, max)).quantize(decimal.Decimal(q))<EOL>

return a random floating number

:param min: minimum value
:param max: maximum value
:param decimal_places: decimal places
:return:


codes = ['<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>',<EOL>'<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>']<EOL>return choice(codes)<EOL>


not_valid_class_A = not_valid or []<EOL>class_a = [r for r in range(<NUM_LIT:1>, <NUM_LIT>) if r not in not_valid_class_A]<EOL>shuffle(class_a)<EOL>first = class_a.pop()<EOL>return "<STR_LIT:.>".join([str(first), str(randrange(<NUM_LIT:1>, <NUM_LIT>)),<EOL>str(randrange(<NUM_LIT:1>, <NUM_LIT>)), str(randrange(<NUM_LIT:1>, <NUM_LIT>))])<EOL>

returns a string representing a random ip address

:param not_valid: if passed must be a list of integers representing valid class A netoworks that must be ignored


def ip(private=True, public=True, max_attempts=<NUM_LIT>):

if not (private or public):<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if private != public:<EOL><INDENT>if private:<EOL><INDENT>is_valid = lambda address: address.is_private()<EOL>not_valid = [n for n in range(<NUM_LIT:1>, <NUM_LIT:255>) if n not in NOT_NET]<EOL><DEDENT>else:<EOL><INDENT>is_valid = lambda address: not address.is_private()<EOL>not_valid = NOT_NET<EOL><DEDENT>attempt = <NUM_LIT:0><EOL>while attempt < max_attempts:<EOL><INDENT>attempt += <NUM_LIT:1><EOL>ip = IPAddress(ipaddress(not_valid))<EOL>if is_valid(ip):<EOL><INDENT>return ip<EOL><DEDENT><DEDENT><DEDENT>else:<EOL><INDENT>return IPAddress(ipaddress())<EOL><DEDENT>

returns a :class:`netaddr.IPAddress` instance with a random value

:param private: if False does not return private networks
:param public:  if False does not return public networks
:param max_attempts:


return '<STR_LIT>'.join(choice(choices) for x in range(length))<EOL>

returns a random (fixed length) string

    :param length: string length
    :param choices: string containing all the chars can be used to build the string

    .. seealso::
       :py:func:`rtext`


def rtext(maxlength, minlength=<NUM_LIT:1>, choices=string.ascii_letters):

return '<STR_LIT>'.join(choice(choices) for x in range(randint(minlength, maxlength)))<EOL>

returns a random (variable length) string.

        :param maxlength: maximum string length
        :param minlength: minimum string length
        :param choices: string containing all the chars can be used to build the string

        .. seealso::
           :py:func:`text`


if version is None:<EOL><INDENT>version = VERSION<EOL><DEDENT>assert len(version) == <NUM_LIT:5><EOL>assert version[<NUM_LIT:3>] in ('<STR_LIT>', '<STR_LIT>', '<STR_LIT>', '<STR_LIT>')<EOL>parts = <NUM_LIT:2> if version[<NUM_LIT:2>] == <NUM_LIT:0> else <NUM_LIT:3><EOL>main = '<STR_LIT:.>'.join(str(x) for x in version[:parts])<EOL>sub = '<STR_LIT>'<EOL>if version[<NUM_LIT:3>] == '<STR_LIT>' and version[<NUM_LIT:4>] == <NUM_LIT:0>:<EOL><INDENT>git_changeset = get_git_changeset()<EOL>if git_changeset:<EOL><INDENT>sub = '<STR_LIT>' % git_changeset<EOL><DEDENT><DEDENT>elif version[<NUM_LIT:3>] != '<STR_LIT>':<EOL><INDENT>mapping = {'<STR_LIT>': '<STR_LIT:a>', '<STR_LIT>': '<STR_LIT:b>', '<STR_LIT>': '<STR_LIT:c>'}<EOL>sub = mapping[version[<NUM_LIT:3>]] + str(version[<NUM_LIT:4>])<EOL><DEDENT>return main + sub<EOL>

Derives a PEP386-compliant version number from VERSION.


repo_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))<EOL>git_log = subprocess.Popen('<STR_LIT>',<EOL>stdout=subprocess.PIPE, stderr=subprocess.PIPE,<EOL>shell=True, cwd=repo_dir, universal_newlines=True)<EOL>timestamp = git_log.communicate()[<NUM_LIT:0>]<EOL>try:<EOL><INDENT>timestamp = datetime.datetime.utcfromtimestamp(int(timestamp))<EOL><DEDENT>except ValueError:<EOL><INDENT>return None<EOL><DEDENT>return timestamp.strftime('<STR_LIT>')<EOL>

Returns a numeric identifier of the latest git changeset.

The result is the UTC timestamp of the changeset in YYYYMMDDHHMMSS format.
This value isn't guaranteed to be unique, but collisions are very unlikely,
so it's sufficient for generating the development version numbers.


i = <NUM_LIT:0><EOL>while <NUM_LIT:1>:<EOL><INDENT>yield i<EOL>i += <NUM_LIT:1><EOL><DEDENT>


if cache is None:<EOL><INDENT>cache = _sequence_counters<EOL><DEDENT>if cache == -<NUM_LIT:1>:<EOL><INDENT>cache = {}<EOL><DEDENT>if prefix not in cache:<EOL><INDENT>cache[prefix] = infinite()<EOL><DEDENT>while cache[prefix]:<EOL><INDENT>yield "<STR_LIT>".format(prefix, next(cache[prefix]))<EOL><DEDENT>

generator that returns an unique string

:param prefix: prefix of string
:param cache: cache used to store the last used number

>>> next(sequence('abc'))
'abc-0'
>>> next(sequence('abc'))
'abc-1'


def _get_memoized_value(func, args, kwargs):

key = (repr(args), repr(kwargs))<EOL>if not key in func._cache_dict:<EOL><INDENT>ret = func(*args, **kwargs)<EOL>func._cache_dict[key] = ret<EOL><DEDENT>return func._cache_dict[key]<EOL>

Used internally by memoize decorator to get/store function results


func._cache_dict = {}<EOL>@wraps(func)<EOL>def _inner(*args, **kwargs):<EOL><INDENT>return _get_memoized_value(func, args, kwargs)<EOL><DEDENT>return _inner<EOL>

Decorator that stores function results in a dictionary to be used on the
    next time that the same arguments were informed.


def unique(func, num_args=<NUM_LIT:0>, max_attempts=<NUM_LIT:100>, cache=None):

if cache is None:<EOL><INDENT>cache = _cache_unique<EOL><DEDENT>@wraps(func)<EOL>def wrapper(*args):<EOL><INDENT>key = "<STR_LIT>" % (str(func.__name__), str(args[:num_args]))<EOL>attempt = <NUM_LIT:0><EOL>while attempt < max_attempts:<EOL><INDENT>attempt += <NUM_LIT:1><EOL>drawn = cache.get(key, [])<EOL>result = func(*args)<EOL>if result not in drawn:<EOL><INDENT>drawn.append(result)<EOL>cache[key] = drawn<EOL>return result<EOL><DEDENT><DEDENT>raise MaxAttemptException()<EOL><DEDENT>return wrapper<EOL>

wraps a function so that produce unique results

:param func:
:param num_args:

>>> import random
>>> choices = [1,2]
>>> a = unique(random.choice, 1)
>>> a,b = a(choices), a(choices)
>>> a == b
False


return int(text(int(length), choices=string.digits))<EOL>

return a random integer

:param length: number of digits


return text(int(length), choices=string.hexdigits)<EOL>

return a random  string represents hexadecimal number of `length` size

:param length: length (without 0x prefix)


num = randint(<NUM_LIT:1>, <NUM_LIT>)<EOL>mask = '<STR_LIT:0>' * length<EOL>return (mask + '<STR_LIT>'.join([str(num >> i & <NUM_LIT:1>) for i in range(<NUM_LIT:7>, -<NUM_LIT:1>, -<NUM_LIT:1>)]))[-length:]<EOL>

returns a a random string that represent a binary representation

:param length: number of bits


def make_link_node(rawtext, app, type, slug, options):

try:<EOL><INDENT>base = app.config.github_project_url<EOL>if not base:<EOL><INDENT>raise AttributeError<EOL><DEDENT>if not base.endswith('<STR_LIT:/>'):<EOL><INDENT>base += '<STR_LIT:/>'<EOL><DEDENT><DEDENT>except AttributeError as err:<EOL><INDENT>raise ValueError('<STR_LIT>' % str(err))<EOL><DEDENT>ref = base + type + '<STR_LIT:/>' + slug + '<STR_LIT:/>'<EOL>set_classes(options)<EOL>prefix = "<STR_LIT:#>"<EOL>if type == '<STR_LIT>':<EOL><INDENT>prefix = "<STR_LIT>" + prefix<EOL><DEDENT>node = nodes.reference(rawtext, prefix + utils.unescape(slug), refuri=ref,<EOL>**options)<EOL>return node<EOL>

Create a link to a github resource.

    :param rawtext: Text being replaced with link node.
    :param app: Sphinx application context
    :param type: Link type (issues, changeset, etc.)
    :param slug: ID of the thing to link to
    :param options: Options dictionary passed to role func.


def ghissue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):

try:<EOL><INDENT>issue_num = int(text)<EOL>if issue_num <= <NUM_LIT:0>:<EOL><INDENT>raise ValueError<EOL><DEDENT><DEDENT>except ValueError:<EOL><INDENT>msg = inliner.reporter.error(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>' % text, line=lineno)<EOL>prb = inliner.problematic(rawtext, rawtext, msg)<EOL>return [prb], [msg]<EOL><DEDENT>app = inliner.document.settings.env.app<EOL>if '<STR_LIT>' in name.lower():<EOL><INDENT>category = '<STR_LIT>'<EOL><DEDENT>elif '<STR_LIT>' in name.lower():<EOL><INDENT>category = '<STR_LIT>'<EOL><DEDENT>else:<EOL><INDENT>msg = inliner.reporter.error(<EOL>'<STR_LIT>'<EOL>'<STR_LIT>' % name, line=lineno)<EOL>prb = inliner.problematic(rawtext, rawtext, msg)<EOL>return [prb], [msg]<EOL><DEDENT>node = make_link_node(rawtext, app, category, str(issue_num), options)<EOL>return [node], []<EOL>

Link to a GitHub issue.

    Returns 2 part tuple containing list of nodes to insert into the
    document and a list of system messages.  Both are allowed to be
    empty.

    :param name: The role name used in the document.
    :param rawtext: The entire markup snippet, with role.
    :param text: The text marked with the role.
    :param lineno: The line number where rawtext appears in the input.
    :param inliner: The inliner instance that called us.
    :param options: Directive options for customization.
    :param content: The directive content for customization.


def ghuser_role(name, rawtext, text, lineno, inliner, options={}, content=[]):

<EOL>ref = '<STR_LIT>' + text<EOL>node = nodes.reference(rawtext, text, refuri=ref, **options)<EOL>return [node], []<EOL>

Link to a GitHub user.

    Returns 2 part tuple containing list of nodes to insert into the
    document and a list of system messages.  Both are allowed to be
    empty.

    :param name: The role name used in the document.
    :param rawtext: The entire markup snippet, with role.
    :param text: The text marked with the role.
    :param lineno: The line number where rawtext appears in the input.
    :param inliner: The inliner instance that called us.
    :param options: Directive options for customization.
    :param content: The directive content for customization.