knit_script.knit_script_interpreter.scope.local_scope module

Scoping structure for Knit Script.

This module provides the Knit_Script_Scope class, which manages variable scoping and namespace hierarchy for knit script program execution. It implements a hierarchical scoping system that supports local variables, global variables, function scopes, module scopes, and machine state management. The scoping system integrates with Python’s namespace and provides comprehensive variable resolution with proper shadowing warnings and scope inheritance.

class Knit_Script_Scope(context, parent=None, name=None, is_function=False, is_module=False, module_scope=None)

Bases: object

Keeps track of values in a confined scope. Also accesses globals and checks python scope.

The Knit_Script_Scope class implements a hierarchical variable scoping system for knit script execution. It manages local variables, global variables, function scopes, module scopes, and machine state while providing integration with Python’s namespace. The class supports scope nesting, variable shadowing detection, and proper inheritance of machine settings across scope boundaries.

This scoping system enables complex knit script programs to maintain proper variable isolation between functions and modules

while allowing controlled access to global state and machine configuration. It provides comprehensive variable resolution that searches through local scope, parent scopes, module scopes, and global scope in the correct order.

_context

The execution context for this scope.

Type:

_Context_Base

_is_module

True if this scope represents a module.

Type:

bool

_is_function

True if this scope represents a function.

Type:

bool

_returned

True if a return statement has been executed in this scope.

Type:

bool

_name

The name of this scope if it’s a named function or module.

Type:

str | None

_parent

The parent scope in the hierarchy.

Type:

Knit_Script_Scope | None

_module_scope

Associated module scope for this scope.

Type:

Knit_Script_Scope | None

_globals

Global variable storage shared across all scopes.

Type:

Knit_Script_Globals

_machine_scope

Machine state and configuration for this scope.

Type:

Machine_Scope

_child_scope

Current child scope if one exists.

Type:

Knit_Script_Scope | None

_return_value

Return value set by return statements in function scopes.

Type:

Any | None

Parameters:

• context (<module ‘knit_script.knit_script_interpreter._Context_Base’ from ‘/home/runner/work/knit_script/knit_script/src/knit_script/knit_script_interpreter/_Context_Base.py’>)

• parent (Knit_Script_Scope | None)

• name (str | None)

• is_function (bool)

• is_module (bool)

• module_scope (Knit_Script_Scope | None)

__init__(context, parent=None, name=None, is_function=False, is_module=False, module_scope=None)

Initialize a new scope with the specified configuration.

Creates a new scope in the hierarchy with the given characteristics. Root scopes (those without parents) initialize their own global and machine scope instances, while child scopes inherit from their parents.

Parameters:

• context (Knit_Script_Context) – The execution context for this scope.

• parent (Knit_Script_Scope | None, optional) – The parent scope in the hierarchy. If None, this becomes a root scope. Defaults to None.

• name (str | None, optional) – The name of this scope if it represents a named function or module. Defaults to None.

• is_function (bool, optional) – If True, this scope can handle return statements and function-specific behavior. Defaults to False.

• is_module (bool, optional) – If True, this scope represents a module and will be added to the parent’s namespace. Defaults to False.

• module_scope (Knit_Script_Scope | None, optional) – Associated module scope for variable resolution. Defaults to None.

property machine_scope: Machine_Scope

Get the machine scope for this level of scope.

Returns:

The machine scope for this level of scope, containing machine state and configuration settings.

Return type:

Machine_Scope

property variables: dict[str, Any]

Get the variables as key value pairs in a dictionary of variables set at this level of scope.

Returns only variables that are defined directly on this scope instance, excluding internal attributes that start with underscore.

Returns:

The variables as key value pairs in a dictionary of variables set at this level of scope.

Return type:

dict[str, Any]

property returned: bool

Check if the scope has found a return value.

Returns:

True if the scope has found a return value, indicating that execution should return from this scope.

Return type:

bool

property machine_state: Knitting_Machine

Get the current state of the knitting machine at the given execution context.

Returns:

The current state of the knitting machine at the given execution context.

Return type:

Knitting_Machine

property direction: Carriage_Pass_Direction

Get the current direction the carriage will take.

Returns:

The current direction the carriage will take.

Return type:

Carriage_Pass_Direction

property Carrier: Yarn_Carrier_Set | None

Get the current carrier being used by the machine.

Returns:

The current carrier being used by the machine, or None if no carrier is active.

Return type:

Yarn_Carrier_Set | None

property Rack: float

Get current racking of the machine.

Returns:

Current racking of the machine as a floating-point value.

Return type:

float

property Racking: float

Get current racking of the machine.

Returns:

Current racking of the machine as a floating-point value.

Return type:

float

property Gauge: int

Get the current number of sheets on the machine.

Returns:

The current number of sheets on the machine.

Return type:

int

property Sheet: Sheet_Identifier

Get the current sheet being worked on the machine.

Returns:

The current sheet being worked on the machine.

Return type:

Sheet_Identifier

static get_value_from_python_scope(key)

Test if key can be accessed from python scope.

