You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
# Python environment tools for Visual Studio Code
2
2
3
-
Performant Python environment tooling and support, such as locating all global Python installs and virtual environments.
3
+
Performant Python environment tooling and support, such as locating all global Python installs and virtual environments.
4
4
5
5
This project will be consumed by the [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) directly. You can find the code to consume `pet` in the Python extension [source code](https://github.com/microsoft/vscode-python/blob/main/src/client/pythonEnvironments/base/locators/common/nativePythonFinder.ts). For more information on JSNORPC requests/notifications for this tool, please reference [/docs/JSONRPC.md](https://github.com/microsoft/python-environment-tools/blob/main/docs/JSONRPC.md).
6
6
7
-
## Environment Types Supported
7
+
## Environment Types Supported
8
8
9
9
- python.org
10
10
- Windows Store
@@ -22,7 +22,7 @@ This project will be consumed by the [Python extension](https://marketplace.visu
22
22
- VirtualEnv
23
23
- Python on your PATH
24
24
25
-
## Features
25
+
## Features
26
26
27
27
- Discovery of all global Python installs
28
28
- Discovery of all Python virtual environments
@@ -35,7 +35,7 @@ Locator refresh-state contracts are documented in [docs/LOCATOR_STATE.md](docs/L
35
35
36
36
## Contributing
37
37
38
-
This project welcomes contributions and suggestions. Most contributions require you to agree to a
38
+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
39
39
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
40
40
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
41
41
@@ -49,8 +49,8 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
49
49
50
50
## Trademarks
51
51
52
-
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
53
-
trademarks or logos is subject to and must follow
52
+
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
Copy file name to clipboardExpand all lines: docs/LOCATOR_STATE.md
+25-25Lines changed: 25 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,34 +6,34 @@ The `Locator::refresh_state()` classification is the contract for that boundary.
6
6
7
7
## Classifications
8
8
9
-
| Classification | Meaning | Sync behavior |
10
-
| --- | --- | --- |
11
-
|`Stateless`| The locator keeps no mutable state that survives a request. | Nothing is copied back. |
12
-
|`ConfiguredOnly`| The locator stores configured inputs such as executable paths or workspace directories. | Refresh must use the transient locator's request snapshot and must not copy this state back. |
13
-
|`SelfHydratingCache`| The locator stores a cache that later requests can rebuild on demand. | Refresh may fill a transient cache, but correctness must not rely on syncing it. |
|`Stateless`| The locator keeps no mutable state that survives a request. | Nothing is copied back.|
12
+
|`ConfiguredOnly`| The locator stores configured inputs such as executable paths or workspace directories. | Refresh must use the transient locator's request snapshot and must not copy this state back.|
13
+
|`SelfHydratingCache`| The locator stores a cache that later requests can rebuild on demand. | Refresh may fill a transient cache, but correctness must not rely on syncing it.|
14
14
|`SyncedDiscoveryState`| The locator stores refresh-discovered state that later requests need for correctness or fidelity. | The locator must override `sync_refresh_state_from()` and copy only state appropriate for the `RefreshStateSyncScope`. |
15
15
16
16
## Current Locator Inventory
17
17
18
-
| Locator | Mutable state | Classification | Notes |
19
-
| --- | --- | --- | --- |
20
-
| WindowsStore | Discovered Store environments |`SyncedDiscoveryState`| Full and matching global-kind refreshes replace the cache; workspace refreshes leave it alone. |
21
-
| WindowsRegistry | Discovered registry managers and environments |`SyncedDiscoveryState`| Full and matching global-kind refreshes replace the cache; workspace refreshes leave it alone. |
| PyEnv | Manager and versions-directory cache |`SelfHydratingCache`|`find()` clears the cache, and `try_from()` can rebuild it from the environment. |
24
-
| Pixi | None |`Stateless`| Identification is derived from filesystem markers. |
25
-
| Conda | Environment, manager, and mamba-manager discovery caches; configured executable |`SyncedDiscoveryState`| Discovery caches are synced. The configured executable remains configuration state and is not copied from refresh locators. |
26
-
| Uv | Configured workspace directories; immutable uv install directory |`ConfiguredOnly`| Workspace directories come from the request configuration snapshot. |
27
-
| Poetry | Configured workspace directories and executable; discovered search result |`SyncedDiscoveryState`| Search results are synced or merged by scope. Configured inputs are not copied back. |
28
-
| PipEnv | Configured pipenv executable |`ConfiguredOnly`| The executable comes from the configuration snapshot. |
29
-
| VirtualEnvWrapper | Environment variables captured at construction |`Stateless`| No refresh-discovered mutable state. |
30
-
| Venv | None |`Stateless`| Identification is derived from `pyvenv.cfg` and filesystem layout. |
31
-
| VirtualEnv | None |`Stateless`| Identification is derived from virtualenv markers. |
32
-
| Homebrew | Environment variables captured at construction |`Stateless`| No refresh-discovered mutable state. |
| WindowsStore | Discovered Store environments |`SyncedDiscoveryState`| Full and matching global-kind refreshes replace the cache; workspace refreshes leave it alone.|
21
+
| WindowsRegistry | Discovered registry managers and environments |`SyncedDiscoveryState`| Full and matching global-kind refreshes replace the cache; workspace refreshes leave it alone.|
| PyEnv | Manager and versions-directory cache |`SelfHydratingCache`|`find()` clears the cache, and `try_from()` can rebuild it from the environment.|
24
+
| Pixi | None |`Stateless`| Identification is derived from filesystem markers.|
25
+
| Conda | Environment, manager, and mamba-manager discovery caches; configured executable |`SyncedDiscoveryState`| Discovery caches are synced. The configured executable remains configuration state and is not copied from refresh locators. |
26
+
| Uv | Configured workspace directories; immutable uv install directory |`ConfiguredOnly`| Workspace directories come from the request configuration snapshot.|
27
+
| Poetry | Configured workspace directories and executable; discovered search result |`SyncedDiscoveryState`| Search results are synced or merged by scope. Configured inputs are not copied back.|
28
+
| PipEnv | Configured pipenv executable |`ConfiguredOnly`| The executable comes from the configuration snapshot.|
29
+
| VirtualEnvWrapper | Environment variables captured at construction |`Stateless`| No refresh-discovered mutable state.|
30
+
| Venv | None |`Stateless`| Identification is derived from `pyvenv.cfg` and filesystem layout.|
31
+
| VirtualEnv | None |`Stateless`| Identification is derived from virtualenv markers.|
32
+
| Homebrew | Environment variables captured at construction |`Stateless`| No refresh-discovered mutable state.|
|LinuxGlobal | Reported executable cache |`SelfHydratingCache`|`try_from()` can repopulate the cache by scanning known global bin directories.|
37
37
38
38
## Updating The Contract
39
39
@@ -43,4 +43,4 @@ When adding mutable state to a locator, classify it before relying on it across
43
43
2. If it is only a performance cache, use `SelfHydratingCache` and make later requests able to rebuild it.
44
44
3. If later requests need refresh-discovered state, use `SyncedDiscoveryState`, implement `sync_refresh_state_from()`, and cover full, workspace, and kind-filtered scopes with tests.
45
45
46
-
The locator graph has a regression test in `crates/pet/src/jsonrpc.rs` that pins the current classification of each locator created by `create_locators()`.
46
+
The locator graph has a regression test in `crates/pet/src/jsonrpc.rs` that pins the current classification of each locator created by `create_locators()`.
0 commit comments