A zero-copy file-like wrapper for byte buffers, inspired by Rust's std::io::Cursor.
Project description
io‸cursor
A zero-copy
file-like wrapper
for Python byte buffers,
inspired by Rust's std::io::Cursor
.
🗺️ Overview
iocursor.Cursor
lets you wrap an allocated buffer (i.e. a Python object
implementing the buffer protocol),
and interfacing with it through the API of a file-like object. It shares
some common points with io.BytesIO
but with the following main differences:
- zero-copy VS copy:
Cursor
will not copy the data you give it at initialisation, whileBytesIO
will. This makesCursor
more efficient when you are using it for read-only operations. - static VS growable:
Cursor
will only use the buffer you give it at static memory, whileBytesIO
will use its dedicated, growable buffer.
🔧 Installing
Install directly from PyPI, using pip:
$ pip install iocursor
Pre-built wheels are available on Linux and OSX for all supported Python3 versions. Otherwise, building from source only requires a working C compiler.
🧶 Thread-safety
iocursor.Cursor
instances are not thread-safe. Using several Cursor
instances with the same backend memory only for reading should be fine.
Use a lock when interfacing otherwise.
💡 Examples
- Use
iocursor.Cursor
when you havebytes
you need to pass to an interface that only accepts file-like objects. For instance, pass a PNG image decoded from base64 to PIL, without copy:import base64 from iocursor import Cursor from PIL import Image imgdata = base64.b64decode("iVBORw0KGgoAAAANSUhEU...") img = Image.open(Cursor(imgdata))
- Use
iocursor.Cursor
when you want to use the file-like API to write to a buffer of known size. For instance, retrieve a file using thepysmb
API, which only accepts file-like objects:from SMB.SMBConnection import SMBConnectSMBConnection smb = SMBConnection('guest', '', 'client', 'server') smb.connect("192.168.0.1") info = smb.getAttributes("Music", "The Clash/Rock the Casbah.mp3") cursor = Cursor(bytearray(shared_file.file_size)) smb.retrieveFile("Music", "The Clash/Rock the Casbah.mp3", cursor) buffer = cursor.getvalue()
- Use
iocursor.Cursor
when you want to do direct I/O on a type implementing the buffer protocol. For instance, initialize anumpy
array by writing bytes to it:import numpy array = numpy.empty(4, dtype="int16") cursor = Cursor(array) cursor.write(b"\x01\x00\x02\x00\x03\x00\x04\x00") print(array) # array([1, 2, 3, 4], dtype=int16)
💭 Feedback
⚠️ Issue Tracker
Found a bug ? Have an enhancement request ? Head over to the GitHub issue tracker if you need to report or ask something. If you are filing in on a bug, please include as much information as you can about the issue, and try to recreate the same bug in a simple, easily reproducible situation.
🏗️ Contributing
Contributions are more than welcome! See CONTRIBUTING.md
for more details.
⚖️ License
This library is provided under the MIT License.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for iocursor-0.1.2-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5844963b750a3a2087a0ab29fecce66d5263a43321f62d663ee93e19138976a7 |
|
MD5 | fc0edbd469f5a2c07eca76fd9fafa2c7 |
|
BLAKE2b-256 | ce8d98f7eafcd7a887047a82f9795140e6e54aedd161ee855f77bc9ba6cf33de |
Hashes for iocursor-0.1.2-cp310-cp310-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4467dd2a7ebb223038e7d39c12fdc5c77a2b7514e04b79ffaa0e768dcdaf58d8 |
|
MD5 | 73938401d92a69619c9cd8b2003d5725 |
|
BLAKE2b-256 | 3b2b33fc55fdbe374ef754d3c9fa835423f6d76057c30f97fe7cab72ede23116 |
Hashes for iocursor-0.1.2-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fc1fe6ac6bb0b9ce8af79c5e564452c6c68ceaea134952af8f9f4b22d8f0f01a |
|
MD5 | 6fa5667084187c6eb55926a139df51e8 |
|
BLAKE2b-256 | c188b12e0ff4d9f9df3d3cbc8690f6a1c74a5ed3cc323810b60c177f5b62834f |
Hashes for iocursor-0.1.2-cp39-cp39-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ef0d7b4d3370314fe5b5c68aab377830af8af96de5ec4332306d9a77b0110ce1 |
|
MD5 | 7fd010401cf5b01837a67440c2524989 |
|
BLAKE2b-256 | d8721337ae018cb2953855c2742c6268991f9af0bec634db595853b1dda64dcd |
Hashes for iocursor-0.1.2-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 250c234dc0e41860c49ecfd64b85bdcdbea9d0ab4dc463ca306e66853dca8a8d |
|
MD5 | 9185bbad1f35c933387da7db116f4960 |
|
BLAKE2b-256 | 31268bcb64785a529bf43a03e35fd27bd37912d1f6ce6c8f31e98a54a0241b5b |
Hashes for iocursor-0.1.2-cp38-cp38-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5623ec4fd4f655d0c21cf517a13c2cc31e89fd9dcf79baab8362574d2778c8bb |
|
MD5 | 6169f3d5c4aa511beaf95c2677bb6428 |
|
BLAKE2b-256 | a6279fe7b87b6b622b179cb0dddf2291c409fff52fd2fba8bb614ee54fde5c64 |
Hashes for iocursor-0.1.2-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 67695a16c5bf9b327c5f6277b8bb9d5e3a27982f688800eac6b229aad1053d2e |
|
MD5 | bfbdecac691fc376ceb5e076099b0d94 |
|
BLAKE2b-256 | 0f1783f8dc1a5ff2e281a014d2e27f8f7a492d06bd564426af3721c76cdb44b2 |
Hashes for iocursor-0.1.2-cp37-cp37m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f0b8806ab4bae4238e8daf3a1b8a597c304da52beb73bcd14ffbffdb17f62779 |
|
MD5 | b1568d8a664a75bf11c2f46add885fa0 |
|
BLAKE2b-256 | 4af468f7b3960974569fbe178c7678319944af292e6cdba4119b84a91664c1e8 |
Hashes for iocursor-0.1.2-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0912da6f89550b70dfad94adb5af7b4f4f1ca2e889632ed3ecdf5351d8f6295c |
|
MD5 | 7fd3911f5c1b8f15b48ead8c4f06bea3 |
|
BLAKE2b-256 | 58a8e7ab1f5170e5f754291cc8dcad95a549e837719ab096b7114c656e59295c |
Hashes for iocursor-0.1.2-cp36-cp36m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 79bd50e8ce067eb0291388d63be9742d82cbbf762bb0bd758f0acf05d72bb08a |
|
MD5 | aebf7e90e78d6d4ced185dc809b6476b |
|
BLAKE2b-256 | 500bfc182505facf81d491a27ce6eaa8ce2b51009d69281260be5d44db9f22e1 |
Hashes for iocursor-0.1.2-cp35-cp35m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b0002bd1a1e79f724168bbdbedd1c79a195e1e5401e4522646492a1b0a9b594f |
|
MD5 | d1a3e4b0e76ed146a380431eedefd62c |
|
BLAKE2b-256 | 5fdc869187c7460b58f96e4a805bd73a2b691e59180f8be92d490519074b72a9 |