design doc addition #386
design doc addition #386
Conversation
|
@karthiknadig this is a first draft on a doc outlining technical design of the envs extension api. Would love a first pass of feedback, fixing any misunderstandings I have and what I might be missing / over-explaining. I am also not sure about the placement, do we just want it as part of the README or is it better as a separate file? |
|
Haven't had a chance to fully read and review but this is great! Since it is rather comprehensive, I would suggest keeping it as a separate file and linking from the README or storing this as a Wiki page that we can direct to in the README |
There was a problem hiding this comment.
Pull Request Overview
This PR adds a design documentation file outlining the Python Environments API for the VS Code extension.
- Introduces comprehensive technical design details on environment management, package handling, and project creation.
- Documents the interactions between various API components and the connection to the UI.
|
|
||
|
|
||
| ### Copilot Tooling | ||
| xxxx |
There was a problem hiding this comment.
The 'Copilot Tooling' section currently contains a placeholder ('xxxx'). Please update this section with a meaningful description or remove it until the appropriate content is available.
Copilot uses AI. Check for mistakes.
| @@ -0,0 +1,130 @@ | |||
|
|
|||
| # Python Environments API | |||
| The following helps describe the technical design of the Python Environments Extension for use mainly by contributing extension authors. This extension is the entry point which will surface the entire environment management experience for Python in VS Code and its modularity should allow for individual tools / libraries to implement these methods for their tool making them usable in VS Code. | |||
There was a problem hiding this comment.
| The following helps describe the technical design of the Python Environments Extension for use mainly by contributing extension authors. This extension is the entry point which will surface the entire environment management experience for Python in VS Code and its modularity should allow for individual tools / libraries to implement these methods for their tool making them usable in VS Code. | |
| The following guide describes the technical design of the Python Environments Extension. Its intended use is mainly for contributing extension authors. This extension is the entry point which will surface the entire environment management experience for Python in VS Code and its modularity should allow for individual tools / libraries to implement these methods for their tool making them usable in VS Code. |
|
|
||
|
|
||
| ## Functionalities of Extension & its API | ||
| The python environment extension has four main functionalities: |
There was a problem hiding this comment.
| The python environment extension has four main functionalities: | |
| The Python Environments extension has four main functionalities: |
|
|
||
| ### Workspace and Environments | ||
| The relationship between **workspaces** and **environments** in the extension can be any of the following configurations: | ||
| | workspace | environment | description | example | |
There was a problem hiding this comment.
| | workspace | environment | description | example | | |
| | Workspace | Environment | Description | Example | |
|
|
||
| ## API Surface | ||
| - **PythonProjectApi** -> The API for interacting with Python projects. | ||
| - **PythonExecutionApi** |
There was a problem hiding this comment.
| - **PythonExecutionApi** | |
| - **PythonExecutionApi** | |
| ```-> The API for running code (experimental) |
|
|
||
| ## Objects in Extension API | ||
| The core components are as follows: | ||
| - `PythonEnvironment`: a python environment |
There was a problem hiding this comment.
| - `PythonEnvironment`: a python environment | |
| - `PythonEnvironment`: a python environment (created using `createPythonEnvironmentItem`) |
| - Has unique id and correlates to a `EnvironmentManager` | ||
| - Contains `PythonEnvironmentExecutionInfo` | ||
| - `EnvironmentManager`: an object which manages `PythonEnvironment` | ||
| - registered by an extension in form with id `<publisher-id>.<extension-id>:<manager-name>` |
There was a problem hiding this comment.
| - registered by an extension in form with id `<publisher-id>.<extension-id>:<manager-name>` | |
| - registered by an extension in form with id `<publisher-id>.<extension-id>:<manager-name>` (id is generated internally by extension) |
| - one `EnvironmentManager` can create many `PythonEnvironment` objects | ||
| - `PackageManagementOptions`: actions relating to, and specifying packages | ||
| - `PackageManager`: an object which manages packages | ||
| - registered by an extension in form with id `<publisher-id>.<extension-id>:<manager-name>` |
There was a problem hiding this comment.
| - registered by an extension in form with id `<publisher-id>.<extension-id>:<manager-name>` | |
| - registered by an extension in form with id `<publisher-id>.<extension-id>:<manager-name>` (Id is generated internally by the extension) |
| - envId: PythonEnvironmentId; (unique identifier) | ||
| - id: string; | ||
| - managerId: string; |
There was a problem hiding this comment.
We may need to mention that is autogenerated, and immutable.
| | venv | pip | | ||
| | conda | conda | |
There was a problem hiding this comment.
| | venv | pip | | |
| | conda | conda | | |
| | venv | pip/uv | | |
| | conda | conda | | |
| | pyenv | pip/uv | | |
| | poetry | poetry | |
No description provided.