# `taurus.core.util.codecs`

This module contains a list of codecs for the DEV_ENCODED attribute type. All codecs are based on the pair format, data. The format is a string containing the codec signature and data is a sequence of bytes (string) containing the encoded data.

This module contains a list of codecs capable of decoding several codings like bz2, zip and json.

The `CodecFactory` class allows you to get a codec object for a given format and also to register new codecs. The `CodecPipeline` is a special codec that is able to code/decode a sequence of codecs. This way you can have codecs ‘inside’ codecs.

Example:

    >>> from taurus.core.util.codecs import CodecFactory
    >>> cf = CodecFactory()
    >>> json_codec = cf.getCodec('json')
    >>> bz2_json_codec = cf.getCodec('bz2_json')
    >>> data = range(100000)
    >>> f1, enc_d1 = json_codec.encode(('', data))
    >>> f2, enc_d2 = bz2_json_codec.encode(('', data))
    >>> print(len(enc_d1), len(enc_d2))
    688890 123511
    >>>
    >>> f1, dec_d1 = json_codec.decode((f1, enc_d1))
    >>> f2, dec_d2 = bz2_json_codec.decode((f2, enc_d2))

A Taurus related example:

    >>> # automatically get the data from a DEV_ENCODED attribute
    >>> import taurus
    >>> from taurus.core.util.codecs import CodecFactory
    >>> cf = CodecFactory()
    >>> devenc_attr = taurus.Attribute('a/b/c/devenc_attr')
    >>> v = devenc_attr.read()
    >>> codec = CodecFactory().getCodec(v.format)
    >>> f, d = codec.decode((v.format, v.value))

Classes

class BZ2Codec

  A codec able to encode/decode to/from BZ2 format. It uses the `bz2` module

  Example:

      >>> from taurus.core.util.codecs import CodecFactory

      >>> # first encode something
      >>> data = 100 * "Hello world\n"
      >>> cf = CodecFactory()
      >>> codec = cf.getCodec('bz2')
      >>> format, encoded_data = codec.encode(("", data))
      >>> print(len(data), len(encoded_data))
      1200, 68
      >>> format, decoded_data = codec.decode((format, encoded_data))
      >>> print(decoded_data[20])
      'Hello world\nHello wo'

  (more info)

class Codec

  The base class for all codecs

  (more info)

class CodecFactory(*p, **k)

  The singleton CodecFactory class.

  To get the singleton object do:

      from taurus.core.util.codecs import CodecFactory
      f = CodecFactory()

  The `CodecFactory` class allows you to get a codec object for a given format and also to register new codecs.

  The `CodecPipeline` is a special codec that is able to code/decode a sequence of codecs. This way you can have codecs ‘inside’ codecs.

  Example:

      >>> from taurus.core.util.codecs import CodecFactory
      >>> cf = CodecFactory()
      >>> json_codec = cf.getCodec('json')
      >>> bz2_json_codec = cf.getCodec('bz2_json')
      >>> data = range(100000)
      >>> f1, enc_d1 = json_codec.encode(('', data))
      >>> f2, enc_d2 = bz2_json_codec.encode(('', data))
      >>> print(len(enc_d1), len(enc_d2))
      688890 123511
      >>>
      >>> f1, dec_d1 = json_codec.decode((f1, enc_d1))
      >>> f2, dec_d2 = bz2_json_codec.decode((f2, enc_d2))

  A Taurus related example:

      >>> # automatically get the data from a DEV_ENCODED attribute
      >>> import taurus
      >>> from taurus.core.util.codecs import CodecFactory
      >>> cf = CodecFactory()
      >>> devenc_attr = taurus.Attribute('a/b/c/devenc_attr')
      >>> v = devenc_attr.read()
      >>> codec = CodecFactory().getCodec(v.format)
      >>> f, d = codec.decode((v.format, v.value))

  (more info)

class CodecPipeline(format)

  The codec class used when encoding/decoding data with multiple encoders

  Example usage:

      >>> from taurus.core.util.codecs import CodecPipeline

      >>> data = range(100000)
      >>> codec = CodecPipeline('bz2_json')
      >>> format, encoded_data = codec.encode(("", data))

      # decode it
      format, decoded_data = codec.decode((format, encoded_data))
      print(decoded_data)

  (more info)

class FunctionCodec(func_name)

  A generic function codec

  (more info)

class JSONCodec

  A codec able to encode/decode to/from json format. It uses the `json` module.

  Example:

      >>> from taurus.core.util.codecs import CodecFactory

      >>> cf = CodecFactory()
      >>> codec = cf.getCodec('json')
      >>>
      >>> # first encode something
      >>> data = { 'hello' : 'world', 'goodbye' : 1000 }
      >>> format, encoded_data = codec.encode(("", data))
      >>> print(encoded_data)
      '{"hello": "world", "goodbye": 1000}'
      >>>
      >>> # now decode it
      >>> format, decoded_data = codec.decode((format, encoded_data))
      >>> print(decoded_data)
      {'hello': 'world', 'goodbye': 1000}

  (more info)

class NullCodec

  (more info)

class PlotCodec

  A specialization of the `FunctionCodec` for plot function

  (more info)

class Utf8Codec

  A codec able to encode/decode utf8 strings to/from bytes. Useful to adapt i/o encodings in a codec pipe.

  Example:

      >>> from taurus.core.util.codecs import CodecFactory

      >>> cf = CodecFactory()
      >>> codec = cf.getCodec('zip_utf8_json')
      >>>
      >>> # first encode something
      >>> data = { 'hello' : 'world', 'goodbye' : 1000 }
      >>> format, encoded_data = codec.encode(("", data))
      >>>
      >>> # now decode it
      >>> _, decoded_data = codec.decode((format, encoded_data))
      >>> print(decoded_data)

  (more info)

class ZIPCodec

  A codec able to encode/decode to/from gzip format. It uses the `zlib` module

  Example:

      >>> from taurus.core.util.codecs import CodecFactory

      >>> # first encode something
      >>> data = 100 * "Hello world\n"
      >>> cf = CodecFactory()
      >>> codec = cf.getCodec('zip')
      >>> format, encoded_data = codec.encode(("", data))
      >>> print(len(data), len(encoded_data))
      1200, 31
      >>> format, decoded_data = codec.decode((format, encoded_data))
      >>> print(decoded_data[20])
      'Hello world\nHello wo'

  (more info)