crosswalk-codec
The Python package of crossmap, a bidirectional crosswalk codec. One crosswalk document describes how to map between a dataset's native JSON shape and a shared target shape, and that one document derives both directions: decode undoes encode over the paths the crosswalk maps, and what cannot be undone is declared as one-way rules. The codec is the Rust crate, built into one wheel per platform against CPython's stable ABI, so a wheel installs on CPython 3.11 and every later version. The crosswalk format is documented in the crossmap README.
pip install crosswalk-codec
from crosswalk_codec import assert_round_trip, decode, encode, parse_crosswalk
crosswalk = parse_crosswalk(
{
"source": "field-sensors/reading",
"target": "observations/v1",
"rules": [
{"op": "move", "from": "rows[].sensor", "to": "observations[].deviceId"},
{"op": "scale", "from": "rows[].depthM", "to": "observations[].depthMm", "factor": 1000},
],
"oneWay": [{"op": "drop", "from": "rows[].batteryPct", "direction": "encode"}],
}
)
table = {"rows": [{"sensor": "S-01", "depthM": 3, "batteryPct": 91}]}
encode(crosswalk, table)
# {'observations': [{'deviceId': 'S-01', 'depthMm': 3000}]}
decode(crosswalk, encode(crosswalk, table))
# {'rows': [{'sensor': 'S-01', 'depthM': 3}]}: batteryPct was declared lossy
assert_round_trip(crosswalk, [table])
API
The names follow the npm package's and the Rust crate's in Python's spelling.
| Name | |
|---|---|
parse_crosswalk(document) |
Parses a crosswalk document into an immutable Crosswalk (source, target, schema, to_dict() for the parsed form). Raises CrosswalkSyntaxError carrying every issue. |
validate_crosswalk(crosswalk) |
The structural defects of the rule list as CrosswalkIssues, empty when it can execute. |
encode(crosswalk, document), decode(crosswalk, document) |
Translate a document in either direction. A crosswalk is validated and prepared the first time it is used and kept prepared, so translating many documents with one Crosswalk validates it once. |
compile_crosswalk(crosswalk) |
Validates and prepares now, raising CrosswalkStructureError here, and returns a CompiledCrosswalk with encode(document) and decode(document). |
assert_round_trip(crosswalk, samples) |
Encodes and decodes each sample and raises RoundTripMismatchError at the first difference, leaving out the paths one-way rules touch. |
rule_sides(rule) |
The from_ and to paths of a two-way rule, such as an element of crosswalk.to_dict()["rules"]. |
json_schema_text() |
The crosswalk format's JSON Schema 2020-12 document as text, byte for byte the crossmap/schemas/crossmap.schema.json the npm package of the same version ships. |
Every error the codec raises is a CrossmapError: CrosswalkSyntaxError and CrosswalkStructureError carry issues (SyntaxIssue(message), CrosswalkIssue(rule_index, message)), RuleApplicationError carries rule_index, path and detail, and RoundTripMismatchError carries sample_index, path and detail. A when predicate that cannot be evaluated at all (a lookup node, or a collection that is not an array of records) raises ValueError, as the npm package throws a plain Error there.
The package installs the crossmap command, the same command the npm package installs, documented in the crossmap README.
Documents and numbers
Documents are native Python values: dict with str keys, list, str, int, float, bool and None, and their subclasses. Anything else raises TypeError, naming where it is in the document: a tuple, a set or bytes is refused rather than turned into something else, since decode could not give it back. A document is converted once on the way in and once on the way out, straight to and from the codec's own value, never through JSON text, and the interpreter is released while the codec runs.
A JSON number is an IEEE double, as JavaScript's JSON.parse reads it, so numbers convert by their value as a double:
- An
intis accepted when a double has exactly its value: every integer of magnitude up to 2^53, and larger ones a double holds exactly. Any otherintraisesValueErrorrather than being rounded, whereJSON.parsewould round the same digits to the nearest double. Afloatis accepted when it is finite; NaN and the infinities raiseValueError, since JSON cannot write them. - A number comes back as an
intwhen it is a safe integer (integral with magnitude at most 2^53 - 1, asNumber.isSafeIntegerdefines it) and as afloatotherwise. So3,3.0and3e0all come back as3, which is whatjson.loadsgives for the textJSON.stringifywrites for each of them, and2.5and1e300come back asfloat. Negative zero comes back as thefloat-0.0, keeping its sign.
Records keep their key order, in the order a JavaScript object would list the same keys: keys that are array indices ("0", "17") first in numeric order, then the others in insertion order. A document may nest 127 arrays and records, the root included, which is as deep as the crossmap command reads from JSON text; deeper nesting, or a container that contains itself, raises ValueError.
MIT licensed.
Metadata
Release files for crosswalk-codec 0.12.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| crosswalk_codec-0.12.1.tar.gz | 122.6 kB | With provenance | Details for crosswalk_codec-0.12.1.tar.gz |
Built distributions (wheels)
Total release size: 15.4 MB
Release files / crosswalk_codec-0.12.1.tar.gz
| Download URL | crosswalk_codec-0.12.1.tar.gz |
|---|---|
| Size | 122.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a4b54a4c3d9eaa676945d55af6d53ed21c24242f61709e72420c2be3ab71337
|
|
BLAKE2b-256 checksum How to use checksums |
47ff68572f7bcd68301e9759c611cb5ce41caec6412bc210feb3ab5b74eafe17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-win_arm64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-win_arm64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.11 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
bdfc4b1d9f6940af860da1de1a4092142e6a4a4a48ee20dae51d5cfa1ff4f396
|
|
BLAKE2b-256 checksum How to use checksums |
722f72d983aef26253ab7fc18f2f5db71f3071df7f462a19e492f96157e0088e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-win_amd64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 1.7 MB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
455a0893fe0a9d66b89fbf390221c4d5770a1fdb545c0de6bb0d33a24335de8e
|
|
BLAKE2b-256 checksum How to use checksums |
7d72e98876560dc1e46326e27a6bc09ab062375a2e79baa3b86de989914922bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-musllinux_1_2_x86_64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 2.2 MB |
| Tags | CPython 3.11 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
9839c069c97ed44ce678df06da7a685959bf812d00fe9c3961bd93f94029528d
|
|
BLAKE2b-256 checksum How to use checksums |
534422d5aba44faae7c702a13820119d094df72d1408f3117527fa7fb0682fc5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-musllinux_1_2_aarch64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 2.2 MB |
| Tags | CPython 3.11 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
9666008393958c9c5f83752f01585c8489e1df92a77313b0282f1c99ecdcc927
|
|
BLAKE2b-256 checksum How to use checksums |
3c45637845628e188ca5e19ac2b96f4373100b9583042d535d2f74ad23fcf590
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-manylinux_2_28_x86_64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
49c2cbef3e8af99d571cc109bb63b21499d67c695b2c96ac37c4e7b5d268b23e
|
|
BLAKE2b-256 checksum How to use checksums |
99685541354442fc57d61144782769169ec351500ca1db4af1de3ad6ec796904
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-manylinux_2_28_aarch64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 2.0 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
062ef7e3e8f99495d43db3b99e275b9e4b6d61beb480584706bea29a6df871c0
|
|
BLAKE2b-256 checksum How to use checksums |
632e8386a83a9d8d478ff5bdd1ba1980912a66768c3b76b18a781774822bbbe2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-macosx_11_0_arm64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.11 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
9642ead950dcb695abf609e21067235af06031091fbb898155d4947510bd7b83
|
|
BLAKE2b-256 checksum How to use checksums |
a343b8564ec73ebd2dc0cd44e1964af791d38daa82337e45ad902fa9d8ce7800
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / crosswalk_codec-0.12.1-cp311-abi3-macosx_10_12_x86_64.whl
| Download URL | crosswalk_codec-0.12.1-cp311-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.8 MB |
| Tags | CPython 3.11 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
517001b22078c35bfee806aa29119a61cabf86e336c3304a4005d95577f32314
|
|
BLAKE2b-256 checksum How to use checksums |
ac3ec0f3222b4dddcfc772cbc8ddd3e83a555eaa15e1635b4114f36a8fecf0e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for crosswalk-codec 0.12.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 9 files in this release have been uploaded with provenance metadata.
Attestation for crosswalk_codec-0.12.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.