secfury / base64io-python

A stream implementation for Python that provides transparent base64 encoding and decoding of an underlying stream.

base64io

This project is designed to develop a class, :class:`base64io.Base64IO`, that implements a streaming interface for Base64 encoding.

Python has supported native Base64 encoding since version 2.4. However, there is no streaming interface for Base64 encoding, and none is available from the community.

The legacy base64.encode and base64.decode interface lets you shuffle data between two streams, but it assumes that you have two complete streams. We wanted a standard stream that applies Base64 encoding and decoding.

:class:`base64io.Base64IO` provides an io streaming interface with context manager support that transparently Base64-encodes data read from it. You can use it to transform large files without caching the entire context in memory, or to transform an existing stream.

For the latest full documentation, see Read the Docs.

Find us on GitHub.

Getting Started

:class:`base64io.Base64IO` has no dependencies other than the standard library and should work with any version of Python greater than 2.6. We test it on CPython 2.6, 2.7, 3.3, 3.4, 3.5, 3.6, and 3.7.

Installation

$ pip install base64io

Use

:class:`base64io.Base64IO` wraps the input stream and transparently encodes or decodes data written to or read from the input stream.

• write() encodes data before writing it to the wrapped stream
• read() decodes data after reading it from the wrapped stream

Because the position of the :class:`base64io.Base64IO` stream and the wrapped stream will almost always be different, :class:`base64io.Base64IO` does not support:

• seek()
• tell()

Also, :class:`base64io.Base64IO` does not support:

• fileno()
• truncate()

Encode data

Warning

If you are not using :class:`base64io.Base64IO` as a context manager, when you write to a :class:`base64io.Base64IO` stream, you must close the stream after your final write. The Base64 transformation might hold up to two bytes of unencoded data in an internal buffer before writing it to the wrapped stream. Calling close() flushes this buffer and writes the padded result to the wrapped stream. The :class:`base64io.Base64IO` context manager does this for you.

from base64io import Base64IO

with open("source_file", "rb") as source, open("encoded_file", "wb") as target:
    with Base64IO(target) as encoded_target:
        for line in source:
            encoded_target.write(line)

Decode data

Note

When it reads data from the wrapping stream, it might read up to three additional bytes from the underlying stream.

from base64io import Base64IO

with open("encoded_file", "rb") as encoded_source, open("target_file", "wb") as target:
    with Base64IO(encoded_source) as source:
        for line in source:
            target.write(line)

License

This library is licensed under the Apache 2.0 License.