| \section{Built-in Types} |
| |
| The following sections describe the standard types that are built into |
| the interpreter. These are the numeric types, sequence types, and |
| several others, including types themselves. There is no explicit |
| Boolean type; use integers instead. |
| \indexii{built-in}{types} |
| \indexii{Boolean}{type} |
| |
| Some operations are supported by several object types; in particular, |
| all objects can be compared, tested for truth value, and converted to |
| a string (with the \code{`{\rm \ldots}`} notation). The latter conversion is |
| implicitly used when an object is written by the \code{print} statement. |
| \stindex{print} |
| |
| \subsection{Truth Value Testing} |
| |
| Any object can be tested for truth value, for use in an \code{if} or |
| \code{while} condition or as operand of the Boolean operations below. |
| The following values are false: |
| \stindex{if} |
| \stindex{while} |
| \indexii{truth}{value} |
| \indexii{Boolean}{operations} |
| \index{false} |
| |
| \begin{itemize} |
| \renewcommand{\indexsubitem}{(Built-in object)} |
| |
| \item \code{None} |
| \ttindex{None} |
| |
| \item zero of any numeric type, e.g., \code{0}, \code{0L}, \code{0.0}. |
| |
| \item any empty sequence, e.g., \code{''}, \code{()}, \code{[]}. |
| |
| \item any empty mapping, e.g., \code{\{\}}. |
| |
| \end{itemize} |
| |
| \emph{All} other values are true --- so objects of many types are |
| always true. |
| \index{true} |
| |
| \subsection{Boolean Operations} |
| |
| These are the Boolean operations: |
| \indexii{Boolean}{operations} |
| |
| \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| \lineiii{\var{x} or \var{y}}{if \var{x} is false, then \var{y}, else \var{x}}{(1)} |
| \lineiii{\var{x} and \var{y}}{if \var{x} is false, then \var{x}, else \var{y}}{(1)} |
| \lineiii{not \var{x}}{if \var{x} is false, then \code{1}, else \code{0}}{} |
| \end{tableiii} |
| \opindex{and} |
| \opindex{or} |
| \opindex{not} |
| |
| \noindent |
| Notes: |
| |
| \begin{description} |
| |
| \item[(1)] |
| These only evaluate their second argument if needed for their outcome. |
| |
| \end{description} |
| |
| \subsection{Comparisons} |
| |
| Comparison operations are supported by all objects: |
| |
| \begin{tableiii}{|c|l|c|}{code}{Operation}{Meaning}{Notes} |
| \lineiii{<}{strictly less than}{} |
| \lineiii{<=}{less than or equal}{} |
| \lineiii{>}{strictly greater than}{} |
| \lineiii{>=}{greater than or equal}{} |
| \lineiii{==}{equal}{} |
| \lineiii{<>}{not equal}{(1)} |
| \lineiii{!=}{not equal}{(1)} |
| \lineiii{is}{object identity}{} |
| \lineiii{is not}{negated object identity}{} |
| \end{tableiii} |
| \indexii{operator}{comparison} |
| \opindex{==} % XXX *All* others have funny characters < ! > |
| \opindex{is} |
| \opindex{is not} |
| |
| \noindent |
| Notes: |
| |
| \begin{description} |
| |
| \item[(1)] |
| \code{<>} and \code{!=} are alternate spellings for the same operator. |
| (I couldn't choose between \ABC{} and \C{}! :-) |
| \indexii{\ABC{}}{language} |
| \indexii{\C{}}{language} |
| |
| \end{description} |
| |
| Objects of different types, except different numeric types, never |
| compare equal; such objects are ordered consistently but arbitrarily |
| (so that sorting a heterogeneous array yields a consistent result). |
| Furthermore, some types (e.g., windows) support only a degenerate |
| notion of comparison where any two objects of that type are unequal. |
| Again, such objects are ordered arbitrarily but consistently. |
| \indexii{types}{numeric} |
| \indexii{objects}{comparing} |
| |
| (Implementation note: objects of different types except numbers are |
| ordered by their type names; objects of the same types that don't |
| support proper comparison are ordered by their address.) |
| |
| Two more operations with the same syntactic priority, \code{in} and |
| \code{not in}, are supported only by sequence types (below). |
| \opindex{in} |
| \opindex{not in} |
| |
| \subsection{Numeric Types} |
| |
| There are three numeric types: \dfn{plain integers}, \dfn{long integers}, and |
| \dfn{floating point numbers}. Plain integers (also just called \dfn{integers}) |
| are implemented using \code{long} in \C{}, which gives them at least 32 |
| bits of precision. Long integers have unlimited precision. Floating |
| point numbers are implemented using \code{double} in \C{}. All bets on |
| their precision are off unless you happen to know the machine you are |
| working with. |
| \indexii{numeric}{types} |
| \indexii{integer}{types} |
| \indexii{integer}{type} |
| \indexiii{long}{integer}{type} |
| \indexii{floating point}{type} |
| \indexii{\C{}}{language} |
| |
| Numbers are created by numeric literals or as the result of built-in |
| functions and operators. Unadorned integer literals (including hex |
| and octal numbers) yield plain integers. Integer literals with an \samp{L} |
| or \samp{l} suffix yield long integers |
| (\samp{L} is preferred because \code{1l} looks too much like eleven!). |
| Numeric literals containing a decimal point or an exponent sign yield |
| floating point numbers. |
| \indexii{numeric}{literals} |
| \indexii{integer}{literals} |
| \indexiii{long}{integer}{literals} |
| \indexii{floating point}{literals} |
| \indexii{hexadecimal}{literals} |
| \indexii{octal}{literals} |
| |
| Python fully supports mixed arithmetic: when a binary arithmetic |
| operator has operands of different numeric types, the operand with the |
| ``smaller'' type is converted to that of the other, where plain |
| integer is smaller than long integer is smaller than floating point. |
| Comparisons between numbers of mixed type use the same rule.% |
| \footnote{As a consequence, the list \code{[1, 2]} is considered equal |
| to \code{[1.0, 2.0]}, and similar for tuples.} |
| The functions \code{int()}, \code{long()} and \code{float()} can be used |
| to coerce numbers to a specific type. |
| \index{arithmetic} |
| \bifuncindex{int} |
| \bifuncindex{long} |
| \bifuncindex{float} |
| |
| All numeric types support the following operations: |
| |
| \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| \lineiii{abs(\var{x})}{absolute value of \var{x}}{} |
| \lineiii{int(\var{x})}{\var{x} converted to integer}{(1)} |
| \lineiii{long(\var{x})}{\var{x} converted to long integer}{(1)} |
| \lineiii{float(\var{x})}{\var{x} converted to floating point}{} |
| \lineiii{-\var{x}}{\var{x} negated}{} |
| \lineiii{+\var{x}}{\var{x} unchanged}{} |
| \lineiii{\var{x} + \var{y}}{sum of \var{x} and \var{y}}{} |
| \lineiii{\var{x} - \var{y}}{difference of \var{x} and \var{y}}{} |
| \lineiii{\var{x} * \var{y}}{product of \var{x} and \var{y}}{} |
| \lineiii{\var{x} / \var{y}}{quotient of \var{x} and \var{y}}{(2)} |
| \lineiii{\var{x} \%{} \var{y}}{remainder of \code{\var{x} / \var{y}}}{} |
| \lineiii{divmod(\var{x}, \var{y})}{the pair \code{(\var{x} / \var{y}, \var{x} \%{} \var{y})}}{(3)} |
| \lineiii{pow(\var{x}, \var{y})}{\var{x} to the power \var{y}}{} |
| \end{tableiii} |
| \indexiii{operations on}{numeric}{types} |
| |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] |
| Conversion from floating point to (long or plain) integer may round or |
| % XXXJH xref here |
| truncate as in \C{}; see functions \code{floor} and \code{ceil} in module |
| \code{math} for well-defined conversions. |
| \indexii{numeric}{conversions} |
| \ttindex{math} |
| \indexii{\C{}}{language} |
| |
| \item[(2)] |
| For (plain or long) integer division, the result is an integer; it |
| always truncates towards zero. |
| % XXXJH integer division is better defined nowadays |
| \indexii{integer}{division} |
| \indexiii{long}{integer}{division} |
| |
| \item[(3)] |
| See the section on built-in functions for an exact definition. |
| |
| \end{description} |
| % XXXJH exceptions: overflow (when? what operations?) zerodivision |
| |
| \subsubsection{Bit-string Operations on Integer Types.} |
| |
| Plain and long integer types support additional operations that make |
| sense only for bit-strings. Negative numbers are treated as their 2's |
| complement value: |
| |
| \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| \lineiii{\~\var{x}}{the bits of \var{x} inverted}{} |
| \lineiii{\var{x} \^{} \var{y}}{bitwise \dfn{exclusive or} of \var{x} and \var{y}}{} |
| \lineiii{\var{x} \&{} \var{y}}{bitwise \dfn{and} of \var{x} and \var{y}}{} |
| \lineiii{\var{x} | \var{y}}{bitwise \dfn{or} of \var{x} and \var{y}}{} |
| \lineiii{\var{x} << \var{n}}{\var{x} shifted left by \var{n} bits}{} |
| \lineiii{\var{x} >> \var{n}}{\var{x} shifted right by \var{n} bits}{} |
| \end{tableiii} |
| % XXXJH what's `left'? `right'? maybe better use lsb or msb or something |
| \indexiii{operations on}{integer}{types} |
| \indexii{bit-string}{operations} |
| \indexii{shifting}{operations} |
| \indexii{masking}{operations} |
| |
| \subsection{Sequence Types} |
| |
| There are three sequence types: strings, lists and tuples. |
| Strings literals are written in single quotes: \code{'xyzzy'}. |
| Lists are constructed with square brackets, |
| separating items with commas: |
| \code{[a, b, c]}. |
| Tuples are constructed by the comma operator |
| (not within square brackets), with or without enclosing parentheses, |
| but an empty tuple must have the enclosing parentheses, e.g., |
| \code{a, b, c} or \code{()}. A single item tuple must have a trailing comma, |
| e.g., \code{(d,)}. |
| \indexii{sequence}{types} |
| \indexii{string}{type} |
| \indexii{tuple}{type} |
| \indexii{list}{type} |
| |
| Sequence types support the following operations (\var{s} and \var{t} are |
| sequences of the same type; \var{n}, \var{i} and \var{j} are integers): |
| |
| \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| \lineiii{len(\var{s})}{length of \var{s}}{} |
| \lineiii{min(\var{s})}{smallest item of \var{s}}{} |
| \lineiii{max(\var{s})}{largest item of \var{s}}{} |
| \lineiii{\var{x} in \var{s}}{\code{1} if an item of \var{s} is equal to \var{x}, else \code{0}}{} |
| \lineiii{\var{x} not in \var{s}}{\code{0} if an item of \var{s} is equal to \var{x}, else \code{1}}{} |
| \lineiii{\var{s} + \var{t}}{the concatenation of \var{s} and \var{t}}{} |
| \lineiii{\var{s} * \var{n}{\rm ,} \var{n} * \var{s}}{\var{n} copies of \var{s} concatenated}{} |
| \lineiii{\var{s}[\var{i}]}{\var{i}'th item of \var{s}, origin 0}{(1)} |
| \lineiii{\var{s}[\var{i}:\var{j}]}{slice of \var{s} from \var{i} to \var{j}}{(1), (2)} |
| \end{tableiii} |
| \indexiii{operations on}{sequence}{types} |
| \bifuncindex{len} |
| \bifuncindex{min} |
| \bifuncindex{max} |
| \indexii{concatenation}{operation} |
| \indexii{repetition}{operation} |
| \indexii{subscript}{operation} |
| \indexii{slice}{operation} |
| \opindex{in} |
| \opindex{not in} |
| |
| \noindent |
| Notes: |
| |
| % XXXJH all TeX-math expressions replaced by python-syntax expressions |
| \begin{description} |
| |
| \item[(1)] If \var{i} or \var{j} is negative, the index is relative to |
| the end of the string, i.e., \code{len(\var{s}) + \var{i}} or |
| \code{len(\var{s}) + \var{j}} is substituted. But note that \code{-0} is |
| still \code{0}. |
| |
| \item[(2)] The slice of \var{s} from \var{i} to \var{j} is defined as |
| the sequence of items with index \var{k} such that \code{\var{i} <= |
| \var{k} < \var{j}}. If \var{i} or \var{j} is greater than |
| \code{len(\var{s})}, use \code{len(\var{s})}. If \var{i} is omitted, |
| use \code{0}. If \var{j} is omitted, use \code{len(\var{s})}. If |
| \var{i} is greater than or equal to \var{j}, the slice is empty. |
| |
| \end{description} |
| |
| \subsubsection{More String Operations.} |
| |
| String objects have one unique built-in operation: the \code{\%} |
| operator (modulo) with a string left argument interprets this string |
| as a C sprintf format string to be applied to the right argument, and |
| returns the string resulting from this formatting operation. |
| |
| The right argument should be a tuple with one item for each argument |
| required by the format string; if the string requires a single |
| argument, the right argument may also be a single non-tuple object.% |
| \footnote{A tuple object in this case should be a singleton.} |
| The following format characters are understood: |
| \%, c, s, i, d, u, o, x, X, e, E, f, g, G. |
| Width and precision may be a * to specify that an integer argument |
| specifies the actual width or precision. The flag characters -, +, |
| blank, \# and 0 are understood. The size specifiers h, l or L may be |
| present but are ignored. The \code{\%s} conversion takes any Python |
| object and converts it to a string using \code{str()} before |
| formatting it. The ANSI features \code{\%p} and \code{\%n} |
| are not supported. Since Python strings have an explicit length, |
| \code{\%s} conversions don't assume that \code{'\\0'} is the end of |
| the string. |
| |
| For safety reasons, floating point precisions are clipped to 50; |
| \code{\%f} conversions for numbers whose absolute value is over 1e25 |
| are replaced by \code{\%g} conversions.% |
| \footnote{These numbers are fairly arbitrary. They are intended to |
| avoid printing endless strings of meaningless digits without hampering |
| correct use and without having to know the exact precision of floating |
| point values on a particular machine.} |
| All other errors raise exceptions. |
| |
| If the right argument is a dictionary (or any kind of mapping), then |
| the formats in the string must have a parenthesized key into that |
| dictionary inserted immediately after the \code{\%} character, and |
| each format formats the corresponding entry from the mapping. E.g. |
| \begin{verbatim} |
| >>> count = 2 |
| >>> language = 'Python' |
| >>> print '%(language)s has %(count)03d quote types.' % vars() |
| Python has 002 quote types. |
| >>> |
| \end{verbatim} |
| In this case no * specifiers may occur in a format. |
| |
| Additional string operations are defined in standard module |
| \code{string} and in built-in module \code{regex}. |
| \index{string} |
| \index{regex} |
| |
| \subsubsection{Mutable Sequence Types.} |
| |
| List objects support additional operations that allow in-place |
| modification of the object. |
| These operations would be supported by other mutable sequence types |
| (when added to the language) as well. |
| Strings and tuples are immutable sequence types and such objects cannot |
| be modified once created. |
| The following operations are defined on mutable sequence types (where |
| \var{x} is an arbitrary object): |
| \indexiii{mutable}{sequence}{types} |
| \indexii{list}{type} |
| |
| \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| \lineiii{\var{s}[\var{i}] = \var{x}} |
| {item \var{i} of \var{s} is replaced by \var{x}}{} |
| \lineiii{\var{s}[\var{i}:\var{j}] = \var{t}} |
| {slice of \var{s} from \var{i} to \var{j} is replaced by \var{t}}{} |
| \lineiii{del \var{s}[\var{i}:\var{j}]} |
| {same as \code{\var{s}[\var{i}:\var{j}] = []}}{} |
| \lineiii{\var{s}.append(\var{x})} |
| {same as \code{\var{s}[len(\var{s}):len(\var{s})] = [\var{x}]}}{} |
| \lineiii{\var{s}.count(\var{x})} |
| {return number of \var{i}'s for which \code{\var{s}[\var{i}] == \var{x}}}{} |
| \lineiii{\var{s}.index(\var{x})} |
| {return smallest \var{i} such that \code{\var{s}[\var{i}] == \var{x}}}{(1)} |
| \lineiii{\var{s}.insert(\var{i}, \var{x})} |
| {same as \code{\var{s}[\var{i}:\var{i}] = [\var{x}]}}{} |
| \lineiii{\var{s}.remove(\var{x})} |
| {same as \code{del \var{s}[\var{s}.index(\var{x})]}}{(1)} |
| \lineiii{\var{s}.reverse()} |
| {reverses the items of \var{s} in place}{} |
| \lineiii{\var{s}.sort()} |
| {permutes the items of \var{s} to satisfy |
| \code{\var{s}[\var{i}] <= \var{s}[\var{j}]}, |
| for \code{\var{i} < \var{j}}}{(2)} |
| \end{tableiii} |
| \indexiv{operations on}{mutable}{sequence}{types} |
| \indexiii{operations on}{sequence}{types} |
| \indexiii{operations on}{list}{type} |
| \indexii{subscript}{assignment} |
| \indexii{slice}{assignment} |
| \stindex{del} |
| \renewcommand{\indexsubitem}{(list method)} |
| \ttindex{append} |
| \ttindex{count} |
| \ttindex{index} |
| \ttindex{insert} |
| \ttindex{remove} |
| \ttindex{reverse} |
| \ttindex{sort} |
| |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] Raises an exception when \var{x} is not found in \var{s}. |
| |
| \item[(2)] The \code{sort()} method takes an optional argument |
| specifying a comparison function of two arguments (list items) which |
| should return \code{-1}, \code{0} or \code{1} depending on whether the |
| first argument is considered smaller than, equal to, or larger than the |
| second argument. Note that this slows the sorting process down |
| considerably; e.g. to sort an array in reverse order it is much faster |
| to use calls to \code{sort()} and \code{reverse()} than to use |
| \code{sort()} with a comparison function that reverses the ordering of |
| the elements. |
| \end{description} |
| |
| \subsection{Mapping Types} |
| |
| A \dfn{mapping} object maps values of one type (the key type) to |
| arbitrary objects. Mappings are mutable objects. There is currently |
| only one mapping type, the \dfn{dictionary}. A dictionary's keys are |
| almost arbitrary values. The only types of values not acceptable as |
| keys are values containing lists or dictionaries or other mutable |
| types that are compared by value rather than by object identity. |
| Numeric types used for keys obey the normal rules for numeric |
| comparison: if two numbers compare equal (e.g. 1 and 1.0) then they |
| can be used interchangeably to index the same dictionary entry. |
| |
| \indexii{mapping}{types} |
| \indexii{dictionary}{type} |
| |
| Dictionaries are created by placing a comma-separated list of |
| \code{\var{key}: \var{value}} pairs within braces, for example: |
| \code{\{'jack': 4098, 'sjoerd: 4127\}} or |
| \code{\{4098: 'jack', 4127: 'sjoerd\}}. |
| |
| The following operations are defined on mappings (where \var{a} is a |
| mapping, \var{k} is a key and \var{x} is an arbitrary object): |
| |
| \begin{tableiii}{|c|l|c|}{code}{Operation}{Result}{Notes} |
| \lineiii{len(\var{a})}{the number of items in \var{a}}{} |
| \lineiii{\var{a}[\var{k}]}{the item of \var{a} with key \var{k}}{(1)} |
| \lineiii{\var{a}[\var{k}] = \var{x}}{set \code{\var{a}[\var{k}]} to \var{x}}{} |
| \lineiii{del \var{a}[\var{k}]}{remove \code{\var{a}[\var{k}]} from \var{a}}{(1)} |
| \lineiii{\var{a}.items()}{a copy of \var{a}'s list of (key, item) pairs}{(2)} |
| \lineiii{\var{a}.keys()}{a copy of \var{a}'s list of keys}{(2)} |
| \lineiii{\var{a}.values()}{a copy of \var{a}'s list of values}{(2)} |
| \lineiii{\var{a}.has_key(\var{k})}{\code{1} if \var{a} has a key \var{k}, else \code{0}}{} |
| \end{tableiii} |
| \indexiii{operations on}{mapping}{types} |
| \indexiii{operations on}{dictionary}{type} |
| \stindex{del} |
| \bifuncindex{len} |
| \renewcommand{\indexsubitem}{(dictionary method)} |
| \ttindex{keys} |
| \ttindex{has_key} |
| |
| % XXXJH some lines above, you talk about `true', elsewhere you |
| % explicitely states \code{0} or \code{1}. |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] Raises an exception if \var{k} is not in the map. |
| |
| \item[(2)] Keys and values are listed in random order, but at any |
| moment the ordering of the \code{keys()}, \code{values()} and |
| \code{items()} lists is the consistent with each other. |
| \end{description} |
| |
| \subsection{Other Built-in Types} |
| |
| The interpreter supports several other kinds of objects. |
| Most of these support only one or two operations. |
| |
| \subsubsection{Modules.} |
| |
| The only special operation on a module is attribute access: |
| \code{\var{m}.\var{name}}, where \var{m} is a module and \var{name} accesses |
| a name defined in \var{m}'s symbol table. Module attributes can be |
| assigned to. (Note that the \code{import} statement is not, strictly |
| spoken, an operation on a module object; \code{import \var{foo}} does not |
| require a module object named \var{foo} to exist, rather it requires |
| an (external) \emph{definition} for a module named \var{foo} |
| somewhere.) |
| |
| A special member of every module is \code{__dict__}. |
| This is the dictionary containing the module's symbol table. |
| Modifying this dictionary will actually change the module's symbol |
| table, but direct assignment to the \code{__dict__} attribute is not |
| possible (i.e., you can write \code{\var{m}.__dict__['a'] = 1}, which |
| defines \code{\var{m}.a} to be \code{1}, but you can't write \code{\var{m}.__dict__ = \{\}}. |
| |
| Modules are written like this: \code{<module 'sys'>}. |
| |
| \subsubsection{Classes and Class Instances.} |
| % XXXJH cross ref here |
| (See the Python Reference Manual for these.) |
| |
| \subsubsection{Functions.} |
| |
| Function objects are created by function definitions. The only |
| operation on a function object is to call it: |
| \code{\var{func}(\var{argument-list})}. |
| |
| There are really two flavors of function objects: built-in functions |
| and user-defined functions. Both support the same operation (to call |
| the function), but the implementation is different, hence the |
| different object types. |
| |
| The implementation adds two special read-only attributes: |
| \code{\var{f}.func_code} is a function's \dfn{code object} (see below) and |
| \code{\var{f}.func_globals} is the dictionary used as the function's |
| global name space (this is the same as \code{\var{m}.__dict__} where |
| \var{m} is the module in which the function \var{f} was defined). |
| |
| \subsubsection{Methods.} |
| |
| Methods are functions that are called using the attribute notation. |
| There are two flavors: built-in methods (such as \code{append()} on |
| lists) and class instance methods. Built-in methods are described |
| with the types that support them. |
| |
| The implementation adds two special read-only attributes to class |
| instance methods: \code{\var{m}.im_self} is the object whose method this |
| is, and \code{\var{m}.im_func} is the function implementing the method. |
| Calling \code{\var{m}(\var{arg-1}, \var{arg-2}, {\rm \ldots}, |
| \var{arg-n})} is completely equivalent to calling |
| \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1}, \var{arg-2}, {\rm |
| \ldots}, \var{arg-n})}. |
| |
| (See the Python Reference Manual for more info.) |
| |
| \subsubsection{Type Objects.} |
| |
| Type objects represent the various object types. An object's type is |
| % XXXJH xref here |
| accessed by the built-in function \code{type()}. There are no special |
| operations on types. |
| |
| Types are written like this: \code{<type 'int'>}. |
| |
| \subsubsection{The Null Object.} |
| |
| This object is returned by functions that don't explicitly return a |
| value. It supports no special operations. There is exactly one null |
| object, named \code{None} (a built-in name). |
| |
| It is written as \code{None}. |
| |
| \subsubsection{File Objects.} |
| |
| File objects are implemented using \C{}'s \code{stdio} package and can be |
| % XXXJH xref here |
| created with the built-in function \code{open()} described under |
| Built-in Functions below. |
| |
| When a file operation fails for an I/O-related reason, the exception |
| \code{IOError} is raised. This includes situations where the |
| operation is not defined for some reason, like \code{seek()} on a tty |
| device or writing a file opened for reading. |
| |
| Files have the following methods: |
| |
| |
| \renewcommand{\indexsubitem}{(file method)} |
| |
| \begin{funcdesc}{close}{} |
| Close the file. A closed file cannot be read or written anymore. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{flush}{} |
| Flush the internal buffer, like \code{stdio}'s \code{fflush()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{isatty}{} |
| Return \code{1} if the file is connected to a tty(-like) device, else |
| \code{0}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{read}{size} |
| Read at most \var{size} bytes from the file (less if the read hits |
| \EOF{} or no more data is immediately available on a pipe, tty or |
| similar device). If the \var{size} argument is omitted, read all |
| data until \EOF{} is reached. The bytes are returned as a string |
| object. An empty string is returned when \EOF{} is encountered |
| immediately. (For certain files, like ttys, it makes sense to |
| continue reading after an \EOF{} is hit.) |
| \end{funcdesc} |
| |
| \begin{funcdesc}{readline}{} |
| Read one entire line from the file. A trailing newline character is |
| kept in the string (but may be absent when a file ends with an |
| incomplete line). An empty string is returned when \EOF{} is hit |
| immediately. Note: unlike \code{stdio}'s \code{fgets()}, the returned |
| string contains null characters (\code{'\e 0'}) if they occurred in the |
| input. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{readlines}{} |
| Read until \EOF{} using \code{readline()} and return a list containing |
| the lines thus read. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{seek}{offset\, whence} |
| Set the file's current position, like \code{stdio}'s \code{fseek()}. |
| The \var{whence} argument is optional and defaults to \code{0} |
| (absolute file positioning); other values are \code{1} (seek |
| relative to the current position) and \code{2} (seek relative to the |
| file's end). There is no return value. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{tell}{} |
| Return the file's current position, like \code{stdio}'s \code{ftell()}. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{write}{str} |
| Write a string to the file. There is no return value. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{writelines}{list} |
| Write a list of strings to the file. There is no return value. |
| (The name is intended to match \code{readlines}; \code{writelines} |
| does not add line separators.) |
| \end{funcdesc} |
| |
| \subsubsection{Internal Objects.} |
| |
| (See the Python Reference Manual for these.) |
| |
| \subsection{Special Attributes} |
| |
| The implementation adds a few special read-only attributes to several |
| object types, where they are relevant: |
| |
| \begin{itemize} |
| |
| \item |
| \code{\var{x}.__dict__} is a dictionary of some sort used to store an |
| object's (writable) attributes; |
| |
| \item |
| \code{\var{x}.__methods__} lists the methods of many built-in object types, |
| e.g., \code{[].__methods__} is |
| % XXXJH results in?, yields?, written down as an example |
| \code{['append', 'count', 'index', 'insert', 'remove', 'reverse', 'sort']}; |
| |
| \item |
| \code{\var{x}.__members__} lists data attributes; |
| |
| \item |
| \code{\var{x}.__class__} is the class to which a class instance belongs; |
| |
| \item |
| \code{\var{x}.__bases__} is the tuple of base classes of a class object. |
| |
| \end{itemize} |