diff --git a/.gitignore b/.gitignore index 6a44ebf4..1f303fe4 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,6 @@ .ropeproject *.pyc /build/ -/docs/build/ +/docs/_build/ /dist/ jedi.egg-info/ diff --git a/README.rst b/README.rst index b00267a0..9ebc551c 100644 --- a/README.rst +++ b/README.rst @@ -29,15 +29,15 @@ Jedi for now, you'll have to use VIM. But there are new plugins emerging: Here are some pictures: -.. image:: https://github.com/davidhalter/jedi/raw/master/docs/source/screenshot_complete.png +.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_complete.png Completion for almost anything (Ctrl+Space). -.. image:: https://github.com/davidhalter/jedi/raw/master/docs/source/screenshot_function.png +.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_function.png Display of function/class bodies, docstrings. -.. image:: https://github.com/davidhalter/jedi/raw/master/docs/source/screenshot_pydoc.png +.. image:: https://github.com/davidhalter/jedi/raw/master/docs/_screenshots/screenshot_pydoc.png Pydoc support (with highlighting, Shift+k). @@ -47,8 +47,7 @@ Get the latest version from `github `_ (master branch should always be kind of stable/working). Docs are available at `https://jedi.readthedocs.org/ -`_. Pull requests with documentation -nhancements +`_. Pull requests with documentation enhancements and/or fixes are awesome and most welcome. Jedi uses `semantic versioning `_ starting with version @@ -57,100 +56,17 @@ Jedi uses `semantic versioning `_ starting with version Installation ============ -You can either include Jedi as a submodule in your text editor plugin (like -jedi-vim_ does it by default), or you -can install Jedi systemwide. - -The preferred way to install the Jedi library into your system is by using -pip_:: - - sudo pip install jedi - -If you want to install the current development version:: - - sudo pip install -e git://github.com/davidhalter/jedi.git#egg=jedi +See https://jedi.readthedocs.org/en/latest/docs/installation.html Note: This just installs the Jedi library, not the editor plugins. For information about how to make it work with your editor, refer to the corresponding documentation. -Support -======= +Feature Support and Caveats +=========================== -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 -- with-statement / exceptions -- \*args / \*\*kwargs -- decorators / lambdas / closures -- descriptors -> property / staticmethod / classmethod -- 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 -- ``isinstance`` checks for if/while/assert -- virtualenv support -- infer function arguments with sphinx (and other) docstrings - -However, it does not yet support (and probably will in future versions, because -they are on my todo list): - -- manipulations of instances outside the instance variables, without using - functions - -It does not support (and most probably will not in future versions): - -- metaclasses (how could an auto-completion ever support this) -- ``setattr()``, ``__import__()`` -- Writing to some dicts: ``globals()``, ``locals()``, ``object.__dict__`` -- 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! - -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 -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. - -Security is an important issue for Jedi. Therefore no Python code is executed. -As long as you write pure python, everything is evaluated statically. But: If -you use builtin modules (`c_builtin`) there is no other option than to execute -those modules. However: Execute isn't that critical (as e.g. in pythoncomplete, -which used to execute *every* import!), because it means one import and no -more. So basically the only dangerous thing is using the import itself. If your -`c_builtin` uses some strange initializations, it might be dangerous. But if it -does you're screwed anyways, because eventualy you're going to execute your -code, which executes the import. +See https://jedi.readthedocs.org/en/latest/docs/features.html A little history @@ -184,82 +100,9 @@ think understanding it might need quite some time, because of its recursive nature. -API-Design for IDEs -=================== +API for IDEs +============ -If you want to set up an IDE with Jedi, you need to ``import jedi``. You should -have the following objects available: - -:: - - Script(source, line, column, source_path) - -``source`` would be the source of your python file/script, separated by new -lines. ``line`` is the current line you want to perform actions on (starting -with line #1 as the first line). ``column`` represents the current -column/indent of the cursor (starting with zero). ``source_path`` should be the -path of your file in the file system. - -It 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().goto - -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. - - - -.. _jedi-vim: http://github.com/davidhalter/jedi-vim -.. _pip: http://www.pip-installer.org/ +It's very easy to create an editor plugin that uses Jedi. See +https://jedi.readthedocs.org/en/latest/docs/plugin-api.html for more +information. diff --git a/docs/Makefile b/docs/Makefile index 62c5845a..14cfdf4b 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,14 +5,14 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = build +BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext diff --git a/docs/source/screenshot_complete.png b/docs/_screenshots/screenshot_complete.png similarity index 100% rename from docs/source/screenshot_complete.png rename to docs/_screenshots/screenshot_complete.png diff --git a/docs/source/screenshot_function.png b/docs/_screenshots/screenshot_function.png similarity index 100% rename from docs/source/screenshot_function.png rename to docs/_screenshots/screenshot_function.png diff --git a/docs/source/screenshot_pydoc.png b/docs/_screenshots/screenshot_pydoc.png similarity index 100% rename from docs/source/screenshot_pydoc.png rename to docs/_screenshots/screenshot_pydoc.png diff --git a/docs/_static/logo.png b/docs/_static/logo.png new file mode 100644 index 00000000..f56374e3 Binary files /dev/null and b/docs/_static/logo.png differ diff --git a/docs/_templates/ghbuttons.html b/docs/_templates/ghbuttons.html new file mode 100644 index 00000000..badb06af --- /dev/null +++ b/docs/_templates/ghbuttons.html @@ -0,0 +1,4 @@ +

