Skip to content

Commit 4262f4d

Browse files
scannyscanny
committed
modn: improve type annotation
1 parent 3228bc5 commit 4262f4d

File tree

9 files changed

+51
-57
lines changed

9 files changed

+51
-57
lines changed

‎src/docx/opc/coreprops.py

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66
from __future__ import annotations
77

8+
import datetime as dt
89
from typing import TYPE_CHECKING
910

1011
from docx.oxml.coreprops import CT_CoreProperties
@@ -57,7 +58,7 @@ def created(self):
5758
return self._element.created_datetime
5859

5960
@created.setter
60-
def created(self, value):
61+
def created(self, value: dt.datetime):
6162
self._element.created_datetime = value
6263

6364
@property
@@ -97,23 +98,23 @@ def last_printed(self):
9798
return self._element.lastPrinted_datetime
9899

99100
@last_printed.setter
100-
def last_printed(self, value):
101+
def last_printed(self, value: dt.datetime):
101102
self._element.lastPrinted_datetime = value
102103

103104
@property
104105
def modified(self):
105106
return self._element.modified_datetime
106107

107108
@modified.setter
108-
def modified(self, value):
109+
def modified(self, value: dt.datetime):
109110
self._element.modified_datetime = value
110111

111112
@property
112113
def revision(self):
113114
return self._element.revision_number
114115

115116
@revision.setter
116-
def revision(self, value):
117+
def revision(self, value: int):
117118
self._element.revision_number = value
118119

119120
@property

‎src/docx/opc/oxml.py

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ def parse_xml(text: str) -> etree._Element:
3838
return etree.fromstring(text, oxml_parser)
3939

4040

41-
def qn(tag):
41+
def qn(tag: str) -> str:
4242
"""Stands for "qualified name", a utility function to turn a namespace prefixed tag
4343
name into a Clark-notation qualified tag name for lxml.
4444
@@ -50,7 +50,7 @@ def qn(tag):
5050
return "{%s}%s" % (uri, tagroot)
5151

5252

53-
def serialize_part_xml(part_elm: etree._Element):
53+
def serialize_part_xml(part_elm: etree._Element) -> bytes:
5454
"""Serialize `part_elm` etree element to XML suitable for storage as an XML part.
5555
5656
That is to say, no insignificant whitespace added for readability, and an
@@ -59,7 +59,7 @@ def serialize_part_xml(part_elm: etree._Element):
5959
return etree.tostring(part_elm, encoding="UTF-8", standalone=True)
6060

6161

62-
def serialize_for_reading(element):
62+
def serialize_for_reading(element: etree._Element) -> str:
6363
"""Serialize `element` to human-readable XML suitable for tests.
6464
6565
No XML declaration.
@@ -77,7 +77,7 @@ class BaseOxmlElement(etree.ElementBase):
7777
classes in one place."""
7878

