| Name | xmlable JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | None |
| Summary | A decorator for generating xsd, xml and parsers from dataclasses |
| upload_time | 2023-08-27 14:44:34 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2023 Oliver Killane
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. |
| keywords |
lxml
xml
xmlschema
xsd
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# XMLable
## An easy xml/xsd generator and parser for python dataclasses!
```python
@xmlify
@dataclass
class Config:
date: str
number_of_cores: int
codes: list[int]
show_logs: bool
write_xsd(THIS_DIR / "config.xsd", Config)
write_xml_template(THIS_DIR / "config_xml_template.xml", Config)
original = Config(
date="31/02/2023",
number_of_cores=48,
codes=[101, 345, 42, 67],
show_logs=False,
)
write_xml_value(THIS_DIR / "config_xml_example.xml", original)
read_config: Config = parse_file(Config, THIS_DIR / "config_xml_example.xml")
assert read_config == original
```
See more in [examples](https://github.com/OliverKillane/xmlable/tree/master/examples)
## Capabilities
### Types
Currently supports the types:
```python
int, float, str, dict, tuple, set, list, None
# as well as unions!
int | float | None
```
And dataclasses that have been `@xmlify`-ed.
These can be combined for types such as:
```python
@xmlify
@dataclass
class Complex:
a: dict[tuple[int, str], list[tuple[dict[int, float | str], set[bool]]]]
c1 = Complex(
a={(3, "hello"): [({3: 0.4}, {True, False}), ({2: "str"}, {False})]}
)
```
### Custom Classes
The xmlify interface can be implemented by adding methods described in [xmlify](src/xmlable/_xmlify.py)
Once the class `is_xmlified` it can be used just as if generated by `@xmlify`
```python
from xmlable._xobject import XObject
from xmlable._user import IXmlify
from xmlable._manual import manual_xmlify
@manual_xmlify
class MyClass(IXmlify):
def get_xobject() -> XObject:
class XMyClass(XObject):
def xsd_out(self, name: str, attribs: dict[str, str] = {}, add_ns: dict[str, str] = {}) -> _Element:
pass
def xml_temp(self, name: str) -> _Element:
pass
def xml_out(self, name: str, val: Any, ctx: XErrorCtx) -> _Element:
pass
def xml_in(self, obj: ObjectifiedElement, ctx: XErrorCtx) -> Any:
pass
return XMyClass() # must be an instance of XMyClass, not the class
def xsd_forward(add_ns: dict[str, str]) -> _Element:
pass
def xsd_dependencies() -> set[type]:
return {MyClass}
```
See the [user define example](https://github.com/OliverKillane/xmlable/tree/master/examples/userdefined) for implementation.
## Limitations
### Unions of Generic Types
Generating xsd works, parsing works, however generating an xml template can fail
if they type is not determinable at runtime.
- Values do not have type arguments carried with them
- Many types are indistinguishable in python
For example:
```python
@xmlify
@dataclass
class GenericUnion:
u: dict[int, float] | dict[int, str]
GenericUnion(u={}) # which variant in the xml should {} have??named_
```
In this case an error is raised
## To Develop
```bash
git clone # this project
# Can use hatch to build, run
hatch run check:test # run tests/
hatch run check:lint # check formatting
hatch run check:typecheck # mypy for src/ and all examples
hatch run auto:examplegen # regenerate the example code
hatch run auto:lint # format code
# Alternatively can just create a normal env
python3.11 -m venv .venv
source .venv/bin/activate # activate virtual environment
pip install -e . # install this project in the venv
pip install -e .[dev] # install optional dev dependencies (mypy, black and pytest)
black . # to reformat
mypy # type check
pytest # to run tests
```
[Hatch](https://hatch.pypa.io/) is used for build, test and pypi publish.
## To Improve
### Fuzzing
(As a fun weekend project) generate arbitrary python data types with values, and dataclasses.
Then `@xmlify` all and validate as in the current tests
### Etree vs Objectify
Currently using objectify for parsing and etree for construction, I want to move parsing to use `etree`
- previously used objectify for quick prototype.
Raw data
{
"_id": null,
"home_page": null,
"name": "xmlable",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "lxml,xml,xmlschema,xsd",
"author": null,
"author_email": "Oliver Killane <oliverkillane.business@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e8/ac/8a33ac6e519ca578a804be977fbd85f61078b851dc09222278b76b598f72/xmlable-2.0.0.tar.gz",
"platform": null,
"description": "# XMLable\n\n## An easy xml/xsd generator and parser for python dataclasses!\n\n```python\n@xmlify\n@dataclass\nclass Config:\n date: str\n number_of_cores: int\n codes: list[int]\n show_logs: bool\n\n\nwrite_xsd(THIS_DIR / \"config.xsd\", Config)\nwrite_xml_template(THIS_DIR / \"config_xml_template.xml\", Config)\n\noriginal = Config(\n date=\"31/02/2023\",\n number_of_cores=48,\n codes=[101, 345, 42, 67],\n show_logs=False,\n)\nwrite_xml_value(THIS_DIR / \"config_xml_example.xml\", original)\n\nread_config: Config = parse_file(Config, THIS_DIR / \"config_xml_example.xml\")\n\nassert read_config == original\n```\n\nSee more in [examples](https://github.com/OliverKillane/xmlable/tree/master/examples)\n\n## Capabilities\n\n### Types\n\nCurrently supports the types:\n\n```python\nint, float, str, dict, tuple, set, list, None\n# as well as unions!\nint | float | None\n```\n\nAnd dataclasses that have been `@xmlify`-ed.\n\nThese can be combined for types such as:\n\n```python\n@xmlify\n@dataclass\nclass Complex:\n a: dict[tuple[int, str], list[tuple[dict[int, float | str], set[bool]]]]\n\nc1 = Complex(\n a={(3, \"hello\"): [({3: 0.4}, {True, False}), ({2: \"str\"}, {False})]}\n)\n```\n\n### Custom Classes\n\nThe xmlify interface can be implemented by adding methods described in [xmlify](src/xmlable/_xmlify.py)\nOnce the class `is_xmlified` it can be used just as if generated by `@xmlify`\n\n```python\nfrom xmlable._xobject import XObject\nfrom xmlable._user import IXmlify\nfrom xmlable._manual import manual_xmlify\n\n@manual_xmlify\nclass MyClass(IXmlify):\n def get_xobject() -> XObject:\n class XMyClass(XObject):\n def xsd_out(self, name: str, attribs: dict[str, str] = {}, add_ns: dict[str, str] = {}) -> _Element:\n pass\n\n def xml_temp(self, name: str) -> _Element:\n pass\n\n def xml_out(self, name: str, val: Any, ctx: XErrorCtx) -> _Element:\n pass\n\n def xml_in(self, obj: ObjectifiedElement, ctx: XErrorCtx) -> Any:\n pass\n\n return XMyClass() # must be an instance of XMyClass, not the class\n\n def xsd_forward(add_ns: dict[str, str]) -> _Element:\n pass\n\n def xsd_dependencies() -> set[type]:\n return {MyClass}\n```\n\nSee the [user define example](https://github.com/OliverKillane/xmlable/tree/master/examples/userdefined) for implementation.\n\n## Limitations\n\n### Unions of Generic Types\n\nGenerating xsd works, parsing works, however generating an xml template can fail\nif they type is not determinable at runtime.\n\n- Values do not have type arguments carried with them\n- Many types are indistinguishable in python\n\nFor example:\n\n```python\n@xmlify\n@dataclass\nclass GenericUnion:\n u: dict[int, float] | dict[int, str]\n\nGenericUnion(u={}) # which variant in the xml should {} have??named_\n```\n\nIn this case an error is raised\n\n## To Develop\n\n```bash\ngit clone # this project\n\n# Can use hatch to build, run\nhatch run check:test # run tests/\nhatch run check:lint # check formatting\nhatch run check:typecheck # mypy for src/ and all examples\n\nhatch run auto:examplegen # regenerate the example code\nhatch run auto:lint # format code\n\n# Alternatively can just create a normal env\npython3.11 -m venv .venv\nsource .venv/bin/activate # activate virtual environment\n\npip install -e . # install this project in the venv\npip install -e .[dev] # install optional dev dependencies (mypy, black and pytest)\n\nblack . # to reformat\nmypy # type check\npytest # to run tests\n```\n\n[Hatch](https://hatch.pypa.io/) is used for build, test and pypi publish.\n\n## To Improve\n\n### Fuzzing\n\n(As a fun weekend project) generate arbitrary python data types with values, and dataclasses.\nThen `@xmlify` all and validate as in the current tests\n\n### Etree vs Objectify\n\nCurrently using objectify for parsing and etree for construction, I want to move parsing to use `etree`\n\n- previously used objectify for quick prototype.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2023 Oliver Killane\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "A decorator for generating xsd, xml and parsers from dataclasses",
"version": "2.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/OliverKillane/xmlable/issues",
"Homepage": "https://github.com/OliverKillane/xmlable",
"Source": "https://github.com/OliverKillane/xmlable"
},
"split_keywords": [
"lxml",
"xml",
"xmlschema",
"xsd"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15a2b099661a2990311d790ee0de2857ea1b12a90f4df70f670726703f825726",
"md5": "35aaa2cff3c251eea7778020783d6c6b",
"sha256": "27b868e99569636452f74a20fd0251320520d08d6ab6f40f04530ec84cfc0964"
},
"downloads": -1,
"filename": "xmlable-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35aaa2cff3c251eea7778020783d6c6b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 17668,
"upload_time": "2023-08-27T14:44:35",
"upload_time_iso_8601": "2023-08-27T14:44:35.671775Z",
"url": "https://files.pythonhosted.org/packages/15/a2/b099661a2990311d790ee0de2857ea1b12a90f4df70f670726703f825726/xmlable-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e8ac8a33ac6e519ca578a804be977fbd85f61078b851dc09222278b76b598f72",
"md5": "c0f9254e2bdb2ff475f82bbbdf96ceac",
"sha256": "96f21d1ad77e2a8dcc2f0cc73f6f3f069ed532201f79137b09341e5e287c84b6"
},
"downloads": -1,
"filename": "xmlable-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c0f9254e2bdb2ff475f82bbbdf96ceac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 20972,
"upload_time": "2023-08-27T14:44:34",
"upload_time_iso_8601": "2023-08-27T14:44:34.740296Z",
"url": "https://files.pythonhosted.org/packages/e8/ac/8a33ac6e519ca578a804be977fbd85f61078b851dc09222278b76b598f72/xmlable-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-27 14:44:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OliverKillane",
"github_project": "xmlable",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xmlable"
}
