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,
    "w15": W15,
    "w16cid": W16CID,
    "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 cached 

qn(name: str) -> str

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

Memoized, and unboundedly so: the input domain is the OOXML tag vocabulary, a few hundred literals fixed at authoring time. The resolver calls this from inside its hot loops — 563,000 times in a 1000-paragraph sweep, 25% of the runtime — because writing qn("w:r") at the callsite is what keeps that code legible. Caching buys the legibility back for free. Failures are not cached, so a bad name raises every time it is asked.

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 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
@cache
def qn(name: str) -> str:
    """Convert ``"prefix:local"`` to Clark notation ``"{namespace}local"``.

    Memoized, and unboundedly so: the input domain is the OOXML tag
    vocabulary, a few hundred literals fixed at authoring time. The
    resolver calls this from inside its hot loops — 563,000 times in a
    1000-paragraph sweep, 25% of the runtime — because writing ``qn("w:r")``
    at the callsite is what keeps that code legible. Caching buys the
    legibility back for free. Failures are not cached, so a bad name raises
    every time it is asked.

    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}"