environs

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Bump version and update changelog

Features:

• Add prefix parameter to Env constructor (#384). Thanks arthurc0102 for the suggestion.
• Re-export validate module from marshmallow (#385).

Bug fixes:

• Typing: Fix typing for Env.enum to allow by_value to be passed (#386).

Features:

• Add env singleton ([#194]). Thanks AndBondStyle for the suggestion.

from environs import env

Changes:

• default values are expected to be their in their deserialized form. Backwards-incompatible: Passing serialized values to default is no longer supported.

from datetime import date, timedelta
import environs

# DO
enable_login = env.bool("ENABLE_LOGIN", True)
ttl = env.timedelta("TTL", default=timedelta(seconds=600))
release_date = env.date("RELEASE", date(2025, 1, 7))
numbers = env.list("FOO", [1.0, 2.0, 3.0], subcast=float)

# DON'T
enable_login = env.bool("ENABLE_LOGIN", "true")
ttl = env.timedelta("TTL", default=600)
release_date = env.date("RELEASE", "2025-01-07")
numbers = env.list("NUMBERS", "1,2,42", subcast=float)

The exceptions to this rule are the Django-related functions, which accept string defaults.

DATABASE_URL = env.dj_db_url("DATABASE_URL", default="postgresql://localhost:5432/mydb")

This fixes #297 and #270.

Features:

• Typing: Add type hints for parser methods (#367). Thanks OkeyDev for the PR.
• Add by_value param to Env.enum. Pass by_value=True to parse Enum by values instead of names.

Other changes:

• Drop support for marshmallow<3.18.0.
• Backwards-incompatible: Remove load_default param from parser methods. Use default instead.
• Backwards-incompatible: Rename Env.enum's type param to enum.
• Backwards-incompatible: Remove ignore_case param from Env.enum.
• Backwards-incompatible: Remove allow_none, error_messages, and metadata params from parser methods.

Features:

• Env.enum allows passing an Enum as default.

Other changes:

• Support marshmallow 4.
• Support Python 3.9-3.13.
• Backwards-incompatible: Make Field classes private. Users should not need to access these.

Bug fixes:

• Fix passing non-string default values to Env.timedelta (#369). Thanks tcleonard for reporting and thanks ddelange for the PR.
• Fix Env.read_env(recurse=True) so that it returns as soon as a .env file is found (#370). Thanks senese for the PR.

Features:

• Env.timedelta can parse GEP-2257 duration strings (#366). Thanks ddelange for the PR.

Features:

• Add return_path argument to Env.read_env to return the path of the parsed file (#362). Thanks senese for the suggestion and PR. NOTE: This is added as a backwards-compatible change that is scheduled to be removed in 12.0.0. The path will stored as an attribute of Env.

Fixes:

• Prevent DeprecationWarning getting raised by marshmallow 3.21.0 (:issue:333).

Other changes:

• Remove subcast_key argument of env.dict. Use subcast_keys instead.
• Bump minimum required marshmallow version to 3.13.0.
• Remove missing argument from Env methods. Use default instead.
• Remove subcast argument from Env methods that don't use it.
• Backwards-incompatible: Remove environs.__version__ variable. Use importlib.metadata.version("environs") instead.

Features:

• Env.__repr__ and Env.__str__ no longer display environment variables, to prevent accidental exfiltration of sensitive data (#292). Thanks mro-rhansen2 for the suggestion.

Bug fixes:

• Fix passing None as default to env.list (#298). Thanks lucas-bremond for reporting.

Features:

• env.read_env returns False if file not found (#294). Thanks rptaylor for the suggestion.

Features:

• Allow default for env.json to be a dict or list (#240). Thanks tomgrin10 and bvanelli for the PRs.

Other changes:

• Test against Python 3.12.

Features:

• Add delimiter argument to env.dict (#277). Thanks gregoiredx for the PR.

Other changes:

• Backwards-incompatible: Drop support for EOL Python 3.6 and 3.7.
• Test against Python 3.11.
• Migrate to setup.cfg. Thanks deronnax for the PR.

Features:

• Allow callables or custom marshmallow fields to be passed to subcast, subcast_keys, and subcast_values. (#241). Thanks bvanelli for the PR.

Bug fixes:

• Address warning about passing metadata in newer versions of marshmallow.

Other changes:

• Test against Python 3.10.

Bug fixes:

• Fix env.url and other parsers that take field keyword arguments (#227). Thanks KochankovID for the PR.

Bug fixes:

• Allow default for env.path to be a pathlib.Path (#228). Thanks KochankovID for the PR.

Bug fixes:

• Fix compatibility with marshmallow>=3.13.0 so that no DeprecationWarnings are raised (#224).

Bug fixes:

• Handle JSON decoding errors when using env.json (#212). Thanks bvanelli for the PR.

Bug fixes:

• Apply variable expansion to default values (#204). Thanks rjcohn for the PR.

Deprecations:

• Rename subcast_key argument of env.dict to subcast_keys for consistency with subcast_values. subcast_key is deprecated.

Features:

• Add time parser (#191).

Features:

• Add enum parser (#185).
• Add delimiter param to env.list (#184).

Thanks tomgrin10 for the PRs.

Bug fixes:

• Loosen ParserMethod typing (#186 (comment)). Thanks hukkinj1 for the PR.

Other changes:

• When using deferred validation (eager=False), parser methods return None for missing or invalid values. Note: This may break code that depended on parser methods returning marshmallow.missing, but this behavior was not documented nor tested and therefore is not considered public API.

• Backwards-incompatible: Rename subcast param of env.dict to subcast_values for consistency with subcast_keys.
• Backwards-incompatible: Remove variable proxying. Use variable expansion instead (see 8.1.0 release notes below) (#175).
• Backwards-incompatible: Drop support for marshmallow 2 and Python 3.5, which are both EOL (#174).

Features:

• Add support for variable expansion, e.g. MY_VAR=${MY_OTHER_VAR:-mydefault} (#164). Thanks gnarvaja for the PR.

Deprecations:

• Variable proxying using the {{VAR}} syntax is deprecated and will be removed in environs 9.0.0. Use variable expansion using ${VAR} instead.

# Before
export MAILGUN_LOGIN=sloria
export SMTP_LOGIN={{MAILGUN_LOGIN}}

# After
export MAILGUN_LOGIN=sloria
export SMTP_LOGIN=${MAILGUN_LOGIN}

from environs import Env

env = Env(expand_vars=True)

SMTP_LOGIN = env.str("SMTP_LOGIN")  # => 'sloria'

Bug fixes:

• Fix deferred validation behavior for dj_db_url, dj_email_url, dj_cache_url, and custom parsers (#121). Thanks hukkinj1 for reporting.

Other changes:

• Test against Python 3.9.
• Remove usage of implicit typing.Optional (171).

Bug fixes:

• Fix behavior of recurse=True when custom filepath is passed to env.read_env (#100). Thanks ribeaud and timoklimmer for the help.

Other changes:

• Backwards-incompatible: As a result of the above fix, passing a directory to env.read_env is no longer allowed and will raise a ValueError. Only file paths or file names should be passed.

• Add subcast_key argument to env.dict (#151). Thanks AugPro for the suggestion and PR.

• Fix error when parsing empty list with subcast #137. Thanks [sabdouni] for the catch and patch.

• log_level accepts lower-cased log level names and rejects invalid names (#138). Thanks gnarvaja for the PR.

• Add dj_cache_url for caching Django cache URLs (requires installing with [django]) (#126). Thanks epicserve for the suggestion and PR.

• Improve typings and run mypy with dependencies type annotations (#115).
• Distribute types per PEP 561 (#116).

Thanks hukkinj1 for the PRs.

• Backwards-incompatible: Remove stream argument from read_env, since it had no effect (#114).
• Backwards-incompatible: Env.read_env consistently returns None (#111).
• Remove unnecessary __str__ definition (#112).

Thanks hukkinj1 for the PRs.

Features:

• Add deferred validation via the eager parameter and env.seal() (#56). Thanks robertlagrant for the suggestion.

Other changes:

• Test against Python 3.8 (#108).

Features:

• Default parser methods are now defined as bound methods. This enables static analysis features, e.g. autocomplete (#103). Thanks rugleb for the suggestion. Backwards-incompatible: As a result of this change, adding a parser name that is the same as an existing method will result in an error being raised.

import environs

env = environs.Env()


# Below conflicts with built-in `url` method.
# In <6.0.0, this would override the built-in method.
# In >=6.0.0, this raises an error:
#   environs.ParserConflictError: Env already has a method with name 'url'. Use a different name.
@env.parser_for("url")
def https_url(value):
    return "https://" + value

Bug fixes:

• Fix error message for prefixed variables (#102). Thanks AGeekInside for reporting.

Other changes:

• Backwards-incompatible: Rename Env.__parser_map__ to Env.__custom_parsers__.

Bug fixes:

• Fix behavior when recursively searching for a specified file (#96). Thanks ribeaud for the catch and patch.

Changes:

• Improve typings.

Features:

• Add env.log_level (#7).
• Use raise from to improve tracebacks.

Other changes:

• Improve typings.

Features:

• Add env.path (#81). Thanks umrashrf for the suggestion.
• Add type annotations.

Other changes:

• Backwards-incompatible: Drop support for Python 2. If you use Python 2, you will need to use version 4.2.0 or older.

• Minor optimization.

Bug fixes:

• Reset prefix when an exception is raised within an env.prefixed() context (#78). Thanks rcuza for the catch and patch.

Bug fixes:

• Fix behavior when passing a dict value as the default to env.dict (#76). Thanks c-w for the PR.

Support:

• Document how to read a specific file with env.read_env (#66). Thanks nvtkaszpir and c-w.

Bug fixes:

• Fix compatibility with marshmallow 3.0.0>=rc6.

Bug fixes:

• Fix accessing proxied envvars when using env.prefixed (#72). Thanks Kamforka for the catch and patch.
• Fix behavior when an envvar is explicitly set to an empty string (#71). Thanks twosigmajab for reporting and thanks hvtuananh for the PR.

• EnvError subclasses ValueError (#50). Thanks alexpirine.
• Test against Python 3.7.

• Use python-dotenv for parsing .env files. Env.read_env behaves mostly the same except that a warning isn't raised by default if a .env file isn't found. Pass verbose=True to raise a warning.

Features:

• Backwards-incompatible: Env.read_env raises a warning instead of an error when .env isn't found (#10). Thanks lachlancooper for the suggestion.
• Add optional Django support. Install using pip install environs[django], which enables env.dj_db_url and env.dj_email_url.

Features:

• Fix compatibility with marshmallow 3 beta.

Features:

• Add recurse parameter to Env.read_env (#9). Thanks gthank for the PR.

Features:

• Add url parser that returns a urllib.parse.ParseResult (#6). Thanks IlyaSemenov for the suggestion.

Bug fixes:

• Every instance of Env gets its own parser map, so calling env.parser_for for one instance doesn't affect other instances.

• Add Env.read_env method for reading .env files.

• Support for proxied variables (#2).
• Backwards-incompatible: Remove env.get method. Use env() instead.
• Document how to read .env files (#1).