langadapter 0.1.0__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.
Files changed (208) hide show
  1. langadapter/__init__.py +76 -0
  2. langadapter/_environment.py +71 -0
  3. langadapter/_execution_scope.py +441 -0
  4. langadapter/_host.py +73 -0
  5. langadapter/_input_copy.py +86 -0
  6. langadapter/_linux_command.py +795 -0
  7. langadapter/_linux_container.py +142 -0
  8. langadapter/_linux_job.py +633 -0
  9. langadapter/_lizard.py +42 -0
  10. langadapter/_owned_directory.py +243 -0
  11. langadapter/_prepared_copy.py +703 -0
  12. langadapter/_process_tree.py +707 -0
  13. langadapter/_project_environments.py +201 -0
  14. langadapter/_treesitter.py +565 -0
  15. langadapter/_windows_job.py +220 -0
  16. langadapter/_words.py +17 -0
  17. langadapter/adapter.py +915 -0
  18. langadapter/c/__init__.py +3 -0
  19. langadapter/c/_build.py +844 -0
  20. langadapter/c/_ctest.py +278 -0
  21. langadapter/c/_extension.py +224 -0
  22. langadapter/c/_extension_policy.py +145 -0
  23. langadapter/c/_gcov.py +273 -0
  24. langadapter/c/_merge.py +360 -0
  25. langadapter/c/_mull.py +167 -0
  26. langadapter/c/_mutation.py +1043 -0
  27. langadapter/c/_pool.py +88 -0
  28. langadapter/c/_programs.py +52 -0
  29. langadapter/c/_pytest_plugin.py +166 -0
  30. langadapter/c/_recorder.py +175 -0
  31. langadapter/c/_repair.py +158 -0
  32. langadapter/c/_sitecustomize.py +29 -0
  33. langadapter/c/_structure.py +183 -0
  34. langadapter/c/_syntax.py +230 -0
  35. langadapter/c/_timing.py +206 -0
  36. langadapter/c/_toolchain.py +118 -0
  37. langadapter/c/_utest.py +453 -0
  38. langadapter/c/_validity.py +210 -0
  39. langadapter/c/adapter.py +2970 -0
  40. langadapter/c/data/counters.c +59 -0
  41. langadapter/c/data/gcov_exports.c +17 -0
  42. langadapter/c/data/utest.h +2050 -0
  43. langadapter/c/data/utest_skip.c +21 -0
  44. langadapter/cancellation.py +62 -0
  45. langadapter/capabilities.py +276 -0
  46. langadapter/check.py +818 -0
  47. langadapter/cli.py +701 -0
  48. langadapter/conformance.py +456 -0
  49. langadapter/consumers.py +549 -0
  50. langadapter/context.py +515 -0
  51. langadapter/errors.py +111 -0
  52. langadapter/execution.py +581 -0
  53. langadapter/hooks.py +839 -0
  54. langadapter/java/__init__.py +4 -0
  55. langadapter/java/_benchmark.py +225 -0
  56. langadapter/java/_build.py +887 -0
  57. langadapter/java/_collisions.py +602 -0
  58. langadapter/java/_env.py +305 -0
  59. langadapter/java/_jacoco.py +623 -0
  60. langadapter/java/_java_source.py +63 -0
  61. langadapter/java/_mutation.py +474 -0
  62. langadapter/java/_pit.py +537 -0
  63. langadapter/java/_policy.py +5 -0
  64. langadapter/java/_profile.py +166 -0
  65. langadapter/java/_questions.py +101 -0
  66. langadapter/java/_runs.py +887 -0
  67. langadapter/java/_setup.py +715 -0
  68. langadapter/java/_sources.py +1294 -0
  69. langadapter/java/_tools.py +586 -0
  70. langadapter/java/_validity.py +215 -0
  71. langadapter/java/_warmed.py +772 -0
  72. langadapter/java/_warmed_fork.py +707 -0
  73. langadapter/java/adapter.py +1238 -0
  74. langadapter/java/source_analysis.py +362 -0
  75. langadapter/mutation/__init__.py +2132 -0
  76. langadapter/operations.py +1095 -0
  77. langadapter/outcomes.py +198 -0
  78. langadapter/placement.py +43 -0
  79. langadapter/preparation.py +786 -0
  80. langadapter/py.typed +0 -0
  81. langadapter/python/__init__.py +14 -0
  82. langadapter/python/_bytecode_helper.py +163 -0
  83. langadapter/python/_collisions.py +1210 -0
  84. langadapter/python/_cosmic_ray.py +3833 -0
  85. langadapter/python/_cr_session_runner.py +1145 -0
  86. langadapter/python/_cr_verify.py +1109 -0
  87. langadapter/python/_mutation.py +514 -0
  88. langadapter/python/_output.py +198 -0
  89. langadapter/python/_plugins.py +1327 -0
  90. langadapter/python/_profile.py +155 -0
  91. langadapter/python/_project_files.py +206 -0
  92. langadapter/python/_provision.py +149 -0
  93. langadapter/python/_questions.py +135 -0
  94. langadapter/python/_run_definition.py +112 -0
  95. langadapter/python/_runs.py +2153 -0
  96. langadapter/python/_setup.py +625 -0
  97. langadapter/python/_sources.py +2467 -0
  98. langadapter/python/_syntax.py +100 -0
  99. langadapter/python/_validity.py +890 -0
  100. langadapter/python/adapter.py +1204 -0
  101. langadapter/python/cosmic_ray.py +175 -0
  102. langadapter/python/project.py +690 -0
  103. langadapter/python/source_analysis.py +336 -0
  104. langadapter/registry.py +379 -0
  105. langadapter/resources.py +101 -0
  106. langadapter/runs.py +1461 -0
  107. langadapter/setup.py +599 -0
  108. langadapter/skeletons/benchmark.txt +3 -0
  109. langadapter/skeletons/call_statistics.txt +4 -0
  110. langadapter/skeletons/capabilities.txt +5 -0
  111. langadapter/skeletons/check_syntax.txt +4 -0
  112. langadapter/skeletons/choose_profile.txt +5 -0
  113. langadapter/skeletons/code_smells.txt +3 -0
  114. langadapter/skeletons/coverage.txt +3 -0
  115. langadapter/skeletons/coverage_texts.txt +8 -0
  116. langadapter/skeletons/delivered_case.txt +4 -0
  117. langadapter/skeletons/discover_runtime.txt +7 -0
  118. langadapter/skeletons/execution_kinds.txt +4 -0
  119. langadapter/skeletons/execution_setup_issue.txt +4 -0
  120. langadapter/skeletons/import_statement.txt +5 -0
  121. langadapter/skeletons/kill_attribution.txt +3 -0
  122. langadapter/skeletons/kill_tokens.txt +10 -0
  123. langadapter/skeletons/language_facts.txt +7 -0
  124. langadapter/skeletons/merge_sources.txt +3 -0
  125. langadapter/skeletons/metric_providers.txt +4 -0
  126. langadapter/skeletons/open_mutation_session.txt +11 -0
  127. langadapter/skeletons/operation_context_issue.txt +4 -0
  128. langadapter/skeletons/operation_readiness.txt +5 -0
  129. langadapter/skeletons/order_dependent_mock_warnings.txt +5 -0
  130. langadapter/skeletons/per_test_evidence.txt +3 -0
  131. langadapter/skeletons/prepare_suite.txt +7 -0
  132. langadapter/skeletons/profile_suite.txt +4 -0
  133. langadapter/skeletons/project.txt +5 -0
  134. langadapter/skeletons/project_test_files.txt +4 -0
  135. langadapter/skeletons/provision_runtime.txt +6 -0
  136. langadapter/skeletons/prune_collection_breakers.txt +5 -0
  137. langadapter/skeletons/prune_unresolvable_imports.txt +5 -0
  138. langadapter/skeletons/request_options.txt +8 -0
  139. langadapter/skeletons/run_as_delivered.txt +5 -0
  140. langadapter/skeletons/run_counts.txt +4 -0
  141. langadapter/skeletons/run_suite.txt +7 -0
  142. langadapter/skeletons/salvage_syntax.txt +5 -0
  143. langadapter/skeletons/scoped_metrics.txt +5 -0
  144. langadapter/skeletons/setup_files.txt +8 -0
  145. langadapter/skeletons/setup_questions.txt +8 -0
  146. langadapter/skeletons/strip_module_level_skips.txt +3 -0
  147. langadapter/skeletons/structural_metrics.txt +11 -0
  148. langadapter/skeletons/test_files.txt +4 -0
  149. langadapter/skeletons/test_units.txt +5 -0
  150. langadapter/skeletons/validate_mutation_session_options.txt +5 -0
  151. langadapter/skeletons/validity_policy.txt +9 -0
  152. langadapter/sources.py +1243 -0
  153. langadapter/suites.py +193 -0
  154. langadapter/templates.py +199 -0
  155. langadapter/toolchains/__init__.py +147 -0
  156. langadapter/toolchains/c.ubuntu-24.04.sh +149 -0
  157. langadapter/toolchains/java.ubuntu-24.04.sh +146 -0
  158. langadapter/toolchains/python.ubuntu-24.04.sh +103 -0
  159. langadapter/treesitter.py +212 -0
  160. langadapter/tutorial/__init__.py +413 -0
  161. langadapter/tutorial/example/__init__.py +3 -0
  162. langadapter/tutorial/example/project/calc.toy +4 -0
  163. langadapter/tutorial/example/project/test_calc.toy +5 -0
  164. langadapter/tutorial/example/steps/01_run_tests.py +179 -0
  165. langadapter/tutorial/example/steps/02_test_units.py +197 -0
  166. langadapter/tutorial/example/steps/03_coverage.py +287 -0
  167. langadapter/tutorial/example/steps/04_mutation.py +381 -0
  168. langadapter/tutorial/example/steps/05_load_repair.py +412 -0
  169. langadapter/tutorial/example/steps/06_versions.py +417 -0
  170. langadapter/tutorial/example/tools.py +259 -0
  171. langadapter/tutorial/language.py +254 -0
  172. langadapter/versions.py +264 -0
  173. langadapter/vocabulary.py +80 -0
  174. langadapter-0.1.0.data/data/share/doc/langadapter/README.md +115 -0
  175. langadapter-0.1.0.data/data/share/doc/langadapter/docs/changelog.md +213 -0
  176. langadapter-0.1.0.data/data/share/doc/langadapter/docs/explanation/environment-selection.md +144 -0
  177. langadapter-0.1.0.data/data/share/doc/langadapter/docs/explanation/outcomes.md +44 -0
  178. langadapter-0.1.0.data/data/share/doc/langadapter/docs/explanation/prepared-copies.md +244 -0
  179. langadapter-0.1.0.data/data/share/doc/langadapter/docs/extending/add-a-language.md +3265 -0
  180. langadapter-0.1.0.data/data/share/doc/langadapter/docs/extending/architecture.md +92 -0
  181. langadapter-0.1.0.data/data/share/doc/langadapter/docs/extending/conformance.md +196 -0
  182. langadapter-0.1.0.data/data/share/doc/langadapter/docs/extending/consumer-requirements.md +195 -0
  183. langadapter-0.1.0.data/data/share/doc/langadapter/docs/extending/index.md +44 -0
  184. langadapter-0.1.0.data/data/share/doc/langadapter/docs/extending/metric-provider.md +133 -0
  185. langadapter-0.1.0.data/data/share/doc/langadapter/docs/extending/who-needs-what.md +208 -0
  186. langadapter-0.1.0.data/data/share/doc/langadapter/docs/getting-started.md +194 -0
  187. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/c.md +344 -0
  188. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/containers.md +110 -0
  189. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/java.md +123 -0
  190. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/mutation-sessions.md +252 -0
  191. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/python.md +143 -0
  192. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/settings.md +165 -0
  193. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/source-analysis.md +279 -0
  194. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/timing.md +111 -0
  195. langadapter-0.1.0.data/data/share/doc/langadapter/docs/guide/toolchains.md +184 -0
  196. langadapter-0.1.0.data/data/share/doc/langadapter/docs/reference/cli.md +69 -0
  197. langadapter-0.1.0.data/data/share/doc/langadapter/docs/reference/hooks.md +1399 -0
  198. langadapter-0.1.0.data/data/share/doc/langadapter/docs/reference/tested-environments.md +148 -0
  199. langadapter-0.1.0.data/data/share/doc/langadapter/examples/metric_provider.py +74 -0
  200. langadapter-0.1.0.data/data/share/doc/langadapter/examples/python_mutation.py +58 -0
  201. langadapter-0.1.0.data/data/share/doc/langadapter/examples/python_suite.py +57 -0
  202. langadapter-0.1.0.data/data/share/doc/langadapter/examples/toy_adapter.py +219 -0
  203. langadapter-0.1.0.dist-info/METADATA +176 -0
  204. langadapter-0.1.0.dist-info/RECORD +208 -0
  205. langadapter-0.1.0.dist-info/WHEEL +4 -0
  206. langadapter-0.1.0.dist-info/entry_points.txt +2 -0
  207. langadapter-0.1.0.dist-info/licenses/LICENSE +21 -0
  208. langadapter-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +171 -0
