Skip to content

environment

flavor.psp.format_2025.environment

Environment variable management for PSPF/2025 packages.

Handles platform-specific environment variables and layered environment processing.

Functions

apply_environment_layers 

apply_environment_layers(
    base_env: dict[str, str],
    runtime_env: dict[str, Any] | None = None,
    workenv_env: dict[str, str] | None = None,
    execution_env: dict[str, str] | None = None,
) -> dict[str, str]

Apply environment variable layers in order.

Layers (applied in order): 1. Runtime security layer (unset, pass, map, set operations) 2. Workenv layer (workenv-specific paths) 3. Execution layer (application-specific settings) 4. Platform layer (automatic, highest priority)

Parameters:

Name Type Description Default
base_env dict[str, str]

Base environment variables

 required
runtime_env dict[str, Any] | None

Runtime security operations

 None
workenv_env dict[str, str] | None

Workenv-specific variables

 None
execution_env dict[str, str] | None

Execution-specific variables

 None

Returns:

Type Description
dict[str, str]

Final environment dictionary
Source code in flavor/psp/format_2025/environment.py 
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def apply_environment_layers(
    base_env: dict[str, str],
    runtime_env: dict[str, Any] | None = None,
    workenv_env: dict[str, str] | None = None,
    execution_env: dict[str, str] | None = None,
) -> dict[str, str]:
    """
    Apply environment variable layers in order.

    Layers (applied in order):
    1. Runtime security layer (unset, pass, map, set operations)
    2. Workenv layer (workenv-specific paths)
    3. Execution layer (application-specific settings)
    4. Platform layer (automatic, highest priority)

    Args:
        base_env: Base environment variables
        runtime_env: Runtime security operations
        workenv_env: Workenv-specific variables
        execution_env: Execution-specific variables

    Returns:
        Final environment dictionary
    """
    result = base_env.copy()

    # Layer 1: Runtime security - use dedicated processor matching Rust/Go
    if runtime_env:
        process_runtime_env(result, runtime_env)

    # Layer 2: Workenv
    if workenv_env:
        result.update(workenv_env)

    # Layer 3: Execution
    if execution_env:
        result.update(execution_env)

    # Layer 4: Platform (automatic, always last)
    set_platform_environment(result)

    return result

process_runtime_env 

process_runtime_env(
    env_map: dict[str, str], runtime_env: dict[str, Any]
) -> None

Process runtime environment configuration for PSPF/2025 packages.

This function modifies the environment map in-place, applying runtime environment operations in a specific order to ensure correct behavior. This implementation aligns with the Rust and Go implementations for cross-language consistency in the PSPF/2025 format.

Operations are processed in this order: 1. Analyze pass patterns - Build list of variables to preserve 2. unset - Remove specified variables (skipping those marked to preserve) 3. map - Rename variables (old_name -> new_name) 4. set - Set specific values (override or add new) 5. pass verification - Check that required variables/patterns exist

Pattern matching supports: - Exact matches: "PATH" matches only PATH - Glob patterns: "PYTHON_" matches PYTHON_HOME, PYTHON_PATH, etc. - Wildcard: "" matches all variables

Parameters:

Name Type Description Default
env_map dict[str, str]

Mutable environment variables dictionary to process. This dict is modified in-place.

 required
runtime_env dict[str, Any]

Runtime environment configuration containing: - pass: List of patterns for variables to preserve/require - unset: List of patterns for variables to remove - map: Dict of old_name -> new_name mappings - set: Dict of variable -> value assignments

 required
Example

env = {"FOO": "bar", "BAZ": "qux", "TEMP": "123"} runtime = { ... "pass": ["FOO", "BA*"], ... "unset": ["TEMP"], ... "map": {"FOO": "NEW_FOO"}, ... "set": {"CUSTOM": "value"} ... } process_runtime_env(env, runtime)

Result:
Note

This function is called during package execution to prepare the environment for the packaged application. It ensures consistent environment handling across different platforms and launchers.

