Metadata-Version: 2.5
Name: langadapter
Version: 0.1.0
Summary: Test execution, coverage, mutation and timing observations for a configured project
Project-URL: Homepage, https://github.com/k-kammler/langadapter
Project-URL: Repository, https://github.com/k-kammler/langadapter
Project-URL: Documentation, https://k-kammler.github.io/langadapter/
Project-URL: Issues, https://github.com/k-kammler/langadapter/issues
Author: Kevin Kammler
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: coverage,junit,mutation-testing,pytest,test-execution,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: lizard<2,>=1.17
Requires-Dist: packaging>=22
Requires-Dist: tomli-w<2,>=1.0
Requires-Dist: tree-sitter-java<0.24,>=0.23.5
Requires-Dist: tree-sitter-python<0.26,>=0.25
Requires-Dist: tree-sitter<0.26,>=0.25
Provides-Extra: c
Requires-Dist: gcovr<9,>=8.7; extra == 'c'
Requires-Dist: setuptools>=70; extra == 'c'
Requires-Dist: tree-sitter-c<0.25,>=0.24.2; extra == 'c'
Provides-Extra: dev
Requires-Dist: anyio<5,>=4; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: coverage==7.16.2; (python_version >= '3.14') and extra == 'dev'
Requires-Dist: coverage==7.6.8; (python_version < '3.14') and extra == 'dev'
Requires-Dist: gcovr<9,>=8.7; extra == 'dev'
Requires-Dist: pytest-benchmark<6,>=5; extra == 'dev'
Requires-Dist: pytest-cov<7,>=6; extra == 'dev'
Requires-Dist: pytest-xdist<4,>=3; extra == 'dev'
Requires-Dist: pytest==8.1.1; (python_version < '3.14') and extra == 'dev'
Requires-Dist: pytest==8.4.2; (python_version >= '3.14') and extra == 'dev'
Requires-Dist: ruff<1,>=0.16; extra == 'dev'
Requires-Dist: setuptools>=70; extra == 'dev'
Requires-Dist: tree-sitter-c<0.25,>=0.24.2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: griffe-sphinx<0.4,>=0.3.1; extra == 'docs'
Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]<1,>=0.26; extra == 'docs'
Requires-Dist: pymdown-extensions<12,>=10; extra == 'docs'
Description-Content-Type: text/markdown

# LangAdapter

[![PyPI version](https://img.shields.io/pypi/v/langadapter)](https://pypi.org/project/langadapter/)
[![Python versions](https://img.shields.io/pypi/pyversions/langadapter)](https://pypi.org/project/langadapter/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/k-kammler/langadapter/blob/main/LICENSE)
[![Documentation](https://github.com/k-kammler/langadapter/actions/workflows/docs.yml/badge.svg)](https://k-kammler.github.io/langadapter/)

LangAdapter runs a project's own test, coverage, mutation and timing tools
and reports what they observed as typed results. It supports Python and Java
projects, locally and in a running Linux container you provide, and C projects
on Linux. It works with any test suite, written by people or generated, and
needs no model access.

## Install

The library needs Python 3.10 or newer. It is supported on Windows and
Linux, the systems where it confirms that a command and everything it
started have ended. On macOS it is expected to work, but this release has
not run on a Mac:
[Tested environments](https://k-kammler.github.io/langadapter/reference/tested-environments/)
says what is known. On macOS and other POSIX systems it runs each command
in its own process group and cannot confirm that every descendant ended, so
it warns and records that in its observations. Install it into the Python
environment of the program that uses it, such as a virtual environment.
On Ubuntu 24.04, also in WSL, Python is `python3`, and a virtual
environment needs the package `python3-venv`:

```
sudo apt-get install python3-venv
python3 -m venv .venv
.venv/bin/python -m pip install langadapter
```

On Windows:

```
py -m venv .venv
.venv\Scripts\python -m pip install langadapter
```

In a source checkout, `.venv/bin/python -m pip install .` installs it from
the checkout. For C projects, install it with the extra for C:
`.venv/bin/python -m pip install "langadapter[c]"`. On Windows the
environment's Python is `.venv\Scripts\python`.

The project under test keeps its own runtime and tools, which
[Getting started](https://k-kammler.github.io/langadapter/getting-started/)
names for each language. On Ubuntu 24.04 on x86_64, `langadapter toolchains`
installs them, as
[Install the toolchains](https://k-kammler.github.io/langadapter/guide/toolchains/)
describes.

## Example

Run a Python project's tests with the project's interpreter and read the
result:

```python
import langadapter as la
from langadapter.runs import SuiteRunRequest

project = "path/to/project"
project_python = "path/to/project/.venv/bin/python"  # path/to/project/.venv/Scripts/python.exe on Windows
context = la.ProjectContext(root=project, interpreter=la.Interpreter(path=project_python))
adapter = la.create("python", context)
suite = la.Suite(project, ("tests/test_example.py",))
result = adapter.tests.run_suite(SuiteRunRequest(suite, timeout_s=120))
print(result.outcome, result.counts.passed, "passed")
```

If the project has a `conftest.py` in its directory or in `tests`, list it as a
setup file, for example
`la.Suite(project, ("tests/test_example.py",), ("tests/conftest.py",))`. A run
refuses a suite that leaves out a setup file pytest would load.

Every result carries an outcome such as `completed`, `test_failures`,
`missing_setup` or `unsupported`, and a reason, as
[Outcomes](https://k-kammler.github.io/langadapter/explanation/outcomes/)
describes.

## Documentation

The documentation site is <https://k-kammler.github.io/langadapter/>.

- [Getting started](https://k-kammler.github.io/langadapter/getting-started/):
  install, run a suite and read its result. Start here.
- [Python](https://k-kammler.github.io/langadapter/guide/python/),
  [Java](https://k-kammler.github.io/langadapter/guide/java/) and
  [C](https://k-kammler.github.io/langadapter/guide/c/) projects: the guide
  for each language.
- [Mutation sessions](https://k-kammler.github.io/langadapter/guide/mutation-sessions/)
  and [timing](https://k-kammler.github.io/langadapter/guide/timing/): a
  suite measured against the mutants of one source file, and timed.
- [Extension points](https://k-kammler.github.io/langadapter/extending/):
  extending the library at each of them, such as a new language adapter or
  metric provider, with
  [Add a language](https://k-kammler.github.io/langadapter/extending/add-a-language/).
- [API reference](https://k-kammler.github.io/langadapter/reference/): generated
  from the modules and their docstrings.

The guides also cover containers, source analysis and settings, and the
explanations cover outcomes, prepared copies of a project and environment
selection. The guides are also in the repository's
[docs directory](https://github.com/k-kammler/langadapter/tree/v0.1.0/docs)
and installed with the package under `share/doc/langadapter/docs`, without
the API reference, which is on the site only: in the installed copy,
Python's `help()` shows each name's documentation. Building the site
yourself is described in
[CONTRIBUTING.md](https://github.com/k-kammler/langadapter/blob/v0.1.0/CONTRIBUTING.md).
What the library depends on and downloads, with each license, is in
[THIRD_PARTY_NOTICES.md](https://github.com/k-kammler/langadapter/blob/v0.1.0/THIRD_PARTY_NOTICES.md).

## License

MIT, see [LICENSE](https://github.com/k-kammler/langadapter/blob/v0.1.0/LICENSE).
