VimPlug/jedi-fork
1
0
Fork 0
forked from VimPlug/jedi
Code Pull Requests Activity

Merge pull request #86 from dbrgn/docs

Browse Source 
Sphinx Docs
This commit is contained in:
David Halter
2012-12-26 08:35:38 -08:00
parent bd93f8fd2d 6b31199371
commit b7888c3d7c
8 changed files with 685 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
jedi/api.py
+44 -36
View File
@@ -46,7 +46,7 @@ from _compatibility import next, unicode
class NotFoundError(Exception):
""" A custom error to avoid catching the wrong exceptions """
"""A custom error to avoid catching the wrong exceptions."""
pass
@@ -54,16 +54,17 @@ class Script(object):
"""
A Script is the base for a completion, goto or whatever call.
:param source: The source code of the current file
:param source: The source code of the current file, separated by newlines.
:type source: string
:param line: The line to complete in.
:param line: The line to perform actions on (starting with 1).
:type line: int
:param col: The column to complete in.
:param col: The column of the cursor (starting with 0).
:type col: int
:param source_path: The path in the os, the current module is in.
:param source_path: The path of the file in the file system, or ``''`` if
it hasn't been saved yet.
:type source_path: string or None
:param source_encoding: encoding for decoding `source`, if it
is not a `unicode` object.
:param source_encoding: The encoding of ``source``, if it is not a
``unicode`` object (default `utf-8`).
:type source_encoding: string
"""
def __init__(self, source, line, column, source_path,
@@ -79,14 +80,16 @@ class Script(object):
@property
def parser(self):
""" The lazy parser """
""" The lazy parser."""
return self.module.parser
def complete(self):
"""
An auto completer for python files.
Return :class:`api_classes.Completion` objects. Those objects contain
information about the completions, more than just names.
:return: list of Completion objects, sorted by name and __ comes last.
:return: list of :class:`api_classes.Completion` objects, sorted by
name and __ comes last.
:rtype: list
"""
def follow_imports_if_possible(name):
@@ -207,16 +210,16 @@ class Script(object):
def get_definition(self):
"""
Returns the definitions of a the path under the cursor. This is
not a goto function! This follows complicated paths and returns the
end, not the first definition.
The big difference of goto and get_definition is that goto 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.
Return the definitions of a the path under the cursor. This is not a
goto function! This follows complicated paths and returns the end, not
the first definition. The big difference between :meth:`goto` and
:meth:`get_definition` is that :meth:`goto` 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.
:return: list of Definition objects, which are basically scopes.
:return: list of :class:`api_classes.Definition` objects, which are
basically scopes.
:rtype: list
"""
def resolve_import_paths(scopes):
@@ -248,13 +251,13 @@ class Script(object):
def goto(self):
"""
Returns the first definition found by goto. This means: It 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.
Return the first definition found by goto. 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.
:return: list of Definition objects, which are basically scopes.
:return: list of :class:`api_classes.Definition` objects, which are
basically scopes.
"""
d = [api_classes.Definition(d) for d in set(self._goto()[0])]
return sorted(d, key=lambda x: (x.module_path, x.start_pos))
@@ -305,12 +308,12 @@ class Script(object):
def related_names(self, additional_module_paths=[]):
"""
Returns `dynamic.RelatedName` objects, which contain all names, that
are defined by the same variable, function, class or import.
This function can be used either to show all the usages of a variable
or for renaming purposes.
Return :class:`api_classes.RelatedName` 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
.. todo:: Implement additional_module_paths
"""
user_stmt = self.parser.user_stmt
definitions, search_name = self._goto(add_import_name=True)
@@ -339,13 +342,17 @@ class Script(object):
def get_in_function_call(self):
"""
Return the function, that the cursor is in, e.g.:
>>> isinstance(| # | <-- cursor is here
Return the function object of the call you're currently in.
E.g. if the cursor is here::
This would return the `isinstance` function. In contrary:
>>> isinstance()| # | <-- cursor is here
>>> abs(# <-- cursor is here
This would return `None`.
This would return the ``abs`` function. On the other hand::
>>> abs()# <-- cursor is here
This would return ``None``.
"""
def check_user_stmt(user_stmt):
if user_stmt is None \
@@ -451,7 +458,8 @@ class Script(object):
def set_debug_function(func_cb=debug.print_to_stdout, warnings=True,
notices=True, speed=True):
"""
You can define a callback debug function to get all the debug messages.
Define a callback debug function to get all the debug messages.
:param func_cb: The callback function for debug messages, with n params.
"""
debug.debug_function = func_cb
jedi/api_classes.py
+52 -27
View File
@@ -56,6 +56,7 @@ class BaseDefinition(object):
@property
def type(self):
"""The type of the definition."""
# generate the type
stripped = self.definition
if isinstance(self.definition, evaluate.InstanceElement):
@@ -64,6 +65,7 @@ class BaseDefinition(object):
@property
def path(self):
"""The module path."""
path = []
if not isinstance(self.definition, keywords.Keyword):
par = self.definition
@@ -77,20 +79,24 @@ class BaseDefinition(object):
@property
def module_name(self):
"""The module name."""
path = self.module_path
sep = os.path.sep
p = re.sub(r'^.*?([\w\d]+)(%s__init__)?.py$' % sep, r'\1', path)
return p
def in_builtin_module(self):
"""Whether this is a builtin module."""
return not self.module_path.endswith('.py')
@property
def line_nr(self):
"""The line where the definition occurs (starting with 1)."""
return self.start_pos[0]
@property
def column(self):
"""The column where the definition occurs (starting with 0)."""
return self.start_pos[1]
@property
@@ -103,7 +109,7 @@ class BaseDefinition(object):
@property
def raw_doc(self):
""" Returns the raw docstring `__doc__` for any object """
"""The raw docstring ``__doc__`` for any object."""
try:
return unicode(self.definition.docstr)
except AttributeError:
@@ -111,13 +117,12 @@ class BaseDefinition(object):
@property
def description(self):
"""A textual description of the object."""
return unicode(self.definition)
@property
def full_name(self):
"""
Returns the path to a certain class/function, see #61.
"""
"""The path to a certain class/function, see #61."""
path = [unicode(p) for p in self.path]
# TODO add further checks, the mapping should only occur on stdlib.
try:
@@ -135,8 +140,10 @@ class BaseDefinition(object):
class Completion(BaseDefinition):
""" `Completion` objects are returned from `Script.complete`. Providing
some useful functions for IDE's. """
"""
`Completion` objects are returned from :meth:`api.Script.complete`. They
provide additional information about a completion.
"""
def __init__(self, name, needs_dot, like_name_length, base):
super(Completion, self).__init__(name.parent, name.start_pos)
@@ -149,11 +156,13 @@ class Completion(BaseDefinition):
@property
def complete(self):
""" Delievers the rest of the word, e.g. completing `isinstance`
>>> isinstan
"""
Return the rest of the word, e.g. completing ``isinstance``::
>>> isinstan# <-- Cursor is here
would return the string 'ce'. It also adds additional stuff, depending
on your `settings.py`
on your `settings.py`.
"""
dot = '.' if self.needs_dot else ''
append = ''
@@ -170,8 +179,10 @@ class Completion(BaseDefinition):
@property
def word(self):
""" In contrary to `complete` returns the whole word, e.g.
>>> isinstan
"""
Similar to :meth:`Completion.complete`, but return the whole word, e.g. ::
>>> isinstan
would return 'isinstance'.
"""
@@ -179,8 +190,11 @@ class Completion(BaseDefinition):
@property
def description(self):
""" Provides a description of the completion object
TODO return value is just __repr__ of some objects, improve! """
"""
Provide a description of the completion object.
.. todo:: return value is just __repr__ of some objects, improve!
"""
parent = self.name.parent
if parent is None:
return ''
@@ -194,12 +208,13 @@ class Completion(BaseDefinition):
return '%s: %s%s' % (t, desc, line_nr)
def follow_definition(self):
""" Returns you the original definitions. I strongly recommend not
using it for your completions, because it might slow down Jedi. If you
want to read only a few objects (<=20). I think it might be useful,
especially to get the original docstrings.
The basic problem of this function is that it follows all results. This
means with 1000 completions (e.g. numpy), it's just PITA slow.
"""
Return the original definitions. I strongly recommend not using it for
your completions, because it might slow down *Jedi*. If you want to read
only a few objects (<=20), it might be useful, especially to
get the original docstrings. The basic problem of this function is
that it follows all results. This means with 1000 completions (e.g.
numpy), it's just PITA-slow.
"""
if self._followed_definitions is None:
if self.definition.isinstance(parsing.Statement):
@@ -220,15 +235,19 @@ class Completion(BaseDefinition):
class Definition(BaseDefinition):
""" These are the objects returned by either `Script.goto` or
`Script.get_definition`. """
"""
*Definition* objects are returned from :meth:`api.Script.goto` or
:meth:`api.Script.get_definition`.
"""
def __init__(self, definition):
super(Definition, self).__init__(definition, definition.start_pos)
@property
def description(self):
""" A description of the Definition object, which is heavily used in
testing. e.g. for `isinstance` it returns 'def isinstance' """
"""
A description of the :class:`.Definition` object, which is heavily used
in testing. e.g. for ``isinstance`` it returns ``def isinstance``.
"""
d = self.definition
if isinstance(d, evaluate.InstanceElement):
d = d.var
@@ -252,10 +271,15 @@ class Definition(BaseDefinition):
@property
def desc_with_module(self):
""" In addition to the Definition, it also returns the module. Don't
use it yet, its behaviour may change. If you really need it, talk to me
TODO add full path. This function is should return a
module.class.function path. """
"""
In addition to the definition, also return the module.
.. warning:: Don't use this function yet, its behaviour may change. If
you really need it, talk to me.
.. todo:: Add full path. This function is should return a
`module.class.function` path.
"""
if self.module_path.endswith('.py') \
and not isinstance(self.definition, parsing.Module):
position = '@%s' % (self.line_nr)
@@ -266,6 +290,7 @@ class Definition(BaseDefinition):
class RelatedName(BaseDefinition):
"""TODO: document this"""
def __init__(self, name_part, scope):
super(RelatedName, self).__init__(scope, name_part.start_pos)
self.name_part = name_part