Merge pull request faif#322 from h4ppysmile/patch-1

changing description and example to add more clarification

Author: faif

patterns/behavioral/command.py

@@ -1,61 +1,101 @@
 """
+Command pattern decouples the object invoking a job from the one who knows
+how to do it. As mentioned in the GoF book, a good example is in menu items.
+You have a menu that has lots of items. Each item is responsible for doing a
+special thing and you want your menu item just call the execute method when
+it is pressed. To achieve this you implement a command object with the execute
+method for each menu item and pass to it.
+
+*About the example
+We have a menu containing two items. Each item accepts a file name, one hides the file
+and the other deletes it. Both items have an undo option.
+Each item is a MenuItem class that accepts the corresponding command as input and executes
+it's execute method when it is pressed.
+
 *TL;DR
-Encapsulates all information needed to perform an action or trigger an event.
+Object oriented implementation of callback functions.
 
 *Examples in Python ecosystem:
-Django HttpRequest (without `execute` method):
-https://docs.djangoproject.com/en/2.1/ref/request-response/#httprequest-objects
+Django HttpRequest (without execute method):
+https://docs.djangoproject.com/en/2.1/ref/request-response/#httprequest-objects
 """
 
-importos
 
+classHideFileCommand:
+"""
+ A command to hide a file given its name
+ """
 
-classMoveFileCommand:
-def__init__(self, src, dest):
-self.src=src
-self.dest=dest
+def__init__(self):
+# an array of files hidden, to undo them as needed
+self._hidden_files= []
 
-defexecute(self):
-self.rename(self.src, self.dest)
+defexecute(self, filename):
+print(f'hiding {filename}')
+self._hidden_files.append(filename)
 
 defundo(self):
-self.rename(self.dest, self.src)
+filename=self._hidden_files.pop()
+print(f'un-hiding {filename}')
+
+
+classDeleteFileCommand:
+"""
+ A command to delete a file given its name
+ """
+
+def__init__(self):
+# an array of deleted files, to undo them as needed
+self._deleted_files= []
+
+defexecute(self, filename):
+print(f'deleting {filename}')
+self._deleted_files.append(filename)
 
-defrename(self, src, dest):
-print("renaming{} to{}".format(src, dest))
-os.rename(src, dest)
+defundo(self):
+filename=self._deleted_files.pop()
+print(f'restoring {filename}')
+
+
+classMenuItem:
+"""
+ The invoker class. Here it is items in a menu.
+ """
+
+def__init__(self, command):
+self._command=command
+
+defon_do_press(self, filename):
+self._command.execute(filename)
+
+defon_undo_press(self):
+self._command.undo()
 
 
 defmain():
 """
- >>> from os.path import lexists
-
- >>> command_stack = [
- ... MoveFileCommand('foo.txt', 'bar.txt'),
- ... MoveFileCommand('bar.txt', 'baz.txt')
- ... ]
-
- # Verify that none of the target files exist
- >>> assert not lexists("foo.txt")
- >>> assert not lexists("bar.txt")
- >>> assert not lexists("baz.txt")
-
- # Create empty file
- >>> open("foo.txt", "w").close()
-
- # Commands can be executed later on
- >>> for cmd in command_stack:
- ... cmd.execute()
- renaming foo.txt to bar.txt
- renaming bar.txt to baz.txt
-
- # And can also be undone at will
- >>> for cmd in reversed(command_stack):
- ... cmd.undo()
- renaming baz.txt to bar.txt
- renaming bar.txt to foo.txt
-
- >>> os.unlink("foo.txt")
+ >>> item1 = MenuItem(DeleteFileCommand())
+
+ >>> item2 = MenuItem(HideFileCommand())
+
+ # create a file named `test-file` to work with
+ >>> test_file_name = 'test-file'
+
+ # deleting `test-file`
+ >>> item1.on_do_press(test_file_name)
+ deleting test-file
+
+ # restoring `test-file`
+ >>> item1.on_undo_press()
+ restoring test-file
+
+ # hiding `test-file`
+ >>> item2.on_do_press(test_file_name)
+ hiding test-file
+
+ # un-hiding `test-file`
+ >>> item2.on_undo_press()
+ un-hiding test-file
  """