Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 7974b0f

Browse files
gvanrossumgvanrossum
committed
Documented __import__, callable, isinstance, issubclass,
and slice.
1 parent df3dba0 commit 7974b0f

2 files changed

Lines changed: 166 additions & 10 deletions

File tree

‎Doc/lib/libfuncs.tex‎

Lines changed: 83 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,51 @@ \section{Built-in Functions}
55

66

77
\renewcommand{\indexsubitem}{(built-in function)}
8+
9+
\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist}}}}
10+
This function is invoked by the \code{import} statement. It
11+
mainly exists so that you can replace it with another
12+
function that has a compatible interface, in order to change the
13+
semantics of the \code{import} statement. For examples of why and
14+
how you would do this, see the standard library modules \code{ni},
15+
\code{ihooks} and \code{rexec}. See also the built-in module
16+
\code{imp}, which defines some useful operations out of which you can
17+
build your own \code{__import__} function.
18+
\stindex{import}
19+
\stmodindex{ni}
20+
\stmodindex{ihooks}
21+
\stmodindex{rexec}
22+
\bimodindex{imp}
23+
24+
For example, the statement \code{import spam} results in the following
25+
call:
26+
\code{__import__('spam', globals(), locals(), [])};
27+
the statement \code{from spam.ham import eggs} results in
28+
\code{__import__('spam.ham', globals(), locals(), ['eggs'])}.
29+
Note that even though \code{locals()} and \code{['eggs']} are passed
30+
in as arguments, the \code{__import__()} function does not set the
31+
local variable named \code{eggs}; this is done by subsequent code that
32+
is generated for the import statement. (In fact, the standard
33+
implementation does not use its \var{locals} argument at all, and uses
34+
its \var{globals} only to determine the package context of the
35+
\code{import} statement.)
36+
37+
When the \var{name} variable is of the form \code{package.module},
38+
normally, the top-level package (the name up till the first dot) is
39+
returned, \emph{not} the module named by \var{name}. However, when a
40+
non-empty \var{fromlist} argument is given, the module named by
41+
\var{name} is returned. This is done for compatibility with the
42+
bytecode generated for the different kinds of import statement; when
43+
using \code{import spam.ham.eggs}, the top-level package \code{spam}
44+
must be placed in the importing namespace, but when using \code{from
45+
spam.ham import eggs}, the \code{spam.ham} subpackage must be used to
46+
find the \code{eggs} variable.
47+
\end{funcdesc}
48+
849
\begin{funcdesc}{abs}{x}
950
Return the absolute value of a number. The argument may be a plain
1051
or long integer or a floating point number. If the argument is a
11-
complex number, its magnitude is returned.
52+
complex number, its magnitude is returned.
1253
\end{funcdesc}
1354

1455
\begin{funcdesc}{apply}{function\, args\optional{, keywords}}
@@ -24,6 +65,14 @@ \section{Built-in Functions}
2465
be added to the end of the the argument list.
2566
\end{funcdesc}
2667

68+
\begin{funcdesc}{callable}{object}
69+
Return true if the \var{object} argument appears callable, false if
70+
not. If this returns true, it is still possible that a call fails,
71+
but if it is false, calling \var{object} will never succeed. Note
72+
that classes are callable (calling a class returns a new instance);
73+
class instances are callable if they have an attribute \code{__call__}.
74+
\end{funcdesc}
75+
2776
\begin{funcdesc}{chr}{i}
2877
Return a string of one character whose \ASCII{} code is the integer
2978
\var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
@@ -76,6 +125,9 @@ \section{Built-in Functions}
76125
\end{funcdesc}
77126

78127
\begin{funcdesc}{dir}{}
128+
XXX New functionality takes anything and looks in __dict__,
129+
__methods__, __members__.
130+
79131
Without arguments, return the list of names in the current local
80132
symbol table. With a module, class or class instance object as
81133
argument (or anything else that has a \code{__dict__} attribute),
@@ -253,6 +305,20 @@ \section{Built-in Functions}
253305
language definition should require truncation towards zero.}
254306
\end{funcdesc}
255307

308+
\begin{funcdesc}{isinstance}{object, class}
309+
Return true if the \var{object} argument is an instance of the
310+
\var{class} argument, or of a (direct or indirect) subclass thereof.
311+
If \var{object} is not a class instance, the function always returns
312+
false. If \var{class} is not a class object, a \code{TypeError}
313+
exception is raised.
314+
\end{funcdesc}
315+
316+
\begin{funcdesc}{issubclass}{class1, class2}
317+
Return true if \var{class1} is a subclass (direct or indirect) of
318+
\var{class2}. A class is considered a subclass of itself. If either
319+
argument is not a class object, a \code{TypeError} exception is raised.
320+
\end{funcdesc}
321+
256322
\begin{funcdesc}{len}{s}
257323
Return the length (the number of items) of an object. The argument
258324
may be a sequence (string, tuple or list) or a mapping (dictionary).
@@ -365,7 +431,7 @@ \section{Built-in Functions}
365431
35000)} is not allowed.
366432
\end{funcdesc}
367433

368-
\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
434+
\begin{funcdesc}{range}{\optional{start\,} stop\optional{\, step}}
369435
This is a versatile function to create lists containing arithmetic
370436
progressions. It is most often used in \code{for} loops. The
371437
arguments must be plain integers. If the \var{step} argument is
@@ -374,9 +440,9 @@ \section{Built-in Functions}
374440
plain integers \code{[\var{start}, \var{start} + \var{step},
375441
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
376442
the last element is the largest \code{\var{start} + \var{i} *
377-
\var{step}} less than \var{end}; if \var{step} is negative, the last
443+
\var{step}} less than \var{stop}; if \var{step} is negative, the last
378444
element is the largest \code{\var{start} + \var{i} * \var{step}}
379-
greater than \var{end}. \var{step} must not be zero (or else an
445+
greater than \var{stop}. \var{step} must not be zero (or else an
380446
exception is raised). Example:
381447

382448
\bcode\begin{verbatim}
@@ -499,6 +565,18 @@ \section{Built-in Functions}
499565
\code{\var{x}.\var{foobar} = 123}.
500566
\end{funcdesc}
501567

568+
\begin{funcdesc}{slice}{\optional{start\,} stop\optional{\, step}}
569+
Return a slice object representing the set of indices specified by
570+
\code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
571+
and \var{step} arguments default to None. Slice objects have
572+
read-only data attributes \code{start}, \code{stop} and \code{step}
573+
which merely return the argument values (or their default). They have
574+
no other explicit functionality; however they are used by Numerical
575+
Python and other third party extensions. Slice objects are also
576+
generated when extended indexing syntax is used, e.g. for
577+
\code{a[start:stop:step]} or \code{a[start:stop, i]}.
578+
\end{funcdesc}
579+
502580
\begin{funcdesc}{str}{object}
503581
Return a string containing a nicely printable representation of an
504582
object. For strings, this returns the string itself. The difference
@@ -541,7 +619,7 @@ \section{Built-in Functions}
541619
other scopes (e.g. modules) can be. This may change.}
542620
\end{funcdesc}
543621

544-
\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
622+
\begin{funcdesc}{xrange}{\optional{start\,} stop\optional{\, step}}
545623
This function is very similar to \code{range()}, but returns an
546624
``xrange object'' instead of a list. This is an opaque sequence type
547625
which yields the same values as the corresponding list, without

‎Doc/libfuncs.tex‎

Lines changed: 83 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,51 @@ \section{Built-in Functions}
55

66

77
\renewcommand{\indexsubitem}{(built-in function)}
8+
9+
\begin{funcdesc}{__import__}{name\optional{, globals\optional{, locals\optional{, fromlist}}}}
10+
This function is invoked by the \code{import} statement. It
11+
mainly exists so that you can replace it with another
12+
function that has a compatible interface, in order to change the
13+
semantics of the \code{import} statement. For examples of why and
14+
how you would do this, see the standard library modules \code{ni},
15+
\code{ihooks} and \code{rexec}. See also the built-in module
16+
\code{imp}, which defines some useful operations out of which you can
17+
build your own \code{__import__} function.
18+
\stindex{import}
19+
\stmodindex{ni}
20+
\stmodindex{ihooks}
21+
\stmodindex{rexec}
22+
\bimodindex{imp}
23+
24+
For example, the statement \code{import spam} results in the following
25+
call:
26+
\code{__import__('spam', globals(), locals(), [])};
27+
the statement \code{from spam.ham import eggs} results in
28+
\code{__import__('spam.ham', globals(), locals(), ['eggs'])}.
29+
Note that even though \code{locals()} and \code{['eggs']} are passed
30+
in as arguments, the \code{__import__()} function does not set the
31+
local variable named \code{eggs}; this is done by subsequent code that
32+
is generated for the import statement. (In fact, the standard
33+
implementation does not use its \var{locals} argument at all, and uses
34+
its \var{globals} only to determine the package context of the
35+
\code{import} statement.)
36+
37+
When the \var{name} variable is of the form \code{package.module},
38+
normally, the top-level package (the name up till the first dot) is
39+
returned, \emph{not} the module named by \var{name}. However, when a
40+
non-empty \var{fromlist} argument is given, the module named by
41+
\var{name} is returned. This is done for compatibility with the
42+
bytecode generated for the different kinds of import statement; when
43+
using \code{import spam.ham.eggs}, the top-level package \code{spam}
44+
must be placed in the importing namespace, but when using \code{from
45+
spam.ham import eggs}, the \code{spam.ham} subpackage must be used to
46+
find the \code{eggs} variable.
47+
\end{funcdesc}
48+
849
\begin{funcdesc}{abs}{x}
950
Return the absolute value of a number. The argument may be a plain
1051
or long integer or a floating point number. If the argument is a
11-
complex number, its magnitude is returned.
52+
complex number, its magnitude is returned.
1253
\end{funcdesc}
1354

1455
\begin{funcdesc}{apply}{function\, args\optional{, keywords}}
@@ -24,6 +65,14 @@ \section{Built-in Functions}
2465
be added to the end of the the argument list.
2566
\end{funcdesc}
2667

68+
\begin{funcdesc}{callable}{object}
69+
Return true if the \var{object} argument appears callable, false if
70+
not. If this returns true, it is still possible that a call fails,
71+
but if it is false, calling \var{object} will never succeed. Note
72+
that classes are callable (calling a class returns a new instance);
73+
class instances are callable if they have an attribute \code{__call__}.
74+
\end{funcdesc}
75+
2776
\begin{funcdesc}{chr}{i}
2877
Return a string of one character whose \ASCII{} code is the integer
2978
\var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
@@ -76,6 +125,9 @@ \section{Built-in Functions}
76125
\end{funcdesc}
77126

78127
\begin{funcdesc}{dir}{}
128+
XXX New functionality takes anything and looks in __dict__,
129+
__methods__, __members__.
130+
79131
Without arguments, return the list of names in the current local
80132
symbol table. With a module, class or class instance object as
81133
argument (or anything else that has a \code{__dict__} attribute),
@@ -253,6 +305,20 @@ \section{Built-in Functions}
253305
language definition should require truncation towards zero.}
254306
\end{funcdesc}
255307

