Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve documentation for read_env() #88

Open
edmorley opened this issue Jul 7, 2016 · 5 comments · May be fixed by #252
Open

Improve documentation for read_env() #88

edmorley opened this issue Jul 7, 2016 · 5 comments · May be fixed by #252
Assignees
@sergeyklay
Labels
documentation Improvements or additions to documentation

Comments

@edmorley
Copy link

edmorley commented Jul 7, 2016

The readme briefly mentions read_env(), however it wasn't until reading the source that the following became apparent:

  • that the values read in from the .env file are overridden by any that already existed in the environment (I think this is handy, but isn't immediately obvious)
  • that read_env() also takes an overrides list
  • that read_env() updates os.environ directly, rather than just that particular Env instance (someone not realising this was intentional is what caused Why read_env reads everything to os.environ? #66 to be filed)

It would be great to mention the above in the readme. If I get a chance to open a PR I will, but it may not be soon, so if anyone wants to do so in the meantime, go ahead :-)
@bittner
Copy link

bittner commented Nov 26, 2016

Also, the documentation mentions a "filthy magic stack backtracking" in order to "find manage.py and then find the dotenv".

It should be specified more in detail what this means. When you have a two-level hierarchy then the .env file is not found, at the moment. It's yet to be discussed whether this is by design or a bug.

mysite
+-- mysite
|   +-- settings.py
+-- .env               # not found by Env.read_env() in mysite.settings

@max-arnold max-arnold mentioned this issue Dec 20, 2016
Closed
@QasimK QasimK mentioned this issue Mar 29, 2018
Closed
@dk-WZFinTech
Copy link

IMO less problematic will be to inform user that they can point path for .env file, like I did here:

BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

env = environ.Env(
    DEBUG=(bool, False),
)

environ.Env.read_env('{}/.env'.format(BASE_DIR))

@bittner
Copy link

bittner commented May 21, 2019

I'd suggest to use os.path.join(base, ".env") instead of a slash in a string. The former is OS independent.

@dk-WZFinTech
Copy link

I'd suggest to use os.path.join(base, ".env") instead of a slash in a string. The former is OS independent.

True my bad 😄

@remarkov
Copy link

Also, the documentation mentions a "filthy magic stack backtracking" in order to "find manage.py and then find the dotenv".

It should be specified more in detail what this means. When you have a two-level hierarchy then the .env file is not found, at the moment. It's yet to be discussed whether this is by design or a bug.

mysite
+-- mysite
|   +-- settings.py
+-- .env               # not found by Env.read_env() in mysite.settings

That really gave me some wtf moments. After reading that wording regarding "filthy magic" I was literally expect it to magically find that my .env is located at the same directory as manage.py which was one level up from settings.py.
Thanks all for this discussion and hints.

birdcar added a commit to birdcar/django-environ that referenced this issue Mar 19, 2020
@birdcar
Remove "filthy magic stack backtracking" in favor of BASE_DIR
b9a9dc2 
The read_env documentation currently states:

> If not given a path to a dotenv path, does filthy magic stack
> backtracking to find manage.py and then find the dotenv.

Based on joke2k#88, it appears that this behavior is
rather fragile.

To improve this, I think the package should document that read_env
expects you to provide a path. If one is not provided, it will
attempt to use the BASE_DIR constant from the django settings
module. If an ImportError is encountered while it attempts to do this,
read_env will assume there's no .env file to be found, log an info
message to that effect, and continue on.

fixes: joke2k#88
@birdcar birdcar linked a pull request Mar 19, 2020 that will close this issue
Open
@yourcelf yourcelf mentioned this issue Oct 12, 2020
Open
This was referenced May 28, 2021
Merged
Merged
@sergeyklay sergeyklay self-assigned this Sep 1, 2021
@sergeyklay sergeyklay added the documentation Improvements or additions to documentation label Sep 1, 2021
birdcar added a commit to birdcar/django-environ that referenced this issue Sep 5, 2021
@birdcar
Remove "filthy magic stack backtracking" in favor of BASE_DIR
21aabba 
The read_env documentation currently states:

> If not given a path to a dotenv path, does filthy magic stack
> backtracking to find manage.py and then find the dotenv.

Based on joke2k#88, it appears that this behavior is
rather fragile.

To improve this, I think the package should document that read_env
expects you to provide a path. If one is not provided, it will
attempt to use the BASE_DIR constant from the django settings
module. If an ImportError is encountered while it attempts to do this,
read_env will assume there's no .env file to be found, log an info
message to that effect, and continue on.

fixes: joke2k#88
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@sergeyklay sergeyklay

Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Remove "filthy magic stack backtracking" in favor of BASE_DIR birdcar/django-environ
5 participants
@edmorley @bittner @sergeyklay @remarkov @dk-WZFinTech