Skip to content

Python API

Names listed in dotenv_fusion.__all__ are the supported public compatibility surface. Other module attributes are implementation details. The package ships public type annotations through its py.typed marker.

load_dotenv()

Load a dotenv-fusion input and return its values. When filepath is omitted, the function auto-detects .env-fuse, .env-fuse.local, then .env in the current directory. Parent traversal is opt-in through walk.

from dotenv_fusion import load_dotenv

config = load_dotenv(
    filepath=None,
    apply_types=True,
    override=False,
    restrict_imports=True,
    compile_vars={"ENV": "production"},
    walk=1,
)

Signature:

load_dotenv(
    filepath=None,
    override=False,
    apply_types=True,
    restrict_imports=False,
    compile_vars=None,
    walk=0,
)

The function returns a dictionary. With apply_types=True, declared integers, booleans, JSON values, and lists use their Python types. Unless override=False preserves an existing name, values are also written to os.environ as strings.

from dotenv_fusion import load_dotenv

config = load_dotenv(".env-fuse")
port = config["PORT"]
debug = config["DEBUG"]

DotenvLoader

Use the loader directly when the caller needs warnings, static source inspection, a controlled environment snapshot, or generated documentation.

from dotenv_fusion import DotenvLoader

loader = DotenvLoader(
    compile_vars={"ENV": "production", "REGION": "eu"},
    restrict_imports=True,
)
values = loader.load(".env-fuse", export_env=False)
warnings = loader.warnings

Pass environ={...} to define the environment used for expansion, conditions, and secret sources. An empty mapping prevents fallback to the host environment. Omitting it snapshots os.environ on each load. This setting controls lookups; use export_env=False to prevent writes to os.environ.

load()

loader.load(
    filepath,
    override=False,
    apply_types=True,
    verbose=0,
    export_env=True,
    resolve_sources=False,
    allow_unresolved_sources=False,
)
  • override controls writes over existing environment variables.
  • apply_types returns declared Python types when enabled.
  • export_env controls writes to os.environ.
  • resolve_sources contacts configured secret backends.
  • allow_unresolved_sources permits static inspection without backend access; it is intended for inspection tooling and requires export_env=False.

The method returns the parsed values as a dictionary.

check()

values = loader.check(
    ".env-fuse",
    apply_types=True,
    verbose=0,
    resolve_sources=True,
)

check() validates without writing values to os.environ. Set resolve_sources=False for static source validation without backend access.

Documentation and templates

loader = DotenvLoader()
loader.load(".env-fuse", export_env=False)

docs = loader.get_docs()
template = loader.generate_template()

get_docs() returns a mapping from variable names to documentation. generate_template() returns dotenv template content derived from inline or external definitions.

Parsed values

loader.values        # Raw strings
loader.typed_values  # Values after declared type conversion
loader.warnings      # Parse and compatibility warnings

A #@mode strict=true directive promotes subsequent warnings to DotenvError.

Standalone module

The core can also be imported from a copied dotenvfusion.py file for regular dotenv features. Package installation remains the supported way to obtain the public dotenv_fusion package and official backend modules.