Attempts to evaluate the given key as a Python expression to determine if it exists in the Python namespace and retrieve its value.

Parameters:

key (str) – Value to access from Python’s namespace.

Returns:

A tuple containing the value from python and True if value was in python scope, otherwise None and False.

Return type:

tuple[Any | None, bool]

property is_module: bool

Check if the variable scope belongs to a knit script module.

Returns:

True if the variable scope belongs to a knit script module.

Return type:

bool

property is_function: bool

Check if the variable scope belongs to a function.

Returns:

True if the variable scope belongs to a function.

Return type:

bool

property return_value: Any

Get the return value set for this scope.

This property can only be accessed on function scopes. It returns the value that was set by a return statement within the function.

Returns:

The return value set for this scope.

Return type:

Any

Raises:

AssertionError – If this scope is not a function scope.

set_local(key, value)

Set a local variable by the name <key> to the given value.

If a local variable exists from a parent scope within this function and module, set that value. Otherwise, creates a new local variable within the current scope.

Parameters:

• key (str) – Variable name to set.

• value (Any) – Value to set key to.

Return type:

None

set_global(key, value)

Set a global variable.

Parameters:

• key (str) – Variable name to set in global scope.

• value (Any) – Value to add to globals.

Return type:

None

get_local(key)

Find the lowest level value in local scope by key.

Looks for value in the following order: 1. The machine scope. 2. Python scope. 3. Local scope 4. Modules owned by the local scope. 5. A parent scope or any of its modules. 6. The Global Scope.

Parameters:

key (str) – The variable name to search for.

Returns:

The value in the local hierarchy by that key.

Return type:

Any

Raises:

NameError – If key is not in scope.

Warns:

• Shadows_Global_Variable_Warning – If the key is found in a local scope but also exists in the globals.

• Shadow_Variable_Warning – If the key is found and exists at a higher scope (excludes modules).

add_local_by_path(path, value)

Add module sub scopes to variable space following the given path.

Sets final value in the lowest module subscope. Creates intermediate module scopes as needed to establish the full path.

Parameters:

• path (list[str]) – List of module names representing the path to the final variable.

• value (Any) – Value to associate with end of path.

Return type:

None

has_local(key, stop_at_function=False, stop_at_module=False)

Check for key in local scope. Ignores globals.

Parameters:

• key (str) – The variable name to search for.

• stop_at_function (bool, optional) – Will not search for local variable beyond function scope. Defaults to False.

• stop_at_module (bool, optional) – Will not search for local variable beyond module scope. Defaults to False.

Returns:

True if key is in local scope within the specified boundaries.

Return type:

bool

delete_local(key)

Delete the variable at lowest scope level. If not found, no-op.

Parameters:

key (str) – The variable name to delete.

Returns:

True if a value was found and deleted, False otherwise.

Return type:

bool

delete_global(key)

Delete global variable. If not found, no-op.

Parameters:

key (str) – Variable name to delete from global scope.

Returns:

True if a global was deleted, False if not found.

Return type:

bool

Raises:

NameError – If attempting to delete reserved keywords like ‘exit_value’.

enter_new_scope(name=None, is_function=False, is_module=False, module_scope=None)

Enter a new sub scope and put it into the hierarchy.

Parameters:

• name (str | None, optional) – Name of the sub_scope if a function or module. Required for functions and modules. Defaults to None.

• is_function (bool, optional) – If true, may have return values and function-specific behavior. Defaults to False.

• is_module (bool, optional) – If true, module is added by variable name to parent scope. Defaults to False.

• module_scope (Knit_Script_Scope | None, optional) – Module scope to use for variable resolution. Defaults to None.

Returns:

Child scope that was created and is now active.

Return type:

Knit_Script_Scope

Raises:

AssertionError – If is_function is True but name is None, or if is_module is True but name is None.

collapse_lower_scope()

Brings all values in the child scopes (recursively) up into this scope.

Recursively collapses child scopes by bringing their variables up to this scope level and inheriting machine scope settings. This is used when exiting scopes that should preserve their variables.

Return type:

None

exit_current_scope(collapse_into_parent=False)

Set child scope to none.

If the current scope is not a module this may cause values to be deleted and become inaccessible.

Parameters:

collapse_into_parent (bool, optional) – If True, brings all lower level values from child scope into the current scope. Defaults to False.

Returns:

The parent scope or None if program exits.

Return type:

None | Knit_Script_Scope

__contains__(key)

Check if a variable exists in any accessible scope.

Checks for variable existence in Python scope, global scope, or local scope hierarchy.

Parameters:

key (str) – The variable name to check for.

Returns:

True if the variable exists in any accessible scope.

Return type:

bool

__getitem__(key)

Get a variable value using dictionary-style access.

Parameters:

key (str) – The variable name to retrieve.

Returns:

The value of the variable.

Return type:

Any

Raises:

NameError – If the variable is not found in any accessible scope.

__setitem__(key, value)

Set a variable value using dictionary-style access.

Parameters:

• key (str) – The variable name to set.

• value (Any) – The value to assign to the variable.

Return type:

None