env.values

import env.values

env lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled env.values.* needs import env.values.

Reading configuration back out of the process environment, in the type the program actually wants.

An environment variable is always text. A port is a number, a feature flag is a boolean, and an allow-list is a list, so somewhere that text has to be checked and converted. Doing it here means it is done the same way everywhere, and that a PORT=eighty is a loud error at startup rather than a silent zero halfway through the first request.

Empty means unconfigured

Every function here treats a variable set to the empty string exactly as it treats one that was never set at all: the default applies, and require() raises. This is the same rule ${NAME:-...} follows, and it is what makes a FLAG= line, an unset shell variable and an orchestrator passing an empty value all mean one thing instead of three.

os.get_env() is the unfiltered view for the rare case that needs to tell those apart.

Functions

has()

env.has(name: string) -> bool

Returns true when name is set to a non-empty value.

if env.has('SENTRY_DSN') {
  reporting.enable(env.require('SENTRY_DSN'))
}

Parameters

• name (string)

Returns bool

get()

env.get(name: string, default_value) -> ?any

Returns the value of name, or default_value when it is unset or empty.

var host = env.get('HOST', '127.0.0.1')

Parameters

• name (string)
• default_value (?any) — Returned unchanged; nil when not given.

Returns ?any

require()

env.require(name: string, message: ?string) -> string

Returns the value of name, and raises when it is unset or empty.

This is the line to write for a setting the program cannot invent a default for. Failing here, at startup, beats failing later at the first request that needed it.

var secret = env.require('SESSION_SECRET')

Parameters

• name (string)
• message (?string) — A reason to report instead of the default text.

Returns string

Raises MissingVariable when name is unset or empty.

int()

env.int(name: string, default_value: ?number) -> ?number

Returns the value of name as an integer.

The value must be a decimal integer, optionally signed. Anything else is a ValueError naming the variable, because a port of eighty is a mistake in the configuration and not a reason to fall back to a default.

var port = env.int('PORT', 8080)

Parameters

• name (string)
• default_value (?number) — Returned when name is unset or empty.

Returns ?number

Raises ValueError when the value is not a decimal integer.

float()

env.float(name: string, default_value: ?number) -> ?number

Returns the value of name as a number.

Decimals and exponents are both accepted. Anything else is a ValueError naming the variable.

var timeout = env.float('REQUEST_TIMEOUT', 2.5)

Parameters

• name (string)
• default_value (?number) — Returned when name is unset or empty.

Returns ?number

Raises ValueError when the value is not a number.

bool()

env.bool(name: string, default_value: ?bool) -> ?bool

Returns the value of name as a boolean.

1, true, yes, y and on are true; 0, false, no, n and off are false. Case and surrounding whitespace do not matter. Anything else is a ValueError, so a DEBUG=maybe is caught rather than quietly read as true.

if env.bool('DEBUG', false) {
  log.set_level(log.Debug)
}

Parameters

• name (string)
• default_value (?bool) — Returned when name is unset or empty.

Returns ?bool

Raises ValueError when the value is not one of the spellings above.

list()

env.list(name: string, separator: ?string, default_value: ?list) -> ?list

Returns the value of name split into a list.

The value is split on separator, each item loses the whitespace around it, and empty items are dropped, so A, B,,C and A,B,C give the same three items.

var origins = env.list('CORS_ORIGINS', ',', [])

Parameters

• name (string)
• separator (?string) — Defaults to ','.
• default_value (?list) — Returned when name is unset or empty.

Returns ?list

2026, Richard Ore and Zuri contributors