@@ -0,0 +1,76 @@
1
+ """Test execution, coverage, mutation and timing observations for a
2
+ configured project.
3
+
4
+ A caller describes the project in a ``ProjectContext`` and creates an
5
+ adapter for its language with ``create``. Results of executing operations
6
+ carry an ``Outcome``, source operations a ``SourceStatus``. A value the
7
+ adapter did not observe is absent, never zero.
8
+ """
9
+ from langadapter.adapter import LangAdapter
10
+ from langadapter.capabilities import (
11
+ Availability, Capability, CapabilityReport, LanguageFacts, OperationCapability, ToolVersion,
12
+ )
13
+ from langadapter.context import (
14
+ ContainerExecution, Environment, Interpreter, LocalExecution, ProjectContext,
15
+ ProvisioningRequest, TestFrameworkConfig, ProjectInputSelection,
16
+ )
17
+ from langadapter.errors import (
18
+ ExtensionFoundOnlyByImport, InvalidRequest, LangAdapterError, OperationCancelled,
19
+ OwnershipRefused,
20
+ recovery_owners,
21
+ RegistrationConflict, SourceReadError, UnsupportedLanguage,
22
+ )
23
+ from langadapter.cancellation import CancelScope
24
+ from langadapter.outcomes import (
25
+ ExecutionIdentity, FileIdentity, InstrumentIdentity, ObservationIdentity, ToolchainIdentity,
26
+ Outcome,
27
+ )
28
+ from langadapter.setup import (
29
+ ProjectSetupItem, ProjectSetupReport, ProjectSetupRequest, inspect_project, verify_project,
30
+ )
31
+ from langadapter.sources import (
32
+ MetricDefinition, MetricProvider, MetricScope, MetricValue, SourceMetrics, SourceObservation,
33
+ SourceStatus,
34
+ )
35
+ from langadapter.registry import (
36
+ Extension, Registration, create, language_for, load_extension, names, register,
37
+ registration, resolve_extension, unregister,
38
+ )
39
+ from langadapter.suites import (
40
+ BranchItem, CrashItem, EvidenceItem, KillItem, LineItem, Suite, TestId,
41
+ parse_token,
42
+ )
43
+ from langadapter.operations import SourceOperations, TestOperations, MutationOperations
44
+ from langadapter.preparation import PreparedProject, prepare_project
45
+
46
+ # The built-in adapters, registered when the package is imported.
47
+ from langadapter.c.adapter import CAdapter as _CAdapter
48
+ from langadapter.java.adapter import JavaAdapter as _JavaAdapter
49
+ from langadapter.python.adapter import PythonAdapter as _PythonAdapter
50
+
51
+ register(_PythonAdapter.language, _PythonAdapter.file_extensions, _PythonAdapter)
52
+ register(_JavaAdapter.language, _JavaAdapter.file_extensions, _JavaAdapter)
53
+ register(_CAdapter.language, _CAdapter.file_extensions, _CAdapter)
54
+
55
+ __version__ = "0.1.0"
56
+
57
+ __all__ = [
58
+ "__version__", "Availability", "LangAdapter", "BranchItem", "CancelScope", "Capability",
59
+ "CapabilityReport", "ContainerExecution", "CrashItem", "create",
60
+ "Environment",
61
+ "EvidenceItem", "ExecutionIdentity", "Extension", "ExtensionFoundOnlyByImport", "FileIdentity",
62
+ "InstrumentIdentity",
63
+ "Interpreter", "InvalidRequest", "KillItem", "language_for", "load_extension",
64
+ "LangAdapterError", "LanguageFacts", "LineItem", "LocalExecution",
65
+ "MetricDefinition", "MetricProvider", "MetricScope", "MetricValue", "SourceMetrics",
66
+ "names", "ObservationIdentity", "OperationCancelled", "OperationCapability", "Outcome",
67
+ "OwnershipRefused", "recovery_owners",
68
+ "parse_token", "ProjectContext",
69
+ "ProvisioningRequest", "register", "Registration", "registration",
70
+ "ProjectInputSelection",
71
+ "ProjectSetupItem", "ProjectSetupReport", "ProjectSetupRequest", "resolve_extension",
72
+ "inspect_project", "verify_project",
73
+ "PreparedProject", "prepare_project",
74
+ "RegistrationConflict", "SourceObservation", "SourceOperations", "SourceReadError", "SourceStatus", "Suite", "TestFrameworkConfig", "TestId",
75
+ "MutationOperations", "TestOperations", "ToolchainIdentity", "ToolVersion", "unregister", "UnsupportedLanguage",
76
+ ]
@@ -0,0 +1,71 @@
1
+ """Compose a selected command environment without reviving captured absence."""
2
+ from __future__ import annotations
3
+
4
+ import os
5
+ from pathlib import Path
6
+ from typing import Mapping, Optional
7
+
8
+ from langadapter.context import Environment
9
+
10
+
11
+ def captured(values: Optional[Mapping[str, str]]) -> bool:
12
+ return isinstance(values, Environment) and not values.inherit
13
+
14
+
15
+ def launch_environment(values: Optional[Mapping[str, str]] = None, *,
16
+ native: bool = True) -> dict[str, str]:
17
+ """A command's environment: a native overlay over the caller's environment
18
+ unless ``values`` is captured, a container overlay alone. The returned dict may
19
+ take operation-specific native flags without changing the selection."""
20
+ result = dict(os.environ) if native and not captured(values) else {}
21
+ if values is not None:
22
+ result.update(values)
23
+ return result
24
+
25
+
26
+ #: The variables pytest-xdist sets in a worker for itself.
27
+ XDIST_WORKER_VARIABLES = ("PYTEST_XDIST_WORKER", "PYTEST_XDIST_WORKER_COUNT",
28
+ "PYTEST_XDIST_TESTRUNUID")
29
+
30
+
31
+ def run_launch_environment(values: Optional[Mapping[str, str]]) -> dict[str, str]:
32
+ """A Python run's ``launch_environment``, whose inherited part leaves out
33
+ the variables pytest-xdist sets in a worker for itself: a run started
34
+ inside a worker of the caller is not that worker, though the project's
35
+ plugins and conftest would take it for one. ``values`` may set them."""
36
+ result = launch_environment(values)
37
+ for name in XDIST_WORKER_VARIABLES:
38
+ if name not in (values or {}):
39
+ result.pop(name, None)
40
+ return result
41
+
42
+
43
+ def selected_executable(command: str, values: Mapping[str, str]) -> Optional[str]:
44
+ """The host executable ``command`` binds to through explicit absolute paths
45
+ and ``values`` only, or None: unlike Windows process creation or
46
+ ``shutil.which``, never the process's PATH/PATHEXT or current directory."""
47
+ selected = Path(command)
48
+ if selected.is_absolute():
49
+ candidates = (selected,)
50
+ elif selected.name != command or selected.drive:
51
+ return None
52
+ else:
53
+ def selected_value(name):
54
+ if os.name != "nt":
55
+ return values.get(name, "")
56
+ aliases = [value for key, value in values.items() if key.upper() == name]
57
+ return "" if not aliases else aliases[0] if len(set(aliases)) == 1 else None
58
+
59
+ path, file_extensions = selected_value("PATH"), selected_value("PATHEXT")
60
+ if path is None or file_extensions is None:
61
+ return None
62
+ suffixes = [""]
63
+ if os.name == "nt":
64
+ suffixes.extend(suffix for suffix in file_extensions.split(";")
65
+ if suffix.startswith(".") and "/" not in suffix and "\\" not in suffix)
66
+ candidates = (Path(search_dir) / f"{command}{suffix}"
67
+ for search_dir in path.split(os.pathsep)
68
+ if search_dir and Path(search_dir).is_absolute()
69
+ for suffix in dict.fromkeys(suffixes))
70
+ return next((str(path) for path in candidates if path.is_file()
71
+ and (os.name == "nt" or os.access(path, os.X_OK))), None)
@@ -0,0 +1,441 @@
1
+ """Private operation-local accounting for acquired commands and sessions:
2
+ adapter-owned handles, not arbitrary processes or file authorship. Only the
3
+ actual lifecycle owner may confirm disposal. No PID is probed or reclaimed,
4
+ and an interrupted launch without a handle remains uncertain."""
5
+ from __future__ import annotations
6
+
7
+ from contextvars import ContextVar
8
+ import contextlib
9
+ import threading
10
+
11
+ from langadapter._owned_directory import OwnershipRefused
12
+
13
+
14
+ _CURRENT = ContextVar("langadapter_execution_scope", default=None)
15
+
16
+
17
+ class _Ticket:
18
+ pass
19
+
20
+
21
+ class _Scope:
22
+ def __init__(self, *, parent=None, cleanup=False):
23
+ self._resources = {}
24
+ self._lock = threading.RLock()
25
+ self._entry = threading.Lock()
26
+ self._token = None
27
+ self._thread = None
28
+ self._borrow_thread = None
29
+ self._operations = 0
30
+ self._revoked = False
31
+ self._persistent = {}
32
+ self._recovery_thread = None
33
+ self._parent = parent
34
+ self._cleanup = cleanup
35
+ self._prepared_owner = None
36
+ self._children = {}
37
+ # The worker threads ``lend`` admits as the use's actors, while it lasts.
38
+ self._lending = False
39
+ self._lent = set()
40
+
41
+ def __enter__(self):
42
+ current = _CURRENT.get()
43
+ if current is not self._parent or not self._entry.acquire(blocking=False):
44
+ raise OwnershipRefused("Another execution scope is already active: workspace uses "
45
+ "cannot be nested")
46
+ parent_entered = False
47
+ try:
48
+ if current is not None:
49
+ current._enter_child(cleanup=self._cleanup)
50
+ parent_entered = True
51
+ self.require_quiescent()
52
+ self._revoked = False
53
+ self._token = _CURRENT.set(self)
54
+ self._thread = threading.get_ident()
55
+ return self
56
+ except BaseException:
57
+ self._entry.release()
58
+ if parent_entered:
59
+ current._exit_child(failed=True)
60
+ raise
61
+
62
+ def __exit__(self, kind, error, traceback):
63
+ failed = error is not None
64
+ try:
65
+ try:
66
+ self.finish_use()
67
+ except OwnershipRefused as cleanup:
68
+ failed = True
69
+ if error is None:
70
+ raise
71
+ error._langadapter_execution_scope = self
72
+ if hasattr(error, "add_note"):
73
+ error.add_note(str(cleanup))
74
+ finally:
75
+ with self._lock:
76
+ self._revoked = True
77
+ _CURRENT.reset(self._token)
78
+ self._token = None
79
+ self._thread = None
80
+ self._entry.release()
81
+ if self._parent is not None:
82
+ self._parent._exit_child(failed=failed)
83
+
84
+ def _enter_child(self, *, cleanup):
85
+ with self._lock:
86
+ actor = self._borrow_thread if self._borrow_thread is not None else self._thread
87
+ if (self._token is None or _CURRENT.get() is not self
88
+ or actor != threading.get_ident() or self._operations):
89
+ raise OwnershipRefused("Another operation owns the containing workspace")
90
+ if not cleanup:
91
+ self.require_active()
92
+ self.require_idle(ignore_children=True)
93
+ self._operations += 1
94
+
95
+ def _exit_child(self, *, failed):
96
+ with self._lock:
97
+ self._operations -= 1
98
+ if failed:
99
+ self._revoked = True
100
+
101
+ def track_child(self, dependency):
102
+ with self._lock:
103
+ self.require_active()
104
+ self.track(dependency, "independent prepared child")
105
+ self._children[id(dependency)] = dependency
106
+
107
+ def finish_use(self):
108
+ with self._lock:
109
+ self._revoked = True
110
+ self.require_quiescent()
111
+
112
+ def prepare_cleanup(self):
113
+ with self._lock:
114
+ self.require_quiescent()
115
+ self._revoked = True
116
+
117
+ def require_active(self):
118
+ with self._lock:
119
+ actor = self._borrow_thread if self._borrow_thread is not None else self._thread
120
+ if (self._recovery_thread == threading.get_ident()
121
+ and _CURRENT.get() is self):
122
+ return
123
+ if self._revoked and self._resources:
124
+ # Revoked with resources unresolved (an interrupted launch): raise
125
+ # them as a pending cleanup for the caller, not a plain refusal.
126
+ labels = ", ".join(label for _, label in self._resources.values())
127
+ error = OwnershipRefused(
128
+ "The workspace use was revoked while these resources are unresolved: "
129
+ + labels + ". Clean them up before using the workspace again")
130
+ error._langadapter_execution_scope = self
131
+ error._langadapter_resources = tuple(
132
+ resource for resource, _ in self._resources.values())
133
+ raise error
134
+ current = threading.get_ident()
135
+ if (self._revoked or self._token is None or _CURRENT.get() is not self
136
+ or (actor != current and current not in self._lent)):
137
+ raise OwnershipRefused("Execution requires the current workspace use on its owning thread")
138
+
139
+ @contextlib.contextmanager
140
+ def lend(self):
141
+ """Admit worker threads (``admit``) as the use's actors for the block,
142
+ which the use's actor opens and which ends only once they are done."""
143
+ with self._lock:
144
+ self.require_active()
145
+ if self._lending:
146
+ raise OwnershipRefused("The workspace use is already lent to worker threads")
147
+ self._lending = True
148
+ try:
149
+ yield
150
+ finally:
151
+ with self._lock:
152
+ self._lending = False
153
+ self._lent.clear()
154
+
155
+ def admit(self):
156
+ """Run the current thread as one of the use's actors until ``dismiss``."""
157
+ with self._lock:
158
+ if not self._lending:
159
+ raise OwnershipRefused("The workspace use lends no worker threads now")
160
+ self._lent.add(threading.get_ident())
161
+
162
+ def dismiss(self):
163
+ with self._lock:
164
+ self._lent.discard(threading.get_ident())
165
+
166
+ @contextlib.contextmanager
167
+ def operation(self, *, recovery=False, idle=False):
168
+ token = None
169
+ parent = None
170
+ failed = False
171
+ with self._lock:
172
+ if (recovery and self._borrow_thread is None and self._recovery_thread is None
173
+ and (self._token is None or (self._revoked and _CURRENT.get() is self
174
+ and self._thread == threading.get_ident()))):
175
+ current = _CURRENT.get()
176
+ if self._operations or current not in (None, self, self._parent):
177
+ raise OwnershipRefused("Another operation owns this cleanup scope")
178
+ if current is not None and current is self._parent:
179
+ current._enter_child(cleanup=True)
180
+ parent = current
181
+ self._recovery_thread = threading.get_ident()
182
+ token = _CURRENT.set(self)
183
+ else:
184
+ self.require_active()
185
+ if not recovery:
186
+ self._refuse_failed_session()
187
+ if idle:
188
+ self.require_idle()
189
+ self._operations += 1
190
+ try:
191
+ yield
192
+ except BaseException:
193
+ failed = True
194
+ raise
195
+ finally:
196
+ with self._lock:
197
+ self._operations -= 1
198
+ if token is not None:
199
+ _CURRENT.reset(token)
200
+ self._recovery_thread = None
201
+ if parent is not None:
202
+ parent._exit_child(failed=failed)
203
+
204
+ def _refuse_failed_session(self):
205
+ """Refuse an ordinary operation while a registered mutation session's
206
+ cleanup has failed: it may have left the target mutated or its
207
+ workers running. The session is the refusal's ``cleanup_handle``,
208
+ whose ``close()`` retries as a recovery."""
209
+ from langadapter.mutation import MutationSession
210
+ with self._lock:
211
+ for resource, label in self._resources.values():
212
+ if isinstance(resource, MutationSession) and resource._cleanup_failure is not None:
213
+ error = OwnershipRefused(
214
+ f"The {label}'s cleanup failed. Close it before other operations in this use")
215
+ error.cleanup_handle = resource
216
+ raise error
217
+
218
+ def register_persistent(self, owner, resources):
219
+ """Bind native handles acquired in this scope to their mutation session."""
220
+ with self._lock:
221
+ self.require_active()
222
+ from langadapter.mutation import MutationSession
223
+ if not isinstance(owner, MutationSession) or self._resources.get(id(owner), (None,))[0] is not owner:
224
+ raise OwnershipRefused("Persistent commands require their registered mutation session")
225
+ for resource in resources:
226
+ entry = self._resources.get(id(resource))
227
+ if entry is None and getattr(resource, "_langadapter_command_disposed", False) is True:
228
+ continue
229
+ if entry is None or entry[0] is not resource or isinstance(resource, _Ticket):
230
+ raise OwnershipRefused("Persistent command is not acquired in this execution scope")
231
+ self._persistent[id(resource)] = (resource, owner)
232
+
233
+ def require_idle(self, *, ignore_children=False):
234
+ from langadapter.mutation import MutationSession
235
+ with self._lock:
236
+ if self._operations:
237
+ raise OwnershipRefused("Workspace has an active execution operation")
238
+ for resource, label in self._resources.values():
239
+ if ignore_children and self._children.get(id(resource)) is resource:
240
+ continue
241
+ owner = resource if isinstance(resource, MutationSession) else (
242
+ self._persistent.get(id(resource), (None, None))[1])
243
+ if (not isinstance(owner, MutationSession) or
244
+ self._resources.get(id(owner), (None,))[0] is not owner or
245
+ owner._operation.locked() or owner._cleanup_failure is not None):
246
+ error = OwnershipRefused("Workspace still owns unresolved resources: " + label)
247
+ error._langadapter_execution_scope = self
248
+ error._langadapter_resources = (resource,)
249
+ raise error
250
+
251
+ def _only_retained_sessions(self):
252
+ """Whether every resource left is a registered, idle mutation session or
253
+ one of its commands, whose failed cleanup its own handle retries."""
254
+ from langadapter.mutation import MutationSession
255
+ with self._lock:
256
+ if self._operations:
257
+ return False
258
+ for resource, _ in self._resources.values():
259
+ owner = resource if isinstance(resource, MutationSession) else (
260
+ self._persistent.get(id(resource), (None, None))[1])
261
+ if (not isinstance(owner, MutationSession)
262
+ or self._resources.get(id(owner), (None,))[0] is not owner
263
+ or owner._operation.locked()):
264
+ return False
265
+ return True
266
+
267
+ @contextlib.contextmanager
268
+ def borrow(self, validate):
269
+ primary = None
270
+ with self._lock:
271
+ if self._revoked or self._token is None or self._borrow_thread is not None:
272
+ raise OwnershipRefused("Prepared worker requires an idle active use")
273
+ if _CURRENT.get() not in (None, self):
274
+ raise OwnershipRefused("Another execution scope is active on this worker")
275
+ self._refuse_failed_session()
276
+ self.require_idle()
277
+ self._borrow_thread = threading.get_ident()
278
+ token = _CURRENT.set(self)
279
+ try:
280
+ try:
281
+ validate()
282
+ except BaseException:
283
+ with self._lock:
284
+ self._revoked = True
285
+ raise
286
+ yield
287
+ except BaseException as error:
288
+ primary = error
289
+ raise
290
+ finally:
291
+ try:
292
+ self.require_idle()
293
+ except BaseException as cleanup:
294
+ # A session keeping resources after a failed or interrupted
295
+ # cleanup holds the use, refusing new work, only until its own
296
+ # close() succeeds. Anything else revokes the use.
297
+ if not self._only_retained_sessions():
298
+ with self._lock:
299
+ self._revoked = True
300
+ if primary is None:
301
+ raise
302
+ primary._langadapter_execution_scope = self
303
+ primary._langadapter_scope_cleanup_error = cleanup
304
+ if hasattr(primary, "add_note"):
305
+ try:
306
+ primary.add_note(str(cleanup))
307
+ except BaseException:
308
+ pass
309
+ finally:
310
+ with self._lock:
311
+ _CURRENT.reset(token)
312
+ self._borrow_thread = None
313
+
314
+ def track(self, resource, label):
315
+ with self._lock:
316
+ if self._token is not None or self._recovery_thread is not None:
317
+ self.require_active()
318
+ resource._langadapter_execution_scope = self
319
+ self._resources[id(resource)] = (resource, label)
320
+ return resource
321
+
322
+ def reserve_launch(self):
323
+ with self._lock:
324
+ self.require_active()
325
+ ticket = _Ticket()
326
+ ticket._langadapter_execution_scope = self
327
+ self._resources[id(ticket)] = (ticket, "unfinished native launch")
328
+ return ticket
329
+
330
+ def acquired(self, ticket, resource):
331
+ with self._lock:
332
+ if self._resources.get(id(ticket), (None,))[0] is not ticket:
333
+ raise OwnershipRefused("Native acquisition has no current launch reservation")
334
+ # Admission preceded acquisition. Revocation must not drop its handle.
335
+ resource._langadapter_execution_scope = self
336
+ self._resources[id(resource)] = (resource, "owned command")
337
+ del self._resources[id(ticket)]
338
+
339
+ def completed(self, resource):
340
+ with self._lock:
341
+ entry = self._resources.get(id(resource))
342
+ if entry is not None and entry[0] is resource:
343
+ del self._resources[id(resource)]
344
+ self._persistent.pop(id(resource), None)
345
+ self._children.pop(id(resource), None)
346
+
347
+ def require_quiescent(self, *, current_operation=False):
348
+ with self._lock:
349
+ if current_operation:
350
+ self.require_active()
351
+ elif self._borrow_thread is not None or self._operations:
352
+ error = OwnershipRefused("Workspace has an active worker or operation")
353
+ error._langadapter_execution_scope = self
354
+ raise error
355
+ if not self._resources:
356
+ return
357
+ labels = ", ".join(label for _, label in self._resources.values())
358
+ error = OwnershipRefused("Workspace still owns unresolved resources: " + labels)
359
+ error._langadapter_execution_scope = self
360
+ error._langadapter_resources = tuple(resource for resource, _ in self._resources.values())
361
+ raise error
362
+
363
+
364
+ @contextlib.contextmanager
365
+ def operation(context=None):
366
+ binding = context._prepared_copy_binding if context is not None else None
367
+ scope = binding.scope if binding is not None else _CURRENT.get()
368
+ with scope.operation() if isinstance(scope, _Scope) else contextlib.nullcontext():
369
+ if context is not None:
370
+ context._require_execution()
371
+ yield
372
+
373
+
374
+ def track(resource, label):
375
+ scope = _CURRENT.get()
376
+ return scope.track(resource, label) if scope is not None else resource
377
+
378
+
379
+ def completed(resource):
380
+ scope = getattr(resource, "_langadapter_execution_scope", None)
381
+ if isinstance(scope, _Scope):
382
+ scope.completed(resource)
383
+
384
+
385
+ def unresolved_command(error):
386
+ """The command owner ``error`` carries while its process may still run,
387
+ else None. The acquired command's own disposal proof is authoritative:
388
+ the disposed marker, or a Linux command whose control closed."""
389
+ from langadapter._linux_command import _Command
390
+
391
+ for name in ("_langadapter_linux_command", "_langadapter_command"):
392
+ owner = getattr(error, name, None)
393
+ if owner is not None and not (
394
+ getattr(owner, "_langadapter_command_disposed", False) is True
395
+ or (isinstance(owner, _Command) and getattr(owner, "_closed", False) is True)):
396
+ return owner
397
+ return None
398
+
399
+
400
+ def reraise_unresolved(error):
401
+ """Re-raise ``error`` rather than turn it into a value-only outcome when it
402
+ carries an unresolved command (``unresolved_command``) or its scope has an
403
+ unfinished launch. An open session in the scope does not count."""
404
+ if unresolved_command(error) is not None:
405
+ raise error
406
+ scope = getattr(error, "_langadapter_execution_scope", None)
407
+ if isinstance(scope, _Scope):
408
+ with scope._lock:
409
+ unfinished = any(isinstance(resource, _Ticket)
410
+ for resource, _ in scope._resources.values())
411
+ if unfinished:
412
+ raise error
413
+
414
+
415
+ def reserve_launch():
416
+ scope = _CURRENT.get()
417
+ return scope.reserve_launch() if scope is not None else None
418
+
419
+
420
+ def acquired(ticket, resource):
421
+ if ticket is not None:
422
+ scope = ticket._langadapter_execution_scope
423
+ scope.acquired(ticket, resource)
424
+
425
+
426
+ def _command_owner(error):
427
+ linux_owner = getattr(error, "_langadapter_linux_command", None)
428
+ return linux_owner if linux_owner is not None else getattr(error, "_langadapter_command", None)
429
+
430
+
431
+ def failed_launch(ticket, error):
432
+ if ticket is None:
433
+ return
434
+ scope = ticket._langadapter_execution_scope
435
+ if _command_owner(error) is not None:
436
+ running = unresolved_command(error)
437
+ if running is None:
438
+ scope.completed(ticket)
439
+ else:
440
+ acquired(ticket, running)
441
+ error._langadapter_execution_scope = scope
langadapter/_host.py ADDED
@@ -0,0 +1,73 @@
1
+ """The hosts LangAdapter runs a project's commands on.
2
+
3
+ Windows (a job object) and Linux (its supervisor) supervise a command and its
4
+ descendants and confirm that every process it started has ended. Other POSIX
5
+ systems, macOS above all, run a command in its own process group
6
+ (``langadapter._process_tree``), ending the group without confirming cleanup.
7
+ Hosts without processes (emscripten, wasi) run no command. Importing
8
+ LangAdapter and the source operations, which run none, work on every host.
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ import sys
14
+ from typing import Optional
15
+
16
+
17
+ #: The platforms without processes, where no command runs.
18
+ _NO_PROCESSES = ("emscripten", "wasi")
19
+
20
+
21
+ def confirms_cleanup() -> bool:
22
+ """Whether this host confirms that a command's processes all ended (Windows, Linux)."""
23
+ return sys.platform == "win32" or sys.platform.startswith("linux")
24
+
25
+
26
+ def runs_commands() -> bool:
27
+ """Whether this host can run a project's commands: Windows and Linux,
28
+ and the other POSIX systems in a command's process group."""
29
+ return confirms_cleanup() or sys.platform not in _NO_PROCESSES
30
+
31
+
32
+ #: The longest working directory Windows starts a command in, even with long
33
+ #: paths enabled: 258 characters start, 259 are refused (WinError 267).
34
+ WINDOWS_WORKING_DIR_LIMIT = 258
35
+
36
+
37
+ def working_dir_limit():
38
+ """The longest working directory this host starts a command in, None if unlimited."""
39
+ return WINDOWS_WORKING_DIR_LIMIT if sys.platform == "win32" else None
40
+
41
+
42
+ def working_dir_issue(working_dir) -> str:
43
+ """Why this host starts no command in ``working_dir`` (past its limit), or ""."""
44
+ limit = working_dir_limit()
45
+ if working_dir is None or limit is None or len(str(working_dir)) <= limit:
46
+ return ""
47
+ return (f"the working directory {working_dir} is {len(str(working_dir))} characters long, and Windows "
48
+ f"starts no command in a directory longer than {limit} characters, even with long "
49
+ f"paths enabled: run from a shorter directory")
50
+
51
+
52
+ def refusal() -> str:
53
+ """Why this host runs no command, and what works on it."""
54
+ return (f"LangAdapter runs a project's commands on Windows and Linux, where it "
55
+ f"supervises them and confirms that every process a command started has "
56
+ f"ended, and on other POSIX systems such as macOS in the command's own "
57
+ f"process group, without that confirmation. {sys.platform} has no "
58
+ f"processes to run a command in. Importing LangAdapter and its source "
59
+ f"operations, which run no command, work here, with a context created "
60
+ f"without an interpreter.")
61
+
62
+
63
+ def started_file(path: str) -> Optional[str]:
64
+ """The file a process start runs for ``path``: the path itself, or on
65
+ Windows, for a path with a directory whose file name has no extension,
66
+ the name with .exe, which process creation adds. None when neither is a
67
+ file."""
68
+ name = os.path.basename(path)
69
+ candidates = [path]
70
+ if (os.name == "nt" and os.path.dirname(path) and not os.path.splitext(name)[1]
71
+ and not name.endswith(".")):
72
+ candidates.append(path + ".exe")
73
+ return next((candidate for candidate in candidates if os.path.isfile(candidate)), None)