diff options
author | Georg Brandl <georg@python.org> | 2007-08-31 16:33:38 (GMT) |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2007-08-31 16:33:38 (GMT) |
commit | 85eb8c103c9e460917911b43c6be302c30d75efb (patch) | |
tree | 2cbb4ff9497eb9db774e40d4f84abb368a311ed6 /Doc/library | |
parent | 3540ef16c19f2260e347a679cb27d44ba734bec6 (diff) | |
download | cpython-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.rst | 98 | ||||
-rw-r--r-- | Doc/library/pickle.rst | 2 | ||||
-rw-r--r-- | Doc/library/sqlite3.rst | 5 | ||||
-rw-r--r-- | Doc/library/stdtypes.rst | 16 |
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 |