SessionContext Frozen Dataclass

🔍 Overview

SessionContext is an immutable dataclass designed to hold the execution context for a shell or REPL environment across multiple command invocations. It preserves the current working directory, a dictionary of environment variables, and the active character encoding. Because the class is frozen (frozen=True), instances are hashable and thread‑safe, encouraging explicit state transitions via replacement or factory methods.

📦 Class Definition

@dataclass(frozen=True)
class SessionContext:
    """Maintains persistent state across Shell executions."""
    
    cwd: Path = field(default_factory=Path.cwd)
    env: Dict[str, str] = field(default_factory=dict)
    encoding: str = "utf-8"

The frozen decorator guarantees immutability after construction. All fields are read‑only, making SessionContext ideal for functional updates or storing in caches.

📋 Attributes & Field Behavior

The three primary attributes define the persistent session contract. Below you'll find deeper insight into each field:

📌 Field Summary

⚙️ Usage Examples

Typical patterns for constructing and “updating” a SessionContext in a persistent shell environment. Since the class is frozen, modifications produce new instances — this aligns with functional state management.

📌 Basic instantiation

from pathlib import Path
from dataclasses import dataclass, field
from typing import Dict

# Assuming SessionContext definition from above
initial_context = SessionContext()
print(initial_context.cwd)      # /current/working/directory
print(initial_context.env)      # {}
print(initial_context.encoding) # utf-8

📌 Custom session with specific working directory & env

custom_env = {"EDITOR": "vim", "LANG": "en_US.UTF-8"}
project_context = SessionContext(
    cwd=Path("/home/user/projects/myapp"),
    env=custom_env,
    encoding="utf-8"
)
# Access fields
print(project_context.env["EDITOR"])  # vim

📌 Updating context (immutable approach)

Because frozen=True disables direct assignment, use dataclasses.replace or construct new contexts:

from dataclasses import replace

# create new context with changed cwd
old_ctx = SessionContext(cwd=Path("/initial/path"))
new_ctx = replace(old_ctx, cwd=Path("/new/workspace"))

print(old_ctx.cwd)  # /initial/path
print(new_ctx.cwd)  # /new/workspace

# To update environment variables, merge and create a fresh instance
updated_env = {**old_ctx.env, "NEW_VAR": "value"}
refreshed_ctx = replace(old_ctx, env=updated_env)

📌 Shell REPL state machine pattern

class ShellExecutor:
    def __init__(self, context: SessionContext):
        self._context = context

    def run_command(self, cmd: str) -> str:
        # use self._context.cwd, self._context.env, self._context.encoding
        # simulate execution ...
        return f"Executed '{cmd}' in {self._context.cwd}"

    def change_directory(self, new_path: Path) -> 'ShellExecutor':
        new_ctx = replace(self._context, cwd=new_path)
        return ShellExecutor(new_ctx)

# usage:
shell = ShellExecutor(SessionContext())
shell = shell.change_directory(Path("/var/log"))

🧠 Behavior & Design Notes

• ✔ Thread safety: Immutable contexts can be safely shared across threads without locking.
• ✔ Default factory semantics: Path.cwd() is evaluated at construction, not at class definition. So each instance gets the current directory of the Python process at that moment.
• ✔ Serialization: Because it's a dataclass, you can easily serialize to JSON or dict: asdict(context).
• ✔ Equality & Hashing: Two contexts with identical cwd, env, and encoding are considered equal and produce the same hash — useful for caching.

📌 Advanced considerations

Environment variable fallback: While the env dictionary is empty by default, in a real shell you may want to pre‑populate it with os.environ.copy(). The design intentionally leaves this decision to the caller, making the context lightweight.

Encoding validation: The encoding attribute is a simple string; consumers should validate against Python's codecs.lookup() if needed. The class does not perform runtime checks to keep overhead minimal.

📖 API Reference Summary

Class: SessionContext (frozen dataclass)
Module: shell.context (assumed)
Since: core shell abstraction

@dataclass(frozen=True) ensures the shell session state is predictable. For any modifications, the consumer must produce a new instance — enabling clean rollback and snapshot capabilities.

See also: dataclasses.replace utility to create modified copies without boilerplate.