Title: Outdated/Incorrect annotations for `os.startfile` · Issue #10991 · python/typeshed · GitHub
Open Graph Title: Outdated/Incorrect annotations for `os.startfile` · Issue #10991 · python/typeshed
X Title: Outdated/Incorrect annotations for `os.startfile` · Issue #10991 · python/typeshed
Description: In my opinion, the annotations for os.startfile have major problems that have been overlooked for the past few years. For reference, the current annotations in stdlib/os__init__.pyi if sys.platform == "win32": if sys.version_info >= (3, ...
Open Graph Description: In my opinion, the annotations for os.startfile have major problems that have been overlooked for the past few years. For reference, the current annotations in stdlib/os__init__.pyi if sys.platform...
X Description: In my opinion, the annotations for os.startfile have major problems that have been overlooked for the past few years. For reference, the current annotations in stdlib/os__init__.pyi if sys.platform...
Opengraph URL: https://github.com/python/typeshed/issues/10991
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Outdated/Incorrect annotations for `os.startfile`","articleBody":"In my opinion, the annotations for `os.startfile` have major problems that have been overlooked for the past few years.\r\n\r\nFor reference, the current annotations in [stdlib/os__init__.pyi](https://github.com/python/typeshed/blob/main/stdlib/os/__init__.pyi#L927C10-L927C10)\r\n```python\r\nif sys.platform == \"win32\":\r\n if sys.version_info >= (3, 8):\r\n def startfile(path: StrOrBytesPath, operation: str | None = None) -> None: ...\r\n else:\r\n def startfile(filepath: StrOrBytesPath, operation: str | None = None) -> None: ...\r\n```\r\n\r\n## 1. Renaming the first argument for `filepath` to `path` in >= 3.8\r\n\r\nIs there reason why this change has been added? While the official docs list the argument name as `path` ([docs](https://docs.python.org/3/library/os.html#os.startfile)), the CPython source code has the first argument as `filepath` ([CPython/main](https://github.com/python/cpython/blob/f55cb44359821e71c29903f2152b4658509dac0d/Modules/clinic/posixmodule.c.h#L9784)), and firing up a REPL to check actual behavior mirrors the same:\r\n\r\n```\r\n>>> from os import startfile\r\n>>> startfile(path='explorer')\r\nTraceback (most recent call last):\r\n File \"\u003cpyshell#1>\", line 1, in \u003cmodule>\r\n startfile(path='explorer')\r\nTypeError: startfile() missing required argument 'filepath' (pos 1)\r\n```\r\n\r\nTo me, it looks like a case of incorrect documentation that has been transferred into type annotations without checking whether it mirrors runtime behaviour.\r\n\r\n## 2. Allowing `None` for `operation` argument\r\n\r\nThis is another annotation that conflicts with runtime behaviour:\r\n\r\n```\r\n>>> from os import startfile\r\n>>> startfile(filepath='explorer', operation=None)\r\nTraceback (most recent call last):\r\n File \"\u003cpyshell#3>\", line 1, in \u003cmodule>\r\n startfile(filepath='explorer', operation=None)\r\nTypeError: startfile() argument 2 must be str, not None\r\n```\r\n\r\nI'll be honest, I'm not 100% sure what the correct default value is. Maybe just the empty string `\"\"` since the logic itself sits in Windows' own ShellExecuteW?\r\n\r\n## 3. Missing arguments from >= 3.10\r\n\r\n`os.startfile` gained additional arguments in Python 3.10, but they are all missing from the type annotations.\r\n\r\n```python\r\ndef startfile(\r\n filepath: StrOrBytesPath, \r\n operation: str = \"\", # Can't be None during runtime\r\n arguments: str = \"\", # Can't be None during runtime\r\n cwd: StrOrBytesPath | None = None, # Can be None during runtime\r\n show_cmd: int = 1 # Can't be None during runtime, 1 from CPython source\r\n) -> None: ...\r\n```\r\n\r\n## Disclaimer\r\n\r\nI've been investigating this issue from my limited view point. There could be historic reasons why some things are the way they are. That's why I'm opening this as an Issue open for discussion instead of a PR. If you or somebody you know have more insight on this topic, please do share.\r\n\r\n## My proposal\r\n\r\nIf there are no mistakes in my assumptions, I would suggest the following annotations for `os.startfile`:\r\n\r\n```python\r\nif sys.platform == \"win32\":\r\n if sys.version_info >= (3, 10):\r\n def startfile(filepath: StrOrBytesPath, operation: str = \"\", arguments: str = \"\", cwd: StrOrBytesPath | None = None, show_cmd: int = 1) -> None: ...\r\n else:\r\n def startfile(filepath: StrOrBytesPath, operation: str = '') -> None: ...\r\n```","author":{"url":"https://github.com/Jakob-Stadler","@type":"Person","name":"Jakob-Stadler"},"datePublished":"2023-11-07T16:56:47Z","url":"https://github.com/python/typeshed/issues/10991"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:7ac4a1fe-9efc-19ab-29e4-23d2d534dcf0 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | D122:CF959:2A5E875:377BE24:6B0007DC |
| html-safe-nonce | 890fa5a8cff51ac586caacd6938b9b51fa9f925cfb64a7325091159870947a20 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEMTIyOkNGOTU5OjJBNUU4NzU6Mzc3QkUyNDo2QjAwMDdEQyIsInZpc2l0b3JfaWQiOiI5MTUwNzI4MDI2OTU3Mjg1MzQwIiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 05d63b463475e1eab63dbea17a9eb9901b449ab3ca8fa54cf4bc84a30f0e2628 |
| hovercard-subject-tag | issue:1981812045 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python/typeshed/10991/issue_layout |
| twitter:image | https://opengraph.githubassets.com/1643358fe1ea6b39d87c77f1c703e23b451d67432d1915699f10a28ee2541291/python/typeshed/issues/10991 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/1643358fe1ea6b39d87c77f1c703e23b451d67432d1915699f10a28ee2541291/python/typeshed/issues/10991 |
| og:image:alt | In my opinion, the annotations for os.startfile have major problems that have been overlooked for the past few years. For reference, the current annotations in stdlib/os__init__.pyi if sys.platform... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Jakob-Stadler |
| hostname | github.com |
| expected-hostname | github.com |
| None | 0a0d8686a27478df474dd7415776a7a080cde8838b3cd92ea7601187572e5729 |
| turbo-cache-control | no-preview |
| go-import | github.com/python/typeshed git https://github.com/python/typeshed.git |
| octolytics-dimension-user_id | 1525981 |
| octolytics-dimension-user_login | python |
| octolytics-dimension-repository_id | 31696383 |
| octolytics-dimension-repository_nwo | python/typeshed |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 31696383 |
| octolytics-dimension-repository_network_root_nwo | python/typeshed |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 16a11879678aaf97e2a42c33ee70830aa084fa37 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width