7979
@property
80-
def xml(self):
80+
def xml(self) -> str:
8181
"""Return XML string for this element, suitable for testing purposes.
8282
8383
Pretty printed for readability and without an XML declaration at the top.
@@ -86,8 +86,10 @@ def xml(self):
8686

8787

8888
class CT_Default(BaseOxmlElement):
89-
"""``<Default>`` element, specifying the default content type to be applied to a
90-
part with the specified extension."""
89+
"""`<Default>` element that appears in `[Content_Types].xml` part.
90+
91+
Used to specify a default content type to be applied to any part with the specified extension.
92+
"""
9193

9294
@property
9395
def content_type(self):
@@ -101,9 +103,8 @@ def extension(self):
101103
return self.get("Extension")
102104

103105
@staticmethod
104-
def new(ext, content_type):
105-
"""Return a new ``<Default>`` element with attributes set to parameter
106-
values."""
106+
def new(ext: str, content_type: str):
107+
"""Return a new ``<Default>`` element with attributes set to parameter values."""
107108
xml = '<Default xmlns="%s"/>' % nsmap["ct"]
108109
default = parse_xml(xml)
109110
default.set("Extension", ext)
@@ -123,8 +124,7 @@ def content_type(self):
123124

124125
@staticmethod
125126
def new(partname, content_type):
126-
"""Return a new ``<Override>`` element with attributes set to parameter
127-
values."""
127+
"""Return a new ``<Override>`` element with attributes set to parameter values."""
128128
xml = '<Override xmlns="%s"/>' % nsmap["ct"]
129129
override = parse_xml(xml)
130130
override.set("PartName", partname)
@@ -138,8 +138,7 @@ def partname(self):
138138

139139

140140
class CT_Relationship(BaseOxmlElement):
141-
"""``<Relationship>`` element, representing a single relationship from a source to a
142-
target part."""
141+
"""`<Relationship>` element, representing a single relationship from source to target part."""
143142

144143
@staticmethod
145144
def new(rId: str, reltype: str, target: str, target_mode: str = RTM.INTERNAL):

‎src/docx/oxml/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@
234234
register_element_cls("w:jc", CT_Jc)
235235
register_element_cls("w:keepLines", CT_OnOff)
236236
register_element_cls("w:keepNext", CT_OnOff)
237+
register_element_cls("w:outlineLvl", CT_DecimalNumber)
237238
register_element_cls("w:pageBreakBefore", CT_OnOff)
238239
register_element_cls("w:pPr", CT_PPr)
239240
register_element_cls("w:pStyle", CT_String)

‎src/docx/oxml/coreprops.py

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
import datetime as dt
66
import re
7-
from typing import TYPE_CHECKING, Any, Callable
7+
from typing import TYPE_CHECKING, Any, Callable, cast
88

99
from docx.oxml.ns import nsdecls, qn
1010
from docx.oxml.parser import parse_xml
@@ -45,14 +45,14 @@ class CT_CoreProperties(BaseOxmlElement):
4545
_coreProperties_tmpl = "<cp:coreProperties %s/>\n" % nsdecls("cp", "dc", "dcterms")
4646

4747
@classmethod
48-
def new(cls):
48+
def new(cls) -> CT_CoreProperties:
4949
"""Return a new `<cp:coreProperties>` element."""
5050
xml = cls._coreProperties_tmpl
51-
coreProperties = parse_xml(xml)
51+
coreProperties = cast(CT_CoreProperties, parse_xml(xml))
5252
return coreProperties
5353

5454
@property
55-
def author_text(self):
55+
def author_text(self) -> str:
5656
"""The text in the `dc:creator` child element."""
5757
return self._text_of_element("creator")
5858

@@ -77,55 +77,55 @@ def comments_text(self, value: str):
7777
self._set_element_text("description", value)
7878

7979
@property
80-
def contentStatus_text(self):
80+
def contentStatus_text(self) -> str:
8181
return self._text_of_element("contentStatus")
8282

8383
@contentStatus_text.setter
8484
def contentStatus_text(self, value: str):
8585
self._set_element_text("contentStatus", value)
8686

8787
@property
88-
def created_datetime(self):
88+
def created_datetime(self) -> dt.datetime | None:
8989
return self._datetime_of_element("created")
9090

9191
@created_datetime.setter
9292
def created_datetime(self, value: dt.datetime):
9393
self._set_element_datetime("created", value)
9494

9595
@property
96-
def identifier_text(self):
96+
def identifier_text(self) -> str:
9797
return self._text_of_element("identifier")
9898

9999
@identifier_text.setter
100100
def identifier_text(self, value: str):
101101
self._set_element_text("identifier", value)
102102

103103
@property
104-
def keywords_text(self):
104+
def keywords_text(self) -> str:
105105
return self._text_of_element("keywords")
106106

107107
@keywords_text.setter
108108
def keywords_text(self, value: str):
109109
self._set_element_text("keywords", value)
110110

111111
@property
112-
def language_text(self):
112+
def language_text(self) -> str:
113113
return self._text_of_element("language")
114114

115115
@language_text.setter
116116
def language_text(self, value: str):
117117
self._set_element_text("language", value)
118118

119119
@property
120-
def lastModifiedBy_text(self):
120+
def lastModifiedBy_text(self) -> str:
121121
return self._text_of_element("lastModifiedBy")
122122

123123
@lastModifiedBy_text.setter
124124
def lastModifiedBy_text(self, value: str):
125125
self._set_element_text("lastModifiedBy", value)
126126

127127
@property
128-
def lastPrinted_datetime(self):
128+
def lastPrinted_datetime(self) -> dt.datetime | None:
129129
return self._datetime_of_element("lastPrinted")
130130

131131
@lastPrinted_datetime.setter
@@ -141,7 +141,7 @@ def modified_datetime(self, value: dt.datetime):
141141
self._set_element_datetime("modified", value)
142142

143143
@property
144-
def revision_number(self):
144+
def revision_number(self) -> int:
145145
"""Integer value of revision property."""
146146
revision = self.revision
147147
if revision is None:
@@ -167,23 +167,23 @@ def revision_number(self, value: int):
167167
revision.text = str(value)
168168

169169
@property
170-
def subject_text(self):
170+
def subject_text(self) -> str:
171171
return self._text_of_element("subject")
172172

173173
@subject_text.setter
174174
def subject_text(self, value: str):
175175
self._set_element_text("subject", value)
176176

177177
@property
178-
def title_text(self):
178+
def title_text(self) -> str:
179179
return self._text_of_element("title")
180180

181181
@title_text.setter
182182
def title_text(self, value: str):
183183
self._set_element_text("title", value)
184184

185185
@property
186-
def version_text(self):
186+
def version_text(self) -> str:
187187
return self._text_of_element("version")
188188

189189
@version_text.setter
@@ -257,7 +257,7 @@ def _parse_W3CDTF_to_datetime(cls, w3cdtf_str: str) -> dt.datetime:
257257
dt_ = cls._offset_dt(dt_, offset_str)
258258
return dt_.replace(tzinfo=dt.timezone.utc)
259259

260-
def _set_element_datetime(self, prop_name: str, value: dt.datetime):
260+
def _set_element_datetime(self, prop_name: str, value: dt.datetime) -> None:
261261
"""Set date/time value of child element having `prop_name` to `value`."""
262262
if not isinstance(value, dt.datetime): # pyright: ignore[reportUnnecessaryIsInstance]
263263
tmpl = "property requires <type 'datetime.datetime'> object, got %s"

‎src/docx/oxml/ns.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
from __future__ import annotations
44

5-
from typing import Any, Dict
5+
from typing import Dict
66

77
nsmap = {
88
"a": "http://schemas.openxmlformats.org/drawingml/2006/main",
@@ -29,7 +29,7 @@
2929
class NamespacePrefixedTag(str):
3030
"""Value object that knows the semantics of an XML tag having a namespace prefix."""
3131

32-
def __new__(cls, nstag: str, *args: Any):
32+
def __new__(cls, nstag: str):
3333
return super(NamespacePrefixedTag, cls).__new__(cls, nstag)
3434

3535
def __init__(self, nstag: str):

‎src/docx/oxml/shape.py

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -145,10 +145,8 @@ class CT_Picture(BaseOxmlElement):
145145
spPr: CT_ShapeProperties = OneAndOnlyOne("pic:spPr") # pyright: ignore[reportAssignmentType]
146146

147147
@classmethod
148-
def new(cls, pic_id, filename, rId, cx, cy):
149-
"""Return a new ``<pic:pic>`` element populated with the minimal contents
150-
required to define a viable picture element, based on the values passed as
151-
parameters."""
148+
def new(cls, pic_id: int, filename: str, rId: str, cx: Length, cy: Length) -> CT_Picture:
149+
"""A new minimum viable `<pic:pic>` (picture) element."""
152150
pic = parse_xml(cls._pic_xml())
153151
pic.nvPicPr.cNvPr.id = pic_id
154152
pic.nvPicPr.cNvPr.name = filename

‎src/docx/oxml/text/parfmt.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
WD_TAB_ALIGNMENT,
1111
WD_TAB_LEADER,
1212
)
13+
from docx.oxml.shared import CT_DecimalNumber
1314
from docx.oxml.simpletypes import ST_SignedTwipsMeasure, ST_TwipsMeasure
1415
from docx.oxml.xmlchemy import (
1516
BaseOxmlElement,
@@ -55,6 +56,7 @@ class CT_PPr(BaseOxmlElement):
5556

5657
get_or_add_ind: Callable[[], CT_Ind]
5758
get_or_add_pStyle: Callable[[], CT_String]
59+
get_or_add_sectPr: Callable[[], CT_SectPr]
5860
_insert_sectPr: Callable[[CT_SectPr], None]
5961
_remove_pStyle: Callable[[], None]
6062
_remove_sectPr: Callable[[], None]
@@ -111,6 +113,9 @@ class CT_PPr(BaseOxmlElement):
111113
"w:ind", successors=_tag_seq[23:]
112114
)
113115
jc = ZeroOrOne("w:jc", successors=_tag_seq[27:])
116+
outlineLvl: CT_DecimalNumber = ZeroOrOne( # pyright: ignore[reportAssignmentType]
117+
"w:outlineLvl", successors=_tag_seq[31:]
118+
)
114119
sectPr = ZeroOrOne("w:sectPr", successors=_tag_seq[35:])
115120
del _tag_seq
116121

‎src/docx/oxml/xmlchemy.py

Lines changed: 7 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,7 @@
55
from __future__ import annotations
66

77
import re
8-
from typing import (
9-
TYPE_CHECKING,
10-
Any,
11-
Callable,
12-
Dict,
13-
List,
14-
Sequence,
15-
Tuple,
16-
Type,
17-
TypeVar,
18-
)
8+
from typing import TYPE_CHECKING, Any, Callable, Sequence, Type, TypeVar
199

2010
from lxml import etree
2111
from lxml.etree import ElementBase, _Element # pyright: ignore[reportPrivateUsage]
@@ -65,7 +55,7 @@ def __eq__(self, other: object) -> bool:
6555
def __ne__(self, other: object) -> bool:
6656
return not self.__eq__(other)
6757

68-
def _attr_seq(self, attrs: str) -> List[str]:
58+
def _attr_seq(self, attrs: str) -> list[str]:
6959
"""Return a sequence of attribute strings parsed from `attrs`.
7060
7161
Each attribute string is stripped of whitespace on both ends.
@@ -90,7 +80,7 @@ def _eq_elm_strs(self, line: str, line_2: str):
9080
return True
9181

