0
# Python GnuPG
1

2
A comprehensive Python wrapper for the GNU Privacy Guard (GPG/GnuPG) command-line tool. This library enables developers to integrate cryptographic operations into Python applications through a high-level interface for key management, encryption/decryption, digital signing, signature verification, and keyring operations.
3

4
## Package Information
5

6
- **Package Name**: python-gnupg
7
- **Language**: Python
8
- **Installation**: `pip install python-gnupg`
9

10
## Core Imports
11

12
```python
13
import gnupg
14
```
15

16
## Basic Usage
17

18
```python
19
import gnupg
20

21
# Create GPG instance with default settings
22
gpg = gnupg.GPG()
23

24
# Or with custom GPG home directory
25
gpg = gnupg.GPG(gnupghome='/path/to/gnupg/home')
26

27
# Generate a key pair
28
input_data = gpg.gen_key_input(
29
    name_real='John Doe',
30
    name_email='john@example.com',
31
    passphrase='my_passphrase'
32
)
33
key = gpg.gen_key(input_data)
34

35
# Encrypt data
36
encrypted_data = gpg.encrypt('Hello, World!', recipients=['john@example.com'])
37
print(encrypted_data.ok)  # True if successful
38
print(str(encrypted_data))  # Encrypted ASCII-armored data
39

40
# Decrypt data  
41
decrypted_data = gpg.decrypt(str(encrypted_data), passphrase='my_passphrase')
42
print(decrypted_data.ok)  # True if successful
43
print(str(decrypted_data))  # 'Hello, World!'
44

45
# Sign data
46
signed_data = gpg.sign('Hello, World!', passphrase='my_passphrase')
47
print(signed_data.status)  # Status of signing operation
48

49
# Verify signature
50
verified = gpg.verify(str(signed_data))
51
print(verified.valid)  # True if signature is valid
52
```
53

54
## Architecture
55

56
The library follows a consistent pattern where operations are performed via the main `GPG` class methods, which return specialized result objects containing operation outcomes and any retrieved data:
57

58
- **GPG Class**: Main interface providing all cryptographic operations
59
- **Result Objects**: Operation-specific classes (Verify, ImportResult, Crypt, etc.) that contain status information and results
60
- **Status Handling**: Internal status message processing from the GPG subprocess
61
- **Platform Support**: Cross-platform compatibility with Windows and Unix/Linux systems
62

63
## Capabilities
64

65
### GPG Instance Management
66

67
Core GPG instance creation and configuration, supporting custom binary paths, keyring locations, and environment settings.
68

69
```python { .api }
70
class GPG:
71
    def __init__(self, gpgbinary='gpg', gnupghome=None, verbose=False, 
72
                 use_agent=False, keyring=None, options=None, 
73
                 secret_keyring=None, env=None): ...
74
```
75

76
[GPG Instance Management](./gpg-instance.md)
77

78
### Key Management Operations
79

80
Comprehensive key management including generation, import, export, deletion, and keyring operations. Supports both local keyring operations and keyserver interactions.
81

82
```python { .api }
83
def gen_key(self, input): ...
84
def gen_key_input(self, **kwargs): ...
85
def import_keys(self, key_data, extra_args=None, passphrase=None): ...
86
def export_keys(self, keyids, secret=False, armor=True, minimal=False, 
87
                passphrase=None, expect_passphrase=True, output=None): ...
88
def delete_keys(self, fingerprints, secret=False, **kwargs): ...
89
def list_keys(self, secret=False, keys=None, sigs=False): ...
90
```
91

92
[Key Management](./key-management.md)
93

94
### Encryption and Decryption
95

96
Symmetric and asymmetric encryption/decryption operations supporting files, strings, and streams with comprehensive configuration options.
97

98
```python { .api }
99
def encrypt(self, data, recipients, **kwargs): ...
100
def encrypt_file(self, fileobj_or_path, recipients, **kwargs): ...
101
def decrypt(self, message, **kwargs): ...
102
def decrypt_file(self, fileobj_or_path, **kwargs): ...
103
def get_recipients(self, message, **kwargs): ...
104
```
105

