[ahopkins]

The goal of this PR is to come up with a nicer API for assigning HTML id and class attributes that clash with Python syntax. One approach is to overload the __getitem__ method to allow for this:

from html5tagger import Document

doc = Document("Test")
doc.div["#some-id.one.two.three[href=/some/path][another='foo bar']"]

print(str(doc))

<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<div id="some-id" href="/some/path" another="foo bar" class="one two three"></div>

There are a few considerations:

1. Whether the value passed to __getitem__ should be a single string, or a tuple of strings: ["#id", "class", ...]
2. Whether the values (particularly class names) should be dot (.) prepended: .one.two.three v one two three
3. Whether arbitrary attributes should be supported in this pattern

The implementation I proposed answers these as by opting for a single string that follows CSS-style selector. While potentially we could go with #some-id one two three and just check the first character for a #, in which case we pop off the one value, this pattern was not chosen because it then means that this lib would be introducing a new pattern that is not found in HTML.

Alternatively, we could have multiple values builder["#some-id","one two three"]. While this is valid Python, it is a bit awkward (granted, any overload of __getitem__ is certainly non-standard).

Finally, assuming "#some-id.one.two.three" is preferred over "#some-id one two three", the next logical question is why not arbitrary attribute assignment with [foo=bar] style syntax.

As a side benefit, it would allow a data-foo_bar=thing attribute, if that is desired.

[Tronic]

Looks good. Neat how compact & fast implementation you got for this.

Remaining considerations: should we catch/handle if the same attributes are defined as kwargs too (I believe now you get another attribute by the same name in HTML)? Possibly even restructure html5tagger such that the whole opening tag is written at once instead of appending attributes to HTML snippet the way it currently does.

[Tronic]

Needs README update I guess, but is there anything else stopping this from merging?

[CiberNin]

data-foo_bar=thing is a requirement for my use case (datastar uses attrs of that style)

[Tronic]

data-foo_bar=thing is a requirement for my use case (datastar uses attrs of that style)

Removed mangling from CSS syntax, so this will work as you wanted.

[Copilot]

Pull request overview

This PR introduces a CSS-selector-inspired API for setting HTML attributes that are awkward to express as Python keyword arguments (notably id and class), by overloading Builder.__getitem__ to accept selector strings like #id, .class, and [attr=value].

Changes:

• Add Builder.__getitem__ parsing for #id, .class, and [attr[=value]] selector fragments (including chaining).
• Add classes= kwarg support to append to an existing class attribute while preserving attribute ordering.
• Add extensive tests and README documentation for the new selector/classes= behaviors.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
html5tagger/builder.py	Implements CSS-selector [] attribute assignment and classes= class-appending behavior.
html5tagger/util.py	Refactors attribute value escaping into escape_attr_value() and extends attributes() to optionally skip name mangling.
tests/test_html5tagger.py	Adds tests covering selector parsing, attribute emission, chaining, and classes= append semantics.
README.md	Documents the new selector-style attribute assignment and classes= usage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.