Skip to content

Commit 14f532b

Browse files
vinitkumarvinitkumar
authored
update documentation and make it more correct (#263)
1 parent 6b781f8 commit 14f532b

File tree

3 files changed

+295
-16
lines changed

3 files changed

+295
-16
lines changed

‎docs/index.md‎

Lines changed: 26 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,31 @@
1-
# Welcome to MkDocs
1+
# json2xml Documentation
22

3-
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
3+
**json2xml** is a Python library that allows you to convert JSON data into XML format. It's simple, efficient, and easy to use.
44

5-
## Commands
5+
## Quick Start
66

7-
* `mkdocs new [dir-name]` - Create a new project.
8-
* `mkdocs serve` - Start the live-reloading docs server.
9-
* `mkdocs build` - Build the documentation site.
10-
* `mkdocs -h` - Print help message and exit.
7+
```python
8+
from json2xml import json2xml
9+
from json2xml.utils import readfromstring
1110

12-
## Project layout
11+
data = readfromstring('{"name": "John", "age": 30}')
12+
print(json2xml.Json2xml(data).to_xml())
13+
```
1314

14-
mkdocs.yml # The configuration file.
15-
docs/
16-
index.md # The documentation homepage.
17-
... # Other markdown pages, images and other files.
15+
## Features
16+
17+
- Conversion from a JSON string to XML
18+
- Conversion from a JSON file to XML
19+
- Conversion from an API that emits JSON data to XML
20+
- XPath 3.1 compliant output format (optional)
21+
- Customizable root element wrapper
22+
- Optional type attributes on elements
23+
- Configurable list item wrapping
24+
25+
## Documentation
26+
27+
For detailed documentation, visit [json2xml.readthedocs.io](https://json2xml.readthedocs.io).
28+
29+
## Source Code
30+
31+
The source code is available on [GitHub](https://github.com/vinitkumar/json2xml).

‎docs/installation.rst‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,18 @@ you through the process.
2323
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
2424

2525

26+
Using uv (recommended)
27+
----------------------
28+
29+
`uv`_ is a fast Python package installer. You can install json2xml using:
30+
31+
.. code-block:: console
32+
33+
$ uv pip install json2xml
34+
35+
.. _uv: https://github.com/astral-sh/uv
36+
37+
2638
From sources
2739
------------
2840

@@ -38,13 +50,44 @@ Or download the `tarball`_:
3850

3951
.. code-block:: console
4052
41-
$ curl -OL https://github.com/vinitkumar/json2xml/tarball/master
53+
$ curl -OL https://github.com/vinitkumar/json2xml/tarball/master
4254
4355
Once you have a copy of the source, you can install it with:
4456

4557
.. code-block:: console
4658
47-
$ python setup.py install
59+
$ pip install .
60+
61+
Or for development (editable install):
62+
63+
.. code-block:: console
64+
65+
$ pip install -e .
66+
67+
68+
Development Setup
69+
-----------------
70+
71+
For contributing to json2xml, set up a development environment:
72+
73+
.. code-block:: console
74+
75+
# Create and activate virtual environment (using uv - recommended)
76+
$ uv venv
77+
$ source .venv/bin/activate # On Windows: .venv\Scripts\activate
78+
79+
# Install dependencies
80+
$ uv pip install -r requirements-dev.txt
81+
$ uv pip install -e .
82+
83+
84+
Requirements
85+
------------
86+
87+
json2xml requires Python 3.10 or later and depends on:
88+
89+
* ``defusedxml`` - For secure XML parsing
90+
* ``urllib3`` - For fetching JSON from URLs
4891

4992

5093
.. _Github repo: https://github.com/vinitkumar/json2xml

‎docs/usage.rst‎

Lines changed: 224 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,228 @@
22
Usage
33
=====
44

5-
To use json2xml in a project::
5+
Basic Usage
6+
-----------
67

7-
import json2xml
8+
The json2xml library provides three main ways to read JSON data:
9+
10+
* From a JSON file using ``readfromjson``
11+
* From a URL using ``readfromurl``
12+
* From a string using ``readfromstring``
13+
14+
Here's how to use each method:
15+
16+
.. code-block:: python
17+
18+
from json2xml import json2xml
19+
from json2xml.utils import readfromurl, readfromstring, readfromjson
20+
21+
# Convert JSON data from a URL to XML
22+
data = readfromurl("https://api.example.com/data")
23+
print(json2xml.Json2xml(data).to_xml())
24+
25+
# Convert a JSON string to XML
26+
data = readfromstring(
27+
'{"login":"mojombo","id":1,"avatar_url":"https://example.com/avatar.png"}'
28+
)
29+
print(json2xml.Json2xml(data).to_xml())
30+
31+
# Convert a JSON file to XML
32+
data = readfromjson("examples/licht.json")
33+
print(json2xml.Json2xml(data).to_xml())
34+
35+
36+
Constructor Parameters
37+
----------------------
38+
39+
The ``Json2xml`` class accepts the following parameters:
40+
41+
* ``data`` - The JSON data (dict or list) to convert
42+
* ``wrapper`` (default: ``"all"``) - Custom root element name
43+
* ``root`` (default: ``True``) - Whether to include the XML declaration and root element
44+
* ``pretty`` (default: ``True``) - Whether to pretty-print the XML output
45+
* ``attr_type`` (default: ``True``) - Whether to include type attributes on elements
46+
* ``item_wrap`` (default: ``True``) - Whether to wrap list items in ``<item>`` tags
47+
* ``xpath_format`` (default: ``False``) - Whether to use XPath 3.1 compliant output format
48+
49+
50+
Custom Wrappers and Indentation
51+
-------------------------------
52+
53+
By default, a wrapper ``all`` and ``pretty=True`` is set. You can customize these:
54+
55+
.. code-block:: python
56+
57+
from json2xml import json2xml
58+
from json2xml.utils import readfromstring
59+
60+
data = readfromstring(
61+
'{"login":"mojombo","id":1,"avatar_url":"https://example.com/avatar.png"}'
62+
)
63+
print(json2xml.Json2xml(data, wrapper="all", pretty=True).to_xml())
64+
65+
66+
Outputs:
67+
68+
.. code-block:: xml
69+
70+
<?xml version="1.0" encoding="UTF-8"?>
71+
<all>
72+
<login type="str">mojombo</login>
73+
<id type="int">1</id>
74+
<avatar_url type="str">https://example.com/avatar.png</avatar_url>
75+
</all>
76+
77+
78+
Omit List Item Wrapping
79+
-----------------------
80+
81+
By default, items in an array are wrapped in ``<item></item>`` tags.
82+
83+
Given this JSON input:
84+
85+
.. code-block:: json
86+
87+
{
88+
"my_items": [
89+
{ "my_item": { "id": 1 } },
90+
{ "my_item": { "id": 2 } }
91+
],
92+
"my_str_items": ["a", "b"]
93+
}
94+
95+
Default output (``item_wrap=True``):
96+
97+
.. code-block:: xml
98+
99+
<?xml version="1.0" ?>
100+
<all>
101+
<my_items type="list">
102+
<item type="dict">
103+
<my_item type="dict">
104+
<id type="int">1</id>
105+
</my_item>
106+
</item>
107+
<item type="dict">
108+
<my_item type="dict">
109+
<id type="int">2</id>
110+
</my_item>
111+
</item>
112+
</my_items>
113+
<my_str_items type="list">
114+
<item type="str">a</item>
115+
<item type="str">b</item>
116+
</my_str_items>
117+
</all>
118+
119+
To disable item wrapping:
120+
121+
.. code-block:: python
122+
123+
from json2xml import json2xml
124+
from json2xml.utils import readfromstring
125+
126+
data = readfromstring('{"my_items":[{"my_item":{"id":1}},{"my_item":{"id":2}}],"my_str_items":["a","b"]}')
127+
print(json2xml.Json2xml(data, item_wrap=False).to_xml())
128+
129+
130+
Output with ``item_wrap=False``:
131+
132+
.. code-block:: xml
133+
134+
<?xml version="1.0" ?>
135+
<all>
136+
<my_items type="list">
137+
<my_item type="dict">
138+
<id type="int">1</id>
139+
</my_item>
140+
<my_item type="dict">
141+
<id type="int">2</id>
142+
</my_item>
143+
</my_items>
144+
<my_str_items type="str">a</my_str_items>
145+
<my_str_items type="str">b</my_str_items>
146+
</all>
147+
148+
149+
Disabling Type Attributes
150+
-------------------------
151+
152+
You can disable the type attributes on elements:
153+
154+
.. code-block:: python
155+
156+
from json2xml import json2xml
157+
from json2xml.utils import readfromstring
158+
159+
data = readfromstring(
160+
'{"login":"mojombo","id":1,"avatar_url":"https://example.com/avatar.png"}'
161+
)
162+
print(json2xml.Json2xml(data, wrapper="all", pretty=True, attr_type=False).to_xml())
163+
164+
165+
Outputs:
166+
167+
.. code-block:: xml
168+
169+
<?xml version="1.0" ?>
170+
<all>
171+
<login>mojombo</login>
172+
<id>1</id>
173+
<avatar_url>https://example.com/avatar.png</avatar_url>
174+
</all>
175+
176+
177+
XPath 3.1 Compliance
178+
--------------------
179+
180+
The library supports XPath 3.1 ``json-to-xml`` function specification from
181+
`W3C <https://www.w3.org/TR/xpath-functions-31/#func-json-to-xml>`_.
182+
183+
When ``xpath_format=True``, the XML output uses standardized type-based element names
184+
(``map``, ``array``, ``string``, ``number``, ``boolean``, ``null``) with ``key`` attributes:
185+
186+
.. code-block:: python
187+
188+
from json2xml import json2xml
189+
from json2xml.utils import readfromstring
190+
191+
data = readfromstring(
192+
'{"login":"mojombo","id":1,"avatar_url":"https://example.com/avatar.png"}'
193+
)
194+
print(json2xml.Json2xml(data, xpath_format=True).to_xml())
195+
196+
197+
Outputs:
198+
199+
.. code-block:: xml
200+
201+
<?xml version="1.0" encoding="UTF-8" ?>
202+
<map xmlns="http://www.w3.org/2005/xpath-functions">
203+
<string key="login">mojombo</string>
204+
<number key="id">1</number>
205+
<string key="avatar_url">https://example.com/avatar.png</string>
206+
</map>
207+
208+
209+
Error Handling
210+
--------------
211+
212+
The library provides custom exceptions for error handling:
213+
214+
* ``JSONReadError`` - Raised when there's an error reading a JSON file
215+
* ``URLReadError`` - Raised when there's an error fetching data from a URL
216+
* ``StringReadError`` - Raised when there's an error parsing a JSON string
217+
* ``InvalidDataError`` - Raised when the data cannot be converted to valid XML
218+
219+
Example:
220+
221+
.. code-block:: python
222+
223+
from json2xml import json2xml
224+
from json2xml.utils import readfromstring, StringReadError
225+
226+
try:
227+
data = readfromstring("invalid json")
228+
except StringReadError as e:
229+
print(f"Error: {e}")

0 commit comments

Comments
 (0)