9282
@classmethod
93-
def _parse_line(cls, line: str) -> Tuple[str, str, str, str]:
83+
def _parse_line(cls, line: str) -> tuple[str, str, str, str]:
9484
"""(front, attrs, close, text) 4-tuple result of parsing XML element `line`."""
9585
match = cls._xml_elm_line_patt.match(line)
9686
if match is None:
@@ -105,7 +95,7 @@ def _parse_line(cls, line: str) -> Tuple[str, str, str, str]:
10595
class MetaOxmlElement(type):
10696
"""Metaclass for BaseOxmlElement."""
10797

108-
def __init__(cls, clsname: str, bases: Tuple[type, ...], namespace: Dict[str, Any]):
98+
def __init__(cls, clsname: str, bases: tuple[type, ...], namespace: dict[str, Any]):
10999
dispatchable = (
110100
OneAndOnlyOne,
111101
OneOrMore,
@@ -280,7 +270,7 @@ class _BaseChildElement:
280270
and ZeroOrMore.
281271
"""
282272

283-
def __init__(self, nsptagname: str, successors: Tuple[str, ...] = ()):
273+
def __init__(self, nsptagname: str, successors: tuple[str, ...] = ()):
284274
super(_BaseChildElement, self).__init__()
285275
self._nsptagname = nsptagname
286276
self._successors = successors
@@ -446,7 +436,7 @@ def populate_class_members( # pyright: ignore[reportIncompatibleMethodOverride]
446436
self,
447437
element_cls: MetaOxmlElement,
448438
group_prop_name: str,
449-
successors: Tuple[str, ...],
439+
successors: tuple[str, ...],
450440
) -> None:
451441
"""Add the appropriate methods to `element_cls`."""
452442
self._element_cls = element_cls
@@ -597,7 +587,7 @@ class ZeroOrOneChoice(_BaseChildElement):
597587
"""Correspondes to an ``EG_*`` element group where at most one of its members may
598588
appear as a child."""
599589

600-
def __init__(self, choices: Sequence[Choice], successors: Tuple[str, ...] = ()):
590+
def __init__(self, choices: Sequence[Choice], successors: tuple[str, ...] = ()):
601591
self._choices = choices
602592
self._successors = successors
603593

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy