Introduce pyls.extraSysPath configuration

Before this commit, there is no way to specify extra "sys path" for
completion, lint-ing, and so on: passing it via PYTHONPATH might cause
unintentional side effect for pyls itself.

In order to explicitly specify extra "sys path", this commit
introduces pyls.extraSysPath configuration, and adds its value to
extra_sys_path at Document construction.

After this commit, Document.sys_path() returns the list of paths in
the order below.

  1. source root(s) in the workspace
  2. extra sys path (introduced by this commit)
  3. sys.path of Python runtime

pyls.extraSysPath configuration accepts any path, even if it referring
outside of the workspace.

BTW, paths configured via pyls.plugins.jedi.extra_paths will be added
after values above at Document.jedi_script(). Therefore,
pyls.extraSysPath configuration is also useful at putting paths at the
front of runtime sys.path for jedi plugin.

pyls/config/pyls_conf.py

@@ -8,6 +8,7 @@
 PROJECT_CONFIGS = ['setup.cfg', 'tox.ini']
 
 OPTIONS = [
+    ('extra-sys-path', 'extraSysPath', list),
     ('source-roots', 'sourceRoots', list),
 ]
 

pyls/workspace.py

@@ -131,10 +131,12 @@ def source_roots(self, document_path):
         return list(set((os.path.dirname(project_file) for project_file in files))) or [self._root_path]
 
     def _create_document(self, doc_uri, source=None, version=None):
+        # extraSysPath allows path to outside workspace
+        extra_sys_path = self.normalize_config_paths('extraSysPath', inside_only=False)
         path = uris.to_fs_path(doc_uri)
         return Document(
             doc_uri, source=source, version=version,
-            extra_sys_path=self.source_roots(path),
+            extra_sys_path=self.source_roots(path) + extra_sys_path,
             rope_project_builder=self._rope_project_builder,
             config=self._config, workspace=self,
         )

test/test_workspace.py

@@ -169,3 +169,43 @@ def test_source_roots_config(tmpdir, metafile):
             assert full_path not in sys_path  # check for safety
         else:
             assert norm_path in sys_path
+
+
+@pytest.mark.parametrize('metafile', ['setup.cfg', 'tox.ini', None])
+def test_extra_sys_path_config(tmpdir, metafile):
+    root_path = str(tmpdir)
+
+    extra_sys_path = ['/abs/path', '../relative/path']
+
+    if metafile:
+        # configured by metafile at pyls startup
+        with open(os.path.join(root_path, metafile), 'w+') as f:
+            f.write('[pyls]\nextra-sys-path=\n    %s\n' %
+                    ',\n    '.join(extra_sys_path))
+
+    pyls = PythonLanguageServer(StringIO, StringIO)
+    pyls.m_initialize(
+        processId=1,
+        rootUri=uris.from_fs_path(root_path),
+        initializationOptions={}
+    )
+
+    if not metafile:
+        # configured by client via LSP after pyls startup
+        pyls.m_workspace__did_change_configuration({
+            'pyls': {'extraSysPath': extra_sys_path},
+        })
+
+    test_uri = uris.from_fs_path(os.path.join(root_path, 'hello/test.py'))
+    pyls.workspace.put_document(test_uri, 'assert True')
+    test_doc = pyls.workspace.get_document(test_uri)
+
+    # apply os.path.normcase() on paths below, because case-sensitive
+    # comparison on Windows causes unintentional failure for case
+    # instability around drive letter
+
+    sys_path = [os.path.normcase(p) for p in test_doc.sys_path()]
+    for raw_path in extra_sys_path:
+        full_path = os.path.join(root_path, raw_path)
+        norm_path = os.path.normcase(os.path.normpath(full_path))
+        assert norm_path in sys_path

vscode-client/package.json

@@ -35,6 +35,15 @@
                     },
                     "uniqueItems": true
                 },
+                "pyls.extraSysPath": {
+                    "type": "array",
+                    "default": [],
+                    "description": "List of extra paths to find packages.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "uniqueItems": true
+                },
                 "pyls.sourceRoots": {
                     "type": "array",
                     "default": [],