I like!

[OleJoik]

I've been playing around building some very similar lib. Used some different python tricks to get similar syntax, but instead of the getitem trick, used overloaded functions that sometimes returned another function, other times just a node. This is the working syntax:

div(class_="bg-red")(
  p(class_="text-4x")("Hello"),
  a(href="/get")("click me!"),
)

This was also valid (without attrs)

div(
  p("Hello")
)

I like your approach (better) and will play around with it.

Way to go!

[pelme]

Very nice! I agree, the [] syntax makes a big difference when reading the code. Let me know if you have other suggestions/improvements. Especially when it comes to documentation, I think that is probably almost as important as the library itself to get the idea across :)

[OleJoik]

I have spent some time playing with it, and I must say, I am very happy with it, and want to keep using it as is. But I have a couple of things that I might mention, some suggestions and comments. If you want I can suggest some implementation/bring PR for any of these. The utility functions I already played around with implementing, so I will submit a PR for that anyway.

Documentation

In general I think it is quite sufficient for me, but ofcourse, I was already onto something similar, and thus didn't need a whole lot of documentation to "get the point". Yet, I did note a couple of points/thoughts recarding the docs:

• div(...)[...] syntax: This is obviously part of the charm of this library. But even for someone having written quite a bit of python, what is actually going on here was quite confusing for me at first, and was almost off-putting for the first few seconds looking at the syntax. I was like "what the actual f..." is going on with that. For me personally, it was quite interesting to read the source and figure how that actually works. I would suggest adding some simple explanation about how to reason about the syntax - both how paranthesis and square paranthesis works and behaves - maybe on the first part of the readme.
• While I think the # and . shorthands for ids and classes sure can be useful, I generally still prefer to use the syntax which more similarly resembles "pure html", thus the id=... and class_=... key word arguments. I would personally have used that on the main readme example instead of the shorthand syntax. But this is a matter of taste I guess. I was looking for something very minimal, and this is kind of ease of use utilites that I personally wasnt looking for.
• In some situations it wasn't super clear to me how and when a _ postfix was necessary for attributes. Although the docs are quite clear regarding class_ and for_, I still ran into some confusion when trying to use other key word arguments such as the type attribute (typically used for buttons and inputs, for example). This SO question seems to suggest that using type as a keyword arg is concidered bad practice. I noticed that using both type= and type_= kwargs works fine in htpy, but maybe the docs should recommend the latter alternative in this specific case.

Suggestions

if_ and for_ / map_ utilities

In my light version, one of the first things I implemented was utility functions for conditional rendering and looping. I wanted the syntax to be more similar to what you might do in tsx/jsx, to make it more approachable for my non-pythonista collegues. Don't generally like the suggested syntax from the docs, eg. print(div[error and b[error]]) although again, its a matter of taste I guess.

The syntax I implemented was this:

if_(True)(
    p("This is rendered")
)

if_(False)(
    p("This is not rendered")
)

ul(
    map("Cat", "Dog", "Horse")(
        lambda animal: li(animal)
    )
)

I realize at this point that I am kind of a hypocrite, because in the previous section I didn't want utilities, and now I do. Well, again, a matter of taste I guess. I was playing around with this today, and have an implementation using this syntax in htpy. I don't know if you like it, or if you prefer map over for for the looping util. Or if you want one and not the other. Anyway, I will bring a PR for this and you can think about it.

if_(True)[
    p("This is rendered")
]

if_(False)[
    p("This is not rendered")
]

ul[
    for_(["Cat", "Dog", "Horse"], lambda animal: li[animal])
]

Type hints for attrs

MDN web docs contains a list of html attributes for various elements. I was thinking about writing some kind of python documentation for various types of elements, which might make it somewhat easier to use python tooling to get suggestions about common kwargs that is recommended for any given element. This was actually fairly easy to implement (although a bit of work...) using my old implementation, and at the moment its not clear for me what the best route would be to add these to htpy. This is not very important either. Anyway, I can look into it and bring a PR if you want.

