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)[source]

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.

__init__(context, parent=None, name=None, is_function=False, is_module=False, module_scope=None)[source]

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 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 scope_name: str | None: Returns: str | None: The name of this scope if it represents a named function or module.

property function_name: str | None: Returns: str | None: The name of this scope if it represents a function.

property module_name: str | None: Returns: str | None: The name of this scope if it represents a module.

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 module_scope: Knit_Script_Scope | None: Returns: Knit_Script_Scope: The module scope for this variable scope.

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 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

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

enter_new_scope(name=None, is_function=False, is_module=False, module_scope=None)[source]

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:

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

collapse_descendant_scopes()[source]

Brings all values in the child scopes (recursively) up into this scope. If there is no child scope, this is a no-op.

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.

The machine state will be updated by any changes in the descendant scopes.

exit_current_scope(collapse_into_parent=False)[source]

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

static get_value_from_python_scope(key)[source]

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]

set_global(key, value)[source]

Set a global variable with the given key name. Overrides any global variable already defined by that key.

Parameters:

key (str) – The name of the global variable to set.
value (Any) – The value of the global variable.

add_local_by_path(path, value)[source]

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.

Raises:

NameError – If path is empty. No variable names can be used to set the value.

has_local(key, stop_at_function=False, stop_at_module=False)[source]

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)[source]

Delete the variable at lowest scope level.

Parameters:: key (str) – The variable name to delete.
Raises:: NameError – If key is not in scope and cannot be deleted.

__contains__(key)[source]

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__(variable_name)[source]

Find the lowest level value of the given variable name in local scope.

Looks for value in the following order:

The machine scope.
Python scope.
Local scope
Modules owned by the local scope.
A parent scope or any of its modules.
The Global Scope.

Parameters:: variable_name (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.

__setitem__(variable_name, value)[source]

Set a local variable to the given value.

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

Parameters:

variable_name (str) – Variable name to set.
value (Any) – Value to set key to.

__str__()[source]

Returns:: The string representation of this scope by its instance count and any name value for modules or functions.
Return type:: str