0
# PE File Parsing
1

2
Core functionality for loading, parsing, and accessing PE file structures including headers, sections, and data directories. The PE class serves as the main entry point for all PE file operations.
3

4
## Capabilities
5

6
### PE Class Constructor
7

8
Creates a new PE instance by loading a PE file from disk or raw data in memory.
9

10
```python { .api }
11
class PE:
12
    def __init__(self, name=None, data=None, fast_load=None, max_symbol_exports=8192, max_repeated_symbol=120):
13
        """
14
        Load and parse a PE file.
15
        
16
        Args:
17
            name (str, optional): Path to PE file to load
18
            data (bytes, optional): Raw PE file data to parse
19
            fast_load (bool, optional): Skip loading some directories for faster parsing
20
            max_symbol_exports (int): Maximum number of export symbols to parse
21
            max_repeated_symbol (int): Maximum repeated symbol count threshold
22
            
23
        Note:
24
            Must provide either 'name' or 'data', not both.
25
            Can be used as context manager with 'with' statement.
26
        """
27
    
28
    def __enter__(self):
29
        """
30
        Enter context manager.
31
        
32
        Returns:
33
            PE: Self for context manager usage
34
        """
35
        
36
    def __exit__(self, type, value, traceback):
37
        """
38
        Exit context manager and clean up resources.
39
        
40
        Args:
41
            type: Exception type (if any)
42
            value: Exception value (if any) 
43
            traceback: Exception traceback (if any)
44
        """
45
```
46

47
### Resource Management
48

49
Methods for managing file resources and cleaning up memory-mapped files.
50

51
```python { .api }
52
def close(self):
53
    """
54
    Close memory mapped file resources.
55
    
56
    Should be called when done with PE file to free resources.
57
    Automatically called when using PE as context manager.
58
    """
59

60
def full_load(self):
61
    """
62
    Load all data directories if fast_load was used during initialization.
63
    
64
    This method loads directory entries that were skipped during fast loading,
65
    including imports, exports, resources, relocations, etc.
66
    """
67

68
def parse_rich_header(self):
69
    """
70
    Parse Rich header information if present.
71
    
72
    The Rich header contains compiler and linker information used during
73
    PE file creation. This method populates the rich_header attribute.
74
    """
75
```
76

77
### File Output
78

79
Write modified PE files back to disk.
80

81
```python { .api }
82
def write(self, filename=None):
83
    """
84
    Write PE file to disk with any modifications.
85
    
86
    Args:
87
        filename (str, optional): Output filename. If None, overwrites original file.
88
        
89
    Note:
90
        This will write the PE file with any modifications made through
91
        set_*_at_rva() or set_*_at_offset() methods.
92
    """
93
```
94

95
### Information and Diagnostics
96

97
Methods for accessing parsing information and warnings.
98

99
```python { .api }
100
def get_warnings(self):
101
    """
102
    Get list of parsing warnings encountered.
103
    
104
    Returns:
105
        list: List of warning strings
106
    """
107

108
def show_warnings(self):
109
    """Print warnings to stdout."""
110

111
def print_info(self, encoding="utf-8"):
112
    """
113
    Print comprehensive PE file information to stdout.
114
    
115
    Args:
116
        encoding (str): Text encoding for output
117
    """
118

119
def dump_info(self, dump=None, encoding="ascii"):
120
    """
121
    Return comprehensive PE file information as string.
122
    
123
    Args:
124
        dump (object, optional): Custom dump object
125
        encoding (str): Text encoding for output
126
        
127
    Returns:
128
        str: Formatted PE file information
129
    """
130

131
def dump_dict(self):
132
    """
133
    Return PE file information as dictionary.
134
    
135
    Returns:
136
        dict: PE file information in dictionary format
137
    """
138
```
139

140
### File Type Detection
141

142
Methods to determine the type and characteristics of the PE file.
143

144
```python { .api }
145
def is_exe(self):
146
    """
147
    Check if PE file is an executable.
148
    
149
    Returns:
150
        bool: True if file is executable
151
    """
152

153
def is_dll(self):
154
    """
155
    Check if PE file is a Dynamic Link Library.
156
    
157
    Returns:
158
        bool: True if file is DLL
159
    """
160

161
def is_driver(self):
162
    """
163
    Check if PE file is a device driver.
164
    
165
    Returns:
166
        bool: True if file is driver
167
    """
168

169
def has_relocs(self):
170
    """
171
    Check if PE file has relocation table.
172
    
173
    Returns:
174
        bool: True if file has relocations
175
    """
176

177
def has_dynamic_relocs(self):
178
    """
179
    Check if PE file has dynamic relocations.
180
    
181
    Returns:
182
        bool: True if file has dynamic relocations
183
    """
184
```
185

186
## Usage Examples
187

188
### Basic PE Loading
189

190
```python
191
import pefile
192

193
# Load from file path
194
pe = pefile.PE('executable.exe')
195

196
# Check file type
197
if pe.is_exe():
198
    print("This is an executable file")
199
elif pe.is_dll():
200
    print("This is a DLL file")
201

202
# Access basic headers
203
print(f"Machine: {hex(pe.FILE_HEADER.Machine)}")
204
print(f"Sections: {pe.FILE_HEADER.NumberOfSections}")
205
print(f"Timestamp: {pe.FILE_HEADER.TimeDateStamp}")
206

207
# Clean up
208
pe.close()
209
```
210

211
### Context Manager Usage
212

213
```python
214
import pefile
215

216
# Automatic resource cleanup
217
with pefile.PE('executable.exe') as pe:
218
    print(f"Entry point: {hex(pe.OPTIONAL_HEADER.AddressOfEntryPoint)}")
219
    print(f"Image base: {hex(pe.OPTIONAL_HEADER.ImageBase)}")
220
    
221
    # Check for warnings
222
    warnings = pe.get_warnings()
223
    if warnings:
224
        print("Parsing warnings:")
225
        for warning in warnings:
226
            print(f"  {warning}")
227
```
228

229
### Fast Loading
230

231
```python
232
import pefile
233

234
# Fast load - skip directories for speed
235
pe = pefile.PE('large_executable.exe', fast_load=True)
236

237
# Access basic info (available immediately)
238
print(f"Machine type: {pe.FILE_HEADER.Machine}")
239

240
# Load remaining directories when needed
241
pe.full_load()
242

243
# Now can access imports, exports, etc.
244
if hasattr(pe, 'DIRECTORY_ENTRY_IMPORT'):
245
    print(f"Number of imports: {len(pe.DIRECTORY_ENTRY_IMPORT)}")
246

247
pe.close()
248
```
249

250
### Loading from Memory
251

252
```python
253
import pefile
254

255
# Load PE data from memory
256
with open('executable.exe', 'rb') as f:
257
    pe_data = f.read()
258

259
pe = pefile.PE(data=pe_data)
260

261
# Same functionality as file-based loading
262
print(f"Size of image: {pe.OPTIONAL_HEADER.SizeOfImage}")
263

264
pe.close()
265
```