Embedded doctests vs. dedicated pytest modules for algorithm edge cases

The Python repository emphasizes the use of doctests within function docstrings to provide both documentation and executable verification. This approach ensures that basic usage examples remain synchronized with the implementation during CI via pytest --doctest-modules.

However, when implementing complex sorting or mathematical algorithms, a clear trade-off emerges between maintaining this stylistic consistency and ensuring robust code coverage. While doctests excel at demonstrating standard usage, they are often ill-suited for testing edge cases such as large datasets, negative values, or specific boundary conditions without cluttering the documentation.

The current contribution guidelines prioritize doctests for educational clarity, but do not explicitly define the threshold for when a contributor must supplement these with a dedicated pytest test file.

What specific complexity metrics or input varieties should warrant a dedicated test module over embedded doctests? How should the project balance the need for readable documentation with the requirement for exhaustive edge-case verification?