Metadata-Version: 2.5
Name: lupaxa-data-converter
Version: 0.1.5
Summary: Python library that converts mappings between JSON, JSON5, XML, YAML, and TOML.
Project-URL: Homepage, https://github.com/lupaxa-developers-toolbox/data-converter
Project-URL: Repository, https://github.com/lupaxa-developers-toolbox/data-converter
Project-URL: Issues, https://github.com/lupaxa-developers-toolbox/data-converter/issues
Author: The Lupaxa Project
License: MIT License
        
        Copyright (c) The Lupaxa Project
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENCE
Keywords: data-conversion,json,json5,toml,xml,yaml
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: defusedxml>=0.7
Requires-Dist: json5>=0.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli-w>=1.1
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: bump-my-version>=1.2.0; extra == 'dev'
Requires-Dist: hatch>=1.12.0; extra == 'dev'
Requires-Dist: mypy>=1.12.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://github.com/lupaxa-developers-toolbox">
    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/developers-toolbox/readme-logo.png" alt="Developers Toolbox" />
  </a>
</p>

<h1 align="center">Data Converter</h1>

Python library that loads JSON, JSON5, XML, YAML, or TOML into a
dictionary, then writes any of those formats. Conversion is two-pass
through that dict hub — there are no pairwise converters.

The PyPI name is `lupaxa-data-converter`. The import path is
`lupaxa.data_converter`. `lupaxa` is a namespace package.

## Install

```bash
pip install lupaxa-data-converter
```

Requires Python 3.10+. The package pulls in `PyYAML`, `defusedxml`,
`json5`, and `tomli-w`. Python 3.10 also needs `tomli`; 3.11+ uses
stdlib `tomllib`.

This is a library only. There is no console script and no
`python -m` entry point.

## Usage

```python
from lupaxa.data_converter import DataConverter

payload = {"name": "Lupaxa", "formats": ["json", "json5", "xml", "yaml", "toml"]}
converter = DataConverter(payload, data_type="dict")

print(converter.to_json())
print(converter.to_json5())
print(converter.to_xml())
print(converter.to_yaml())
print(converter.to_toml())
```

`DataConverter` accepts a dictionary or a document string. Set
`data_type` to match the input (case-insensitive). The value is always
stored as a mapping on `converter.data`, then any `to_*` method can
write it out. Identity conversions are supported.

| `data_type` | Input                          |
| ----------- | ------------------------------ |
| `dict`      | A Python dictionary            |
| `json`      | A JSON object string (default) |
| `json5`     | A JSON5 object string          |
| `xml`       | An XML document string         |
| `yaml`      | A YAML mapping string          |
| `toml`      | A TOML table string            |

```python
from_dict = DataConverter({"id": 1}, data_type="dict")
from_json = DataConverter('{"id": 1}', data_type="json")
from_json5 = DataConverter("{ id: 1, }", data_type="json5")
from_xml = DataConverter("<root><id>1</id></root>", data_type="xml")
from_yaml = DataConverter("id: 1\n", data_type="yaml")
from_toml = DataConverter("id = 1\n", data_type="toml")
```

JSON, JSON5, YAML, and TOML documents must be mappings. Arrays and
scalars raise `DataConverterError`.

`to_xml()` wraps the mapping in `root_tag` (the XML source root, or
`root` for other sources). Pass `root_tag` to override it.

```python
converter.to_xml(root_tag="item")
```

### XML

Child elements with the same tag become a list. Attributes are stored
as `@name` keys and written back as attributes. A list value is
emitted as repeated elements with that key. The original root stays
on `converter.root_tag`.

```python
converter = DataConverter('<person id="7"><name>Ann</name></person>', data_type="xml")
converter.data
# {"@id": "7", "name": "Ann"}
converter.to_xml()
# <person id="7">...</person>
```

### Errors

Parse failures, type mismatches, unsupported `data_type` values, and
invalid XML names raise `DataConverterError`. Underlying parser errors
are attached as `__cause__`.

```python
from lupaxa.data_converter import DataConverter, DataConverterError

try:
    DataConverter("{not-json", data_type="json")
except DataConverterError as exc:
    print(exc)
```

### Helpers

These class methods convert without constructing an instance first.
`dict_to_xml` and `json_to_xml` wrap the mapping in `root_tag`
(default `root`). `xml_to_json` returns the element payload, not a
`{root: ...}` wrapper.

```python
from lupaxa.data_converter import DataConverter

DataConverter.dict_to_xml({"id": 1}, root_tag="root")
DataConverter.json_to_xml({"id": 1}, root_tag="root")
DataConverter.xml_to_json("<root><id>1</id></root>")
DataConverter.yaml_to_dict("id: 1\n")
DataConverter.toml_to_dict("id = 1\n")
DataConverter.json5_to_dict("{ id: 1, }")
```

<a href="https://github.com/the-lupaxa-project">
    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
</a>
