****************************
  What's New In Python 3.1
****************************

.. XXX Add trademark info for Apple, Microsoft.

:Author: No one so far
:Release: |release|
:Date: |today|

.. $Id$
   Rules for maintenance:

   * Anyone can add text to this document.  Do not spend very much time
   on the wording of your changes, because your text will probably
   get rewritten to some degree.

   * The maintainer will go through Misc/NEWS periodically and add
   changes; it's therefore more important to add your changes to
   Misc/NEWS than to this file.  (Note: I didn't get to this for 3.0.
   GvR.)

   * This is not a complete list of every single change; completeness
   is the purpose of Misc/NEWS.  Some changes I consider too small
   or esoteric to include.  If such a change is added to the text,
   I'll just remove it.  (This is another reason you shouldn't spend
   too much time on writing your addition.)

   * If you want to draw your new text to the attention of the
   maintainer, add 'XXX' to the beginning of the paragraph or
   section.

   * It's OK to just add a fragmentary note about a change.  For
   example: "XXX Describe the transmogrify() function added to the
   socket module."  The maintainer will research the change and
   write the necessary text.

   * You can comment out your additions if you like, but it's not
   necessary (especially when a final release is some months away).

   * Credit the author of a patch or bugfix.   Just the name is
   sufficient; the e-mail address isn't necessary.  (Due to time
   constraints I haven't managed to do this for 3.0.  GvR.)

   * It's helpful to add the bug/patch number as a comment:

   % Patch 12345
   XXX Describe the transmogrify() function added to the socket
   module.
   (Contributed by P.Y. Developer.)

   This saves the maintainer the effort of going through the SVN log
   when researching a change.  (Again, I didn't get to this for 3.0.
   GvR.)

This article explains the new features in Python 3.1, compared to 3.0.

.. Compare with previous release in 2 - 3 sentences here.
.. add hyperlink when the documentation becomes available online.

.. ======================================================================
.. Large, PEP-level features and changes should be described here.
.. Should there be a new section here for 3k migration?
.. Or perhaps a more general section describing module changes/deprecation?
.. sets module deprecated
.. ======================================================================


Other Language Changes
======================

Some smaller changes made to the core Python language are:

* The :func:`int` type gained a ``bit_length`` method that returns the
  number of bits necessary to represent its argument in binary::

      >>> n = 37
      >>> bin(37)
      '0b100101'
      >>> n.bit_length()
      6
      >>> n = 2**123-1
      >>> n.bit_length()
      123
      >>> (n+1).bit_length()
      124

  (Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.)

* Integers are now stored internally either in base 2**15 or in base
  2**30, the base being determined at build time.  Previously, they
  were always stored in base 2**15.  Using base 2**30 gives
  significant performance improvements on 64-bit machines, but
  benchmark results on 32-bit machines have been mixed.  Therefore,
  the default is to use base 2**30 on 64-bit machines and base 2**15
  on 32-bit machines; on Unix, there's a new configure option
  --enable-big-digits that can be used to override this default.

  Apart from the performance improvements this change should be
  invisible to end users, with one exception: for testing and
  debugging purposes there's a new structseq ``sys.int_info`` that
  provides information about the internal format, giving the number of
  bits per digit and the size in bytes of the C type used to store
  each digit::

     >>> import sys
     >>> sys.int_info
     sys.int_info(bits_per_digit=30, sizeof_digit=4)


  (Contributed by Mark Dickinson; :issue:`4258`.)


.. ======================================================================


Optimizations
-------------

Major performance enhancements have been added:

* The new I/O library (as defined in :pep:`3116`) was mostly written in
  Python and quickly proved to be a problematic bottleneck in Python 3.0.
  In Python 3.1, the I/O library has been entirely rewritten in C and is
  2 to 20 times faster depending on the task at hand. The pure Python
  version is still available for experimentation purposes through
  the ``_pyio`` module.

  (Contributed by Amaury Forgeot d'Arc and Antoine Pitrou.)

* A new configure flag, ``--with-computed-gotos``, enables a faster opcode
  dispatch mechanism on compilers which support it. Speedups of up to 20%
  have been observed, depending on the system and compiler.

  (Contributed by Antoine Pitrou, :issue:`4753`.)


.. ======================================================================