Make it clear how to write platform-dependent stubs

[ymyzk]

Background

• These are some platform-dependent stubs
  

  typeshed/stdlib/2/os/__init__.pyi

  Lines 38 to 52 in fa74160

  	O_DSYNC: int # Unix only
  	O_RSYNC: int # Unix only
  	O_SYNC: int # Unix only
  	O_NDELAY: int # Unix only
  	O_NONBLOCK: int # Unix only
  	O_NOCTTY: int # Unix only
  	O_SHLOCK: int # Unix only
  	O_EXLOCK: int # Unix only
  	O_BINARY: int # Windows only
  	O_NOINHERIT: int # Windows only
  	O_SHORT_LIVED: int # Windows only
  	O_TEMPORARY: int # Windows only
  	O_RANDOM: int # Windows only
  	O_SEQUENTIAL: int # Windows only
  	O_TEXT: int # Windows only

• Two different styles are used to write these stubs, and this difference is confusing for contributors
  • Using comments like # Windows only or # Unix only
  • Using sys.platform like

    typeshed/stdlib/2and3/time.pyi

    Line 82 in fa74160

    if sys.platform != 'win32':

Proposal

• Decide a guideline on writing platform-dependent stubs
• Summarize it into the conventions section in CONTRIBUTING.md
• Update the existing stubs with the consistent style

Notes

• Based on this review Add nis stub #2213 (comment) by @gvanrossum, use of sys.platform seems to be recommended now?
• I'm interested in updating existing stubs after a guideline is decided

[JelleZijlstra]

We should prefer using sys.platform checks. Thanks for opening this!

[gvanrossum]

Yes, Also maybe update the text about this in CONTRIBUTING.md if it's not yet clear about this?

…

On Sun, Jun 24, 2018 at 7:23 AM Jelle Zijlstra ***@***.***> wrote: We should prefer using sys.platform checks. Thanks for opening this! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2275 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACwrMmDG2nUF9yI_E7EfvNB7T8ccbwpEks5t_6DqgaJpZM4U1EcU> .

-- --Guido van Rossum (python.org/~guido)

[ymyzk]

We don't have any text about platform-dependent APIs in CONTRIBUTING.md. So, I have just sent a PR #2281.