0
# Legacy HTTP Functions
1

2
Deprecated conversion functions maintained for backward compatibility. These functions provide binary and structured format conversion but are superseded by newer APIs in the main HTTP module.
3

4
⚠️ **Note**: These functions are deprecated and maintained only for backward compatibility. New code should use the main `cloudevents.http` module functions instead.
5

6
## Capabilities
7

8
### Binary Format Conversion (Deprecated)
9

10
Converts CloudEvent to binary HTTP format where attributes are stored as HTTP headers with `ce-` prefix and data in the body.
11

12
```python { .api }
13
def to_binary(event: CloudEvent, 
14
              data_marshaller: Optional[MarshallerType] = None) -> Tuple[Dict[str, str], bytes]:
15
    """
16
    Converts CloudEvent to binary HTTP format.
17
    
18
    DEPRECATED: Use newer HTTP conversion methods instead.
19
    
20
    Args:
21
        event: CloudEvent to convert
22
        data_marshaller: Optional function to serialize event data
23
        
24
    Returns:
25
        Tuple of (headers dict, body bytes) in binary format
26
        
27
    Raises:
28
        DataMarshallerError: If data marshalling fails
29
    """
30

31
def to_binary_http(event: CloudEvent,
32
                   data_marshaller: Optional[MarshallerType] = None) -> Tuple[Dict[str, str], bytes]:
33
    """
34
    Converts CloudEvent to binary HTTP format.
35
    
36
    DEPRECATED: Alias for to_binary function.
37
    
38
    Args:
39
        event: CloudEvent to convert  
40
        data_marshaller: Optional function to serialize event data
41
        
42
    Returns:
43
        Tuple of (headers dict, body bytes) in binary format
44
    """
45
```
46

47
#### Usage Example
48

49
```python
50
from cloudevents.http import to_binary, CloudEvent
51

52
# Create CloudEvent
53
event = CloudEvent({
54
    "type": "com.example.string",
55
    "source": "https://example.com/source"
56
}, {"key": "value"})
57

58
# Convert to binary format (deprecated)
59
headers, body = to_binary(event)
60
print(f"Headers: {headers}")  # Contains ce-type, ce-source, etc.
61
print(f"Body: {body}")        # Contains serialized data
62
```
63

64
### Structured Format Conversion (Deprecated)  
65

66
Converts CloudEvent to structured HTTP format where the entire event is serialized as JSON in the body.
67

68
```python { .api }
69
def to_structured(event: CloudEvent,
70
                  data_marshaller: Optional[MarshallerType] = None) -> bytes:
71
    """
72
    Converts CloudEvent to structured HTTP format.
73
    
74
    DEPRECATED: Use newer HTTP conversion methods instead.
75
    
76
    Args:
77
        event: CloudEvent to convert
78
        data_marshaller: Optional function to serialize event data
79
        
80
    Returns:
81
        Serialized CloudEvent as JSON bytes
82
        
83
    Raises:
84
        DataMarshallerError: If data marshalling fails
85
    """
86

87
def to_structured_http(event: CloudEvent,
88
                       data_marshaller: Optional[MarshallerType] = None) -> Tuple[Dict[str, str], bytes]:
89
    """
90
    Converts CloudEvent to structured HTTP format with headers.
91
    
92
    DEPRECATED: Use newer HTTP conversion methods instead.
93
    
94
    Args:
95
        event: CloudEvent to convert
96
        data_marshaller: Optional function to serialize event data
97
        
98
    Returns:
99
        Tuple of (headers dict, body bytes) with content-type header
100
    """
101
```
102

103
#### Usage Example
104

105
```python
106
from cloudevents.http import to_structured, CloudEvent
107

108
# Create CloudEvent
109
event = CloudEvent({
110
    "type": "com.example.string", 
111
    "source": "https://example.com/source",
112
    "datacontenttype": "application/json"
113
}, {"key": "value"})
114

115
# Convert to structured format (deprecated)
116
json_bytes = to_structured(event)
117
print(f"Structured JSON: {json_bytes.decode()}")
118
```
119

