From 700493cac8429e2b2daca5651726b18bda57daad Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 14:07:07 +0100 Subject: [PATCH 01/10] Fix and improve Statement.__doc__ - The type of `set_vars` and `used_vars` were wrong. - ":param ...:" was used instead of ":type ...:". - The parameter table is aligned to make it easier to read. --- jedi/parsing_representation.py | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/jedi/parsing_representation.py b/jedi/parsing_representation.py index 3df46239..683d6bcd 100644 --- a/jedi/parsing_representation.py +++ b/jedi/parsing_representation.py @@ -663,14 +663,18 @@ class Statement(Simple): stores pretty much all the Python code, except functions, classes, imports, and flow functions like if, for, etc. - :param set_vars: The variables which are defined by the statement. - :param set_vars: str - :param used_vars: The variables which are used by the statement. - :param used_vars: str - :param token_list: Token list which is also peppered with Name. - :param token_list: list - :param start_pos: Position (line, column) of the Statement. - :type start_pos: tuple(int, int) + :type set_vars: list of :class:`Name` + :param set_vars: The variables which are defined by the statement. + :type used_vars: list of :class:`Name` + :param used_vars: The variables which are used by the statement. + :type token_list: list + :param token_list: + List of tokens or names. Each element is either an instance + of :class:`Name` or a tuple of token type value (e.g., + :data:`tokenize.NUMBER`), token string (e.g., ``'='``), and + start position (e.g., ``(1, 0)``). + :type start_pos: 2-tuple of int + :param start_pos: Position (line, column) of the Statement. """ __slots__ = ('token_list', 'used_vars', 'set_vars', '_commands', '_assignment_details') From dc9a269d35bcad9dcaa48408432e4a22e2a842fd Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 14:07:48 +0100 Subject: [PATCH 02/10] Use literal block instead of >>> for code example --- jedi/parsing_representation.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/jedi/parsing_representation.py b/jedi/parsing_representation.py index 683d6bcd..08cdba53 100644 --- a/jedi/parsing_representation.py +++ b/jedi/parsing_representation.py @@ -696,11 +696,11 @@ class Statement(Simple): def _remove_executions_from_set_vars(self, set_vars): """ - Important mainly for assosiative arrays: + Important mainly for assosiative arrays:: - >>> a = 3 - >>> b = {} - >>> b[a] = 3 + a = 3 + b = {} + b[a] = 3 `a` is in this case not a set_var, it is used to index the dict. """ From ac159bac07855de7870c857d419fa9dcbd877300 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 14:17:16 +0100 Subject: [PATCH 03/10] Document pr.Simple.__init__ --- jedi/parsing_representation.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/jedi/parsing_representation.py b/jedi/parsing_representation.py index 08cdba53..c4c0ac1d 100644 --- a/jedi/parsing_representation.py +++ b/jedi/parsing_representation.py @@ -50,6 +50,16 @@ class Simple(Base): '_end_pos') def __init__(self, module, start_pos, end_pos=(None, None)): + """ + Initialize :class:`Simple`. + + :type module: :class:`SubModule` + :param module: The module in which this Python object locates. + :type start_pos: 2-tuple of int + :param start_pos: Position (line, column) of the Statement. + :type end_pos: 2-tuple of int + :param end_pos: Same as `start_pos`. + """ self._sub_module = module self._start_pos = start_pos self._end_pos = end_pos From 77e8b2aecd859974fa993b74026b3ad8926cdbb8 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 14:18:58 +0100 Subject: [PATCH 04/10] Remove a philosophical (and confusing) statement --- jedi/parsing_representation.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/jedi/parsing_representation.py b/jedi/parsing_representation.py index c4c0ac1d..cbadf488 100644 --- a/jedi/parsing_representation.py +++ b/jedi/parsing_representation.py @@ -587,9 +587,6 @@ class Import(Simple): """ Stores the imports of any Scopes. - >>> 1+1 - 2 - :param start_pos: Position (line, column) of the Import. :type start_pos: tuple(int, int) :param namespace: The import, can be empty if a star is given From 99ab2dec158d9d29579aa5673482d42696c554e0 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 14:39:10 +0100 Subject: [PATCH 05/10] Document pr.SubModule --- jedi/parsing_representation.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/jedi/parsing_representation.py b/jedi/parsing_representation.py index cbadf488..492b2119 100644 --- a/jedi/parsing_representation.py +++ b/jedi/parsing_representation.py @@ -269,12 +269,22 @@ class Module(IsScope): class SubModule(Scope, Module): + """ The top scope, which is always a module. Depending on the underlying parser this may be a full module or just a part of a module. """ + def __init__(self, path, start_pos=(1, 0), top_module=None): + """ + Initialize :class:`SubModule`. + + :type path: str + :arg path: File path to this module. + + .. todo:: Document `top_module`. + """ super(SubModule, self).__init__(self, start_pos) self.path = path self.global_vars = [] From d256c5470ce6fa172774ccd9d4c41e073c90583f Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 14:52:31 +0100 Subject: [PATCH 06/10] Add a very short tutorial on parsing_representation --- jedi/parsing_representation.py | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/jedi/parsing_representation.py b/jedi/parsing_representation.py index 492b2119..816087f9 100644 --- a/jedi/parsing_representation.py +++ b/jedi/parsing_representation.py @@ -14,6 +14,25 @@ One special thing: ``[1, 2+33]`` for example would be an Array with two ``Statement`` inside. This is the easiest way to write a parser. The same behaviour applies to ``Param``, which is being used in a function definition. + +The easiest way to play with this module is to use :class:`parsing.Parser`. +:attr:`parsing.Parser.scope` holds an instance of :class:`SubModule`: + +>>> from jedi.parsing import Parser +>>> parser = Parser('import os', 'example.py') +>>> submodule = parser.scope +>>> submodule + + +Any subclasses of :class:`Scope`, including :class:`SubModule` has +attribute :attr:`imports `. This attribute has import +statements in this scope. Check this out: + +>>> submodule.imports +[] + +See also :attr:`Scope.subscopes` and :attr:`Scope.statements`. + """ import os From 8e85adb71887d12badcb3089a63bf71744ca0a49 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 15:19:34 +0100 Subject: [PATCH 07/10] Document Scope.get_defined_names --- jedi/parsing_representation.py | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/jedi/parsing_representation.py b/jedi/parsing_representation.py index 816087f9..ba201023 100644 --- a/jedi/parsing_representation.py +++ b/jedi/parsing_representation.py @@ -212,7 +212,7 @@ class Scope(Simple, IsScope): def get_set_vars(self): """ Get all the names, that are active and accessible in the current - scope. + scope. See :meth:`get_defined_names` for examples. :return: list of Name :rtype: list @@ -233,6 +233,26 @@ class Scope(Simple, IsScope): return n def get_defined_names(self): + """ + Get all defined names in this scope. + + >>> from jedi.parsing import Parser + >>> parser = Parser(''' + ... a = x + ... b = y + ... b.c = z + ... ''') + >>> parser.scope.get_defined_names() + [, ] + + Note that unlike :meth:`get_set_vars`, assignment to object + attribute does not change the result because it does not change + the defined names in this scope. + + >>> parser.scope.get_set_vars() + [, , ] + + """ return [n for n in self.get_set_vars() if isinstance(n, Import) or len(n) == 1] From 11707ffbbb7e9d72349aed005fa90a4d16e6cb54 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 15:29:26 +0100 Subject: [PATCH 08/10] Document evaluate.get_defined_names_for_position --- jedi/evaluate.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/jedi/evaluate.py b/jedi/evaluate.py index 4d6269b3..1587ac09 100644 --- a/jedi/evaluate.py +++ b/jedi/evaluate.py @@ -87,9 +87,17 @@ import docstrings def get_defined_names_for_position(scope, position=None, start_scope=None): """ - Deletes all names that are ahead of the position, except for some special - objects like instances, where the position doesn't matter. + Return filtered version of ``scope.get_defined_names()``. + This function basically does what :meth:`scope.get_defined_names + ` does. + + - If `position` is given, delete all names defined after `position`. + - For special objects like instances, `position` is ignored and all + names are returned. + + :type scope: :class:`parsing_representation.IsScope` + :param scope: Scope in which names are searched. :param position: the position as a line/column tuple, default is infinity. """ names = scope.get_defined_names() From 0c6f7f66e9ffe66889e206857423adca15dc6df0 Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Sun, 3 Mar 2013 15:49:49 +0100 Subject: [PATCH 09/10] Document get_names_of_scope with examples --- jedi/evaluate.py | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/jedi/evaluate.py b/jedi/evaluate.py index 1587ac09..421cc859 100644 --- a/jedi/evaluate.py +++ b/jedi/evaluate.py @@ -120,6 +120,39 @@ def get_names_of_scope(scope, position=None, star_search=True, Get all completions (names) possible for the current scope. The star search option is only here to provide an optimization. Otherwise the whole thing would probably start a little recursive madness. + + This function is used to include names from outer scopes. For example, + when the current scope is function: + + >>> from jedi.parsing import Parser + >>> parser = Parser(''' + ... x = ['a', 'b', 'c'] + ... def func(): + ... y = None + ... ''') + >>> scope = parser.scope.subscopes[0] + >>> scope + + + `get_names_of_scope` is a generator. First it yields names from + most inner scope. + + >>> pairs = list(get_names_of_scope(scope)) + >>> pairs[0] + (, []) + + Then it yield the names from one level outer scope. For this + example, this is the most outer scope. + + >>> pairs[1] + (, [, ]) + + Finally, it yields names from builtin, if `include_builtin` is + true (default). + + >>> pairs[2] #doctest: +ELLIPSIS + (, [, ...]) + """ in_func_scope = scope non_flow = scope.get_parent_until(pr.Flow, reverse=True) From 8d486ff9aa82446f7af3b351e79749f02b201f0f Mon Sep 17 00:00:00 2001 From: Takafumi Arakaki Date: Mon, 4 Mar 2013 02:07:47 +0100 Subject: [PATCH 10/10] Make doctest Python 3.x compatible --- jedi/evaluate.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jedi/evaluate.py b/jedi/evaluate.py index 421cc859..884a2ea6 100644 --- a/jedi/evaluate.py +++ b/jedi/evaluate.py @@ -151,7 +151,7 @@ def get_names_of_scope(scope, position=None, star_search=True, true (default). >>> pairs[2] #doctest: +ELLIPSIS - (, [, ...]) + (, [, ...]) """ in_func_scope = scope