From 3f270c876d613b059a046a6d07171b66c8f3fe3f Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Mon, 17 Sep 2012 23:46:27 +0200 Subject: [PATCH 1/4] Converted README: markdown to rst (fixexs #13) --- README.mdown => README.rst | 145 ++++++++++++++++++++++--------------- 1 file changed, 88 insertions(+), 57 deletions(-) rename README.mdown => README.rst (62%) diff --git a/README.mdown b/README.rst similarity index 62% rename from README.mdown rename to README.rst index 52da3129..fb4a569e 100644 --- a/README.mdown +++ b/README.rst @@ -1,5 +1,6 @@ +###################################### Jedi - a clever Python auto-completion -============================ +###################################### **now in alpha testing phase** @@ -23,10 +24,11 @@ problems with licensing, just contact me. At the moment Jedi can be used as a **VIM-Plugin**. So, if you want to test Jedi for now, you'll have to use VIM. Just check the chapter on VIM bellow. -Get the latest from [github](http://github.com/davidhalter/jedi). +Get the latest from `github `_. + Support -------- +======= Jedi supports Python 2.5 up to 3.x. There is just one code base, for both Python 2 and 3. @@ -43,17 +45,17 @@ Jedi supports many of the widely used Python features: - descriptors -> property / staticmethod / classmethod - closures - generators (yield statement) / iterators - - support for some magic methods: `__call__`, `__iter__`, `__next__`, - `__get__`, `__getitem__`, `__init__` + - support for some magic methods: ``__call__``, ``__iter__``, ``__next__``, + ``__get__``, ``__getitem__``, ``__init__`` - support for list.append, set.add, list.extend, etc. - (nested) list comprehensions / ternary expressions - relative imports - - `getattr()` / `__getattr__` / `__getattribute__` + - ``getattr()`` / ``__getattr__`` / ``__getattribute__`` - function annotations (py3k feature, are ignored right now, but being parsed. I don't know what to do with them.) - class decorators (py3k feature, are being ignored too, until I find a use case, that doesn't work with Jedi) - - simple/usual `sys.path` modifications + - simple/usual ``sys.path`` modifications However, it does not yet support (and probably will in future versions, because they are on my todo list): @@ -69,28 +71,28 @@ It does not support (and most probably will not in future versions): - evaluate if / while Caveats -------- +======= This framework should work for both Python 2/3. However, some things were just not as *pythonic* in Python 2 as things should be. To keep things simple, some things have been held back: - - Classes: Always Python 3 like, therefore all classes inherit from `object`. - - Generators: No `next` method. The `__next__` method is used instead. - - Exceptions are only looked at in the form of `Exception as e`, no comma! + - Classes: Always Python 3 like, therefore all classes inherit from ``object``. + - Generators: No ``next`` method. The ``__next__`` method is used instead. + - Exceptions are only looked at in the form of ``Exception as e``, no comma! Syntax errors and other strange stuff, that is defined differently in the Python language, may lead to undefined behaviour of the completion. Jedi is **NOT** a Python compiler, that tries to correct you. It is a tool that wants to help you. But **YOU** have to know Python, not Jedi. -Importing `numpy` can be quite slow sometimes, as well as loading the builtins +Importing ``numpy`` can be quite slow sometimes, as well as loading the builtins the first time. If you want to speed it up, you could write import hooks in jedi, which preloads this stuff. However, once loaded, this is not a problem -anymore. The same is true for huge modules like `PySide`, `wx`, etc. +anymore. The same is true for huge modules like ``PySide``, ``wx``, etc. A little history ----------------- +================ The Star Wars Jedi are awesome. My Jedi software tries to imitate a little bit of the precognition the Jedi have. @@ -101,7 +103,7 @@ second name. After I explained Guido van Rossum, how some parts of my auto-completion work, he said (we drank a beer or two): -*Oh, that worries me* + *Oh, that worries me* When it's finished, I hope he'll like it :-) @@ -118,83 +120,110 @@ By the way, I really tried to program it as understandable as possible. But I think understanding it might need some time, because of its recursive nature. API-Design for IDEs -------------------- +=================== -If you want to set up an IDE with Jedi, you need to `import jedi`. You should +If you want to set up an IDE with Jedi, you need to ``import jedi``. You should have the following objects available: -`Script` -> Returns a script object, that contains the relevant information for the -> other functions to work without params. +:: -`Script().complete` -> Returns `api.Completion` objects. Those objects have got -> informations about the completions. More than just names. + `Script` -`Script().goto` -> Similar to complete. The returned `api.Definition` objects contain -> information about the definitions found. +Returns a script object, that contains the relevant information for the +other functions to work without params. -`Script().get_definition` -> Mostly used for tests. Like goto, but follows statements and imports and -> doesn't break there. You probably don't want to use this function. It's -> mostly for testing. +:: -`Script().related_names` -> Returns all names that point to the definition of the name under the -> cursor. This is also very useful for refactoring (renaming). + `Script().complete` -`Script().get_in_function_call` -> Get the `Function` object of the call you're currently in, e.g.: `abs(` -> with the cursor at the end would return the builtin `abs` function. +Returns ``api.Completion`` objects. Those objects have got +informations about the completions. More than just names. -`NotFoundError` -> If you use the goto function and no valid identifier (name) is at the -> place of the cursor (position). It will raise this exception. +:: -`set_debug_function` -> Sets a callback function for `debug.py`. This function is called with -> multiple text objects, in python 3 you could insert `print`. + `Script().goto` -`settings` -> Access to the `settings.py` module. The settings are described there. +Similar to complete. The returned ``api.Definition`` objects contain +information about the definitions found. + +:: + + `Script().get_definition` + +Mostly used for tests. Like goto, but follows statements and imports and +doesn't break there. You probably don't want to use this function. It's +mostly for testing. + +:: + + `Script().related_names` + +Returns all names that point to the definition of the name under the +cursor. This is also very useful for refactoring (renaming). + +:: + + `Script().get_in_function_call` + +Get the ``Function`` object of the call you're currently in, e.g.: ``abs(`` +with the cursor at the end would return the builtin ``abs`` function. + +:: + + `NotFoundError` + +If you use the goto function and no valid identifier (name) is at the +place of the cursor (position). It will raise this exception. + +:: + + `set_debug_function` + +Sets a callback function for ``debug.py``. This function is called with +multiple text objects, in python 3 you could insert ``print``. + +:: + + `settings` + +Access to the ``settings.py`` module. The settings are described there. VIM Plugin -------------------- +========== At the moment jedi is also a VIM plugin. It is some sort of reference implementation for other IDE's. -The VIM plugin is located under `plugin/jedi.vim`. +The VIM plugin is located under ``plugin/jedi.vim``. -You might want to use [pathogen](https://github.com/tpope/vim-pathogen) to +You might want to use `pathogen `_ to install jedi in VIM. Also you need a VIM version that was compiled with -`+python`, which is typical for most distributions on Linux. +``+python``, which is typical for most distributions on Linux. Jedi is automatically initialized. If you don't want that I suggest you -disable the auto-initialization in your `.vimrc`: +disable the auto-initialization in your ``.vimrc``: let g:jedi#auto_initialization = 0 -The autocompletion can be used with \, if you want it to work with -\ you can use [supertab](https://github.com/ervandew/supertab). -The goto is by default on \. If you want to change that: +The autocompletion can be used with , if you want it to work with + you can use `supertab `_. +The goto is by default on . If you want to change that: let g:jedi#goto_command = "g" -`get_definition` is by default on \. If you want to change that: +``get_definition`` is by default on . If you want to change that: let g:jedi#get_definition_command = "d" -Showing the pydoc is by default on `K` If you want to change that: +Showing the pydoc is by default on ``K`` If you want to change that: let g:jedi#pydoc = "K" If you are a person who likes to use VIM-buffers not tabs, you might want to -put that in your `.vimrc`: +put that in your ``.vimrc``: let g:jedi#use_tabs_not_buffers = 0 -Jedi automatically starts the completion, if you type a dot, e.g. `str.`, if +Jedi automatically starts the completion, if you type a dot, e.g. ``str.``, if you don't want this: let g:jedi#popup_on_dot = 0 @@ -207,4 +236,6 @@ And you can list all names that are related (have the same origin): let g:jedi#related_names_command = "n" -[![Build Status](https://secure.travis-ci.org/davidhalter/jedi.png?branch=master)](http://travis-ci.org/davidhalter/jedi) +.. image:: https://secure.travis-ci.org/davidhalter/jedi.png?branch=master + :target: http://travis-ci.org/davidhalter/jedi + :alt: Travis-CI build status From 5ce9946fdb0edf9e1a8627f1de121776f0480a13 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Mon, 17 Sep 2012 23:46:46 +0200 Subject: [PATCH 2/4] Updated .gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 9c2d5b80..bc5e08fc 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,6 @@ *.swo .ropeproject *.pyc +/build/ +/dist/ +jedi.egg-info/ From bed7c3ff748feb05d02e5dc9ab207600d90dad9b Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Mon, 17 Sep 2012 23:52:31 +0200 Subject: [PATCH 3/4] Some README fixes --- README.rst | 113 ++++++++++++++++++++++++++++------------------------- 1 file changed, 59 insertions(+), 54 deletions(-) diff --git a/README.rst b/README.rst index fb4a569e..099cd4da 100644 --- a/README.rst +++ b/README.rst @@ -2,6 +2,10 @@ Jedi - a clever Python auto-completion ###################################### +.. image:: https://secure.travis-ci.org/davidhalter/jedi.png?branch=master + :target: http://travis-ci.org/davidhalter/jedi + :alt: Travis-CI build status + **now in alpha testing phase** *If you have any comments or feature request, please tell me! I really want to @@ -34,41 +38,43 @@ Jedi supports Python 2.5 up to 3.x. There is just one code base, for both Python 2 and 3. Jedi supports many of the widely used Python features: - - builtin functions/classes support - - complex module / function / class structures - - ignores syntax and indentation errors - - multiple returns / yields - - tuple assignments / array indexing / dictionary indexing - - exceptions / with-statement - - \*args / \*\*kwargs - - decorators - - descriptors -> property / staticmethod / classmethod - - closures - - generators (yield statement) / iterators - - support for some magic methods: ``__call__``, ``__iter__``, ``__next__``, - ``__get__``, ``__getitem__``, ``__init__`` - - support for list.append, set.add, list.extend, etc. - - (nested) list comprehensions / ternary expressions - - relative imports - - ``getattr()`` / ``__getattr__`` / ``__getattribute__`` - - function annotations (py3k feature, are ignored right now, but being parsed. - I don't know what to do with them.) - - class decorators (py3k feature, are being ignored too, until I find a use - case, that doesn't work with Jedi) - - simple/usual ``sys.path`` modifications +- builtin functions/classes support +- complex module / function / class structures +- ignores syntax and indentation errors +- multiple returns / yields +- tuple assignments / array indexing / dictionary indexing +- exceptions / with-statement +- \*args / \*\*kwargs +- decorators +- descriptors -> property / staticmethod / classmethod +- closures +- generators (yield statement) / iterators +- support for some magic methods: ``__call__``, ``__iter__``, ``__next__``, + ``__get__``, ``__getitem__``, ``__init__`` +- support for list.append, set.add, list.extend, etc. +- (nested) list comprehensions / ternary expressions +- relative imports +- ``getattr()`` / ``__getattr__`` / ``__getattribute__`` +- function annotations (py3k feature, are ignored right now, but being parsed. + I don't know what to do with them.) +- class decorators (py3k feature, are being ignored too, until I find a use + case, that doesn't work with Jedi) +- simple/usual ``sys.path`` modifications However, it does not yet support (and probably will in future versions, because they are on my todo list): - - assert / isinstance - - manipulations of instances outside the instance variables, without using - functions - - operation support -> \_\_mul\_\_, \_\_add\_\_, etc. +- assert / isinstance +- manipulations of instances outside the instance variables, without using + functions +- operation support -> ``__mul__``, ``__add__``, etc. It does not support (and most probably will not in future versions): - - metaclasses (how could an auto-completion ever support this) - - setattr() - - evaluate if / while + +- metaclasses (how could an auto-completion ever support this) +- ``setattr()`` +- evaluate ``if`` / ``while`` + Caveats ======= @@ -77,9 +83,9 @@ This framework should work for both Python 2/3. However, some things were just not as *pythonic* in Python 2 as things should be. To keep things simple, some things have been held back: - - Classes: Always Python 3 like, therefore all classes inherit from ``object``. - - Generators: No ``next`` method. The ``__next__`` method is used instead. - - Exceptions are only looked at in the form of ``Exception as e``, no comma! +- Classes: Always Python 3 like, therefore all classes inherit from ``object``. +- Generators: No ``next`` method. The ``__next__`` method is used instead. +- Exceptions are only looked at in the form of ``Exception as e``, no comma! Syntax errors and other strange stuff, that is defined differently in the Python language, may lead to undefined behaviour of the completion. Jedi is @@ -91,6 +97,7 @@ the first time. If you want to speed it up, you could write import hooks in jedi, which preloads this stuff. However, once loaded, this is not a problem anymore. The same is true for huge modules like ``PySide``, ``wx``, etc. + A little history ================ @@ -119,6 +126,7 @@ many of Python's key features. By the way, I really tried to program it as understandable as possible. But I think understanding it might need some time, because of its recursive nature. + API-Design for IDEs =================== @@ -127,28 +135,28 @@ have the following objects available: :: - `Script` + Script Returns a script object, that contains the relevant information for the other functions to work without params. :: - `Script().complete` + Script().complete Returns ``api.Completion`` objects. Those objects have got informations about the completions. More than just names. :: - `Script().goto` + Script().goto Similar to complete. The returned ``api.Definition`` objects contain information about the definitions found. :: - `Script().get_definition` + Script().get_definition Mostly used for tests. Like goto, but follows statements and imports and doesn't break there. You probably don't want to use this function. It's @@ -156,38 +164,39 @@ mostly for testing. :: - `Script().related_names` + Script().related_names Returns all names that point to the definition of the name under the cursor. This is also very useful for refactoring (renaming). :: - `Script().get_in_function_call` + Script().get_in_function_call Get the ``Function`` object of the call you're currently in, e.g.: ``abs(`` with the cursor at the end would return the builtin ``abs`` function. :: - `NotFoundError` + NotFoundError If you use the goto function and no valid identifier (name) is at the place of the cursor (position). It will raise this exception. :: - `set_debug_function` + set_debug_function Sets a callback function for ``debug.py``. This function is called with multiple text objects, in python 3 you could insert ``print``. :: - `settings` + settings Access to the ``settings.py`` module. The settings are described there. + VIM Plugin ========== @@ -200,42 +209,38 @@ install jedi in VIM. Also you need a VIM version that was compiled with ``+python``, which is typical for most distributions on Linux. Jedi is automatically initialized. If you don't want that I suggest you -disable the auto-initialization in your ``.vimrc``: +disable the auto-initialization in your ``.vimrc``:: let g:jedi#auto_initialization = 0 The autocompletion can be used with , if you want it to work with you can use `supertab `_. -The goto is by default on . If you want to change that: +The goto is by default on . If you want to change that:: let g:jedi#goto_command = "g" -``get_definition`` is by default on . If you want to change that: +``get_definition`` is by default on . If you want to change that:: let g:jedi#get_definition_command = "d" -Showing the pydoc is by default on ``K`` If you want to change that: +Showing the pydoc is by default on ``K`` If you want to change that:: let g:jedi#pydoc = "K" If you are a person who likes to use VIM-buffers not tabs, you might want to -put that in your ``.vimrc``: +put that in your ``.vimrc``:: let g:jedi#use_tabs_not_buffers = 0 Jedi automatically starts the completion, if you type a dot, e.g. ``str.``, if -you don't want this: +you don't want this:: let g:jedi#popup_on_dot = 0 -There's some support for refactoring: +There's some support for refactoring:: let g:jedi#rename_command = "r" -And you can list all names that are related (have the same origin): +And you can list all names that are related (have the same origin):: + let g:jedi#related_names_command = "n" - - -.. image:: https://secure.travis-ci.org/davidhalter/jedi.png?branch=master - :target: http://travis-ci.org/davidhalter/jedi - :alt: Travis-CI build status From 95a059398e533bad2e591637d02ea1a3925411e2 Mon Sep 17 00:00:00 2001 From: Danilo Bargen Date: Mon, 17 Sep 2012 23:55:07 +0200 Subject: [PATCH 4/4] Fixed README path in MANIFEST.in, set README as long description in setup.py --- MANIFEST.in | 2 +- setup.py | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/MANIFEST.in b/MANIFEST.in index 12d70a52..99357d3d 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include README.mdown +include README.rst include LICENSE.txt include AUTHORS.txt recursive-exclude * *.pyc diff --git a/setup.py b/setup.py index 13d6bd76..78e4ff80 100644 --- a/setup.py +++ b/setup.py @@ -5,6 +5,8 @@ from setuptools import setup __AUTHOR__ = 'David Halter' __AUTHOR_EMAIL__ = 'davidhalter88@gmail.com' +readme = open('README.rst').read() + setup(name='jedi', version='0.5.0-beta', description='An autocompletion tool for Python that can be used from text editors like vim.', @@ -15,6 +17,7 @@ setup(name='jedi', url='https://github.com/davidhalter/jedi', license='LGPLv3', keywords='python completion refactoring vim', + long_description=readme, packages=['jedi'], platforms=['any'], classifiers=[