summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1997-10-05 18:53:00 (GMT)
committerGuido van Rossum <guido@python.org>1997-10-05 18:53:00 (GMT)
commit7974b0f2d8a91b4b2783e8bb93b8b809de833cf1 (patch)
tree6bc05163e25f1fa035128818565aa8a696595819
parentdf3dba049d4b7b8e2484d278c21e1025361a7776 (diff)
downloadcpython-7974b0f2d8a91b4b2783e8bb93b8b809de833cf1.zip
cpython-7974b0f2d8a91b4b2783e8bb93b8b809de833cf1.tar.gz
cpython-7974b0f2d8a91b4b2783e8bb93b8b809de833cf1.tar.bz2
Documented __import__, callable, isinstance, issubclass,
and slice.
-rw-r--r--Doc/lib/libfuncs.tex88
-rw-r--r--Doc/libfuncs.tex88
2 files changed, 166 insertions, 10 deletions
diff --git a/Doc/lib/libfuncs.tex b/Doc/lib/libfuncs.tex
index 0ef8201..0211cec 100644
--- a/Doc/lib/libfuncs.tex
+++ b/Doc/lib/libfuncs.tex
@@ -5,10 +5,51 @@ are always available. They are listed here in alphabetical order.
\renewcommand{\indexsubitem}{(built-in function)}
+
+\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist}}}}
+This function is invoked by the \code{import} statement. It
+mainly exists so that you can replace it with another
+function that has a compatible interface, in order to change the
+semantics of the \code{import} statement. For examples of why and
+how you would do this, see the standard library modules \code{ni},
+\code{ihooks} and \code{rexec}. See also the built-in module
+\code{imp}, which defines some useful operations out of which you can
+build your own \code{__import__} function.
+\stindex{import}
+\stmodindex{ni}
+\stmodindex{ihooks}
+\stmodindex{rexec}
+\bimodindex{imp}
+
+For example, the statement \code{import spam} results in the following
+call:
+\code{__import__('spam', globals(), locals(), [])};
+the statement \code{from spam.ham import eggs} results in
+\code{__import__('spam.ham', globals(), locals(), ['eggs'])}.
+Note that even though \code{locals()} and \code{['eggs']} are passed
+in as arguments, the \code{__import__()} function does not set the
+local variable named \code{eggs}; this is done by subsequent code that
+is generated for the import statement. (In fact, the standard
+implementation does not use its \var{locals} argument at all, and uses
+its \var{globals} only to determine the package context of the
+\code{import} statement.)
+
+When the \var{name} variable is of the form \code{package.module},
+normally, the top-level package (the name up till the first dot) is
+returned, \emph{not} the module named by \var{name}. However, when a
+non-empty \var{fromlist} argument is given, the module named by
+\var{name} is returned. This is done for compatibility with the
+bytecode generated for the different kinds of import statement; when
+using \code{import spam.ham.eggs}, the top-level package \code{spam}
+must be placed in the importing namespace, but when using \code{from
+spam.ham import eggs}, the \code{spam.ham} subpackage must be used to
+find the \code{eggs} variable.
+\end{funcdesc}
+
\begin{funcdesc}{abs}{x}
Return the absolute value of a number. The argument may be a plain
or long integer or a floating point number. If the argument is a
- complex number, its magnitude is returned.
+ complex number, its magnitude is returned.
\end{funcdesc}
\begin{funcdesc}{apply}{function\, args\optional{, keywords}}
@@ -24,6 +65,14 @@ dictionary whose keys are strings. It specifies keyword arguments to
be added to the end of the the argument list.
\end{funcdesc}
+\begin{funcdesc}{callable}{object}
+Return true if the \var{object} argument appears callable, false if
+not. If this returns true, it is still possible that a call fails,
+but if it is false, calling \var{object} will never succeed. Note
+that classes are callable (calling a class returns a new instance);
+class instances are callable if they have an attribute \code{__call__}.
+\end{funcdesc}
+
\begin{funcdesc}{chr}{i}
Return a string of one character whose \ASCII{} code is the integer
\var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
@@ -76,6 +125,9 @@ be added to the end of the the argument list.
\end{funcdesc}
\begin{funcdesc}{dir}{}
+XXX New functionality takes anything and looks in __dict__,
+__methods__, __members__.
+
Without arguments, return the list of names in the current local
symbol table. With a module, class or class instance object as
argument (or anything else that has a \code{__dict__} attribute),
@@ -253,6 +305,20 @@ module from which it is called).
language definition should require truncation towards zero.}
\end{funcdesc}
+\begin{funcdesc}{isinstance}{object, class}
+Return true if the \var{object} argument is an instance of the
+\var{class} argument, or of a (direct or indirect) subclass thereof.
+If \var{object} is not a class instance, the function always returns
+false. If \var{class} is not a class object, a \code{TypeError}
+exception is raised.
+\end{funcdesc}
+
+\begin{funcdesc}{issubclass}{class1, class2}
+Return true if \var{class1} is a subclass (direct or indirect) of
+\var{class2}. A class is considered a subclass of itself. If either
+argument is not a class object, a \code{TypeError} exception is raised.
+\end{funcdesc}
+
\begin{funcdesc}{len}{s}
Return the length (the number of items) of an object. The argument
may be a sequence (string, tuple or list) or a mapping (dictionary).
@@ -365,7 +431,7 @@ there's no reliable way to determine whether this is the case.}
35000)} is not allowed.
\end{funcdesc}
-\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
+\begin{funcdesc}{range}{\optional{start\,} stop\optional{\, step}}
This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \code{for} loops. The
arguments must be plain integers. If the \var{step} argument is
@@ -374,9 +440,9 @@ there's no reliable way to determine whether this is the case.}
plain integers \code{[\var{start}, \var{start} + \var{step},
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
the last element is the largest \code{\var{start} + \var{i} *
- \var{step}} less than \var{end}; if \var{step} is negative, the last
+ \var{step}} less than \var{stop}; if \var{step} is negative, the last
element is the largest \code{\var{start} + \var{i} * \var{step}}
- greater than \var{end}. \var{step} must not be zero (or else an
+ greater than \var{stop}. \var{step} must not be zero (or else an
exception is raised). Example:
\bcode\begin{verbatim}
@@ -499,6 +565,18 @@ when passed to \code{eval()}.
\code{\var{x}.\var{foobar} = 123}.
\end{funcdesc}
+\begin{funcdesc}{slice}{\optional{start\,} stop\optional{\, step}}
+Return a slice object representing the set of indices specified by
+\code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
+and \var{step} arguments default to None. Slice objects have
+read-only data attributes \code{start}, \code{stop} and \code{step}
+which merely return the argument values (or their default). They have
+no other explicit functionality; however they are used by Numerical
+Python and other third party extensions. Slice objects are also
+generated when extended indexing syntax is used, e.g. for
+\code{a[start:stop:step]} or \code{a[start:stop, i]}.
+\end{funcdesc}
+
\begin{funcdesc}{str}{object}
Return a string containing a nicely printable representation of an
object. For strings, this returns the string itself. The difference
@@ -541,7 +619,7 @@ cannot normally be affected this way, but variables retrieved from
other scopes (e.g. modules) can be. This may change.}
\end{funcdesc}
-\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
+\begin{funcdesc}{xrange}{\optional{start\,} stop\optional{\, step}}
This function is very similar to \code{range()}, but returns an
``xrange object'' instead of a list. This is an opaque sequence type
which yields the same values as the corresponding list, without
diff --git a/Doc/libfuncs.tex b/Doc/libfuncs.tex
index 0ef8201..0211cec 100644
--- a/Doc/libfuncs.tex
+++ b/Doc/libfuncs.tex
@@ -5,10 +5,51 @@ are always available. They are listed here in alphabetical order.
\renewcommand{\indexsubitem}{(built-in function)}
+
+\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist}}}}
+This function is invoked by the \code{import} statement. It
+mainly exists so that you can replace it with another
+function that has a compatible interface, in order to change the
+semantics of the \code{import} statement. For examples of why and
+how you would do this, see the standard library modules \code{ni},
+\code{ihooks} and \code{rexec}. See also the built-in module
+\code{imp}, which defines some useful operations out of which you can
+build your own \code{__import__} function.
+\stindex{import}
+\stmodindex{ni}
+\stmodindex{ihooks}
+\stmodindex{rexec}
+\bimodindex{imp}
+
+For example, the statement \code{import spam} results in the following
+call:
+\code{__import__('spam', globals(), locals(), [])};
+the statement \code{from spam.ham import eggs} results in
+\code{__import__('spam.ham', globals(), locals(), ['eggs'])}.
+Note that even though \code{locals()} and \code{['eggs']} are passed
+in as arguments, the \code{__import__()} function does not set the
+local variable named \code{eggs}; this is done by subsequent code that
+is generated for the import statement. (In fact, the standard
+implementation does not use its \var{locals} argument at all, and uses
+its \var{globals} only to determine the package context of the
+\code{import} statement.)
+
+When the \var{name} variable is of the form \code{package.module},
+normally, the top-level package (the name up till the first dot) is
+returned, \emph{not} the module named by \var{name}. However, when a
+non-empty \var{fromlist} argument is given, the module named by
+\var{name} is returned. This is done for compatibility with the
+bytecode generated for the different kinds of import statement; when
+using \code{import spam.ham.eggs}, the top-level package \code{spam}
+must be placed in the importing namespace, but when using \code{from
+spam.ham import eggs}, the \code{spam.ham} subpackage must be used to
+find the \code{eggs} variable.
+\end{funcdesc}
+
\begin{funcdesc}{abs}{x}
Return the absolute value of a number. The argument may be a plain
or long integer or a floating point number. If the argument is a
- complex number, its magnitude is returned.
+ complex number, its magnitude is returned.
\end{funcdesc}
\begin{funcdesc}{apply}{function\, args\optional{, keywords}}
@@ -24,6 +65,14 @@ dictionary whose keys are strings. It specifies keyword arguments to
be added to the end of the the argument list.
\end{funcdesc}
+\begin{funcdesc}{callable}{object}
+Return true if the \var{object} argument appears callable, false if
+not. If this returns true, it is still possible that a call fails,
+but if it is false, calling \var{object} will never succeed. Note
+that classes are callable (calling a class returns a new instance);
+class instances are callable if they have an attribute \code{__call__}.
+\end{funcdesc}
+
\begin{funcdesc}{chr}{i}
Return a string of one character whose \ASCII{} code is the integer
\var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
@@ -76,6 +125,9 @@ be added to the end of the the argument list.
\end{funcdesc}
\begin{funcdesc}{dir}{}
+XXX New functionality takes anything and looks in __dict__,
+__methods__, __members__.
+
Without arguments, return the list of names in the current local
symbol table. With a module, class or class instance object as
argument (or anything else that has a \code{__dict__} attribute),
@@ -253,6 +305,20 @@ module from which it is called).
language definition should require truncation towards zero.}
\end{funcdesc}
+\begin{funcdesc}{isinstance}{object, class}
+Return true if the \var{object} argument is an instance of the
+\var{class} argument, or of a (direct or indirect) subclass thereof.
+If \var{object} is not a class instance, the function always returns
+false. If \var{class} is not a class object, a \code{TypeError}
+exception is raised.
+\end{funcdesc}
+
+\begin{funcdesc}{issubclass}{class1, class2}
+Return true if \var{class1} is a subclass (direct or indirect) of
+\var{class2}. A class is considered a subclass of itself. If either
+argument is not a class object, a \code{TypeError} exception is raised.
+\end{funcdesc}
+
\begin{funcdesc}{len}{s}
Return the length (the number of items) of an object. The argument
may be a sequence (string, tuple or list) or a mapping (dictionary).
@@ -365,7 +431,7 @@ there's no reliable way to determine whether this is the case.}
35000)} is not allowed.
\end{funcdesc}
-\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
+\begin{funcdesc}{range}{\optional{start\,} stop\optional{\, step}}
This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \code{for} loops. The
arguments must be plain integers. If the \var{step} argument is
@@ -374,9 +440,9 @@ there's no reliable way to determine whether this is the case.}
plain integers \code{[\var{start}, \var{start} + \var{step},
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
the last element is the largest \code{\var{start} + \var{i} *
- \var{step}} less than \var{end}; if \var{step} is negative, the last
+ \var{step}} less than \var{stop}; if \var{step} is negative, the last
element is the largest \code{\var{start} + \var{i} * \var{step}}
- greater than \var{end}. \var{step} must not be zero (or else an
+ greater than \var{stop}. \var{step} must not be zero (or else an
exception is raised). Example:
\bcode\begin{verbatim}
@@ -499,6 +565,18 @@ when passed to \code{eval()}.
\code{\var{x}.\var{foobar} = 123}.
\end{funcdesc}
+\begin{funcdesc}{slice}{\optional{start\,} stop\optional{\, step}}
+Return a slice object representing the set of indices specified by
+\code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
+and \var{step} arguments default to None. Slice objects have
+read-only data attributes \code{start}, \code{stop} and \code{step}
+which merely return the argument values (or their default). They have
+no other explicit functionality; however they are used by Numerical
+Python and other third party extensions. Slice objects are also
+generated when extended indexing syntax is used, e.g. for
+\code{a[start:stop:step]} or \code{a[start:stop, i]}.
+\end{funcdesc}
+
\begin{funcdesc}{str}{object}
Return a string containing a nicely printable representation of an
object. For strings, this returns the string itself. The difference
@@ -541,7 +619,7 @@ cannot normally be affected this way, but variables retrieved from
other scopes (e.g. modules) can be. This may change.}
\end{funcdesc}
-\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
+\begin{funcdesc}{xrange}{\optional{start\,} stop\optional{\, step}}
This function is very similar to \code{range()}, but returns an
``xrange object'' instead of a list. This is an opaque sequence type
which yields the same values as the corresponding list, without