Fix typing for Env.enum; document by_value (#388)

CHANGELOG.md

@@ -8,6 +8,10 @@ Features:
   Thanks [arthurc0102](https://github.com/sloria/environs/issues/384)
   for the suggestion.
 
+Bug fixes:
+
+- Typing: Fix typing for `Env.enum` to allow `by_value` to be passed ([#386](https://github.com/sloria/environs/issues/386)).
+
 ## 14.0.0 (2025-06-07)
 
 Features:

README.md

@@ -114,6 +114,7 @@ The following are all type-casting methods of `Env`:
 - `env.log_level`
 - `env.path` (casts to a [`pathlib.Path`](https://docs.python.org/3/library/pathlib.html))
 - `env.enum` (casts to any given enum type specified in `enum` keyword argument)
+  - Pass `by_value=True` to parse and validate by the Enum's values.
 
 ## Reading `.env` files
 

src/environs/types.py

@@ -2,7 +2,7 @@
 
 .. warning::
 
-    This module is provisional. Types may be modified, added, and removed between minor releases.
+    This module is private. Types may be modified, added, and removed between minor releases.
 """
 
 from __future__ import annotations
@@ -16,6 +16,7 @@
     from typing_extensions import Unpack
 
 import marshmallow as ma
+from marshmallow.fields import Field
 
 T = typing.TypeVar("T")
 EnumT = typing.TypeVar("EnumT", bound=enum.Enum)
@@ -137,6 +138,7 @@ def __call__(
         default: None = ...,
         *,
         enum: type[EnumT],
+        by_value: bool | Field | type[Field] = ...,
         **kwargs: Unpack[BaseMethodKwargs],
     ) -> EnumT | None: ...
 
@@ -147,6 +149,7 @@ def __call__(
         default: EnumT = ...,
         *,
         enum: type[EnumT],
+        by_value: bool | Field | type[Field] = ...,
         **kwargs: Unpack[BaseMethodKwargs],
     ) -> EnumT: ...
 
@@ -156,5 +159,6 @@ def __call__(
         default: EnumT | None = ...,
         *,
         enum: type[EnumT],
+        by_value: bool | Field | type[Field] = False,
         **kwargs: Unpack[BaseMethodKwargs],
     ) -> EnumT | None: ...