Skip to content

docx_plus.core.ns

Namespace constants and the qn() Clark-notation shortcut. Every other module reaches for these when constructing or querying OOXML.

docx_plus.core.ns

OOXML namespace URIs and Clark-notation helper.

All XML element construction in the library uses these constants and the :func:qn helper, so that a single change here propagates everywhere.

NSMAP module-attribute 

NSMAP: dict[str, str] = {
    "w": W,
    "w14": W14,
    "r": R,
    "mc": MC,
    "a": A,
    "xml": XML,
}

W module-attribute 

W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'

W14 module-attribute 

W14 = 'http://schemas.microsoft.com/office/word/2010/wordml'

R module-attribute 

R = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'

MC module-attribute 

MC = 'http://schemas.openxmlformats.org/markup-compatibility/2006'

A module-attribute 

A = 'http://schemas.openxmlformats.org/drawingml/2006/main'

XML module-attribute 

XML = 'http://www.w3.org/XML/1998/namespace'

InvalidNamespaceError

Bases: DocxPlusError, ValueError

Raised by :func:qn for a malformed name or unknown prefix.

Subclasses ValueError so existing except ValueError: clauses still catch it; also subclasses :class:DocxPlusError per SPEC §9.7.

qn 

qn(name: str) -> str

Convert "prefix:local" to Clark notation "{namespace}local".

Parameters:

Name Type Description Default
name str

Qualified name in prefix:local form. prefix must be a key in :data:NSMAP.

 required

Returns:

Type Description
str

The Clark-notation form "{namespace-uri}local-name" used by lxml.

Raises:

Type Description
InvalidNamespaceError

If name is not in prefix:local form, or the prefix is unknown.
Example

qn("w:tag") '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}tag'

Source code in docx_plus/core/ns.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
def qn(name: str) -> str:
    """Convert ``"prefix:local"`` to Clark notation ``"{namespace}local"``.

    Args:
        name: Qualified name in ``prefix:local`` form. ``prefix`` must be a
            key in :data:`NSMAP`.

    Returns:
        The Clark-notation form ``"{namespace-uri}local-name"`` used by lxml.

    Raises:
        InvalidNamespaceError: If ``name`` is not in ``prefix:local`` form,
            or the prefix is unknown.

    Example:
        >>> qn("w:tag")
        '{http://schemas.openxmlformats.org/wordprocessingml/2006/main}tag'
    """
    if ":" not in name:
        raise InvalidNamespaceError(f"qn() expected 'prefix:local', got {name!r}")
    prefix, _, local = name.partition(":")
    try:
        uri = NSMAP[prefix]
    except KeyError as exc:
        raise InvalidNamespaceError(f"unknown namespace prefix {prefix!r} in {name!r}") from exc
    return f"{{{uri}}}{local}"