Metadata-Version: 2.4
Name: maxml
Version: 1.0.3
Summary: A streamlined pure Python XML serializer.
Author: Daniel Sissman
License-Expression: MIT
Project-URL: documentation, https://github.com/bluebinary/maxml/blob/main/README.md
Project-URL: changelog, https://github.com/bluebinary/maxml/blob/main/CHANGELOG.md
Project-URL: repository, https://github.com/bluebinary/maxml
Project-URL: issues, https://github.com/bluebinary/maxml/issues
Project-URL: homepage, https://github.com/bluebinary/maxml
Keywords: xml,serialization,xml serialization,xml writer
Platform: any
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: classicist==1.0.*
Requires-Dist: enumerific==1.0.*
Provides-Extra: development
Requires-Dist: black==24.10.*; extra == "development"
Requires-Dist: pytest==8.3.*; extra == "development"
Requires-Dist: pytest-codeblocks==0.17.0; extra == "development"
Provides-Extra: distribution
Requires-Dist: build; extra == "distribution"
Requires-Dist: twine; extra == "distribution"
Requires-Dist: wheel; extra == "distribution"

# MaXML: A Pure Python XML Serializer

The MaXML library provides a streamlined pure Python XML serializer.

### Requirements

The MaXML library has been tested with Python 3.10, 3.11, 3.12 and 3.13. The library is
not compatible with Python 3.9 or earlier.

### Installation

The MaXML library is available from PyPI, so may be added to a project's dependencies
via its `requirements.txt` file or similar by referencing the MaXML library's name,
`maxml`, or the library may be installed directly into your local runtime environment
using `pip` via the `pip install` command by entering the following into your shell:

	$ pip install maxml

### Example Usage

To use the MaXML library, import the library and begin creating your XML document:

```python
import maxml

root = maxml.Element(name="my:node", namespace="http://namespace.example.org/my")

child = root.subelement(name="my:child-node")

child.set("my-attribute", "my-attribute-value")

child.text = "testing"

root.tostring(pretty=True)
```

The above example will result in the following XML:

```xml
<my:node xmlns:my="http://namespace.example.org/my">
  <my:child-node my-attribute="my-attribute-value">testing</my:child-node>
</my:node>
```

### Methods & Properties

The MaXML library provides two main classes for use in creating and serializing XML, the
`Elements` class that is used to represent nodes in the XML document tree along with any
attributes those nodes have, their associated namespaces, any text content and children,
and the `Namespace` class for holding information about namespaces.

The classes and their methods and properties are listed below:

#### Element Class

The `Element` class constructor `Element(...)` takes the following arguments:

 * `name` (`str`) – The required `name` argument sets the prefixed name of the element.

 * `text` (`str`) – The optional `text` argument can be used to specify the text content
	of the element; alternatively it can be set later via the `text` property.

 * `namespace` (`Namespace` | `str`) – The optional `namespace` argument can be used to
	specify the namespace for the element while it is being created; the namespace can
	either be specified as the URI that corresponds with the prefix specified as part of
	the element's name, or can be a reference to a `Namespace` class instance that holds
	the corresponding `prefix` and matching `URI`. If the matching namespace has already
	been registered before the element is created via the class' `register_element()`
	method, then it is not necessary to specify a `namespace` argument when an element
	that references that namespace (via its `name` prefix) is created.

 * `mixed` (`bool`) – The optional `mixed` argument can be used to override the default
	mixed-content mode of the element; by default each element allows mixed-content
	which means that the element can contain both text content and children; if an
	element should only be allowed to contain text content or children, then
	`mixed` can be set to `False` during the construction of the element, which will
	then prevent both content types from being serialized and will instead result in an
	error being raised.

 * `parent` (`Element`) – The optional `parent` property is used internally by the
	library when sub-elements are created to set the appropriate parent reference; this
	property should not be set manually unless one is conformable with the possible
	side-effects that may occur.

