feat: reverse parameters of SentinelValue() constructor

BREAKING CHANGE: SentinelValue() parameter order is different now:

Previously it was:

    SentinelValue(instance_name, module_name)

and now it is:

    SentinelValue(module_name, instance_name)

because the latter is more natural, and also opens possibility
for a little bit of extension in the future.

This is the last major change in the API, I'm going to freeze it,
so here I'm also triggering release of v.1.0.0
(by removing `major_on_zero = false` from `pyproject.toml`)

Author: vdmit11

README.rst

@@ -40,7 +40,7 @@ Or, the same thing, but using the ``SentinelValue`` class
   class Missing(SentinelValue):
       pass
 
-  MISSING = Missing("MISSING", __name__)
+  MISSING = Missing(__name__, "MISSING")
 
   def get_something(default: Union[str, Missing] = MISSING):
       ...

docs/index.rst

@@ -68,7 +68,7 @@ A little bit more advanced way to create sentinel objects is to do this::
   >>> class Missing(SentinelValue):
   ...     pass
 
-  >>> MISSING = Missing("MISSING", __name__)
+  >>> MISSING = Missing(__name__, "MISSING")
 
 Such code is slightly more verbose (than using :func:`sentinel`), but, there are some benefits:
 
@@ -118,7 +118,7 @@ and instead make your own sub-classes of :class:`SentinelValue`, like this::
   >>> class NotGiven(SentinelValue):
   ...     pass
 
-  >>> NOT_GIVEN = NotGiven("NOT_GIVEN", __name__)
+  >>> NOT_GIVEN = NotGiven(__name__, "NOT_GIVEN")
 
   >>> def foo(value: Union[int, NotGiven]) -> None:
   ...     return None
@@ -140,7 +140,7 @@ or, when subclassing :class:`SentinelValue`:
   >>> class NotSet(SentinelValue):
   ...     pass
 
-  >>> NOT_SET = NotSet("NOT_SET", __name__)
+  >>> NOT_SET = NotSet(__name__, "NOT_SET")
 
 Why? Because:
 

pyproject.toml

@@ -67,7 +67,6 @@ version_toml = "pyproject.toml:tool.poetry.version"
 upload_to_pypi = true
 upload_to_release = true
 build_command = "poetry build"
-major_on_zero = false
 
 [tool.pytest.ini_options]
 norecursedirs = "build dist .tox"

sentinel_value/sentinel_value.py

@@ -10,7 +10,7 @@ class SentinelValue:
     Useful for distinguishing "value is not set" and "value is set to None" cases
     as shown in this example::
 
-        >>> NOT_SET = SentinelValue("NOT_SET", __name__)
+        >>> NOT_SET = SentinelValue(__name__, "NOT_SET")
 
         >>> value = getattr(object, "some_attribute", NOT_SET)
         >>> if value is NOT_SET:
@@ -25,7 +25,7 @@ class SentinelValue:
         >>> class Missing(SentinelValue):
         ...     pass
 
-        >>> MISSING = Missing("MISSING", __name__)
+        >>> MISSING = Missing(__name__, "MISSING")
 
         # Here is how the Missing class can be used for type hinting.
         >>> value: Union[str, None, Missing] = getattr(object, "some_attribute", MISSING)
@@ -34,12 +34,12 @@ class SentinelValue:
         value is missing
     """
 
-    def __init__(self, instance_name: str, module_name: str) -> None:
+    def __init__(self, module_name: str, instance_name: str) -> None:
         """Initialize :class:`SentinelValue` object.
 
-        :param instance_name: name of Python variable that points to the sentinel value.
         :param module_name: name of Python module that hosts the sentinel value.
                             In the majority of cases you should pass ``__name__`` here.
+        :param instance_name: name of Python variable that points to the sentinel value.
         """
         assert not ((module_name == self.__module__) and (instance_name == self.__class__.__name__))
 
@@ -49,7 +49,7 @@ def __init__(self, instance_name: str, module_name: str) -> None:
 
         super().__init__()
 
-    def __new__(cls, instance_name, module_name):
+    def __new__(cls, module_name, instance_name):
         """Create 1 instance of SentinelValue per name.
 
         Usually, when you call a class, you expect to get a new instance on each call.
@@ -64,8 +64,8 @@ def __new__(cls, instance_name, module_name):
         That is, if you call :class:`SentinelValue` multiple times with the same arguments,
         you get the *exactly same* instance, check this out::
 
-          >>> MISSING1 = SentinelValue("MISSING", __name__)
-          >>> MISSING2 = SentinelValue("MISSING", __name__)
+          >>> MISSING1 = SentinelValue(__name__, "MISSING")
+          >>> MISSING2 = SentinelValue(__name__, "MISSING")
 
           >>> MISSING1 is MISSING2
           True
@@ -124,7 +124,7 @@ def __getnewargs__(self):
         # This is needed for pickle serialization.
         # In combination with magic in the overriden __new__() method above,
         # that allows to avoid constructing duplicates when un-pickling the object.
-        return (self.instance_name, self.module_name)
+        return (self.module_name, self.instance_name)
 
     @staticmethod
     def _compose_qualified_name(instance_name: str, module_name: str) -> str:
@@ -153,7 +153,7 @@ def __bool__():
         So it is often handy to do ``if not value`` to check if there is no value
         (like if an attribute is set to ``None``, or not set at all)::
 