308+
\begin{funcdesc}{isinstance}{object, class}
309+
Return true if the \var{object} argument is an instance of the
310+
\var{class} argument, or of a (direct or indirect) subclass thereof.
311+
If \var{object} is not a class instance, the function always returns
312+
false. If \var{class} is not a class object, a \code{TypeError}
313+
exception is raised.
314+
\end{funcdesc}
315+
316+
\begin{funcdesc}{issubclass}{class1, class2}
317+
Return true if \var{class1} is a subclass (direct or indirect) of
318+
\var{class2}. A class is considered a subclass of itself. If either
319+
argument is not a class object, a \code{TypeError} exception is raised.
320+
\end{funcdesc}
321+
256322
\begin{funcdesc}{len}{s}
257323
Return the length (the number of items) of an object. The argument
258324
may be a sequence (string, tuple or list) or a mapping (dictionary).
@@ -365,7 +431,7 @@ \section{Built-in Functions}
365431
35000)} is not allowed.
366432
\end{funcdesc}
367433

368-
\begin{funcdesc}{range}{\optional{start\,} end\optional{\, step}}
434+
\begin{funcdesc}{range}{\optional{start\,} stop\optional{\, step}}
369435
This is a versatile function to create lists containing arithmetic
370436
progressions. It is most often used in \code{for} loops. The
371437
arguments must be plain integers. If the \var{step} argument is
@@ -374,9 +440,9 @@ \section{Built-in Functions}
374440
plain integers \code{[\var{start}, \var{start} + \var{step},
375441
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
376442
the last element is the largest \code{\var{start} + \var{i} *
377-
\var{step}} less than \var{end}; if \var{step} is negative, the last
443+
\var{step}} less than \var{stop}; if \var{step} is negative, the last
378444
element is the largest \code{\var{start} + \var{i} * \var{step}}
379-
greater than \var{end}. \var{step} must not be zero (or else an
445+
greater than \var{stop}. \var{step} must not be zero (or else an
380446
exception is raised). Example:
381447

382448
\bcode\begin{verbatim}
@@ -499,6 +565,18 @@ \section{Built-in Functions}
499565
\code{\var{x}.\var{foobar} = 123}.
500566
\end{funcdesc}
501567

568+
\begin{funcdesc}{slice}{\optional{start\,} stop\optional{\, step}}
569+
Return a slice object representing the set of indices specified by
570+
\code{range(\var{start}, \var{stop}, \var{step})}. The \var{start}
571+
and \var{step} arguments default to None. Slice objects have
572+
read-only data attributes \code{start}, \code{stop} and \code{step}
573+
which merely return the argument values (or their default). They have
574+
no other explicit functionality; however they are used by Numerical
575+
Python and other third party extensions. Slice objects are also
576+
generated when extended indexing syntax is used, e.g. for
577+
\code{a[start:stop:step]} or \code{a[start:stop, i]}.
578+
\end{funcdesc}
579+
502580
\begin{funcdesc}{str}{object}
503581
Return a string containing a nicely printable representation of an
504582
object. For strings, this returns the string itself. The difference
@@ -541,7 +619,7 @@ \section{Built-in Functions}
541619
other scopes (e.g. modules) can be. This may change.}
542620
\end{funcdesc}
543621

544-
\begin{funcdesc}{xrange}{\optional{start\,} end\optional{\, step}}
622+
\begin{funcdesc}{xrange}{\optional{start\,} stop\optional{\, step}}
545623
This function is very similar to \code{range()}, but returns an
546624
``xrange object'' instead of a list. This is an opaque sequence type
547625
which yields the same values as the corresponding list, without

0 commit comments

Comments
 (0)