API Return Classes

Abstract Base Class

class jedi.api.classes.BaseName(inference_state, name)

Bases: object

The base class for all definitions, completions and signatures.

module_path

Shows the file path of a module. e.g. /usr/lib/python2.7/os.py

Return type:str or None

name

Name of variable/function/class/module.

For example, for x = None it returns 'x'.

Return type:str or None

type

The type of the definition.

Here is an example of the value of this attribute. Let’s consider the following source. As what is in variable is unambiguous to Jedi, jedi.Script.infer() should return a list of definition for sys, f, C and x.

>>> from jedi._compatibility import no_unicode_pprint
>>> 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()

Before showing what is in defs, let’s sort it by line so that it is easy to relate the result to the source code.

>>> defs = sorted(defs, key=lambda d: d.line)
>>> no_unicode_pprint(defs)  # doctest: +NORMALIZE_WHITESPACE
[<Name full_name='keyword', description='module keyword'>,
 <Name full_name='__main__.C', description='class C'>,
 <Name full_name='__main__.D', description='instance D'>,
 <Name full_name='__main__.f', description='def f'>]

Finally, here is what you can get from type:

>>> defs = [str(d.type) for d in defs]  # It's unicode and in Py2 has u before it.
>>> defs[0]
'module'
>>> defs[1]
'class'
>>> defs[2]
'instance'
>>> defs[3]
'function'

Valid values for type are module, class, instance, function, param, path, keyword and statement.

module_name

The module name, a bit similar to what __name__ is in a random Python module.

>>> from jedi import Script
>>> source = 'import json'
>>> script = Script(source, path='example.py')
>>> d = script.infer()[0]
>>> print(d.module_name)  # doctest: +ELLIPSIS
json

in_builtin_module()

Returns True, if this is a builtin module.

line

The line where the definition occurs (starting with 1).

column

The column where the definition occurs (starting with 0).

get_definition_start_position()

The (row, column) of the start of the definition range. Rows start with 1, columns start with 0.

Return type:Optional[Tuple[int, int]]

get_definition_end_position()

The (row, column) of the end of the definition range. Rows start with 1, columns start with 0.

Return type:Optional[Tuple[int, int]]

docstring(raw=False, fast=True)

Return a document string for this completion object.

Example:

>>> from jedi import Script
>>> source = '''\
... def f(a, b=1):
...     "Document for function f."
... '''
>>> script = Script(source, path='example.py')
>>> doc = script.infer(1, len('def f'))[0].docstring()
>>> print(doc)
f(a, b=1)
<BLANKLINE>
Document for function f.

Notice that useful extra information is added to the actual docstring, e.g. function signatures are prepended to their docstrings. If you need the actual docstring, use raw=True instead.

>>> print(script.infer(1, len('def f'))[0].docstring(raw=True))
Document for function f.

Parameters:fast – Don’t follow imports that are only one level deep like import foo, but follow from foo import bar. This makes sense for speed reasons. Completing import a is slow if you use the foo.docstring(fast=False) on every object, because it parses all libraries starting with a.

description

A description of the Name object, which is heavily used in testing. e.g. for isinstance it returns def isinstance.

Example:

>>> from jedi._compatibility import no_unicode_pprint
>>> from jedi import Script
>>> source = '''
... def f():
...     pass
...
... class C:
...     pass
...
... variable = f if random.choice([0,1]) else C'''
>>> script = Script(source)  # line is maximum by default
>>> defs = script.infer(column=3)
>>> defs = sorted(defs, key=lambda d: d.line)
>>> no_unicode_pprint(defs)  # doctest: +NORMALIZE_WHITESPACE
[<Name full_name='__main__.f', description='def f'>,
 <Name full_name='__main__.C', description='class C'>]
>>> str(defs[0].description)  # strip literals in python2
'def f'
>>> str(defs[1].description)
'class C'

full_name

Dot-separated path of this object.

It is in the form of <module>[.<submodule>[...]][.<object>]. It is useful when you want to look up Python manual of the object at hand.

Example:

>>> from jedi import Script
>>> source = '''
... import os
... os.path.join'''
>>> script = Script(source, path='example.py')
>>> print(script.infer(3, len('os.path.join'))[0].full_name)
os.path.join

