0
# Core Parsing Functions
1

2
Essential functions for parsing PEM files and strings into structured objects. These functions automatically detect and categorize different PEM object types using pattern matching.
3

4
## Capabilities
5

6
### String/Bytes Parsing
7

8
Parses PEM objects from string or bytes input, extracting all recognizable PEM-encoded cryptographic objects using regex patterns.
9

10
```python { .api }
11
def parse(pem_str: bytes | str) -> list[AbstractPEMObject]:
12
    """
13
    Extract PEM-like objects from string or bytes.
14
    
15
    Args:
16
        pem_str: PEM-encoded content as bytes or string
17
        
18
    Returns:
19
        list[AbstractPEMObject]: List of parsed PEM objects, each typed 
20
        according to its content (Certificate, PrivateKey, etc.)
21
    """
22
```
23

24
**Usage Example:**
25

26
```python
27
import pem
28

29
# Parse from string
30
pem_string = """-----BEGIN CERTIFICATE-----
31
MIIBkjCB/AIBATANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA7bNnbNf7hEtC...
32
-----END CERTIFICATE-----
33
-----BEGIN RSA PRIVATE KEY-----
34
MIICdgIBADANBgkqhkiG9w0BAQEFAASCAmAwggJcAgEAAoGBAO2zZ2zX+4RL...
35
-----END RSA PRIVATE KEY-----"""
36

37
objects = pem.parse(pem_string)
38
print(f"Found {len(objects)} PEM objects")
39

40
for obj in objects:
41
    print(f"Type: {type(obj).__name__}")
42
    print(f"SHA-1: {obj.sha1_hexdigest}")
43

44
# Also works with bytes
45
pem_bytes = pem_string.encode('utf-8')
46
objects_from_bytes = pem.parse(pem_bytes)
47
```
48

49
### File Parsing
50

51
Reads a file and parses PEM objects from its contents using the core `parse()` function.
52

53
```python { .api }
54
def parse_file(file_name: str | Path) -> list[AbstractPEMObject]:
55
    """
56
    Read file and parse PEM objects from it.
57
    
58
    Args:
59
        file_name: Path to file containing PEM objects (string or pathlib.Path)
60
        
61
    Returns:
62
        list[AbstractPEMObject]: List of parsed PEM objects from the file
63
    """
64
```
65

66
**Usage Example:**
67

68
```python
69
import pem
70
from pathlib import Path
71

72
# Parse from file path string
73
objects = pem.parse_file("certificates.pem")
74

75
# Also works with pathlib.Path objects
76
cert_path = Path("certs") / "server.pem"
77
objects = pem.parse_file(cert_path)
78

79
# Process parsed objects
80
for obj in objects:
81
    if isinstance(obj, pem.Certificate):
82
        print(f"Certificate SHA-1: {obj.sha1_hexdigest}")
83
    elif isinstance(obj, pem.PrivateKey):
84
        print(f"Private key SHA-1: {obj.sha1_hexdigest}")
85
```
86

87
## Parsing Details
88

89
- **Pattern Recognition**: Uses regex patterns to identify PEM object boundaries and types
90
- **Multiple Objects**: Single input can contain multiple PEM objects of different types
91
- **Format Support**: Handles standard PEM format with `-----BEGIN` and `-----END` markers
92
- **Encoding**: Automatically handles both UTF-8 strings and bytes input
93
- **Error Handling**: Invalid PEM objects are skipped, valid ones are returned
94
- **Type Detection**: Automatically instantiates appropriate object classes based on PEM headers