Skip to content

Add explicit environment loading API: read_env() and env helper#186

Open
gowhari wants to merge 1 commit into
HBNetwork:masterfrom
gowhari:explicit-read-env
Open

Add explicit environment loading API: read_env() and env helper#186
gowhari wants to merge 1 commit into
HBNetwork:masterfrom
gowhari:explicit-read-env

Conversation

@gowhari

@gowhari gowhari commented Jul 6, 2026

Copy link
Copy Markdown

One of the best features of python-decouple is the module-level config object. It allows developers to simply import it
and read configuration values. Another great feature is the built-in cast support, which makes configuration parsing simple and consistent.

However, in larger applications, the implicit loading of .env files becomes a limitation.
Configuration loading is an application startup concern, while reading configuration values happens
throughout the codebase. Mixing these two responsibilities makes it difficult to control when configuration is loaded.

Examples include:

  • Large projects with many modules, where importing a module may unexpectedly trigger .env loading.
  • Multiprocessing applications, where child processes should simply inherit os.environ instead of re-reading configuration files.
  • Applications that need to load or merge configuration from multiple sources before the rest of the application starts.

This pull request keeps the same simple programming model while separating initialization from access:

# Once during application startup
from decouple import read_env
read_env()

# Later, anywhere in the codebase
from decouple import env
debug = env("DEBUG", cast=bool)

read_env() performs the initialization explicitly, while env preserves everything developers like about config:
a ready-to-use module-level object and full cast support.

The difference is that env reads exclusively from os.environ, making configuration access deterministic and allowing
applications to control exactly when and how environment variables are populated.

This feature is completely additive and does not change the behavior of the existing config API.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant