neighborhood module

neighborhood contains the Neighborhood class, which acts as a mediator class between different functions that have been re-cast as Door objects.

A mediator object for sequentially executing callables with a variable set of data values.

The primary mediator object is the Neighborhood class. It acts as an interface for other parts of the porchlight library, meaning it will manage Door creation, Param assignment, and other checks. It can be further extended using user-defined Door.

Also contains the definition for NeighborhoodError.

class porchlight.neighborhood.Neighborhood(initial_doors: List[Callable] | None = [], *, initialization: List[Callable | Door] | None = None, finalization: List[Callable | Door] | None = None)

Bases: object

A neighborhood manages the interactions between Doors. It consists of a modifiable collection of Door (or BaseDoor) objects.

_doors

Contains all data for Door objects. The keys are, by default, the name() property for the corresponding Door values.

Type:

dict, str: Door

_params

Contains all the parameters currently known to and managed by the Neighborhood object.

Type:

dict, str: Param

_call_order

The order in which the Door objects in _doors are called. By default, this is the order in which Door are added to the Neighborhood.

Type:

list, str

initialization

These will be called once the Neighborhood object begins any execution (e.g., via run_step()) will run these callables. This will only execute again if Neighborhood.has_initialized is set to False.

Type:

list of Callable, keyword-only

__init__(initial_doors: List[Callable] | None = [], *, initialization: List[Callable | Door] | None = None, finalization: List[Callable | Door] | None = None)
add_door(new_door: Door | List[Door], overwrite_defaults: bool = False, dynamic_door: bool = False)

Adds an already-initialized Door to the neighborhood.

Parameters:

  • new_door (Door,) –

    DynamicDoor, or list of Door objects.

    Either a single initialized Door object or a list of them. If a list is provided, this function is called for each item in the list.

  • overwrite_defaults (bool, optional) – If True, will overwrite any parameters shared between the new_door and Neighborhood._params to be equal to the defaults set by new_door. If False (default), no parameters that exist in the Neighborhood object already will be changed.

  • dynamic_door (bool, optional) – If True (default False), then the output(s) of this Door will be converted into a Door or set of Door in the Neighborhood object.

add_function(function: Callable, overwrite_defaults: bool = False, dynamic_door: bool = False)

Adds a new function to the Neighborhood object.

Parameters:

  • function (Callable) – The function to be added. This is converted to a Door object by this method.

  • overwrite_defaults (bool, optional) – If True, will overwrite any parameters shared between the function and Neighborhood._params to be equal to the defaults set by function. If False (default), no parameters that exist in the Neighborhood object already will be changed.

  • dynamic_door (bool, optional) – If True (default False), then the output(s) of this Door will be converted into a Door or set of Door in the Neighborhood object.

add_param(parameter_name: str, value: Any, constant: bool = False, restrict: Callable | None = None)

Adds a new parameter to the Neighborhood object.

The parameters all correspond to arguments passed directly to the Param initializer.

Parameters:

  • parameter_name (str) – Name of the parameter being created.

  • value (Any) – Parameter value

  • constant (bool, optional) – If True, the parameter is set to constant.

  • restrict (Callable or None, optional) –

    Either a callable that returns something that can be evaluated to True or False, or None. Raises an error if the parameter is set to a value that fails the restriction check.

    For a full description, see the docs for Param.

call(door_name: str | Door) → Any

Executes a call for a single door.

call_all_doors()

Calls every door currently present in the neighborhood object.

This order is currently dictated by the order in which Door are added to the Neighborhood.

The way this is currently set up, it will not handle positional arguments. That is, if an input cannot be passed using its variable name, this will break.

finalize()

Finalization executes doors/callables found in Neighborhood.finalization. It must be invoked directly by the user.

Unlike initialization, finalization will add new constant Param to the |Neighborhood| object.

gather_door_arguments(input_door: Door, defaults: Dict[str, Any] = {}) → Tuple[List, Dict]

This retrieves all parameters required by a Door, returning them as a list (positional arguments) and a dictionary (keyword arguments). If there are no positional-only arguments and/or no no keyword arguments, then empty objects are returned.

Parameters:

  • input_door (Door) – The door to gather necessary parameters for.

  • defaults (dict[str, Any]) – Default values for any arguments that may be missing from the Neighborhood. Keys must correspond to an arg or kwarg present in the input_door.

Returns:

  • args (list) – Positional-only arguments required by door.

  • kwargs (dict[str, Any]) – Keyword arguments for the door.

Notes

The return values must be unpacked before being used to call the Door.

get_value(parameter_name: str) → Any

Retrieves the value of a parameter by name. Does not return a Param object; it returns whatever data is stored in Param.value.

Parameters:

parameter_name (str) – The name of the parameter to retrieve the current value for.

initialize()

Runs initialization functions present in initialization if has_initialized is False for this Neighborhood.

order_doors(order: List[str])

Allows the doors to be ordered when called.

If this is never called, the call order will be equivalent to the order in which the doors are added to the Neighborhood. As of right now, all doors present must be included in the order argument or a KeyError will be thrown.

Parameters:

order (list, str) – The order for doors to be called in. Each str must correspond to a key in Neighborhood._doors.

remove_door(name: str)

Removes a Door from _doors.

Parameters:

name (str) – The name of the Door to be removed. It must correspond to a key in Neighborhood._doors attribute.

Raises:

KeyError – If name is not present in _doors attribute.

required_args_present() → bool

Returns True if all the necessary arguments to run all Doors in the Neighborhood object are included in the Neighborhood object.

property required_parameters

Defines parameters that must not be empty at the start of a run for the run to successfully execute.

run_step()

Runs a single step forward for all functions, in specified order, based on the current parameter state of the Neighborhood object.

The way this is currently set up, it will not handle positional arguments. That is, if an input cannot be passed using its variable name, this will break.

run_steps(number_of_steps: int)

This function calls run_step() repeatedly.

It is exactly equivalent to the following code:

set_param(parameter_name: str, new_value: Any, constant: bool = False, *, ignore_constant: bool = False) → Param

Set the value of a parameter to a new value. Since parameters are not meant to be modified like this right now, generate a new parameter.

Parameters:

  • parameter_name (str) – The name of the parameter to modify.

  • new_value (Any) – The value to be assigned to this parameter.

  • constant (bool) – Will be passed to Param as the constant keyword argument.

  • ignore_constant (bool, optional, keyword-only) – When assigning this parameter, it will ignore the constant attribute of the current parameter.

Raises:

ParameterError – Is raised if the parameter attempting to be changed has True for its constant attribute. Will not be raised by this method if ignore_constant is True.

property uninitialized_inputs

Parameters that are inputs to Doors within this Neighborhood with Empty values.

exception porchlight.neighborhood.NeighborhoodError

Bases: Exception