Document .env reading; test read_env integration

.gitignore

@@ -44,3 +44,6 @@ docs/_build
 README.html
 
 sandbox
+
+
+!tests/.env

README.rst

@@ -2,7 +2,7 @@
 environs: simplified environment variable parsing
 *************************************************
 
-.. image:: https://badge.fury.io/py/environs.png
+.. image:: https://badge.fury.io/py/environs.svg
     :target: http://badge.fury.io/py/environs
     :alt: Latest version
 
@@ -113,6 +113,7 @@ Validation
     env.str('EMAIL', validate=[Length(min=4), Email()])
     # => Environment variable "EMAIL" invalid: ['Shorter than minimum length 4.', 'Not a valid email address.']
 
+
 Serialization
 -------------
 
@@ -183,6 +184,32 @@ Marshmallow integration
     static_path = env.path('STATIC_PATH')  # => PosixPath('app/static')
     env.dump()['STATIC_PATH']  # => 'app/static'
 
+Reading ``.env`` files
+----------------------
+
+Use the external `read_env <https://github.com/sloria/read_env>`_ package to read ``.env`` files into ``os.environ``. ::
+
+    pip install read_env
+
+
+.. code-block:: bash
+
+    # myapp/.env
+    DEBUG=true
+    PORT=4567
+
+.. code-block:: python
+
+    from read_env import read_env
+
+    # Read .env into os.environ
+    read_env()
+
+    env.bool('DEBUG')  # => True
+    env.int('PORT')   # => 4567
+
+
+
 Why...
 ------
 

dev-requirements.txt

@@ -14,3 +14,5 @@ wheel
 
 # Linting
 flake8
+
+read_env

environs.py

@@ -5,6 +5,7 @@
 import os
 
 import marshmallow as ma
+from read_env import read_env
 
 __version__ = '1.0.0.dev0'
 __all__ = ['EnvError', 'Env']
@@ -111,6 +112,10 @@ def prefixed(self, prefix):
         yield self
         self._prefix = None
 
+    @staticmethod
+    def read_env(path=None):
+        return read_env(path)
+
     def __getattr__(self, name, **kwargs):
         try:
             partial = functools.partial(self.__parser_map__[name], self)

tests/.env

@@ -0,0 +1,5 @@
+ignored
+# Comment
+STRING=foo
+BOOL=true
+LIST=wat,wer,wen

test_environs.py → tests/test_environs.py

@@ -6,6 +6,7 @@
 
 import pytest
 from marshmallow import fields, validate
+import read_env
 
 import environs
 
@@ -123,6 +124,14 @@ def test_uuid_cast(self, set_env, env):
         assert env.uuid('UUID') == uid
 
 
+class TestEnvFileReading:
+
+    def test_read_env_integration(self, env):
+        assert env('STRING', 'default') == 'default'  # sanity check
+        read_env.read_env()
+        assert env('STRING') == 'foo'
+        assert env.list('LIST') == ['wat', 'wer', 'wen']
+
 def always_fail(value):
     raise environs.EnvError('something went wrong')