Document "language_level=3str" and also support it in the cythonize command as "--3str".

CHANGES.rst

@@ -89,8 +89,8 @@ Features added
 
 * An additional ``check_size`` clause was added to the ``ctypedef class`` name
   specification to allow suppressing warnings when importing modules with
-  backward-compatible `PyTypeObject`` size changes.
-  (Github issue #2627)
+  backwards-compatible ``PyTypeObject`` size changes.
+  Patch by Matti Picus.  (Github issue #2627)
 
 Bugs fixed
 ----------
@@ -162,16 +162,16 @@ Bugs fixed
 Other changes
 -------------
 
-* Cython now emits a warning when no ``language_level`` (2 or 3) is set explicitly,
-  neither as a ``cythonize()`` option nor as a compiler directive.  This is meant
-  to prepare the transition of the default language level from currently Py2
-  to Py3, since that is what most new users will expect these days.  The future
-  default will, however, not enforce unicode literals, because this has proven a
-  major obstacle in the support for both Python 2.x and 3.x.  The next major
-  release is intended to make this change, so that it will parse all code that
-  does not request a specific language level as Python 3 code, but with ``str``
-  literals.  The language level 2 will continue to be supported for an indefinite
-  time.
+* Cython now emits a warning when no ``language_level`` (2, 3 or '3str') is set
+  explicitly, neither as a ``cythonize()`` option nor as a compiler directive.
+  This is meant to prepare the transition of the default language level from
+  currently Py2 to Py3, since that is what most new users will expect these days.
+  The future default will, however, not enforce unicode literals, because this
+  has proven a major obstacle in the support for both Python 2.x and 3.x.  The
+  next major release is intended to make this change, so that it will parse all
+  code that does not request a specific language level as Python 3 code, but with
+  ``str`` literals.  The language level 2 will continue to be supported for an
+  indefinite time.
 
 * The documentation was restructured, cleaned up and examples are now tested.
   The NumPy tutorial was also rewritten to simplify the running example.

Cython/Build/Cythonize.py

@@ -165,6 +165,8 @@ def parse_args(args):
                       help='use Python 2 syntax mode by default')
     parser.add_option('-3', dest='language_level', action='store_const', const=3,
                       help='use Python 3 syntax mode by default')
+    parser.add_option('--3str', dest='language_level', action='store_const', const='3str',
+                      help='use Python 3 syntax mode by default')
     parser.add_option('-a', '--annotate', dest='annotate', action='store_true',
                       help='generate annotated HTML page for source files')
 
@@ -198,7 +200,7 @@ def parse_args(args):
     if multiprocessing is None:
         options.parallel = 0
     if options.language_level:
-        assert options.language_level in (2, 3)
+        assert options.language_level in (2, 3, '3str')
         options.options['language_level'] = options.language_level
     return options, args
 

docs/src/userguide/source_files_and_compilation.rst

@@ -815,11 +815,14 @@ Cython code.  Here is the list of currently supported directives:
     expressions* is considered unsafe (due to possible overflow) and must be
     explicitly requested.
 
-``language_level`` (2/3)
+``language_level`` (2/3/3str)
     Globally set the Python language level to be used for module
     compilation.  Default is compatibility with Python 2.  To enable
-    Python 3 source code semantics, set this to 3 at the start of a
-    module or pass the "-3" command line option to the compiler.
+    Python 3 source code semantics, set this to 3 (or 3str) at the start
+    of a module or pass the "-3" or "--3str" command line options to the
+    compiler.  The ``3str`` option enables Python 3 semantics but does
+    not change the ``str`` type and unprefixed string literals to
+    ``unicode`` when the compiled code runs in Python 2.x.
     Note that cimported files inherit this setting from the module
     being compiled, unless they explicitly set their own language level.
     Included source files always inherit this setting.