# nobodd.netascii

Registers a Python codec to translate strings to the TFTP netascii encoding (defined in the TELNET RFC 764, under the printer and keyboard section). This is intended to translate line-endings of text files transparently between platforms, but only handles ASCII characters.

Note

TFTPd implementations could probably ignore this as a historical artefact at this point and assume all transfers will be done with “octet” (straight byte for byte) encoding, as seems to be common practice. However, netascii isn’t terribly hard to support, hence the inclusion of this module.

The functions in this module should never need to be accessed directly. Simply use the ‘netascii’ encoding as you would any other Python byte-encoding:

    >>> import os
    >>> os.linesep
    '\n'
    >>> import nobodd.netascii
    >>> 'foo\nbar\r'.encode('netascii')
    b'foo\r\nbar\r\0'
    >>> b'foo\r\nbar\r\0\r\r'.decode('netascii', errors='replace')
    'foo\nbar\r??'

## Support functions

nobodd.netascii.encode(s, errors='strict', final=False)

  Encodes the `str` s, which must only contain valid ASCII characters, to the netascii `bytes` representation.

  The errors parameter specifies the handling of encoding errors in the typical manner (‘strict’, ‘ignore’, ‘replace’, etc). The final parameter indicates whether this is the end of the input. This only matters on the Windows platform where the line separator is ‘rn’ in which case a trailing ‘r’ character may be the start of a newline sequence.

  The return value is a tuple of the encoded `bytes` string, and the number of characters consumed from s (this may be less than the length of s when final is `False`).

nobodd.netascii.decode(s, errors='strict', final=False)

  Decodes the `bytes` string s, which must contain a netascii encoded string, to the `str` representation (which can only contain ASCII characters).

  The errors parameter specifies the handling of encoding errors in the typical manner (‘strict’, ‘ignore’, ‘replace’, etc). The final parameter indicates whether this is the end of the input. This matters as a trailing ‘r’ in the input is the beginning of a newline sequence, an encoded ‘r’, or an error (in other cases).

  The return value is a tuple of the decoded `str`, and the number of characters consumed from s (this may be less than the length of s when final is `False`).

class nobodd.netascii.IncrementalEncoder(errors='strict')

  Use `codecs.iterencode()` to utilize this class for encoding:

      >>> import os
      >>> os.linesep
      '\n'
      >>> import nobodd.netascii
      >>> import codecs
      >>> it = ['foo', '\n', 'bar\r']
      >>> b''.join(codecs.iterencode(it, 'netascii'))
      b'foo\r\nbar\r\0'

class nobodd.netascii.IncrementalDecoder(errors='strict')

  Use `codecs.iterdecode()` to utilize this class for encoding:

      >>> import os
      >>> os.linesep
      '\n'
      >>> import nobodd.netascii
      >>> import codecs
      >>> it = [b'foo\r', b'\n', b'bar\r', b'\0']
      >>> ''.join(codecs.iterdecode(it, 'netascii'))
      'foo\nbar\r'

class nobodd.netascii.StreamWriter(stream, errors='strict')
  encode(s, errors='strict')

    Encodes the object input and returns a tuple (output object, length consumed).

    errors defines the error handling to apply. It defaults to ‘strict’ handling.

    The method may not store state in the Codec instance. Use StreamWriter for codecs which have to keep state in order to make encoding efficient.

    The encoder must be able to handle zero length input and return an empty object of the output object type in this situation.

  reset()

    Resets the codec buffers used for keeping internal state.

    Calling this method should ensure that the data on the output is put into a clean state, that allows appending of new fresh data without having to rescan the whole stream to recover state.

class nobodd.netascii.StreamReader(stream, errors='strict')
  decode(s, errors='strict', final=False)

    Decodes the object input and returns a tuple (output object, length consumed).

    input must be an object which provides the bf_getreadbuf buffer slot. Python strings, buffer objects and memory mapped files are examples of objects providing this slot.

    errors defines the error handling to apply. It defaults to ‘strict’ handling.

    The method may not store state in the Codec instance. Use StreamReader for codecs which have to keep state in order to make decoding efficient.

    The decoder must be able to handle zero length input and return an empty object of the output object type in this situation.