python-discovery 1.9.5__py3-none-any.whl → 1.9.6__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,16 +2,13 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from importlib.metadata import version
6
-
5
+ from ._about import __version__
7
6
  from ._cache import ContentStore, DiskCache, PyInfoCache
8
7
  from ._discovery import get_interpreter, iter_interpreters
9
8
  from ._py_info import KNOWN_ARCHITECTURES, MarkerEnvironment, PythonInfo, normalize_isa
10
9
  from ._py_spec import KNOWN_IMPLEMENTATIONS, PythonSpec
11
10
  from ._specifier import SimpleSpecifier, SimpleSpecifierSet, SimpleVersion
12
11
 
13
- __version__ = version("python-discovery")
14
-
15
12
  __all__ = [
16
13
  "KNOWN_ARCHITECTURES",
17
14
  "KNOWN_IMPLEMENTATIONS",
@@ -0,0 +1,8 @@
1
+ """The installed distribution version."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from importlib.metadata import version
6
+
7
+ #: the installed distribution version
8
+ __version__ = version("python-discovery")
@@ -24,11 +24,19 @@ class ContentStore(Protocol):
24
24
  """A store for reading and writing cached content."""
25
25
 
26
26
  def exists(self) -> bool:
27
- """Return whether the cached content exists."""
27
+ """
28
+ Return whether the cached content exists.
29
+
30
+ :returns: ``True`` if the content is cached, ``False`` otherwise.
31
+ """
28
32
  ...
29
33
 
30
34
  def read(self) -> dict | None:
31
- """Read the cached content, or ``None`` if unavailable or corrupt."""
35
+ """
36
+ Read the cached content, or ``None`` if unavailable or corrupt.
37
+
38
+ :returns: the cached content, or ``None``.
39
+ """
32
40
  ...
33
41
 
34
42
  def write(self, content: dict) -> None:
@@ -45,7 +53,11 @@ class ContentStore(Protocol):
45
53
 
46
54
  @contextmanager
47
55
  def locked(self) -> Generator[None]:
48
- """Context manager that acquires an exclusive lock on this store."""
56
+ """
57
+ Context manager that acquires an exclusive lock on this store.
58
+
59
+ :returns: a context manager; the lock is held inside its ``with`` block.
60
+ """
49
61
  ...
50
62
 
51
63
 
@@ -58,6 +70,7 @@ class PyInfoCache(Protocol):
58
70
  Return the content store for the interpreter at *path*.
59
71
 
60
72
  :param path: absolute path to a Python executable.
73
+ :returns: the content store for *path*.
61
74
  """
62
75
  ...
63
76
 
@@ -66,20 +79,98 @@ class PyInfoCache(Protocol):
66
79
  ...
67
80
 
68
81
 
69
- class DiskContentStore:
70
- """JSON file-based content store with file locking."""
82
+ class DiskCache:
83
+ """
84
+ File-system based Python interpreter info cache (``<root>/py_info/4/<sha256>.json``).
85
+
86
+ :param root: root directory for the on-disk cache.
87
+ """
88
+
89
+ def __init__(self, root: Path) -> None:
90
+ self._root = Path(os.path.abspath(root)) # ruff:ignore[os-path-abspath] # resolve() follows untrusted links
91
+
92
+ def py_info(self, path: Path) -> ContentStore:
93
+ """
94
+ Return the content store for the interpreter at *path*.
95
+
96
+ :param path: absolute path to a Python executable.
97
+ :returns: the content store for *path*.
98
+ """
99
+ if not self._trusted_folder():
100
+ return NoOpContentStore()
101
+ return DiskContentStore(self._py_info_dir, sha256(fsencode(path)).hexdigest())
71
102
 
103
+ def _trusted_folder(self) -> bool:
104
+ if not hasattr(os, "geteuid"):
105
+ return True
106
+ user_id = os.geteuid()
107
+ folder = self._py_info_dir
108
+ private = {self._root, folder.parent, folder}
109
+ for candidate in (*reversed(folder.parents), folder):
110
+ try:
111
+ try:
112
+ status = candidate.lstat()
113
+ except FileNotFoundError:
114
+ candidate.mkdir(exist_ok=True)
115
+ status = candidate.lstat()
116
+ except OSError:
117
+ _LOGGER.warning("not caching in %s", candidate, exc_info=True)
118
+ return False
119
+ if (
120
+ not stat.S_ISDIR(status.st_mode)
121
+ or status.st_uid not in {user_id, 0}
122
+ or (status.st_mode & 0o022 and (candidate in private or not status.st_mode & stat.S_ISVTX))
123
+ ):
124
+ _LOGGER.warning("not caching in untrusted directory %s", candidate)
125
+ return False
126
+ return True
127
+
128
+ @property
129
+ def _py_info_dir(self) -> Path:
130
+ return self._root / "py_info" / "4"
131
+
132
+ def py_info_clear(self) -> None:
133
+ """Remove all cached interpreter information."""
134
+ folder = self._py_info_dir
135
+ if folder.exists() and self._trusted_folder():
136
+ for entry in folder.iterdir():
137
+ if entry.suffix == ".json":
138
+ with suppress(OSError):
139
+ entry.unlink()
140
+
141
+
142
+ class NoOpContentStore(ContentStore):
143
+ # Content store that does nothing -- implements ContentStore protocol.
144
+ def exists(self) -> bool: # ruff:ignore[no-self-use] cache protocol
145
+ return False
146
+
147
+ def read(self) -> dict | None: # ruff:ignore[no-self-use] cache protocol
148
+ return None
149
+
150
+ def write(self, content: dict) -> None:
151
+ pass
152
+
153
+ def remove(self) -> None:
154
+ pass
155
+
156
+ @contextmanager
157
+ def locked(self) -> Generator[None]: # ruff:ignore[no-self-use] cache protocol
158
+ yield
159
+
160
+
161
+ class DiskContentStore:
162
+ # JSON file-based content store with file locking.
72
163
  def __init__(self, folder: Path, key: str) -> None:
73
164
  self._folder = folder
74
165
  self._key = key
75
166
 
167
+ def exists(self) -> bool:
168
+ return self._file.exists()
169
+
76
170
  @property
77
171
  def _file(self) -> Path:
78
172
  return self._folder / f"{self._key}.json"
79
173
 
80
- def exists(self) -> bool:
81
- return self._file.exists()
82
-
83
174
  def read(self) -> dict | None:
84
175
  data, bad_format = None, False
85
176
  try:
@@ -116,6 +207,11 @@ class DiskContentStore:
116
207
  def _open_entry(path: str, flags: int) -> int:
117
208
  return os.open(path, flags | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
118
209
 
210
+ def remove(self) -> None:
211
+ with suppress(OSError):
212
+ self._file.unlink()
213
+ _LOGGER.debug("removed python info at %s", self._file)
214
+
119
215
  def write(self, content: dict) -> None:
120
216
  self._folder.mkdir(parents=True, exist_ok=True)
121
217
  temporary: Path | None = None
@@ -136,14 +232,9 @@ class DiskContentStore:
136
232
  with suppress(OSError):
137
233
  temporary.unlink(missing_ok=True)
138
234
 
139
- def remove(self) -> None:
140
- with suppress(OSError):
141
- self._file.unlink()
142
- _LOGGER.debug("removed python info at %s", self._file)
143
-
144
235
  @contextmanager
145
236
  def locked(self) -> Generator[None]:
146
- from filelock import FileLock # ruff:ignore[import-outside-top-level]
237
+ from filelock import FileLock # ruff:ignore[import-outside-top-level] filelock is needed only when locking
147
238
 
148
239
  self._folder.mkdir(parents=True, exist_ok=True)
149
240
  if os.name == "posix":
@@ -157,90 +248,9 @@ class DiskContentStore:
157
248
  yield
158
249
 
159
250
 
160
- class DiskCache:
161
- """
162
- File-system based Python interpreter info cache (``<root>/py_info/4/<sha256>.json``).
163
-
164
- :param root: root directory for the on-disk cache.
165
- """
166
-
167
- def __init__(self, root: Path) -> None:
168
- self._root = Path(os.path.abspath(root)) # ruff:ignore[os-path-abspath] # resolve() follows untrusted links
169
-
170
- @property
171
- def _py_info_dir(self) -> Path:
172
- return self._root / "py_info" / "4"
173
-
174
- def py_info(self, path: Path) -> ContentStore:
175
- """
176
- Return the content store for the interpreter at *path*.
177
-
178
- :param path: absolute path to a Python executable.
179
- """
180
- if not self._trusted_folder():
181
- return NoOpContentStore()
182
- key = sha256(fsencode(path)).hexdigest()
183
- return DiskContentStore(self._py_info_dir, key)
184
-
185
- def _trusted_folder(self) -> bool:
186
- if not hasattr(os, "geteuid"):
187
- return True
188
- user_id = os.geteuid()
189
- folder = self._py_info_dir
190
- private = {self._root, folder.parent, folder}
191
- for candidate in (*reversed(folder.parents), folder):
192
- try:
193
- try:
194
- status = candidate.lstat()
195
- except FileNotFoundError:
196
- candidate.mkdir(exist_ok=True)
197
- status = candidate.lstat()
198
- except OSError:
199
- _LOGGER.warning("not caching in %s", candidate, exc_info=True)
200
- return False
201
- if (
202
- not stat.S_ISDIR(status.st_mode)
203
- or status.st_uid not in {user_id, 0}
204
- or (status.st_mode & 0o022 and (candidate in private or not status.st_mode & stat.S_ISVTX))
205
- ):
206
- _LOGGER.warning("not caching in untrusted directory %s", candidate)
207
- return False
208
- return True
209
-
210
- def py_info_clear(self) -> None:
211
- """Remove all cached interpreter information."""
212
- folder = self._py_info_dir
213
- if folder.exists() and self._trusted_folder():
214
- for entry in folder.iterdir():
215
- if entry.suffix == ".json":
216
- with suppress(OSError):
217
- entry.unlink()
218
-
219
-
220
- class NoOpContentStore(ContentStore):
221
- """Content store that does nothing -- implements ContentStore protocol."""
222
-
223
- def exists(self) -> bool: # ruff:ignore[no-self-use]
224
- return False
225
-
226
- def read(self) -> dict | None: # ruff:ignore[no-self-use]
227
- return None
228
-
229
- def write(self, content: dict) -> None:
230
- pass
231
-
232
- def remove(self) -> None:
233
- pass
234
-
235
- @contextmanager
236
- def locked(self) -> Generator[None]: # ruff:ignore[no-self-use]
237
- yield
238
-
239
-
240
251
  class NoOpCache(PyInfoCache):
241
- """Cache that does nothing -- implements PyInfoCache protocol."""
242
-
243
- def py_info(self, path: Path) -> NoOpContentStore: # ruff:ignore[unused-method-argument, no-self-use]
252
+ # Cache that does nothing -- implements PyInfoCache protocol.
253
+ def py_info(self, path: Path) -> NoOpContentStore: # ruff:ignore[unused-method-argument, no-self-use] protocol
244
254
  return NoOpContentStore()
245
255
 
246
256
  def py_info_clear(self) -> None: