Types-lxml

Breaking changes and features
- `bytearray` accepted as tag names, attribute names and attribute values
- Related change: create `_TextArg` type alias to slowly replace existing `_AnyStr` (71)
- Warn IDE users via `warnings.deprecated` about exception upon certain argument combinations in HTML link functions

Bug fixes
- Property deleter missing for HTML elements (73)
- `etree.strip_attributes()` support `bytes` and `QName` as input
- Completion of 64 for remaining known cases
- Corrected link replacement function return type in `html.rewrite_links()`
- `etree.canonicalize()` shouldn't accept `bytes` as input

Tests related
- Use [`hypothesis`](https://hypothesis.readthedocs.io/) for extensive tests on function arguments, currently used in `_Attrib` and HTML link function tests (#75)
- `reveal_type()` injector has been splitted into [its own project](https://github.com/abelcheung/pytest-revealtype-injector) and pulled via dependency

Internal changes
- Folder structure changes for the whole repository (70)
- Remove `_HANDLE_FAILURES` type alias and show values directly to users
- Rename type-only protocol `SupportsLaxedItems` to `SupportsLaxItems`

----
**Full Changelog**: https://github.com/abelcheung/types-lxml/compare/2024.11.08...2024.12.13

Breaking and important changes


- `pyright` users (and IDE that can make use of `pyright`) will see warning if a single string is supplied where collection of string is expected (`tuple`, `set`, `list` etc). In terms of typing, a single `str` itself is valid as a `Sequence`, so type checkers normally would not raise alarm when using `str` in such function parameters, but can induce unexpected runtime behavior. ([64](https://github.com/abelcheung/types-lxml/issues/64))
- `_ElementTree.write()`, `etree.fromstringlist()`, `etree.tostring()`, `html.soupparser.fromstring()`, `html.soupparser.parse()`
- It is possible to verify release files indeed come from GitHub and not maliciously altered. See [Release file attestation](README.mdrelease-file-attestation) for detail.
- Runtime tests support comparing with `mypy` results, therefore officially making static stub tests obsolete


Bug fixes

- Element tag names, attribute names and attribute values support `bytearray`. This is discovered via `hypothesis` testing, which is intended to be utilized in next release
- Compatibility with `pyright ⩾ 1.1.378`, which imposes additional overload warning for `etree.iterparse()`
- Use relative import in `lxml.ElementInclude`, otherwise `mypy` triggers `--install-type` behavior.
- `ObjectifiedElement` `__getitem()__` and `__setitem()__` should accept `str` as key, which behaves mostly like `__getattr__()` and `__setattr__()`. That means, `elem["foo"]` is equivalent to `elem.foo` for non-repeating subelements.

fixes for etree submodule

- `_Element.tag` property is not just a `str`. It is `str` after initial document or string parsing, but can be set manually to any type supported by tag name and returns the same object.
- When `QName` is initialized with first argument set to `None`, `_Element` can be used as second argument (which is promoted to first argument in implementation)
- Relax single argument usage in `_Element.iter*()` method family, doesn't need `tag=` keyword when argument is `None`
- `FunctionNamespace()` should generate an `_XPathFunctionNamespaceRegistry` object, not its superclass
- For [decorator usage](https://lxml.de/element_classes.html#implementing-namespaces-1) of `_XPathFunctionNamespaceRegistry` and `_ClassNamespaceRegistry`, decorator signature included an extraneous argument, though it doesn't affect any existing correct usage.
- `indent()` first parameter has wrong name

fixes for html submodule

- `soupparser.parse()` should accept `pathlib.Path` object as input
- `.value` property of `SelectElement` can't be set to `bytes`
- `.action` property of `FormElement` can have a value of `None`, and can be set to `None`. They have different meanings though.

Small and internal changes

- Declare python 3.13 support and perform CI tests.
- Separation of `pyright` and `mypy` ignore comments: in previous releases ` type: ignore[code]` was enabled in `pyright` settings. Now it only uses ` pyright: ignore[code]` so `mypy` comment won't affect `pyright` behavior.
- Add `._name` property to `html.FormElement` for form name
- Eliminate `typing.TypeAlias` usage ([declared obsolete](https://docs.python.org/3/library/typing.html#deprecation-timeline-of-major-features), and we can do without it)

Test related changes

- Stub tests migration to runtime:
- Most of remaining `etree._Element` methods, now only `.makeelement()` and `.xpath()` left in stub test
- Runtime test additions:
- `ElementNamespaceClassLookup()`
- `tox` config migrated to `pyproject.toml`, thus requiring `tox ⩾ 4.22`
- Runtime tests are now executed within `test-rt` folder due to python/mypy8400
- Some tests need to be performed conditionally when multi-subclass patch is applied
- Some tests or syntaxes need to be turned off to cope with `mypy` deficiencies
- Usage of [Rust-based `uv`](https://docs.astral.sh/uv/) as well as [related `tox` plugin](https://github.com/tox-dev/tox-uv) to speed up test environment recreation
- Don't force users installing [`tox-gh-actions`](https://github.com/ymyzk/tox-gh-actions) when checkout out repository, it is only useful for GitHub workflows

Docstring additions

- `etree` submodule: `parse()`, `fromstringlist()`, `tostring()`, `indent()`, `iselement()`, `adopt_external_document()`, `DocInfo` properties, `QName`, `CData`, some exception classes
- `html.soupparser` submodule: `fromstring()`, `parse()`, `convert_tree()`

Bug fix and small changes
================

- Namespace argument in Elementpath methods should allow `None` (60 thanks to cukiernick)

Internal changes
==========

- Perform runtime tests against `lxml 5.3`

Breaking changes
===========

- Multiple builds available, with the alternative build enhancing multiple XML subclassing scenario. See [relevant README section](https://github.com/abelcheung/types-lxml#choosing-the-build) for detail. Thanks to scanny for the driving force behind [51](https://github.com/abelcheung/types-lxml/issues/51).
- `Mypy` 1.11 required, which introduced backward incompatible `typing.overload` changes.
- `lxml.html.clean` stub depreated, `lxml 5.2.0` completely removes the submodule due to multiple security issues. Corresponding code and type definitions are split into a [new independent repo](https://github.com/fedora-python/lxml_html_clean).

Features
=====

- ([56](https://github.com/abelcheung/types-lxml/issues/56)) Replace `typing.TypeGuard` with `typing.TypeIs`
- Use [callback protocol](https://github.com/python/typing/discussions/1432) for more precise element and `ElementMaker` factory function typing
- `lxml.etree.ICONV_COMPILED_VERSION` exported since `5.2.2`
- Special handling for `ObjectifiedElement` and `HTMLElement` in `lxml.cssselect.CSSSelector` and various `cssselect()` methods
- `html.builder` shorthands return more precise element type for certain HTML elements. For example, `html.builder.LABEL()`, corresponding to `<LABEL>` tag, yields `LabelElement`.
- More precise `etree.Extension()` annotation depending on supplied namespace
- Stricter namespace argument type in `_Element` ElementPath methods
- For `lxml.builder.ElementMaker` class:
- Provide better hint in `__call__()` argument
- Accepts namespace tuple in `nsmap` argument
- Export private properties
- For `lxml.sax` module:
- Export private properties in various classes
- Explicitly list all inherited methods in `ElementTreeContentHandler` class, as method arguments names are different from superclass ones
- Alert `etree.HTMLParser` users to remove deprecated `strip_cdata` argument

Bug fix and small changes
================

- Some `_Element` related input arguments fixed to use `typing.Sequence` instead of `Interable`, as `_Element` is already an `Iterable` itself. Supplying `_Element` where a proper `Iterable` is expected would cause problem.
- Similar situation arises for `str` or `byte` in tag selector argument; use `typing.Collection` to alert user more clearly.
- `None` can't be used as `etree.strip_*()` argument
- Some `etree.DocInfo` read-only properties can't be `None`
- Fix `etree.Resolver` method return types
- Avoid exception raising arg combinations in `html.html5parser.HTMLParser`

Internal changes
==========

- The usual static stub to runtime test migration:
- Part of basic `_Element` tests and its `find*()` methods
- More extensive `_Attrib` tests
- Use [`ruff`](https://docs.astral.sh/ruff/) to replace [`black`](https://black.readthedocs.io/en/stable/) and [`isort`](https://pycqa.github.io/isort/) as code formatter
- Migrate stub tests to support `pytest-mypy-plugins ⩾ 2.0`
- Use [`pdm-backend`](https://backend.pdm-project.org/) as build backend due to its more versatile versioning support

Breaking changes
===========

- `Mypy` 1.9 is required, dropping 1.5 support. 1.6 - 1.8 was never supported.
- `lxml.ElementInclude` completely reworked

Features
=====

- PEP 696 support, simplifying usage of some subscripted types (42)
- As a convenient side effect, `lxml.html` parser constructor signatures can be removed
- All annotations do provide default values in their signatures now instead of `...`

Bug fix and small changes
================

- Type of `_Comment.text` property (and those of similar elements) is always `str` (46, thanks to eemeli)
- Tag selector argument in element iterator methods should support keyword with a single tag (45, thanks to eemeli)
- `html.fragments_fromstring()` should receive same fix as `html.html5parser.fragments_fromstring()` do (43, thanks to Wuestengecko)
- `overload` for `etree.SubElement()` on handling of `HtmlElement` and `ObjectifiedElement`
- Some exported constants were missing from `lxml.ElementInclude` stub
- `html.soupparser` module functions return type depends on `makeelement` argument
- Keyword arguments in `html.soupparser` module functions are explicitly listed now (instead of generic `**kwargs` before)
- The 2 arguments in `html.diff.html_annotate()` should align their annotation types
- `html.submit_form()` return type depends on the result of `open_http` function argument
- Add missing exported variable for `lxml.isoschematron`
- Uppercase variants of output method arguments ("HTML", "TEXT", "XML") were dropped

Internal changes
==========

- Usual runtime test additions: `lxml.html.soupparser`, `lxml.ElementInclude`, various exported constants
- Runtime tests also do test against lxml 5.2

Breaking change

- Requires `cssselect ⩾ 1.2` for annotation in `lxml.cssselect`, since `cssselect` is now inline annotated.

Bug fix and small changes

- Compatibility with `pyright ⩾ 1.1.353`
- In `etree.clean_*` functions, first argument (the Element or ElementTree to be processed) must be strictly positional
- `etree._LogEntry.filename` property is never empty, as it uses the value `<string>` as fallback
- `etree._BaseErrorLog.receive()` argument name was wrong
- Self brewed `SupportsReadClose` protocol dropped, replacing with more standardized `SupportsRead`
- `html.html5parser.parse()` should support data stream as input
- `html.html5parser.fragments_fromstring()` return type is dependent on `no_leading_text` argument
- `encoding` arguments in various methods / functions used to only support ASCII and UTF-8 as byte encodings, now the restriction is lifted
- Place some `typing` usage under python version check (`if sys.version_info >= (3, x)`)
- `etree.PyErrorLog` constructor shouldn't accept 2 logger arguments simultaneously
- `etree.PyErrorLog.level_map` property reverted to vanilla type (`int`) instead of our fake `enum`

Internal changes

- Some runtime tests are lxml version dependent ([34](https://github.com/abelcheung/types-lxml/issues/34), thanks to fabaff)
- Adds stub check for `_Element`, `_Comment` and `_ElementTree` ([33](https://github.com/abelcheung/types-lxml/issues/33), thanks to udifuchs)
- Following stub tests migrated to runtime: `_Attrib`, `_ErrorLog` and friends, `html5lib`