-           >>> NOT_SET = SentinelValue("NOT_SET", __name__)
+           >>> NOT_SET = SentinelValue(__name__, "NOT_SET")
 
            >>> value = getattr(object, "foobar", NOT_SET)
 
@@ -173,9 +173,9 @@ def __bool__():
 This dictionary looks like this::
 
   {
-      "package1.module1.MISSING": SentinelValue("MISSING", module_name="package1.module1.MISSING"),
-      "package2.module2.MISSING": SentinelValue("MISSING", module_name="package2.module2.MISSING"),
-      "package2.module2.ABSENT": SentinelValue("ABSENT", module_name="package2.module2.ABSENT"),
+      "package1.module1.MISSING": SentinelValue("package1.module1", "MISSING"),
+      "package2.module2.MISSING": SentinelValue("package2.module2", "MISSING"),
+      "package2.module2.ABSENT": SentinelValue("package2.module2", "ABSENT"),
   }
 
 When a :class:`SentinelValue` object is instanciated, it registers itself in this dictionary
@@ -228,12 +228,12 @@ def sentinel(
     module_name = _get_caller_module_name()
     assert module_name
 
-    SentinelValueSubclass = _create_sentinel_value_subclass(instance_name, module_name)
+    SentinelValueSubclass = _create_sentinel_value_subclass(module_name, instance_name)
 
     if repr:
         SentinelValueSubclass.__repr__ = lambda self: repr  # type: ignore
 
-    return SentinelValueSubclass(instance_name, module_name)
+    return SentinelValueSubclass(module_name, instance_name)
 
 
 def _get_caller_module_name() -> Optional[str]:
@@ -253,7 +253,7 @@ def _get_caller_module_name() -> Optional[str]:
     return None
 
 
-def _create_sentinel_value_subclass(instance_name: str, module_name: str) -> Type[SentinelValue]:
+def _create_sentinel_value_subclass(module_name: str, instance_name: str) -> Type[SentinelValue]:
     module = sys.modules[module_name]
 
     # Genarate class name from variable name.

tests/test_sentinel_value.py

@@ -14,44 +14,44 @@ def cleanup_sentinel_value_instances_after_each_test():
 
 
 def test__SentinelValue__str_and_repr():
-    MISSING = SentinelValue("MISSING", "some.module2")
+    MISSING = SentinelValue("some.module2", "MISSING")
     assert str(MISSING) == "<MISSING>"
     assert repr(MISSING) == "<MISSING>"
 
 
 def test__SentinelValue__is_falsy():
-    MISSING = SentinelValue("MISSING", "some.module3")
+    MISSING = SentinelValue("some.module3", "MISSING")
     assert not bool(MISSING)
 
 
 def test__SentinelValue_creates_new_instance_only_once_per_name():
-    MISSING = SentinelValue("MISSING", "some.module")
+    MISSING = SentinelValue("some.module", "MISSING")
 
-    MISSING_duplicate = SentinelValue("MISSING", "some.module")
+    MISSING_duplicate = SentinelValue("some.module", "MISSING")
     assert MISSING is MISSING_duplicate
 
-    MISSING2 = SentinelValue("MISSING2", "some.module")
+    MISSING2 = SentinelValue("some.module", "MISSING2")
     assert MISSING is not MISSING2
 
-    MISSING_in_other_module = SentinelValue("MISSING", "some.module2")
+    MISSING_in_other_module = SentinelValue("some.module2", "MISSING")
     assert MISSING is not MISSING_in_other_module
 
 
 def test__SentinelValue_can_change_class_on_the_fly():
-    MISSING = SentinelValue("MISSING", __name__)
+    MISSING = SentinelValue(__name__, "MISSING")
     assert MISSING.__class__ is SentinelValue
 
     class Missing(SentinelValue):
         pass
 
-    MISSING_redefined = Missing("MISSING", __name__)
+    MISSING_redefined = Missing(__name__, "MISSING")
 
     assert MISSING_redefined is MISSING
     assert MISSING_redefined.__class__ is Missing
 
 
 def test__SentinelValue_is_pickleable():
-    MISSING = SentinelValue("MISSING", __name__)
+    MISSING = SentinelValue(__name__, "MISSING")
     MISSING_unpickled = pickle.loads(pickle.dumps(MISSING))
     assert MISSING_unpickled is MISSING
 
@@ -61,7 +61,7 @@ class NoValue(SentinelValue):
 
 
 def test__SentinelValueSubclass_is_pickleable():
-    NO_VALUE = NoValue("NO_VALUE", __name__)
+    NO_VALUE = NoValue(__name__, "NO_VALUE")
     NO_VALUE_unpickled = pickle.loads(pickle.dumps(NO_VALUE))
     assert NO_VALUE_unpickled is NO_VALUE
 
@@ -70,8 +70,8 @@ def test__SentinelValue__remains_singleton__when_copied():
     class Missing(SentinelValue):
         pass
 
-    DELETED = Missing("DELETED", __name__)
-    NEVER_SET = Missing("NEVER_SET", __name__)
+    DELETED = Missing(__name__, "DELETED")
+    NEVER_SET = Missing(__name__, "NEVER_SET")
 
     DELETED_copy = copy(DELETED)
     assert DELETED_copy is DELETED