Fix 3226: add docstrings, clean up check_type_completeness.py

[CheViana]

Fixes #3226.

• add docstring to types that are mentioned in public interface (suggestions for better text/wording/content are very welcome)
• remove empty _check_type_completeness.json file
• clean up ignore list in check_type_completeness.py
• add comments about why some types in check_type_completeness.py are throwing exception when we're trying to introspect them

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00000%. Comparing base (582223a) to head (55e796b).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@               Coverage Diff               @@
##                 main        #3523   +/-   ##
===============================================
  Coverage   100.00000%   100.00000%           
===============================================
  Files             128          128           
  Lines           19474        19474           
  Branches         1323         1322    -1     
===============================================
  Hits            19474        19474           

Files with missing lines	Coverage Δ
src/trio/_core/_io_epoll.py	100.00000% <ø> (ø)
src/trio/_core/_io_kqueue.py	100.00000% <ø> (ø)
src/trio/_core/_io_windows.py	100.00000% <ø> (ø)
src/trio/_core/_local.py	100.00000% <100.00000%> (ø)
src/trio/_core/_run.py	100.00000% <ø> (ø)
src/trio/_file_io.py	100.00000% <ø> (ø)
src/trio/_socket.py	100.00000% <ø> (ø)
src/trio/_subprocess.py	100.00000% <ø> (ø)
src/trio/_sync.py	100.00000% <ø> (ø)
src/trio/_unix_pipes.py	100.00000% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[CheViana]

I believe there's a bug-typo in pypy which made some of the tests fail - pypy/pypy#5594 . Tests are fragile for when new symbols appear. I added exclude for "missing" symbol in test_exports.py until bug is fixed. It's not really a missing symbol, it's a symbol pypy adds with typo.

[CheViana]

I think this is ready for review @A5rocks @CoolCat467 . new docstrings wording could probably be better.
was getting some unrelated to this PR test failures because of recent major pypy release. pinned pypy version for win. I can pin it for linux too, although new version mostly works on linux.

[A5rocks]

Thank you!! I did a quick skim through, though I wasn't very thorough and probably some of my comments are incorrect.

I think some of your new docstrings are invalid RST, but that's fine because the only thing that will show them is Pyright, I guess? (or maybe ty too...).

[A5rocks]

I made an issue about cryptography failing to install, see pyca/cryptography#15735

IMO just ignore that CI error for now!

[CheViana]

I made an issue about cryptography failing to install, see pyca/cryptography#15735

IMO just ignore that CI error for now!

I believe cryptography 50.0.2 has a correct wheel https://pypi.org/project/cryptography/#cryptography-50.0.2-pp311-pypy311_pp80-win_amd64.whl

[A5rocks]

Feel free to make another PR that bumps our cryptography version to that! I didn't notice.

Edit: done in #3525

[CheViana]

@A5rocks I have updated docstings per comments. Disclosure that I used Claude for format checks, and for proof-reading. Please re-review/approve/merge .

[CoolCat467]

Changing the way CI works makes me feel uneasy and feels outside the scope of this pull request. I would much prefer if you factored that out into a separate pull request.

[CheViana]

Changing the way CI works makes me feel uneasy and feels outside the scope of this pull request. I would much prefer if you factored that out into a separate pull request.

I didn't change how ci works (if you're refering to recent commits to ci.yml?). that was done by some other PRs that got merged into main and then merged here. I don't see their changes in https://github.com/python-trio/trio/pull/3523/changes :

cc @CoolCat467

I removed not used code from src\trio_tests\check_type_completeness.py that's all

I can revert check_type_completeness.py to what'as now in main and bring back empty json file, is that the case?

[CheViana]

Changing the way CI works makes me feel uneasy and feels outside the scope of this pull request. I would much prefer if you factored that out into a separate pull request.

done

[CoolCat467]

Yes, it was the ci.yml changes, I saw that in the diff earlier, but yes, I agree this is fine.

On other notes, +1 on one of the review comments earlier

IIRC our convention for docstrings is:

"""Summary

Longer description
"""

(this probably applies elsewhere in this PR, but I'll only leave a comment this time)

I see a couple docstrings that are yet to follow this. I haven't looked at the wording super closely quite yet, will review more closely later.