mirror of https://github.com/ansible/ansible.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
69 lines
2.4 KiB
Python
69 lines
2.4 KiB
Python
# 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
|