Skip to content

[CLIENT-4702] Convert docstring code examples to doctest format and validate them#1047

Draft
juliannguyen4 wants to merge 120 commits into
devfrom
CLIENT-4702-doc-validate-code-examples-using-doctest
Draft

[CLIENT-4702] Convert docstring code examples to doctest format and validate them#1047
juliannguyen4 wants to merge 120 commits into
devfrom
CLIENT-4702-doc-validate-code-examples-using-doctest

Conversation

@juliannguyen4
Copy link
Copy Markdown
Collaborator

@juliannguyen4 juliannguyen4 commented Apr 26, 2026

Extra Changes

  • Replaced the code example for client.udf_put(), client.udf_list(), and client.udf_remove() with a higher level code example for the "User Defined Functions" section. The latter is verified to run without errors using doctest and demonstrates the outcomes of those API calls.
  • Add ability to copy code examples while also stripping any characters that aren't valid Python syntax
  • Remove bad code example for HyperLogLog class. Normally, HyperLogLog bins are created using operations or expressions.

Known issues introduced here

  • The testsetup code block isn't visible by default, so we have to have a duplicate codeblock to show that code. This introduces some technical debt, and having the testsetup code visible is a missing feature in Sphinx

Trade-offs

  • Code examples are harder to run because the Python REPL gives a syntax error when it encounters >>>. As a workaround, developers have to use IPython REPL with their specific desired version of Python to copy and run the code examples

Manual testing

TODO

  • aerospike needs to be compiled before running doctest
  • Copying doctest formatted code into Python REPL causes syntax errors related to >>> Moved to a different format from doctest
  • client.info_all() output format is kinda weird...

Out of scope

  • Doctest teardown

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Apr 26, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.46%. Comparing base (5bc339b) to head (fb0850f).

Additional details and impacted files
@@           Coverage Diff           @@
##              dev    #1047   +/-   ##
=======================================
  Coverage   84.46%   84.46%           
=======================================
  Files          99       99           
  Lines       14088    14090    +2     
=======================================
+ Hits        11899    11901    +2     
  Misses       2189     2189           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…the TLS test which needs to be run with a different job
…uple that contains the line number where it happened which isn't important
… run boilerplate code before each example in client.rst
…y code example. It doesn't seem possible with doctest + unittest
…plicate code block that shows the testblock code.
…te-code-examples-using-doctest

# Conflicts:
#	.github/workflows/smoke-tests.yml
…ode example doesn't show the MAC address anymore.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants