Re-export validate module from marshmallow (#391)

* Re-export validate module from marshmallow

* Update docs and changelog

CHANGELOG.md

@@ -7,6 +7,7 @@ Features:
 - Add `prefix` parameter to `Env` constructor ([#384](https://github.com/sloria/environs/issues/384)).
   Thanks [arthurc0102](https://github.com/sloria/environs/issues/384)
   for the suggestion.
+- Re-export `validate` module from marshmallow ([#385](https://github.com/sloria/environs/issues/385)).
 
 Bug fixes:
 

README.md

@@ -219,34 +219,35 @@ year = env.int("YEAR")  # =>2020
 # export NODE_ENV='invalid'
 # export EMAIL='^_^'
 
-from environs import env, ValidationError
-from marshmallow.validate import OneOf, Length, Email
+from environs import env, validate, ValidationError
 
 
-# simple validator
-def validator(n):
-    if n <= 0:
-        raise ValidationError("Invalid value.")
-
-
-env.int("TTL", validate=validator)
-# => Environment variable "TTL" invalid: ['Invalid value.']
-
-
-# using marshmallow validators
+# built-in validators (provided by marshmallow)
 env.str(
     "NODE_ENV",
-    validate=OneOf(
+    validate=validate.OneOf(
         ["production", "development"], error="NODE_ENV must be one of: {choices}"
     ),
 )
 # => Environment variable "NODE_ENV" invalid: ['NODE_ENV must be one of: production, development']
 
 # multiple validators
-env.str("EMAIL", validate=[Length(min=4), Email()])
+env.str("EMAIL", validate=[validate.Length(min=4), validate.Email()])
 # => Environment variable "EMAIL" invalid: ['Shorter than minimum length 4.', 'Not a valid email address.']
+
+
+# custom validator
+def validator(n):
+    if n <= 0:
+        raise ValidationError("Invalid value.")
+
+
+env.int("TTL", validate=validator)
+# => Environment variable "TTL" invalid: ['Invalid value.']
 ```
 
+`environs.validate` is equivalent to [`marshmallow.validate`](https://marshmallow.readthedocs.io/en/stable/marshmallow.validate.html), so you can use any of the validators provided by that module.
+
 ## Deferred validation
 
 By default, a validation error is raised immediately upon calling a parser method for an invalid environment variable.

examples/deferred_validation_example.py

@@ -1,24 +1,22 @@
 import os
 from pprint import pprint
 
-from marshmallow.validate import Email, Length, OneOf, Range
-
-from environs import Env, EnvValidationError
+from environs import Env, EnvValidationError, validate
 
 os.environ["TTL"] = "-2"
 os.environ["NODE_ENV"] = "invalid"
 os.environ["EMAIL"] = "^_^"
 
 
 env = Env(eager=False)
-TTL = env.int("TTL", validate=Range(min=0, max=100))
+TTL = env.int("TTL", validate=validate.Range(min=0, max=100))
 NODE_ENV = env.str(
     "NODE_ENV",
-    validate=OneOf(
+    validate=validate.OneOf(
         ["production", "development"], error="NODE_ENV must be one of: {choices}"
     ),
 )
-EMAIL = env.str("EMAIL", validate=[Length(min=4), Email()])
+EMAIL = env.str("EMAIL", validate=[validate.Length(min=4), validate.Email()])
 
 # This will raise an error with the combined validation messages
 try:

examples/django_example.py

@@ -10,9 +10,8 @@
 import os
 from pprint import pprint
 
-import environs
+from environs import env
 
-env = environs.Env()
 env.read_env()
 
 BASE_DIR = os.path.dirname(os.path.abspath(__file__))

examples/marshmallow_example.py

@@ -3,7 +3,7 @@
 
 import marshmallow as ma
 
-from environs import Env
+from environs import env
 
 os.environ["STATIC_PATH"] = "app/static"
 
@@ -16,7 +16,6 @@ def _serialize(self, value, *args, **kwargs):
         return str(value)
 
 
-env = Env()
 env.parser_from_field("path", PathField)
 
 static_path = env.path("STATIC_PATH")

examples/plugin_example.py

@@ -3,7 +3,7 @@
 from furl import furl as Furl
 from yarl import URL
 
-from environs import Env
+from environs import env
 
 ##### This is the beginning of the plugin code #####
 
@@ -28,7 +28,6 @@ def setup(env):
 
 # Our application activates the plugin using the setup function
 
-env = Env()
 setup(env)
 
 # We now have the 'furl' and 'yurl' methods available

examples/validation_example.py

@@ -1,27 +1,16 @@
 import os
 
-from marshmallow.validate import Email, Length, OneOf
-
-from environs import Env, EnvError
+from environs import EnvError, ValidationError, env, validate
 
 os.environ["TTL"] = "-2"
 os.environ["NODE_ENV"] = "invalid"
 os.environ["EMAIL"] = "^_^"
 
-
-env = Env()
-
-# simple validator
-try:
-    env.int("TTL", validate=lambda n: n > 0)
-except EnvError as err:
-    print(err)
-
-# marshmallow validator
+# built-in validator
 try:
     env.str(
         "NODE_ENV",
-        validate=OneOf(
+        validate=validate.OneOf(
             ["production", "development"], error="NODE_ENV must be one of: {choices}"
         ),
     )
@@ -31,6 +20,19 @@
 
 # multiple validators
 try:
-    env.str("EMAIL", validate=[Length(min=4), Email()])
+    env.str("EMAIL", validate=[validate.Length(min=4), validate.Email()])
+except EnvError as err:
+    print(err)
+
+
+# custom validator
+def validate_ttl(value):
+    if value <= 0:
+        raise ValidationError("TTL must be greater than 0")
+    return value
+
+
+try:
+    env.int("TTL", validate=validate_ttl)
 except EnvError as err:
     print(err)

src/environs/__init__.py

@@ -54,7 +54,9 @@
 _EXPANDED_VAR_PATTERN = re.compile(r"(?<!\\)\$\{([A-Za-z0-9_]+)(:-[^\}:]*)?\}")
 
 
-# Reexport marshmallow's ValidationError. Custom validators should raise this for invalid input.
+# Reexport marshmallow's validate module and ValidationError.
+validate = ma.validate
+# Custom validators should raise this for invalid input.
 ValidationError = ma.ValidationError
 
 

tests/test_environs.py

@@ -18,10 +18,11 @@
 import django_cache_url
 import marshmallow as ma
 import pytest
-from marshmallow import fields, validate
+from marshmallow import fields
 from packaging.version import Version
 
 import environs
+from environs import validate
 
 HERE = pathlib.Path(__file__).parent
 MARSHMALLOW_VERSION = Version(importlib.metadata.version("marshmallow"))