bjdata-serpent 0.1.0__tar.gz

bjdata_serpent-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,110 @@
+name: build
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, python ${{ matrix.python }})
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+          fetch-depth: 0  # tags, for the version
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+
+      # ubuntu-latest's default GCC 13 lacks std::ranges::to; 14 is installed beside it.
+      - name: Use GCC 14
+        if: runner.os == 'Linux'
+        run: echo "CXX=g++-14" >> "$GITHUB_ENV"
+
+      - name: Install
+        run: pip install -v '.[test,numpy]'
+        shell: bash
+
+      - name: Test
+        run: python -X faulthandler -m pytest -q --tb=short -p no:cacheprovider
+
+  wheels:
+    name: wheels (${{ matrix.os }})
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, macos-15-intel, windows-latest, windows-11-arm]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - uses: pypa/cibuildwheel@v3.3
+        env:
+          CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-* cp314-*"
+          CIBW_SKIP: "*-win32 *_i686 *-musllinux_*"
+          MACOSX_DEPLOYMENT_TARGET: "13.3"  # floating-point to_chars, which serpent reaches through <format>
+          CIBW_TEST_REQUIRES: pytest
+          CIBW_TEST_COMMAND: pytest -q {project}/tests
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Build
+        run: pipx run build --sdist
+
+      - name: Use GCC 14
+        run: echo "CXX=g++-14" >> "$GITHUB_ENV"
+
+      # The sdist has to build on its own, with nothing fetched: both libraries are in it.
+      - name: Build a wheel from it
+        run: |
+          pip install dist/*.tar.gz pytest
+          pytest -q tests
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    name: Publish to PyPI
+    needs: [wheels, sdist]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

bjdata_serpent-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+/build/
+/dist/
+*.so
+*.pyd
+__pycache__/
+*.egg-info/
+.pytest_cache/

bjdata_serpent-0.1.0/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "extern/cpp-serpent"]
+	path = extern/cpp-serpent
+	url = https://github.com/nebkat/cpp-serpent.git
+[submodule "extern/cpp-unaligned"]
+	path = extern/cpp-unaligned
+	url = https://github.com/nebkat/cpp-unaligned.git

bjdata_serpent-0.1.0/CMakeLists.txt

@@ -0,0 +1,36 @@
+cmake_minimum_required(VERSION 3.21)
+
+project(bjdata_serpent LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+find_package(Python 3.10 REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(nanobind CONFIG REQUIRED)
+
+# Both libraries are submodules, so a build from an sdist fetches nothing. serpent takes the
+# cpp-unaligned target that is already there rather than cloning its own.
+add_subdirectory(extern/cpp-unaligned EXCLUDE_FROM_ALL)
+set(SERPENT_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+# Żmij, serpent's real-number writer (only to_json uses it here), does not compile with Apple
+# Clang for x86_64; std::to_chars writes the same text there.
+if(APPLE AND (CMAKE_OSX_ARCHITECTURES MATCHES "x86_64" OR (NOT CMAKE_OSX_ARCHITECTURES AND CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64")))
+    set(SERPENT_USE_ZMIJ OFF CACHE BOOL "" FORCE)
+endif()
+add_subdirectory(extern/cpp-serpent EXCLUDE_FROM_ALL)
+
+nanobind_add_module(_core NB_STATIC
+    src/ext/common.cpp
+    src/ext/decode.cpp
+    src/ext/encode.cpp
+    src/ext/module.cpp)
+target_link_libraries(_core PRIVATE serpent::serpent)
+
+# nanobind links a macOS extension against a list of the interpreter's symbols, and the one
+# that grows a bytes object in place - documented, and stable since Python 2 - is not on it.
+if(APPLE)
+    target_link_options(_core PRIVATE "LINKER:-U,__PyBytes_Resize")
+endif()
+
+install(TARGETS _core LIBRARY DESTINATION bjdata_serpent)

bjdata_serpent-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Nebojša Cvetković
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Code by other people
+
+`include/serpent/external/` holds copies of three libraries, each under its own licence and
+each kept beside the licence it came with. All three are permissive and compatible with the
+MIT terms above; none of them places any further condition on a program that uses serpent
+beyond preserving the notices below.
+
+| Directory | Project | Copyright | Licence |

bjdata_serpent-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: bjdata-serpent
+Version: 0.1.0
+Summary: BJData (Binary JData) encoder and decoder, on the serpent C++ library
+Author: Nebojša Cvetković
+License-Expression: MIT
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Project-URL: Source, https://github.com/nebkat/python-bjdata-serpent
+Requires-Python: >=3.10
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.25; extra == "numpy"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Description-Content-Type: text/markdown
+
+# bjdata-serpent
+
+[BJData](https://github.com/NeuroJSON/bjdata) (Binary JData) for Python, on the [serpent](https://github.com/nebkat/cpp-serpent) C++ library: draft 3 in full, and draft 4 Structure-of-Arrays tables.
+
+```sh
+pip install bjdata-serpent            # numpy is optional: pip install 'bjdata-serpent[numpy]'
+```
+
+```python
+import bjdata_serpent as bjd
+
+data = bjd.encode({"port": 4411, "samples": [1, 2, 3]})
+bjd.decode(data)                       # {'port': 4411, 'samples': [1, 2, 3]}
+bjd.notation(data)                     # '[{][U][4][port][u][4411][U][7][samples][[][U][1]...'
+bjd.to_json(data)                      # '{"port":4411,"samples":[1,2,3]}'
+```
+
+## API
+
+| | |
+|---|---|
+| `encode(obj, *, prefer="size", sort_keys=False, default=None, tables=False, table_order="row")` | one document, as bytes |
+| `decode(data, *, numpy=False, object_hook=None, object_pairs_hook=None)` | the value of exactly one document |
+| `decode_prefix(data, ...)` | the first value in `data`, and how many bytes it took |
+| `dump(obj, fp, ...)` / `load(fp, ...)` | the same, to and from a binary file |
+| `validate(data)` | raises `DecodeError` unless `data` is one well-formed value |
+| `notation(data)` / `to_json(data, *, indent=0)` | what the bytes say, for reading |
+
+`DecodeError` and `EncodeError` are `ValueError`s. A `DecodeError` carries the byte `offset` and serpent's name for what went wrong as `code` (`"unexpected_end"`, `"trailing_data"`, ...).
+
+### Size or speed
+
+`prefer="size"` (the default) writes each number under the narrowest marker that holds it exactly - `200` is `U`, `1.5` a two-byte half - and leaves containers uncounted. `prefer="speed"` writes numbers at their own width and counts every container, so a reader sizes it once. Either decodes the same.
+
+### What becomes what
+
+| Python | BJData | back |
+|---|---|---|
+| `None`, `bool` | `Z`, `T`/`F` | the same |
+| `int` | the narrowest integer marker, or `H` digits beyond 64 bits | `int` |
+| `float` | `h`/`d`/`D`, narrowed only when exact | `float` |
+| `Decimal` | `H` | `Decimal`, or `int` for an integer |
+| `str` | `S` | `str` |
+| `bytes`, `bytearray`, byte `memoryview` | `[$B#` | `bytes` |
+| `list`, `tuple`, other sequences | `[` | `list` |
+| `dict`, other mappings | `{` | `dict` |
+| numpy array, `array.array`, numeric `memoryview` | `[$T#n` typed, `[$T#[dims]` N-D | `list`, or with `numpy=True` an array of the same dtype and shape |
+| numpy scalar | its own marker for speed, the narrowest for size | `int`/`float` |
+| list of like dicts, structured numpy array (`tables=True`) | `[${schema}#n` table (`{${` with `table_order="column"`) | list of dicts, or with `numpy=True` a structured array |
+
+What a document decodes to never depends on what is installed: packed arrays are lists unless `numpy=True` is asked for.
+
+### Tables
+
+With `tables=True`, a list of two or more dicts that share their keys - every value of a key being one kind a schema can say: booleans, integers, reals, text, `None`, nested dicts of the same, or lists of one length - is written as a Structure-of-Arrays table: the keys once, then the records back to back with no markers. Integer columns narrow to their range; text columns become single characters, a dictionary of up to 255 values, or a table of offsets. Anything else is written as an array of objects, as it would be without the option.
+
+```python
+rows = [{"id": i, "ok": i % 2 == 0, "station": f"s-{i % 4}"} for i in range(1000)]
+len(bjd.encode(rows))                  # 28746
+len(bjd.encode(rows, tables=True))     # 4053
+```
+
+## Compared with `bjdata`
+
+[`bjdata`](https://pypi.org/project/bjdata/) (NeuroJSON's pybj) reads and writes the same format, and the two read each other's output. This one:
+
+- has no required dependencies: numpy is used only when asked for, through its Python API, so there is no numpy ABI to build or run against;
+- is one implementation, the extension, with no pure-Python fallback to drift from it;
+- writes 2-2.6x faster and a few percent smaller, and reads about as fast;
+- writes tables from plain lists of dicts as well as from structured arrays;
+- ships wheels.
+
+It does not write big-endian documents (pybj's `islittle=False`), it nests at most 32 deep, and it rejects typed containers of strings (`[$S#`), as serpent's grammar is strict.
+
+## Building
+
+The two C++ libraries are submodules:
+
+```sh
+git clone --recursive https://github.com/nebkat/python-bjdata-serpent
+pip install '.[test,numpy]' && pytest
+```
+
+A C++23 compiler is needed: GCC 14, Clang 17, Apple Clang 15, or MSVC 19.40.

bjdata_serpent-0.1.0/README.md

@@ -0,0 +1,84 @@
+# bjdata-serpent
+
+[BJData](https://github.com/NeuroJSON/bjdata) (Binary JData) for Python, on the [serpent](https://github.com/nebkat/cpp-serpent) C++ library: draft 3 in full, and draft 4 Structure-of-Arrays tables.
+
+```sh
+pip install bjdata-serpent            # numpy is optional: pip install 'bjdata-serpent[numpy]'
+```
+
+```python
+import bjdata_serpent as bjd
+
+data = bjd.encode({"port": 4411, "samples": [1, 2, 3]})
+bjd.decode(data)                       # {'port': 4411, 'samples': [1, 2, 3]}
+bjd.notation(data)                     # '[{][U][4][port][u][4411][U][7][samples][[][U][1]...'
+bjd.to_json(data)                      # '{"port":4411,"samples":[1,2,3]}'
+```
+
+## API
+
+| | |
+|---|---|
+| `encode(obj, *, prefer="size", sort_keys=False, default=None, tables=False, table_order="row")` | one document, as bytes |
+| `decode(data, *, numpy=False, object_hook=None, object_pairs_hook=None)` | the value of exactly one document |
+| `decode_prefix(data, ...)` | the first value in `data`, and how many bytes it took |
+| `dump(obj, fp, ...)` / `load(fp, ...)` | the same, to and from a binary file |
+| `validate(data)` | raises `DecodeError` unless `data` is one well-formed value |
+| `notation(data)` / `to_json(data, *, indent=0)` | what the bytes say, for reading |
+
+`DecodeError` and `EncodeError` are `ValueError`s. A `DecodeError` carries the byte `offset` and serpent's name for what went wrong as `code` (`"unexpected_end"`, `"trailing_data"`, ...).
+
+### Size or speed
+
+`prefer="size"` (the default) writes each number under the narrowest marker that holds it exactly - `200` is `U`, `1.5` a two-byte half - and leaves containers uncounted. `prefer="speed"` writes numbers at their own width and counts every container, so a reader sizes it once. Either decodes the same.
+
+### What becomes what
+
+| Python | BJData | back |
+|---|---|---|
+| `None`, `bool` | `Z`, `T`/`F` | the same |
+| `int` | the narrowest integer marker, or `H` digits beyond 64 bits | `int` |
+| `float` | `h`/`d`/`D`, narrowed only when exact | `float` |
+| `Decimal` | `H` | `Decimal`, or `int` for an integer |
+| `str` | `S` | `str` |
+| `bytes`, `bytearray`, byte `memoryview` | `[$B#` | `bytes` |
+| `list`, `tuple`, other sequences | `[` | `list` |
+| `dict`, other mappings | `{` | `dict` |
+| numpy array, `array.array`, numeric `memoryview` | `[$T#n` typed, `[$T#[dims]` N-D | `list`, or with `numpy=True` an array of the same dtype and shape |
+| numpy scalar | its own marker for speed, the narrowest for size | `int`/`float` |
+| list of like dicts, structured numpy array (`tables=True`) | `[${schema}#n` table (`{${` with `table_order="column"`) | list of dicts, or with `numpy=True` a structured array |
+
+What a document decodes to never depends on what is installed: packed arrays are lists unless `numpy=True` is asked for.
+
+### Tables
+
+With `tables=True`, a list of two or more dicts that share their keys - every value of a key being one kind a schema can say: booleans, integers, reals, text, `None`, nested dicts of the same, or lists of one length - is written as a Structure-of-Arrays table: the keys once, then the records back to back with no markers. Integer columns narrow to their range; text columns become single characters, a dictionary of up to 255 values, or a table of offsets. Anything else is written as an array of objects, as it would be without the option.
+
+```python
+rows = [{"id": i, "ok": i % 2 == 0, "station": f"s-{i % 4}"} for i in range(1000)]
+len(bjd.encode(rows))                  # 28746
+len(bjd.encode(rows, tables=True))     # 4053
+```
+
+## Compared with `bjdata`
+
+[`bjdata`](https://pypi.org/project/bjdata/) (NeuroJSON's pybj) reads and writes the same format, and the two read each other's output. This one:
+
+- has no required dependencies: numpy is used only when asked for, through its Python API, so there is no numpy ABI to build or run against;
+- is one implementation, the extension, with no pure-Python fallback to drift from it;
+- writes 2-2.6x faster and a few percent smaller, and reads about as fast;
+- writes tables from plain lists of dicts as well as from structured arrays;
+- ships wheels.
+
+It does not write big-endian documents (pybj's `islittle=False`), it nests at most 32 deep, and it rejects typed containers of strings (`[$S#`), as serpent's grammar is strict.
+
+## Building
+
+The two C++ libraries are submodules:
+
+```sh
+git clone --recursive https://github.com/nebkat/python-bjdata-serpent
+pip install '.[test,numpy]' && pytest
+```
+
+A C++23 compiler is needed: GCC 14, Clang 17, Apple Clang 15, or MSVC 19.40.

bjdata_serpent-0.1.0/extern/cpp-serpent/.clang-format

@@ -0,0 +1,55 @@
+# Continuation is always a fixed indent, never aligned to a column set by the line above.
+Language: Cpp
+BasedOnStyle: LLVM
+Standard: Latest
+
+ColumnLimit: 120
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+AccessModifierOffset: -4
+
+# The rules this file exists for.
+ContinuationIndentWidth: 8
+AlignAfterOpenBracket: DontAlign
+AlignOperands: DontAlign
+AlignEscapedNewlines: DontAlign
+AlignConsecutiveAssignments: None
+AlignConsecutiveDeclarations: None
+AlignConsecutiveMacros: None
+AlignTrailingComments: false
+BitFieldColonSpacing: Both
+
+SpaceAfterTemplateKeyword: false
+SpaceBeforeParens: Custom
+SpaceBeforeParensOptions:
+  AfterControlStatements: true
+  AfterFunctionDefinitionName: false
+  AfterFunctionDeclarationName: false
+  AfterRequiresInClause: true
+  AfterRequiresInExpression: false
+
+BreakBeforeBraces: Attach
+BreakConstructorInitializers: BeforeComma
+ConstructorInitializerIndentWidth: 0
+PackConstructorInitializers: CurrentLine
+BreakBeforeBinaryOperators: NonAssignment
+BreakTemplateDeclarations: Yes
+
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: WithoutElse
+AllowShortLambdasOnASingleLine: All
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortBlocksOnASingleLine: Empty
+
+Cpp11BracedListStyle: false
+SpaceBeforeCpp11BracedList: true
+PointerAlignment: Right
+DerivePointerAlignment: false
+ReferenceAlignment: Pointer
+
+SortIncludes: Never
+IndentPPDirectives: None
+KeepEmptyLinesAtTheStartOfBlocks: false
+MaxEmptyLinesToKeep: 1
+SeparateDefinitionBlocks: Leave

bjdata_serpent-0.1.0/extern/cpp-serpent/.git

@@ -0,0 +1 @@
+gitdir: ../../.git/modules/extern/cpp-serpent

bjdata_serpent-0.1.0/extern/cpp-serpent/.gitattributes

@@ -0,0 +1,2 @@
+# The fixtures are compared byte for byte, so a checkout must not turn their newlines into CRLF.
+test/fixtures/** -text

bjdata_serpent-0.1.0/extern/cpp-serpent/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # MSVC's AddressSanitizer is incompatible with the /RTC1 checks a Debug build has.
+          - name: Windows x86_64 MSVC
+            os: windows-2025
+            msvc_arch: x64
+            build_type: RelWithDebInfo
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up the MSVC environment
+        if: matrix.msvc_arch
+        uses: ilammy/msvc-dev-cmd@v1
+        with:
+          arch: ${{ matrix.msvc_arch }}
+
+      - name: Configure
+        run: >
+          cmake -S . -B build -G Ninja
+          -DCMAKE_BUILD_TYPE=${{ matrix.build_type || 'Debug' }}
+          -DSERPENT_TEST_SANITIZE=${{ matrix.sanitize || 'ON' }}
+
+      - name: Build
+        run: cmake --build build
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure

bjdata_serpent-0.1.0/extern/cpp-serpent/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    # Pages is not available for a private repository on a free plan, so deploying is opt-in:
+    # set the PAGES_ENABLED repository variable to true once Pages is enabled with its source
+    # set to GitHub Actions. Until then the build above still runs, so the docs cannot rot.
+    #
+    #   gh variable set PAGES_ENABLED --body true
+    if: github.ref == 'refs/heads/main' && vars.PAGES_ENABLED == 'true'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

bjdata_serpent-0.1.0/extern/cpp-serpent/.gitignore

@@ -0,0 +1,3 @@
+build*/
+site/
+.DS_Store

bjdata_serpent-0.1.0/extern/cpp-serpent/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

bjdata_serpent-0.1.0/extern/cpp-serpent/.idea/.name

@@ -0,0 +1 @@
+serpent