Format: application/octet-stream
1 import sys
2 from _typeshed import AnyPath, FileDescriptor, SupportsWrite
3 from typing import (
4 IO,
5 Any,
6 Callable,
7 Dict,
8 Generator,
9 ItemsView,
10 Iterable,
11 Iterator,
12 KeysView,
13 List,
14 MutableSequence,
15 Optional,
16 Sequence,
17 Text,
18 Tuple,
19 TypeVar,
20 Union,
21 overload,
22 )
23 from typing_extensions import Literal
24
25 VERSION: str
26
27 class ParseError(SyntaxError):
28 code: int
29 position: Tuple[int, int]
30
31 def iselement(element: object) -> bool: ...
32
33 _T = TypeVar("_T")
34
35 # Type for parser inputs. Parser will accept any unicode/str/bytes and coerce,
36 # and this is true in py2 and py3 (even fromstringlist() in python3 can be
37 # called with a heterogeneous list)
38 _parser_input_type = Union[bytes, Text]
39
40 # Type for individual tag/attr/ns/text values in args to most functions.
41 # In py2, the library accepts str or unicode everywhere and coerces
42 # aggressively.
43 # In py3, bytes is not coerced to str and so use of bytes is probably an error,
44 # so we exclude it. (why? the parser never produces bytes when it parses XML,
45 # so e.g., element.get(b'name') will always return None for parsed XML, even if
46 # there is a 'name' attribute.)
47 _str_argument_type = Union[str, Text]
48
49 # Type for return values from individual tag/attr/text values
50 if sys.version_info >= (3,):
51 # note: in python3, everything comes out as str, yay:
52 _str_result_type = str
53 else:
54 # in python2, if the tag/attribute/text wasn't decode-able as ascii, it
55 # comes out as a unicode string; otherwise it comes out as str. (see
56 # _fixtext function in the source). Client code knows best:
57 _str_result_type = Any
58
59 _file_or_filename = Union[AnyPath, FileDescriptor, IO[Any]]
60
61 if sys.version_info >= (3, 8):
62 @overload
63 def canonicalize(
64 xml_data: Optional[_parser_input_type] = ...,
65 *,
66 out: None = ...,
67 from_file: Optional[_file_or_filename] = ...,
68 with_comments: bool = ...,
69 strip_text: bool = ...,
70 rewrite_prefixes: bool = ...,
71 qname_aware_tags: Optional[Iterable[str]] = ...,
72 qname_aware_attrs: Optional[Iterable[str]] = ...,
73 exclude_attrs: Optional[Iterable[str]] = ...,
74 exclude_tags: Optional[Iterable[str]] = ...,
75 ) -> str: ...
76 @overload
77 def canonicalize(
78 xml_data: Optional[_parser_input_type] = ...,
79 *,
80 out: SupportsWrite[str],
81 from_file: Optional[_file_or_filename] = ...,
82 with_comments: bool = ...,
83 strip_text: bool = ...,
84 rewrite_prefixes: bool = ...,
85 qname_aware_tags: Optional[Iterable[str]] = ...,
86 qname_aware_attrs: Optional[Iterable[str]] = ...,
87 exclude_attrs: Optional[Iterable[str]] = ...,
88 exclude_tags: Optional[Iterable[str]] = ...,
89 ) -> None: ...
90
91 class Element(MutableSequence[Element]):
92 tag: _str_result_type
93 attrib: Dict[_str_result_type, _str_result_type]
94 text: Optional[_str_result_type]
95 tail: Optional[_str_result_type]
96 def __init__(
97 self,
98 tag: Union[_str_argument_type, Callable[..., Element]],
99 attrib: Dict[_str_argument_type, _str_argument_type] = ...,
100 **extra: _str_argument_type,
101 ) -> None: ...
102 def append(self, __subelement: Element) -> None: ...
103 def clear(self) -> None: ...
104 def extend(self, __elements: Iterable[Element]) -> None: ...
105 def find(
106 self, path: _str_argument_type, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
107 ) -> Optional[Element]: ...
108 def findall(
109 self, path: _str_argument_type, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
110 ) -> List[Element]: ...
111 @overload
112 def findtext(
113 self,
114 path: _str_argument_type,
115 default: None = ...,
116 namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...,
117 ) -> Optional[_str_result_type]: ...
118 @overload
119 def findtext(
120 self, path: _str_argument_type, default: _T, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
121 ) -> Union[_T, _str_result_type]: ...
122 @overload
123 def get(self, key: _str_argument_type, default: None = ...) -> Optional[_str_result_type]: ...
124 @overload
125 def get(self, key: _str_argument_type, default: _T) -> Union[_str_result_type, _T]: ...
126 if sys.version_info >= (3, 2):
127 def insert(self, __index: int, __subelement: Element) -> None: ...
128 else:
129 def insert(self, __index: int, __element: Element) -> None: ...
130 def items(self) -> ItemsView[_str_result_type, _str_result_type]: ...
131 def iter(self, tag: Optional[_str_argument_type] = ...) -> Generator[Element, None, None]: ...
132 def iterfind(
133 self, path: _str_argument_type, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
134 ) -> List[Element]: ...
135 def itertext(self) -> Generator[_str_result_type, None, None]: ...
136 def keys(self) -> KeysView[_str_result_type]: ...
137 def makeelement(self, __tag: _str_argument_type, __attrib: Dict[_str_argument_type, _str_argument_type]) -> Element: ...
138 def remove(self, __subelement: Element) -> None: ...
139 def set(self, __key: _str_argument_type, __value: _str_argument_type) -> None: ...
140 def __delitem__(self, i: Union[int, slice]) -> None: ...
141 @overload
142 def __getitem__(self, i: int) -> Element: ...
143 @overload
144 def __getitem__(self, s: slice) -> MutableSequence[Element]: ...
145 def __len__(self) -> int: ...
146 @overload
147 def __setitem__(self, i: int, o: Element) -> None: ...
148 @overload
149 def __setitem__(self, s: slice, o: Iterable[Element]) -> None: ...
150 if sys.version_info < (3, 9):
151 def getchildren(self) -> List[Element]: ...
152 def getiterator(self, tag: Optional[_str_argument_type] = ...) -> List[Element]: ...
153
154 def SubElement(
155 parent: Element,
156 tag: _str_argument_type,
157 attrib: Dict[_str_argument_type, _str_argument_type] = ...,
158 **extra: _str_argument_type,
159 ) -> Element: ...
160 def Comment(text: Optional[_str_argument_type] = ...) -> Element: ...
161 def ProcessingInstruction(target: _str_argument_type, text: Optional[_str_argument_type] = ...) -> Element: ...
162
163 PI: Callable[..., Element]
164
165 class QName:
166 text: str
167 def __init__(self, text_or_uri: _str_argument_type, tag: Optional[_str_argument_type] = ...) -> None: ...
168
169 class ElementTree:
170 def __init__(self, element: Optional[Element] = ..., file: Optional[_file_or_filename] = ...) -> None: ...
171 def getroot(self) -> Element: ...
172 def parse(self, source: _file_or_filename, parser: Optional[XMLParser] = ...) -> Element: ...
173 def iter(self, tag: Optional[_str_argument_type] = ...) -> Generator[Element, None, None]: ...
174 if sys.version_info < (3, 9):
175 def getiterator(self, tag: Optional[_str_argument_type] = ...) -> List[Element]: ...
176 def find(
177 self, path: _str_argument_type, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
178 ) -> Optional[Element]: ...
179 @overload
180 def findtext(
181 self,
182 path: _str_argument_type,
183 default: None = ...,
184 namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...,
185 ) -> Optional[_str_result_type]: ...
186 @overload
187 def findtext(
188 self, path: _str_argument_type, default: _T, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
189 ) -> Union[_T, _str_result_type]: ...
190 def findall(
191 self, path: _str_argument_type, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
192 ) -> List[Element]: ...
193 def iterfind(
194 self, path: _str_argument_type, namespaces: Optional[Dict[_str_argument_type, _str_argument_type]] = ...
195 ) -> List[Element]: ...
196 if sys.version_info >= (3, 4):
197 def write(
198 self,
199 file_or_filename: _file_or_filename,
200 encoding: Optional[str] = ...,
201 xml_declaration: Optional[bool] = ...,
202 default_namespace: Optional[_str_argument_type] = ...,
203 method: Optional[str] = ...,
204 *,
205 short_empty_elements: bool = ...,
206 ) -> None: ...
207 else:
208 def write(
209 self,
210 file_or_filename: _file_or_filename,
211 encoding: Optional[str] = ...,
212 xml_declaration: Optional[bool] = ...,
213 default_namespace: Optional[_str_argument_type] = ...,
214 method: Optional[str] = ...,
215 ) -> None: ...
216 def write_c14n(self, file: _file_or_filename) -> None: ...
217
218 def register_namespace(prefix: _str_argument_type, uri: _str_argument_type) -> None: ...
219
220 if sys.version_info >= (3, 8):
221 @overload
222 def tostring(
223 element: Element,
224 encoding: None = ...,
225 method: Optional[str] = ...,
226 *,
227 xml_declaration: Optional[bool] = ...,
228 default_namespace: Optional[_str_argument_type] = ...,
229 short_empty_elements: bool = ...,
230 ) -> bytes: ...
231 @overload
232 def tostring(
233 element: Element,
234 encoding: Literal["unicode"],
235 method: Optional[str] = ...,
236 *,
237 xml_declaration: Optional[bool] = ...,
238 default_namespace: Optional[_str_argument_type] = ...,
239 short_empty_elements: bool = ...,
240 ) -> str: ...
241 @overload
242 def tostring(
243 element: Element,
244 encoding: str,
245 method: Optional[str] = ...,
246 *,
247 xml_declaration: Optional[bool] = ...,
248 default_namespace: Optional[_str_argument_type] = ...,
249 short_empty_elements: bool = ...,
250 ) -> Any: ...
251 @overload
252 def tostringlist(
253 element: Element,
254 encoding: None = ...,
255 method: Optional[str] = ...,
256 *,
257 xml_declaration: Optional[bool] = ...,
258 default_namespace: Optional[_str_argument_type] = ...,
259 short_empty_elements: bool = ...,
260 ) -> List[bytes]: ...
261 @overload
262 def tostringlist(
263 element: Element,
264 encoding: Literal["unicode"],
265 method: Optional[str] = ...,
266 *,
267 xml_declaration: Optional[bool] = ...,
268 default_namespace: Optional[_str_argument_type] = ...,
269 short_empty_elements: bool = ...,
270 ) -> List[str]: ...
271 @overload
272 def tostringlist(
273 element: Element,
274 encoding: str,
275 method: Optional[str] = ...,
276 *,
277 xml_declaration: Optional[bool] = ...,
278 default_namespace: Optional[_str_argument_type] = ...,
279 short_empty_elements: bool = ...,
280 ) -> List[Any]: ...
281
282 elif sys.version_info >= (3,):
283 @overload
284 def tostring(
285 element: Element, encoding: None = ..., method: Optional[str] = ..., *, short_empty_elements: bool = ...
286 ) -> bytes: ...
287 @overload
288 def tostring(
289 element: Element, encoding: Literal["unicode"], method: Optional[str] = ..., *, short_empty_elements: bool = ...
290 ) -> str: ...
291 @overload
292 def tostring(element: Element, encoding: str, method: Optional[str] = ..., *, short_empty_elements: bool = ...) -> Any: ...
293 @overload
294 def tostringlist(
295 element: Element, encoding: None = ..., method: Optional[str] = ..., *, short_empty_elements: bool = ...
296 ) -> List[bytes]: ...
297 @overload
298 def tostringlist(
299 element: Element, encoding: Literal["unicode"], method: Optional[str] = ..., *, short_empty_elements: bool = ...
300 ) -> List[str]: ...
301 @overload
302 def tostringlist(
303 element: Element, encoding: str, method: Optional[str] = ..., *, short_empty_elements: bool = ...
304 ) -> List[Any]: ...
305
306 else:
307 def tostring(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ...) -> bytes: ...
308 def tostringlist(element: Element, encoding: Optional[str] = ..., method: Optional[str] = ...) -> List[bytes]: ...
309
310 def dump(elem: Element) -> None: ...
311 def parse(source: _file_or_filename, parser: Optional[XMLParser] = ...) -> ElementTree: ...
312 def iterparse(
313 source: _file_or_filename, events: Optional[Sequence[str]] = ..., parser: Optional[XMLParser] = ...
314 ) -> Iterator[Tuple[str, Any]]: ...
315
316 if sys.version_info >= (3, 4):
317 class XMLPullParser:
318 def __init__(self, events: Optional[Sequence[str]] = ..., *, _parser: Optional[XMLParser] = ...) -> None: ...
319 def feed(self, data: bytes) -> None: ...
320 def close(self) -> None: ...
321 def read_events(self) -> Iterator[Tuple[str, Element]]: ...
322
323 def XML(text: _parser_input_type, parser: Optional[XMLParser] = ...) -> Element: ...
324 def XMLID(text: _parser_input_type, parser: Optional[XMLParser] = ...) -> Tuple[Element, Dict[_str_result_type, Element]]: ...
325
326 # This is aliased to XML in the source.
327 fromstring = XML
328
329 def fromstringlist(sequence: Sequence[_parser_input_type], parser: Optional[XMLParser] = ...) -> Element: ...
330
331 # This type is both not precise enough and too precise. The TreeBuilder
332 # requires the elementfactory to accept tag and attrs in its args and produce
333 # some kind of object that has .text and .tail properties.
334 # I've chosen to constrain the ElementFactory to always produce an Element
335 # because that is how almost everyone will use it.
336 # Unfortunately, the type of the factory arguments is dependent on how
337 # TreeBuilder is called by client code (they could pass strs, bytes or whatever);
338 # but we don't want to use a too-broad type, or it would be too hard to write
339 # elementfactories.
340 _ElementFactory = Callable[[Any, Dict[Any, Any]], Element]
341
342 class TreeBuilder:
343 def __init__(self, element_factory: Optional[_ElementFactory] = ...) -> None: ...
344 def close(self) -> Element: ...
345 def data(self, __data: _parser_input_type) -> None: ...
346 def start(self, __tag: _parser_input_type, __attrs: Dict[_parser_input_type, _parser_input_type]) -> Element: ...
347 def end(self, __tag: _parser_input_type) -> Element: ...
348
349 if sys.version_info >= (3, 8):
350 class C14NWriterTarget:
351 def __init__(
352 self,
353 write: Callable[[str], Any],
354 *,
355 with_comments: bool = ...,
356 strip_text: bool = ...,
357 rewrite_prefixes: bool = ...,
358 qname_aware_tags: Optional[Iterable[str]] = ...,
359 qname_aware_attrs: Optional[Iterable[str]] = ...,
360 exclude_attrs: Optional[Iterable[str]] = ...,
361 exclude_tags: Optional[Iterable[str]] = ...,
362 ) -> None: ...
363
364 class XMLParser:
365 parser: Any
366 target: Any
367 # TODO-what is entity used for???
368 entity: Any
369 version: str
370 if sys.version_info >= (3, 8):
371 def __init__(self, *, target: Any = ..., encoding: Optional[str] = ...) -> None: ...
372 else:
373 def __init__(self, html: int = ..., target: Any = ..., encoding: Optional[str] = ...) -> None: ...
374 def doctype(self, __name: str, __pubid: str, __system: str) -> None: ...
375 def close(self) -> Any: ...
376 def feed(self, __data: _parser_input_type) -> None: ...
377