Handle bare ClassVar type qualifiers, rename INFERRED sentinel (#26)

While currently not explicitly allowed by the typing specification, `ClassVar` is allowed as a bare type qualifier. Unlike `Final`, the actual type doesn't have to be inferred from the assignment (e.g. one can use `Any`). For this reason, the `INFERRED` sentinel was renamed to `UNKNOWN`.

Author: Viicos

docs/api/introspection.md

@@ -9,6 +9,5 @@
         - AnnotationSource
         - Qualifier
         - InspectedAnnotation
-        - INFERRED
-        - InferredType
+        - UNKNOWN
         - ForbiddenQualifier

docs/usage.md

@@ -98,28 +98,40 @@ If you want to allow all of them, use the [`AnnotationSource.ANY`][typing_inspec
 source.
 
 The result of the [`inspect_annotation()`][typing_inspection.introspection.inspect_annotation] function contains the underlying
-[type expression][], the qualifiers and the annotated metadata. Note that some qualifiers are allowed to be used without any
-type expression. In this case, the type should be inferred from the assigned value:
+[type expression][], the qualifiers and the annotated metadata.
+
+#### Handling bare type qualifiers
+
+Note that some qualifiers are allowed to be used without any
+type expression. In this case, the [`InspectedAnnotation.type`][typing_inspection.introspection.InspectedAnnotation.type] attribute
+will take the value of the [`UNKNOWN`][typing_inspection.introspection.UNKNOWN] sentinel.
+
+Depending on the type qualifier that was used, you can infer the actual type in different ways:
 
 ```python
+from typing import get_type_hints
+
+from typing_inspection.introspection import UNKNOWN, AnnotationSource, inspect_annotation
+
+
 class A:
-    x: Annotated[Final, 'meta'] = 1  # type of x should be inferred to `int`.
-```
+    # For `Final` annotations, the type should be inferred from the assignment
+    # (and you may error if no assignment is available).
+    # In this case, you can infer to either `int` or `Literal[1]`:
+    x: Annotated[Final, 'meta'] = 1
 
-In this case, the [`InspectedAnnotation.type`][typing_inspection.introspection.InspectedAnnotation.type] attribute is set
-to the [`INFERRED`][typing_inspection.introspection.INFERRED] sentinel value, so you should check for this sentinel value
-before doing any processing on the type:
+    # For `ClassVar` annotations, the type can be inferred as `Any`,
+    # or from the assignment if available (both options are valid in all cases):
+    y: ClassVar
 
-```python
-from typing_inspection.introspection import INFERRED, AnnotationSource, inspect_annotation
 
 inspected_annotation = inspect_annotation(
-    Annotated[Final, 'meta'],
+    get_type_hints(A)['x'],
     annotation_source=AnnotationSource.CLASS,
 )
 
-if inspected_annotation.type is INFERRED:
-    ann_type = type(assigned_value)  # assigned_value would come from the class
+if inspected_annotation.type is UNKNOWN:
+    ann_type = type(A.x)
 else:
     ann_type = inspected_annotation.type
 ```

src/typing_inspection/introspection.py

@@ -277,33 +277,37 @@ def __init__(self, qualifier: Qualifier, /) -> None:
         self.qualifier = qualifier
 
 
-class _InferredTypeEnum(Enum):
-    INFERRED = auto()
+class _UnknownTypeEnum(Enum):
+    UNKNOWN = auto()
+
+    def __str__(self) -> str:
+        return 'UNKNOWN'
 
     def __repr__(self) -> str:
-        return 'INFERRED'
+        return '<UNKNOWN>'
 
 
-INFERRED = _InferredTypeEnum.INFERRED
-"""A sentinel value used when no [type expression][] is used, indicating
-that the type should be inferred from the assigned value.
-"""
+UNKNOWN = _UnknownTypeEnum.UNKNOWN
+"""A sentinel value used when no [type expression][] is present."""
 
-InferredType: TypeAlias = Literal[_InferredTypeEnum.INFERRED]
-"""The type of the [`INFERRED`][typing_inspection.introspection.INFERRED] sentinel value."""
+_UnkownType: TypeAlias = Literal[_UnknownTypeEnum.UNKNOWN]
+"""The type of the [`UNKNOWN`][typing_inspection.introspection.UNKNOWN] sentinel value."""
 
 
 class InspectedAnnotation(NamedTuple):
     """The result of the inspected annotation."""
 
-    type: Any | InferredType
+    type: Any | _UnkownType
     """The final [type expression][], with [type qualifiers][type qualifier] and annotated metadata stripped.
 
-    If no type expression is available, the [`INFERRED`][typing_inspection.introspection.INFERRED] sentinel
+    If no type expression is available, the [`UNKNOWN`][typing_inspection.introspection.UNKNOWN] sentinel
     value is used instead. This is the case when a [type qualifier][] is used with no type annotation:
 
     ```python
     ID: Final = 1
+
+    class C:
+        x: ClassVar = 'test'
     ```
     """
 
@@ -413,16 +417,18 @@ def inspect_annotation(
         else:
             break
 
-    # `Final` is the only type qualifier allowed to be used as a bare annotation
-    # (`ClassVar` is under discussion: https://discuss.python.org/t/81705):
+    # `Final` and `ClassVar` are type qualifiers allowed to be used as a bare annotation
+    # (`ClassVar` is not explicitly specified, but will be: https://discuss.python.org/t/81705).
     if typing_objects.is_final(annotation):
         if 'final' not in allowed_qualifiers:
             raise ForbiddenQualifier('final')
         qualifiers.add('final')
-        # No type expression is available, the type should be inferred from the
-        # assigned value.
-        # See https://typing.readthedocs.io/en/latest/spec/qualifiers.html#syntax
-        annotation = INFERRED
+        annotation = UNKNOWN
+    elif typing_objects.is_classvar(annotation):
+        if 'class_var' not in allowed_qualifiers:
+            raise ForbiddenQualifier('class_var')
+        qualifiers.add('class_var')
+        annotation = UNKNOWN
 
     return InspectedAnnotation(annotation, qualifiers, metadata)
 

tests/introspection/test_inspect_annotation.py

@@ -6,7 +6,13 @@
 import pytest
 import typing_extensions as t_e
 
-from typing_inspection.introspection import INFERRED, AnnotationSource, ForbiddenQualifier, inspect_annotation
+from typing_inspection.introspection import UNKNOWN, AnnotationSource, ForbiddenQualifier, inspect_annotation
+
+
+def test_unknown_repr() -> None:
+    assert str(UNKNOWN) == 'UNKNOWN'
+    assert repr(UNKNOWN) == '<UNKNOWN>'
+
 
 _all_qualifiers: list[Any] = [
     t_e.ClassVar[int],
@@ -51,14 +57,30 @@ def test_annotation_source_invalid_qualifiers(source: AnnotationSource, annotati
             inspect_annotation(annotation, annotation_source=source)
 
 
-def test_bare_final_qualifier() -> None:
+def test_final_bare_final_qualifier() -> None:
     result = inspect_annotation(
         t.Final,
         annotation_source=AnnotationSource.ANY,
     )
 
     assert result.qualifiers == {'final'}
-    assert result.type is INFERRED
+    assert result.type is UNKNOWN
+
+    with pytest.raises(ForbiddenQualifier):
+        inspect_annotation(t.Final, annotation_source=AnnotationSource.BARE)
+
+
+def test_class_var_bare_final_qualifier() -> None:
+    result = inspect_annotation(
+        t.ClassVar,
+        annotation_source=AnnotationSource.ANY,
+    )
+
+    assert result.qualifiers == {'class_var'}
+    assert result.type is UNKNOWN
+
+    with pytest.raises(ForbiddenQualifier):
+        inspect_annotation(t.ClassVar, annotation_source=AnnotationSource.BARE)
 
 
 def test_nested_metadata_and_qualifiers() -> None: