Skip to content

bpo-32208: update threading.Semaphore docs and add unit test #4709

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Dec 7, 2017

Conversation

vitiral
Copy link
Contributor

@vitiral vitiral commented Dec 5, 2017

Note: this is my first PR and I'm not sure if doc fixes which apply to all versions of the docs (including python2.7) count as a "backport" PR

This attempts to fix https://bugs.python.org/issue32208

https://bugs.python.org/issue32208

@the-knights-who-say-ni
Copy link

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA (this might be simply due to a missing "GitHub Name" entry in your b.p.o account settings). This is necessary for legal reasons before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

Thanks again to your contribution and we look forward to looking at it!

@vitiral
Copy link
Contributor Author

vitiral commented Dec 5, 2017

During testing I also found an exception with the language "returns nothing" when it actually returns True.

@vitiral
Copy link
Contributor Author

vitiral commented Dec 5, 2017

the PSF should be signed!

@vitiral
Copy link
Contributor Author

vitiral commented Dec 5, 2017

I'm not sure what to do for the rest of the issues. I got this in the travis build:

Warning, treated as error:

/home/travis/build/python/cpython/Doc/library/threading.rst:706:Unexpected indentation.

make[1]: *** [build] Error 1

make[1]: Leaving directory `/home/travis/build/python/cpython/Doc'

Suspicious check complete; look for any errors in the above output or in build/suspicious/suspicious.csv.  If all issues are false positives, append that file to tools/susp-ignored.csv.

make: *** [suspicious] Error 1

@vitiral vitiral changed the title fix issue32208: update threading.Semaphore docs and add unit test fix #32208: update threading.Semaphore docs and add unit test Dec 5, 2017
Copy link
Contributor

@asvetlov asvetlov left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've fixed docs formatting but test should be improved


start = time.time()
while th1.is_alive():
assert time.time() - start < 0.5
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use unittest methods like self.assertEqual() and family: https://docs.python.org/3/library/unittest.html#assert-methods

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are tests for semaphores in BaseSemaphoreTests in Lib/test/lock_tests.py. You should look there and add any tests there as needed instead.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(but everything seems to be tested already there, except the return value of blocking semaphores which wasn't really documented anyway)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't see those, thanks for pointing it out.

I've removed the "doc tests" and added testing the return type to the base semaphore tests. Let me know if that looks good!

@bedevere-bot
Copy link

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

@asvetlov
Copy link
Contributor

asvetlov commented Dec 7, 2017

Sorry, I don't see your card in https://bugs.python.org/user?username=&realname=&github=vitiral&%40action=search
Are you sure that you've registered on bugs.python.org and signed CLA?

@vitiral
Copy link
Contributor Author

vitiral commented Dec 7, 2017

@asvetlov I forgot to put in my "github user name". Should be in there now!

@asvetlov asvetlov changed the title fix #32208: update threading.Semaphore docs and add unit test bpo-32208: update threading.Semaphore docs and add unit test Dec 7, 2017
@miss-islington
Copy link
Contributor

Thanks @vitiral for the PR, and @asvetlov for merging it 🌮🎉.. I'm working now to backport this PR to: 2.7, 3.6.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Dec 7, 2017
…H-4709)

* fix issue32208: update threading.Semaphore docs and add unit test to validate correct behavior

* add test for blocking

* Update threading.rst

* semaphore: remove documentation validation tests and move 'return value' test to BaseSemaphore
(cherry picked from commit a0374dd)
@bedevere-bot
Copy link

GH-4750 is a backport of this pull request to the 3.6 branch.

@miss-islington
Copy link
Contributor

Sorry, @vitiral and @asvetlov, I could not cleanly backport this to 2.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker a0374dd34aa25f0895195d388b5ceff43b121b00 2.7

@asvetlov
Copy link
Contributor

asvetlov commented Dec 7, 2017

Docs for 2.7 is slightly different, let's not add the change to Python 2.7

@vitiral
Copy link
Contributor Author

vitiral commented Dec 7, 2017

@asvetlov the only difference between them should be the addition of timeout. I don't believe there are any other changes.

However, I am fine leaving python2.7 (including its docs) alone since it really isn't relevant anymore. The only annoyance is that google STILL points to python2.7 as the "main docs", but meh.

@vitiral
Copy link
Contributor Author

vitiral commented Dec 7, 2017

and thanks @miss-islington and @asvetlov, it was a great first contribution for a language I've been using for over half a decade now 🎉

@asvetlov
Copy link
Contributor

asvetlov commented Dec 7, 2017

@vitiral docs for 2.7 has a little different paragraphs flow but the fix is not very important to make docs divergency.
Thanks for contribution!

@vitiral
Copy link
Contributor Author

vitiral commented Dec 7, 2017

@asvetlov (sorry if this shows up in your email twice, I replied to the wrong thread before!)

The 2.7 docs has one error:

It says "There is no return value in this case" for when a thread is blocked, when in fact the return value is True.

I don't think a port would be difficult if you would be open to getting it into 2.7 (Edit: I can work on it).

asvetlov pushed a commit that referenced this pull request Dec 7, 2017
#4750)

* fix issue32208: update threading.Semaphore docs and add unit test to validate correct behavior

* add test for blocking

* Update threading.rst

* semaphore: remove documentation validation tests and move 'return value' test to BaseSemaphore
(cherry picked from commit a0374dd)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants