- document bytes()

- throw out many mentions of "old-style/new-style"
- add memoryview() though I somebody has to fill in the details
- throw out str.decode()
- throw out classobj and instanceobj

Author: birkenfeld

Doc/c-api/concrete.rst

@@ -2503,43 +2503,6 @@ Dictionary Objects
 Other Objects
 =============
 
-
-.. _classobjects:
-
-Class Objects
--------------
-
-.. index:: object: class
-
-Note that the class objects described here represent old-style classes, which
-will go away in Python 3. When creating new types for extension modules, you
-will want to work with type objects (section :ref:`typeobjects`).
-
-
-.. ctype:: PyClassObject
-
-   The C structure of the objects used to describe built-in classes.
-
-
-.. cvar:: PyObject* PyClass_Type
-
-   .. index:: single: ClassType (in module types)
-
-   This is the type object for class objects; it is the same object as
-   ``types.ClassType`` in the Python layer.
-
-
-.. cfunction:: int PyClass_Check(PyObject *o)
-
-   Return true if the object *o* is a class object, including instances of types
-   derived from the standard class object.  Return false in all other cases.
-
-
-.. cfunction:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)
-
-   Return true if *klass* is a subclass of *base*. Return false in all other cases.
-
-
 .. _fileobjects:
 
 File Objects
@@ -2668,40 +2631,6 @@ change in future releases of Python.
    failure; the appropriate exception will be set.
 
 
-.. _instanceobjects:
-
-Instance Objects
-----------------
-
-.. index:: object: instance
-
-There are very few functions specific to instance objects.
-
-
-.. cvar:: PyTypeObject PyInstance_Type
-
-   Type object for class instances.
-
-
-.. cfunction:: int PyInstance_Check(PyObject *obj)
-
-   Return true if *obj* is an instance.
-
-
-.. cfunction:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)
-
-   Create a new instance of a specific class.  The parameters *arg* and *kw* are
-   used as the positional and keyword parameters to the object's constructor.
-
-
-.. cfunction:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)
-
-   Create a new instance of a specific class without calling its constructor.
-   *class* is the class of new object.  The *dict* parameter will be used as the
-   object's :attr:`__dict__`; if *NULL*, a new dictionary will be created for the
-   instance.
-
-
 .. _function-objects:
 
 Function Objects

Doc/c-api/utilities.rst

@@ -750,6 +750,7 @@ return true, otherwise they return false and raise an appropriate exception.
    va_list rather than a variable number of arguments.
 
 
+.. XXX deprecated, will be removed
 .. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
 
    Function used to deconstruct the argument lists of "old-style" functions ---

Doc/glossary.rst

@@ -29,8 +29,8 @@ Glossary
       bytecode.
 
    classic class
-      Any class which does not inherit from :class:`object`.  See
-      :term:`new-style class`.
+      One of the two flavors of classes in earlier Python versions.  Since
+      Python 3.0, there are no classic classes anymore.
 
    coercion
       The implicit conversion of an instance of one type to another during an
@@ -58,15 +58,14 @@ Glossary
       it's almost certain you can safely ignore them.
 
    descriptor
-      Any *new-style* object that defines the methods :meth:`__get__`,
-      :meth:`__set__`, or :meth:`__delete__`. When a class attribute is a
-      descriptor, its special binding behavior is triggered upon attribute
-      lookup.  Normally, writing *a.b* looks up the object *b* in the class
-      dictionary for *a*, but if *b* is a descriptor, the defined method gets
-      called. Understanding descriptors is a key to a deep understanding of
-      Python because they are the basis for many features including functions,
-      methods, properties, class methods, static methods, and reference to super
-      classes.
+      An object that defines the methods :meth:`__get__`, :meth:`__set__`, or
+      :meth:`__delete__`.  When a class attribute is a descriptor, its special
+      binding behavior is triggered upon attribute lookup.  Normally, writing
+      *a.b* looks up the object *b* in the class dictionary for *a*, but if *b*
+      is a descriptor, the defined method gets called.  Understanding
+      descriptors is a key to a deep understanding of Python because they are
+      the basis for many features including functions, methods, properties,
+      class methods, static methods, and reference to super classes.
 
    dictionary
       An associative array, where arbitrary keys are mapped to values.  The use
@@ -277,11 +276,10 @@ Glossary
       scope.  Likewise, global variables read and write to the global namespace.
 
    new-style class
