Add include_builtins to usages, fixes #1131.

jedi/api/__init__.py

@@ -238,7 +238,7 @@ class Script(object):
         defs = [classes.Definition(self._evaluator, d) for d in set(names)]
         return helpers.sorted_definitions(defs)
 
-    def usages(self, additional_module_paths=()):
+    def usages(self, additional_module_paths=(), **kwargs):
         """
         Return :class:`classes.Definition` objects, which contain all
         names that point to the definition of the name under the cursor. This
@@ -247,8 +247,11 @@ class Script(object):
 
         .. todo:: Implement additional_module_paths
 
+        :param include_builtins: Default True, checks if a usage is a builtin
+            (e.g. ``sys``) and in that case does not return it.
         :rtype: list of :class:`classes.Definition`
         """
+        def _usages(include_builtins=True):
             tree_name = self._module_node.get_name_of_position(self._pos)
             if tree_name is None:
                 # Must be syntax
@@ -257,7 +260,10 @@ class Script(object):
             names = usages.usages(self._get_module(), tree_name)
 
             definitions = [classes.Definition(self._evaluator, n) for n in names]
+            if not include_builtins:
+                definitions = [d for d in definitions if not d.in_builtin_module()]
             return helpers.sorted_definitions(definitions)
+        return _usages(**kwargs)
 
     def call_signatures(self):
         """

test/test_api/test_usages.py

@@ -1,3 +1,14 @@
 def test_import_usage(Script):
     s = Script("from .. import foo", line=1, column=18, path="foo.py")
     assert [usage.line for usage in s.usages()] == [1]
+
+
+def test_exclude_builtin_modules(Script):
+    def get(include):
+        return [(d.line, d.column) for d in Script(source, column=8).usages(include_builtins=include)]
+    source = '''import sys\nprint(sys.path)'''
+    places = get(include=True)
+    assert places == [(None, None), (1, 7), (2, 6)]
+
+    places = get(include=False)
+    assert places == [(1, 7), (2, 6)]