"""Tests for the introspection module.""" import unittest from typing import cast from introspect import ( FunctionData, infer_getter_return_types, parse_rst_function_sig, infer_context_member_type, introspect_callable, refine_types_by_context, clean_docstring, clean_type_str, parse_docstring_types, python_type_name, ) class TestCleanTypeStr(unittest.TestCase): def test_class_markup_removal(self) -> None: self.assertEqual( clean_type_str(":class:`bpy.types.Library`"), "bpy.types.Library" ) def test_plain_type_passthrough(self) -> None: self.assertEqual(clean_type_str("str | bytes"), "str | bytes") def test_generic_type(self) -> None: self.assertEqual( clean_type_str("list[tuple[str, str]]"), "list[tuple[str, str]]" ) def test_sequence_type(self) -> None: self.assertEqual(clean_type_str("Sequence[str]"), "Sequence[str]") def test_whitespace_collapse(self) -> None: self.assertEqual(clean_type_str("str | bytes"), "str | bytes") def test_multiline_collapse(self) -> None: self.assertEqual(clean_type_str("str\n | bytes"), "str | bytes") class TestParseDocstringTypes(unittest.TestCase): def test_simple_type(self) -> None: doc = ":type name: str\n:rtype: str" param_types, return_type = parse_docstring_types(doc) self.assertEqual(param_types, {"name": "str"}) self.assertEqual(return_type, "str") def test_union_type(self) -> None: doc = ":type path: str | bytes\n:rtype: str" param_types, return_type = parse_docstring_types(doc) self.assertEqual(param_types, {"path": "str | bytes"}) self.assertEqual(return_type, "str") def test_class_reference(self) -> None: doc = ":type library: :class:`bpy.types.Library`\n:rtype: str" param_types, _return_type = parse_docstring_types(doc) self.assertEqual(param_types, {"library": "bpy.types.Library"}) def test_generic_return(self) -> None: doc = ":rtype: list[tuple[str, str]]" _param_types, return_type = parse_docstring_types(doc) self.assertEqual(return_type, "list[tuple[str, str]]") def test_empty_docstring(self) -> None: param_types, return_type = parse_docstring_types("") self.assertEqual(param_types, {}) self.assertIsNone(return_type) def test_no_type_annotations(self) -> None: doc = "Just a description with no type info." param_types, return_type = parse_docstring_types(doc) self.assertEqual(param_types, {}) self.assertIsNone(return_type) def test_multiple_params(self) -> None: doc = ( ":arg start: Relative to this path.\n" ":type start: str | bytes\n" ":arg library: The library.\n" ":type library: :class:`bpy.types.Library`\n" ":rtype: str" ) param_types, return_type = parse_docstring_types(doc) self.assertEqual( param_types, { "start": "str | bytes", "library": "bpy.types.Library", }, ) self.assertEqual(return_type, "str") def test_literal_inferred_from_arg_enum_values(self) -> None: doc = ( ":arg mode: The blend mode.\n" " * ``NONE`` No blending.\n" " * ``ALPHA`` Alpha blend.\n" " * ``ADDITIVE`` Additive.\n" ":type mode: str" ) param_types, _ = parse_docstring_types(doc) self.assertEqual( param_types["mode"], 'Literal["NONE", "ALPHA", "ADDITIVE"]', ) def test_literal_not_inferred_when_few_values(self) -> None: doc = ":arg path: The ``PATH`` to use.\n:type path: str" param_types, _ = parse_docstring_types(doc) self.assertEqual(param_types["path"], "str") def test_lowercase_generator(self) -> None: self.assertEqual( clean_type_str("generator"), "Generator[object, None, None]", ) def test_lowercase_sequence(self) -> None: self.assertEqual(clean_type_str("sequence"), "Sequence[object]") def test_bare_set_gets_parameterized(self) -> None: self.assertEqual(clean_type_str("set"), "set[object]") def test_bare_frozenset_gets_parameterized(self) -> None: self.assertEqual(clean_type_str("frozenset"), "frozenset[object]") def test_module_maps_to_types_moduletype(self) -> None: self.assertEqual(clean_type_str("Module"), "types.ModuleType") self.assertEqual(clean_type_str("Module | None"), "types.ModuleType | None") def test_nonetype_maps_to_none(self) -> None: self.assertEqual(clean_type_str("NoneType"), "None") self.assertEqual(clean_type_str("str | NoneType"), "str | None") def test_undefined_maps_to_object(self) -> None: self.assertEqual(clean_type_str("Undefined"), "object") def test_uint_maps_to_int(self) -> None: self.assertEqual(clean_type_str("uint"), "int") self.assertEqual(clean_type_str("uint | None"), "int | None") def test_type_sequence_pattern(self) -> None: self.assertEqual(clean_type_str("int or int sequence"), "int | Sequence[int]") self.assertEqual( clean_type_str("float or float sequence"), "float | Sequence[float]" ) def test_plural_bools(self) -> None: self.assertEqual(clean_type_str("Sequence of bools"), "Sequence[bool]") def test_plural_numbers(self) -> None: self.assertEqual(clean_type_str("Sequence of numbers"), "Sequence[float]") def test_plural_vectors(self) -> None: self.assertEqual(clean_type_str("vectors"), "mathutils.Vector") def test_plural_matrices(self) -> None: self.assertEqual(clean_type_str("matrices"), "mathutils.Matrix") def test_sequence_multi_arg_to_tuple(self) -> None: self.assertEqual( clean_type_str("Sequence[int, int]"), "Sequence[tuple[int, int]]" ) self.assertEqual( clean_type_str("Sequence[Sequence[int, int]]"), "Sequence[Sequence[tuple[int, int]]]", ) def test_plural_tuples(self) -> None: self.assertEqual(clean_type_str("list[tuples]"), "list[tuple[object, ...]]") def test_sequence_of_n_type_skips_number(self) -> None: self.assertEqual(clean_type_str("Sequence of 3 float"), "Sequence[float]") self.assertEqual(clean_type_str("Iterable of 4 int"), "Iterable[int]") def test_sequence_of_n_or_m_type_skips_dimensions(self) -> None: self.assertEqual(clean_type_str("Sequence of 3 or 4 float"), "Sequence[float]") self.assertEqual(clean_type_str("Sequence of 1 to 4 float"), "Sequence[float]") def test_numeric_type_arg_stripped(self) -> None: # "Sequence[3]" from malformed docstring -> bare Sequence -> parameterized self.assertEqual(clean_type_str("Sequence[3]"), "Sequence[object]") def test_numeric_union_parts_stripped(self) -> None: # "Sequence[1] | 2 | 3" from dimension descriptions result = clean_type_str("Sequence[1] | 2 | 3 | object") self.assertNotIn("2", result) self.assertNotIn("3", result) def test_empty_brackets_treated_as_bare(self) -> None: self.assertEqual(clean_type_str("dict[]"), "dict[str, object]") self.assertEqual(clean_type_str("list[]"), "list[object]") def test_callable_empty_params_preserved(self) -> None: self.assertEqual(clean_type_str("Callable[[], None]"), "Callable[[], None]") def test_bare_generic_no_false_match(self) -> None: # \bSequence\b should not match inside SequenceEntry self.assertEqual(clean_type_str("SequenceEntry"), "SequenceEntry") # \bset\b should not match inside SettingsGroup self.assertEqual(clean_type_str("SettingsGroup"), "SettingsGroup") class TestRefineTypesByContext(unittest.TestCase): def test_bool_vector_default(self) -> None: param_types = {"default": "Sequence"} param_types, _ = refine_types_by_context( "BoolVectorProperty", param_types, None ) self.assertEqual(param_types["default"], "Sequence[bool]") def test_float_vector_default(self) -> None: param_types = {"default": "Sequence[object]"} param_types, _ = refine_types_by_context( "FloatVectorProperty", param_types, None ) self.assertEqual(param_types["default"], "Sequence[float]") def test_int_vector_default(self) -> None: param_types = {"default": "Sequence[object]"} param_types, _ = refine_types_by_context("IntVectorProperty", param_types, None) self.assertEqual(param_types["default"], "Sequence[int]") def test_property_options_set_str(self) -> None: param_types = {"options": "set[object]", "override": "set[object]"} param_types, _ = refine_types_by_context("BoolProperty", param_types, None) self.assertEqual(param_types["options"], "set[str]") self.assertEqual(param_types["override"], "set[str]") def test_generator_return_refined(self) -> None: _, return_type = refine_types_by_context("app_template_paths", {}, "Generator") self.assertEqual(return_type, "Generator[str, None, None]") def test_non_property_set_unchanged(self) -> None: param_types = {"options": "set[object]"} param_types, _ = refine_types_by_context("some_function", param_types, None) self.assertEqual(param_types["options"], "set[object]") class TestPythonTypeName(unittest.TestCase): def test_set_with_string_contents(self) -> None: obj: object = {"a", "b"} self.assertEqual(python_type_name(obj), "set[str]") def test_empty_set_defaults_to_str(self) -> None: obj = cast(object, set()) self.assertEqual(python_type_name(obj), "set[str]") def test_list_with_int_contents(self) -> None: obj: object = [1, 2, 3] self.assertEqual(python_type_name(obj), "list[int]") def test_empty_list_defaults_to_object(self) -> None: obj: object = [] self.assertEqual(python_type_name(obj), "list[object]") def test_frozenset_with_contents(self) -> None: obj: object = frozenset({"x"}) self.assertEqual(python_type_name(obj), "frozenset[str]") def test_empty_frozenset_defaults_to_str(self) -> None: obj = cast(object, frozenset()) self.assertEqual(python_type_name(obj), "frozenset[str]") class TestParseRstFunctionSig(unittest.TestCase): def test_keyword_only_with_defaults(self) -> None: doc = ".. function:: blend_paths(*, absolute=False, packed=False)" result = parse_rst_function_sig(doc) self.assertEqual(result["absolute"], ("False", "KEYWORD_ONLY")) self.assertEqual(result["packed"], ("False", "KEYWORD_ONLY")) def test_positional_and_keyword(self) -> None: doc = ".. function:: foo(path, *, create=True)" result = parse_rst_function_sig(doc) self.assertEqual(result["path"], (None, "POSITIONAL_OR_KEYWORD")) self.assertEqual(result["create"], ("True", "KEYWORD_ONLY")) def test_no_rst_directive(self) -> None: doc = "Just a plain docstring." result = parse_rst_function_sig(doc) self.assertEqual(result, {}) def test_class_directive(self) -> None: doc = ".. class:: GPUBatch(type, buf, elem=None)" result = parse_rst_function_sig(doc) self.assertEqual(result["type"], (None, "POSITIONAL_OR_KEYWORD")) self.assertEqual(result["buf"], (None, "POSITIONAL_OR_KEYWORD")) self.assertEqual(result["elem"], ("None", "POSITIONAL_OR_KEYWORD")) def test_positional_only_separator(self) -> None: doc = ".. class:: Color(/, rgb=(0.0, 0.0, 0.0))" result = parse_rst_function_sig(doc) self.assertNotIn("/", result) self.assertEqual(result["rgb"], ("...", "POSITIONAL_OR_KEYWORD")) def test_rst_optional_brackets(self) -> None: doc = ".. method:: write(data[, position])" result = parse_rst_function_sig(doc) self.assertEqual(result["data"], (None, "POSITIONAL_OR_KEYWORD")) self.assertEqual(result["position"], (None, "POSITIONAL_OR_KEYWORD")) def test_rst_nested_optional_brackets(self) -> None: doc = ".. method:: bar(a[, b[, c]])" result = parse_rst_function_sig(doc) self.assertIn("a", result) self.assertIn("b", result) self.assertIn("c", result) def test_positional_only_with_named_params(self) -> None: doc = ".. function:: foo(a, b, /, c, *, d=True)" result = parse_rst_function_sig(doc) self.assertEqual(result["a"], (None, "POSITIONAL_ONLY")) self.assertEqual(result["b"], (None, "POSITIONAL_ONLY")) self.assertEqual(result["c"], (None, "POSITIONAL_OR_KEYWORD")) self.assertEqual(result["d"], ("True", "KEYWORD_ONLY")) class _NoSigCallable: """Callable that raises ValueError on inspect.signature (like C builtins).""" def __init__(self, doc: str) -> None: self.__doc__ = doc def __call__(self) -> None: pass @property def __signature__(self) -> None: raise ValueError("no signature") class TestRstOnlyParams(unittest.TestCase): def test_param_from_rst_sig_without_type_directive(self) -> None: """Params in RST signature but without :type: should still appear.""" func = _NoSigCallable( ".. method:: foreach_get(seq)\n\nFast access to array data." ) result = introspect_callable(func, "foreach_get") assert result is not None self.assertEqual(len(result["params"]), 1) self.assertEqual(result["params"][0]["name"], "seq") self.assertIsNone(result["params"][0]["type"]) def test_rst_params_merged_with_typed_params(self) -> None: """RST params without :type: are added after typed params.""" func = _NoSigCallable(".. method:: foo(a, b)\n\n:type a: str") result = introspect_callable(func, "foo") assert result is not None self.assertEqual(len(result["params"]), 2) self.assertEqual(result["params"][0]["name"], "a") self.assertEqual(result["params"][0]["type"], "str") self.assertEqual(result["params"][1]["name"], "b") self.assertIsNone(result["params"][1]["type"]) class TestParamNameMismatch(unittest.TestCase): def test_docstring_name_used_when_sig_has_generic(self) -> None: """When __text_signature__ uses 'object' but docstring uses 'string'.""" def fake_func(object: object) -> str: # noqa: A002 """:type string: str :rtype: str""" return "" result = introspect_callable(fake_func, "escape_identifier") assert result is not None self.assertEqual(result["params"][0]["name"], "string") self.assertEqual(result["params"][0]["type"], "str") def test_matching_names_work_normally(self) -> None: def fake_func(path: str) -> str: """:type path: str :rtype: str""" return "" result = introspect_callable(fake_func, "basename") assert result is not None self.assertEqual(result["params"][0]["name"], "path") self.assertEqual(result["params"][0]["type"], "str") class TestInferContextMemberType(unittest.TestCase): def test_objects_suffix(self) -> None: self.assertEqual( infer_context_member_type("selected_objects"), "Sequence[Object]" ) self.assertEqual( infer_context_member_type("visible_objects"), "Sequence[Object]" ) def test_object_suffix(self) -> None: self.assertEqual(infer_context_member_type("active_object"), "Object") self.assertEqual(infer_context_member_type("edit_object"), "Object") def test_bones_suffix(self) -> None: self.assertEqual( infer_context_member_type("selected_bones"), "Sequence[EditBone]" ) def test_bone_suffix(self) -> None: self.assertEqual(infer_context_member_type("active_bone"), "EditBone") def test_fcurves_suffix(self) -> None: self.assertEqual( infer_context_member_type("visible_fcurves"), "Sequence[FCurve]" ) def test_strips_suffix(self) -> None: self.assertEqual( infer_context_member_type("selected_strips"), "Sequence[NlaStrip]" ) def test_unknown_returns_none(self) -> None: self.assertIsNone(infer_context_member_type("some_random_thing")) self.assertIsNone(infer_context_member_type("property")) class TestCleanDocstring(unittest.TestCase): def test_strips_arg_directives(self) -> None: doc = "Description of function.\n\n:arg name: The name.\n:type name: str" result = clean_docstring(doc) self.assertEqual(result, "Description of function.") def test_preserves_multiline_description(self) -> None: doc = "First line.\nSecond line.\n\n:arg x: something" result = clean_docstring(doc) self.assertEqual(result, "First line.\nSecond line.") def test_empty(self) -> None: self.assertEqual(clean_docstring(""), "") def test_no_directives(self) -> None: doc = "Just a plain description." self.assertEqual(clean_docstring(doc), "Just a plain description.") class TestInferGetterReturnTypes(unittest.TestCase): def test_getter_inferred_from_setter(self) -> None: functions: list[FunctionData] = [ { "name": "blend_get", "doc": "", "params": [], "return_type": None, "is_classmethod": False, }, { "name": "blend_set", "doc": "", "params": [ { "name": "mode", "type": "Literal['NONE', 'ALPHA']", "default": None, "kind": "POSITIONAL_OR_KEYWORD", } ], "return_type": "None", "is_classmethod": False, }, ] infer_getter_return_types(functions) self.assertEqual(functions[0]["return_type"], "Literal['NONE', 'ALPHA']") def test_getter_not_overwritten_when_typed(self) -> None: functions: list[FunctionData] = [ { "name": "depth_mask_get", "doc": "", "params": [], "return_type": "bool", "is_classmethod": False, }, { "name": "depth_mask_set", "doc": "", "params": [ { "name": "value", "type": "bool", "default": None, "kind": "POSITIONAL_OR_KEYWORD", } ], "return_type": "None", "is_classmethod": False, }, ] infer_getter_return_types(functions) self.assertEqual(functions[0]["return_type"], "bool") def test_setter_with_multiple_params_ignored(self) -> None: functions: list[FunctionData] = [ { "name": "scissor_get", "doc": "", "params": [], "return_type": None, "is_classmethod": False, }, { "name": "scissor_set", "doc": "", "params": [ { "name": "x", "type": "int", "default": None, "kind": "POSITIONAL_OR_KEYWORD", }, { "name": "y", "type": "int", "default": None, "kind": "POSITIONAL_OR_KEYWORD", }, ], "return_type": "None", "is_classmethod": False, }, ] infer_getter_return_types(functions) self.assertIsNone(functions[0]["return_type"]) if __name__ == "__main__": unittest.main()