0
# GData Convention
1

2
GData convention uses $t for text content and attributes added as-is, following the format used by Google's GData APIs for XML-JSON conversion.
3

4
## Capabilities
5

6
### GData Class
7

8
Creates a GData converter using $t for text content with attributes as direct properties.
9

10
```python { .api }
11
class GData(XMLData):
12
    def __init__(self, **kwargs):
13
        """
14
        Initialize GData 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
```
21

22
### Data to XML Conversion
23

24
Converts Python dictionaries and lists to XML elements using GData convention.
25

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

40
### XML to Data Conversion
41

42
Converts XML elements to Python dictionaries using GData convention.
43

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

57
**Usage Examples:**
58

59
```python
60
from xmljson import gdata
61
from xml.etree.ElementTree import fromstring, tostring, Element
62
import json
63

64
# XML to data conversion
65
xml_string = '<entry><title type="text">Sample Title</title><content>Hello World</content></entry>'
66
xml_element = fromstring(xml_string)
67
data = gdata.data(xml_element)
68
print(json.dumps(data))
69
# Output: {"entry": {"title": {"type": "text", "$t": "Sample Title"}, "content": {"$t": "Hello World"}}}
70

71
# Data to XML conversion
72
data = {
73
    'entry': {
74
        'title': {'type': 'text', '$t': 'Sample Title'},
75
        'content': {'$t': 'Hello World'}
76
    }
77
}
78
elements = gdata.etree(data)
79
print(tostring(elements[0]).decode())
80
# Output: <entry><title type="text">Sample Title</title><content>Hello World</content></entry>
81
```
82

83
### Pre-configured Instance
84

85
```python { .api }
86
gdata: GData
87
```
88

89
A pre-configured GData instance available at module level for immediate use.
90

91
## Convention Rules
92

93
- **Text Content**: Stored in $t key (e.g., `<title>text</title>` becomes `{"title": {"$t": "text"}}`)
94
- **Attributes**: Added as direct properties in the same object as $t
95
- **Scalar Values**: Non-dict, non-list values treated as attributes when no text content
96
- **Arrays**: Multiple elements with same name become arrays
97
- **Type Conversion**: Automatic conversion of strings to booleans, integers, and floats
98
- **Empty Elements**: Become empty dictionaries
99

100
## Use Cases
101

102
- **Google API Integration**: Compatible with Google's GData API format
103
- **Web Services**: When working with APIs that use GData-style JSON
104
- **Mixed Content**: XML with both attributes and text content
105
- **Enterprise Systems**: Common in business applications using Google services
106

107
## Attribute vs Text Handling
108

109
The GData convention treats scalars differently based on context:
110

111
```python
112
from xmljson import gdata
113
from xml.etree.ElementTree import fromstring
114
import json
115

116
# Element with text content
117
xml1 = '<item>text value</item>'
118
data1 = gdata.data(fromstring(xml1))
119
print(json.dumps(data1))
120
# Output: {"item": {"$t": "text value"}}
121

122
# Element with attribute and text
123
xml2 = '<item type="string">text value</item>'
124
data2 = gdata.data(fromstring(xml2))
125
print(json.dumps(data2))
126
# Output: {"item": {"type": "string", "$t": "text value"}}
127
```