Github

+ +

diff --git a/docs/_templates/sidebarlogo.html b/docs/_templates/sidebarlogo.html new file mode 100644 index 00000000..d9243c4e --- /dev/null +++ b/docs/_templates/sidebarlogo.html @@ -0,0 +1,3 @@ + diff --git a/docs/_themes/flask/LICENSE b/docs/_themes/flask/LICENSE new file mode 100644 index 00000000..8daab7ee --- /dev/null +++ b/docs/_themes/flask/LICENSE @@ -0,0 +1,37 @@ +Copyright (c) 2010 by Armin Ronacher. + +Some rights reserved. + +Redistribution and use in source and binary forms of the theme, with or +without modification, are permitted provided that the following conditions +are met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + +* The names of the contributors may not be used to endorse or + promote products derived from this software without specific + prior written permission. + +We kindly ask you to only use these themes in an unmodified manner just +for Flask and Flask-related products, not for unrelated projects. If you +like the visual style and want to use it for your own projects, please +consider making some larger changes to the themes (such as changing +font faces, sizes, colors or margins). + +THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/docs/_themes/flask/layout.html b/docs/_themes/flask/layout.html new file mode 100644 index 00000000..e781a119 --- /dev/null +++ b/docs/_themes/flask/layout.html @@ -0,0 +1,28 @@ +{%- extends "basic/layout.html" %} +{%- block extrahead %} + {{ super() }} + {% if theme_touch_icon %} + + {% endif %} + + + Fork me on GitHub + +{% endblock %} +{%- block relbar2 %}{% endblock %} +{% block header %} + {{ super() }} + {% if pagename == 'index' %} +
+ {% endif %} +{% endblock %} +{%- block footer %} +
+ © Copyright {{ copyright }}. + Created using Sphinx. +
+ {% if pagename == 'index' %} +
+ {% endif %} +{%- endblock %} diff --git a/docs/_themes/flask/relations.html b/docs/_themes/flask/relations.html new file mode 100644 index 00000000..3bbcde85 --- /dev/null +++ b/docs/_themes/flask/relations.html @@ -0,0 +1,19 @@ +

Related Topics