106
[Encryption and Decryption](./encryption-decryption.md)
107

108
### Digital Signing and Verification
109

110
Digital signature creation and verification for data integrity and authenticity, supporting detached signatures, clear-text signing, and comprehensive verification.
111

112
```python { .api }
113
def sign(self, message, **kwargs): ...
114
def sign_file(self, fileobj_or_path, **kwargs): ...
115
def verify(self, data, **kwargs): ...  
116
def verify_file(self, fileobj_or_path, **kwargs): ...
117
def verify_data(self, sig_filename, data, **kwargs): ...
118
```
119

120
[Digital Signing and Verification](./signing-verification.md)
121

122
### Keyserver Operations
123

124
Keyserver interactions for publishing, retrieving, and searching public keys across distributed keyserver networks.
125

126
```python { .api }
127
def recv_keys(self, keyserver, *keyids, **kwargs): ...
128
def send_keys(self, keyserver, *keyids, **kwargs): ...
129
def search_keys(self, query, keyserver='pgp.mit.edu', **kwargs): ...
130
def auto_locate_key(self, email, mechanisms=None, **kwargs): ...
131
```
132

133
[Keyserver Operations](./keyserver-operations.md)
134

135
### Key Discovery and Analysis
136

137
Advanced key discovery, scanning, and analysis operations for examining keys without importing them and understanding key structures.
138

139
```python { .api }
140
def scan_keys(self, filename): ...
141
def scan_keys_mem(self, key_data): ...
142
def trust_keys(self, fingerprints, trustlevel): ...
143
def add_subkey(self, master_key, **kwargs): ...
144
```
145

146
[Key Discovery and Analysis](./key-discovery.md)
147

148
## Module Information
149

150
```python { .api }
151
# Module metadata
152
__version__: str = '0.5.5'    # Library version
153
__author__: str = 'Vinay Sajip'
154
__date__: str = '$04-Aug-2025 19:49:23$'
155

156
# Utility functions
157
def shell_quote(s):
158
    """
159
    Quote text for safe shell usage.
160
    
161
    Parameters:
162
    - s (str): String to quote
163
    
164
    Returns:
165
    str: Shell-safe quoted string
166
    """
167
```
168

169
## Common Types
170

171
```python { .api }
172
# Result object base properties (common to all result types)
173
class StatusHandler:
174
    status: str          # Operation status message
175
    stderr: str          # Error output from GPG
176
    returncode: int      # GPG process return code
177

178
# Main result types
179
class Verify(StatusHandler):
180
    valid: bool          # True if signature is valid
181
    fingerprint: str     # Signer's key fingerprint
182
    username: str        # Signer's username
183
    trust_level: int     # Trust level of the key (0-5)
184
    trust_text: str      # Human-readable trust level
185
    creation_date: str   # Signature creation date
186
    signature_id: str    # Signature identifier
187
    
188
    # Trust level constants
189
    TRUST_EXPIRED: int = 0
190
    TRUST_UNDEFINED: int = 1
191
    TRUST_NEVER: int = 2
192
    TRUST_MARGINAL: int = 3
193
    TRUST_FULLY: int = 4
194
    TRUST_ULTIMATE: int = 5
195
    TRUST_LEVELS: dict   # Mapping of trust level names to values
196
    
197
class Crypt(StatusHandler):
198
    ok: bool            # True if operation succeeded
199
    data: str           # Encrypted/decrypted data
200
    
201
class ImportResult(StatusHandler):
202
    count: int          # Total keys processed
203
    imported: int       # Keys successfully imported
204
    fingerprints: list  # List of imported key fingerprints
205
    
206
class GenKey(StatusHandler):
207
    fingerprint: str    # Generated key fingerprint
208
    
209
class ListKeys(list):
210
    # List of key dictionaries with fingerprint, uids, etc.
211
    pass
212

213
class SendResult(StatusHandler):
214
    # Result of keyserver send operations
215
    pass
216

217
class Sign(StatusHandler):
218
    data: str           # Signed data
219
    fingerprint: str    # Signing key fingerprint
220
```