0
# Yahoo Convention
1

2
Yahoo convention uses 'content' for text content and disables automatic string parsing, keeping all values as strings unless explicitly converted. It follows the format used by Yahoo's JSON APIs.
3

4
## Capabilities
5

6
### Yahoo Class
7

8
Creates a Yahoo converter with 'content' for text and string preservation.
9

10
```python { .api }
11
class Yahoo(XMLData):
12
    def __init__(self, **kwargs):
13
        """
14
        Initialize Yahoo converter.
15
        
16
        Parameters:
17
        - **kwargs: Additional XMLData parameters (xml_fromstring, xml_tostring,
18
                   element, dict_type, list_type, simple_text, invalid_tags)
19
        
20
        Note: xml_fromstring defaults to False (no automatic type conversion)
21
        """
22
```
23

24
### Data to XML Conversion
25

26
Converts Python dictionaries and lists to XML elements using Yahoo convention.
27

28
```python { .api }
29
def etree(self, data, root=None):
30
    """
31
    Convert data structure into a list of etree.Element.
32
    
33
    Parameters:
34
    - data: dict or list, data structure to convert
35
    - root: Element, optional root element to append to
36
    
37
    Returns:
38
    List of etree.Element objects or modified root element
39
    """
40
```
41

42
### XML to Data Conversion
43

44
Converts XML elements to Python dictionaries using Yahoo convention.
45

46
```python { .api }
47
def data(self, root):
48
    """
49
    Convert etree.Element into a dictionary.
50
    
51
    Parameters:
52
    - root: Element, XML element to convert
53
    
54
    Returns:
55
    dict: Dictionary representation using Yahoo convention
56
    """
57
```
58

59
**Usage Examples:**
60

61
```python
62
from xmljson import yahoo
63
from xml.etree.ElementTree import fromstring, tostring
64
import json
65

66
# XML to data conversion (strings preserved)
67
xml_string = '<item id="123"><title>Sample</title><count>42</count><active>true</active></item>'
68
xml_element = fromstring(xml_string)
69
data = yahoo.data(xml_element)
70
print(json.dumps(data))
71
# Output: {"item": {"id": "123", "title": "Sample", "count": "42", "active": "true"}}
72

73
# Data to XML conversion
74
data = {
75
    'item': {
76
        'id': '123',
77
        'title': 'Sample Title',
78
        'content': 'This is the content'
79
    }
80
}
81
elements = yahoo.etree(data)
82
print(tostring(elements[0]).decode())
83
# Output: <item id="123"><title>Sample Title</title>This is the content</item>
84
```
85

86
### Pre-configured Instance
87

88
```python { .api }
89
yahoo: Yahoo
90
```
91

92
A pre-configured Yahoo instance available at module level for immediate use.
93

94
## Convention Rules
95

96
- **Text Content**: Stored in 'content' key when mixed with attributes/children
97
- **Simple Text**: Elements with only text content become string values directly
98
- **Attributes**: Added as direct properties alongside content
99
- **No Type Conversion**: All values remain as strings (xml_fromstring=False)
100
- **Arrays**: Multiple elements with same name become arrays
101
- **String Preservation**: Numbers, booleans remain as string representations
102

103
## Use Cases
104

105
- **Legacy APIs**: When working with older Yahoo-style JSON APIs
106
- **String Fidelity**: When exact string representation must be preserved
107
- **No Type Inference**: When automatic type conversion is undesirable
108
- **Simple Structures**: XML with minimal nesting and string-based data
109

110
## String Preservation Example
111

112
The Yahoo convention's key feature is string preservation:
113

114
```python
115
from xmljson import yahoo, badgerfish
116
from xml.etree.ElementTree import fromstring
117
import json
118

119
xml_string = '<data><number>42</number><flag>true</flag><text>hello</text></data>'
120
xml_element = fromstring(xml_string)
121

122
# Yahoo preserves strings
123
yahoo_data = yahoo.data(xml_element)
124
print("Yahoo:", json.dumps(yahoo_data))
125
# Output: Yahoo: {"data": {"number": "42", "flag": "true", "text": "hello"}}
126

127
# BadgerFish converts types
128
bf_data = badgerfish.data(xml_element)  
129
print("BadgerFish:", json.dumps(bf_data))
130
# Output: BadgerFish: {"data": {"number": {"$": 42}, "flag": {"$": true}, "text": {"$": "hello"}}}
131
```
132

133
## Limitations
134

135
- **No Type Inference**: Manual conversion required for numbers/booleans
136
- **Content Key Conflicts**: 'content' key name may conflict with element names
137
- **Limited Adoption**: Less commonly used than other conventions