This library is no longer maintained. An unaffiliated fork exists at https://github.com/3wnbr1/transit-python2.
Transit is a format and set of libraries for conveying values between applications written in different programming languages. The library provides support for marshalling data to/from Python.
This implementation's major.minor version number corresponds to the version of the Transit specification it supports.
NOTE: Transit is intended primarily as a wire protocol for transferring data between applications. If storing Transit data durably, readers and writers are expected to use the same version of Transit and you are responsible for migrating/transforming/re-storing that data when and if the transit format changes.
The PYPI package is
transit-python
- Latest stable release: 0.8
You can install with any of the following:
easy_install transit-python
pip install --use-wheel --pre transit-python
You can uninstall with:
pip uninstall transit-python
# io can be any Python file descriptor,
# like you would typically use with JSON's load/dump
from transit.writer import Writer
from transit.reader import Reader
writer = Writer(io, "json") # or "json-verbose", "msgpack"
writer.write(value)
reader = Reader("json") # or "msgpack"
val = reader.read(io)
For example:
>>> from transit.writer import Writer
>>> from transit.reader import Reader
>>> from StringIO import StringIO
>>> io = StringIO()
>>> writer = Writer(io, "json")
>>> writer.write(["abc", 1234567890])
>>> s = io.getvalue()
>>> reader = Reader()
>>> vals = reader.read(StringIO(s))
- 2.7.X
- 3.5.X
The transit spec defines several semantic types that map to more general types in Python:
- typed arrays (ints, longs, doubles, floats, bools) map to Python Tuples
- lists map to Python Tuples
- chars map to Strings/Unicode
When the reader encounters an of these (e.g. {"ints" =>
[1,2,3]}
) it delivers just the appropriate object to the app
(e.g. (1,2,3)
).
Use a TaggedValue to write these out if it will benefit a consuming app e.g.:
writer.write(TaggedValue("ints", [1,2,3]))
In Python, bools are subclasses of int (that is, True
is actually 1
).
>>> hash(1)
1
>>> hash(True)
1
>>> True == 1
True
This becomes problematic when decoding a map that contains bool and int keys. The bool keys may be overridden (ie: you'll only see the int key), and the value will be one of any possible bool/int keyed value.
>>> {1: "Hello", True: "World"}
{1: 'World'}
To counter this problem, the latest version of Transit Python introduces a Boolean type with singleton (by convention of use) instances of "true" and "false." A Boolean can be converted to a native Python bool with bool(x) where x is the "true" or "false" instance. Logical evaluation works correctly with Booleans (that is, they override the nonzero method and correctly evaluate as true and false in simple logical evaluation), but uses of a Boolean as an integer will fail.
Transit type | Write accepts | Read returns |
---|---|---|
null | None | None |
string | unicode, str | unicode |
boolean | bool | bool |
integer | int | int |
decimal | float | float |
keyword | transit_types.Keyword | transit_types.Keyword |
symbol | transit_types.Symbol | transit_types.Symbol |
big decimal | float | float |
big integer | long | long |
time | long, int, datetime | datetime |
uri | transit_types.URI | transit_types.URI |
uuid | uuid.UUID | uuid.UUID |
char | transit_types.TaggedValue | unicode |
array | list, tuple | tuple |
list | list, tuple | tuple |
set | set | set |
map | dict | dict |
bytes | transit_types.TaggedValue | tuple |
shorts | transit_types.TaggedValue | tuple |
ints | transit_types.TaggedValue | tuple |
longs | transit_types.TaggedValue | tuple |
floats | transit_types.TaggedValue | tuple |
doubles | transit_types.TaggedValue | tuple |
chars | transit_types.TaggedValue | tuple |
bools | transit_types.TaggedValue | tuple |
link | transit_types.Link | transit_types.Link |
Transit Python requires Transit to be at the same directory level as transit-python for access to the exemplar files. You will also need to add transit-python to your PYTHONPATH.
export PYTHONPATH=$(pwd)
Tests should be run from the transit-python directory.
python tests/seattle_benchmark.py
python tests/exemplars_test.py
pip install -e .
The version number is automatically incremented based on the number of commits. The command below shows what version number will be applied.
bin/revision
This library is open source, developed internally by Cognitect. We welcome discussions of potential problems and enhancement suggestions on the transit-format mailing list. Issues can be filed using GitHub issues for this project. Because transit is incorporated into products and client projects, we prefer to do development internally and are not accepting pull requests or patches.
Copyright © 2014-2016 Cognitect
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
http://www.apache.org/licenses/LICENSE-2.0
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.