Notice that it returns 'os.path.join' instead of (for example) 'posixpath.join'. This is not correct, since the modules name would be <module 'posixpath' ...>`. However most users find the latter more practical.

is_stub()

Returns True if the current name is defined in a stub file.

is_side_effect()

Checks if a name is defined as self.foo = 3. In case of self, this function would return False, for foo it would return True.

goto(**kwargs)

Like Script.goto() (also supports the same params), but does it for the current name. This is typically useful if you are using something like Script.get_names().

Parameters:

• follow_imports – The goto call will follow imports.
• follow_builtin_imports – If follow_imports is True will try to look up names in builtins (i.e. compiled or extension modules).
• only_stubs – Only return stubs for this goto call.
• prefer_stubs – Prefer stubs to Python objects for this goto call.

Return type:

list of Name

infer(**kwargs)

Like Script.infer(), it can be useful to understand which type the current name has.

Return the actual definitions. I strongly recommend not using it for your completions, because it might slow down Jedi. If you want to read only a few objects (<=20), it might be useful, especially to get the original docstrings. The basic problem of this function is that it follows all results. This means with 1000 completions (e.g. numpy), it’s just very, very slow.

Parameters:

• only_stubs – Only return stubs for this goto call.
• prefer_stubs – Prefer stubs to Python objects for this type inference call.

Return type:

list of Name

parent()

Returns the parent scope of this identifier.

Return type:Name

get_line_code(before=0, after=0)

Returns the line of code where this object was defined.

Parameters:

• before – Add n lines before the current line to the output.
• after – Add n lines after the current line to the output.

Return str:

Returns the line(s) of code or an empty string if it’s a builtin.

get_signatures()

Returns all potential signatures for a function or a class. Multiple signatures are typical if you use Python stubs with @overload.

Return type:list of BaseSignature

execute()

Uses type inference to “execute” this identifier and returns the executed objects.

Return type:list of Name

get_type_hint()

Returns type hints like Iterable[int] or Union[int, str].

This method might be quite slow, especially for functions. The problem is finding executions for those functions to return something like Callable[[int, str], str].

Return type:str

Name

class jedi.api.classes.Name(inference_state, definition)

Bases: jedi.api.classes.BaseName

Name objects are returned from many different APIs including Script.goto() or Script.infer().

defined_names(*args, **kwargs)

List sub-definitions (e.g., methods in class).

Return type:list of Name

is_definition()

Returns True, if defined as a name in a statement, function or class. Returns False, if it’s a reference to such a definition.

Completion

class jedi.api.classes.Completion(inference_state, name, stack, like_name_length, is_fuzzy, cached_name=None)

Bases: jedi.api.classes.BaseName

Completion objects are returned from Script.complete(). They provide additional information about a completion.

complete

Only works with non-fuzzy completions. Returns None if fuzzy completions are used.

Return the rest of the word, e.g. completing isinstance:

isinstan# <-- Cursor is here

would return the string ‘ce’. It also adds additional stuff, depending on your settings.py.

Assuming the following function definition:

def foo(param=0):
    pass

completing foo(par would give a Completion which complete would be am=.

name_with_symbols

Similar to name, but like name returns also the symbols, for example assuming the following function definition:

def foo(param=0):
    pass

completing foo( would give a Completion which name_with_symbols would be “param=”.

docstring(raw=False, fast=True)

Documented under BaseName.docstring().

type

Documented under BaseName.type().

BaseSignature

class jedi.api.classes.BaseSignature(inference_state, signature)

Bases: jedi.api.classes.Name

These signatures are returned by BaseName.get_signatures() calls.

params

Returns definitions for all parameters that a signature defines. This includes stuff like *args and **kwargs.

Return type:list of ParamName

to_string()

Returns a text representation of the signature. This could for example look like foo(bar, baz: int, **kwargs).

Return type:str

Signature

class jedi.api.classes.Signature(inference_state, signature, call_details)

Bases: jedi.api.classes.BaseSignature

A full signature object is the return value of Script.get_signatures().

index

Returns the param index of the current cursor position. Returns None if the index cannot be found in the curent call.

Return type:int

bracket_start

Returns a line/column tuple of the bracket that is responsible for the last function call. The first line is 1 and the first column 0.

Return type:int, int

ParamName

class jedi.api.classes.ParamName(inference_state, definition)

Bases: jedi.api.classes.Name

infer_default()

Returns default values like the 1 of def foo(x=1):.

Return type:list of Name

infer_annotation(**kwargs)

Parameters:execute_annotation – Default True; If False, values are not executed and classes are returned instead of instances. Return type:list of Name

to_string()

Returns a simple representation of a param, like f: Callable[..., Any].

Return type:str

kind

Returns an enum instance of inspect’s Parameter enum.

Return type:inspect.Parameter.kind

Refactoring

class jedi.api.refactoring.Refactoring(inference_state, file_to_node_changes, renames=())

Bases: object

get_changed_files()

Returns a path to ChangedFile map.

get_renames()

Files can be renamed in a refactoring.

Returns Iterable[Tuple[str, str]].

apply()

Applies the whole refactoring to the files, which includes renames.

class jedi.api.errors.SyntaxError(parso_error)

Bases: object

Syntax errors are generated by Script.get_syntax_errors().

line

The line where the error starts (starting with 1).

column

The column where the error starts (starting with 0).

until_line

The line where the error ends (starting with 1).

until_column

The column where the error ends (starting with 0).