# Welcome to stringtools’s documentation!

## stringtools (Stringtools)

Author:

- Dirk Alders <sudo-dirk@mount-mockery.de>

Description:

> This Module supports functionality around string operations.

Submodules:

- `stringtools.csp`
- `stringtools.stp`
- `gzip_compress()`
- `gzip_extract()`
- `hexlify()`

Unittest:

> See also the `unittest` documentation.

Module Documentation:

`stringtools.``gzip_compress`(s, compresslevel=9)

  Method to compress a stream of bytes.

  Parameters: | s (str) – The bytestream (string) to be compressed compresslevel (int) – An optional compressionn level (default is 9)
  Returns: | The compressed bytestream
  Return type: | str

  Example:

      import sys
      sys.path.append('../..')

      import stringtools
      import report

      report.stdoutLoggingConfigure(log_name_lvl=[('root', 'DEBUG'), ])
      print(stringtools.hexlify(stringtools.gzip_compress(15 * b'\x00' + 15 * b'\xff')))

  Will result to the following output:

      2021-01-03 20:57:12,305: root.stringtools - DEBUG - GZIP: Finished to compress a string (compression_rate=0.867, consumed_time=0.0s).
      (26): 1f 8b 08 00 98 21 f2 5f 02 ff 63 60 40 01 ff 51 01 00 2d 8a 7d de 1e 00 00 00

`stringtools.``gzip_extract`(s)

  Method to extract data from a compress stream of bytes.

  Parameters: | s (str) – The compressed bytestream (string) to be extracted
  Returns: | The extracted data
  Return type: | str

  Example:

      import sys
      sys.path.append('../..')

      import stringtools
      import report

      report.stdoutLoggingConfigure(log_name_lvl=[('root', 'DEBUG'), ])
      print(stringtools.hexlify(stringtools.gzip_extract(b'\x1f\x8b\x08\x00\xd0\x82\xe5\x5c\x02\xff\x63\x60\x40\x01\xff\x51\x01\x00\x2d\x8a\x7d\xde\x1e\x00\x00\x00')))

  Will result to the following output:

      2021-01-03 20:57:12,210: root.stringtools - DEBUG - GZIP: Finished to extract a string (compression_rate=0.867, consumed_time=0.0s).
      (30): 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff

`stringtools.``hexlify`(s)

  Method to hexlify a string.

  Parameters: | s (str) – A string including the bytes to be hexlified.
  Returns: | The hexlified string
  Return type: | str

  Example:

      import sys
      sys.path.append('../..')

      import stringtools

      print(stringtools.hexlify(b'A stringexample with non printable characters like \x12'))

  Will result to the following output:

      (52): 41 20 73 74 72 69 6e 67 65 78 61 6d 70 6c 65 20 77 69 74 68 20 6e 6f 6e 20 70 72 69 6e 74 61 62 6c 65 20 63 68 61 72 61 63 74 65 72 73 20 6c 69 6b 65 20 12

## stringtools.csp (Carriage-Return seperation protocol)

Author:

- Dirk Alders <sudo-dirk@mount-mockery.de>

Description:

> This module is a submodule of `stringtools` and creates an frame to transmit and receive messages via an serial interface.

Submodules:

- `stringtools.csp.csp`
- `stringtools.csp.build_frame()`

`stringtools.csp.``build_frame`(msg, seperator=b'\n')

  This Method builds an “csp-frame” to be transfered via a stream.

  Parameters: | data (str) – A String (Bytes) to be framed
  Returns: | The “csp-framed” message to be sent
  Return type: | str

  Example:

      import sys
      sys.path.append('../..')

      import stringtools

      data = b'message'
      print(stringtools.hexlify(data))
      print(stringtools.hexlify(stringtools.csp.build_frame(data)))

  Will result to the following output:

      (7): 6d 65 73 73 61 67 65
      (8): 6d 65 73 73 61 67 65 0a

