How should I think about nanobind enums?

[oremanj]

There isn't much documentation about the detailed semantics of nb::enum_s, and it's pretty different from pybind11 enums. I've made some changes to add missing functionality, which I'd like to upstream, but before I go that route, I'm wondering what the intended mental model for a nb::enum_ is. Is the goal to mimic Python enum.Enum? Mimic C++? Why is there a separate nb_enum metaclass but it doesn't add anything to the type object? Is there some future expansion planned there?

[wjakob]

The nb_enum metaclass is a relic of an earlier implementation. I've just committed a change to master that will remove it in an upcoming release. Other than that, it is designed to be similar to a C++ enum. I am open to suggestions, though there are practical constraints on what can be changed due to the semantic versioning policy. Perhaps it's best to discuss here before upstreaming changes.

[wjakob]

Also worth mentioning: a difference between pybind11 and nanobind is that the former generally leaks everything (instances, type objects, functions) related to enums. nanobind is strict about catching leaks and needs some extra code to ensure an orderly cleanup.

[oremanj]

The things I've noticed so far are:

• Enumerators don't have name and value attributes (differs from pybind and enum.Enum)
• Enumerators of different types are comparable with each other based on their integer values, even without is_arithmetic (differs from pybind for scoped enums, differs from enum.Enum, seems plausibly dangerous)
• ... but you still can't construct an enumerator with a value that isn't one of the named constants (differs from C++)

I think the name and value attributes can be added backward-compatibly, at least on enums that don't have enumerators called literally name or value.

Changing comparison semantics would be a breaking change, but also seems pretty important for type-safety! I would actually contend that the current behavior is a bug: since all enums with the same integral value have the same hash and also compare equal, you can't put two different enumerators (from different enums) in the same dict/set if they have the same value.

Allowing enum objects whose values aren't in the enumerated list is a larger change and might be out-of-scope (and I think nanobind's current enumerators-are-singletons semantics are a better fit for most enums in that respect anyway). I think it would not be too hard to provide a weak_enum that doesn't enforce that enumerators have known values; this is useful for strongly-typed bit flags and for binding the enum class SomeSpecificKindOfInt : int { Invalid = -1 }; newtype idiom. I'd be happy to upstream that if there's appetite, but it's also pretty easy to maintain out-of-tree.

It would also be nice to add pickle support. For most classes it's easy enough to write __getstate__ and __setstate__ methods, but nanobind's enums require __getnewargs__ which I think is rather less well-known.

Any interest in supporting syntax for looking up an enumerator by its name? EnumType["foo"] does this in python enums; we could also spell it EnumType("foo") since there's no ambiguity between name and value arguments (since C++ enums' values are always integral). getattr(EnumType, "foo") works in most cases but can get confused by descriptors (if you don't know in advance that the name is valid and are relying on catching an error).

I am happy to implement any and all of these, just want to seek consensus on the design first.

[wjakob]

Enumerators don't have name and value attributes (differs from pybind and enum.Enum)

I would be fine with adding those, if done compactly. It might be possible to reuse existing functionality or refactor parts of it as not to unnecessarily expand libnanobind.

Enumerators of different types are comparable with each other based on their integer values, even without is_arithmetic (differs from pybind for scoped enums, differs from enum.Enum, seems plausibly dangerous)

That's not good and something that should probably be forbidden. I think that can go in without considering it as a breaking change (I can't imagine somebody depending on that!)

... but you still can't construct an enumerator with a value that isn't one of the named constants (differs from C++)

I'd say it is out of scope for the enum binding class. If somebody wants such unusual behavior, they can make their own enumeration class as you suggest. That kind of code is easy to maintain out of tree.

It would also be nice to add pickle support. For most classes it's easy enough to write getstate and setstate methods, but nanobind's enums require getnewargs which I think is rather less well-known.

Indeed, I did not know this dunder method at all. It might be weird to add specialized pickle support to nb::enum_ though if there isn't a general solution for the base class (nb::class_). Maybe a separate thing to consider?

[oremanj]

I just noticed that enums aren't actually singletons if you return them from C++: (test_enum_ext is the module built from nanobind/tests/test_enum.cpp)

>>> lst = [test_enum_ext.to_enum(1) for _ in range(1000000)]
>>> len(set(id(v) for v in lst))
1000000
>>> all(v == lst[0] for v in lst[1:])
True
>>>

Similarly, you can create an invalid enum value (by returning it from C++) that will only sort of work in Python:

