0
# GPG Instance Management
1

2
Core GPG instance creation and configuration for establishing connections to the GPG binary and setting up the cryptographic environment.
3

4
## Capabilities
5

6
### GPG Instance Creation
7

8
Creates a GPG instance with comprehensive configuration options for binary location, keyring paths, and environment settings.
9

10
```python { .api }
11
class GPG:
12
    def __init__(self, gpgbinary='gpg', gnupghome=None, verbose=False, 
13
                 use_agent=False, keyring=None, options=None, 
14
                 secret_keyring=None, env=None):
15
        """
16
        Initialize a GPG process wrapper.
17

18
        Parameters:
19
        - gpgbinary (str): Path to the GPG binary to use (default: 'gpg')
20
        - gnupghome (str): Path to GPG home directory for keyrings
21
        - verbose (bool): Enable verbose output
22
        - use_agent (bool): Use GPG agent for passphrase handling
23
        - keyring (str|list): Alternative keyring file(s) to use
24
        - options (list): Additional command-line options for GPG
25
        - secret_keyring (str|list): Alternative secret keyring file(s)
26
        - env (dict): Environment variables for GPG subprocess
27
        """
28
```
29

30
### Instance Properties
31

32
Properties and attributes available on GPG instances for configuration and introspection.
33

34
```python { .api }
35
class GPG:
36
    # Configuration properties
37
    gpgbinary: str          # Path to GPG binary
38
    gnupghome: str          # GPG home directory path
39
    keyring: list           # List of keyring files
40
    secret_keyring: list    # List of secret keyring files
41
    verbose: bool           # Verbose output flag
42
    use_agent: bool         # GPG agent usage flag
43
    options: list           # Additional GPG options
44
    env: dict               # Environment variables
45
    encoding: str           # Character encoding (default: 'latin-1')
46
    
47
    # Runtime properties
48
    version: tuple          # GPG version information
49
    buffer_size: int        # I/O buffer size
50
    decode_errors: str      # Error handling strategy
51
    on_data: callable       # Data callback function
52
```
53

54
### Utility Methods
55

56
Utility methods for validation and argument construction.
57

58
```python { .api }
59
def make_args(self, args, passphrase):
60
    """
61
    Construct command line arguments for GPG operations.
62
    
63
    Parameters:
64
    - args (list): Base arguments for the operation
65
    - passphrase (str): Passphrase to include if needed
66
    
67
    Returns:
68
    list: Complete argument list for GPG subprocess
69
    """
70

71
def is_valid_file(self, fileobj):
72
    """
73
    Check if object is a valid file-like object.
74
    
75
    Parameters:
76
    - fileobj: Object to validate
77
    
78
    Returns:
79
    bool: True if object is file-like
80
    """
81

82
def is_valid_passphrase(self, passphrase):
83
    """
84
    Validate passphrase format (no newlines allowed).
85
    
86
    Parameters:
87
    - passphrase (str): Passphrase to validate
88
    
89
    Returns:
90
    bool: True if passphrase is valid
91
    """
92

93
def set_output_without_confirmation(self, args, output):
94
    """
95
    Configure output file handling to avoid confirmation prompts.
96
    
97
    Parameters:
98
    - args (list): Command arguments to modify
99
    - output (str): Output file path
100
    """
101
```
102

103
## Usage Examples
104

105
### Basic Instance Creation
106

107
```python
108
import gnupg
109

110
# Default configuration
111
gpg = gnupg.GPG()
112

113
# Custom GPG binary location
114
gpg = gnupg.GPG(gpgbinary='/usr/local/bin/gpg2')
115

116
# Custom GPG home directory
117
gpg = gnupg.GPG(gnupghome='/home/user/.gnupg')
118

119
# Multiple configuration options
120
gpg = gnupg.GPG(
121
    gpgbinary='/usr/bin/gpg',
122
    gnupghome='/path/to/gnupg/home',
123
    verbose=True,
124
    use_agent=True,
125
    options=['--trust-model', 'always']
126
)
127
```
128

129
### Alternative Keyring Configuration
130

131
```python
132
# Single alternative keyring
133
gpg = gnupg.GPG(keyring='/path/to/keyring.gpg')
134

135
# Multiple keyrings
136
gpg = gnupg.GPG(keyring=[
137
    '/path/to/public.gpg',
138
    '/path/to/additional.gpg'
139
])
140

141
# Custom secret keyring
142
gpg = gnupg.GPG(
143
    keyring='/path/to/public.gpg',
144
    secret_keyring='/path/to/secret.gpg'
145
)
146
```
147

148
### Environment and Options
149

150
```python
151
# Custom environment variables
152
gpg = gnupg.GPG(env={
153
    'GNUPGHOME': '/tmp/gnupg',
154
    'GPG_TTY': '/dev/tty'
155
})
156

157
# Additional GPG options
158
gpg = gnupg.GPG(options=[
159
    '--trust-model', 'always',
160
    '--cipher-algo', 'AES256',
161
    '--digest-algo', 'SHA256'
162
])
163

164
# Data callback for progress monitoring
165
def data_callback(data):
166
    print(f"Processing: {len(data)} bytes")
167

168
gpg = gnupg.GPG()
169
gpg.on_data = data_callback
170
```