Issue #10089: Add support for arbitrary -X options on the command-line.

They can be retrieved through a new attribute `sys._xoptions`.

4 files changed, 55 insertions, 5 deletions

diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 232cec0..252bd1a 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -127,6 +127,21 @@ accessible to C code.  They all work with the current interpreter thread's
 
    .. versionadded:: 3.2
 
+.. c:function:: void PySys_AddXOption(const wchar_t *s)
+
+   Parse *s* as a set of :option:`-X` options and add them to the current
+   options mapping as returned by :c:func:`PySys_GetXOptions`.
+
+   .. versionadded:: 3.2
+
+.. c:function:: PyObject *PySys_GetXOptions()
+
+   Return the current dictionary of :option:`-X` options, similarly to
+   :data:`sys._xoptions`.  On error, *NULL* is returned and an exception is
+   set.
+
+   .. versionadded:: 3.2
+
 
 .. _processcontrol:
 
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 2dc7084..f2a8767 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -1305,6 +1305,9 @@ PyString_AsEncodedString:const char*:errors::
 PySys_AddWarnOption:void:::
 PySys_AddWarnOption:char*:s::
 
+PySys_AddXOption:void:::
+PySys_AddXOption:const wchar_t*:s::
+
 PySys_GetFile:FILE*:::
 PySys_GetFile:char*:name::
 PySys_GetFile:FILE*:def::
@@ -1312,6 +1315,8 @@ PySys_GetFile:FILE*:def::
 PySys_GetObject:PyObject*::0:
 PySys_GetObject:char*:name::
 
+PySys_GetXOptions:PyObject*::0:
+
 PySys_SetArgv:int:::
 PySys_SetArgv:int:argc::
 PySys_SetArgv:char**:argv::
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 23fdb09..bf8e0d0 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -975,6 +975,30 @@ always available.
    module for informational purposes; modifying this value has no effect on the
    registry keys used by Python. Availability: Windows.
 
+
+.. data:: _xoptions
+
+   A dictionary of the various implementation-specific flags passed through
+   the :option:`-X` command-line option.  Option names are either mapped to
+   their values, if given explicitly, or to :const:`True`.  Example::
+
+      $ ./python -Xa=b -Xc
+      Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
+      [GCC 4.4.3] on linux2
+      Type "help", "copyright", "credits" or "license" for more information.
+      >>> import sys
+      >>> sys._xoptions
+      {'a': 'b', 'c': True}
+
+   .. impl-detail::
+
+      This is a CPython-specific way of accessing options passed through
+      :option:`-X`.  Other implementations may export them through other
+      means, or not at all.
+
+   .. versionadded:: 3.2
+
+
 .. rubric:: Citations
 
 .. [C99] ISO/IEC 9899:1999.  "Programming languages -- C."  A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf .
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
index 7da1954..6f3cfbe 100644
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -321,6 +321,17 @@ Miscellaneous options
 
    .. note:: The line numbers in error messages will be off by one.
 
+
+.. cmdoption:: -X
+
+   Reserved for various implementation-specific options.  CPython currently
+   defines none of them, but allows to pass arbitrary values and retrieve
+   them through the :data:`sys._xoptions` dictionary.
+
+   .. versionchanged:: 3.2
+      It is now allowed to pass :option:`-X` with CPython.
+
+
 Options you shouldn't use
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -330,11 +341,6 @@ Options you shouldn't use
 
 .. _Jython: http://jython.org
 
-.. cmdoption:: -X
-
-    Reserved for alternative implementations of Python to use for their own
-    purposes.
-
 .. _using-on-envvars:
 
 Environment variables