{"id":7040,"library":"base64io","title":"Base64 Streaming I/O","description":"`base64io` is a Python library that provides a file-like object interface for streaming Base64 encoding and decoding. It allows processing large files without loading their entire content into memory by wrapping an existing byte stream. The current version is 1.0.3, and due to its stable and specialized utility, releases are infrequent.","status":"active","version":"1.0.3","language":"en","source_language":"en","source_url":"https://github.com/aws/base64io-python","tags":["base64","io","streaming","aws","binary-data","file-like"],"install":[{"cmd":"pip install base64io","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Base64IO","correct":"from base64io import Base64IO"}],"quickstart":{"code":"import base64io\nimport tempfile\nimport os\n\n# Create dummy input files in a temporary directory\ndummy_input_bin_content = b\"Hello, base64io streaming!\"\ndummy_input_b64_content = b\"SGVsbG8sIGJhc2U2NGlvIHN0cmVhbWluZyE=\" # Base64 of the above\n\nwith tempfile.TemporaryDirectory() as tmpdir:\n    input_bin_path = os.path.join(tmpdir, 'input.bin')\n    input_b64_path = os.path.join(tmpdir, 'input.b64')\n    output_b64_path = os.path.join(tmpdir, 'output.b64')\n    output_bin_path = os.path.join(tmpdir, 'output.bin')\n\n    # Write dummy content to temporary files\n    with open(input_bin_path, 'wb') as f:\n        f.write(dummy_input_bin_content)\n    with open(input_b64_path, 'wb') as f:\n        f.write(dummy_input_b64_content)\n\n    print(f\"Temporary directory: {tmpdir}\")\n\n    # --- Encoding example ---\n    # Open original binary input, wrap with Base64IO for encoding\n    with open(input_bin_path, 'rb') as fin, base64io.Base64IO(fin, 'encode') as fenc:\n        # Write encoded content to output file\n        with open(output_b64_path, 'wb') as fout:\n            fout.write(fenc.read())\n    \n    # Verify encoded output\n    with open(output_b64_path, 'rb') as f:\n        encoded_output = f.read()\n    print(f\"Encoded content written to {output_b64_path}: {encoded_output}\")\n    assert encoded_output == dummy_input_b64_content\n\n    # --- Decoding example ---\n    # Open Base64 encoded input, wrap with Base64IO for decoding\n    with open(input_b64_path, 'rb') as fin, base64io.Base64IO(fin, 'decode') as fdec:\n        # Write decoded content to output file\n        with open(output_bin_path, 'wb') as fout:\n            fout.write(fdec.read())\n            \n    # Verify decoded output\n    with open(output_bin_path, 'rb') as f:\n        decoded_output = f.read()\n    print(f\"Decoded content written to {output_bin_path}: {decoded_output}\")\n    assert decoded_output == dummy_input_bin_content\n\nprint(\"Quickstart successful!\")","lang":"python","description":"This quickstart demonstrates how to use `base64io.Base64IO` to stream encode and decode content. It creates dummy binary and Base64 files, then uses `Base64IO` to transform them, verifying the output. Note that `Base64IO` always expects and produces byte streams."},"warnings":[{"fix":"Always open the underlying file with a binary mode, such as `rb` for reading or `wb` for writing.","message":"The `Base64IO` class expects a binary file-like object (opened in `rb` or `wb` mode) as its input. Passing a text-mode file handle (e.g., `open('file.txt', 'r')`) will lead to a `TypeError`.","severity":"gotcha","affected_versions":"<=1.0.3"},{"fix":"For non-streaming operations with raw strings or bytes, use `base64.b64decode()` or `base64.b64encode()` directly. If you need to treat a `bytes` object as a stream for `Base64IO`, wrap it in `io.BytesIO` (e.g., `base64io.Base64IO(io.BytesIO(my_bytes_data), 'decode')`).","message":"Unlike the standard library's `base64.b64decode` or `base64.b64encode` functions, `base64io.Base64IO` does not accept a raw `str` or `bytes` object directly as its first argument. It strictly requires a file-like object that implements `read()` (or `write()` for encoding).","severity":"gotcha","affected_versions":"<=1.0.3"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the underlying file is opened in binary mode, e.g., `open('my_file.txt', 'rb')` for reading or `open('output.b64', 'wb')` for writing.","cause":"Attempting to initialize `base64io.Base64IO` with a file opened in text mode (`'r'` or `'w'`), but the library expects a binary stream.","error":"TypeError: a bytes-like object is required, not '_io.TextIOWrapper'"},{"fix":"Wrap the `str` (after encoding to bytes) or `bytes` object in an `io.BytesIO` object before passing it to `Base64IO`, or use the standard `base64` module for direct string/bytes operations.","cause":"Passing a raw `str` or `bytes` object directly to the `base64io.Base64IO` constructor instead of a file-like object.","error":"AttributeError: 'str' object has no attribute 'read'"},{"fix":"Verify that the input stream consists solely of valid Base64 characters. Pre-process the stream to remove any unexpected characters or padding if necessary.","cause":"When `Base64IO` is in decode mode, the underlying stream contains characters that are not part of the standard Base64 alphabet (A-Z, a-z, 0-9, +, /, =).","error":"ValueError: Non-base64 character found"}]}