Metadata-Version: 2.4
Name: pyblackboxprotobuf
Version: 0.1.0
Summary: Python bindings for the Rust blackboxprotobuf codec
Author: aFunnyStrange
License-Expression: MIT
Project-URL: Repository, https://github.com/aFunnyStrange/blackboxprotobuf
Project-URL: Upstream, https://github.com/nccgroup/blackboxprotobuf
Keywords: protobuf,decoder,encoder,reverse-engineering,rust
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Rust
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# pyblackboxprotobuf

Python 3.9+ bindings for the pure Rust `blackboxprotobuf` crate. The package
uses a small stable C ABI and Python's standard-library `ctypes`, so it is not
tied to a specific CPython minor version.

This package continues the API lineage of NCC Group's original
[`nccgroup/blackboxprotobuf`](https://github.com/nccgroup/blackboxprotobuf)
project. The original project is Copyright (c) 2018-2023 NCC Group Plc and is
distributed under the MIT License. The earlier Python 3.9+ refactor reorganized
that implementation in aFunnyStrange's project style; this version replaces
the codec implementation with the independently written Rust port and exposes
it through a stable C ABI plus `ctypes` for faster encoding and decoding. It is
not an official NCC Group release and is not endorsed by NCC Group.

Build a platform wheel. The PEP 517 backend invokes Cargo automatically and
embeds the release dynamic library:

```powershell
python -m pip install build
python -m build --wheel
python -m pip install --force-reinstall dist\pyblackboxprotobuf-*.whl
```

The resulting filename uses `py3-none-<platform>` because the `ctypes` ABI is
independent of CPython minor versions but still contains native platform code.
For source-tree development, `build_native.py` remains available after a
normal Cargo release build.

```powershell
cargo build --release
python python/pyblackboxprotobuf/build_native.py
```

```python
from pyblackboxprotobuf import ProtobufFactory

data = {"1": "Alice", "2": b"opaque"}
typedef = {"1": {"type": "string"}, "2": {"type": "bytes"}}
encoded = ProtobufFactory.protobuf_encode(data, typedef)
decoded, inferred = ProtobufFactory.protobuf_decode(encoded)
```

`protobuf_encode`, `protobuf_decode`, `grpc_encode`, `grpc_stream_encode`, and
`grpc_decode` are compatible with the retained API in `blackboxprotobuf_origin`.

## Releases

The GitHub Actions workflow builds and installs wheels for manylinux x86_64,
Windows x86_64, macOS Intel, and macOS ARM64. A `v*` tag publishes the tested
wheels and source distribution through PyPI Trusted Publishing.

Publish the matching `blackboxprotobuf` Rust crate to crates.io before tagging
this repository. This repository is independent and resolves
`blackboxprotobuf = 0.1.1` directly from crates.io; `Cargo.lock` pins the native
release build to the reviewed dependency graph.

Create a project-scoped PyPI API token, save it as the `PYPI_API_TOKEN` secret
in this repository (or its `pypi` GitHub environment), and then push a tag such
as `v0.1.0`. The workflow reads that secret without printing it and rejects
tags whose version does not match `pyproject.toml`.

See [NOTICE](NOTICE) for the complete upstream relationship and attribution.
