python-gnupg

python-gnupg is a pure-Python library that wraps the GNU Privacy Guard (gpg) command-line program, giving you a clean object-oriented interface to OpenPGP key management and cryptography without shelling out by hand. Through a single GPG class you can generate and import keys, encrypt and decrypt messages or files, sign data, and verify signatures.

Built on the standard-library subprocess module with no third-party runtime dependencies, it works identically on Windows, macOS, and Linux and supports Python 2.7 through 3.14. It parses gpg’s machine-readable status output into typed result objects, so your code deals with structured attributes instead of raw terminal text.

What You Get

• A single GPG class exposing encrypt/decrypt, sign/verify, and full key management
• Typed result objects that parse gpg’s machine-readable status output into attributes
• Cross-platform operation on Windows, macOS, and Linux with no third-party runtime dependencies
• File-oriented variants (encrypt_file, decrypt_file, sign_file, verify_file) for streaming large data
• Keyserver integration for sending, receiving, and searching keys, plus Web Key Directory auto-location

Common Use Cases

• Encrypting and decrypting sensitive files or messages within a Python application
• Signing release artifacts and verifying signatures in automated build pipelines
• Managing an OpenPGP keyring — generating, importing, exporting, and trusting keys programmatically

Under The Hood

Architecture The entire library is a single ~87KB module, gnupg.py, centered on the GPG class (gnupg.py:1072). On construction it probes the gpg binary via --list-config to detect the version and configuration. Each operation (encrypt, sign, list_keys, etc.) builds an argument list through make_args, spawns gpg with subprocess.Popen, and streams data over pipes. Output is drained on background threads coordinated by a Queue to avoid deadlocks, then dispatched through a result_map that routes each operation to a typed result class (Crypt, Sign, Verify, ListKeys, ImportResult, and others) which parse gpg’s --with-colons machine-readable status lines into structured attributes.

Tech Stack Pure Python with zero third-party runtime dependencies — it uses only the standard library (subprocess, threading, queue, io, logging, re, socket). It targets Python 2.7 through 3.14, packaged as a single py_modules entry via setuptools (setup.cfg, pyproject.toml). The one external requirement is a separately installed GnuPG (gpg) binary. Development tooling includes tox, flake8, and coverage.

Code Quality The project ships an extensive test suite in test_gnupg.py (~82KB, 44 test methods) exercising real gpg round-trips, with codecov coverage reporting and CI via GitHub Actions. Public methods carry docstrings, and the code deliberately splits logging into always-safe and sensitive tiers (gh-196) to avoid leaking secrets. The main tradeoff is that all logic lives in one large module rather than being decomposed into packages.

API Design The public surface is ergonomic and consistent: a single GPG instance exposes clearly named verbs — encrypt, decrypt, sign, verify, gen_key, import_keys, export_keys, list_keys — each with a _file variant for streaming. Optional behavior is passed as keyword arguments, and results are truthy objects with rich attributes. Documentation is thorough, hosted on Read the Docs, keeping the boilerplate to get started minimal.