environment – Environment Block

Each process has an environment block (which may be empty). It consists of a set of key-value pairs, each of which is a string. The value string may be formed partly or wholly from other environment variables using the %envvar% notation. By default, this module will reinterpret those embedded variables but this can be overriden.

The process environment is derived on startup from a combination of the system environment variables and the user’s environment variable, some of which are generated automatically by the system to reflect the user’s profile location and home drive etc.

All three environments are available as a dictalike class whose interface matches the Env base class. Each environment object quacks like a dict in respect of item access, Env.get(), Env.keys(), Env.items() and Env.update() methods and the system and user objects supply an additional Persistent.broadcast() method which sends a message to top-level windows, such as the shell, to indicate that the environment has changed.

Functions

process()

Return a dict-like object representing the environment block of the current process.

system(machine=None)

Return a dict-like object representing the system-level persistent environment variables, optionally selecting a different machine.

Parameters:machine – name or address of a different machine whose system environment is to be represented.

user()

Return a dict-like object representing the user-level persistent environment for the logged-on user.

TODO: include alternate user functionality via logon token

Classes

class Env

Semi-abstract base class for all environment classes. Outlines a dict-like interface which relies on subclasses to implement simple _get() and _items() methods.

as_string()

Produce a readable version of the data, used by __str__.

dump(level=0)

dumped(level)

static expand(item)

Return a version of item with internal environment variables expanded to their corresponding value. This is done automatically by the functions in this class unless you specify expand=False.

get(item, default=None, expand=True)

Return an environment value if it exists, otherwise [default]. This is the only way to get an unexpanded environment value by setting expand to False.

Parameters:

• item – name of an environment variable
• default – value to return if no such environment variable exists. This default is expanded if expand is True.
• expand – whether to expand embedded environment variables [True]

items(expand=True)

Yield key-value pairs of environment variables

Parameters:expand – whether to expand embedded environment variables [True]

iteritems(expand=True)

Yield key-value pairs of environment variables

Parameters:expand – whether to expand embedded environment variables [True]

keys()

Yield environment variable names

update(dict_initialiser)

Update this environment from a dict-like object, typically another environment:

from winsys import environment

penv = environment.process ()
penv.update (environment.system ())

path

class Persistent(root)

Represent persistent (registry-based) environment variables. These are held at system and at user level, the latter overriding the former when an process environment is put together. Don’t instantiate this class directly: use the user() and system() functions.

as_string()

Produce a readable version of the data, used by __str__.

static broadcast(timeout_ms=2000)

Broadcast a message to all top-level windows informing them that an environment change has occurred. The message must be sent, not posted, and times out after timeout_ms ms since some top-level windows handle this badly. NB This is a static method.

dump(level=0)

dumped(level)

static expand(item)

Return a version of item with internal environment variables expanded to their corresponding value. This is done automatically by the functions in this class unless you specify expand=False.

get(item, default=None, expand=True)

Return an environment value if it exists, otherwise [default]. This is the only way to get an unexpanded environment value by setting expand to False.

Parameters:

• item – name of an environment variable
• default – value to return if no such environment variable exists. This default is expanded if expand is True.
• expand – whether to expand embedded environment variables [True]

items(expand=True)

Yield key-value pairs of environment variables

Parameters:expand – whether to expand embedded environment variables [True]

iteritems(expand=True)

Yield key-value pairs of environment variables

Parameters:expand – whether to expand embedded environment variables [True]

keys()

update(dict_initialiser)

Update this environment from a dict-like object, typically another environment:

from winsys import environment

penv = environment.process ()
penv.update (environment.system ())

path

References

See also

Using the environment module

Cookbook examples of using the environment module