dask / dask/distributed

Should `utils_test.py` be considered public API?

Open
#6,806 14 comments 0 reactions 0 assignees View on GitHub
discussion
Dominant language
Python
Stars
1.7k
Forks
778
Avg merge
2h 50m
Merged PRs (30d)
3

Description

We currently expose a number of functions and fixtures in `distributed.utils_test`. While I would consider these implementation details of our tests, and not part of any stable user-facing API, other projects, including `dask/dask` rely on them for their test suites (https://github.com/dask/dask/blob/ac74939697c328bd6456aa9fad7d9520328db6e5/dask/tests/test_distributed.py#L11-L14, #5300, #6775, https://github.com/dask/distributed/pull/6802#pullrequestreview-1052813812). This creates friction between the stability requirements of downstream users and our ability to adjust the contents of `utils_test` to fit our internal testing needs. For example, we cannot easily move functionality around without breaking things for downstream users (https://github.com/dask/distributed/pull/6802#pullrequestreview-1052813812).

This leads me to several questions:
**Should the contents of `utils_test.py` be considered part of the public API?**

If so:
* What guarantees are we willing to make around API stability?
* How do we want to test/enforce those?
* Which parts should be considered public API?
* For example, should we only expose context managers/functions, but not fixtures?

If not:
* How do we make this clear and discourage users from importing them?
* How do we deal with projects that already import them?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.