Source code in flavor/psp/format_2025/environment.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def process_runtime_env(env_map: dict[str, str], runtime_env: dict[str, Any]) -> None:
    """
    Process runtime environment configuration for PSPF/2025 packages.

    This function modifies the environment map in-place, applying runtime
    environment operations in a specific order to ensure correct behavior.
    This implementation aligns with the Rust and Go implementations for
    cross-language consistency in the PSPF/2025 format.

    Operations are processed in this order:
    1. Analyze pass patterns - Build list of variables to preserve
    2. unset - Remove specified variables (skipping those marked to preserve)
    3. map - Rename variables (old_name -> new_name)
    4. set - Set specific values (override or add new)
    5. pass verification - Check that required variables/patterns exist

    Pattern matching supports:
    - Exact matches: "PATH" matches only PATH
    - Glob patterns: "PYTHON_*" matches PYTHON_HOME, PYTHON_PATH, etc.
    - Wildcard: "*" matches all variables

    Args:
        env_map: Mutable environment variables dictionary to process.
                 This dict is modified in-place.
        runtime_env: Runtime environment configuration containing:
            - pass: List of patterns for variables to preserve/require
            - unset: List of patterns for variables to remove
            - map: Dict of old_name -> new_name mappings
            - set: Dict of variable -> value assignments

    Example:
        >>> env = {"FOO": "bar", "BAZ": "qux", "TEMP": "123"}
        >>> runtime = {
        ...     "pass": ["FOO", "BA*"],
        ...     "unset": ["TEMP"],
        ...     "map": {"FOO": "NEW_FOO"},
        ...     "set": {"CUSTOM": "value"}
        ... }
        >>> process_runtime_env(env, runtime)
        >>> # Result: {"NEW_FOO": "bar", "BAZ": "qux", "CUSTOM": "value"}

    Note:
        This function is called during package execution to prepare the
        environment for the packaged application. It ensures consistent
        environment handling across different platforms and launchers.
    """

    pass_patterns = runtime_env.get("pass", [])
    should_preserve = _create_preserve_checker(pass_patterns)

    _process_unset_operations(env_map, runtime_env, should_preserve)
    _process_map_operations(env_map, runtime_env, should_preserve)
    _process_set_operations(env_map, runtime_env)
    _verify_pass_requirements(pass_patterns, env_map)

set_platform_environment 

set_platform_environment(env: dict[str, str]) -> None

Set platform-specific environment variables.

These variables are always set and cannot be overridden by user configuration.

Variables set: - FLAVOR_OS: Operating system (darwin, linux, windows) - FLAVOR_ARCH: Architecture (amd64, arm64, x86, i386) - FLAVOR_PLATFORM: Combined OS_arch string - FLAVOR_OS_VERSION: OS version (if available) - FLAVOR_CPU_TYPE: CPU type/family (if available)

Parameters:

Name Type Description Default
env dict[str, str]

Environment dictionary to update

 required
Source code in flavor/psp/format_2025/environment.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
def set_platform_environment(env: dict[str, str]) -> None:
    """
    Set platform-specific environment variables.

    These variables are always set and cannot be overridden by user configuration.

    Variables set:
    - FLAVOR_OS: Operating system (darwin, linux, windows)
    - FLAVOR_ARCH: Architecture (amd64, arm64, x86, i386)
    - FLAVOR_PLATFORM: Combined OS_arch string
    - FLAVOR_OS_VERSION: OS version (if available)
    - FLAVOR_CPU_TYPE: CPU type/family (if available)

    Args:
        env: Environment dictionary to update
    """
    # Get platform information from centralized utilities
    os_name = get_os_name()
    arch_name = get_arch_name()
    platform_str = get_platform_string()

    # Set required platform variables (override any existing values)
    env["FLAVOR_OS"] = os_name
    env["FLAVOR_ARCH"] = arch_name
    env["FLAVOR_PLATFORM"] = platform_str

    # Try to get OS version
    os_version = get_os_version()
    if os_version:
        env["FLAVOR_OS_VERSION"] = os_version

    # Try to get CPU type
    cpu_type = get_cpu_type()
    if cpu_type:
        env["FLAVOR_CPU_TYPE"] = cpu_type