classicist 1.0.4__tar.gz → 1.0.5__tar.gz

{classicist-1.0.4/source/classicist.egg-info → classicist-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classicist
-Version: 1.0.4
+Version: 1.0.5
 Summary: Classy class decorators for Python.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -33,17 +33,20 @@ Dynamic: license-file
 
 # Classicist: Classy Class Decorators & Extensions
 
-The Classicist library provides several useful decorators and helper methods including:
+The Classicist library provides several useful decorators, functions, classes, and types
+that offer useful behaviours and functionality, and help to fill some of the gaps in the
+current standard library:
 
  * `@hybridmethod` – a decorator that allows methods to be used both as class methods and as instance methods;
- * `@classproperty` – a decorator that allow class methods to be accessed as class properties;
+ * `@classproperty` – a decorator that allows class methods to be accessed as class properties;
  * `@annotation` – a decorator that can be used to apply arbitrary annotations to code objects;
- * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated;
+ * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated, with support for adding optional arbitrary annotations;
  * `@alias` – a decorator that can be used to add aliases to classes, methods defined within classes, module-level functions, and nested functions when overriding the aliasing scope;
  * `@nocache` – a decorator that can be used to mark functions and methods as not being suitable for caching;
- * `@runtimer` – a decorator that can be used to time function and method calls;
+ * `@runtimer` – a decorator that can be used to gather call run time information for function and method calls;
  * `shadowproof` – a metaclass that can be used to protect subclasses from class-level attributes
-  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases.
+  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases;
+* `Null` – an alternative to `None`, useful when building custom data model classes and libraries, where supporting "null-safe" style access and navigation of the model's nested hierarchy is preferred.
 
 The `classicist` library was previously named `hybridmethod` so if a prior version had
 been installed, please update references to the new library name. Installation of the
@@ -554,6 +557,146 @@ except AttributeShadowingError as exception:
     pass
 ```
 
+#### NullType: Null-Safe Style Access for Data Models and Nested Class Hierarchies
+
+The `NullType` class supports the creation of a `Null` singleton instance that offers
+support for safely chaining nested attribute accesses without raising exceptions for
+attributes that have no inherent value.
+
+As Python currently lacks a null-aware navigation operator, such as `?.`, unlike many
+other dynamic languages, for safely navigating nested object hierarchies which may
+contain null attributes, the library offers the `NullType` and `Null` singleton as a
+potential option to support this need in the interim. Consistent use of the `Null`
+singleton in place of the standard `None` singleton, in relevant scenarios, such as
+within a custom data model library, can allow for more expressive and clearer code that
+does not require endless checks for intermediary or nested attribute existence.
+
+However, there are some caveats to the use of the `NullType` and `Null` singleton as
+these are not built-in features of the language, and Python does not offer support for
+the creation of custom operators nor overriding the `is` operator for identity checking
+which limits some of the use cases in which the `Null` singleton can be used.
+
+With knowledge of these caveats and in the right scenarios, the `Null` singleton can
+offer a good way to achieve clearer and more expressive code while navigating nested
+object hierarchies without the clutter of nested attribute existence checks.
+
+```python
+from __future__ import annotations
+
+from classicist import Null
+
+data: dict = {
+  "id": 1,
+  "name": "A",
+  "related": {
+    "id": 2,
+    "name": "B",
+    "related": {
+      "id": 3,
+      "name": "C",
+    },
+  },
+}
+
+class Model(object):
+  """Sample Model class with some properties that reference nested Model instances."""
+
+  def __init__(self, data: dict):
+    if not isinstance(data, dict):
+      raise TypeError("The 'data' argument must reference a valid data dictionary!")
+
+    if not ("id" in data and isinstance(data["id"], int)):
+      raise ValueError("The 'data' must contain an 'id' key with an integer value!")
+
+    if not ("name" in data and isinstance(data["name"], str)):
+      raise ValueError("The 'data' must contain an 'name' key with an string value!")
+
+    self.data = data
+
+  @property
+  def id(self) -> int:
+    return self.data["id"]
+
+  @property
+  def name(self) -> str:
+    return self.data["name"]
+
+  @property
+  def related(self) -> Model | Null:
+    if data := self.data.get("related"):
+      return Model(data=data)
+    else:
+      return Null
+
+  @property
+  def relates(self) -> Model | Null:
+    if data := self.data.get("relates"):
+      return Model(data=data)
+    else:
+      return Null
+
+# Create an instance of the sample Model data class
+model = Model(data=data)
+
+# Check that the expected data attributes are available
+assert model.id == 1
+assert model.name == "A"
+
+# The model.related property references A/1 in the data above, so these properties exist
+assert model.related
+assert model.related.id
+assert model.related.name
+
+# Ensure the nested property values are as expected
+assert model.related.id == 2
+assert model.related.name == "B"
+
+# Note that model.relates had no corresponding data, so the Model returns `Null` which
+# still allows for nested attribute access, such as to `.id` and `.name` without raising
+# any exceptions; the `Null` singleton also allows for `bool` comparison as shown below:
+assert not model.relates
+assert not model.relates.id
+assert not model.relates.name
+
+# There is no limit to the levels of nesting that `NullType` and the `Null` singleton
+# can support, so long as a custom data model or library consistently returns `Null` for
+# cases where the "null-safe" navigation is desired:
+
+# model.related.related references 3/C in the data above, so these properties exist
+assert model.related.related.id
+assert model.related.related.name
+
+# model.related.relates was not specified in the data above so the Model returns `Null`
+assert not model.related.relates.id
+assert not model.related.relates.name
+
+# Ensure the nested property values are as expected
+assert model.related.related.id == 3
+assert model.related.related.name == "C"
+
+# These features make it easy to write clearer more expressive code without boilerplate
+# code to check for the availability of nested attributes or entities:
+if isinstance(name := model.related.name, str):
+  print("model.related.name => %s" % (name))
+
+# No exception is raised here even though model.relates is effectively "null":
+if isinstance(name := model.relates.name, str):
+  print("model.relates.name => %s" % (name))
+
+# However, there are some caveats as noted with `NullType` and the `Null` singleton as
+# these are a third-party solution so we can only go so far in supplementing null-safe
+# operator behaviour in the language; for example, we cannot perform identity checks to
+# boolean values, True or False, or the actual None singleton value:
+assert not model.relates is True  # Notice the `assert not` as `assert` would fail here
+assert not model.relates is False  # Notice the `assert not` as `assert` would fail here
+
+# Furthermore, we cannot use `None` identity comparison either:
+assert not model.relates is None  # Notice the `assert not` as `assert` would fail here
+
+# We can however perform an identity check against the `Null` singleton if needed:
+assert model.relates is Null
+```
+
 ### Unit Tests
 
 The Classicist library includes a suite of comprehensive unit tests which ensure that

{classicist-1.0.4 → classicist-1.0.5}/README.md

@@ -1,16 +1,19 @@
 # Classicist: Classy Class Decorators & Extensions
 
-The Classicist library provides several useful decorators and helper methods including:
+The Classicist library provides several useful decorators, functions, classes, and types
+that offer useful behaviours and functionality, and help to fill some of the gaps in the
+current standard library:
 
  * `@hybridmethod` – a decorator that allows methods to be used both as class methods and as instance methods;
- * `@classproperty` – a decorator that allow class methods to be accessed as class properties;
+ * `@classproperty` – a decorator that allows class methods to be accessed as class properties;
  * `@annotation` – a decorator that can be used to apply arbitrary annotations to code objects;
- * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated;
+ * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated, with support for adding optional arbitrary annotations;
  * `@alias` – a decorator that can be used to add aliases to classes, methods defined within classes, module-level functions, and nested functions when overriding the aliasing scope;
  * `@nocache` – a decorator that can be used to mark functions and methods as not being suitable for caching;
- * `@runtimer` – a decorator that can be used to time function and method calls;
+ * `@runtimer` – a decorator that can be used to gather call run time information for function and method calls;
  * `shadowproof` – a metaclass that can be used to protect subclasses from class-level attributes
-  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases.
+  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases;
+* `Null` – an alternative to `None`, useful when building custom data model classes and libraries, where supporting "null-safe" style access and navigation of the model's nested hierarchy is preferred.
 
 The `classicist` library was previously named `hybridmethod` so if a prior version had
 been installed, please update references to the new library name. Installation of the
@@ -521,6 +524,146 @@ except AttributeShadowingError as exception:
     pass
 ```
 
+#### NullType: Null-Safe Style Access for Data Models and Nested Class Hierarchies
+
+The `NullType` class supports the creation of a `Null` singleton instance that offers
+support for safely chaining nested attribute accesses without raising exceptions for
+attributes that have no inherent value.
+
+As Python currently lacks a null-aware navigation operator, such as `?.`, unlike many
+other dynamic languages, for safely navigating nested object hierarchies which may
+contain null attributes, the library offers the `NullType` and `Null` singleton as a
+potential option to support this need in the interim. Consistent use of the `Null`
+singleton in place of the standard `None` singleton, in relevant scenarios, such as
+within a custom data model library, can allow for more expressive and clearer code that
+does not require endless checks for intermediary or nested attribute existence.
+
+However, there are some caveats to the use of the `NullType` and `Null` singleton as
+these are not built-in features of the language, and Python does not offer support for
+the creation of custom operators nor overriding the `is` operator for identity checking
+which limits some of the use cases in which the `Null` singleton can be used.
+
+With knowledge of these caveats and in the right scenarios, the `Null` singleton can
+offer a good way to achieve clearer and more expressive code while navigating nested
+object hierarchies without the clutter of nested attribute existence checks.
+
+```python
+from __future__ import annotations
+
+from classicist import Null
+
+data: dict = {
+  "id": 1,
+  "name": "A",
+  "related": {
+    "id": 2,
+    "name": "B",
+    "related": {
+      "id": 3,
+      "name": "C",
+    },
+  },
+}
+
+class Model(object):
+  """Sample Model class with some properties that reference nested Model instances."""
+
+  def __init__(self, data: dict):
+    if not isinstance(data, dict):
+      raise TypeError("The 'data' argument must reference a valid data dictionary!")
+
+    if not ("id" in data and isinstance(data["id"], int)):
+      raise ValueError("The 'data' must contain an 'id' key with an integer value!")
+
+    if not ("name" in data and isinstance(data["name"], str)):
+      raise ValueError("The 'data' must contain an 'name' key with an string value!")
+
+    self.data = data
+
+  @property
+  def id(self) -> int:
+    return self.data["id"]
+
+  @property
+  def name(self) -> str:
+    return self.data["name"]
+
+  @property
+  def related(self) -> Model | Null:
+    if data := self.data.get("related"):
+      return Model(data=data)
+    else:
+      return Null
+
+  @property
+  def relates(self) -> Model | Null:
+    if data := self.data.get("relates"):
+      return Model(data=data)
+    else:
+      return Null
+
+# Create an instance of the sample Model data class
+model = Model(data=data)
+
+# Check that the expected data attributes are available
+assert model.id == 1
+assert model.name == "A"
+
+# The model.related property references A/1 in the data above, so these properties exist
+assert model.related
+assert model.related.id
+assert model.related.name
+
+# Ensure the nested property values are as expected
+assert model.related.id == 2
+assert model.related.name == "B"
+
+# Note that model.relates had no corresponding data, so the Model returns `Null` which
+# still allows for nested attribute access, such as to `.id` and `.name` without raising
+# any exceptions; the `Null` singleton also allows for `bool` comparison as shown below:
+assert not model.relates
+assert not model.relates.id
+assert not model.relates.name
+
+# There is no limit to the levels of nesting that `NullType` and the `Null` singleton
+# can support, so long as a custom data model or library consistently returns `Null` for
+# cases where the "null-safe" navigation is desired:
+
+# model.related.related references 3/C in the data above, so these properties exist
+assert model.related.related.id
+assert model.related.related.name
+
+# model.related.relates was not specified in the data above so the Model returns `Null`
+assert not model.related.relates.id
+assert not model.related.relates.name
+
+# Ensure the nested property values are as expected
+assert model.related.related.id == 3
+assert model.related.related.name == "C"
+
+# These features make it easy to write clearer more expressive code without boilerplate
+# code to check for the availability of nested attributes or entities:
+if isinstance(name := model.related.name, str):
+  print("model.related.name => %s" % (name))
+
+# No exception is raised here even though model.relates is effectively "null":
+if isinstance(name := model.relates.name, str):
+  print("model.relates.name => %s" % (name))
+
+# However, there are some caveats as noted with `NullType` and the `Null` singleton as
+# these are a third-party solution so we can only go so far in supplementing null-safe
+# operator behaviour in the language; for example, we cannot perform identity checks to
+# boolean values, True or False, or the actual None singleton value:
+assert not model.relates is True  # Notice the `assert not` as `assert` would fail here
+assert not model.relates is False  # Notice the `assert not` as `assert` would fail here
+
+# Furthermore, we cannot use `None` identity comparison either:
+assert not model.relates is None  # Notice the `assert not` as `assert` would fail here
+
+# We can however perform an identity check against the `Null` singleton if needed:
+assert model.relates is Null
+```
+
 ### Unit Tests
 
 The Classicist library includes a suite of comprehensive unit tests which ensure that

{classicist-1.0.4 → classicist-1.0.5}/source/classicist/__init__.py

@@ -49,6 +49,11 @@ from classicist.exceptions import (
     AttributeShadowingError,
 )
 
+from classicist.types import (
+    NullType,
+    Null,
+)
+
 __all__ = [
     # Decorators
     "alias",
@@ -75,4 +80,7 @@ __all__ = [
     "AliasError",
     "AnnotationError",
     "AttributeShadowingError",
+    # Types
+    "NullType",
+    "Null",
 ]

classicist-1.0.5/source/classicist/types/__init__.py

@@ -0,0 +1,6 @@
+from classicist.types.null import NullType, Null
+
+__all__ = [
+    "NullType",
+    "Null",
+]

classicist-1.0.5/source/classicist/types/null/__init__.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+
+class NullType(object):
+    """The NullType class supports the creation of a Null singleton instance that offers
+    support for safely chaining nested attribute accesses without raising exceptions for
+    attributes that have no inherent value.
+
+    As Python currently lacks a null-aware navigation operator, such as `?.`, like many
+    other dynamic languages, for safely navigating nested object hierarchies which may
+    contain null attributes, the library offers the `NullType` and `Null` singleton as a
+    potential option to support this need in the interim. Consistent use of the `Null`
+    singleton in place of the standard `None` singleton, in relevant scenarios, such as
+    within a data model library for example, can allow for more expressive and clearer
+    code that does not require endless checks for intermediary attribute existence.
+
+    However, there are some caveats to the use of the `NullType` and `Null` singleton as
+    these are not built-in features of the language, and Python does not offer support
+    for the creation of custom operators nor overriding the `is` operator for identity
+    checking which limits some of the cases in which the `Null` singleton could be used.
+
+    With knowledge of the caveats and in the right scenarios, the `Null` singleton can
+    offer a good way to achieve clearer and more expressive code while navigating nested
+    object hierarchies without the clutter of nested attribute existence checks."""
+
+    _instance: NullType = None
+
+    def __new__(cls) -> NullType:
+        """Ensure NullType can only create a singleton instance; further calls to create
+        instances of the NullType will return the existing singleton instance."""
+
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+
+        return cls._instance
+
+    def __getattr__(self, name: str) -> NullType:
+        """Support nested attribute access by returning the singleton instance."""
+
+        return self.__class__._instance
+
+    def __bool__(self) -> bool:
+        """Support falsey equality checks for boolean comparisons against NullType."""
+
+        return False  # Always returns False
+
+    def __eq__(self, value: object) -> bool:
+        """Support value equality checks against NullType via the `==` operator as the
+        fallback option to being able to support identity equality checks via the `is`
+        operator which are not currently possible due to language constraints."""
+
+        if value is None or value is False:
+            return True
+        else:
+            return self is value
+
+    def __str__(self) -> str:
+        return "Null"
+
+    def __repr__(self) -> str:
+        return "Null"
+
+
+# Create the singleton instance of Null
+Null = NullType()
+
+__all__ = [
+    "NullType",
+    "Null",
+]

classicist-1.0.5/source/classicist/version.txt

@@ -0,0 +1 @@
+1.0.5

{classicist-1.0.4 → classicist-1.0.5/source/classicist.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classicist
-Version: 1.0.4
+Version: 1.0.5
 Summary: Classy class decorators for Python.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -33,17 +33,20 @@ Dynamic: license-file
 
 # Classicist: Classy Class Decorators & Extensions
 
-The Classicist library provides several useful decorators and helper methods including:
+The Classicist library provides several useful decorators, functions, classes, and types
+that offer useful behaviours and functionality, and help to fill some of the gaps in the
+current standard library:
 
  * `@hybridmethod` – a decorator that allows methods to be used both as class methods and as instance methods;
- * `@classproperty` – a decorator that allow class methods to be accessed as class properties;
+ * `@classproperty` – a decorator that allows class methods to be accessed as class properties;
  * `@annotation` – a decorator that can be used to apply arbitrary annotations to code objects;
- * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated;
+ * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated, with support for adding optional arbitrary annotations;
  * `@alias` – a decorator that can be used to add aliases to classes, methods defined within classes, module-level functions, and nested functions when overriding the aliasing scope;
  * `@nocache` – a decorator that can be used to mark functions and methods as not being suitable for caching;
- * `@runtimer` – a decorator that can be used to time function and method calls;
+ * `@runtimer` – a decorator that can be used to gather call run time information for function and method calls;
  * `shadowproof` – a metaclass that can be used to protect subclasses from class-level attributes
-  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases.
+  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases;
+* `Null` – an alternative to `None`, useful when building custom data model classes and libraries, where supporting "null-safe" style access and navigation of the model's nested hierarchy is preferred.
 
 The `classicist` library was previously named `hybridmethod` so if a prior version had
 been installed, please update references to the new library name. Installation of the
@@ -554,6 +557,146 @@ except AttributeShadowingError as exception:
     pass
 ```
 
+#### NullType: Null-Safe Style Access for Data Models and Nested Class Hierarchies
+
+The `NullType` class supports the creation of a `Null` singleton instance that offers
+support for safely chaining nested attribute accesses without raising exceptions for
+attributes that have no inherent value.
+
+As Python currently lacks a null-aware navigation operator, such as `?.`, unlike many
+other dynamic languages, for safely navigating nested object hierarchies which may
+contain null attributes, the library offers the `NullType` and `Null` singleton as a
+potential option to support this need in the interim. Consistent use of the `Null`
+singleton in place of the standard `None` singleton, in relevant scenarios, such as
+within a custom data model library, can allow for more expressive and clearer code that
+does not require endless checks for intermediary or nested attribute existence.
+
+However, there are some caveats to the use of the `NullType` and `Null` singleton as
+these are not built-in features of the language, and Python does not offer support for
+the creation of custom operators nor overriding the `is` operator for identity checking
+which limits some of the use cases in which the `Null` singleton can be used.
+
+With knowledge of these caveats and in the right scenarios, the `Null` singleton can
+offer a good way to achieve clearer and more expressive code while navigating nested
+object hierarchies without the clutter of nested attribute existence checks.
+
+```python
+from __future__ import annotations
+
+from classicist import Null
+
+data: dict = {
+  "id": 1,
+  "name": "A",
+  "related": {
+    "id": 2,
+    "name": "B",
+    "related": {
+      "id": 3,
+      "name": "C",
+    },
+  },
+}
+
+class Model(object):
+  """Sample Model class with some properties that reference nested Model instances."""
+
+  def __init__(self, data: dict):
+    if not isinstance(data, dict):
+      raise TypeError("The 'data' argument must reference a valid data dictionary!")
+
+    if not ("id" in data and isinstance(data["id"], int)):
+      raise ValueError("The 'data' must contain an 'id' key with an integer value!")
+
+    if not ("name" in data and isinstance(data["name"], str)):
+      raise ValueError("The 'data' must contain an 'name' key with an string value!")
+
+    self.data = data
+
+  @property
+  def id(self) -> int:
+    return self.data["id"]
+
+  @property
+  def name(self) -> str:
+    return self.data["name"]
+
+  @property
+  def related(self) -> Model | Null:
+    if data := self.data.get("related"):
+      return Model(data=data)
+    else:
+      return Null
+
+  @property
+  def relates(self) -> Model | Null:
+    if data := self.data.get("relates"):
+      return Model(data=data)
+    else:
+      return Null
+
+# Create an instance of the sample Model data class
+model = Model(data=data)
+
+# Check that the expected data attributes are available
+assert model.id == 1
+assert model.name == "A"
+
+# The model.related property references A/1 in the data above, so these properties exist
+assert model.related
+assert model.related.id
+assert model.related.name
+
+# Ensure the nested property values are as expected
+assert model.related.id == 2
+assert model.related.name == "B"
+
+# Note that model.relates had no corresponding data, so the Model returns `Null` which
+# still allows for nested attribute access, such as to `.id` and `.name` without raising
+# any exceptions; the `Null` singleton also allows for `bool` comparison as shown below:
+assert not model.relates
+assert not model.relates.id
+assert not model.relates.name
+
+# There is no limit to the levels of nesting that `NullType` and the `Null` singleton
+# can support, so long as a custom data model or library consistently returns `Null` for
+# cases where the "null-safe" navigation is desired:
+
+# model.related.related references 3/C in the data above, so these properties exist
+assert model.related.related.id
+assert model.related.related.name
+
+# model.related.relates was not specified in the data above so the Model returns `Null`
+assert not model.related.relates.id
+assert not model.related.relates.name
+
+# Ensure the nested property values are as expected
+assert model.related.related.id == 3
+assert model.related.related.name == "C"
+
+# These features make it easy to write clearer more expressive code without boilerplate
+# code to check for the availability of nested attributes or entities:
+if isinstance(name := model.related.name, str):
+  print("model.related.name => %s" % (name))
+
+# No exception is raised here even though model.relates is effectively "null":
+if isinstance(name := model.relates.name, str):
+  print("model.relates.name => %s" % (name))
+
+# However, there are some caveats as noted with `NullType` and the `Null` singleton as
+# these are a third-party solution so we can only go so far in supplementing null-safe
+# operator behaviour in the language; for example, we cannot perform identity checks to
+# boolean values, True or False, or the actual None singleton value:
+assert not model.relates is True  # Notice the `assert not` as `assert` would fail here
+assert not model.relates is False  # Notice the `assert not` as `assert` would fail here
+
+# Furthermore, we cannot use `None` identity comparison either:
+assert not model.relates is None  # Notice the `assert not` as `assert` would fail here
+
+# We can however perform an identity check against the `Null` singleton if needed:
+assert model.relates is Null
+```
+
 ### Unit Tests
 
 The Classicist library includes a suite of comprehensive unit tests which ensure that

{classicist-1.0.4 → classicist-1.0.5}/source/classicist.egg-info/SOURCES.txt

@@ -31,10 +31,13 @@ source/classicist/logging/__init__.py
 source/classicist/metaclasses/__init__.py
 source/classicist/metaclasses/aliased/__init__.py
 source/classicist/metaclasses/shadowproof/__init__.py
+source/classicist/types/__init__.py
+source/classicist/types/null/__init__.py
 tests/test_aliased.py
 tests/test_annotation.py
 tests/test_classproperty.py
 tests/test_deprecated.py
 tests/test_hybridmethod.py
+tests/test_nulltype.py
 tests/test_runtimer.py
 tests/test_shadowproof.py

classicist-1.0.5/tests/test_nulltype.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+from classicist import NullType, Null
+
+
+def test_nulltype():
+    """Test the `NullType` class."""
+
+    assert isinstance(NullType, type)
+    assert issubclass(NullType, object)
+
+
+def test_nulltype_instantiation():
+    """Test the instantiation of the `NullType` class."""
+
+    # Create an instance of the NullType class (this should return the singleton)
+    null1 = NullType()
+
+    # Ensure it has the expected type
+    assert isinstance(null1, NullType)
+
+    # Create an instance of the NullType class (this should return the singleton)
+    null2 = NullType()
+
+    # Ensure it has the expected type
+    assert isinstance(null2, NullType)
+
+    # Ensure that the NullType can only create and return a singleton instance; as all
+    # instances should pass identity checks with each other via the `is` operator:
+    assert null1 is null2
+
+    # Ensure any NullType instances are all the same, and are the same as the singleton
+    assert null1 is null2 is Null
+
+
+def test_nulltype_singleton():
+    """Test the `Null` singleton instance's type."""
+
+    assert isinstance(Null, NullType)
+
+
+def test_nulltype_string_representation():
+    """Test the `Null` singleton instance's string representation."""
+
+    assert str(Null) == "Null"
+
+
+def test_nulltype_debug_string_representation():
+    """Test the `Null` singleton instance's debug string representation."""
+
+    assert repr(Null) == "Null"
+
+
+def test_nulltype_arbitrary_attribute_access():
+    """Test arbitrary attribute access on the `Null` singleton instance."""
+
+    thing = Null
+
+    assert thing.a is Null
+    assert thing.a.b is Null
+    assert thing.a.c is Null
+    assert thing.a.c.d is Null
+    assert thing.a.c.d.e is Null
+    assert thing.a.c.d.e.f is Null
+
+
+def test_nulltype_boolean_comparison():
+    """Test arbitrary attribute boolean comparison on the `Null` singleton instance."""
+
+    thing: object = Null
+
+    # We expect that these non-existent nested attributes will boolean compare as falsey
+    # hence the use of `assert not` in the tests below:
+    assert not thing.a
+    assert not thing.a.b
+    assert not thing.a.c
+    assert not thing.a.c.d
+    assert not thing.a.c.d.e
+    assert not thing.a.c.d.e.f
+
+
+def test_nulltype_boolean_comparison_with_if_else_statement():
+    """Test arbitrary attribute boolean comparison on the `Null` singleton instance."""
+
+    thing: object = Null
+
+    exists: bool = None
+
+    # Test the boolean comparison through an `if-else` statement
+    if thing.a.b.c.d.e.f:
+        exists = True
+    else:
+        exists = False  # We expect to reach this assignment as `if` should not pass
+
+    # Ensure that the result of the if-else statement is as expected
+    assert exists is False
+
+
+def test_nulltype_boolean_comparison_with_if_not_else_statement():
+    """Test arbitrary attribute boolean comparison on the `Null` singleton instance."""
+
+    thing: object = Null
+
+    exists: bool = None
+
+    # Test the boolean comparison through an `if-else` statement
+    if not thing.a.b.c.d.e.f:
+        exists = False  # We expect to reach this assignment as `if not` should pass
+    else:
+        exists = True
+
+    # Ensure that the result of the if-not-else statement is as expected
+    assert exists is False
+
+
+def test_nulltype_identity_comparison():
+    """Test arbitrary attribute boolean comparison on the `Null` singleton instance."""
+
+    thing: object = Null
+
+    # We expect that the identity comparisons to True should *not* pass
+    assert not thing.a is True
+    assert not thing.a.b is True
+
+    # We expect that the identity comparisons to False should *not* pass
+    assert not thing.a is False
+    assert not thing.a.b is False
+
+    # We expect that the identity comparisons to None should *not* pass
+    assert not thing.a is None
+    assert not thing.a.b is None
+
+    # We expect identity comparisons to anything other than `Null` should *not* pass
+    assert not thing.a == 123
+    assert not thing.a.b == 123
+
+    # We expect that the identity comparison to the `Null` singleton *will* pass
+    assert thing.a is Null
+    assert thing.a.b is Null
+
+
+def test_nulltype_with_a_custom_data_model():
+    """Test the `Null` singleton instance in a custom data model to demonstrate the
+    ability to use the `Null` singleton instead of `None` for a null-safe experience."""
+
+    data: dict = {
+        "id": 1,
+        "name": "A",
+        "related": {
+            "id": 2,
+            "name": "B",
+            "related": {
+                "id": 3,
+                "name": "C",
+            },
+        },
+    }
+
+    class Model(object):
+        """Sample Model with some properties that reference nested Model instances."""
+
+        def __init__(self, data: dict):
+            if not isinstance(data, dict):
+                raise TypeError(
+                    "The 'data' argument must reference a valid data dictionary!"
+                )
+
+            if not ("id" in data and isinstance(data["id"], int)):
+                raise ValueError(
+                    "The 'data' must contain an 'id' key with an integer value!"
+                )
+
+            if not ("name" in data and isinstance(data["name"], str)):
+                raise ValueError(
+                    "The 'data' must contain an 'name' key with an string value!"
+                )
+
+            self.data = data
+
+        @property
+        def id(self) -> int:
+            return self.data["id"]
+
+        @property
+        def name(self) -> str:
+            return self.data["name"]
+
+        @property
+        def related(self) -> Model | Null:
+            if data := self.data.get("related"):
+                return Model(data=data)
+            else:
+                return Null
+
+        @property
+        def relates(self) -> Model | Null:
+            if data := self.data.get("relates"):
+                return Model(data=data)
+            else:
+                return Null
+
+    # Create an instance of the sample Model data class
+    model = Model(data=data)
+
+    # Check that the expected data attributes are available
+    assert model.id == 1
+    assert model.name == "A"
+
+    # The model.related property references A/1 in the data above, so these properties exist
+    assert model.related
+    assert model.related.id
+    assert model.related.name
+
+    # Ensure the nested property values are as expected
+    assert model.related.id == 2
+    assert model.related.name == "B"
+
+    # Note that model.relates had no corresponding data, so the Model returns `Null` which
+    # still allows for nested attribute access, such as to `.id` and `.name` without raising
+    # any exceptions; the `Null` singleton also allows for `bool` comparison as shown below:
+    assert not model.relates
+    assert not model.relates.id
+    assert not model.relates.name
+
+    # There is no limit to the levels of nesting that `NullType` and the `Null` singleton
+    # can support, so long as a custom data model or library consistently returns `Null`
+    # for cases where the "null-safe" navigation is desired:
+
+    # model.related.related references 3/C in the data above, so these properties exist
+    assert model.related.related.id
+    assert model.related.related.name
+
+    # model.related.relates was not specified in the data above so the Model returns `Null`
+    assert not model.related.relates.id
+    assert not model.related.relates.name
+
+    # Ensure the nested property values are as expected
+    assert model.related.related.id == 3
+    assert model.related.related.name == "C"
+
+    # These features make it easy to write clearer more expressive code without
+    # boilerplate code to check for the availability of nested attributes or entities:
+    if isinstance(name := model.related.name, str):
+        print("model.related.name => %s" % (name))
+
+    # No exception is raised here even though model.relates is effectively "null":
+    if isinstance(name := model.relates.name, str):
+        print("model.relates.name => %s" % (name))
+
+    # However, there are some caveats as noted with `NullType` and the `Null` singleton
+    # as these are a third-party solution so we can only go so far in supplementing
+    # null-safe operator behaviour in the language; for example, we cannot perform
+    # identity checks to the boolean values, True or False, or None singleton value:
+
+    # Notice the `assert not` as `assert` would fail here
+    assert not model.relates is True
+
+    # Notice the `assert not` as `assert` would fail here
+    assert not model.relates is False
+
+    # Notice the `assert not` as `assert` would fail here
+    assert not model.relates is None
+
+    # We can however perform an identity check against the `Null` singleton if needed:
+    assert model.relates is Null

classicist-1.0.4/source/classicist/version.txt

@@ -1 +0,0 @@
-1.0.4