class `stringtools.csp.``csp`(seperator=b'n')

  This class extracts messages from an “csp-stream”.

  Example:

      import sys
      sys.path.append('../..')

      import report
      import stringtools

      report.stdoutLoggingConfigure(log_name_lvl=[('root', 'DEBUG'), ])
      s = stringtools.csp.csp()
      for byte in b'message\n':
          data = s.process(bytes([byte]))
          if len(data) > 0:
              print(data)

  Will result to the following output:

      2021-01-03 20:57:12,362: root.stringtools.csp - DEBUG - CSP: Leaving data in buffer (to be processed next time): (1): 6d
      2021-01-03 20:57:12,362: root.stringtools.csp - DEBUG - CSP: Leaving data in buffer (to be processed next time): (2): 6d 65
      2021-01-03 20:57:12,362: root.stringtools.csp - DEBUG - CSP: Leaving data in buffer (to be processed next time): (3): 6d 65 73
      2021-01-03 20:57:12,362: root.stringtools.csp - DEBUG - CSP: Leaving data in buffer (to be processed next time): (4): 6d 65 73 73
      2021-01-03 20:57:12,362: root.stringtools.csp - DEBUG - CSP: Leaving data in buffer (to be processed next time): (5): 6d 65 73 73 61
      2021-01-03 20:57:12,362: root.stringtools.csp - DEBUG - CSP: Leaving data in buffer (to be processed next time): (6): 6d 65 73 73 61 67
      2021-01-03 20:57:12,362: root.stringtools.csp - DEBUG - CSP: Leaving data in buffer (to be processed next time): (7): 6d 65 73 73 61 67 65
      2021-01-03 20:57:12,362: root.stringtools.csp - INFO - CSP: message identified - (7): 6d 65 73 73 61 67 65
      [b'message']

  `process`(data)

    This processes a byte out of a “stp-stream”.

    Parameters: | data (bytes) – A byte stream
    Returns: | A list of the extracted message(s)
    Return type: | list

## stringtools.stp (Serial transfer protocol)

Author:

- Dirk Alders <sudo-dirk@mount-mockery.de>

Description:

> This module is a submodule of `stringtools` and creates an serial frame to transmit and receive messages via an serial interface.

Submodules:

- `stringtools.stp.stp`
- `stringtools.stp.build_frame()`

`stringtools.stp.``DATA_CLEAR_BUFFER` = b'<'

  The clear buffer byte (‘\x3a\x3c’ -> start of message)

`stringtools.stp.``DATA_STORE_SYNC_VALUE` = b'='

  The store sync value byte (‘\x3a\x3d’ -> ‘\x3a’ inside a message)

`stringtools.stp.``DATA_SYNC` = b':'

  The data sync byte

`stringtools.stp.``DATA_VALID_MSG` = b'>'

  The valid message byte (‘\x3a\x3e’ -> end of message)

`stringtools.stp.``STP_STATE_ESCAPE_1` = 1

  Escape 1 state definition (‘\x3a\x3c’ found)

`stringtools.stp.``STP_STATE_ESCAPE_2` = 2

  Escape 2 state definition (‘\x3a’ found inside a message)

`stringtools.stp.``STP_STATE_IDLE` = 0

  Idle state definition (default)

`stringtools.stp.``STP_STATE_STORE_DATA` = 3

  Store data state definition (start of message found; data will be stored)

`stringtools.stp.``build_frame`(data)

  This Method builds an “stp-frame” to be transfered via a stream.

  Parameters: | data (str) – A String (Bytes) to be framed
  Returns: | The “stp-framed” message to be sent
  Return type: | str

  Example:

      import sys
      sys.path.append('../..')

      import stringtools

      print(repr(stringtools.stp.build_frame(b':message:')))

  Will result to the following output:

      b':<:=message:=:>'

class `stringtools.stp.``stp`

  This class extracts messages from an “stp-stream”.

  Example:

      import sys
      sys.path.append('../..')

      import report
      import stringtools

      report.stdoutLoggingConfigure(log_name_lvl=[('root', 'DEBUG'), ])
      s = stringtools.stp.stp()
      for byte in b':<:=message:=:>':
          data = s.process(bytes([byte]))
          if len(data) > 0:
              print(data)

  Will result to the following output:

      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: data sync (3a) received => changing state STP_STATE_IDLE -> STP_STATE_ESCAPE_1
      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: start pattern (3a 3c) received => changing state STP_STATE_ESCAPE_1 -> STP_STATE_STORE_DATA
      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: data sync (3a) received => changing state STP_STATE_STORE_DATA -> STP_STATE_ESCAPE_2
      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: store sync pattern (3a 3d) received => changing state STP_STATE_ESCAPE_2 -> STP_STATE_STORE_DATA
      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: data sync (3a) received => changing state STP_STATE_STORE_DATA -> STP_STATE_ESCAPE_2
      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: store sync pattern (3a 3d) received => changing state STP_STATE_ESCAPE_2 -> STP_STATE_STORE_DATA
      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: data sync (3a) received => changing state STP_STATE_STORE_DATA -> STP_STATE_ESCAPE_2
      2021-01-03 20:57:12,157: root.stringtools.stp - DEBUG - STP: end pattern (3a 3e) received => storing message and changing state STP_STATE_ESCAPE_2 -> STP_STATE_IDLE
      2021-01-03 20:57:12,157: root.stringtools.stp - INFO - STP: message identified - (9): 3a 6d 65 73 73 61 67 65 3a
      [b':message:']

  `process`(data)

    This processes a byte out of a “stp-stream”.

    Parameters: | data (bytes) – A byte stream
    Returns: | The extracted message or None, if no message is identified yet
    Return type: | str

# Indices and tables

- Index
- Module Index
- Search Page