Path decorators: allow empty docstrings to support embedded Python

[ameily]

I am developing an application that runs on the Windows embedded Python package. It appears that the embedded Python standard library does not include docstrings which means an unhandled exception is raised when importing trio because of a couple assert X.__doc__ is not None statements. This PR makes it so __doc__ is allowed to be None.

To test, I am using Python Windows Embedded 64-bit 3.11.8 package. I wrote a small script to show that __doc__ is None on every Path function:

import inspect
from pathlib import Path

for name in dir(Path):
    if name.startswith("_"):
        continue

    attr = getattr(Path, name)
    if inspect.isfunction(attr) or inspect.ismethod(attr):
        if attr.__doc__ is None:
            print(f"Path.{name}.__doc__ is None")

When I run this through embedded Python I see every function in Path has no docstring.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.62%. Comparing base (e87dc46) to head (b519645).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2979      +/-   ##
==========================================
- Coverage   99.63%   99.62%   -0.01%     
==========================================
  Files         117      117              
  Lines       17598    17602       +4     
  Branches     3171     3174       +3     
==========================================
+ Hits        17533    17536       +3     
- Misses         46       47       +1     
  Partials       19       19              

Files	Coverage Δ
src/trio/_path.py	100.00% <100.00%> (ø)
src/trio/_tests/test_path.py	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

[A5rocks]

IMO we shouldn't set the docstring if there isn't one, rather than acting as though the docstring is blank.

[TeamSpen210]

That would make sense yes. This might be tricky to test for though - Trio can't work in -OO mode, because pycparser (imported from cffi) needs docstrings to work. But it would be fine if only the standard library is stripped.

[A5rocks]

Sorry, I should have marked my previous comment properly. Here it is just as reference:

IMO we shouldn't set the docstring if there isn't one, rather than acting as though the docstring is blank.

[jakkdl]

Could add tests which monkeypatch Path and then runs the decorator on them, which would appease codecov.

[A5rocks]

I added a test case cause it can be annoying to make them. cc @jakkdl does it look good?

(the only iffy bit is passing a sync function to a function that assumes it is async -- but it's not like we run it and we can update that if we ever require passed in functions to satisfy inspect.iscoroutinefunction)

[A5rocks]

@ameily I'm super flakey on these (so you can ignore this if you want) but you don't have a changelog attached! Might be nice to have that.

[jakkdl]

I added a test case cause it can be annoying to make them. cc @jakkdl does it look good?

(the only iffy bit is passing a sync function to a function that assumes it is async -- but it's not like we run it and we can update that if we ever require passed in functions to satisfy inspect.iscoroutinefunction)

looks great! (other than needing a # pragma: no cover :P)

[trio-bot]

Hey @ameily, it looks like that was the first time we merged one of your PRs! Thanks so much! 🎉 🎂

If you want to keep contributing, we'd love to have you. So, I just sent you an invitation to join the python-trio organization on Github! If you accept, then here's what will happen:

• Github will automatically subscribe you to notifications on all our repositories. (But you can unsubscribe again if you don't want the spam.)

• You'll be able to help us manage issues (add labels, close them, etc.)

• You'll be able to review and merge other people's pull requests

• You'll get a [member] badge next to your name when participating in the Trio repos, and you'll have the option of adding your name to our member's page and putting our icon on your Github profile (details)

If you want to read more, here's the relevant section in our contributing guide.

Alternatively, you're free to decline or ignore the invitation. You'll still be able to contribute as much or as little as you like, and I won't hassle you about joining again. But if you ever change your mind, just let us know and we'll send another invitation. We'd love to have you, but more importantly we want you to do whatever's best for you.

If you have any questions, well... I am just a humble Python script, so I probably can't help. But please do post a comment here, or in our chat, or on our forum, whatever's easiest, and someone will help you out!