python-introspect 0.1.13__tar.gz → 0.1.16__tar.gz

{python_introspect-0.1.13/src/python_introspect.egg-info → python_introspect-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.13
+Version: 0.1.16
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT

{python_introspect-0.1.13 → python_introspect-0.1.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.13"
+version = "0.1.16"
 description = "Pure Python introspection toolkit for function signatures, dataclasses, and type hints"
 readme = "README.md"
 requires-python = ">=3.10"

{python_introspect-0.1.13 → python_introspect-0.1.16}/src/python_introspect/__init__.py

@@ -9,7 +9,7 @@ Extensibility:
     type resolution for framework-specific types (lazy configs, proxies, etc.)
 """
 
-__version__ = "0.1.12"
+__version__ = "0.1.16"
 
 from .signature_analyzer import (
     SignatureAnalyzer,

{python_introspect-0.1.13 → python_introspect-0.1.16}/src/python_introspect/dataclass_projection.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from dataclasses import MISSING, fields, is_dataclass
 from enum import Enum
 from pathlib import Path
@@ -19,7 +19,6 @@ from typing import (
 from .annotation_types import is_union_type
 from .validation import validate_annotated_dataclass, validate_annotation_value
 
-
 DataclassT = TypeVar("DataclassT")
 
 
@@ -27,12 +26,15 @@ def dataclass_from_mapping(
     target_type: type[DataclassT],
     values: Mapping[str, object],
 ) -> DataclassT:
-    """Construct one dataclass from the fields declared by its class."""
+    """Construct declared init fields and verify supplied constructor-owned fields.
+
+    Non-init fields belong to the dataclass's defaults or post-init behavior,
+    not the input mapping. If supplied, they must agree with that owner.
+    """
 
     if not isinstance(target_type, type) or not is_dataclass(target_type):
         raise TypeError(
-            "dataclass_from_mapping requires a dataclass type; "
-            f"got {target_type!r}."
+            "dataclass_from_mapping requires a dataclass type; " f"got {target_type!r}."
         )
     if not isinstance(values, Mapping):
         raise TypeError("dataclass_from_mapping requires a mapping.")
@@ -43,9 +45,7 @@ def dataclass_from_mapping(
             f"got {non_text_keys!r}."
         )
 
-    declared_fields = tuple(
-        declared_field for declared_field in fields(target_type) if declared_field.init
-    )
+    declared_fields = fields(target_type)
     declared_names = {declared_field.name for declared_field in declared_fields}
     extras = tuple(sorted(set(values) - declared_names))
     if extras:
@@ -54,15 +54,19 @@ def dataclass_from_mapping(
         )
 
     annotations = get_type_hints(target_type, include_extras=True)
-    constructor_values: dict[str, object] = {}
+    decoded_values: dict[str, object] = {}
     missing: list[str] = []
     for declared_field in declared_fields:
         if declared_field.name not in values:
-            if declared_field.default is MISSING and declared_field.default_factory is MISSING:
+            if (
+                declared_field.init
+                and declared_field.default is MISSING
+                and declared_field.default_factory is MISSING
+            ):
                 missing.append(declared_field.name)
             continue
         annotation = annotations.get(declared_field.name, declared_field.type)
-        constructor_values[declared_field.name] = _mapping_value_for_annotation(
+        decoded_values[declared_field.name] = _mapping_value_for_annotation(
             annotation,
             values[declared_field.name],
             path=f"{target_type.__name__}.{declared_field.name}",
@@ -72,8 +76,23 @@ def dataclass_from_mapping(
             f"{target_type.__name__} is missing required field(s): {', '.join(missing)}."
         )
 
-    result = target_type(**constructor_values)
+    result = target_type(
+        **{
+            declared_field.name: decoded_values[declared_field.name]
+            for declared_field in declared_fields
+            if declared_field.init and declared_field.name in decoded_values
+        }
+    )
     validate_annotated_dataclass(result)
+    for declared_field in declared_fields:
+        if not declared_field.init and declared_field.name in decoded_values:
+            if decoded_values[declared_field.name] != object.__getattribute__(
+                result, declared_field.name
+            ):
+                raise ValueError(
+                    f"{target_type.__name__}.{declared_field.name} disagrees with "
+                    "its constructed value."
+                )
     return result
 
 
@@ -154,9 +173,7 @@ def _mapping_value_for_annotation(
         if len(successes) == 1:
             return successes[0]
         exact_matches = tuple(
-            converted
-            for converted in successes
-            if type(converted) is type(value)
+            converted for converted in successes if type(converted) is type(value)
         )
         if len(exact_matches) == 1:
             return exact_matches[0]
@@ -164,9 +181,7 @@ def _mapping_value_for_annotation(
             raise TypeError(
                 f"{path} ambiguously matches multiple members of {annotation!r}."
             )
-        value_errors = tuple(
-            error for error in errors if isinstance(error, ValueError)
-        )
+        value_errors = tuple(error for error in errors if isinstance(error, ValueError))
         if len(value_errors) == 1:
             raise value_errors[0]
         if value_errors:
@@ -197,7 +212,9 @@ def _mapping_value_for_annotation(
                 for index, item in enumerate(value)
             )
         if member_types and len(value) != len(member_types):
-            raise ValueError(f"{path} must contain {len(member_types)} item(s); got {len(value)}.")
+            raise ValueError(
+                f"{path} must contain {len(member_types)} item(s); got {len(value)}."
+            )
         return tuple(
             _mapping_value_for_annotation(
                 member_type,
@@ -206,13 +223,19 @@ def _mapping_value_for_annotation(
             )
             for index, (member_type, item) in enumerate(zip(member_types, value))
         )
-    if origin is list:
-        if not isinstance(value, list):
+    if origin in {list, Sequence}:
+        if (origin is list and not isinstance(value, list)) or (
+            origin is Sequence
+            and (
+                not isinstance(value, Sequence)
+                or isinstance(value, (str, bytes, bytearray))
+            )
+        ):
             raise TypeError(f"{path} must be an array.")
         member_types = get_args(annotation)
         if not member_types:
-            return list(value)
-        return [
+            return list(value) if origin is list else tuple(value)
+        converted = [
             _mapping_value_for_annotation(
                 member_types[0],
                 item,
@@ -220,6 +243,7 @@ def _mapping_value_for_annotation(
             )
             for index, item in enumerate(value)
         ]
+        return converted if origin is list else tuple(converted)
     if origin in {dict, Mapping}:
         if not isinstance(value, Mapping):
             raise TypeError(f"{path} must be an object.")
@@ -250,7 +274,9 @@ def _mapping_value_for_annotation(
             return annotation(value)
         except ValueError as error:
             choices = tuple(member.value for member in annotation)
-            raise ValueError(f"{path} must be one of {choices!r}; got {value!r}.") from error
+            raise ValueError(
+                f"{path} must be one of {choices!r}; got {value!r}."
+            ) from error
     if isinstance(annotation, type) and is_dataclass(annotation):
         if isinstance(value, annotation):
             return value

{python_introspect-0.1.13 → python_introspect-0.1.16}/src/python_introspect/signature_analyzer.py

@@ -9,6 +9,9 @@ resolvers to extend functionality without modifying this code.
 
 import ast
 import inspect
+import sys
+import linecache
+from functools import lru_cache
 import dataclasses
 import re
 from abc import ABC, abstractmethod
@@ -434,12 +437,7 @@ class DocstringExtractor:
         if not docstring:
             return DocstringInfo(parameters={})
 
-        # Try AST-based parsing first for better accuracy
-        try:
-            return DocstringExtractor._parse_docstring_ast(actual_target, docstring)
-        except Exception:
-            # Fall back to regex-based parsing
-            return DocstringExtractor._parse_docstring(docstring)
+        return DocstringExtractor._parse_docstring(docstring)
 
     @staticmethod
     def _resolve_lazy_target(target: Union[Callable, type]) -> Union[Callable, type]:
@@ -448,38 +446,6 @@ class DocstringExtractor:
             return target
         return _resolve_type(target)
 
-    @staticmethod
-    def _parse_docstring_ast(target: Union[Callable, type], docstring: str) -> DocstringInfo:
-        """Parse docstring using AST for more accurate extraction.
-
-        This method uses AST to parse the source code and extract docstring
-        information more accurately, especially for complex multiline descriptions.
-        """
-        try:
-            # Get source code
-            source = inspect.getsource(target)
-            tree = ast.parse(source)
-
-            # Find the function/class node
-            for node in ast.walk(tree):
-                if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
-                    if ast.get_docstring(node) == docstring:
-                        return DocstringExtractor._parse_ast_docstring(node, docstring)
-
-            # Fallback to regex parsing if AST parsing fails
-            return DocstringExtractor._parse_docstring(docstring)
-
-        except Exception:
-            # Fallback to regex parsing
-            return DocstringExtractor._parse_docstring(docstring)
-
-    @staticmethod
-    def _parse_ast_docstring(node: Union[ast.FunctionDef, ast.ClassDef], docstring: str) -> DocstringInfo:
-        """Parse docstring from AST node with enhanced multiline support."""
-        # For now, use the improved regex parser
-        # This can be extended later with more sophisticated AST-based parsing
-        return DocstringExtractor._parse_docstring(docstring)
-
     @staticmethod
     def _parse_docstring(docstring: str) -> DocstringInfo:
         """Parse a docstring into structured components with improved multiline support.
@@ -1006,6 +972,56 @@ class SignatureAnalyzer:
             # Return empty dict on error (don't cache errors)
             return {}
 
+    @staticmethod
+    def prepare_dataclass_declaration(dataclass_type: type) -> None:
+        """Warm pure source lookup without evaluating fields or default factories."""
+        SignatureAnalyzer._extract_inline_field_docs(dataclass_type)
+
+    @staticmethod
+    def _dataclass_source(dataclass_type: type) -> str:
+        """Read current loader source, deriving its class block by immutable content."""
+        # Python 3.13+ locates class source from __firstlineno__ directly;
+        # its native locator does not perform the repeated module AST traversal.
+        if sys.version_info >= (3, 13):
+            return inspect.getsource(dataclass_type)
+        target = inspect.unwrap(dataclass_type)
+        if not inspect.isclass(target):
+            return inspect.getsource(target)
+        file = inspect.getsourcefile(target)
+        if file:
+            linecache.checkcache(file)
+        else:
+            file = inspect.getfile(target)
+            if not (file.startswith('<') and file.endswith('>')):
+                raise OSError('source code not available')
+        module = inspect.getmodule(target, file)
+        lines = linecache.getlines(file, module.__dict__) if module else linecache.getlines(file)
+        if not lines:
+            raise OSError('could not get source code')
+        source = SignatureAnalyzer._qualified_class_source(''.join(lines), target.__qualname__)
+        if source is None:
+            raise OSError('could not find class definition')
+        return source
+
+    @staticmethod
+    @lru_cache(maxsize=32)
+    def _module_source_tree(source: str) -> ast.AST:
+        """Parse current immutable module bytes once; never expose the retained AST."""
+        return ast.parse(source)
+
+    @staticmethod
+    @lru_cache(maxsize=256)
+    def _qualified_class_source(source: str, qualname: str) -> Optional[str]:
+        """Use Python's qualified class/decorator locator on current source content."""
+        tree = SignatureAnalyzer._module_source_tree(source)
+        finder = inspect._ClassFinder(qualname)
+        try:
+            finder.visit(tree)
+        except inspect.ClassFoundException as found:
+            lines = source.splitlines(keepends=True)
+            return ''.join(inspect.getblock(lines[found.args[0]:]))
+        return None
+
     @staticmethod
     def _extract_inline_field_docs(dataclass_type: type) -> Dict[str, str]:
         """Extract inline field documentation strings using AST parsing.
@@ -1039,7 +1055,7 @@ class SignatureAnalyzer:
             # Try to get source code - handle cases where it might not be available
             source = None
             try:
-                source = inspect.getsource(dataclass_type)
+                source = SignatureAnalyzer._dataclass_source(dataclass_type)
             except (OSError, TypeError):
                 try:
                     source_file = inspect.getfile(dataclass_type)

{python_introspect-0.1.13 → python_introspect-0.1.16/src/python_introspect.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-introspect
-Version: 0.1.13
+Version: 0.1.16
 Summary: Pure Python introspection toolkit for function signatures, dataclasses, and type hints
 Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
 License: MIT

{python_introspect-0.1.13 → python_introspect-0.1.16}/src/python_introspect.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ src/python_introspect.egg-info/top_level.txt
 tests/test_annotation_types.py
 tests/test_callable_declaration.py
 tests/test_dataclass_projection.py
+tests/test_dataclass_source_preparation.py
 tests/test_environment_projection.py
 tests/test_exceptions.py
 tests/test_init.py

python_introspect-0.1.16/tests/test_dataclass_projection.py

@@ -0,0 +1,256 @@
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from collections.abc import Sequence
+
+import pytest
+
+from python_introspect import dataclass_from_mapping, project_dataclass
+
+
+class Mode(Enum):
+    IPC = "ipc"
+    TCP = "tcp"
+
+
+@dataclass(frozen=True)
+class Connection:
+    host: str
+    port: int
+    mode: Mode | None = None
+
+
+@dataclass(frozen=True)
+class Envelope:
+    connection: Connection
+    started_at: float
+
+
+@dataclass(frozen=True)
+class StoredEnvelope:
+    connection: Connection
+    started_at: float
+    path: str
+
+
+@dataclass(frozen=True)
+class UntypedTupleEnvelope:
+    values: tuple
+
+
+@dataclass(frozen=True)
+class RecursiveSequenceNode:
+    name: str
+    children: Sequence["RecursiveSequenceNode"] = ()
+
+
+@dataclass(frozen=True)
+class SequenceEnvelope:
+    nodes: Sequence[RecursiveSequenceNode]
+
+
+@dataclass(frozen=True)
+class ConnectionWithSummary(Connection):
+    summary: tuple[str, int] = field(init=False)
+    effective_mode: Mode = field(init=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "summary", (self.host, self.port))
+        object.__setattr__(self, "effective_mode", self.mode or Mode.IPC)
+
+
+@dataclass(frozen=True, slots=True)
+class DerivedDefaults:
+    count: int
+    label: str = field(init=False, default="counter")
+    connections: list[Connection] = field(init=False, default_factory=list)
+
+
+@dataclass(frozen=True)
+class DerivedEnvelope:
+    connection: ConnectionWithSummary
+
+
+def test_dataclass_mapping_verifies_inherited_post_init_fields() -> None:
+    original = ConnectionWithSummary("localhost", 7888, Mode.TCP)
+    values = asdict(original)
+    values.update(mode="tcp", effective_mode="tcp", summary=["localhost", 7888])
+    assert dataclass_from_mapping(ConnectionWithSummary, values) == original
+    assert dataclass_from_mapping(
+        ConnectionWithSummary, {"host": "localhost", "port": 7888}
+    ) == ConnectionWithSummary("localhost", 7888)
+
+
+@pytest.mark.parametrize(
+    "overrides,error_type,match",
+    (
+        ({"summary": ["elsewhere", 7888]}, ValueError, "summary.*disagrees"),
+        ({"effective_mode": "tcp"}, ValueError, "effective_mode.*disagrees"),
+        ({"summary": ["localhost", True]}, TypeError, "must be int"),
+        ({"effective_mode": "invalid"}, ValueError, "must be one of"),
+        ({"extra": 1}, ValueError, "undeclared.*extra"),
+    ),
+)
+def test_dataclass_mapping_cannot_override_derived_owner(overrides, error_type, match):
+    values = {"host": "localhost", "port": 7888, **overrides}
+    with pytest.raises(error_type, match=match):
+        dataclass_from_mapping(ConnectionWithSummary, values)
+
+
+def test_dataclass_mapping_verifies_non_init_defaults_and_nested_derived_fields() -> None:
+    original = DerivedDefaults(3)
+    assert dataclass_from_mapping(DerivedDefaults, asdict(original)) == original
+    assert dataclass_from_mapping(DerivedDefaults, {"count": 3}) == original
+    with pytest.raises(ValueError, match="connections.*disagrees"):
+        dataclass_from_mapping(
+            DerivedDefaults,
+            {"count": 3, "connections": [{"host": "localhost", "port": 7888}]},
+        )
+    values = {
+        "connection": {
+            "host": "localhost", "port": 7888,
+            "summary": ["localhost", 7888], "effective_mode": "ipc",
+        }
+    }
+    assert dataclass_from_mapping(DerivedEnvelope, values) == DerivedEnvelope(
+        ConnectionWithSummary("localhost", 7888)
+    )
+    values["connection"]["effective_mode"] = "tcp"
+    with pytest.raises(ValueError, match="effective_mode.*disagrees"):
+        dataclass_from_mapping(DerivedEnvelope, values)
+
+
+def test_dataclass_mapping_derived_defaults_do_not_supply_missing_init_fields() -> None:
+    with pytest.raises(ValueError, match="missing required field.*count"):
+        dataclass_from_mapping(DerivedDefaults, {"label": "counter"})
+
+
+@pytest.mark.parametrize("container", (list, tuple))
+def test_dataclass_mapping_recurses_from_abstract_sequence_annotations(container):
+    result = dataclass_from_mapping(
+        SequenceEnvelope,
+        {
+            "nodes": container([{"name": "parent", "children": [{"name": "child"}]}]),
+        },
+    )
+    assert result == SequenceEnvelope(
+        (RecursiveSequenceNode("parent", (RecursiveSequenceNode("child"),)),)
+    )
+
+
+@pytest.mark.parametrize(
+    "value", ("text", b"bytes", bytearray(b"bytes"), {"name": "mapping"}, 7)
+)
+def test_dataclass_mapping_sequence_rejects_non_array_values(value):
+    with pytest.raises(TypeError, match="must be an array"):
+        dataclass_from_mapping(SequenceEnvelope, {"nodes": value})
+
+
+def test_dataclass_mapping_recursive_sequence_rejects_unknown_fields_and_wrong_elements():
+    with pytest.raises(ValueError, match="undeclared.*extra"):
+        dataclass_from_mapping(
+            SequenceEnvelope,
+            {
+                "nodes": [
+                    {"name": "parent", "children": [{"name": "child", "extra": 1}]}
+                ]
+            },
+        )
+    with pytest.raises(TypeError, match="must be an object"):
+        dataclass_from_mapping(SequenceEnvelope, {"nodes": [42]})
+
+
+def test_dataclass_mapping_abstract_sequence_preserves_typed_members():
+    node = RecursiveSequenceNode("typed")
+    assert dataclass_from_mapping(
+        SequenceEnvelope, {"nodes": [node]}
+    ) == SequenceEnvelope((node,))
+
+
+def test_dataclass_mapping_uses_nested_types_as_the_schema() -> None:
+    result = dataclass_from_mapping(
+        Envelope,
+        {
+            "connection": {
+                "host": "localhost",
+                "port": 7888,
+                "mode": "ipc",
+            },
+            "started_at": 1,
+        },
+    )
+
+    assert result == Envelope(
+        connection=Connection(
+            host="localhost",
+            port=7888,
+            mode=Mode.IPC,
+        ),
+        started_at=1.0,
+    )
+
+
+def test_dataclass_mapping_rejects_missing_and_undeclared_fields() -> None:
+    with pytest.raises(ValueError, match="missing required field"):
+        dataclass_from_mapping(Envelope, {"started_at": 1.0})
+
+    with pytest.raises(ValueError, match="undeclared field"):
+        dataclass_from_mapping(
+            Connection,
+            {"host": "localhost", "port": 7888, "extra": True},
+        )
+
+    with pytest.raises(ValueError, match="must be one of.*ipc.*tcp"):
+        dataclass_from_mapping(
+            Connection,
+            {"host": "localhost", "port": 7888, "mode": "invalid"},
+        )
+
+    with pytest.raises(TypeError, match="field names must be strings"):
+        dataclass_from_mapping(Connection, {1: "localhost"})
+
+
+def test_dataclass_mapping_preserves_bare_tuple_values() -> None:
+    result = dataclass_from_mapping(UntypedTupleEnvelope, {"values": [1, "two"]})
+
+    assert result.values == (1, "two")
+
+
+def test_dataclass_projection_derives_shared_fields_from_both_declarations() -> None:
+    source = Envelope(
+        connection=Connection("localhost", 7888, Mode.TCP),
+        started_at=2.0,
+    )
+
+    result = project_dataclass(StoredEnvelope, source, path="/tmp/bridge.json")
+
+    assert result == StoredEnvelope(
+        connection=source.connection,
+        started_at=2.0,
+        path="/tmp/bridge.json",
+    )
+
+
+def test_dataclass_mapping_union_projection_does_not_use_member_order() -> None:
+    @dataclass(frozen=True)
+    class NumericValue:
+        value: float | int
+
+    assert dataclass_from_mapping(NumericValue, {"value": 1}).value == 1
+    assert type(dataclass_from_mapping(NumericValue, {"value": 1}).value) is int
+
+
+def test_dataclass_mapping_rejects_ambiguous_structured_unions() -> None:
+    @dataclass(frozen=True)
+    class Left:
+        value: int
+
+    @dataclass(frozen=True)
+    class Right:
+        value: int
+
+    @dataclass(frozen=True)
+    class Envelope:
+        payload: Left | Right
+
+    with pytest.raises(TypeError, match="ambiguously matches multiple members"):
+        dataclass_from_mapping(Envelope, {"payload": {"value": 1}})

python_introspect-0.1.16/tests/test_dataclass_source_preparation.py

@@ -0,0 +1,214 @@
+"""Source preparation must preserve live declarations and first-use values."""
+import dataclasses
+import importlib.util
+import inspect
+import linecache
+import os
+import sys
+import types
+from typing import Annotated
+
+import pytest
+from python_introspect import SignatureAnalyzer
+
+
+def _load_module(monkeypatch, name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    monkeypatch.setitem(sys.modules, name, module)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_preparation_does_not_run_factories_or_snapshot_annotations():
+    calls = []
+    current = {"value": 1}
+
+    def first():
+        calls.append("first")
+        return current["value"]
+
+    def second():
+        calls.append("second")
+        return []
+
+    @dataclasses.dataclass
+    class Declaration:
+        value: int = dataclasses.field(default_factory=first)
+        values: list = dataclasses.field(default_factory=second)
+
+    SignatureAnalyzer.prepare_dataclass_declaration(Declaration)
+    assert calls == []
+    current["value"] = 4
+    Declaration.__annotations__["value"] = str
+    result = SignatureAnalyzer._analyze_dataclass(Declaration)
+    assert calls == ["first", "second"]
+    assert result["value"].default_value == 4
+    assert result["value"].param_type is str
+    assert SignatureAnalyzer._analyze_dataclass(Declaration) is result
+    assert calls == ["first", "second"]
+
+
+def test_throwing_factory_stays_uncached_and_retryable():
+    calls = []
+
+    def throwing():
+        calls.append(1)
+        raise RuntimeError("first-use factory")
+
+    @dataclasses.dataclass
+    class Declaration:
+        value: int = dataclasses.field(default_factory=throwing)
+
+    SignatureAnalyzer.prepare_dataclass_declaration(Declaration)
+    assert calls == []
+    assert SignatureAnalyzer._analyze_dataclass(Declaration) == {}
+    assert Declaration not in SignatureAnalyzer._dataclass_analysis_cache
+    assert SignatureAnalyzer._analyze_dataclass(Declaration) == {}
+    assert calls == [1, 1]
+
+
+def test_factory_effects_precede_metadata_and_inherited_documentation():
+    metadata = {"description": "before"}
+
+    def factory():
+        metadata["description"] = "after"
+        Parent.__doc__ = "Args:\n    inherited: after factory"
+        return 3
+
+    @dataclasses.dataclass
+    class Parent:
+        """Args:
+            inherited: before factory
+        """
+        owned: int = dataclasses.field(default_factory=factory, metadata=metadata)
+        inherited: int = 1
+
+    @dataclasses.dataclass
+    class Child(Parent):
+        pass
+
+    SignatureAnalyzer.prepare_dataclass_declaration(Parent)
+    SignatureAnalyzer.prepare_dataclass_declaration(Child)
+    result = SignatureAnalyzer._analyze_dataclass(Child)
+    assert result["owned"].description == "after"
+    assert result["inherited"].description == "after factory"
+
+
+def test_optional_and_required_field_semantics_survive_preparation():
+    marker = object()
+
+    @dataclasses.dataclass
+    class Declaration:
+        required: Annotated[int, marker]
+        inherited: int | None = None
+
+    SignatureAnalyzer.prepare_dataclass_declaration(Declaration)
+    result = SignatureAnalyzer._analyze_dataclass(Declaration)
+    assert result["required"].is_required
+    assert result["required"].param_type == Annotated[int, marker]
+    assert result["inherited"].default_value is None
+    assert not result["inherited"].is_required
+
+
+def test_source_lookup_uses_qualified_nested_and_decorated_classes(tmp_path, monkeypatch):
+    path = tmp_path / "declarations.py"
+    path.write_text('''from dataclasses import dataclass
+
+def identity(target):
+    return target
+
+@identity
+@dataclass
+class Outer:
+    value: int = 1
+    "Outer documentation"
+    @dataclass
+    class Inner:
+        value: int = 2
+        "Inner documentation"
+
+def factory():
+    @dataclass
+    class Inner:
+        value: int = 3
+        "Local documentation"
+    return Inner
+''')
+    module = _load_module(monkeypatch, "qualified_source_preparation", path)
+    for declaration in (module.Outer, module.Outer.Inner, module.factory()):
+        SignatureAnalyzer.prepare_dataclass_declaration(declaration)
+        assert SignatureAnalyzer._dataclass_source(declaration) == inspect.getsource(declaration)
+    # The original inline extractor does not dedent nested blocks before parsing.
+    # Source preparation preserves that behavior rather than repairing it here.
+    assert SignatureAnalyzer._extract_inline_field_docs(module.Outer.Inner) == {}
+    assert SignatureAnalyzer._extract_inline_field_docs(module.factory()) == {}
+
+
+def test_warmed_lookup_observes_changed_file_content_and_qualname(tmp_path, monkeypatch):
+    path = tmp_path / "declarations.py"
+    source = '''from dataclasses import dataclass
+@dataclass
+class First:
+    value: int = 1
+    "First documentation"
+@dataclass
+class Second:
+    value: int = 2
+    "Second documentation"
+'''
+    path.write_text(source)
+    module = _load_module(monkeypatch, "live_source_preparation", path)
+    SignatureAnalyzer.prepare_dataclass_declaration(module.First)
+    module.First.__qualname__ = "Second"
+    assert SignatureAnalyzer._dataclass_source(module.First) == inspect.getsource(module.First)
+    module.First.__qualname__ = "First"
+    path.write_text(source.replace("First documentation", "Changed documentation"))
+    os.utime(path, (path.stat().st_atime, path.stat().st_mtime + 2))
+    assert SignatureAnalyzer._extract_inline_field_docs(module.First) == {"value": "Changed documentation"}
+
+
+def test_loader_source_is_read_at_original_observation_point(tmp_path, monkeypatch):
+    class Loader:
+        source = 'from dataclasses import dataclass\n@dataclass\nclass Loaded:\n    value:int=1\n    "Original documentation"\n'
+
+        def get_source(self, name):
+            return self.source
+
+    loader = Loader()
+    module = types.ModuleType("loader_source_preparation")
+    module.__file__ = str(tmp_path / "not_on_disk.py")
+    module.__loader__ = loader
+    monkeypatch.setitem(sys.modules, module.__name__, module)
+    exec(compile(loader.source, module.__file__, "exec"), module.__dict__)
+    SignatureAnalyzer.prepare_dataclass_declaration(module.Loaded)
+    loader.source = loader.source.replace("Original documentation", "Current documentation")
+    linecache.cache.pop(module.__file__, None)
+    assert SignatureAnalyzer._dataclass_source(module.Loaded) == inspect.getsource(module.Loaded)
+    assert SignatureAnalyzer._extract_inline_field_docs(module.Loaded) == {"value": "Current documentation"}
+
+
+def test_generated_type_keeps_original_fallback_without_inventing_source(tmp_path, monkeypatch):
+    path = tmp_path / "declarations.py"
+    path.write_text('''from dataclasses import dataclass
+@dataclass
+class Public:
+    value: int = 1
+    "Public documentation"
+''')
+    module = _load_module(monkeypatch, "generated_source_preparation", path)
+    generated = dataclasses.make_dataclass("Public", [("value", int, 1)])
+    generated.__module__ = module.__name__
+    generated.__qualname__ = "GeneratedPublic"
+    SignatureAnalyzer.prepare_dataclass_declaration(generated)
+    assert SignatureAnalyzer._extract_inline_field_docs(generated) == {"value": "Public documentation"}
+
+
+def test_missing_source_keeps_original_error():
+    with pytest.raises(TypeError) as original:
+        inspect.getsource(int)
+    with pytest.raises(TypeError) as prepared:
+        SignatureAnalyzer._dataclass_source(int)
+    assert str(prepared.value) == str(original.value)
+    SignatureAnalyzer.prepare_dataclass_declaration(int)
+    assert SignatureAnalyzer._extract_inline_field_docs(int) == {}

{python_introspect-0.1.13 → python_introspect-0.1.16}/tests/test_init.py

@@ -2,6 +2,7 @@
 
 import pytest
 import python_introspect
+from packaging.version import Version
 
 
 class TestPackageImports:
@@ -11,7 +12,7 @@ class TestPackageImports:
         """Test that __version__ is available."""
         assert hasattr(python_introspect, "__version__")
         assert isinstance(python_introspect.__version__, str)
-        assert python_introspect.__version__ == "0.1.12"
+        assert str(Version(python_introspect.__version__)) == python_introspect.__version__
 
     def test_signature_analyzer_import(self):
         """Test SignatureAnalyzer is importable."""

python_introspect-0.1.13/tests/test_dataclass_projection.py

@@ -1,126 +0,0 @@
-from dataclasses import dataclass
-from enum import Enum
-
-import pytest
-
-from python_introspect import dataclass_from_mapping, project_dataclass
-
-
-class Mode(Enum):
-    IPC = "ipc"
-    TCP = "tcp"
-
-
-@dataclass(frozen=True)
-class Connection:
-    host: str
-    port: int
-    mode: Mode | None = None
-
-
-@dataclass(frozen=True)
-class Envelope:
-    connection: Connection
-    started_at: float
-
-
-@dataclass(frozen=True)
-class StoredEnvelope:
-    connection: Connection
-    started_at: float
-    path: str
-
-
-@dataclass(frozen=True)
-class UntypedTupleEnvelope:
-    values: tuple
-
-
-def test_dataclass_mapping_uses_nested_types_as_the_schema() -> None:
-    result = dataclass_from_mapping(
-        Envelope,
-        {
-            "connection": {
-                "host": "localhost",
-                "port": 7888,
-                "mode": "ipc",
-            },
-            "started_at": 1,
-        },
-    )
-
-    assert result == Envelope(
-        connection=Connection(
-            host="localhost",
-            port=7888,
-            mode=Mode.IPC,
-        ),
-        started_at=1.0,
-    )
-
-
-def test_dataclass_mapping_rejects_missing_and_undeclared_fields() -> None:
-    with pytest.raises(ValueError, match="missing required field"):
-        dataclass_from_mapping(Envelope, {"started_at": 1.0})
-
-    with pytest.raises(ValueError, match="undeclared field"):
-        dataclass_from_mapping(
-            Connection,
-            {"host": "localhost", "port": 7888, "extra": True},
-        )
-
-    with pytest.raises(ValueError, match="must be one of.*ipc.*tcp"):
-        dataclass_from_mapping(
-            Connection,
-            {"host": "localhost", "port": 7888, "mode": "invalid"},
-        )
-
-    with pytest.raises(TypeError, match="field names must be strings"):
-        dataclass_from_mapping(Connection, {1: "localhost"})
-
-
-def test_dataclass_mapping_preserves_bare_tuple_values() -> None:
-    result = dataclass_from_mapping(UntypedTupleEnvelope, {"values": [1, "two"]})
-
-    assert result.values == (1, "two")
-
-
-def test_dataclass_projection_derives_shared_fields_from_both_declarations() -> None:
-    source = Envelope(
-        connection=Connection("localhost", 7888, Mode.TCP),
-        started_at=2.0,
-    )
-
-    result = project_dataclass(StoredEnvelope, source, path="/tmp/bridge.json")
-
-    assert result == StoredEnvelope(
-        connection=source.connection,
-        started_at=2.0,
-        path="/tmp/bridge.json",
-    )
-
-
-def test_dataclass_mapping_union_projection_does_not_use_member_order() -> None:
-    @dataclass(frozen=True)
-    class NumericValue:
-        value: float | int
-
-    assert dataclass_from_mapping(NumericValue, {"value": 1}).value == 1
-    assert type(dataclass_from_mapping(NumericValue, {"value": 1}).value) is int
-
-
-def test_dataclass_mapping_rejects_ambiguous_structured_unions() -> None:
-    @dataclass(frozen=True)
-    class Left:
-        value: int
-
-    @dataclass(frozen=True)
-    class Right:
-        value: int
-
-    @dataclass(frozen=True)
-    class Envelope:
-        payload: Left | Right
-
-    with pytest.raises(TypeError, match="ambiguously matches multiple members"):
-        dataclass_from_mapping(Envelope, {"payload": {"value": 1}})