[Python-modules-commits] [py-ubjson] 01/06: import source for py-ubjson
Orestis Ioannou
oorestisime-guest at moszumanska.debian.org
Tue Jul 26 22:04:32 UTC 2016
This is an automated email from the git hooks/post-receive script.
oorestisime-guest pushed a commit to branch master
in repository py-ubjson.
commit c187c6a6710d521defac35a0593461285998f460
Author: Orestis Ioannou <orestis at oioannou.com>
Date: Mon Jul 25 00:08:08 2016 +0200
import source for py-ubjson
---
CHANGELOG | 11 +
LICENSE | 201 +
MANIFEST.in | 3 +
NOTICE | 11 +
PKG-INFO | 140 +
README.md | 82 +
UBJSON-Specification.md | 376 +
ez_setup.py | 415 +
py_ubjson.egg-info/PKG-INFO | 140 +
py_ubjson.egg-info/SOURCES.txt | 32 +
py_ubjson.egg-info/dependency_links.txt | 1 +
py_ubjson.egg-info/not-zip-safe | 1 +
py_ubjson.egg-info/top_level.txt | 5 +
setup.cfg | 5 +
setup.py | 104 +
test/test.py | 374 +
ubjson/__init__.py | 35 +
ubjson/__main__.py | 103 +
ubjson/compat.pxd | 20 +
ubjson/compat.py | 97 +
ubjson/compat.py2.c | 4134 +++++++++
ubjson/compat.py3.c | 4138 +++++++++
ubjson/decoder.pxd | 96 +
ubjson/decoder.py | 366 +
ubjson/decoder.py2.c | 12735 ++++++++++++++++++++++++++++
ubjson/decoder.py3.c | 13543 ++++++++++++++++++++++++++++++
ubjson/encoder.pxd | 70 +
ubjson/encoder.py | 334 +
ubjson/encoder.py2.c | 9476 +++++++++++++++++++++
ubjson/encoder.py3.c | 9448 +++++++++++++++++++++
ubjson/markers.pxd | 37 +
ubjson/markers.py | 42 +
ubjson/markers.py2.c | 2016 +++++
ubjson/markers.py3.c | 2016 +++++
34 files changed, 60607 insertions(+)
diff --git a/CHANGELOG b/CHANGELOG
new file mode 100644
index 0000000..7e08a73
--- /dev/null
+++ b/CHANGELOG
@@ -0,0 +1,11 @@
+0.8.5
+- Added Python 3.5 to classifiers list
+- Fix index in argv (command line utility)
+
+0.8.4
+- License information update
+- Allow for lack of stdin/stdout/stdout buffer access (#1)
+- Allow for extenion building to be skipped via env. var (#2)
+
+0.8.3
+- Initial public release
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..266b37e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2016 Iotic Labs Ltd
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ https://github.com/Iotic-Labs/py-ubjson/blob/master/LICENSE
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..963c276
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,3 @@
+include README.md NOTICE LICENSE CHANGELOG UBJSON-Specification.md
+include ez_setup.py
+include ubjson/*.pxd ubjson/*.c
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..0dc8cf9
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,11 @@
+py-ubjson
+Copyright 2016 Iotic Labs Ltd
+
+Universal Binary JSON Specification
+Copyright 2015 ubjson.org
+
+six.py
+Copyright (c) 2010-2015 Benjamin Peterson
+
+ez_setup.py
+Copyright (c) Python Packaging Authority
diff --git a/PKG-INFO b/PKG-INFO
new file mode 100644
index 0000000..1cc9ee1
--- /dev/null
+++ b/PKG-INFO
@@ -0,0 +1,140 @@
+Metadata-Version: 1.1
+Name: py-ubjson
+Version: 0.8.5
+Summary: Universal Binary JSON encoder/decoder
+Home-page: https://github.com/Iotic-Labs/py-ubjson
+Author: Iotic Labs Ltd
+Author-email: vilnis.termanis at iotic-labs.com
+License: Apache License 2.0
+Description: Overview
+ ========
+
+ This is a Python v3.2+ (and 2.7+) `Universal Binary
+ JSON <http://ubjson.org>`__ encoder/decoder based on the
+ `draft-12 <UBJSON-Specification.md>`__ specification.
+
+ Installing / packaging
+ ======================
+
+ .. code:: shell
+
+ # To get from PyPI
+ pip3 install py-ubjson
+
+ # To only build extension modules inline (e.g. in repository)
+ python3 setup.py build_ext -i
+
+ # To build & install globally
+ python3 setup.py install
+
+ # To skip building of extensions when installing (or building)
+ PYUBJSON_NO_EXTENSION=1 python3 setup.py install
+
+ **Notes**
+
+ - The (`cython <http://cython.org>`__-generated) extension modules are
+ not required but provide a significant speed boost.
+ - The above can also be run with v2.7+
+ - PyPI releases are signed with the `Iotic Labs Software release
+ signing key <https://iotic-labs.com/iotic-labs.com.asc>`__
+ - If any *.py* or *.pxd* has been modified, *cython*\ generate.sh\_ has
+ to be run first
+ - At run time, one can check whether compiled version is in use via the
+ *ubjson.EXTENSION*\ ENABLED\_ boolean
+
+ Usage
+ =====
+
+ It's meant to behave very much like Python's built-in `JSON
+ module <https://docs.python.org/3/library/json.html>`__, e.g.:
+
+ .. code:: python
+
+ import ubjson
+
+ encoded = ubjson.dumpb({u'a': 1})
+
+ decoded = ubjson.loadb(encoded)
+
+ **Note**: Only unicode strings in Python 2 will be encoded as strings,
+ plain *str* will be encoded as a byte array.
+
+ Documentation
+ =============
+
+ .. code:: python
+
+ import ubsjon
+ help(ubjson.dump)
+ help(ubjson.load)
+
+ Command-line utility
+ ====================
+
+ This converts between JSON and UBJSON formats:
+
+ .. code:: shell
+
+ python3 -mubjson
+ USAGE: ubjson (fromjson|tojson) (INFILE|-) [OUTFILE]
+
+ Tests
+ =====
+
+ Static
+ ------
+
+ This library has been checked using
+ `flake8 <https://pypi.python.org/pypi/flake8>`__ and
+ `pylint <http://www.pylint.org>`__, using a modified configuration - see
+ *pylint.rc* and *flake8.cfg*.
+
+ Unit
+ ----
+
+ .. code:: shell
+
+ ./coverage_test.sh
+
+ **Note**: This requires
+ `coverage <https://pypi.python.org/pypi/coverage>`__.
+
+ Limitations
+ ===========
+
+ - The **No-Op** type is not supported. (This should arguably be a
+ protocol-level rather than serialisation-level option.)
+ - Strongly-typed containers are only supported by the decoder (apart
+ from for **bytes**/**bytearray**).
+ - Encoder/decoder extensions are not supported at this time.
+ - cython optimizations could be improved.
+
+ Why?
+ ====
+
+ The only existing implementation I was aware of at the time of writing
+ (`simpleubjson <https://github.com/brainwater/simpleubjson>`__) had the
+ following limitations:
+
+ - Does not support efficient binary encoding
+ - Only supports draft-9
+ - Only supports individual Python types rather than anything
+ implementing an interface (e.g. *Mapping*)
+ - Does not decode nested arrays or objects in expected form
+ - Lacks C extension speed-up
+
+
+Keywords: ubjson,ubj
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3.2
+Classifier: Programming Language :: Python :: 3.3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b565d9f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# Overview
+
+This is a Python v3.2+ (and 2.7+) [Universal Binary JSON](http://ubjson.org) encoder/decoder based on the [draft-12](UBJSON-Specification.md) specification.
+
+
+# Installing / packaging
+```shell
+# To get from PyPI
+pip3 install py-ubjson
+
+# To only build extension modules inline (e.g. in repository)
+python3 setup.py build_ext -i
+
+# To build & install globally
+python3 setup.py install
+
+# To skip building of extensions when installing (or building)
+PYUBJSON_NO_EXTENSION=1 python3 setup.py install
+```
+**Notes**
+
+- The ([cython](http://cython.org)-generated) extension modules are not required but provide a significant speed boost.
+- The above can also be run with v2.7+
+- PyPI releases are signed with the [Iotic Labs Software release signing key](https://iotic-labs.com/iotic-labs.com.asc)
+- If any _.py_ or _.pxd_ has been modified, _cython_generate.sh_ has to be run first
+- At run time, one can check whether compiled version is in use via the _ubjson.EXTENSION_ENABLED_ boolean
+
+
+# Usage
+It's meant to behave very much like Python's built-in [JSON module](https://docs.python.org/3/library/json.html), e.g.:
+```python
+import ubjson
+
+encoded = ubjson.dumpb({u'a': 1})
+
+decoded = ubjson.loadb(encoded)
+```
+**Note**: Only unicode strings in Python 2 will be encoded as strings, plain *str* will be encoded as a byte array.
+
+
+# Documentation
+```python
+import ubsjon
+help(ubjson.dump)
+help(ubjson.load)
+```
+
+# Command-line utility
+This converts between JSON and UBJSON formats:
+```shell
+python3 -mubjson
+USAGE: ubjson (fromjson|tojson) (INFILE|-) [OUTFILE]
+```
+
+
+# Tests
+
+## Static
+This library has been checked using [flake8](https://pypi.python.org/pypi/flake8) and [pylint](http://www.pylint.org), using a modified configuration - see _pylint.rc_ and _flake8.cfg_.
+
+## Unit
+```shell
+./coverage_test.sh
+```
+**Note**: This requires [coverage](https://pypi.python.org/pypi/coverage).
+
+
+# Limitations
+- The **No-Op** type is not supported. (This should arguably be a protocol-level rather than serialisation-level option.)
+- Strongly-typed containers are only supported by the decoder (apart from for **bytes**/**bytearray**).
+- Encoder/decoder extensions are not supported at this time.
+- cython optimizations could be improved.
+
+
+# Why?
+The only existing implementation I was aware of at the time of writing ([simpleubjson](https://github.com/brainwater/simpleubjson)) had the following limitations:
+
+- Does not support efficient binary encoding
+- Only supports draft-9
+- Only supports individual Python types rather than anything implementing an interface (e.g. _Mapping_)
+- Does not decode nested arrays or objects in expected form
+- Lacks C extension speed-up
diff --git a/UBJSON-Specification.md b/UBJSON-Specification.md
new file mode 100644
index 0000000..83c3b49
--- /dev/null
+++ b/UBJSON-Specification.md
@@ -0,0 +1,376 @@
+# Index
+- [Introduction](#introduction)
+- [License](#license)
+- [Draft 12 specification](#draft12)
+ - [Data Format](#data_format)
+ - [Type overview](#type_overview)
+ - [Value types](#value_types)
+ - [Container types](#container_types)
+ - [Optimized format](#container_optimized)
+
+
+# <a name="introduction"/>Introduction
+For the official, most up-to-date, more verbose specification (with discussion and examples) of Universal Binary JSON please visit [ubjson.org](http://ubjson.org). Since at the time of writing (6th August 2015) neither said website nor the [community workspace git repository](https://github.com/thebuzzmedia/universal-binary-json) indicated what version the specification applies to, I made the decision to produce this minimal document to act as a reference in case the specification on ubj [...]
+
+
+# <a name="license"/>License
+The UBJSON Specification is licensed under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0.html).
+
+
+# <a name="draft12"/>Draft 12 specification
+
+
+## <a name="data_format"/>Data Format
+
+A single construct with two optional segments (length and data) is used for all types:
+```
+[type, 1 byte char]([integer numeric length])([data])
+```
+Each element in the tuple is defined as:
+- **type** - A 1 byte ASCII char (**_Marker_**) used to indicate the type of the data following it.
+
+- **length** (_optional_) - A positive, integer numeric type (uint8, int16, int32, int64) specifying the length of the following data payload.
+
+- **data** (_optional_) - A run of bytes representing the actual binary data for this type of value.
+
+### Notes
+- Some values are simple enough that just writing the 1 byte ASCII marker into the stream is enough to represent the value (e.g. null) while others have a type that is specific enough that no length is needed as the length is implied by the type (e.g. int32) while others still require both a type and a length to communicate their value (e.g. string). Additionally some values (e.g. array) have additional (_optional_) parameters to improve decoding efficiency and/or to reduce size of the e [...]
+
+- The UBJSON specification requires that all numeric values be written in Big-Endian order.
+
+- To store binary data, use a [strongly-typed](#container_optimized) array of uint8 values.
+
+- _application/ubjson_ should be used as the mime type
+
+- _.ubj_ should be used a the file extension when storing UBJSON-encoded data is saved to a file
+
+## <a name="type_overview"/>Type overview
+
+Type | Total size | ASCII Marker(s) | Length required | Data (payload)
+---|---|---|---|---
+[null](#value_null) | 1 byte | *Z* | No | No
+[no-op](#value_noop) | 1 byte | *N* | No | No
+[true](#value_bool) | 1 byte | *T* | No | No
+[false](#value_bool) | 1 byte | *F* | No | No
+[int8](#value_numeric) | 2 bytes | *i* | No | Yes
+[uint8](#value_numeric) | 2 bytes | *U* | No | Yes
+[int16](#value_numeric) | 3 bytes | *I* (upper case i) | No | Yes
+[int32](#value_numeric) | 5 bytes | *l* (lower case L) | No | Yes
+[int64](#value_numeric) | 9 bytes | *L* | No | Yes
+[float32](#value_numeric) | 5 bytes | *d* | No | Yes
+[float64](#value_numeric) | 9 bytes | *D* | No | Yes
+[high-precision number](#value_numeric) | 1 byte + int num val + string byte len | *H* | Yes | Yes
+[char](#value_char) | 2 bytes | *C* | No | Yes
+[string](#value_string) | 1 byte + int num val + string byte len | *S* | Yes | Yes (if not empty)
+[array](#container_array) | 2+ bytes | *\[* and *\]* | Optional | Yes (if not empty)
+[object](#container_object) | 2+ bytes | *{* and *}* | Optional | Yes (if not empty)
+
+
+## <a name="value_types"/>Value Types
+
+### <a name="value_null"/>Null
+The null value in is equivalent to the null value from the JSON specification.
+
+#### Example
+In JSON:
+```json
+{
+ "passcode": null
+}
+```
+
+In UBJSON (using block-notation):
+```
+[{]
+ [i][8][passcode][Z]
+[}]
+```
+
+---
+### <a name="value_noop"/>No-Op
+There is no equivalent to no-op value in the original JSON specification. When decoding, No-Op values should be skipped. Also, they can only occur as elements of a container.
+
+---
+### <a name="value_bool"/>Boolean
+A boolean type is is equivalent to the boolean value from the JSON specification.
+
+#### Example
+In JSON:
+```json
+{
+ "authorized": true,
+ "verified": false
+}
+```
+
+In UBJSON (using block-notation):
+```
+[{]
+ [i][10][authorized][T]
+ [i][8][verified][F]
+[}]
+```
+
+---
+### <a name="value_numeric"/>Numeric
+Unlike in JSON whith has a single _Number_ type (used for both integers and floating point numbers), UBJSON defines multiple types for integers. The minimum/maximum of values (inclusive) for each integer type are as follows:
+
+Type | Signed | Minimum | Maximum
+---|---|---|---
+int8 | Yes | -128 | 127
+uint8 | No | 0 | 255
+int16 | Yes | -32,768 | 32,767
+int32 | Yes | -2,147,483,648 | 2,147,483,647
+int64 | Yes | -9,223,372,036,854,775,808 | 9,223,372,036,854,775,807
+float32 | Yes | See [IEEE 754 Spec](http://en.wikipedia.org/wiki/IEEE_754-1985) | See [IEEE 754 Spec](https://en.wikipedia.org/wiki/IEEE_754-1985)
+float64 | Yes | See [IEEE 754 Spec](http://en.wikipedia.org/wiki/IEEE_754-1985) | See [IEEE 754 Spec](https://en.wikipedia.org/wiki/IEEE_754-1985)
+high-precision number | Yes | Infinite | Infinite
+
+**Notes**:
+- Numeric values of infinity (and NaN) are to be encoded as a [null](#value_null) in all cases
+- It is advisable to use the smallest applicable type when encoding a number.
+
+#### Integer
+All integer types are written in Big-Endian order.
+
+#### Float
+- float32 values are written in [IEEE 754 single precision floating point format](http://en.wikipedia.org/wiki/IEEE_754-1985), which has the following structure:
+ - Bit 31 (1 bit) - sign
+ - Bit 30-23 (8 bits) - exponent
+ - Bit 22-0 (23 bits) - fraction (significant)
+
+- float64 values are written in [IEEE 754 double precision floating point format](http://en.wikipedia.org/wiki/IEEE_754-1985), which has the following structure:
+ - Bit 63 (1 bit) - sign
+ - Bit 62-52 (11 bits) - exponent
+ - Bit 51-0 (52 bits) - fraction (significant)
+
+#### High-Precision
+These are encoded as a string and thus are only limited by the maximum string size. Values **must** be written out in accordance with the original [JSON number type specification](http://json.org). Infinity (and NaN) are to be encoded as a [null](#value_null) value.
+
+#### Examples
+Numeric values in JSON:
+```json
+{
+ "int8": 16,
+ "uint8": 255,
+ "int16": 32767,
+ "int32": 2147483647,
+ "int64": 9223372036854775807,
+ "float32": 3.14,
+ "float64": 113243.7863123,
+ "huge1": "3.14159265358979323846",
+ "huge2": "-1.93+E190",
+ "huge3": "719..."
+}
+```
+
+In UBJSON (using block-notation):
+```
+[{]
+ [i][4][int8][i][16]
+ [i][5][uint8][U][255]
+ [i][5][int16][I]32767]
+ [i][5][int32][l][2147483647]
+ [i][5][int64][L][9223372036854775807]
+ [i][7][float32][d][3.14]
+ [i][7][float64][D][113243.7863123]
+ [i][5][huge1][H][i][22][3.14159265358979323846]
+ [i][5][huge2][H][i][10][-1.93+E190]
+ [i][5][huge3][H][U][200][719...]
+[}]
+```
+
+---
+### <a name="value_char"/>Char
+The char type in UBJSON is an unsigned byte meant to represent a single printable ASCII character (decimal values 0-127). It **must not** have a decimal value larger than 127. It is functionally identical to the uint8 type, but semantically is meant to represent a character and not a numeric value.
+
+#### Example
+Char values in JSON:
+```json
+{
+ "rolecode": "a",
+ "delim": ";",
+}
+```
+
+UBJSON (using block-notation):
+```
+[{]
+ [i][8][rolecode][C][a]
+ [i][5][delim][C][;]
+[}]
+```
+
+---
+### <a name="value_string"/>String
+The string type in UBJSON is equivalent to the string type from the JSON specification apart from that the UBJSON string value **requires** UTF-8 encoding.
+
+#### Example
+String values in JSON:
+```json
+{
+ "username": "rkalla",
+ "imagedata": "...huge string payload..."
+}
+```
+
+UBJSON (using block-notation):
+```
+[{]
+ [i][8][username][S][i][5][rkalla]
+ [i][9][imagedata][S][l][2097152][...huge string payload...]
+[}]
+```
+
+
+## <a name="container_types"/>Container types
+See also [optimized format](#container_optimized) below.
+
+### <a name="container_array"/>Array
+The array type in UBJSON is equivalent to the array type from the JSON specification.
+
+#### Example
+Array in JSON:
+```json
+[
+ null,
+ true,
+ false,
+ 4782345193,
+ 153.132,
+ "ham"
+]
+```
+
+UBJSON (using block-notation):
+```
+[[]
+ [Z]
+ [T]
+ [F]
+ [l][4782345193]
+ [d][153.132]
+ [S][i][3][ham]
+[]]
+```
+
+---
+### <a name="container_object"/>Object
+The object type in UBJSON is equivalent to the object type from the JSON specification. Since value names can only be strings, the *S* (string) marker **must not** be included since it is redundant.
+
+#### Example
+
+Object in JSON:
+```json
+{
+ "post": {
+ "id": 1137,
+ "author": "rkalla",
+ "timestamp": 1364482090592,
+ "body": "I totally agree!"
+ }
+}
+```
+
+UBJSON (using block-notation):
+```
+[{]
+ [i][4][post][{]
+ [i][2][id][I][1137]
+ [i][6][author][S][i][5][rkalla]
+ [i][9][timestamp][L][1364482090592]
+ [i][4][body][S][i][16][I totally agree!]
+ [}]
+[}]
+```
+
+## <a name="container_optimized"/>Optimized Format
+Both container types support optional parameters that can help optimize the container for better parsing performance and smaller size.
+
+### Type - *$*
+When a _type_ is specified, all value types stored in the container (either array or object) are considered to be of that singular _type_ and as a result, _type_ markers are omitted for each value within the container. This can be thought of providing the ability to create a strongly typed container in UBJSON.
+- If a _type_ is specified, it **must** be done so before a _count_.
+- If a _type_ is specified, a _count_ **must** be specified as well. (Otherwise it is impossible to tell when a container is ending, e.g. did you just parse *]* or the int8 value of 93?)
+
+#### Example (string type):
+```
+[$][S]
+```
+
+---
+### Count - *\#*
+When a _count_ is specified, the parser is able to know ahead of time how many child elements will be parsed. This allows the parser to pre-size any internal construct used for parsing, verify that the promised number of child values were found and avoid scanning for any terminating bytes while parsing.
+- A _count_ can be specified without a type.
+
+#### Example (count of 64):
+```
+[#][i][64]
+```
+
+### Additional rules
+- A _count_ **must** be >= 0.
+- A _count_ can be specified by itself.
+- If a _count_ is specified the container **must not** specify an end-marker.
+- A container that specifies a _count_ **must** contain the specified number of child elements.
+- If a _type_ is specified, it **must** be done so before count.
+- If a _type_ is specified, a _count_ **must** also be specified. A _type_ cannot be specified by itself.
+- A container that specifies a _type_ **must not** contain any additional _type_ markers for any contained value.
+
+---
+### Array Examples
+Optimized with count
+```
+[[][#][i][5] // An array of 5 elements.
+ [d][29.97]
+ [d][31.13]
+ [d][67.0]
+ [d][2.113]
+ [d][23.8889]
+// No end marker since a count was specified.
+```
+Optimized with type & count
+```
+[[][$][d][#][i][5] // An array of 5 float32 elements.
+ [29.97] // Value type is known, so type markers are omitted.
+ [31.13]
+ [67.0]
+ [2.113]
+ [23.8889]
+// No end marker since a count was specified.
+```
+
+---
+### Object Examples
+Optimized with count
+```
+[{][#][i][3] // An object of 3 name:value pairs.
+ [i][3][lat][d][29.976]
+ [i][4][long][d][31.131]
+ [i][3][alt][d][67.0]
+// No end marker since a count was specified.
+```
+Optimized with type & count
+```
+[{][$][d][#][i][3] // An object of 3 name:float32-value pairs.
+ [i][3][lat][29.976] // Value type is known, so type markers are omitted.
+ [i][4][long][31.131]
+ [i][3][alt][67.0]
+// No end marker since a count was specified.
+```
+
+---
+### Special case: Marker-only types (null, no-op & boolean)
+If using both _count_ and _type_ optimisations, the marker itself represent the value thus saving repetition (since these types to not have a payload). Additional requirements are:
+
+Strongly typed array of type no-op and with a count of 512:
+```
+[[][$][N][#][I][512]
+```
+
+Strongly typed object of type null and with a count of 3:
+```
+[{][$][Z][#][i][3]
+ [i][4][name] // name only, no value specified.
+ [i][8][password]
+ [i][5][email]
+```
diff --git a/ez_setup.py b/ez_setup.py
new file mode 100644
index 0000000..9715bdc
--- /dev/null
+++ b/ez_setup.py
@@ -0,0 +1,415 @@
+#!/usr/bin/env python
+
+"""
+Setuptools bootstrapping installer.
+
+Run this script to install or upgrade setuptools.
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+import zipfile
+import optparse
+import subprocess
+import platform
+import textwrap
+import contextlib
+import json
+import codecs
+
+from distutils import log
+
+try:
+ from urllib.request import urlopen
+except ImportError:
+ from urllib2 import urlopen
+
+try:
+ from site import USER_SITE
+except ImportError:
+ USER_SITE = None
+
+LATEST = object()
+DEFAULT_VERSION = LATEST
+DEFAULT_URL = "https://pypi.python.org/packages/source/s/setuptools/"
+DEFAULT_SAVE_DIR = os.curdir
+
+
+def _python_cmd(*args):
+ """
+ Execute a command.
+
+ Return True if the command succeeded.
+ """
+ args = (sys.executable,) + args
+ return subprocess.call(args) == 0
+
+
+def _install(archive_filename, install_args=()):
+ """Install Setuptools."""
+ with archive_context(archive_filename):
+ # installing
+ log.warn('Installing Setuptools')
+ if not _python_cmd('setup.py', 'install', *install_args):
+ log.warn('Something went wrong during the installation.')
+ log.warn('See the error message above.')
+ # exitcode will be 2
+ return 2
+
+
+def _build_egg(egg, archive_filename, to_dir):
+ """Build Setuptools egg."""
+ with archive_context(archive_filename):
+ # building an egg
+ log.warn('Building a Setuptools egg in %s', to_dir)
+ _python_cmd('setup.py', '-q', 'bdist_egg', '--dist-dir', to_dir)
+ # returning the result
+ log.warn(egg)
+ if not os.path.exists(egg):
+ raise IOError('Could not build the egg.')
+
+
+class ContextualZipFile(zipfile.ZipFile):
+
+ """Supplement ZipFile class to support context manager for Python 2.6."""
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, type, value, traceback):
+ self.close()
+
+ def __new__(cls, *args, **kwargs):
+ """Construct a ZipFile or ContextualZipFile as appropriate."""
+ if hasattr(zipfile.ZipFile, '__exit__'):
... 59854 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/py-ubjson.git
More information about the Python-modules-commits
mailing list