From 394e2e77dec560844b574ae56b28e29e3c4f28e0 Mon Sep 17 00:00:00 2001 From: Dave Halter Date: Tue, 11 Mar 2014 17:26:38 +0100 Subject: [PATCH] refactored the development docs, which was badly needed especially since evaluate/dynamic.py doesn't contain a lot of functionality anymore. --- docs/docs/development.rst | 28 +++++++++++++++++++++++---- jedi/evaluate/dynamic.py | 40 +++------------------------------------ jedi/evaluate/finder.py | 13 +++++++++++++ jedi/evaluate/iterable.py | 22 +++++++++++++++++++++ 4 files changed, 62 insertions(+), 41 deletions(-) diff --git a/docs/docs/development.rst b/docs/docs/development.rst index 29ea8bb7..bb2c4796 100644 --- a/docs/docs/development.rst +++ b/docs/docs/development.rst @@ -103,6 +103,15 @@ Evaluation Representation (evaluate/representation.py) FunctionExecution :parts: 1 + +.. _name_resolution: + +Name resolution (evaluate/finder.py) +++++++++++++++++++++++++++++++++++++ + +.. automodule:: jedi.evaluate.finder + + .. _dev-api: API (api.py and api_classes.py) @@ -115,7 +124,6 @@ conservative with the API. I'd rather not add new API features if they are not necessary, because it's much harder to deprecate stuff than to add it later. - .. _core-extensions: Core Extensions @@ -123,7 +131,8 @@ Core Extensions Core Extensions is a summary of the following topics: -- :ref:`Dynamic Arrays & Function Parameters ` +- :ref:`Iterables & Dynamic Arrays ` +- :ref:`Dynamic Parameters ` - :ref:`Fast Parser ` - :ref:`Docstrings ` - :ref:`Refactoring ` @@ -132,10 +141,21 @@ These topics are very important to understand what Jedi additionally does, but they could be removed from Jedi and Jedi would still work. But slower and without some features. +.. _iterables: + +Iterables & Dynamic Arrays (evaluate/iterable.py) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To understand Python on a deeper level, |jedi| needs to understand some of the +dynamic features of Python, however this probably the most complicated part: + +.. automodule:: jedi.evaluate.iterable + + .. _dynamic: -Dynamic Arrays & Function Parameters (dynamic.py) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Parameter completion (evaluate/dynamic.py) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. automodule:: jedi.evaluate.dynamic diff --git a/jedi/evaluate/dynamic.py b/jedi/evaluate/dynamic.py index b01c0ce5..48cba7f3 100644 --- a/jedi/evaluate/dynamic.py +++ b/jedi/evaluate/dynamic.py @@ -1,30 +1,4 @@ """ -To understand Python on a deeper level, |jedi| needs to understand some of the -dynamic features of Python, however this probably the most complicated part: - -- Array modifications (e.g. ``list.append``) -- Parameter completion in functions -- Flow checks (e.g. ``if isinstance(a, str)`` -> a is a str) - -Array modifications -******************* - -If the content of an array (``set``/``list``) is wanted somewhere, the current -module will be checked for appearances of ``arr.append``, ``arr.insert``, etc. -If the ``arr`` name points to an actual array, the content will be added - -This can be really cpu intensive, as you can imagine. Because |jedi| has to -follow **every** ``append``. However this works pretty good, because in *slow* -cases, the recursion detector and other settings will stop this process. - -It is important to note that: - -1. Array modfications work only in the current module -2. Only Array additions are being checked, ``list.pop``, etc. is being ignored. - -Parameter completion -******************** - One of the really important features of |jedi| is to have an option to understand code like this:: @@ -38,19 +12,11 @@ that's what a human would expect. It works as follows: -- A param is being encountered +- |Jedi| sees a param - search for function calls named ``foo`` -- execute these calls and check the injected params. This work with a - ``ParamListener``. - -Flow checks -*********** - -Flow checks are not really mature. There's only a check for ``isinstance``. It -would check whether a flow has the form of ``if isinstance(a, type_or_tuple)``. -Unfortunately every other thing is being ignored (e.g. a == '' would be easy to -check for -> a is a string). There's big potential in these checks. +- execute these calls and check the input. This work with a ``ParamListener``. """ + from jedi.parser import representation as pr from jedi import settings from jedi.evaluate import helpers diff --git a/jedi/evaluate/finder.py b/jedi/evaluate/finder.py index 12675ef8..55c86ed9 100644 --- a/jedi/evaluate/finder.py +++ b/jedi/evaluate/finder.py @@ -1,3 +1,16 @@ +""" +Searcjing for names with given scope and name. This is very central in Jedi and +Python. The name resolution is quite complicated with descripter, +``__getattribute__``, ``__getattr__``, ``global``, etc. + +Flow checks ++++++++++++ + +Flow checks are not really mature. There's only a check for ``isinstance``. It +would check whether a flow has the form of ``if isinstance(a, type_or_tuple)``. +Unfortunately every other thing is being ignored (e.g. a == '' would be easy to +check for -> a is a string). There's big potential in these checks. +""" import copy import sys diff --git a/jedi/evaluate/iterable.py b/jedi/evaluate/iterable.py index a26c59e6..790a5b76 100644 --- a/jedi/evaluate/iterable.py +++ b/jedi/evaluate/iterable.py @@ -1,3 +1,25 @@ +""" +Contains all classes and functions to deal with lists, dicts, generators and +iterators in general. + +Array modifications +******************* + +If the content of an array (``set``/``list``) is requested somewhere, the +current module will be checked for appearances of ``arr.append``, +``arr.insert``, etc. If the ``arr`` name points to an actual array, the +content will be added + +This can be really cpu intensive, as you can imagine. Because |jedi| has to +follow **every** ``append`` and check wheter it's the right array. However this +works pretty good, because in *slow* cases, the recursion detector and other +settings will stop this process. + +It is important to note that: + +1. Array modfications work only in the current module. +2. Jedi only checks Array additions; ``list.pop``, etc are ignored. +""" import itertools from jedi import common