The `Element` class provides the following methods:

 * `register_namespace(prefix: str, uri: str)` – The `register_namespace()`  method
	supports registering namespaces globally for the module or per instance depending
	on whether the method is called on the class directly or whether it is called on a
	specific instance of the class.

	If a namespace is registered globally for the module, the registered namespaces
	become available for use by any instance of the class created within the program
	after that point. This is especially useful for widely used XML namespaces which
	obviates the need to re-register these widely used namespaces for each instance.

	If there are namespaces which are specific to a document that is being created
	and that won't be used elsewhere in the program, then those namespaces can be
	registered on the specific class instance within which they will be used without
	affecting the global list of registered namespaces.

	Each namespace consists of a prefix which can be used to prefix element names
	and the URI associated with that namespace prefix.

	For example, the 'rdf' prefix is associated with the following canonical URI:
		"http://www.w3.org/1999/02/22-rdf-syntax-ns#"

	This would be registered globally by calling:

	```python
	from maxml import Element
	
	Element.register_namespace(
	  prefix="rdf",
	  uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#",
	)
	```

	Or this would be registered locally on an instance of the class before its use by a
	sub-element by calling:

	```python
	from maxml import Element
	
	element = Element(name="my:test", namespace="http://namespace.example.org/my")
	
	element.register_namespace(
	  prefix="rdf",
	  uri="http://www.w3.org/1999/02/22-rdf-syntax-ns#",
	)
	```

	Where `instance` was the variable referencing the desired instance of the class.

 * `set(name: str, value: object)` (`Element`) – The `set()` supports setting a named
	attribute value on the current element; if the named attribute already exists, its
	value is overwritten. The `set()` method returns a reference to `self` so it may be
	chained with other calls on the element.

 * `get(name: str, default: object = None)` (`object` | `None`) – The `get()` supports
	getting the value of a named attribute on the Element if the named attribute exists,
	returning the optional `default` value if the named attributes does not exist or if
	the `default` value has not been specified, returning `None` otherwise.

 * `unset(name: str)` (`Element`) – The `set()` supports unsetting a named attribute on
	the element. The `unset()` method returns a reference to `self` so it may be chained
	with other calls on the element.

 * `subelement(name: str, **kwargs)` (`Element`) – The `subelement()` method creates a
	child element nested under the current element. It requires a `name` and optionally
	accepts all of the other arguments that the `Element` class constructor accepts as
	documented above. When a child element is created, its parent is automatically set
	to the element it is nested under. The `subelement()` method returns a reference to
	the newly created element, thus other calls on that element may be chained.

 * `find(path: str)` (`Element` | `None`) – The `find()` method can be used to find the
	matching element nested within the current element as specified by the element path
	which consists of one or more prefixed names and optional wildcard characters.
	
	The path to the element we wish to find can be specified from the root node of the
	tree by starting the path with the "//" marker which indicates the root node, or the
	path can be specified as a relative path by omitting this, which will result in the
	search starting at the current element node. The path should be specified with the
	name of the element at each level of the nesting that should be matched against to
	reach the desired node; each element node name should be separated by a single "/"
	character, and if any node name could be matched as part of the search the wildcard
	character "*" can be used in place of an element node name.

 * `findall(path: str)` (`list[Element]`) – The `findall()` method can be used to find
	the matching elements nested within the current element as specified by the element
	path which consists of one or more prefixed names and optional wildcard characters.
	
	The `findall()` method uses the same search path format as the `find()` method
	described above, the only difference being that if multiple elements are found at
	the end of the search, all matching elements will be returned instead of the first
	match found as is the case with the `find` method.

 * `tostring(pretty: bool = False, indent: str | int = None, encoding: str = None)` –
	The `tostring()` method supports serializing the current element tree to a string,
	or to a bytes array if a string encoding, such as 'UTF-8' is specified.
	
	To create a 'pretty' printed string, set the `pretty` argument to `True` and set an
	optional indent, which by default is set to two spaces per level of indentation. To
	set the indent level to 1 or more spaces, set `indent` to a positive integer value
	of the number of spaces that should be used for the indentation per level of nesting
	or to use a different whitespace character, such as a tab, set the `indent` value to
	a tab character using the escape sequence for a tab, `"\t"`.
	
	To have the method return an encoded `bytes` sequence instead of a unicode string,
	set the optional `encoding` argument to a valid string encoding, such as `"UTF-8"`.

