grscheller.untyped.nothing

  1# Copyright 2023-2024 Geoffrey R. Scheller
  2#
  3# Licensed under the Apache License, Version 2.0 (the "License");
  4# you may not use this file except in compliance with the License.
  5# You may obtain a copy of the License at
  6#
  7#     http://www.apache.org/licenses/LICENSE-2.0
  8#
  9# Unless required by applicable law or agreed to in writing, software
 10# distributed under the License is distributed on an "AS IS" BASIS,
 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12# See the License for the specific language governing permissions and
 13# limitations under the License.
 14
 15"""#### Singleton Representing a Non-existing Value
 16
 17A version of grscheller.fp.nada geared for use in less strictly
 18typed code.
 19"""
 20
 21from __future__ import annotations
 22from typing import Any, Callable, Iterator, NewType
 23
 24__all__ = [ 'Nothing', 'nothing' ]
 25
 26_S = NewType('_S', tuple[tuple[()], tuple[tuple[()], tuple[tuple[()], None]]])
 27_sentinel: _S = _S(((), ((), ((), None))))
 28
 29class Nothing():
 30    """
 31    #### Singleton semantically represents a missing value.
 32
 33    * singleton nothing: nothing = Nothing() represents a non-existent value
 34    * returns itself for arbitrary method calls
 35    * returns itself if called as a Callable with arbitrary arguments
 36    * interpreted as an empty container by standard Python functions
 37    * comparison ops compare true only when 2 non-missing values compare true
 38      * when compared to itself behaves somewhat like IEEE Float NAN's
 39        * `nothing is nothing` is true
 40        * `nothing == nothing` is false
 41        * `nothing != nothing` is true
 42    """
 43    __slots__ = ()
 44
 45    def __new__(cls) -> Nothing:
 46        if not hasattr(cls, 'instance'):
 47            cls.instance = super(Nothing, cls).__new__(cls)
 48            cls._hash = hash((_sentinel, (_sentinel,)))
 49        return cls.instance
 50
 51    def __iter__(self) -> Iterator:
 52        return iter(())
 53
 54    def __hash__(self) -> int:
 55        return self._hash
 56
 57    def __repr__(self) -> str:
 58        return 'nothing'
 59
 60    def __bool__(self) -> bool:
 61        return False
 62
 63    def __len__(self) -> int:
 64        return 0
 65
 66    def __add__(self, right: Any) -> Nothing:
 67        return Nothing()
 68
 69    def __radd__(self, left: Any) -> Nothing:
 70        return Nothing()
 71
 72    def __mul__(self, right: Any) -> Nothing:
 73        return Nothing()
 74
 75    def __rmul__(self, left: Any) -> Nothing:
 76        return Nothing()
 77
 78    def __eq__(self, right: Any) -> bool:
 79        """Never equals anything, even itself."""
 80        return False
 81
 82    def __ne__(self, right: Any) -> bool:
 83        """Always does not equal anything, even itself."""
 84        return True
 85
 86    def __ge__(self, right: Any) -> bool:
 87        return False
 88
 89    def __gt__(self, right: Any) -> bool:
 90        return False
 91
 92    def __le__(self, right: Any) -> bool:
 93        return False
 94
 95    def __lt__(self, right: Any) -> bool:
 96        return False
 97
 98    def __getitem__(self, index: int|slice) -> Any:
 99        return Nothing()
100
101    def __setitem__(self, index: int|slice, item: Any) -> None:
102        return
103
104    def __call__(*args: Any, **kwargs: Any) -> Any:
105        return Nothing()
106
107  # def __getattr__(self, name: str) -> Callable[[Any], Any]:
108  #     """Comment out for doc generation, pdoc gags on this method."""
109  #     def method(*args: Any, **kwargs: Any) -> Any:
110  #         return Nothing()
111  #     return method
112
113    def get(self, alt: Any=_sentinel) -> Any:
114        """
115        ##### Get an alternate value, defaults to Nada().
116        """
117        if alt == _sentinel:
118            return Nothing()
119        else:
120            return alt
121
122nothing = Nothing()