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

{python_introspect-0.1.14/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.14
+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.14 → python_introspect-0.1.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-introspect"
-version = "0.1.14"
+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.14 → 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.14 → python_introspect-0.1.16}/src/python_introspect/dataclass_projection.py

@@ -26,7 +26,11 @@ 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(
@@ -41,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:
@@ -52,18 +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
+                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}",
@@ -73,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
 
 

{python_introspect-0.1.14 → 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.14 → 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.14
+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.14 → 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.14 → python_introspect-0.1.16}/tests/test_dataclass_projection.py

@@ -1,4 +1,4 @@
-from dataclasses import dataclass
+from dataclasses import asdict, dataclass, field
 from enum import Enum
 from collections.abc import Sequence
 
@@ -48,6 +48,82 @@ 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(

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.14 → 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."""