120
### JSON Conversion (Deprecated)
121

122
Converts CloudEvent to JSON string representation.
123

124
```python { .api }
125
def to_json(event: CloudEvent,
126
            data_marshaller: Optional[MarshallerType] = None) -> str:
127
    """
128
    Converts CloudEvent to JSON string.
129
    
130
    DEPRECATED: Use newer HTTP conversion methods instead.
131
    
132
    Args:
133
        event: CloudEvent to convert
134
        data_marshaller: Optional function to serialize event data
135
        
136
    Returns:
137
        CloudEvent as JSON string
138
        
139
    Raises:
140
        DataMarshallerError: If data marshalling fails
141
    """
142
```
143

144
#### Usage Example
145

146
```python
147
from cloudevents.http import to_json, CloudEvent
148

149
# Create CloudEvent
150
event = CloudEvent({
151
    "type": "com.example.string",
152
    "source": "https://example.com/source"
153
}, {"message": "Hello World"})
154

155
# Convert to JSON string (deprecated)
156
json_str = to_json(event)
157
print(f"JSON representation: {json_str}")
158
```
159

160
### Format Detection (Deprecated)
161

162
Functions to detect CloudEvent format from HTTP headers.
163

164
```python { .api }
165
def is_binary(headers: Dict[str, str]) -> bool:  
166
    """
167
    Checks if headers indicate binary CloudEvent format.
168
    
169
    DEPRECATED: Use newer format detection methods instead.
170
    
171
    Args:
172
        headers: HTTP headers dictionary
173
        
174
    Returns:
175
        True if headers indicate binary format, False otherwise
176
    """
177

178
def is_structured(headers: Dict[str, str]) -> bool:
179
    """
180
    Checks if headers indicate structured CloudEvent format.
181
    
182
    DEPRECATED: Use newer format detection methods instead.
183
    
184
    Args:
185
        headers: HTTP headers dictionary
186
        
187
    Returns:
188
        True if headers indicate structured format, False otherwise
189
    """
190
```
191

192
#### Usage Example
193

194
```python
195
from cloudevents.http import is_binary, is_structured
196

197
# Binary format headers
198
binary_headers = {
199
    'ce-specversion': '1.0',
200
    'ce-type': 'com.example.string',
201
    'ce-source': 'https://example.com/source'
202
}
203

204
print(f"Is binary: {is_binary(binary_headers)}")      # True
205
print(f"Is structured: {is_structured(binary_headers)}")  # False
206

207
# Structured format headers  
208
structured_headers = {
209
    'content-type': 'application/cloudevents+json'
210
}
211

212
print(f"Is binary: {is_binary(structured_headers)}")      # False  
213
print(f"Is structured: {is_structured(structured_headers)}")  # True
214
```
215

216
## Migration Guide
217

218
### From Legacy to Modern API
219

220
**Old (Deprecated)**:
221
```python
222
from cloudevents.http import to_binary, to_structured, to_json, is_binary
223
from cloudevents.http import CloudEvent
224

225
event = CloudEvent(attributes, data)
226
headers, body = to_binary(event)
227
json_str = to_json(event)
228
```
229

230
**New (Recommended)**:
231
```python  
232
from cloudevents.http import CloudEvent, from_json, from_http
233
from cloudevents.conversion import to_dict
234

235
event = CloudEvent(attributes, data) 
236
# Use modern parsing functions
237
parsed_event = from_http(headers, body)
238
# Use conversion utilities
239
event_dict = to_dict(event)
240
```
241

242
### Why Migrate?
243

244
1. **Better Error Handling**: Modern functions provide more specific exception types
245
2. **Improved Type Safety**: Better type annotations and IDE support  
246
3. **Consistent API**: Unified interface across different transports
247
4. **Active Maintenance**: New features and bug fixes focus on modern API
248
5. **Performance**: Optimized implementations in newer functions
249

250
## Types
251

252
```python { .api }
253
# Type aliases used in legacy functions
254
MarshallerType = Callable[[Any], AnyStr]
255
UnmarshallerType = Callable[[AnyStr], Any]
256
```