mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 19:34:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Documented __import__, callable, isinstance, issubclass,

Browse source 
and slice.
This commit is contained in:
Guido van Rossum 1997-10-05 18:53:00 +00:00
parent df3dba049d
commit 7974b0f2d8
2 changed files with 166 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

86
Doc/lib/libfuncs.tex
View file

@ -5,6 +5,47 @@ are always available. They are listed here in alphabetical order.
\renewcommand{\indexsubitem}{(built-in function)} \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} \begin{funcdesc}{abs}{x}
Return the absolute value of a number. The argument may be a plain 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 or long integer or a floating point number. If the argument is a
@ -24,6 +65,14 @@ dictionary whose keys are strings. It specifies keyword arguments to
be added to the end of the the argument list. be added to the end of the the argument list.
\end{funcdesc} \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} \begin{funcdesc}{chr}{i}
Return a string of one character whose \ASCII{} code is the integer 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 \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} \end{funcdesc}
\begin{funcdesc}{dir}{} \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 Without arguments, return the list of names in the current local
symbol table. With a module, class or class instance object as symbol table. With a module, class or class instance object as
argument (or anything else that has a \code{__dict__} attribute), 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.} language definition should require truncation towards zero.}
\end{funcdesc} \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} \begin{funcdesc}{len}{s}
Return the length (the number of items) of an object. The argument Return the length (the number of items) of an object. The argument
may be a sequence (string, tuple or list) or a mapping (dictionary). 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. 35000)} is not allowed.
\end{funcdesc} \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 This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \code{for} loops. The progressions. It is most often used in \code{for} loops. The
arguments must be plain integers. If the \var{step} argument is 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}, plain integers \code{[\var{start}, \var{start} + \var{step},
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive, \var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
the last element is the largest \code{\var{start} + \var{i} * 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}} 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: exception is raised). Example:
\bcode\begin{verbatim} \bcode\begin{verbatim}
@ -499,6 +565,18 @@ when passed to \code{eval()}.
\code{\var{x}.\var{foobar} = 123}. \code{\var{x}.\var{foobar} = 123}.
\end{funcdesc} \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} \begin{funcdesc}{str}{object}
Return a string containing a nicely printable representation of an Return a string containing a nicely printable representation of an
object. For strings, this returns the string itself. The difference 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.} other scopes (e.g. modules) can be. This may change.}
\end{funcdesc} \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 This function is very similar to \code{range()}, but returns an
``xrange object'' instead of a list. This is an opaque sequence type ``xrange object'' instead of a list. This is an opaque sequence type
which yields the same values as the corresponding list, without which yields the same values as the corresponding list, without

86
Doc/libfuncs.tex
View file

@ -5,6 +5,47 @@ are always available. They are listed here in alphabetical order.
\renewcommand{\indexsubitem}{(built-in function)} \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} \begin{funcdesc}{abs}{x}
Return the absolute value of a number. The argument may be a plain 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 or long integer or a floating point number. If the argument is a
@ -24,6 +65,14 @@ dictionary whose keys are strings. It specifies keyword arguments to
be added to the end of the the argument list. be added to the end of the the argument list.
\end{funcdesc} \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} \begin{funcdesc}{chr}{i}
Return a string of one character whose \ASCII{} code is the integer 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 \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} \end{funcdesc}
\begin{funcdesc}{dir}{} \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 Without arguments, return the list of names in the current local
symbol table. With a module, class or class instance object as symbol table. With a module, class or class instance object as
argument (or anything else that has a \code{__dict__} attribute), 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.} language definition should require truncation towards zero.}
\end{funcdesc} \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} \begin{funcdesc}{len}{s}
Return the length (the number of items) of an object. The argument Return the length (the number of items) of an object. The argument
may be a sequence (string, tuple or list) or a mapping (dictionary). 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. 35000)} is not allowed.
\end{funcdesc} \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 This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \code{for} loops. The progressions. It is most often used in \code{for} loops. The
arguments must be plain integers. If the \var{step} argument is 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}, plain integers \code{[\var{start}, \var{start} + \var{step},
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive, \var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
the last element is the largest \code{\var{start} + \var{i} * 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}} 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: exception is raised). Example:
\bcode\begin{verbatim} \bcode\begin{verbatim}
@ -499,6 +565,18 @@ when passed to \code{eval()}.
\code{\var{x}.\var{foobar} = 123}. \code{\var{x}.\var{foobar} = 123}.
\end{funcdesc} \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} \begin{funcdesc}{str}{object}
Return a string containing a nicely printable representation of an Return a string containing a nicely printable representation of an
object. For strings, this returns the string itself. The difference 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.} other scopes (e.g. modules) can be. This may change.}
\end{funcdesc} \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 This function is very similar to \code{range()}, but returns an
``xrange object'' instead of a list. This is an opaque sequence type ``xrange object'' instead of a list. This is an opaque sequence type
which yields the same values as the corresponding list, without which yields the same values as the corresponding list, without