mirror of https://github.com/ansible/ansible.git
Use sentinel everywhere (#84041)
* Use sentinel everywhere Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>pull/84043/head
Abhijeet Kasurde
2 months ago
committed by
GitHub
parent
9abc651cd6
commit
b3c4154e86
@ -0,0 +1,66 @@
|
||||
# Copyright (c) 2019 Ansible Project
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
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
|
||||
@ -1,66 +1,8 @@
|
||||
# Copyright (c) 2019 Ansible Project
|
||||
# -*- coding: utf-8 -*-
|
||||
# Copyright: Contributors to the Ansible project
|
||||
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
|
||||
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
|
||||
# For Backward compatibility
|
||||
from ansible.module_utils.common.sentinel import Sentinel # pylint: disable=unused-import
|
||||
|
||||
Loading…
Reference in New Issue