0
# BadgerFish Convention
1

2
BadgerFish convention uses @ prefix for XML attributes and $ for text content, creating a clean and widely-supported JSON representation of XML structures.
3

4
## Capabilities
5

6
### BadgerFish Class
7

8
Creates a BadgerFish converter with @ prefix for attributes and $ for text content.
9

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

42
```python
43
from xmljson import badgerfish as bf
44
from xml.etree.ElementTree import Element, tostring
45

46
# Convert dictionary to XML
47
data = {'p': {'@id': 'main', '$': 'Hello', 'b': 'bold'}}
48
elements = bf.etree(data)
49
print(tostring(elements[0]).decode())
50
# Output: <p id="main">Hello<b>bold</b></p>
51

52
# Convert with existing root element
53
root = Element('root')
54
result = bf.etree({'p': {'@id': 'main'}}, root=root)
55
print(tostring(result).decode())
56
# Output: <root><p id="main"/></root>
57
```
58

59
### XML to Data Conversion
60

61
Converts XML elements to Python dictionaries using BadgerFish convention.
62

63
```python { .api }
64
def data(self, root):
65
    """
66
    Convert etree.Element into a dictionary.
67
    
68
    Parameters:
69
    - root: Element, XML element to convert
70
    
71
    Returns:
72
    dict: Dictionary representation using BadgerFish convention
73
    """
74
```
75

76
**Usage Example:**
77

78
```python
79
from xmljson import badgerfish as bf
80
from xml.etree.ElementTree import fromstring
81
import json
82

83
# Convert XML to dictionary
84
xml_string = '<p id="main">Hello<b>bold</b></p>'
85
xml_element = fromstring(xml_string)
86
data = bf.data(xml_element) 
87
print(json.dumps(data))
88
# Output: {"p": {"@id": "main", "$": "Hello", "b": {"$": "bold"}}}
89
```
90

91
### Pre-configured Instance
92

93
```python { .api }
94
badgerfish: BadgerFish
95
```
96

97
A pre-configured BadgerFish instance available at module level for immediate use.
98

99
## Convention Rules
100

101
- **Attributes**: Prefixed with @ (e.g., `id="main"` becomes `"@id": "main"`)
102
- **Text Content**: Stored in $ key (e.g., `<p>text</p>` becomes `{"p": {"$": "text"}}`)
103
- **Elements**: Element names become dictionary keys
104
- **Arrays**: Multiple elements with same name become arrays
105
- **Type Conversion**: Automatic conversion of strings to booleans, integers, and floats
106
- **Boolean Values**: `true`/`false` (lowercase) in XML, `True`/`False` in Python
107

108
## Error Handling
109

110
- **Invalid XML Tags**: Can be dropped using `invalid_tags='drop'` parameter
111
- **Type Conversion Errors**: Falls back to string representation
112
- **Namespace Handling**: Not yet supported (raises ValueError)