| 1 |
# Python bindings for the BLAKE3 C implementation |
| 2 |
|
| 3 |
This directory contains a reimplementation of the Python |
| 4 |
[`blake3`](https://pypi.org/project/blake3) module, based on the official C |
| 5 |
implementation of BLAKE3 rather than the official Rust implementation. This is |
| 6 |
mainly intended as a proof-of-concept for code that might be submitted to |
| 7 |
Python's hashlib in the future, and this module probably won't be published to |
| 8 |
PyPI. Most applications should prefer the Rust-based bindings. |
| 9 |
|
| 10 |
The C implementation of BLAKE3 doesn't currently support multithreading, but |
| 11 |
the `max_threads` parameter is still allowed (and ignored) in these bindings |
| 12 |
for compatibility with the Rust version. This point of compatibility is |
| 13 |
actually why the parameter was named `max_threads` in the first place. Credit |
| 14 |
to Larry Hastings for that idea. |
| 15 |
|
| 16 |
## Building |
| 17 |
|
| 18 |
The build is defined in [`setup.py`](setup.py), and you can compile and install |
| 19 |
this module with the usual commands like |
| 20 |
|
| 21 |
``` |
| 22 |
pip install . |
| 23 |
``` |
| 24 |
|
| 25 |
Python 3.8 or later is required. |
| 26 |
|
| 27 |
The build implements the following decision tree, which is [documented in |
| 28 |
greater detail |
| 29 |
upstream](https://github.com/BLAKE3-team/BLAKE3/tree/master/c#building): |
| 30 |
|
| 31 |
- Are we building on macOS? |
| 32 |
- Combine the Unix assembly files and the NEON intrinsics implementation |
| 33 |
into a "universal" binary using the `lipo` tool. |
| 34 |
- Are we targetting x86-64? |
| 35 |
- Are we targetting Windows? |
| 36 |
- Include the MSVC assembly files. |
| 37 |
- Otherwise: |
| 38 |
- Include the Unix assembly files. |
| 39 |
- Are we targetting 32-bit x86? |
| 40 |
- Build and include the x86 intrinsics files. These are OS-independent, but |
| 41 |
each one needs to be compiled with different flags (`-msse4.1`, `-mavx2`, |
| 42 |
etc.) to enable the appropriate instruction set extensions. |
| 43 |
- Are we targetting AArch64? |
| 44 |
- Build and include the NEON intrinsics implementation. There are ARMv7 |
| 45 |
targets that support NEON, but there are also ARMv7 targets that don't, |
| 46 |
and there's no standard way to distinguish them. So we play it safe and |
| 47 |
only enable NEON on AArch64. |
| 48 |
- Otherwise: |
| 49 |
- Just build the portable implementation. |
| 50 |
|
| 51 |
The x86-64-only assembly implementations perform better than intrinsics, and |
| 52 |
they also build faster, so these are preferable where possible. They come in |
| 53 |
three target-specific flavors: Unix, Windows MSVC, and Windows GNU. Currently |
| 54 |
`setup.py` doesn't try to target the Windows GNU ABI, but this should be |
| 55 |
relatively easy to add if needed. |
| 56 |
|
| 57 |
Nothing here takes cross-compilation into account yet. Can Python extensions be |
| 58 |
cross-compiled? Do we care about this? |
| 59 |
|
| 60 |
**Feedback needed:** I'm very new to both `setuptools` and the Python C API, |
| 61 |
and there's a good chance I've made mistakes or accidentally relied on |
| 62 |
deprecated features. This code needs to be reviewed by someone with more |
| 63 |
experience. The part that sets compiler flags for intrinsics files and the part |
| 64 |
that builds `.asm` files on Windows are especially rocky. |