{"id":7510,"library":"poster3","title":"Poster3","description":"Poster3 (version 0.8.1) is a Python library providing support for streaming HTTP POST requests and multipart/form-data encoding. It's a fork of the original 'poster' package, designed to address the limitation in Python's standard library where large files had to be loaded entirely into memory before uploading. The library allows for efficient uploading of large files without excessive memory consumption. Its last release was in December 2018, indicating a maintenance-level release cadence.","status":"maintenance","version":"0.8.1","language":"en","source_language":"en","source_url":"https://github.com/EvanDarwin/poster3","tags":["http","upload","streaming","multipart","form-data","files"],"install":[{"cmd":"pip install poster3","lang":"bash"}],"dependencies":[],"imports":[{"note":"Used to encode parameters and files into multipart/form-data.","symbol":"multipart_encode","correct":"from poster.encode import multipart_encode"},{"note":"The `register_openers` function is directly available from the `poster.streaminghttp` submodule, not the top-level `poster` module.","wrong":"import poster.streaminghttp","symbol":"streaminghttp","correct":"from poster.streaminghttp import register_openers"}],"quickstart":{"code":"import os\nimport urllib.request\nfrom poster.encode import multipart_encode\nfrom poster.streaminghttp import register_openers\n\n# Register the streaming http handlers with urllib2\nregister_openers()\n\n# Prepare file and simple field for upload\nfilename = 'test_upload.txt'\nwith open(filename, 'w') as f:\n    f.write('This is a test file for poster3 upload.')\n\n# 'datagen' is a generator object that yields ranges of the encoded multipart data\n# 'headers' is a dictionary of headers that must be included with the request\ndatagen, headers = multipart_encode({\"field1\": \"value1\", \"file1\": open(filename, \"rb\")})\n\n# In a real scenario, you'd replace this with your actual upload URL\nupload_url = os.environ.get('POSTER3_TEST_URL', 'http://httpbin.org/post')\n\n# Create the request object\nrequest = urllib.request.Request(upload_url, datagen, headers)\n\n# Actually upload the file\nprint(f\"Uploading to {upload_url}...\")\ntry:\n    response = urllib.request.urlopen(request)\n    print(\"Upload successful!\")\n    print(response.read().decode('utf-8'))\nexcept urllib.error.URLError as e:\n    print(f\"Upload failed: {e.reason}\")\nfinally:\n    # Clean up the test file\n    os.remove(filename)\n","lang":"python","description":"This quickstart demonstrates how to use `poster3` to upload a file along with other form data using `urllib.request`. It registers the streaming HTTP handlers, encodes the multipart data, and then sends the request. Remember to replace `POSTER3_TEST_URL` with your actual endpoint."},"warnings":[{"fix":"Review the `poster3` documentation or README for version 0.9 and above to understand the new object-oriented API if upgrading beyond 0.8.1. Stick to 0.8.1 for the current function-based API.","message":"The GitHub repository mentions a 'Version 0.9 Notice' indicating a complete internal rewrite and a shift from scattered functions to object-managed APIs. While 0.8.1 is the latest PyPI release, be aware that future versions (>=0.9) will likely introduce significant breaking changes to the API structure.","severity":"breaking","affected_versions":">=0.9.0 (unreleased at time of 0.8.1)"},{"fix":"Test `poster3` in your specific Python environment. For new projects, evaluate more actively maintained alternatives like `requests-toolbelt` for multipart encoding, or built-in `http.client` if direct streaming control is needed.","message":"The library's last release was in December 2018. This means it may not be actively maintained and might have compatibility issues with very recent Python versions (e.g., Python 3.9+) or modern HTTP client libraries. Consider testing thoroughly in your target environment.","severity":"gotcha","affected_versions":"All versions, especially with Python >3.8"},{"fix":"Ensure `open(filename, 'rb')` is used for all file parameters passed to `multipart_encode`.","message":"When opening files for upload, always use binary read mode ('rb'). Using text mode ('r') can lead to `TypeError` or incorrect encoding, especially on Windows where text mode might perform newline translations.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Always open files in binary read mode: `open(filename, 'rb')`. Ensure any string data passed for encoding is explicitly encoded to bytes if necessary, though `multipart_encode` usually handles string fields correctly.","cause":"This error typically occurs when a file is opened in text mode ('r') but `poster3` expects a bytes-like object for stream processing, or when non-bytes data is passed where bytes are expected for encoding.","error":"TypeError: a bytes-like object is required, not 'str'"},{"fix":"Use explicit `from poster.<submodule> import <symbol>` statements. For example, `from poster.streaminghttp import register_openers` or `from poster.encode import multipart_encode`.","cause":"Users often try to import submodules directly from the top-level `poster` module (e.g., `import poster.streaminghttp`), but the correct way is to import specific components from their respective submodules (e.g., `from poster.streaminghttp import register_openers`).","error":"AttributeError: module 'poster' has no attribute 'streaminghttp' (or 'encode')"},{"fix":"Ensure all string inputs (especially filenames and field values) are correctly encoded if they contain non-ASCII characters. `poster3` generally handles this, but explicit `str.encode('utf-8')` might be needed for unusual cases or when combining with other libraries. Also, avoid manual manipulation of `datagen`.","cause":"This can happen if there are issues with non-ASCII characters in filenames or form field values, or if the `datagen` is modified incorrectly after `multipart_encode`.","error":"ValueError: Invalid boundary in multipart form data (or similar encoding errors)"}]}