Add docs for env_parse usage

docs/examples/settings_with_custom_parsing.py

@@ -0,0 +1,17 @@
+# output-json
+import os
+from typing import List
+
+from pydantic import BaseSettings, Field
+
+
+def parse_list(s: str) -> List[int]:
+    return [int(x.strip()) for x in s.split(",")]
+
+
+class Settings(BaseSettings):
+    numbers: List[int] = Field(env_parse=parse_list)
+
+
+os.environ["numbers"] = "1,2,3"
+print(Settings().dict())

docs/examples/settings_with_custom_parsing_validator.py

@@ -0,0 +1,17 @@
+# output-json
+import os
+from typing import List
+
+from pydantic import BaseSettings, Field, validator
+
+
+class Settings(BaseSettings):
+    numbers: List[int] = Field(env_parse=str)
+
+    @validator("numbers", pre=True)
+    def validate_numbers(cls, s):
+        return [int(x.strip()) for x in s.split(",")]
+
+
+os.environ["numbers"] = "1,2,3"
+print(Settings().dict())

docs/usage/settings.md

@@ -90,7 +90,7 @@ You could load a settings module thus:
 {!.tmp_examples/settings_nested_env.py!}
 ```
 
-`env_nested_delimiter` can be configured via the `Config` class as shown above, or via the 
+`env_nested_delimiter` can be configured via the `Config` class as shown above, or via the
 `_env_nested_delimiter` keyword argument on instantiation.
 
 JSON is only parsed in top-level fields, if you need to parse JSON in sub-models, you will need to implement
@@ -99,6 +99,21 @@ validators on those models.
 Nested environment variables take precedence over the top-level environment variable JSON
 (e.g. in the example above, `SUB_MODEL__V2` trumps `SUB_MODEL`).
 
+You may also populate a complex type by providing your own parsing function to
+`env_parse` in the field extras.
+
+```py
+{!.tmp_examples/settings_with_custom_parsing.py!}
+```
+
+You might choose to pass the environment string value through to pydantic and
+transform in a validator instead.
+
+```py
+{!.tmp_examples/settings_with_custom_parsing_validator.py!}
+```
+
+
 ## Dotenv (.env) support
 
 !!! note
@@ -162,7 +177,7 @@ see [python-dotenv's documentation](https://saurabh-kumar.com/python-dotenv/#usa
 
 Placing secret values in files is a common pattern to provide sensitive configuration to an application.
 
-A secret file follows the same principal as a dotenv file except it only contains a single value and the file name 
+A secret file follows the same principal as a dotenv file except it only contains a single value and the file name
 is used as the key. A secret file will look like the following:
 
 `/var/run/database_password`:
@@ -215,7 +230,7 @@ class Settings(BaseSettings):
         secrets_dir = '/run/secrets'
 ```
 !!! note
-    By default Docker uses `/run/secrets` as the target mount point. If you want to use a different location, change 
+    By default Docker uses `/run/secrets` as the target mount point. If you want to use a different location, change
     `Config.secrets_dir` accordingly.
 
 Then, create your secret via the Docker CLI