Skip to content

Mixin Named Range

Mixin class NRMixin for classes using Named Ranges.

Classes:

Name Description
NRMixin

Mixin for Named Range access.
TableNamedExpressions

Container of assignments of names to expressions, tag “table:named-expressions”.

NRMixin

Bases: Element

Mixin for Named Range access.

Used by the following classes: Chart, Drawing, Presentation, Spreadsheet, Text.

Methods:

Name Description
append_named_range

Append a NamedRange object to the document.
delete_named_range

Delete a named range from the document by its name.
get_named_range

Retrieve a specific named range global to the document by its name.
get_named_ranges

Retrieve all named ranges (NamedRange objects) global to the document.
set_named_range

Create or update a named range in the document.
Source code in odfdo/mixin_named_range.py 
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 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
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
class NRMixin(Element):
    """Mixin for Named Range access.

    Used by the following classes: Chart, Drawing, Presentation, Spreadsheet, Text.
    """

    def get_named_ranges(self) -> list[NamedRange]:
        """Retrieve all named ranges (`NamedRange` objects) global to the document.

        Returns:
            list[NamedRange]: A list of `NamedRange` instances found in the document.
        """
        return cast(
            list[NamedRange],
            self.get_elements("descendant::table:named-expressions/table:named-range"),
        )

    def get_named_range(self, name: str) -> NamedRange | None:
        """Retrieve a specific named range global to the document by its name.

        Args:
            name: The name of the named range to retrieve.

        Returns:
            NamedRange | None: The `NamedRange` instance if found, otherwise `None`.
        """
        named_range = cast(
            list[NamedRange],
            self.get_elements(
                f'descendant::table:named-expressions/table:named-range[@table:name="{name}"][1]'
            ),
        )
        if named_range:
            return named_range[0]
        else:
            return None

    def append_named_range(self, named_range: NamedRange) -> None:
        """Append a `NamedRange` object to the document.

        If a named range with the same name already exists, it will be replaced.

        Args:
            named_range: The `NamedRange` object to append.
        """
        named_expressions = cast(
            None | TableNamedExpressions,
            self.get_element("table:named-expressions"),
        )
        if not named_expressions:
            named_expressions = cast(
                TableNamedExpressions, Element.from_tag("table:named-expressions")
            )
            self._Element__append(named_expressions)  # type: ignore[attr-defined]
        # exists ?
        current = cast(
            None | NamedRange,
            named_expressions.get_element(
                f'table:named-range[@table:name="{named_range.name}"][1]'
            ),
        )
        if current:
            named_expressions.delete(current)
        named_expressions._Element__append(named_range)  # type: ignore[attr-defined]

    def set_named_range(
        self,
        name: str,
        crange: str | tuple | list,
        table_name: str,
        usage: str | None = None,
    ) -> None:
        """Create or update a named range in the document.

        A `NamedRange` element is created with the given parameters and inserted
        into the document. If a named range with the same name already exists,
        it will be replaced.

        Args:
            name: The name of the named range.
            crange: The cell or cell range coordinate
                (e.g., "Sheet1.A1", "Sheet1.A1:B2", or a tuple/list of integers
                representing coordinates).
            table_name: The name of the table to which the named range refers.
            usage: Optional usage type (e.g., "print-range", "filter",
                "repeat-column", "repeat-row").

        Raises:
            ValueError: If `name` or `table_name` is empty.
        """
        name = name.strip()
        if not name:
            raise ValueError("Name required")
        table_name = table_name.strip()
        if not table_name:
            raise ValueError("Table name required")
        named_range = NamedRange(name, crange, table_name, usage)
        self.append_named_range(named_range)

    def delete_named_range(self, name: str) -> None:
        """Delete a named range from the document by its name.

        Args:
            name: The name of the named range to delete.
        """
        named_range = self.get_named_range(name)
        if not named_range:
            return
        named_range.delete()
        named_expressions = cast(
            TableNamedExpressions, self.get_element("table:named-expressions")
        )
        if named_expressions.is_empty():
            self.delete(named_expressions)

append_named_range 

append_named_range(named_range: NamedRange) -> None

Append a NamedRange object to the document.

If a named range with the same name already exists, it will be replaced.

Parameters:

Name Type Description Default
named_range NamedRange

The NamedRange object to append.

 required
Source code in odfdo/mixin_named_range.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def append_named_range(self, named_range: NamedRange) -> None:
    """Append a `NamedRange` object to the document.

    If a named range with the same name already exists, it will be replaced.

    Args:
        named_range: The `NamedRange` object to append.
    """
    named_expressions = cast(
        None | TableNamedExpressions,
        self.get_element("table:named-expressions"),
    )
    if not named_expressions:
        named_expressions = cast(
            TableNamedExpressions, Element.from_tag("table:named-expressions")
        )
        self._Element__append(named_expressions)  # type: ignore[attr-defined]
    # exists ?
    current = cast(
        None | NamedRange,
        named_expressions.get_element(
            f'table:named-range[@table:name="{named_range.name}"][1]'
        ),
    )
    if current:
        named_expressions.delete(current)
    named_expressions._Element__append(named_range)  # type: ignore[attr-defined]

