1 files changed, 68 insertions, 0 deletions
diff --git a/lib/ansible/utils/sentinel.py b/lib/ansible/utils/sentinel.py
new file mode 100644
index 0000000..ca4f827
--- /dev/null
+++ b/lib/ansible/utils/sentinel.py
@@ -0,0 +1,68 @@
+# Copyright (c) 2019 Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class Sentinel:
+    """
+    Object which can be used to mark whether an entry as being special
+
+    A sentinel value demarcates a value or marks an entry as having a special meaning.  In C, the
+    Null byte is used as a sentinel for the end of a string.  In Python, None is often used as
+    a Sentinel in optional parameters to mean that the parameter was not set by the user.
+
+    You should use None as a Sentinel value any Python code where None is not a valid entry.  If
+    None is a valid entry, though, then you need to create a different value, which is the purpose
+    of this class.
+
+    Example of using Sentinel as a default parameter value::
+
+        def confirm_big_red_button(tristate=Sentinel):
+            if tristate is Sentinel:
+                print('You must explicitly press the big red button to blow up the base')
+            elif tristate is True:
+                print('Countdown to destruction activated')
+            elif tristate is False:
+                print('Countdown stopped')
+            elif tristate is None:
+                print('Waiting for more input')
+
+    Example of using Sentinel to tell whether a dict which has a default value has been changed::
+
+        values = {'one': Sentinel, 'two': Sentinel}
+        defaults = {'one': 1, 'two': 2}
+
+        # [.. Other code which does things including setting a new value for 'one' ..]
+        values['one'] = None
+        # [..]
+
+        print('You made changes to:')
+        for key, value in values.items():
+            if value is Sentinel:
+                continue
+            print('%s: %s' % (key, value)
+    """
+
+    def __new__(cls):
+        """
+        Return the cls itself.  This makes both equality and identity True for comparing the class
+        to an instance of the class, preventing common usage errors.
+
+        Preferred usage::
+
+            a = Sentinel
+            if a is Sentinel:
+                print('Sentinel value')
+
+        However, these are True as well, eliminating common usage errors::
+
+            if Sentinel is Sentinel():
+                print('Sentinel value')
+
+            if Sentinel == Sentinel():
+                print('Sentinel value')
+        """
+        return cls