PySide-doc: Create some developer doc about enum features

This is the internal documentation of the flags that
can control the enum behavior at startup of a script.

Task-number: PYSIDE-1735
Change-Id: Ibe9653de04edf2b73ac199e2dad6f7ddf55716da
Pick-to: 6.3 6.4
Reviewed-by: Adrian Herrmann <[email protected]>
Reviewed-by: Venugopal Shivashankar <[email protected]>

1 files changed, 159 insertions, 0 deletions

diff --git a/sources/pyside6/doc/developer/enumfeatures_doc.rst b/sources/pyside6/doc/developer/enumfeatures_doc.rst
new file mode 100644
index 000000000..63535d5f2
--- /dev/null
+++ b/sources/pyside6/doc/developer/enumfeatures_doc.rst
@@ -0,0 +1,159 @@
+************************
+The Set of Enum Features
+************************
+
+The development of the new Python enums took the form of a series of patches.
+While we put a lot of effort into supporting the old Enums (without promoting
+them), it is still possible that someone has a case where they cannot use
+the Python enums as they are now. To avoid people setting the environment
+flag to disable this completely, we implemented a way to select each
+combination of enum functions step by step with a specific set of flags.
+
+
+The Possible Enum Flags
+=======================
+
+This is the table of all flags used to control the creation of Python enums.
+
+======================  =====  ======================================================
+Flag Name               Value
+======================  =====  ======================================================
+ENOPT_OLD_ENUM           0x00  (False) Disable new enums
+ENOPT_NEW_ENUM           0x01  (True) The default for PySide 6.4, full implementation
+ENOPT_INHERIT_INT        0x02  Turn all Enum into IntEnum and Flag into IntFlag
+ENOPT_GLOBAL_SHORTCUT    0x04  Re-add shortcuts for global enums
+ENOPT_SCOPED_SHORTCUT    0x08  Re-add shortcuts for scoped enums
+ENOPT_NO_FAKESHORTCUT    0x10  Don't fake rename (forgiveness mode)
+ENOPT_NO_FAKERENAMES     0x20  Don't fake shortcuts (forgiveness mode)
+ENOPT_NO_ZERODEFAULT     0x40  Don't use zero default (forgiveness mode)
+ENOPT_NO_MISSING         0x80  Don't allow missing values in Enum
+======================  =====  ======================================================
+
+Such a set of flags can be defined either by the environment variable
+``PYSIDE63_OPTION_PYTHON_ENUM`` or set by the Python variable
+``sys.pyside63_option_python_enum`` before PySide6 is imported.
+The environment variable also supports arbitrary integer expressions
+by using ``ast.literal_eval``.
+
+
+ENOPT_OLD_ENUM (0x00)
+---------------------
+
+This option completely disables the new enum implementation.
+Even though this is a valid option, we want to avoid it if possible.
+The goal is to eventually remove the old implementation. To make this
+possible, we have made the individual features of the enum implementation
+accessible as flags. This way, if users report problems, we may be able
+to provide a temporary solution before extending enum support accordingly.
+
+
+ENOPT_NEW_ENUM (0x01)
+---------------------
+
+In a perfect world, no one would choose anything other than this default
+setting. Unfortunately, reality is not always like that. That is why
+there are the following flags.
+
+
+The most likely flags needed
+============================
+
+If there are errors, they are likely to be the following: Either implicit
+assumptions are there that require IntEnum, or global enums are used that
+unfortunately cannot be replaced with tricks.
+
+
+ENOPT_INHERIT_INT (0x02)
+------------------------
+
+When this flag is set, all ``enum.Enum/enum.Flag`` classes are converted to
+``enum.IntEnum/enum.IntFlag``. This solves the most likely compatibility
+problem when switching to Python enums. The old Shiboken enums always
+inherit from int, but most Python enums do not.
+
+It was a decision of Python developers not to let enums inherit from int by
+default, since no order should be implied. In most cases, inheritance from
+int can be avoided, either by using the value property or better by
+uplifting: instead of using ``AnEnum.AnInstance.value`` in a function that
+expects an int argument, you can also convert the integer to an enumeration
+instance after the call by ``AnEnum(int_arg)`` and use that in comparisons.
+
+However, there are cases where this is not possible, and explicit support in
+PySide is simply not available. In those cases, you can use this flag as a
+workaround until we have implemented alternatives.
+
+
+ENOPT_GLOBAL_SHORTCUT (0x04)
+----------------------------
+
+At the beginning of the Python enum implementation, we continued to support
+the shortcut behavior of Shiboken enums: the enum constants were mirrored
+into the enclosing scope.
+This was later emulated in the course of forgiveness mode. For enum classes
+in a PySide class this works fine, but for enum classes directly on the module
+level there is no good way to implement forgiveness.
+
+It is unlikely that errors are hidden for global enums, because they should
+already produce an error during import. But for cases without access to
+the source code, you can help yourself with this flag.
+
+A flag value of 0x6 is likely to solve the majority of problems.
+
+
+Flags for completeness
+======================
+
+The following flags complement the description of Python Enums.
+They essentially serve the better understanding of the
+implementation and make it fully transparent and customizable.
+
+
+ENOPT_SCOPED_SHORTCUT (0x08)
+----------------------------
+
+For completeness, we also supported mirroring scoped enums, although this
+has since been replaced by forgiveness mode. If you want to try this,
+please also use the ENOPT_NO_FAKESHORTCUT flag (0x10), otherwise the
+effect of this flag will remain invisible.
+
+
+ENOPT_NO_FAKERENAMES (0x10)
+---------------------------
+
+Forgiveness mode emulates renaming ``Enum.Flag`` classes back to Shiboken
+QFlags structures, which have slightly different names.
+So when such a defunct name is used, the system replaces it internally
+with the new ``enum.Flag`` structure. Unless special boundary problems
+are provoked, this replacement should work.
+
+To see the effect of this renaming, you can turn it off with this flag.
+
+
+ENOPT_NO_ZERODEFAULT (0x40)
+---------------------------
+
+As part of the forgiveness mode, Python enums can be created by a
+parameterless call, although Python enums actually force a parameter
+when called.
+
+The effect can be examined if this flag is set to disable it.
+
+
+ENOPT_NO_MISSING (0x80)
+-----------------------
+
+There are a few cases where Shiboken enums use missing values. In
+``enum.Flag`` structures, this is allowed anyway because we have set the
+``FlagBoundary.KEEP`` flag (see ``enum.py``).
+
+Normal ``enum.Enum`` structures don't have this provision, but the
+``enum`` module allows to pass a ``_missing_`` function for customization.
+
+Our way of dealing with this situation is to create a new fake
+``enum.Enum`` class with the same name and a nameless instance, and
+pretend with an attribute setting that it has the same type.
+The additional instances created in this way are recorded in a class dict
+``_sbk_missing_`` in order to preserve their identity.
+
+You will see the effect of not defining a ``_missing_`` function if you
+set this flag.