fields-metadata 1.3.2__tar.gz → 1.3.3__tar.gz

{fields_metadata-1.3.2 → fields_metadata-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fields-metadata
-Version: 1.3.2
+Version: 1.3.3
 Summary: A Python library for extracting field metadata from dataclasses and Pydantic models
 Project-URL: Homepage, https://github.com/Kencho1/fields-metadata
 Project-URL: Repository, https://github.com/Kencho1/fields-metadata
@@ -238,6 +238,38 @@ metadata = extractor.extract(User)
 assert metadata["email_domain"].computed is True
 ```
 
+#### Literal Types
+
+Literal types are automatically unwrapped to their underlying type:
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+@dataclass
+class Task:
+    name: str
+    status: Literal["pending", "in_progress", "done"]
+    priority: Literal[1, 2, 3]
+    score: Literal[1.0, 2.0, 3.0]
+
+extractor = MetadataExtractor()
+metadata = extractor.extract(Task)
+
+# Literal types are unwrapped to their underlying type
+assert metadata["status"].field_type == str
+assert metadata["status"].effective_type == str
+assert metadata["status"].categorical is True
+
+assert metadata["priority"].field_type == int
+assert metadata["priority"].numeric is True
+assert metadata["priority"].categorical is True  # int is categorical by default
+
+assert metadata["score"].field_type == float
+assert metadata["score"].numeric is True
+assert metadata["score"].categorical is False  # float is non-categorical
+```
+
 ### Nested Structures
 
 The library automatically traverses nested structures and builds dot-separated paths:

{fields_metadata-1.3.2 → fields_metadata-1.3.3}/README.md

@@ -207,6 +207,38 @@ metadata = extractor.extract(User)
 assert metadata["email_domain"].computed is True
 ```
 
+#### Literal Types
+
+Literal types are automatically unwrapped to their underlying type:
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+@dataclass
+class Task:
+    name: str
+    status: Literal["pending", "in_progress", "done"]
+    priority: Literal[1, 2, 3]
+    score: Literal[1.0, 2.0, 3.0]
+
+extractor = MetadataExtractor()
+metadata = extractor.extract(Task)
+
+# Literal types are unwrapped to their underlying type
+assert metadata["status"].field_type == str
+assert metadata["status"].effective_type == str
+assert metadata["status"].categorical is True
+
+assert metadata["priority"].field_type == int
+assert metadata["priority"].numeric is True
+assert metadata["priority"].categorical is True  # int is categorical by default
+
+assert metadata["score"].field_type == float
+assert metadata["score"].numeric is True
+assert metadata["score"].categorical is False  # float is non-categorical
+```
+
 ### Nested Structures
 
 The library automatically traverses nested structures and builds dot-separated paths:

{fields_metadata-1.3.2 → fields_metadata-1.3.3}/fields_metadata/__init__.py

@@ -19,7 +19,7 @@ from fields_metadata.extractor import MetadataExtractor
 from fields_metadata.metadata import FieldMetadata
 from fields_metadata.path import FieldsMetadataMap, FieldsPath
 
-__version__ = "1.3.2"
+__version__ = "1.3.3"
 
 __all__ = [
     "MetadataExtractor",

{fields_metadata-1.3.2 → fields_metadata-1.3.3}/fields_metadata/extractor.py

@@ -30,6 +30,7 @@ from fields_metadata.type_utils import (
     is_numeric_type,
     is_optional_type,
     unwrap_annotated,
+    unwrap_literal_type,
 )
 
 TMetadata = TypeVar("TMetadata", bound=FieldMetadata)
@@ -373,8 +374,6 @@ class MetadataExtractor(Generic[TMetadata]):
                 parent_field_path = field_meta.parent_field
                 if parent_field_path in metadata:
                     parent_meta = metadata[parent_field_path]
-                    # Set the full path to the field (can be used as lookup key)
-                    # e.g., for "department.location.building_id", set "department.location.building_id"
                     parent_meta.extra["suggested_human_sorting_field"] = field_path
 
     def _get_fields(self, obj_type: type[Any]) -> list[tuple[str, type[Any]]]:
@@ -516,6 +515,10 @@ class MetadataExtractor(Generic[TMetadata]):
 
         clean_type = unwrap_annotated(base_type)
 
+        literal_underlying_type = unwrap_literal_type(clean_type)
+        if literal_underlying_type is not None:
+            clean_type = literal_underlying_type
+
         is_multivalued = is_multivalued_type(clean_type)
         items_type = get_items_type(clean_type) if is_multivalued else None
         effective_type = items_type if is_multivalued else clean_type

{fields_metadata-1.3.2 → fields_metadata-1.3.3}/fields_metadata/type_utils.py

@@ -4,7 +4,7 @@ import dataclasses
 import typing
 from datetime import date, datetime, time, timedelta
 from decimal import Decimal
-from typing import Any, cast, get_args, get_origin
+from typing import Any, Literal, cast, get_args, get_origin
 
 from fields_metadata.exceptions import InvalidTypeUnionError, NoneTypeFieldError
 
@@ -196,6 +196,30 @@ def is_numeric_type(type_hint: type[Any]) -> bool:
         return False
 
 
+def unwrap_literal_type(type_hint: type[Any]) -> type[Any] | None:
+    """
+    Extract the underlying type from a Literal type.
+
+    For Literal types, returns the type of the literal value(s).
+    For example: Literal['abc'] -> str, Literal[1, 2, 3] -> int
+
+    :param type_hint: The type to check
+    :return: The underlying type if it's a Literal, None otherwise
+    """
+    origin = get_origin(type_hint)
+
+    # Check if this is a Literal type
+    # In Python 3.8+, Literal's origin is typing.Literal
+    if origin is Literal:
+        args = get_args(type_hint)
+        if args:
+            # Get the type of the first literal value
+            # All values in a Literal should be of the same type or compatible types
+            return type(args[0])
+
+    return None
+
+
 def is_computed_field(obj_class: type[Any], field_name: str) -> bool:
     """
     Check if a field is computed (property or pydantic computed_field).

fields_metadata-1.3.3/tests/test_literal_types.py

@@ -0,0 +1,89 @@
+"""Tests for Literal type handling."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+from fields_metadata.extractor import MetadataExtractor
+
+
+def test_literal_string_unwrapped_to_str():
+    """Test that Literal['value'] is unwrapped to str."""
+
+    @dataclass
+    class Example:
+        status: Literal["active", "inactive"]
+
+    extractor = MetadataExtractor()
+    metadata = extractor.extract(Example)
+
+    assert metadata["status"].field_type == str
+    assert metadata["status"].effective_type == str
+    assert metadata["status"].original_annotation == Literal["active", "inactive"]
+
+
+def test_literal_int_unwrapped_to_int():
+    """Test that Literal[1, 2, 3] is unwrapped to int."""
+
+    @dataclass
+    class Example:
+        priority: Literal[1, 2, 3]
+
+    extractor = MetadataExtractor()
+    metadata = extractor.extract(Example)
+
+    assert metadata["priority"].field_type == int
+    assert metadata["priority"].effective_type == int
+    assert metadata["priority"].numeric is True
+
+
+def test_literal_bool_unwrapped_to_bool():
+    """Test that Literal[True, False] is unwrapped to bool."""
+
+    @dataclass
+    class Example:
+        flag: Literal[True, False]
+
+    extractor = MetadataExtractor()
+    metadata = extractor.extract(Example)
+
+    assert metadata["flag"].field_type == bool
+    assert metadata["flag"].effective_type == bool
+
+
+def test_optional_literal_unwrapped():
+    """Test that Optional[Literal['value']] is unwrapped to str."""
+
+    @dataclass
+    class Example:
+        status: Literal["pending", "done"] | None = None
+
+    extractor = MetadataExtractor()
+    metadata = extractor.extract(Example)
+
+    assert metadata["status"].field_type == str
+    assert metadata["status"].effective_type == str
+    assert metadata["status"].optional is True
+
+
+def test_literal_categorical_behavior():
+    """Test that Literal fields have correct categorical behavior."""
+
+    @dataclass
+    class Example:
+        status: Literal["active", "inactive"]
+        priority: Literal[1, 2, 3]
+        score: Literal[1.0, 2.0, 3.0]
+
+    extractor = MetadataExtractor()
+    metadata = extractor.extract(Example)
+
+    # String literals should be categorical
+    assert metadata["status"].categorical is True
+
+    # Int literals should be categorical (int is categorical by default)
+    assert metadata["priority"].categorical is True
+    assert metadata["priority"].numeric is True
+
+    # Float literals should be non-categorical (float is inherently non-categorical)
+    assert metadata["score"].categorical is False
+    assert metadata["score"].numeric is True