开发工具【免费下载链接】jediAwesome autocompletion, static analysis and refactoring library for python项目地址https://gitcode.com/gh_mirrors/je/jedi点击查看免费下载导读本文以 docs/docs/api-classes.rst 为骨架系统讲解 Jedi 对外 API 的核心返回类BaseName、Name、Completion、BaseSignature、Signature、ParamName、Refactoring与SyntaxError。这些类承载了 Jedi 补全、跳转、类型推断、签名提示与重构等全部操作的结果数据是编辑器/IDE 插件开发者理解并消费 Jedi 能力的第一站。读完本文你将掌握每个返回类的全部公开属性与方法、它们与Script/Interpreter各方法的对应关系以及如何用源码与测试验证行为。一、这些类从何而来API 返回类在整个 Jedi 中的位置Jedi 的 API 由几个部分组成见 docs/docs/api.rst入口类Script与Interpreter、返回类、环境Environment管理与项目Project管理。其中返回类几乎是 API 的全部血肉——它们承载了所有操作的有趣信息。正如 jedi/api/classes.py 模块开头注释所言这些类构成了 API 的最大部分因为它们包含所有操作的相关信息。返回类与Script方法的对应关系如下返回类由哪个方法产生NameScript.goto()、Script.infer()、Script.get_names()、Script.get_references()、Script.search()、Script.get_context()CompletionScript.complete()、Script.complete_search()SignatureScript.get_signatures()ParamNameBaseSignature.params签名内部的参数对象RefactoringScript.rename()、Script.extract_variable()、Script.extract_function()、Script.inline()SyntaxErrorScript.get_syntax_errors()这些类的定义位置集中在两个文件返回类主体在 jedi/api/classes.py重构返回类在 jedi/api/refactoring/init.py语法错误返回类在 jedi/api/errors.py。二、BaseName所有定义、补全与签名对象的抽象基类BaseName定义于 jedi/api/classes.py#L58是所有 definitions、completions 和 signatures 的基类。它不直接对外返回但Name、Completion、BaseSignature均继承自它因此其公开成员几乎全员可用。2.1 核心元数据属性name变量/函数/类/模块的名字。例如x None返回x。类型为str 或 None。实现上调用self._name.get_public_name()jedi/api/classes.py#L110-L119。type定义的类型。合法值包括module、class、instance、function、param、path、keyword、property与statement。对于from X import Y这类导入Jedi 会尝试解析真实对象以给出准确的类型jedi/api/classes.py#L121-L190。文档自带 doctest 演示 from jedi import Script source ... import keyword ... ... class C: ... pass ... ... class D: ... pass ... ... x D() ... ... def f(): ... pass ... ... for variable in [keyword, f, C, x]: ... variable script Script(source) defs script.infer() defs sorted(defs, keylambda d: d.line) [d.type for d in defs] [module, class, instance, function]module_path定义所在模块的文件路径如/usr/lib/python3.14/os.py。编译型compiled模块不返回路径stub 模块则正常返回jedi/api/classes.py#L96-L108。module_name模块名类似模块内的__name__。import json的 infer 结果返回jsonjedi/api/classes.py#L192-L205。in_builtin_module()返回是否为内置builtin模块中的名字。stub 模块会检查其对应的非 stub 值是否 compiledjedi/api/classes.py#L207-L214。full_name点分隔的完整路径形如module[.submodule[...]][.object]。例如os.path.join。Jedi 会做路径归一化映射如posixpath→os.path、_io→io映射表定义于 jedi/api/classes.py#L62-L79使返回的名字更贴近用户直觉 from jedi import Script source ... import os ... os.path.join script Script(source, pathexample.py) print(script.infer(3, len(os.path.join))[0].full_name) os.path.joindescription人类可读的描述测试中大量使用。函数返回def f、类返回class C、isinstance返回def isinstance对语句则返回压缩后的单行代码自动剔除注释与多余空白见 jedi/api/classes.py#L318-L365。2.2 位置与范围信息Jedi 的行号约定与常规一致行从 1 开始列从 0 开始。line/column定义发生的位置若名字无位置如某些关键字返回Nonejedi/api/classes.py#L216-L230。get_definition_start_position()定义范围的起始(row, column)对function/class返回整个定义块含函数体的结束位置行从 1 开始、列从 0 开始jedi/api/classes.py#L232-L263。get_line_code(before0, after0)返回该名字所在行的代码片段可扩展前后若干行内置模块无源码时返回空字符串jedi/api/classes.py#L534-L554。2.3 文档字符串与签名docstring(rawFalse, fastTrue)返回文档字符串并自动在正文前拼接函数签名这是 Jedi 的特色增强 from jedi import Script source \ ... def f(a, b1): ... Document for function f. ... script Script(source, pathexample.py) doc script.infer(1, len(def f))[0].docstring() print(doc) f(a, b1) BLANKLINE Document for function f. print(script.infer(1, len(def f))[0].docstring(rawTrue)) Document for function f.参数说明rawTrue返回真实 docstring不拼接签名fastTrue表示不深追一级浅层导入如import foo但会追from foo import bar以提升速度jedi/api/classes.py#L265-L307。get_signatures()返回该函数/类的所有可能签名返回list[BaseSignature]当使用带overload的 stub 时会出现多个签名jedi/api/classes.py#L573-L584。execute()通过类型推断执行该标识符返回执行后的对象如类实例类型为list[Name]jedi/api/classes.py#L586-L594。get_type_hint()返回类型提示字符串如Iterable[int]或Union[int, str]该方法对函数可能较慢jedi/api/classes.py#L596-L607。2.4 导航与推断方法goto(follow_importsFalse, follow_builtin_importsFalse, only_stubsFalse, prefer_stubsFalse)等价于Script.goto但作用于当前名字返回list[Name]jedi/api/classes.py#L425-L454。infer(only_stubsFalse, prefer_stubsFalse)等价于Script.infer。官方文档强烈建议不要用它对补全结果做批量推断——它会追查所有结果在 numpy 这类上千补全的场景下非常慢只适合少量≤20 个对象的读取jedi/api/classes.py#L456-L491。注意only_stubs与prefer_stubs不能同时为真源码有assert校验。parent()返回该标识符的父作用域模块/类/函数类型为Namejedi/api/classes.py#L493-L524。is_stub()名字是否定义在 stub 文件中jedi/api/classes.py#L406-L413。is_side_effect()判断名字是否以self.foo 3形式定义——对self返回False对foo返回Truejedi/api/classes.py#L415-L423。BaseName的__repr__格式为ClassName full_name..., description...这也是调试与测试断言中常见的形态jedi/api/classes.py#L526-L532。三、Name跳转与推断的主力返回类型Name定义于 jedi/api/classes.py#L753文档明确说明Name对象由许多 API 返回包括Script.goto与Script.infer。它继承BaseName的全部能力并新增defined_names()列出子定义如类中的方法。例如对一个Name调用会返回其内部定义的子Name列表按起始位置排序jedi/api/classes.py#L761-L773。模块级辅助函数defined_namesjedi/api/classes.py#L38-L51是其底层实现通过获取 scope 的 filters 枚举名字。is_definition()True表示是语句/函数/类中定义的定义名False表示对某个定义的引用jedi/api/classes.py#L775-L783。相等性与哈希Name实现了__eq__/__ne__/__hash__比较依据为起始位置、模块路径、名字与 inference statejedi/api/classes.py#L785-L795。因此Script.infer()返回的列表天然可去重、可排序。Name的典型用法对Script.infer()或Script.get_references()的结果遍历读取name、type、line、column、module_path、docstring等字段用于编辑器高亮、悬停提示或跳转到定义。四、Completion补全结果对象Completion定义于 jedi/api/classes.py#L610由Script.complete()返回在BaseName之上提供补全专属信息。4.1 核心补全属性complete返回剩余待补全的字符非模糊补全时有效模糊补全返回None。例如光标在isinstan#处返回ce。若开启了settings.add_bracket_after_function默认开启见 jedi/api/classes.py#L630-L637函数补全会自动追加(。对参数补全def foo(param0)中补全foo(parcomplete为amjedi/api/classes.py#L639-L662。name_with_symbols类似name但保留符号。对foo(的补全它返回param含等号便于编辑器直接插入带默认参数的调用片段jedi/api/classes.py#L664-L677。get_completion_prefix_length()返回正在补全的前缀长度。isinstan#返回 8foo(par返回 3jedi/api/classes.py#L731-L747。type与BaseName.type相同但针对带缓存的补全_cached_name非空走completion_cache缓存路径以提速jedi/api/classes.py#L716-L729。docstring(rawFalse, fastTrue)补全对象同样支持 docstring当已输入前缀长度 ≥ 3 时自动关闭fast优化因为此时不会加载超过 100 个模块jedi/api/classes.py#L679-L689。Completion.__repr__为Completion: namejedi/api/classes.py#L749-L750。4.2 结合 api.rst 的补全示例docs/docs/api.rst 给出可直接运行的真机示例 import jedi code import json; json.l script jedi.Script(code, pathexample.py) script Script: example.py SameEnvironment: 3.14.0 in /usr completions script.complete(1, 19) completions [Completion: load, Completion: loads] completions[1] Completion: loads completions[1].complete oads completions[1].name loads注意complete返回的是oads从光标位置起的剩余部分而name返回完整名字loads——这正是补全插入与显示名称两个场景的分工。4.3 补全的底层实现脉络Script.complete()内部构造jedi.api.completion.Completion对象注意与返回类同名但不同角色由其complete()方法驱动随后通过filter_names过滤、去重并排序——普通名字排在_开头私有名之前私有名排在__开头魔术名之前见 jedi/api/init.py#L190-L212 与 jedi/api/completion.py。若传入fuzzyTrue则支持模糊补全如ooa匹配foobar此时Completion.complete属性会返回None。五、BaseSignature 与 Signature调用签名对象5.1 BaseSignatureBaseSignature定义于 jedi/api/classes.py#L798由BaseName.get_signatures()返回继承Name并新增两个成员params该签名定义的全部参数返回list[ParamName]包含*args与**kwargs通过get_param_names(resolve_starsTrue)展开星号参数见 jedi/api/classes.py#L807-L817。to_string()签名的文本表示如foo(bar, baz: int, **kwargs)jedi/api/classes.py#L819-L827。5.2 SignatureSignature定义于 jedi/api/classes.py#L830是Script.get_signatures()的返回类型在BaseSignature之上增加调用现场call site信息index当前光标位置对应的参数下标若无法定位则返回None。例如在abs(内部光标处于第 0 个参数index为 0jedi/api/classes.py#L840-L850。bracket_start负责本次调用的括号的(line, column)位置行从 1 开始、列从 0 开始jedi/api/classes.py#L852-L860。Signature.__repr__为Signature: index... foo(bar)形式方便在测试与调试中快速定位当前参数位置。Script.get_signatures()的判定逻辑在 jedi/api/init.py#L433-L470光标必须位于函数调用的括号内部例如abs(# -- cursor返回abs签名而abs()# -- cursor返回空列表。实现通过helpers.get_signature_details分析括号节点再经helpers.cache_signatures缓存签名推断结果最后封装为Signature返回。六、ParamName签名参数对象ParamName定义于 jedi/api/classes.py#L870是BaseSignature.params中每个参数的类型。它继承Name并新增infer_default()推断参数的默认值如def foo(x1):中x的默认值1返回list[Name]jedi/api/classes.py#L871-L878。infer_annotation(**kwargs)推断参数类型注解对应的对象。参数execute_annotation默认为True设为False时不做执行直接返回类本身而非实例jedi/api/classes.py#L880-L887。to_string()参数的简单文本表示如f: Callable[..., Any]jedi/api/classes.py#L889-L897。kind返回inspect.Parameter.kind枚举实例可用于区分位置参数、*args、**kwargs等参数类别jedi/api/classes.py#L899-L906。一个典型场景编辑器拿到Signature.params后遍历ParamName用to_string()渲染签名提示用kind判断当前参数是否可填关键字参数用index来自外层Signature高亮当前参数。七、Refactoring重构结果对象Refactoring定义于 jedi/api/refactoring/init.py#L82由Script.rename()、Script.extract_variable()、Script.extract_function()、Script.inline()返回。它描述一次尚未落盘的重构变更集支持三个核心操作7.1 成员方法get_changed_files()返回Dict[Path, ChangedFile]键为文件路径。ChangedFilejedi/api/refactoring/init.py#L16-L79封装单个文件的变更提供get_diff()、get_new_code()与apply()。其中get_new_code()调用 parso 的grammar.refactor()依据节点替换映射生成新代码get_diff()基于difflib.unified_diff生成标准 unified diff。get_renames()返回Iterable[Tuple[Path, Path]]表示重构伴随的文件重命名如重命名模块文件或包目录见 jedi/api/refactoring/init.py#L114-L118。get_diff()汇总所有文件变更的 unified diff并前置rename from .../rename to ...行描述重命名jedi/api/refactoring/init.py#L120-L127。apply()将整个重构写回磁盘包括所有文件写入与文件重命名jedi/api/refactoring/init.py#L129-L137。7.2 重构的典型工作流编辑器插件标准做法是先预览、后应用调用Script.rename(line, column, new_namebar)等获得Refactoring调用refactoring.get_diff()展示预览给用户确认用户确认后调用refactoring.apply()落盘。需要说明的限制ChangedFile.apply()要求原Script提供真实path对pathNone的脚本会抛出RefactoringError(Cannot apply a refactoring on a Script with pathNone)jedi/api/refactoring/init.py#L69-L76。7.3 底层实现脉络重构实现分散在 jedi/api/refactoring/init.py 与 jedi/api/refactoring/extract.pyrename()收集光标下名字的所有定义树节点构造{tree_name: 新名字}映射对模块/隐式命名空间包会生成文件重命名如__init__.py重命名整个目录见_calculate_rename。inline()反向提取变量将右侧表达式替换到所有引用处对模块、命名空间、内建/扩展对象及多重定义等情形会抛出RefactoringError。extract_variable()/extract_function()将光标处表达式提取为新变量/新函数自动分析输入输出变量见 jedi/api/refactoring/extract.py 中的_find_inputs_and_outputs等。异常类型RefactoringError定义于 jedi/api/exceptions.py与InternalError一同在 docs/docs/api.rst 的 Errors 一节中被引用。八、SyntaxError语法错误对象SyntaxError定义于 jedi/api/errors.py#L11由Script.get_syntax_errors()返回经parso_to_jedi_errors将 parso 错误包装为 Jedi 错误见 jedi/api/errors.py#L7-L8。注意它与 Python 内建SyntaxError无关专门描述Python 文件中的语法错误。成员属性line/column错误起始位置行从 1 开始、列从 0 开始。until_line/until_column错误结束位置行从 1 开始、列从 0 开始。get_message()错误消息文本。__repr__为SyntaxError from(line, column) to(line, column)便于测试断言。编辑器可据此为错误区域绘制波浪线用line/column与until_line/until_column圈定错误区间用get_message()提供悬停说明。九、组合实战一次完整的补全 推断 引用流程将以上返回类串联起来即可实现编辑器中最常见的交互。下面结合 docs/docs/api.rst 的 doctest 演示goto/infer/get_references的返回类行为。9.1 goto 与 infer 的差异goto不追导入与赋值语句返回第一个定义infer追查复杂路径返回最终定义 import jedi code \ ... def my_func(): ... print called ... ... alias my_func ... my_list [1, None, alias] ... inception my_list[2] ... ... inception() script jedi.Script(code) script.goto(8, 1) [Name full_name__main__.inception, descriptioninception my_list[2]] script.infer(8, 1) [Name full_name__main__.my_func, descriptiondef my_func]9.2 引用收集 code \ ... x 3 ... if 1 2: ... x 4 ... else: ... del x script jedi.Script(code) rns script.get_references(5, 8) rns [Name full_name__main__.x, descriptionx 3, Name full_name__main__.x, descriptionx 4, Name full_name__main__.x, descriptiondel x] rns[1].line 3 rns[1].column 4这里的每个元素都是Name可通过line/column精准定位配合is_definition()区分定义与引用——这正是Script.rename()内部获取全部引用位置的依据jedi/api/init.py#L589-L600。9.3 补全结果的类型推断补全结果的infer()会按完整名字进行推断测试 test/test_api/test_api_classes_follow_definition.py 对此有专门验证例如def test_follow_import_incomplete(Script, environment): Completion on incomplete imports should always take the full completion to do any type inference. datetime check_follow_definition_types(Script, import itertool) assert datetime [module] # ... alias check_follow_definition_types(Script, import io as abcd; abcd) assert alias [module]同一测试文件还验证了嵌套导入import pkg.mod1; pkg.mod1.a推断为instance、别名导入等场景下补全Completion.infer()的类型准确性是理解返回类行为的最佳参考。十、快速参考返回类属性/方法一览返回类核心成员典型用途BaseNamename、type、full_name、module_path、module_name、line、column、description、docstring()、get_signatures()、goto()、infer()、parent()、execute()、get_type_hint()、get_line_code()所有返回类的公共接口Namedefined_names()、is_definition()、相等性比较跳转定义、引用定位、类型推断Completioncomplete、name_with_symbols、get_completion_prefix_length()补全插入与显示BaseSignatureparams、to_string()签名文本与参数列表Signatureindex、bracket_start当前光标所在参数高亮ParamNameinfer_default()、infer_annotation()、to_string()、kind参数默认值/注解/类别Refactoringget_changed_files()、get_renames()、get_diff()、apply()重构预览与落盘SyntaxErrorline、column、until_line、until_column、get_message()语法错误定位与提示值得注意的是Jedi 官方对插件的建议是Script与Interpreter是入口本文的返回类则是所有入口方法的返回值契约。从 docs/docs/api.rst 可以看到Script.complete、Script.goto、Script.infer、Script.get_signatures、Script.get_references等全部公开方法其返回类型都落在本文描述的类体系内。理解这一体系即可无障碍地消费 Jedi 的全部分析能力。赞分享开发工具【免费下载链接】jediAwesome autocompletion, static analysis and refactoring library for python项目地址https://gitcode.com/gh_mirrors/je/jedi点击查看免费下载相关推荐Jedi与函数签名参数类型推断和返回值分析的完整方案Jedi作为Python生态系统中功能强大的自动补全和静态分析库在函数签名分析方面展现出了卓越的能力。无论是参数类型推断还是返回值分析Jedi都能为开发者提开发工具AutoHarness的/learn技能完全指南一句话沉淀本会话经验让经验不再流失AutoHarness的/learn技能完全指南一句话沉淀本会话经验让经验不再流失 AutoHarness 是 Claude Code 的自学习技能层 其PHPStan 错误详解return.nestedUnusedType —— 收窄返回类型中从未实际返回的嵌套类型PHPStan 错误详解return.nestedUnusedType —— 收窄返回类型中从未实际返回的嵌套类型 导读 return.nestedUnuse开发工具代码质量静态分析上一篇yt-dlp-gui终极指南从命令行恐惧到视频下载高手下一篇Mac清理新神器Pearcleaner帮你三步搞定顽固残留文件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
开发工具【免费下载链接】jediAwesome autocompletion, static analysis and refactoring library for python项目地址https://gitcode.com/gh_mirrors/je/jedi点击查看免费下载导读本文以 docs/docs/api-classes.rst 为骨架系统讲解 Jedi 对外 API 的核心返回类BaseName、Name、Completion、BaseSignature、Signature、ParamName、Refactoring与SyntaxError。这些类承载了 Jedi 补全、跳转、类型推断、签名提示与重构等全部操作的结果数据是编辑器/IDE 插件开发者理解并消费 Jedi 能力的第一站。读完本文你将掌握每个返回类的全部公开属性与方法、它们与Script/Interpreter各方法的对应关系以及如何用源码与测试验证行为。一、这些类从何而来API 返回类在整个 Jedi 中的位置Jedi 的 API 由几个部分组成见 docs/docs/api.rst入口类Script与Interpreter、返回类、环境Environment管理与项目Project管理。其中返回类几乎是 API 的全部血肉——它们承载了所有操作的有趣信息。正如 jedi/api/classes.py 模块开头注释所言这些类构成了 API 的最大部分因为它们包含所有操作的相关信息。返回类与Script方法的对应关系如下返回类由哪个方法产生NameScript.goto()、Script.infer()、Script.get_names()、Script.get_references()、Script.search()、Script.get_context()CompletionScript.complete()、Script.complete_search()SignatureScript.get_signatures()ParamNameBaseSignature.params签名内部的参数对象RefactoringScript.rename()、Script.extract_variable()、Script.extract_function()、Script.inline()SyntaxErrorScript.get_syntax_errors()这些类的定义位置集中在两个文件返回类主体在 jedi/api/classes.py重构返回类在 jedi/api/refactoring/init.py语法错误返回类在 jedi/api/errors.py。二、BaseName所有定义、补全与签名对象的抽象基类BaseName定义于 jedi/api/classes.py#L58是所有 definitions、completions 和 signatures 的基类。它不直接对外返回但Name、Completion、BaseSignature均继承自它因此其公开成员几乎全员可用。2.1 核心元数据属性name变量/函数/类/模块的名字。例如x None返回x。类型为str 或 None。实现上调用self._name.get_public_name()jedi/api/classes.py#L110-L119。type定义的类型。合法值包括module、class、instance、function、param、path、keyword、property与statement。对于from X import Y这类导入Jedi 会尝试解析真实对象以给出准确的类型jedi/api/classes.py#L121-L190。文档自带 doctest 演示 from jedi import Script source ... import keyword ... ... class C: ... pass ... ... class D: ... pass ... ... x D() ... ... def f(): ... pass ... ... for variable in [keyword, f, C, x]: ... variable script Script(source) defs script.infer() defs sorted(defs, keylambda d: d.line) [d.type for d in defs] [module, class, instance, function]module_path定义所在模块的文件路径如/usr/lib/python3.14/os.py。编译型compiled模块不返回路径stub 模块则正常返回jedi/api/classes.py#L96-L108。module_name模块名类似模块内的__name__。import json的 infer 结果返回jsonjedi/api/classes.py#L192-L205。in_builtin_module()返回是否为内置builtin模块中的名字。stub 模块会检查其对应的非 stub 值是否 compiledjedi/api/classes.py#L207-L214。full_name点分隔的完整路径形如module[.submodule[...]][.object]。例如os.path.join。Jedi 会做路径归一化映射如posixpath→os.path、_io→io映射表定义于 jedi/api/classes.py#L62-L79使返回的名字更贴近用户直觉 from jedi import Script source ... import os ... os.path.join script Script(source, pathexample.py) print(script.infer(3, len(os.path.join))[0].full_name) os.path.joindescription人类可读的描述测试中大量使用。函数返回def f、类返回class C、isinstance返回def isinstance对语句则返回压缩后的单行代码自动剔除注释与多余空白见 jedi/api/classes.py#L318-L365。2.2 位置与范围信息Jedi 的行号约定与常规一致行从 1 开始列从 0 开始。line/column定义发生的位置若名字无位置如某些关键字返回Nonejedi/api/classes.py#L216-L230。get_definition_start_position()定义范围的起始(row, column)对function/class返回整个定义块含函数体的结束位置行从 1 开始、列从 0 开始jedi/api/classes.py#L232-L263。get_line_code(before0, after0)返回该名字所在行的代码片段可扩展前后若干行内置模块无源码时返回空字符串jedi/api/classes.py#L534-L554。2.3 文档字符串与签名docstring(rawFalse, fastTrue)返回文档字符串并自动在正文前拼接函数签名这是 Jedi 的特色增强 from jedi import Script source \ ... def f(a, b1): ... Document for function f. ... script Script(source, pathexample.py) doc script.infer(1, len(def f))[0].docstring() print(doc) f(a, b1) BLANKLINE Document for function f. print(script.infer(1, len(def f))[0].docstring(rawTrue)) Document for function f.参数说明rawTrue返回真实 docstring不拼接签名fastTrue表示不深追一级浅层导入如import foo但会追from foo import bar以提升速度jedi/api/classes.py#L265-L307。get_signatures()返回该函数/类的所有可能签名返回list[BaseSignature]当使用带overload的 stub 时会出现多个签名jedi/api/classes.py#L573-L584。execute()通过类型推断执行该标识符返回执行后的对象如类实例类型为list[Name]jedi/api/classes.py#L586-L594。get_type_hint()返回类型提示字符串如Iterable[int]或Union[int, str]该方法对函数可能较慢jedi/api/classes.py#L596-L607。2.4 导航与推断方法goto(follow_importsFalse, follow_builtin_importsFalse, only_stubsFalse, prefer_stubsFalse)等价于Script.goto但作用于当前名字返回list[Name]jedi/api/classes.py#L425-L454。infer(only_stubsFalse, prefer_stubsFalse)等价于Script.infer。官方文档强烈建议不要用它对补全结果做批量推断——它会追查所有结果在 numpy 这类上千补全的场景下非常慢只适合少量≤20 个对象的读取jedi/api/classes.py#L456-L491。注意only_stubs与prefer_stubs不能同时为真源码有assert校验。parent()返回该标识符的父作用域模块/类/函数类型为Namejedi/api/classes.py#L493-L524。is_stub()名字是否定义在 stub 文件中jedi/api/classes.py#L406-L413。is_side_effect()判断名字是否以self.foo 3形式定义——对self返回False对foo返回Truejedi/api/classes.py#L415-L423。BaseName的__repr__格式为ClassName full_name..., description...这也是调试与测试断言中常见的形态jedi/api/classes.py#L526-L532。三、Name跳转与推断的主力返回类型Name定义于 jedi/api/classes.py#L753文档明确说明Name对象由许多 API 返回包括Script.goto与Script.infer。它继承BaseName的全部能力并新增defined_names()列出子定义如类中的方法。例如对一个Name调用会返回其内部定义的子Name列表按起始位置排序jedi/api/classes.py#L761-L773。模块级辅助函数defined_namesjedi/api/classes.py#L38-L51是其底层实现通过获取 scope 的 filters 枚举名字。is_definition()True表示是语句/函数/类中定义的定义名False表示对某个定义的引用jedi/api/classes.py#L775-L783。相等性与哈希Name实现了__eq__/__ne__/__hash__比较依据为起始位置、模块路径、名字与 inference statejedi/api/classes.py#L785-L795。因此Script.infer()返回的列表天然可去重、可排序。Name的典型用法对Script.infer()或Script.get_references()的结果遍历读取name、type、line、column、module_path、docstring等字段用于编辑器高亮、悬停提示或跳转到定义。四、Completion补全结果对象Completion定义于 jedi/api/classes.py#L610由Script.complete()返回在BaseName之上提供补全专属信息。4.1 核心补全属性complete返回剩余待补全的字符非模糊补全时有效模糊补全返回None。例如光标在isinstan#处返回ce。若开启了settings.add_bracket_after_function默认开启见 jedi/api/classes.py#L630-L637函数补全会自动追加(。对参数补全def foo(param0)中补全foo(parcomplete为amjedi/api/classes.py#L639-L662。name_with_symbols类似name但保留符号。对foo(的补全它返回param含等号便于编辑器直接插入带默认参数的调用片段jedi/api/classes.py#L664-L677。get_completion_prefix_length()返回正在补全的前缀长度。isinstan#返回 8foo(par返回 3jedi/api/classes.py#L731-L747。type与BaseName.type相同但针对带缓存的补全_cached_name非空走completion_cache缓存路径以提速jedi/api/classes.py#L716-L729。docstring(rawFalse, fastTrue)补全对象同样支持 docstring当已输入前缀长度 ≥ 3 时自动关闭fast优化因为此时不会加载超过 100 个模块jedi/api/classes.py#L679-L689。Completion.__repr__为Completion: namejedi/api/classes.py#L749-L750。4.2 结合 api.rst 的补全示例docs/docs/api.rst 给出可直接运行的真机示例 import jedi code import json; json.l script jedi.Script(code, pathexample.py) script Script: example.py SameEnvironment: 3.14.0 in /usr completions script.complete(1, 19) completions [Completion: load, Completion: loads] completions[1] Completion: loads completions[1].complete oads completions[1].name loads注意complete返回的是oads从光标位置起的剩余部分而name返回完整名字loads——这正是补全插入与显示名称两个场景的分工。4.3 补全的底层实现脉络Script.complete()内部构造jedi.api.completion.Completion对象注意与返回类同名但不同角色由其complete()方法驱动随后通过filter_names过滤、去重并排序——普通名字排在_开头私有名之前私有名排在__开头魔术名之前见 jedi/api/init.py#L190-L212 与 jedi/api/completion.py。若传入fuzzyTrue则支持模糊补全如ooa匹配foobar此时Completion.complete属性会返回None。五、BaseSignature 与 Signature调用签名对象5.1 BaseSignatureBaseSignature定义于 jedi/api/classes.py#L798由BaseName.get_signatures()返回继承Name并新增两个成员params该签名定义的全部参数返回list[ParamName]包含*args与**kwargs通过get_param_names(resolve_starsTrue)展开星号参数见 jedi/api/classes.py#L807-L817。to_string()签名的文本表示如foo(bar, baz: int, **kwargs)jedi/api/classes.py#L819-L827。5.2 SignatureSignature定义于 jedi/api/classes.py#L830是Script.get_signatures()的返回类型在BaseSignature之上增加调用现场call site信息index当前光标位置对应的参数下标若无法定位则返回None。例如在abs(内部光标处于第 0 个参数index为 0jedi/api/classes.py#L840-L850。bracket_start负责本次调用的括号的(line, column)位置行从 1 开始、列从 0 开始jedi/api/classes.py#L852-L860。Signature.__repr__为Signature: index... foo(bar)形式方便在测试与调试中快速定位当前参数位置。Script.get_signatures()的判定逻辑在 jedi/api/init.py#L433-L470光标必须位于函数调用的括号内部例如abs(# -- cursor返回abs签名而abs()# -- cursor返回空列表。实现通过helpers.get_signature_details分析括号节点再经helpers.cache_signatures缓存签名推断结果最后封装为Signature返回。六、ParamName签名参数对象ParamName定义于 jedi/api/classes.py#L870是BaseSignature.params中每个参数的类型。它继承Name并新增infer_default()推断参数的默认值如def foo(x1):中x的默认值1返回list[Name]jedi/api/classes.py#L871-L878。infer_annotation(**kwargs)推断参数类型注解对应的对象。参数execute_annotation默认为True设为False时不做执行直接返回类本身而非实例jedi/api/classes.py#L880-L887。to_string()参数的简单文本表示如f: Callable[..., Any]jedi/api/classes.py#L889-L897。kind返回inspect.Parameter.kind枚举实例可用于区分位置参数、*args、**kwargs等参数类别jedi/api/classes.py#L899-L906。一个典型场景编辑器拿到Signature.params后遍历ParamName用to_string()渲染签名提示用kind判断当前参数是否可填关键字参数用index来自外层Signature高亮当前参数。七、Refactoring重构结果对象Refactoring定义于 jedi/api/refactoring/init.py#L82由Script.rename()、Script.extract_variable()、Script.extract_function()、Script.inline()返回。它描述一次尚未落盘的重构变更集支持三个核心操作7.1 成员方法get_changed_files()返回Dict[Path, ChangedFile]键为文件路径。ChangedFilejedi/api/refactoring/init.py#L16-L79封装单个文件的变更提供get_diff()、get_new_code()与apply()。其中get_new_code()调用 parso 的grammar.refactor()依据节点替换映射生成新代码get_diff()基于difflib.unified_diff生成标准 unified diff。get_renames()返回Iterable[Tuple[Path, Path]]表示重构伴随的文件重命名如重命名模块文件或包目录见 jedi/api/refactoring/init.py#L114-L118。get_diff()汇总所有文件变更的 unified diff并前置rename from .../rename to ...行描述重命名jedi/api/refactoring/init.py#L120-L127。apply()将整个重构写回磁盘包括所有文件写入与文件重命名jedi/api/refactoring/init.py#L129-L137。7.2 重构的典型工作流编辑器插件标准做法是先预览、后应用调用Script.rename(line, column, new_namebar)等获得Refactoring调用refactoring.get_diff()展示预览给用户确认用户确认后调用refactoring.apply()落盘。需要说明的限制ChangedFile.apply()要求原Script提供真实path对pathNone的脚本会抛出RefactoringError(Cannot apply a refactoring on a Script with pathNone)jedi/api/refactoring/init.py#L69-L76。7.3 底层实现脉络重构实现分散在 jedi/api/refactoring/init.py 与 jedi/api/refactoring/extract.pyrename()收集光标下名字的所有定义树节点构造{tree_name: 新名字}映射对模块/隐式命名空间包会生成文件重命名如__init__.py重命名整个目录见_calculate_rename。inline()反向提取变量将右侧表达式替换到所有引用处对模块、命名空间、内建/扩展对象及多重定义等情形会抛出RefactoringError。extract_variable()/extract_function()将光标处表达式提取为新变量/新函数自动分析输入输出变量见 jedi/api/refactoring/extract.py 中的_find_inputs_and_outputs等。异常类型RefactoringError定义于 jedi/api/exceptions.py与InternalError一同在 docs/docs/api.rst 的 Errors 一节中被引用。八、SyntaxError语法错误对象SyntaxError定义于 jedi/api/errors.py#L11由Script.get_syntax_errors()返回经parso_to_jedi_errors将 parso 错误包装为 Jedi 错误见 jedi/api/errors.py#L7-L8。注意它与 Python 内建SyntaxError无关专门描述Python 文件中的语法错误。成员属性line/column错误起始位置行从 1 开始、列从 0 开始。until_line/until_column错误结束位置行从 1 开始、列从 0 开始。get_message()错误消息文本。__repr__为SyntaxError from(line, column) to(line, column)便于测试断言。编辑器可据此为错误区域绘制波浪线用line/column与until_line/until_column圈定错误区间用get_message()提供悬停说明。九、组合实战一次完整的补全 推断 引用流程将以上返回类串联起来即可实现编辑器中最常见的交互。下面结合 docs/docs/api.rst 的 doctest 演示goto/infer/get_references的返回类行为。9.1 goto 与 infer 的差异goto不追导入与赋值语句返回第一个定义infer追查复杂路径返回最终定义 import jedi code \ ... def my_func(): ... print called ... ... alias my_func ... my_list [1, None, alias] ... inception my_list[2] ... ... inception() script jedi.Script(code) script.goto(8, 1) [Name full_name__main__.inception, descriptioninception my_list[2]] script.infer(8, 1) [Name full_name__main__.my_func, descriptiondef my_func]9.2 引用收集 code \ ... x 3 ... if 1 2: ... x 4 ... else: ... del x script jedi.Script(code) rns script.get_references(5, 8) rns [Name full_name__main__.x, descriptionx 3, Name full_name__main__.x, descriptionx 4, Name full_name__main__.x, descriptiondel x] rns[1].line 3 rns[1].column 4这里的每个元素都是Name可通过line/column精准定位配合is_definition()区分定义与引用——这正是Script.rename()内部获取全部引用位置的依据jedi/api/init.py#L589-L600。9.3 补全结果的类型推断补全结果的infer()会按完整名字进行推断测试 test/test_api/test_api_classes_follow_definition.py 对此有专门验证例如def test_follow_import_incomplete(Script, environment): Completion on incomplete imports should always take the full completion to do any type inference. datetime check_follow_definition_types(Script, import itertool) assert datetime [module] # ... alias check_follow_definition_types(Script, import io as abcd; abcd) assert alias [module]同一测试文件还验证了嵌套导入import pkg.mod1; pkg.mod1.a推断为instance、别名导入等场景下补全Completion.infer()的类型准确性是理解返回类行为的最佳参考。十、快速参考返回类属性/方法一览返回类核心成员典型用途BaseNamename、type、full_name、module_path、module_name、line、column、description、docstring()、get_signatures()、goto()、infer()、parent()、execute()、get_type_hint()、get_line_code()所有返回类的公共接口Namedefined_names()、is_definition()、相等性比较跳转定义、引用定位、类型推断Completioncomplete、name_with_symbols、get_completion_prefix_length()补全插入与显示BaseSignatureparams、to_string()签名文本与参数列表Signatureindex、bracket_start当前光标所在参数高亮ParamNameinfer_default()、infer_annotation()、to_string()、kind参数默认值/注解/类别Refactoringget_changed_files()、get_renames()、get_diff()、apply()重构预览与落盘SyntaxErrorline、column、until_line、until_column、get_message()语法错误定位与提示值得注意的是Jedi 官方对插件的建议是Script与Interpreter是入口本文的返回类则是所有入口方法的返回值契约。从 docs/docs/api.rst 可以看到Script.complete、Script.goto、Script.infer、Script.get_signatures、Script.get_references等全部公开方法其返回类型都落在本文描述的类体系内。理解这一体系即可无障碍地消费 Jedi 的全部分析能力。赞分享开发工具【免费下载链接】jediAwesome autocompletion, static analysis and refactoring library for python项目地址https://gitcode.com/gh_mirrors/je/jedi点击查看免费下载相关推荐Jedi与函数签名参数类型推断和返回值分析的完整方案Jedi作为Python生态系统中功能强大的自动补全和静态分析库在函数签名分析方面展现出了卓越的能力。无论是参数类型推断还是返回值分析Jedi都能为开发者提开发工具AutoHarness的/learn技能完全指南一句话沉淀本会话经验让经验不再流失AutoHarness的/learn技能完全指南一句话沉淀本会话经验让经验不再流失 AutoHarness 是 Claude Code 的自学习技能层 其PHPStan 错误详解return.nestedUnusedType —— 收窄返回类型中从未实际返回的嵌套类型PHPStan 错误详解return.nestedUnusedType —— 收窄返回类型中从未实际返回的嵌套类型 导读 return.nestedUnuse开发工具代码质量静态分析上一篇yt-dlp-gui终极指南从命令行恐惧到视频下载高手下一篇Mac清理新神器Pearcleaner帮你三步搞定顽固残留文件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
