def __init__(self, source, namespaces, **kwds):
"""
Parse `source` and mixin interpreted Python objects from `namespaces`.
:type source: str
:arg source: Code to parse.
:type namespaces: list of dict
:arg namespaces: a list of namespace dictionaries such as the one
returned by :func:`locals`.
Other optional arguments are same as the ones for :class:`Script`.
If `line` and `column` are None, they are assumed be at the end of
`source`.
"""
if type(namespaces) is not list or len(namespaces) == 0 or \
any([type(x) is not dict for x in namespaces]):
raise TypeError("namespaces must be a non-empty list of dict")
super(Interpreter, self).__init__(source, **kwds)
self.namespaces = namespaces
# Don't use the fast parser, because it does crazy stuff that we don't
# need in our very simple and small code here (that is always
# changing).
self._parser = UserContextParser(self._grammar,
self.source,
self._orig_path,
self._pos,
self._user_context,
self._parsed_callback,
use_fast_parser=False)
interpreter.add_namespaces_to_parser(self._evaluator, namespaces,
self._parser.module())
def test_user_statement_on_import():
"""github #285"""
s = u("from datetime import (\n" " time)")
for pos in [(2, 1), (2, 4)]:
p = UserContextParser(load_grammar(), s, None, pos, None).user_stmt()
assert isinstance(p, pt.Import)
assert [str(n) for n in p.get_defined_names()] == ['time']
def test_user_statement_on_import():
"""github #285"""
s = u("from datetime import (\n" " time)")
for pos in [(2, 1), (2, 4)]:
p = UserContextParser(load_grammar(), s, None, pos, None).user_stmt()
assert isinstance(p, pt.Import)
assert [str(n) for n in p.get_defined_names()] == ["time"]
def test_user_statement_on_import():
"""github #285"""
s = u("from datetime import (\n"
" time)")
for pos in [(2, 1), (2, 4)]:
p = UserContextParser(s, None, pos, None).user_stmt()
assert isinstance(p, pr.Import)
assert p.defunct is False
assert [str(n) for n in p.get_defined_names()] == ['time']
def __init__(self,
source=None,
line=None,
column=None,
path=None,
encoding='utf-8',
source_path=None,
source_encoding=None,
sys_path=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.",
DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.",
DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
self.source = common.source_to_unicode(source, encoding)
lines = common.splitlines(self.source)
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_time_caches()
debug.reset_time()
self._grammar = load_grammar('grammar%s.%s' % sys.version_info[:2])
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self._grammar, self.source, path,
self._pos, self._user_context,
self._parsed_callback)
if sys_path is None:
venv = os.getenv('VIRTUAL_ENV')
if venv:
sys_path = list(get_venv_path(venv))
self._evaluator = Evaluator(self._grammar, sys_path=sys_path)
debug.speed('init')
def __init__(self, source, namespaces, **kwds):
"""
Parse `source` and mixin interpreted Python objects from `namespaces`.
:type source: str
:arg source: Code to parse.
:type namespaces: list of dict
:arg namespaces: a list of namespace dictionaries such as the one
returned by :func:`locals`.
Other optional arguments are same as the ones for :class:`Script`.
If `line` and `column` are None, they are assumed be at the end of
`source`.
"""
if type(namespaces) is not list or len(namespaces) == 0 or \
any([type(x) is not dict for x in namespaces]):
raise TypeError("namespaces must be a non-empty list of dict")
super(Interpreter, self).__init__(source, **kwds)
self.namespaces = namespaces
# Don't use the fast parser, because it does crazy stuff that we don't
# need in our very simple and small code here (that is always
# changing).
self._parser = UserContextParser(self._grammar, self.source,
self._orig_path, self._pos,
self._user_context, self._parsed_callback,
use_fast_parser=False)
interpreter.add_namespaces_to_parser(self._evaluator, namespaces,
self._parser.module())
def __init__(self, source=None, line=None, column=None, path=None,
encoding='utf-8', source_path=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.", DeprecationWarning)
path = source_path
self._source_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
lines = source.splitlines() or ['']
if source and source[-1] == '\n':
lines.append('')
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_caches()
debug.reset_time()
self.source = common.source_to_unicode(source, encoding)
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self.source, path, self._pos, self._user_context)
self._evaluator = Evaluator()
debug.speed('init')
def __init__(self,
source=None,
line=None,
column=None,
path=None,
encoding='utf-8',
source_path=None,
source_encoding=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.",
DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.",
DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
lines = source.splitlines() or ['']
if source and source[-1] == '\n':
lines.append('')
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_caches()
debug.reset_time()
self.source = common.source_to_unicode(source, encoding)
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self.source, path, self._pos,
self._user_context)
self._evaluator = Evaluator()
debug.speed('init')
def __init__(self, source=None, line=None, column=None, path=None,
encoding='utf-8', source_path=None, source_encoding=None,
sys_path=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.", DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.", DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
self.source = common.source_to_unicode(source, encoding)
lines = common.splitlines(self.source)
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_time_caches()
debug.reset_time()
self._grammar = load_grammar('grammar%s.%s' % sys.version_info[:2])
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self._grammar, self.source, path,
self._pos, self._user_context,
self._parsed_callback)
if sys_path is None:
venv = os.getenv('VIRTUAL_ENV')
if venv:
sys_path = list(get_venv_path(venv))
self._evaluator = Evaluator(self._grammar, sys_path=sys_path)
debug.speed('init')
def __init__(self, source=None, line=None, column=None, path=None,
encoding='utf-8', source_path=None, source_encoding=None,
resolve_variables_to_types=True):
if source_path is not None:
warnings.warn("Use path instead of source_path.", DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.", DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
self.source = common.source_to_unicode(source, encoding)
lines = common.splitlines(self.source)
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
if not cache.never_clear_cache:
cache.clear_caches()
debug.reset_time()
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self.source, path, self._pos, self._user_context)
self._evaluator = Evaluator(resolve_variables_to_types=resolve_variables_to_types)
debug.speed('init')
class Script(object):
"""
A Script is the base for completions, goto or whatever you want to do with
|jedi|.
You can either use the ``source`` parameter or ``path`` to read a file.
Usually you're going to want to use both of them (in an editor).
:param source: The source code of the current file, separated by newlines.
:type source: str
:param line: The line to perform actions on (starting with 1).
:type line: int
:param col: The column of the cursor (starting with 0).
:type col: int
:param path: The path of the file in the file system, or ``''`` if
it hasn't been saved yet.
:type path: str or None
:param encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
:param source_encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
"""
def __init__(self,
source=None,
line=None,
column=None,
path=None,
encoding='utf-8',
source_path=None,
source_encoding=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.",
DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.",
DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
self.source = common.source_to_unicode(source, encoding)
lines = common.splitlines(self.source)
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_time_caches()
debug.reset_time()
self._grammar = load_grammar('grammar%s.%s' % sys.version_info[:2])
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self._grammar, self.source, path,
self._pos, self._user_context,
self._parsed_callback)
self._evaluator = Evaluator(self._grammar)
debug.speed('init')
def _parsed_callback(self, parser):
module = self._evaluator.wrap(parser.module)
imports.add_module(self._evaluator, unicode(module.name), module)
@property
def source_path(self):
"""
.. deprecated:: 0.7.0
Use :attr:`.path` instead.
.. todo:: Remove!
"""
warnings.warn("Use path instead of source_path.", DeprecationWarning)
return self.path
def __repr__(self):
return '<%s: %s>' % (self.__class__.__name__, repr(self._orig_path))
def completions(self):
"""
Return :class:`classes.Completion` objects. Those objects contain
information about the completions, more than just names.
:return: Completion objects, sorted by name and __ comes last.
:rtype: list of :class:`classes.Completion`
"""
def get_completions(user_stmt, bs):
# TODO this closure is ugly. it also doesn't work with
# simple_complete (used for Interpreter), somehow redo.
module = self._evaluator.wrap(self._parser.module())
names, level, only_modules, unfinished_dotted = \
helpers.check_error_statements(module, self._pos)
completion_names = []
if names is not None:
imp_names = tuple(
str(n) for n in names if n.end_pos < self._pos)
i = imports.Importer(self._evaluator, imp_names, module, level)
completion_names = i.completion_names(self._evaluator,
only_modules)
# TODO this paragraph is necessary, but not sure it works.
context = self._user_context.get_context()
if not next(context).startswith('.'): # skip the path
if next(context) == 'from':
# completion is just "import" if before stands from ..
if unfinished_dotted:
return completion_names
else:
return set([keywords.keyword('import').name])
if isinstance(user_stmt, tree.Import):
module = self._parser.module()
completion_names += imports.completion_names(
self._evaluator, user_stmt, self._pos)
return completion_names
if names is None and not isinstance(user_stmt, tree.Import):
if not path and not dot:
# add keywords
completion_names += keywords.completion_names(
self._evaluator, user_stmt, self._pos, module)
# TODO delete? We should search for valid parser
# transformations.
completion_names += self._simple_complete(path, dot, like)
return completion_names
debug.speed('completions start')
path = self._user_context.get_path_until_cursor()
# Dots following an int are not the start of a completion but a float
# literal.
if re.search(r'^\d\.$', path):
return []
path, dot, like = helpers.completion_parts(path)
user_stmt = self._parser.user_stmt_with_whitespace()
b = compiled.builtin
completion_names = get_completions(user_stmt, b)
if not dot:
# add named params
for call_sig in self.call_signatures():
# Allow protected access, because it's a public API.
module = call_sig._name.get_parent_until()
# Compiled modules typically don't allow keyword arguments.
if not isinstance(module, compiled.CompiledObject):
for p in call_sig.params:
# Allow access on _definition here, because it's a
# public API and we don't want to make the internal
# Name object public.
if p._definition.stars == 0: # no *args/**kwargs
completion_names.append(p._name)
needs_dot = not dot and path
comps = []
comp_dct = {}
for c in set(completion_names):
n = str(c)
if settings.case_insensitive_completion \
and n.lower().startswith(like.lower()) \
or n.startswith(like):
if isinstance(c.parent, (tree.Function, tree.Class)):
# TODO I think this is a hack. It should be an
# er.Function/er.Class before that.
c = self._evaluator.wrap(c.parent).name
new = classes.Completion(self._evaluator, c, needs_dot,
len(like))
k = (new.name, new.complete) # key
if k in comp_dct and settings.no_completion_duplicates:
comp_dct[k]._same_name_completions.append(new)
else:
comp_dct[k] = new
comps.append(new)
debug.speed('completions end')
return sorted(
comps,
key=lambda x:
(x.name.startswith('__'), x.name.startswith('_'), x.name.lower()))
def _simple_complete(self, path, dot, like):
if not path and not dot:
scope = self._parser.user_scope()
if not scope.is_scope(): # Might be a flow (if/while/etc).
scope = scope.get_parent_scope()
names_dicts = global_names_dict_generator(
self._evaluator, self._evaluator.wrap(scope), self._pos)
completion_names = []
for names_dict, pos in names_dicts:
names = list(chain.from_iterable(names_dict.values()))
if not names:
continue
completion_names += filter_definition_names(
names, self._parser.user_stmt(), pos)
elif self._get_under_cursor_stmt(path) is None:
return []
else:
scopes = list(self._prepare_goto(path, True))
completion_names = []
debug.dbg('possible completion scopes: %s', scopes)
for s in scopes:
names = []
for names_dict in s.names_dicts(search_global=False):
names += chain.from_iterable(names_dict.values())
completion_names += filter_definition_names(
names, self._parser.user_stmt())
return completion_names
def _prepare_goto(self, goto_path, is_completion=False):
"""
Base for completions/goto. Basically it returns the resolved scopes
under cursor.
"""
debug.dbg('start: %s in %s', goto_path, self._parser.user_scope())
user_stmt = self._parser.user_stmt_with_whitespace()
if not user_stmt and len(goto_path.split('\n')) > 1:
# If the user_stmt is not defined and the goto_path is multi line,
# something's strange. Most probably the backwards tokenizer
# matched to much.
return []
if isinstance(user_stmt, tree.Import):
i, _ = helpers.get_on_import_stmt(self._evaluator,
self._user_context, user_stmt,
is_completion)
if i is None:
return []
scopes = [i]
else:
# just parse one statement, take it and evaluate it
eval_stmt = self._get_under_cursor_stmt(goto_path)
if eval_stmt is None:
return []
module = self._evaluator.wrap(self._parser.module())
names, level, _, _ = helpers.check_error_statements(
module, self._pos)
if names:
names = [str(n) for n in names]
i = imports.Importer(self._evaluator, names, module, level)
return i.follow()
scopes = self._evaluator.eval_element(eval_stmt)
return scopes
@memoize_default()
def _get_under_cursor_stmt(self, cursor_txt, start_pos=None):
tokenizer = source_tokens(cursor_txt)
r = Parser(self._grammar, cursor_txt, tokenizer=tokenizer)
try:
# Take the last statement available that is not an endmarker.
# And because it's a simple_stmt, we need to get the first child.
stmt = r.module.children[-2].children[0]
except (AttributeError, IndexError):
return None
user_stmt = self._parser.user_stmt()
if user_stmt is None:
# Set the start_pos to a pseudo position, that doesn't exist but
# works perfectly well (for both completions in docstrings and
# statements).
pos = start_pos or self._pos
else:
pos = user_stmt.start_pos
stmt.move(pos[0] - 1, pos[1]) # Moving the offset.
stmt.parent = self._parser.user_scope()
return stmt
def goto_definitions(self):
"""
Return the definitions of a the path under the cursor. goto function!
This follows complicated paths and returns the end, not the first
definition. The big difference between :meth:`goto_assignments` and
:meth:`goto_definitions` is that :meth:`goto_assignments` doesn't
follow imports and statements. Multiple objects may be returned,
because Python itself is a dynamic language, which means depending on
an option you can have two different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
def resolve_import_paths(scopes):
for s in scopes.copy():
if isinstance(s, imports.ImportWrapper):
scopes.remove(s)
scopes.update(resolve_import_paths(set(s.follow())))
return scopes
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
definitions = set()
if next(context) in ('class', 'def'):
definitions = set(
[self._evaluator.wrap(self._parser.user_scope())])
else:
# Fetch definition of callee, if there's no path otherwise.
if not goto_path:
definitions = set(signature._definition
for signature in self.call_signatures())
if re.match('\w[\w\d_]*$', goto_path) and not definitions:
user_stmt = self._parser.user_stmt()
if user_stmt is not None and user_stmt.type == 'expr_stmt':
for name in user_stmt.get_defined_names():
if name.start_pos <= self._pos <= name.end_pos:
# TODO scaning for a name and then using it should be
# the default.
definitions = set(
self._evaluator.goto_definition(name))
if not definitions and goto_path:
definitions = set(self._prepare_goto(goto_path))
definitions = resolve_import_paths(definitions)
names = [s.name for s in definitions]
defs = [classes.Definition(self._evaluator, name) for name in names]
return helpers.sorted_definitions(set(defs))
def goto_assignments(self):
"""
Return the first definition found. Imports and statements aren't
followed. Multiple objects may be returned, because Python itself is a
dynamic language, which means depending on an option you can have two
different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
results = self._goto()
d = [classes.Definition(self._evaluator, d) for d in set(results)]
return helpers.sorted_definitions(d)
def _goto(self, add_import_name=False):
"""
Used for goto_assignments and usages.
:param add_import_name: Add the the name (if import) to the result.
"""
def follow_inexistent_imports(defs):
""" Imports can be generated, e.g. following
`multiprocessing.dummy` generates an import dummy in the
multiprocessing module. The Import doesn't exist -> follow.
"""
definitions = set(defs)
for d in defs:
if isinstance(d.parent, tree.Import) \
and d.start_pos == (0, 0):
i = imports.ImportWrapper(self._evaluator,
d.parent).follow(is_goto=True)
definitions.remove(d)
definitions |= follow_inexistent_imports(i)
return definitions
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
user_stmt = self._parser.user_stmt()
user_scope = self._parser.user_scope()
stmt = self._get_under_cursor_stmt(goto_path)
if stmt is None:
return []
if user_scope is None:
last_name = None
else:
# Try to use the parser if possible.
last_name = user_scope.name_for_position(self._pos)
if last_name is None:
last_name = stmt
while not isinstance(last_name, tree.Name):
try:
last_name = last_name.children[-1]
except AttributeError:
# Doesn't have a name in it.
return []
if next(context) in ('class', 'def'):
# The cursor is on a class/function name.
user_scope = self._parser.user_scope()
definitions = set([user_scope.name])
elif isinstance(user_stmt, tree.Import):
s, name = helpers.get_on_import_stmt(self._evaluator,
self._user_context, user_stmt)
definitions = self._evaluator.goto(name)
else:
# The Evaluator.goto function checks for definitions, but since we
# use a reverse tokenizer, we have new name_part objects, so we
# have to check the user_stmt here for positions.
if isinstance(user_stmt, tree.ExprStmt) \
and isinstance(last_name.parent, tree.ExprStmt):
for name in user_stmt.get_defined_names():
if name.start_pos <= self._pos <= name.end_pos:
return [name]
defs = self._evaluator.goto(last_name)
definitions = follow_inexistent_imports(defs)
return definitions
def usages(self, additional_module_paths=()):
"""
Return :class:`classes.Definition` objects, which contain all
names that point to the definition of the name under the cursor. This
is very useful for refactoring (renaming), or to show all usages of a
variable.
.. todo:: Implement additional_module_paths
:rtype: list of :class:`classes.Definition`
"""
temp, settings.dynamic_flow_information = \
settings.dynamic_flow_information, False
try:
user_stmt = self._parser.user_stmt()
definitions = self._goto(add_import_name=True)
if not definitions and isinstance(user_stmt, tree.Import):
# For not defined imports (goto doesn't find something, we take
# the name as a definition. This is enough, because every name
# points to it.
name = user_stmt.name_for_position(self._pos)
if name is None:
# Must be syntax
return []
definitions = [name]
if not definitions:
# Without a definition for a name we cannot find references.
return []
if not isinstance(user_stmt, tree.Import):
# import case is looked at with add_import_name option
definitions = usages.usages_add_import_modules(
self._evaluator, definitions)
module = set([d.get_parent_until() for d in definitions])
module.add(self._parser.module())
names = usages.usages(self._evaluator, definitions, module)
for d in set(definitions):
names.append(classes.Definition(self._evaluator, d))
finally:
settings.dynamic_flow_information = temp
return helpers.sorted_definitions(set(names))
def call_signatures(self):
"""
Return the function object of the call you're currently in.
E.g. if the cursor is here::
abs(# <-- cursor is here
This would return the ``abs`` function. On the other hand::
abs()# <-- cursor is here
This would return ``None``.
:rtype: list of :class:`classes.CallSignature`
"""
call_txt, call_index, key_name, start_pos = self._user_context.call_signature(
)
if call_txt is None:
return []
stmt = self._get_under_cursor_stmt(call_txt, start_pos)
if stmt is None:
return []
with common.scale_speed_settings(settings.scale_call_signatures):
origins = cache.cache_call_signatures(self._evaluator, stmt,
self.source, self._pos)
debug.speed('func_call followed')
return [
classes.CallSignature(self._evaluator, o.name, stmt, call_index,
key_name) for o in origins
if hasattr(o, 'py__call__')
]
def _analysis(self):
def check_types(types):
for typ in types:
try:
f = typ.iter_content
except AttributeError:
pass
else:
check_types(f())
#statements = set(chain(*self._parser.module().used_names.values()))
nodes, imp_names, decorated_funcs = \
analysis.get_module_statements(self._parser.module())
# Sort the statements so that the results are reproducible.
for n in imp_names:
imports.ImportWrapper(self._evaluator, n).follow()
for node in sorted(nodes, key=lambda obj: obj.start_pos):
check_types(self._evaluator.eval_element(node))
for dec_func in decorated_funcs:
er.Function(self._evaluator, dec_func).get_decorated_func()
ana = [a for a in self._evaluator.analysis if self.path == a.path]
return sorted(set(ana), key=lambda x: x.line)
class Interpreter(Script):
"""
Jedi API for Python REPLs.
In addition to completion of simple attribute access, Jedi
supports code completion based on static code analysis.
Jedi can complete attributes of object which is not initialized
yet.
>>> from os.path import join
>>> namespace = locals()
>>> script = Interpreter('join().up', [namespace])
>>> print(script.completions()[0].name)
upper
"""
def __init__(self, source, namespaces, **kwds):
"""
Parse `source` and mixin interpreted Python objects from `namespaces`.
:type source: str
:arg source: Code to parse.
:type namespaces: list of dict
:arg namespaces: a list of namespace dictionaries such as the one
returned by :func:`locals`.
Other optional arguments are same as the ones for :class:`Script`.
If `line` and `column` are None, they are assumed be at the end of
`source`.
"""
if type(namespaces) is not list or len(namespaces) == 0 or \
any([type(x) is not dict for x in namespaces]):
raise TypeError("namespaces must be a non-empty list of dict")
super(Interpreter, self).__init__(source, **kwds)
self.namespaces = namespaces
# Don't use the fast parser, because it does crazy stuff that we don't
# need in our very simple and small code here (that is always
# changing).
self._parser = UserContextParser(self._grammar, self.source,
self._orig_path, self._pos,
self._user_context, self._parsed_callback,
use_fast_parser=False)
interpreter.add_namespaces_to_parser(self._evaluator, namespaces,
self._parser.module())
def _simple_complete(self, path, dot, like):
user_stmt = self._parser.user_stmt_with_whitespace()
is_simple_path = not path or re.search('^[\w][\w\d.]*$', path)
if isinstance(user_stmt, tree.Import) or not is_simple_path:
return super(Interpreter, self)._simple_complete(path, dot, like)
else:
class NamespaceModule(object):
def __getattr__(_, name):
for n in self.namespaces:
try:
return n[name]
except KeyError:
pass
raise AttributeError()
def __dir__(_):
gen = (n.keys() for n in self.namespaces)
return list(set(chain.from_iterable(gen)))
paths = path.split('.') if path else []
namespaces = (NamespaceModule(), builtins)
for p in paths:
old, namespaces = namespaces, []
for n in old:
try:
namespaces.append(getattr(n, p))
except Exception:
pass
completion_names = []
for namespace in namespaces:
for name in dir(namespace):
if name.lower().startswith(like.lower()):
scope = self._parser.module()
n = FakeName(name, scope)
completion_names.append(n)
return completion_names
class Script(object):
"""
A Script is the base for completions, goto or whatever you want to do with
|jedi|.
You can either use the ``source`` parameter or ``path`` to read a file.
Usually you're going to want to use both of them (in an editor).
:param source: The source code of the current file, separated by newlines.
:type source: str
:param line: The line to perform actions on (starting with 1).
:type line: int
:param col: The column of the cursor (starting with 0).
:type col: int
:param path: The path of the file in the file system, or ``''`` if
it hasn't been saved yet.
:type path: str or None
:param encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
:param source_encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
"""
def __init__(self, source=None, line=None, column=None, path=None,
encoding='utf-8', source_path=None, source_encoding=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.", DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.", DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
self.source = common.source_to_unicode(source, encoding)
lines = common.splitlines(self.source)
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_time_caches()
debug.reset_time()
self._grammar = load_grammar('grammar%s.%s' % sys.version_info[:2])
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self._grammar, self.source, path,
self._pos, self._user_context,
self._parsed_callback)
self._evaluator = Evaluator(self._grammar)
debug.speed('init')
def _parsed_callback(self, parser):
module = self._evaluator.wrap(parser.module)
imports.add_module(self._evaluator, unicode(module.name), module)
@property
def source_path(self):
"""
.. deprecated:: 0.7.0
Use :attr:`.path` instead.
.. todo:: Remove!
"""
warnings.warn("Use path instead of source_path.", DeprecationWarning)
return self.path
def __repr__(self):
return '<%s: %s>' % (self.__class__.__name__, repr(self._orig_path))
def completions(self):
"""
Return :class:`classes.Completion` objects. Those objects contain
information about the completions, more than just names.
:return: Completion objects, sorted by name and __ comes last.
:rtype: list of :class:`classes.Completion`
"""
def get_completions(user_stmt, bs):
# TODO this closure is ugly. it also doesn't work with
# simple_complete (used for Interpreter), somehow redo.
module = self._evaluator.wrap(self._parser.module())
names, level, only_modules, unfinished_dotted = \
helpers.check_error_statements(module, self._pos)
completion_names = []
if names is not None:
imp_names = tuple(str(n) for n in names if n.end_pos < self._pos)
i = imports.Importer(self._evaluator, imp_names, module, level)
completion_names = i.completion_names(self._evaluator, only_modules)
# TODO this paragraph is necessary, but not sure it works.
context = self._user_context.get_context()
if not next(context).startswith('.'): # skip the path
if next(context) == 'from':
# completion is just "import" if before stands from ..
if unfinished_dotted:
return completion_names
else:
return set([keywords.keyword('import').name])
if isinstance(user_stmt, tree.Import):
module = self._parser.module()
completion_names += imports.completion_names(self._evaluator,
user_stmt, self._pos)
return completion_names
if names is None and not isinstance(user_stmt, tree.Import):
if not path and not dot:
# add keywords
completion_names += keywords.completion_names(
self._evaluator,
user_stmt,
self._pos,
module)
# TODO delete? We should search for valid parser
# transformations.
completion_names += self._simple_complete(path, dot, like)
return completion_names
debug.speed('completions start')
path = self._user_context.get_path_until_cursor()
# Dots following an int are not the start of a completion but a float
# literal.
if re.search(r'^\d\.$', path):
return []
path, dot, like = helpers.completion_parts(path)
user_stmt = self._parser.user_stmt_with_whitespace()
b = compiled.builtin
completion_names = get_completions(user_stmt, b)
if not dot:
# add named params
for call_sig in self.call_signatures():
# Allow protected access, because it's a public API.
module = call_sig._name.get_parent_until()
# Compiled modules typically don't allow keyword arguments.
if not isinstance(module, compiled.CompiledObject):
for p in call_sig.params:
# Allow access on _definition here, because it's a
# public API and we don't want to make the internal
# Name object public.
if p._definition.stars == 0: # no *args/**kwargs
completion_names.append(p._name)
needs_dot = not dot and path
comps = []
comp_dct = {}
for c in set(completion_names):
n = str(c)
if settings.case_insensitive_completion \
and n.lower().startswith(like.lower()) \
or n.startswith(like):
if isinstance(c.parent, (tree.Function, tree.Class)):
# TODO I think this is a hack. It should be an
# er.Function/er.Class before that.
c = self._evaluator.wrap(c.parent).name
new = classes.Completion(self._evaluator, c, needs_dot, len(like))
k = (new.name, new.complete) # key
if k in comp_dct and settings.no_completion_duplicates:
comp_dct[k]._same_name_completions.append(new)
else:
comp_dct[k] = new
comps.append(new)
debug.speed('completions end')
return sorted(comps, key=lambda x: (x.name.startswith('__'),
x.name.startswith('_'),
x.name.lower()))
def _simple_complete(self, path, dot, like):
if not path and not dot:
scope = self._parser.user_scope()
if not scope.is_scope(): # Might be a flow (if/while/etc).
scope = scope.get_parent_scope()
names_dicts = global_names_dict_generator(
self._evaluator,
self._evaluator.wrap(scope),
self._pos
)
completion_names = []
for names_dict, pos in names_dicts:
names = list(chain.from_iterable(names_dict.values()))
if not names:
continue
completion_names += filter_definition_names(names, self._parser.user_stmt(), pos)
elif self._get_under_cursor_stmt(path) is None:
return []
else:
scopes = list(self._prepare_goto(path, True))
completion_names = []
debug.dbg('possible completion scopes: %s', scopes)
for s in scopes:
names = []
for names_dict in s.names_dicts(search_global=False):
names += chain.from_iterable(names_dict.values())
completion_names += filter_definition_names(names, self._parser.user_stmt())
return completion_names
def _prepare_goto(self, goto_path, is_completion=False):
"""
Base for completions/goto. Basically it returns the resolved scopes
under cursor.
"""
debug.dbg('start: %s in %s', goto_path, self._parser.user_scope())
user_stmt = self._parser.user_stmt_with_whitespace()
if not user_stmt and len(goto_path.split('\n')) > 1:
# If the user_stmt is not defined and the goto_path is multi line,
# something's strange. Most probably the backwards tokenizer
# matched to much.
return []
if isinstance(user_stmt, tree.Import):
i, _ = helpers.get_on_import_stmt(self._evaluator, self._user_context,
user_stmt, is_completion)
if i is None:
return []
scopes = [i]
else:
# just parse one statement, take it and evaluate it
eval_stmt = self._get_under_cursor_stmt(goto_path)
if eval_stmt is None:
return []
module = self._evaluator.wrap(self._parser.module())
names, level, _, _ = helpers.check_error_statements(module, self._pos)
if names:
names = [str(n) for n in names]
i = imports.Importer(self._evaluator, names, module, level)
return i.follow()
scopes = self._evaluator.eval_element(eval_stmt)
return scopes
@memoize_default()
def _get_under_cursor_stmt(self, cursor_txt, start_pos=None):
tokenizer = source_tokens(cursor_txt)
r = Parser(self._grammar, cursor_txt, tokenizer=tokenizer)
try:
# Take the last statement available that is not an endmarker.
# And because it's a simple_stmt, we need to get the first child.
stmt = r.module.children[-2].children[0]
except (AttributeError, IndexError):
return None
user_stmt = self._parser.user_stmt()
if user_stmt is None:
# Set the start_pos to a pseudo position, that doesn't exist but
# works perfectly well (for both completions in docstrings and
# statements).
pos = start_pos or self._pos
else:
pos = user_stmt.start_pos
stmt.move(pos[0] - 1, pos[1]) # Moving the offset.
stmt.parent = self._parser.user_scope()
return stmt
def goto_definitions(self):
"""
Return the definitions of a the path under the cursor. goto function!
This follows complicated paths and returns the end, not the first
definition. The big difference between :meth:`goto_assignments` and
:meth:`goto_definitions` is that :meth:`goto_assignments` doesn't
follow imports and statements. Multiple objects may be returned,
because Python itself is a dynamic language, which means depending on
an option you can have two different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
def resolve_import_paths(scopes):
for s in scopes.copy():
if isinstance(s, imports.ImportWrapper):
scopes.remove(s)
scopes.update(resolve_import_paths(set(s.follow())))
return scopes
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
definitions = set()
if next(context) in ('class', 'def'):
definitions = set([self._evaluator.wrap(self._parser.user_scope())])
else:
# Fetch definition of callee, if there's no path otherwise.
if not goto_path:
definitions = set(signature._definition
for signature in self.call_signatures())
if re.match('\w[\w\d_]*$', goto_path) and not definitions:
user_stmt = self._parser.user_stmt()
if user_stmt is not None and user_stmt.type == 'expr_stmt':
for name in user_stmt.get_defined_names():
if name.start_pos <= self._pos <= name.end_pos:
# TODO scaning for a name and then using it should be
# the default.
definitions = set(self._evaluator.goto_definition(name))
if not definitions and goto_path:
definitions = set(self._prepare_goto(goto_path))
definitions = resolve_import_paths(definitions)
names = [s.name for s in definitions]
defs = [classes.Definition(self._evaluator, name) for name in names]
return helpers.sorted_definitions(set(defs))
def goto_assignments(self):
"""
Return the first definition found. Imports and statements aren't
followed. Multiple objects may be returned, because Python itself is a
dynamic language, which means depending on an option you can have two
different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
results = self._goto()
d = [classes.Definition(self._evaluator, d) for d in set(results)]
return helpers.sorted_definitions(d)
def _goto(self, add_import_name=False):
"""
Used for goto_assignments and usages.
:param add_import_name: Add the the name (if import) to the result.
"""
def follow_inexistent_imports(defs):
""" Imports can be generated, e.g. following
`multiprocessing.dummy` generates an import dummy in the
multiprocessing module. The Import doesn't exist -> follow.
"""
definitions = set(defs)
for d in defs:
if isinstance(d.parent, tree.Import) \
and d.start_pos == (0, 0):
i = imports.ImportWrapper(self._evaluator, d.parent).follow(is_goto=True)
definitions.remove(d)
definitions |= follow_inexistent_imports(i)
return definitions
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
user_stmt = self._parser.user_stmt()
user_scope = self._parser.user_scope()
stmt = self._get_under_cursor_stmt(goto_path)
if stmt is None:
return []
if user_scope is None:
last_name = None
else:
# Try to use the parser if possible.
last_name = user_scope.name_for_position(self._pos)
if last_name is None:
last_name = stmt
while not isinstance(last_name, tree.Name):
try:
last_name = last_name.children[-1]
except AttributeError:
# Doesn't have a name in it.
return []
if next(context) in ('class', 'def'):
# The cursor is on a class/function name.
user_scope = self._parser.user_scope()
definitions = set([user_scope.name])
elif isinstance(user_stmt, tree.Import):
s, name = helpers.get_on_import_stmt(self._evaluator,
self._user_context, user_stmt)
definitions = self._evaluator.goto(name)
else:
# The Evaluator.goto function checks for definitions, but since we
# use a reverse tokenizer, we have new name_part objects, so we
# have to check the user_stmt here for positions.
if isinstance(user_stmt, tree.ExprStmt) \
and isinstance(last_name.parent, tree.ExprStmt):
for name in user_stmt.get_defined_names():
if name.start_pos <= self._pos <= name.end_pos:
return [name]
defs = self._evaluator.goto(last_name)
definitions = follow_inexistent_imports(defs)
return definitions
def usages(self, additional_module_paths=()):
"""
Return :class:`classes.Definition` objects, which contain all
names that point to the definition of the name under the cursor. This
is very useful for refactoring (renaming), or to show all usages of a
variable.
.. todo:: Implement additional_module_paths
:rtype: list of :class:`classes.Definition`
"""
temp, settings.dynamic_flow_information = \
settings.dynamic_flow_information, False
try:
user_stmt = self._parser.user_stmt()
definitions = self._goto(add_import_name=True)
if not definitions and isinstance(user_stmt, tree.Import):
# For not defined imports (goto doesn't find something, we take
# the name as a definition. This is enough, because every name
# points to it.
name = user_stmt.name_for_position(self._pos)
if name is None:
# Must be syntax
return []
definitions = [name]
if not definitions:
# Without a definition for a name we cannot find references.
return []
if not isinstance(user_stmt, tree.Import):
# import case is looked at with add_import_name option
definitions = usages.usages_add_import_modules(self._evaluator,
definitions)
module = set([d.get_parent_until() for d in definitions])
module.add(self._parser.module())
names = usages.usages(self._evaluator, definitions, module)
for d in set(definitions):
names.append(classes.Definition(self._evaluator, d))
finally:
settings.dynamic_flow_information = temp
return helpers.sorted_definitions(set(names))
def call_signatures(self):
"""
Return the function object of the call you're currently in.
E.g. if the cursor is here::
abs(# <-- cursor is here
This would return the ``abs`` function. On the other hand::
abs()# <-- cursor is here
This would return ``None``.
:rtype: list of :class:`classes.CallSignature`
"""
call_txt, call_index, key_name, start_pos = self._user_context.call_signature()
if call_txt is None:
return []
stmt = self._get_under_cursor_stmt(call_txt, start_pos)
if stmt is None:
return []
with common.scale_speed_settings(settings.scale_call_signatures):
origins = cache.cache_call_signatures(self._evaluator, stmt,
self.source, self._pos)
debug.speed('func_call followed')
return [classes.CallSignature(self._evaluator, o.name, stmt, call_index, key_name)
for o in origins if hasattr(o, 'py__call__')]
def _analysis(self):
def check_types(types):
for typ in types:
try:
f = typ.iter_content
except AttributeError:
pass
else:
check_types(f())
#statements = set(chain(*self._parser.module().used_names.values()))
nodes, imp_names, decorated_funcs = \
analysis.get_module_statements(self._parser.module())
# Sort the statements so that the results are reproducible.
for n in imp_names:
imports.ImportWrapper(self._evaluator, n).follow()
for node in sorted(nodes, key=lambda obj: obj.start_pos):
check_types(self._evaluator.eval_element(node))
for dec_func in decorated_funcs:
er.Function(self._evaluator, dec_func).get_decorated_func()
ana = [a for a in self._evaluator.analysis if self.path == a.path]
return sorted(set(ana), key=lambda x: x.line)
class Script(object):
"""
A Script is the base for completions, goto or whatever you want to do with
|jedi|.
You can either use the ``source`` parameter or ``path`` to read a file.
Usually you're going to want to use both of them (in an editor).
:param source: The source code of the current file, separated by newlines.
:type source: str
:param line: The line to perform actions on (starting with 1).
:type line: int
:param col: The column of the cursor (starting with 0).
:type col: int
:param path: The path of the file in the file system, or ``''`` if
it hasn't been saved yet.
:type path: str or None
:param encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
:param source_encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
"""
def __init__(self,
source=None,
line=None,
column=None,
path=None,
encoding='utf-8',
source_path=None,
source_encoding=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.",
DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.",
DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
lines = source.splitlines() or ['']
if source and source[-1] == '\n':
lines.append('')
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_caches()
debug.reset_time()
self.source = common.source_to_unicode(source, encoding)
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self.source, path, self._pos,
self._user_context)
self._evaluator = Evaluator()
debug.speed('init')
@property
def source_path(self):
"""
.. deprecated:: 0.7.0
Use :attr:`.path` instead.
.. todo:: Remove!
"""
warnings.warn("Use path instead of source_path.", DeprecationWarning)
return self.path
def __repr__(self):
return '<%s: %s>' % (self.__class__.__name__, repr(self._orig_path))
def completions(self):
"""
Return :class:`classes.Completion` objects. Those objects contain
information about the completions, more than just names.
:return: Completion objects, sorted by name and __ comes last.
:rtype: list of :class:`classes.Completion`
"""
def get_completions(user_stmt, bs):
if isinstance(user_stmt, pr.Import):
context = self._user_context.get_context()
next(context) # skip the path
if next(context) == 'from':
# completion is just "import" if before stands from ..
return ((k, bs) for k in keywords.keyword_names('import'))
return self._simple_complete(path, like)
def completion_possible(path):
"""
The completion logic is kind of complicated, because we strip the
last word part. To ignore certain strange patterns with dots, just
use regex.
"""
if re.match('\d+\.\.$|\.{4}$', path):
return True # check Ellipsis and float literal `1.`
return not re.search(r'^\.|^\d\.$|\.\.$', path)
debug.speed('completions start')
path = self._user_context.get_path_until_cursor()
if not completion_possible(path):
return []
path, dot, like = helpers.completion_parts(path)
user_stmt = self._parser.user_stmt_with_whitespace()
b = compiled.builtin
completions = get_completions(user_stmt, b)
if not dot:
# add named params
for call_sig in self.call_signatures():
# allow protected access, because it's a public API.
module = call_sig._definition.get_parent_until()
# Compiled modules typically don't allow keyword arguments.
if not isinstance(module, compiled.CompiledObject):
for p in call_sig.params:
# Allow access on _definition here, because it's a
# public API and we don't want to make the internal
# Name object public.
if p._definition.stars == 0: # no *args/**kwargs
completions.append((p._definition.get_name(), p))
if not path and not isinstance(user_stmt, pr.Import):
# add keywords
completions += ((k, b)
for k in keywords.keyword_names(all=True))
needs_dot = not dot and path
comps = []
comp_dct = {}
for c, s in set(completions):
n = str(c.names[-1])
if settings.case_insensitive_completion \
and n.lower().startswith(like.lower()) \
or n.startswith(like):
if not filter_private_variable(
s, user_stmt or self._parser.user_scope(), n):
new = classes.Completion(self._evaluator, c, needs_dot,
len(like), s)
k = (new.name, new.complete) # key
if k in comp_dct and settings.no_completion_duplicates:
comp_dct[k]._same_name_completions.append(new)
else:
comp_dct[k] = new
comps.append(new)
debug.speed('completions end')
return sorted(
comps,
key=lambda x:
(x.name.startswith('__'), x.name.startswith('_'), x.name.lower()))
def _simple_complete(self, path, like):
try:
scopes = list(self._prepare_goto(path, True))
except NotFoundError:
scopes = []
scope_generator = get_names_of_scope(self._evaluator,
self._parser.user_scope(),
self._pos)
completions = []
for scope, name_list in scope_generator:
for c in name_list:
completions.append((c, scope))
else:
completions = []
debug.dbg('possible completion scopes: %s', scopes)
for s in scopes:
if s.isinstance(er.Function):
names = s.get_magic_function_names()
else:
if isinstance(s, imports.ImportWrapper):
under = like + self._user_context.get_path_after_cursor(
)
if under == 'import':
current_line = self._user_context.get_position_line(
)
if not current_line.endswith('import import'):
continue
a = s.import_stmt.alias
if a and a.start_pos <= self._pos <= a.end_pos:
continue
names = s.get_defined_names(on_import_stmt=True)
else:
names = s.get_defined_names()
for c in names:
completions.append((c, s))
return completions
def _prepare_goto(self, goto_path, is_completion=False):
"""
Base for completions/goto. Basically it returns the resolved scopes
under cursor.
"""
debug.dbg('start: %s in %s', goto_path, self._parser.user_scope())
user_stmt = self._parser.user_stmt_with_whitespace()
if not user_stmt and len(goto_path.split('\n')) > 1:
# If the user_stmt is not defined and the goto_path is multi line,
# something's strange. Most probably the backwards tokenizer
# matched to much.
return []
if isinstance(user_stmt, pr.Import):
scopes = [
helpers.get_on_import_stmt(self._evaluator, self._user_context,
user_stmt, is_completion)[0]
]
else:
# just parse one statement, take it and evaluate it
eval_stmt = self._get_under_cursor_stmt(goto_path)
if not is_completion:
# goto_definition returns definitions of its statements if the
# cursor is on the assignee. By changing the start_pos of our
# "pseud" statement, the Jedi evaluator can find the assignees.
if user_stmt is not None:
eval_stmt.start_pos = user_stmt.end_pos
scopes = self._evaluator.eval_statement(eval_stmt)
return scopes
def _get_under_cursor_stmt(self, cursor_txt):
tokenizer = source_tokens(cursor_txt, line_offset=self._pos[0] - 1)
r = Parser(cursor_txt, no_docstr=True, tokenizer=tokenizer)
try:
# Take the last statement available.
stmt = r.module.statements[-1]
except IndexError:
raise NotFoundError()
if not isinstance(stmt, pr.Statement):
raise NotFoundError()
user_stmt = self._parser.user_stmt()
if user_stmt is None:
# Set the start_pos to a pseudo position, that doesn't exist but works
# perfectly well (for both completions in docstrings and statements).
stmt.start_pos = self._pos
else:
stmt.start_pos = user_stmt.start_pos
stmt.parent = self._parser.user_scope()
return stmt
def complete(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.completions` instead.
.. todo:: Remove!
"""
warnings.warn("Use completions instead.", DeprecationWarning)
return self.completions()
def goto(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.goto_assignments` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_assignments instead.", DeprecationWarning)
return self.goto_assignments()
def definition(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.goto_definitions` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_definitions instead.", DeprecationWarning)
return self.goto_definitions()
def get_definition(self):
"""
.. deprecated:: 0.5.0
Use :attr:`.goto_definitions` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_definitions instead.", DeprecationWarning)
return self.goto_definitions()
def related_names(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.usages` instead.
.. todo:: Remove!
"""
warnings.warn("Use usages instead.", DeprecationWarning)
return self.usages()
def get_in_function_call(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.call_signatures` instead.
.. todo:: Remove!
"""
return self.function_definition()
def function_definition(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.call_signatures` instead.
.. todo:: Remove!
"""
warnings.warn("Use line instead.", DeprecationWarning)
sig = self.call_signatures()
return sig[0] if sig else None
def goto_definitions(self):
"""
Return the definitions of a the path under the cursor. goto function!
This follows complicated paths and returns the end, not the first
definition. The big difference between :meth:`goto_assignments` and
:meth:`goto_definitions` is that :meth:`goto_assignments` doesn't
follow imports and statements. Multiple objects may be returned,
because Python itself is a dynamic language, which means depending on
an option you can have two different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
def resolve_import_paths(scopes):
for s in scopes.copy():
if isinstance(s, imports.ImportWrapper):
scopes.remove(s)
scopes.update(resolve_import_paths(set(s.follow())))
return scopes
user_stmt = self._parser.user_stmt_with_whitespace()
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
definitions = set()
if next(context) in ('class', 'def'):
definitions = set([self._parser.user_scope()])
else:
# Fetch definition of callee, if there's no path otherwise.
if not goto_path:
(call, _) = search_call_signatures(user_stmt, self._pos)
if call is not None:
while call.next is not None:
call = call.next
# reset cursor position:
(row, col) = call.name.end_pos
pos = (row, max(col - 1, 0))
self._user_context = UserContext(self.source, pos)
# then try to find the path again
goto_path = self._user_context.get_path_under_cursor()
if not definitions:
if goto_path:
definitions = set(self._prepare_goto(goto_path))
definitions = resolve_import_paths(definitions)
d = set([
classes.Definition(self._evaluator, s) for s in definitions
if s is not imports.ImportWrapper.GlobalNamespace
])
return helpers.sorted_definitions(d)
def goto_assignments(self):
"""
Return the first definition found. Imports and statements aren't
followed. Multiple objects may be returned, because Python itself is a
dynamic language, which means depending on an option you can have two
different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
results, _ = self._goto()
d = [
classes.Definition(self._evaluator, d) for d in set(results)
if d is not imports.ImportWrapper.GlobalNamespace
]
return helpers.sorted_definitions(d)
def _goto(self, add_import_name=False):
"""
Used for goto_assignments and usages.
:param add_import_name: Add the the name (if import) to the result.
"""
def follow_inexistent_imports(defs):
""" Imports can be generated, e.g. following
`multiprocessing.dummy` generates an import dummy in the
multiprocessing module. The Import doesn't exist -> follow.
"""
definitions = set(defs)
for d in defs:
if isinstance(d.parent, pr.Import) \
and d.start_pos == (0, 0):
i = imports.ImportWrapper(self._evaluator,
d.parent).follow(is_goto=True)
definitions.remove(d)
definitions |= follow_inexistent_imports(i)
return definitions
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
user_stmt = self._parser.user_stmt()
if next(context) in ('class', 'def'):
user_scope = self._parser.user_scope()
definitions = set([user_scope.name])
search_name = unicode(user_scope.name)
elif isinstance(user_stmt, pr.Import):
s, name_part = helpers.get_on_import_stmt(self._evaluator,
self._user_context,
user_stmt)
try:
definitions = [s.follow(is_goto=True)[0]]
except IndexError:
definitions = []
search_name = unicode(name_part)
if add_import_name:
import_name = user_stmt.get_defined_names()
# imports have only one name
if not user_stmt.star \
and unicode(name_part) == unicode(import_name[0].names[-1]):
definitions.append(import_name[0])
else:
stmt = self._get_under_cursor_stmt(goto_path)
def test_lhs():
"""
Special rule for goto, left hand side of the statement returns
itself, if the name is ``foo``, but not ``foo.bar``.
"""
if isinstance(user_stmt, pr.Statement):
for name in user_stmt.get_defined_names():
if name.start_pos <= self._pos <= name.end_pos \
and len(name.names) == 1:
return name, unicode(name.names[-1])
return None, None
lhs, search_name = test_lhs()
if lhs is None:
expression_list = stmt.expression_list()
if len(expression_list) == 0:
return [], ''
# Only the first command is important, the rest should basically not
# happen except in broken code (e.g. docstrings that aren't code).
call = expression_list[0]
if isinstance(call, pr.Call):
call_path = list(call.generate_call_path())
else:
call_path = [call]
defs, search_name_part = self._evaluator.goto(stmt, call_path)
search_name = unicode(search_name_part)
definitions = follow_inexistent_imports(defs)
else:
definitions = [lhs]
if isinstance(user_stmt, pr.Statement):
c = user_stmt.expression_list()
if c and not isinstance(c[0], (str, unicode)) \
and c[0].start_pos > self._pos \
and not re.search(r'\.\w+$', goto_path):
# The cursor must be after the start, otherwise the
# statement is just an assignee.
definitions = [user_stmt]
return definitions, search_name
def usages(self, additional_module_paths=()):
"""
Return :class:`classes.Definition` objects, which contain all
names that point to the definition of the name under the cursor. This
is very useful for refactoring (renaming), or to show all usages of a
variable.
.. todo:: Implement additional_module_paths
:rtype: list of :class:`classes.Definition`
"""
temp, settings.dynamic_flow_information = \
settings.dynamic_flow_information, False
user_stmt = self._parser.user_stmt()
definitions, search_name = self._goto(add_import_name=True)
if isinstance(user_stmt, pr.Statement):
c = user_stmt.expression_list()[0]
if not isinstance(c, unicode) and self._pos < c.start_pos:
# the search_name might be before `=`
definitions = [
v for v in user_stmt.get_defined_names()
if unicode(v.names[-1]) == search_name
]
if not isinstance(user_stmt, pr.Import):
# import case is looked at with add_import_name option
definitions = usages.usages_add_import_modules(
self._evaluator, definitions, search_name)
module = set([d.get_parent_until() for d in definitions])
module.add(self._parser.module())
names = usages.usages(self._evaluator, definitions, search_name,
module)
for d in set(definitions):
try:
name_part = d.names[-1]
except AttributeError:
names.append(classes.Definition(self._evaluator, d))
else:
names.append(classes.Definition(self._evaluator, name_part))
settings.dynamic_flow_information = temp
return helpers.sorted_definitions(set(names))
def call_signatures(self):
"""
Return the function object of the call you're currently in.
E.g. if the cursor is here::
abs(# <-- cursor is here
This would return the ``abs`` function. On the other hand::
abs()# <-- cursor is here
This would return ``None``.
:rtype: list of :class:`classes.CallSignature`
"""
user_stmt = self._parser.user_stmt_with_whitespace()
call, index = search_call_signatures(user_stmt, self._pos)
if call is None:
return []
stmt_el = call
while isinstance(stmt_el.parent, pr.StatementElement):
# Go to parent literal/variable until not possible anymore. This
# makes it possible to return the whole expression.
stmt_el = stmt_el.parent
# We can reset the execution since it's a new object
# (fast_parent_copy).
execution_arr, call.execution = call.execution, None
with common.scale_speed_settings(settings.scale_call_signatures):
_callable = lambda: self._evaluator.eval_call(stmt_el)
origins = cache.cache_call_signatures(_callable, self.source,
self._pos, user_stmt)
debug.speed('func_call followed')
key_name = None
try:
detail = execution_arr[index].assignment_details[0]
except IndexError:
pass
else:
try:
key_name = unicode(detail[0][0].name)
except (IndexError, AttributeError):
pass
return [
classes.CallSignature(self._evaluator, o, call, index, key_name)
for o in origins if o.is_callable()
]
class Interpreter(Script):
"""
Jedi API for Python REPLs.
In addition to completion of simple attribute access, Jedi
supports code completion based on static code analysis.
Jedi can complete attributes of object which is not initialized
yet.
>>> from os.path import join
>>> namespace = locals()
>>> script = Interpreter('join().up', [namespace])
>>> print(script.completions()[0].name)
upper
"""
def __init__(self, source, namespaces, **kwds):
"""
Parse `source` and mixin interpreted Python objects from `namespaces`.
:type source: str
:arg source: Code to parse.
:type namespaces: list of dict
:arg namespaces: a list of namespace dictionaries such as the one
returned by :func:`locals`.
Other optional arguments are same as the ones for :class:`Script`.
If `line` and `column` are None, they are assumed be at the end of
`source`.
"""
if type(namespaces) is not list or len(namespaces) == 0 or \
any([type(x) is not dict for x in namespaces]):
raise TypeError("namespaces must be a non-empty list of dict")
super(Interpreter, self).__init__(source, **kwds)
self.namespaces = namespaces
# Don't use the fast parser, because it does crazy stuff that we don't
# need in our very simple and small code here (that is always
# changing).
self._parser = UserContextParser(self._grammar,
self.source,
self._orig_path,
self._pos,
self._user_context,
self._parsed_callback,
use_fast_parser=False)
interpreter.add_namespaces_to_parser(self._evaluator, namespaces,
self._parser.module())
def _simple_complete(self, path, dot, like):
user_stmt = self._parser.user_stmt_with_whitespace()
is_simple_path = not path or re.search('^[\w][\w\d.]*$', path)
if isinstance(user_stmt, tree.Import) or not is_simple_path:
return super(Interpreter, self)._simple_complete(path, dot, like)
else:
class NamespaceModule(object):
def __getattr__(_, name):
for n in self.namespaces:
try:
return n[name]
except KeyError:
pass
raise AttributeError()
def __dir__(_):
gen = (n.keys() for n in self.namespaces)
return list(set(chain.from_iterable(gen)))
paths = path.split('.') if path else []
namespaces = (NamespaceModule(), builtins)
for p in paths:
old, namespaces = namespaces, []
for n in old:
try:
namespaces.append(getattr(n, p))
except Exception:
pass
completion_names = []
for namespace in namespaces:
for name in dir(namespace):
if name.lower().startswith(like.lower()):
scope = self._parser.module()
n = FakeName(name, scope)
completion_names.append(n)
return completion_names
class Script(object):
"""
A Script is the base for completions, goto or whatever you want to do with
|jedi|.
You can either use the ``source`` parameter or ``path`` to read a file.
Usually you're going to want to use both of them (in an editor).
:param source: The source code of the current file, separated by newlines.
:type source: str
:param line: The line to perform actions on (starting with 1).
:type line: int
:param col: The column of the cursor (starting with 0).
:type col: int
:param path: The path of the file in the file system, or ``''`` if
it hasn't been saved yet.
:type path: str or None
:param encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
:param source_encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
"""
def __init__(self, source=None, line=None, column=None, path=None,
encoding='utf-8', source_path=None, source_encoding=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.", DeprecationWarning)
path = source_path
if source_encoding is not None:
warnings.warn("Use encoding instead of source_encoding.", DeprecationWarning)
encoding = source_encoding
self._orig_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
self.source = common.source_to_unicode(source, encoding)
lines = common.splitlines(self.source)
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_time_caches()
debug.reset_time()
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self.source, path, self._pos, self._user_context)
self._evaluator = Evaluator()
debug.speed('init')
@property
def source_path(self):
"""
.. deprecated:: 0.7.0
Use :attr:`.path` instead.
.. todo:: Remove!
"""
warnings.warn("Use path instead of source_path.", DeprecationWarning)
return self.path
def __repr__(self):
return '<%s: %s>' % (self.__class__.__name__, repr(self._orig_path))
def completions(self):
"""
Return :class:`classes.Completion` objects. Those objects contain
information about the completions, more than just names.
:return: Completion objects, sorted by name and __ comes last.
:rtype: list of :class:`classes.Completion`
"""
def get_completions(user_stmt, bs):
if isinstance(user_stmt, pr.Import):
context = self._user_context.get_context()
next(context) # skip the path
if next(context) == 'from':
# completion is just "import" if before stands from ..
return ((k, bs) for k in keywords.keyword_names('import'))
return self._simple_complete(path, like)
def completion_possible(path):
"""
The completion logic is kind of complicated, because we strip the
last word part. To ignore certain strange patterns with dots, just
use regex.
"""
if re.match('\d+\.\.$|\.{4}$', path):
return True # check Ellipsis and float literal `1.`
return not re.search(r'^\.|^\d\.$|\.\.$', path)
debug.speed('completions start')
path = self._user_context.get_path_until_cursor()
if not completion_possible(path):
return []
path, dot, like = helpers.completion_parts(path)
user_stmt = self._parser.user_stmt_with_whitespace()
b = compiled.builtin
completions = get_completions(user_stmt, b)
if not dot:
# add named params
for call_sig in self.call_signatures():
# Allow protected access, because it's a public API.
module = call_sig._name.get_parent_until()
# Compiled modules typically don't allow keyword arguments.
if not isinstance(module, compiled.CompiledObject):
for p in call_sig.params:
# Allow access on _definition here, because it's a
# public API and we don't want to make the internal
# Name object public.
if p._definition.stars == 0: # no *args/**kwargs
completions.append((p._name, p._name))
if not path and not isinstance(user_stmt, pr.Import):
# add keywords
completions += ((k, b) for k in keywords.keyword_names(all=True))
needs_dot = not dot and path
comps = []
comp_dct = {}
for c, s in set(completions):
n = str(c)
if settings.case_insensitive_completion \
and n.lower().startswith(like.lower()) \
or n.startswith(like):
if not filter_private_variable(s, user_stmt or self._parser.user_scope(), n):
if isinstance(c.parent, (pr.Function, pr.Class)):
# TODO I think this is a hack. It should be an
# er.Function/er.Class before that.
c = er.wrap(self._evaluator, c.parent).name
new = classes.Completion(self._evaluator, c, needs_dot, len(like), s)
k = (new.name, new.complete) # key
if k in comp_dct and settings.no_completion_duplicates:
comp_dct[k]._same_name_completions.append(new)
else:
comp_dct[k] = new
comps.append(new)
debug.speed('completions end')
return sorted(comps, key=lambda x: (x.name.startswith('__'),
x.name.startswith('_'),
x.name.lower()))
def _simple_complete(self, path, like):
try:
scopes = list(self._prepare_goto(path, True))
except NotFoundError:
scopes = []
scope_names_generator = get_names_of_scope(self._evaluator,
self._parser.user_scope(),
self._pos)
completions = []
for scope, name_list in scope_names_generator:
for c in name_list:
completions.append((c, scope))
else:
completions = []
debug.dbg('possible completion scopes: %s', scopes)
for s in scopes:
if s.isinstance(er.Function):
names = s.get_magic_function_names()
elif isinstance(s, imports.ImportWrapper):
under = like + self._user_context.get_path_after_cursor()
if under == 'import':
current_line = self._user_context.get_position_line()
if not current_line.endswith('import import'):
continue
a = s.import_stmt.alias
if a and a.start_pos <= self._pos <= a.end_pos:
continue
names = s.get_defined_names(on_import_stmt=True)
else:
names = []
for _, new_names in s.scope_names_generator():
names += new_names
for c in names:
completions.append((c, s))
return completions
def _prepare_goto(self, goto_path, is_completion=False):
"""
Base for completions/goto. Basically it returns the resolved scopes
under cursor.
"""
debug.dbg('start: %s in %s', goto_path, self._parser.user_scope())
user_stmt = self._parser.user_stmt_with_whitespace()
if not user_stmt and len(goto_path.split('\n')) > 1:
# If the user_stmt is not defined and the goto_path is multi line,
# something's strange. Most probably the backwards tokenizer
# matched to much.
return []
if isinstance(user_stmt, pr.Import):
scopes = [helpers.get_on_import_stmt(self._evaluator, self._user_context,
user_stmt, is_completion)[0]]
else:
# just parse one statement, take it and evaluate it
eval_stmt = self._get_under_cursor_stmt(goto_path)
if not is_completion:
# goto_definition returns definitions of its statements if the
# cursor is on the assignee. By changing the start_pos of our
# "pseudo" statement, the Jedi evaluator can find the assignees.
if user_stmt is not None:
eval_stmt.start_pos = user_stmt.end_pos
scopes = self._evaluator.eval_statement(eval_stmt)
return scopes
def _get_under_cursor_stmt(self, cursor_txt):
tokenizer = source_tokens(cursor_txt, line_offset=self._pos[0] - 1)
r = Parser(cursor_txt, no_docstr=True, tokenizer=tokenizer)
try:
# Take the last statement available.
stmt = r.module.statements[-1]
except IndexError:
raise NotFoundError()
if isinstance(stmt, pr.KeywordStatement):
stmt = stmt.stmt
if not isinstance(stmt, pr.ExprStmt):
raise NotFoundError()
user_stmt = self._parser.user_stmt()
if user_stmt is None:
# Set the start_pos to a pseudo position, that doesn't exist but works
# perfectly well (for both completions in docstrings and statements).
stmt.start_pos = self._pos
else:
stmt.start_pos = user_stmt.start_pos
stmt.parent = self._parser.user_scope()
return stmt
def complete(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.completions` instead.
.. todo:: Remove!
"""
warnings.warn("Use completions instead.", DeprecationWarning)
return self.completions()
def goto(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.goto_assignments` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_assignments instead.", DeprecationWarning)
return self.goto_assignments()
def definition(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.goto_definitions` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_definitions instead.", DeprecationWarning)
return self.goto_definitions()
def get_definition(self):
"""
.. deprecated:: 0.5.0
Use :attr:`.goto_definitions` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_definitions instead.", DeprecationWarning)
return self.goto_definitions()
def related_names(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.usages` instead.
.. todo:: Remove!
"""
warnings.warn("Use usages instead.", DeprecationWarning)
return self.usages()
def get_in_function_call(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.call_signatures` instead.
.. todo:: Remove!
"""
return self.function_definition()
def function_definition(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.call_signatures` instead.
.. todo:: Remove!
"""
warnings.warn("Use call_signatures instead.", DeprecationWarning)
sig = self.call_signatures()
return sig[0] if sig else None
def goto_definitions(self):
"""
Return the definitions of a the path under the cursor. goto function!
This follows complicated paths and returns the end, not the first
definition. The big difference between :meth:`goto_assignments` and
:meth:`goto_definitions` is that :meth:`goto_assignments` doesn't
follow imports and statements. Multiple objects may be returned,
because Python itself is a dynamic language, which means depending on
an option you can have two different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
def resolve_import_paths(scopes):
for s in scopes.copy():
if isinstance(s, imports.ImportWrapper):
scopes.remove(s)
scopes.update(resolve_import_paths(set(s.follow())))
return scopes
user_stmt = self._parser.user_stmt_with_whitespace()
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
definitions = set()
if next(context) in ('class', 'def'):
definitions = set([er.wrap(self._evaluator, self._parser.user_scope())])
else:
# Fetch definition of callee, if there's no path otherwise.
if not goto_path:
call, _, _ = search_call_signatures(user_stmt, self._pos)
if call is not None:
definitions = set(self._evaluator.eval_call(call))
if not definitions:
if goto_path:
definitions = set(self._prepare_goto(goto_path))
definitions = resolve_import_paths(definitions)
names = [s.name for s in definitions
if s is not imports.ImportWrapper.GlobalNamespace]
defs = [classes.Definition(self._evaluator, name) for name in names]
return helpers.sorted_definitions(set(defs))
def goto_assignments(self):
"""
Return the first definition found. Imports and statements aren't
followed. Multiple objects may be returned, because Python itself is a
dynamic language, which means depending on an option you can have two
different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
results = self._goto()
d = [classes.Definition(self._evaluator, d) for d in set(results)
if d is not imports.ImportWrapper.GlobalNamespace]
return helpers.sorted_definitions(d)
def _goto(self, add_import_name=False):
"""
Used for goto_assignments and usages.
:param add_import_name: Add the the name (if import) to the result.
"""
def follow_inexistent_imports(defs):
""" Imports can be generated, e.g. following
`multiprocessing.dummy` generates an import dummy in the
multiprocessing module. The Import doesn't exist -> follow.
"""
definitions = set(defs)
for d in defs:
if isinstance(d.parent, pr.Import) \
and d.start_pos == (0, 0):
i = imports.ImportWrapper(self._evaluator, d.parent).follow(is_goto=True)
definitions.remove(d)
definitions |= follow_inexistent_imports(i)
return definitions
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
user_stmt = self._parser.user_stmt()
stmt = self._get_under_cursor_stmt(goto_path)
expression_list = stmt.expression_list()
if len(expression_list) == 0:
return []
# The reverse tokenizer only generates parses call.
assert len(expression_list) == 1
call = expression_list[0]
if isinstance(call, pr.Call):
call_path = list(call.generate_call_path())
else:
# goto_assignments on Operator returns nothing.
return []
if next(context) in ('class', 'def'):
# The cursor is on a class/function name.
user_scope = self._parser.user_scope()
definitions = set([user_scope.name])
elif isinstance(user_stmt, pr.Import):
s, name_part = helpers.get_on_import_stmt(self._evaluator,
self._user_context, user_stmt)
try:
definitions = [s.follow(is_goto=True)[0]]
except IndexError:
definitions = []
if add_import_name:
import_name = user_stmt.get_defined_names()
# imports have only one name
np = import_name[0]
if not user_stmt.star and unicode(name_part) == unicode(np):
definitions.append(np)
else:
# The Evaluator.goto function checks for definitions, but since we
# use a reverse tokenizer, we have new name_part objects, so we
# have to check the user_stmt here for positions.
if isinstance(user_stmt, pr.ExprStmt):
for name in user_stmt.get_defined_names():
if name.start_pos <= self._pos <= name.end_pos \
and (not isinstance(name.parent, pr.Call)
or name.parent.next is None):
return [name]
defs = self._evaluator.goto(stmt, call_path)
definitions = follow_inexistent_imports(defs)
return definitions
def usages(self, additional_module_paths=()):
"""
Return :class:`classes.Definition` objects, which contain all
names that point to the definition of the name under the cursor. This
is very useful for refactoring (renaming), or to show all usages of a
variable.
.. todo:: Implement additional_module_paths
:rtype: list of :class:`classes.Definition`
"""
temp, settings.dynamic_flow_information = \
settings.dynamic_flow_information, False
try:
user_stmt = self._parser.user_stmt()
definitions = self._goto(add_import_name=True)
if not definitions:
# Without a definition for a name we cannot find references.
return []
if not isinstance(user_stmt, pr.Import):
# import case is looked at with add_import_name option
definitions = usages.usages_add_import_modules(self._evaluator,
definitions)
module = set([d.get_parent_until() for d in definitions])
module.add(self._parser.module())
names = usages.usages(self._evaluator, definitions, module)
for d in set(definitions):
try:
name_part = d.names[-1]
except AttributeError:
names.append(classes.Definition(self._evaluator, d))
else:
names.append(classes.Definition(self._evaluator, name_part))
finally:
settings.dynamic_flow_information = temp
return helpers.sorted_definitions(set(names))
def call_signatures(self):
"""
Return the function object of the call you're currently in.
E.g. if the cursor is here::
abs(# <-- cursor is here
This would return the ``abs`` function. On the other hand::
abs()# <-- cursor is here
This would return ``None``.
:rtype: list of :class:`classes.CallSignature`
"""
user_stmt = self._parser.user_stmt_with_whitespace()
call, execution_arr, index = search_call_signatures(user_stmt, self._pos)
if call is None:
return []
with common.scale_speed_settings(settings.scale_call_signatures):
origins = cache.cache_call_signatures(self._evaluator, call, self.source,
self._pos, user_stmt)
debug.speed('func_call followed')
key_name = None
try:
detail = execution_arr[index].assignment_details[0]
except IndexError:
pass
else:
try:
key_name = unicode(detail[0][0].name)
except (IndexError, AttributeError):
pass
return [classes.CallSignature(self._evaluator, o.name, call, index, key_name)
for o in origins if hasattr(o, 'py__call__')]
def _analysis(self):
#statements = set(chain(*self._parser.module().used_names.values()))
stmts, imps = analysis.get_module_statements(self._parser.module())
# Sort the statements so that the results are reproducible.
for i in imps:
iw = imports.ImportWrapper(self._evaluator, i,
nested_resolve=True).follow()
if i.is_nested() and any(not isinstance(i, pr.Module) for i in iw):
analysis.add(self._evaluator, 'import-error', i.namespace_names[-1])
for stmt in sorted(stmts, key=lambda obj: obj.start_pos):
if not (isinstance(stmt.parent, pr.ForFlow)
and stmt.parent.set_stmt == stmt):
self._evaluator.eval_statement(stmt)
ana = [a for a in self._evaluator.analysis if self.path == a.path]
return sorted(set(ana), key=lambda x: x.line)
class Script(object):
"""
A Script is the base for completions, goto or whatever you want to do with
|jedi|.
You can either use the ``source`` parameter or ``path`` to read a file.
Usually you're going to want to use both of them (in an editor).
:param source: The source code of the current file, separated by newlines.
:type source: str
:param line: The line to perform actions on (starting with 1).
:type line: int
:param col: The column of the cursor (starting with 0).
:type col: int
:param path: The path of the file in the file system, or ``''`` if
it hasn't been saved yet.
:type path: str or None
:param encoding: The encoding of ``source``, if it is not a
``unicode`` object (default ``'utf-8'``).
:type encoding: str
"""
def __init__(self, source=None, line=None, column=None, path=None,
encoding='utf-8', source_path=None):
if source_path is not None:
warnings.warn("Use path instead of source_path.", DeprecationWarning)
path = source_path
self._source_path = path
self.path = None if path is None else os.path.abspath(path)
if source is None:
with open(path) as f:
source = f.read()
lines = source.splitlines() or ['']
if source and source[-1] == '\n':
lines.append('')
line = max(len(lines), 1) if line is None else line
if not (0 < line <= len(lines)):
raise ValueError('`line` parameter is not in a valid range.')
line_len = len(lines[line - 1])
column = line_len if column is None else column
if not (0 <= column <= line_len):
raise ValueError('`column` parameter is not in a valid range.')
self._pos = line, column
cache.clear_caches()
debug.reset_time()
self.source = common.source_to_unicode(source, encoding)
self._user_context = UserContext(self.source, self._pos)
self._parser = UserContextParser(self.source, path, self._pos, self._user_context)
self._evaluator = Evaluator()
debug.speed('init')
@property
def source_path(self):
"""
.. deprecated:: 0.7.0
Use :attr:`.path` instead.
.. todo:: Remove!
"""
warnings.warn("Use path instead of source_path.", DeprecationWarning)
return self.path
def __repr__(self):
return '<%s: %s>' % (self.__class__.__name__, repr(self._source_path))
def completions(self):
"""
Return :class:`classes.Completion` objects. Those objects contain
information about the completions, more than just names.
:return: Completion objects, sorted by name and __ comes last.
:rtype: list of :class:`classes.Completion`
"""
def get_completions(user_stmt, bs):
if isinstance(user_stmt, pr.Import):
context = self._user_context.get_context()
next(context) # skip the path
if next(context) == 'from':
# completion is just "import" if before stands from ..
return ((k, bs) for k in keywords.keyword_names('import'))
return self._simple_complete(path, like)
debug.speed('completions start')
path = self._user_context.get_path_until_cursor()
if re.search('^\.|\.\.$', path):
return []
path, dot, like = helpers.completion_parts(path)
user_stmt = self._parser.user_stmt_with_whitespace()
b = compiled.builtin
completions = get_completions(user_stmt, b)
if not dot:
# add named params
for call_sig in self.call_signatures():
# allow protected access, because it's a public API.
module = call_sig._definition.get_parent_until()
# Compiled modules typically don't allow keyword arguments.
if not isinstance(module, compiled.CompiledObject):
for p in call_sig.params:
# Allow access on _definition here, because it's a
# public API and we don't want to make the internal
# Name object public.
completions.append((p._definition.get_name(), p))
if not path and not isinstance(user_stmt, pr.Import):
# add keywords
completions += ((k, b) for k in keywords.keyword_names(all=True))
needs_dot = not dot and path
comps = []
comp_dct = {}
for c, s in set(completions):
n = str(c.names[-1])
if settings.case_insensitive_completion \
and n.lower().startswith(like.lower()) \
or n.startswith(like):
if not filter_private_variable(s, user_stmt or self._parser.user_scope(), n):
new = classes.Completion(self._evaluator, c, needs_dot, len(like), s)
k = (new.name, new.complete) # key
if k in comp_dct and settings.no_completion_duplicates:
comp_dct[k]._same_name_completions.append(new)
else:
comp_dct[k] = new
comps.append(new)
debug.speed('completions end')
return sorted(comps, key=lambda x: (x.name.startswith('__'),
x.name.startswith('_'),
x.name.lower()))
def _simple_complete(self, path, like):
try:
scopes = list(self._prepare_goto(path, True))
except NotFoundError:
scopes = []
scope_generator = get_names_of_scope(self._evaluator,
self._parser.user_scope(),
self._pos)
completions = []
for scope, name_list in scope_generator:
for c in name_list:
completions.append((c, scope))
else:
completions = []
debug.dbg('possible completion scopes: %s', scopes)
for s in scopes:
if s.isinstance(er.Function):
names = s.get_magic_function_names()
else:
if isinstance(s, imports.ImportPath):
under = like + self._user_context.get_path_after_cursor()
if under == 'import':
current_line = self._user_context.get_position_line()
if not current_line.endswith('import import'):
continue
a = s.import_stmt.alias
if a and a.start_pos <= self._pos <= a.end_pos:
continue
names = s.get_defined_names(on_import_stmt=True)
else:
names = s.get_defined_names()
for c in names:
completions.append((c, s))
return completions
def _prepare_goto(self, goto_path, is_completion=False):
"""
Base for completions/goto. Basically it returns the resolved scopes
under cursor.
"""
debug.dbg('start: %s in %s', goto_path, self._parser.user_scope())
user_stmt = self._parser.user_stmt_with_whitespace()
if not user_stmt and len(goto_path.split('\n')) > 1:
# If the user_stmt is not defined and the goto_path is multi line,
# something's strange. Most probably the backwards tokenizer
# matched to much.
return []
if isinstance(user_stmt, pr.Import):
scopes = [helpers.get_on_import_stmt(self._evaluator, self._user_context,
user_stmt, is_completion)[0]]
else:
# just parse one statement, take it and evaluate it
stmt = self._get_under_cursor_stmt(goto_path)
scopes = self._evaluator.eval_statement(stmt)
return scopes
def _get_under_cursor_stmt(self, cursor_txt):
tokenizer = source_tokens(cursor_txt, self._pos[0] - 1)
r = Parser(cursor_txt, no_docstr=True, tokenizer=tokenizer)
try:
# Take the last statement available.
stmt = r.module.statements[-1]
except IndexError:
raise NotFoundError()
# Set the start_pos to a pseudo position, that doesn't exist but works
# perfectly well (for both completions in docstrings and statements).
stmt.start_pos = self._pos
stmt.parent = self._parser.user_scope()
return stmt
def complete(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.completions` instead.
.. todo:: Remove!
"""
warnings.warn("Use completions instead.", DeprecationWarning)
return self.completions()
def goto(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.goto_assignments` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_assignments instead.", DeprecationWarning)
return self.goto_assignments()
def definition(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.goto_definitions` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_definitions instead.", DeprecationWarning)
return self.goto_definitions()
def get_definition(self):
"""
.. deprecated:: 0.5.0
Use :attr:`.goto_definitions` instead.
.. todo:: Remove!
"""
warnings.warn("Use goto_definitions instead.", DeprecationWarning)
return self.goto_definitions()
def related_names(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.usages` instead.
.. todo:: Remove!
"""
warnings.warn("Use usages instead.", DeprecationWarning)
return self.usages()
def get_in_function_call(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.call_signatures` instead.
.. todo:: Remove!
"""
return self.function_definition()
def function_definition(self):
"""
.. deprecated:: 0.6.0
Use :attr:`.call_signatures` instead.
.. todo:: Remove!
"""
warnings.warn("Use line instead.", DeprecationWarning)
sig = self.call_signatures()
return sig[0] if sig else None
def goto_definitions(self):
"""
Return the definitions of a the path under the cursor. goto function!
This follows complicated paths and returns the end, not the first
definition. The big difference between :meth:`goto_assignments` and
:meth:`goto_definitions` is that :meth:`goto_assignments` doesn't
follow imports and statements. Multiple objects may be returned,
because Python itself is a dynamic language, which means depending on
an option you can have two different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
def resolve_import_paths(scopes):
for s in scopes.copy():
if isinstance(s, imports.ImportPath):
scopes.remove(s)
scopes.update(resolve_import_paths(set(s.follow())))
return scopes
user_stmt = self._parser.user_stmt_with_whitespace()
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
definitions = set()
if next(context) in ('class', 'def'):
definitions = set([self._parser.user_scope()])
else:
# Fetch definition of callee, if there's no path otherwise.
if not goto_path:
(call, _) = helpers.func_call_and_param_index(user_stmt, self._pos)
if call is not None:
while call.next is not None:
call = call.next
# reset cursor position:
(row, col) = call.name.end_pos
pos = (row, max(col - 1, 0))
self._user_context = UserContext(self.source, pos)
# then try to find the path again
goto_path = self._user_context.get_path_under_cursor()
if not definitions:
if goto_path:
definitions = set(self._prepare_goto(goto_path))
definitions = resolve_import_paths(definitions)
d = set([classes.Definition(self._evaluator, s) for s in definitions
if s is not imports.ImportPath.GlobalNamespace])
return helpers.sorted_definitions(d)
def goto_assignments(self):
"""
Return the first definition found. Imports and statements aren't
followed. Multiple objects may be returned, because Python itself is a
dynamic language, which means depending on an option you can have two
different versions of a function.
:rtype: list of :class:`classes.Definition`
"""
results, _ = self._goto()
d = [classes.Definition(self._evaluator, d) for d in set(results)
if d is not imports.ImportPath.GlobalNamespace]
return helpers.sorted_definitions(d)
def _goto(self, add_import_name=False):
"""
Used for goto_assignments and usages.
:param add_import_name: Add the the name (if import) to the result.
"""
def follow_inexistent_imports(defs):
""" Imports can be generated, e.g. following
`multiprocessing.dummy` generates an import dummy in the
multiprocessing module. The Import doesn't exist -> follow.
"""
definitions = set(defs)
for d in defs:
if isinstance(d.parent, pr.Import) \
and d.start_pos == (0, 0):
i = imports.ImportPath(self._evaluator, d.parent).follow(is_goto=True)
definitions.remove(d)
definitions |= follow_inexistent_imports(i)
return definitions
goto_path = self._user_context.get_path_under_cursor()
context = self._user_context.get_context()
user_stmt = self._parser.user_stmt()
if next(context) in ('class', 'def'):
user_scope = self._parser.user_scope()
definitions = set([user_scope.name])
search_name = unicode(user_scope.name)
elif isinstance(user_stmt, pr.Import):
s, name_part = helpers.get_on_import_stmt(self._evaluator,
self._user_context, user_stmt)
try:
definitions = [s.follow(is_goto=True)[0]]
except IndexError:
definitions = []
search_name = unicode(name_part)
if add_import_name:
import_name = user_stmt.get_defined_names()
# imports have only one name
if not user_stmt.star \
and name_part == import_name[0].names[-1]:
definitions.append(import_name[0])
else:
stmt = self._get_under_cursor_stmt(goto_path)
defs, search_name = self._evaluator.goto(stmt)
definitions = follow_inexistent_imports(defs)
if isinstance(user_stmt, pr.Statement):
c = user_stmt.expression_list()
if c and not isinstance(c[0], (str, unicode)) \
and c[0].start_pos > self._pos \
and not re.search(r'\.\w+$', goto_path):
# The cursor must be after the start, otherwise the
# statement is just an assignee.
definitions = [user_stmt]
return definitions, search_name
def usages(self, additional_module_paths=()):
"""
Return :class:`classes.Usage` objects, which contain all
names that point to the definition of the name under the cursor. This
is very useful for refactoring (renaming), or to show all usages of a
variable.
.. todo:: Implement additional_module_paths
:rtype: list of :class:`classes.Usage`
"""
temp, settings.dynamic_flow_information = \
settings.dynamic_flow_information, False
user_stmt = self._parser.user_stmt()
definitions, search_name = self._goto(add_import_name=True)
if isinstance(user_stmt, pr.Statement):
c = user_stmt.expression_list()[0]
if not isinstance(c, unicode) and self._pos < c.start_pos:
# the search_name might be before `=`
definitions = [v for v in user_stmt.get_set_vars()
if unicode(v.names[-1]) == search_name]
if not isinstance(user_stmt, pr.Import):
# import case is looked at with add_import_name option
definitions = usages.usages_add_import_modules(self._evaluator, definitions, search_name)
module = set([d.get_parent_until() for d in definitions])
module.add(self._parser.module())
names = usages.usages(self._evaluator, definitions, search_name, module)
for d in set(definitions):
if isinstance(d, pr.Module):
names.append(usages.Usage(self._evaluator, d, d))
elif isinstance(d, er.Instance):
# Instances can be ignored, because they have been created by
# ``__getattr__``.
pass
else:
names.append(usages.Usage(self._evaluator, d.names[-1], d))
settings.dynamic_flow_information = temp
return helpers.sorted_definitions(set(names))
def call_signatures(self):
"""
Return the function object of the call you're currently in.
E.g. if the cursor is here::
abs(# <-- cursor is here
This would return the ``abs`` function. On the other hand::
abs()# <-- cursor is here
This would return ``None``.
:rtype: list of :class:`classes.CallSignature`
"""
user_stmt = self._parser.user_stmt_with_whitespace()
call, index = helpers.func_call_and_param_index(user_stmt, self._pos)
if call is None:
return []
with common.scale_speed_settings(settings.scale_call_signatures):
_callable = lambda: self._evaluator.eval_call(call)
origins = cache.cache_call_signatures(_callable, user_stmt)
debug.speed('func_call followed')
return [classes.CallSignature(self._evaluator, o, call, index) for o in origins
if o.isinstance(er.Function, er.Instance, er.Class)
or isinstance(o, compiled.CompiledObject) and o.type() != 'module']