>>> invalid = test_enum_ext.to_enum(42)
>>> invalid
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: nb_enum: could not find entry!
>>> test_enum_ext.Enum(invalid)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: nb_enum: could not find entry!
>>> int(invalid)
42
>>> test_enum_ext.from_enum(invalid)
42
>>> invalid > 0
True

It seems like it would be good to normalize the behavior here, so enum values returned from C++ work like enum values constructed from Python. I would propose resolving this via something like:

• Defined enumerators are singletons, whether returned from C++ or constructed in Python.
• Undefined enumerators either create new objects or produce errors, selectable using an nb::enum_ constructor attribute. I guess this could be a three-option choice with "error from Python, OK from C++" as one of the choices, if you think the current behavior is plausibly being depended upon.

[wjakob]

I had not realized this. I think the former way is the right choice for nanobind. Users can easily make their own more powerful enum class to achieve such specialized behavior.

[wjakob]

After thinking more about it, I think this may have been intentional. One can avoid a (somewhat expensive) hashtable lookup when doing the C++->Python conversion with assumption that the binding developer isn't doing weird stuff (returning enum entries that the bindings aren't aware of). It may be preferable to raise an error only when the extension is compiled in debug mode.

[oremanj]

If we map enums returned from C++ to the canonical singleton object for their enumerator, then we're already doing the hashtable lookup and it's ~free to raise an error if that lookup fails.

If we don't map enums returned from C++ to the canonical singleton object for their enumerator, then what's the benefit of doing so when constructing enums from Python? It's no longer meaningfully limiting the number of enum objects that can be created, which is at least slightly important since they're GC-tracked.

[wjakob]

Yep -- sorry. What I meant is that "singleton representation" was not an official feature of the current implementation. It happens to use singletons on the Python -> C++ path because a hashtable lookup is needed and it is easy to then return a singleton, but I would consider this an implementation detail. The cost of creating and destroying GCed instances on the other path (C++->Python) is small because those aren't part of reference cycles (the type object doesn't link back to them, which means that they can be destroyed using normal reference counting operations). This could likely be documented better.

[wjakob]

(sorry about the confusion at the beginning, it's been quite a while since I wrote this code)

[rzhikharevich-wmt]

@wjakob Do you have objections against adding support for Python-style enum methods to nanobind enums, including metaclass methods such as __iter__, __getitem__, etc? I can make a PR for this.

[wjakob]

I think it could be useful, but I am hesitant to commit whether such a feature would be accepted. It depends on how complicated it ends up being.

[nurpax]

I happened to come across this thread and was wondering if it's ever been considered to allow for typing C++ enums as Python IntFlag enums? (there are more variants of this, picking this one up as an example). This seems like a handy and useful support-type for using with bit flags. For example:

class InputTextFlags(IntFlag):
    NONE                     = 0
    CHARS_DECIMAL            = 1 << 0
    CHARS_HEXADECIMAL        = 1 << 1
    CHARS_UPPERCASE          = 1 << 2
    CHARS_NO_BLANK           = 1 << 3
    AUTO_SELECT_ALL          = 1 << 4
    ENTER_RETURNS_TRUE       = 1 << 5
    CALLBACK_COMPLETION      = 1 << 6
    CALLBACK_HISTORY         = 1 << 7
    CALLBACK_ALWAYS          = 1 << 8
    CALLBACK_CHAR_FILTER     = 1 << 9
    ALLOW_TAB_INPUT          = 1 << 10
    CTRL_ENTER_FOR_NEW_LINE  = 1 << 11
    NO_HORIZONTAL_SCROLL     = 1 << 12
    ALWAYS_OVERWRITE         = 1 << 13
    READ_ONLY                = 1 << 14
    PASSWORD                 = 1 << 15
    NO_UNDO_REDO             = 1 << 16
    CHARS_SCIENTIFIC         = 1 << 17
    CALLBACK_RESIZE          = 1 << 18
    CALLBACK_EDIT            = 1 << 19
    ESCAPE_CLEARS_ALL        = 1 << 20

text_input('Input:', flags=InputTextFlags.NO_HORIZONTAL_SCROLL | InputTextFlags.CTRL_ENTER_FOR_NEW_LINE)

There's also an IntEnum for stuff that's not bit fields.

This seems to have useful functionality out of the box, like being able to do arithmetic on the enums.

But I'm not so experienced with Python bindings or nanobind that I could tell if using something like Python's enum IntFlag directly is possible or comes with a lot of downsides.