[Python-Dev] Misc/NEWS (was: Two random and nearly unrelated ideas)

David Goodger goodger@users.sourceforge.net
Wed, 04 Sep 2002 22:44:23 -0400


[Skip]
>> While adding a blurb to Misc/NEWS about the change to the thread
>> ticker and check interval, it occurred to me that perhaps Misc/NEWS
>> would benefit from conversion to ReST format.  You could pump an
>> HTML version out to the website periodically.

I have the Docutils site auto-regenerated via a small cron script.
Any time any of the source text files change, within an hour the site
reflects the change.  It makes site maintenance easy.

(BTW, Skip, thanks for the bug report.  I'll be looking into it ASAP.)

[Guido]
> Nice idea.  How much additional mark-up would this add to quote the
> occasional reST meta-character?

Very little, depending on the desired effect.  The extreme case would
be if you want to mark up everything possible.  The result may look
too busy in the source text form though, especially because there are
so many Python identifiers, expressions, code snippets, and file names
that *could* be marked up.  It's a trade-off.

The nice thing is that Misc/NEWS is already almost valid
reStrucuturedText (which shouldn't be surprising, since
reStrucuturedText is based on common usage).  In fact, most (if not
all) of the standalone text files are almost there: README, PLAN.txt,
etc.  It wouldn't be much work to bring them up to spec.

Here are the areas of Misc/NEWS that would require editing:

* Sections: The two-line titles aren't supported.  Either they should
  be combined into one line, or the "Release date" line should become
  part of the section body.  Either::

      What's New in Python 2.2 final?  Release date: 21-Dec-2001
      ==========================================================

  or::

      What's New in Python 2.2 final?
      ===============================

      Release date: 21-Dec-2001

* Subsections (like "Core and builtins", "Library", "Extension
  modules", etc.): These could be made into true subsections by
  underlining them with dashes (and changing to title case)::

      Core and Builtins
      -----------------

  I notice that there are many headers for empty subsections (such as
  "Tools/Demos" and "Build" in "What's New in Python 2.2 final?").
  Should they be removed?

* Inline literals (filenames, identifiers, expressions and code
  snippets): Surround with double-backquotes to get monospaced,
  uninterpreted text (like HTML TT tags).  There are so many of these
  that it may be best to be selective.

* Literal blocks: Example code should be indented and prefaced with
  double-colons ("::" at the end of the preceding paragraph).  Doctest
  blocks (interactive sessions, begin with ">>> " and end with a blank
  line) don't need this, although it wouldn't hurt.

> Can you convert a section for test and show me?

I'll be happy to help.  Hmm.  Looking at the 2.2.1 Misc/NEWS file, I
see sections for 2.2.1 final, 2.2.1c2, etc., but they're missing from
the CVS Misc/NEWS file.  Is this normal because of separate development
branches or is something amiss?

Following is a converted section from the current Misc/NEWS.

Minimally marked up:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

What's New in Python 2.3 alpha 1?
=================================

XXX Release date: DD-MMM-2002 XXX

Type/class unification and new-style classes
--------------------------------------------

- Assignment to __class__ is disallowed if either the old and the new
  class is a statically allocated type object (such as defined by an
  extension module).  This prevents anomalies like ``2 .__class__ =
  bool``.

- New-style object creation and deallocation have been sped up
  significantly; they are now faster than classic instance creation
  and deallocation.

- The __slots__ variable can now mention "private" names, and the
  right thing will happen (e.g. ``__slots__ = ["__foo"]``).

- The built-ins slice() and buffer() are now callable types.  The
  types classobj (formerly class), code, function, instance, and
  instancemethod (formerly instance-method), which have no built-in
  names but are accessible through the types module, are now also
  callable.  The type dict-proxy is renamed to dictproxy.

- Cycles going through the __class__ link of a new-style instance are
  now detected by the garbage collector.

- Classes using __slots__ are now properly garbage collected.
  [SF bug 519621]

- Tightened the __slots__ rules: a slot name must be a valid Python
  identifier.

- The constructor for the module type now requires a name argument and
  takes an optional docstring argument.  Previously, this constructor
  ignored its arguments.  As a consequence, deriving a class from a
  module (not from the module type) is now illegal; previously this
  created an unnamed module, just like invoking the module type did.
  [SF bug 563060]

- A new type object, 'basestring', is added.  This is a common base
  type for 'str' and 'unicode', and can be used instead of
  ``types.StringTypes``, e.g. to test whether something is "a string":
  ``isinstance(x, basestring)`` is True for Unicode and 8-bit strings.
  This is an abstract base class and cannot be instantiated directly.

- Changed new-style class instantiation so that when C's __new__
  method returns something that's not a C instance, its __init__ is
  not called.  [SF bug #537450]

- Fixed super() to work correctly with class methods.  [SF bug #535444]

- If you try to pickle an instance of a class that has __slots__ but
  doesn't define or override __getstate__, a TypeError is now raised.
  This is done by adding a bozo __getstate__ to the class that always
  raises TypeError.  (Before, this would appear to be pickled, but the
  state of the slots would be lost.)

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Maximally marked up:

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

What's New in Python 2.3 alpha 1?
=================================

XXX Release date: DD-MMM-2002 XXX

Type/class unification and new-style classes
--------------------------------------------

- Assignment to ``__class__`` is disallowed if either the old and the
  new class is a statically allocated type object (such as defined by
  an extension module).  This prevents anomalies like ``2 .__class__ =
  bool``.

- New-style object creation and deallocation have been sped up
  significantly; they are now faster than classic instance creation
  and deallocation.

- The ``__slots__`` variable can now mention "private" names, and the
  right thing will happen (e.g. ``__slots__ = ["__foo"]``).

- The built-ins ``slice()`` and ``buffer()`` are now callable types.
  The types classobj (formerly class), code, function, instance, and
  instancemethod (formerly instance-method), which have no built-in
  names but are accessible through the ``types`` module, are now also
  callable.  The type dict-proxy is renamed to dictproxy.

- Cycles going through the ``__class__`` link of a new-style instance
  are now detected by the garbage collector.

- Classes using ``__slots__`` are now properly garbage collected.
  [SF bug 519621]

- Tightened the ``__slots__`` rules: a slot name must be a valid
  Python identifier.

- The constructor for the module type now requires a name argument and
  takes an optional docstring argument.  Previously, this constructor
  ignored its arguments.  As a consequence, deriving a class from a
  module (not from the module type) is now illegal; previously this
  created an unnamed module, just like invoking the module type did.
  [SF bug 563060]

- A new type object, ``basestring``, is added.  This is a common base
  type for ``str`` and ``unicode``, and can be used instead of
  ``types.StringTypes``, e.g. to test whether something is "a string":
  ``isinstance(x, basestring)`` is ``True`` for Unicode and 8-bit
  strings.  This is an abstract base class and cannot be instantiated
  directly.

- Changed new-style class instantiation so that when C's ``__new__``
  method returns something that's not a C instance, its ``__init__``
  is not called.  [SF bug #537450]

- Fixed ``super()`` to work correctly with class methods.  [SF bug #535444]

- If you try to pickle an instance of a class that has ``__slots__``
  but doesn't define or override ``__getstate__``, a ``TypeError`` is
  now raised.  This is done by adding a bozo ``__getstate__`` to the
  class that always raises ``TypeError``.  (Before, this would appear
  to be pickled, but the state of the slots would be lost.)

<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

-- 
David Goodger  <goodger@users.sourceforge.net>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/