add docs

HISTORY.rst

@@ -6,6 +6,7 @@ History
 v0.6.0 (2017-11-XX)
 ...................
 * assignment validation #94, thanks petroswork!
+* JSON in environment variables for complex times, #96
 
 v0.5.0 (2017-10-23)
 ...................

docs/examples/settings.py

@@ -1,4 +1,11 @@
-from pydantic import DSN, BaseSettings, PyObject
+from typing import Set
+
+from pydantic import BaseModel, DSN, BaseSettings, PyObject
+
+
+class SubModel(BaseModel):
+    foo = 'bar'
+    apple = 1
 
 
 class Settings(BaseSettings):
@@ -20,6 +27,14 @@ class Settings(BaseSettings):
     db_query: dict = None
     dsn: DSN = None
 
+    # to override domains:
+    # export MY_PREFIX_DOMAINS = '["foo.com", "bar.com"]'
+    domains: Set[str] = set()
+
+    # to override more_settings:
+    # export MY_PREFIX_MORE_SETTINGS = '{"foo": "x", "apple": 1}'
+    more_settings: SubModel = SubModel()
+
     class Config:
         env_prefix = 'MY_PREFIX_'  # defaults to 'APP_'
         fields = {

docs/index.rst

@@ -194,6 +194,8 @@ This usage example comes last as it uses numerous concepts described above.
 Here ``redis_port`` could be modified via ``export MY_PREFIX_REDIS_PORT=6380`` or ``auth_key`` by
 ``export my_api_key=6380``.
 
+Complex types like ``list``, ``set``, ``dict`` and submodels can be set by using JSON environment variables.
+
 .. _usage_mypy:
 
 Usage with mypy

tests/test_settings.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-from pydantic import BaseSettings, ValidationError
+from pydantic import BaseModel, BaseSettings, ValidationError
 from pydantic.env_settings import SettingsError
 
 
@@ -49,30 +49,46 @@ class Config:
     assert Settings().apple == 'hello'
 
 
+class DateModel(BaseModel):
+    pips: bool = False
+
+
 class ComplexSettings(BaseSettings):
     apples: List[str] = []
     bananas: Set[int] = set()
     carrots: dict = {}
-    dates: SimpleSettings = SimpleSettings(apple='foobar')
+    date: DateModel = DateModel()
 
 
 def test_list(env):
     env.set('APP_APPLES', '["russet", "granny smith"]')
     s = ComplexSettings()
     assert s.apples == ['russet', 'granny smith']
+    assert s.date.pips is False
 
 
 def test_set_dict_model(env):
     env.set('APP_BANANAS', '[1, 2, 3, 3]')
     env.set('APP_CARROTS', '{"a": null, "b": 4}')
-    env.set('APP_DATES', '{"apple": "snap"}')
+    env.set('APP_DATE', '{"pips": true}')
     s = ComplexSettings()
     assert s.bananas == {1, 2, 3}
     assert s.carrots == {'a': None, 'b': 4}
-    assert s.dates.apple == 'snap'
+    assert s.date.pips is True
 
 
 def test_invalid_json(env):
     env.set('APP_APPLES', '["russet", "granny smith",]')
     with pytest.raises(SettingsError):
         ComplexSettings()
+
+
+def test_required_sub_model(env):
+    class Settings(BaseSettings):
+        foobar: DateModel
+
+    with pytest.raises(ValidationError):
+        Settings()
+    env.set('APP_FOOBAR', '{"pips": "TRUE"}')
+    s = Settings()
+    assert s.foobar.pips is True