[OleJoik]

Another comment I forgot to mention:

Other stringifyable types as children

print(p[5])

The type checker screams at me, and it doesn't run

Here I think the expected behaviour should have been <p>5</p>

I will look into this one and see if I can make more specific suggestions for how to approach it

[pelme]

Every object on python can have str() applied to it and it will not throw an error. For ints it is annoying since it has a sane str(). There is unfortunately no way to distinguish objects with useful end user str representation (like int str(5) -> "5") and those that return a repl style string (like list str([1, 2, 3]) -> "'[1, 2, 3]". It is annoying to accidentally output repr style strings.

So if any object was allowed, things like this would instead not have the type checker scream at you:

my_nums = [1, 2, 3]
print(p[my_nums])

I find this frustrating but just the way Python works. I would have loved if object did not define __str__ (but still had __repr__!). Then class StringLike(typing.Protocol): def __str__(self) -> str: ... would be useful and could have been used in this scenario. However, I do not see object dropping str any time soon so I think we are stuck with this. 😆

I feel that the inconvenience of explicitly forcing a object to string with str() was worth it over the alternative.

[OleJoik]

I agree, probably would be quite annoying to have some weird object be output. I havent checked, but maybe it could be possible to use some type alias or scoped type var to allow (and automatically stringify) a subset of objects of known "sane" str(), particularly for numbers. I feel like that one could come up quite often. However, I agree calling str() every now and then is not the end of the world

[pelme]

Thanks a lot for taking the time to write down the ideas/suggestions!

I have spent some time playing with it, and I must say, I am very happy with it, and want to keep using it as is. But I have a couple of things that I might mention, some suggestions and comments. If you want I can suggest some implementation/bring PR for any of these. The utility functions I already played around with implementing, so I will submit a PR for that anyway.

That's great to hear! :)

• div(...)[...] syntax: This is obviously part of the charm of this library. But even for someone having written quite a bit of python, what is actually going on here was quite confusing for me at first, and was almost off-putting for the first few seconds looking at the syntax. I was like "what the actual f..." is going on with that. For me personally, it was quite interesting to read the source and figure how that actually works. I would suggest adding some simple explanation about how to reason about the syntax - both how paranthesis and square paranthesis works and behaves - maybe on the first part of the readme.

Very much agree! Feel free to send a PR if you have something in mind, otherwise I will add that when I get around to it.

• While I think the # and . shorthands for ids and classes sure can be useful, I generally still prefer to use the syntax which more similarly resembles "pure html", thus the id=... and class_=... key word arguments. I would personally have used that on the main readme example instead of the shorthand syntax. But this is a matter of taste I guess. I was looking for something very minimal, and this is kind of ease of use utilites that I personally wasnt looking for.

We use this syntax extensively in our code base and find it succinct and nice but yes, it is a matter of taste. Will think about the first example, it may be too much to use it there since it may not be obvious how it works and could be off putting. Regular attributes are probably clearer to show of there.

• In some situations it wasn't super clear to me how and when a _ postfix was necessary for attributes. Although the docs are quite clear regarding class_ and for_, I still ran into some confusion when trying to use other key word arguments such as the type attribute (typically used for buttons and inputs, for example). This SO question seems to suggest that using type as a keyword arg is concidered bad practice. I noticed that using both type= and type_= kwargs works fine in htpy, but maybe the docs should recommend the latter alternative in this specific case.

Good point. I think it is generally a bad idea to shadow builtins but that it is fine in this particular case. This is only a potential problem in the implementation of the function, not for the caller. In the case of htpy it is fine since we only deal with **kwargs so it is not possible for the names to collide. If anything, I would rather lean the other way to only allow _ suffix for actual keywords. Maybe https://docs.python.org/3/library/keyword.html#keyword.iskeyword could be used. I think input(type="email") is better than input(type="email"). I would love if the python parser allowed for div(class="foo") btw.

Suggestions

I realize at this point that I am kind of a hypocrite, because in the previous section I didn't want utilities, and now I do. Well, again, a matter of taste I guess. I was playing around with this today, and have an implementation using this syntax in htpy. I don't know if you like it, or if you prefer map over for for the looping util. Or if you want one and not the other. Anyway, I will bring a PR for this and you can think about it.

Pythons inline if still read backwards to me and it looks better in JS just because of the ordering. I am not keen on including these in htpy since it feels out of scope to introduce new custom control flow functions. I think htpy should not make decisions about control flow but anyone is free to use their own helpers for this. I tried to express this at https://htpy.dev/#philosophy - the idea is to just use Python. I would maybe have used another syntax for Python inline if it was up to me but we are kind of stuck with it now for good or worse and I think it is better to stick to it.

ul[
    for_(["Cat", "Dog", "Horse"], lambda animal: li[animal])
]

Did you consider Python builtin map? https://docs.python.org/3/library/functions.html#map

ul[
    map(lambda animal: li[animal], ["Cat", "Dog", "Horse"])
]

MDN web docs contains a list of html attributes for various elements. I was thinking about writing some kind of python documentation for various types of elements, which might make it somewhat easier to use python tooling to get suggestions about common kwargs that is recommended for any given element. This was actually fairly easy to implement (although a bit of work...) using my old implementation, and at the moment its not clear for me what the best route would be to add these to htpy. This is not very important either. Anyway, I can look into it and bring a PR if you want.

This would be interesting if it was possible. But I am also not overly concerned about typing elements/attributes according to the HTML spec. Custom elements is a thing and people (ab)use custom attributes for so many things typing them is impossible. In our company we are heavy users of custom elements, Shoelace, Alpine.js and htmx. Restricting allowed element names/attributes would not be helpful and trying to add types would also be very hard. That said, ff it was possible to add typed attributes in useful way, that would be great!

[OleJoik]

• div(...)[...] syntax: This is obviously part of the charm of this library. But even for someone having written quite a bit of python, what is actually going on here was quite confusing for me at first, and was almost off-putting for the first few seconds looking at the syntax. I was like "what the actual f..." is going on with that. For me personally, it was quite interesting to read the source and figure how that actually works. I would suggest adding some simple explanation about how to reason about the syntax - both how paranthesis and square paranthesis works and behaves - maybe on the first part of the readme.

Very much agree! Feel free to send a PR if you have something in mind, otherwise I will add that when I get around to it.

I will bring a suggestion!

If anything, I would rather lean the other way to only allow _ suffix for actual keywords. Maybe https://docs.python.org/3/library/keyword.html#keyword.iskeyword could be used.

I think it might make it more difficult for the user if they didn't know all the keywords by heart, that it sometimes would work to use an _, sometimes not, but I get your point. Maybe status quo isn't too bad in the end.

Did you consider Python builtin map? https://docs.python.org/3/library/functions.html#map

ul[
    map(lambda animal: li[animal], ["Cat", "Dog", "Horse"])
]

Actually no, I haven't actually used it, have made my own utilities for this kind of stuff. Thank you for bringing it to my attention, useful.

For this particular purpose, it feels a bit backward to me though. Its the same with the list comprehension/for loops in python. I would prefer if the iterable came first and the callback after.

[...] Restricting allowed element names/attributes would not be helpful and trying to add types would also be very hard. That said, ff it was possible to add typed attributes in useful way, that would be great!

I will look into this one a bit at some point

[pelme]

I think it might make it more difficult for the user if they didn't know all the keywords by heart, that it sometimes would work to use an _, sometimes not, but I get your point. Maybe status quo isn't too bad in the end.

There is no need to put a _ at the end unless you get a syntax error then. But yeah, it is probably better as is right now to just always strip a single trailing _ :)