Package: xmlplain
xmlplainXML as plain object utility moduleSynopsysThis module is a set of utility functions for parsing self-contained
XML input into plain list/dict/string types and emitting to/reading
from XML or YAML formats.The motivating usage was to dump XML to YAML, manually edit
files as YAML, and emit XML output back.Though this module can be used more simply to dump compatible plain
list/dict/string objects into XML or YAML for textual storage.An XML file content when read to object and written back to XML has
all it's document strcuture and content preserved w.r.t. to
elements start/end and text content.
Though XML comments, document type specifications, external
entity definitions are discarded if present on input. External system
entities (i.e. inclusion of external files) are not supported
and generate an input error.The input XML is just syntactically validated and does not validate
against any DTD or schema specification as the underlying backend
is the core xml.sax module.The only and optional destructive transformation on the document
content is astrip_spaceoption on reading (resp.prettyoption
on writing) which can affect non-leaf text content (stripping
leading and trailing spaces).The XML namespaces are ignored as there is no actual schema validation,
hence element, attribute names and namespaces URIs attributes
are passed and preserved as-is.Note that there are alternative modules with nearly the same
functionality, but none of them provide all of:simple plain objects (dict, list, strings) dumped to/reloaded from XMLpreservation of semi-structured XML documents (tags duplicates,
mixed text and tags) on inputmanagement of human-editable form through YAML bridgeUsageIn order to convert a XML file to a YAML representation, for instance given
thetests/example-1.xmlfile:<example><doc>Thisisanexampleforxmlobjdocumentation.</doc><contentversion="beta"><kind>document</kind><class>example</class><structured/><elements><item>Elt1</item><doc>Elt2</doc><item>Elt3</item><doc>Elt4</doc></elements></content></example>Execute the following python code:importxmlplain# Read to plain objectwithopen("tests/example-1.xml")asinf:root=xmlplain.xml_to_obj(inf,strip_space=True,fold_dict=True)# Output plain YAMLwithopen("example-1.yml","w")asoutf:xmlplain.obj_to_yaml(root,outf)This will output the YAML representation inexample-1.yml:example:doc:'Thisisanexampleforxmlobjdocumentation.'content:'@version':betakind:documentclass:examplestructured:''elements:-item:Elt 1-doc:Elt 2-item:Elt 3-doc:Elt 4One can then read the emitted YAML representation and generate
again an XML output with:importxmlplain# Read the YAML filewithopen("example-1.yml")asinf:root=xmlplain.obj_from_yaml(inf)# Output back XMLwithopen("example-1.new.xml","w")asoutf:xmlplain.xml_from_obj(root,outf,pretty=True)This will output back the following XML (there may be some
indentation and/or short empty elements differences w.r.t. the
original):<?xml version="1.0" encoding="UTF-8"?><example><doc>Thisisanexampleforxmlobjdocumentation.</doc><contentversion="beta"><kind>document</kind><class>example</class><structured></structured><elements><item>Elt1</item><doc>Elt2</doc><item>Elt3</item><doc>Elt4</doc></elements></content></example>For a detailled usage, read the API documentation with:pydoc xmlplainOr get to the online documentation at:https://guillon.github.io/xmlplainInstallThe module is compatible withpython 2.6/2.7andpython 3.x.For a local installation (installs to$HOME/.local) do:pip install --user xmlplainThis will install the last release and its dependencies in your user environment.Optionally install at system level with:sudo pip install xlmplainSourcesDownload this module archives from the releases at:https://github.com/guillon/xmlplain/releasesOr clone the source git repository at:https://github.com/guillon/xmlplainInstallation from sourcesInstall first modules dependencies with:pip install --user setuptools PyYAML ordereddictEither copy thexmlplain.pyfile somewhere or install it
withsetup.py.For a user local installation (installs to$HOME/.local) do:./setup.py install --userDevelopmentThis module is delivered as part of a source tree with tests, in order
to run tests, do for instance:make -j16 checkWith python coverage installed, one may check coverage of changes with:make -j16 coverage
firefox tests/coverage/html/index.htmlWhen check target pass and newly added code is covered,
please submit a pull request tohttps://github.com/guillon/xmlplainDocumentationThe documentation is generated withsphinxas is:make doc
firefox html/index.htmlThe online documentation is hosted at:https://guillon.github.io/xmlplainReleaseThe release process relies on the virtualenv tool, python2 and python3
being installed on the release host.The release builds, tests, do coverage checks on both python2 and python3
then generates documentation and uploadable archives for PyPi.Before Bumping a release be sure to update the__version__string
inxmlplain.pyand commit it (no check is done against the version
in the release target).Then Proceed as follow to prepare the release:make -j16 releaseWhen all this passes locally, commit all and push to githubnext/masterbranch in order to have travis checks running.
Verify travis status before proceeding further, for instance
from the travis command line with:travis branchesOnce all is passed, and themake -j16 releasetarget has been re-executed,
upload doc to github and packages to PyPI with:make release-uploadAt this point the package version should be available onhttps://pypi.org/project/xmlplainand the doc updated onhttps://guillon.github.io/xmlplainOne should check the proper installation on PyPi with:make -j16 release-checkWhich will restart a release check, this time downloading from PyPI instead of using
the local sources.After all is done, one should manually update the github with:Apply a tagvx.y.zmatching the new release version and push it to githubGo to github and finalize the tag promotion into a release with and at least upload
also on in the github release the source archivexmlplain-x.y.x.tar.gzavailable
on the just uploaded PyPi files:https://pypi.org/project/xmlplain/#filesOptionally add some information and publish the releaseLicenseThis is free and unencumbered software released into the public domain.