NetStruct
=========
NetStruct is a `struct <http://docs.python.org/library/struct.html>`_-like
module for Python designed to make it a bit easier to send and received packed
binary data.
NetStruct is available under the `Apache License, Version 2.0
<http://www.apache.org/licenses/LICENSE-2.0.html>`_.
Install
=======
NetStruct can be installed using `pip <http://http://pypi.python.org/pypi/pip>`_:
pip install netstruct
You can also grab the latest code from the `git <http://git-scm.com/>`_)
repository:
git clone git://github.com/stendec/netstruct
NetStruct runs on `Python 2.6+ <http://python.org>`_, PyPy, and Python 3
(though only Python 3.3 has been tested).
Differences from ``struct``
===========================
NetStruct has two differences from ``struct``.
First, it defaults to using network byte-order, rather than native byte-order,
on the assumption that you'll be using it to send data over the network and,
thus, it's saving you time.
Additionally, the generated strings don't have any padding when using
non-native byte-order.
Second, NetStruct supports a new formatting character, the dollar sign (``$``).
The dollar sign represents a variable-length string, encoded with its length
preceeding the string itself. To accomplish this, the formatting character
directly before the dollar sign is assumed to represent the string's length.
Examples
========
This is as basic as it gets::
>>> import netstruct
>>> netstruct.pack(b"b$", b"Hello World!")
b'\x0cHello World!'
Alternatively::
>>> netstruct.unpack(b"b$", b"\x0cHello World!")
[b'Hello World!']
You can get a bit more complex, if you'd like::
>>> netstruct.pack(b"ih$5b", 1298, b"largeBiomes", 0, 0, 1, 0, 8)
b'\x00\x00\x05\x12\x00\x0blargeBiomes\x00\x00\x01\x00\x08'
And, of course, you can unpack complex data too::
>>> netstruct.unpack(b"bh$h$i", b"'\x00\x07stendec\x00\tlocalhost\x00\x00c\xdd")
[39, b'stendec', b'localhost', 25565]
You just have to be sure to use a long enough string::
>>> netstruct.unpack(b"bh$h$i", b"'\x00\x07stendec\x00\tlocalhost\x00")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "site-packages/netstruct.py", line 275, in unpack
return NetStruct(format).unpack(data)
File "site-packages/netstruct.py", line 165, in unpack
raise error("unpack requires a string argument of length %d" % (len(data) + out))
struct.error: unpack requires a string argument of length 25
But wait, you say. How am I supposed to provide a long enough string to
unpack the data when I can't possibly know the length ahead of time?
Simply put, you *can* know the length::
>>> it = netstruct.iter_unpack(b"ih$5b")
>>> next(it)
11
The ``iter_unpack`` function returns an iterator. Each time you call that
iterator with ``next()``, or call its ``.send()`` method, it can return one of
two values. Either it'll return the number of bytes it wants you to read next,
or it'll return the completed object.
Let's continue from above::
>>> it.send(b"\x00\x00\x05\x12\x00\x0b")
16
>>> it.send(b"largeBiomes")
5
>>> it.send(b"\x00\x00\x01\x00\x08 more")
[1298, b'largeBiomes', 0, 0, 1, 0, 8]
There. I've sent enough data, so it returned the completed list of the
unpacked data. At this point, I can take my data, and do whatever it is I want
with it.
But wait! I just sent too much data to that iterator, and now I've lost some
of my string, haven't I? That's not a problem either. You can call the iterator
one final time and it will return the unconsumed remainder of the data::
>>> next(it)
b' more'
It's just that simple. Of course, not everyone likes iterators, even if they
*are* quicker and less memory intensive than a class instance. NetStruct is
prepared, with its ``Unpacker`` class and ``obj_unpack``. Let's try that last
example one more time::
>>> obj = netstruct.obj_unpack(b"ih$5b")
>>> obj.remaining
11
>>> obj.feed(b"\x00\x00\x05\x12\x00\x0b")
16
>>> obj.feed(b"largeBiomes")
5
>>> obj.feed(b"\x00\x00\x01\x00\x08 more")
0
>>> obj.result
[1298, b'largeBiomes', 0, 0, 1, 0, 8]
>>> obj.unused_data
b' more'
Enjoy.
Raw data
{
"_id": null,
"home_page": "https://github.com/stendec/netstruct",
"name": "netstruct",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Stendec",
"author_email": "me@stendec.me",
"download_url": "https://files.pythonhosted.org/packages/b8/eb/460b09c71d65ea3ea7ff89271207935c44e30aa558b64f5102441f129191/netstruct-1.1.2.zip",
"platform": "UNKNOWN",
"description": "NetStruct\n=========\n\nNetStruct is a `struct <http://docs.python.org/library/struct.html>`_-like\nmodule for Python designed to make it a bit easier to send and received packed\nbinary data.\n\nNetStruct is available under the `Apache License, Version 2.0\n<http://www.apache.org/licenses/LICENSE-2.0.html>`_.\n\n\nInstall\n=======\n\nNetStruct can be installed using `pip <http://http://pypi.python.org/pypi/pip>`_:\n\n pip install netstruct\n\nYou can also grab the latest code from the `git <http://git-scm.com/>`_)\nrepository:\n\n git clone git://github.com/stendec/netstruct\n\nNetStruct runs on `Python 2.6+ <http://python.org>`_, PyPy, and Python 3\n(though only Python 3.3 has been tested).\n\n\nDifferences from ``struct``\n===========================\n\nNetStruct has two differences from ``struct``.\n\nFirst, it defaults to using network byte-order, rather than native byte-order,\non the assumption that you'll be using it to send data over the network and,\nthus, it's saving you time.\n\nAdditionally, the generated strings don't have any padding when using\nnon-native byte-order.\n\nSecond, NetStruct supports a new formatting character, the dollar sign (``$``).\nThe dollar sign represents a variable-length string, encoded with its length\npreceeding the string itself. To accomplish this, the formatting character\ndirectly before the dollar sign is assumed to represent the string's length.\n\n\nExamples\n========\n\nThis is as basic as it gets::\n\n >>> import netstruct\n >>> netstruct.pack(b\"b$\", b\"Hello World!\")\n b'\\x0cHello World!'\n\nAlternatively::\n\n >>> netstruct.unpack(b\"b$\", b\"\\x0cHello World!\")\n [b'Hello World!']\n\nYou can get a bit more complex, if you'd like::\n\n >>> netstruct.pack(b\"ih$5b\", 1298, b\"largeBiomes\", 0, 0, 1, 0, 8)\n b'\\x00\\x00\\x05\\x12\\x00\\x0blargeBiomes\\x00\\x00\\x01\\x00\\x08'\n\nAnd, of course, you can unpack complex data too::\n\n >>> netstruct.unpack(b\"bh$h$i\", b\"'\\x00\\x07stendec\\x00\\tlocalhost\\x00\\x00c\\xdd\")\n [39, b'stendec', b'localhost', 25565]\n\nYou just have to be sure to use a long enough string::\n\n >>> netstruct.unpack(b\"bh$h$i\", b\"'\\x00\\x07stendec\\x00\\tlocalhost\\x00\")\n Traceback (most recent call last):\n File \"<stdin>\", line 1, in <module>\n File \"site-packages/netstruct.py\", line 275, in unpack\n return NetStruct(format).unpack(data)\n File \"site-packages/netstruct.py\", line 165, in unpack\n raise error(\"unpack requires a string argument of length %d\" % (len(data) + out))\n struct.error: unpack requires a string argument of length 25\n\nBut wait, you say. How am I supposed to provide a long enough string to\nunpack the data when I can't possibly know the length ahead of time?\nSimply put, you *can* know the length::\n\n >>> it = netstruct.iter_unpack(b\"ih$5b\")\n >>> next(it)\n 11\n\nThe ``iter_unpack`` function returns an iterator. Each time you call that\niterator with ``next()``, or call its ``.send()`` method, it can return one of\ntwo values. Either it'll return the number of bytes it wants you to read next,\nor it'll return the completed object.\n\nLet's continue from above::\n\n >>> it.send(b\"\\x00\\x00\\x05\\x12\\x00\\x0b\")\n 16\n >>> it.send(b\"largeBiomes\")\n 5\n >>> it.send(b\"\\x00\\x00\\x01\\x00\\x08 more\")\n [1298, b'largeBiomes', 0, 0, 1, 0, 8]\n\nThere. I've sent enough data, so it returned the completed list of the\nunpacked data. At this point, I can take my data, and do whatever it is I want\nwith it.\n\nBut wait! I just sent too much data to that iterator, and now I've lost some\nof my string, haven't I? That's not a problem either. You can call the iterator\none final time and it will return the unconsumed remainder of the data::\n\n >>> next(it)\n b' more'\n\nIt's just that simple. Of course, not everyone likes iterators, even if they\n*are* quicker and less memory intensive than a class instance. NetStruct is\nprepared, with its ``Unpacker`` class and ``obj_unpack``. Let's try that last\nexample one more time::\n\n >>> obj = netstruct.obj_unpack(b\"ih$5b\")\n >>> obj.remaining\n 11\n >>> obj.feed(b\"\\x00\\x00\\x05\\x12\\x00\\x0b\")\n 16\n >>> obj.feed(b\"largeBiomes\")\n 5\n >>> obj.feed(b\"\\x00\\x00\\x01\\x00\\x08 more\")\n 0\n >>> obj.result\n [1298, b'largeBiomes', 0, 0, 1, 0, 8]\n >>> obj.unused_data\n b' more'\n\nEnjoy.",
"bugtrack_url": null,
"license": "UNKNOWN",
"summary": "Packed binary data for networking.",
"version": "1.1.2",
"project_urls": {
"Download": "UNKNOWN",
"Homepage": "https://github.com/stendec/netstruct"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b8eb460b09c71d65ea3ea7ff89271207935c44e30aa558b64f5102441f129191",
"md5": "38b894eaa05cb35f6e7397277c01a8bf",
"sha256": "70b6a5c73f5bbc7ab57b019369642adfb34dd8af41b948c400ce95f952b7df9a"
},
"downloads": -1,
"filename": "netstruct-1.1.2.zip",
"has_sig": false,
"md5_digest": "38b894eaa05cb35f6e7397277c01a8bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7215,
"upload_time": "2013-09-29T07:59:47",
"upload_time_iso_8601": "2013-09-29T07:59:47.910345Z",
"url": "https://files.pythonhosted.org/packages/b8/eb/460b09c71d65ea3ea7ff89271207935c44e30aa558b64f5102441f129191/netstruct-1.1.2.zip",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2013-09-29 07:59:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stendec",
"github_project": "netstruct",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "netstruct"
}
JSON
