0
# types-backports
1

2
Type stubs for Python backports modules, providing type annotations for backported functionality from newer Python versions. This package was historically part of the typeshed project and provided typing support for libraries that backported features to older Python versions.
3

4
### Key Features
5
- SSL certificate hostname verification for older Python versions
6
- Type-safe certificate validation with proper error handling  
7
- Namespace support for incomplete typing scenarios
8
- Seamless integration with Python's ssl module
9

10
## Package Information
11

12
- **Package Name**: types-backports
13
- **Package Type**: pypi
14
- **Language**: Python
15
- **Installation**: `pip install types-backports`
16

17
## Core Imports
18

19
```python
20
from backports.ssl_match_hostname import match_hostname, CertificateError
21
```
22

23
Alternative import style:
24

25
```python
26
import backports.ssl_match_hostname
27
```
28

29
## Basic Usage
30

31
```python
32
from backports.ssl_match_hostname import match_hostname, CertificateError
33
import ssl
34
import socket
35

36
# Get peer certificate from SSL connection
37
sock = ssl.wrap_socket(socket.socket())
38
sock.connect(('example.com', 443))
39
cert = sock.getpeercert()
40

41
# Verify hostname matches certificate
42
try:
43
    match_hostname(cert, 'example.com')
44
    print("Hostname matches certificate")
45
except CertificateError as e:
46
    print(f"Hostname verification failed: {e}")
47
finally:
48
    sock.close()
49

50
# Advanced usage with certificate inspection
51
def verify_with_details(hostname, port=443):
52
    """Verify hostname with detailed certificate information."""
53
    context = ssl.create_default_context()
54
    with socket.create_connection((hostname, port)) as sock:
55
        with context.wrap_socket(sock, server_hostname=hostname) as ssock:
56
            cert = ssock.getpeercert()
57
            
58
            # Extract certificate details
59
            subject = dict(x[0] for x in cert['subject'])
60
            common_name = subject.get('commonName', '')
61
            
62
            try:
63
                match_hostname(cert, hostname)
64
                return True, f"Verified: {common_name}"
65
            except CertificateError as e:
66
                return False, f"Failed for {common_name}: {e}"
67

68
# Example usage
69
success, message = verify_with_details('example.com')
70
print(message)
71
```
72

73
## Capabilities
74

75
### SSL Hostname Verification
76

77
Provides SSL certificate hostname verification functionality that was backported from newer Python versions to work with older Python installations.
78

79
```python { .api }
80
def match_hostname(cert: _PeerCertRetDictType, hostname: str) -> None:
81
    """
82
    Verify that cert (in decoded format as returned by SSLSocket.getpeercert()) 
83
    matches the given hostname.
84
    
85
    Parameters:
86
    - cert: SSL certificate data structure from SSLSocket.getpeercert()
87
    - hostname: str, hostname to verify against certificate
88
    
89
    Returns:
90
    None: Function doesn't return a value, raises exception on failure
91
    
92
    Raises:
93
    CertificateError: If hostname doesn't match certificate
94
    """
95
```
96

97
### Certificate Validation Errors
98

99
Exception class for SSL certificate validation failures.
100

101
```python { .api }
102
class CertificateError(ValueError):
103
    """
104
    Exception raised when SSL certificate validation fails during hostname matching.
105
    
106
    Inherits from ValueError and is raised by match_hostname when the provided
107
    certificate does not match the given hostname.
108
    """
109
```
110

111
### Namespace Support
112

113
Root backports namespace provides dynamic attribute access for incomplete typing.
114

115
```python { .api }
116
def __getattr__(name: str) -> Incomplete:
117
    """
118
    Provides dynamic attribute access for incomplete typing in the backports namespace.
119
    
120
    Parameters:
121
    - name: str, attribute name being accessed
122
    
123
    Returns:
124
    Incomplete: Placeholder type for incomplete typing
125
    """
126
```
127

128
## Types
129

130
The package uses types from the standard library:
131

132
```python { .api }
133
from typing import Any, Dict, List, Union
134

135
# SSL certificate dictionary structure as returned by SSLSocket.getpeercert()
136
_PeerCertRetDictType = Dict[str, Union[
137
    str,                    # Simple string fields like 'serialNumber', 'version'
138
    List[List[str]],       # Subject/issuer DN components
139
    List[str]              # subjectAltName entries  
140
]]
141

142
# Placeholder type for incomplete typing from _typeshed
143
Incomplete = Any
144
```
145

146
## Notes
147

148
- **Deprecation Status**: This package is no longer maintained and was removed from typeshed in March 2023
149
- **Reason for Removal**: Modern Python versions (3.2+) include SSL hostname verification in the standard library
150
- **Migration Path**: Use Python's built-in `ssl.match_hostname()` function instead
151
- **Historical Context**: This package provided typing for the `backports.ssl_match_hostname` PyPI package, which backported SSL hostname matching functionality to older Python versions
152
- **Version Coverage**: The type stubs were compatible with Python 3.7 and later