delete_named_range 

delete_named_range(name: str) -> None

Delete a named range from the document by its name.

Parameters:

Name Type Description Default
name str

The name of the named range to delete.

 required
Source code in odfdo/mixin_named_range.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def delete_named_range(self, name: str) -> None:
    """Delete a named range from the document by its name.

    Args:
        name: The name of the named range to delete.
    """
    named_range = self.get_named_range(name)
    if not named_range:
        return
    named_range.delete()
    named_expressions = cast(
        TableNamedExpressions, self.get_element("table:named-expressions")
    )
    if named_expressions.is_empty():
        self.delete(named_expressions)

get_named_range 

get_named_range(name: str) -> NamedRange | None

Retrieve a specific named range global to the document by its name.

Parameters:

Name Type Description Default
name str

The name of the named range to retrieve.

 required

Returns:

Type Description
NamedRange | None

NamedRange | None: The NamedRange instance if found, otherwise None.
Source code in odfdo/mixin_named_range.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def get_named_range(self, name: str) -> NamedRange | None:
    """Retrieve a specific named range global to the document by its name.

    Args:
        name: The name of the named range to retrieve.

    Returns:
        NamedRange | None: The `NamedRange` instance if found, otherwise `None`.
    """
    named_range = cast(
        list[NamedRange],
        self.get_elements(
            f'descendant::table:named-expressions/table:named-range[@table:name="{name}"][1]'
        ),
    )
    if named_range:
        return named_range[0]
    else:
        return None

get_named_ranges 

get_named_ranges() -> list[NamedRange]

Retrieve all named ranges (NamedRange objects) global to the document.

Returns:

Type Description
list[NamedRange]

list[NamedRange]: A list of NamedRange instances found in the document.
Source code in odfdo/mixin_named_range.py 
52
53
54
55
56
57
58
59
60
61
def get_named_ranges(self) -> list[NamedRange]:
    """Retrieve all named ranges (`NamedRange` objects) global to the document.

    Returns:
        list[NamedRange]: A list of `NamedRange` instances found in the document.
    """
    return cast(
        list[NamedRange],
        self.get_elements("descendant::table:named-expressions/table:named-range"),
    )

set_named_range 

set_named_range(
    name: str,
    crange: str | tuple | list,
    table_name: str,
    usage: str | None = None,
) -> None

Create or update a named range in the document.

A NamedRange element is created with the given parameters and inserted into the document. If a named range with the same name already exists, it will be replaced.

Parameters:

Name Type Description Default
name str

The name of the named range.

 required
crange str | tuple | list

The cell or cell range coordinate (e.g., “Sheet1.A1”, “Sheet1.A1:B2”, or a tuple/list of integers representing coordinates).

 required
table_name str

The name of the table to which the named range refers.

 required
usage str | None

Optional usage type (e.g., “print-range”, “filter”, “repeat-column”, “repeat-row”).

 None

Raises:

Type Description
ValueError

If name or table_name is empty.
Source code in odfdo/mixin_named_range.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
def set_named_range(
    self,
    name: str,
    crange: str | tuple | list,
    table_name: str,
    usage: str | None = None,
) -> None:
    """Create or update a named range in the document.

    A `NamedRange` element is created with the given parameters and inserted
    into the document. If a named range with the same name already exists,
    it will be replaced.

    Args:
        name: The name of the named range.
        crange: The cell or cell range coordinate
            (e.g., "Sheet1.A1", "Sheet1.A1:B2", or a tuple/list of integers
            representing coordinates).
        table_name: The name of the table to which the named range refers.
        usage: Optional usage type (e.g., "print-range", "filter",
            "repeat-column", "repeat-row").

    Raises:
        ValueError: If `name` or `table_name` is empty.
    """
    name = name.strip()
    if not name:
        raise ValueError("Name required")
    table_name = table_name.strip()
    if not table_name:
        raise ValueError("Table name required")
    named_range = NamedRange(name, crange, table_name, usage)
    self.append_named_range(named_range)

TableNamedExpressions

Bases: Element

Container of assignments of names to expressions, tag “table:named-expressions”.

(Mostly internal use). The following expressions may have names: - cell ranges, - Other expressions.

If the “table:named-expressions” element is used with a “table:table” element, the scope of the named expressions are local to that table element.

Source code in odfdo/mixin_named_range.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
class TableNamedExpressions(Element):
    """Container of assignments of names to expressions, tag "table:named-expressions".

    (Mostly internal use).
    The following expressions may have names:
      - cell ranges,
      - Other expressions.

    If the "table:named-expressions" element is used with a "table:table" element,
    the scope of the named expressions are local to that table element.
    """

    _tag: str = "table:named-expressions"
    _properties: tuple[PropDef | PropDefBool, ...] = ()

_properties class-attribute instance-attribute 

_properties: tuple[PropDef | PropDefBool, ...] = ()

_tag class-attribute instance-attribute 

_tag: str = 'table:named-expressions'