0
# Abdera Convention
1

2
Abdera convention uses 'attributes' and 'children' keys for structured XML representation, providing explicit separation between XML attributes and child elements.
3

4
## Capabilities
5

6
### Abdera Class
7

8
Creates an Abdera converter with explicit attributes and children structure.
9

10
```python { .api }
11
class Abdera(XMLData):
12
    def __init__(self, **kwargs):
13
        """
14
        Initialize Abdera 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 Abdera 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 Abdera convention with explicit 'attributes' and 'children' structure.
43

44
```python { .api }
45
def data(self, root):
46
    """
47
    Convert etree.Element into a dictionary using Abdera convention.
48
    
49
    Abdera convention uses explicit 'attributes' and 'children' keys:
50
    - 'attributes': Dictionary containing all XML attributes  
51
    - 'children': List containing child elements and text content
52
    - Single child elements without attributes are flattened
53
    - Text-only elements become direct string values
54
    
55
    Parameters:
56
    - root: Element, XML element to convert
57
    
58
    Returns:
59
    dict: Dictionary with element name as key and structured value:
60
          - Simple text: {"element": "text"}
61
          - Complex: {"element": {"attributes": {...}, "children": [...]}}
62
    """
63
```
64

65
**Usage Examples:**
66

67
```python
68
from xmljson import abdera
69
from xml.etree.ElementTree import fromstring, tostring
70
import json
71

72
# XML to data conversion
73
xml_string = '<book id="123" lang="en"><title>Python Guide</title><author>John Doe</author></book>'
74
xml_element = fromstring(xml_string)
75
data = abdera.data(xml_element)
76
print(json.dumps(data, indent=2))
77
# Output:
78
# {
79
#   "book": {
80
#     "attributes": {
81
#       "id": "123",
82
#       "lang": "en"
83
#     },
84
#     "children": [
85
#       {
86
#         "title": "Python Guide"
87
#       },
88
#       {
89
#         "author": "John Doe"
90
#       }
91
#     ]
92
#   }
93
# }
94

95
# Simple text element (flattened)
96
xml_simple = '<title>Just Text</title>'
97
data_simple = abdera.data(fromstring(xml_simple))
98
print(json.dumps(data_simple))
99
# Output: {"title": "Just Text"}
100
```
101

102
### Pre-configured Instance
103

104
```python { .api }
105
abdera: Abdera
106
```
107

108
A pre-configured Abdera instance available at module level for immediate use.
109

110
## Convention Rules
111

112
- **Attributes**: Grouped under 'attributes' key as a dictionary
113
- **Children**: Grouped under 'children' key as an array
114
- **Simple Text**: Elements with only text and no attributes become direct string values
115
- **Mixed Content**: Text content mixed with child elements in children array
116
- **Flattening**: Single child elements without attributes are flattened
117
- **Type Conversion**: Automatic conversion of strings to booleans, integers, and floats
118

119
## Structure Patterns
120

121
### Complex Structure
122
```python
123
{
124
  "element": {
125
    "attributes": {"attr1": "value1", "attr2": "value2"}, 
126
    "children": [
127
      {"child1": "text"},
128
      {"child2": {"attributes": {}, "children": [...]}}
129
    ]
130
  }
131
}
132
```
133

134
### Simple Text Element
135
```python
136
{"element": "text content"}
137
```
138

139
### Element with Attributes Only
140
```python
141
{
142
  "element": {
143
    "attributes": {"attr": "value"}
144
  }
145
}
146
```
147

148
## Use Cases
149

150
- **Document Processing**: When clear separation of attributes and content is needed
151
- **XML Parsing**: Applications requiring explicit XML structure representation
152
- **Data Interchange**: When both attributes and hierarchical data are important
153
- **Configuration Files**: Complex XML configurations with nested structures
154

155
## Advanced Example
156

157
```python
158
from xmljson import abdera
159
from xml.etree.ElementTree import fromstring
160
import json
161

162
# Complex XML with mixed content
163
xml_complex = '''
164
<document version="1.0" encoding="utf-8">
165
    This is document text
166
    <section id="intro">
167
        <title>Introduction</title>
168
        <paragraph>First paragraph</paragraph>
169
        <paragraph>Second paragraph</paragraph>
170
    </section>
171
    <section id="content">
172
        <title>Main Content</title>
173
        More text here
174
    </section>
175
</document>
176
'''
177

178
xml_element = fromstring(xml_complex)
179
data = abdera.data(xml_element)
180
print(json.dumps(data, indent=2))
181

182
# Shows clear separation between attributes, text content, and child elements
183
```
184

185
## Error Handling
186

187
- **Empty Elements**: Elements with no content become empty dictionaries
188
- **Attribute Conflicts**: Attributes and children are always separate
189
- **Unicode Handling**: Proper Unicode support for attribute names and values