bpo-43538: Add extra arguments to os.startfile (GH-25538)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 371d59e..41ef50d 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -4155,7 +4155,7 @@
.. availability:: Windows.
-.. function:: startfile(path[, operation])
+.. function:: startfile(path, [operation], [arguments], [cwd], [show_cmd])
Start a file with its associated application.
@@ -4169,13 +4169,25 @@
``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
``'find'`` (to be used on directories).
+ When launching an application, specify *arguments* to be passed as a single
+ string. This argument may have no effect when using this function to launch a
+ document.
+
+ The default working directory is inherited, but may be overridden by the *cwd*
+ argument. This should be an absolute path. A relative *path* will be resolved
+ against this argument.
+
+ Use *show_cmd* to override the default window style. Whether this has any
+ effect will depend on the application being launched. Values are integers as
+ supported by the Win32 :c:func:`ShellExecute` function.
+
:func:`startfile` returns as soon as the associated application is launched.
There is no option to wait for the application to close, and no way to retrieve
the application's exit status. The *path* parameter is relative to the current
- directory. If you want to use an absolute path, make sure the first character
- is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function
- doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
- the path is properly encoded for Win32.
+ directory or *cwd*. If you want to use an absolute path, make sure the first
+ character is not a slash (``'/'``) Use :mod:`pathlib` or the
+ :func:`os.path.normpath` function to ensure that paths are properly encoded for
+ Win32.
To reduce interpreter startup overhead, the Win32 :c:func:`ShellExecute`
function is not resolved until this function is first called. If the function
@@ -4183,8 +4195,14 @@
.. audit-event:: os.startfile path,operation os.startfile
+ .. audit-event:: os.startfile/2 path,operation,arguments,cwd,show_cmd os.startfile
+
.. availability:: Windows.
+ .. versionchanged:: 3.10
+ Added the *arguments*, *cwd* and *show_cmd* arguments, and the
+ ``os.startfile/2`` audit event.
+
.. function:: system(command)