summaryrefslogtreecommitdiffstats
path: root/Doc/library
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2007-08-31 16:33:38 (GMT)
committerGeorg Brandl <georg@python.org>2007-08-31 16:33:38 (GMT)
commit85eb8c103c9e460917911b43c6be302c30d75efb (patch)
tree2cbb4ff9497eb9db774e40d4f84abb368a311ed6 /Doc/library
parent3540ef16c19f2260e347a679cb27d44ba734bec6 (diff)
downloadcpython-85eb8c103c9e460917911b43c6be302c30d75efb.zip
cpython-85eb8c103c9e460917911b43c6be302c30d75efb.tar.gz
cpython-85eb8c103c9e460917911b43c6be302c30d75efb.tar.bz2
- 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
Diffstat (limited to 'Doc/library')
-rw-r--r--Doc/library/functions.rst98
-rw-r--r--Doc/library/pickle.rst2
-rw-r--r--Doc/library/sqlite3.rst5
-rw-r--r--Doc/library/stdtypes.rst16
4 files changed, 70 insertions, 51 deletions
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 168be0b..7390fd4 100644
--- a/Doc/library/functions.rst
+++ b/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
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index ab19ff8..1872724 100644
--- a/Doc/library/pickle.rst
+++ b/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
diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index bee32e6..a55fe86 100644
--- a/Doc/library/sqlite3.rst
+++ b/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
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 084c07c..9fd6e44 100644
--- a/Doc/library/stdtypes.rst
+++ b/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