How pyca/bcrypt works
Main Components
• Python API Layer: This is represented by the "bcrypt" directory (src/bcrypt) that exposes functions like hashpw, gensalt, checkpw, and kdf. It defines the library’s public interface.
• Rust Extension Module: Located in src/_bcrypt, these files (Cargo.toml, Cargo.lock, lib.rs, and associated Rust module files) implement the core functionality (the cryptographic operations) in Rust. This parts of the system are built as a Python extension.
• Build/Configuration and Packaging: Files such as pyproject.toml, noxfile.py, MANIFEST.in, release.py, and requirements.txt are involved in building, testing, and packaging the library. They coordinate the setup, compilation with the Rust compiler (and C compiler if required for CFFI aspects), and distribution (wheels and source distributions).
• Continuous Integration & Deployment (CI/CD): The .github/workflows directory includes CI scripts for running tests, building wheels for various platforms, and publishing to PyPI. This outlines the automated workflows that enforce quality and compatibility.
• Tests: The tests directory with test_bcrypt.py confirms that the public API works as intended and that password verification functions operate correctly.
Establish Relationships and Interactions
• When a user calls a function from the Python API (in src/bcrypt), the call is delegated to the Rust extension (from src/_bcrypt) for performing the cryptographic hash.
• The build system (triggered by noxfile.py and configuration in pyproject.toml) compiles the Rust code via Cargo integration, and then packages it alongside the Python modules.
• CI/CD pipelines use GitHub workflows to run tests, build artifacts (including manylinux wheels), and deploy to PyPI.
• There is a direct dependency where the Python API relies on the Rust implementation for performance and security, and automated testing ensures this integration remains consistent.
Architectural Patterns and Design Principles
• Separation of Concerns: The design clearly separates the public-facing API (idiomatic Python) from the performance-intensive cryptographic implementation in Rust.
• Modularization: The division into multiple directories (src, tests, .github) reflects a modular approach, ensuring that each aspect like core logic, testing, and deployment is maintained independently.
• Build/Release Automation: The integration of CI workflows and build scripts emphasizes continuous integration and automated deployment practices.
• Security Focus: Since the library is used for hashing passwords, clear design segments ensure that the Rust module (where security-critical code resides) is isolated and well-tested.
Final Advice
• Although the primary focus is on the password hashing functionality, include pointers (or annotations) regarding security measures and version compatibilities (as mentioned in the README).
• Role of the automated tests and deployment workflows to assure quality and maintain compatibility across different Python and platform versions.