-      Any class that inherits from :class:`object`.  This includes all built-in
-      types like :class:`list` and :class:`dict`.  Only new-style classes can
-      use Python's newer, versatile features like :attr:`__slots__`,
-      descriptors, properties, :meth:`__getattribute__`, class methods, and
-      static methods.
+      Old name for the flavor of classes now used for all class objects.  In
+      earlier Python versions, only new-style classes could use Python's newer,
+      versatile features like :attr:`__slots__`, descriptors, properties,
+      :meth:`__getattribute__`, class methods, and static methods.
 
    Python 3000
       Nickname for the next major Python version, 3.0 (coined long ago when the
@@ -294,11 +292,11 @@ Glossary
       implementation level to keep track of allocated memory.
 
    __slots__
-      A declaration inside a :term:`new-style class` that saves memory by
-      pre-declaring space for instance attributes and eliminating instance
-      dictionaries.  Though popular, the technique is somewhat tricky to get
-      right and is best reserved for rare cases where there are large numbers of
-      instances in a memory-critical application.
+      A declaration inside a class that saves memory by pre-declaring space for
+      instance attributes and eliminating instance dictionaries.  Though
+      popular, the technique is somewhat tricky to get right and is best
+      reserved for rare cases where there are large numbers of instances in a
+      memory-critical application.
 
    sequence
       An :term:`iterable` which supports efficient element access using integer

Doc/library/functions.rst

@@ -139,12 +139,37 @@ available.  They are listed here in alphabetical order.
       If no argument is given, this function returns :const:`False`.
 
 
+.. function:: bytes([arg[, encoding[, errors]]])
+
+   Return a new array of bytes.  The :class:`bytes` type is a mutable sequence
+   of integers in the range 0 <= x < 256.  It has most of the usual methods of
+   mutable sequences, described in :ref:`typesseq-mutable`, as well as a few
+   methods borrowed from strings, described in :ref:`bytes-methods`.
+
+   The optional *arg* parameter can be used to initialize the array in a few
+   different ways:
+
+   * If it is a *string*, you must also give the *encoding* (and optionally,
+     *errors*) parameters; :func:`bytes` then acts like :meth:`str.encode`.
+
+   * If it is an *integer*, the array will have that size and will be
+     initialized with null bytes.
+
+   * If it is an object conforming to the *buffer* interface, a read-only buffer
+     of the object will be used to initialize the bytes array.
+
+   * If it is an *iterable*, it must be an iterable of integers in the range 0
+     <= x < 256, which are used as the initial contents of the array.
+
+   Without an argument, an array of size 0 is created.
+
+
 .. function:: chr(i)
 
-   Return the string of one character whose Unicode codepoint is the integer *i*.  For
-   example, ``chr(97)`` returns the string ``'a'``. This is the inverse of
-   :func:`ord`.  The valid range for the argument depends how Python was
-   configured -- it may be either UCS2 [0..0xFFFF] or UCS4 [0..0x10FFFF].
+   Return the string of one character whose Unicode codepoint is the integer
+   *i*.  For example, ``chr(97)`` returns the string ``'a'``. This is the
+   inverse of :func:`ord`.  The valid range for the argument depends how Python
+   was configured -- it may be either UCS2 [0..0xFFFF] or UCS4 [0..0x10FFFF].
    :exc:`ValueError` will be raised if *i* is outside that range.
 
 
@@ -557,15 +582,13 @@ available.  They are listed here in alphabetical order.
 
 .. function:: isinstance(object, classinfo)
 
-   Return true if the *object* argument is an instance of the *classinfo* argument,
-   or of a (direct or indirect) subclass thereof.  Also return true if *classinfo*
-   is a type object (new-style class) and *object* is an object of that type or of
-   a (direct or indirect) subclass thereof.  If *object* is not a class instance or
-   an object of the given type, the function always returns false.  If *classinfo*
-   is neither a class object nor a type object, it may be a tuple of class or type
-   objects, or may recursively contain other such tuples (other sequence types are
-   not accepted).  If *classinfo* is not a class, type, or tuple of classes, types,
-   and such tuples, a :exc:`TypeError` exception is raised.
+   Return true if the *object* argument is an instance of the *classinfo*
+   argument, or of a (direct or indirect) subclass thereof.  If *object* is not
+   an object of the given type, the function always returns false.  If
+   *classinfo* is not a class (type object), it may be a tuple of type objects,
+   or may recursively contain other such tuples (other sequence types are not
+   accepted).  If *classinfo* is not a type or tuple of types and such tuples,
+   a :exc:`TypeError` exception is raised.
 
    .. versionchanged:: 2.2
       Support for a tuple of type information was added.
@@ -659,6 +682,13 @@ available.  They are listed here in alphabetical order.
       Added support for the optional *key* argument.
 
 
+.. function:: memoryview(obj)
+
+   Return a "memory view" object created from the given argument.
+   
+   XXX: To be documented.
+
+
 .. function:: min(iterable[, args...][key])
 
    With a single argument *iterable*, return the smallest item of a non-empty
@@ -682,9 +712,13 @@ available.  They are listed here in alphabetical order.
 
 .. function:: object()
 
-   Return a new featureless object.  :class:`object` is a base for all new style
-   classes.  It has the methods that are common to all instances of new style
-   classes.
+   Return a new featureless object.  :class:`object` is a base for all classes.
+   It has the methods that are common to all instances of Python classes.
+
+   .. note::
+
+      :class:`object` does *not* have a :attr:`__dict__`, so you can't assign
+      arbitrary attributes to an instance of the :class:`object` class.
 
    .. versionadded:: 2.2
 
@@ -797,8 +831,7 @@ available.  They are listed here in alphabetical order.
 
 .. function:: property([fget[, fset[, fdel[, doc]]]])
 
-   Return a property attribute for new-style classes (classes that derive from
-   :class:`object`).
+   Return a property attribute.
 
    *fget* is a function for getting an attribute value, likewise *fset* is a
    function for setting, and *fdel* a function for del'ing, an attribute.  Typical
@@ -1023,11 +1056,12 @@ available.  They are listed here in alphabetical order.
 
 .. function:: super(type[, object-or-type])
 
+   .. XXX need to document PEP "new super"
+
    Return the superclass of *type*.  If the second argument is omitted the super
    object returned is unbound.  If the second argument is an object,
    ``isinstance(obj, type)`` must be true.  If the second argument is a type,
-   ``issubclass(type2, type)`` must be true. :func:`super` only works for new-style
-   classes.
+   ``issubclass(type2, type)`` must be true.
 
    A typical use for calling a cooperative superclass method is::
 
@@ -1061,23 +1095,26 @@ available.  They are listed here in alphabetical order.
 
    .. index:: object: type
 
-   Return the type of an *object*.  The return value is a type object.  The
-   :func:`isinstance` built-in function is recommended for testing the type of an
-   object.
+   Return the type of an *object*.  The return value is a type object and
+   generally the same object as returned by ``object.__class__``.
+
+   The :func:`isinstance` built-in function is recommended for testing the type
+   of an object, because it takes subclasses into account.
 
-   With three arguments, :func:`type` functions as a constructor as detailed below.
+   With three arguments, :func:`type` functions as a constructor as detailed
+   below.
 
 
 .. function:: type(name, bases, dict)
    :noindex:
 
    Return a new type object.  This is essentially a dynamic form of the
-   :keyword:`class` statement. The *name* string is the class name and becomes the
-   :attr:`__name__` attribute; the *bases* tuple itemizes the base classes and
-   becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
-   namespace containing definitions for class body and becomes the :attr:`__dict__`
-   attribute.  For example, the following two statements create identical
-   :class:`type` objects::
+   :keyword:`class` statement. The *name* string is the class name and becomes
+   the :attr:`__name__` attribute; the *bases* tuple itemizes the base classes
+   and becomes the :attr:`__bases__` attribute; and the *dict* dictionary is the
+   namespace containing definitions for class body and becomes the
+   :attr:`__dict__` attribute.  For example, the following two statements create
+   identical :class:`type` objects::
 
       >>> class X(object):
       ...     a = 1
@@ -1128,6 +1165,7 @@ Python programmers, trainers, students and bookwriters should feel free to
 bypass these functions without concerns about missing something important.
 
 
+.. XXX does this go away?
 .. function:: buffer(object[, offset[, size]])
 
    The *object* argument must be an object that supports the buffer call interface

Doc/library/pickle.rst

@@ -416,6 +416,8 @@ Pickling and unpickling normal class instances
    single: __getinitargs__() (copy protocol)
    single: __init__() (instance constructor)
 
+.. XXX is __getinitargs__ only used with old-style classes?
+
 When a pickled class instance is unpickled, its :meth:`__init__` method is
 normally *not* invoked.  If it is desirable that the :meth:`__init__` method be
 called on unpickling, an old-style class can define a method

Doc/library/sqlite3.rst

@@ -547,11 +547,6 @@ Registering an adapter callable
 The other possibility is to create a function that converts the type to the
 string representation and register the function with :meth:`register_adapter`.
 
-.. note::
-
-   The type/class to adapt must be a new-style class, i. e. it must have
-   :class:`object` as one of its bases.
-
 .. literalinclude:: ../includes/sqlite3/adapter_point_2.py
 
 The :mod:`sqlite3` module has two default adapters for Python's built-in

Doc/library/stdtypes.rst

@@ -682,22 +682,6 @@ the :mod:`re` module for string functions based on regular expressions.
    slice notation.
 
 
-.. XXX what about str.decode???
-.. method:: str.decode([encoding[, errors]])
-
-   Decode the string using the codec registered for *encoding*. *encoding*
-   defaults to the default string encoding.  *errors* may be given to set a
-   different error handling scheme.  The default is ``'strict'``, meaning that
-   encoding errors raise :exc:`UnicodeError`.  Other possible values are
-   ``'ignore'``, ``'replace'`` and any other name registered via
-   :func:`codecs.register_error`, see section :ref:`codec-base-classes`.
-
-   .. versionadded:: 2.2
-
-   .. versionchanged:: 2.3
-      Support for other error handling schemes added.
-
-
 .. method:: str.encode([encoding[, errors]])
 
    Return an encoded version of the string.  Default encoding is the current

Doc/reference/compound_stmts.rst

@@ -540,8 +540,10 @@ must be given a value in the :meth:`__init__` method or in another method.  Both
 class and instance variables are accessible through the notation
 "``self.name``", and an instance variable hides a class variable with the same
 name when accessed in this way.  Class variables with immutable values can be
-used as defaults for instance variables. For new-style classes, descriptors can
-be used to create instance variables with different implementation details.
+used as defaults for instance variables. Descriptors can be used to create
+instance variables with different implementation details.
+
+.. XXX add link to descriptor docs above
 
 .. rubric:: Footnotes