diff --git a/toyrobot/robot.py b/toyrobot/robot.py index 148ad15..90fa5f1 100644 --- a/toyrobot/robot.py +++ b/toyrobot/robot.py @@ -1,15 +1,16 @@ class Robot: """ - Class representing a single "Toy Robot". Robots instances have knowledge of their - position, direction, and movement limits. + Class representing a single "Toy Robot". Robots instances have knowledge + of their position, direction, and movement limits. Attributes: - DEFAULT_MAX_X (int): The default maximum allowable horizontal coordinate - (inclusive). + DEFAULT_MAX_X (int): The default maximum allowable horizontal + coordinate (inclusive). DEFAULT_MAX_Y (int): The default maximum allowable vertical coordinate (inclusive). - DIRECTIONS (dict): A dictionary (str: int) of direction names (e.g. NORTH, EAST - etc) and their numerical encoding. Only the keys are intended for use externally as a list of valid directions. + DIRECTIONS (dict): A dictionary (str: int) of direction names (e.g. + NORTH, EAST etc) and their numerical encoding. Only the keys are + intended for use externally as a list of valid directions. """ DEFAULT_MAX_X = 5 @@ -25,8 +26,8 @@ class Robot: # Private internals # Key corresponds to numerical direction defined in Robot.directions - # Value is an offset vector in with x and y keys (positive x is NORTH, positive y is - # EAST) + # Value is an offset vector in with x and y keys (positive x is NORTH, + # positive y is EAST) _MOVEMENT_VECTORS = { 0: {"x": 0, "y": 1}, 1: {"x": 1, "y": 0}, @@ -36,18 +37,18 @@ class Robot: def __init__(self, max_x: int = DEFAULT_MAX_X, max_y: int = DEFAULT_MAX_Y): """ - Creates a new Robot instance with the specified position limits (optional). - Implicitly, the minimum limit on coordinates is 0 both horizontally and - vertically. + Creates a new Robot instance with the specified position limits + (optional). Implicitly, the minimum limit on coordinates is 0 both + horizontally and vertically. - See the class attributes `DEFAULT_MAX_X` and `DEFAULT_MAX_Y` for the respective - default numerical values. + See the class attributes `DEFAULT_MAX_X` and `DEFAULT_MAX_Y` for the + respective default numerical values. Args: - max_x (int): The maximum allowable horizontal coordinate (inclusive, - positive is EAST). - max_y (int): The maximum allowable vertical coordinate (inclusive, - positive is NORTH). + max_x (int): The maximum allowable horizontal coordinate + (inclusive, positive is EAST). + max_y (int): The maximum allowable vertical coordinate + (inclusive, positive is NORTH). Raises: ValueError: If max_x or max_y are less than 0. @@ -86,18 +87,18 @@ class Robot: Returns the current maximum coordinates valid for this instance. Returns: - (int, int): A tuple of the maximum coordinates in the order (maximum_x, - maximum y). + (int, int): A tuple of the maximum coordinates in the order + (maximum_x, maximum y). """ return (self._max_x, self._max_y) def valid_position(self, x: int, y: int) -> bool: """ - Calculates whether the given coordinates are valid for the limits set on this - Robot instance. + Calculates whether the given coordinates are valid for the limits set + on this Robot instance. - This function is used by the `move()` function to verify that a move action - would be successful. + This function is used by the `move()` function to verify that a move + action would be successful. Args: x: Proposed horizontal coordinate. @@ -111,11 +112,11 @@ class Robot: def is_initialized(self): """ - Returns whether this Robot instance has been initialized (i.e. whether a valid - `place()` command has been executed). + Returns whether this Robot instance has been initialized (i.e. whether + a valid `place()` command has been executed). - This function is used by the `move()` function to verify that the instance has - been correctly placed before movement. + This function is used by the `move()` function to verify that the + instance has been correctly placed before movement. Returns: bool: True if correctly initialized, otherwise false. @@ -128,11 +129,12 @@ class Robot: def move(self): """ - Moves the robot one space in the direction it is currently facing, provided that - said movement would be within limits. + Moves the robot one space in the direction it is currently facing, + provided that said movement would be within limits. - Will do nothing if this Robot instance has not been initialized successfully - with `place()` or the specified movement would be out of bounds. + Will do nothing (fail silently) if this Robot instance has not been + initialized successfully with `place()` or the specified movement would + be out of bounds. """ if not self.is_initialized(): @@ -150,24 +152,23 @@ class Robot: def place(self, position_x: int, position_y: int, direction_name: str): """ - Places the Robot instance at the specified coordinates with the specified - direction. + Places the Robot instance at the specified coordinates with the + specified direction. - Will do nothing if the given coordinates are out of bounds, or the direction is - not one of the keys in `Robot.DIRECTIONS`. + Will do nothing if the given coordinates are out of bounds, or the + direction is not one of the keys in `Robot.DIRECTIONS`. See `__init__()` for detailed coordinate information. Args: position_x (int): Horizontal coordinate for placement. position_y (int): Vertical coordinate for placement. - direction_name (str): Direction of placement; must be one of the string keys - in `Robot.DIRECTIONS`. + direction_name (str): Direction of placement; must be one of the + string keys in `Robot.DIRECTIONS`. """ direction_name = direction_name.upper() - if direction_name not in Robot.DIRECTIONS.keys() or not self.valid_position( - position_x, position_y - ): + if direction_name not in Robot.DIRECTIONS.keys() or \ + not self.valid_position(position_x, position_y): return self._position_x = position_x @@ -179,9 +180,9 @@ class Robot: Returns the current position of this Robot instance. Returns: - (int, int): A tuple with this instance's current coordinates in the order - (position_x, position_y), or (None, None) if this instance has not yet - been initialized. + (int, int): A tuple with this instance's current coordinates in the + order (position_x, position_y), or (None, None) if this + instance has not yet been initialized. """ return ( (self._position_x, self._position_y) @@ -191,12 +192,13 @@ class Robot: def get_direction(self) -> str: """ - Returns the direction in which this instance is currently facing in string form. + Returns the direction in which this instance is currently facing in + string form. Returns: - str: The current direction of this instance; will be one of the keys of - `Robot.DIRECTION`. Will return None if this instance has not yet been - initialized. + str: The current direction of this instance; will be one of the + keys of `Robot.DIRECTION`. Will return None if this instance + has not yet been initialized. """ return ( {v: k for k, v in Robot.DIRECTIONS.items()}[self._direction] @@ -206,10 +208,11 @@ class Robot: def rotate_left(self): """ - Rotates this Robot instance's direction to the LEFT. For example, if currently - facing NORTH, the new direction will be WEST. + Rotates this Robot instance's direction to the LEFT. For example, if + currently facing NORTH, the new direction will be WEST. - Does nothing if this instance has not yet been correctly placed (initialized). + Does nothing if this instance has not yet been correctly placed + (initialized). """ if not self.is_initialized(): return @@ -217,10 +220,11 @@ class Robot: def rotate_right(self): """ - Rotates this Robot instance's direction to the RIGHT. For example, if currently - facing NORTH, the new direction will be EAST. + Rotates this Robot instance's direction to the RIGHT. For example, if + currently facing NORTH, the new direction will be EAST. - Does nothing if this instance has not yet been correctly placed (initialized). + Does nothing if this instance has not yet been correctly placed + (initialized). """ if self.is_initialized(): return