Skip to content

ns

ns

Namespace-related objects.

NamespacePrefixedTag 

NamespacePrefixedTag(nstag: str)

Bases: str

Value object that knows the semantics of an XML tag having a namespace prefix.

Source code in src/docx/oxml/ns.py 
67
68
69
def __init__(self, nstag: str):
    self._pfx, self._local_part = nstag.split(":")
    self._ns_uri = nsmap[self._pfx]

local_part property 

local_part: str

The local part of this tag.

E.g. "foobar" is returned for tag "f:foobar".

nsmap property 

nsmap: Dict[str, str]

Single-member dict mapping prefix of this tag to it's namespace name.

Example: {"f": "http://foo/bar"}. This is handy for passing to xpath calls and other uses.

nspfx property 

nspfx: str

The namespace-prefix for this tag.

For example, "f" is returned for tag "f:foobar".

nsuri property 

nsuri: str

The namespace URI for this tag.

For example, "http://foo/bar" would be returned for tag "f:foobar" if the "f" prefix maps to "http://foo/bar" in nsmap.

is_strict_ooxml_tag 

is_strict_ooxml_tag(tag: object) -> bool

True if tag is a Clark-notation tag name in an ISO Strict namespace.

False for anything that is not a string tag, which covers lxml's comment and processing-instruction elements.

Source code in src/docx/oxml/ns.py 
52
53
54
55
56
57
58
def is_strict_ooxml_tag(tag: object) -> bool:
    """True if `tag` is a Clark-notation tag name in an ISO Strict namespace.

    False for anything that is not a string tag, which covers lxml's comment and
    processing-instruction elements.
    """
    return isinstance(tag, str) and tag.startswith("{" + STRICT_NS_PREFIX)

nsdecls 

nsdecls(*prefixes: str) -> str

Namespace declaration including each namespace-prefix in prefixes.

Handy for adding required namespace declarations to a tree root element.

Source code in src/docx/oxml/ns.py 
116
117
118
119
120
121
def nsdecls(*prefixes: str) -> str:
    """Namespace declaration including each namespace-prefix in `prefixes`.

    Handy for adding required namespace declarations to a tree root element.
    """
    return " ".join(['xmlns:%s="%s"' % (pfx, nsmap[pfx]) for pfx in prefixes])

nspfxmap 

nspfxmap(*nspfxs: str) -> Dict[str, str]

Subset namespace-prefix mappings specified by nspfxs.

Any number of namespace prefixes can be supplied, e.g. namespaces("a", "r", "p").

Source code in src/docx/oxml/ns.py 
124
125
126
127
128
129
def nspfxmap(*nspfxs: str) -> Dict[str, str]:
    """Subset namespace-prefix mappings specified by *nspfxs*.

    Any number of namespace prefixes can be supplied, e.g. namespaces("a", "r", "p").
    """
    return {pfx: nsmap[pfx] for pfx in nspfxs}

qn cached 

qn(tag: str) -> str

Stands for "qualified name".

This utility function converts a familiar namespace-prefixed tag name like "w:p" into a Clark-notation qualified tag name for lxml. For example, qn("w:p") returns "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p".

Memoized; nsmap is a fixed table and this is called for every element access.

Source code in src/docx/oxml/ns.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
@functools.lru_cache(maxsize=None)
def qn(tag: str) -> str:
    """Stands for "qualified name".

    This utility function converts a familiar namespace-prefixed tag name like "w:p"
    into a Clark-notation qualified tag name for lxml. For example, `qn("w:p")` returns
    "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p".

    Memoized; `nsmap` is a fixed table and this is called for every element access.
    """
    prefix, tagroot = tag.split(":")
    uri = nsmap[prefix]
    return "{%s}%s" % (uri, tagroot)