# opentelemetry.propagators.textmap

## Module contents

class opentelemetry.propagators.textmap.Getter

  Bases: `ABC`, `Generic`[`CarrierT`]

  This class implements a Getter that enables extracting propagated fields from a carrier.

  abstractmethod get(carrier, key)

    Function that can retrieve zero or more values from the carrier. In the case that the value does not exist, returns None.

    Parameters:

      - carrier (`TypeVar`(`CarrierT`)) – An object which contains values that are used to construct a Context.

      - key (`str`) – key of a field in carrier.

    Return type:

      `list`[`str`] | `None`

    Returns: first value of the propagation key or None if the key doesn’t

      exist.

  abstractmethod keys(carrier)

    Function that can retrieve all the keys in a carrier object.

    Parameters:

      carrier (`TypeVar`(`CarrierT`)) – An object which contains values that are used to construct a Context.

    Return type:

      `list`[`str`]

    Returns:

      list of keys from the carrier.

class opentelemetry.propagators.textmap.Setter

  Bases: `ABC`, `Generic`[`CarrierT`]

  This class implements a Setter that enables injecting propagated fields into a carrier.

  abstractmethod set(carrier, key, value)

    Function that can set a value into a carrier””

    Parameters:

      - carrier (`TypeVar`(`CarrierT`)) – An object which contains values that are used to construct a Context.

      - key (`str`) – key of a field in carrier.

      - value (`str`) – value for a field in carrier.

    Return type:

      `None`

class opentelemetry.propagators.textmap.DefaultGetter

  Bases: `Getter`[`Mapping`[`str`, `list`[`str`] | `str`]]

  get(carrier, key)

    Getter implementation to retrieve a value from a dictionary.

    Parameters:

      - carrier (`Mapping`[`str`, `list`[`str`] | `str`]) – dictionary in which to get value

      - key (`str`) – the key used to get the value

    Return type:

      `list`[`str`] | `None`

    Returns:

      A list with a single string with the value if it exists, else None.

  keys(carrier)

    Keys implementation that returns all keys from a dictionary.

    Return type:

      `list`[`str`]

class opentelemetry.propagators.textmap.DefaultSetter

  Bases: `Setter`[`MutableMapping`[`str`, `list`[`str`] | `str`]]

  set(carrier, key, value)

    Setter implementation to set a value into a dictionary.

    Parameters:

      - carrier (`MutableMapping`[`str`, `list`[`str`] | `str`]) – dictionary in which to set value

      - key (`str`) – the key used to set the value

      - value (`list`[`str`] | `str`) – the value to set

    Return type:

      `None`

class opentelemetry.propagators.textmap.TextMapPropagator

  Bases: `ABC`

  This class provides an interface that enables extracting and injecting context into headers of HTTP requests. HTTP frameworks and clients can integrate with TextMapPropagator by providing the object containing the headers, and a getter and setter function for the extraction and injection of values, respectively.

  abstractmethod extract(carrier, context=None, getter=<opentelemetry.propagators.textmap.DefaultGetter object>)

    Create a Context from values in the carrier.

    The extract function should retrieve values from the carrier object using getter, and use values to populate a Context value and return it.

    Parameters:

      - getter (`Getter`[`TypeVar`(`CarrierT`)]) – a function that can retrieve zero or more values from the carrier. In the case that the value does not exist, return an empty list.

      - carrier (`TypeVar`(`CarrierT`)) – and object which contains values that are used to construct a Context. This object must be paired with an appropriate getter which understands how to extract a value from it.

      - context (`Context` | `None`) – an optional Context to use. Defaults to root context if not set.

    Return type:

      `Context`

    Returns:

      A Context with configuration found in the carrier.

  abstractmethod inject(carrier, context=None, setter=<opentelemetry.propagators.textmap.DefaultSetter object>)

    Inject values from a Context into a carrier.

    inject enables the propagation of values into HTTP clients or other objects which perform an HTTP request. Implementations should use the `Setter` ‘s set method to set values on the carrier.

    Parameters:

      - carrier (`TypeVar`(`CarrierT`)) – An object that a place to define HTTP headers. Should be paired with setter, which should know how to set header values on the carrier.

      - context (`Context` | `None`) – an optional Context to use. Defaults to current context if not set.

      - setter (`Setter`[`TypeVar`(`CarrierT`)]) – An optional `Setter` object that can set values on the carrier.

    Return type:

      `None`

  abstract property fields: set[str]

    Gets the fields set in the carrier by the `inject` method.

    If the carrier is reused, its fields that correspond with the ones present in this attribute should be deleted before calling `inject`.

    Returns:

      A set with the fields set in `inject`.