+ diff --git a/docs/_themes/flask/static/flasky.css_t b/docs/_themes/flask/static/flasky.css_t new file mode 100644 index 00000000..79ab4787 --- /dev/null +++ b/docs/_themes/flask/static/flasky.css_t @@ -0,0 +1,394 @@ +/* + * flasky.css_t + * ~~~~~~~~~~~~ + * + * :copyright: Copyright 2010 by Armin Ronacher. + * :license: Flask Design License, see LICENSE for details. + */ + +{% set page_width = '940px' %} +{% set sidebar_width = '220px' %} + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'Georgia', serif; + font-size: 17px; + background-color: white; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + width: {{ page_width }}; + margin: 30px auto 0 auto; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 {{ sidebar_width }}; +} + +div.sphinxsidebar { + width: {{ sidebar_width }}; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 0 30px; +} + +img.floatingflask { + padding: 0 0 10px 10px; + float: right; +} + +div.footer { + width: {{ page_width }}; + margin: 20px auto 30px auto; + font-size: 14px; + color: #888; + text-align: right; +} + +div.footer a { + color: #888; +} + +div.related { + display: none; +} + +div.sphinxsidebar a { + color: #444; + text-decoration: none; + border-bottom: 1px dotted #999; +} + +div.sphinxsidebar a:hover { + border-bottom: 1px solid #999; +} + +div.sphinxsidebar { + font-size: 14px; + line-height: 1.5; +} + +div.sphinxsidebarwrapper { + padding: 18px 10px; +} + +div.sphinxsidebarwrapper p.logo { + padding: 0 0 20px 0; + margin: 0; + text-align: center; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: 'Garamond', 'Georgia', serif; + color: #444; + font-size: 24px; + font-weight: normal; + margin: 0 0 5px 0; + padding: 0; +} + +div.sphinxsidebar h4 { + font-size: 20px; +} + +div.sphinxsidebar h3 a { + color: #444; +} + +div.sphinxsidebar p.logo a, +div.sphinxsidebar h3 a, +div.sphinxsidebar p.logo a:hover, +div.sphinxsidebar h3 a:hover { + border: none; +} + +div.sphinxsidebar p { + color: #555; + margin: 10px 0; +} + +div.sphinxsidebar ul { + margin: 10px 0; + padding: 0; + color: #000; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: 'Georgia', serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #004B6B; + text-decoration: underline; +} + +a:hover { + color: #6D4100; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + margin: 30px 0px 10px 0px; + padding: 0; +} + +{% if theme_index_logo %} +div.indexwrapper h1 { + text-indent: -999999px; + background: url({{ theme_index_logo }}) no-repeat center center; + height: {{ theme_index_logo_height }}; +} +{% endif %} + +div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; } +div.body h2 { font-size: 180%; } +div.body h3 { font-size: 150%; } +div.body h4 { font-size: 130%; } +div.body h5 { font-size: 100%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #ddd; + padding: 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + color: #444; +} + +div.body p, div.body dd, div.body li { + line-height: 1.4em; +} + +div.admonition { + background: #fafafa; + margin: 20px -30px; + padding: 10px 30px; + border-top: 1px solid #ccc; + border-bottom: 1px solid #ccc; +} + +div.admonition tt.xref, div.admonition a tt { + border-bottom: 1px solid #fafafa; +} + +dd div.admonition { + margin-left: -60px; + padding-left: 60px; +} + +div.admonition p.admonition-title { + font-family: 'Garamond', 'Georgia', serif; + font-weight: normal; + font-size: 24px; + margin: 0 0 10px 0; + padding: 0; + line-height: 1; +} + +div.admonition p.last { + margin-bottom: 0; +} + +div.highlight { + background-color: white; +} + +dt:target, .highlight { + background: #FAF3E8; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre, tt { + font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; + font-size: 0.9em; +} + +img.screenshot { +} + +tt.descname, tt.descclassname { + font-size: 0.95em; +} + +tt.descname { + padding-right: 0.08em; +} + +img.screenshot { + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils { + border: 1px solid #888; + -moz-box-shadow: 2px 2px 4px #eee; + -webkit-box-shadow: 2px 2px 4px #eee; + box-shadow: 2px 2px 4px #eee; +} + +table.docutils td, table.docutils th { + border: 1px solid #888; + padding: 0.25em 0.7em; +} + +table.field-list, table.footnote { + border: none; + -moz-box-shadow: none; + -webkit-box-shadow: none; + box-shadow: none; +} + +table.footnote { + margin: 15px 0; + width: 100%; + border: 1px solid #eee; + background: #fdfdfd; + font-size: 0.9em; +} + +table.footnote + table.footnote { + margin-top: -15px; + border-top: none; +} + +table.field-list th { + padding: 0 0.8em 0 0; +} + +table.field-list td { + padding: 0; +} + +table.footnote td.label { + width: 0px; + padding: 0.3em 0 0.3em 0.5em; +} + +table.footnote td { + padding: 0.3em 0.5em; +} + +dl { + margin: 0; + padding: 0; +} + +dl dd { + margin-left: 30px; +} + +blockquote { + margin: 0 0 0 30px; + padding: 0; +} + +ul, ol { + margin: 10px 0 10px 30px; + padding: 0; +} + +pre { + background: #eee; + padding: 7px 30px; + margin: 15px -30px; + line-height: 1.3em; +} + +dl pre, blockquote pre, li pre { + margin-left: -60px; + padding-left: 60px; +} + +dl dl pre { + margin-left: -90px; + padding-left: 90px; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ +} + +tt.xref, a tt { + background-color: #FBFBFB; + border-bottom: 1px solid white; +} + +a.reference { + text-decoration: none; + border-bottom: 1px dotted #004B6B; +} + +a.reference:hover { + border-bottom: 1px solid #6D4100; +} + +a.footnote-reference { + text-decoration: none; + font-size: 0.7em; + vertical-align: top; + border-bottom: 1px dotted #004B6B; +} + +a.footnote-reference:hover { + border-bottom: 1px solid #6D4100; +} + +a:hover tt { + background: #EEE; +} diff --git a/docs/_themes/flask/static/small_flask.css b/docs/_themes/flask/static/small_flask.css new file mode 100644 index 00000000..1c6df309 --- /dev/null +++ b/docs/_themes/flask/static/small_flask.css @@ -0,0 +1,70 @@ +/* + * small_flask.css_t + * ~~~~~~~~~~~~~~~~~ + * + * :copyright: Copyright 2010 by Armin Ronacher. + * :license: Flask Design License, see LICENSE for details. + */ + +body { + margin: 0; + padding: 20px 30px; +} + +div.documentwrapper { + float: none; + background: white; +} + +div.sphinxsidebar { + display: block; + float: none; + width: 102.5%; + margin: 50px -30px -20px -30px; + padding: 10px 20px; + background: #333; + color: white; +} + +div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, +div.sphinxsidebar h3 a { + color: white; +} + +div.sphinxsidebar a { + color: #aaa; +} + +div.sphinxsidebar p.logo { + display: none; +} + +div.document { + width: 100%; + margin: 0; +} + +div.related { + display: block; + margin: 0; + padding: 10px 0 20px 0; +} + +div.related ul, +div.related ul li { + margin: 0; + padding: 0; +} + +div.footer { + display: none; +} + +div.bodywrapper { + margin: 0; +} + +div.body { + min-height: 0; + padding: 0; +} diff --git a/docs/_themes/flask/theme.conf b/docs/_themes/flask/theme.conf new file mode 100644 index 00000000..1d5657f2 --- /dev/null +++ b/docs/_themes/flask/theme.conf @@ -0,0 +1,9 @@ +[theme] +inherit = basic +stylesheet = flasky.css +pygments_style = flask_theme_support.FlaskyStyle + +[options] +index_logo = +index_logo_height = 120px +touch_icon = diff --git a/docs/_themes/flask_theme_support.py b/docs/_themes/flask_theme_support.py new file mode 100644 index 00000000..d3e33c06 --- /dev/null +++ b/docs/_themes/flask_theme_support.py @@ -0,0 +1,125 @@ +""" +Copyright (c) 2010 by Armin Ronacher. + +Some rights reserved. + +Redistribution and use in source and binary forms of the theme, with or +without modification, are permitted provided that the following conditions +are met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + +* The names of the contributors may not be used to endorse or + promote products derived from this software without specific + prior written permission. + +We kindly ask you to only use these themes in an unmodified manner just +for Flask and Flask-related products, not for unrelated projects. If you +like the visual style and want to use it for your own projects, please +consider making some larger changes to the themes (such as changing +font faces, sizes, colors or margins). + +THIS THEME IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS THEME, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. +""" +# flasky extensions. flasky pygments style based on tango style +from pygments.style import Style +from pygments.token import Keyword, Name, Comment, String, Error, \ + Number, Operator, Generic, Whitespace, Punctuation, Other, Literal + + +class FlaskyStyle(Style): + background_color = "#f8f8f8" + default_style = "" + + styles = { + # No corresponding class for the following: + #Text: "", # class: '' + Whitespace: "underline #f8f8f8", # class: 'w' + Error: "#a40000 border:#ef2929", # class: 'err' + Other: "#000000", # class 'x' + + Comment: "italic #8f5902", # class: 'c' + Comment.Preproc: "noitalic", # class: 'cp' + + Keyword: "bold #004461", # class: 'k' + Keyword.Constant: "bold #004461", # class: 'kc' + Keyword.Declaration: "bold #004461", # class: 'kd' + Keyword.Namespace: "bold #004461", # class: 'kn' + Keyword.Pseudo: "bold #004461", # class: 'kp' + Keyword.Reserved: "bold #004461", # class: 'kr' + Keyword.Type: "bold #004461", # class: 'kt' + + Operator: "#582800", # class: 'o' + Operator.Word: "bold #004461", # class: 'ow' - like keywords + + Punctuation: "bold #000000", # class: 'p' + + # because special names such as Name.Class, Name.Function, etc. + # are not recognized as such later in the parsing, we choose them + # to look the same as ordinary variables. + Name: "#000000", # class: 'n' + Name.Attribute: "#c4a000", # class: 'na' - to be revised + Name.Builtin: "#004461", # class: 'nb' + Name.Builtin.Pseudo: "#3465a4", # class: 'bp' + Name.Class: "#000000", # class: 'nc' - to be revised + Name.Constant: "#000000", # class: 'no' - to be revised + Name.Decorator: "#888", # class: 'nd' - to be revised + Name.Entity: "#ce5c00", # class: 'ni' + Name.Exception: "bold #cc0000", # class: 'ne' + Name.Function: "#000000", # class: 'nf' + Name.Property: "#000000", # class: 'py' + Name.Label: "#f57900", # class: 'nl' + Name.Namespace: "#000000", # class: 'nn' - to be revised + Name.Other: "#000000", # class: 'nx' + Name.Tag: "bold #004461", # class: 'nt' - like a keyword + Name.Variable: "#000000", # class: 'nv' - to be revised + Name.Variable.Class: "#000000", # class: 'vc' - to be revised + Name.Variable.Global: "#000000", # class: 'vg' - to be revised + Name.Variable.Instance: "#000000", # class: 'vi' - to be revised + + Number: "#990000", # class: 'm' + + Literal: "#000000", # class: 'l' + Literal.Date: "#000000", # class: 'ld' + + String: "#4e9a06", # class: 's' + String.Backtick: "#4e9a06", # class: 'sb' + String.Char: "#4e9a06", # class: 'sc' + String.Doc: "italic #8f5902", # class: 'sd' - like a comment + String.Double: "#4e9a06", # class: 's2' + String.Escape: "#4e9a06", # class: 'se' + String.Heredoc: "#4e9a06", # class: 'sh' + String.Interpol: "#4e9a06", # class: 'si' + String.Other: "#4e9a06", # class: 'sx' + String.Regex: "#4e9a06", # class: 'sr' + String.Single: "#4e9a06", # class: 's1' + String.Symbol: "#4e9a06", # class: 'ss' + + Generic: "#000000", # class: 'g' + Generic.Deleted: "#a40000", # class: 'gd' + Generic.Emph: "italic #000000", # class: 'ge' + Generic.Error: "#ef2929", # class: 'gr' + Generic.Heading: "bold #000080", # class: 'gh' + Generic.Inserted: "#00A000", # class: 'gi' + Generic.Output: "#888", # class: 'go' + Generic.Prompt: "#745334", # class: 'gp' + Generic.Strong: "bold #000000", # class: 'gs' + Generic.Subheading: "bold #800080", # class: 'gu' + Generic.Traceback: "bold #a40000", # class: 'gt' + } diff --git a/docs/source/conf.py b/docs/conf.py similarity index 92% rename from docs/source/conf.py rename to docs/conf.py index 13529c36..905c9038 100644 --- a/docs/source/conf.py +++ b/docs/conf.py @@ -11,13 +11,14 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +import sys, os, datetime # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('../..')) -sys.path.insert(0, os.path.abspath('../../jedi')) +sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../jedi')) +sys.path.append(os.path.abspath('_themes')) # -- General configuration ----------------------------------------------------- @@ -42,10 +43,10 @@ master_doc = 'index' # General information about the project. project = u'Jedi' -copyright = u'2012, Jedi contributors' +copyright = u'2012 - {today.year}, Jedi contributors'.format(today=datetime.date.today()) _path = os.path.dirname(os.path.abspath(__file__)) -with open(_path + '/../../VERSION') as f: +with open(os.path.join(_path, '../VERSION'), 'r') as f: VERSION = f.read().strip() # The version info for the project you're documenting, acts as replacement for @@ -98,7 +99,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'flask' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -106,7 +107,7 @@ html_theme = 'default' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ['_themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -138,7 +139,16 @@ html_static_path = ['_static'] #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': [ +# 'sidebarlogo.html', + 'localtoc.html', + 'relations.html', + 'ghbuttons.html', + 'sourcelink.html', + 'searchbox.html' + ] +} # Additional templates that should be rendered to pages, maps page names to # template names. @@ -173,7 +183,7 @@ html_static_path = ['_static'] # Output file base name for HTML help builder. htmlhelp_basename = 'Jedidoc' -html_style = '/default.css' # Force usage of default template on RTD +#html_style = 'default.css' # Force usage of default template on RTD # -- Options for LaTeX output -------------------------------------------------- @@ -256,4 +266,5 @@ todo_include_todos = False # -- Options for autodoc module ------------------------------------------------ +autodoc_member_order = 'bysource' autodoc_default_flags = ['members', 'undoc-members'] diff --git a/docs/docs/features.rst b/docs/docs/features.rst new file mode 100644 index 00000000..21c34b65 --- /dev/null +++ b/docs/docs/features.rst @@ -0,0 +1,96 @@ +.. include:: ../global.rst + +Features and Caveats +==================== + +|jedi| supports many of the widely used Python features: + + +General Features +---------------- + +- python 2.5+ and 3.2+ support +- ignores syntax errors and wrong indentation +- can deal with complex module / function / class structures +- virtualenv support +- can infer function arguments from sphinx and epydoc docstrings + + +Supported Python Features +------------------------- + +- builtins +- multiple returns or yields +- tuple assignments / array indexing / dictionary indexing +- with-statement / exception handling +- ``*args`` / ``**kwargs`` +- decorators / lambdas / closures +- generators / iterators +- some descriptors: property / staticmethod / classmethod +- some magic methods: ``__call__``, ``__iter__``, ``__next__``, ``__get__``, + ``__getitem__``, ``__init__`` +- ``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 +- ``isinstance`` checks for if/while/assert + + +Unsupported Features +-------------------- + +Not yet implemented: + +- manipulations of instances outside the instance variables without using + methods + +Will probably never be implemented: + +- metaclasses (how could an auto-completion ever support this) +- ``setattr()``, ``__import__()`` +- writing to some dicts: ``globals()``, ``locals()``, ``object.__dict__`` +- evaluating ``if`` / ``while`` + + +Caveats +------- + +**Malformed Syntax** + +Syntax errors and other strange stuff 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|. + +**Legacy Python 2 Features** + +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 +older Python 2 features have been left out: + +- 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! + +**Slow Performance** + +Importing ``numpy`` can be quite slow sometimes, as well as loading the builtins +the first time. If you want to speed things up, you could write import hooks in +|jedi|, which preload stuff. However, once loaded, this is not a problem anymore. +The same is true for huge modules like ``PySide``, ``wx``, etc. + +**Security** + +Security is an important issue for |jedi|. Therefore no Python code is executed. +As long as you write pure python, everything is evaluated statically. But: If +you use builtin modules (``c_builtin``) there is no other option than to execute +those modules. However: Execute isn't that critical (as e.g. in pythoncomplete, +which used to execute *every* import!), because it means one import and no more. +So basically the only dangerous thing is using the import itself. If your +``c_builtin`` uses some strange initializations, it might be dangerous. But if +it does you're screwed anyways, because eventualy you're going to execute your +code, which executes the import. diff --git a/docs/source/installation.rst b/docs/docs/installation.rst similarity index 50% rename from docs/source/installation.rst rename to docs/docs/installation.rst index c8f0099c..60df49be 100644 --- a/docs/source/installation.rst +++ b/docs/docs/installation.rst @@ -1,31 +1,34 @@ +.. include:: ../global.rst + Installation and Configuration ============================== -You can either include *Jedi* as a submodule in your text editor plugin (like -jedi-vim_ does it by default), or you can install it systemwide. +You can either include |jedi| as a submodule in your text editor plugin (like +jedi-vim_ does by default), or you can install it systemwide. System-wide installation via a package manager ---------------------------------------------- -You can install *Jedi* directly from pypi using pip:: +You can install |jedi| directly from pypi using pip:: sudo pip install jedi -If you want to install the current development version:: +If you want to install the current development version (master branch):: sudo pip install -e git://github.com/davidhalter/jedi.git#egg=jedi -.. note:: This just installs the Jedi library, not the editor plugins. For - information about how to make it work with your editor, refer to the - corresponding documentation. +.. note:: This just installs the |jedi| library, not the :ref:`editor plugins + `. For information about how to make it work with your + editor, refer to the corresponding documentation. Manual installation from a downloaded package --------------------------------------------- -If you prefer not to use an automated package installer, you can download a -copy of *Jedi* and install it manually. +If you prefer not to use an automated package installer, you can `download +`__ a current copy of +*Jedi* and install it manually. To install it, navigate to the directory containing `setup.py` on your console and type:: @@ -36,10 +39,11 @@ and type:: Inclusion as a submodule ------------------------ -If you use an editor plugin like jedi-vim_, you can simply include *Jedi* as a -git submodule of the plugin directory. Vim plugin managers like Vundle_ make it -very easy to keep submodules up to date. +If you use an editor plugin like jedi-vim_, you can simply include |jedi| as a +git submodule of the plugin directory. Vim plugin managers like Vundle_ or +Pathogen_ make it very easy to keep submodules up to date. .. _jedi-vim: https://github.com/davidhalter/jedi-vim -.. _Vundle: https://github.com/gmarik/vundle +.. _vundle: https://github.com/gmarik/vundle +.. _pathogen: https://github.com/tpope/vim-pathogen diff --git a/docs/source/plugin-api.rst b/docs/docs/plugin-api.rst similarity index 89% rename from docs/source/plugin-api.rst rename to docs/docs/plugin-api.rst index 58d42994..62ea23f8 100644 --- a/docs/source/plugin-api.rst +++ b/docs/docs/plugin-api.rst @@ -1,4 +1,6 @@ -The plugin API +.. include:: ../global.rst + +The Plugin API ============== .. currentmodule:: jedi @@ -6,7 +8,7 @@ The plugin API Note: This documentation is for Plugin developers, who want to improve their editors/IDE autocompletion -If you want to use **Jedi**, you first need to +If you want to use |jedi|, you first need to ``import jedi``. You then have direct access to the :class:`.Script`. @@ -17,13 +19,19 @@ API Interface ~~~~~~~~~~~~~ .. automodule:: api - :undoc-members: + API Return Classes ~~~~~~~~~~~~~~~~~~ .. automodule:: api_classes - :undoc-members: + +Settings Module +~~~~~~~~~~~~~~~ + +.. automodule:: settings + :no-members: + :no-undoc-members: Examples -------- diff --git a/docs/global.rst b/docs/global.rst new file mode 100644 index 00000000..0279842a --- /dev/null +++ b/docs/global.rst @@ -0,0 +1,3 @@ +:orphan: + +.. |jedi| replace:: *Jedi* diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..8eb83594 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,53 @@ +.. include global.rst + +Jedi +==== + +Release v\ |release|. (:doc:`Installation `) + +.. automodule:: jedi + +Autocompletion can look like this (e.g. VIM plugin): + +.. figure:: _screenshots/screenshot_complete.png + + +.. _toc: + +Docs +---- + +.. toctree:: + :maxdepth: 1 + + docs/installation + docs/features + docs/plugin-api + + +.. _resources: + +Resources +--------- + +- `Source Code on Github `_ +- `Travis Testing `_ +- `Python Package Index `_ + + +.. _editor-plugins: + +Editor Plugins +-------------- + +- `Vim `_ +- `Emacs `_ +- `Sublime Text 2 `_ (*under construction*) + + +.. _other-software: + +Other Software Using Jedi +------------------------- + +- `wdb `_ diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index d12298a0..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,38 +0,0 @@ -Jedi – Python autocompletion that works! -======================================== - - -About Jedi ----------- - -.. automodule:: jedi - :members: - :undoc-members: - -Autocompletion can look like this (e.g. VIM plugin): - -.. figure:: screenshot_complete.png - :align: center - -Contents --------- - -.. toctree:: - :maxdepth: 1 - - installation - plugin-api - -Resources ---------- -- `Source Code on github `_ -- `Travis testing `_ -- `Current PyPi package `_ - -Plugins using the Jedi library ------------------------------- - -- `VIM-Plugin `_ -- `Emacs-Plugin `_ -- `Sublime-Plugin `_ **Under construction** -- `wdb (web debugger) `_ diff --git a/jedi/__init__.py b/jedi/__init__.py index a9e4a2f8..d698bbaa 100644 --- a/jedi/__init__.py +++ b/jedi/__init__.py @@ -1,10 +1,10 @@ """ -Jedi is an autocompletion library for Python. It offers additonal -services such as goto / get_definition / pydoc support / -get_in_function_call / related names. +Jedi is an autocompletion library for Python. It also offers additional +services such as goto / get_definition / pydoc support / get_in_function_call / +related names. -To give you a simple exmple how you can use the jedi library, -here is an exmple for the autocompletion feature: +To give you a simple example how you can use the jedi library, here is an +example for the autocompletion feature: >>> import jedi >>> source = '''import json; json.l''' @@ -19,9 +19,8 @@ here is an exmple for the autocompletion feature: >>> completions[0].word 'load' -As you see Jedi is pretty simple and allows you to concentrate -writing a good text editor, while still having very good IDE features -for Python. +As you see Jedi is pretty simple and allows you to concentrate on writing a +good text editor, while still having very good IDE features for Python. """ import sys diff --git a/jedi/api.py b/jedi/api.py index e9534bd7..ab0c8af2 100644 --- a/jedi/api.py +++ b/jedi/api.py @@ -1,9 +1,10 @@ """ -The api basically only provides one class. You can create a :class:`Script` and -use it's ``complete`` / ``goto`` / etc functions. +The API basically only provides one class. You can create a :class:`Script` and +use its methods. + Additionally you can add a debug function with :func:`set_debug_function` and -catch :exc:`NotFoundError` which is being raised if your completion is -impossible. +catch :exc:`NotFoundError` which is being raised if your completion is not +possible. """ from __future__ import with_statement __all__ = ['Script', 'NotFoundError', 'set_debug_function'] @@ -35,7 +36,7 @@ class NotFoundError(Exception): class Script(object): """ A Script is the base for a completion, goto or whatever you want to do with - jedi. + |jedi|. :param source: The source code of the current file, separated by newlines. :type source: string @@ -71,7 +72,7 @@ class Script(object): Return :class:`api_classes.Completion` objects. Those objects contain information about the completions, more than just names. - :return: completion objects, sorted by name and __ comes last. + :return: Completion objects, sorted by name and __ comes last. :rtype: list of :class:`api_classes.Completion` """ def follow_imports_if_possible(name): diff --git a/jedi/api_classes.py b/jedi/api_classes.py index 64d8a96c..633cf259 100644 --- a/jedi/api_classes.py +++ b/jedi/api_classes.py @@ -1,6 +1,7 @@ -"""`api_classes` contains the return classes of the API. These classes are the -much bigger part of the whole API, because here you get out the information -about completion and goto operations. +""" +The :mod:`api_classes` module contains the return classes of the API. These +classes are the much bigger part of the whole API, because they contain the +interesting information about completion and goto operations. """ import re @@ -20,7 +21,7 @@ import keywords def _clear_caches(): """ - Clears all caches of this and related modules. The only cache that will not + Clear all caches of this and related modules. The only cache that will not be deleted is the module cache. """ cache.clear_caches() @@ -231,7 +232,7 @@ class Completion(BaseDefinition): def follow_definition(self): """ Return the original definitions. I strongly recommend not using it for - your completions, because it might slow down *Jedi*. If you want to read + 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. diff --git a/jedi/settings.py b/jedi/settings.py index b976d866..405fd5a4 100644 --- a/jedi/settings.py +++ b/jedi/settings.py @@ -1,112 +1,224 @@ +""" +This module contains variables with global |jedi| setting. To change the +behavior of |jedi|, change the variables defined in +:mod:`jedi.settings`. + +Plugins should expose an interface so that the user can adjust the +configuration. + + +Example usage:: + + from jedi import settings + settings.case_insensitive_completion = True + + +Completion output +~~~~~~~~~~~~~~~~~ + +.. autodata:: case_insensitive_completion +.. autodata:: add_dot_after_module +.. autodata:: add_bracket_after_function +.. autodata:: no_completion_duplicates + + +Parser +~~~~~~ + +.. autodata:: fast_parser +.. autodata:: fast_parser_always_reparse +.. autodata:: use_get_in_function_call_cache + + +Dynamic stuff +~~~~~~~~~~~~~ + +.. autodata:: dynamic_arrays_instances +.. autodata:: dynamic_array_additions +.. autodata:: dynamic_params +.. autodata:: dynamic_params_for_other_modules +.. autodata:: additional_dynamic_modules + + +Recursions +~~~~~~~~~~ + +Recursion settings are important if you don't want extremly +recursive python code to go absolutely crazy. First of there is a +global limit :data:`max_executions`. This limit is important, to set +a maximum amount of time, the completion may use. + +The default values are based on experiments while completing the |jedi| library +itself (inception!). But I don't think there's any other Python library that +uses recursion in a similarly extreme way. These settings make the completion +definitely worse in some cases. But a completion should also be fast. + +.. autodata:: max_until_execution_unique +.. autodata:: max_function_recursion_level +.. autodata:: max_executions_without_builtins +.. autodata:: max_executions +.. autodata:: scale_get_in_function_call + + +Caching +~~~~~~~ + +.. autodata:: star_import_cache_validity +.. autodata:: get_in_function_call_validity + + +Various +~~~~~~~ + +.. autodata:: part_line_length + + +""" + # ---------------- # completion output settings # ---------------- -# The completion is by default case insensitive. case_insensitive_completion = True +""" +The completion is by default case insensitive. +""" -# Adds a dot after a module, because a module that is not accessed this way is -# definitely not the normal case. However, in VIM this doesn't work, that's why -# it isn't used at the moment. add_dot_after_module = False +""" +Adds a dot after a module, because a module that is not accessed this way is +definitely not the normal case. However, in VIM this doesn't work, that's why +it isn't used at the moment. +""" -# Adds an opening bracket after a function, because that's normal behaviour. -# Removed it again, because in VIM that is not very practical. add_bracket_after_function = False +""" +Adds an opening bracket after a function, because that's normal behaviour. +Removed it again, because in VIM that is not very practical. +""" -# If set, completions with the same name don't appear in the output anymore, -# but are in the `same_name_completions` attribute. no_completion_duplicates = True +""" +If set, completions with the same name don't appear in the output anymore, +but are in the `same_name_completions` attribute. +""" # ---------------- # parser # ---------------- -# Use the fast parser. This means that reparsing is only being done if -# something has been changed e.g. to a function. If this happens, only the -# function is being reparsed. fast_parser = True +""" +Use the fast parser. This means that reparsing is only being done if +something has been changed e.g. to a function. If this happens, only the +function is being reparsed. +""" -# This is just a debugging option. Always reparsing means that the fast parser -# is basically useless. So don't use it. fast_parser_always_reparse = False +""" +This is just a debugging option. Always reparsing means that the fast parser +is basically useless. So don't use it. +""" -# Use the cache (full cache) to generate get_in_function_call's. This may fail -# with multiline docstrings (likely) and other complicated changes (unlikely). -# The goal is to move away from it by making the rest faster. use_get_in_function_call_cache = True +""" +Use the cache (full cache) to generate get_in_function_call's. This may fail +with multiline docstrings (likely) and other complicated changes (unlikely). +The goal is to move away from it by making the rest faster. +""" # ---------------- # dynamic stuff # ---------------- -# check for `append`, etc. on array instances like list() dynamic_arrays_instances = True -# check for `append`, etc. on arrays: [], {}, () +""" +Check for `append`, etc. on array instances like list() +""" + dynamic_array_additions = True +""" +check for `append`, etc. on arrays: [], {}, () +""" -# A dynamic param completion, finds the callees of the function, which define -# the params of a function. dynamic_params = True -# Do the same for other modules. -dynamic_params_for_other_modules = True +""" +A dynamic param completion, finds the callees of the function, which define +the params of a function. +""" + +dynamic_params_for_other_modules = True +""" +Do the same for other modules. +""" -# Additional modules in which Jedi checks if statements are to be found. This -# is practical for IDE's, that want to administrate their modules themselves. additional_dynamic_modules = [] +""" +Additional modules in which |jedi| checks if statements are to be found. This +is practical for IDEs, that want to administrate their modules themselves. +""" # ---------------- # recursions # ---------------- -# Recursion settings are important if you don't want extremly recursive python -# code to go absolutely crazy. First of there is a global limit -# `max_executions`. This limit is important, to set a maximum amount of time, -# the completion may use. -# -# The `max_until_execution_unique` limit is probably the most important one, -# because if that limit is passed, functions can only be one time executed. So -# new functions will be executed, complex recursions with the same functions -# again and again, are ignored. -# -# `max_function_recursion_level` is more about whether the recursions are -# stopped in deepth or in width. The ratio beetween this and -# `max_until_execution_unique` is important here. It stops a recursion (after -# the number of function calls in the recursion), if it was already used -# earlier. -# -# The values are based on my experimental tries, used on the jedi library. But -# I don't think there's any other Python library, that uses recursion in a -# similar (extreme) way. This makes the completion definitely worse in some -# cases. But a completion should also be fast. +max_until_execution_unique = 50 +""" +This limit is probably the most important one, because if this limit is +exceeded, functions can only be one time executed. So new functions will be +executed, complex recursions with the same functions again and again, are +ignored. +""" max_function_recursion_level = 5 -max_until_execution_unique = 50 -max_executions_without_builtins = 200 -max_executions = 250 +""" +`max_function_recursion_level` is more about whether the recursions are +stopped in deepth or in width. The ratio beetween this and +`max_until_execution_unique` is important here. It stops a recursion (after +the number of function calls in the recursion), if it was already used +earlier. +""" + +max_executions_without_builtins = 200 +""" +.. todo:: Document this. +""" + +max_executions = 250 +""" +A maximum amount of time, the completion may use. +""" -# Because get_in_function_call is normally used on every single key hit, it has -# to be faster than a normal completion. This is the factor that is used to -# scale `max_executions` and `max_until_execution_unique`: scale_get_in_function_call = 0.1 +""" +Because get_in_function_call is normally used on every single key hit, it has +to be faster than a normal completion. This is the factor that is used to +scale `max_executions` and `max_until_execution_unique`: +""" # ---------------- # various # ---------------- -# Size of the current code part, which is used to speed up parsing. part_line_length = 20 +""" +Size of the current code part, which is used to speed up parsing. +""" # ---------------- # caching validity (time) # ---------------- -# In huge packages like numpy, checking all star imports on every completion -# might be slow, therefore we do a star import caching, that lasts a certain -# time span (in seconds). star_import_cache_validity = 60.0 +""" +In huge packages like numpy, checking all star imports on every completion +might be slow, therefore we do a star import caching, that lasts a certain +time span (in seconds). +""" -# Finding function calls might be slow (0.1-0.5s). This is not acceptible for -# normal writing. Therefore cache it for a short time. get_in_function_call_validity = 3.0 +""" +Finding function calls might be slow (0.1-0.5s). This is not acceptible for +normal writing. Therefore cache it for a short time. +"""