The `Element` class provides the following properties:

 * `prefix` (`str`) – The `prefix` property returns the prefix portion of the element's
	tag full name, for example `my` from `my:test`.

 * `name` (`str`) – The `name` property getter returns the name portion of the element's
	tag full name, for example `test` from `my:test`.

 * `fullname` (`str`) – The `fullname` property returns the full name of the element's
	tag, for example `my:test`.

 * `namespace` (`Namespace`) – The `namespace` property returns the namespace associated
	with the element, as either registered before the element was created, or created by
	the process of creating the element if the optional `namespace` property was used.

 * `depth` (`int`) – The `depth` property returns depth of the element in the tree.

 * `parent` (`Element` | `None`) – The `parent` property returns the parent, if any, of
	the element; the root node of the tree will not have a parent, while all other
	elements will have an assigned parent, set automatically when a sub-element is made.

 * `children` (`list[Element]`) – The `children` property returns the list of children
	elements associated with the element, if any have been assigned.

 * `attributes` (`dict[str, str]`) – The `attributes` property returns a dictionary of
	the attributes associated with the element, if any have been assigned, where the key
	of each entry is the name of the attribute and the value is its value.

 * `text` (`str` | `None`) – The `text` property returns the text of the element if any
	has been assigned or `None` otherwise.

 * `mixed` (`bool`) – The `mixed` property returns the mixed-content status of the
	element which determines whether the element can have both text content and children
	or if at most it can only have one or the other. By default each element allows both
	content types, but by setting the `mixed` argument on the `Element` constructor to
	`False`, mixed-content mode will be turned-off.

 * `root` (`Element`) – The `root` property returns the root element of the tree from
	anywhere else within the tree.

 * `namespaces` (`set[Namespace]`) – The `namespaces` property returns the full `set` of
	namespaces associated with the element including any inherited from its parents; the
	set can be used to inspect the associated namespaces, but its primary use is to help
	facilitate the serialization of the document.

 * `namespaced` (`set[Namespace]`) – The `namespaced` property returns the unique `set`
	of namespaces associated with the element that have not already been referenced by
	a parent node, thus ensuring only the newly referenced namespaces are introduced in
	the serialized document rather than potentially repeated references to namespaces
	which have already been referenced previously; the set can be used to inspect the
	associated namespaces, but its primary use is to help facilitate the serialization.

#### Namespace Class

The `Namespace` class constructor `Namespace(...)` takes the following arguments:

 * `prefix` (`str`) – The required `prefix` argument sets the namespace prefix.
 * `uri` (`str`) – The required `uri` argument sets the namespace URI.

The `Namespace` class provides the following methods:

 * `copy()` (`Namespace`) – The `copy()` method creates an independent copy of the
	current Namespace instance and returns it.

 * `promote()` (`Namespace`) – The `promote()` marks the current Namespace instance as
	having been 'promoted' which allows it to be listed before any attributes on the
	Element it is associated with; as this method returns a reference to `self` it may
	be chained with other calls.

 * `unpromote()` (`Namespace`) – The `unpromote()` marks the current Namespace instance
	as having been 'un-promoted' preventing it from being listed before any attributes
	on the Element it is associated with; as this method returns a reference to `self`
	it may be chained with other calls.

The `Namespace` class provides the following properties:

 * `prefix` (`str`) – The `prefix` property returns the prefix held by the namespace.
 * `uri` (`str`) – The `uri` property returns the URI held by the namespace.
 * `promoted` (`bool`) – The `promoted` property getter returns the promoted state of the
	Namespace instance as set or unset through the `promote()` and `unpromote()` helper
	methods or via the `promoted` property setter.
 * `promoted` (`bool`) – The `promoted` property setter supports setting the `promoted`
	property value via the property accessor.


### Unit Tests

The MaXML library includes a suite of comprehensive unit tests which ensure that the
library functionality operates as expected. The unit tests were developed with and are
run via `pytest`.

To ensure that the unit tests are run within a predictable runtime environment where all of the necessary dependencies are available, a [Docker](https://www.docker.com) image is created within which the tests are run. To run the unit tests, ensure Docker and Docker Compose is [installed](https://docs.docker.com/engine/install/), and perform the following commands, which will build the Docker image via `docker compose build` and then run the tests via `docker compose run` – the output of running the tests will be displayed:

```shell
$ docker compose build
$ docker compose run tests
```

To run the unit tests with optional command line arguments being passed to `pytest`, append the relevant arguments to the `docker compose run tests` command, as follows, for example passing `-vv` to enable verbose output:

```shell
$ docker compose run tests -vv
```

See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding available optional command line arguments.

### Copyright & License Information

Copyright © 2025 Daniel Sissman; licensed under the MIT License.
