Added flag enums support

docs/changelog/fragments/197.feature.rst

@@ -0,0 +1,4 @@
+Added flags support
+
+Now adaptix has two different ways to process flags: :func:`.flag_by_exact_value` (by default)
+and :func:`.flag_by_member_names`.

docs/loading-and-dumping/specific-types-behavior.rst

@@ -112,7 +112,18 @@ timedelta
 Loader accepts instance of ``int``, ``float`` or ``Decimal`` representing seconds,
 dumper serialize value via ``total_seconds`` method.
 
-Enum subclasses
+
+Flag subclasses
+'''''''''''''''''''''''
+
+Flag members by default are represented by their value. Note that flags with skipped
+bits and negative values are not supported, so it is highly recommended to define flag
+values via enum.auto() instead of manually specifying them.
+Besides, adaptix provides another way to process flags: by list using their names.
+See: :func:`.flag_by_member_names` for details.
+
+
+Other Enum subclasses
 '''''''''''''''''''''''
 
 Enum members are represented by their value without any conversion.

src/adaptix/__init__.py

@@ -14,7 +14,7 @@
     enum_by_name,
     enum_by_value,
     flag_by_exact_value,
-    flag_by_list_using_name,
+    flag_by_member_names,
     loader,
     name_mapping,
     validator,
@@ -62,7 +62,7 @@
     'enum_by_name',
     'enum_by_value',
     'flag_by_exact_value',
-    'flag_by_list_using_name',
+    'flag_by_member_names',
     'name_mapping',
     'default_dict',
     'AdornedRetort',

src/adaptix/_internal/morphing/facade/provider.py

@@ -359,6 +359,8 @@ def enum_by_value(first_pred: EnumPred, /, *preds: EnumPred, tp: TypeHint) -> Pr
 
 def flag_by_exact_value(*preds: EnumPred) -> Provider:
     """Provider that represents flag members to the outside world by their value without any processing.
+    It does not support flags with skipped bits and negative values (it is recommended to use enum.auto() to define flag
+    values instead of manually specifying them).
 
     :param preds: Predicates specifying where the provider should be used.
         The provider will be applied if any predicates meet the conditions,
@@ -369,28 +371,37 @@ def flag_by_exact_value(*preds: EnumPred) -> Provider:
     return _wrap_enum_provider(preds, FlagByExactValueProvider())
 
 
-def flag_by_list_using_name(
+def flag_by_member_names(
     *preds: EnumPred,
     allow_single_value: bool = False,
     allow_duplicates: bool = True,
     allow_compound: bool = True,
     name_style: Optional[NameStyle] = None,
     map: Optional[Mapping[Union[str, Enum], str]] = None  # noqa: A002
 ) -> Provider:
-    """Provider that represents flag members to the outside world by their name.
+    """Provider that represents flag members to the outside world by list of their names.
+
+    Loader takes a flag members name list and returns united flag member
+    (given members combined by operator ``|``, namely `bitwise or`).
+
+    Dumper takes a flag member and returns a list of names of flag members, included in the given flag member.
 
     :param preds: Predicates specifying where the provider should be used.
         The provider will be applied if any predicates meet the conditions,
         if no predicates are passed, the provider will be used for all Flags.
         See :ref:`predicate-system` for details.
-    :param allow_single_value: Specifies if it is allowed to call loader by single value.
-        If it is allowed and loader called by single value, it will be interpreted as a list with single element.
-    :param allow_duplicates: Specifies if it is allowed to call loader by list with non-unique elements.
-        If it is not allowed and loader by list with non-unique elements, ValueError will be raised.
-    :param allow_compound: Specifies if it is allowed for loader to accept compound values and
-        if it is allowed for dumper to return compound values.
-    :param name_style: Name style that represents values to the outside world
-    :param map: Mapping for values to represent them to the outside world
+    :param allow_single_value: Allows calling the loader with a single value.
+        If this is allowed, singlular values are treated as one element list.
+    :param allow_duplicates: Allows calling the loader with a list containing non-unique elements.
+        Unless this is allowed, loader will raise :exc:`.DuplicatedValues` in that case.
+    :param allow_compound: Allows the loader to accept names of compound members
+        (e.g. ``WHITE = RED | GREEN | BLUE``) and the dumper to return names of compound members.
+        If this is allowed, dumper will use compound members names to serialize value.
+    :param name_style: Name style for representing members to the outside world.
+        If it is set, the provider will automatically convert the names of all flag members to the specified convention.
+    :param map: Mapping for representing members to the outside world.
+        If it is set, the provider will use it to rename members individually;
+        its keys can either be member names as strings or member instances.
     :return: desired provider
     """
     return _wrap_enum_provider(

src/adaptix/load_error.py

@@ -2,14 +2,17 @@
     AggregateLoadError,
     BadVariantError,
     DatetimeFormatMismatch,
+    DuplicatedValues,
     ExcludedTypeLoadError,
     ExtraFieldsError,
     ExtraItemsError,
     LoadError,
     LoadExceptionGroup,
     MsgError,
+    MultipleBadVariant,
     NoRequiredFieldsError,
     NoRequiredItemsError,
+    OutOfRange,
     TypeLoadError,
     UnionLoadError,
     ValidationError,
@@ -32,4 +35,7 @@
     'ValidationError',
     'BadVariantError',
     'DatetimeFormatMismatch',
+    'DuplicatedValues',
+    'OutOfRange',
+    'MultipleBadVariant'
 )

tests/unit/morphing/test_enum_provider.py

@@ -11,7 +11,7 @@
     Retort,
     dumper,
     enum_by_value,
-    flag_by_list_using_name,
+    flag_by_member_names,
     loader,
 )
 from adaptix._internal.morphing.enum_provider import EnumExactValueProvider, EnumNameProvider
@@ -262,7 +262,7 @@ def test_flag_by_list_using_name(
         strict_coercion=strict_coercion,
         debug_trail=debug_trail,
         recipe=[
-            flag_by_list_using_name(
+            flag_by_member_names(
                 allow_single_value=allow_single_value,
                 allow_duplicates=allow_duplicates,
                 allow_compound=allow_compound
@@ -331,7 +331,7 @@ def test_flag_by_list_using_name_with_bad_types(
         strict_coercion=strict_coercion,
         debug_trail=debug_trail,
         recipe=[
-            flag_by_list_using_name(
+            flag_by_member_names(
                 allow_single_value=allow_single_value,
                 allow_duplicates=allow_duplicates,
                 allow_compound=allow_compound
@@ -369,7 +369,7 @@ def test_flag_by_list_using_name_with_mapping(strict_coercion, debug_trail):
         strict_coercion=strict_coercion,
         debug_trail=debug_trail,
         recipe=[
-            flag_by_list_using_name(
+            flag_by_member_names(
                 name_style=NameStyle.CAMEL,
                 map={
                     "CASE_ONE": "CASE_1",