Allow extra_paths to be placed in front of sys.path.

* Add pylsp.plugins.jedi.prioritize configuration key

Note that Document.sys_path should be removed OR the prioritize logic moved inside this method. Either option requires breaking the API.

CONFIGURATION.md

@@ -20,6 +20,7 @@ This server can be configured using the `workspace/didChangeConfiguration` metho
 | `pylsp.plugins.flake8.select` | `array` of unique `string` items | List of errors and warnings to enable. | `null` |
 | `pylsp.plugins.jedi.auto_import_modules` | `array` of `string` items | List of module names for jedi.settings.auto_import_modules. | `["numpy"]` |
 | `pylsp.plugins.jedi.extra_paths` | `array` of `string` items | Define extra paths for jedi.Script. | `[]` |
+| `pylsp.plugins.jedi.prioritize` | `boolean` | Whether to place extra_paths at the beginning (true) or end (false) of `sys.path` | `false` |
 | `pylsp.plugins.jedi.env_vars` | `object` | Define environment variables for jedi.Script and Jedi.names. | `null` |
 | `pylsp.plugins.jedi.environment` | `string` | Define environment for jedi.Script and Jedi.names. | `null` |
 | `pylsp.plugins.jedi_completion.enabled` | `boolean` | Enable or disable the plugin. | `true` |

pylsp/config/schema.json

@@ -143,6 +143,11 @@
       },
       "description": "Define extra paths for jedi.Script."
     },
+    "pylsp.plugins.jedi.prioritize": {
+      "type": "boolean",
+      "default": false,
+      "description": "Whether to place extra_paths at the beginning (true) or end (false) of `sys.path`"
+    },
     "pylsp.plugins.jedi.env_vars": {
       "type": [
         "object",
@@ -500,4 +505,4 @@
       "description": "The name of the folder in which rope stores project configurations and data.  Pass `null` for not using such a folder at all."
     }
   }
-}
+}

pylsp/workspace.py

@@ -507,6 +507,7 @@ def jedi_script(self, position=None, use_document_path=False):
         extra_paths = []
         environment_path = None
         env_vars = None
+        prioritize = False
 
         if self._config:
             jedi_settings = self._config.plugin_settings(
@@ -523,9 +524,10 @@ def jedi_script(self, position=None, use_document_path=False):
 
             extra_paths = jedi_settings.get("extra_paths") or []
             env_vars = jedi_settings.get("env_vars")
+            prioritize = jedi_settings.get("prioritize")
 
-        # Drop PYTHONPATH from env_vars before creating the environment because that makes
-        # Jedi throw an error.
+        # Drop PYTHONPATH from env_vars before creating the environment because
+        # to ensure that Jedi can startup properly without module name collision.
         if env_vars is None:
             env_vars = os.environ.copy()
         env_vars.pop("PYTHONPATH", None)
@@ -535,7 +537,10 @@ def jedi_script(self, position=None, use_document_path=False):
             if environment_path
             else None
         )
-        sys_path = self.sys_path(environment_path, env_vars=env_vars) + extra_paths
+        if prioritize:
+            sys_path = extra_paths + self.sys_path(environment_path, env_vars)
+        else:
+            sys_path = self.sys_path(environment_path, env_vars) + extra_paths
         project_path = self._workspace.root_path
 
         # Extend sys_path with document's path if requested
@@ -571,8 +576,8 @@ def get_enviroment(self, environment_path=None, env_vars=None):
         return environment
 
     def sys_path(self, environment_path=None, env_vars=None):
+        # TODO: when safe to break API, remove this method.
         # Copy our extra sys path
-        # TODO: when safe to break API, use env_vars explicitly to pass to create_environment
         path = list(self._extra_sys_path)
         environment = self.get_enviroment(
             environment_path=environment_path, env_vars=env_vars