[Docutils-develop] [docutils:patches] #210 Typing and `docutils.nodes.Node`

[Adam T. <aa-...@us...>]

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -2,7 +2,7 @@
 
 As I noted in commit [r9813] which added type hints:
 
-```
+```text
 Add type hints to ``docutils.nodes``
 
 A significant number of parameters and attributes are typed as

~~~~




---

**[patches:#210] Typing and `docutils.nodes.Node`**

**Status:** open
**Group:** None
**Created:** Thu Aug 15, 2024 08:38 AM UTC by Adam  Turner
**Last Updated:** Thu Aug 15, 2024 08:38 AM UTC
**Owner:** nobody


Commit [r9901] by @milde changes instances of `Element | Text` to `Node`, and adds attributes to `Node`. I think that this is a not the best and the commit should be reverted before the impending 0.22 release, to allow for more discussion.

As I noted in commit [r9813] which added type hints:

```text
Add type hints to ``docutils.nodes``

A significant number of parameters and attributes are typed as
expecting or yielding ``Element | Text`` rather than ``Node``,
which is the more obvious choice. This union type is used because
``Node`` is de facto an abstract base class --- it should not
be used or instantiated. Notably, ``Node.children`` is not defined,
``Node.attributes`` does not exist, etc. The two direct subclasses
fill in many of these missing pieces, making static typing both
more precise and easier.
```

``Element`` and ``Text`` are different types, as `Text` can be treated as a string and `Element` means that we have a concrete node type with attributes and data. Conflating these as `Node` is unhelpful, and we shouldn't signal to users that a `Node` is expected anywhere, as whilst is is *de facto* an abstract base class, it can be instantiated and used at runtime, which should be heavily discouraged.

Aside from verbosity, I'm unsure of the argument to change this. Verbosity can be managed with a type alias, as we had previously used (`ElementT`, though this should perhaps be named `ElementOrText`).

A


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.