forked from VimPlug/jedi
Move recipes to Jedi Usage
This commit is contained in:
Dave Halter
@@ -109,130 +109,6 @@ This is intentional: Most people trust the code bases they have imported,
|
||||
because at that point a malicious code base would have had code execution
|
||||
already.
|
||||
|
||||
Recipes
|
||||
-------
|
||||
|
||||
Here are some tips on how to use |jedi| efficiently.
|
||||
|
||||
|
||||
.. _type-hinting:
|
||||
|
||||
Type Hinting
|
||||
~~~~~~~~~~~~
|
||||
|
||||
If |jedi| cannot detect the type of a function argument correctly (due to the
|
||||
dynamic nature of Python), you can help it by hinting the type using
|
||||
one of the docstring/annotation styles below. **Only gradual typing will
|
||||
always work**, all the docstring solutions are glorified hacks and more
|
||||
complicated cases will probably not work.
|
||||
|
||||
Official Gradual Typing (Recommended)
|
||||
+++++++++++++++++++++++++++++++++++++
|
||||
|
||||
You can read a lot about Python's gradual typing system in the corresponding
|
||||
PEPs like:
|
||||
|
||||
- `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ as an introduction
|
||||
- `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ for variable annotations
|
||||
- `PEP 589 <https://www.python.org/dev/peps/pep-0589/>`_ for ``TypeDict``
|
||||
- There are probably more :)
|
||||
|
||||
Below you can find a few examples how you can use this feature.
|
||||
|
||||
Function annotations::
|
||||
|
||||
def myfunction(node: ProgramNode, foo: str) -> None:
|
||||
"""Do something with a ``node``.
|
||||
|
||||
"""
|
||||
node.| # complete here
|
||||
|
||||
|
||||
Assignment, for-loop and with-statement type hints::
|
||||
|
||||
import typing
|
||||
x: int = foo()
|
||||
y: typing.Optional[int] = 3
|
||||
|
||||
key: str
|
||||
value: Employee
|
||||
for key, value in foo.items():
|
||||
pass
|
||||
|
||||
f: Union[int, float]
|
||||
with foo() as f:
|
||||
print(f + 3)
|
||||
|
||||
PEP-0484 should be supported in its entirety. Feel free to open issues if that
|
||||
is not the case. You can also use stub files.
|
||||
|
||||
|
||||
Sphinx style
|
||||
++++++++++++
|
||||
|
||||
http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists
|
||||
|
||||
::
|
||||
|
||||
def myfunction(node, foo):
|
||||
"""
|
||||
Do something with a ``node``.
|
||||
|
||||
:type node: ProgramNode
|
||||
:param str foo: foo parameter description
|
||||
"""
|
||||
node.| # complete here
|
||||
|
||||
Epydoc
|
||||
++++++
|
||||
|
||||
http://epydoc.sourceforge.net/manual-fields.html
|
||||
|
||||
::
|
||||
|
||||
def myfunction(node):
|
||||
"""
|
||||
Do something with a ``node``.
|
||||
|
||||
@type node: ProgramNode
|
||||
"""
|
||||
node.| # complete here
|
||||
|
||||
Numpydoc
|
||||
++++++++
|
||||
|
||||
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
|
||||
|
||||
In order to support the numpydoc format, you need to install the `numpydoc
|
||||
<https://pypi.python.org/pypi/numpydoc>`__ package.
|
||||
|
||||
::
|
||||
|
||||
def foo(var1, var2, long_var_name='hi'):
|
||||
r"""
|
||||
A one-line summary that does not use variable names or the
|
||||
function name.
|
||||
|
||||
...
|
||||
|
||||
Parameters
|
||||
----------
|
||||
var1 : array_like
|
||||
Array_like means all those objects -- lists, nested lists,
|
||||
etc. -- that can be converted to an array. We can also
|
||||
refer to variables like `var1`.
|
||||
var2 : int
|
||||
The type above can either refer to an actual Python type
|
||||
(e.g. ``int``), or describe the type of the variable in more
|
||||
detail, e.g. ``(N,) ndarray`` or ``array_like``.
|
||||
long_variable_name : {'hi', 'ho'}, optional
|
||||
Choices in brackets, default first when optional.
|
||||
|
||||
...
|
||||
|
||||
"""
|
||||
var2.| # complete here
|
||||
|
||||
A little bit of history
|
||||
-----------------------
|
||||
|
||||
|
||||
@@ -1,11 +1,13 @@
|
||||
.. include:: ../global.rst
|
||||
|
||||
End User Usage
|
||||
==============
|
||||
Using Jedi
|
||||
==========
|
||||
|
||||
|jedi| is can be used in a variety of plugins and software. It is also possible
|
||||
|jedi| is can be used with a variety of plugins and software. It is also possible
|
||||
to use |jedi| in the :ref:`Python shell or with IPython <repl-completion>`.
|
||||
|
||||
Below you can also find a list of :ref:`recipes for type hinting <recipes>`.
|
||||
|
||||
|
||||
.. _editor-plugins:
|
||||
|
||||
@@ -105,6 +107,132 @@ Using a Custom ``$HOME/.pythonrc.py``
|
||||
|
||||
.. autofunction:: jedi.utils.setup_readline
|
||||
|
||||
.. _recipes:
|
||||
|
||||
Recipes
|
||||
-------
|
||||
|
||||
Here are some tips on how to use |jedi| efficiently.
|
||||
|
||||
|
||||
.. _type-hinting:
|
||||
|
||||
Type Hinting
|
||||
~~~~~~~~~~~~
|
||||
|
||||
If |jedi| cannot detect the type of a function argument correctly (due to the
|
||||
dynamic nature of Python), you can help it by hinting the type using
|
||||
one of the docstring/annotation styles below. **Only gradual typing will
|
||||
always work**, all the docstring solutions are glorified hacks and more
|
||||
complicated cases will probably not work.
|
||||
|
||||
Official Gradual Typing (Recommended)
|
||||
+++++++++++++++++++++++++++++++++++++
|
||||
|
||||
You can read a lot about Python's gradual typing system in the corresponding
|
||||
PEPs like:
|
||||
|
||||
- `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ as an introduction
|
||||
- `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ for variable annotations
|
||||
- `PEP 589 <https://www.python.org/dev/peps/pep-0589/>`_ for ``TypeDict``
|
||||
- There are probably more :)
|
||||
|
||||
Below you can find a few examples how you can use this feature.
|
||||
|
||||
Function annotations::
|
||||
|
||||
def myfunction(node: ProgramNode, foo: str) -> None:
|
||||
"""Do something with a ``node``.
|
||||
|
||||
"""
|
||||
node.| # complete here
|
||||
|
||||
|
||||
Assignment, for-loop and with-statement type hints::
|
||||
|
||||
import typing
|
||||
x: int = foo()
|
||||
y: typing.Optional[int] = 3
|
||||
|
||||
key: str
|
||||
value: Employee
|
||||
for key, value in foo.items():
|
||||
pass
|
||||
|
||||
f: Union[int, float]
|
||||
with foo() as f:
|
||||
print(f + 3)
|
||||
|
||||
PEP-0484 should be supported in its entirety. Feel free to open issues if that
|
||||
is not the case. You can also use stub files.
|
||||
|
||||
|
||||
Sphinx style
|
||||
++++++++++++
|
||||
|
||||
http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists
|
||||
|
||||
::
|
||||
|
||||
def myfunction(node, foo):
|
||||
"""
|
||||
Do something with a ``node``.
|
||||
|
||||
:type node: ProgramNode
|
||||
:param str foo: foo parameter description
|
||||
"""
|
||||
node.| # complete here
|
||||
|
||||
Epydoc
|
||||
++++++
|
||||
|
||||
http://epydoc.sourceforge.net/manual-fields.html
|
||||
|
||||
::
|
||||
|
||||
def myfunction(node):
|
||||
"""
|
||||
Do something with a ``node``.
|
||||
|
||||
@type node: ProgramNode
|
||||
"""
|
||||
node.| # complete here
|
||||
|
||||
Numpydoc
|
||||
++++++++
|
||||
|
||||
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
|
||||
|
||||
In order to support the numpydoc format, you need to install the `numpydoc
|
||||
<https://pypi.python.org/pypi/numpydoc>`__ package.
|
||||
|
||||
::
|
||||
|
||||
def foo(var1, var2, long_var_name='hi'):
|
||||
r"""
|
||||
A one-line summary that does not use variable names or the
|
||||
function name.
|
||||
|
||||
...
|
||||
|
||||
Parameters
|
||||
----------
|
||||
var1 : array_like
|
||||
Array_like means all those objects -- lists, nested lists,
|
||||
etc. -- that can be converted to an array. We can also
|
||||
refer to variables like `var1`.
|
||||
var2 : int
|
||||
The type above can either refer to an actual Python type
|
||||
(e.g. ``int``), or describe the type of the variable in more
|
||||
detail, e.g. ``(N,) ndarray`` or ``array_like``.
|
||||
long_variable_name : {'hi', 'ho'}, optional
|
||||
Choices in brackets, default first when optional.
|
||||
|
||||
...
|
||||
|
||||
"""
|
||||
var2.| # complete here
|
||||
|
||||
.. _jedi-vim: https://github.com/davidhalter/jedi-vim
|
||||
.. _youcompleteme: https://valloric.github.io/YouCompleteMe/
|
||||
.. _deoplete-jedi: https://github.com/zchee/deoplete-jedi
|
||||
|
||||
Reference in New Issue
Block a user